@teaflask/assistant 0.3.0 → 0.7.0

package/dist/core/execution-driver.js

@@ -3,22 +3,8 @@ import { ServingApiError } from "../transport/serving-error.js";
 import { KIND_UNSUPPORTED_OUTCOME, MEMBER_ANSWERABLE_KINDS, } from "./execution-handlers.js";
 import { coworkerExecutionRequestOf, } from "./execution-inbox.js";
 import { MAX_DELIVERY_ATTEMPTS } from "./execution-kinds.js";
-// The driver that drains the execution inbox — the automatic half the
-// approval flow leaves to a human. Never inside an event callback: a
-// deferred pass lets a replay burst's own evidence (the receipt, the
-// gated call's result) close stale entries before anything acts, then a
-// REST read confirms the pause is genuinely open, the inbox claim takes
-// the entry, and the ledger makes the execution at-most-once even across
-// the remount a navigation causes.
 const EXECUTION_PASS_DELAY_MS = 400;
-// A failed POST retries on a slower cadence — the outcome is already in
-// the ledger, so only the delivery is being retried.
 const EXECUTION_RETRY_DELAY_MS = 2000;
-/**
- * One drain of the inbox's pending entries. Exported so the pass logic
- * unit-tests in node — the ExecutionDriver below is only a scheduler
- * around it.
- */
 export async function runExecutionPass(context) {
     const eligible = eligibleEntriesOf(context.inbox.entries(), context.attempts);
     if (eligible.length === 0) {
@@ -34,22 +20,13 @@ export async function runExecutionPass(context) {
 }
 function eligibleEntriesOf(entries, attempts) {
     return entries.filter((entry) => entry.status.kind === "pending" &&
-        // A member-answerable kind (builtin.ask_questions) is never the
-        // driver's to serve: auto-answering it — even as unsupported —
-        // would withdraw the ask. Its entry stays pending for the member's
-        // own submit and closes on stream evidence like every entry.
         !MEMBER_ANSWERABLE_KINDS.has(entry.kind) &&
         (attempts.get(entry.interruptId) ?? 0) < MAX_DELIVERY_ATTEMPTS);
 }
 async function _serveEntry(context, entry, turns) {
     const stored = readExecutedOutcome(context.threadId, entry.interruptId);
-    // The pause's holder is resolved across the WHOLE window, newest match
-    // first (there is no busy 409, so the answerable turn can sit
-    // behind QUEUED rows — "newest turn" is not "the pause").
     const holder = _theTurnStillHoldingThisPause(turns, entry);
     if (stored === null && holder === null) {
-        // REST is the acting authority, never the lifetime authority: the
-        // entry stays untouched and the stream's own evidence closes it.
         return;
     }
     if (!context.inbox.beginExecution(entry.interruptId)) {
@@ -57,31 +34,11 @@ async function _serveEntry(context, entry, turns) {
     }
     context.publishEntries(context.inbox.entries());
     const outcome = stored ?? (await _freshOutcomeOf(context, entry));
-    // A stored outcome with no live holder re-POSTs to the ORIGIN turn —
-    // the run the card came from — where the door's evidence arms
-    // (recorded_after_void / already_recorded) expect it; a queued newer
-    // member turn must never be guessed at (it would 409 and markRunStale
-    // would drop the executed result). The newest turn remains only the
-    // lost-capture fallback, backstopped by the door's own 409.
-    // THE PREMISE: a coworker's request has exactly ONE legal
-    // door — its dispatching turn. The door's coworker arms key on the
-    // coworker's ordinal across the whole thread and on the posted turn's
-    // own status, so a wrong turn is not backstopped by a 409 the way the
-    // assistant's newest-turn guess is: it can DELIVER under a pause that
-    // never asked, or record evidence under an unrelated run, and it would
-    // dodge the door's off-page refusal by naming an on-page turn. So a
-    // coworker's stored outcome re-POSTs to its dispatching turn or waits
-    // this pass — the entry stays pending; the row leaving paused delists it.
     const target = holder ??
         (entry.asker.kind === "coworker"
             ? turns.find((turn) => turn.id === entry.turnId)
             : (_theTurnOfThisEntriesRun(turns, entry) ?? turns.at(-1)));
     if (target === undefined) {
-        // Reachable only for a coworker's stored outcome whose dispatching turn
-        // is off the fetched window. Every arm that returns an entry to pending
-        // without a delivery counts an attempt (tests/driver-retry-arms): the
-        // driver's next pass then rides the retry cadence and the cap parks the
-        // entry for the next connection — a bounded wait, never a spin.
         _countDeliveryAttempt(context.attempts, entry.interruptId);
         if (context.inbox.settlePostFailed(entry.interruptId)) {
             context.publishEntries(context.inbox.entries());
@@ -103,8 +60,6 @@ function _theTurnOfThisEntriesRun(turns, entry) {
     return turns.find((turn) => turn.run_id === entry.runId);
 }
 async function _freshOutcomeOf(context, entry) {
-    // Claimed in the ledger before the handler runs: a tab dying mid-handler
-    // must read back as unknown-outcome, never as unexecuted.
     recordExecutionClaimed(context.threadId, entry.interruptId);
     const handler = context.handlers.get(entry.kind);
     const outcome = handler === undefined
@@ -123,8 +78,6 @@ async function _reportOutcome(context, entry, turnId, outcome) {
                     ...(outcome.ok
                         ? { result: outcome.result }
                         : { error: { ...outcome.error } }),
-                    // Names the coworker for a report that lands after its row
-                    // settled — the door's evidence arm reads it.
                     ...(entry.asker.kind === "coworker"
                         ? { coworker_ordinal: entry.asker.ordinal }
                         : {}),
@@ -132,22 +85,12 @@ async function _reportOutcome(context, entry, turnId, outcome) {
             ],
         });
         context.inbox.settleReported(entry.interruptId, outcome.ok);
-        // Delivery is asynchronous (the response's turn still says
-        // awaiting_input); on a live pause the stream's own resume closes the
-        // entry. A result that restarted a parked turn's workflow has no live
-        // stream to do that — reconnecting is what picks up the restarted run.
-        // The delivery field alone decides (the submit paths' law): a notice
-        // can accompany a DELIVERED restart too — the door pairs the
-        // oversize-drop notice with workflow_restarted — and skipping the
-        // reconnect there would freeze the transcript on the dead run.
         if (resolution.delivery === "workflow_restarted") {
             context.onWorkflowRestarted();
         }
     }
     catch (error) {
         if (_turnNoLongerAwaitingToolResults(error)) {
-            // Voided, settled, or answered elsewhere: the whole pause is over —
-            // or, for a coworker's request, that one request is.
             if (entry.asker.kind === "coworker") {
                 context.inbox.markCoworkerRequestStale(entry.interruptId);
             }
@@ -156,8 +99,6 @@ async function _reportOutcome(context, entry, turnId, outcome) {
             }
         }
         else {
-            // The POST failed, not the execution — pending again, and the next
-            // pass re-POSTs the stored outcome on the retry cadence.
             _countDeliveryAttempt(context.attempts, entry.interruptId);
             context.inbox.settlePostFailed(entry.interruptId);
         }
@@ -171,8 +112,6 @@ async function _outcomeNeverThrown(handler, entry) {
         return await handler(entry);
     }
     catch (error) {
-        // Handlers shape their own failures; this catches only a handler bug,
-        // and the turn must still resume.
         return {
             ok: false,
             error: {
@@ -186,22 +125,14 @@ async function _outcomeNeverThrown(handler, entry) {
 }
 async function _theTurnsOrNull(context) {
     try {
-        // The whole newest window, not just the newest row: a
-        // message during a live turn QUEUES, so the turn holding the pause
-        // is not necessarily the newest one.
         return (await context.fetchThreadDetail()).turns;
     }
     catch {
-        // A transient read failure: the entries stay pending and the next
-        // publish (or the next connection) schedules another pass.
         return null;
     }
 }
 function _turnStillHoldsThisPause(turn, entry) {
     if (entry.asker.kind === "coworker") {
-        // A coworker's request is held by its DISPATCHING turn, whatever that
-        // turn's status (normally settled), for as long as the snapshot lists
-        // it — the coworker's row leaving paused is what delists it.
         return (turn.id === entry.turnId &&
             (turn.pending_coworker_executions ?? []).some((raw) => coworkerExecutionRequestOf(raw)?.card.interrupt_id ===
                 entry.interruptId));
@@ -210,20 +141,12 @@ function _turnStillHoldsThisPause(turn, entry) {
     if (!stillAnswerable) {
         return false;
     }
-    // A null run_id is a lost capture — the server cannot locate the
-    // pause's cards either (pending_interrupt_ids reads empty), so the
-    // status gate alone holds and the door's own 409 backstops a stale
-    // guess.
     if (turn.run_id === null) {
         return true;
     }
     return (turn.run_id === entry.runId && _turnStillAwaitsThisInterrupt(turn, entry));
 }
 function _turnStillAwaitsThisInterrupt(turn, entry) {
-    // A replayed card from a superseded round must not act even though
-    // status and run still match. A server predating the field sends no
-    // array at all — that degrades to the status+run gate; an actual empty
-    // list means the pause moved on, so absent must never read as empty.
     return (!Array.isArray(turn.pending_interrupt_ids) ||
         turn.pending_interrupt_ids.includes(entry.interruptId));
 }
@@ -234,18 +157,8 @@ function _turnNoLongerAwaitingToolResults(error) {
 function _countDeliveryAttempt(attempts, interruptId) {
     attempts.set(interruptId, (attempts.get(interruptId) ?? 0) + 1);
 }
-/**
- * Schedules a drain whenever the inbox holds actionable entries. One pass
- * runs at a time; a signal that lands mid-pass queues exactly one
- * follow-up, so evidence arriving during a pass is never missed. The
- * timer dies with `dispose()`, but an in-flight pass runs to completion —
- * that is what carries the result POST across whatever tears the driver
- * down.
- */
 export class ExecutionDriver {
     deps;
-    /** Per-driver on purpose: exhausted entries stay pending for the NEXT
-     *  connection's driver (re-POST is the designed recovery). */
     attempts = new Map();
     passRunning = false;
     passQueued = false;
@@ -254,9 +167,6 @@ export class ExecutionDriver {
     constructor(deps) {
         this.deps = deps;
     }
-    /** Call with every published entries snapshot; each call resets the
-     *  pending timer, so the drain fires one quiet delay after the latest
-     *  evidence rather than racing a replay burst. */
     noteEntriesChanged(entries) {
         if (this.disposed) {
             return;
@@ -295,7 +205,6 @@ export class ExecutionDriver {
                     publishEntries: this.deps.publishEntries,
                     onWorkflowRestarted: this.deps.onWorkflowRestarted,
                 });
-                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- a timer firing mid-pass flips the flag during the await above
             } while (this.passQueued);
         }
         finally {
@@ -312,4 +221,3 @@ export class ExecutionDriver {
         }
     }
 }
-//# sourceMappingURL=execution-driver.js.map

package/dist/core/execution-handlers.d.ts

@@ -2,22 +2,8 @@ import type { ActionIntent } from "../contract/actions-adapter.js";
 import type { HttpIntentResult } from "../generated/models/index.js";
 import type { ExecutionEntryModel } from "./execution-inbox.js";
 export type ExecutionHandler = (entry: ExecutionEntryModel) => Promise<ExecutionOutcome>;
-/** How the host takes the visitor to an app-relative path. */
 export type HostNavigate = (path: string) => void | Promise<void>;
-/** How the provider's wired adapter executes one action intent. */
 export type ExecuteActionIntent = (intent: ActionIntent) => Promise<HttpIntentResult>;
 export { ASK_QUESTIONS_REQUEST_KIND, HIGHLIGHT_REQUEST_KIND, HTTP_INTENT_REQUEST_KIND, KIND_UNSUPPORTED_OUTCOME, MEMBER_ANSWERABLE_KINDS, NAVIGATE_REQUEST_KIND, PREFILL_FORM_REQUEST_KIND, READ_PAGE_REQUEST_KIND, type ExecutionOutcome, } from "./execution-kinds.js";
 import { type ExecutionOutcome } from "./execution-kinds.js";
-/**
- * The registry of kinds this mount can serve. A host that wired no
- * navigation hookup or actions adapter simply has no handler for that
- * kind — the driver answers the request with KIND_UNSUPPORTED_OUTCOME,
- * same as any kind this package has never heard of. read_page,
- * highlight, and prefill_form need no hookup at all: the package
- * operates on the page it is mounted in, so their handlers are always
- * present. threadId keys the reader's diff baseline —
- * the per-thread memory lives at module level in the reader, because
- * this map's identity churns with its React deps.
- */
 export declare function executionHandlersFor(navigate: HostNavigate | null, executeActionIntent: ExecuteActionIntent | null, threadId: string): ReadonlyMap<string, ExecutionHandler>;
-//# sourceMappingURL=execution-handlers.d.ts.map

package/dist/core/execution-handlers.js

@@ -1,13 +1,3 @@
-// What this client can execute, keyed by the request's kind —
-// builtin.navigate for the host's router hookup, http_intent for the
-// host's actions adapter, builtin.read_page / builtin.highlight /
-// builtin.prefill_form served by the package itself, and the seam any
-// future kind plugs into. A kind with no
-// handler here is answered with the canned unsupported error rather than
-// ignored: inside a single mount there is no other handler to defer to,
-// and silence would park the turn for the whole wait window. Every error
-// message is model-actionable prose telling the model what to do next —
-// never a stack, never text derived from customer content.
 import { spotlightElement } from "../affordances/highlight.js";
 import { prefilledFieldsReport, } from "../affordances/prefill.js";
 import { openCompanionDrawer } from "./companion-drawer-flag.js";
@@ -16,13 +6,6 @@ import { readPageResultOf, SnapshotUnavailableError, } from "../reader/read-page
 import { resolvedElementOfRef } from "../reader/snapshot.js";
 import { actionIntentOf } from "../transport/actions-adapter.js";
 import { boundedTextOf, doorCostOfText, doorLengthCeilingOf, } from "../transport/door-budget.js";
-// The kind vocabulary — and the outcome vocabulary with
-// the canned kind-unsupported refusal — lives in core/execution-kinds.ts
-// (a dependency-free leaf: the ./transcript projection
-// entry's decision-anchor family reads MEMBER_ANSWERABLE_KINDS, and
-// reading it through THIS module dragged the transport/reader/affordance
-// imports below into a closure whose law is transport-free). Re-exported
-// here so this module's consumers keep their one import site.
 export { ASK_QUESTIONS_REQUEST_KIND, HIGHLIGHT_REQUEST_KIND, HTTP_INTENT_REQUEST_KIND, KIND_UNSUPPORTED_OUTCOME, MEMBER_ANSWERABLE_KINDS, NAVIGATE_REQUEST_KIND, PREFILL_FORM_REQUEST_KIND, READ_PAGE_REQUEST_KIND, } from "./execution-kinds.js";
 import { HIGHLIGHT_REQUEST_KIND, HTTP_INTENT_REQUEST_KIND, NAVIGATE_REQUEST_KIND, PREFILL_FORM_REQUEST_KIND, READ_PAGE_REQUEST_KIND, } from "./execution-kinds.js";
 const UNUSABLE_PATH_OUTCOME = {
@@ -58,43 +41,10 @@ const UNUSABLE_FIELDS_OUTCOME = {
     },
 };
 const FAILURE_REASON_MAX_CHARS = 300;
-// Action failures are different from the page failures above: the reason
-// is the API's own refusal message, WRITTEN FOR THE MODEL (the server's
-// teach-back law — a 422 lists every offender, and the server budgets
-// that list to ~12k door units), never a host stack trace. Tersing it to
-// 300 chars would amputate the offender list the whole exchange exists
-// to deliver, so it rides a door-sized bound instead.
 const ACTION_FAILURE_REASON_MAX_ESCAPED_CHARS = 14_000;
-// Two 20k ceilings sit downstream of this error object, and the tighter
-// one is the carrier's: the tool-results door drops an error whose own
-// JSON passes 20k (toolresultv1.py TOOL_RESULT_JSON_MAX_CHARS) for its
-// canned too-large failure, whose instruction says the action ran; then
-// the server wraps the error in the interrupt envelope
-// `{"ok": false, "error": …, "instruction": "…"}` (failed_interrupt_
-// response_of) and the AG-UI mapper clips THAT text at 20k
-// (TOOL_RESULT_CONTENT_MAX_CHARS) — a clip mid-JSON collapses the whole
-// failure to the generic sentence. So the error object is fitted against
-// the cap less the envelope's proven overhead: 42 characters of frame
-// punctuation plus the 165-character canned instruction, 207 in all,
-// reserved at 1,024 for headroom (a longer instruction, the sanitizer's
-// longer replacement tokens). The fit is measured as the door measures:
-// the reason yields first, down to a floor that keeps the API's own
-// words, then the field list from its tail — on the sentence and the
-// detail together, since each field rides both.
 const ACTION_FAILURE_ENVELOPE_RESERVE_DOOR_CHARS = 1_024;
 const ACTION_FAILURE_PAYLOAD_MAX_DOOR_CHARS = 20_000 - ACTION_FAILURE_ENVELOPE_RESERVE_DOOR_CHARS;
 const ACTION_FAILURE_REASON_MIN_ESCAPED_CHARS = 2_000;
-/**
- * The registry of kinds this mount can serve. A host that wired no
- * navigation hookup or actions adapter simply has no handler for that
- * kind — the driver answers the request with KIND_UNSUPPORTED_OUTCOME,
- * same as any kind this package has never heard of. read_page,
- * highlight, and prefill_form need no hookup at all: the package
- * operates on the page it is mounted in, so their handlers are always
- * present. threadId keys the reader's diff baseline —
- * the per-thread memory lives at module level in the reader, because
- * this map's identity churns with its React deps.
- */
 export function executionHandlersFor(navigate, executeActionIntent, threadId) {
     const handlers = new Map();
     if (navigate !== null) {
@@ -109,8 +59,6 @@ export function executionHandlersFor(navigate, executeActionIntent, threadId) {
     return handlers;
 }
 async function _navigateOutcomeOf(navigate, entry) {
-    // The server's fence already validated the path; this narrowing is only
-    // wire defense, so its failure text stays canned.
     const path = _appRelativePathOf(entry.action);
     if (path === null) {
         return UNUSABLE_PATH_OUTCOME;
@@ -121,12 +69,7 @@ async function _navigateOutcomeOf(navigate, entry) {
     catch (error) {
         return _navigationFailedOutcome(path, error);
     }
-    // The visitor moved: the companion drawer is open at the destination.
-    // Never on a refused path or a throwing host — only a navigation that
-    // actually happened earns the conversation's return.
     openCompanionDrawer();
-    // The package synthesizes the contract's strict NavigateResult itself —
-    // a host callback can never malform the wire shape into a 422.
     const result = { navigated: true, path };
     return { ok: true, result: { ...result } };
 }
@@ -149,17 +92,12 @@ function _navigationFailedOutcome(path, error) {
     };
 }
 async function _httpIntentOutcomeOf(executeActionIntent, entry) {
-    // The server built the intent from the vetted catalog row; this
-    // narrowing is only wire defense, so its failure text stays canned and
-    // the adapter is never invoked on a shape it can't trust.
     const intent = actionIntentOf(entry.intent);
     if (intent === null) {
         return UNUSABLE_INTENT_OUTCOME;
     }
     try {
         const result = await executeActionIntent(intent);
-        // The package synthesizes the contract's strict HttpIntentResult
-        // itself — an adapter can never malform the wire shape into a 422.
         return { ok: true, result: { ...result } };
     }
     catch (error) {
@@ -170,13 +108,6 @@ function _actionFailedOutcome(intent, error) {
     const detail = _failureDetailOf(error);
     const reason = _failureFirstLineOf(error);
     let omitted = detail?.fieldsOmitted ?? 0;
-    // Every pass changes the candidate: the budget is clamped to the
-    // bounded reason's real door cost before it shrinks, so a decrement
-    // always drops at least one character, and a field drop is a change
-    // by itself. Passes are therefore bounded by the field count plus the
-    // reason's convergence — each reason pass removes at least a third of
-    // the overshoot (a removed unit costs the ceiling at least a third of
-    // what it cost the budget) — never by a budget's idle countdown.
     let reasonBudget = Math.min(ACTION_FAILURE_REASON_MAX_ESCAPED_CHARS, doorCostOfText(reason));
     let fields = detail?.fields;
     for (;;) {
@@ -199,8 +130,6 @@ function _actionFailedOutcome(intent, error) {
             reasonBudget = Math.max(ACTION_FAILURE_REASON_MIN_ESCAPED_CHARS, reasonBudget - over);
         }
         else if (fields !== undefined && fields.length > 1) {
-            // Never below one: the first problem plus the count of the rest
-            // always fits, and "and N more" keeps the list honest.
             fields = fields.slice(0, -1);
             omitted += 1;
         }
@@ -220,20 +149,11 @@ function _actionFailureErrorOf(intent, detail, reason) {
         ...(detail === null ? {} : { detail }),
     };
 }
-/** The status and code inside the sentence too — the mapper keeps only
- *  the sentence for the transcript's error channel, so the facts must
- *  survive in words ("HTTP 422 VALIDATION_ERROR — …"). */
 function _detailPrefixOf(detail) {
     return detail === null
         ? ""
         : `HTTP ${String(detail.status)} ${detail.code} — `;
 }
-/** The field clause's grammar, exact by construction: every path and
- *  message rides as a JSON string literal, so a colon, a semicolon or a
- *  quote inside the API's own words can never read as a delimiter, and a
- *  path-less problem is one bare literal — `"body.title": "Field
- *  required"; "Something: happened"`. The reader (view-dom.ts) tokenizes
- *  exactly this. */
 function _fieldProblemsSentenceOf(detail) {
     if (detail?.fields === undefined || detail.fields.length === 0) {
         return "";
@@ -248,38 +168,16 @@ function _fieldProblemsSentenceOf(detail) {
         : `; and ${String(detail.fieldsOmitted)} more`;
     return `Field problems: ${problems}${omitted}. `;
 }
-/** The bounds on what an adapter's typed error may add to the failure —
- *  per member; the whole payload is then fitted to the door's cap above. */
 const FAILURE_DETAIL_MAX_FIELDS = 20;
 const FAILURE_DETAIL_CODE_MAX_CHARS = 80;
 const FAILURE_DETAIL_FIELD_MAX_CHARS = 300;
-/** The one grammar a code must fit to ride the sentence whole: a
- *  whitespace-free token, whatever the API's casing or punctuation
- *  (VALIDATION_ERROR, doc.slug-taken, e42), so the reader's
- *  `HTTP <status> <code> — ` split (view-dom.ts) is exact. A code with
- *  whitespace fits no sentence: the detail is dropped whole and the
- *  reason still rides verbatim. */
 const FAILURE_CODE_TOKEN = /^\S{1,80}$/;
-/** A status the sentence can carry is an HTTP one — an integer in
- *  100–599, the reader's three-digit grammar (view-dom.ts). A host
- *  adapter's 0 (a network failure), a fraction or a made-up 1000 is no
- *  HTTP fact: the detail is dropped whole and the reason rides alone. */
 function _isHttpStatus(status) {
     return (typeof status === "number" &&
         Number.isInteger(status) &&
         status >= 100 &&
         status <= 599);
 }
-/**
- * The API's own account of the failure, read off the adapter's thrown
- * error when it is shaped like an HTTP error envelope — a numeric
- * `status` beside an `error: {code, message, details?}` record (the
- * shape teaflask's own dashboard client throws, and a natural one for
- * any adapter over a typed API). Duck-typed on purpose: the package
- * imports no host. `details` contributes only when it is a list of
- * `{path|loc|field, message|msg}` records; anything else is dropped,
- * never guessed at.
- */
 function _failureDetailOf(error) {
     if (typeof error !== "object" || error === null) {
         return null;
@@ -307,9 +205,6 @@ function _failureDetailOf(error) {
         ...(named.omitted > 0 ? { fieldsOmitted: named.omitted } : {}),
     };
 }
-/** The API's usable problems — the first FAILURE_DETAIL_MAX_FIELDS kept,
- *  the rest COUNTED, so the cap never passes a partial list off as the
- *  whole. Null when the API named none. */
 function _failureFieldsOf(details) {
     if (!Array.isArray(details)) {
         return null;
@@ -352,9 +247,6 @@ function _fieldPathOf(path) {
     }
     return "";
 }
-/** A field's path or message as the sentence can carry it: one line,
- *  whitespace runs collapsed, bounded — the same text rides the JSON
- *  detail, so the two carriers never disagree. */
 function _sentenceTextOf(text) {
     return text
         .replace(/\s+/g, " ")
@@ -363,9 +255,6 @@ function _sentenceTextOf(text) {
 }
 function _readPageOutcomeOf(threadId, entry) {
     try {
-        // The package synthesizes the contract's strict ReadPageResult
-        // itself (readPageResultOf bounds every field) — nothing here can
-        // malform the wire shape into a 422.
         const result = readPageResultOf(threadId, entry.action, browserLayoutProbe());
         return Promise.resolve({ ok: true, result: { ...result } });
     }
@@ -374,10 +263,6 @@ function _readPageOutcomeOf(threadId, entry) {
     }
 }
 function _readPageFailedOutcome(error) {
-    // An expected refusal (stale ref, unmatched selector) already carries
-    // the reader's own model-actionable sentence — deliver it verbatim;
-    // "ask the user instead" would cancel the retry it asks for. Only a
-    // genuine reader crash earns the give-up wrapper.
     if (error instanceof SnapshotUnavailableError) {
         return {
             ok: false,
@@ -394,16 +279,12 @@ function _readPageFailedOutcome(error) {
     };
 }
 function _highlightOutcomeOf(entry) {
-    // The server sent the ref through verbatim; this narrowing is only
-    // wire defense, so its failure text stays canned.
     const refId = _refIdOf(entry.action);
     if (refId === null) {
         return UNUSABLE_REF_OUTCOME;
     }
     const resolved = resolvedElementOfRef(refId);
     if (resolved.error !== null) {
-        // The reader's own refusal (stale ref, curated subtree) is already
-        // model-actionable — deliver it verbatim, same as read_page does.
         return {
             ok: false,
             error: { code: "execution_failed", message: resolved.error },
@@ -415,8 +296,6 @@ function _highlightOutcomeOf(entry) {
     catch (error) {
         return _highlightFailedOutcome(error);
     }
-    // The package synthesizes the contract's strict HighlightResult
-    // itself — nothing here can malform the wire shape into a 422.
     const result = { highlighted: true, ref_id: refId };
     return { ok: true, result: { ...result } };
 }
@@ -438,16 +317,11 @@ function _highlightFailedOutcome(error) {
     };
 }
 function _prefillFormOutcomeOf(entry) {
-    // The server validated the fields' shape before pausing; this
-    // narrowing is only wire defense, so its failure text stays canned.
     const fields = _prefillFieldsOf(entry.action);
     if (fields === null) {
         return UNUSABLE_FIELDS_OUTCOME;
     }
     try {
-        // The package synthesizes the contract's strict PrefillFormResult
-        // itself (every refusal reason is the package's own prose) — nothing
-        // here can malform the wire shape into a 422.
         const result = prefilledFieldsReport(fields);
         return { ok: true, result: { ...result } };
     }
@@ -486,16 +360,10 @@ function _prefillFailedOutcome(error) {
     };
 }
 function _reasonSentenceOf(error) {
-    // The host error's own first line, sliced for READABILITY in raw
-    // characters — these callers' errors (navigation, page operations) sit
-    // far under any door, so the bound exists to tame stack-trace-shaped
-    // messages, and a non-ASCII host error keeps its full 300 characters.
     return _failureFirstLineOf(error).slice(0, FAILURE_REASON_MAX_CHARS);
 }
 function _failureFirstLineOf(error) {
-    // A reason the model can act on, never a stack trace.
     const message = error instanceof Error ? error.message : String(error);
     const firstLine = message.split("\n", 1)[0].trim();
     return firstLine === "" ? "an unknown error" : firstLine;
 }
-//# sourceMappingURL=execution-handlers.js.map

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

@@ -13,9 +13,6 @@ export type ExecutionEntryStatus = {
 } | {
     kind: "stale";
 };
-/** Who asked: the assistant's own request rides the stream's
- *  marker; a coworker's rides its DISPATCHING turn's REST snapshot
- *  (pending_coworker_executions) and is answered at that turn's door. */
 type ExecutionAsker = {
     kind: "assistant";
 } | {
@@ -23,41 +20,23 @@ type ExecutionAsker = {
     ordinal: number;
 };
 export interface ExecutionEntryModel {
-    /** The contract's opaque interrupt id — the entry key and the report id. */
     interruptId: string;
     toolName: string;
     toolCallId: string | null;
-    /** True when the request's own tool row already streamed. An anchored
-     *  ask is ordered in the suspension queue by its row and settled on it
-     *  by the row projection (the approval cards' anchored/orphan split;
-     *  only member-answerable kinds render cards, but the fact is stream
-     *  evidence and lives here with the rest). */
     anchored: boolean;
-    /** The request's open, additive kind vocabulary (e.g. builtin.navigate). */
     kind: string;
-    /** The request's action payload, verbatim from the wire. */
     action: Record<string, unknown> | null;
-    /** The request's server-built intent payload, verbatim from the wire. */
     intent: Record<string, unknown> | null;
     round: number;
-    /** The server run that paused, stamped from the enclosing RUN_STARTED —
-     *  for a coworker's request, the dispatching turn's run. */
     runId: string;
     status: ExecutionEntryStatus;
     asker: ExecutionAsker;
-    /** The dispatching turn a coworker's result is posted to; null for the
-     *  assistant's own requests, which the driver resolves by run. */
     turnId: string | null;
 }
-/** The turn fields the settled-run reconcile reads. The status is the
- *  generated union, never bare string: a renamed status word in the spec
- *  must fail the compile here, not silently stop closing that run's
- *  entries (contract/dispatches.ts states the rule for the ledger). */
 export interface SettledRunView {
     run_id: string | null;
     status: TurnStatus;
 }
-/** Narrow a tool_result_recorded CUSTOM event's wire value. */
 export declare function toolResultRecordedPayloadOf(value: unknown): {
     interruptId: string;
     ok: boolean;
@@ -71,24 +50,12 @@ export declare class ExecutionInbox {
     noteRunStarted(runId: string): boolean;
     noteToolCallStart(toolCallId: string): boolean;
     noteExecutionRequested(payload: ToolExecutionRequestedPayload): boolean;
-    /**
-     * The coworker requests the turn snapshot lists, adopted: a card not
-     * held opens a pending entry addressed to its dispatching turn; a held
-     * pending entry the stream delivered first is re-labelled; a coworker
-     * entry no turn lists anymore is gone (its row left paused). Bypasses
-     * the marker path's round arbitration — a coworker's round is its own.
-     */
     adoptCoworkerRequests(turns: readonly CoworkerRequestTurn[]): boolean;
-    /** A 409 for a coworker's request speaks for that request alone. */
     markCoworkerRequestStale(interruptId: string): boolean;
-    /** The member's send voids every paused coworker of the thread. */
     markCoworkerRequestsStale(): boolean;
     noteToolResultRecorded(interruptId: string, ok: boolean): boolean;
     noteToolCallResult(toolCallId: string): boolean;
     noteRunFinished(): boolean;
-    /** The durable turn record's word: the assistant's entries
-     *  whose run belongs to a SETTLED turn are gone — the REST-driven close a
-     *  synthesized terminal cannot fake. */
     reconcileWithTurns(turns: readonly SettledRunView[]): boolean;
     noteRunError(): boolean;
     beginExecution(interruptId: string): boolean;
@@ -102,17 +69,4 @@ export declare class ExecutionInbox {
     private _removeWhere;
     private _transition;
 }
-/**
- * The subscriber that feeds the stream into the inbox: markers open
- * entries, receipts report them, and the resume's own evidence closes
- * them. 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.
- *
- * A quiet close needs nothing from this recorder: an open entry survives
- * it untouched, because nothing about being answerable depends on whether
- * the turn parked. The REST consult that tells a park from a dropped
- * connection, and the go/no-go it drives, stay the approval recorder's.
- */
 export declare function executionInboxRecorder(inbox: ExecutionInbox, onEntriesChanged: (entries: readonly ExecutionEntryModel[]) => void): AgentSubscriber;
-//# sourceMappingURL=execution-inbox.d.ts.map