@teaflask/assistant 0.3.0 → 0.6.0

package/dist/core/approval-decision.js

@@ -1,8 +1,3 @@
-// Answering approvals: the one POST per decision, under the
-// self-narration law (attempted, sent, and every drop with its
-// reason), with the durable-turn-first target resolution the execution
-// driver also follows. turnIdAnsweredBy is exported for the elicitation
-// submit, its documented twin.
 import { resolveTurnApproval } from "../transport/serving-api.js";
 import { ServingApiError } from "../transport/serving-error.js";
 import { ANSWER_NOT_SENT_SENTENCE, } from "./approval-inbox.js";
@@ -10,17 +5,10 @@ import { publishApprovalCards } from "./epoch-sync.js";
 import { userSentenceFor } from "./error-copy.js";
 export async function submitApprovalDecisionFromStore(store, card, decision) {
     const active = store._active;
-    // Only a card that advertised the affordance may speak trust — the
-    // door degrades a stray token to a plain approval anyway; this keeps
-    // the wire honest from here.
     const trusting = decision.trust === true && !card.gated && card.trustAvailable;
     const telemetry = _approvalTelemetryOf(store, card, decision, trusting, active);
     telemetry("approval_submit_attempted");
-    // No epoch gate here on purpose: the POST needs only session + thread
-    // + inbox, and a parked turn legitimately holds no socket.
     if (active === null) {
-        // Should be impossible while a card renders (cards come from the
-        // active thread's inbox) — say so loudly instead of swallowing it.
         telemetry("approval_submit_dropped", "no_active_thread");
         store.deps.reportError(new Error(`Approval decision dropped: no active conversation to answer into (interrupt ${card.interruptId}).`));
         return;
@@ -30,13 +18,6 @@ export async function submitApprovalDecisionFromStore(store, card, decision) {
         _explainBeginSubmitRefusal(store, inbox, card, telemetry);
         return;
     }
-    // Confine every shared-cell write to this submit's own inbox: a
-    // thread switch during the POST replaces the active conversation, and
-    // publishing the resolved OLD inbox's cards would stamp a foreign
-    // approval onto the now-active thread until its stream next publishes.
-    // Deliberately the INBOX's identity, not the epoch's or _active's: a
-    // reconnect (or any refresh) on the same thread keeps this inbox, and
-    // the submit's progress must keep rendering straight through it.
     const publishIfCurrent = () => {
         if (store._active?.approvalInbox === inbox) {
             publishApprovalCards(store, inbox.cards());
@@ -48,11 +29,6 @@ export async function submitApprovalDecisionFromStore(store, card, decision) {
     }
     catch (error) {
         if (_turnNoLongerAwaiting(error)) {
-            // Timed out, or answered in another tab: the whole pause is over.
-            // Re-read the thread for its settled truth (busy flag, and the
-            // timeout sentence rides the failure banner). A coworker's 409
-            // speaks for its card alone — the turn's own pause,
-            // if any, is untouched.
             if (card.asker.kind === "coworker") {
                 inbox.markCoworkerCardStale(card.interruptId);
             }
@@ -85,20 +61,12 @@ function _approvalTelemetryOf(store, card, decision, trusting, active) {
         });
     };
 }
-// beginSubmit refused: the rendered card lagged the live one, or the
-// first submit is already in flight — narrate the drop and, when the live
-// truth moved, re-read it so reconciliation visibly settles what the user
-// is seeing.
 function _explainBeginSubmitRefusal(store, inbox, card, telemetry) {
     const liveKind = inbox.statusOf(card.interruptId);
     if (liveKind === "submitting") {
-        // A benign double-click: the first submit is in flight and the
-        // live card already renders its spinner.
         telemetry("approval_submit_dropped", "already_submitting");
         return;
     }
-    // The rendered card lagged the live one — re-read the durable
-    // truth so reconciliation visibly settles what the user is seeing.
     telemetry("approval_submit_dropped", liveKind === "answered"
         ? "not_actionable_answered"
         : liveKind === "stale"
@@ -108,11 +76,7 @@ function _explainBeginSubmitRefusal(store, inbox, card, telemetry) {
         void store.refreshConversation();
     }
 }
-// The POST itself and its delivery arms — target resolution, the one
-// answer per POST, and what each delivery verdict means for the pause.
 async function _postApprovalDecision(store, active, inbox, card, decision, trusting, telemetry) {
-    // A coworker's card has exactly one door — its dispatching turn,
-    // whatever that turn's status (the execution driver's rule).
     const turnId = card.asker.kind === "coworker"
         ? card.turnId
         : await _turnIdAwaitingInterrupt(store, card, active);
@@ -122,8 +86,6 @@ async function _postApprovalDecision(store, active, inbox, card, decision, trust
         return;
     }
     telemetry("approval_submit_sent");
-    // One answer per POST — sibling cards stay individually actionable,
-    // and the workflow resumes once every pending ask is answered.
     const resolution = await resolveTurnApproval(store.deps.session, active.thread.id, turnId, {
         approvals: [
             {
@@ -136,56 +98,16 @@ async function _postApprovalDecision(store, active, inbox, card, decision, trust
             },
         ],
     });
-    // Delivery is asynchronous (the response's turn still says
-    // awaiting_input); on a live pause the stream's own resume closes
-    // the card. An answer that restarted a parked turn's workflow has
-    // no live stream to do that — reconnecting is what picks up the
-    // restarted run (and its approval_resolved receipt keeps the
-    // replayed card answered).
     inbox.settleSubmitAnswered(card.interruptId, decision.approved, trusting);
-    if (
-    // Confined like every post-await read: the reclaim probes exist
-    // to un-freeze the conversation being VIEWED, and after a
-    // mid-POST thread switch there is nothing here to un-freeze —
-    // reopening the thread reconnects on adoption, while the probes
-    // would bounce the other thread's epoch for nothing.
-    store._active?.approvalInbox === inbox) {
+    if (store._active?.approvalInbox === inbox) {
         if (resolution.delivery === "workflow_restarted") {
             store.handleWorkflowRestarted();
         }
         else if (resolution.delivery === "already_consumed") {
-            // The receipt: the answer is already past the door —
-            // the turn's own once a resume consumed it and then died parked, or
-            // a coworker's once its row left paused with the decision
-            // recorded, or paused again at a newer round — nothing
-            // was restarted, so no reconnect will ever arrive to move the
-            // conversation past this pause.
-            // Re-read the turn for its
-            // current truth (the contract's instruction): the refreshed
-            // projection subtracts consumed ids, so the pause
-            // retires instead of rendering a wait nothing will resume.
             void store.refreshConversation();
         }
     }
 }
-// The turn to answer, resolved durable-turn-first (the execution
-// driver's stance): the newest turn that still awaits this interrupt
-// names the POST's target — which stays correct after a park-restart,
-// when the card's stamped run id names a run the ledger never saw. One
-// refresh covers a stale read; a queued message can sit
-// NEWER than the pause, so the refreshed check also consults the
-// newest ANSWERABLE turn, not just the newest row. The CAPTURED
-// conversation's ledger remains as the fallback (absent
-// pending_interrupt_ids must never read as empty, and the door's own
-// 409 backstops a wrong guess).
-//
-// Confinement (the publishIfCurrent law): the first _newestTurn read
-// runs before any await in the submit, so it still belongs to the
-// captured conversation; every read AFTER the refresh trusts the
-// store-global turn only while the submit's inbox is still the active
-// one — a thread switch mid-refresh would otherwise resolve thread B's
-// turn id and POST it to thread A's approval URL. The captured ledger
-// is switch-proof by construction.
 async function _turnIdAwaitingInterrupt(store, card, active) {
     if (_turnAwaitsInterrupt(store._newestTurn, card.interruptId)) {
         return store._newestTurn?.id ?? null;
@@ -202,14 +124,6 @@ async function _turnIdAwaitingInterrupt(store, card, active) {
     const ledger = active.ledger;
     return (ledger.turnForRun(card.runId) ?? ledger.newestTurn())?.turnId ?? null;
 }
-// The elicitation submit's twin of _turnIdAwaitingInterrupt: the
-// ledger names the pausing run when it can; a lost capture (or
-// another tab's send) refreshes and then consults the ANSWERABLE turn
-// — a queued message can sit newer than the pause, so
-// the ledger's newest record may be a QUEUED turn whose POST would
-// 409. Same confinement as the sibling: store-global turns are
-// trusted only while this submit's inbox is still the active one.
-// ledger.newestTurn() stays the last resort, 409-backstopped.
 export async function turnIdAnsweredBy(store, active, card) {
     const ledger = active.ledger;
     const known = ledger.turnForRun(card.runId);
@@ -231,16 +145,6 @@ export async function turnIdAnsweredBy(store, active, card) {
     }
     return ledger.newestTurn()?.turnId ?? null;
 }
-// The sibling of the execution driver's durable-turn guard: a
-// turn is answerable iff it still pauses (awaiting_input or parked — a
-// late answer restarts a parked turn) and still holds the interrupt. Two
-// tolerances mirror the driver's: a null run_id is a lost capture, where
-// the server hides the cards (the set reads empty though the pause is
-// real), so the status gate alone holds; and a server predating
-// pending_interrupt_ids sends no array at all, which degrades to the
-// status gate too — an actual empty list under a captured run means the
-// pause moved on, so absent must never read as empty. A wrong yes is
-// backstopped by the door's own 409.
 function _turnAwaitsInterrupt(turn, interruptId) {
     if (turn === null) {
         return false;
@@ -256,4 +160,3 @@ function _turnNoLongerAwaiting(error) {
     return (error instanceof ServingApiError &&
         error.code === "ASSISTANT_TURN_NOT_AWAITING_APPROVAL");
 }
-//# sourceMappingURL=approval-decision.js.map

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";
 } | {
@@ -29,101 +23,34 @@ export type ApprovalAsker = {
     label: string;
 };
 export interface ApprovalCardModel {
-    /** The contract's opaque interrupt id — the card key and the submit id. */
     interruptId: string;
     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. */
     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. */
     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. */
     toolOutputSchema: Record<string, unknown> | null;
     prompt: string;
     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. */
     anchored: boolean;
     round: number;
-    /** The server run that paused, stamped from the enclosing RUN_STARTED. */
     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.
-     */
     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. */
     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. */
     trustAvailable: boolean;
     status: ApprovalCardStatus;
     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. */
     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.
- */
 export interface ApprovalDecisionInput {
     approved: boolean;
     trust?: boolean;
     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 +77,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 +94,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