@teaflask/assistant 0.0.0 → 0.3.0

package/src/components/use-transcript-folds.ts

@@ -0,0 +1,269 @@
+"use client";
+
+import { useContext, type ReactNode } from "react";
+
+import type { ElicitationCardModel } from "../core/elicitation-cards.js";
+import { hostFillDeclines } from "../core/host-fill.js";
+import {
+  currentTurnStartOf,
+  foldedBlocksOf,
+  runFoldsOf,
+  type FoldedBlock,
+  type FoldedTranscriptRow,
+  type RunFoldMember,
+} from "../core/run-folds.js";
+import { subagentOutcomeCountsOf } from "../core/subagent-rows.js";
+import type {
+  MarkerBoundaries,
+  TranscriptRow,
+} from "../core/transcript-rows.js";
+import { ElicitationsContext } from "./elicitation-context.js";
+import type { MessageListSource } from "./message-list-slots.js";
+import {
+  resolvedSubagentEntryOf,
+  SubagentDispatchesContext,
+  type SubagentDispatchesJoin,
+} from "./subagent-group-row.js";
+
+// Reasoning is structurally excluded: it only ever renders inside a run
+// fold, so Row carries no case for it. The fold derivation itself is the
+// pure runFoldsOf pass in core/run-folds.ts.
+export type DisplayRow = FoldedTranscriptRow;
+
+/** MessageList's per-render derivations, read in one place: the fold
+ *  pass, the hold window, the blocks-mode offsets, the tail receipts and
+ *  the trailing-liveness election. */
+export function useMessageListDerivations(
+  source: MessageListSource,
+  {
+    live,
+    typing,
+    turnOpen,
+    markerBoundaries,
+    turnStartIds,
+    decisionSurfacesInShelf,
+    frameClaimsLiveness,
+    emptyFallback,
+  }: {
+    live: boolean;
+    typing: boolean;
+    turnOpen: boolean | undefined;
+    markerBoundaries?: MarkerBoundaries;
+    turnStartIds?: ReadonlySet<string>;
+    decisionSurfacesInShelf: boolean;
+    frameClaimsLiveness: boolean;
+    emptyFallback: ReactNode;
+  },
+) {
+  const { cards: elicitationCards } = useContext(ElicitationsContext);
+  const { foldedBlocks, flatRows, displayRows } = useTranscriptFolds(source, {
+    live,
+    turnOpen,
+    markerBoundaries,
+    turnStartIds,
+  });
+  // The current turn's start (the hold window) is the fold pass's own
+  // boundary (core/run-folds.ts): the last user or subagent-delivery row,
+  // or a later DECLARED turn start (agent-mode delivery turns project no
+  // row), so the hold window and the fold window read the same boundaries.
+  // Positional on purpose, never a clock: the optimistic echo is a user
+  // row, so decay fires at send, and a replay renders identically every
+  // time.
+  const currentTurnStart = currentTurnStartOf(
+    displayRows,
+    foldedBlocks,
+    turnStartIds,
+  );
+  // Blocks mode renders per block, so each row's flat display index —
+  // what the hold window is measured in — is its block's offset plus
+  // its position in the block.
+  const blockStarts = _blockStartsOf(foldedBlocks ?? []);
+  // An ANSWERED ask whose call never rendered a row (a wire that named
+  // no tool_call_id, a history whose call never reached the messages)
+  // still renders its Q→A receipt at the tail: the member answered, and
+  // that is content. It is the ONE settled-decision tail render left —
+  // the meta-receipt lines were deleted as a product decision.
+  const unrowedAnsweredAsks = decisionSurfacesInShelf
+    ? _unrowedAnsweredAsksOf(flatRows, elicitationCards)
+    : NO_UNROWED_ASKS;
+  // The liveness anchor is simply the last display row: the only trailing
+  // marker row (turn-failed receipts) trails once the run settled.
+  const liveIndex = displayRows.length - 1;
+  // The one trailing-liveness arbiter (a seam, closed at its
+  // mechanism): every element that can claim the beat is decided HERE,
+  // from the same facts its renderer reads, so no host and no tail kind
+  // can double-claim or drop the claim.
+  const dispatchesJoin = useContext(SubagentDispatchesContext);
+  // The host's empty surface owns the empty frame: when the host said
+  // "the log is genuinely empty" AND gave the words for it, a package
+  // "Working…" (or the dot) beside those words is a second liveness
+  // claim in one frame — the run viewer's empty streaming state stacked
+  // "No activity yet." over "Working…". The host surface is the claimant
+  // then; the arbiter yields. An empty live log with NO host surface
+  // keeps the standalone headline — one claim either way.
+  const hostEmptySurfaceShown =
+    !hostFillDeclines(emptyFallback) && displayRows.length === 0;
+  // One yield rule: the host's empty surface showing, or
+  // the host's declared frame claim, each means the frame already
+  // carries the words — the standalone claimants stand down.
+  const livenessClaimant =
+    hostEmptySurfaceShown || frameClaimsLiveness
+      ? "none"
+      : _trailingLivenessClaimantOf(displayRows, live, typing, dispatchesJoin);
+  return {
+    foldedBlocks,
+    displayRows,
+    currentTurnStart,
+    blockStarts,
+    unrowedAnsweredAsks,
+    liveIndex,
+    hostEmptySurfaceShown,
+    livenessClaimant,
+  };
+}
+
+const NO_UNROWED_ASKS: ElicitationCardModel[] = [];
+
+/** The fold derivation, pure per render: blocks mode's segmented pass
+ *  or rows mode's flat one. All tool calls stay inside their work fold. */
+function useTranscriptFolds(
+  source: MessageListSource,
+  {
+    live,
+    turnOpen,
+    markerBoundaries,
+    turnStartIds,
+  }: {
+    live: boolean;
+    turnOpen: boolean | undefined;
+    markerBoundaries?: MarkerBoundaries;
+    turnStartIds?: ReadonlySet<string>;
+  },
+): {
+  foldedBlocks: FoldedBlock[] | null;
+  flatRows: readonly TranscriptRow[];
+  displayRows: readonly DisplayRow[];
+} {
+  const { rows, blocks } = source;
+  // Blocks mode: the segmented fold pass, so a host marker
+  // splits folds exactly as a visible row would. Rows mode takes the
+  // branch below it always took — the store surfaces' rendering is
+  // pinned by the pixel suite and the store-composition suites
+  // (the invariant-comment ledger, row 13).
+  const foldedBlocks =
+    blocks !== undefined
+      ? foldedBlocksOf(blocks, {
+          openTailTurn: turnOpen ?? live,
+          markerBoundaries,
+          turnStartIds,
+        })
+      : null;
+  const flatRows = rows ?? blocks.flatMap((block) => block.rows);
+  const displayRows =
+    foldedBlocks !== null
+      ? foldedBlocks.flatMap((block) => block.rows)
+      : runFoldsOf(flatRows, {
+          openTailTurn: turnOpen ?? live,
+        });
+  return { foldedBlocks, flatRows, displayRows };
+}
+
+/** Each block's offset in the flat display order (blocks mode). */
+function _blockStartsOf(blocks: readonly FoldedBlock[]): number[] {
+  const starts: number[] = [];
+  let next = 0;
+  for (const block of blocks) {
+    starts.push(next);
+    next += block.rows.length;
+  }
+  return starts;
+}
+
+/** The answered asks with no rendered row to settle on (shelf
+ *  composition): a wire that named no tool_call_id, or a history whose
+ *  call never reached the messages. Their Q→A receipts render
+ *  at the transcript tail — content, never meta-narration. Stale asks
+ *  render nothing: the meta-receipt rows were deleted, the quiet
+ *  stale line with them. */
+function _unrowedAnsweredAsksOf(
+  rows: readonly TranscriptRow[],
+  elicitationCards: readonly ElicitationCardModel[],
+): ElicitationCardModel[] {
+  const renderedCallIds = new Set<string>();
+  for (const row of rows) {
+    if (row.kind === "tool-call") {
+      renderedCallIds.add(row.toolCallId);
+    }
+  }
+  return elicitationCards.filter(
+    (card) =>
+      (card.toolCallId === null || !renderedCallIds.has(card.toolCallId)) &&
+      card.status === "answered",
+  );
+}
+
+export type TrailingLivenessClaimant =
+  "tail-row" | "standalone-headline" | "typing-dot" | "none";
+
+/** WHO claims the trailing liveness beat — the one arbiter. Exactly one
+ *  element may say "work is live" at the transcript tail, across every
+ *  host and every tail row kind. Precedence: a claiming tail row (a live
+ *  fold, streaming prose, a delegation group with a running member —
+ *  resolved through the SAME join the group row renders from); else
+ *  `typing` elects the silence-gap dot; else `live` elects the standalone
+ *  Working… headline; else none. The full table is in
+ *  docs/transcript-surfaces.md and tests/liveness-claimants.test.tsx
+ *  executes it. A host-provided empty surface on an empty log outranks
+ *  everything here at the call site. The dot OUTRANKS the headline
+ *  deliberately: the drill-in preview passes typing alongside live and
+ *  keeps its dot; Transcript never passes typing. */
+function _trailingLivenessClaimantOf(
+  displayRows: readonly DisplayRow[],
+  live: boolean,
+  typing: boolean,
+  dispatches: SubagentDispatchesJoin,
+): TrailingLivenessClaimant {
+  const last = displayRows.at(-1);
+  const tailClaims =
+    last !== undefined &&
+    ((last.kind === "run-fold" && _foldClaimsLiveness(last.members, live)) ||
+      (last.kind === "assistant-text" && last.streaming) ||
+      // The group's own headline shimmers exactly when its resolved
+      // counts say a member runs — resolved through the SAME exported
+      // join the group row renders from (never a respelled predicate),
+      // so the arbiter and the row cannot drift.
+      (last.kind === "subagent-group" &&
+        subagentOutcomeCountsOf(
+          last.entries.map((entry) =>
+            resolvedSubagentEntryOf(entry, dispatches.byOrdinal),
+          ),
+        ).running > 0));
+  if (tailClaims) {
+    return "tail-row";
+  }
+  if (typing) {
+    return "typing-dot";
+  }
+  if (live) {
+    return "standalone-headline";
+  }
+  return "none";
+}
+
+/** One live spelling of "this fold reads as running" — ActivityRail's
+ *  headline and the trailing-liveness arbiter both read it. The trailing
+ *  fold's turnLive bridges the quiet beat between one call's result and
+ *  the next call's start, so back-to-back calls don't blink the headline. */
+export function _foldClaimsLiveness(
+  members: readonly RunFoldMember[],
+  turnLive: boolean,
+): boolean {
+  return (
+    turnLive ||
+    members.some(
+      (row) =>
+        (row.kind === "reasoning" && row.streaming) ||
+        (row.kind === "tool-call" && row.state === "input-available"),
+    )
+  );
+}

