@teaflask/assistant 0.3.0 → 0.7.0

package/dist/core/approval-inbox.d.ts

@@ -15,12 +15,6 @@ export type ApprovalCardStatus = {
 } | {
     kind: "stale";
 };
-/** Who asked: the assistant's own card rides the stream's
- *  marker and the turn's own pending_approvals; a coworker's rides its
- *  DISPATCHING turn's REST snapshot (pending_coworker_approvals), is
- *  answered at that turn's door whatever the turn's status, and lives
- *  exactly as long as the snapshot lists it. label is the dispatch's
- *  brief excerpt — the card names the coworker with it. */
 export type ApprovalAsker = {
     kind: "assistant";
 } | {
@@ -28,102 +22,104 @@ export type ApprovalAsker = {
     ordinal: number;
     label: string;
 };
+/**
+ * One request for the visitor to approve or deny a tool or action call before
+ * it runs.
+ */
 export interface ApprovalCardModel {
-    /** The contract's opaque interrupt id — the card key and the submit id. */
+    /** Unique id of this request; use it as the React key. */
     interruptId: string;
+    /**
+     * Name of the tool waiting for approval (an action's is action__<slug>), or
+     * null when the request is not tied to a tool call.
+     */
     toolName: string | null;
-    /** The paused call's arguments, wire-faithful minus the reserved
-     *  `caption` key (the row's label, stripped at narrowing). Populated
-     *  but unread: the banner renders nothing argument-derived; the
-     *  transcript row carries the request. Kept like the schema pair
-     *  below: dropping a recorded consent fact from the model would be a
-     *  wire-shape decision, not a presentation one. */
+    /**
+     * What the agent passed to the call, without its short step caption. For an
+     * action, an object with path_params, query and body.
+     */
     toolArgs: Record<string, unknown>;
-    /** The paused tool's registered input schema. The generic card stays
-     *  schema-agnostic; this is the schema channel's card-side producer:
-     *  consumed by approvalCardSchemasOf (tool-schema-anchors)
-     *  through the store's card funnel, so a paused or denied call's view
-     *  still gets its argsSchema. */
+    /** JSON Schema of the tool's input, or null when the tool declares none. */
     toolInputSchema: Record<string, unknown> | null;
-    /** The paused tool's registered output schema, null when the tool
-     *  declares none; consumed the same way for the view
-     *  contract's resultSchema. */
+    /**
+     * JSON Schema of the tool's output, or null when the tool declares none.
+     */
     toolOutputSchema: Record<string, unknown> | null;
+    /**
+     * The reason approval is needed, from the approval rules that raised it.
+     * May be empty; show a generic line such as "This tool needs your approval"
+     * then.
+     */
     prompt: string;
+    /**
+     * Id of the tool call waiting for approval, matching its row in the
+     * transcript, or null when there is none.
+     */
     toolCallId: string | null;
-    /** True when the card's tool_call_id matched a streamed TOOL_CALL_START.
-     *  Stamped only under the `anchoring` capability; false otherwise. */
+    /**
+     * True when the waiting tool call has already appeared in the transcript on
+     * this connection, so the request can be shown beside that row.
+     */
     anchored: boolean;
+    /** Which step of the agent's run paused for this request. */
     round: number;
-    /** The server run that paused, stamped from the enclosing RUN_STARTED. */
+    /** Id of the agent run that paused for this request. */
     runId: string;
     /**
-     * True once the stream ended without a terminal: the turn parked and the
-     * assistant is no longer actively waiting, though the ask stays live.
+     * True when the agent has stopped actively waiting for an answer. The
+     * request can still be answered, and answering resumes the reply.
      */
     parked: boolean;
-    /** The locked action-approval gate raised this ask (the catalog's ask
-     *  policy): strictly per-call, no session trust can waive it. Stamped
-     *  only under the `gate` capability; false otherwise. */
+    /**
+     * True when this action is set to ask for approval on every call; trust
+     * cannot skip it, so don't offer "don't ask again".
+     */
     gated: boolean;
-    /** The card may offer approve-and-stop-asking (scoped to the asker's
-     *  session) — org hitl with trust enabled, never the gate. Absent on an
-     *  older wire → false, so
-     *  the affordance fails safe to hidden. Stamped only under the `trust`
-     *  capability; false otherwise — a door whose decision carries no
-     *  trust flag never grows the affordance. */
+    /**
+     * True when you may offer "approve and don't ask again" for this tool (send
+     * trust with the approval).
+     */
     trustAvailable: boolean;
+    /**
+     * Where the request stands. actionable means waiting for a decision (with
+     * the last failed submit's error sentence, or null), submitting means
+     * sending, answered carries the decision, and stale means it can no longer
+     * be answered (expired or answered elsewhere).
+     */
     status: ApprovalCardStatus;
+    /**
+     * Who is asking, the assistant itself or one of its sub-agents (with its
+     * number and a label taken from its task), so the card can name it.
+     */
     asker: ApprovalAsker;
-    /** The dispatching turn a coworker's decision is posted to; null for
-     *  the assistant's own cards, which the submit resolves by turn. */
+    /**
+     * For a sub-agent's request, the turn the decision is sent to; null for the
+     * assistant's own requests.
+     */
     turnId: string | null;
 }
-/**
- * A decision as the surface submits it. `trust` (approve AND stop asking
- * about this tool for the rest of the asker's session: the thread for the
- * assistant, that coworker's dispatch for a coworker) is only meaningful on
- * a card whose wire advertised trust_available under the `trust`
- * capability; ignored everywhere else.
- */
+/** The visitor's answer to one approval request, passed to submitDecision. */
 export interface ApprovalDecisionInput {
+    /** True to let the call run, false to deny it. */
     approved: boolean;
+    /**
+     * With an approval, also stop asking about this tool for the rest of the
+     * conversation (or, for a sub-agent's request, the rest of its task). Only
+     * honored when the card's trustAvailable is true and gated is false.
+     */
     trust?: boolean;
+    /**
+     * For a denial, optional text telling the agent why; it is passed to the
+     * agent along with the refusal.
+     */
     feedback?: string;
 }
-/**
- * The optional capabilities a host wires. Every one defaults
- * OFF: a host wiring none gets a working inbox with fewer powers — the
- * stream opens, answers and closes cards exactly the same — never a
- * demand for data its door cannot supply. The serving-door store turns
- * all three on (SERVING_APPROVAL_CAPABILITIES); the dashboard's
- * playground, whose internal door carries no trust flag and renders the
- * cards in one flat block, wires none.
- */
 export interface ApprovalInboxCapabilities {
-    /** Stamp `anchored` from streamed TOOL_CALL_STARTs — the suspension
-     *  queue's ordering and the row projection's settle join. Off:
-     *  noteToolCallStart records nothing and every card reads false. */
     anchoring?: boolean;
-    /** Carry the wire's `gated` flag onto cards (the banner's "asks every
-     *  time" note). Off: every card reads false. */
     gate?: boolean;
-    /** Carry the wire's `trust_available` flag onto cards (the banner's
-     *  approve-and-stop-asking control). Off: every card reads false, so
-     *  the affordance never renders. */
     trust?: boolean;
 }
-/** Every capability on — the serving door's shape. */
 export declare const SERVING_APPROVAL_CAPABILITIES: Required<ApprovalInboxCapabilities>;
-/**
- * The durable turn record as the inbox reads it — the seam a host's REST
- * read satisfies. Every pause field is OPTIONAL on purpose: the
- * serving turn carries all three, the dashboard's internal turn carries
- * them optional-by-default, and an older or partial door may
- * carry none. Absent is never read as empty — it means "no judgement",
- * so the inbox degrades to stream evidence alone rather than demanding a
- * record the host cannot supply.
- */
 export interface ApprovalTurnRecord extends CoworkerApprovalTurn {
     status: TurnStatus;
     pending_interrupt_ids?: readonly string[];
@@ -150,57 +146,11 @@ export declare class ApprovalInbox {
     settleSubmitAnswered(interruptId: string, approved: boolean, trusted?: boolean): boolean;
     settleSubmitError(interruptId: string, sentence: string): boolean;
     markPauseStale(): boolean;
-    /** A 409 for a coworker's decision speaks for that card alone. */
     markCoworkerCardStale(interruptId: string): boolean;
-    /** The member's send voids every paused coworker of the thread. */
     markCoworkerCardsStale(): boolean;
-    /**
-     * The REST recovery path: build cards from the turn record's
-     * pending_approvals snapshot — the same persisted markers the stream
-     * replays — so a failed stream fetch never strands a pending pause. Upsert
-     * only: a held card keeps its status and coordinates, nothing is removed
-     * (reconcile judges membership), the parked flag stays reconcile's job.
-     * Rounds below the run's newest are history, and a closed id never
-     * returns: a REST response that raced the stream's closing evidence would
-     * otherwise put live Approve/Deny on an ask that already executed.
-     * Independent of currentRunId: there may have been no stream at all.
-     */
     hydratePendingApprovals(turn: ApprovalTurnRecord | null): boolean;
-    /**
-     * The coworker approvals the turn snapshot lists, adopted: a
-     * card not held opens actionable, addressed to its dispatching turn; a
-     * held card re-reads its coworker's parked flag; a coworker card no turn
-     * lists anymore is gone (its row left paused). Bypasses the marker path's
-     * round arbitration — a coworker's round is its own — and remembers
-     * nothing it removes: "not in this window" is not monotonic evidence, so
-     * a later read may re-adopt (a re-POST after a real delist is the door's
-     * already_consumed receipt).
-     */
     adoptCoworkerApprovals(turns: readonly CoworkerApprovalTurn[]): boolean;
-    /**
-     * Re-judge the cards against the turn record — the lifetime authority,
-     * called on every REST read of the thread. Terminal turns
-     * close everything (except an in-flight submit, which settles itself);
-     * live turns stamp the parked flag from status; and where the contract
-     * makes pending_interrupt_ids meaningful (awaiting_input or parked,
-     * with a run captured), an actionable card the turn no longer holds
-     * goes visibly stale — never a silent vanish. Under queued/working the
-     * set is contractually empty, so membership is deliberately NOT judged
-     * there: a stale read racing a live marker must not kill a fresh card
-     * (stale has no return transition); the stream's own evidence closes
-     * those. Same tolerance for a card whose round is newer than the
-     * record's awaiting_round: the read predates the card.
-     */
     reconcileWithTurn(turn: ApprovalTurnRecord | null): boolean;
-    /**
-     * The settled turns' word: the assistant's cards whose run
-     * belongs to a turn with a terminal status are gone, whatever row is
-     * newest — the close a synthesized terminal cannot fake. The removal
-     * reads the ACCUMULATED runs, so a stale read still showing the pause
-     * rebuilds nothing. THE PREMISE: a turn's run_id is captured once and a
-     * terminal status is final, so a settled run never carries a live card
-     * again. Submitting cards settle themselves; coworker cards are exempt.
-     */
     reconcileWithTurns(turns: readonly Pick<ApprovalTurnRecord, "run_id" | "status">[]): boolean;
     cards(): readonly ApprovalCardModel[];
     statusOf(interruptId: string): ApprovalCardStatus["kind"] | null;
@@ -213,43 +163,8 @@ export declare class ApprovalInbox {
     private _transition;
 }
 export declare const ANSWER_NOT_SENT_SENTENCE = "That answer couldn't be sent. Please try again.";
-/** The turn holding the answerable pause, if any: the newest row when it
- *  pauses itself, else the newest answerable row behind it (a queued
- *  message can sit newer than the pause, and reading the queued row would
- *  silently miss the pause exactly when the member must answer to unblock
- *  the queue). Generic so each caller gets its own turn type back. */
 export declare function answerablePauseOf<T extends {
     status: TurnStatus;
 }>(turns: readonly T[]): T | null;
-/**
- * The durable turn record re-judges the pending approvals on every REST
- * read: hydration first — the record's pending_approvals snapshot rebuilds
- * any card the stream never delivered — then reconcile judges the whole
- * set, hydrated cards included. Two different rows on purpose: the pause
- * hydrates from the ANSWERABLE turn (a queued message can sit newer than
- * the pause), while reconcile keeps the NEWEST row (a terminal newest turn
- * is what removes the conversation's cards). The inbox's own guards absorb
- * what the read cannot know: closed ids never hydrate back, a round below
- * the run's newest is history, absent pause fields change nothing. The
- * settled-runs arm runs last over the whole window: a card
- * whose run belongs to any turn that settled is gone even while a newer
- * turn is live. Returns whether the visible cards changed.
- */
 export declare function reconcileApprovalsWithTurns(inbox: ApprovalInbox, turns: readonly ApprovalTurnRecord[]): boolean;
-/**
- * The subscriber that feeds the stream into the inbox: markers open cards,
- * receipts answer them, and the resume's own evidence or the settled turn's
- * word closes them — a RUN_FINISHED alone closes nothing. Only the
- * server-named run id from RUN_STARTED is trusted — the connect-run's
- * input.runId is the client's own and never names a recorded run.
- *
- * It also watches for the parked contract's quiet close, with the same
- * last-event-was-a-terminal flags as resumeSnapshotRecorder: lifecycle
- * events route to their dedicated handlers, everything else through
- * onEvent, and an errored or aborted pipeline routes through onRunFailed
- * before finalize — so a finalize where nothing failed and the last
- * applied event was not a terminal is a stream that simply ended. The
- * flags reset per run: one agent can be connected more than once.
- */
 export declare function approvalInboxRecorder(inbox: ApprovalInbox, onCardsChanged: (cards: readonly ApprovalCardModel[]) => void, onStreamClosedWithoutTerminal: () => void): AgentSubscriber;
-//# sourceMappingURL=approval-inbox.d.ts.map

package/dist/core/approval-inbox.js

@@ -7,37 +7,18 @@ const ACTIONABLE = {
     kind: "actionable",
     errorSentence: null,
 };
-/** Every capability on — the serving door's shape. */
 export const SERVING_APPROVAL_CAPABILITIES = { anchoring: true, gate: true, trust: true };
 export class ApprovalInbox {
     currentRunId = null;
     seenToolCallIds = new Set();
     cardList = [];
-    // Every interrupt id whose card this inbox removed — closing evidence
-    // (tool result, RUN_ERROR, round supersession, settled turn) spends
-    // an id forever, and REST hydration must not resurrect it from a stale
-    // read. Interrupt ids name one pause instance of one tool
-    // call, and every legitimate re-presentation of a pause (park restart,
-    // reconnect replay, fallback resume) happens while the card is still
-    // held or was never delivered — never after closing evidence — so a
-    // closed id can never be wrongly suppressed. Thread-lived like the
-    // inbox itself; one short string per closed ask, no eviction needed.
     closedInterruptIds = new Set();
-    // The runs of turns the record reported settled — monotonic
-    // like a closed id: nothing opens under one, nothing survives under one.
     settledRunIds = new Set();
     capabilities;
     constructor(capabilities = {}) {
         this.capabilities = capabilities;
     }
-    // --- the stream side -------------------------------------------------
     noteRunStarted(runId) {
-        // A new run is NOT closing evidence for other runs' cards: a parked
-        // turn's restarted workflow streams under a fresh run id while the
-        // replayed pause still names the old one, and the workflow's wait
-        // condition keeps sibling asks individually answerable. Cards die on
-        // their own evidence (receipt, result, RUN_ERROR) or on the durable
-        // turn record's word — never on another run merely beginning.
         this.currentRunId = runId;
         return false;
     }
@@ -49,26 +30,17 @@ export class ApprovalInbox {
     }
     noteApprovalRequested(payload) {
         if (this.currentRunId === null) {
-            // A marker outside any run segment is unanchorable — ignore it.
             return false;
         }
         const runId = this.currentRunId;
         if (this.settledRunIds.has(runId)) {
-            // A marker under a settled turn's run is history, not an ask.
             return false;
         }
         const held = this.cardList.find((card) => card.interruptId === payload.interrupt_id);
         if (held !== undefined) {
             if (held.asker.kind === "coworker") {
-                // A coworker's coordinates are the snapshot's, never a marker's.
                 return false;
             }
-            // A replayed marker for a card we already hold: keep the card's status
-            // — replay must never resurrect buttons on an answered card — but
-            // re-stamp the stream coordinates, so the run this replay serves under
-            // is the one whose closing evidence governs the card. ANY moved
-            // coordinate is a visible change: the submit path reads runId off the
-            // published card, and placement reads toolCallId/anchored.
             const toolCallId = payload.tool_call_id ?? null;
             const anchored = this._anchoredOf(toolCallId);
             const changed = held.runId !== runId ||
@@ -83,11 +55,8 @@ export class ApprovalInbox {
         }
         const newestRound = this._newestRoundOf(runId);
         if (newestRound !== null && payload.round < newestRound) {
-            // A lower round replaying after a later pause is history, not an ask.
             return false;
         }
-        // A higher round supersedes the run's earlier cards (round
-        // namespacing: multi-pause turns re-emit cards and must not collide).
         if (newestRound !== null && payload.round > newestRound) {
             this._removeWhere((card) => card.asker.kind === "assistant" &&
                 card.runId === runId &&
@@ -97,11 +66,6 @@ export class ApprovalInbox {
         return true;
     }
     noteApprovalResolved(interruptId, approved) {
-        // The receipt is the stream saying "answered" — on a replay it lands
-        // right after the marker it answers, so the card flips to answered in
-        // the same burst and buttons never resurrect on an already-answered
-        // ask. The gated call's result (or the settled turn's word) still
-        // closes the card later, exactly like the live path.
         return this._transition(interruptId, ["actionable", "submitting"], {
             kind: "answered",
             approved,
@@ -109,33 +73,15 @@ export class ApprovalInbox {
         });
     }
     noteToolCallResult(toolCallId) {
-        // The gated call producing a result is the resume made visible.
         return this._removeWhere((card) => card.toolCallId === toolCallId);
     }
     noteRunFinished() {
-        // Closes nothing by itself. THE PREMISE: the thread streamer
-        // synthesizes a RUN_FINISHED for the LIVE run right before re-entering
-        // an old run's segment for a late row, re-emits none of the live pause
-        // on the way back, and the frame is indistinguishable from a real
-        // terminal. A real finish closes through the gated call's result,
-        // RUN_ERROR (never synthesized) or the settled turn's word.
         return false;
     }
     noteRunError() {
-        // RUN_ERROR carries no runId — the run being narrated is the one that
-        // errored. Scoped to it on purpose: a replayed historical run's error
-        // must not wipe a carried live card from a newer pause. The errored
-        // turn's settled truth reaches the survivors on the next REST read.
         return this._removeWhere((card) => card.asker.kind === "assistant" && card.runId === this.currentRunId);
     }
     noteStreamClosedWithoutTerminal() {
-        // The parked contract's only wire signal: the stream just ends, with
-        // no terminal event. The open asks stay answerable — a late answer is
-        // the designed restart path — but their cards learn the assistant
-        // stopped actively waiting. A dropped connection takes this same
-        // transition (the wire shapes are identical); the conversation layer's
-        // REST confirm decides which it was, and either way the cards must
-        // survive.
         let changed = false;
         for (const card of this.cardList) {
             if (card.asker.kind === "assistant" &&
@@ -147,7 +93,6 @@ export class ApprovalInbox {
         }
         return changed;
     }
-    // --- the submit side ---------------------------------------------------
     beginSubmit(interruptId) {
         return this._transition(interruptId, ["actionable"], {
             kind: "submitting",
@@ -167,38 +112,18 @@ export class ApprovalInbox {
         });
     }
     markPauseStale() {
-        // A 409 speaks for the whole pause — the turn no longer awaits ANY of
-        // these answers, whatever run each card is stamped with. Answered
-        // cards keep their honest note. A coworker's card is not the turn's
-        // pause: its 409 is its own (markCoworkerCardStale).
         return this._staleWhere((card) => card.asker.kind === "assistant");
     }
-    /** A 409 for a coworker's decision speaks for that card alone. */
     markCoworkerCardStale(interruptId) {
         return this._staleWhere((card) => card.asker.kind === "coworker" && card.interruptId === interruptId);
     }
-    /** The member's send voids every paused coworker of the thread. */
     markCoworkerCardsStale() {
         return this._staleWhere((card) => card.asker.kind === "coworker");
     }
-    // --- the durable turn record -----------------------------------------------
-    /**
-     * The REST recovery path: build cards from the turn record's
-     * pending_approvals snapshot — the same persisted markers the stream
-     * replays — so a failed stream fetch never strands a pending pause. Upsert
-     * only: a held card keeps its status and coordinates, nothing is removed
-     * (reconcile judges membership), the parked flag stays reconcile's job.
-     * Rounds below the run's newest are history, and a closed id never
-     * returns: a REST response that raced the stream's closing evidence would
-     * otherwise put live Approve/Deny on an ask that already executed.
-     * Independent of currentRunId: there may have been no stream at all.
-     */
     hydratePendingApprovals(turn) {
         if (turn === null ||
             (turn.status !== "awaiting_input" && turn.status !== "parked") ||
             turn.run_id === null ||
-            // A server predating the field sends no array at all — an old
-            // wire, never an empty pause.
             !Array.isArray(turn.pending_approvals)) {
             return false;
         }
@@ -224,16 +149,6 @@ export class ApprovalInbox {
         }
         return changed;
     }
-    /**
-     * The coworker approvals the turn snapshot lists, adopted: a
-     * card not held opens actionable, addressed to its dispatching turn; a
-     * held card re-reads its coworker's parked flag; a coworker card no turn
-     * lists anymore is gone (its row left paused). Bypasses the marker path's
-     * round arbitration — a coworker's round is its own — and remembers
-     * nothing it removes: "not in this window" is not monotonic evidence, so
-     * a later read may re-adopt (a re-POST after a real delist is the door's
-     * already_consumed receipt).
-     */
     adoptCoworkerApprovals(turns) {
         let changed = false;
         const listed = new Set();
@@ -274,38 +189,17 @@ export class ApprovalInbox {
         }
         return changed;
     }
-    /**
-     * Re-judge the cards against the turn record — the lifetime authority,
-     * called on every REST read of the thread. Terminal turns
-     * close everything (except an in-flight submit, which settles itself);
-     * live turns stamp the parked flag from status; and where the contract
-     * makes pending_interrupt_ids meaningful (awaiting_input or parked,
-     * with a run captured), an actionable card the turn no longer holds
-     * goes visibly stale — never a silent vanish. Under queued/working the
-     * set is contractually empty, so membership is deliberately NOT judged
-     * there: a stale read racing a live marker must not kill a fresh card
-     * (stale has no return transition); the stream's own evidence closes
-     * those. Same tolerance for a card whose round is newer than the
-     * record's awaiting_round: the read predates the card.
-     */
     reconcileWithTurn(turn) {
         if (turn === null) {
             return false;
         }
-        // A coworker's card is exempt from every judgement below: its lifetime
-        // is the snapshot's (adoptCoworkerApprovals), and its dispatching turn
-        // is normally settled while it still awaits the member.
         if (isTerminalTurnStatus(turn.status)) {
             return this._removeWhere((card) => card.asker.kind === "assistant" && card.status.kind !== "submitting");
         }
         const parked = turn.status === "parked";
-        // Null where the record makes membership meaningless (or where an
-        // older door sends no set at all — absent is never empty).
         const pendingIds = _membershipIsJudgeable(turn)
             ? turn.pending_interrupt_ids
             : null;
-        // An absent awaiting_round (older door) reads like the null the
-        // serving door sends between pauses: no round to shield behind.
         const awaitingRound = turn.awaiting_round ?? null;
         let changed = false;
         for (const card of this.cardList) {
@@ -327,15 +221,6 @@ export class ApprovalInbox {
         }
         return changed;
     }
-    /**
-     * The settled turns' word: the assistant's cards whose run
-     * belongs to a turn with a terminal status are gone, whatever row is
-     * newest — the close a synthesized terminal cannot fake. The removal
-     * reads the ACCUMULATED runs, so a stale read still showing the pause
-     * rebuilds nothing. THE PREMISE: a turn's run_id is captured once and a
-     * terminal status is final, so a settled run never carries a live card
-     * again. Submitting cards settle themselves; coworker cards are exempt.
-     */
     reconcileWithTurns(turns) {
         for (const turn of turns) {
             if (isTerminalTurnStatus(turn.status) && turn.run_id !== null) {
@@ -346,7 +231,6 @@ export class ApprovalInbox {
             card.status.kind !== "submitting" &&
             this.settledRunIds.has(card.runId));
     }
-    // --- reading -------------------------------------------------------------
     cards() {
         return this.cardList.map((card) => ({ ...card }));
     }
@@ -354,9 +238,6 @@ export class ApprovalInbox {
         return (this.cardList.find((card) => card.interruptId === interruptId)?.status
             .kind ?? null);
     }
-    // --- internals -------------------------------------------------------------
-    // The one card constructor, shared by the stream marker and the REST
-    // snapshot so the two paths cannot drift.
     _cardFrom(payload, runId, ask) {
         const toolCallId = payload.tool_call_id ?? null;
         return {
@@ -372,21 +253,15 @@ export class ApprovalInbox {
             runId,
             parked: ask?.parked ?? false,
             gated: this.capabilities.gate === true && payload.gated,
-            // Either asker's, off the wire: a coworker's grant lands
-            // in its own session, so its card may offer what the record says.
             trustAvailable: this.capabilities.trust === true && payload.trust_available,
             status: ACTIONABLE,
             asker: ask?.asker ?? { kind: "assistant" },
             turnId: ask?.turnId ?? null,
         };
     }
-    // Anchoring is a capability: without it the set stays empty, so this
-    // reads false for every card — the flat-block host never anchors.
     _anchoredOf(toolCallId) {
         return toolCallId !== null && this.seenToolCallIds.has(toolCallId);
     }
-    // Round arbitration is the ASSISTANT's alone: a coworker's card carries
-    // the dispatching turn's run id with the CHILD's segment round.
     _newestRoundOf(runId) {
         const rounds = this.cardList
             .filter((card) => card.asker.kind === "assistant" && card.runId === runId)
@@ -412,8 +287,6 @@ export class ApprovalInbox {
         }
         return changed;
     }
-    // Removal is closing evidence: the removed ids are remembered so a
-    // stale REST snapshot can never hydrate them back.
     _removeWhere(doomed) {
         const kept = [];
         let changed = false;
@@ -441,26 +314,12 @@ export class ApprovalInbox {
         return true;
     }
 }
-// The execution driver's tolerances, mirrored: membership is
-// only meaningful where the contract fills the set — a paused turn with a
-// captured run. A null run_id is a lost capture (the server hides the
-// cards, the set reads empty), and a server predating the field sends no
-// array at all — absent must never read as empty. A type predicate, so
-// the caller reads the set only where this says it may.
 function _membershipIsJudgeable(turn) {
     return ((turn.status === "awaiting_input" || turn.status === "parked") &&
         turn.run_id !== null &&
         Array.isArray(turn.pending_interrupt_ids));
 }
-// The submit path's own failure sentence — reached only when the caller
-// cannot name any turn to answer at all, which a live pause makes
-// near-impossible.
 export const ANSWER_NOT_SENT_SENTENCE = "That answer couldn't be sent. Please try again.";
-/** The turn holding the answerable pause, if any: the newest row when it
- *  pauses itself, else the newest answerable row behind it (a queued
- *  message can sit newer than the pause, and reading the queued row would
- *  silently miss the pause exactly when the member must answer to unblock
- *  the queue). Generic so each caller gets its own turn type back. */
 export function answerablePauseOf(turns) {
     for (let index = turns.length - 1; index >= 0; index -= 1) {
         const turn = turns[index];
@@ -470,45 +329,14 @@ export function answerablePauseOf(turns) {
     }
     return null;
 }
-/**
- * The durable turn record re-judges the pending approvals on every REST
- * read: hydration first — the record's pending_approvals snapshot rebuilds
- * any card the stream never delivered — then reconcile judges the whole
- * set, hydrated cards included. Two different rows on purpose: the pause
- * hydrates from the ANSWERABLE turn (a queued message can sit newer than
- * the pause), while reconcile keeps the NEWEST row (a terminal newest turn
- * is what removes the conversation's cards). The inbox's own guards absorb
- * what the read cannot know: closed ids never hydrate back, a round below
- * the run's newest is history, absent pause fields change nothing. The
- * settled-runs arm runs last over the whole window: a card
- * whose run belongs to any turn that settled is gone even while a newer
- * turn is live. Returns whether the visible cards changed.
- */
 export function reconcileApprovalsWithTurns(inbox, turns) {
     const newest = turns[turns.length - 1] ?? null;
     const hydrated = inbox.hydratePendingApprovals(answerablePauseOf(turns));
-    // The coworkers' cards ride the same read: every turn in the
-    // window may be some paused coworker's dispatching turn.
     const adopted = inbox.adoptCoworkerApprovals(turns);
     const reconciled = inbox.reconcileWithTurn(newest);
     const settled = inbox.reconcileWithTurns(turns);
     return hydrated || adopted || reconciled || settled;
 }
-/**
- * The subscriber that feeds the stream into the inbox: markers open cards,
- * receipts answer them, and the resume's own evidence or the settled turn's
- * word closes them — a RUN_FINISHED alone closes nothing. Only the
- * server-named run id from RUN_STARTED is trusted — the connect-run's
- * input.runId is the client's own and never names a recorded run.
- *
- * It also watches for the parked contract's quiet close, with the same
- * last-event-was-a-terminal flags as resumeSnapshotRecorder: lifecycle
- * events route to their dedicated handlers, everything else through
- * onEvent, and an errored or aborted pipeline routes through onRunFailed
- * before finalize — so a finalize where nothing failed and the last
- * applied event was not a terminal is a stream that simply ended. The
- * flags reset per run: one agent can be connected more than once.
- */
 export function approvalInboxRecorder(inbox, onCardsChanged, onStreamClosedWithoutTerminal) {
     let endedAtTerminal = false;
     let failed = false;
@@ -569,4 +397,3 @@ export function approvalInboxRecorder(inbox, onCardsChanged, onStreamClosedWitho
         },
     };
 }
-//# sourceMappingURL=approval-inbox.js.map