@tai42/api-client 0.1.0

package/dist/schemas.js

@@ -0,0 +1,1103 @@
+/**
+ * One zod schema per consumed endpoint. These mirror the skeleton's router
+ * response shapes exactly; a drift throws (ApiSchemaError) and the UI shows the
+ * error state. JSON-schema-shaped fields are kept as permissive records — the
+ * auto-form renderer interprets them at runtime.
+ */
+import { z } from 'zod';
+/** An arbitrary JSON value (tool results, rendered payloads). */
+export const jsonValue = z.unknown();
+/** A JSON Schema object (Pydantic-emitted). Permissive; parsed by the auto-form. */
+export const jsonSchema = z.record(z.string(), z.unknown());
+// -- tools -------------------------------------------------------------------
+export const toolNames = z.array(z.string());
+export const toolSchema = z.object({
+    input: jsonSchema,
+    output: jsonSchema.nullable(),
+    description: z.string().nullable(),
+});
+export const allToolSchemas = z.record(z.string(), toolSchema);
+export const runToolResult = jsonValue;
+/**
+ * The MEDIA variant a direct tool run (`/api/run-tool`) can return:
+ * fastmcp serializes a returned `Image`/`Audio` MediaBlock to the MCP content
+ * object `{ type: 'image' | 'audio', data: <base64>, mimeType: <mime> }`. The
+ * `ResultViewer` detects this shape and renders an `<img>`/`<audio>` from a
+ * `data:` URI. A tool result is still arbitrary JSON (`runToolResult`); this is
+ * one recognised shape it can take, kept as its own schema so the viewer's
+ * detection is a schema parse, not an ad-hoc shape check.
+ *
+ * SECURITY: the refinement pins `mimeType` to its media kind — an `image` block
+ * MUST carry an `image/*` type, an `audio` block an `audio/*` type. A drifting or
+ * arbitrary mimeType (e.g. a script type) fails the parse, so the viewer never
+ * turns an unexpected mime into a `data:` URI — it falls back to the JSON/text
+ * view instead. A `File` MediaBlock serializes to a distinct `EmbeddedResource`
+ * shape (no top-level `data`/`mimeType`), so it also fails here and is not
+ * media-rendered.
+ */
+export const toolMediaResult = z
+    .object({
+    type: z.enum(['image', 'audio']),
+    data: z.string(),
+    mimeType: z.string(),
+})
+    .refine((media) => media.mimeType.startsWith(`${media.type}/`), {
+    message: 'media mimeType must match its media kind (image/* for image, audio/* for audio)',
+    path: ['mimeType'],
+});
+/**
+ * The ADDITIVE per-tool native-tags map (`GET /api/tools/tags`). Distinct from the
+ * flat `toolNames` contract (`GET /api/tools`, unchanged): this surfaces each
+ * tool's FastMCP `tags` — including the ones preset bodies project — so the shared
+ * `ToolPicker` can group/filter its options by tag.
+ */
+export const toolTagEntry = z.object({ name: z.string(), tags: z.array(z.string()) });
+export const toolTags = z.array(toolTagEntry);
+// -- extensions --------------------------------------------------------------
+export const extension = z.object({ name: z.string(), kind: z.string() });
+export const extensions = z.array(extension);
+/**
+ * One element of an extension combo: a bare extension NAME, or a
+ * `{ name, config }` mapping binding author config (e.g. an `output_schema` JSON
+ * Schema, or an `ask_external` verifier). Both wire forms are admitted so a
+ * config-bearing combo parses without dropping server data. A drift throws
+ * `ApiSchemaError`.
+ */
+export const presetExtensionElement = z.union([
+    z.string(),
+    z.object({ name: z.string(), config: z.record(z.string(), z.unknown()) }),
+]);
+/**
+ * `GET /api/tools/{name}/extensions` — a tool's FULL lossless list-of-combos plus
+ * the extension catalog. `combos` is a list of combos, each an ordered list of
+ * extension ELEMENTS (a bare name or a config-bearing `{ name, config }` mapping —
+ * `output_schema` carries its schema this way); `[]` when the tool has no map entry.
+ * It carries EVERY combo mapped to the base tool (the union across every `tools`/`mcp`
+ * config), never a single flattened one. `available` is the same flat catalog
+ * `GET /api/extensions` returns. A drift throws `ApiSchemaError`.
+ */
+export const toolExtensions = z.object({
+    combos: z.array(z.array(presetExtensionElement)),
+    available: extensions,
+});
+// -- presets -----------------------------------------------------------------
+/** A list of extension COMBOS — each combo an ordered list of elements. */
+export const presetExtensions = z.array(z.array(presetExtensionElement));
+/**
+ * One preset as `GET /api/presets` returns it. Every preset is versioned, so
+ * `active_version` is always an int; `conflicted` marks a QUARANTINED row (its
+ * name collided with a foreign tool at boot — delete-only). `extensions` are the
+ * ACTIVE version's extension combos, `tags` the preset's categorization labels
+ * (distinct from a version's generic label list), and `output_schema` the
+ * optional author-set output JSON Schema. A drift throws `ApiSchemaError`;
+ * nothing is coerced.
+ */
+export const presetRecord = z.object({
+    name: z.string(),
+    base_tool: z.string(),
+    description: z.string(),
+    active_version: z.number(),
+    tags: z.array(z.string()),
+    extensions: presetExtensions,
+    output_schema: z.record(z.string(), z.unknown()).nullable(),
+    conflicted: z.boolean(),
+    // The human-readable cause a row is quarantined (its name collided with a
+    // foreign tool at boot), or `null` when the row is not conflicted. Rendered
+    // verbatim; nothing is coerced.
+    conflicted_reason: z.string().nullable(),
+});
+export const presetList = z.array(presetRecord);
+/** `GET /api/presets/{name}` — the record plus the active version's baked kwargs. */
+export const presetDetail = presetRecord.extend({
+    fixed_kwargs: z.record(z.string(), z.unknown()),
+});
+/** The full version body a preset stores under `kind="preset"`. */
+export const presetBody = z.object({
+    base_tool: z.string(),
+    description: z.string(),
+    fixed_kwargs: z.record(z.string(), z.unknown()),
+    extensions: presetExtensions,
+    tags: z.array(z.string()),
+    output_schema: z.record(z.string(), z.unknown()).nullable(),
+});
+/**
+ * One immutable version row (`GET /api/presets/{name}/versions[/{version}]`).
+ * `is_current` flags the active version; `tags` here is the GENERIC per-version
+ * label list (kind-agnostic), distinct from the categorization `body.tags`.
+ */
+export const presetVersion = z.object({
+    version: z.number(),
+    body: presetBody,
+    tags: z.array(z.string()),
+    created_at: z.string(),
+    is_current: z.boolean(),
+});
+export const presetVersionList = z.array(presetVersion);
+/** `POST /api/presets/{name}/rollback` — the re-pointed active version. */
+export const presetRollback = z.object({ name: z.string(), active_version: z.number() });
+/** `DELETE /api/presets/{name}` — the removed preset. */
+export const presetDeleted = z.object({ name: z.string(), deleted: z.literal(true) });
+/** `POST /api/presets/{name}/rename` — the re-keyed record identity. */
+export const presetRenamed = z.object({
+    name: z.string(),
+    renamed_from: z.string(),
+    active_version: z.number(),
+});
+/**
+ * `GET /api/presets/{name}/referees` — every OTHER preset whose active authored
+ * composition names this one as a tool (the referees a rename would strand). An
+ * empty list is the clean case; a non-empty list means a rename is blocked until
+ * those presets are updated. A drift throws `ApiSchemaError`.
+ */
+export const presetReferees = z.object({
+    name: z.string(),
+    referees: z.array(z.string()),
+});
+/**
+ * `POST /api/presets/validate` — the dry-run verdict for a preset draft. `valid`
+ * is the absence of an `error`; an invalid draft is a SUCCESSFUL validation (HTTP
+ * 200), so `error` carries the server's verbatim message. A drift throws
+ * `ApiSchemaError`.
+ */
+export const presetValidation = z.object({
+    valid: z.boolean(),
+    error: z.string().nullable(),
+});
+/**
+ * `PUT /api/presets/{name}/versions/{version}/tags` — the re-annotated version.
+ * Version tags are labels on an immutable body, so this rebinds nothing; the
+ * response echoes the identity plus the new tag list. A drift throws
+ * `ApiSchemaError`.
+ */
+export const presetVersionTags = z.object({
+    name: z.string(),
+    version: z.number(),
+    tags: z.array(z.string()),
+});
+// -- templates ---------------------------------------------------------------
+export const templateNames = z.array(z.string());
+export const templateDetail = z.object({ template: z.string(), schema: jsonSchema });
+export const templateUploaded = z.object({ path: z.string(), uploaded: z.literal(true) });
+export const templateDeleted = z.object({ path: z.string(), deleted: z.literal(true) });
+export const templateRendered = z.object({ rendered: z.string() });
+export const templateCacheCleared = z.object({ cleared: z.literal(true) });
+// -- storage -----------------------------------------------------------------
+/** `GET /api/storage` — the storage-provider identity, or the absent sentinel
+ * (`present: false`, a 200) when no storage-provider plugin is installed. */
+export const storageInfo = z.object({
+    present: z.boolean(),
+    provider: z.string().nullable(),
+    module: z.string().nullable(),
+});
+/** `GET /api/storage/resources` — the full sorted resource-id list. */
+export const storageResourceList = z.object({ resources: z.array(z.string()) });
+/** `GET /api/storage/resources/{id}/stat` — an object's inferred content type;
+ * `null` when the provider cannot infer one (e.g. an unknown suffix). */
+export const storageResourceStat = z.object({
+    id: z.string(),
+    content_type: z.string().nullable(),
+});
+/** `POST /api/storage/resources` — the stored object's id. */
+export const storageResourceStored = z.object({ id: z.string(), stored: z.literal(true) });
+/** `DELETE /api/storage/resources/{id}` — the removed object's id. */
+export const storageResourceDeleted = z.object({ id: z.string(), deleted: z.literal(true) });
+/** `DELETE /api/storage/dirs/{path}` — the removed directory subtree. */
+export const storageDirDeleted = z.object({ dir: z.string(), deleted: z.literal(true) });
+// -- backend identity + fleet (worker bus) -----------------------------------
+/** `GET /api/backend` — the execution-backend identity, or the absent sentinel
+ * (`present: false`, a 200) when no backend plugin is registered. Backend identity
+ * is kept distinct from the fleet: the fleet doors ride the app's worker bus and
+ * need no backend at all. */
+export const backendInfo = z.object({
+    present: z.boolean(),
+    backend: z.string().nullable(),
+    module: z.string().nullable(),
+});
+/** The two worker kinds that join the bus: an ASGI `serve` worker or a
+ * `backend` runtime process. A drift throws `ApiSchemaError`. */
+export const originKind = z.enum(['serve', 'backend']);
+/**
+ * One live worker on the bus — a presence-census entry. `origin` is the
+ * `{kind}-{uuid}` identity used as a reload target; `kind` tells the two worker
+ * kinds apart; `pid` is the process id the presence key carries.
+ */
+export const fleetOrigin = z.object({
+    origin: z.string(),
+    kind: originKind,
+    pid: z.number(),
+});
+/**
+ * `GET /api/fleet/workers` — the live worker fleet from the bus presence census.
+ * The census lists ALL subscribed origins (ASGI `serve` workers and backend-runtime
+ * processes alike), not only backend workers. A census read that fails surfaces as a
+ * loud 500, never a fabricated empty fleet.
+ */
+export const fleetWorkers = z.object({ workers: z.array(fleetOrigin) });
+/**
+ * One origin's outcome within a fleet broadcast. `applied`/`failed` are terminal
+ * wire replies from a subscriber; `missing`/`departed`/`timed_out` are
+ * publisher-computed from the presence census (a silent origin never sends them).
+ */
+export const fleetOutcome = z.enum(['applied', 'failed', 'missing', 'departed', 'timed_out']);
+/**
+ * One origin's result within a {@link fleetResult}. `payload` carries query-op data
+ * (opaque to the UI); `error` carries a failed apply's message; `detail` carries the
+ * publisher's report text for a computed `missing`/`departed`/`timed_out`. A drift
+ * throws `ApiSchemaError`.
+ */
+export const fleetOriginResult = z.object({
+    origin: z.string(),
+    outcome: fleetOutcome,
+    payload: jsonValue,
+    error: z.string().nullable(),
+    detail: z.string().nullable(),
+});
+/**
+ * The awaited per-origin report of one fleet broadcast. Two honest shapes ride the
+ * same schema. Reachable (`reachable: true`): `results` holds one entry per expected
+ * origin (the serving worker's own entry included), so an unconfirmed sibling is a
+ * visible `failed`/`missing`/`departed`/`timed_out` entry, never a silent stale
+ * worker. Bus-unreachable (`reachable: false`): the transport failed before any
+ * origin could reply, so `results` is empty and only `error` is carried. This is the
+ * bare body of `POST /api/fleet/reload-config` and the single-MCP reload; it is also
+ * the body the mode-wrapped {@link fleetReportFanout} carries under its `fleet` /
+ * `unreachable` modes.
+ */
+export const fleetResult = z.object({
+    op: z.string(),
+    reachable: z.boolean(),
+    local_only: z.boolean(),
+    results: z.array(fleetOriginResult),
+    error: z.string().nullable(),
+});
+/**
+ * `POST /api/fleet/reload-config` — soft-restart the fleet and report per-origin. The
+ * serving worker applies its own reload first, then broadcasts; the returned report
+ * names every origin's outcome. A failed local apply does not abort the broadcast, so
+ * the report is embedded even on the convergence-failure path.
+ */
+export const fleetReloadResult = fleetResult;
+/**
+ * The mode-wrapped fan-out summary a mutation embeds under its `fanout` field. Three
+ * honest modes, discriminated on `mode`:
+ *   - `local-only` — the broadcast reached no sibling (a lone worker / no bus), a
+ *     benign single-process note.
+ *   - `fleet` — a reachable multi-worker broadcast; carries the full {@link
+ *     fleetResult} so an unconfirmed sibling is visible.
+ *   - `unreachable` — the bus itself could not be reached; carries the
+ *     bus-unreachable {@link fleetResult} (no origin list, only `error`).
+ *
+ * Every mutation whose response embeds this parses it EXPLICITLY: zod's default
+ * unknown-key stripping would otherwise silently drop the field, hiding a failed
+ * propagation from the shared fleet-report handler. A drift throws `ApiSchemaError`.
+ */
+export const fleetReportFanout = z.discriminatedUnion('mode', [
+    z.object({ mode: z.literal('local-only'), note: z.string() }),
+    fleetResult.extend({ mode: z.literal('fleet') }),
+    fleetResult.extend({ mode: z.literal('unreachable') }),
+]);
+// -- manifest / mcp ----------------------------------------------------------
+export const manifestView = z.object({
+    mcp: z.array(z.record(z.string(), z.unknown())),
+    user_tools: z.array(z.string()),
+});
+/**
+ * The apply result every config-writer mutation returns (`POST /api/mcp-config`,
+ * `POST /api/config/env`): the serving worker's local reload result (`status` +
+ * `env_keys`) plus the mode-wrapped fleet fan-out of the reload it broadcast. The
+ * `fanout` is parsed EXPLICITLY so the shared fleet-report handler can surface a
+ * failed propagation — zod's unknown-key stripping would otherwise hide it. A drift
+ * throws `ApiSchemaError`.
+ */
+export const reloadConfigResult = z.object({
+    status: z.string(),
+    env_keys: z.number(),
+    fanout: fleetReportFanout,
+});
+// -- system kinds ------------------------------------------------------------
+// `GET /api/system/kinds` — one row per pluggable kind (identity, accounts,
+// monitoring, storage, backend, channels, webhook_verifiers, config,
+// studio_plugins). `state` is the kind's active/default/off status: `active` = a
+// real plugin serves it, `default` = a built-in fallback serves it, `off` =
+// nothing is registered (a legal state, reported not "fixed"). `plugin` is the
+// provider/module name when known, else null. Plain (non-strict) `z.object` so a
+// server that adds a field to the row still parses.
+export const kindStatus = z.object({
+    kind: z.string(),
+    state: z.enum(['active', 'default', 'off']),
+    plugin: z.string().nullable(),
+    detail: z.string(),
+});
+export const kindStatusList = z.array(kindStatus);
+/**
+ * `POST /api/tools/{name}/extensions` — the apply result. The write persists the
+ * manifest, reloads locally, then broadcasts the reload to the whole fleet. The
+ * response is the one apply-result shape every config-writer returns: the local
+ * reload result (`status` + `env_keys`) plus the mode-wrapped fleet `fanout`. The
+ * fan-out rides EVERY deployment (a lone worker reports `local-only`), so this flat
+ * shape parses every save and the shared fleet-report handler renders any failed
+ * propagation from `fanout`.
+ */
+export const toolExtensionsApplyResult = reloadConfigResult;
+export const mcpStatus = z.object({
+    bound: z.record(z.string(), z.array(z.string())),
+    failed: z.array(z.object({ title: z.string(), status: z.string() })),
+});
+/**
+ * `POST /api/mcp-status/{title}/reload` — re-probe a single MCP server and broadcast
+ * the reload to the fleet. The response is the bare per-origin {@link fleetResult}
+ * (the serving worker's re-probe rides its own `results` entry as the payload); there
+ * is no local/workers split. A drift throws `ApiSchemaError`.
+ */
+export const mcpReloadResult = fleetResult;
+// -- sub-mcp -----------------------------------------------------------------
+export const subMcpList = z.record(z.string(), z.record(z.string(), z.unknown()));
+export const subMcpCreated = z.object({ slug: z.string(), tools: z.array(z.string()) });
+export const subMcpRemoved = z.object({ slug: z.string(), removed: z.literal(true) });
+// -- config ------------------------------------------------------------------
+export const envConfig = z.object({
+    env: z.record(z.string(), z.string()),
+    secret_keys: z.array(z.string()),
+});
+/**
+ * `GET /api/config/mode` — the active config backend mode (`file` / `k8s`). The
+ * skeleton emits ONLY `config_mode`; `read_only` is a UI-side gate that no config
+ * backend currently drives (both the `file` and `k8s` providers implement writes),
+ * so it is tolerated-absent and defaults to `false` (writable). A deployment whose
+ * config is genuinely read-only can still opt in by emitting `read_only: true`,
+ * which the settings surface honors — but its absence is the normal case, not a
+ * drift, so requiring it here would make every real `getConfigMode()` throw.
+ */
+export const configMode = z.object({
+    config_mode: z.string(),
+    read_only: z.boolean().default(false),
+});
+// -- connectors --------------------------------------------------------------
+export const subServiceView = z.object({
+    id: z.string(),
+    display_name: z.string(),
+    description: z.string(),
+    scopes: z.array(z.string()),
+});
+export const configFieldView = z.object({
+    key: z.string(),
+    label: z.string(),
+    target: z.enum(['env', 'header']),
+    required: z.boolean(),
+    secret: z.boolean(),
+});
+export const providerView = z.object({
+    id: z.string(),
+    display_name: z.string(),
+    description: z.string(),
+    icon_url: z.string(),
+    kind: z.enum(['oauth', 'none']),
+    origin: z.enum(['system', 'community']),
+    category: z.string(),
+    sub_services: z.array(subServiceView),
+    config_fields: z.array(configFieldView),
+});
+export const providers = z.array(providerView);
+export const connectionView = z.object({
+    connection_id: z.string(),
+    provider_id: z.string(),
+    alias: z.string(),
+    kind: z.enum(['oauth', 'none']),
+    account_identity: z.string().nullable(),
+    enabled_sub_services: z.array(z.string()),
+    granted_scopes: z.array(z.string()),
+    auth_health_state: z.enum(['healthy', 'reconnect_required', 'refresh_failing']),
+    created_at: z.string(),
+});
+export const connectionsList = z.object({ items: z.array(connectionView), total: z.number() });
+// A connector mutation that writes the manifest embeds the mode-wrapped fleet
+// `fanout` of the reload it broadcast; it is `null` when the response path mutated no
+// manifest (an OAuth START opens a flow before any write). Parsed EXPLICITLY so the
+// shared fleet-report handler surfaces a failed propagation on every connector flow —
+// zod's unknown-key stripping would otherwise drop it silently.
+export const startConnectResult = z.union([
+    z.object({ flow_id: z.string(), authorize_url: z.string() }),
+    z.object({
+        connection_id: z.string(),
+        added_manifest_entries: z.array(z.string()),
+        fanout: fleetReportFanout.nullable(),
+    }),
+]);
+// A reconnect START opens an OAuth flow and writes no manifest, so it carries no
+// fan-out (the manifest write lands when the flow completes).
+export const reconnectResult = z.object({ flow_id: z.string(), authorize_url: z.string() });
+export const disconnectResult = z.object({
+    connection_id: z.string(),
+    upstream_revoke_outcome: z.enum(['success', 'failed', 'skipped']),
+    upstream_revoke_status: z.number().nullable(),
+    removed_manifest_entries: z.array(z.string()),
+    fanout: fleetReportFanout.nullable(),
+});
+export const patchSubServicesResult = z.object({
+    connection_id: z.string(),
+    enabled_sub_services: z.array(z.string()),
+    consent_required: z.boolean(),
+    flow_id: z.string().nullable(),
+    authorize_url: z.string().nullable(),
+    added_manifest_entries: z.array(z.string()),
+    removed_manifest_entries: z.array(z.string()),
+    // `null` on a consent-only toggle that forks an OAuth flow without a manifest write.
+    fanout: fleetReportFanout.nullable(),
+});
+export const oauthCompleteResult = z.discriminatedUnion('kind', [
+    z.object({
+        kind: z.literal('success'),
+        connection_id: z.string(),
+        return_url: z.string(),
+        // `null` when completing the flow mutated no manifest (a reconcile that changed
+        // nothing).
+        fanout: fleetReportFanout.nullable(),
+    }),
+    z.object({ kind: z.literal('failed'), reason: z.string() }),
+    z.object({ kind: z.literal('cancelled'), message: z.string() }),
+]);
+// -- studio plugin registry --------------------------------------------------
+export const studioPluginManifest = z.object({
+    name: z.string(),
+    version: z.string(),
+    api_version: z.number(),
+    entry: z.string(),
+    integrity: z.record(z.string(), z.string()),
+    contributions: z.object({
+        tool_panels: z.record(z.string(), z.string()).default({}),
+        pages: z.array(z.string()).default([]),
+        settings_tabs: z.array(z.string()).default([]),
+        // Optional with a default so a manifest without the field still parses; the
+        // non-strict object would otherwise SILENTLY STRIP an undeclared field, so a
+        // server that serves `nav_entries` would never reach the UI.
+        nav_entries: z.array(z.string()).default([]),
+    }),
+});
+export const studioPluginRegistry = z.array(studioPluginManifest);
+// -- interactions ------------------------------------------------------------
+// Shapes match the skeleton's interactions SSE contract: the SSE
+// `interaction.add` frame carries the question and its answer format; the answer
+// door returns { interaction_id, status }. `answered` is not a wire field — it
+// is a client-side flag the stream hook flips on an `interaction.answered` event.
+export const answerFormat = z.enum(['text', 'confirm', 'select', 'form', 'external']);
+/** The kind of a question's display-only media item: a remote/inline image, or a link. */
+export const mediaKind = z.enum(['image', 'link']);
+/**
+ * One item of a question's display-only media. Applied PER ITEM by the renderer
+ * (never as a strict array on the frame): the frame's `media` field is a loose
+ * `z.array(z.unknown())`, and the renderer `safeParse`s each item with this schema
+ * so one malformed/hostile item is a loud per-item notice, not a whole-frame parse
+ * failure that would silently vanish an answerable question.
+ *
+ * `caption` is `.nullish()` (absent OR `null` both parse to a caption-less item):
+ * a caption-less item may arrive with the key omitted OR with an explicit `null`, so
+ * `.optional()` here would false-fail the explicit `null` and render a good image as
+ * malformed. `url` and `kind` are the only load-bearing fields; the image
+ * src scheme gate and the link neutralization are enforced by the renderer.
+ */
+export const interactionMediaItem = z.object({
+    kind: mediaKind,
+    url: z.string(),
+    caption: z.string().nullish(),
+});
+export const interaction = z.object({
+    interaction_id: z.string(),
+    group_id: z.string(),
+    question: z.string().default(''),
+    answer_format: answerFormat,
+    // Format-specific payload: select options, form JSON schema, external url. The
+    // wire sends `null` for formats that carry none (text/confirm); it is
+    // normalized to `{}` so consumers always see an object.
+    format_payload: z
+        .record(z.string(), z.unknown())
+        .nullish()
+        .transform((value) => value ?? {}),
+    created_at: z.string(),
+    timeout_at: z.string(),
+    // Whether the answer body is sensitive and never persisted server-side. Rides
+    // every add frame; an absent value (older frame) normalizes to false.
+    sensitive: z.boolean().default(false),
+    // True only for an external question answered by a signed server-to-server
+    // callback (never by a human); the frame never carries the verifier object.
+    // Absent/undefined for every other question.
+    server_verified: z.boolean().optional(),
+    // Name of the channel plugin the question was also delivered through (e.g.
+    // "telegram"); absent when the question lives only in this inbox.
+    channel: z.string().optional(),
+    // Display-only media shown WITH the question (images and/or links). Absent when
+    // the question carries none. Deliberately LOOSE (`z.array(z.unknown())`): each
+    // item is `safeParse`d per item by the renderer against `interactionMediaItem`,
+    // so one malformed/hostile item can never fail the whole frame parse and hide an
+    // answerable question. A present non-array value is still malformed.
+    media: z.array(z.unknown()).optional(),
+});
+/** The answer door's response — the blocked caller was woken. */
+export const interactionAnswered = z.object({
+    interaction_id: z.string(),
+    status: z.string(),
+});
+// -- channels ----------------------------------------------------------------
+// The installed channel-plugin catalog: names registered via the manifest's
+// channel modules. A deployment with none bound answers questions only in this
+// inbox (the Studio default).
+export const channels = z.object({
+    channels: z.array(z.string()),
+});
+// -- notifications -----------------------------------------------------------
+// The internal notifications sink: the messages the `notify_user` operation records
+// with no channel, so they land only in the Studio inbox. Each record carries the
+// server-minted id + timestamp; `recipient` is null when the message names none.
+export const notification = z.object({
+    id: z.string(),
+    message: z.string(),
+    recipient: z.string().nullable(),
+    created_at: z.string(),
+});
+export const notifications = z.object({
+    notifications: z.array(notification),
+});
+// -- hooks -------------------------------------------------------------------
+// Shapes match tai_contract.hooks.HookParams: a hook fires a `tool` on a `topic`,
+// optionally gated by a `condition` and shaped by an `expr` (each either an inline
+// spec or a registered id, with its own kwargs).
+export const hookParams = z.object({
+    name: z.string(),
+    topic: z.string(),
+    tool: z.string(),
+    tool_kwargs: z.record(z.string(), z.unknown()).default({}),
+    condition: z.string().nullable().default(null),
+    condition_id: z.string().nullable().default(null),
+    // The `*_kwargs` pair is non-optional in the contract (defaults to {}, never
+    // null) — unlike the sibling condition/expr string fields, which are nullable.
+    condition_kwargs: z.record(z.string(), z.unknown()).default({}),
+    expr: z.string().nullable().default(null),
+    expr_id: z.string().nullable().default(null),
+    expr_kwargs: z.record(z.string(), z.unknown()).default({}),
+});
+export const hookList = z.object({
+    items: z.array(hookParams),
+    total: z.number(),
+    // Per-topic verifier bindings: the topic name maps to the verifier bound to it
+    // and that verifier's config (which carries a `secret_env` name, never a secret
+    // value). Tolerant of an older/empty response, which omits the key entirely.
+    topic_verifiers: z
+        .record(z.string(), z.object({ verifier: z.string(), config: z.record(z.string(), z.unknown()) }))
+        .default({}),
+});
+export const hookRegistered = z.object({
+    registered: z.boolean(),
+    name: z.string(),
+});
+export const hookRemoved = z.object({
+    removed: z.boolean(),
+    name: z.string(),
+});
+// The registered webhook-verifier catalog (`GET /api/hooks/verifiers`) — the
+// sorted verifier NAMES only, never any verifier's config. An empty registry is a
+// valid empty array. This is the ONLY source the topic-verifier bind picker reads.
+export const hookVerifiers = z.array(z.string());
+/** `PUT /api/hooks/topics/{topic}/verifier` — the bound topic + verifier name. */
+export const topicVerifierSet = z.object({ topic: z.string(), verifier: z.string() });
+/** `DELETE /api/hooks/topics/{topic}/verifier` — the unbound topic. */
+export const topicVerifierRemoved = z.object({ removed: z.boolean(), topic: z.string() });
+// -- settings schema ---------------------------------------------------------
+// The settings form is auto-rendered from a declarative group/field description
+// the skeleton emits from its typed settings models.
+export const settingsSchema = z.object({
+    groups: z.array(z.object({
+        name: z.string(),
+        module: z.string(),
+        qualname: z.string(),
+        fields: z.array(z.object({
+            name: z.string(),
+            env_var: z.string(),
+            type: z.string(),
+            default: jsonValue.nullable(),
+            required: z.boolean(),
+            secret: z.boolean(),
+            description: z.string().nullable(),
+            nested_group: z.string().nullable(),
+            value: jsonValue.nullable(),
+        })),
+    })),
+});
+// -- auth: scopes + api keys -------------------------------------------------
+/** `{ url: scope_id }` — every URL currently mapped to a scope. */
+export const authScopes = z.record(z.string(), z.string());
+export const addUrlToScopeResult = z.object({ scope_id: z.string(), url: z.string() });
+export const removeUrlFromScopeResult = z.object({ url: z.string() });
+export const removeScopeResult = z.object({ scope_id: z.string(), deleted_keys: z.number() });
+/**
+ * One row of the route catalog (`GET /api/auth/routes`) — a plain HTTP route with
+ * its current mapping. `mapped` is the scope id, the public marker, or `null` when
+ * the path is unmapped (the mapper's "unassigned" bucket source). `methods` is the
+ * route's method set with `HEAD` removed.
+ */
+export const authRoute = z.object({
+    path: z.string(),
+    methods: z.array(z.string()),
+    mapped: z.string().nullable(),
+});
+export const authRoutes = z.array(authRoute);
+/** `GET /api/auth/public-routes` — the sorted urls pinned to the public marker. */
+export const publicRoutes = z.array(z.string());
+/** `POST /api/auth/public-routes` — the pinned url. */
+export const pinPublicResult = z.object({ url: z.string() });
+/** `DELETE /api/auth/public-routes` — the unpinned url (404 when not pinned). */
+export const unpinPublicResult = z.object({ url: z.string() });
+export const tokensPayload = z.array(z.object({
+    user_id: z.string(),
+    description: z.string(),
+    scopes: z.array(z.string()),
+    policy_data: jsonValue,
+    condition: z.string().nullable().optional(),
+    condition_id: z.string().nullable().optional(),
+    condition_kwargs: jsonValue.nullable().optional(),
+}));
+/** The raw `sk-…` key string, returned once at creation time and never again. */
+export const createdApiKey = z.string();
+export const editApiKeyResult = z.object({ user_id: z.string(), updated: z.boolean() });
+export const revokeApiKeyResult = z.object({ user_id: z.string(), revoked: z.boolean() });
+// -- login methods (the public sign-in aggregator) ---------------------------
+/**
+ * One field of a `form` login method. `secret` fields render as password
+ * inputs; `autocomplete` passes through to the input (e.g. "email",
+ * "current-password", "new-password").
+ */
+export const loginFormField = z.object({
+    name: z.string().min(1),
+    label: z.string().min(1),
+    secret: z.boolean(),
+    autocomplete: z.string().optional(),
+});
+/**
+ * The two — and only two — login-method shapes. Discriminated on `shape`; an
+ * unknown shape fails validation loudly (contract drift, not a soft skip).
+ * Optional fields are `.optional()` (absent), never `.nullable()`: the server
+ * serializes with `exclude_none`, so an absent field is OMITTED, never `null`.
+ */
+export const loginMethod = z.discriminatedUnion('shape', [
+    z.object({
+        shape: z.literal('form'),
+        id: z.string().min(1),
+        title: z.string().min(1),
+        purpose: z.enum(['login', 'bootstrap', 'invite']).default('login'),
+        fields: z.array(loginFormField).min(1),
+        submit_path: z.string().min(1),
+    }),
+    z.object({
+        shape: z.literal('button'),
+        id: z.string().min(1),
+        label: z.string().min(1),
+        icon: z.string().optional(),
+        href: z.string().min(1),
+    }),
+]);
+/**
+ * `GET /api/login/methods` (PUBLIC). `bootstrap: true` ⇒ the deployment has zero
+ * accounts and `methods` contains the owner-creation form. Non-strict — the
+ * skeleton may grow additive fields.
+ */
+export const loginMethods = z.object({
+    methods: z.array(loginMethod),
+    bootstrap: z.boolean(),
+});
+/**
+ * A successful login/exchange: the minted session token (opaque, `tai-sess-`
+ * prefixed — the client treats it as an opaque string) + its user.
+ */
+export const loginResult = z.object({
+    token: z.string().min(1),
+    user_id: z.string().min(1),
+});
+// -- auth: the caller's capability projection (GET /api/auth/me) --------------
+/** A concrete route the caller can reach, with the methods that pass its jq fence. */
+export const routeEntry = z.object({
+    path: z.string(),
+    methods: z.array(z.string()),
+});
+/**
+ * A dynamic route pattern the caller can reach — a mount/pattern surface not
+ * enumerable into concrete paths, projected only when its scope AND jq admit it.
+ */
+export const patternEntry = z.object({
+    pattern: z.string(),
+    scope_id: z.string(),
+});
+/** A sub-MCP mount the caller can reach, with the tools it exposes. */
+export const subMcpEntry = z.object({
+    slug: z.string(),
+    tools: z.array(z.string()),
+    transport: z.string(),
+});
+/**
+ * `GET /api/auth/me` — the caller's derived capability projection: the concrete
+ * (path, method) surface, dynamic patterns, sub-MCP mounts, tools, and agents it
+ * can reach RIGHT NOW (derived server-side, never stored). `admin` is the
+ * condition-free ownerless `"*"` discriminator (a TOTAL projection); a scoped
+ * session carries `admin: false` and a jq-exact `routes` list. `owner_user_id` is
+ * the key's owner claim, `null` for an ownerless key. The invariant is
+ * projection ⊆ gate: every projected surface is one the server would admit, so
+ * the UI can filter on it without ever advertising a door the gate denies.
+ */
+export const meProjection = z.object({
+    user_id: z.string(),
+    owner_user_id: z.string().nullable(),
+    admin: z.boolean(),
+    scopes: z.array(z.string()),
+    routes: z.array(routeEntry),
+    route_patterns: z.array(patternEntry),
+    sub_mcp: z.array(subMcpEntry),
+    tools: z.array(z.string()),
+    agents: z.array(z.string()),
+    mintable: z.boolean(),
+});
+/**
+ * `POST /api/auth/claim-links` — a one-time claim link minted in the key-create
+ * flow. `claim_path` is a fragment-carrier path (`/login#claim=<token>`, never an
+ * absolute URL — the Studio composes the origin); `token` is the raw claim token
+ * returned exactly ONCE; `expires_at` is an ISO-8601 instant.
+ */
+export const claimLinkCreated = z.object({
+    claim_path: z.string(),
+    token: z.string(),
+    expires_at: z.string(),
+});
+/**
+ * `POST /api/auth/logout` — the single authed logout dispatcher's result.
+ * `revoked` is `true` when a live accounts session was revoked; a plain `sk-` key
+ * has nothing to revoke and answers `404` (a loud absent-session signal), never a
+ * `revoked: false` body. Non-strict, so a SUCCESSFUL logout never throws
+ * `ApiSchemaError` on an additive field.
+ */
+export const logoutResult = z.object({ revoked: z.boolean() });
+/**
+ * `GET /api/auth/capabilities` — whether this deployment can MINT API keys
+ * locally. `mintable: false` means every configured identity provider is
+ * validator-only (keys are issued at an external issuer), so the key-creation
+ * UI disables up front instead of surfacing a raw mint failure. Non-strict.
+ */
+export const authCapabilities = z.object({
+    mintable: z.boolean(),
+    providers: z.array(z.object({ name: z.string(), mintable: z.boolean() })),
+});
+// -- access-control policy (authoring + versioning) --------------------------
+/**
+ * `POST /api/auth/validate-condition` — the fail-closed jq guard. `ok` is the
+ * compile/render result; `result` is the boolean of a sample evaluation, or
+ * `null` when no `sample_context` was supplied (compile-only). A broken condition
+ * is a `400 {error}` surfaced by the transport, NEVER a false `ok` — so a
+ * syntactically-broken condition can be caught before it locks a key out. A drift
+ * throws `ApiSchemaError`.
+ */
+export const validateConditionResult = z.object({
+    ok: z.boolean(),
+    result: z.boolean().nullable(),
+});
+/**
+ * The enforced policy shape a version body carries. SECRET-ADJACENT — `condition`
+ * can reveal auth logic, so its fixtures are hand-authored, never captured.
+ * `condition`/`condition_id` are mutually exclusive at author time; both are
+ * nullable here because whichever mode is unused is stored as `null`.
+ */
+export const policyBody = z.object({
+    scopes: z.array(z.string()),
+    policy_data: jsonValue,
+    condition: z.string().nullable(),
+    condition_id: z.string().nullable(),
+    condition_kwargs: jsonValue.nullable(),
+});
+/**
+ * One immutable policy version row
+ * (`GET /api/auth/api-keys/{user_id}/policy/versions`). `is_current` flags the
+ * active pointer; `tags` is the generic per-version label list (kind-agnostic),
+ * mirroring the preset version shape.
+ */
+export const policyVersion = z.object({
+    version: z.number(),
+    body: policyBody,
+    tags: z.array(z.string()),
+    created_at: z.string(),
+    is_current: z.boolean(),
+});
+export const policyVersionList = z.array(policyVersion);
+/** `POST /api/auth/api-keys/{user_id}/policy/rollback` — the re-pointed version. */
+export const policyRollback = z.object({ user_id: z.string(), active_version: z.number() });
+// -- backup ------------------------------------------------------------------
+export const backupSections = z.array(z.object({ name: z.string(), secret: z.boolean() }));
+/** The exported backup document — validated when the UI reads a picked file. */
+export const backupDocument = z.object({
+    version: z.literal(1),
+    created_at: z.string(),
+    sections: z.record(z.string(), z.unknown()),
+    errors: z.record(z.string(), z.string()).optional(),
+});
+export const backupImportReport = z.object({
+    ok: z.boolean(),
+    sections: z.record(z.string(), z.object({
+        created: z.number(),
+        updated: z.number(),
+        skipped: z.number(),
+        errors: z.array(z.string()),
+        new_api_keys: z
+            .array(z.object({
+            user_id: z.string(),
+            description: z.string(),
+            api_key: z.string(),
+        }))
+            .optional(),
+        // The `manifest` and `env` sections apply through the config pipeline, so their
+        // report carries the mode-wrapped fleet `fanout` of the restore's reload; other
+        // sections omit it. Parsed EXPLICITLY so the shared fleet-report handler can
+        // surface a failed restore propagation — otherwise zod would strip it silently.
+        fanout: fleetReportFanout.optional(),
+    })),
+});
+// -- schedules ---------------------------------------------------------------
+// The skeleton returns opaque backend-tool results; the table reads a few known
+// fields and passes the rest through untouched.
+export const scheduleItem = z
+    .object({
+    name: z.string(),
+    enabled: z.boolean().optional(),
+    schedule: jsonValue.optional(),
+    target: jsonValue.optional(),
+    args: z.array(jsonValue).optional(),
+    kwargs: z.record(z.string(), jsonValue).optional(),
+})
+    .passthrough();
+export const scheduleList = z.array(scheduleItem);
+export const serverDateTime = z
+    .object({
+    utc: jsonValue,
+    local: jsonValue.optional(),
+    system: jsonValue.optional(),
+})
+    .passthrough();
+// -- observability -----------------------------------------------------------
+export const dashboardMetrics = z.object({
+    summary: z.object({
+        totalRuns: z.number(),
+        totalCost: z.number(),
+        totalTokens: z.number(),
+        averageLatencyMs: z.number(),
+        avgCostPerRun: z.number(),
+        avgTokensPerRun: z.number(),
+        timeToFirstTokenMs: z.number().nullable(),
+    }),
+    timeSeries: z.array(z.object({
+        bucket: z.string().nullable(),
+        runs: z.number(),
+        cost: z.number(),
+        avgLatencyMs: z.number(),
+        totalTokens: z.number(),
+    })),
+    byModel: z.array(z.object({
+        model: z.string(),
+        calls: z.number(),
+        cost: z.number(),
+        totalTokens: z.number(),
+        avgLatencyMs: z.number(),
+    })),
+    granularity: z.enum(['hour', 'day', 'week']),
+});
+export const run = z.object({
+    id: z.string(),
+    traceId: z.string(),
+    createdAt: z.string().nullable(),
+    tags: z.array(z.string()),
+    status: z.enum(['error', 'success']),
+    cost: z.number().nullable(),
+    latencyMs: z.number().nullable(),
+    totalTokens: z.number().nullable(),
+    model: z.string().nullable(),
+    inputPreview: jsonValue,
+    outputPreview: jsonValue,
+    fetchError: z.string().nullable(),
+});
+export const runsPage = z.object({
+    items: z.array(run),
+    page: z.number(),
+    nextPage: z.number().nullable(),
+});
+export const runSpan = z.object({
+    id: z.string(),
+    parentId: z.string().nullable(),
+    traceId: z.string().nullable(),
+    name: z.string().nullable(),
+    type: z.string().nullable(),
+    level: z.string().nullable(),
+    statusMessage: z.string().nullable(),
+    start: z.string().nullable(),
+    end: z.string().nullable(),
+    model: z.string().nullable(),
+    usage: jsonValue.nullable(),
+    metadata: jsonValue.nullable(),
+    input: jsonValue,
+    output: jsonValue,
+    nodeId: z.string().nullable(),
+});
+export const runTrace = z.object({
+    traceId: z.string(),
+    timestamp: z.string().nullable(),
+    tags: z.array(z.string()),
+    totalCost: z.number().nullable(),
+    input: jsonValue,
+    output: jsonValue,
+    metadata: jsonValue.nullable(),
+    availability: z.enum(['unavailable', 'full', 'partial']),
+    fetchError: z.string().nullable(),
+    spans: z.array(runSpan),
+});
+// -- marketplace -------------------------------------------------------------
+/**
+ * One contained item of a marketplace plugin (a searchable row): its kind
+ * (tool / agent / extension / …), name, description, and free-form tags.
+ */
+export const marketplaceItem = z.object({
+    kind: z.string(),
+    name: z.string(),
+    description: z.string(),
+    tags: z.array(z.string()),
+});
+/**
+ * One item-level search row (`GET /api/marketplace/search`): the contained item
+ * plus the listing it belongs to. `ref` is the "namespace/name" install target
+ * (install targets the LISTING), so every row carries enough to group under and
+ * link to its plugin. `latest_version` is nullable defensively; the search
+ * relation only emits listings with a published version.
+ */
+export const marketplaceSearchRow = z.object({
+    item: marketplaceItem,
+    ref: z.string(),
+    namespace: z.string(),
+    name: z.string(),
+    display_name: z.string().nullable(),
+    icon_url: z.string().nullable(),
+    package: z.string(),
+    description: z.string(),
+    categories: z.array(z.string()),
+    tags: z.array(z.string()),
+    trust_tier: z.string(),
+    pricing: z.string(),
+    latest_version: z.string().nullable(),
+    downloads: z.number(),
+    updated_at: z.string(),
+});
+/**
+ * One page of search rows. The wire carries no next-page field — has-next is
+ * COMPUTED: `page * page_size < total`.
+ */
+export const marketplaceSearchPage = z.object({
+    items: z.array(marketplaceSearchRow),
+    total: z.number(),
+    page: z.number(),
+    page_size: z.number(),
+});
+/**
+ * One version of a listing as the versions list carries it (`version`, its
+ * publication `status`, the `contract_range` it was validated against, and when
+ * it was `published_at`). `contract_range` and `published_at` are null until a
+ * version reaches the published state, so both are nullable.
+ */
+export const marketplaceVersion = z.object({
+    version: z.string(),
+    contract_range: z.string().nullable(),
+    status: z.string(),
+    published_at: z.string().nullable(),
+});
+/**
+ * The listing's latest published version as embedded in its detail: the version
+ * plus the items that version contains.
+ */
+export const marketplaceLatestVersion = marketplaceVersion.extend({
+    items: z.array(marketplaceItem),
+});
+/** One advisory row; `withdrawn_at` non-null means it no longer applies. */
+export const marketplaceAdvisory = z.object({
+    id: z.number(),
+    // The "namespace/name" listing ref exactly as the registry serves it — the
+    // wire field consumers match installed plugins against.
+    listing: z.string(),
+    affected_versions: z.string(),
+    severity: z.string(),
+    summary: z.string(),
+    created_at: z.string(),
+    withdrawn_at: z.string().nullable(),
+});
+/**
+ * A plugin's full detail (`GET /api/marketplace/plugins/{ns}/{name}`): the
+ * listing, its latest published version (`null` when nothing is published yet,
+ * carrying the contained items), and the known version history.
+ */
+export const marketplacePluginDetail = z.object({
+    namespace: z.string(),
+    name: z.string(),
+    display_name: z.string().nullable(),
+    icon_url: z.string().nullable(),
+    package: z.string(),
+    description: z.string(),
+    readme_md: z.string().nullable(),
+    license: z.string().nullable(),
+    homepage_url: z.string().nullable(),
+    repository_url: z.string().nullable(),
+    categories: z.array(z.string()),
+    tags: z.array(z.string()),
+    trust_tier: z.string(),
+    pricing: z.string(),
+    downloads: z.number(),
+    latest: marketplaceLatestVersion.nullable(),
+    versions: z.array(marketplaceVersion),
+});
+/**
+ * One installed marketplace plugin as the local attribution store records it.
+ * `latest` is the newest registry version (`null` when unknown); update
+ * availability comes from the wire field `update_available` (computed
+ * server-side as a PEP 440 comparison). `missing_upstream` flags a plugin the
+ * registry no longer lists.
+ */
+export const marketplaceInstalledPlugin = z.object({
+    ref: z.string(),
+    version: z.string(),
+    source: z.string(),
+    installed_at: z.string(),
+    latest: z.string().nullable(),
+    update_available: z.boolean(),
+    missing_upstream: z.boolean(),
+});
+export const marketplaceInstalled = z.array(marketplaceInstalledPlugin);
+/** The advisory state for installed plugins, with when it was last fetched. */
+export const marketplaceAdvisories = z.object({
+    advisories: z.array(marketplaceAdvisory),
+    fetched_at: z.string(),
+});
+/** The registry's controlled category list, proxied through the skeleton. */
+export const marketplaceCategories = z.array(z.string());
+/**
+ * The receipt of an install / update: what landed and at which version.
+ * `notes` (env-selected items naming their activating env var) and any
+ * non-critical `advisories` ride BOTH the install and update receipts. The wire
+ * also carries `package`, `reload`, and `pip_output`, which the receipt does not
+ * model — zod's default strip drops them; the UI renders the receipt, not the
+ * raw install log.
+ */
+export const marketplaceInstallResult = z.object({
+    ref: z.string(),
+    version: z.string(),
+    notes: z.array(z.string()),
+    advisories: z.array(marketplaceAdvisory),
+});
+/**
+ * The receipt of an uninstall. `notes` carries operator warnings (e.g. a config
+ * provider still selected by its env var); render them like the install
+ * receipt's notes.
+ */
+export const marketplaceUninstallResult = z.object({
+    ref: z.string(),
+    uninstalled: z.literal(true),
+    notes: z.array(z.string()),
+});
+// Background tool-run schemas live in their own module; re-exported here so the
+// shared fixture-validation contract resolves them by name alongside the rest.
+export { toolRunSubmitResult, toolRunRecord, toolRunList } from './tool-runs';
+//# sourceMappingURL=schemas.js.map