TAI42 — the OS for AI tools

The React hooks and providers every feature builds on — API access, theme, auth, and the interactions stream.

ApiProvider

const ApiProvider: Provider<ApiClient | null>

Related: ApiClient

AuthProvider

function AuthProvider(
  props: { children: ReactNode },
): FunctionComponentElement<ProviderProps<AuthState | null>>

Parameters

Parameter	Type	Default	Description
`props`	`{ children: ReactNode }`	—	—

Related: AuthState

AuthState

interface AuthState

Properties

Property	Type	Description
`isAuthenticated`	`boolean`	—
`login`	`(token: string, remember: boolean) => void`	Store the key; `remember` persists to sessionStorage for this device.
`logout`	`() => void`	—
`token`	`string \| null`	—

Breakpoint

type Breakpoint = "phone" | "compact" | "medium" | "full"

BreakpointState

interface BreakpointState

Properties

Property	Type	Description
`band`	`Breakpoint`	—
`isPhone`	`boolean`	True below 640 — the `phone` band, where a surface has one column to work in.
`isSinglePane`	`boolean`	True below 1024 — too narrow for two panes side by side.

Related: Breakpoint

CapabilityContextValue

interface CapabilityContextValue

Properties

Property	Type	Description
`retry`	`() => void`	Re-fetch the projection (the nav-region `ErrorState`’s retry action).
`state`	`CapabilityState`	—

Related: CapabilityState

CapabilityProvider

function CapabilityProvider(
  props: { children: ReactNode },
): FunctionComponentElement<ProviderProps<CapabilityContextValue | null>>

Parameters

Parameter	Type	Default	Description
`props`	`{ children: ReactNode }`	—	—

Related: CapabilityContextValue

CapabilityState

type CapabilityState = { status: "loading" } | { projection: MeProjection; status: "ready" } | { error: unknown; status: "failed" }

InteractionsStreamOptions

interface InteractionsStreamOptions

The inputs the caller drives the tail-only stream with. Properties

Property	Type	Description
`onResync`	`() => boolean \| Promise<boolean>`	Refetch `seed`. Called on every (re)connect ONLY — the tail carries no backlog, so this reconciles anything missed while disconnected. A live delta never calls it: the overlay updates the list and the derived `count` in place. MUST resolve `true` only when the refetch LANDED a fresh `total`, and `false` when it failed: the hook advances `countEpoch` only on `true`, so terminals and adds already folded into the fresh `total` are not applied to the count again, while after a failed refetch the prior-epoch deltas keep applying against the unchanged prior total instead of being discarded against a stale one.
`seed`	readonly ({ answer_format: "form" \| "select" \| "external" \| "text" \| "confirm"; audience?: string; channel?: string; created_at: string; format_payload: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>, z.ZodTransform<Record<string, unknown>, Record<string, unknown> \| null \| undefined>>; group_id: string; interaction_id: string; media?: unknown[]; origin?: string; question: string; recipient?: string; sensitive: boolean; server_verified?: boolean; timeout_at: string })[]	The pending set from the paged `GET /api/interactions` door — the base the live tail overlays. A stable reference between refetches (memoize it upstream); a new reference re-merges but does NOT reopen the stream.
`total`	`number`	The door’s authoritative pending TOTAL for the current `seed` (the paged response’s `total`). The published `count` derives the live pending tally from this plus the overlay delta, so the badge stays live without a refetch.

InteractionsStreamState

interface InteractionsStreamState

Properties

Property	Type	Description
`connected`	`boolean`	—
`count`	`number`	The live pending count: the seed `total` adjusted by the overlay delta stamped at or after the last landed resync’s epoch (adds not in the seed, minus one per terminal id). Stays live without a refetch; a delta stamped before `countEpoch` is already reflected in `total` and not applied again.
`disabled`	`boolean`	The interactions store is not configured on this deployment: the stream answered with a terminal 501 `interactions-not-configured`. Reconnection is abandoned (retrying would replay the same refusal forever) and the consumer renders the muted OFF state instead of a red error or a floating badge.
`error`	`Error \| null`	—
`interactions`	`StreamInteraction[]`	—

