@tai42/api-client 19.3.0 → 21.0.0

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

package/src/schemas/marketplace.ts

@@ -1,13 +1,19 @@
 /** Marketplace listing, version, install and advisory schemas. */
 import { z } from 'zod';
 
+import * as openapi from '../generated/openapi-schemas';
+
+// The registry's listing, search, version, detail and advisory shapes are hand-written: the
+// skeleton passes the upstream registry's bodies through as opaque values. The installed,
+// upgrade, install, preview and uninstall shapes are the skeleton's own.
+
 /**
  * The CLOSED HTTP-method enum fixed by the contract's RouteMethod, the one source
  * for every route-method field (declaration and install/preview responses alike):
  * a wire method the contract does not define fails loudly as drift rather than
  * passing through silently.
  */
-export const routeMethod = z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+export const routeMethod = openapi.mountedRoute.shape.methods.element;
 export type RouteMethod = z.infer<typeof routeMethod>;
 
 /**
@@ -16,7 +22,7 @@ export type RouteMethod = z.infer<typeof routeMethod>;
  * installs nothing but the manifest entry. A CLOSED enum, so a wire value the
  * server does not derive fails loudly as drift.
  */
-export const marketplaceDelivery = z.enum(['package', 'descriptor']);
+export const marketplaceDelivery = openapi.installedRow.shape.delivery;
 export type MarketplaceDelivery = z.infer<typeof marketplaceDelivery>;
 
 /**
@@ -32,7 +38,7 @@ export type MarketplaceSource = z.infer<typeof marketplaceSource>;
  * a `secret` (an OAuth client secret is; a client id or a plain marker var is not).
  * The install dialog seeds each toggle from `secret` and collects the missing ones.
  */
-export const marketplaceRequiredEnvVar = z.object({ name: z.string(), secret: z.boolean() });
+export const marketplaceRequiredEnvVar = openapi.requiredEnvVar;
 export type MarketplaceRequiredEnvVar = z.infer<typeof marketplaceRequiredEnvVar>;
 
 /**
@@ -230,16 +236,9 @@ export type MarketplacePluginDetail = z.infer<typeof marketplacePluginDetail>;
  * One installed plugin's compat verdict against the RUNNING tai42-contract:
  * `compatible` / `incompatible` per its declared contract range, `unknown` when
  * no verdict could be computed. `reason` is the human-readable explanation of a
- * non-`compatible` verdict, `null` when compatible. CLOSED (`.strict()`): the
- * server is built against exactly this shape, so an unknown key is drift and
- * throws instead of being stripped.
+ * non-`compatible` verdict, `null` when compatible.
  */
-export const marketplaceInstalledCompat = z
-  .object({
-    status: z.enum(['compatible', 'incompatible', 'unknown']),
-    reason: z.string().nullable(),
-  })
-  .strict();
+export const marketplaceInstalledCompat = openapi.compatStatus;
 export type MarketplaceInstalledCompat = z.infer<typeof marketplaceInstalledCompat>;
 
 /**
@@ -249,92 +248,51 @@ export type MarketplaceInstalledCompat = z.infer<typeof marketplaceInstalledComp
  * `incompatible_newer` names the newest version blocked by the running
  * contract (`null` when none), so "an update exists but needs a newer core" is
  * visible. `missing_upstream` flags a plugin the registry no longer lists.
- * `compat` is the row's verdict against the running contract. CLOSED, like
- * every shape of the installed listing.
+ * `compat` is the row's verdict against the running contract. `delivery` is `package`
+ * for a pip-installed plugin, `descriptor` for a descriptor-only plugin whose stored spec
+ * names no package. `items` is the `{kind, name}` of every item this plugin's stored spec
+ * provides (local truth); `route_mounts` is the persisted `{item_name: base}` mount this
+ * plugin is installed at (`{}` means every item at its declared base).
  */
