@tai42/api-client 16.0.0 → 17.0.0

package/src/schemas/states.ts

@@ -0,0 +1,273 @@
+/** State declaration, record, template and consumer response schemas. */
+import { z } from 'zod';
+
+import { conversationTargetKind } from './conversations';
+import { stateDeclaration, stateTemplateDocument } from './served';
+
+// The hand-written state response DTOs — list rows and detail (built on the generated
+// `stateDeclaration`), attachments, per-subject records and subjects, stats and consumers.
+// The served DOCUMENT schemas (`stateDeclaration`/`stateTemplateDocument` and the template
+// sub-shapes) are generated from the contract bundle and re-exported at the top of this
+// file. The composed `effective_schema` and write `regimes` stay permissive JSON records
+// (the auto-form and JsonTree interpret them at runtime) and are server-computed, so they
+// are modelled optional and a response that omits them still parses.
+
+/** One addressed subject: the conversation-target scope plus the (kind, key) within it. */
+export const stateSubject = z.object({
+  target_kind: conversationTargetKind,
+  target_name: z.string(),
+  kind: z.string(),
+  key: z.string(),
+});
+export type StateSubject = z.infer<typeof stateSubject>;
+
+/** One absolute write-regime rule composed over the attachments: `{path, regime}`, permissive. */
+export const stateRegime = z.record(z.string(), z.unknown());
+
+/**
+ * One row of `GET /api/states` — a served declaration (`list_states` dumps every
+ * `StateDeclaration`) plus `updated_at` (the row's last-write timestamp, ISO or
+ * `null`). The list carries no record count; the `Records` column reads
+ * `getStateStats` lazily per row.
+ */
+export const stateListItem = stateDeclaration.extend({
+  updated_at: z.string().nullable().default(null),
+});
+export type StateListItem = z.infer<typeof stateListItem>;
+export const stateList = z.array(stateListItem);
+
+/** One template attachment on a state: where the fragment lands + its param/declaration values. */
+export const stateAttachment = z.object({
+  template: z.string(),
+  path: z.array(z.string()),
+  parameters: z.record(z.string(), z.unknown()).default({}),
+  declarations: z.record(z.string(), z.unknown()).default({}),
+});
+export type StateAttachment = z.infer<typeof stateAttachment>;
+export const stateAttachmentList = z.array(stateAttachment);
+
+/** `GET /api/states/{name}` — the declaration (with effective schema + regimes) plus attachments. */
+export const stateDetail = stateDeclaration.extend({
+  attachments: z.array(stateAttachment).default([]),
+});
+export type StateDetail = z.infer<typeof stateDetail>;
+
+/**
+ * `GET /api/states/{name}/stats` — `records` (total documents), `per_field` (the count
+ * of records carrying each base-schema property), `per_kind` (records per subject kind)
+ * and `consumers` (the count of listable consumers). The Records tab shows `records`;
+ * the states list reads it lazily for its Records column.
+ */
+export const stateStats = z.object({
+  records: z.number(),
+  per_field: z.record(z.string(), z.number()).default({}),
+  per_kind: z.record(z.string(), z.number()).default({}),
+  consumers: z.number().default(0),
+});
+export type StateStats = z.infer<typeof stateStats>;
+
+/**
+ * One row of `GET /api/state-templates`. The template document plus the two derived columns
+ * the Templates tab shows: `attached_to` (how many states attach it — a delete is refused
+ * while > 0) and `shipped_default` (a platform-shipped template). Both are server-derived
+ * columns; the document fields are verbatim.
+ */
+export const stateTemplateListItem = stateTemplateDocument.extend({
+  attached_to: z.number().default(0),
+  shipped_default: z.boolean().default(false),
+});
+export type StateTemplateListItem = z.infer<typeof stateTemplateListItem>;
+export const stateTemplateList = z.array(stateTemplateListItem);
+
+/** A read record: the state, its subject, the document + monotonic seq, and any fold. */
+export const stateRecord = z.object({
+  state: z.string(),
+  subject: stateSubject,
+  data: z.record(z.string(), z.unknown()).default({}),
+  seq: z.number(),
+  canonical_subject: stateSubject,
+  folded_from: z.array(stateSubject).default([]),
+});
+export type StateRecord = z.infer<typeof stateRecord>;
+
+/** The outcome of an `apply` (a delta batch): whether it applied + the resulting doc. */
+export const applyResult = z.object({
+  applied: z.boolean(),
+  data: z.record(z.string(), z.unknown()).nullable().default(null),
+  seq: z.number().nullable().default(null),
+  skipped: z.array(z.record(z.string(), z.unknown())).default([]),
+});
+export type ApplyResult = z.infer<typeof applyResult>;
+
+/**
+ * `GET …/template-jq/{name}` — the evaluated template jq's `name`, its `purpose`, and
+ * its `value` (the `input` jq's read). GET evaluates ONLY an `input`-purpose jq; a GET
+ * on an `update`-purpose name is refused with 422, so the result's purpose is always
+ * `input`.
+ */
+export const templateJqResult = z.object({
+  name: z.string(),
+  purpose: z.literal('input'),
+  value: z.unknown(),
+});
+export type TemplateJqResult = z.infer<typeof templateJqResult>;
+
+/**
+ * `POST …/template-jq/{name}` — the applied template jq's outcome. The jq lands an op
+ * batch through the same `apply` chokepoint as a delta, so `applied`/`data`/`seq`/`skipped`
+ * carry that outcome.
+ */
+export const templateJqApplyResult = z.object({
+  name: z.string(),
+  applied: z.boolean(),
+  data: z.record(z.string(), z.unknown()).nullable().default(null),
+  seq: z.number().nullable().default(null),
+  skipped: z.array(z.record(z.string(), z.unknown())).default([]),
+});
+export type TemplateJqApplyResult = z.infer<typeof templateJqApplyResult>;
+
+/**
+ * One paged subject row: the addressed `subject` plus its record's last-write
+ * `updated_at` — epoch seconds (the store's `extract(epoch FROM updated_at)`), served
+ * raw (no `mode="json"` dump), and `NOT NULL` on every record, so a plain number.
+ */
+export const subjectRow = z.object({
+  subject: stateSubject,
+  updated_at: z.number(),
+});
+export type SubjectRow = z.infer<typeof subjectRow>;
+
+/**
+ * `GET /api/states/{name}/subjects` — a keyset page of subject rows (optionally of one
+ * `kind`): the matched `subjects` plus the `next_cursor` a "Load more" carries back
+ * (`null` at the end).
+ */
+export const subjectPage = z.object({
+  subjects: z.array(subjectRow),
+  next_cursor: z.string().nullable().default(null),
+});
+export type SubjectPage = z.infer<typeof subjectPage>;
+
+/**
+ * `POST /api/states/{name}/records/search` — a keyset page of the subject rows whose
+ * document contains the filters (a JSONB containment match). Each hit's `subject` opens
+ * the record page; `next_cursor` pages the rest.
+ */
+export const recordSearchPage = z.object({
+  matches: z.array(subjectRow),
+  next_cursor: z.string().nullable().default(null),
+});
+export type RecordSearchPage = z.infer<typeof recordSearchPage>;
+
+/** A WriteEntry's origin completed by the platform chokepoint (mirrors CompletedOrigin). */
+export const completedOrigin = z.object({
+  consumer: z.string().nullable().default(null),
+  // Opaque consumer-supplied provenance JSON the platform stores as is.
+  meta: z.record(z.string(), z.unknown()).nullable().default(null),
+  run_id: z.string().nullable().default(null),
+  op_id: z.string().nullable().default(null),
+  door: z.string(),
+  actor: z.string().nullable().default(null),
+  turn_id: z.string().nullable().default(null),
+  inbound_id: z.string().nullable().default(null),
+});
+export type CompletedOrigin = z.infer<typeof completedOrigin>;
+
+/** One row of a subject's audit trail (mirrors WriteEntry). `paths` are absolute. */
+export const writeEntry = z.object({
+  seq: z.number(),
+  at: z.string(),
+  origin: completedOrigin,
+  paths: z.array(z.array(z.union([z.string(), z.number()]))).default([]),
+});
+export type WriteEntry = z.infer<typeof writeEntry>;
+
+/** `GET /api/states/{name}/records/.../writes` — a keyset page of the audit trail. */
+export const writesPage = z.object({
+  items: z.array(writeEntry),
+  next_cursor: z.string().nullable().default(null),
+});
+export type WritesPage = z.infer<typeof writesPage>;
+
+/** Where the Studio opens a consumer (mirrors ConsumerLink): a token+search OR plugin path. */
+export const consumerLink = z.object({
+  token: z.string().nullable().default(null),
+  plugin_path: z.string().nullable().default(null),
+  search: z.record(z.string(), z.unknown()).nullable().default(null),
+});
+export type ConsumerLink = z.infer<typeof consumerLink>;
+
+/**
+ * One thing that binds a state (mirrors ConsumerRow): its `kind` (flow / hook / schedule
+ * / agent), `name`, human `detail` and optional `link`. `unavailable` marks a consumer
+ * family that cannot be listed on this deployment (e.g. no scheduling backend), surfaced
+ * as a muted line — never swallowed.
+ */
+export const consumerRow = z.object({
+  kind: z.string(),
+  name: z.string().nullable().default(null),
+  detail: z.string().nullable().default(null),
+  link: consumerLink.nullable().default(null),
+  unavailable: z.string().nullable().default(null),
+});
+export type ConsumerRow = z.infer<typeof consumerRow>;
+
+/** `GET /api/states/{name}/consumers` — the union of every registered lister's rows. */
+export const stateConsumers = z.array(consumerRow);
+export type StateConsumers = z.infer<typeof stateConsumers>;
+
+/** `DELETE /api/states/{name}` — the removed state. */
+export const stateDeleted = z.object({ name: z.string(), deleted: z.literal(true) });
+
+/** `PUT /api/states/{name}/attachments/{template}` — the template now attached to the state. */
+export const stateAttached = z.object({
+  attached: z.literal(true),
+  state: z.string(),
+  template: z.string(),
+});
+export type StateAttached = z.infer<typeof stateAttached>;
+
+/** `PATCH /api/states/{name}/attachments/{template}` — the attachment whose declarations were rewritten. */
+export const stateAttachmentUpdated = z.object({
+  updated: z.literal(true),
+  state: z.string(),
+  template: z.string(),
+});
+export type StateAttachmentUpdated = z.infer<typeof stateAttachmentUpdated>;
+
+/** `DELETE /api/states/{name}/attachments/{template}` — the template detached from the state. */
+export const stateDetached = z.object({
+  detached: z.literal(true),
+  state: z.string(),
+  template: z.string(),
+});
+export type StateDetached = z.infer<typeof stateDetached>;
+
+/**
+ * `POST /api/states/{name}/records/.../fold` — the fold report: the `mode`, the
+ * `{kind, key}` of the folded `from` and surviving `into` subjects, whether the fold
+ * was `already` in place, and how many records were `flattened` into the survivor.
+ */
+export const stateFoldReport = z.object({
+  mode: z.enum(['switch', 'merge']),
+  from: z.object({ kind: z.string(), key: z.string() }),
+  into: z.object({ kind: z.string(), key: z.string() }),
+  already: z.boolean(),
+  flattened: z.number().default(0),
+});
+export type StateFoldReport = z.infer<typeof stateFoldReport>;
+
+/** `DELETE /api/state-templates/{name}` — the removed template document. */
+export const stateTemplateDeleted = z.object({ name: z.string(), deleted: z.literal(true) });
+
+/** `DELETE /api/states/{name}/records/...` — the erased record marker. */
+export const recordErased = z.object({ erased: z.literal(true) });
+
+/**
+ * `POST /api/state-retention/prune` — the retention sweep's per-state deleted counts
+ * (`{}` when nothing expired); the UI sums the values for its total.
+ */
+export const stateRetentionPruned = z.object({
+  pruned: z.record(z.string(), z.number()).default({}),
+});
+export type StateRetentionPruned = z.infer<typeof stateRetentionPruned>;

