@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/harness/terminal-table.js

@@ -0,0 +1,329 @@
+/**
+ * The terminal table: every way a turn ends, as data — the phase it writes,
+ * the `error` it sets, the system rows it appends, whether it stamps
+ * `completedAt`, and whether the activity RETURNS the slim status or THROWS
+ * a `CancelledFailure` — with one function that applies an arm to a status.
+ *
+ * Why data and not one function per arm: the copy is the user-facing
+ * contract of the runner (the hermetic goldens pin every string below byte
+ * for byte, `activities/execute-cursor/__tests__/hermetic/`), and a table a
+ * reader can scan is how that contract stays reviewable. The native
+ * harness once kept one function per arm (`streaming-terminal.ts`, retired
+ * in #1096); since #1096 both harnesses' turns end through this one table.
+ *
+ * The `error` of a FAILED arm is the failure itself, never framed: the
+ * `Execution failed:` wording belongs to the rows and to each consumer's
+ * own copy (the console's badge, the CLI's epilogue), so a consumer meets
+ * one grammar whichever arm wrote it. The interruption arms' `Execution
+ * interrupted:` errors are a different outcome, one the user resumes.
+ *
+ * The throw-vs-return rule, unchanged from the orchestrator it replaces:
+ *  - RETURN when a Temporal retry would only repeat the outcome — a stall
+ *    would wedge again, an exhausted budget would burn again, a platform
+ *    stop is the platform's decision, a failed engine would fail the same
+ *    prompt the same way, a completed turn is complete.
+ *  - THROW `CancelledFailure` when the workflow must see the activity as
+ *    cancelled — the orchestrator's pause, the runner's own drain, and an
+ *    infrastructure cancel it delivered — with the message the control
+ *    planes recognise.
+ *
+ * One stop has no copy here: the orchestrator's (a Pause or a Cancel, which
+ * reach the activity as the same workflow-requested cancellation). The turn
+ * cannot tell which it is, so its arm writes no phase and no row, and the
+ * invoke workflow, which knows, writes the phase and the stop row that the
+ * server's merge keeps last (stigmer#980;
+ * `backend/services/stigmer-server/src/domain/run/platform-rows.ts`).
+ * The pause row lived here until then, and a cancelled run ended with an
+ * instruction to resume it. The arm's throw messages keep their bytes: they
+ * are the wire copy the control planes see on the activity failure.
+ *
+ * An arm's rows are appended exactly once, by `applyTerminalArm`, and an arm
+ * is persisted exactly once, by `run-turn.ts`'s `settleWith` — the one
+ * writer of a terminal. The orchestrator this table replaced appended the
+ * three THROW arms' rows twice (its throw fell into its own catch, which
+ * wrote the copy again); #1070 reproduced that on purpose so the goldens could
+ * pin the wire byte for byte, and the PR after it removed it with a reviewed
+ * golden regeneration (stigmer#1054).
+ */
+import { create } from "@bufbuild/protobuf";
+import { RunPhase } from "@stigmer/apis/ai/stigmer/agentic/run/v1/enum_pb";
+import { COST_LIMIT_USER_COPY, formatCostLimitError } from "../shared/cost-guard.js";
+import { TOOL_CALL_LIMIT_USER_COPY, formatToolCallLimitError } from "../shared/tool-rounds.js";
+import { formatStallFailure } from "../shared/stall-watchdog.js";
+import { utcTimestamp } from "../shared/status.js";
+import { formatTryStop } from "@stigmer/eval-runtime";
+import { AgentMessageSchema } from "../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+import { MessageType } from "../gen/turn/ai/stigmer/runner/turn/v1/enum_pb.js";
+const RETURN = { kind: "return" };
+/** The fixed strings of the table, in one place. Every one is pinned by a golden or a hermetic assertion. */
+export const TERMINAL_COPY = {
+    orchestratorStop: {
+        throwMessage: "Activity paused by orchestrator",
+        throwMessageAfterError: "Activity paused by orchestrator (error during pause)",
+    },
+    workerShutdown: {
+        error: "Execution interrupted: runner worker was shut down. Retry or resume.",
+        row: "Execution interrupted: the runner worker was shut down while the agent was still running. You can retry or resume.",
+        throwMessage: "Activity cancelled (worker shutdown, not user pause)",
+    },
+    infrastructureCancel: {
+        error: "Execution interrupted: agent was unresponsive (heartbeat timeout). Retry or resume.",
+        row: "Execution interrupted: the agent was unresponsive for too long. You can retry or resume.",
+        throwMessage: "Activity cancelled (heartbeat timeout, not user pause)",
+        throwMessageAfterError: "Activity cancelled (infrastructure, not user pause)",
+    },
+    platformStop: {
+        row: "Execution stopped by the platform.",
+    },
+    fileReview: {
+        applyFailedPrefix: "Some approved file changes could not be applied because the file changed after review: ",
+        discardedPrefix: "Some proposed file changes were discarded by the user and were not applied: ",
+    },
+    internalFailure: {
+        row: "Internal system error occurred. Please contact support if this issue persists.",
+    },
+};
+// ── The arms ────────────────────────────────────────────────────────────────
+/** The watchdog cancelled a turn that made no progress. RETURN: an identical prompt would wedge again. */
+export function stallArm(error) {
+    return {
+        phase: RunPhase.RUN_FAILED,
+        error: formatStallFailure(error),
+        rows: [
+            `Execution failed: the agent made no progress for too long and was stopped (${error.message}). You can retry or resume.`,
+        ],
+        completes: true,
+        stopCause: "timeout",
+        disposition: RETURN,
+    };
+}
+/**
+ * A eval-run try's scaffold failed before the engine started.
+ * TERMINATED, as the other stops of a try: the platform stopped the run
+ * before the agent did anything, and a TERMINATED run keeps the runner's
+ * error as written (a FAILED one is reframed by the invoke workflow), so the
+ * eval reads the try stop's sentence back (`parseTryStop`) and scores the
+ * try 0. RETURN: a retry would run the same script.
+ */
+export function evalScaffoldFailedArm(message) {
+    return {
+        phase: RunPhase.RUN_TERMINATED,
+        error: message,
+        rows: [message],
+        completes: true,
+        stopCause: "eval_stopped",
+        disposition: RETURN,
+    };
+}
+/**
+ * A eval-run try's mock stopped the turn: its input guard was violated,
+ * its agent ended the run, or the agent mocks' call budget ran out.
+ * TERMINATED, as the cost cap: the platform stopped the run on purpose. The
+ * error is the try stop's sentence (`@stigmer/eval-runtime`
+ * `formatTryStop`), which the eval reads back as the try's `aborted`.
+ * RETURN: a retry would make the same call.
+ */
+export function mockAbortArm(abort) {
+    return {
+        phase: RunPhase.RUN_TERMINATED,
+        error: formatTryStop({ kind: "mock-aborted", server: abort.server, tool: abort.tool, reason: abort.reason }),
+        rows: [`A mock stopped this run: ${abort.server}.${abort.tool}: ${abort.reason}`],
+        completes: true,
+        stopCause: "eval_stopped",
+        disposition: RETURN,
+    };
+}
+/**
+ * The cost cap stopped the turn. TERMINATED, not FAILED: the platform
+ * deliberately stopped the run, work is checkpointed, and the conversation
+ * continues on the next message (the recursion-limit precedent,
+ * {@link toolCallLimitArm}). RETURN: a retry would burn the same budget
+ * again.
+ */
+export function costCapArm(maxCostUsd, estimatedCostUsd) {
+    return {
+        phase: RunPhase.RUN_TERMINATED,
+        error: formatCostLimitError(maxCostUsd, estimatedCostUsd),
+        rows: [COST_LIMIT_USER_COPY],
+        completes: true,
+        stopCause: "budget_reached",
+        disposition: RETURN,
+    };
+}
+/**
+ * The engine exhausted its tool-round budget (`max_tool_rounds`). TERMINATED,
+ * not FAILED, for the cost cap's reason: the platform deliberately stopped
+ * the run, work is checkpointed, and the conversation continues on the next
+ * message. RETURN: a retry would spend the same budget again. The error's
+ * prefix is a cross-repo contract (`shared/tool-rounds.ts`).
+ */
+export function toolCallLimitArm() {
+    return {
+        phase: RunPhase.RUN_TERMINATED,
+        error: formatToolCallLimitError(),
+        rows: [TOOL_CALL_LIMIT_USER_COPY],
+        completes: true,
+        stopCause: "budget_reached",
+        disposition: RETURN,
+    };
+}
+/** The runner is draining. Not a user's stop: FAILED with the shutdown copy, thrown as cancelled. */
+export function workerShutdownArm() {
+    return {
+        phase: RunPhase.RUN_FAILED,
+        error: TERMINAL_COPY.workerShutdown.error,
+        rows: [TERMINAL_COPY.workerShutdown.row],
+        completes: true,
+        stopCause: "infrastructure",
+        disposition: { kind: "throw", message: TERMINAL_COPY.workerShutdown.throwMessage },
+    };
+}
+/**
+ * The orchestrator stopped the turn: a Pause or a Cancel, indistinguishable
+ * here (the module header). The transcript is settled and persisted with no
+ * phase and no row, because the workflow writes both; not an error, not
+ * complete; thrown as cancelled so the workflow sees the activity stop.
+ */
+export function orchestratorStopArm() {
+    return {
+        phase: RunPhase.RUN_PHASE_UNSPECIFIED,
+        rows: [],
+        completes: false,
+        stopCause: "user",
+        disposition: { kind: "throw", message: TERMINAL_COPY.orchestratorStop.throwMessage },
+    };
+}
+/** Temporal cancelled for its own reason (a heartbeat timeout). FAILED with the unresponsive copy, thrown as cancelled. */
+export function infrastructureCancelArm() {
+    return {
+        phase: RunPhase.RUN_FAILED,
+        error: TERMINAL_COPY.infrastructureCancel.error,
+        rows: [TERMINAL_COPY.infrastructureCancel.row],
+        completes: true,
+        stopCause: "infrastructure",
+        disposition: { kind: "throw", message: TERMINAL_COPY.infrastructureCancel.throwMessage },
+    };
+}
+/**
+ * The engine proposed at least one gated side effect and stopped: the
+ * WAITING_APPROVAL rows are already on the transcript. Not an error, not
+ * complete, no copy; RETURN to the workflow, which waits for the approval
+ * signal and reinvokes with the decisions. Until #1096 this was an inline
+ * phase flip in `run-turn.ts`; it is an arm because every way an activity
+ * ends belongs in this one table.
+ */
+export function awaitingApprovalArm() {
+    return { phase: RunPhase.RUN_WAITING_FOR_APPROVAL, rows: [], completes: false, stopCause: null, disposition: RETURN };
+}
+/** The control plane answered STOP. A clean COMPLETED early exit. */
+export function platformStopArm() {
+    return {
+        phase: RunPhase.RUN_COMPLETED,
+        rows: [TERMINAL_COPY.platformStop.row],
+        completes: true,
+        stopCause: "platform_stop",
+        disposition: RETURN,
+    };
+}
+/** Another turn held the primary tree past the lock timeout. RETURN: a retry would queue behind the same holder. */
+export function workspaceLockTimeoutArm(error) {
+    return {
+        phase: RunPhase.RUN_FAILED,
+        error: error.message,
+        rows: [`Execution failed: ${error.message}`],
+        completes: true,
+        stopCause: "timeout",
+        disposition: RETURN,
+    };
+}
+/**
+ * A reconcile turn: the run a person's Undo on an ended turn starts. The
+ * agent finished that turn long ago, so undoing a change never re-prompts it
+ * (Cursor-like); putting the files back is the whole act and the execution
+ * is complete. A failed undo (the captured content no longer matched what
+ * was reviewed, or the files could not be restored) tells the human; a
+ * successful one names the files put back — the agent's native context
+ * still believes those edits stuck, and any edit it makes from that belief
+ * is offered for review again next turn (the structural safety net). The
+ * copy is the table's pinned wire and keeps its bytes.
+ */
+export function fileReviewResolvedArm(settlement) {
+    const rows = [];
+    if (settlement.failed) {
+        rows.push(`${TERMINAL_COPY.fileReview.applyFailedPrefix}${settlement.failureDetail}.`);
+    }
+    else if (settlement.discardedPaths.length > 0) {
+        rows.push(`${TERMINAL_COPY.fileReview.discardedPrefix}${settlement.discardedPaths.join(", ")}.`);
+    }
+    return { phase: RunPhase.RUN_COMPLETED, rows, completes: true, stopCause: "review_resolved", disposition: RETURN };
+}
+/**
+ * The adapter settled `failed`. The surface picks the copy (the three shapes
+ * the Cursor orchestrator wrote, `types.ts` `FailureSurface`); `message` is
+ * the adapter's user-facing sentence and becomes `status.error` whole.
+ */
+export function failedArm(message, surface) {
+    const rows = (() => {
+        switch (surface) {
+            case "engine":
+                return [];
+            case "actionable":
+                return [`Execution failed: ${message}`];
+            case "internal":
+                return [TERMINAL_COPY.internalFailure.row, `Error details: ${message}`];
+            default: {
+                const exhaustive = surface;
+                throw new Error(`terminal table: unknown failure surface ${String(exhaustive)}`);
+            }
+        }
+    })();
+    // The engine's own failure is the model provider's (a refused or failed
+    // model request); every other surface is a failure of the turn.
+    const stopCause = surface === "engine" ? "model_error" : "failed";
+    return { phase: RunPhase.RUN_FAILED, error: message, rows, completes: true, stopCause, disposition: RETURN };
+}
+/**
+ * An error the runtime caught itself, outside any adapter (a resolution
+ * phase, the epilogue): an `internal` failure like any adapter's, described
+ * as `[<type>] <message>` (`describeExecutionError` supplies the two parts),
+ * so `status.error` reads the same whichever side caught the fault. Until
+ * stigmer#1122 this arm alone prefixed `status.error` with `Execution
+ * failed:`, and a consumer that adds its own failure copy (the CLI's
+ * epilogue) printed the words twice.
+ */
+export function unexpectedErrorArm(errorType, errorMessage) {
+    return failedArm(`[${errorType}] ${errorMessage}`, "internal");
+}
+// ── Applying an arm ─────────────────────────────────────────────────────────
+/**
+ * Append system rows, each with its own timestamp, in order. Module-private
+ * on purpose: rows reach the turn's rows only through `applyTerminalArm`, so
+ * no caller can append an arm's copy a second time (the shape of
+ * stigmer#1054).
+ */
+function appendSystemRows(rows, contents) {
+    for (const content of contents) {
+        rows.messages.push(create(AgentMessageSchema, { type: MessageType.MESSAGE_SYSTEM, content, timestamp: utcTimestamp() }));
+    }
+}
+/**
+ * Write an arm onto the status (phase, error, completion stamp, stop cause)
+ * and its rows onto the turn's rows. The caller persists and disposes.
+ * Returns the root positions of the rows it appended: they repeat the stop
+ * the session's status events and the stop cause already say, so the
+ * session event emitter is told never to write them as notes of the harness
+ * (`events/emitter.ts`).
+ */
+export function applyTerminalArm(status, rows, arm) {
+    status.phase = arm.phase;
+    if (arm.error !== undefined)
+        status.error = arm.error;
+    if (arm.completes)
+        status.completedAt = utcTimestamp();
+    if (arm.stopCause !== null)
+        status.stopCause = arm.stopCause;
+    const first = rows.messages.length;
+    appendSystemRows(rows, arm.rows);
+    return arm.rows.map((_, index) => first + index);
+}
+//# sourceMappingURL=terminal-table.js.map

