@teaflask/assistant 0.0.0 → 0.3.0

package/src/core/tool-call-display.ts

@@ -0,0 +1,149 @@
+// The tool-call rendering contract: tool NAME, PROTOCOL state, raw I/O and
+// an optional backend-authored display envelope. The package knows the
+// protocol, never a CUSTOMER's tool catalog: no tool-name switch lives
+// client-side; per-tool parsing exists only inside the rung-3 built-in views.
+
+/** Protocol states from the AG-UI event trail — the AI SDK vocabulary
+ *  minus the approval states, plus four the SDK never names: cancelled,
+ *  superseded, refused and denied
+ *  (docs/tool-call-contract.md, "States"). */
+export type ToolCallState =
+  | "input-streaming"
+  | "input-available"
+  | "output-available"
+  | "output-error"
+  | "denied"
+  | "cancelled"
+  | "refused"
+  | "superseded";
+
+/** Backend-authored display metadata for one tool call — the client mirror
+ *  of the wire's six-field envelope; absent on unannotated tools. */
+export interface ToolCallDisplay {
+  /** The model's own words for the step: the row's label in
+   *  every state; the shimmer or a quiet state word carries the state. */
+  caption?: string;
+  progressText?: string;
+  completeText?: string;
+  /** Authored failure copy for output-error; never success copy. */
+  errorText?: string;
+  /** Semantic icon token, verbatim from the wire's open vocabulary; unknown
+   *  values resolve to "generic" at presentation time, never here. */
+  icon?: string;
+  /** The tool-view reference (tool-views.md): an opaque key plus the
+   *  contract version it targets — meaningless apart, so merged atomically. */
+  view?: { key: string; version: number };
+}
+
+export interface ToolCallViewModel {
+  toolName: string;
+  state: ToolCallState;
+  /** The wire's tool call id; optional because presentation-only callers
+   *  (subagent presence) have none — the tool-view call carries "" then,
+   *  and the row stamps its data-tf-tool-call-id hook only when present. */
+  toolCallId?: string;
+  /** The streamed arguments, pretty-printed by the caller. */
+  input: string;
+  /** The raw streamed argument JSON text, for the tool-view call's `args`. */
+  argsText?: string;
+  /** The tool result, verbatim from the wire; absent until it lands. */
+  output?: string;
+  /** True when the wire's result was the context offloader's model-facing
+   *  replacement: `output` is withheld; the row says the result was shortened. */
+  offloaded?: boolean;
+  errorText?: string;
+  /** The door's own refusal sentence, present only on refused
+   *  rows — the row's reason in neutral ink, never in the Error pane. */
+  refusalText?: string;
+  display?: ToolCallDisplay;
+  /** The tool's registered argument schema, verbatim from the wire; absent when none
+   *  was declared, never `{}`. Forwarded to the tool-view call's argsSchema, never interpreted here. */
+  argsSchema?: Record<string, unknown>;
+  /** The registered success-result schema; same absence rules. */
+  resultSchema?: Record<string, unknown>;
+}
+
+/** "create_support_ticket" → "create support ticket": mechanical, never
+ *  title-cased — reads the name's SPELLING, never its meaning. */
+export function humanizedToolName(name: string): string {
+  return name.replace(/[-_]+/g, " ").trim();
+}
+
+/** The row's headline by the fallback ladder: the backend's display text
+ *  when the wire sent one → the humanized tool name in a protocol-state verb
+ *  frame ("Running X…", "Ran X", "X failed"). The frame comes from the STATE,
+ *  never the tool's meaning. Per-state frames: docs/tool-call-contract.md. */
+export function toolRowHeadlineOf(view: ToolCallViewModel): string {
+  const caption = view.display?.caption;
+  if (caption !== undefined) {
+    return _captionedHeadlineOf(caption, view.state);
+  }
+  const displayText = _displayTextFor(view);
+  if (displayText !== undefined) {
+    return displayText;
+  }
+  const name = humanizedToolName(view.toolName);
+  switch (view.state) {
+    case "input-streaming":
+      return name;
+    case "input-available":
+      return `Running ${name}…`;
+    case "output-available":
+      return `Ran ${name}`;
+    case "output-error":
+      return `${name} failed`;
+    case "denied":
+      return `You didn't approve ${name}`;
+    case "cancelled":
+      return `Didn't run ${name}`;
+    case "refused":
+      return `Didn't ${name}`;
+    case "superseded":
+      return `Didn't finish ${name}`;
+  }
+}
+
+/** A caption is intent, not a claim, so it stays the label in every state;
+ *  off the running/done path the state rides as a quiet word after it. */
+function _captionedHeadlineOf(caption: string, state: ToolCallState): string {
+  switch (state) {
+    case "input-streaming":
+    case "input-available":
+    case "output-available":
+      return caption;
+    case "output-error":
+      return `${caption} · failed`;
+    case "denied":
+      return `${caption} · not approved`;
+    case "cancelled":
+      return `${caption} · didn't run`;
+    case "refused":
+      return `${caption} · declined`;
+    case "superseded":
+      return `${caption} · didn't finish`;
+  }
+}
+
+/** The display slot per state: completion copy only for a call that
+ *  completed; output-error takes authored error copy, else the "X failed"
+ *  frame. Denied, cancelled, refused and superseded refuse copy — the
+ *  progress sentence predates the decision (docs/tool-call-contract.md). */
+function _displayTextFor(view: ToolCallViewModel): string | undefined {
+  switch (view.state) {
+    case "input-streaming":
+    case "input-available":
+      return view.display?.progressText;
+    case "output-available":
+      return view.display?.completeText;
+    case "output-error":
+      return view.display?.errorText;
+    case "denied":
+      return undefined;
+    case "cancelled":
+      return undefined;
+    case "refused":
+      return undefined;
+    case "superseded":
+      return undefined;
+  }
+}