Related: StreamInteraction

StreamInteraction

type StreamInteraction = Interaction & { answered: boolean }

A live interaction plus the client-maintained answered flag.

SystemKindsProvider

function SystemKindsProvider(
  props: { children: ReactNode },
): FunctionComponentElement<ProviderProps<SystemKindsState | null>>

Fetch the kind-status table once the caller is authenticated and hold it as SDK state. Gated on isAuthenticated (the table is an authed read), so the login screen never fires a doomed request; a fetch failure settles into failed QUIETLY — no unauthorized routing, no loud error — because the consuming affordance falls back to its reactive OFF handling. Parameters

Parameter	Type	Default	Description
`props`	`{ children: ReactNode }`	—	—

Related: SystemKindsState

SystemKindsState

type SystemKindsState = { status: "loading" } | { kinds: readonly KindStatus[]; status: "ready" } | { error: unknown; status: "failed" }

Theme

type Theme = "light" | "dark"

ThemePreference

type ThemePreference = "light" | "dark" | "system"

ThemeProvider

function ThemeProvider(
  props: { children: ReactNode },
): FunctionComponentElement<ProviderProps<ThemeState | null>>

Parameters

Parameter	Type	Default	Description
`props`	`{ children: ReactNode }`	—	—

Related: ThemeState

ThemeState

interface ThemeState

Properties

Property	Type	Description
`preference`	`ThemePreference`	The operator’s choice: a pinned theme, or `'system'` to follow the OS.
`setPreference`	`(preference: ThemePreference) => void`	Set the preference and persist it. The only path that writes storage.
`setTheme`	`(theme: Theme) => void`	Pin an explicit theme (persists) — a preference shortcut kept for callers.
`theme`	`Theme`	The resolved theme the tokens key off — always concrete, never `'system'`.
`toggle`	`() => void`	Flip between the two pinned themes off the current resolved theme (persists).

Related: Theme, ThemePreference

ToolDisplayNamesContextValue

interface ToolDisplayNamesContextValue

Properties

Property	Type	Description
`reload`	`() => void`	Re-fetch the overlay (drives the app-level refresh after a display-name edit).
`state`	`ToolDisplayNamesState`	—

Related: ToolDisplayNamesState

ToolDisplayNamesProvider

function ToolDisplayNamesProvider(
  props: { children: ReactNode },
): FunctionComponentElement<ProviderProps<ToolDisplayNamesContextValue | null>>

Fetch the tool-meta overlay once the caller is authenticated and hold its display-name map as SDK state. Gated on isAuthenticated (the overlay is an authed read), so the login screen never fires a doomed request; a fetch failure settles into failed QUIETLY, because the consuming pickers fall back to the bare raw name. reload re-fetches on demand, so an app-level display-name write refreshes every picker without a remount. Parameters

Parameter	Type	Default	Description
`props`	`{ children: ReactNode }`	—	—

Related: ToolDisplayNamesContextValue

ToolDisplayNamesState

type ToolDisplayNamesState = { status: "loading" } | { names: Readonly<Record<string, string>>; status: "ready" } | { error: unknown; status: "failed" }

UnauthorizedProvider

const UnauthorizedProvider: Provider<() => void>

coversAnyRoute

function coversAnyRoute(
  projection: { admin: boolean; agents: string[]; mintable: boolean; owner_user_id: string | null; route_patterns: ({ pattern: string; scope_id: string })[]; routes: ({ methods: string[]; path: string })[]; scopes: string[]; sub_mcp: ({ slug: string; tools: string[]; transport: string })[]; tools: string[]; user_id: string },
  prefixes: readonly string[],
): boolean

