@tai42/api-client 15.0.0 → 16.0.1

package/src/schemas/fleet.ts

@@ -0,0 +1,153 @@
+/** Backend identity and worker-bus fleet/fan-out response schemas. */
+import { z } from 'zod';
+import { jsonValue } from './shared';
+
+/** `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(),
+});
+export type BackendInfo = z.infer<typeof backendInfo>;
+
+/** The two worker kinds that join the bus: an ASGI `serve` worker or a
+ * `backend` runtime process. A drift throws `ApiSchemaError`. */
+export const workerKind = z.enum(['serve', 'backend']);
+export type WorkerKind = z.infer<typeof workerKind>;
+
+/** The lifecycle state a worker advertises in its presence value: `ready` once its
+ * resync has converged, `resyncing` while a boot/reconnect resync runs, `recycling`
+ * once it has begun a graceful self-exit. A drift throws `ApiSchemaError`. */
+export const workerState = z.enum(['ready', 'resyncing', 'recycling']);
+export type WorkerState = z.infer<typeof workerState>;
+
+/** The last op a worker applied, stamped onto its presence row after the terminal
+ * reply. `outcome` is the free op-outcome string; `at` is the ISO instant it landed. */
+export const workerLastOp = z.object({
+  op: z.string(),
+  outcome: z.string(),
+  at: z.string(),
+});
+export type WorkerLastOp = z.infer<typeof workerLastOp>;
+
+/**
+ * One live worker on the bus — a presence-census row. `name` is the stable slot
+ * (`{kind}-{n}`) that doubles as a reload target; `generation` is the monotonic life
+ * counter minted with the worker's claim; `kind` tells the two worker kinds apart;
+ * `pid` is the process id. `joined_at`/`beat_at` are ISO instants (first-seen and last
+ * heartbeat) for the cosmetic seen-since display; `state` is the advertised lifecycle
+ * state; `stale` is SERVER-computed from the row's remaining presence TTL against the
+ * bus cadence (a quiet row past the freshness bound — reconnecting or dead) and is the
+ * only freshness signal a client reads, never a client-side threshold; `last_op` is the
+ * worker's last applied op, or `null` before it has applied one.
+ */
+export const fleetWorker = z.object({
+  name: z.string(),
+  kind: workerKind,
+  pid: z.number(),
+  generation: z.number(),
+  joined_at: z.string(),
+  beat_at: z.string(),
+  state: workerState,
+  stale: z.boolean(),
+  last_op: workerLastOp.nullable(),
+});
+export type FleetWorker = z.infer<typeof fleetWorker>;
+
+/**
+ * `GET /api/fleet/workers` — the live worker fleet from the bus presence census.
+ * The census lists ALL subscribed workers (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(fleetWorker) });
+export type FleetWorkers = z.infer<typeof fleetWorkers>;
+
+/**
+ * One worker'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 worker never sends them); `resyncing`/`recycling`/
+ * `stale` are the gap outcomes for a row that failed the ready+fresh gate — reported as
+ * its own actual condition rather than dropped (`resyncing` converges on its resync,
+ * `recycling` is departing, `stale` is a quiet row past the freshness bound carrying no
+ * convergence promise).
+ */
+export const fleetOutcome = z.enum([
+  'applied',
+  'failed',
+  'missing',
+  'departed',
+  'timed_out',
+  'resyncing',
+  'recycling',
+  'stale',
+]);
+export type FleetOutcome = z.infer<typeof fleetOutcome>;
+
+/**
+ * One worker'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 gap outcome (`missing`/`departed`/`timed_out`/
+ * `resyncing`/`recycling`/`stale`). A drift throws `ApiSchemaError`.
+ */
+export const fleetWorkerResult = z.object({
+  name: z.string(),
+  outcome: fleetOutcome,
+  payload: jsonValue,
+  error: z.string().nullable(),
+  detail: z.string().nullable(),
+});
+export type FleetWorkerResult = z.infer<typeof fleetWorkerResult>;
+
+/**
+ * The awaited per-worker report of one fleet broadcast. Two honest shapes ride the
+ * same schema. Reachable (`reachable: true`): `results` holds one entry per expected
+ * worker (the serving worker's own entry included) plus the gap rows, so an unconfirmed
+ * sibling is a visible `failed`/`missing`/`departed`/`timed_out`/`resyncing`/`recycling`/
+ * `stale` entry, never a silent stale worker. Bus-unreachable (`reachable: false`): the
+ * transport failed before any worker 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(fleetWorkerResult),
+  error: z.string().nullable(),
+});
+export type FleetResult = z.infer<typeof fleetResult>;
+
+/**
+ * `POST /api/fleet/reload-config` — soft-restart the fleet and report per-worker. The
+ * serving worker applies its own reload first, then broadcasts; the returned report
+ * names every worker'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;
+export type FleetReloadResult = z.infer<typeof fleetReloadResult>;
+
+/**
+ * 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 worker 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') }),
+]);
+export type FleetReportFanout = z.infer<typeof fleetReportFanout>;

package/src/schemas/hooks.ts

@@ -0,0 +1,56 @@
+/** Hook listing, registration and topic-verifier response schemas. */
+import { z } from 'zod';
+import { hookParams } from './served';
+
+// The hand-written hook response DTOs: the fire-door authority enum, the list rows and
+// their wrapper, and the per-topic verifier/trigger metadata. The served hook DOCUMENT
+// schemas (`hookSubject`/`hookParams`/`hookRegister`) are generated from the contract
+// bundle and re-exported at the top of this file, not defined here.
+
+/** A fire door — who may trigger a path, not what the fire may do. A string enum. */
+export const triggerAuth = z.enum([
+  'public',
+  'verifier',
+  'token',
+  'token+api_key',
+  'out-of-service',
+]);
+export type TriggerAuth = z.infer<typeof triggerAuth>;
+
+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({}),
+  // Per-topic fire door (topic → door). Tolerant of an older response omitting it.
+  trigger_auth: z.record(z.string(), triggerAuth).default({}),
+});
+export type HookList = z.infer<typeof hookList>;
+
+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() });