package/src/core/tool-call-presentation.ts

@@ -0,0 +1,264 @@
+// One presenter, many consumers: the transcript row, the
+// resolved-action summary, the subagent current-work label and the
+// tool-view slot all read ONE resolved presentation — consumers select
+// slots, none reinterprets the raw display envelope (that would fork the
+// fallback ladder). Unknown wire vocabulary collapses to the documented
+// fallbacks here and only here, so a stored display survives a vocabulary
+// the build predates. React-free by design.
+
+import type { ToolCallState, ToolCallViewModel } from "./tool-call-display.js";
+import { toolRowHeadlineOf } from "./tool-call-display.js";
+import { toolResultEnvelopePayloadOf } from "./tool-result-envelope.js";
+import type {
+  ToolViewCall,
+  ToolViewRegistry,
+  ToolViewResolution,
+} from "./tool-view.js";
+import { STEP_CAPTION_ARG_KEY, withoutStepCaption } from "./step-caption.js";
+import { resolvedToolViewsOf } from "./tool-view.js";
+
+/** The semantic icon vocabulary — operational meaning, never a brand or
+ *  a tool name. Open on the wire; unknown values resolve to "generic". */
+export const TOOL_CALL_ICONS = [
+  "search",
+  "file",
+  "terminal",
+  "question",
+  "memory",
+  "delegation",
+  "routine",
+  "todo",
+  "navigation",
+  "generic",
+] as const;
+
+export type ToolCallIcon = (typeof TOOL_CALL_ICONS)[number];
+
+/**
+ * One tool call's resolved presentation — every consumer's single source.
+ * Slots, and who reads them: the transcript row takes headline, icon and
+ * status; resolved-action and provenance summaries take settledSummary;
+ * subagent presence takes currentWorkLabel; toolView is the resolution
+ * ladder's answer (tool-views.md) and the row's whole body — no raw
+ * payload disclosure exists. The approval banner reads no slot.
+ */
+export interface ToolCallPresentation {
+  /** The transcript row's words — the fallback ladder's answer:
+   *  backend copy when the wire sent it, the mechanical
+   *  protocol-state frame otherwise. */
+  headline: string;
+  icon: ToolCallIcon;
+  status: ToolCallState;
+  /** The line a settled call leaves behind — BY DEFINITION the resolved
+   *  headline (the ladder's settled arms are the summary: completion
+   *  copy, error copy or the failed frame, the refusal frame, the
+   *  not-approved frame). The slot is named separately so summary
+   *  consumers bind here, not to the row's wording; if the two are ever
+   *  meant to differ, the divergence lands in this one resolver, never
+   *  in a consumer. */
+  settledSummary: string;
+  /** The present-progressive "what it is doing now" line — the
+   *  ladder's RUNNING arm regardless of the view's own state, so
+   *  consumers need no state guard of their own. */
+  currentWorkLabel: string;
+  toolView: ToolViewResolution;
+}
+
+export function toolCallPresentationOf(
+  view: ToolCallViewModel,
+  registry?: ToolViewRegistry,
+  options?: { awaitingDecision?: boolean },
+): ToolCallPresentation {
+  const headline = toolRowHeadlineOf(view);
+  const resolved = resolvedToolViewsOf(
+    view.display?.view,
+    view.toolName,
+    registry,
+  );
+  // The call is assembled LAZILY, memoized per presentation, and its
+  // RESULT structures lazier still (see _toolViewCallOf): the row's slot
+  // reads the call on every render, the default view reads args alone,
+  // and a transcript re-renders every row per streamed token — so a
+  // rung-4 row never structures its result, and the parse memo holds
+  // only what a mounted view read. The getters keep the single-
+  // resolution-point law: assembly still happens only here, on first read.
+  let call: ToolViewCall | undefined;
+  const awaitingDecision = options?.awaitingDecision === true;
+  return {
+    headline,
+    icon: _iconOf(view.display?.icon),
+    status: view.state,
+    settledSummary: headline,
+    currentWorkLabel: toolRowHeadlineOf({ ...view, state: "input-available" }),
+    toolView: {
+      views: resolved.views,
+      icons: resolved.icons,
+      get call(): ToolViewCall {
+        call ??= _toolViewCallOf(view, awaitingDecision);
+        return call;
+      },
+    },
+  };
+}
+
+function _iconOf(token: string | undefined): ToolCallIcon {
+  if (
+    token !== undefined &&
+    (TOOL_CALL_ICONS as readonly string[]).includes(token)
+  ) {
+    return token as ToolCallIcon;
+  }
+  return "generic";
+}
+
+/**
+ * The tool-view call, assembled once here: parsing wire text into
+ * renderable data is resolution, and it must not fork per consumer.
+ * `context.themeMode` is deliberately NOT assembled here — it is the
+ * slot's ambient fact (use-resolved-theme-mode.ts), not replay data.
+ * `result` and `truncated` are lazy accessors over the verbatim
+ * resultText: a settled result can run to the door's 20k and most rows
+ * (rung 4, whose default view reads args alone) never look at it, so
+ * the structuring parse happens on first read and once per call.
+ * IDENTITY LAW: every value on the call is identity-stable across a
+ * re-render with unchanged source, because the mount slot's structural
+ * delivery guard rests on it. The member-by-member census:
+ * docs/tool-call-contract.md, "The identity law".
+ */
+function _toolViewCallOf(
+  view: ToolCallViewModel,
+  awaitingDecision: boolean,
+): ToolViewCall {
+  const call: ToolViewCall = {
+    toolName: view.toolName,
+    toolCallId: view.toolCallId ?? "",
+    status: view.state,
+    awaitingDecision,
+    args: _argsOf(view.argsText ?? view.input),
+  };
+  if (view.output !== undefined) {
+    const output = view.output;
+    call.resultText = output;
+    let structured: StructuredResult | undefined;
+    const structure = (): StructuredResult =>
+      (structured ??= _structuredResultOf(output));
+    Object.defineProperties(call, {
+      result: {
+        enumerable: true,
+        configurable: true,
+        get: () => structure().result,
+      },
+      truncated: {
+        enumerable: true,
+        configurable: true,
+        get: () => structure().truncated,
+      },
+    });
+  }
+  if (view.offloaded === true) {
+    call.offloaded = true;
+  }
+  if (view.errorText !== undefined) {
+    call.errorText = view.errorText;
+  }
+  if (view.refusalText !== undefined) {
+    call.refusalText = view.refusalText;
+  }
+  // Absent stays absent: a tool with no declared schema hands
+  // the view `undefined`, never `{}` and never an invented one.
+  if (view.argsSchema !== undefined) {
+    call.argsSchema = view.argsSchema;
+  }
+  if (view.resultSchema !== undefined) {
+    call.resultSchema = view.resultSchema;
+  }
+  return call;
+}
+
+interface StructuredResult {
+  result?: unknown;
+  truncated?: boolean;
+}
+
+/** The tool-result/v1 envelope unwrap (core/tool-result-envelope.ts): a
+ *  {payload} box structures, null refuses — the wire's bytes were
+ *  degraded to fit the size cap, and a complete-looking `result` over a
+ *  cut payload would be a wrong claim; the honest flag rides instead,
+ *  beside the verbatim resultText. Non-JSON output structures nothing. */
+function _structuredResultOf(output: string): StructuredResult {
+  const parsed = _jsonDocumentOf(output);
+  if (parsed === undefined) {
+    return {};
+  }
+  const box = toolResultEnvelopePayloadOf(parsed.document);
+  return box === null ? { truncated: true } : { result: box.payload };
+}
+
+/** The one shared empty-args identity (see the identity law above). */
+const EMPTY_ARGS: Record<string, unknown> = Object.freeze({});
+
+/** The streamed arguments, parsed whole: a JSON record when complete,
+ *  EMPTY_ARGS while the tail is still arriving or when the text is not
+ *  a record — a view must never see half an argument object. */
+function _argsOf(argsText: string): Record<string, unknown> {
+  const parsed = _jsonDocumentOf(argsText);
+  if (parsed === undefined || !_isRecord(parsed.document)) {
+    return EMPTY_ARGS;
+  }
+  if (!(STEP_CAPTION_ARG_KEY in parsed.document)) {
+    return parsed.document;
+  }
+  return _captionlessArgsOf(parsed.document);
+}
+
+// The reserved-key strip keeps the identity law: keyed on the memoized
+// document, one caption-less copy per source text, the shared document
+// itself never mutated.
+const _captionlessArgs = new WeakMap<
+  Record<string, unknown>,
+  Record<string, unknown>
+>();
+
+function _captionlessArgsOf(
+  document: Record<string, unknown>,
+): Record<string, unknown> {
+  const memoized = _captionlessArgs.get(document);
+  if (memoized !== undefined) {
+    return memoized;
+  }
+  const rest = withoutStepCaption(document);
+  const args = Object.keys(rest).length === 0 ? EMPTY_ARGS : rest;
+  _captionlessArgs.set(document, args);
+  return args;
+}
+
+// The parse memo: identity by construction, keyed on the source text, so
+// "same source text" and "same object" are one fact. The memoized document
+// is SHARED across readers (never mutate what a call hands you); failures
+// are not memoized; the cap is a wholesale reset, not an LRU
+// (docs/tool-call-contract.md, "The parse memo").
+const JSON_MEMO_MAX_ENTRIES = 512;
+const _jsonMemo = new Map<string, { document: unknown }>();
+
+/** JSON.parse behind a box, so a legitimately-null document stays
+ *  distinguishable from "not JSON". */
+function _jsonDocumentOf(text: string): { document: unknown } | undefined {
+  const memoized = _jsonMemo.get(text);
+  if (memoized !== undefined) {
+    return memoized;
+  }
+  try {
+    const parsed = { document: JSON.parse(text) as unknown };
+    if (_jsonMemo.size >= JSON_MEMO_MAX_ENTRIES) {
+      _jsonMemo.clear();
+    }
+    _jsonMemo.set(text, parsed);
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}
+
+function _isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/core/tool-cancel-anchors.ts

@@ -0,0 +1,15 @@
+// The tool-cancel anchor set: a cancelled TOOL_CALL_RESULT's content is
+// the model-facing cancellation text, so the transcript reads this set to
+// light the call's cancelled state and keep that text off the Result
+// pane. One binding of the shared boolean-flag family — see
+// tool-flag-anchors.ts for the model and the strip-and-lift rationale.
+
+import { toolFlagAnchorsOf } from "./tool-flag-anchors.js";
+
+const anchors = toolFlagAnchorsOf("cancelled");
+
+export const EMPTY_TOOL_CANCEL_ANCHORS = anchors.empty;
+export const toolCallCancelledOf = anchors.flagOf;
+export const withToolCancelAnchored = anchors.withAnchored;
+export const wellFormedToolCancelAnchorsOf = anchors.wellFormedOf;
+export const toolCancelRecorder = anchors.recorderOf;

package/src/core/tool-decision-anchors.ts

@@ -0,0 +1,108 @@
+// The tool-decision anchor set: the durable record that a call
+// carried a member decision, keyed by tool_call_id. The placement hold
+// reads THIS, never the pruned live card stores — the hold window is the
+// TURN. A pure fold over replayed CUSTOM markers: docs/decision-anchors.md.
+
+import type { AgentSubscriber } from "@ag-ui/client";
+
+import {
+  APPROVAL_REQUESTED_EVENT_NAME,
+  TOOL_EXECUTION_REQUESTED_EVENT_NAME,
+} from "../contract/events.js";
+// The kinds leaf, never execution-handlers: this module is a value
+// export of the ./transcript projection entry, and the handlers module
+// drags the transport/reader/affordance layers that entry's law bans
+// (tests/bundle-closure.test.ts pins it).
+import { MEMBER_ANSWERABLE_KINDS } from "./execution-kinds.js";
+
+export const EMPTY_TOOL_DECISION_ANCHORS: ReadonlySet<string> = new Set();
+
+/**
+ * Narrow a CUSTOM event to the tool call id it marks as decision-bearing,
+ * or null: an approval_requested with a tool_call_id, or a
+ * tool_execution_requested whose request.kind is member-answerable. Anything malformed is ignored — the contract's
+ * "clients MUST ignore events and fields they do not recognize". An
+ * unanchored ask (tool_call_id null — a wire that named no call) marks
+ * nothing: there is no row to hold open.
+ */
+export function toolDecisionAnchorOf(
+  name: string,
+  value: unknown,
+): string | null {
+  if (typeof value !== "object" || value === null) {
+    return null;
+  }
+  const record = value as Record<string, unknown>;
+  const toolCallId =
+    typeof record.tool_call_id === "string" && record.tool_call_id !== ""
+      ? record.tool_call_id
+      : null;
+  if (toolCallId === null) {
+    return null;
+  }
+  if (name === APPROVAL_REQUESTED_EVENT_NAME) {
+    return toolCallId;
+  }
+  if (name === TOOL_EXECUTION_REQUESTED_EVENT_NAME) {
+    const request = record.request;
+    if (typeof request !== "object" || request === null) {
+      return null;
+    }
+    const kind = (request as Record<string, unknown>).kind;
+    // MEMBER_ANSWERABLE_KINDS, not the single ask kind: the anchor marks
+    // "a member decision rode this call", and a future member-answerable
+    // kind must hold its row without a second edit here.
+    return typeof kind === "string" && MEMBER_ANSWERABLE_KINDS.has(kind)
+      ? toolCallId
+      : null;
+  }
+  return null;
+}
+
+/**
+ * Idempotent anchor merge: every connection replays the stream from its
+ * boundary (and StrictMode aborts and reruns the first connection), so
+ * the same marker can arrive more than once per mount. A repeat returns
+ * the set unchanged — identity is the publish gate.
+ */
+export function withToolDecisionAnchored(
+  previous: ReadonlySet<string>,
+  toolCallId: string,
+): ReadonlySet<string> {
+  if (previous.has(toolCallId)) {
+    return previous;
+  }
+  const next = new Set(previous);
+  next.add(toolCallId);
+  return next;
+}
+
+/**
+ * A defensive copy for seeding transcript state from the resume store:
+ * non-string members are dropped rather than rendered (or crashed on) —
+ * a dropped anchor reappears on the next full replay.
+ */
+export function wellFormedToolDecisionAnchorsOf(
+  stored: ReadonlySet<string>,
+): ReadonlySet<string> {
+  const seeded = new Set<string>();
+  for (const toolCallId of stored as ReadonlySet<unknown>) {
+    if (typeof toolCallId === "string") {
+      seeded.add(toolCallId);
+    }
+  }
+  return seeded;
+}
+
+export function toolDecisionRecorder(
+  onDecisionAnchored: (toolCallId: string) => void,
+): AgentSubscriber {
+  return {
+    onCustomEvent({ event }) {
+      const toolCallId = toolDecisionAnchorOf(event.name, event.value);
+      if (toolCallId !== null) {
+        onDecisionAnchored(toolCallId);
+      }
+    },
+  };
+}

package/src/core/tool-denial-anchors.ts

@@ -0,0 +1,145 @@
+// The tool-denial ledger: the durable record that a member
+// DECLINED the approval a call was paused for, keyed by tool_call_id. The
+// wire stamps a denial `cancelled`, so the state is a client-side JOIN of
+// the approval_requested and approval_resolved markers that reclassifies
+// that stamp. The ordering premises: docs/decision-anchors.md.
+
+import type { AgentSubscriber } from "@ag-ui/client";
+
+import {
+  APPROVAL_REQUESTED_EVENT_NAME,
+  APPROVAL_RESOLVED_EVENT_NAME,
+} from "../contract/events.js";
+import { approvalResolvedPayloadOf } from "./approval-resolved.js";
+
+/**
+ * The ledger's two halves: the ask map (interrupt id → the tool call an
+ * approval_requested named) and the denied set (tool call ids whose ask
+ * was answered approved:false). Only `denied` is presentation — the
+ * snapshot exposes it alone as `toolDenialAnchors`; `asks` exists so the
+ * fold can join a later resolution.
+ */
+export interface ToolDenialLedger {
+  asks: ReadonlyMap<string, string>;
+  denied: ReadonlySet<string>;
+}
+
+export const EMPTY_TOOL_DENIAL_LEDGER: ToolDenialLedger = {
+  asks: new Map(),
+  denied: new Set(),
+};
+
+/** The presentation half's empty value — what the projection reads when
+ *  a snapshot carries no ledger at all. */
+export const EMPTY_TOOL_DENIAL_ANCHORS: ReadonlySet<string> =
+  EMPTY_TOOL_DENIAL_LEDGER.denied;
+
+/** A narrowed marker the ledger folds: an ask, or a denial. */
+export type ToolDenialMarker =
+  | { kind: "ask"; interruptId: string; toolCallId: string }
+  | { kind: "denied"; interruptId: string };
+
+/**
+ * Narrow a CUSTOM event to the marker the ledger folds, or null: an
+ * approval_requested carrying both a non-empty interrupt_id and a
+ * non-empty tool_call_id (an unanchored ask — a wire that named no call
+ * — marks nothing: there is no row to reclassify), or an
+ * approval_resolved whose `approved` is false. An approval is not a
+ * marker here (the call then runs, and its own result tells its story).
+ * Anything malformed is ignored — the contract's "clients MUST ignore
+ * events and fields they do not recognize".
+ */
+export function toolDenialMarkerOf(
+  name: string,
+  value: unknown,
+): ToolDenialMarker | null {
+  if (name === APPROVAL_REQUESTED_EVENT_NAME) {
+    if (typeof value !== "object" || value === null) {
+      return null;
+    }
+    const record = value as Record<string, unknown>;
+    const interruptId = record.interrupt_id;
+    const toolCallId = record.tool_call_id;
+    if (
+      typeof interruptId !== "string" ||
+      interruptId === "" ||
+      typeof toolCallId !== "string" ||
+      toolCallId === ""
+    ) {
+      return null;
+    }
+    return { kind: "ask", interruptId, toolCallId };
+  }
+  if (name === APPROVAL_RESOLVED_EVENT_NAME) {
+    const resolved = approvalResolvedPayloadOf(value);
+    if (resolved === null || resolved.approved) {
+      return null;
+    }
+    return { kind: "denied", interruptId: resolved.interruptId };
+  }
+  return null;
+}
+
+/**
+ * The idempotent fold: every connection replays the stream from its
+ * boundary (and StrictMode aborts and reruns the first connection), so
+ * the same marker can arrive more than once per mount. A repeat — an
+ * ask already held, a denial already recorded — returns the ledger
+ * unchanged, and so does a denial whose interrupt no held ask names
+ * (premise 2). Otherwise the changed half is rebuilt and the untouched
+ * half keeps its identity: `denied`'s identity is the publish gate, so
+ * an ask alone never repaints the transcript.
+ */
+export function withToolDenialMarkerFolded(
+  ledger: ToolDenialLedger,
+  marker: ToolDenialMarker,
+): ToolDenialLedger {
+  if (marker.kind === "ask") {
+    if (ledger.asks.has(marker.interruptId)) {
+      return ledger;
+    }
+    const asks = new Map(ledger.asks);
+    asks.set(marker.interruptId, marker.toolCallId);
+    return { asks, denied: ledger.denied };
+  }
+  const toolCallId = ledger.asks.get(marker.interruptId);
+  if (toolCallId === undefined || ledger.denied.has(toolCallId)) {
+    return ledger;
+  }
+  const denied = new Set(ledger.denied);
+  denied.add(toolCallId);
+  return { asks: ledger.asks, denied };
+}
+
+/**
+ * A defensive copy for seeding transcript state from the resume store:
+ * non-string members are dropped rather than rendered (or crashed on) —
+ * a dropped anchor reappears on the next full replay.
+ */
+export function wellFormedToolDenialAnchorsOf(
+  stored: ReadonlySet<string>,
+): ReadonlySet<string> {
+  const seeded = new Set<string>();
+  for (const toolCallId of stored as ReadonlySet<unknown>) {
+    if (typeof toolCallId === "string") {
+      seeded.add(toolCallId);
+    }
+  }
+  return seeded;
+}
+
+/** Records the two approval markers, narrowed — CUSTOM events only; this
+ *  recorder never reads a tool result (the cancelled stamp it
+ *  reclassifies rides tool-cancel-anchors.ts, one rung below). */
+export function toolDenialRecorder(
+  onMarker: (marker: ToolDenialMarker) => void,
+): AgentSubscriber {
+  return {
+    onCustomEvent({ event }) {
+      const marker = toolDenialMarkerOf(event.name, event.value);
+      if (marker !== null) {
+        onMarker(marker);
+      }
+    },
+  };
+}