@sema-agent/core 7.48.0 → 7.49.0

package/dist/core/runner/terminal-account.js

@@ -0,0 +1,186 @@
+import { MODEL_OUTPUT_INVALID_CAUSES } from "../../internal/llm.js";
+import { isProviderEchoShape } from "../../brain/errors.js";
+import { isProviderCondition, isProviderConditionSource } from "../../brain/provider-dialect.js";
+import { admittedRequestRoute } from "../../brain/request-route.js";
+import { readMember } from "../thrown-value.js";
+import { redactSecrets } from "../untrusted-egress.js";
+import { isSensitiveName, looksLikeCredentialValue } from "../secret-env.js";
+import { isSensitiveRecordKey } from "../credential-vocabulary.js";
+export function providerVerdictOf(final) {
+    const condition = readMember(final, "providerCondition");
+    const source = readMember(final, "providerConditionSource");
+    if (!isProviderCondition(condition) || !isProviderConditionSource(source))
+        return {};
+    const resetAtMs = readMember(final, "providerResetAtMs");
+    return { providerCondition: condition, providerConditionSource: source, ...(typeof resetAtMs === "number" && Number.isFinite(resetAtMs) ? { providerResetAtMs: resetAtMs } : {}) };
+}
+export function requestRouteOfMessage(final) {
+    return admittedRequestRoute(readMember(final, "apiErrorRoute"));
+}
+const MODEL_OUTPUT_INVALID_CAUSE_SET = new Set(MODEL_OUTPUT_INVALID_CAUSES);
+const countOf = (v) => (typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : undefined);
+export function modelOutputInvalidOfMessage(final) {
+    const account = readMember(final, "modelOutputInvalid");
+    const cause = readMember(account, "cause");
+    if (!MODEL_OUTPUT_INVALID_CAUSE_SET.has(cause))
+        return undefined;
+    const limit = cause === "truncated" ? readMember(account, "outputLimit") : undefined;
+    const capStop = readMember(limit, "capStop");
+    if (typeof capStop !== "boolean")
+        return { cause: cause };
+    const outputTokens = countOf(readMember(limit, "outputTokens"));
+    const capTokens = countOf(readMember(limit, "capTokens"));
+    const outputLimit = { capStop, ...(outputTokens !== undefined ? { outputTokens } : {}), ...(capTokens !== undefined ? { capTokens } : {}) };
+    return { cause: cause, outputLimit };
+}
+const CODED_DETAIL_DEPTH = 4;
+const CODED_DETAIL_ENTRIES = 64;
+const CODED_DETAIL_STRING = 4_096;
+const CODED_DETAIL_VALUES = 256;
+const CODED_DETAIL_CHARS = 16_384;
+const REDACTED = "[redacted]";
+const INDEX_KEY_RE = /^(?:0|[1-9][0-9]*)$/;
+function carriesCredential(text) {
+    return looksLikeCredentialValue(text) || redactSecrets(text) !== text;
+}
+const NAME_CHARS = 128;
+function namesCredential(name) {
+    return name.length <= NAME_CHARS && (isSensitiveName(name) || isSensitiveRecordKey(name));
+}
+const NAME_POSITION_KEYS = new Set(["name", "key", "header", "field"]);
+const VALUE_POSITION_KEYS = new Set(["value", "val"]);
+function charge(budget, chars) {
+    if (budget.values >= CODED_DETAIL_VALUES || budget.chars + chars > CODED_DETAIL_CHARS)
+        return false;
+    budget.values++;
+    budget.chars += chars;
+    return true;
+}
+function leafOf(keyContext, read, depth, budget) {
+    if (keyContext !== undefined && namesCredential(keyContext))
+        return charge(budget, REDACTED.length) ? REDACTED : undefined;
+    const value = read();
+    if (value === null || typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value)))
+        return charge(budget, 0) ? value : undefined;
+    if (typeof value === "string") {
+        if (value.length > CODED_DETAIL_STRING)
+            return undefined;
+        const shown = carriesCredential(value) ? REDACTED : value;
+        return charge(budget, shown.length) ? shown : undefined;
+    }
+    if (typeof value !== "object" || depth >= CODED_DETAIL_DEPTH)
+        return undefined;
+    let isArray;
+    try {
+        if (ArrayBuffer.isView(value))
+            return undefined;
+        isArray = Array.isArray(value);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isArray)
+        return recordOf(value, depth, budget);
+    const length = readMember(value, "length");
+    if (typeof length !== "number" || !Number.isInteger(length) || length < 0 || length > CODED_DETAIL_ENTRIES)
+        return undefined;
+    if (!charge(budget, 0))
+        return undefined;
+    const items = [];
+    const handed = Array.from({ length }, (_, i) => readMember(value, String(i)));
+    for (let i = 0; i < length; i++) {
+        const before = handed[i - 1];
+        const item = leafOf(typeof before === "string" && namesCredential(before) ? before : keyContext, () => handed[i], depth + 1, budget);
+        if (item === undefined)
+            return undefined;
+        items.push(item);
+    }
+    return items;
+}
+function pairedNameOf(value, keys, read) {
+    if (!keys.some((k) => VALUE_POSITION_KEYS.has(k.toLowerCase())))
+        return undefined;
+    let named;
+    for (const key of keys) {
+        if (!NAME_POSITION_KEYS.has(key.toLowerCase()))
+            continue;
+        const name = readMember(value, key);
+        read.set(key, name);
+        if (named === undefined && typeof name === "string" && namesCredential(name))
+            named = name;
+    }
+    return named;
+}
+function recordOf(value, depth, budget) {
+    let keys;
+    try {
+        keys = Object.keys(value);
+    }
+    catch {
+        return undefined;
+    }
+    if (keys.length > CODED_DETAIL_ENTRIES || (keys.length > 0 && keys.every((k) => INDEX_KEY_RE.test(k))) || !charge(budget, 0))
+        return undefined;
+    const nameMembers = new Map();
+    const paired = pairedNameOf(value, keys, nameMembers);
+    const out = {};
+    for (const key of keys) {
+        if (!isProviderEchoShape(key) || carriesCredential(key) || budget.chars + key.length > CODED_DETAIL_CHARS)
+            continue;
+        const charsBefore = budget.chars;
+        budget.chars += key.length;
+        const context = paired !== undefined && VALUE_POSITION_KEYS.has(key.toLowerCase()) ? paired : key;
+        const admitted = leafOf(context, () => (nameMembers.has(key) ? nameMembers.get(key) : readMember(value, key)), depth + 1, budget);
+        if (admitted === undefined)
+            budget.chars = charsBefore;
+        else
+            Object.defineProperty(out, key, { value: admitted, enumerable: true, writable: true, configurable: true });
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function detailRecordOf(detail) {
+    try {
+        if (detail === null || typeof detail !== "object" || Array.isArray(detail) || ArrayBuffer.isView(detail))
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    return recordOf(detail, 0, { values: 0, chars: 0 });
+}
+function codedFailureDetailOf(link) {
+    const detail = detailRecordOf(readMember(link, "detail"));
+    return detail === undefined ? undefined : { kind: "coded", detail };
+}
+export function errorCodeOf(err) {
+    return codedLinkOf(err)?.code;
+}
+function codedLinkOf(err) {
+    let cur = err;
+    let fallback;
+    for (let depth = 0; cur !== null && cur !== undefined && typeof cur === "object" && depth < 8; depth++) {
+        const code = readMember(cur, "code");
+        if (typeof code === "string" && code) {
+            if (code !== "unknown") {
+                return { code, link: cur };
+            }
+            fallback ??= { code, link: cur };
+        }
+        cur = readMember(cur, "cause");
+    }
+    return fallback;
+}
+export function thrownFailureOf(err, text) {
+    const message = redactSecrets(text);
+    const coded = codedLinkOf(err);
+    if (coded === undefined)
+        return { message };
+    const detail = codedFailureDetailOf(coded.link);
+    return { code: coded.code, message, ...(detail !== undefined ? { detail } : {}) };
+}
+export function completedTerminalOf(final) {
+    const finishReasonUnknown = readMember(final, "finishReasonUnknown");
+    return typeof finishReasonUnknown === "string" && isProviderEchoShape(finishReasonUnknown)
+        ? { kind: "completed", detail: { kind: "finish_reason_unknown", finishReasonUnknown } }
+        : { kind: "completed" };
+}

package/dist/core/runner/tool-end-body.d.ts

@@ -1,7 +1,8 @@
 /**
- * What the run loop derives from a tool call's END, in every leg that closes one: the `tool_end` frame
- * body (the ONE projection the live loop, the resumed batch and the reconcile-recovered orphan all go
- * through), the `toolResult` transcript message the resume engine closes pending calls with, the thin
+ * What the run loop derives from a tool call's occurrence (`tool-occurrence.ts`), in every leg that opens or
+ * closes one: the `tool_start` and `tool_end` frames (the ONE start projection and the ONE end projection the
+ * live loop, the resumed batch and both reconciles go through, with the frame body), the `toolResult`
+ * transcript message the resume engine closes pending calls with, the thin
  * `response` digest the post-tool-batch observer is handed, and the canonical write-tool → reminder-window
  * family the attachment reducer keys on when a write tool ends.
  *
@@ -13,6 +14,8 @@
  */
 import { type AgentMessage } from "../../internal/harness.js";
 import type { GateOutcome } from "../gate-outcome.js";
+import type { TaskEvent, TaskEventIdentity } from "../types.js";
+import type { OccurrenceStart, ToolOccurrenceTable } from "./tool-occurrence.js";
 import { type McpDelivered } from "../mcp-failure.js";
 import type { RecoveredOrphan } from "../session-reconcile.js";
 import { type StructuredProjector } from "./tool-output-projection.js";
@@ -33,8 +36,8 @@ export declare function toolEndBodyFrom(result: unknown, isError: boolean,
  *  set alone would silently drop every declared caller card and never announce. */
 structured: StructuredProjector, 
 /** The gate's record of the pass that admitted or refused this call, supplied by the CALLER of this
- *  projection — the live loop reads it off the gate's per-call sideband, the resumed leg off the decide's
- *  minted record. Deliberately a parameter and never derived from `result`: a tool's own `details`
+ *  projection — the end projection ({@link emitSettled}) reads it off the call's occurrence (its latest gate
+ *  record). Deliberately a parameter and never derived from `result`: a tool's own `details`
  *  (which post-tool hooks may also replace) is writable by layers that adjudicate nothing, so reading
  *  provenance out of it would let a failing tool claim a person approved it. Omitted ⇒ the call never
  *  went through the gate (see the `tool_end.gate` doc, the one home). */
@@ -54,21 +57,55 @@ gatedCallIdOfRun?: string): {
     gatedCallId?: string;
     gate?: GateOutcome;
 };
+/** A frame of one tool call before the leg stamps its identity. */
+export type OccurrenceFrame = Omit<Extract<TaskEvent, {
+    type: "tool_start";
+}>, keyof TaskEventIdentity> | Omit<Extract<TaskEvent, {
+    type: "tool_end";
+}>, keyof TaskEventIdentity>;
+/** Where an occurrence's frames go: the leg's push (it stamps the identity and picks the queue) and its card projector. */
+export interface OccurrenceFrames {
+    push(frame: OccurrenceFrame): void;
+    structured: StructuredProjector;
+}
+/** The START projection: the call's occurrence opens and its start frame goes out. Every leg that announces a call
+ *  comes through here (the live loop's `tool_execution_start`, the resumed leg's approved call). */
+export declare function announceToolCall(table: ToolOccurrenceTable, start: OccurrenceStart, frames: Pick<OccurrenceFrames, "push">): void;
+/** How a call ended, as the station closing it knows it. */
+export interface OccurrenceEnd {
+    /** The harness result (or the exact text the closing station records). */
+    result: unknown;
+    isError: boolean;
+    /** POSITIVE evidence the call never executed — the loop's own mark on a call it closed without running it, or the
+     *  reconcile's never-started class. Absent = no such evidence, never "it ran" (see `tool_end.notExecuted`). */
+    notExecuted?: true;
+    /** The call is closed by an interruption rather than a result of its own. */
+    interrupted?: true;
+    /** See {@link toolEndBodyFrom}'s parameter of the same name. */
+    gatedCallIdOfRun?: string;
+}
+/** What the end projection decided, for the readers that ride beside the frame (the trace row, the row's record). */
+export interface SettledOccurrence {
+    /** The latest gate record — the call's disposition (absent when no gate exit saw it). */
+    gate?: GateOutcome;
+    /** The tool's own error bit, or a refusal recorded after the gate: the engine's record wins over the tool's word. */
+    isError: boolean;
+}
 /**
- * scan-1/A1 — the BODY of the synthetic `tool_end` that closes a reconcile-recovered orphan. ONE
- * construction point for BOTH minting legs (the live-abort loop at the end of a run, and the wake/crash
- * leg's replay at run open), so the two can never disagree about the shape of the same event.
+ * The END projection — the ONE mint of `tool_end`, for every station that closes a call: the live loop's
+ * `tool_execution_end`, the resumed leg's resolution, an interrupted run's reconcile and the reconcile replayed at
+ * the next process start. It reads the occurrence and nothing else: `gate` is its latest gate record, `isError` is
+ * the tool's bit or the refusal that record names, and `notExecuted` rides only on the station's positive evidence.
  *
- * Both frames used to carry `isError:true` and NOTHING else: a consumer rendering tool output from the
- * event stream showed an EMPTY body for every interrupted call, even though the persisted transcript
- * (which the model reads) carried the full `[INTERRUPTED]` explanation — the two faces of one call
- * disagreed. The projection goes through the same {@link toolEndBodyFrom} every live tool result uses, so
- * `output` = the persisted model-facing text and `errorCode` = the persisted `details.errorKind`
- * (`interrupted_never_started` / `interrupted_outcome_unknown`) — a consumer discriminates on the code
- * instead of prose-matching. No `structured`: the reconcile mints no CC card (no `details.type`), which the
- * leg's projector already enforces.
+ * A call whose start never went out on this stream (a call the loop never reached, a call announced by a dead
+ * process) gets its start minted here first, marked `recovered` and carrying the input the closing station holds —
+ * every end is preceded by a start with the same id. `start` opens the occurrence only when this leg holds none.
  */
-export declare function reconciledToolEndBody(orphan: Pick<RecoveredOrphan, "text" | "errorKind">, structured: StructuredProjector): ReturnType<typeof toolEndBodyFrom>;
+export declare function emitSettled(table: ToolOccurrenceTable, start: OccurrenceStart, end: OccurrenceEnd, frames: OccurrenceFrames): SettledOccurrence;
+/** The end of a call an interrupted run's reconcile closed: the persisted `[INTERRUPTED]` text is the body and its
+ *  `errorKind` the frame's `errorCode` (no card — the reconcile mints none), and the never-started class is the
+ *  positive evidence `notExecuted` needs. One reading for both reconciling legs (the live abort, the next start). */
+export declare function reconciledEnd(orphan: Pick<RecoveredOrphan, "text" | "errorKind">): OccurrenceEnd;
 /** task #51 F2/F3 — the CANONICAL write-tool → reminder-window mapping (CC qFm :480253-480254
  *  `a.name === bD || a.name === hF` = TaskCreate/TaskUpdate; BFm :480217-480219 = TodoWrite). Live
  *  deployment-alias resolution happens at the call sites (run-local `writeFamilyOf` over the mounted

package/dist/core/runner/tool-end-body.js

@@ -52,8 +52,33 @@ export function toolEndBodyFrom(result, isError, structured, gate, gatedCallIdOf
         ...(gate !== undefined ? { gate } : {}),
     };
 }
-export function reconciledToolEndBody(orphan, structured) {
-    return toolEndBodyFrom({ content: orphan.text, details: { code: orphan.errorKind } }, true, structured);
+const startFrameOf = (o, recovered) => ({ type: "tool_start", toolCallId: o.toolCallId, toolName: o.spelledName, ...(o.label !== undefined ? { label: o.label } : {}), args: o.args, ...(recovered ? { recovered: true } : {}) });
+export function announceToolCall(table, start, frames) {
+    table.open(start);
+    frames.push(startFrameOf(start, false));
+    table.noteStartEmitted(start.toolCallId);
+}
+export function emitSettled(table, start, end, frames) {
+    const occ = table.ensure(start);
+    if (!occ.startEmitted)
+        frames.push(startFrameOf(occ, true));
+    const gate = occ.gateRounds.at(-1);
+    const isError = end.isError || gate?.disposition.kind === "denied";
+    table.close(occ.toolCallId, end.interrupted === true ? "interrupted" : "settled");
+    frames.push({
+        type: "tool_end",
+        toolCallId: occ.toolCallId,
+        toolName: occ.spelledName,
+        ...(occ.label !== undefined ? { label: occ.label } : {}),
+        isError,
+        ...toolEndBodyFrom(end.result, isError, frames.structured, gate, end.gatedCallIdOfRun),
+        ...(gate?.disposition.kind === "denied" && occ.wireName !== undefined ? { wireName: occ.wireName } : {}),
+        ...(end.notExecuted === true ? { notExecuted: true } : {}),
+    });
+    return { ...(gate !== undefined ? { gate } : {}), isError };
+}
+export function reconciledEnd(orphan) {
+    return { result: { content: orphan.text, details: { code: orphan.errorKind } }, isError: true, interrupted: true, ...(orphan.errorKind === "interrupted_never_started" ? { notExecuted: true } : {}) };
 }
 export function writeFamilyOfCanonical(name) {
     if (name === TASK_CREATE_TOOL_NAME || name === TASK_UPDATE_TOOL_NAME)

package/dist/core/runner/tool-face-overlay.d.ts

@@ -21,7 +21,9 @@ import { type EngineNotice } from "../engine-notice.js";
 export declare const APPROVAL_CARD_REQUIRED_KEYS: Readonly<Record<ToolApprovalCard, readonly string[]>>;
 export type McpToolFace = NonNullable<McpServerSpec["toolFaces"]>[string];
 /** Why an overlay is refused — a closed reason list, each a distinct declaration mistake. */
-export declare function toolFaceProblem(face: McpToolFace, schema: AgentTool["parameters"]): string | undefined;
+export declare function toolFaceProblem(face: McpToolFace, schema: AgentTool["parameters"], tool?: {
+    readonly toolName: string;
+}): string | undefined;
 export interface ApplyToolFacesInput {
     /** The materialized tools of ONE server (namespaced names). */
     tools: readonly AgentTool[];

package/dist/core/runner/tool-face-overlay.js

@@ -1,7 +1,7 @@
 import { MCP_NAMESPACE } from "../protocol-table.js";
 import { mintNamespacePrefix } from "../protocol-naming.js";
-import { TOOL_APPROVAL_CARDS, TOOL_FAMILIES, TOOL_PATH_ABSENCES, TOOL_PATH_ACCESSES, TOOL_PATH_BASES, RENDER_HINT_ACTIVITY_MAX_CHARS, RENDER_HINT_MAX_CHARS, RENDER_HINT_MAX_LIST, TOOL_KEY_MAX_CHARS, } from "../tool-face.js";
-import { inputKeysOf } from "../tool-roster.js";
+import { RESERVED_APPROVAL_CARDS, TOOL_APPROVAL_CARDS, TOOL_FAMILIES, TOOL_PATH_ABSENCES, TOOL_PATH_ACCESSES, TOOL_PATH_BASES, RENDER_HINT_ACTIVITY_MAX_CHARS, RENDER_HINT_MAX_CHARS, RENDER_HINT_MAX_LIST, TOOL_KEY_MAX_CHARS, } from "../tool-face.js";
+import { engineCardOf, inputKeysOf } from "../tool-roster.js";
 import { deliverEngineNotice } from "../engine-notice.js";
 export const APPROVAL_CARD_REQUIRED_KEYS = Object.freeze({
     "file-edit": ["file_path"],
@@ -13,7 +13,7 @@ export const APPROVAL_CARD_REQUIRED_KEYS = Object.freeze({
     question: [],
     generic: [],
 });
-export function toolFaceProblem(face, schema) {
+export function toolFaceProblem(face, schema, tool) {
     const { keys, scalar } = inputKeysOf(schema);
     const top = new Set(keys.map((k) => k.name));
     if (face.family !== undefined && !TOOL_FAMILIES.includes(face.family))
@@ -60,6 +60,8 @@ export function toolFaceProblem(face, schema) {
         if (card !== undefined) {
             if (!TOOL_APPROVAL_CARDS.includes(card))
                 return `renderHints.approvalCard ${JSON.stringify(card)} is outside the closed set`;
+            if (RESERVED_APPROVAL_CARDS.includes(card) && (tool === undefined || engineCardOf(tool) !== card))
+                return `renderHints.approvalCard ${JSON.stringify(card)} is reserved for the engine's own tool that owns it; a declared tool takes another card or none`;
             const missing = APPROVAL_CARD_REQUIRED_KEYS[card].filter((k) => !top.has(k));
             if (missing.length > 0)
                 return `renderHints.approvalCard ${JSON.stringify(card)} needs ${missing.join(", ")} on the tool's schema`;
@@ -119,7 +121,7 @@ export function applyMcpToolFaces(input) {
         if (raw === undefined || face === undefined)
             return t;
         const hit = { raw, face };
-        const problem = toolFaceProblem(hit.face, t.parameters);
+        const problem = toolFaceProblem(hit.face, t.parameters, { toolName: t.name });
         if (problem !== undefined) {
             const key = `invalid:${t.name}`;
             if (!input.announced.has(key)) {

package/dist/core/runner/tool-occurrence.d.ts

@@ -0,0 +1,106 @@
+/**
+ * ONE TOOL CALL ATTEMPT, ONE RECORD — the occurrence.
+ *
+ * A tool call on one leg (one `toolCallId`, one attempt) has a single record here, and everything the engine
+ * says about the call is read off it: the `tool_start` / `tool_end` frames (projected in `tool-end-body.ts`), the
+ * `tool_progress` heartbeat (`tool-progress-lane.ts`), the trace row's `ok`, and the resumed leg's
+ * `executionOutcome` filing. The record has three parts:
+ *
+ *  - the EXECUTION LIFE, monotonic: `announced` (the start frame is out) → `executing` (the engine started the
+ *    tool body itself — the resumed leg; on a live leg the loop starts the body and the runner does not observe
+ *    that moment, so a live call stays `announced`) → `settled` or `interrupted`. Leaving a terminal state is an
+ *    engine defect and throws;
+ *  - the WAIT ON A PERSON, re-entrant: every ask put to the person's seat for this call counts one entry and one
+ *    exit (several rounds of one gate pass, a confirmation asked during the execution) — a count, never a bit,
+ *    because the waits nest and overlap;
+ *  - the GATE ROUNDS: one record per gate exit for this call, and one more when a station AFTER the gate refuses
+ *    it (the shell read admission that re-establishes what the gate judged, a resumed leg's belts). The latest
+ *    record is the call's disposition: a refusal after the gate is a refusal, never a tool failure under an
+ *    `allowed` record.
+ *
+ * WHAT IS NOT HERE: frames, clocks of a lane, the deny observer. This module is the record and its transitions;
+ * the projections read it. A durable park that crosses legs is two occurrences on two tables (the parking leg's,
+ * the resumed leg's), joined by the checkpoint row the resumed leg was opened from — never by a field here.
+ */
+import type { DeniedBy, GateOutcome } from "../gate-outcome.js";
+/** The one clock the occurrence's heartbeat facts are stamped on. MONOTONIC for the reason the progress lane
+ *  states: every reading is subtracted from another, and a wall-clock step backwards would silence the beat. A
+ *  host without `performance` falls back to the wall clock and inherits its rollback behaviour. */
+export declare const occurrenceClock: () => number;
+/** Where a call's execution life stands — see the module header for the order. */
+export type OccurrenceLife = "announced" | "executing" | "settled" | "interrupted";
+/** What opens an occurrence: the facts its start frame carries. */
+export interface OccurrenceStart {
+    readonly toolCallId: string;
+    /** The name the frames carry — the model's spelling on a live leg, the parked row's spelling on a resumed one. */
+    readonly spelledName: string;
+    /** The name of the tool the call dispatches to on the live roster — the name every gate station judged (absent when
+     *  the station opening the record does not know it). */
+    readonly wireName?: string;
+    /** The tool's display label, when it differs from the name. */
+    readonly label?: string;
+    /** The arguments the start frame carries (for a recovered start: the call's own input as the transcript holds it). */
+    readonly args: unknown;
+}
+/** The record, as its readers see it. Written only through {@link ToolOccurrenceTable}. */
+export interface ToolOccurrence extends OccurrenceStart {
+    /** 1 for the first attempt of this id on this table, counting re-announcements of a reused id. */
+    readonly attempt: number;
+    readonly life: OccurrenceLife;
+    /** How many asks put to the person for this call are open right now. */
+    readonly awaitingUser: number;
+    /** One outcome per gate exit, plus one per refusal after the gate; the last one is the call's disposition. */
+    readonly gateRounds: readonly GateOutcome[];
+    /** The input the latest gate exit decided on, as a FROZEN snapshot (absent when no gate saw the call). */
+    readonly finalInput?: unknown;
+    /** The call's start frame is out on this leg. */
+    readonly startEmitted: boolean;
+    /** When the call was announced, on {@link occurrenceClock} — the heartbeat's elapsed origin. */
+    readonly startedAt: number;
+    /** The last moment anything was heard from the call (a frame for it, or its return from a wait on the person). */
+    readonly lastHeardAt: number;
+    /** The heartbeat covers it. Cleared when the loop leaves the call behind at a turn end with no end of its own:
+     *  the record stays (a later settlement must still know its start frame went out) but no beat describes it. */
+    readonly beating: boolean;
+}
+/** The table of one leg's occurrences — the record's only writer. */
+export interface ToolOccurrenceTable {
+    /** The live (unsettled) attempt for this id, if any. */
+    get(toolCallId: string): ToolOccurrence | undefined;
+    /** Every live attempt, in the order they were opened. */
+    live(): readonly ToolOccurrence[];
+    /** Open a new attempt. A live earlier attempt for the same id is superseded: the loop left it behind without an
+     *  end (a reused id can only be re-announced after its earlier call stopped producing events), and nothing can
+     *  settle it any more. */
+    open(start: OccurrenceStart): ToolOccurrence;
+    /** The live attempt for this id, opened from `start` when there is none — a call the engine is told about
+     *  before it was announced (a frame the loop's own start never preceded). */
+    ensure(start: OccurrenceStart): ToolOccurrence;
+    /** The call's start frame is out. */
+    noteStartEmitted(toolCallId: string): void;
+    /** The engine starts the tool body. */
+    execute(toolCallId: string): void;
+    /** A gate exit for this call: its record and the input it decided on (frozen by the gate's exit). */
+    gateRound(toolCallId: string, outcome: GateOutcome, finalInput?: unknown): void;
+    /** A station after the gate refused the call: one more gate record, minted as a veto of whatever the latest one
+     *  settled (a person's yes stays on the settlement; the refusing layer is the disposition). Returns the record. */
+    refuse(toolCallId: string, layer: DeniedBy): GateOutcome;
+    /** An ask for this call is put to the person: the count rises, and the returned `resumeFromUser` lowers it once
+     *  (a second call is a no-op). The pair is bound to THIS attempt — a return after the call ended, or after a
+     *  reused id re-opened, touches nothing — and an ask for a call this leg does not hold counts nothing: the wait
+     *  is the person's, and no bookkeeping here may turn their answer into a failure. */
+    awaitUser(toolCallId: string): () => void;
+    /** The one bracket every asker uses: the count rises before `ask` puts its question and lowers when the answer
+     *  settles, either way. Returns `ask`'s own value, so the asker awaits exactly what it awaited before; a synchronous
+     *  answer (or anything that is not a promise) was no wait at all. */
+    whileAwaitingUser<T>(toolCallId: string, ask: () => T): T;
+    /** A frame for the call went out: its silence clock restarts. */
+    heard(toolCallId: string): void;
+    /** The call ended: it leaves the table and the record is returned for the end projection. */
+    close(toolCallId: string, life: "settled" | "interrupted"): ToolOccurrence | undefined;
+    /** The heartbeat stops covering every live attempt (turn end, leg teardown). Records stay. */
+    quiesce(): void;
+    /** Called whenever an attempt opens (the heartbeat arms its timer). One listener — the leg's one lane. */
+    onOpen(listener: () => void): void;
+}
+export declare function createToolOccurrenceTable(): ToolOccurrenceTable;

package/dist/core/runner/tool-occurrence.js

@@ -0,0 +1,123 @@
+import { mintGateOutcome } from "./gate-exit.js";
+export const occurrenceClock = () => (typeof performance !== "undefined" ? performance.now() : Date.now());
+const TERMINAL = { announced: false, executing: false, settled: true, interrupted: true };
+export function createToolOccurrenceTable() {
+    const byId = new Map();
+    const attempts = new Map();
+    let listener;
+    const held = (toolCallId, verb) => {
+        const occ = byId.get(toolCallId);
+        if (occ === undefined)
+            throw new Error(`tool occurrence: ${verb} for call "${toolCallId}", which this leg does not hold`);
+        return occ;
+    };
+    const open = (start) => {
+        const attempt = (attempts.get(start.toolCallId) ?? 0) + 1;
+        attempts.set(start.toolCallId, attempt);
+        const now = occurrenceClock();
+        const occ = {
+            toolCallId: start.toolCallId,
+            spelledName: start.spelledName,
+            ...(start.wireName !== undefined ? { wireName: start.wireName } : {}),
+            ...(start.label !== undefined ? { label: start.label } : {}),
+            args: start.args,
+            attempt,
+            life: "announced",
+            awaitingUser: 0,
+            gateRounds: [],
+            startEmitted: false,
+            startedAt: now,
+            lastHeardAt: now,
+            beating: true,
+        };
+        byId.delete(start.toolCallId);
+        byId.set(start.toolCallId, occ);
+        listener?.();
+        return occ;
+    };
+    const awaitUser = (toolCallId) => {
+        const occ = byId.get(toolCallId);
+        if (occ === undefined)
+            return () => { };
+        occ.awaitingUser += 1;
+        let returned = false;
+        return () => {
+            if (returned)
+                return;
+            returned = true;
+            if (byId.get(toolCallId) !== occ)
+                return;
+            occ.awaitingUser -= 1;
+            if (occ.awaitingUser === 0)
+                occ.lastHeardAt = occurrenceClock();
+        };
+    };
+    return {
+        awaitUser,
+        whileAwaitingUser(toolCallId, ask) {
+            const resumeFromUser = awaitUser(toolCallId);
+            let answer;
+            try {
+                answer = ask();
+            }
+            catch (err) {
+                resumeFromUser();
+                throw err;
+            }
+            if (answer instanceof Promise)
+                answer.then(resumeFromUser, resumeFromUser);
+            else
+                resumeFromUser();
+            return answer;
+        },
+        get: (toolCallId) => byId.get(toolCallId),
+        live: () => [...byId.values()],
+        open,
+        ensure: (start) => byId.get(start.toolCallId) ?? open(start),
+        noteStartEmitted(toolCallId) {
+            held(toolCallId, "a start frame").startEmitted = true;
+        },
+        execute(toolCallId) {
+            const occ = held(toolCallId, "execute");
+            if (occ.life !== "announced")
+                throw new Error(`tool occurrence: call "${toolCallId}" (attempt ${occ.attempt}) cannot start executing from "${occ.life}"`);
+            occ.life = "executing";
+        },
+        gateRound(toolCallId, outcome, finalInput) {
+            const occ = held(toolCallId, "a gate round");
+            occ.gateRounds.push(outcome);
+            if (finalInput !== undefined)
+                occ.finalInput = finalInput;
+        },
+        refuse(toolCallId, layer) {
+            const occ = held(toolCallId, "a refusal");
+            const latest = occ.gateRounds.at(-1);
+            const round = mintGateOutcome({ deniedBy: layer, ...(latest?.settlement !== undefined && latest.origin !== undefined ? { settled: { settlement: latest.settlement, origin: latest.origin } } : {}) });
+            occ.gateRounds.push(round);
+            return round;
+        },
+        heard(toolCallId) {
+            const occ = byId.get(toolCallId);
+            if (occ !== undefined)
+                occ.lastHeardAt = occurrenceClock();
+        },
+        close(toolCallId, life) {
+            const occ = byId.get(toolCallId);
+            if (occ === undefined)
+                return undefined;
+            if (TERMINAL[occ.life])
+                throw new Error(`tool occurrence: call "${toolCallId}" (attempt ${occ.attempt}) is already ${occ.life}`);
+            occ.life = life;
+            occ.beating = false;
+            byId.delete(toolCallId);
+            return occ;
+        },
+        quiesce() {
+            for (const occ of byId.values())
+                occ.beating = false;
+        },
+        onOpen(l) {
+            listener = l;
+        },
+    };
+}