-export const marketplaceInstalledPlugin = z
-  .object({
-    ref: z.string(),
-    version: z.string(),
-    source: z.string(),
-    // How the row was delivered: `package` for a pip-installed plugin, `descriptor`
-    // for a descriptor-only plugin whose stored spec names no package.
-    delivery: marketplaceDelivery,
-    installed_at: z.string(),
-    latest: z.string().nullable(),
-    update_available: z.boolean(),
-    incompatible_newer: z.string().nullable(),
-    missing_upstream: z.boolean(),
-    compat: marketplaceInstalledCompat,
-    // The `{kind, name}` of every item this plugin's stored spec provides
-    // (local truth). The connectors page's McpServersSection joins the mcp-server
-    // item names against the manifest's mcp-entry titles to render an
-    // installer-written entry read-only.
-    items: z.array(marketplaceItem.pick({ kind: true, name: true })),
-    // The persisted `{item_name: base}` mount this plugin is installed at (local
-    // truth; `{}` means every item at its declared base). Studio seeds the update
-    // flow and renders routes at the ACTUAL mounted base from this.
-    route_mounts: z.record(z.string(), z.string()),
-  })
-  .strict();
+export const marketplaceInstalledPlugin = openapi.installedRow;
 export type MarketplaceInstalledPlugin = z.infer<typeof marketplaceInstalledPlugin>;
 
 /**
  * The installed inventory (`GET /api/marketplace/installed`): the attributed
- * rows, each with its per-row compat verdict and update picture. CLOSED.
+ * rows, each with its per-row compat verdict and update picture.
  */
-export const marketplaceInstalled = z
-  .object({
-    installed: z.array(marketplaceInstalledPlugin),
-  })
-  .strict();
+export const marketplaceInstalled = openapi.installedInventory;
 export type MarketplaceInstalled = z.infer<typeof marketplaceInstalled>;
 
 /**
  * One per-plugin outcome of `POST /api/marketplace/upgrade-all`: `upgraded`,
  * already `up-to-date`, `no-compatible-version` in the registry, or `failed`;
- * `detail` always carries the human-readable specifics. CLOSED.
+ * `detail` always carries the human-readable specifics.
  */
-export const marketplaceUpgradeAllRow = z
-  .object({
-    ref: z.string(),
-    outcome: z.enum(['upgraded', 'up-to-date', 'no-compatible-version', 'failed']),
-    detail: z.string(),
-  })
-  .strict();
+export const marketplaceUpgradeAllRow = openapi.upgradeRow;
 export type MarketplaceUpgradeAllRow = z.infer<typeof marketplaceUpgradeAllRow>;
 
-/** The whole upgrade-all readout: one outcome row per installed plugin. CLOSED. */
-export const marketplaceUpgradeAllResult = z
-  .object({
-    results: z.array(marketplaceUpgradeAllRow),
-  })
-  .strict();
+/** The whole upgrade-all readout: one outcome row per installed plugin. */
+export const marketplaceUpgradeAllResult = openapi.upgradeAllResult;
 export type MarketplaceUpgradeAllResult = z.infer<typeof marketplaceUpgradeAllResult>;
 
 /** The advisory state for installed plugins, with when it was last fetched. */