package/src/components/use-transcript.ts

@@ -0,0 +1,131 @@
+"use client";
+
+// The transcript read surface: the ONE derivation from the store's read cells
+// to renderable rows, consumed by components/transcript.tsx and exported public
+// on ./headless — never ./transcript, since the BINDING to a live store rides
+// the provider, which constructs the transport. Chrome-free by construction
+// (tests/bundle-closure.test.ts): VALUE-imports only core/*, React, ./headless
+// seams.
+
+import { useEffect, useMemo } from "react";
+
+import type { Message } from "@ag-ui/core";
+
+import {
+  isTerminalTurnStatus,
+  type AssistantActivitySnapshot,
+} from "../core/activity.js";
+import type { MarkerAnchorsSnapshot } from "../core/connection-epoch.js";
+import { runReadsAsWorking } from "../core/run-status.js";
+import {
+  approvalAwaitsMember,
+  elicitationAwaitsMember,
+} from "../core/suspension-queue.js";
+import {
+  transcriptRowsOf,
+  withPendingUserEcho,
+  type TranscriptRow,
+} from "../core/transcript-rows.js";
+import type { UserTurnMeta } from "../core/user-turn-ledger.js";
+import { useConversation } from "./conversation-context.js";
+import { useAssistantSession } from "./teaflask-assistant-provider.js";
+import { useCell } from "./use-store-cell.js";
+
+/** The transcript read surface: everything a host needs to render the
+ *  assistant's replies, derived exactly the way the package chrome derives it. */
+export interface TranscriptSurface {
+  /** transcriptRowsOf(messages, markerAnchors, running, turnMeta) — the
+   *  pure interleave, identity-stable while its four inputs hold. */
+  rows: readonly TranscriptRow[];
+  /** `rows` with the composer's optimistic echo appended (withPendingUserEcho).
+   *  Render this; a host that also paints its own bubble would double it. */
+  displayRows: readonly TranscriptRow[];
+  /** runReadsAsWorking(activity.newestTurnStatus, decisionsPending) — the
+   *  machine's time. False for the send round trip, so a "working" indicator
+   *  should join the composer contract's pendingSend, as the chrome does. */
+  running: boolean;
+  /** The newest turn is non-terminal — broader than `running`: the HITL
+   *  pauses (awaiting_input, parked) count. */
+  turnOpen: boolean;
+  /** A member-actionable decision is live — the run is the MEMBER's time. */
+  decisionsPending: boolean;
+  /** The four raw store reads, as plain values — so transcriptRowsOf(messages,
+   *  markerAnchors, running, turnMeta) type-checks verbatim for a host's own projection. */
+  messages: readonly Message[];
+  markerAnchors: MarkerAnchorsSnapshot;
+  activity: AssistantActivitySnapshot;
+  turnMeta: ReadonlyMap<string, UserTurnMeta>;
+}
+
+/**
+ * The store's read side, projected: the message list and marker anchors
+ * folded into the flat row list, plus the run-state facts the rows key on.
+ * Mounting registers transcript presence (the lease) — what guarantees the
+ * epoch connects and history paints by full replay; unmounting mid-turn changes nothing.
+ */
+export function useTranscript(options?: {
+  /** The lease label the store's presence ledger records (the chrome's `surface` prop). */
+  surface?: string;
+}): TranscriptSurface {
+  const { store } = useAssistantSession();
+  const { pendingEcho } = useConversation();
+  const messages = useCell(store.messages);
+  const markerAnchors = useCell(store.markerAnchors);
+  const approvalCards = useCell(store.approvals);
+  const elicitationCards = useCell(store.elicitations);
+  const activity = useCell(store.activity);
+  const turnMeta = useCell(store.turnMeta);
+
+  const surface = options?.surface ?? "headless";
+  useEffect(() => store.acquireTranscriptLease(surface), [store, surface]);
+
+  // The decision-live fact: the one honest signal that the run is the
+  // MEMBER's time — claimed only while a decision surface exists, via the
+  // shared predicates, never the sorted queue (whose row-index input
+  // changes every token). The gap counts too: the role="alert" banner says
+  // the run waits. Truthiness on purpose: a partial snapshot's undefined
+  // is no-gap.
+  const decisionSurfaceLive = useMemo(
+    () =>
+      approvalCards.some(approvalAwaitsMember) ||
+      elicitationCards.some(elicitationAwaitsMember),
+    [approvalCards, elicitationCards],
+  );
+  const decisionsPending =
+    decisionSurfaceLive || Boolean(activity.pendingDecisionGap);
+  // "The run is live" is the machine's time: queued/working, or a
+  // non-terminal pause with no live decision surface — the same function the
+  // sr-only announcer speaks, so headline and live region never disagree. It
+  // narrows the tool rows' no-result presentation and the newest rows' streaming flag.
+  const running = runReadsAsWorking(
+    activity.newestTurnStatus,
+    decisionsPending,
+  );
+  // "The turn is open" is broader than "the run is live": it includes the HITL
+  // pauses. The completed-episode fold keys on terminality, so a pause never
+  // unifies the tail turn mid-flight and pops it back out on resume.
+  const turnOpen =
+    activity.newestTurnStatus !== null &&
+    !isTerminalTurnStatus(activity.newestTurnStatus);
+
+  const rows = useMemo(
+    () => transcriptRowsOf(messages, markerAnchors, running, turnMeta),
+    [messages, markerAnchors, running, turnMeta],
+  );
+  const displayRows = useMemo(
+    () => withPendingUserEcho(rows, pendingEcho),
+    [pendingEcho, rows],
+  );
+
+  return {
+    rows,
+    displayRows,
+    running,
+    turnOpen,
+    decisionsPending,
+    messages,
+    markerAnchors,
+    activity,
+    turnMeta,
+  };
+}

