TAI42 — the OS for AI tools

The shell⇄feature route-token contract — the navigation provider, links, and resolution hooks.

AppLink

function AppLink<T extends keyof RouteSearchByToken>(props: AppLinkProps<T>): ReactNode

A real anchor (so middle-click / open-in-new-tab keep working) that drives a client-side transition on plain left-click. Modified clicks (new tab/window, download) fall through to the browser’s default handling. Props

Prop	Type	Description
`aria-current?`	`boolean \| "time" \| "true" \| "false" \| "page" \| "step" \| "location" \| "date"`	—
`aria-label?`	`string`	—
`children`	`ReactNode`	—
`className?`	`string`	—
`search?`	`RouteSearch<T>`	—
`style?`	`CSSProperties`	Inline styles for the anchor.
`title?`	`string`	Native tooltip text (also a sensible non-AT hover hint).
`to`	`T`	—

Related: AppLinkProps

AppLinkProps

interface AppLinkProps<T extends RouteToken>

Properties

Property	Type	Description
`aria-current?`	`boolean \| "time" \| "true" \| "false" \| "page" \| "step" \| "location" \| "date"`	—
`aria-label?`	`string`	—
`children`	`ReactNode`	—
`className?`	`string`	—
`search?`	`RouteSearch<T>`	—
`style?`	`CSSProperties`	Inline styles for the anchor.
`title?`	`string`	Native tooltip text (also a sensible non-AT hover hint).
`to`	`T`	—

Related: RouteSearch

NavigateOptions

interface NavigateOptions

How a token navigation enters session history. The default is a PUSH: a move the reader made, which Back must be able to undo. replace overwrites the current entry instead, and is for a transition the reader did NOT make — a page rewriting an unrenderable URL of its own accord. Pushing such a rewrite leaves the URL it rewrote sitting behind Back, where pressing Back rewrites it again and pushes again: a page no Back can leave. Properties

Property	Type	Description
`replace?`	`boolean`	Overwrite the current history entry instead of pushing a new one.

NavigationContextValue

interface NavigationContextValue

The runtime navigation surface the shell provides through NavigationProvider. navigate performs a client-side transition, by default pushing a history entry — see NavigateOptions for the third argument that replaces one instead. resolvePath produces the href a link should point at (so an AppLink is a real anchor — middle-click / open-in-new-tab work — while still driving a client-side transition on plain click). navigatePlugin/resolvePluginPath are the plugin-page twins: they target a runtime plugin path (/plugins/{pluginId}/{pagePath} plus an optional validated sub-path params and search), NOT a route token — routes.ts never learns plugin paths. Plugins reach these two via the usePluginNavigation hook. Properties

Property	Type	Description
`navigate`	`<T extends keyof RouteSearchByToken>(token: T, search?: RouteSearch<T>, options?: NavigateOptions) => void`	—
`navigatePlugin`	`(pluginId: string, pagePath: string, params?: string, search?: PluginSearch) => void`	—
`navigatePluginWithOptions?`	`(pluginId: string, pagePath: string, params?: string, search?: PluginSearch, options?: PluginNavigateOptions) => void`	ADDITIVE plugin-page navigation that also carries per-history-entry PluginNavigateOptions. OPTIONAL because a Studio host built before this feature does not provide it; plugins reach it — and require a host that does — through usePluginEntryNavigation, which throws loudly on an older host. It behaves exactly like navigatePlugin for path / params / search, and in addition writes `options.state` onto the DESTINATION entry under the plugin’s own namespace slot (see PluginPageProps.entryState). NEXT-MAJOR (9.0) CONSOLIDATION NOTE: fold `options` into navigatePlugin’s own signature and RETIRE this sibling. It exists as a separate optional member ONLY to stay additive under the plugin-API equality gate — a new optional member does not move STUDIO_PLUGIN_API_VERSION, so every existing plugin keeps loading. Cutting a MAJOR now purely to rename one method onto another is the disproportion anti-pattern: a breaking change for a cosmetic merge. The merge therefore waits for the next major that carries real breaks; until then both coexist and navigatePlugin stays byte-for-byte stable.
`resolvePath`	`<T extends keyof RouteSearchByToken>(token: T, search?: RouteSearch<T>) => string`	—
`resolvePluginPath`	`(pluginId: string, pagePath: string, params?: string, search?: PluginSearch) => string`	—
`updatePluginEntryState?`	`(pluginId: string, state: unknown) => void`	ADDITIVE: replace the CURRENT history entry’s per-entry state slot for `pluginId` IN PLACE (merge-preserving other plugins’ slots), WITHOUT navigating — the URL, params, search, and scroll are untouched. A page uses it to checkpoint its live view state onto the entry the reader is already on, so a later back/forward or a hard reload restores it. OPTIONAL for the same additive reason as navigatePluginWithOptions; reached through usePluginEntryNavigation.

