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" }

ExecutionKeyBinding

type ExecutionKeyBinding = { mode: "pending" } | { fillKey: string; mode: "unchecked" } | { mode: "checked"; own: OwnIdentity }

How a form binds the execution key a stored record runs as, read from the session’s projection. Related: OwnIdentity

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" \| "free" \| "confirm"; audience: string \| null; channel: string \| null; 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: ({ caption: string \| null; filename: string \| null; kind: "audio" \| "link" \| "video" \| "document" \| "image"; url: string })[] \| null; origin: string \| null; question: string; recipient: string \| null; sensitive: boolean; server_verified: boolean \| null; 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 and the consumer renders the muted OFF state instead of a red error.
`error`	`Error \| null`	—
`interactions`	`StreamInteraction[]`	—

Related: StreamInteraction

OwnIdentity

interface OwnIdentity

The session’s own identity, as the execution-key pickers offer it. Properties

Property	Type	Description
`admin`	`boolean`	—
`kind`	`"key" \| "account"`	’account’ when the session is a principal itself (no owner claim, a principal row): the bind check refuses it. ‘key’ otherwise: an owned api key, or a key with no owner.
`userId`	`string`	—

StreamInteraction

type StreamInteraction = Interaction & { answered: boolean }

A live interaction plus the client-maintained answered flag.

SystemKindsProvider