package/src/schemas/storage.ts

@@ -0,0 +1,31 @@
+/** Storage-provider info and resource CRUD response schemas. */
+import { z } from 'zod';
+
+/** `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(),
+});
+export type StorageInfo = z.infer<typeof storageInfo>;
+
+/** `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(),
+});
+export type StorageResourceStat = z.infer<typeof storageResourceStat>;
+
+/** `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) });

package/src/schemas/studio-plugins.ts

@@ -0,0 +1,21 @@
+/** Studio front-end plugin registry response schemas. */
+import { z } from 'zod';
+
+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);
+export type StudioPluginManifest = z.infer<typeof studioPluginManifest>;

package/src/schemas/sub-mcp.ts

@@ -0,0 +1,24 @@
+/** Sub-MCP mount registry response schemas. */
+import { z } from 'zod';
+
+/**
+ * One registered sub-MCP mount as it rides the registry list and the projection:
+ * the tools it exposes and the transport it serves on. In `GET /api/sub-mcp` the
+ * slug is the map key, so the mount value carries no slug; {@link subMcpEntry}
+ * extends this with `slug` for the capability projection where mounts are a flat
+ * list. `transport` is always present on the wire (the server defaults it to
+ * `http`), so it is required — its absence is a drift, not a legal shape.
+ */
+export const subMcpMount = z.object({
+  tools: z.array(z.string()),
+  transport: z.string(),
+});
+export type SubMcpMount = z.infer<typeof subMcpMount>;
+
+export const subMcpList = z.record(z.string(), subMcpMount);
+export const subMcpCreated = z.object({
+  slug: z.string(),
+  tools: z.array(z.string()),
+  transport: z.string(),
+});
+export const subMcpRemoved = z.object({ slug: z.string(), removed: z.literal(true) });