-export const marketplaceAdvisories = z.object({
+export const marketplaceAdvisories = openapi.advisorySnapshot.extend({
   advisories: z.array(marketplaceAdvisory),
-  fetched_at: z.string(),
 });
 
 /** The registry's controlled category list, proxied through the skeleton. */
-export const marketplaceCategories = z.array(z.string());
+export const marketplaceCategories = openapi.stringList;
 
 /** The registry's controlled item-kind list, proxied through the skeleton. */
-export const marketplaceKinds = z.array(z.string());
+export const marketplaceKinds = openapi.stringList;
 
 /**
  * One route the install / update actually mounted: the item that owns it, the
  * absolute `full_path` it now answers, the `methods`, and whether it is served
  * `public`. The receipt lists these so the operator sees what was opened where.
  */
-export const marketplaceMountedRoute = z.object({
-  item: z.string(),
-  full_path: z.string(),
-  methods: z.array(routeMethod),
-  public: z.boolean(),
-});
+export const marketplaceMountedRoute = openapi.mountedRoute;
 export type MarketplaceMountedRoute = z.infer<typeof marketplaceMountedRoute>;
 
 /**
@@ -342,60 +300,34 @@ export type MarketplaceMountedRoute = z.infer<typeof marketplaceMountedRoute>;
  * `notes` (env-selected items naming their activating env var) and any
  * non-critical `advisories` ride BOTH the install and update receipts.
  * `routes` is the mounted-route list — empty for a plugin that registers none.
- * The wire also carries `package`, `reload`, and `pip_output`, which the receipt
- * does not model — zod's default strip drops them; the UI renders the receipt,
- * not the raw install log.
+ * `package`, `reload` and `pip_output` carry the installed package, the config reload
+ * and the raw install log.
  */
-export const marketplaceInstallResult = z.object({
-  ref: z.string(),
-  version: z.string(),
-  notes: z.array(z.string()),
+export const marketplaceInstallResult = openapi.installResult.extend({
   advisories: z.array(marketplaceAdvisory),
-  routes: z.array(marketplaceMountedRoute),
 });
 export type MarketplaceInstallResult = z.infer<typeof marketplaceInstallResult>;
 
 /** One resolved route in an install preview: the declared `path`, its resolved
  * absolute `full_path`, the `methods`, and whether it is `public`. */
-export const marketplacePreviewRoute = z.object({
-  path: z.string(),
-  full_path: z.string(),
-  methods: z.array(routeMethod),
-  public: z.boolean(),
-});
+export const marketplacePreviewRoute = openapi.previewItemRoute;
 export type MarketplacePreviewRoute = z.infer<typeof marketplacePreviewRoute>;
 
 /** One route-carrying item in an install preview: its resolved `base` (the
  * override or the default), the `default_base` it declares, and the routes that
  * mount under it. */
-export const marketplacePreviewItem = z.object({
-  item: z.string(),
-  kind: z.string(),
-  base: z.string(),
-  default_base: z.string(),
-  routes: z.array(marketplacePreviewRoute),
-});
+export const marketplacePreviewItem = openapi.previewItem;
 export type MarketplacePreviewItem = z.infer<typeof marketplacePreviewItem>;
 
 /** One collision the preview found: a route whose resolved shape+method clashes
  * with an already-owned route. `conflict_owner` is `core` or `plugin:<ref>`; the
  * remedy is to remap the item's base. */
-export const marketplacePreviewCollision = z.object({
-  item: z.string(),
-  full_path: z.string(),
-  methods: z.array(routeMethod),
-  conflict_owner: z.string(),
-  conflict_path: z.string(),
-});
+export const marketplacePreviewCollision = openapi.routeCollision;
 export type MarketplacePreviewCollision = z.infer<typeof marketplacePreviewCollision>;
 
 /** One public route the operator is asked to accept: served WITHOUT
  * authentication once installed. */
-export const marketplacePreviewPublicRoute = z.object({
-  item: z.string(),
-  full_path: z.string(),
-  methods: z.array(routeMethod),
-});
+export const marketplacePreviewPublicRoute = openapi.publicRouteRow;
 export type MarketplacePreviewPublicRoute = z.infer<typeof marketplacePreviewPublicRoute>;
 
 /**
@@ -410,28 +342,13 @@ export type MarketplacePreviewPublicRoute = z.infer<typeof marketplacePreviewPub
  * process env (server-computed — the ONE authority the dialog collects), and
  * `delivery` is the one word the surface shows (`package` / `descriptor`).
  */
-export const marketplaceInstallPreview = z.object({
-  ref: z.string(),
-  version: z.string(),
-  items: z.array(marketplacePreviewItem),
-  collisions: z.array(marketplacePreviewCollision),
-  public_routes: z.array(marketplacePreviewPublicRoute),
-  new_public_routes: z.array(marketplacePreviewPublicRoute),
-  requires_public_acceptance: z.boolean(),
-  required_env: z.array(marketplaceRequiredEnvVar),
-  missing_env: z.array(z.string()),
-  delivery: marketplaceDelivery,
-});
+export const marketplaceInstallPreview = openapi.installPreview;
 export type MarketplaceInstallPreview = z.infer<typeof marketplaceInstallPreview>;
 
 /**
  * The receipt of an uninstall. `notes` carries operator warnings (e.g. a config
  * provider still selected by its env var); render them like the install
- * receipt's notes.
+ * receipt's notes. `reload` is `null` when the plugin wrote no manifest entry to remove.
  */
-export const marketplaceUninstallResult = z.object({
-  ref: z.string(),
-  uninstalled: z.literal(true),
-  notes: z.array(z.string()),
-});
+export const marketplaceUninstallResult = openapi.uninstallResult;
 export type MarketplaceUninstallResult = z.infer<typeof marketplaceUninstallResult>;

package/src/schemas/members.ts

@@ -0,0 +1,91 @@
+/** Member, invite, directory and member-action schemas for the generic Members view. */
+import type { z } from 'zod';
+
+import * as openapi from '../generated/openapi-schemas';
+
+/**
+ * Where a declared member action renders: a page-level button, a member-row menu
+ * item, or an invite-row menu item. A provider classifies each of its own actions
+ * into one of these three places; Studio only joins by `scope`, never reads the
+ * provider's meaning behind it.
+ */
+export const memberActionScope = openapi.memberActionDescriptor.shape.scope;
+export type MemberActionScope = z.infer<typeof memberActionScope>;
+
+/**
+ * One platform principal a member holds (`GET /api/auth/members` →
+ * `members[].principals[]`). `user_id` is the platform principal id; `disabled` is
+ * taken from that principal's own record (the store the principals listing reads) and
+ * `role` is the role it holds, joined from its own policy record — both never from a
+ * provider. `role` is `null` when the principal's policy was not written from a role
+ * template.
+ */
+export const memberPrincipalState = openapi.memberPrincipalState;
+export type MemberPrincipalState = z.infer<typeof memberPrincipalState>;
+
+/**
+ * One person an accounts provider owns, as the directory door returns them
+ * (`GET /api/auth/members` → `members[]`). `id` is the provider's stable handle for
+ * the person (a list key, not shown). `email` is the sign-in identity; `role` is the
+ * one role name every principal holds (the NAME only — the role definition is read
+ * from the role listing), or `null` when there is no single name: every principal's
+ * access was set directly, or the principals hold different roles
+ * (`principals[].role` carries each one's own). `principals` carries each principal's
+ * platform-joined state; `disabled` is derived True only when EVERY principal is disabled, so a
+ * person with any enabled principal still reads active while the per-principal truth
+ * stays visible. `handle` routes an invoke back to the producing provider and pins
+ * this row; `action_keys` are the opaque catalog keys of the actions applicable to
+ * it — Studio joins and echoes both, never parses them. `created_at` is an ISO-8601
+ * instant.
+ */
+export const memberRow = openapi.memberRow;
+export type MemberRow = z.infer<typeof memberRow>;
+
+/**
+ * One outstanding invitation an accounts provider holds, as the directory door
+ * returns them (`GET /api/auth/members` → `invites[]`). `id` is the provider's
+ * stable handle for the invited person; `email` is the invited address; `role` names
+ * the platform role they will hold (name only, or `null` when not from a role template). An
+ * invitation holds no principal, so it carries no principal state. `handle` and
+ * `action_keys` are the opaque routing tokens (see {@link memberRow}). `created_at`
+ * and `expires_at` are ISO-8601 instants.
+ */
+export const inviteRow = openapi.inviteRow;
+export type InviteRow = z.infer<typeof inviteRow>;
+
+/**
+ * The deployment-wide membership (`GET /api/auth/members`): every accounts
+ * provider's people and outstanding invitations, aggregated and platform-joined by
+ * the backend into one view so a generic Members screen renders without naming any
+ * provider.
+ */
+export const memberDirectory = openapi.memberDirectory;
+export type MemberDirectory = z.infer<typeof memberDirectory>;
+
+/**
+ * One declared member action, serialized for the catalog (`GET
+ * /api/auth/member-actions` → `actions[]`). `key` is the opaque catalog key a caller
+ * joins and echoes, never parses. `label` is the resolved wording. `scope` places
+ * the action; `destructive` asks for a confirm before invoking. `input_schema` and
+ * `result_schema` are the declared models' JSON Schema — a caller renders an input
+ * form and a read-only result view from them generically, with no provider field
+ * name known to Studio.
+ */
+export const memberActionDescriptor = openapi.memberActionDescriptor;
+export type MemberActionDescriptor = z.infer<typeof memberActionDescriptor>;
+
+/**
+ * Every declared member action across the registered accounts providers (`GET
+ * /api/auth/member-actions`). ADMIN-ONLY (`secret`) — a non-admin projection never
+ * reaches the route, exactly as the members listing.
+ */
+export const memberActionCatalog = openapi.memberActionCatalog;
+export type MemberActionCatalog = z.infer<typeof memberActionCatalog>;
+
+/**
+ * The invoke-door result (`POST /api/auth/member-actions/invoke`): the provider's
+ * result-model dump, carried opaquely. `result` is rendered through the action's
+ * `result_schema`; Studio reads no field of it by name.
+ */
+export const invokeMemberActionResult = openapi.invokeMemberActionResult;
+export type InvokeMemberActionResult = z.infer<typeof invokeMemberActionResult>;

package/src/schemas/notifications.ts

@@ -1,43 +1,19 @@
 /** Notification-sink record response schemas. */
-import { z } from 'zod';
+import type { z } from 'zod';
 
-import { channelTemplate } from './served';
+import * as openapi from '../generated/openapi-schemas';
 
 // The internal notifications sink: the messages the `notify_user` operation records
 // with no channel, so they land only in the Studio inbox. Each record carries the
-// server-minted id + timestamp; `recipient` is null when the message names none.
-// The sink also stores the richer-send forms a notify carried — `media`
-// (images/links shown WITH the message), `template` (a pre-approved out-of-window
-// send), `options` (tappable option labels) — plus the `audience` identity the
-// record is addressed to; the inbox renders them.
+// server-minted id + timestamp; `recipient` is the channel DELIVERY address the message
+// went to (null when the send named none) and `audience` the IDENTITY (a user_id) whose
+// in-app inbox the record is addressed to. The sink also stores the richer-send forms a
+// notify carried — `media` (images/links shown WITH the message), `template` (a
+// pre-approved out-of-window send), `options`/`sections` (tappable options), `header`,
+// `footer`, `location` and `schema` — and the inbox renders them.
 
-export const notification = z.object({
-  id: z.string(),
-  message: z.string(),
-  // A channel DELIVERY address the message went to; null when the send named none.
-  recipient: z.string().nullable(),
-  // The IDENTITY (a user_id) whose in-app inbox the record is addressed to, distinct
-  // from `recipient`. `.nullish()` accepts both an older record that predates the
-  // field (key omitted) and a broadcast send (explicit null) — both parse to "none".
-  audience: z.string().nullish(),
-  // Display-only media stored WITH the message (images and/or links). Deliberately
-  // LOOSE (`z.array(z.unknown())`), like the interactions frame: each item is
-  // `safeParse`d per item by the renderer against `interactionMediaItem`, so one
-  // malformed/hostile item is a loud per-item notice, never a whole-feed parse
-  // failure that would silently vanish every other notification. `.nullish()` covers
-  // an older record (key omitted) and a plain send (explicit null).
-  media: z.array(z.unknown()).nullish(),
-  // A pre-approved template the notify carried, parsed strictly: a drifting one is a
-  // loud feed-level `ApiSchemaError`, consistent with the record contract.
-  template: channelTemplate.nullish(),
-  // Tappable option labels the notify offered; display-only in the operator inbox
-  // (there is no conversation for the sink to enter). Strictly a string list.
-  options: z.array(z.string()).nullish(),
-  created_at: z.string(),
-});
+export const notification = openapi.notificationRecord;
 export type Notification = z.infer<typeof notification>;
 
-export const notifications = z.object({
-  notifications: z.array(notification),
-});
+export const notifications = openapi.notificationListing;
 export type Notifications = z.infer<typeof notifications>;

package/src/schemas/observability.ts

@@ -1,90 +1,45 @@
 /** Run metrics, listing, span and trace response schemas. */
-import { z } from 'zod';
+import type { z } from 'zod';
 
-import { jsonValue } from './shared';
+import * as openapi from '../generated/openapi-schemas';
 
-export const dashboardMetrics = z.object({
-  summary: z.object({
-    totalRuns: z.number(),
-    totalCost: z.number(),
-    totalTokens: z.number(),
-    averageLatencyMs: z.number(),
-    avgCostPerRun: z.number(),
-    avgTokensPerRun: z.number(),
-    timeToFirstTokenMs: z.number().nullable(),
-  }),
-  timeSeries: z.array(
-    z.object({
-      bucket: z.string().nullable(),
-      runs: z.number(),
-      cost: z.number(),
-      avgLatencyMs: z.number(),
-      totalTokens: z.number(),
-    }),
-  ),
-  byModel: z.array(
-    z.object({
-      model: z.string(),
-      calls: z.number(),
-      cost: z.number(),
-      totalTokens: z.number(),
-      avgLatencyMs: z.number(),
-    }),
-  ),
-  // `false` when the by-model sub-query faulted, so an empty breakdown is
-  // distinguishable from an unavailable one.
-  byModelAvailable: z.boolean(),
-  granularity: z.enum(['hour', 'day', 'week']),
-});
+// `byModelAvailable` is `false` when the by-model sub-query faulted, so an empty breakdown is
+// distinguishable from an unavailable one.
+export const dashboardMetrics = openapi.metricsResult;
 export type DashboardMetrics = z.infer<typeof dashboardMetrics>;
 
-export const run = z.object({
-  id: z.string(),
-  traceId: z.string(),
-  createdAt: z.string().nullable(),
-  tags: z.array(z.string()),
-  status: z.enum(['error', 'success']),
-  cost: z.number().nullable(),
-  latencyMs: z.number().nullable(),
-  totalTokens: z.number().nullable(),
-  inputPreview: jsonValue,
-  outputPreview: jsonValue,
-});
+export const run = openapi.observabilityRunView;
 export type Run = z.infer<typeof run>;
 
-export const runsPage = z.object({
-  items: z.array(run),
-  page: z.number(),
-  nextPage: z.number().nullable(),
-});
+export const runsPage = openapi.observabilityRunsPage;
 
-export const runSpan = z.object({
-  id: z.string(),
-  parentId: z.string().nullable(),
-  traceId: z.string().nullable(),
-  name: z.string().nullable(),
-  type: z.string().nullable(),
-  level: z.string().nullable(),
-  statusMessage: z.string().nullable(),
-  start: z.string().nullable(),
-  end: z.string().nullable(),
-  model: z.string().nullable(),
-  usage: jsonValue.nullable(),
-  metadata: jsonValue.nullable(),
-  input: jsonValue,
-  output: jsonValue,
-  nodeId: z.string().nullable(),
-});
+/** The neutral span kinds the monitoring backend maps its own observation types onto. */
+export const spanKind = openapi.spanOutlineView.shape.kind.unwrap().unwrap();
+export type SpanKind = z.infer<typeof spanKind>;
+
+/** One span of a run without its input and output: the light span-tree row. */
+export const runSpanOutline = openapi.spanOutlineView;
+export type RunSpanOutline = z.infer<typeof runSpanOutline>;
+
+export const runSpan = openapi.spanView;
 export type RunSpan = z.infer<typeof runSpan>;
 
-export const runTrace = z.object({
-  traceId: z.string(),
-  timestamp: z.string().nullable(),
-  tags: z.array(z.string()),
-  totalCost: z.number().nullable(),
-  input: jsonValue,
-  output: jsonValue,
-  metadata: jsonValue.nullable(),
-  spans: z.array(runSpan),
-});
+/** A run's span tree (`GET /api/observability/runs/{trace}/trace/outline`). */
+export const runTraceOutline = openapi.runTraceOutlineView;
+export type RunTraceOutline = z.infer<typeof runTraceOutline>;
+
+export const runTrace = openapi.runTraceView;
 export type RunTrace = z.infer<typeof runTrace>;
+
+/**
+ * What the monitoring backend serves, in the run list's wire names
+ * (`GET /api/observability/capabilities`): the largest run-list page, the sort keys
+ * it serves, the filter params each sort cannot be combined with, and the metrics
+ * measures and dimensions.
+ */
+export const observabilityCapabilities = openapi.observabilityCapabilities;
+export type ObservabilityCapabilities = z.infer<typeof observabilityCapabilities>;
+
+/** One span field's value with every record reference resolved. */
+export const resolvedSpanValue = openapi.resolvedSpanValue;
+export type ResolvedSpanValue = z.infer<typeof resolvedSpanValue>;

package/src/schemas/policy.ts

@@ -1,6 +1,7 @@
 /** Access-policy validation, version and rollback response schemas. */
 import { z } from 'zod';
 
+import * as openapi from '../generated/openapi-schemas';
 import { policyBody } from './served';
 
 /**
@@ -11,10 +12,7 @@ import { policyBody } from './served';
  * syntactically-broken condition can be caught before it locks a key out. A drift
  * throws `ApiSchemaError`.
  */
-export const validateConditionResult = z.object({
-  ok: z.boolean(),
-  result: z.boolean().nullable(),
-});
+export const validateConditionResult = openapi.conditionCheckResult;
 export type ValidateConditionResult = z.infer<typeof validateConditionResult>;
 
 /**
@@ -23,16 +21,11 @@ export type ValidateConditionResult = z.infer<typeof validateConditionResult>;
  * active pointer; `tags` is the generic per-version label list (kind-agnostic),
  * mirroring the preset version shape.
  */
-export const policyVersion = z.object({
-  version: z.number(),
-  body: policyBody,
-  tags: z.array(z.string()),
-  created_at: z.string(),
-  is_current: z.boolean(),
-});
+// The body is hand-typed: the spec publishes a version body as an open object.
+export const policyVersion = openapi.documentVersion.extend({ body: policyBody });
 export type PolicyVersion = z.infer<typeof policyVersion>;
 
 export const policyVersionList = z.array(policyVersion);
 
 /** `POST /api/auth/api-keys/{user_id}/policy/rollback` — the re-pointed version. */
-export const policyRollback = z.object({ user_id: z.string(), active_version: z.number() });
+export const policyRollback = openapi.policyRollbackResult;