package/src/schemas/index.ts

@@ -0,0 +1,37 @@
+/** Public barrel for the api-client response/DTO schemas. */
+export * from './served';
+export { jsonSchema, jsonValue } from './shared';
+export * from './tools';
+export * from './extensions';
+export * from './presets';
+export * from './tool-meta';
+export * from './templates';
+export * from './storage';
+export * from './fleet';
+export * from './manifest-mcp';
+export * from './system-kinds';
+export * from './sub-mcp';
+export * from './config';
+export * from './profiles';
+export * from './connectors';
+export * from './studio-plugins';
+export * from './interactions';
+export * from './channels';
+export * from './conversations';
+export * from './web-entry';
+export * from './notifications';
+export * from './hooks';
+export * from './trigger-links';
+export * from './settings-schema';
+export * from './auth-routes';
+export * from './roles';
+export * from './api-keys';
+export * from './login';
+export * from './capabilities';
+export * from './policy';
+export * from './backup';
+export * from './schedules';
+export * from './observability';
+export * from './marketplace';
+export * from './states';
+export { toolRunSubmitResult, toolRunRecord, toolRunList } from '../tool-runs';

package/src/schemas/interactions.ts

@@ -0,0 +1,146 @@
+/** Interaction question, answer and media response schemas. */
+import { z } from 'zod';
+import { pageWindow } from './shared';
+
+// 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']);
+export type AnswerFormat = z.infer<typeof answerFormat>;
+
+/** The kind of a question's display-only media item: a remote/inline image, or a link. */
+export const mediaKind = z.enum(['image', 'link']);
+export type MediaKind = z.infer<typeof mediaKind>;
+
+/**
+ * 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 type InteractionMediaItem = z.infer<typeof interactionMediaItem>;
+
+/**
+ * One per-send choice for a `form` property whose schema is a string (or array of
+ * strings). `value` is what the answer carries; `label` (absent OR null both parse
+ * to no label) is the human text shown in its place. A send may replace a property's
+ * `enum` this way for one ask without republishing the form. Applied per property by
+ * the form preview (safeParsed), so a malformed entry is a loud notice, never silent.
+ */
+export const formOption = z.object({
+  value: z.string(),
+  label: z.string().nullish(),
+});
+export type FormOption = z.infer<typeof formOption>;
+
+/**
+ * Per-send `form` data: `values` prefills top-level properties (keyed by property
+ * name), `options` supplies per-send choice lists (keyed by property name). Both
+ * default to empty. The form preview safeParses this off `format_payload.data`, so a
+ * malformed block is a loud notice rather than a whole-frame parse failure.
+ */
+export const formData = z.object({
+  values: z.record(z.string(), z.unknown()).default({}),
+  options: z.record(z.string(), z.array(formOption)).default({}),
+});
+export type FormData = z.infer<typeof formData>;
+
+/**
+ * One page of a stepped `form`: a `title` and the ordered top-level property names it
+ * groups. `format_payload.pages` is the ordered list of these; absent = one page. The
+ * form preview safeParses the list, so a malformed page is a loud notice, never silent.
+ */
+export const formPage = z.object({
+  title: z.string(),
+  fields: z.array(z.string()),
+});
+export type FormPage = z.infer<typeof formPage>;
+
+/** The `form` pages list (`format_payload.pages`), safeParsed as a whole by the preview. */
+export const formPages = z.array(formPage);
+export type FormPages = z.infer<typeof formPages>;
+
+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 (with optional per-send
+  // `data` and `pages`), 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(),
+  // Interaction attribution, each additive and absent when unset. `recipient` is
+  // the channel delivery address the question went to; `origin` is the run id of
+  // the background tool run that asked; `audience` is the user_id the question is
+  // addressed to. Display/binding data only, never an authorization axis; a
+  // present non-string is malformed.
+  recipient: z.string().optional(),
+  origin: z.string().optional(),
+  audience: 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(),
+});
+export type Interaction = z.infer<typeof interaction>;
+
+/** The answer door's response — the blocked caller was woken. */
+export const interactionAnswered = z.object({
+  interaction_id: z.string(),
+  status: z.string(),
+});
+export type InteractionAnswered = z.infer<typeof interactionAnswered>;
+
+/**
+ * The cancel door's response — a pending ask was WITHDRAWN without an answer (the
+ * asking flow does not resume). `status` is `"cancelled"`; the shape mirrors the
+ * answer door's terminal reply, but the door is distinct so it carries its own
+ * schema.
+ */
+export const interactionCancelled = z.object({
+  interaction_id: z.string(),
+  status: z.string(),
+});
+export type InteractionCancelled = z.infer<typeof interactionCancelled>;
+
+/**
+ * A page of pending interactions from `GET /api/interactions?page=&pageSize=`. Each
+ * item is the same record the stream's `interaction.add` frame carries. The pending
+ * set is the paged base the tail-only stream applies live deltas over.
+ */
+export const interactionsPage = z.object({
+  items: z.array(interaction),
+  ...pageWindow,
+});
+export type InteractionsPage = z.infer<typeof interactionsPage>;