Whether the projection reaches ANY route under one of prefixes — the declarative test behind nav filtering and plugin requiredCapabilities. A concrete routes[].path covers a prefix when it is that prefix or a segment-nested descendant of it; a dynamic route_patterns[].pattern covers a prefix only when it is a simple anchored open-wildcard pattern (^<literal>.*$) whose open literal overlaps the prefix at a segment boundary. Under-showing is safe (projection is UX; the server is the authority); over-showing is the bug. So any non-anchored or otherwise complex pattern (alternation, char class, bounded quantifier) is conservatively treated as NOT covering — its matched set is not a clean prefix, so we never infer reach from it. Parameters

Parameter	Type	Default	Description
`projection`	`{ admin: boolean; agents: string[]; mintable: boolean; owner_user_id: string \| null; route_patterns: ({ pattern: string; scope_id: string })[]; routes: ({ methods: string[]; path: string })[]; scopes: string[]; sub_mcp: ({ slug: string; tools: string[]; transport: string })[]; tools: string[]; user_id: string }`	—	—
`prefixes`	`readonly string[]`	—	—

coversRoute

function coversRoute(
  projection: { admin: boolean; agents: string[]; mintable: boolean; owner_user_id: string | null; route_patterns: ({ pattern: string; scope_id: string })[]; routes: ({ methods: string[]; path: string })[]; scopes: string[]; sub_mcp: ({ slug: string; tools: string[]; transport: string })[]; tools: string[]; user_id: string },
  path: string,
  method: string,
): boolean

Whether the projection reaches a specific WRITE route — an EXACT path whose admitted methods include method. This is the method-aware companion to coversAnyRoute: a read/nav surface gates path-only (any method reaching a prefix means the surface is navigable), but an action that issues method path must gate on the method too, or a caller whose jq fence admits only GET on path would be shown a control that 403s on submit (projection ⊆ gate). Only concrete routes are consulted: dynamic route_patterns carry no method, so no write capability can be soundly inferred from them, and a synthetic TOTAL (admin) projection carries no concrete routes at all — callers short-circuit it with isFullProjection before reaching here. Under-showing is safe (the server stays the authority); over-showing an action the gate denies is the bug. Parameters

Parameter	Type	Default	Description
`projection`	`{ admin: boolean; agents: string[]; mintable: boolean; owner_user_id: string \| null; route_patterns: ({ pattern: string; scope_id: string })[]; routes: ({ methods: string[]; path: string })[]; scopes: string[]; sub_mcp: ({ slug: string; tools: string[]; transport: string })[]; tools: string[]; user_id: string }`	—	—
`path`	`string`	—	—
`method`	`string`	—	—

coversWrite

function coversWrite(state: CapabilityState, path: string, method: string): boolean

Whether a WRITE control may be shown/enabled for this caller — the fail-closed, method-aware gate the features fold together with any deployment-level read-only flag (the projection ⊆ gate invariant, in one place). It is true ONLY once the projection is ready AND either it is a full (admin / gate-off) projection or it reaches method path. While the projection is loading/failed it is false — a write control never enables before the gate is known (fail closed; not-ready ⇒ disabled/read-only). Only concrete routes carry methods, so a DYNAMIC (templated) write route — one the projection can represent only as a method-less route_patterns row — reads false for every non-admin caller and degrades that control to read-only. Under-showing is safe (the server stays the authority); over-showing a write the gate denies is the bug. Parameters

Parameter	Type	Default	Description
`state`	`CapabilityState`	—	—
`path`	`string`	—	—
`method`	`string`	—	—

Related: CapabilityState

isFullProjection

function isFullProjection(
  projection: { admin: boolean; agents: string[]; mintable: boolean; owner_user_id: string | null; route_patterns: ({ pattern: string; scope_id: string })[]; routes: ({ methods: string[]; path: string })[]; scopes: string[]; sub_mcp: ({ slug: string; tools: string[]; transport: string })[]; tools: string[]; user_id: string },
): boolean