NavigationGuardHandler

type NavigationGuardHandler = () => boolean | Promise<boolean>

A navigation guard’s decision function, run while armed before any SDK-controlled navigation commits (navigate, navigatePlugin, or a browser back/forward). Returns true to proceed, false to veto; a promise lets it await a confirm dialog. Guards compose — navigation proceeds only if every armed guard allows, and the first veto blocks (at most one dialog). A full-page unload can’t await, so it is covered by a beforeunload prompt independent of this handler.

NavigationProvider

function NavigationProvider(
  props: { children: ReactNode; value: NavigationContextValue },
): ReactNode

Parameters

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

Related: NavigationContextValue

PageProps

interface PageProps<T extends RouteToken>

Props the shell passes to a feature’s page component: the route’s typed search parameters. Features type their exported page as PageProps<'tools'> and read search — they receive route state as data, never by importing the router. Properties

Property	Type	Description
`search`	`RouteSearch<T>`	—

Related: RouteSearch

PluginNavigateOptions

interface PluginNavigateOptions

Per-navigation options for navigatePluginWithOptions. replace mirrors replace: overwrite the current history entry instead of pushing a new one (a page rewriting its own unrenderable URL). state is an opaque, per-history-ENTRY bag the host stores ON the destination history entry, namespaced to the navigating plugin, and hands the page back as entryState. It survives back/forward traversal AND a hard reload — the browser persists history.state across a document load, verified in a real browser against the router’s pinned major before this channel was built. Two hard rules bind the value:

JSON-ROUND-TRIP: it is serialized into history.state, so it must survive structured-clone / JSON semantics — plain data only, no functions, DOM nodes, or class instances. The page reads back a structural COPY, never the same reference it wrote.
SIZE: history.state is browser-bounded (Firefox caps a serialized entry at 16 MiB; others higher). Keep a slot SMALL — a soft cap of ~32 KB — and store only view state (a selection, a scroll anchor, a draft id), never bulk data. Oversized state risks a browser-thrown navigation; the host does not police the cap, so the discipline is the plugin’s.

Properties

Property	Type	Description
`replace?`	`boolean`	Overwrite the current history entry instead of pushing a new one.
`state?`	`unknown`	Opaque, JSON-round-trippable per-entry state (soft cap ~32 KB); see the type doc.

PluginSearch

type PluginSearch = Record<string, unknown>

A plugin page’s deep-link search object. Plugin paths are RUNTIME contributions outside the compile-time RouteToken map, so their search is an open bag of serializable values (the page’s own PluginPageParamsSchema validates it); this is deliberately NOT a RouteSearch.

RouteSearch

type RouteSearch<T extends RouteToken> = RouteSearchByToken[T]

The search parameters a given route token accepts. Related: RouteSearchByToken

RouteSearchByToken

interface RouteSearchByToken

Every top-level route the shell owns, mapped to its typed search parameters. A route with no parameters maps to the empty object. Detail views are driven by a search parameter (e.g. the selected tool / connection), keeping the route map flat — one entry per feature surface, matching the shell route map. Properties