package/dist/harness/terminal-table.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-table.js","sourceRoot":"","sources":["../../src/harness/terminal-table.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,MAAM,iDAAiD,CAAC;AAE3E,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACrF,OAAO,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAC/F,OAAO,EAAE,kBAAkB,EAA0B,MAAM,6BAA6B,CAAC;AACzF,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAInD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAiB,MAAM,kDAAkD,CAAC;AACrG,OAAO,EAAE,WAAW,EAAE,MAAM,kDAAkD,CAAC;AAsC/E,MAAM,MAAM,GAAwB,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AAEvD,6GAA6G;AAC7G,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,gBAAgB,EAAE;QAChB,YAAY,EAAE,iCAAiC;QAC/C,sBAAsB,EAAE,sDAAsD;KAC/E;IACD,cAAc,EAAE;QACd,KAAK,EAAE,sEAAsE;QAC7E,GAAG,EAAE,oHAAoH;QACzH,YAAY,EAAE,sDAAsD;KACrE;IACD,oBAAoB,EAAE;QACpB,KAAK,EAAE,qFAAqF;QAC5F,GAAG,EAAE,0FAA0F;QAC/F,YAAY,EAAE,wDAAwD;QACtE,sBAAsB,EAAE,qDAAqD;KAC9E;IACD,YAAY,EAAE;QACZ,GAAG,EAAE,oCAAoC;KAC1C;IACD,UAAU,EAAE;QACV,iBAAiB,EAAE,yFAAyF;QAC5G,eAAe,EAAE,8EAA8E;KAChG;IACD,eAAe,EAAE;QACf,GAAG,EAAE,gFAAgF;KACtF;CACO,CAAC;AAEX,+EAA+E;AAE/E,0GAA0G;AAC1G,MAAM,UAAU,QAAQ,CAAC,KAAwB;IAC/C,OAAO;QACL,KAAK,EAAE,QAAQ,CAAC,UAAU;QAC1B,KAAK,EAAE,kBAAkB,CAAC,KAAK,CAAC;QAChC,IAAI,EAAE;YACJ,8EAA8E,KAAK,CAAC,OAAO,6BAA6B;SACzH;QACD,SAAS,EAAE,IAAI;QACf,SAAS,EAAE,SAAS;QACpB,WAAW,EAAE,MAAM;KACpB,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAe;IACnD,OAAO;QACL,KAAK,EAAE,QAAQ,CAAC,cAAc;QAC9B,KAAK,EAAE,OAAO;QACd,IAAI,EAAE,CAAC,OAAO,CAAC;QACf,SAAS,EAAE,IAAI;QACf,SAAS,EAAE,cAAc;QACzB,WAAW,EAAE,MAAM;KACpB,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAgB;IAC3C,OAAO;QACL,KAAK,EAAE,QAAQ,CAAC,cAAc;QAC9B,KAAK,EAAE,aAAa,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;QAC5G,IAAI,EAAE,CAAC,4BAA4B,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC;QACjF,SAAS,EAAE,IAAI;QACf,SAAS,EAAE,cAAc;QACzB,WAAW,EAAE,MAAM;KACpB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,UAAkB,EAAE,gBAAwB;IACrE,OAAO;QACL,KAAK,EAAE,QAAQ,CAAC,cAAc;QAC9B,KAAK,EAAE,oBAAoB,CAAC,UAAU,EAAE,gBAAgB,CAAC;QACzD,IAAI,EAAE,CAAC,oBAAoB,CAAC;QAC5B,SAAS,EAAE,IAAI;QACf,SAAS,EAAE,gBAAgB;QAC3B,WAAW,EAAE,MAAM;KACpB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO;QACL,KAAK,EAAE,QAAQ,CAAC,cAAc;QAC9B,KAAK,EAAE,wBAAwB,EAAE;QACjC,IAAI,EAAE,CAAC,yBAAyB,CAAC;QACjC,SAAS,EAAE,IAAI;QACf,SAAS,EAAE,gBAAgB;QAC3B,WAAW,EAAE,MAAM;KACpB,CAAC;AACJ,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL,KAAK,EAAE,QAAQ,CAAC,UAAU;QAC1B,KAAK,EAAE,aAAa,CAAC,cAAc,CAAC,KAAK;QACzC,IAAI,EAAE,CAAC,aAAa,CAAC,cAAc,CAAC,GAAG,CAAC;QACxC,SAAS,EAAE,IAAI;QACf,SAAS,EAAE,gBAAgB;QAC3B,WAAW,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,YAAY,EAAE;KACnF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO;QACL,KAAK,EAAE,QAAQ,CAAC,qBAAqB;QACrC,IAAI,EAAE,EAAE;QACR,SAAS,EAAE,KAAK;QAChB,SAAS,EAAE,MAAM;QACjB,WAAW,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,CAAC,gBAAgB,CAAC,YAAY,EAAE;KACrF,CAAC;AACJ,CAAC;AAED,2HAA2H;AAC3H,MAAM,UAAU,uBAAuB;IACrC,OAAO;QACL,KAAK,EAAE,QAAQ,CAAC,UAAU;QAC1B,KAAK,EAAE,aAAa,CAAC,oBAAoB,CAAC,KAAK;QAC/C,IAAI,EAAE,CAAC,aAAa,CAAC,oBAAoB,CAAC,GAAG,CAAC;QAC9C,SAAS,EAAE,IAAI;QACf,SAAS,EAAE,gBAAgB;QAC3B,WAAW,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,CAAC,oBAAoB,CAAC,YAAY,EAAE;KACzF,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,wBAAwB,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;AACxH,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,eAAe;IAC7B,OAAO;QACL,KAAK,EAAE,QAAQ,CAAC,aAAa;QAC7B,IAAI,EAAE,CAAC,aAAa,CAAC,YAAY,CAAC,GAAG,CAAC;QACtC,SAAS,EAAE,IAAI;QACf,SAAS,EAAE,eAAe;QAC1B,WAAW,EAAE,MAAM;KACpB,CAAC;AACJ,CAAC;AAED,oHAAoH;AACpH,MAAM,UAAU,uBAAuB,CAAC,KAAgC;IACtE,OAAO;QACL,KAAK,EAAE,QAAQ,CAAC,UAAU;QAC1B,KAAK,EAAE,KAAK,CAAC,OAAO;QACpB,IAAI,EAAE,CAAC,qBAAqB,KAAK,CAAC,OAAO,EAAE,CAAC;QAC5C,SAAS,EAAE,IAAI;QACf,SAAS,EAAE,SAAS;QACpB,WAAW,EAAE,MAAM;KACpB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CAAC,UAIrC;IACC,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,IAAI,UAAU,CAAC,MAAM,EAAE,CAAC;QACtB,IAAI,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,iBAAiB,GAAG,UAAU,CAAC,aAAa,GAAG,CAAC,CAAC;IACzF,CAAC;SAAM,IAAI,UAAU,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChD,IAAI,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,eAAe,GAAG,UAAU,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnG,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,aAAa,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;AACrH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,OAAuB;IAChE,MAAM,IAAI,GAAG,CAAC,GAAsB,EAAE;QACpC,QAAQ,OAAO,EAAE,CAAC;YAChB,KAAK,QAAQ;gBACX,OAAO,EAAE,CAAC;YACZ,KAAK,YAAY;gBACf,OAAO,CAAC,qBAAqB,OAAO,EAAE,CAAC,CAAC;YAC1C,KAAK,UAAU;gBACb,OAAO,CAAC,aAAa,CAAC,eAAe,CAAC,GAAG,EAAE,kBAAkB,OAAO,EAAE,CAAC,CAAC;YAC1E,OAAO,CAAC,CAAC,CAAC;gBACR,MAAM,UAAU,GAAU,OAAO,CAAC;gBAClC,MAAM,IAAI,KAAK,CAAC,2CAA2C,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;YACnF,CAAC;QACH,CAAC;IACH,CAAC,CAAC,EAAE,CAAC;IACL,wEAAwE;IACxE,gEAAgE;IAChE,MAAM,SAAS,GAAc,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC7E,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;AAC/G,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAiB,EAAE,YAAoB;IACxE,OAAO,SAAS,CAAC,IAAI,SAAS,KAAK,YAAY,EAAE,EAAE,UAAU,CAAC,CAAC;AACjE,CAAC;AAED,+EAA+E;AAE/E;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,IAAgC,EAAE,QAA2B;IACrF,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,kBAAkB,EAAE,EAAE,IAAI,EAAE,WAAW,CAAC,cAAc,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,EAAE,CAAC,CAAC,CAAC;IAC3H,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAiB,EAAE,IAAgC,EAAE,GAAgB;IACpG,MAAM,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;IACzB,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS;QAAE,MAAM,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;IACtD,IAAI,GAAG,CAAC,SAAS;QAAE,MAAM,CAAC,WAAW,GAAG,YAAY,EAAE,CAAC;IACvD,IAAI,GAAG,CAAC,SAAS,KAAK,IAAI;QAAE,MAAM,CAAC,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;IAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;IACnC,gBAAgB,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,OAAO,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC;AACnD,CAAC"}