package/src/schemas/system-kinds.ts

@@ -0,0 +1,47 @@
+/** Pluggable-kind status and MCP status/reload response schemas. */
+import { z } from 'zod';
+
+import { fleetResult } from './fleet';
+import { reloadConfigResult } from './manifest-mcp';
+
+// `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);
+export type KindStatus = z.infer<typeof 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 type ToolExtensionsApplyResult = z.infer<typeof toolExtensionsApplyResult>;
+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-worker {@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;
+export type McpReloadResult = z.infer<typeof mcpReloadResult>;

package/src/schemas/templates.ts

@@ -0,0 +1,12 @@
+/** Prompt-template listing, render and mutation ack schemas. */
+import { z } from 'zod';
+
+import { jsonSchema } from './shared';
+
+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 templateDirDeleted = 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) });

package/src/schemas/tool-meta.ts

@@ -0,0 +1,51 @@
+/** Tool-organization overlay (folders and per-tool meta) schemas. */
+import { z } from 'zod';
+
+/**
+ * One folder in the tool-organization tree (`tool_folders`). `parent_id` is `null`
+ * for a root folder and otherwise the containing folder's `id`; nesting is endless
+ * via the parent chain. Ids are UUID strings. A drift throws `ApiSchemaError`.
+ */
+export const folderRecord = z.object({
+  id: z.string(),
+  name: z.string(),
+  parent_id: z.string().nullable(),
+});
+export type FolderRecord = z.infer<typeof folderRecord>;
+
+/**
+ * The organizational overlay for one tool, keyed by `tool_name`. `display_name`
+ * overrides the rendered label (`display_name ?? name`); `folder_id` places the tool
+ * in a folder (`null` = unfiled); `tags` is the user's editable categorization,
+ * merged with the tool's read-only native tags by the UI; `badges` is the operator's
+ * editable capability-label overlay, merged with the tool's read-only plugin-declared
+ * badges by the UI (INFORMATIONAL, never an enforced gate); `hidden` is TRI-STATE —
+ * `null` = defer to the plugin declaration, `true` = force hidden, `false` = force
+ * visible. A drift throws `ApiSchemaError`.
+ */
+export const toolMetaRecord = z.object({
+  tool_name: z.string(),
+  display_name: z.string().nullable(),
+  folder_id: z.string().nullable(),
+  tags: z.array(z.string()),
+  badges: z.array(z.string()),
+  hidden: z.boolean().nullable(),
+});
+export type ToolMetaRecord = z.infer<typeof toolMetaRecord>;
+
+/**
+ * `GET /api/tool-meta` — the whole overlay in one read: the flat folder tree plus
+ * every per-tool row. The UI builds the tree and merges the rows against the live
+ * tool list client-side. A drift throws `ApiSchemaError`.
+ */
+export const toolMetaOverlay = z.object({
+  folders: z.array(folderRecord),
+  meta: z.array(toolMetaRecord),
+});
+export type ToolMetaOverlay = z.infer<typeof toolMetaOverlay>;
+
+/** `DELETE /api/tool-meta/tools/{tool_name}` — the dropped overlay row (idempotent). */
+export const toolMetaDeleted = z.object({ tool_name: z.string(), deleted: z.literal(true) });
+
+/** `DELETE /api/tool-meta/folders/{folder_id}` — the removed empty folder. */
+export const folderDeleted = z.object({ folder_id: z.string(), deleted: z.literal(true) });