function SystemKindsProvider(
  props: { children: ReactNode },
): FunctionComponentElement<ProviderProps<SystemKindsContextValue | 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 }`	—	—

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>

boundExecutionKey

function boundExecutionKey(value: string, binding: ExecutionKeyBinding): string

The key a write sends: the form’s value; with access control off and a blank value, the fill key. Parameters

Parameter	Type	Default	Description
`value`	`string`	—	—
`binding`	`ExecutionKeyBinding`	—	—

Related: ExecutionKeyBinding

coversAnyRoute

function coversAnyRoute(
  projection: { access_control_enabled: boolean; admin: boolean; agents: string[]; mintable: boolean; owner_user_id: string | null; principal: { display_name: string; kind: "human" | "service"; user_id: string } | null; public_resource_id: string; route_patterns: ({ open_prefix: string | null; pattern: string; scope_id: string })[]; routes: ({ methods: string[]; path: string })[]; scopes: string[]; sub_mcp: ({ access_pattern: string; mount_url: string; 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 routes[].path (a concrete path, or a route template such as /api/presets/{name}) covers a prefix when it is that prefix or a segment-nested descendant of it; a dynamic route_patterns[] entry covers a prefix through its served open_prefix — the literal the server rules every path starting with is reachable — when it overlaps the prefix at a segment boundary. A null open prefix (a pattern whose matched set is not a clean prefix) covers nothing by prefix: under-showing is safe, over-showing is the bug. Parameters

Parameter	Type	Default	Description
`projection`	{ access_control_enabled: boolean; admin: boolean; agents: string[]; mintable: boolean; owner_user_id: string \| null; principal: { display_name: string; kind: "human" \| "service"; user_id: string } \| null; public_resource_id: string; route_patterns: ({ open_prefix: string \| null; pattern: string; scope_id: string })[]; routes: ({ methods: string[]; path: string })[]; scopes: string[]; sub_mcp: ({ access_pattern: string; mount_url: string; slug: string; tools: string[]; transport: string })[]; tools: string[]; user_id: string }	—	—
`prefixes`	`readonly string[]`	—	—

coversRoute

function coversRoute(
  projection: { access_control_enabled: boolean; admin: boolean; agents: string[]; mintable: boolean; owner_user_id: string | null; principal: { display_name: string; kind: "human" | "service"; user_id: string } | null; public_resource_id: string; route_patterns: ({ open_prefix: string | null; pattern: string; scope_id: string })[]; routes: ({ methods: string[]; path: string })[]; scopes: string[]; sub_mcp: ({ access_pattern: string; mount_url: string; 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. A templated route is listed under its template path (/api/presets/{name}) with the methods the caller’s grant admits on a representative instance of it, so a caller names the template on both sides. 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 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`	{ access_control_enabled: boolean; admin: boolean; agents: string[]; mintable: boolean; owner_user_id: string \| null; principal: { display_name: string; kind: "human" \| "service"; user_id: string } \| null; public_resource_id: string; route_patterns: ({ open_prefix: string \| null; pattern: string; scope_id: string })[]; routes: ({ methods: string[]; path: string })[]; scopes: string[]; sub_mcp: ({ access_pattern: string; mount_url: string; 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). A templated write route is gated by its template path: the projection lists it with the methods the caller’s grant admits on a representative instance. A credential fenced per instance is decided at the server, which answers 403 on submit where the fence denies that instance. 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: { access_control_enabled: boolean; admin: boolean; agents: string[]; mintable: boolean; owner_user_id: string | null; principal: { display_name: string; kind: "human" | "service"; user_id: string } | null; public_resource_id: string; route_patterns: ({ open_prefix: string | null; pattern: string; scope_id: string })[]; routes: ({ methods: string[]; path: string })[]; scopes: string[]; sub_mcp: ({ access_pattern: string; mount_url: string; 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 "*" 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 projected 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`	{ access_control_enabled: boolean; admin: boolean; agents: string[]; mintable: boolean; owner_user_id: string \| null; principal: { display_name: string; kind: "human" \| "service"; user_id: string } \| null; public_resource_id: string; route_patterns: ({ open_prefix: string \| null; pattern: string; scope_id: string })[]; routes: ({ methods: string[]; path: string })[]; scopes: string[]; sub_mcp: ({ access_pattern: string; mount_url: string; 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

useExecutionKeyBinding

function useExecutionKeyBinding(): ExecutionKeyBinding

The execution-key binding of the live session. Related: ExecutionKeyBinding

useFeatureOff

function useFeatureOff(kind: string): boolean

Whether kind is OFF — the single predicate a write affordance folds in to hide itself before a doomed write. It is true once the table is ready AND that kind’s row carries state: 'off', or once a write refusal revealed the kind OFF (useReportFeatureOff). Otherwise — the table loading/failed, no provider mounted, the kind unknown — it is false (not-off until known: under-hiding is safe, a write’s 501 refusal still reveals 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; for a kind only a write refusal revealed OFF, that refusal’s message. null whenever the kind is not OFF, 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" \| "free" \| "confirm"; audience: string \| null; channel: string \| null; 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: ({ caption: string \| null; filename: string \| null; kind: "audio" \| "link" \| "video" \| "document" \| "image"; url: string })[] \| null; origin: string \| null; question: string; recipient: string \| null; sensitive: boolean; server_verified: boolean \| null; 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

​ExecutionKeyBinding

​InteractionsStreamOptions

​InteractionsStreamState

​OwnIdentity

​StreamInteraction

​SystemKindsProvider

​SystemKindsState

​Theme

​ThemePreference

​ThemeProvider

​ThemeState

​ToolDisplayNamesContextValue

​ToolDisplayNamesProvider

​ToolDisplayNamesState

​UnauthorizedProvider

​boundExecutionKey

​coversAnyRoute

​coversRoute

​coversWrite

​isFullProjection

​toolDisplayLabel

​useApi

​useAuth

​useBreakpoint

​useCanWrite

​useCapabilities

​useExecutionKeyBinding

​useFeatureOff

​useFeatureOffMessage

​useInteractionsStream

​useOnUnauthorized

​useReloadToolDisplayNames

​useSystemKinds

​useTheme

​useToolDisplayNames

ApiProvider

AuthProvider

AuthState

Breakpoint

BreakpointState

CapabilityContextValue

CapabilityProvider

CapabilityState

ExecutionKeyBinding

InteractionsStreamOptions

InteractionsStreamState

OwnIdentity

StreamInteraction

SystemKindsProvider

SystemKindsState

Theme

ThemePreference

ThemeProvider

ThemeState

ToolDisplayNamesContextValue

ToolDisplayNamesProvider

ToolDisplayNamesState

UnauthorizedProvider

boundExecutionKey

coversAnyRoute

coversRoute

coversWrite

isFullProjection

toolDisplayLabel

useApi

useAuth

useBreakpoint

useCanWrite

useCapabilities

useExecutionKeyBinding

useFeatureOff

useFeatureOffMessage

useInteractionsStream

useOnUnauthorized

useReloadToolDisplayNames

useSystemKinds

useTheme

useToolDisplayNames