@tai42/api-client 20.0.0 → 22.0.0

package/src/schemas/interactions.ts

@@ -1,69 +1,41 @@
 /** Interaction question, answer and media response schemas. */
 import { z } from 'zod';
 
-import { pageWindow } from './shared';
+import * as openapi from '../generated/openapi-schemas';
+import * as served from '../generated/served-schemas';
 
 // 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 const answerFormat = openapi.answerFormat;
 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']);
+/** The kind of a display-only media item: an image, a link, or a document, video or audio file. */
+export const mediaKind = openapi.mediaKind;
 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.
+ * One item of a question's display-only media. The renderer resolves `url` (the image src
+ * scheme gate and the link neutralization are enforced there); `caption` and `filename`
+ * are `null` when absent.
  */
-export const interactionMediaItem = z.object({
-  kind: mediaKind,
-  url: z.string(),
-  caption: z.string().nullish(),
-});
+export const interactionMediaItem = openapi.mediaItem;
 export type InteractionMediaItem = z.infer<typeof interactionMediaItem>;
 
-/**
- * The kind of a byte-backed inbound attachment carried on a transcript record. A
- * fetchable file — `image`/`document`/`audio`/`video` — never a `link`: a labelled
- * anchor is question CONTEXT (see {@link mediaKind}), not a participant's sent file.
- */
-export const attachmentMediaKind = z.enum(['image', 'document', 'audio', 'video']);
+/** The kind of an inbound attachment carried on a transcript record. */
+export const attachmentMediaKind = openapi.mediaKind;
 export type AttachmentMediaKind = z.infer<typeof attachmentMediaKind>;
 
 /**
  * One inbound attachment a participant sent, projected onto a transcript record's
- * `inbound_attachments`. Applied PER ITEM by the renderer (the record's array is a
- * loose `z.array(z.unknown())`, `safeParse`d per member) so one malformed/hostile
- * item is a loud per-item notice, never a whole-record parse failure that would
- * vanish the transcript.
- *
- * `url` is the served-media reference the renderer resolves to the API origin (the
- * same served-url discipline the ask-media renderer uses); the image src scheme gate
- * and the per-item load-failure notice are enforced there. `caption` and `filename`
- * are `.nullish()` (absent OR explicit `null` both parse to absent): the projection
- * may omit the key OR emit `null`, so `.optional()` alone would false-fail an explicit
- * `null`. `filename` is meaningful only for a `document`; the renderer shows it as the
- * download label.
+ * `inbound_attachments`. `url` is the served-media reference the renderer resolves to the
+ * API origin (the same served-url discipline the ask-media renderer uses); the image src
+ * scheme gate and the per-item load-failure notice are enforced there. `filename` is
+ * meaningful only for a `document`; the renderer shows it as the download label.
  */
-export const attachmentMediaItem = z.object({
-  kind: attachmentMediaKind,
-  url: z.string(),
-  caption: z.string().nullish(),
-  filename: z.string().nullish(),
-});
+export const attachmentMediaItem = openapi.mediaItem;
 export type AttachmentMediaItem = z.infer<typeof attachmentMediaItem>;
 
 /**
@@ -73,10 +45,7 @@ export type AttachmentMediaItem = z.infer<typeof attachmentMediaItem>;
  * `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 const formOption = openapi.formOption;
 export type FormOption = z.infer<typeof formOption>;
 
 /**
@@ -85,14 +54,11 @@ export type FormOption = z.infer<typeof formOption>;
  * 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 const formData = openapi.formData;
 export type FormData = z.infer<typeof formData>;
 
 /** The kind of an ordered display block a page may carry alongside its input fields. */
-export const displayBlockKind = z.enum(['heading', 'body', 'image']);
+export const displayBlockKind = openapi.displayBlock.shape.kind;
 export type DisplayBlockKind = z.infer<typeof displayBlockKind>;
 
 /**
@@ -106,17 +72,11 @@ export type DisplayBlockKind = z.infer<typeof displayBlockKind>;
  * whole-page parse failure. Applied per block by the preview (safeParsed via its page),
  * so a malformed block is a loud notice, never silent.
  */
-export const displayBlock = z.object({
-  kind: displayBlockKind,
-  text: z.string().nullish(),
-  src: z.string().nullish(),
-  alt: z.string().nullish(),
-  slot: z.string().nullish(),
-});
+export const displayBlock = openapi.displayBlock;
 export type DisplayBlock = z.infer<typeof displayBlock>;
 
 /** A page's role: an ordinary `input` page (default) or a terminal `review` summary. */