package/src/schemas/tools.ts

@@ -0,0 +1,62 @@
+/** Tool catalog, run-result and per-tool tag response schemas. */
+import { z } from 'zod';
+
+import { jsonSchema, jsonValue } from './shared';
+
+export const toolNames = z.array(z.string());
+
+export const toolSchema = z.object({
+  input: jsonSchema,
+  output: jsonSchema.nullable(),
+  description: z.string().nullable(),
+});
+export type ToolSchema = z.infer<typeof toolSchema>;
+
+export const allToolSchemas = z.record(z.string(), toolSchema);
+
+export const runToolResult = jsonValue;
+
+/**
+ * The MEDIA content shape a direct tool run may return — fastmcp's serialized
+ * `Image`/`Audio` MediaBlock (`{ type, data: <base64>, mimeType }`). One recognised
+ * shape of the otherwise-arbitrary `runToolResult`, kept as its own schema so the
+ * viewer detects media by parse, not by ad-hoc shape check.
+ *
+ * SECURITY: the refinement pins `mimeType` to its kind — `image` MUST be `image/*`,
+ * `audio` MUST be `audio/*` — so a drifting/arbitrary mime fails the parse and is
+ * never turned into a `data:` URI (a `File` MediaBlock's distinct `EmbeddedResource`
+ * shape also fails here, by design).
+ */
+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'],
+  });
+export type ToolMediaResult = z.infer<typeof toolMediaResult>;
+
+/**
+ * The ADDITIVE per-tool native surface (`GET /api/tools/tags`). Distinct from the
+ * flat `toolNames` contract (`GET /api/tools`, unchanged): each entry carries the
+ * tool's read-only FastMCP `tags` — so the shared `ToolPicker` can group/filter its
+ * options — plus `hidden`, the tool's OWN plugin-declared visibility (read from the
+ * FastMCP `meta` under `tai42/hidden`; a tool that never declared it is not hidden).
+ * The tool_meta overlay's tri-state override is merged on top client-side; this read
+ * exposes only the declaration.
+ *
+ * `badges` are the tool's plugin-DECLARED capability labels — purely INFORMATIONAL
+ * (e.g. `network`, `filesystem`), never a gate the server enforces. The overlay's
+ * own badges are merged on top client-side; this read exposes only the declaration.
+ */
+export const toolTagEntry = z.object({
+  name: z.string(),
+  tags: z.array(z.string()),
+  badges: z.array(z.string()),
+  hidden: z.boolean(),
+});
+export const toolTags = z.array(toolTagEntry);
+export type ToolTagEntry = z.infer<typeof toolTagEntry>;