package/src/components/user-message.tsx

@@ -0,0 +1,68 @@
+"use client";
+
+// The adopted register — bake-off 2026-07-30 (assistant-ui thread.tsx's user message): a muted
+// rounded-xl bubble right-anchored behind a wide reserved gutter, so
+// long messages never crowd the left edge. assistant-ui's markup with
+// the action bar and branch picker removed (the widget has neither).
+// Attachments stack above the bubble, right-anchored with it; an
+// attachment-only message is just the stack, no empty bubble.
+//
+// Beneath the bubble, one reserved meta row: the turn's timestamp and
+// the package's one copy affordance are both hover/focus-revealed (the
+// roster chevron's reveal idiom; always visible on coarse pointers).
+// The row's height is reserved whether or not the button shows, so the
+// reveal never shifts the message. An attachment-only message renders
+// no meta row: there is no text to copy, and its turn's stamp has no
+// bubble to belong to.
+
+import { conversationalTimeOf } from "../core/time-labels.js";
+import type { TurnAttachment } from "../contract/threads.js";
+import { AttachmentChips } from "./attachment-chips.js";
+import { CopyTextButton } from "./copy-text-button.js";
+
+export function UserMessage({
+  children,
+  attachments = [],
+  createdAt,
+}: {
+  children: string;
+  attachments?: readonly TurnAttachment[];
+  /** The turn's server created_at (ISO-8601) — the bubble's one honest
+   *  clock: the wire carries no per-message timestamp, and a client clock
+   *  would lie on every replay. Absent (the optimistic echo, meta-less
+   *  hosts) renders no stamp — never a wrong one. */
+  createdAt?: string;
+}) {
+  const time = createdAt !== undefined ? conversationalTimeOf(createdAt) : null;
+  return (
+    <div
+      className="tf:group/user-message tf:flex tf:flex-col tf:items-end tf:gap-2 tf:ps-20"
+      data-role="user"
+    >
+      <AttachmentChips attachments={attachments} />
+      {children !== "" ? (
+        <>
+          <div className="tf:min-w-0 tf:rounded-xl tf:bg-tf-muted tf:px-4 tf:py-2 tf:text-tf-body tf:break-words tf:whitespace-pre-wrap tf:text-tf-foreground">
+            {children}
+          </div>
+          <div className="tf:flex tf:h-7 tf:items-center tf:justify-end tf:gap-1">
+            {time !== null ? (
+              <time
+                dateTime={createdAt}
+                title={time.full}
+                className="tf:text-xs tf:text-tf-muted-foreground tf:opacity-0 tf:transition-opacity tf:group-hover/user-message:opacity-100 tf:group-focus-within/user-message:opacity-100 tf:pointer-coarse:opacity-100"
+              >
+                {time.label}
+              </time>
+            ) : null}
+            <CopyTextButton
+              text={children}
+              label="Copy message"
+              className="tf:opacity-0 tf:transition-opacity tf:group-hover/user-message:opacity-100 tf:group-focus-within/user-message:opacity-100 tf:focus-visible:opacity-100 tf:pointer-coarse:opacity-100"
+            />
+          </div>
+        </>
+      ) : null}
+    </div>
+  );
+}

