@tai42/api-client 16.0.0 → 16.0.1

package/src/schemas/connectors.ts

@@ -0,0 +1,138 @@
+/** Connector provider catalog and connection lifecycle schemas. */
+import { z } from 'zod';
+import { fleetReportFanout } from './fleet';
+
+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(),
+  // Required and a real URL: the contract's `ProviderDescriptor.icon_url` runs
+  // `check_web_url(schemes=("https",))`, which rejects an empty/relative value, so
+  // an empty or malformed one here is drift and fails the parse loudly.
+  icon_url: z.url(),
+  kind: z.enum(['oauth', 'none']),
+  origin: z.enum(['system', 'community']),
+  category: z.string(),
+  sub_services: z.array(subServiceView),
+  config_fields: z.array(configFieldView),
+});
+export type ProviderView = z.infer<typeof providerView>;
+
+/**
+ * One `connector_category` grouping row served alongside the catalog: the UI's
+ * label and sort key for the providers it groups, so the list can group, order,
+ * and label providers by category without a second read.
+ */
+export const connectorCategoryView = z.object({
+  id: z.string(),
+  display_name: z.string(),
+  sort_order: z.number(),
+});
+export type ConnectorCategoryView = z.infer<typeof connectorCategoryView>;
+
+/**
+ * `GET /api/connectors/providers` — the provider catalog: the providers plus the
+ * category groupings the UI arranges them under. Reshaped from a bare provider
+ * array so the category label/order surface rides the same read.
+ */
+export const providers = z.object({
+  providers: z.array(providerView),
+  categories: z.array(connectorCategoryView),
+});
+export type ProviderCatalogResponse = z.infer<typeof providers>;
+
+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()),
+  // Sub-services whose MCP server did not answer a live reachability probe.
+  // Populated only on the single-connection GET (the list projection is
+  // probe-free and always sends `[]`). Reachability is distinct from
+  // `auth_health_state`: a healthy connection can still have a down sub-service.
+  // Defaulted so a projection that omits it (an older worker mid-rollout) still
+  // parses rather than false-failing the whole view.
+  unreachable_sub_services: z.array(z.string()).default([]),
+  auth_health_state: z.enum(['healthy', 'reconnect_required', 'refresh_failing']),
+  created_at: z.string(),
+});
+export type ConnectionView = z.infer<typeof connectionView>;
+
+export const connectionsList = z.object({
+  items: z.array(connectionView),
+  total: z.number(),
+  // Count of connections whose `auth_health_state` is not healthy across the whole
+  // set (independent of any filter/limit) — the attention-badge count. Optional:
+  // no UI consumes it, and an older worker mid-rollout omits it.
+  unhealthy: z.number().optional(),
+});
+
+// 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() }),
+]);
+export type OAuthCompleteResult = z.infer<typeof oauthCompleteResult>;

package/src/schemas/conversations.ts

