@tai42/api-client 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tai42/api-client",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Typed client for the tai42-skeleton HTTP API.",
   "license": "Apache-2.0",
   "author": "tai42 <oss@tai42.ai>",

package/src/client.ts

@@ -223,6 +223,20 @@ export interface StorageUploadBody {
   readonly content_base64?: string;
 }
 
+/**
+ * One transcript read (GET `/api/conversations/{route}/transcript` query params).
+ * `order` is not a default the caller may skip: `asc` reads the thread from its
+ * beginning and `desc` from its newest end, and which one a screen wants is a
+ * decision that screen must make.
+ */
+export interface ConversationTranscriptQuery {
+  readonly routeName: string;
+  readonly threadId: string;
+  readonly page: number;
+  readonly pageSize: number;
+  readonly order: s.TranscriptOrder;
+}
+
 /** The observability-metrics window + bucket size (GET query params). */
 export interface MetricsQuery {
   readonly from?: string;
@@ -535,14 +549,14 @@ export function createApiClient(config: ApiConfig) {
     // the FLEET doors, which ride the app's worker bus and need no backend at all.
     // `getBackendInfo` reports `present: false` (a 200 empty state) when no backend
     // plugin is registered. `listFleetWorkers` reads the live bus presence census
-    // (every subscribed origin, ASGI + backend-runtime) and never fabricates an empty
+    // (every subscribed worker, ASGI + backend-runtime) and never fabricates an empty
     // fleet — a census read that fails surfaces as a loud 500.
     getBackendInfo: (signal?: AbortSignal) => req('/api/backend', s.backendInfo, { signal }),
     listFleetWorkers: (signal?: AbortSignal) =>
       req('/api/fleet/workers', s.fleetWorkers, { signal }),
     // Soft-restart the fleet: `targets` names the workers to reload, or `null` for
     // the whole fleet. The serving worker applies locally then broadcasts; a 200
-    // response carries the per-origin fleet report, so workers that did not converge
+    // response carries the per-worker fleet report, so workers that did not converge
     // are named, not hidden. A failed local apply instead re-raises as a loud error
     // (the transport throws with the failure message), not a returned report.
     reloadFleetConfig: (targets: string[] | null) =>
@@ -709,6 +723,44 @@ export function createApiClient(config: ApiConfig) {
     // The installed channel-plugin names (delivery media for ask_user questions).
     listChannels: (signal?: AbortSignal) => req('/api/channels', s.channels, { signal }),
 
+    // -- conversations ---------------------------------------------------------
+    // The stored routing rows, each with its `callback_secret` withheld — the
+    // conversation monitor's route picker.
+    listConversationRoutes: (signal?: AbortSignal) =>
+      req('/api/conversations', s.conversationRoutes, { signal }),
+    // One route's threads, newest activity first. Admin-only server-side: a
+    // listing spans every caller on the route, so a scoped session gets a 403.
+    listConversationThreads: (
+      routeName: string,
+      page: number,
+      pageSize: number,
+      signal?: AbortSignal,
+    ) =>
+      req(`/api/conversations/${encodeSegment(routeName)}/threads`, s.conversationThreadsPage, {
+        signal,
+        query: { page, pageSize },
+      }),
+    // One thread's transcript, caller-scoped, read in the asked-for direction.
+    // The `thread_id` rides the QUERY STRING, never the path: it embeds the api
+    // door's `{principal}/{end user}` address with the principal already
+    // percent-encoded, which a path segment would have to encode a second time
+    // and the server would then decode once too few. A query value is decoded
+    // exactly once whatever it holds, so it is passed through verbatim.
+    readConversationTranscript: (query: ConversationTranscriptQuery, signal?: AbortSignal) =>
+      req(
+        `/api/conversations/${encodeSegment(query.routeName)}/transcript`,
+        s.conversationTranscriptPage,
+        {
+          signal,
+          query: {
+            thread_id: query.threadId,
+            page: query.page,
+            pageSize: query.pageSize,
+            order: query.order,
+          },
+        },
+      ),
+
     // -- notifications ---------------------------------------------------------
     // The internal notifications sink, newest-first — the messages the `notify_user`
     // operation records with no channel, so they surface only in this inbox.

package/src/fleet-report.ts

@@ -3,9 +3,9 @@
  * fleet broadcast. Every mutation surface (connector, backup, mcp-config, env,
  * extensions, single-MCP reload, fleet reload) routes its broadcast report through
  * this one function so a FAILED propagation is never invisible: an unconfirmed
- * sibling (`failed`/`missing`/`departed`/`timed_out`) or an unreachable bus becomes
- * an explicit summary the UI renders as a loud, user-visible state — never a faked
- * success on a departed/timed_out/failed origin.
+ * sibling (any non-`applied` outcome) or an unreachable bus becomes an explicit
+ * summary the UI renders as a loud, user-visible state — never a faked success on a
+ * worker that did not converge.
  *
  * A mutation embeds its broadcast in one of two shapes: the mode-wrapped
  * {@link FleetReportFanout} (`fanout` field) or the bare {@link FleetResult} (the
@@ -15,12 +15,12 @@
  */
 import type { FleetOutcome, FleetReportFanout, FleetResult } from './schemas';
 
-/** A per-origin propagation FAILURE: an origin that did not confirm `applied`. */
+/** A per-worker propagation FAILURE: a worker that did not confirm `applied`. */
 export type FleetFailureOutcome = Exclude<FleetOutcome, 'applied'>;
 
-/** One origin that failed to converge, with the report's message for it. */
-export interface FleetOriginFailure {
-  readonly origin: string;
+/** One worker that failed to converge, with the report's message for it. */
+export interface FleetWorkerFailure {
+  readonly name: string;
   readonly outcome: FleetFailureOutcome;
   /** The failed apply's `error`, or the publisher's computed-outcome `detail`. */
   readonly message: string | null;
@@ -28,10 +28,10 @@ export interface FleetOriginFailure {
 
 /**
  * The interpreted state of one broadcast.
- *   - `converged` — the bus was reached and every origin applied (or the change was
+ *   - `converged` — the bus was reached and every worker applied (or the change was
  *     local-only on a lone worker). The caller renders its own success; the report
  *     needs no loud state.
- *   - `degraded` — the bus was reached but one or more origins did not confirm; the
+ *   - `degraded` — the bus was reached but one or more workers did not confirm; the
  *     named `failures` are stale/unreached siblings the operator must see.
  *   - `unreachable` — the bus itself could not be reached, so no sibling was told;
  *     `error` carries the transport failure.
@@ -42,8 +42,8 @@ export interface FleetReportSummary {
   readonly status: FleetReportStatus;
   /** The single-worker `local-only` note, when the broadcast reached no sibling. */
   readonly note: string | null;
-  /** The origins that did not apply — empty unless `status` is `degraded`. */
-  readonly failures: readonly FleetOriginFailure[];
+  /** The workers that did not apply — empty unless `status` is `degraded`. */
+  readonly failures: readonly FleetWorkerFailure[];
   /** The bus-unreachable transport error — non-null only when `unreachable`. */
   readonly error: string | null;
 }
@@ -56,16 +56,16 @@ export function isFleetReportFailure(summary: FleetReportSummary | null): boolea
 /**
  * Interpret a bare {@link FleetResult} (the fleet-reload / single-MCP-reload body).
  * An unreachable bus is `unreachable`; a reachable report with any non-`applied`
- * origin is `degraded` (those origins named); otherwise `converged`.
+ * worker is `degraded` (those workers named); otherwise `converged`.
  */
 export function summarizeFleetResult(result: FleetResult): FleetReportSummary {
   if (!result.reachable) {
     return { status: 'unreachable', note: null, failures: [], error: result.error };
   }
-  const failures: FleetOriginFailure[] = result.results
+  const failures: FleetWorkerFailure[] = result.results
     .filter((entry) => entry.outcome !== 'applied')
     .map((entry) => ({
-      origin: entry.origin,
+      name: entry.name,
       outcome: entry.outcome as FleetFailureOutcome,
       message: entry.error ?? entry.detail ?? null,
     }));

package/src/index.ts

@@ -24,6 +24,7 @@ export type {
   ValidatePresetBody,
   ToolMetaPatch,
   StorageUploadBody,
+  ConversationTranscriptQuery,
   MetricsQuery,
   RunsQuery,
   MarketplaceSearchQuery,
@@ -62,7 +63,7 @@ export { summarizeFleetResult, summarizeFleetFanout, isFleetReportFailure } from
 export type {
   FleetReportSummary,
   FleetReportStatus,
-  FleetOriginFailure,
+  FleetWorkerFailure,
   FleetFailureOutcome,
 } from './fleet-report';
 export * as schemas from './schemas';
@@ -110,6 +111,17 @@ export type {
   MediaKind,
   AnswerFormat,
   Channels,
+  ConversationDoor,
+  ConversationTargetKind,
+  ConversationDeliveryStatus,
+  ConversationAnswerStatus,
+  ConversationRoute,
+  ConversationRoutes,
+  ConversationThread,
+  ConversationThreadsPage,
+  ConversationMessage,
+  TranscriptOrder,
+  ConversationTranscriptPage,
   Notification,
   Notifications,
   HookParams,
@@ -139,11 +151,13 @@ export type {
   StorageInfo,
   StorageResourceStat,
   BackendInfo,
-  OriginKind,
-  FleetOrigin,
+  WorkerKind,
+  WorkerState,
+  WorkerLastOp,
+  FleetWorker,
   FleetWorkers,
   FleetOutcome,
-  FleetOriginResult,
+  FleetWorkerResult,
   FleetResult,
   FleetReloadResult,
   FleetReportFanout,

package/src/schemas.ts

@@ -319,77 +319,117 @@ 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 originKind = z.enum(['serve', 'backend']);
-export type OriginKind = z.infer<typeof originKind>;
+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 entry. `origin` is the
- * `{kind}-{uuid}` identity used as a reload target; `kind` tells the two worker
- * kinds apart; `pid` is the process id the presence key carries.
+ * 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 fleetOrigin = z.object({
-  origin: z.string(),
-  kind: originKind,
+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 FleetOrigin = z.infer<typeof fleetOrigin>;
+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 origins (ASGI `serve` workers and backend-runtime
+ * 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(fleetOrigin) });
+export const fleetWorkers = z.object({ workers: z.array(fleetWorker) });
 export type FleetWorkers = z.infer<typeof fleetWorkers>;
 
 /**
- * One origin'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 origin never sends them).
- */
-export const fleetOutcome = z.enum(['applied', 'failed', 'missing', 'departed', 'timed_out']);
+ * 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 origin's result within a {@link fleetResult}. `payload` carries query-op data
+ * 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 `missing`/`departed`/`timed_out`. A drift
- * throws `ApiSchemaError`.
+ * publisher's report text for a computed gap outcome (`missing`/`departed`/`timed_out`/
+ * `resyncing`/`recycling`/`stale`). A drift throws `ApiSchemaError`.
  */
-export const fleetOriginResult = z.object({
-  origin: z.string(),
+export const fleetWorkerResult = z.object({
+  name: z.string(),
   outcome: fleetOutcome,
   payload: jsonValue,
   error: z.string().nullable(),
   detail: z.string().nullable(),
 });
-export type FleetOriginResult = z.infer<typeof fleetOriginResult>;
+export type FleetWorkerResult = z.infer<typeof fleetWorkerResult>;
 
 /**
- * The awaited per-origin report of one fleet broadcast. Two honest shapes ride the
+ * 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
- * origin (the serving worker's own entry included), so an unconfirmed sibling is a
- * visible `failed`/`missing`/`departed`/`timed_out` entry, never a silent stale
- * worker. Bus-unreachable (`reachable: false`): the transport failed before any
- * origin 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.
+ * 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(fleetOriginResult),
+  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-origin. The
+ * `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 origin's outcome. A failed local apply does not abort the broadcast, so
+ * 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;
@@ -403,7 +443,7 @@ export type FleetReloadResult = z.infer<typeof fleetReloadResult>;
  *   - `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 origin list, only `error`).
+ *     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
@@ -501,7 +541,7 @@ export const mcpStatus = z.object({
 
 /**
  * `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-origin {@link fleetResult}
+ * 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`.
  */
@@ -615,16 +655,28 @@ export type SettingsProfileDiff = z.infer<typeof settingsProfileDiff>;
  * `POST /api/config/profiles/{name}/apply` — the dedicated `profile_apply_response`
  * (action=fenced, destructive). NAMES-ONLY (no env value in any
  * section): `hot` is the hot-swapped key names; `recycle` is the orchestrator's
- * per-origin section — the applier's OWN entry carries the `self-deferred` status
- * literal when the diff has serve-affecting recycle keys; `refused` is `[]` on
- * success by construction (populated `{key, reason}` only on a refusal), the
- * populated refusal surfaces being the diff preview and the refusal error report.
- * `fanout` is the mode-wrapped fleet broadcast, parsed EXPLICITLY so a failed
- * propagation reaches the shared fleet-report handler. A drift throws `ApiSchemaError`.
+ * per-worker section — one `{name, kind, status, generation_before}` row per recycled
+ * target, `generation_before` the life that was recycled, the applier's OWN row carrying
+ * the `self-deferred` status literal when the diff has serve-affecting recycle keys;
+ * `fresh` is the per-kind list of NEW ready lives observed since the pre-apply snapshot
+ * (each `{name, kind, generation}`), evidence of fresh capacity and never claimed as any
+ * target's successor; `refused` is `[]` on success by construction (populated
+ * `{key, reason}` only on a refusal), the populated refusal surfaces being the diff
+ * preview and the refusal error report. `fanout` is the mode-wrapped fleet broadcast,
+ * parsed EXPLICITLY so a failed propagation reaches the shared fleet-report handler. A
+ * drift throws `ApiSchemaError`.
  */
 export const profileApplyResponse = z.object({
   hot: z.array(z.string()),
-  recycle: z.array(z.object({ origin: z.string(), kind: z.string(), status: z.string() })),
+  recycle: z.array(
+    z.object({
+      name: z.string(),
+      kind: z.string(),
+      status: z.string(),
+      generation_before: z.number(),
+    }),
+  ),
+  fresh: z.array(z.object({ name: z.string(), kind: z.string(), generation: z.number() })),
   refused: z.array(z.object({ key: z.string(), reason: z.string() })),
   fanout: fleetReportFanout,
 });
@@ -900,6 +952,139 @@ export const channels = z.object({
 });
 export type Channels = z.infer<typeof channels>;
 
+// -- conversations -----------------------------------------------------------
+// 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>;
+
+/**
+ * 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>;
+
+/** A stored routing row as a read door returns it, its `callback_secret` withheld. */
+export const conversationRoute = z.object({
+  route_name: z.string(),
+  door: conversationDoor,
+  target_kind: conversationTargetKind,
+  target_name: z.string(),
+  payload_expr: z.string().nullable(),
+  reply_expr: z.string().nullable(),
+  execution_key: z.string(),
+  channel: z.string().nullable(),
+  our_identity: z.string().nullable(),
+  callback_url: z.string().nullable(),
+  execution_key_fingerprint: z.string(),
+});
+export type ConversationRoute = z.infer<typeof conversationRoute>;
+
+export const conversationRoutes = z.object({
+  items: z.array(conversationRoute),
+  total: z.number(),
+});
+export type ConversationRoutes = z.infer<typeof conversationRoutes>;
+
+/**
+ * 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>;
+
+/** The page window both thread read doors carry; `next_page` is null on the last. */
+const conversationPageWindow = {
+  total: z.number(),
+  page: z.number(),
+  page_size: z.number(),
+  next_page: z.number().nullable(),
+};
+
+export const conversationThreadsPage = z.object({
+  items: z.array(conversationThread),
+  ...conversationPageWindow,
+});
+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(),
+  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),
+  ...conversationPageWindow,
+  order: transcriptOrder,
+});
+export type ConversationTranscriptPage = z.infer<typeof conversationTranscriptPage>;
+
 // -- notifications -----------------------------------------------------------
 // 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