Whether the projection is the synthetic TOTAL projection — the admin session (the condition-free ownerless "*" discriminator) and the gate-off local-dev projection alike. This is projection.admin === true and NOTHING else: a seeded editor/viewer carries ["*"] scopes PLUS a jq fence, so keying on "*" scopes would hand every editor/viewer the unfiltered nav and a wall of 403s on the admin routes their fence denies. Keying on admin makes editor/viewer SCOPED sessions whose nav is filtered by their jq-exact routes, which is exactly right — and the gate-off synthetic projection (admin: true, empty routes) still reads as full, so an AC-disabled deployment shows everything. Parameters

Parameter	Type	Default	Description
`projection`	`{ admin: boolean; agents: string[]; mintable: boolean; owner_user_id: string \| null; route_patterns: ({ pattern: string; scope_id: string })[]; routes: ({ methods: string[]; path: string })[]; scopes: string[]; sub_mcp: ({ slug: string; tools: string[]; transport: string })[]; tools: string[]; user_id: string }`	—	—

toolDisplayLabel

function toolDisplayLabel(names: Readonly<Record<string, string>>, rawName: string): string

The option label for a raw tool name under a display-name map: Display (raw) when a display name maps the name and is non-empty AND differs from the raw name, else the bare raw name. Shared so every tool picker labels identically. Parameters

Parameter	Type	Default	Description
`names`	`Readonly<Record<string, string>>`	—	the raw-name → display-name map (from useToolDisplayNames).
`rawName`	`string`	—	the raw tool name to label.

useApi

function useApi(): ApiClient

Related: ApiClient

useAuth

function useAuth(): AuthState

Related: AuthState

useBreakpoint

function useBreakpoint(): BreakpointState

Related: BreakpointState

useCanWrite

function useCanWrite(path: string, method: string): boolean

Whether a WRITE control may be shown for the current caller — the single boundary primitive a feature calls to hide a control whose method path the caller’s projection cannot reach. It reads the live capability state and folds it through coversWrite: true only once the projection is ready AND it is a full (admin / gate-off) projection or it reaches method path; while the projection is loading/failed it is false (fail closed — no write control before the gate is known). method defaults to POST, the common write verb; pass the exact verb for a PUT/PATCH/DELETE control. Parameters

Parameter	Type	Default	Description
`path`	`string`	—	—
`method`	`string`	`'POST'`	—

useCapabilities

function useCapabilities(): CapabilityContextValue

Related: CapabilityContextValue

useFeatureOff

function useFeatureOff(kind: string): boolean

Whether kind is reported OFF by the kind-status table — the single proactive predicate a write affordance folds in to hide itself before a doomed write. It is true ONLY once the table is ready AND that kind’s row carries state: 'off'; while the table is loading/failed, no provider is mounted, or the kind is unknown, it is false (treat as not-off until known — under-hiding is safe, the reactive 501 backstop still catches a genuinely-off feature). Parameters

Parameter	Type	Default	Description
`kind`	`string`	—	—

useFeatureOffMessage

function useFeatureOffMessage(kind: string): string | null

The OFF row’s server detail for kind — the proactive counterpart to a write refusal’s message, so a proactively-hidden surface shows the SERVER’s own remediation line rather than a client-composed env-var string. null whenever the kind is not reported OFF (table loading/failed, no provider, unknown kind, or the kind is on), mirroring useFeatureOff’s not-off-until-known default. Parameters

Parameter	Type	Default	Description
`kind`	`string`	—	—

useInteractionsStream

function useInteractionsStream(options: InteractionsStreamOptions): InteractionsStreamState

Props