@@ -0,0 +1,256 @@
+/** Conversation route, thread, transcript and config schemas. */
+import { z } from 'zod';
+import { conversationRoute, targetConversationConfig } from './served';
+import { pageWindow } from './shared';
+
+// The cross-channel conversation monitor's READ side: the stored routing rows
+// (the route picker) from `GET /api/conversations`, a route's threads from
+// `GET /api/conversations/{route}/threads`, and one thread's transcript from
+// `GET /api/conversations/{route}/transcript?thread_id=`. Timestamps are float
+// epoch seconds, not ISO strings, and both paged doors carry the same window
+// fields; the transcript adds the direction it was read in.
+
+/** The inbound door a route is bound to: the authed API, or a channel medium. */
+export const conversationDoor = z.enum(['api', 'channel']);
+export type ConversationDoor = z.infer<typeof conversationDoor>;
+
+/** What a route's turn runs: a registered agent, or a tool dispatch. */
+export const conversationTargetKind = z.enum(['agent', 'tool']);
+export type ConversationTargetKind = z.infer<typeof conversationTargetKind>;
+
+/**
+ * A route's default control mode (`initial_mode`) when a thread carries no
+ * per-thread override: `agent` runs the target turn, `manual` suppresses it for an
+ * operator to answer. The same value vocabulary as a per-thread mode override, but
+ * a distinct concept (the route default vs. one thread's override).
+ */
+export const conversationMode = z.enum(['agent', 'manual']);
+export type ConversationMode = z.infer<typeof conversationMode>;
+
+/**
+ * Where a record sits between intake and a terminal outcome. `failed` is the one
+ * the monitor surfaces loudly; `shed` and `silent` are terminal by design and
+ * never send.
+ */
+export const conversationDeliveryStatus = z.enum([
+  'accepted',
+  'pending_delivery',
+  'provisional',
+  'delivered',
+  'failed',
+  'shed',
+  'silent',
+]);
+export type ConversationDeliveryStatus = z.infer<typeof conversationDeliveryStatus>;
+
+/** The nature of a turn's outcome, orthogonal to where its delivery stands. */
+export const conversationAnswerStatus = z.enum(['answered', 'error', 'silent']);
+export type ConversationAnswerStatus = z.infer<typeof conversationAnswerStatus>;
+
+/**
+ * Who authored a record's outgoing side. `client` is the ordinary turn the flow
+ * answered; `operator` is a message a human sent into the thread, whose text
+ * rides `answer` (its `inbound_text` is empty).
+ */
+export const conversationRecordOrigin = z.enum(['client', 'operator']);
+export type ConversationRecordOrigin = z.infer<typeof conversationRecordOrigin>;
+
+export const conversationRoutes = z.object({
+  items: z.array(conversationRoute),
+  total: z.number(),
+});
+export type ConversationRoutes = z.infer<typeof conversationRoutes>;
+
+/**
+ * The create/replace reply: whether THIS call created the row (vs. replaced an
+ * existing one), the row itself (its `callback_secret` withheld), and the
+ * `callback_secret` returned ONCE for an `api`-door row (`null` for a `channel`
+ * row). The secret signs delivery callbacks and is never re-read from any door, so
+ * a caller that needs it must capture it from this reply.
+ */
+export const conversationRouteWritten = z.object({
+  created: z.boolean(),
+  route_name: z.string(),
+  route: conversationRoute,
+  callback_secret: z.string().nullable(),
+});
+export type ConversationRouteWritten = z.infer<typeof conversationRouteWritten>;
+
+/**
+ * The delete reply: `removed` says whether THIS call removed the routing row (a
+ * retryable reclamation of orphaned thread indexes answers `false` rather than a
+ * 404).
+ */
+export const conversationRouteDeleted = z.object({
+  removed: z.boolean(),
+  route_name: z.string(),
+});
+export type ConversationRouteDeleted = z.infer<typeof conversationRouteDeleted>;
+
+/**
+ * One thread of a route, summarized from its newest record. A `thread_id` holds
+ * an api-door address (`{principal}/{end user}`, percent-encoded), so it never
+ * goes back into a URL as a path segment — the transcript door takes it as a
+ * query value.
+ */
+export const conversationThread = z.object({
+  thread_id: z.string(),
+  client_address: z.string(),
+  last_activity_at: z.number(),
+  message_count: z.number(),
+  last_delivery_status: conversationDeliveryStatus,
+});
+export type ConversationThread = z.infer<typeof conversationThread>;
+
+export const conversationThreadsPage = z.object({
+  items: z.array(conversationThread),
+  ...pageWindow,
+});
+export type ConversationThreadsPage = z.infer<typeof conversationThreadsPage>;
+
+/**
+ * One exchange: the visitor's `inbound_text` — every record answers a message, so
+ * both projections always carry it — and the agent's `answer`, plus where that
+ * answer's delivery stands. The fields after `updated_at` are ADMIN ONLY —
+ * the same door serves a caller-scoped projection that withholds them — so they
+ * are optional here and absence means "not published to this reader".
+ */
+export const conversationMessage = z.object({
+  message_id: z.string(),
+  route_name: z.string(),
+  door: conversationDoor,
+  thread_id: z.string(),
+  client_address: z.string(),
+  caller_principal: z.string().nullable(),
+  inbound_text: z.string(),
+  answer_status: conversationAnswerStatus.nullable(),
+  answer: z.string().nullable(),
+  origin: conversationRecordOrigin,
+  delivery_status: conversationDeliveryStatus,
+  created_at: z.number(),
+  updated_at: z.number(),
+  channel: z.string().nullable().optional(),
+  our_identity: z.string().nullable().optional(),
+  provider_message_id: z.string().nullable().optional(),
+  callback_url: z.string().nullable().optional(),
+  error: z.string().nullable().optional(),
+  outbound_message_ids: z.array(z.string()).optional(),
+  attempts: z.number().optional(),
+});
+export type ConversationMessage = z.infer<typeof conversationMessage>;
+
+/**
+ * The direction a transcript page reads in. `asc` is the reading order (oldest
+ * first); `desc` is the live-tail order, where page 1 is always the newest page
+ * and paging forward walks BACKWARDS through the thread's history.
+ */
+export const transcriptOrder = z.enum(['asc', 'desc']);
+export type TranscriptOrder = z.infer<typeof transcriptOrder>;
+
+/** A transcript page, echoing the order it was read in. */
+export const conversationTranscriptPage = z.object({
+  items: z.array(conversationMessage),
+  ...pageWindow,
+  order: transcriptOrder,
+});
+export type ConversationTranscriptPage = z.infer<typeof conversationTranscriptPage>;
+
+/**
+ * A route-scoped message search (`GET /api/conversations/{route}/messages/search?q`):
+ * every record on the route whose text matches `q`, across threads, newest first.
+ * The record shape is the transcript's exactly, so a hit renders with the same
+ * projection. `truncated` says the match set outran the door's scan cap — surfaced
+ * loudly, never a silent cut.
+ */
+export const conversationMessageSearchPage = z.object({
+  items: z.array(conversationMessage),
+  ...pageWindow,
+});
+export type ConversationMessageSearchPage = z.infer<typeof conversationMessageSearchPage>;
+
+/**
+ * Who answers a thread's incoming messages: `agent` lets the flow reply on its
+ * own; `manual` holds the flow back so a human answers. `source` says whether the
+ * setting is the thread's own (`thread`) or inherited from its route (`route`).
+ */
+export const conversationThreadMode = z.enum(['agent', 'manual']);
+export type ConversationThreadMode = z.infer<typeof conversationThreadMode>;
+
+export const conversationThreadModeState = z.object({
+  mode: conversationThreadMode,
+  source: z.enum(['thread', 'route']),
+});
+export type ConversationThreadModeState = z.infer<typeof conversationThreadModeState>;
+
+/** The receipt a thread-message write returns: the stored id and its thread. */
+export const conversationThreadMessageSent = z.object({
+  message_id: z.string(),
+  thread_id: z.string(),
+});
+export type ConversationThreadMessageSent = z.infer<typeof conversationThreadMessageSent>;
+
+/** Every stored per-target config (`GET /api/conversation-configs`). */
+export const conversationConfigs = z.object({
+  items: z.array(targetConversationConfig),
+  total: z.number(),
+});
+export type ConversationConfigs = z.infer<typeof conversationConfigs>;
+
+/**
+ * The upsert reply: whether THIS call created the config (vs. replaced an existing
+ * one), its key, and the stored row.
+ */
+export const conversationConfigWritten = z.object({
+  created: z.boolean(),
+  target_kind: conversationTargetKind,
+  target_name: z.string(),
+  config: targetConversationConfig,
+});
+export type ConversationConfigWritten = z.infer<typeof conversationConfigWritten>;
+
+/** The config-delete reply: `removed` is always `true` on success (an unknown key is a 404). */
+export const conversationConfigDeleted = z.object({
+  removed: z.boolean(),
+  target_kind: conversationTargetKind,
+  target_name: z.string(),
+});
+export type ConversationConfigDeleted = z.infer<typeof conversationConfigDeleted>;
+
+/**
+ * The admin-only failed-delivery listing (`GET /api/conversations/messages/failed`):
+ * every answer record whose delivery ended `failed`, across every route and caller.
+ * The records are the ADMIN projection (delivery bookkeeping and `error` included),
+ * so the row shape is {@link conversationMessage} exactly. It is NOT a paged window —
+ * the door returns `{items, total}` and nothing more.
+ */
+export const conversationFailedMessages = z.object({
+  items: z.array(conversationMessage),
+  total: z.number(),
+});
+export type ConversationFailedMessages = z.infer<typeof conversationFailedMessages>;
+
+/**
+ * The thread-delete reply (`DELETE /api/conversations/{route_name}/thread?thread_id=`).
+ * `removed` is a COUNT of the answer records this call deleted — `0` when a prior
+ * run already cleared them, when they had aged out under retention, or when the id
+ * was never stored (forgetting is absolute, never a 404 on a valid id).
+ */
+export const conversationThreadDeleted = z.object({
+  removed: z.number(),
+  route_name: z.string(),
+  thread_id: z.string(),
+});
+export type ConversationThreadDeleted = z.infer<typeof conversationThreadDeleted>;
+
+/**
+ * The person-erase reply (`DELETE /api/conversations/persons/{person_id}`).
+ * `removed` counts the answer records deleted across the person's routes; `erased`
+ * says whether THIS call removed the person row (`false` on a retry or an
+ * already-gone person — never a 404).
+ */
+export const conversationPersonDeleted = z.object({
+  person_id: z.string(),
+  removed: z.number(),
+  erased: z.boolean(),
+});
+export type ConversationPersonDeleted = z.infer<typeof conversationPersonDeleted>;

package/src/schemas/extensions.ts

@@ -0,0 +1,34 @@
+/** Extension element/combo and per-tool extension response schemas. */
+import { z } from 'zod';
+
+export const extension = z.object({ name: z.string(), kind: z.string() });
+export const extensions = z.array(extension);
+export type Extension = z.infer<typeof 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()) }),
+]);
+export type PresetExtensionElement = z.infer<typeof presetExtensionElement>;
+
+/**
+ * `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,
+});
+export type ToolExtensions = z.infer<typeof toolExtensions>;

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';