package/src/schemas/trigger-links.ts

@@ -0,0 +1,55 @@
+/** Trigger-link record and lifecycle response schemas. */
+import { z } from 'zod';
+
+import { triggerAuth } from './hooks';
+
+// A trigger link is a minted, token-bearing PUBLIC URL (`GET|POST /trigger/{token}`)
+// that resolves to a hook TOPIC and fires it. Studio mints, lists, and revokes them
+// on the hooks page; the QR encodes the composed absolute URL.
+
+/**
+ * `POST /api/hooks/trigger-links` — a freshly minted trigger link. `trigger_path`
+ * is a relative path (`/trigger/<token>`, never an absolute URL — Studio composes
+ * the API origin); `token` is the raw token returned exactly ONCE, in this response
+ * (nothing else stores or lists it — a listed link's QR is unrecoverable by
+ * design). `expires_at` is an ISO-8601 instant, or `null` for a permanent link.
+ */
+export const triggerLinkCreated = z.object({
+  name: z.string(),
+  trigger_path: z.string(),
+  token: z.string(),
+  topic: z.string(),
+  expires_at: z.string().nullable(),
+});
+export type TriggerLinkCreated = z.infer<typeof triggerLinkCreated>;
+
+/**
+ * One listed trigger-link record (`GET /api/hooks/trigger-links` item). `tool_kwargs`
+ * is the per-link params merged last into every fire (`null` or `{}` = none);
+ * `created_by` is the ambient creator identity (`null` on an identity-less,
+ * gate-off deployment); `token_hash_prefix` is a short hash prefix for log
+ * correlation — never a raw token (none is stored).
+ */
+export const triggerLinkRecord = z.object({
+  name: z.string(),
+  topic: z.string(),
+  execution_key: z.string().min(1),
+  trigger_auth: triggerAuth,
+  tool_kwargs: z.record(z.string(), z.unknown()).nullable(),
+  created_by: z.string().nullable(),
+  created_at: z.string(),
+  expires_at: z.string().nullable(),
+  token_hash_prefix: z.string(),
+});
+export type TriggerLinkRecord = z.infer<typeof triggerLinkRecord>;
+
+/** `GET /api/hooks/trigger-links` — every live trigger-link record. */
+export const triggerLinkList = z.object({
+  items: z.array(triggerLinkRecord),
+  total: z.number(),
+});
+export type TriggerLinkList = z.infer<typeof triggerLinkList>;
+
+/** `DELETE /api/hooks/trigger-links/{name}` — the revoked link. */
+export const triggerLinkDeleted = z.object({ removed: z.boolean(), name: z.string() });
+export type TriggerLinkDeleted = z.infer<typeof triggerLinkDeleted>;