package/src/contract/actions-adapter.ts

@@ -0,0 +1,70 @@
+// The actions-adapter contract — the one seam a host wires to let the
+// assistant act against its own API. FROZEN and
+// additive-only forever: fields may be added, never renamed, retyped, or
+// removed. The package never sniffs the host's fetch and never asks for
+// per-endpoint registration — one adapter serves the whole catalog. The
+// request's origin always belongs to the adapter: intents carry only a
+// relative path template, so a compromised turn cannot point a request
+// anywhere the host didn't choose.
+
+// A host's coding agent authors its adapter against this file as
+// published in the adapters guide (docs.teaflask.com/adapters.md).
+/** The catalog identity of the action being executed — server-built, never model prose. */
+export interface ActionIntentAction {
+  slug: string;
+  title: string;
+}
+
+/**
+ * One action the assistant asks this page to perform: the server-built
+ * request — method, path template, validated arguments — from the org's
+ * vetted actions catalog. `pathTemplate` is app-relative
+ * ("/subscriptions/{subscription_id}"); the origin is always the
+ * adapter's own.
+ */
+export interface ActionIntent {
+  action: ActionIntentAction;
+  method: string;
+  pathTemplate: string;
+  pathParams: Record<string, unknown>;
+  query: Record<string, unknown>;
+  /** The JSON request body; absent when the action sends none. */
+  body?: unknown;
+}
+/**
+ * Session-cookie APIs: the package assembles the URL under `baseUrl` and
+ * fetches with credentials included — the request runs in the user's own
+ * session, so the assistant can do nothing the user couldn't.
+ */
+export interface CookiesActionsAdapter {
+  kind: "cookies";
+  baseUrl: string;
+}
+
+/**
+ * Token-auth APIs: the package assembles the URL under `baseUrl` and
+ * asks `getHeaders` per action (may be async — mint or refresh inside).
+ */
+export interface HeadersActionsAdapter {
+  kind: "headers";
+  baseUrl: string;
+  getHeaders: (
+    intent: ActionIntent,
+  ) => Record<string, string> | Promise<Record<string, string>>;
+}
+
+/**
+ * Full control: the host's own request wrapper receives the whole intent
+ * and resolves with the API's response body. A resolved promise reads as
+ * a success; a rejection reads as a failed execution and is reported to
+ * the assistant as such — the convention every wrapper in this class
+ * (an orval mutator, an axios instance) already follows by throwing on
+ * non-2xx.
+ */
+export interface RequestActionsAdapter {
+  kind: "request";
+  execute: (intent: ActionIntent) => Promise<unknown>;
+}
+
+export type ActionsAdapter =
+  CookiesActionsAdapter | HeadersActionsAdapter | RequestActionsAdapter;