Property	Type	Description
`agents`	`Record<string, never>`	—
`connectors`	`{ connection?: string }`	—
`conversations`	`{ address?: string; q?: string; route?: string; status?: "failed" \| "accepted" \| "pending_delivery" \| "provisional" \| "delivered" \| "shed" \| "silent"; thread?: string }`	—
`extensions`	`Record<string, never>`	—
`hooks`	`Record<string, never>`	—
`interactions`	`Record<string, never>`	—
`login`	`Record<string, never>`	—
`manifest`	`Record<string, never>`	—
`marketplace`	`{ category?: string; kind?: string; plugin?: string; q?: string; sort?: "name" \| "downloads" \| "updated" \| "relevance"; tab?: "browse" \| "installed"; tags?: string[] }`	—
`notifications`	`Record<string, never>`	—
`observability`	`{ dir?: "asc" \| "desc"; from?: string; maxCost?: number; maxLatencyMs?: number; maxTokens?: number; minCost?: number; minLatencyMs?: number; minTokens?: number; sort?: "createdAt" \| "cost" \| "latencyMs" \| "totalTokens"; status?: "error" \| "success"; tab?: "dashboard" \| "tracing"; tags?: string[]; to?: string; trace?: string }`	—
`presets`	`{ preset?: string }`	—
`scheduling`	`Record<string, never>`	—
`servedEndpoints`	`Record<string, never>`	—
`settings`	`Record<string, never>`	—
`states`	`{ state?: string; subject?: string; tab?: "declaration" \| "templates" \| "records" \| "consumers"; target?: string; template?: string }`	—
`storage`	`{ q?: string }`	—
`system`	`Record<string, never>`	—
`templates`	`{ q?: string; template?: string }`	—
`tools`	`{ q?: string; tags?: string[]; tool?: string }`	—

RouteToken

type RouteToken = keyof RouteSearchByToken

An opaque, typed handle to a shell route. Related: RouteSearchByToken

SearchCommitParams

interface SearchCommitParams<T extends RouteToken>

The inputs a page hands useSearchCommit: the route token the commit targets, the container whose delegated Enter/blur commits, the search input’s accessible name (the delegation keys the input on it), the committed value now in the URL, the live draft, the page’s composer of the full search object from the next query (undefined when the box is empty), and the loud message thrown if the container ref never attaches. Properties

Property	Type	Description
`buildSearch`	`(query: string \| undefined) => RouteSearch<T>`	—
`committedValue`	`string`	—
`containerMissingError`	`string`	—
`containerRef`	`RefObject<HTMLElement \| null>`	—
`draft`	`string`	—
`searchLabel`	`string`	—
`token`	`T`	—

Related: RouteSearch

useAppNavigate

function useAppNavigate(): <T extends keyof RouteSearchByToken>(token: T, search?: RouteSearch<T>, options?: NavigateOptions) => void

Imperative navigation to a shell route token with its typed search params. Related: NavigateOptions, RouteSearch, RouteSearchByToken

useNavigationGate

function useNavigationGate(): (href: string) => Promise<boolean>

Consult the armed navigation guards before a transition the shell drives itself (a chrome link whose target is outside the route-token map). Resolves true when the navigation may proceed. Token and plugin navigations already run this gate inside NavigationProvider; this is the escape hatch for the shell’s own raw-path links, without which such a link would bypass every armed guard.

useNavigationGuard

function useNavigationGuard(when: boolean, handler: NavigationGuardHandler): void

Block navigation away from the current page while when is true. handler is consulted before any SDK-controlled navigation commits — a route-token navigate, a plugin navigate, or a browser back/forward — and the navigation proceeds only if it resolves true; a promise lets the handler drive a confirm dialog. A full-page unload (tab close / refresh) is additionally covered by a native beforeunload prompt that fires whenever any guard is armed. Guards compose against the provider’s shared registry: a feature and a plugin page may each arm one, and any veto blocks. Parameters

Parameter	Type	Default	Description
`when`	`boolean`	—	—
`handler`	`NavigationGuardHandler`	—	—

Related: NavigationGuardHandler

usePluginEntryNavigation

