@tai42/api-client 16.0.0 → 17.0.0

package/src/client.ts

@@ -1,1771 +0,0 @@
-/**
- * The typed client: one method per endpoint, each validating
- * its response against the matching zod schema. Server state flows through
- * TanStack Query in the features; this client is a plain typed transport with no
- * caching of its own.
- */
-import {
-  type ApiConfig,
-  type RequestOptions,
-  apiDownload,
-  apiRequest,
-  apiText,
-  encodeSegment,
-  extractError,
-  isUnsafePathSegment,
-} from './http';
-import { ApiError, ApiLoginFailedError, ApiUnauthorizedError } from './errors';
-import { readSseFrames, sseOpenToken } from './sse';
-import { agentList, streamAgentRun, streamAuthoredAgentRun } from './agents';
-import { getToolRun, listToolRuns, submitToolRun, type SubmitToolRunArgs } from './tool-runs';
-import * as s from './schemas';
-
-export interface RunToolArgs {
-  readonly tool: string;
-  readonly kwargs?: Record<string, unknown>;
-}
-
-/**
- * Identify one app tool for a live-registry op (`POST /api/tools/reload`,
- * `POST /api/tools/remove`): its `kind` (the reloader kind a plugin registered,
- * e.g. `example_tool`) and `name`. `targets` optionally restricts the fleet
- * fan-out to specific workers; omit it to reach every worker.
- */
-export interface ToolAdminArgs {
-  readonly kind: string;
-  readonly name: string;
-  readonly targets?: string[];
-}
-
-/**
- * Names to add to / remove from the manifest `api_tools` include and exclude
- * lists (`POST /api/api-tools`). Each field is a bare name list; the server
- * refuses a body whose four lists are all empty.
- */
-export interface ApiToolsListsBody {
-  readonly include_add?: string[];
-  readonly include_remove?: string[];
-  readonly exclude_add?: string[];
-  readonly exclude_remove?: string[];
-}
-
-export interface StartConnectArgs {
-  readonly provider_id: string;
-  readonly alias: string;
-  readonly enabled_sub_services: string[];
-  readonly config_values?: Record<string, string>;
-  readonly return_url?: string;
-}
-
-/** Body for creating or editing an API key (POST/PUT `/api/auth/api-keys`). */
-export interface ApiKeyBody {
-  readonly user_id: string;
-  readonly description: string;
-  readonly scopes: string[];
-  // `null` is an explicit clear on edit (PATCH-style PUT): absent preserves the
-  // stored policy data, `null` wipes it. Create never sends `null`.
-  readonly policy_data?: Record<string, unknown> | null;
-  // The access-control condition: an authored templated-text value (inline content
-  // or a stored template id), or `null` to explicitly clear it on edit.
-  readonly condition?: s.TemplatedText | null;
-}
-
-/**
- * Body for one-time claim-link creation (POST `/api/auth/claim-links`). The
- * `api_key` is a raw key the caller holds (the just-minted key, client-side
- * exactly once); `ttl_seconds` optionally overrides the default lifetime (the
- * server caps it at its ceiling).
- */
-export interface ClaimLinkBody {
-  readonly api_key: string;
-  readonly ttl_seconds?: number | null;
-}
-
-/**
- * Body for the fail-closed jq guard (POST `/api/auth/validate-condition`). The guard
- * compile-checks the inline jq `condition` the author typed. `sample_context` is a
- * `JqAuthContext`-shaped sample; when present the guard also evaluates the condition
- * against it and returns the boolean `result` (else `result` is `null`).
- */
-export interface ValidateConditionBody {
-  readonly condition?: string;
-  readonly sample_context?: Record<string, unknown>;
-}
-
-/**
- * Body for binding a webhook verifier to a topic
- * (PUT `/api/hooks/topics/{topic}/verifier`). `verifier` is a registered verifier
- * NAME, resolved against the live registry at bind time (an unknown name is a loud
- * 400). `config` is that verifier's config object — it carries a `secret_env` name,
- * never a secret value — and defaults to `{}` when omitted.
- */
-export interface TopicVerifierBody {
-  readonly verifier: string;
-  readonly config?: Record<string, unknown>;
-}
-
-/**
- * Body for minting a trigger link (POST `/api/hooks/trigger-links`). `ttl_seconds`
- * is REQUIRED and nullable — a positive int is a timed link, `null` is a permanent
- * link (`0`/negative is a loud server 400); it is always sent EXPLICITLY (a dropped
- * key 400s server-side). `name` is optional (the server generates one when omitted);
- * `tool_kwargs` is the optional per-link params merged last into every fire.
- */
-export interface TriggerLinkCreateBody {
-  readonly topic: string;
-  readonly name?: string;
-  readonly execution_key: string;
-  // The link is a token door; this is its only auth knob (token → token+api_key).
-  readonly require_api_key: boolean;
-  readonly ttl_seconds: number | null;
-  readonly tool_kwargs?: Record<string, unknown> | null;
-}
-
-/**
- * Body for minting a web entry code (POST
- * `/api/channels/web/gates/{identity}/codes`). Both fields are optional-nullable
- * and sent EXPLICITLY: `label` is a human tag (`null` for none); `expires_at` is
- * an ISO-8601 instant the code dies at (`null` for a code that never expires).
- */
-export interface WebEntryCodeMintBody {
-  readonly label: string | null;
-  readonly expires_at: string | null;
-}
-
-/** Body for adding a URL to a scope (POST `/api/auth/scopes`). */
-export interface AddUrlToScopeBody {
-  readonly scope_id: string;
-  readonly url: string;
-  readonly pattern?: string;
-}
-
-/**
- * Body for creating a role (POST `/api/auth/roles`). `base_tier` is the security
- * tier the role inherits (`editor`/`viewer` — `admin` is reserved); its jq is
- * resolved server-side, never authored here. `grants` is the editable per-tag
- * access-level map (feature-group tag → `none`/`read`/`write`); it defaults to
- * empty (every group `none`, fail-closed) when omitted.
- */
-export interface RoleCreateBody {
-  readonly name: string;
-  readonly description?: string;
-  readonly base_tier: string;
-  readonly grants?: Record<string, s.GrantLevel>;
-}
-
-/**
- * Body for editing a role (PUT `/api/auth/roles/{name}`). Both fields are
- * omit-means-KEEP: an absent `grants` preserves the stored map (never a silent
- * wipe), an absent `description` preserves the stored description. The base-tier jq
- * is seed-fixed and not editable here.
- */
-export interface RoleUpdateBody {
-  readonly grants?: Record<string, s.GrantLevel>;
-  readonly description?: string;
-}
-
-/**
- * Body for pinning a route public (POST `/api/auth/public-routes`). `pattern` is an
- * optional regex the AC verifier full-matches request paths against, mapping every
- * match to the `url` key (so a mount's whole subtree can be pinned in one call).
- */
-export interface PinRoutePublicBody {
-  readonly url: string;
-  readonly pattern?: string;
-}
-
-/**
- * Body for creating a preset (POST `/api/presets`). `description` is the bound
- * tool's LLM-facing docstring — REQUIRED non-empty on every create path (the door
- * rejects an empty one with a 422); it is never the tool_meta `display_name`.
- * `extensions` is the combos list — the create flow OMITS it when there are no
- * combos (the route rejects an explicit `extensions: []`). `output_schema` is the
- * optional author-set output JSON Schema; `input_schema` is the optional author-set
- * input JSON Schema, read by the router as a top-level version field. Each combo
- * element is a bare extension name or a `{ name, config }` mapping. Categorization
- * tags live in the tool_meta overlay, written after a successful create — never in
- * this body.
- */
-export interface CreatePresetBody {
-  readonly name: string;
-  readonly base_tool: string;
-  readonly description: string;
-  readonly fixed_kwargs?: Record<string, unknown>;
-  readonly extensions?: readonly s.PresetExtensionElement[][];
-  readonly output_schema?: Record<string, unknown> | null;
-  readonly input_schema?: Record<string, unknown> | null;
-  // The optional door-layer state binding applied around every run of this preset.
-  readonly state_binding?: s.StateBinding | null;
-}
-
-/**
- * Body for saving a new preset version (POST `/api/presets/{name}/versions`). At
- * least one field must be provided (an empty body is a loud 400). Each field's
- * sentinel is uniform: omitted carries the active version's value forward; an
- * explicit `[]` clears `extensions`, and an explicit `null` clears `output_schema`
- * or `input_schema`. `input_schema` is the optional author-set input JSON Schema and
- * follows the same carry-forward sentinel as `output_schema`. `state_binding` is the
- * optional door-layer binding and follows the same sentinel: omitted carries the active
- * one forward, an explicit `null` clears it. `description` carries forward when omitted;
- * an explicit non-empty string sets it (the API rejects an explicit empty one).
- * Categorization tags are not a version field — they live in the tool_meta overlay.
- */
-export interface SavePresetVersionBody {
-  readonly fixed_kwargs?: Record<string, unknown>;
-  readonly description?: string;
-  readonly extensions?: readonly s.PresetExtensionElement[][];
-  readonly output_schema?: Record<string, unknown> | null;
-  readonly input_schema?: Record<string, unknown> | null;
-  readonly state_binding?: s.StateBinding | null;
-}
-
-/**
- * Body for the dry-run validate door (POST `/api/presets/validate`). `name` is
- * required and selects the verdict mode server-side: CREATE when no preset named
- * `name` exists (then `base_tool` is required), VERSION when one does (the version
- * fields are read under save-version semantics). The draft is sent exactly as the
- * matching write would send it.
- */
-export interface ValidatePresetBody {
-  readonly name: string;
-  readonly base_tool?: string;
-  readonly description?: string;
-  readonly fixed_kwargs?: Record<string, unknown>;
-  readonly extensions?: readonly s.PresetExtensionElement[][];
-  readonly output_schema?: Record<string, unknown> | null;
-  readonly input_schema?: Record<string, unknown> | null;
-  // The optional door-layer state binding to dry-run — validated (never mounted) by the
-  // same checks the write would run. In VERSION mode it follows the save-version sentinel:
-  // omitted carries the active binding forward, an explicit `null` clears it.
-  readonly state_binding?: s.StateBinding | null;
-}
-
-/**
- * Merge-patch body for a tool's overlay row (PATCH
- * `/api/tool-meta/tools/{tool_name}`). Only the fields PRESENT are written; a
- * present-null clears (`hidden: null` writes the tri-state "defer to the plugin
- * declaration" state, `display_name: null` clears the label, `folder_id: null`
- * unfiles); a present `tags` array replaces the whole set. Absent fields are left
- * untouched — there is no full-row replace, so a display-name+tags editor sends
- * ONLY those two keys with no risk to `folder_id`/`hidden`. At least one field must
- * be present. A blank/whitespace-only `display_name` is rejected by the API (422) —
- * callers map an emptied label to `null`, never `""`. A present `badges` array
- * replaces the whole overlay set (INFORMATIONAL labels, never an enforced gate).
- */
-export interface ToolMetaPatch {
-  readonly display_name?: string | null;
-  readonly folder_id?: string | null;
-  readonly tags?: readonly string[];
-  readonly badges?: readonly string[];
-  readonly hidden?: boolean | null;
-}
-
-/**
- * Body for a storage upload (POST `/api/storage/resources`). Exactly ONE of
- * `content_text` (stored verbatim) or `content_base64` (a base64 string decoded to
- * bytes) supplies the content for `id`; uploading an existing id overwrites it
- * (provider passthrough semantics).
- */
-export interface StorageUploadBody {
-  readonly id: string;
-  readonly content_text?: string;
-  readonly content_base64?: string;
-}
-
-/**
- * The thread-list filter set (GET `/api/conversations/{route}/threads` query
- * params, alongside `page`/`pageSize`). `status` narrows to threads whose newest
- * record sits in one delivery state; `address` is a SUBSTRING match over the
- * client address. Both omitted when undefined — an unfiltered listing.
- */
-export interface ConversationThreadFilters {
-  readonly status?: s.ConversationDeliveryStatus;
-  readonly address?: string;
-}
-
-/**
- * One transcript read (GET `/api/conversations/{route}/transcript` query params).
- * `order` is not a default the caller may skip: `asc` reads the thread from its
- * beginning and `desc` from its newest end, and which one a screen wants is a
- * decision that screen must make. `q` narrows the page to records whose text
- * matches it (a SUBSTRING), omitted for an unfiltered read.
- */
-export interface ConversationTranscriptQuery {
-  readonly routeName: string;
-  readonly threadId: string;
-  readonly page: number;
-  readonly pageSize: number;
-  readonly order: s.TranscriptOrder;
-  readonly q?: string;
-}
-
-/**
- * A route-scoped message search (GET
- * `/api/conversations/{route}/messages/search` query params). `q` is the required
- * needle — a substring over record text, across every thread on the route; `page`
- * is supplied per-request by the infinite query.
- */
-export interface ConversationMessageSearchQuery {
-  readonly routeName: string;
-  readonly q: string;
-  readonly page: number;
-  readonly pageSize: number;
-}
-
-/**
- * Body for sending a message into a thread (POST
- * `/api/conversations/{route}/thread/messages`). `thread_id` names the thread
- * (an api-door address, passed as a value); `text` is the message. `address` is
- * an optional override the server otherwise derives from the thread, omitted
- * when undefined.
- */
-export interface ConversationThreadMessageBody {
-  readonly thread_id: string;
-  readonly text: string;
-  readonly address?: string;
-}
-
-/** The observability-metrics window + bucket size (GET query params). */
-export interface MetricsQuery {
-  readonly from?: string;
-  readonly to?: string;
-  readonly granularity?: string;
-}
-
-/**
- * The observability runs filter. List/dict-valued params (`tags`) are
- * JSON-encoded into the query string; scalars are sent verbatim. Shared by
- * `listRuns` and the `exportRuns` download.
- */
-export interface RunsQuery {
-  readonly from?: string;
-  readonly to?: string;
-  readonly tags?: string[];
-  readonly status?: 'error' | 'success';
-  readonly minCost?: number;
-  readonly maxCost?: number;
-  readonly minTokens?: number;
-  readonly maxTokens?: number;
-  readonly minLatencyMs?: number;
-  readonly maxLatencyMs?: number;
-  readonly sort?: string;
-  readonly dir?: 'asc' | 'desc';
-  readonly page?: number;
-  readonly pageSize?: number;
-}
-
-/**
- * The marketplace search filter (GET `/api/marketplace/search` query params).
- * `tags` is sent as REPEATED `tags` params, one per value; `page` is supplied
- * per-request by the infinite query, never from the URL. `tier`, `namespace`,
- * `contract`, and `page_size` are accepted by the route but the v1 UI sends none
- * of them (every v1 row is official/tai42; the page size stays the server
- * default) — they exist for contract completeness.
- */
-export interface MarketplaceSearchQuery {
-  readonly q?: string;
-  readonly kind?: string;
-  readonly category?: string;
-  readonly tags?: string[];
-  readonly namespace?: string;
-  readonly tier?: string;
-  readonly contract?: string;
-  readonly sort?: 'downloads' | 'updated' | 'name' | 'relevance';
-  readonly page?: number;
-  readonly page_size?: number;
-}
-
-/**
- * Body for installing / updating a plugin. `ref` is `namespace/name`.
- *
- * `env` / `secret_keys` satisfy an mcp-server entry's required `!ENV` markers in
- * the same transaction that writes the entry: `env` supplies the values,
- * `secret_keys` marks which land in the secret band. Both omitted for a plain
- * install (no required markers).
- *
- * `route_mounts` maps a route-carrying item name to the base prefix its routes
- * mount under (the default or the operator's remap); `accept_public_routes`
- * explicitly consents to the routes served without authentication. Omitted for a
- * plugin that registers no routes.
- */
-export interface MarketplaceInstallBody {
-  readonly ref: string;
-  readonly version?: string;
-  readonly env?: Record<string, string>;
-  readonly secret_keys?: string[];
-  readonly route_mounts?: Record<string, string>;
-  readonly accept_public_routes?: boolean;
-}
-
-/**
- * Body for previewing an install / update (`POST /api/marketplace/install/preview`):
- * resolves the spec and computes the routes, collisions, and public rows WITHOUT
- * side effects. `route_mounts` applies base overrides so the operator sees the
- * effect of a remap before committing.
- */
-export interface MarketplaceInstallPreviewBody {
-  readonly ref: string;
-  readonly version?: string;
-  readonly route_mounts?: Record<string, string>;
-}
-
-/** Body for uninstalling a plugin. */
-export interface MarketplaceUninstallBody {
-  readonly ref: string;
-}
-
-/**
- * Encode a possibly-nested storage id / directory path for use in a URL path,
- * percent-encoding each segment while preserving the `/` separators. A storage id
- * can be a nested path (e.g. `a/b c.txt`); encoding each segment independently keeps
- * the slashes structural and escapes everything else (spaces, `#`, `?`, …).
- *
- * Dot segments (`.`, `..`), empty segments (a leading/trailing/doubled `/`, or an
- * empty id) are REJECTED loudly rather than encoded: the browser's WHATWG URL parser
- * removes dot-segments from a relative request path before it is sent — collapsing
- * `..` even when percent-encoded — so such an id can never be faithfully transmitted.
- * Left to encode, it would silently retarget the request at an unrelated same-origin
- * route. The server enforces the same relative-path rule; failing fast here keeps a
- * malformed id from ever leaving the client.
- */
-function encodePath(id: string): string {
-  const segments = id.split('/');
-  if (segments.some(isUnsafePathSegment)) {
-    throw new Error("storage path must be a relative path with no empty, '.', or '..' segment");
-  }
-  return segments.map(encodeURIComponent).join('/');
-}
-
-/** Flatten a `RunsQuery` to transport params, JSON-encoding the `tags` list. */
-function runsQueryToParams(query: RunsQuery): Required<RequestOptions>['query'] {
-  return {
-    from: query.from,
-    to: query.to,
-    tags: query.tags === undefined ? undefined : JSON.stringify(query.tags),
-    status: query.status,
-    minCost: query.minCost,
-    maxCost: query.maxCost,
-    minTokens: query.minTokens,
-    maxTokens: query.maxTokens,
-    minLatencyMs: query.minLatencyMs,
-    maxLatencyMs: query.maxLatencyMs,
-    sort: query.sort,
-    dir: query.dir,
-    page: query.page,
-    pageSize: query.pageSize,
-  };
-}
-
-/**
- * Whether a login-method target is a safe same-origin relative API path. The
- * login screen is the one page where a misconfigured/compromised manifest could
- * redirect CREDENTIALS off-origin, so a `submit_path`/`href` MUST start `/api/`
- * — anything else (absolute URL, protocol-relative `//host`, missing prefix) is
- * rejected. The `/api/` prefix already excludes `//`-prefixed values; the
- * explicit double-slash clause is kept for readability.
- */
-export function isSafeApiPath(path: string): boolean {
-  return path.startsWith('/api/') && !path.startsWith('//');
-}
-
-/**
- * Map a transport error from a login submission onto an `ApiLoginFailedError`
- * (rendered inline on the login page) or rethrow it unchanged (5xx, schema
- * drift, network — the page's generic failure branch surfaces it loudly).
- *
- * A transport 401 arrives as `ApiUnauthorizedError` before any body is read, so
- * its message is generic by construction; the domain 4xx statuses carry the
- * server's informative envelope text (rate-limit, bootstrap-already-initialized,
- * password-policy, or the claim exchange's uniform "unknown or already used"
- * 404) straight through to the inline surface.
- */
-function asLoginError(error: unknown): never {
-  if (error instanceof ApiUnauthorizedError) {
-    throw new ApiLoginFailedError('Sign-in failed — check your credentials.', 401);
-  }
-  if (
-    error instanceof ApiError &&
-    (error.status === 400 ||
-      error.status === 403 ||
-      error.status === 404 ||
-      error.status === 409 ||
-      error.status === 422 ||
-      error.status === 429)
-  ) {
-    throw new ApiLoginFailedError(error.message, error.status);
-  }
-  throw error;
-}
-
-/**
- * Body for the combined env+manifest secret op (POST `/api/mcp-config/secret-env`).
- * The server generates the env key from `value` (shaping the name from `key_hint`),
- * then writes the env value and the literal `!ENV ${KEY}` manifest leaf at
- * `manifest_pointer` atomically. `manifest_pointer`'s head segment MUST be `mcp`
- * (the server refuses any other with a loud 400).
- */
-export interface SetMcpSecretEnvBody {
-  readonly value: string;
-  readonly key_hint: string;
-  readonly manifest_pointer: string;
-}
-
-/**
- * The client-facing write body for a state declaration (`PUT /api/states/{name}`), the
- * wire shape of `tai42_contract.states.StateDeclaration` minus the platform-computed
- * `effective_schema`/`regimes` (those are read-only, refused on a write). `schema` is the
- * `TemplatedText | dict` union: an inline JSON-schema object, or a stored template reference
- * (`id` + render `kwargs`) the platform renders to the schema. `retention_days` is `null` to
- * keep records forever.
- */
-export interface StateDeclarationBody {
-  readonly name: string;
-  readonly description?: string;
-  readonly schema: s.TemplatedText | Record<string, unknown>;
-  readonly subject_kinds: readonly string[];
-  readonly default_subject_kind: string;
-  readonly retention_days?: number | null;
-}
-
-/**
- * A state-template document write body (`PUT /api/state-templates/{name}`, the platform half).
- * `schema` is the `TemplatedText | dict` union — an inline fragment schema, or a stored
- * template reference the platform renders to the fragment.
- */
-export interface StateTemplateBody {
-  readonly name: string;
-  readonly description?: string;
-  readonly parameters?: Record<string, unknown>;
-  readonly schema: s.TemplatedText | Record<string, unknown>;
-  readonly regimes?: Record<string, unknown>[];
-  readonly declarations?: Record<string, unknown> | null;
-  readonly trace?: Record<string, unknown>;
-}
-
-/** A template attach / re-attach body (`PUT|PATCH /api/states/{name}/attachments/{template}`). */
-export interface StateAttachmentBody {
-  readonly path?: string[];
-  readonly parameters?: Record<string, unknown>;
-  readonly declarations?: Record<string, unknown>;
-  // Reconcile directive for a re-attach that would orphan open records: retry with
-  // `{ orphans: "close", resolution: "<name>" }` to close them (the server refuses
-  // without it). Omitted on a first attach.
-  readonly options?: Record<string, unknown>;
-}
-
-/** The four-part subject a record route addresses in its path. */
-export interface StateSubjectRef {
-  readonly target_kind: string;
-  readonly target_name: string;
-  readonly kind: string;
-  readonly key: string;
-}
-
-/** A keyset page request: an optional size and the opaque cursor a prior page returned. */
-export interface StatePageQuery {
-  readonly limit?: number;
-  readonly cursor?: string;
-}
-
-/**
- * The subject-addressed record path: `/api/states/{name}/records/{target_kind}/
- * {target_name}/{kind}/{key}` — four path segments, each percent-encoded, so a key
- * carrying a slash or a colon never escapes its segment.
- */
-function stateRecordPath(name: string, subject: StateSubjectRef): string {
-  return (
-    `/api/states/${encodeSegment(name)}/records/` +
-    `${encodeSegment(subject.target_kind)}/${encodeSegment(subject.target_name)}/` +
-    `${encodeSegment(subject.kind)}/${encodeSegment(subject.key)}`
-  );
-}
-
-/**
- * Encode a template jq's declared params as JSON query values: the record `template-jq`
- * route reads each `?<param>=<json>` as a JSON-decoded argument, so a string, number,
- * array or object round-trips faithfully. An `undefined` value is dropped (an
- * omitted optional param).
- */
-function encodeJqParams(params?: Record<string, unknown>): Record<string, string> | undefined {
-  if (params === undefined) return undefined;
-  const query: Record<string, string> = {};
-  for (const [key, value] of Object.entries(params)) {
-    if (value === undefined) continue;
-    query[key] = JSON.stringify(value);
-  }
-  return query;
-}
-
-export function createApiClient(config: ApiConfig) {
-  const req = <S extends Parameters<typeof apiRequest>[2]>(
-    path: string,
-    schema: S,
-    options?: Parameters<typeof apiRequest>[3],
-  ) => apiRequest(config, path, schema, options);
-
-  return {
-    // The configured API base — the exact `baseUrl` this client was constructed
-    // with (`''` for a same-origin deployment). Read-only: features that must
-    // compose an ABSOLUTE API URL (a QR-encoded public path the API origin must
-    // receive, not the SPA origin) read it instead of assuming same-origin. The
-    // transport itself still joins it per request; this only surfaces the value.
-    baseUrl: config.baseUrl ?? '',
-
-    // -- tools ---------------------------------------------------------------
-    listTools: (signal?: AbortSignal) => req('/api/tools', s.toolNames, { signal }),
-    getToolSchema: (name: string, signal?: AbortSignal) =>
-      req(`/api/tools/${encodeSegment(name)}/schema`, s.toolSchema, { signal }),
-    getAllToolSchemas: (signal?: AbortSignal) =>
-      req('/api/tools-schema', s.allToolSchemas, { signal }),
-    runTool: (args: RunToolArgs, signal?: AbortSignal) =>
-      req('/api/run-tool', s.runToolResult, {
-        method: 'POST',
-        // The backend's `/api/run-tool` door reads `{tool_name, arguments}` (the
-        // shape `read_tool_call` enforces and the background `/api/tool-runs`
-        // submit already sends). The SPA keeps `tool`/`kwargs` as its ergonomic
-        // arg names; map them onto the wire fields here.
-        body: { tool_name: args.tool, arguments: args.kwargs ?? {} },
-        signal,
-      }),
-
-    // -- app tool live-registry admin ----------------------------------------
-    // Re-register or remove one app tool by kind+name, applied on this worker and
-    // broadcast to the fleet (all workers, or only `targets`); both return the bare
-    // per-worker `fleetResult` the shared fleet-report handler renders. Both are
-    // fenced + destructive server-side, so a refusal surfaces as a loud error.
-    reloadTool: (args: ToolAdminArgs) =>
-      req('/api/tools/reload', s.fleetResult, {
-        method: 'POST',
-        body: { kind: args.kind, name: args.name, targets: args.targets ?? null },
-      }),
-    removeTool: (args: ToolAdminArgs) =>
-      req('/api/tools/remove', s.fleetResult, {
-        method: 'POST',
-        body: { kind: args.kind, name: args.name, targets: args.targets ?? null },
-      }),
-
-    // -- background tool runs ------------------------------------------------
-    submitToolRun: (args: SubmitToolRunArgs, signal?: AbortSignal) =>
-      submitToolRun(config, args, signal),
-    getToolRun: (runId: string, signal?: AbortSignal) => getToolRun(config, runId, signal),
-    listToolRuns: (toolName: string, signal?: AbortSignal) =>
-      listToolRuns(config, toolName, signal),
-
-    // -- tool tags (additive map feeding the ToolPicker tag grouping) --------
-    listToolTags: (signal?: AbortSignal) => req('/api/tools/tags', s.toolTags, { signal }),
-
-    // -- presets -------------------------------------------------------------
-    // Every preset is store-backed and versioned; the list is the single
-    // management population (the presets plus the conflicted quarantined rows).
-    listPresets: (signal?: AbortSignal) => req('/api/presets', s.presetList, { signal }),
-    createPreset: (body: CreatePresetBody) =>
-      req('/api/presets', s.presetRecord, { method: 'POST', body }),
-    getPreset: (name: string, signal?: AbortSignal) =>
-      req(`/api/presets/${encodeSegment(name)}`, s.presetDetail, { signal }),
-    listPresetVersions: (name: string, signal?: AbortSignal) =>
-      req(`/api/presets/${encodeSegment(name)}/versions`, s.presetVersionList, { signal }),
-    getPresetVersion: (name: string, version: number, signal?: AbortSignal) =>
-      req(
-        `/api/presets/${encodeSegment(name)}/versions/${encodeSegment(version)}`,
-        s.presetVersion,
-        { signal },
-      ),
-    savePresetVersion: (name: string, body: SavePresetVersionBody) =>
-      req(`/api/presets/${encodeSegment(name)}/versions`, s.presetVersion, {
-        method: 'POST',
-        body,
-      }),
-    rollbackPreset: (name: string, version: number) =>
-      req(`/api/presets/${encodeSegment(name)}/rollback`, s.presetRollback, {
-        method: 'POST',
-        body: { version },
-      }),
-    deletePreset: (name: string) =>
-      req(`/api/presets/${encodeSegment(name)}`, s.presetDeleted, { method: 'DELETE' }),
-    renamePreset: (name: string, newName: string) =>
-      req(`/api/presets/${encodeSegment(name)}/rename`, s.presetRenamed, {
-        method: 'POST',
-        body: { new_name: newName },
-      }),
-    // The presets whose active composition names this one as a tool — the referees
-    // a rename would strand. A rename preflight reads this to warn before the 409.
-    getPresetReferees: (name: string, signal?: AbortSignal) =>
-      req(`/api/presets/${encodeSegment(name)}/referees`, s.presetReferees, { signal }),
-    // The dry-run verdict for a draft (create OR version, mode-resolved server-side):
-    // `valid` plus the server's verbatim `error` message. Both verdicts are HTTP 200.
-    validatePreset: (body: ValidatePresetBody) =>
-      req('/api/presets/validate', s.presetValidation, { method: 'POST', body }),
-    // Replace one version's `tags` annotation — labels on an immutable body, so no
-    // rebind. Returns the re-annotated identity + new tag list.
-    setPresetVersionTags: (name: string, version: number, tags: readonly string[]) =>
-      req(
-        `/api/presets/${encodeSegment(name)}/versions/${encodeSegment(version)}/tags`,
-        s.presetVersionTags,
-        { method: 'PUT', body: { tags } },
-      ),
-
-    // -- states --------------------------------------------------------------
-    // A state is a declared JSON document, one per subject. The list is the
-    // management population; a single state read composes the declaration with its
-    // effective schema, regimes and attachments. Every record route addresses its subject
-    // as four percent-encoded path segments (see `stateRecordPath`).
-    listStates: (signal?: AbortSignal) => req('/api/states', s.stateList, { signal }),
-    getState: (name: string, signal?: AbortSignal) =>
-      req(`/api/states/${encodeSegment(name)}`, s.stateDetail, { signal }),
-    // A plain declaration upsert — no `replace` flag. With records present the server
-    // accepts additive schema changes and refuses with a 409 any change that removes or
-    // alters an existing field, or a subject-kind removal that would strand records.
-    putState: (name: string, body: StateDeclarationBody) =>
-      req(`/api/states/${encodeSegment(name)}`, s.stateDetail, {
-        method: 'PUT',
-        body,
-      }),
-    deleteState: (name: string) =>
-      req(`/api/states/${encodeSegment(name)}`, s.stateDeleted, { method: 'DELETE' }),
-    getStateStats: (name: string, signal?: AbortSignal) =>
-      req(`/api/states/${encodeSegment(name)}/stats`, s.stateStats, { signal }),
-    // -- state template attachments ------------------------------------------
-    listStateAttachments: (name: string, signal?: AbortSignal) =>
-      req(`/api/states/${encodeSegment(name)}/attachments`, s.stateAttachmentList, { signal }),
-    getStateAttachment: (name: string, template: string, signal?: AbortSignal) =>
-      req(
-        `/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`,
-        s.stateAttachment,
-        { signal },
-      ),
-    attachStateTemplate: (name: string, template: string, body: StateAttachmentBody) =>
-      req(
-        `/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`,
-        s.stateAttached,
-        { method: 'PUT', body },
-      ),
-    patchStateAttachment: (name: string, template: string, body: StateAttachmentBody) =>
-      req(
-        `/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`,
-        s.stateAttachmentUpdated,
-        { method: 'PATCH', body },
-      ),
-    detachStateTemplate: (name: string, template: string) =>
-      req(
-        `/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`,
-        s.stateDetached,
-        { method: 'DELETE' },
-      ),
-    // -- state subjects + records -------------------------------------------
-    listStateSubjects: (
-      name: string,
-      params: { kind?: string } & StatePageQuery,
-      signal?: AbortSignal,
-    ) =>
-      req(`/api/states/${encodeSegment(name)}/subjects`, s.subjectPage, {
-        signal,
-        query: { kind: params.kind, limit: params.limit, cursor: params.cursor },
-      }),
-    // The content search body is a single JSONB containment document (`filters`); the
-    // server refuses an empty one, so the UI validates a non-empty object first.
-    searchStateRecords: (
-      name: string,
-      body: { filters: Record<string, unknown> } & StatePageQuery,
-      signal?: AbortSignal,
-    ) =>
-      req(`/api/states/${encodeSegment(name)}/records/search`, s.recordSearchPage, {
-        method: 'POST',
-        body,
-        signal,
-      }),
-    // A subject with no document yet reads as `null` (a 200 `{data: null}`, the record
-    // page's Create path) — never an error, so the schema is nullable.
-    getStateRecord: (name: string, subject: StateSubjectRef, signal?: AbortSignal) =>
-      req(stateRecordPath(name, subject), s.stateRecord.nullable(), { signal }),
-    putStateRecord: (name: string, subject: StateSubjectRef, data: Record<string, unknown>) =>
-      req(stateRecordPath(name, subject), s.stateRecord, { method: 'PUT', body: data }),
-    patchStateRecord: (name: string, subject: StateSubjectRef, data: Record<string, unknown>) =>
-      req(stateRecordPath(name, subject), s.stateRecord, { method: 'PATCH', body: data }),
-    applyStateRecord: (
-      name: string,
-      subject: StateSubjectRef,
-      ops: readonly Record<string, unknown>[],
-    ) =>
-      req(`${stateRecordPath(name, subject)}/deltas`, s.applyResult, {
-        method: 'POST',
-        body: { ops },
-      }),
-    // Evaluate a template jq over the subject: each declared param is JSON-encoded into
-    // the query string (`?<param>=<json>`); the response is `{name, purpose, value}`. An
-    // `attachment.name` jq is percent-encoded as one path segment.
-    evalTemplateJq: (
-      name: string,
-      subject: StateSubjectRef,
-      jqName: string,
-      params?: Record<string, unknown>,
-      signal?: AbortSignal,
-    ) =>
-      req(
-        `${stateRecordPath(name, subject)}/template-jq/${encodeSegment(jqName)}`,
-        s.templateJqResult,
-        { signal, query: encodeJqParams(params) },
-      ),
-    // Apply an `update`-purpose template jq to the subject: `input` is the jq's argument,
-    // `op_id` its idempotency key (a replay is a no-op). The jq lands its op batch through
-    // the apply chokepoint. An `attachment.name` jq is percent-encoded as one path segment.
-    applyTemplateJq: (
-      name: string,
-      subject: StateSubjectRef,
-      jqName: string,
-      body?: { input?: unknown; op_id?: string },
-    ) =>
-      req(
-        `${stateRecordPath(name, subject)}/template-jq/${encodeSegment(jqName)}`,
-        s.templateJqApplyResult,
-        { method: 'POST', body: body ?? {} },
-      ),
-    deleteStateRecord: (name: string, subject: StateSubjectRef) =>
-      req(stateRecordPath(name, subject), s.recordErased, { method: 'DELETE' }),
-    // `mode` is required server-side (`switch` drops, `merge` combines); the fold returns
-    // a report, not the surviving record.
-    foldStateRecord: (
-      name: string,
-      subject: StateSubjectRef,
-      into: StateSubjectRef,
-      mode: 'switch' | 'merge',
-    ) =>
-      req(`${stateRecordPath(name, subject)}/fold`, s.stateFoldReport, {
-        method: 'POST',
-        body: { into, mode },
-      }),
-    listStateWrites: (
-      name: string,
-      subject: StateSubjectRef,
-      params?: StatePageQuery,
-      signal?: AbortSignal,
-    ) =>
-      req(`${stateRecordPath(name, subject)}/writes`, s.writesPage, {
-        signal,
-        query: { limit: params?.limit, cursor: params?.cursor },
-      }),
-    stateConsumers: (name: string, signal?: AbortSignal) =>
-      req(`/api/states/${encodeSegment(name)}/consumers`, s.stateConsumers, { signal }),
-    // -- state-template documents (top-level sibling collection) ---------------
-    listStateTemplates: (signal?: AbortSignal) =>
-      req('/api/state-templates', s.stateTemplateList, { signal }),
-    getStateTemplate: (name: string, signal?: AbortSignal) =>
-      req(`/api/state-templates/${encodeSegment(name)}`, s.stateTemplateDocument, { signal }),
-    putStateTemplate: (name: string, body: StateTemplateBody, replace?: boolean) =>
-      req(`/api/state-templates/${encodeSegment(name)}`, s.stateTemplateDocument, {
-        method: 'PUT',
-        body,
-        query: replace === true ? { replace: 'true' } : undefined,
-      }),
-    deleteStateTemplate: (name: string) =>
-      req(`/api/state-templates/${encodeSegment(name)}`, s.stateTemplateDeleted, {
-        method: 'DELETE',
-      }),
-    // -- state retention -----------------------------------------------------
-    pruneStateRetention: () =>
-      req('/api/state-retention/prune', s.stateRetentionPruned, { method: 'POST', body: {} }),
-
-    // -- tool_meta (the organizational overlay) ------------------------------
-    // The folder tree + per-tool overlay rows in one read; the features merge the
-    // rows against the live tool list and native tags client-side.
-    listToolMeta: (signal?: AbortSignal) => req('/api/tool-meta', s.toolMetaOverlay, { signal }),
-    // Merge-patch a tool's overlay row (create it if absent). `patch` carries ONLY
-    // the fields to change — a present-null clears, an absent field is untouched,
-    // and a present `tags` array replaces the set.
-    upsertToolMeta: (toolName: string, patch: ToolMetaPatch) =>
-      req(`/api/tool-meta/tools/${encodeSegment(toolName)}`, s.toolMetaRecord, {
-        method: 'PATCH',
-        body: patch,
-      }),
-    deleteToolMeta: (toolName: string) =>
-      req(`/api/tool-meta/tools/${encodeSegment(toolName)}`, s.toolMetaDeleted, {
-        method: 'DELETE',
-      }),
-    createFolder: (name: string, parentId: string | null = null) =>
-      req('/api/tool-meta/folders', s.folderRecord, {
-        method: 'POST',
-        body: { name, parent_id: parentId },
-      }),
-    renameFolder: (folderId: string, name: string) =>
-      req(`/api/tool-meta/folders/${encodeSegment(folderId)}/rename`, s.folderRecord, {
-        method: 'POST',
-        body: { name },
-      }),
-    // `null` re-parents to the root.
-    moveFolder: (folderId: string, parentId: string | null) =>
-      req(`/api/tool-meta/folders/${encodeSegment(folderId)}/move`, s.folderRecord, {
-        method: 'POST',
-        body: { parent_id: parentId },
-      }),
-    deleteFolder: (folderId: string) =>
-      req(`/api/tool-meta/folders/${encodeSegment(folderId)}`, s.folderDeleted, {
-        method: 'DELETE',
-      }),
-
-    // -- storage -------------------------------------------------------------
-    // The content store a storage-provider plugin exposes. Dead by default:
-    // `getStorageInfo` reports `present: false` (a 200 empty state) and every other
-    // door answers a loud 501 when no provider is installed. Ids may be nested
-    // paths, so each is `encodePath`-encoded (per-segment, `/` preserved).
-    getStorageInfo: (signal?: AbortSignal) => req('/api/storage', s.storageInfo, { signal }),
-    listStorageResources: (signal?: AbortSignal) =>
-      req('/api/storage/resources', s.storageResourceList, { signal }),
-    statStorageResource: (id: string, signal?: AbortSignal) =>
-      req(`/api/storage/resources/${encodePath(id)}/stat`, s.storageResourceStat, { signal }),
-    downloadStorageResource: (id: string, signal?: AbortSignal): Promise<Blob> =>
-      apiDownload(config, `/api/storage/resources/${encodePath(id)}/content`, { signal }),
-    uploadStorageResource: (body: StorageUploadBody) =>
-      req('/api/storage/resources', s.storageResourceStored, { method: 'POST', body }),
-    deleteStorageResource: (id: string) =>
-      req(`/api/storage/resources/${encodePath(id)}`, s.storageResourceDeleted, {
-        method: 'DELETE',
-      }),
-    deleteStorageDir: (path: string) =>
-      req(`/api/storage/dirs/${encodePath(path)}`, s.storageDirDeleted, { method: 'DELETE' }),
-
-    // -- backend identity + fleet (worker bus) -------------------------------
-    // Backend IDENTITY (`getBackendInfo`, kept on `/api/backend`) is distinct from
-    // the FLEET doors, which ride the app's worker bus and need no backend at all.
-    // `getBackendInfo` reports `present: false` (a 200 empty state) when no backend
-    // plugin is registered. `listFleetWorkers` reads the live bus presence census
-    // (every subscribed worker, ASGI + backend-runtime) and never fabricates an empty
-    // fleet — a census read that fails surfaces as a loud 500.
-    getBackendInfo: (signal?: AbortSignal) => req('/api/backend', s.backendInfo, { signal }),
-    listFleetWorkers: (signal?: AbortSignal) =>
-      req('/api/fleet/workers', s.fleetWorkers, { signal }),
-    // Soft-restart the fleet: `targets` names the workers to reload, or `null` for
-    // the whole fleet. The serving worker applies locally then broadcasts; a 200
-    // response carries the per-worker fleet report, so workers that did not converge
-    // are named, not hidden. A failed local apply instead re-raises as a loud error
-    // (the transport throws with the failure message), not a returned report.
-    reloadFleetConfig: (targets: string[] | null) =>
-      req('/api/fleet/reload-config', s.fleetReloadResult, { method: 'POST', body: { targets } }),
-
-    // -- extensions ----------------------------------------------------------
-    listExtensions: (signal?: AbortSignal) => req('/api/extensions', s.extensions, { signal }),
-    // A MANIFEST-provided tool's current combos + the extension catalog. (A preset
-    // tool's extensions live on the preset spec, read via `getPreset`.)
-    getToolExtensions: (name: string, signal?: AbortSignal) =>
-      req(`/api/tools/${encodeSegment(name)}/extensions`, s.toolExtensions, { signal }),
-    // Author ALL of a MANIFEST tool's combos at once (the full lossless list; `[]`
-    // clears). Returns the apply result: the local reload (`status` + `env_keys`) plus
-    // the mode-wrapped fleet `fanout` of the reload it broadcast, from which the shared
-    // fleet-report handler surfaces any failed propagation.
-    setToolExtensions: (name: string, combos: readonly s.PresetExtensionElement[][]) =>
-      req(`/api/tools/${encodeSegment(name)}/extensions`, s.toolExtensionsApplyResult, {
-        method: 'POST',
-        body: { combos },
-      }),
-
-    // -- templates -----------------------------------------------------------
-    listTemplates: (signal?: AbortSignal) => req('/api/templates', s.templateNames, { signal }),
-    getTemplate: (templateId: string) =>
-      req('/api/template', s.templateDetail, { method: 'POST', body: { template_id: templateId } }),
-    uploadTemplate: (path: string, content: string) =>
-      req('/api/upload-template', s.templateUploaded, { method: 'POST', body: { path, content } }),
-    deleteTemplate: (path: string) =>
-      req('/api/delete-template', s.templateDeleted, { method: 'POST', body: { path } }),
-    // Delete every stored template under a directory prefix. Unlike the idempotent
-    // single delete, the server 404s a prefix matching nothing and 400s the template
-    // root; those surface as loud errors, never a faked success.
-    deleteTemplateDir: (path: string) =>
-      req('/api/delete-template-dir', s.templateDirDeleted, { method: 'POST', body: { path } }),
-    // Render one authored text — inline `content` OR a stored template `id`, plus its
-    // render `kwargs` — and parse the rendered output. The value is the shared
-    // `TemplatedText` (exactly one source); the route wraps it under `text`.
-    renderTemplate: (text: s.TemplatedText) =>
-      req('/api/render-template', s.templateRendered, { method: 'POST', body: { text } }),
-    clearTemplatesCache: () =>
-      req('/api/clear-templates-cache', s.templateCacheCleared, { method: 'POST' }),
-
-    // -- manifest / mcp ------------------------------------------------------
-    getManifest: (signal?: AbortSignal) => req('/api/manifest', s.manifestView, { signal }),
-    setMcpConfig: (mcp: unknown[]) =>
-      req('/api/mcp-config', s.reloadConfigResult, { method: 'POST', body: { mcp } }),
-    getMcpStatus: (signal?: AbortSignal) => req('/api/mcp-status', s.mcpStatus, { signal }),
-    reloadMcp: (title: string) =>
-      req(`/api/mcp-status/${encodeSegment(title)}/reload`, s.mcpReloadResult, {
-        method: 'POST',
-      }),
-
-    // Granular manifest-section entry edits — add/replace or remove ONE entry by
-    // title, leaving the rest of the section untouched (the surgical counterpart to
-    // the whole-section `setMcpConfig`). Each crosses the config pipeline and returns
-    // the shared apply-result (`status` + `env_keys` + fleet `fanout`). `replace` lets
-    // an entry whose title already exists swap in; without it a collision is refused.
-    addToolsEntries: (entries: readonly unknown[], replace = false) =>
-      req('/api/tools-config/entries', s.reloadConfigResult, {
-        method: 'POST',
-        body: { entries, replace },
-      }),
-    removeToolsEntry: (title: string) =>
-      req(`/api/tools-config/entries/${encodeSegment(title)}`, s.reloadConfigResult, {
-        method: 'DELETE',
-      }),
-    addAgentsEntries: (entries: readonly unknown[], replace = false) =>
-      req('/api/agents-config/entries', s.reloadConfigResult, {
-        method: 'POST',
-        body: { entries, replace },
-      }),
-    removeAgentsEntry: (title: string) =>
-      req(`/api/agents-config/entries/${encodeSegment(title)}`, s.reloadConfigResult, {
-        method: 'DELETE',
-      }),
-    // Edit the manifest `api_tools` include/exclude name lists by delta (add/remove
-    // names on either list). Absent fields default to empty; the server refuses a body
-    // whose four lists are all empty. Returns the shared apply-result.
-    updateApiTools: (body: ApiToolsListsBody) =>
-      req('/api/api-tools', s.reloadConfigResult, {
-        method: 'POST',
-        body: {
-          include_add: body.include_add ?? [],
-          include_remove: body.include_remove ?? [],
-          exclude_add: body.exclude_add ?? [],
-          exclude_remove: body.exclude_remove ?? [],
-        },
-      }),
-
-    // -- failed-MCP health ---------------------------------------------------
-    // The MCP servers skipped by the viability check, plus their remediation ops. The
-    // LIST rides the fleet fan-out primitive (each worker's failed roster arrives as
-    // its own report payload; `failedMcpsFromReport` unions them). Reload-all re-probes
-    // every failed server; deregister detaches one server's tools by title. Each op
-    // returns the bare per-worker `fleetResult`.
-    listFailedMcps: (signal?: AbortSignal) =>
-      req('/api/mcp-status/failed', s.fleetResult, { signal }),
-    reloadFailedMcps: () =>
-      req('/api/mcp-status/reload-failed', s.fleetResult, {
-        method: 'POST',
-        body: { targets: null },
-      }),
-    deregisterMcp: (title: string) =>
-      req(`/api/mcp-status/${encodeSegment(title)}/deregister`, s.fleetResult, {
-        method: 'POST',
-        body: { targets: null },
-      }),
-
-    // -- sub-mcp -------------------------------------------------------------
-    listSubMcp: (signal?: AbortSignal) => req('/api/sub-mcp', s.subMcpList, { signal }),
-    // `transport` is optional at the client boundary (the server defaults it to
-    // `http`); when omitted, JSON.stringify drops the undefined key from the body.
-    createSubMcp: (slug: string, tools: string[], transport?: string) =>
-      req('/api/sub-mcp', s.subMcpCreated, { method: 'POST', body: { slug, tools, transport } }),
-    deleteSubMcp: (slug: string) =>
-      req(`/api/sub-mcp/${encodeSegment(slug)}`, s.subMcpRemoved, { method: 'DELETE' }),
-
-    // -- config --------------------------------------------------------------
-    getEnvConfig: (signal?: AbortSignal) => req('/api/config/env', s.envConfig, { signal }),
-    setEnvConfig: (env: Record<string, string>) =>
-      req('/api/config/env', s.reloadConfigResult, { method: 'POST', body: env }),
-    getConfigMode: (signal?: AbortSignal) => req('/api/config/mode', s.configMode, { signal }),
-    // The LOCAL soft-restart door (distinct from the System page's fleet door
-    // `/api/fleet/reload-config`): refresh env from the config manager, reset the
-    // settings caches, and re-initialize from the manifest — applied on the serving
-    // worker and broadcast to the fleet (all workers, or only `targets`; `null` = all).
-    // Admin-`fenced`; the 200 body is the bare per-worker fleet report so an
-    // unconverged sibling is visible, never hidden.
-    reloadConfig: (targets: string[] | null = null) =>
-      req('/api/config/reload', s.fleetReloadResult, { method: 'POST', body: { targets } }),
-
-    // -- settings profiles ---------------------------------------------------
-    // The admin-only `/api/config/profiles/*` surface. Bodies/diff/versions carry
-    // REAL secret values (secret/fenced routes); masking is CLIENT-SIDE.
-    listSettingsProfiles: (signal?: AbortSignal) =>
-      req('/api/config/profiles', s.settingsProfileList, { signal }),
-    getSettingsProfile: (name: string, signal?: AbortSignal) =>
-      req(`/api/config/profiles/${encodeSegment(name)}`, s.settingsProfileBody, { signal }),
-    putSettingsProfile: (name: string, body: s.SettingsProfileBody) =>
-      req(`/api/config/profiles/${encodeSegment(name)}`, s.settingsProfileSaved, {
-        method: 'PUT',
-        body,
-      }),
-    deleteSettingsProfile: (name: string) =>
-      req(`/api/config/profiles/${encodeSegment(name)}`, s.settingsProfileDeleted, {
-        method: 'DELETE',
-      }),
-    // Diff of the SAVED profile vs the stored env — server-computed, no request body.
-    diffSettingsProfile: (name: string) =>
-      req(`/api/config/profiles/${encodeSegment(name)}/diff`, s.settingsProfileDiff, {
-        method: 'POST',
-      }),
-    // Apply the SAVED profile (full-replace of the profile-managed band). Fenced,
-    // destructive → the dedicated `profile_apply_response` report.
-    applySettingsProfile: (name: string) =>
-      req(`/api/config/profiles/${encodeSegment(name)}/apply`, s.profileApplyResponse, {
-        method: 'POST',
-      }),
-    listSettingsProfileVersions: (name: string, signal?: AbortSignal) =>
-      req(`/api/config/profiles/${encodeSegment(name)}/versions`, s.settingsProfileVersionList, {
-        signal,
-      }),
-    getSettingsProfileVersion: (name: string, version: number, signal?: AbortSignal) =>
-      req(
-        `/api/config/profiles/${encodeSegment(name)}/versions/${encodeSegment(version)}`,
-        s.settingsProfileVersion,
-        { signal },
-      ),
-    rollbackSettingsProfile: (name: string, version: number) =>
-      req(`/api/config/profiles/${encodeSegment(name)}/rollback`, s.settingsProfileRollback, {
-        method: 'POST',
-        body: { version },
-      }),
-
-    // -- combined env+manifest op + preserved manifest -----------------------
-    // The SecretRefField server half: one atomic env-value + `!ENV` manifest
-    // write, returning the shared apply-result shape (reload + fleet fanout).
-    setMcpSecretEnv: (body: SetMcpSecretEnvBody) =>
-      req('/api/mcp-config/secret-env', s.reloadConfigResult, { method: 'POST', body }),
-    // The PRESERVED manifest (`!ENV` markers intact, no resolved secrets) — the
-    // connectors page's McpServersSection reads this so round-trips never inline
-    // resolved values.
-    getManifestPreserved: (signal?: AbortSignal) =>
-      req('/api/manifest/preserved', s.manifestView, { signal }),
-    // The manifest MCP section's `!ENV ${VAR[:default]}` marker refs — NAMES and
-    // set/unset BOOLEANS only, never values. Drives the McpServersSection env-refs
-    // checklist on the connectors page.
-    getMcpEnvRefs: (signal?: AbortSignal) =>
-      req('/api/manifest/mcp-env-refs', s.mcpEnvRefs, { signal }),
-
-    // -- connectors ----------------------------------------------------------
-    listProviders: (signal?: AbortSignal) =>
-      req('/api/connectors/providers', s.providers, { signal }),
-    listConnections: (signal?: AbortSignal) =>
-      req('/api/connectors/connections', s.connectionsList, { signal }),
-    getConnection: (id: string, signal?: AbortSignal) =>
-      req(`/api/connectors/connections/${encodeSegment(id)}`, s.connectionView, { signal }),
-    startConnect: (args: StartConnectArgs) =>
-      req('/api/connectors/connections/start', s.startConnectResult, {
-        method: 'POST',
-        body: args,
-      }),
-    disconnect: (id: string) =>
-      req(`/api/connectors/connections/${encodeSegment(id)}`, s.disconnectResult, {
-        method: 'DELETE',
-      }),
-    reconnect: (id: string, enabled_sub_services: string[], return_url?: string) =>
-      req(`/api/connectors/connections/${encodeSegment(id)}/reconnect`, s.reconnectResult, {
-        method: 'POST',
-        body: { enabled_sub_services, return_url },
-      }),
-    patchSubServices: (id: string, enabled_sub_services: string[], return_url?: string) =>
-      req(
-        `/api/connectors/connections/${encodeSegment(id)}/sub-services`,
-        s.patchSubServicesResult,
-        {
-          method: 'PATCH',
-          body: { enabled_sub_services, return_url },
-        },
-      ),
-    completeOAuth: (state: string, code: string, error?: string) =>
-      req('/api/connectors/oauth/complete', s.oauthCompleteResult, {
-        method: 'POST',
-        body: { state, code, error },
-      }),
-
-    // -- studio plugin registry ---------------------------------------------
-    listStudioPlugins: (signal?: AbortSignal) =>
-      req('/api/plugins', s.studioPluginRegistry, { signal }),
-
-    // -- interactions --------------------------------------------------------
-    // One page of the pending interactions (the tail-only stream's paged base). The
-    // door filters by audience before paging — the SAME filter the stream applies —
-    // so `total` is the caller's own count, and every terminal frame it later receives
-    // refers to a question within that `total`.
-    listInteractions: (page: number, pageSize: number, signal?: AbortSignal) =>
-      req('/api/interactions', s.interactionsPage, { signal, query: { page, pageSize } }),
-    answerInteraction: (interactionId: string, answer: unknown) =>
-      req(`/api/interactions/${encodeSegment(interactionId)}/answer`, s.interactionAnswered, {
-        method: 'POST',
-        body: { answer },
-      }),
-    // Withdraw a pending ask WITHOUT answering it (a bodyless POST): the question is
-    // resolved as cancelled and the flow that asked never resumes. Terminal like an
-    // answer, so the loud failure mappings mirror it — a 409 (already answered, so no
-    // longer cancellable) surfaces as `ApiConflictError`, a 404 (unknown/already gone)
-    // and a 403 (not this caller's audience) as `ApiError` — all via the shared
-    // `apiRequest` status handling.
-    cancelInteraction: (interactionId: string) =>
-      req(`/api/interactions/${encodeSegment(interactionId)}/cancel`, s.interactionCancelled, {
-        method: 'POST',
-      }),
-
-    // -- channels --------------------------------------------------------------
-    // The installed channel-plugin names (delivery media for ask_user questions).
-    listChannels: (signal?: AbortSignal) => req('/api/channels', s.channels, { signal }),
-
-    // -- conversations ---------------------------------------------------------
-    // The stored routing rows, each with its `callback_secret` withheld — the
-    // conversation monitor's route picker.
-    listConversationRoutes: (signal?: AbortSignal) =>
-      req('/api/conversations', s.conversationRoutes, { signal }),
-    // Create or REPLACE a route (an UPSERT: the same door is the create and the
-    // edit path). `route_name` rides the URL path AND the body; the door rejects a
-    // disagreeing pair, so both come from the one create object. The reply carries
-    // the freshly-minted `callback_secret` for an `api`-door row, returned ONCE.
-    createOrReplaceConversationRoute: (route: s.ConversationRouteCreate) =>
-      req(`/api/conversations/${encodeSegment(route.route_name)}`, s.conversationRouteWritten, {
-        method: 'POST',
-        body: route,
-      }),
-    // Delete a route by name (destructive + authority-changing server-side): it
-    // drops the routing row and reclaims the thread indexes it owned.
-    deleteConversationRoute: (routeName: string) =>
-      req(`/api/conversations/${encodeSegment(routeName)}`, s.conversationRouteDeleted, {
-        method: 'DELETE',
-      }),
-    // One route's threads, newest activity first. Admin-only server-side: a
-    // listing spans every caller on the route, so a scoped session gets a 403.
-    listConversationThreads: (
-      routeName: string,
-      page: number,
-      pageSize: number,
-      filters: ConversationThreadFilters = {},
-      signal?: AbortSignal,
-    ) =>
-      req(`/api/conversations/${encodeSegment(routeName)}/threads`, s.conversationThreadsPage, {
-        signal,
-        query: { page, pageSize, status: filters.status, address: filters.address },
-      }),
-    // One thread's transcript, caller-scoped, read in the asked-for direction.
-    // The `thread_id` rides the QUERY STRING, never the path: it embeds the api
-    // door's `{principal}/{end user}` address with the principal already
-    // percent-encoded, which a path segment would have to encode a second time
-    // and the server would then decode once too few. A query value is decoded
-    // exactly once whatever it holds, so it is passed through verbatim.
-    readConversationTranscript: (query: ConversationTranscriptQuery, signal?: AbortSignal) =>
-      req(
-        `/api/conversations/${encodeSegment(query.routeName)}/transcript`,
-        s.conversationTranscriptPage,
-        {
-          signal,
-          query: {
-            thread_id: query.threadId,
-            page: query.page,
-            pageSize: query.pageSize,
-            order: query.order,
-            q: query.q,
-          },
-        },
-      ),
-    // Search every record on a route by text, across threads, newest first. The
-    // needle rides the QUERY (`q`); paging is the infinite query's own window. The
-    // page's `truncated` flag says the match set outran the door's scan cap.
-    searchConversationMessages: (query: ConversationMessageSearchQuery, signal?: AbortSignal) =>
-      req(
-        `/api/conversations/${encodeSegment(query.routeName)}/messages/search`,
-        s.conversationMessageSearchPage,
-        { signal, query: { q: query.q, page: query.page, pageSize: query.pageSize } },
-      ),
-    // Send a human message into a thread. The `thread_id` rides the BODY (a POST,
-    // never a path segment) — same encode-once reasoning as the transcript read.
-    sendConversationThreadMessage: (routeName: string, body: ConversationThreadMessageBody) =>
-      req(
-        `/api/conversations/${encodeSegment(routeName)}/thread/messages`,
-        s.conversationThreadMessageSent,
-        { method: 'POST', body },
-      ),
-    // Read a thread's reply mode (`agent`/`manual`) and where it comes from. The
-    // `thread_id` rides the QUERY value, encoded once, as the transcript read does.
-    getConversationThreadMode: (routeName: string, threadId: string, signal?: AbortSignal) =>
-      req(
-        `/api/conversations/${encodeSegment(routeName)}/thread/mode`,
-        s.conversationThreadModeState,
-        { signal, query: { thread_id: threadId } },
-      ),
-    // Flip a thread's reply mode. The `thread_id` rides the BODY (a PUT).
-    setConversationThreadMode: (
-      routeName: string,
-      threadId: string,
-      mode: s.ConversationThreadMode,
-    ) =>
-      req(
-        `/api/conversations/${encodeSegment(routeName)}/thread/mode`,
-        s.conversationThreadModeState,
-        { method: 'PUT', body: { thread_id: threadId, mode } },
-      ),
-
-    // -- conversation target configs -------------------------------------------
-    // The stored per-target presentation configs (each `(target_kind, target_name)`
-    // pair's multichannel flag + first-contact greeting). Admin config surface.
-    listConversationConfigs: (signal?: AbortSignal) =>
-      req('/api/conversation-configs', s.conversationConfigs, { signal }),
-    // One config by its `(target_kind, target_name)` key. 404 when unknown.
-    getConversationConfig: (
-      targetKind: s.ConversationTargetKind,
-      targetName: string,
-      signal?: AbortSignal,
-    ) =>
-      req(
-        `/api/conversation-configs/${encodeSegment(targetKind)}/${encodeSegment(targetName)}`,
-        s.targetConversationConfig,
-        { signal },
-      ),
-    // Create or REPLACE a config (an UPSERT: the same door is the create and the
-    // edit path). The `(target_kind, target_name)` key rides the URL path; the door
-    // rejects a body whose key disagrees, so both come from the one config object.
-    setConversationConfig: (config: s.TargetConversationConfig) =>
-      req(
-        `/api/conversation-configs/${encodeSegment(config.target_kind)}/${encodeSegment(config.target_name)}`,
-        s.conversationConfigWritten,
-        { method: 'PUT', body: config },
-      ),
-    // Delete a config by its key. 404 when the key is unknown.
-    deleteConversationConfig: (targetKind: s.ConversationTargetKind, targetName: string) =>
-      req(
-        `/api/conversation-configs/${encodeSegment(targetKind)}/${encodeSegment(targetName)}`,
-        s.conversationConfigDeleted,
-        { method: 'DELETE' },
-      ),
-
-    // -- conversation admin ----------------------------------------------------
-    // Every answer record whose delivery ended `failed`, across every route and
-    // caller. Admin-only server-side; not a paged window (returns `{items, total}`).
-    listFailedConversationMessages: (signal?: AbortSignal) =>
-      req('/api/conversations/messages/failed', s.conversationFailedMessages, { signal }),
-    // Forget ONE thread on a route (destructive): its checkpoint, answer records and
-    // thread indexes. The `thread_id` rides the QUERY value, encoded once — it embeds
-    // the api door's percent-encoded `{principal}/{end user}` address, which a path
-    // segment would encode a second time. `removed` counts the records this call
-    // cleared; a valid id on its own route always succeeds, never a 404.
-    deleteConversationThread: (routeName: string, threadId: string) =>
-      req(`/api/conversations/${encodeSegment(routeName)}/thread`, s.conversationThreadDeleted, {
-        method: 'DELETE',
-        query: { thread_id: threadId },
-      }),
-    // Erase a LINKED person ENTIRELY (GDPR, wide blast radius): its aggregated thread
-    // and checkpoint, its person row, and every address→person index mapping, across
-    // EVERY route it wrote under. The `person_id` is a uuid4 with no percent-encoded
-    // principal, so it rides the PATH cleanly. `erased` says whether this call removed
-    // the person row (idempotent — a retry answers `false`, never a 404).
-    deleteConversationPerson: (personId: string) =>
-      req(`/api/conversations/persons/${encodeSegment(personId)}`, s.conversationPersonDeleted, {
-        method: 'DELETE',
-      }),
-
-    // -- channel-web entry gate ------------------------------------------------
-    // A web route's entry gate, keyed by its `our_identity`: read the flag + its
-    // live codes, flip the flag, mint a code (raw returned ONCE), revoke a code by
-    // its hash id. The conversation monitor's first route mutations.
-    getWebEntryGate: (identity: string, signal?: AbortSignal) =>
-      req(`/api/channels/web/gates/${encodeSegment(identity)}`, s.webEntryGate, { signal }),
-    setWebEntryGate: (identity: string, enabled: boolean) =>
-      req(`/api/channels/web/gates/${encodeSegment(identity)}`, s.webEntryGateState, {
-        method: 'PUT',
-        body: { enabled },
-      }),
-    // Mint a code. `label`/`expires_at` are sent EXPLICITLY (including `null`). The
-    // raw `code` rides the reply ONCE (composed into the chat URL client-side).
-    mintWebEntryCode: (identity: string, body: WebEntryCodeMintBody) =>
-      req(`/api/channels/web/gates/${encodeSegment(identity)}/codes`, s.webEntryCodeMinted, {
-        method: 'POST',
-        body: { label: body.label, expires_at: body.expires_at },
-      }),
-    // Revoke a code by its hash id (immediate + durable). 404 when the id is unknown.
-    revokeWebEntryCode: (identity: string, codeId: string) =>
-      req(
-        `/api/channels/web/gates/${encodeSegment(identity)}/codes/${encodeSegment(codeId)}`,
-        s.webEntryCodeRevoked,
-        { method: 'DELETE' },
-      ),
-
-    // -- notifications ---------------------------------------------------------
-    // The internal notifications sink, newest-first — the messages the `notify_user`
-    // operation records with no channel, so they surface only in this inbox.
-    listNotifications: (signal?: AbortSignal) =>
-      req('/api/notifications', s.notifications, { signal }),
-
-    // -- agents --------------------------------------------------------------
-    listAgents: (signal?: AbortSignal) => req('/api/agents', agentList, { signal }),
-    // The authorable subset (agents whose `spec_runnable` is true) — the compose
-    // UI's base-agent picker. An empty `items` list ⇒ no authoring is possible.
-    listSpecRunnableAgents: (signal?: AbortSignal) =>
-      req('/api/agents/spec-runnable', agentList, { signal }),
-    // The streaming run: opens POST /api/agents/{name}/runs and yields parsed
-    // agent events. The auto-form's built value is the POST body.
-    streamAgentRun: (name: string, input: unknown, signal?: AbortSignal) =>
-      streamAgentRun(config, name, input, signal),
-    // The streaming run of an AUTHORED agent (POST /api/agents/authored/{name}/runs).
-    // The body carries only the non-baked ToolInput fields; the baked spec is
-    // resolved server-side. Reuses the same SSE parser (never EventSource).
-    streamAuthoredAgentRun: (name: string, input: unknown, signal?: AbortSignal) =>
-      streamAuthoredAgentRun(config, name, input, signal),
-
-    // -- hooks --------------------------------------------------------
-    listHooks: (topic?: string, signal?: AbortSignal) =>
-      req('/api/hooks', s.hookList, { signal, query: topic === undefined ? undefined : { topic } }),
-    registerHook: (params: s.HookRegister) =>
-      req('/api/hooks', s.hookRegistered, { method: 'POST', body: params }),
-    unregisterHook: (name: string) =>
-      req(`/api/hooks/${encodeSegment(name)}`, s.hookRemoved, { method: 'DELETE' }),
-    // The registered webhook-verifier catalog — the only source the bind picker
-    // reads (names only; an empty registry is a valid empty list).
-    listHookVerifiers: (signal?: AbortSignal) =>
-      req('/api/hooks/verifiers', s.hookVerifiers, { signal }),
-    // Bind a verifier to a topic (locks its otherwise-open public ingress). A PUT
-    // replaces any existing binding; an unknown verifier name is a loud 400.
-    setTopicVerifier: (topic: string, body: TopicVerifierBody) =>
-      req(`/api/hooks/topics/${encodeSegment(topic)}/verifier`, s.topicVerifierSet, {
-        method: 'PUT',
-        body,
-      }),
-    // Unbind a topic's verifier (re-opens its public ingress). 404 when no binding.
-    deleteTopicVerifier: (topic: string) =>
-      req(`/api/hooks/topics/${encodeSegment(topic)}/verifier`, s.topicVerifierRemoved, {
-        method: 'DELETE',
-      }),
-
-    // -- hooks: trigger links -------------------------------------------------
-    // Mint a trigger link for a topic. `ttl_seconds` is sent EXPLICITLY
-    // (including `null` for a permanent link) — the server requires the key present
-    // and 400s a dropped one; `tool_kwargs` is omitted when undefined. The raw
-    // `token` rides the response ONCE (composed into the QR URL client-side).
-    createTriggerLink: (body: TriggerLinkCreateBody) =>
-      req('/api/hooks/trigger-links', s.triggerLinkCreated, {
-        method: 'POST',
-        body: {
-          topic: body.topic,
-          name: body.name,
-          execution_key: body.execution_key,
-          require_api_key: body.require_api_key,
-          ttl_seconds: body.ttl_seconds,
-          tool_kwargs: body.tool_kwargs,
-        },
-      }),
-    // Every live trigger-link record (hash prefix only — never a raw token).
-    listTriggerLinks: (signal?: AbortSignal) =>
-      req('/api/hooks/trigger-links', s.triggerLinkList, { signal }),
-    // Revoke a link by name (immediate + durable). 404 when the name is unknown.
-    deleteTriggerLink: (name: string) =>
-      req(`/api/hooks/trigger-links/${encodeSegment(name)}`, s.triggerLinkDeleted, {
-        method: 'DELETE',
-      }),
-
-    // -- mcp config schema (connectors McpServersSection form) ---------------
-    getMcpConfigSchema: (signal?: AbortSignal) =>
-      req('/api/mcp-config/schema', s.jsonSchema, { signal }),
-
-    // -- settings schema -----------------------------------------------------
-    getSettingsSchema: (signal?: AbortSignal) =>
-      req('/api/config/settings-schema', s.settingsSchema, { signal }),
-
-    // -- auth: scopes --------------------------------------------------------
-    listScopes: (signal?: AbortSignal) => req('/api/auth/scopes', s.authScopes, { signal }),
-    addUrlToScope: (body: AddUrlToScopeBody) =>
-      req('/api/auth/scopes', s.addUrlToScopeResult, { method: 'POST', body }),
-    removeUrlFromScope: (body: { url: string }) =>
-      req('/api/auth/scopes/urls', s.removeUrlFromScopeResult, { method: 'DELETE', body }),
-    removeScope: (scopeId: string) =>
-      req(`/api/auth/scopes/${encodeSegment(scopeId)}`, s.removeScopeResult, {
-        method: 'DELETE',
-      }),
-    // The app's HTTP route catalog with each route's current mapping — the only
-    // source of the mapper's unassigned-routes bucket (`mapped: null` entries).
-    listAuthRoutes: (signal?: AbortSignal) => req('/api/auth/routes', s.authRoutes, { signal }),
-    // The urls pinned to the public marker; pinning/unpinning is the dedicated
-    // public-routes writer, never the scope machinery.
-    listPublicRoutes: (signal?: AbortSignal) =>
-      req('/api/auth/public-routes', s.publicRoutes, { signal }),
-    pinRoutePublic: (body: PinRoutePublicBody) =>
-      req('/api/auth/public-routes', s.pinPublicResult, { method: 'POST', body }),
-    // Unpin a public url. A url that is absent or scope-mapped is a loud 404.
-    unpinPublicRoute: (url: string) =>
-      req('/api/auth/public-routes', s.unpinPublicResult, { method: 'DELETE', body: { url } }),
-
-    // -- auth: roles (editable per-tag RBAC) ---------------------------------
-    // The seeded + operator-authored roles as full bodies (base-tier ceiling +
-    // editable per-tag grant map). ADMIN-ONLY — the route is `secret` (a listing
-    // exposes each role's raw base-tier jq); a non-admin projection never reaches it.
-    listRoles: (signal?: AbortSignal) => req('/api/auth/roles', s.roleList, { signal }),
-    // Create an operator-authored role. The server validates the grant map + base
-    // tier and 409s on a name collision; the reserved `admin` role cannot be created.
-    createRole: (body: RoleCreateBody) =>
-      req('/api/auth/roles', s.roleBody, { method: 'POST', body }),
-    // Edit a role's per-tag grant map + description (omit-means-keep). The reserved
-    // `admin` role and any `allow_all` role are block-downgrade guarded server-side.
-    updateRole: (name: string, body: RoleUpdateBody) =>
-      req(`/api/auth/roles/${encodeSegment(name)}`, s.roleBody, { method: 'PUT', body }),
-    // Delete a role. The reserved `admin` role is undeletable; a role still assigned
-    // to any principal is a loud 409.
-    deleteRole: (name: string) =>
-      req(`/api/auth/roles/${encodeSegment(name)}`, s.roleDeleted, { method: 'DELETE' }),
-    // A role's append-only version history + who/action/before→after audit trail.
-    // ADMIN-ONLY (`secret`).
-    listRoleVersions: (name: string, signal?: AbortSignal) =>
-      req(`/api/auth/roles/${encodeSegment(name)}/versions`, s.roleVersions, { signal }),
-    // Re-point a role's active version to a prior one (LIVE — holders follow on
-    // their next request); returns the re-pointed role body.
-    rollbackRole: (name: string, version: number) =>
-      req(`/api/auth/roles/${encodeSegment(name)}/rollback`, s.roleBody, {
-        method: 'POST',
-        body: { version },
-      }),
-
-    // -- auth: api keys ------------------------------------------------------
-    listTokensPayload: (signal?: AbortSignal) =>
-      req('/api/auth/tokens-payload', s.tokensPayload, { signal }),
-    createApiKey: (body: ApiKeyBody) =>
-      req('/api/auth/api-keys', s.createdApiKey, { method: 'POST', body }),
-    editApiKey: (userId: string, body: Omit<ApiKeyBody, 'user_id'>) =>
-      req(`/api/auth/api-keys/${encodeSegment(userId)}`, s.editApiKeyResult, {
-        method: 'PUT',
-        body,
-      }),
-    revokeApiKey: (userId: string) =>
-      req(`/api/auth/api-keys/${encodeSegment(userId)}`, s.revokeApiKeyResult, {
-        method: 'DELETE',
-      }),
-    // Mint a one-time claim link carrying a raw key to another device (the QR
-    // onboarding leg). The token rides the URL fragment; the server returns a
-    // relative `claim_path` and the raw token ONCE.
-    createClaimLink: (body: ClaimLinkBody) =>
-      req('/api/auth/claim-links', s.claimLinkCreated, { method: 'POST', body }),
-
-    // -- auth: the caller's capability projection ----------------------------
-    // The derived (path, method) surface + tools/agents the caller can reach
-    // right now — the projection the Studio filters its nav and pages on.
-    getMe: (signal?: AbortSignal) => req('/api/auth/me', s.meProjection, { signal }),
-
-    // -- login: the public sign-in aggregator --------------------------------
-    // PUBLIC by design: `apiRequest` attaches `x-api-key` only when a token
-    // exists, so the unauthenticated call carries no auth header — no transport
-    // change needed.
-    getLoginMethods: (options?: { signal?: AbortSignal }) =>
-      req('/api/login/methods', s.loginMethods, { signal: options?.signal }),
-    // Submit a `form` method's field VALUES as a flat top-level JSON body (the
-    // server's request models take the declared field names top-level). `path`
-    // is re-checked with the same relative-`/api/` guard the renderer uses — an
-    // off-origin path is a PROGRAMMING error (loud `Error`), not a login failure.
-    // A refused credential becomes an inline `ApiLoginFailedError`.
-    submitLoginForm: async (path: string, values: Record<string, string>) => {
-      if (!isSafeApiPath(path)) {
-        throw new Error(
-          `login submit_path must be a relative /api/ path; received ${JSON.stringify(path)}`,
-        );
-      }
-      try {
-        return await req(path, s.loginResult, { method: 'POST', body: values });
-      } catch (error) {
-        return asLoginError(error);
-      }
-    },
-    // Exchange a one-time SSO hand-back code for a session (never a token in the
-    // URL). An expired/reused code is a login failure, surfaced inline.
-    exchangeSsoCode: async (code: string) => {
-      try {
-        return await req('/api/login/sso/exchange', s.loginResult, {
-          method: 'POST',
-          body: { code },
-        });
-      } catch (error) {
-        return asLoginError(error);
-      }
-    },
-    // Exchange a one-time claim token (read from the login URL fragment, never a
-    // query param) for a session. PUBLIC. The token is single-use and burns
-    // server-side; a used/unknown/expired token answers the uniform 404, which —
-    // like the SSO leg — maps to an inline `ApiLoginFailedError`, not a global
-    // unauthorized redirect. The caller latches the exchange so it fires once.
-    claimLogin: async (body: { token: string }) => {
-      try {
-        return await req('/api/login/claim', s.loginResult, { method: 'POST', body });
-      } catch (error) {
-        return asLoginError(error);
-      }
-    },
-    // Whether this deployment can mint API keys locally (the settings key-create
-    // UI gates on `mintable`). AUTHED.
-    getAuthCapabilities: (signal?: AbortSignal) =>
-      req('/api/auth/capabilities', s.authCapabilities, { signal }),
-
-    // -- auth: session logout ------------------------------------------------
-    // The single authed logout dispatcher — revokes the caller's accounts
-    // session server-side before the shell clears local state. A plain `sk-` key
-    // has nothing to revoke and answers 404 (surfaced as an `ApiError`, quiet at
-    // the call site); a 5xx/network failure is a real revoke failure the shell
-    // surfaces loudly.
-    logout: () => req('/api/auth/logout', s.logoutResult, { method: 'POST' }),
-
-    // -- auth: policy authoring + versioning ---------------------------------
-    // The fail-closed jq guard: compiles (and, with `sample_context`, evaluates) a
-    // condition without persisting anything, so a broken condition is caught at
-    // author time instead of locking a key out at enforcement. A broken condition
-    // is a 400 the transport throws — never a false-positive `ok`.
-    validateCondition: (body: ValidateConditionBody) =>
-      req('/api/auth/validate-condition', s.validateConditionResult, { method: 'POST', body }),
-    // The user's append-only policy version history (each row's `is_current`
-    // derived from the active pointer). SECRET-ADJACENT — the body carries the raw
-    // condition, so its fixtures are hand-authored.
-    listPolicyVersions: (userId: string, signal?: AbortSignal) =>
-      req(`/api/auth/api-keys/${encodeSegment(userId)}/policy/versions`, s.policyVersionList, {
-        signal,
-      }),
-    // Re-point the enforced policy to a prior version; returns the re-pointed
-    // active version. Enforcement follows on cache invalidation.
-    rollbackPolicy: (userId: string, version: number) =>
-      req(`/api/auth/api-keys/${encodeSegment(userId)}/policy/rollback`, s.policyRollback, {
-        method: 'POST',
-        body: { version },
-      }),
-
-    // -- backup --------------------------------------------------------------
-    listBackupSections: (signal?: AbortSignal) =>
-      req('/api/backup/sections', s.backupSections, { signal }),
-    exportBackup: (sections: string[], signal?: AbortSignal): Promise<Blob> =>
-      apiDownload(config, '/api/backup/export', { method: 'POST', body: { sections }, signal }),
-    importBackup: (body: { document: unknown; sections: string[] }) =>
-      req('/api/backup/import', s.backupImportReport, { method: 'POST', body }),
-
-    // -- schedules -----------------------------------------------------------
-    listSchedules: (signal?: AbortSignal) => req('/api/schedules', s.scheduleList, { signal }),
-    getServerDateTime: (signal?: AbortSignal) =>
-      req('/api/schedules/server-datetime', s.serverDateTime, { signal }),
-    addSchedule: (body: {
-      tool_name: string;
-      tool_kwargs: Record<string, unknown>;
-      schedule_kwargs: Record<string, unknown>;
-      // The optional door-layer state binding applied around every fire of this schedule.
-      state_binding?: s.StateBinding | null;
-    }) => req('/api/schedules', s.jsonValue, { method: 'POST', body }),
-    deleteSchedule: (name: string) =>
-      req(`/api/schedules/${encodeSegment(name)}`, s.jsonValue, { method: 'DELETE' }),
-
-    // -- observability -------------------------------------------------------
-    // The monitoring-backend dashboard rollups (`GET /api/observability/metrics`),
-    // a JSON aggregate distinct from any raw process-metrics text endpoint.
-    getObservabilityMetrics: (params: MetricsQuery = {}, signal?: AbortSignal) =>
-      req('/api/observability/metrics', s.dashboardMetrics, {
-        query: { from: params.from, to: params.to, granularity: params.granularity },
-        signal,
-      }),
-    listRuns: (params: RunsQuery = {}, signal?: AbortSignal) =>
-      req('/api/observability/runs', s.runsPage, { query: runsQueryToParams(params), signal }),
-    getRunTrace: (traceId: string, signal?: AbortSignal) =>
-      req(`/api/observability/runs/${encodeSegment(traceId)}/trace`, s.runTrace, { signal }),
-    exportTrace: (traceId: string, signal?: AbortSignal): Promise<Blob> =>
-      apiDownload(config, `/api/observability/runs/${encodeSegment(traceId)}/trace/export`, {
-        signal,
-      }),
-    exportRuns: (
-      params: RunsQuery & { format: 'csv' | 'json' },
-      signal?: AbortSignal,
-    ): Promise<Blob> =>
-      apiDownload(config, '/api/observability/runs/export', {
-        query: { ...runsQueryToParams(params), format: params.format },
-        signal,
-      }),
-
-    // -- marketplace ---------------------------------------------------------
-    // Browse/search proxy the registry through the app (one origin, one auth);
-    // install/uninstall/update mutate the RUNNING app (pip install + manifest
-    // patch + reload) and return synchronous receipts.
-    searchMarketplace: (query: MarketplaceSearchQuery = {}, signal?: AbortSignal) =>
-      req('/api/marketplace/search', s.marketplaceSearchPage, {
-        query: {
-          q: query.q,
-          kind: query.kind,
-          category: query.category,
-          tags: query.tags,
-          namespace: query.namespace,
-          tier: query.tier,
-          contract: query.contract,
-          sort: query.sort,
-          page: query.page,
-          page_size: query.page_size,
-        },
-        signal,
-      }),
-    getMarketplacePlugin: (namespace: string, name: string, signal?: AbortSignal) =>
-      req(
-        `/api/marketplace/plugins/${encodeSegment(namespace)}/${encodeSegment(name)}`,
-        s.marketplacePluginDetail,
-        { signal },
-      ),
-    listMarketplaceCategories: (signal?: AbortSignal) =>
-      req('/api/marketplace/categories', s.marketplaceCategories, { signal }),
-    listMarketplaceKinds: (signal?: AbortSignal) =>
-      req('/api/marketplace/kinds', s.marketplaceKinds, { signal }),
-    listInstalledMarketplacePlugins: (signal?: AbortSignal) =>
-      req('/api/marketplace/installed', s.marketplaceInstalled, { signal }),
-    // Preview resolves the spec and computes routes/collisions/public rows with
-    // NO side effects, so the install dialog can show absolute paths, block on a
-    // collision, and surface the public routes before the operator commits.
-    previewMarketplaceInstall: (body: MarketplaceInstallPreviewBody, signal?: AbortSignal) =>
-      req('/api/marketplace/install/preview', s.marketplaceInstallPreview, {
-        method: 'POST',
-        body,
-        signal,
-      }),
-    installMarketplacePlugin: (body: MarketplaceInstallBody) =>
-      req('/api/marketplace/install', s.marketplaceInstallResult, { method: 'POST', body }),
-    uninstallMarketplacePlugin: (body: MarketplaceUninstallBody) =>
-      req('/api/marketplace/uninstall', s.marketplaceUninstallResult, { method: 'POST', body }),
-    updateMarketplacePlugin: (body: MarketplaceInstallBody) =>
-      req('/api/marketplace/update', s.marketplaceInstallResult, { method: 'POST', body }),
-    // Upgrade EVERY installed plugin to its newest compatible version in one
-    // pass; the response is the per-plugin outcome readout.
-    upgradeAllMarketplacePlugins: () =>
-      req('/api/marketplace/upgrade-all', s.marketplaceUpgradeAllResult, { method: 'POST' }),
-    getMarketplaceAdvisories: (signal?: AbortSignal) =>
-      req('/api/marketplace/advisories', s.marketplaceAdvisories, { signal }),
-
-    // -- system (plain-text ops endpoint) ------------------------------------
-    getHealth: (signal?: AbortSignal) => apiText(config, '/health', { signal }),
-
-    // The pluggable-kind status table (`GET /api/system/kinds`) — a JSON `{data}`
-    // envelope, one row per kind with its active/default/off state.
-    getSystemKinds: (signal?: AbortSignal) =>
-      req('/api/system/kinds', s.kindStatusList, { signal }),
-
-    /**
-     * Open the authed interactions SSE stream. The stream is TAIL-ONLY: its cursor
-     * is the stream tail at connect, so it carries no backlog and no
-     * `interaction.backlog_done` frame — the pending base comes from
-     * `listInteractions`. The caller drives reconnect and refetches that base on
-     * each (re)connect. Returns the raw frame iterator; the interactions feature
-     * maps frames to typed events.
-     *
-     * `lastEventId` (the id of the last frame the caller saw) is sent as the
-     * `Last-Event-ID` header so the server resumes AFTER it and replays any frame —
-     * including a card's `answered` — that landed during a disconnect gap. It is
-     * also sent as a `?last_event_id=` query param so a proxy that strips the header
-     * still resumes; the server reads either. Omitted on a first connect.
-     */
-    streamInteractions: async (signal?: AbortSignal, lastEventId?: string) => {
-      const doFetch = config.fetch ?? globalThis.fetch;
-      const token = config.getToken();
-      const headers: Record<string, string> = { accept: 'text/event-stream' };
-      if (token) headers['x-api-key'] = token;
-      if (lastEventId) headers['last-event-id'] = lastEventId;
-      // Distinct-URL per open — see the canonical constraint on `sseOpenToken`.
-      const resume = lastEventId ? `&last_event_id=${encodeURIComponent(lastEventId)}` : '';
-      const url = `${config.baseUrl ?? ''}/api/interactions/stream?_=${sseOpenToken()}${resume}`;
-      const response = await doFetch(url, {
-        headers,
-        signal,
-      });
-      if (response.status === 401) throw new ApiUnauthorizedError();
-      // A non-ok stream open (5xx/4xx) still carries a body, which would parse to
-      // zero frames and look like a silently-empty stream — surface it loudly so
-      // the caller shows an error instead of hanging on a reconnect loop. Read the
-      // `{ "error" }` envelope so a load-bearing server message (e.g. the OFF
-      // store's 501 remediation line) surfaces verbatim instead of collapsing to
-      // the bare status text.
-      if (!response.ok) {
-        let payload: unknown;
-        try {
-          payload = await response.json();
-        } catch {
-          throw new ApiError(response.statusText || 'stream failed', response.status);
-        }
-        const { message, code } = extractError(payload);
-        throw new ApiError(
-          message ?? (response.statusText || 'stream failed'),
-          response.status,
-          code,
-        );
-      }
-      return readSseFrames(response, signal);
-    },
-  } as const;
-}
-
-export type ApiClient = ReturnType<typeof createApiClient>;