package/src/contract/assistant-config.ts

@@ -0,0 +1,12 @@
+// The assistant-config read: the authored widget configuration served at
+// runtime. The shapes are generated from serving-openapi.json; this file
+// keeps the package's public names stable over the generated ones.
+
+export type {
+  AssistantConfigResponse,
+  AttachmentPolicyResponse as ServedAttachmentPolicy,
+  ModelChoiceResponse as ServedModelChoice,
+  RouteSuggestions as ServedRouteSuggestions,
+  SuggestionsConfig as ServedSuggestionsConfig,
+  ThinkingEffort as ServedThinkingEffort,
+} from "../generated/models/index.js";

package/src/contract/dispatches.ts

@@ -0,0 +1,76 @@
+// The thread's subagent dispatch ledger: the serving projection
+// is receipts/status/summary — no row id, no model; summary is
+// the child report's bounded excerpt stamped at settle — and the
+// package's public names for it stay stable over the generated ones.
+// Rows join the
+// transcript's dispatch receipts by ORDINAL — the ask's identity;
+// child_session_id is the drill-in handle, and a resume
+// chain shares it across rows — and the row's status outranks the
+// receipt's frozen outcome (the serving contract, "Reading a thread's
+// subagent dispatches").
+
+import { AgentDispatchStatus } from "../generated/models/index.js";
+
+export type { ServingAgentDispatchResponse as ThreadDispatch } from "../generated/models/index.js";
+
+export type ThreadDispatchStatus = AgentDispatchStatus;
+
+// The predicates take the generated union, never bare string — a renamed
+// status word in the spec must fail the compile here, not silently turn
+// every ledger row into finished-and-not-failed (the dashboard's
+// dispatch-status twin takes the same posture).
+
+// Running means the child still owns its row: dispatched, or paused for
+// an answer it cannot give itself — both are open, unsettled.
+export function dispatchIsRunning(dispatch: {
+  status: ThreadDispatchStatus;
+}): boolean {
+  return (
+    dispatch.status === AgentDispatchStatus.dispatched ||
+    dispatch.status === AgentDispatchStatus.paused
+  );
+}
+
+export function dispatchFailed(dispatch: {
+  status: ThreadDispatchStatus;
+}): boolean {
+  return dispatch.status === AgentDispatchStatus.failed;
+}
+
+/** Paused for an answer only the member's browser can give — a running
+ *  row whose request the transcript can name. */
+export function dispatchIsPaused(dispatch: {
+  status: ThreadDispatchStatus;
+}): boolean {
+  return dispatch.status === AgentDispatchStatus.paused;
+}
+
+/** Whether the ledger AFFIRMATIVELY says this child is done — a row we
+ *  hold whose status is succeeded or failed. The one predicate a
+ *  stream-end verdict may read "settled" from: its
+ *  complement is not "running" but "not known to have settled", which
+ *  covers a still-dispatched row AND no row at all — a ledger read that
+ *  bounded out or failed with no prior snapshot. A ledger not read is not
+ *  a ledger that settled (the backend's own null posture on the
+ *  sse_stream_teardown line), so undefined answers false here, and a
+ *  judge asking "did it settle?" through this predicate can never turn an
+ *  unreadable ledger into Finished. Enumerated over every state:
+ *
+ *    dispatched → false     succeeded → true
+ *    paused     → false     failed    → true
+ *    undefined (unread) → false */
+export function dispatchHasSettled(
+  dispatch: { status: ThreadDispatchStatus } | undefined,
+): boolean {
+  if (dispatch === undefined) {
+    return false;
+  }
+  switch (dispatch.status) {
+    case AgentDispatchStatus.succeeded:
+    case AgentDispatchStatus.failed:
+      return true;
+    case AgentDispatchStatus.dispatched:
+    case AgentDispatchStatus.paused:
+      return false;
+  }
+}

package/src/contract/errors.ts

@@ -0,0 +1,23 @@
+// The error envelope every non-2xx serving answer rides. The code
+// vocabulary is generated from serving-openapi.json; the envelope shape
+// stays hand-written because the generated ErrorEnvelope carries the
+// dashboard's full closed ApiErrorCode, while this public surface wants
+// the serving codes plus forward compatibility.
+
+export type { ServingErrorCode } from "../generated/models/index.js";
+
+import type { ServingErrorCode } from "../generated/models/index.js";
+
+// The contract is additive-only: new codes may appear, so a client must
+// tolerate strings outside the known union while keeping autocompletion.
+export type ServingErrorCodeOnTheWire = ServingErrorCode | (string & {});
+
+export interface ServingErrorBody {
+  code: ServingErrorCodeOnTheWire;
+  message: string;
+  details?: unknown;
+}
+
+export interface ServingErrorEnvelope {
+  error: ServingErrorBody;
+}