Prop	Type	Description
`onResync`	`() => boolean \| Promise<boolean>`	Refetch `seed`. Called on every (re)connect ONLY — the tail carries no backlog, so this reconciles anything missed while disconnected. A live delta never calls it: the overlay updates the list and the derived `count` in place. MUST resolve `true` only when the refetch LANDED a fresh `total`, and `false` when it failed: the hook advances `countEpoch` only on `true`, so terminals and adds already folded into the fresh `total` are not applied to the count again, while after a failed refetch the prior-epoch deltas keep applying against the unchanged prior total instead of being discarded against a stale one.
`seed`	readonly ({ answer_format: "form" \| "select" \| "external" \| "text" \| "confirm"; audience?: string; channel?: string; created_at: string; format_payload: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>, z.ZodTransform<Record<string, unknown>, Record<string, unknown> \| null \| undefined>>; group_id: string; interaction_id: string; media?: unknown[]; origin?: string; question: string; recipient?: string; sensitive: boolean; server_verified?: boolean; timeout_at: string })[]	The pending set from the paged `GET /api/interactions` door — the base the live tail overlays. A stable reference between refetches (memoize it upstream); a new reference re-merges but does NOT reopen the stream.
`total`	`number`	The door’s authoritative pending TOTAL for the current `seed` (the paged response’s `total`). The published `count` derives the live pending tally from this plus the overlay delta, so the badge stays live without a refetch.

useOnUnauthorized

function useOnUnauthorized(): () => void

useReloadToolDisplayNames

function useReloadToolDisplayNames(): () => void

Re-fetch the display-name overlay. A surface that writes a display name calls this so the app-level provider — and every picker reading it — refreshes alongside the surface’s own list invalidation. A no-op when no provider is mounted.

useSystemKinds

function useSystemKinds(): SystemKindsState

The live kind-status state. Falls back to loading when no provider is mounted, so a consumer rendered outside the shell reads every kind as not-off rather than throwing — the fail-open default this proactive-hiding idiom relies on. Related: SystemKindsState

useTheme

function useTheme(): ThemeState

Related: ThemeState

useToolDisplayNames

function useToolDisplayNames(): Readonly<Record<string, string>>

The live raw-name → display-name map — {} while the overlay is loading/failed, no provider is mounted, or no row carries a display name. A tool picker folds this into its option labels; an unmapped name reads the bare raw name.

​ApiProvider

​AuthProvider

​AuthState

​Breakpoint

​BreakpointState

​CapabilityContextValue

​CapabilityProvider

​CapabilityState

​InteractionsStreamOptions

​InteractionsStreamState

​StreamInteraction

​SystemKindsProvider

​SystemKindsState

​Theme

​ThemePreference

​ThemeProvider

​ThemeState

​ToolDisplayNamesContextValue

​ToolDisplayNamesProvider

​ToolDisplayNamesState

​UnauthorizedProvider

​coversAnyRoute

​coversRoute

​coversWrite

​isFullProjection

​toolDisplayLabel

​useApi

​useAuth

​useBreakpoint

​useCanWrite

​useCapabilities

​useFeatureOff

​useFeatureOffMessage

​useInteractionsStream

​useOnUnauthorized

​useReloadToolDisplayNames

​useSystemKinds

​useTheme

​useToolDisplayNames

ApiProvider

AuthProvider

AuthState

Breakpoint

BreakpointState

CapabilityContextValue

CapabilityProvider

CapabilityState

InteractionsStreamOptions

InteractionsStreamState

StreamInteraction

SystemKindsProvider

SystemKindsState

Theme

ThemePreference

ThemeProvider

ThemeState

ToolDisplayNamesContextValue

ToolDisplayNamesProvider

ToolDisplayNamesState

UnauthorizedProvider

coversAnyRoute

coversRoute

coversWrite

isFullProjection

toolDisplayLabel

useApi

useAuth

useBreakpoint

useCanWrite

useCapabilities

useFeatureOff

useFeatureOffMessage

useInteractionsStream

useOnUnauthorized

useReloadToolDisplayNames

useSystemKinds

useTheme

useToolDisplayNames