package/src/schemas/login.ts

@@ -0,0 +1,62 @@
+/** Public login-method aggregator and login-result schemas. */
+import { z } from 'zod';
+
+/**
+ * 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),
+});
+
+export type LoginFormField = z.infer<typeof loginFormField>;
+export type LoginMethod = z.infer<typeof loginMethod>;
+export type LoginMethods = z.infer<typeof loginMethods>;
+export type LoginResult = z.infer<typeof loginResult>;

package/src/schemas/manifest-mcp.ts

@@ -0,0 +1,69 @@
+/** Live-manifest MCP section, env-ref and config-reload schemas. */
+import { z } from 'zod';
+import { fleetReportFanout } from './fleet';
+
+/**
+ * The back-reference a connector writes onto a manifest MCP entry to mark it
+ * connector-owned: the connection and the provider sub-service that own it.
+ * Hand-authored entries carry no `managed` marker.
+ */
+export const connectorRef = z.object({
+  connection_id: z.string(),
+  provider_id: z.string(),
+  sub_service: z.string(),
+});
+export type ConnectorRef = z.infer<typeof connectorRef>;
+
+/**
+ * One entry of the live manifest's MCP section. Only the `managed` provenance
+ * marker is typed — the connect/disconnect flows write it server-side to point a
+ * connector-owned entry back at its connection, and the editor renders such
+ * entries read-only. `.nullish()` because a hand-authored entry carries `null`
+ * (present) or omits the key. Every other field (title, config, extensions) rides
+ * through `.loose()` unmodeled so the config editor keeps editing the whole
+ * entry — narrowing it to a typed subset would silently strip the fields it saves.
+ */
+export const manifestMcpEntry = z
+  .object({
+    managed: connectorRef.nullish(),
+  })
+  .loose();
+export type ManifestMcpEntry = z.infer<typeof manifestMcpEntry>;
+
+export const manifestView = z.object({
+  mcp: z.array(manifestMcpEntry),
+  user_tools: z.array(z.string()),
+});
+
+/**
+ * One `!ENV ${VAR[:default]}` marker the manifest's MCP section carries
+ * (`GET /api/manifest/mcp-env-refs`) — NAMES and BOOLEANS only, NEVER values.
+ * `pointer` is the RFC 6901 json-pointer of the leaf (`/mcp/<i>/config/...`);
+ * `has_default` is whether the marker carries a `:default`; `set` is whether the
+ * var resolves in the EFFECTIVE env (the resolution truth the install-time
+ * dangling refusal reads), so a var supplied by the deployment shows green, never
+ * a false red. The checklist derives from THIS alone — no env value is ever fetched.
+ */
+export const mcpEnvRef = z.object({
+  var: z.string(),
+  pointer: z.string(),
+  has_default: z.boolean(),
+  set: z.boolean(),
+});
+export type McpEnvRef = z.infer<typeof mcpEnvRef>;
+export const mcpEnvRefs = z.array(mcpEnvRef);
+export type McpEnvRefs = z.infer<typeof mcpEnvRefs>;
+/**
+ * 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,
+});
+export type ReloadConfigResult = z.infer<typeof reloadConfigResult>;