function usePluginEntryNavigation(): { navigatePluginWithOptions: (pluginId: string, pagePath: string, params?: string, search?: PluginSearch, options?: PluginNavigateOptions) => void; updatePluginEntryState: (pluginId: string, state: unknown) => void }

Plugin-page navigation WITH the per-history-entry state channel: navigatePluginWithOptions navigates and writes a per-entry state slot, and updatePluginEntryState checkpoints the CURRENT entry’s slot in place (no navigation). Both require a host that provides the channel; on an OLDER host that predates it, this hook THROWS a loud, descriptive error rather than silently degrading — the plugin then knows to fall back or the deployment knows to update the host. A plugin that only navigates without carrying state should keep using usePluginNavigation, which every host supports. Related: PluginNavigateOptions, PluginSearch

usePluginNavigation

function usePluginNavigation(): Pick<NavigationContextValue, "navigatePlugin" | "resolvePluginPath">

Plugin-page navigation: navigatePlugin drives a client-side transition to a runtime plugin path, resolvePluginPath yields its href. These are the ONLY navigation methods a plugin page uses to reach its own deep-linkable sub-paths — the token-typed useAppNavigate/useResolvePath address the shell’s compile-time routes and know nothing of plugin paths. Related: NavigationContextValue

useResolvePath

function useResolvePath(): <T extends keyof RouteSearchByToken>(token: T, search?: RouteSearch<T>) => string

Resolve a token + search to the href the shell would route to. Related: RouteSearch, RouteSearchByToken

useSearchCommit

function useSearchCommit<T extends keyof RouteSearchByToken>(
  props: SearchCommitParams<T>,
): void

The shared commit behavior for a filter box that writes its text into a route-token search param. The SDK search input is controlled (value/onChange only), so the URL commit is delegated on the CONTAINER: Enter or an edited blur of the search box writes the URL. The listeners bind once — the latest draft and committed value are read from a ref, never re-bound per keystroke. A commit REPLACES the current history entry rather than pushing: a filter change refines the current view, not a place Back should step back through one keystroke-commit at a time. A cleared box commits undefined so the URL and box cannot drift. A redundant commit (the draft already the committed value, trimmed both sides, so a padded deep-link never self-commits without a real edit) writes nothing. Props

Prop	Type	Description
`buildSearch`	`(query: string \| undefined) => RouteSearch<T>`	—
`committedValue`	`string`	—
`containerMissingError`	`string`	—
`containerRef`	`RefObject<HTMLElement \| null>`	—
`draft`	`string`	—
`searchLabel`	`string`	—
`token`	`T`	—

Related: SearchCommitParams

HTTP API

CLI

Settings

Capability map

Conversation bridge

Python SDK

Studio SDK

Navigation

AppLink

AppLinkProps

NavigateOptions

NavigationContextValue

NavigationGuardHandler

NavigationProvider

PageProps

PluginNavigateOptions

PluginSearch

RouteSearch

RouteSearchByToken

RouteToken

SearchCommitParams

useAppNavigate

useNavigationGate

useNavigationGuard

usePluginEntryNavigation

usePluginNavigation

useResolvePath

useSearchCommit

​AppLink

​AppLinkProps

​NavigateOptions

​NavigationContextValue

​NavigationGuardHandler

​NavigationProvider

​PageProps

​PluginNavigateOptions

​PluginSearch

​RouteSearch

​RouteSearchByToken

​RouteToken

​SearchCommitParams

​useAppNavigate

​useNavigationGate

​useNavigationGuard

​usePluginEntryNavigation

​usePluginNavigation

​useResolvePath

​useSearchCommit

AppLink

AppLinkProps

NavigateOptions

NavigationContextValue

NavigationGuardHandler

NavigationProvider

PageProps

PluginNavigateOptions

PluginSearch

RouteSearch

RouteSearchByToken

RouteToken

SearchCommitParams

useAppNavigate

useNavigationGate

useNavigationGuard

usePluginEntryNavigation

usePluginNavigation

useResolvePath

useSearchCommit