package/src/schemas/web-entry.ts

@@ -0,0 +1,46 @@
+/** Web-channel entry-gate code response schemas. */
+import { z } from 'zod';
+
+// The web channel's entry gate: a web route can be gated so its chat page is
+// served only to a navigation carrying a live entry code. These four doors are
+// keyed by the route's `our_identity`. A raw code exists only in flight (the
+// mint reply); a listed code carries its hash id, never a raw value (none is
+// stored).
+
+/** One minted entry code as the gate read door lists it — its hash id, its
+ * optional label, and when it was created / dies. Never a raw code. */
+export const webEntryCode = z.object({
+  code_id: z.string(),
+  label: z.string().nullable(),
+  created_at: z.string(),
+  expires_at: z.string().nullable(),
+});
+export type WebEntryCode = z.infer<typeof webEntryCode>;
+
+/** `GET /api/channels/web/gates/{identity}` — the gate flag and its live codes. */
+export const webEntryGate = z.object({
+  enabled: z.boolean(),
+  codes: z.array(webEntryCode),
+});
+export type WebEntryGate = z.infer<typeof webEntryGate>;
+
+/** `PUT /api/channels/web/gates/{identity}` — the gate flag after the write. */
+export const webEntryGateState = z.object({ enabled: z.boolean() });
+export type WebEntryGateState = z.infer<typeof webEntryGateState>;
+
+/**
+ * `POST /api/channels/web/gates/{identity}/codes` — a freshly minted code. The
+ * raw `code` rides this reply ONCE (nothing else stores or lists it — a listed
+ * code's raw value is unrecoverable by design); `code_id` is its hash id and
+ * `expires_at` an ISO-8601 instant, or `null` for a code that never expires.
+ */
+export const webEntryCodeMinted = z.object({
+  code: z.string(),
+  code_id: z.string(),
+  expires_at: z.string().nullable(),
+});
+export type WebEntryCodeMinted = z.infer<typeof webEntryCodeMinted>;
+
+/** `DELETE /api/channels/web/gates/{identity}/codes/{code_id}` — the revoked code. */
+export const webEntryCodeRevoked = z.object({ status: z.literal('revoked') });
+export type WebEntryCodeRevoked = z.infer<typeof webEntryCodeRevoked>;

package/src/tool-runs.ts

@@ -14,8 +14,8 @@
  */
 import { z } from 'zod';
 
-import { apiRequest, encodeSegment } from './http';
 import type { ApiConfig } from './http';
+import { apiRequest, encodeSegment } from './http';
 
 /** A run's lifecycle state. `lost` = the server restarted mid-run; the result is
  * unrecoverable. `running` is the only non-terminal state. */