package/dist/harness/transcript/builder.d.ts

@@ -0,0 +1,269 @@
+/**
+ * TranscriptBuilder — folds `TranscriptEvent`s into the turn's rows it is
+ * handed (`TurnRows`, the runner's own proto: messages, tool-call rows and
+ * their approval status, sub-agent rows, todos), and registers the turn's
+ * artifacts and write-backs on the run's status it is handed beside them.
+ *
+ * The one transcript builder, for every harness (#1097). It
+ * was the native harness's `V3StatusBuilder` (the one builder there since
+ * #1096 retired the v2 `StatusBuilder`), promoted here on 2026-09-14
+ * unchanged and then cut engine-neutral one rule per commit:
+ * it reads no engine envelope, decides nothing about approval,
+ * and knows no engine's tool names or namespace grammar — every engine
+ * fact reaches it as a translator's output, on one union. The Cursor
+ * harness feeds it through a translator; the runtime constructs it once
+ * per turn and hands it to every adapter as `TurnSink.transcript`, so
+ * a transcript row has exactly one way into the rows — a source-walking
+ * fence, `harness/__tests__/transcript-writers.test.ts`, refuses a second.
+ *
+ * ONE set of handlers over ONE scope shape: every handler takes
+ * the scope's {@link Transcript} — the root's over `rows.messages`, or a
+ * sub-agent's over its row's — from `TranscriptState`, so a sub-agent's
+ * transcript is folded by exactly the rules the root's is. Until #1097 the
+ * sub-agents' half was a second module (`SubAgentTracker`) with its own copy
+ * of every handler, differing only in which array it pushed into — the
+ * memo's third copy of the folding rule, and the one whose namespace filter
+ * differed from the root's by one segment (found in #1096: the root
+ * filed text under `model_request:<uuid>` and looked the tool's parent up
+ * under `""`, so every native tool row sat on an empty message after its
+ * text). With scope a single value per transcript, that class of miss
+ * cannot exist.
+ *
+ * The rules this builder owns, each with an arm in
+ * `harness/transcript/__tests__/builder.test.ts` and the harness whose rule
+ * it generalises in parentheses:
+ *
+ *   - A row per `callId`, indexed over the rows as handed and over what
+ *     {@link seed} appends (a reinvocation's asks, indexed by the same
+ *     routine, so a builder born before the seed is no different from one
+ *     born after it), reconciled in place on a re-emitted start — an UNSETTLED row becomes
+ *     RUNNING (a WAITING row on native's durable-checkpoint resume; an
+ *     INTERRUPTED row on a recovery replay, the enum's supersede rule) and
+ *     takes the args and preview it lacked — never duplicated. Every row
+ *     with args carries them with secret-keyed values redacted
+ *     (stigmer#1119), and an `argsPreview` elided and redacted, salient
+ *     fields verbatim. A finish or an error is an upsert: status
+ *     monotonic, `completedAt` once, a non-empty result or message
+ *     overwrites, an empty one never clears; a re-emit that
+ *     changes nothing forces no persist; a fact the harness
+ *     observed earlier and delivers later stamps its own instant
+ *     (`observedAt`); an output chunk for a settled row is stale
+ *     and dropped — the completion's result is the whole output.
+ *   - One observation, one instant: the facts a translator made of one
+ *     raw engine event, folded through {@link applyObservation}, share
+ *     one clock read for every stamp they make (a Cursor completion with
+ *     no running before it starts and finishes at the same instant,
+ *     stigmer#1390); {@link apply} alone reads the clock per fact.
+ *   - The AI-message boundary (native's own rule, made correct by
+ *     scoping): a tool row attaches to the scope's current AI message — the
+ *     latest with text, the seed's last AI message over a seeded transcript
+ *     — and to a new empty one only when the scope has none.
+ *   - A THINKING row per `runId`, a text message per `runId`; a
+ *     new run closes the previous message's streaming flag, and a run's
+ *     finish closes both its text and its thinking.
+ *   - A sub-agent row per `subAgentId`, opened by `sub_agent_started`,
+ *     closed COMPLETED/FAILED by `sub_agent_finished/failed` with its
+ *     transcript's streaming flags cleared; a known id is never re-opened.
+ *     CANCELLED is not this builder's: `shared/subagent-rows.ts`
+ *     `cancelInProgressSubAgentProtos` is the one home of that transition.
+ *   - `approval_proposed` is the one place a row is ever WAITING: a known
+ *     row REOPENS — WAITING, the outcome fields cleared,
+ *     `approvalRequestedAt` stamped once, the proposal's args and preview
+ *     taken when carried (Cursor's `markWaitingApproval` + `applyGateInput`);
+ *     an unknown call gets a WAITING row on the scope's current AI message,
+ *     the text that proposed it (native's post-stream seed, before #1097 a new
+ *     empty message of its own). Either way {@link awaitingApproval} is set.
+ *   - `system_note` is a SYSTEM message in the scope, in the harness's
+ *     voice; it hosts no rows and moves no boundary.
+ *   - A completed `ToolKind.TODO` call in the ROOT scope is projected into
+ *     `rows.todos` through the shared `applyTodoUpdate`, a full replace
+ *     unless the call's args say `merge: true` (the row stays — the
+ *     clients filter it); a sub-agent's is not.
+ *   - `finalize()` clears every streaming flag in every scope.
+ *   - Artifacts upsert by `sandboxPath`/`contentHash`, write-backs by
+ *     `workspaceEntryName`: the inline publisher and the write-back
+ *     coordinator register theirs here, each through the one-method view it
+ *     declares for itself (`ArtifactSink`, `WriteBackSink`), which this class
+ *     satisfies by shape.
+ *   - {@link dirty} is set by every discrete change above and by nothing a
+ *     token delta does; the adapter's loop reads it and clears it with
+ *     {@link markPersisted} as it requests the persist.
+ *
+ * The runtime may hand the constructor an OBSERVER of the fold: a callback
+ * that sees every event `apply` folded, in order, after the fold, and creates
+ * nothing (the runtime's turn timeline, `harness/turn-timeline.ts`, is the
+ * one observer today). A callback at construction, not a subscribe method,
+ * because that is how the runtime tells its collaborators what to do
+ * everywhere else (`PersistChokepoint`'s options, the stall watchdog's
+ * `onStall`): one observer, fixed at the one constructor call, nothing to
+ * add or remove mid-turn. The observer runs in its own try/catch, so it can
+ * neither block a fold nor break a harness; `seed()` does not notify it,
+ * because a seeded row is last turn's fact. When the adapter runs in the agent
+ * host, the events are folded by the host's builder and this one only relays
+ * them to its observer ({@link relayObserved}), with the instant of the
+ * host's fold.
+ *
+ * What this builder deliberately does NOT write, and who does (the adapter
+ * contract's field ownership, `harness/types.ts` `TurnSink`): the phase,
+ * `startedAt`, `streamingUsage` and the epilogue's plan artifact are the
+ * turn runtime's (the plan artifact supersedes by its own name rule, which
+ * is the plan's knowledge, not the transcript's). A row left
+ * WAITING_APPROVAL is reported as the {@link awaitingApproval} fact and the
+ * caller decides what that means for the turn — a fact only
+ * `approval_proposed` produces, because a call that has
+ * STARTED is never parked at creation. Usage never passes
+ * through here: the native loop reads it off the wire (`usageOf`) and
+ * prices it into the sink, the Cursor loop reads its own from the SDK.
+ */
+import type { RunStatus } from "@stigmer/apis/ai/stigmer/agentic/run/v1/api_pb";
+import type { TurnRows } from "../../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+import type { RunArtifact } from "@stigmer/apis/ai/stigmer/agentic/run/v1/artifact_pb";
+import type { WorkspaceWriteBack } from "@stigmer/apis/ai/stigmer/agentic/run/v1/writeback_pb";
+import { type TranscriptSeed } from "./state.js";
+import type { TranscriptEvent } from "./events.js";
+/** Where a fold left a token delta's row: its place in its scope's message array. */
+export interface FoldPlace {
+    readonly messageIndex: number;
+}
+/**
+ * Told every folded event, in order, after the fold; creates nothing.
+ * `atMs` is the fold's instant (`performance.now()` scale) when it is not
+ * now; `place` is where a text or reasoning delta's row sits, which names
+ * the session event the delta previews (`harness/events/ids.ts`).
+ */
+export type TranscriptObserver = (event: TranscriptEvent, atMs?: number, place?: FoldPlace) => void;
+export declare class TranscriptBuilder {
+    readonly executionId: string;
+    private readonly state;
+    private readonly observer;
+    private _dirty;
+    private _awaitingApproval;
+    /** The one instant of the observation being folded, while {@link applyObservation} runs; absent otherwise. */
+    private observationInstant;
+    /** Hook provenance that arrived before its call's row, by call id; stamped when the row opens. */
+    private readonly pendingPolicies;
+    /**
+     * Builds INTO `rows`, by reference: its `messages`, `subAgentRuns` and
+     * every sub-agent row's `messages` are the arrays indexed and pushed
+     * into, never replaced, so a caller that holds the same rows (the
+     * runtime's chokepoint, a settle amending rows by identity) keeps seeing
+     * every row. Rows already there are indexed here; the asks a reinvocation
+     * resumes onto arrive later through {@link seed}, indexed by the same
+     * routine, so a re-driven event reconciles onto them either way. The
+     * turn's artifacts and write-backs are registered on `status`.
+     *
+     * The builder hands nothing back. A reader holds the rows it built the
+     * builder over — `TurnSink.rows` in production, the test's own in a
+     * test — so the transcript has one read handle and one write handle, and
+     * no second spelling of either.
+     *
+     * `observer`, when given, is told every event after it is folded (the
+     * header's rule). The runtime passes its turn timeline; the contract kit
+     * and the test doubles pass nothing.
+     */
+    constructor(executionId: string, rows: TurnRows, status: RunStatus, observer?: TranscriptObserver);
+    /**
+     * Append a reinvocation's asks — the asked calls its engine resumes onto,
+     * read from the session's log, and the sub-agent rows that hold them —
+     * and index them, so a re-issued call reconciles onto its seeded row
+     * instead of duplicating it. The runtime calls this once, in its
+     * reinvocation phase, before any harness runs (`harness/transcript/resume-seed.ts`
+     * says what is seeded and why nothing else is). Seeded rows are an earlier
+     * invocation's facts: this sets neither {@link dirty} nor
+     * {@link awaitingApproval}.
+     */
+    seed(seeded: TranscriptSeed): void;
+    /**
+     * True once a row this turn was left WAITING_APPROVAL: the engine has
+     * interrupted (or the harness's boundary parked the call) and the turn
+     * should end awaiting a decision. A fact about the transcript, not a phase
+     * — the caller owns the phase. No `tool_started` sets it (a started call
+     * is running); `approval_proposed` does.
+     */
+    get awaitingApproval(): boolean;
+    /**
+     * True once a discrete, user-visible change has landed since the last
+     * persist — a row started or settled, a sub-agent opened or closed, an
+     * artifact or write-back registered, a note appended; never a token
+     * delta, which rides the streaming cadence. The one fact the adapter's
+     * persist decision reads (`shared/persist-decision.ts`); the adapter
+     * clears it with {@link markPersisted} as it requests the write, so a
+     * change that lands after the write started dirties the next one.
+     */
+    get dirty(): boolean;
+    markPersisted(): void;
+    /**
+     * Fold one canonical event into the transcript, then tell the observer.
+     * Never throws: a handler's error is logged and the stream goes on, and so
+     * is an observer's — each in its own catch, so a failing observer still
+     * sees a folded transcript and a failing handler still reaches the observer.
+     */
+    apply(event: TranscriptEvent): void;
+    /**
+     * Tell the observer about an event the agent host's builder folded
+     * (`agent-host/remote-adapter.ts`): the host's builder is the adapter's,
+     * this one is the runtime's, and the runtime's timeline observes through
+     * this one. Nothing is folded here; the host's rows reach these rows
+     * with its next persist. `atMs` is the host's fold instant on this
+     * process's `performance.now()` scale, `place` where the host's fold left
+     * a delta's row (the host's rows are these, row for row). Never
+     * throws.
+     */
+    relayObserved(event: TranscriptEvent, atMs: number, place?: FoldPlace): void;
+    /**
+     * Fold the facts ONE harness observation yields — the events a translator
+     * made of one raw engine event — at one instant: the clock is read once,
+     * and every stamp the facts make (a row's start and finish, a sub-agent's
+     * open and close, a message's timestamp) is that instant. A Cursor
+     * completion the stream reports with no running before it is a start and a
+     * finish in one event, and it must carry one instant, not two reads a
+     * millisecond apart (stigmer#1390). A fact that carries its own
+     * `observedAt` keeps it. Each fact is applied exactly as {@link apply}
+     * applies it, observer included.
+     */
+    applyObservation(facts: readonly TranscriptEvent[]): void;
+    /** Where the fold left a text or reasoning delta's row; absent for every other fact. */
+    private placeOf;
+    /** The instant a stamp records: the observation's, while one is being folded, else now. */
+    private instant;
+    private fold;
+    /**
+     * Every streaming flag off, in every scope — messages and rows. What a
+     * turn owes the transcript when its stream ends, however it ended: a
+     * stopped turn's in-flight message must not persist as still streaming.
+     * The sub-agent rows' own CANCELLED transition is the caller's, through
+     * the shared `cancelInProgressSubAgentProtos`.
+     */
+    finalize(): void;
+    addArtifact(artifact: RunArtifact): void;
+    addWriteBack(wb: WorkspaceWriteBack): void;
+    private openSubAgent;
+    private closeSubAgent;
+    private failSubAgent;
+    private handleMessageStart;
+    private handleMessageFinish;
+    private appendTextContent;
+    private appendThinkingContent;
+    private handleToolStarted;
+    /**
+     * A hook's provenance for a call that runs (`ToolPolicyEvent`): stamped on
+     * the row now, or held until the row opens, so it outranks whatever its
+     * `tool_started` said in either order. A row a person already decided (its
+     * answer, copied from the session's log onto the row at the seed) keeps
+     * the provenance that asked them, as a re-emitted start does: on
+     * resume the hook runs again and an "approve all" it just leased answers
+     * it, and re-stamping that as the lease would make the next turn read the
+     * row as the tool's whole category or server instead of the hook.
+     */
+    private handleToolPolicy;
+    private handleToolFinished;
+    private handleToolError;
+    private handleToolArgDelta;
+    private handleToolOutputDelta;
+    private handleApprovalProposed;
+    private appendSystemNote;
+    /** The AI message a run's text streams into, created on its first token; a new run closes the previous message's flag. */
+    private ensureAiMessage;
+    /** The message a tool row lands on when the scope has no AI message yet: the latest run's, else a new empty one. */
+    private ensureAiMessageForToolCall;
+}