-export const formPageKind = z.enum(['input', 'review']);
+export const formPageKind = openapi.formPage.shape.kind.unwrap();
 export type FormPageKind = z.infer<typeof formPageKind>;
 
 /**
@@ -128,14 +88,14 @@ export type FormPageKind = z.infer<typeof formPageKind>;
  * instead of, for a review page) its input fields; it defaults to empty, so a page that
  * carries none renders exactly as before. `kind` marks a `review` page — a terminal
  * summary step that shows the readback of entered values and the confirm/submit footer
- * and carries no new input fields; it defaults to `input`. Both are additive: an older
+ * and carries no new input fields; it defaults to `input`. `button_label` is the text of
+ * the page's primary button — the one that advances from an input page, or submits from
+ * the last — in the sender's words and the end-user's language; absent (`null`), the
+ * surface shows its own generic word ("Next"/"Submit"/"Confirm"). All additive: an older
  * payload ({title, fields}) parses unchanged.
  */
-export const formPage = z.object({
-  title: z.string(),
-  fields: z.array(z.string()),
-  display: z.array(displayBlock).default([]),
-  kind: formPageKind.default('input'),
+export const formPage = openapi.formPage.extend({
+  button_label: z.string().nullable().default(null),
 });
 export type FormPage = z.infer<typeof formPage>;
 
@@ -143,6 +103,183 @@ export type FormPage = z.infer<typeof formPage>;
 export const formPages = z.array(formPage);
 export type FormPages = z.infer<typeof formPages>;
 
+// The one catalogue of a send's platform-drawn texts (`format_payload.wording`): a
+// question's or a notification's buttons, headings, input hints, message lines,
+// answer-page sentences, refusal sentences, settled-card badges and screen-reader labels,
+// grouped into six chapters. Every leaf is the sender's own words in the end-user's
+// language; absent (or `null`), the surface shows its own generic word. Mirrors the
+// skeleton's `Wording` model member-for-member. A renderer safeParses this off the loose
+// `format_payload`, so a malformed shape falls back to the default words rather than
+// crashing the card (the labels are chrome, never an answer). The Studio inbox draws only
+// the subset of members it has a control for; the rest parse and are ignored.
+
+/**
+ * One form field's platform-drawn words (`wording.form.fields[name]`): `choice_label` is
+ * the placeholder of the field's picker (its empty-state prompt).
+ */
+export const fieldWording = z.object({
+  choice_label: z.string().nullish(),
+});
+export type FieldWording = z.infer<typeof fieldWording>;
+
+/**
+ * A form's platform-drawn chrome (`wording.form`): `title` heads the form surface;
+ * `open`/`cancel` label the buttons that open and close it; `back` the button that returns
+ * to the previous step; `submit` the terminal button of a form with no pages;
+ * `review_empty` the review step's line before anything is filled; `fields` carries
+ * per-field words keyed by property name. The inbox draws the form inline, so it reads
+ * `back`, `submit` and `fields`; `title`/`open`/`cancel`/`review_empty` parse unused.
+ */
+export const formWording = z.object({
+  title: z.string().nullish(),
+  open: z.string().nullish(),
+  cancel: z.string().nullish(),
+  back: z.string().nullish(),
+  submit: z.string().nullish(),
+  review_empty: z.string().nullish(),
+  fields: z.record(z.string(), fieldWording).nullish(),
+});
+export type FormWording = z.infer<typeof formWording>;
+
+/**
+ * A choice list's platform-drawn words (`wording.choice`): `label` is the word on the
+ * control that presents the list, `reply_hint` the line under a numbered-text list, and
+ * `group_label` the accessible name of a flat group of option buttons. The inbox reads
+ * `label` (the select field's label and picker placeholder); the rest parse unused.
+ */
+export const choiceWording = z.object({
+  label: z.string().nullish(),
+  reply_hint: z.string().nullish(),
+  group_label: z.string().nullish(),
+});
+export type ChoiceWording = z.infer<typeof choiceWording>;
+
+/**
+ * A non-form question's answer controls and refusal sentences (`wording.answer`): `open`
+ * labels the control that opens a `confirm`/`external` question's answer page, `confirm`
+ * its affirmative control, `decline` its negative control, `submit` the button that sends a
+ * typed or picked answer, `reply_hint` the hint in an empty reply input. `rejected` /
+ * `rejected_final` are the sentences the end user reads when an answer is refused; the
+ * inbox draws neither (web-only). The inbox reads `open`, `confirm`, `decline`, `submit`
+ * and `reply_hint` where it draws the matching control.
+ */
+export const answerWording = z.object({
+  open: z.string().nullish(),
+  confirm: z.string().nullish(),
+  decline: z.string().nullish(),
+  submit: z.string().nullish(),
+  reply_hint: z.string().nullish(),
+  rejected: z.string().nullish(),
+  rejected_final: z.string().nullish(),
+});
+export type AnswerWording = z.infer<typeof answerWording>;
+
+/**
+ * The lines of a delivery message (`wording.lines`): `answer_link` carries the tappable
+ * answer link, `deadline` names the deadline, `reply` tells the end user how to reply, and
+ * `options` lists the choices. Drawn by the chat channels; the inbox draws none of them.
+ */
+export const lineWording = z.object({
+  answer_link: z.string().nullish(),
+  deadline: z.string().nullish(),
+  reply: z.string().nullish(),
+  options: z.string().nullish(),
+});
+export type LineWording = z.infer<typeof lineWording>;
+
+/** The heading and sentence of one platform-drawn answer page (`wording.answer_page.*`). */
+export const pageCopy = z.object({
+  heading: z.string().nullish(),
+  text: z.string().nullish(),
+});
+export type PageCopy = z.infer<typeof pageCopy>;
+
+/**
+ * The form page's own sentences (`wording.answer_page.form`): `failed` when a send did not
+ * land, `network_error` when the browser could not reach the server, `update_failed` when a
+ * reacting form could not refresh, `choose_one` for an empty required multi-choice, and
+ * `date_unavailable` for a blocked date. Drawn by the callback form page; the inbox draws
+ * none of them.
+ */
+export const formPageWording = z.object({
+  failed: z.string().nullish(),
+  network_error: z.string().nullish(),
+  update_failed: z.string().nullish(),
+  choose_one: z.string().nullish(),
+  date_unavailable: z.string().nullish(),
+});
+export type FormPageWording = z.infer<typeof formPageWording>;
+
+/**
+ * The pages a question's link opens (`wording.answer_page`): `confirm` the confirm page's
+ * copy, `done` the already-answered page's, `awaiting` the reply-on-the-channel page's,
+ * `submitted` the form page's post-submit copy, and `form` the form page's own
+ * validation/error sentences. Drawn by the callback pages; the inbox draws none of them.
+ */
+export const answerPageWording = z.object({
+  confirm: pageCopy.nullish(),
+  done: pageCopy.nullish(),
+  awaiting: pageCopy.nullish(),
+  submitted: pageCopy.nullish(),
+  form: formPageWording.nullish(),
+});
+export type AnswerPageWording = z.infer<typeof answerPageWording>;
+
+/**
+ * A live question card's countdown words (`wording.status.countdown`): `seconds_left` the
+ * visible plural line, `one_second_left` the visible singular, and `under_minute` /
+ * `under_half_minute` / `under_ten_seconds` the spoken lines at the three thresholds. Drawn
+ * by the web widget; the inbox draws no countdown.
+ */
+export const countdownWording = z.object({
+  seconds_left: z.string().nullish(),
+  one_second_left: z.string().nullish(),
+  under_minute: z.string().nullish(),
+  under_half_minute: z.string().nullish(),
+  under_ten_seconds: z.string().nullish(),
+});
+export type CountdownWording = z.infer<typeof countdownWording>;
+
+/**
+ * In-flight and settled status copy (`wording.status`): `sending` the screen-reader label
+ * while a send is in flight, `answered` / `expired` / `closed` the badges once a question
+ * settles, `sent` the badge after an ask-less form is submitted, `unavailable` the line
+ * when a form's door no longer resolves, and `countdown` the live-countdown words. Drawn by
+ * the web widget; the inbox draws none of them.
+ */
+export const statusWording = z.object({
+  sending: z.string().nullish(),
+  answered: z.string().nullish(),
+  expired: z.string().nullish(),
+  closed: z.string().nullish(),
+  sent: z.string().nullish(),
+  unavailable: z.string().nullish(),
+  countdown: countdownWording.nullish(),
+});
+export type StatusWording = z.infer<typeof statusWording>;
+
+/**
+ * The one catalogue of a send's platform-drawn texts (`format_payload.wording`), grouped
+ * by what each word decorates: the form (`form`), the choice list (`choice`), a question's
+ * answer controls and refusal sentences (`answer`), the lines of the delivery message
+ * (`lines`), the pages a question's link opens (`answer_page`), and in-flight and settled
+ * status (`status`). A page's primary button is the one text not here — it is on the page
+ * (`pages[].button_label`). Every leaf is the sender's own words in the end-user's
+ * language; absent (or `null`), the surface shows its own word.
+ */
+export const wording = z.object({
+  form: formWording.nullish(),
+  choice: choiceWording.nullish(),
+  answer: answerWording.nullish(),
+  lines: lineWording.nullish(),
+  answer_page: answerPageWording.nullish(),
+  status: statusWording.nullish(),
+});
+export type Wording = z.infer<typeof wording>;
+
+// The form reactions and the form update are hand-written: the spec carries them inside an
+// open `format_payload` and an open reaction `update`.
+
 /**
  * When a `form` reacts while it is open (`format_payload.reactions`): the plain,
  * renderer-readable description of WHEN the form calls its reaction handler. Absent ⇒ a
@@ -163,12 +300,12 @@ export const formReactions = z.object({
 export type FormReactions = z.infer<typeof formReactions>;
 
 /**
- * The form update a reaction door returns (`POST /api/interactions/{id}/react`): the
- * same kind of data a form is sent with, applied to the open form. `values` sets field
- * values; `options` replaces the per-send choice list of option-bearing fields; `errors`
- * shows per-field messages (keyed by field name); `display` fills display slots (keyed by
- * slot name) — a computed total among them. Every member defaults to empty, so a reaction
- * that touches only one of them returns only that one. The door response is safeParsed, so
+ * The form update a reaction door returns (`POST /api/interactions/{id}/react`, its
+ * `update`): the same kind of data a form is sent with, applied to the open form. `values`
+ * sets field values; `options` replaces the per-send choice list of option-bearing fields;
+ * `errors` shows per-field messages (keyed by field name); `display` fills display slots
+ * (keyed by slot name) — a computed total among them. Every member defaults to empty, so a
+ * reaction that touches only one of them returns only that one. The door response is safeParsed, so
  * a malformed update surfaces loudly rather than applying a half-understood change.
  */
 export const formUpdate = z.object({
@@ -180,68 +317,33 @@ export const formUpdate = z.object({
 export type FormUpdate = z.infer<typeof formUpdate>;
 
 /**
- * The event a reaction round-trip reports to the door: `kind` is which of the three
- * declared events fired, `field` names the changed field for a `field_changed` event, and
- * `page` names the advanced-from page (by title) for a `page_advanced` event. A
- * `submitted` event carries neither. The body also carries the partial `values` filled so
- * far (see {@link interactionsClient}'s `reactInteraction`).
+ * The event a reaction round-trip reports to the door (the contract's `FormReactionEvent`
+ * document): `kind` is which of the three declared events fired, `field` names the changed
+ * field for a `field_changed` event, and `page` names the advanced-from page (by title) for a
+ * `page_advanced` event. A `submitted` event carries neither. The body also carries the
+ * partial `values` filled so far (see {@link interactionsClient}'s `reactInteraction`).
  */
-export const reactionEventKind = z.enum(['field_changed', 'page_advanced', 'submitted']);
-export type ReactionEventKind = z.infer<typeof reactionEventKind>;
-
-export const reactionEvent = z.object({
-  kind: reactionEventKind,
-  field: z.string().optional(),
-  page: z.string().optional(),
-});
+export const reactionEvent = served.formReactionEvent;
 export type ReactionEvent = z.infer<typeof reactionEvent>;
+export type ReactionEventKind = ReactionEvent['kind'];
 
-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
+/** The reaction door's reply: the interaction id and the form `update` to apply. */
+export const interactionReaction = openapi.interactionReactionResult.extend({ update: formUpdate });
+export type InteractionReaction = z.infer<typeof interactionReaction>;
+
+export const interaction = openapi.interactionFrame.extend({
+  // Hand-written: the format-specific payload (select options, form JSON schema with
+  // optional per-send `data` and `pages`, external url) is `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 const interactionAnswered = openapi.interactionActionResult;
 export type InteractionAnswered = z.infer<typeof interactionAnswered>;
 
 /**
@@ -250,10 +352,7 @@ export type InteractionAnswered = z.infer<typeof interactionAnswered>;
  * 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 const interactionCancelled = openapi.interactionActionResult;
 export type InteractionCancelled = z.infer<typeof interactionCancelled>;
 
 /**
@@ -261,8 +360,5 @@ export type InteractionCancelled = z.infer<typeof interactionCancelled>;
  * 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 const interactionsPage = openapi.interactionWindow.extend({ items: z.array(interaction) });
 export type InteractionsPage = z.infer<typeof interactionsPage>;

package/src/schemas/login.ts

@@ -1,67 +1,36 @@
 /** Public login-method aggregator and login-result schemas. */
-import { z } from 'zod';
+import type { z } from 'zod';
+
+import * as openapi from '../generated/openapi-schemas';
 
 /**
  * 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(),
-});
+export const loginFormField = openapi.formField;
 
 /**
  * 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', '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),
-  }),
-]);
+export const loginMethod = openapi.loginMethodsListing.shape.methods.element;
 
 /**
  * `GET /api/login/methods` (PUBLIC). `needs_setup: true` ⇒ no principal exists
  * yet, so the deployment must be initialized through the setup door before anyone
  * can sign in. `setup_login` names the login-credential kinds the setup door can
- * attach the owner's login with; it is `null`/absent when no login-attaching
- * accounts provider is configured (a keys-only deployment). Non-strict — the
- * skeleton may grow additive fields.
+ * attach the owner's login with; it is `null` when no login-attaching accounts
+ * provider is configured (a keys-only deployment). `claim_fragment_key` names the
+ * URL-fragment key a claim link carries its token under.
  */
-export const loginMethods = z.object({
-  methods: z.array(loginMethod),
-  needs_setup: z.boolean(),
-  setup_login: z
-    .object({ kinds: z.array(z.enum(['password', 'invite'])) })
-    .nullable()
-    .optional(),
-});
+export const loginMethods = openapi.loginMethodsListing;
 
 /**
  * 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 const loginResult = openapi.claimExchangeResult;
 
 export type LoginFormField = z.infer<typeof loginFormField>;
 export type LoginMethod = z.infer<typeof loginMethod>;

package/src/schemas/manifest-mcp.ts

@@ -1,6 +1,7 @@
 /** Live-manifest MCP section, env-ref and config-reload schemas. */
 import { z } from 'zod';
 
+import * as openapi from '../generated/openapi-schemas';
 import { fleetReportFanout } from './fleet';
 
 /**
@@ -16,7 +17,8 @@ export const connectorRef = z.object({
 export type ConnectorRef = z.infer<typeof connectorRef>;
 
 /**
- * One entry of the live manifest's MCP section. Only the `managed` provenance
+ * One entry of the live manifest's MCP section, hand-typed: the spec publishes an entry as
+ * an open object. 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`
@@ -31,9 +33,8 @@ export const manifestMcpEntry = z
   .loose();
 export type ManifestMcpEntry = z.infer<typeof manifestMcpEntry>;
 
-export const manifestView = z.object({
+export const manifestView = openapi.preservedManifestView.extend({
   mcp: z.array(manifestMcpEntry),
-  user_tools: z.array(z.string()),
 });
 
 /**
@@ -45,26 +46,19 @@ export const manifestView = z.object({
  * 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 const mcpEnvRef = openapi.mcpEnvRef;
 export type McpEnvRef = z.infer<typeof mcpEnvRef>;
-export const mcpEnvRefs = z.array(mcpEnvRef);
+export const mcpEnvRefs = openapi.mcpEnvRefList;
 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`.
+ * `env_keys`), the mode-wrapped fleet fan-out of the reload it broadcast, `recycle` — the
+ * fleet recycle roll an env change carrying a recycle-class key ran (`null` when it carried
+ * none) — and `awaiting_respawn`, the workers (name + keys) still awaiting a respawn after
+ * it, empty when its roll converged. The `fanout` is hand-typed (the spec publishes it as
+ * one object with optional fields) so the shared fleet-report handler can surface a failed
+ * propagation. A drift throws `ApiSchemaError`.
  */
-export const reloadConfigResult = z.object({
-  status: z.string(),
-  env_keys: z.number(),
-  fanout: fleetReportFanout,
-});
+export const reloadConfigResult = openapi.applyResponse.extend({ fanout: fleetReportFanout });
 export type ReloadConfigResult = z.infer<typeof reloadConfigResult>;