@inflexa-ai/harness 0.42.2 → 0.43.0

package/dist/execution/run-event-stream.js

@@ -34,6 +34,7 @@ import { DBOS } from "@dbos-inc/dbos-sdk";
 import { sleep } from "../lib/async-utils.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { describeDbError } from "../lib/db-result.js";
+import { queryRun } from "../state/runs.js";
 import { queryStepsByRun } from "../state/step-executions.js";
 import { foldRunEventParts, parseRunEventPart } from "./run-event-parts.js";
 /** Durable stream key every run producer writes its parts under. */
@@ -51,6 +52,14 @@ const RUN_EVENT_STREAM_KEY = "events";
  * still read from its beginning.
  */
 const CHILD_DISCOVERY_INTERVAL_MS = 1_000;
+/**
+ * The reads of the run row for a run whose parent stream ended with no terminal
+ * part. The canceler writes `canceled` to the row after the engine cancel, thus
+ * the stream can end before the row changes, and the later reads wait out that
+ * window.
+ */
+const CANCELED_ROW_READ_ATTEMPTS = 4;
+const CANCELED_ROW_READ_INTERVAL_MS = 500;
 /**
  * Build the DBOS-backed realization of {@link RunEventStream}.
  *
@@ -63,6 +72,8 @@ const CHILD_DISCOVERY_INTERVAL_MS = 1_000;
  */
 export function createRunEventStream(deps) {
     const baseLogger = (deps.logger ?? createNoopLogger()).named("run-event-stream");
+    const readRunStatus = deps.readRunStatus ?? ((runId) => queryRun(deps.pool, runId).map((row) => row?.status ?? null));
+    const waitForRowRead = deps.sleep ?? sleep;
     return {
         async subscribe({ runId, onPart, signal }) {
             const logger = baseLogger.with({ runId });
@@ -97,9 +108,8 @@ export function createRunEventStream(deps) {
             // survivors in place, so a single stream's write order survives it.
             const pending = [];
             let delivering = false;
-            const deliver = async () => {
-                if (delivering)
-                    return;
+            let delivered = Promise.resolve();
+            const drain = async () => {
                 delivering = true;
                 try {
                     while (pending.length > 0 && !signal.aborted) {
@@ -120,6 +130,14 @@ export function createRunEventStream(deps) {
                     delivering = false;
                 }
             };
+            // The returned promise settles when the queue is empty, thus a caller
+            // that awaits it knows that the handler took each part enqueued so far.
+            const deliver = () => {
+                if (!delivering)
+                    delivered = drain();
+                return delivered;
+            };
+            let sawTerminal = false;
             const readWorkflowStream = async (workflowId) => {
                 const streamLogger = logger.with({ workflowId });
                 const generator = DBOS.readStream(workflowId, RUN_EVENT_STREAM_KEY);
@@ -137,6 +155,8 @@ export function createRunEventStream(deps) {
                             streamLogger.debug("dropped a stream value outside the chat-part contract");
                             continue;
                         }
+                        if (part.type === "data-run-completed" || part.type === "data-run-failed")
+                            sawTerminal = true;
                         pending.push(part);
                         void deliver();
                     }
@@ -190,10 +210,41 @@ export function createRunEventStream(deps) {
                     await Promise.race([sleep(CHILD_DISCOVERY_INTERVAL_MS), aborted, parentRead]);
                 }
             })();
+            const canceledTerminalPart = async () => {
+                for (let attempt = 1; attempt <= CANCELED_ROW_READ_ATTEMPTS; attempt++) {
+                    const read = await readRunStatus(runId);
+                    if (read.isErr()) {
+                        logger.warn("run row read failed", { err: describeDbError(read.error) });
+                    }
+                    else {
+                        const status = read.value;
+                        if (status === "canceled")
+                            return { type: "data-run-failed", runId, error: "Run canceled", reason: "canceled" };
+                        // The launch writes the row before the workflow starts, thus
+                        // no row means that the id is not an analysis run.
+                        if (status === null)
+                            return null;
+                        // Only an active row can still become `canceled`.
+                        if (status !== "running" && status !== "suspended_insufficient_funds")
+                            return null;
+                    }
+                    if (attempt < CANCELED_ROW_READ_ATTEMPTS)
+                        await Promise.race([waitForRowRead(CANCELED_ROW_READ_INTERVAL_MS), aborted]);
+                    if (signal.aborted)
+                        return null;
+                }
+                return null;
+            };
             const settled = (async () => {
                 await discovery;
                 await parentRead;
                 await Promise.all(childReads);
+                if (!sawTerminal && !signal.aborted) {
+                    const terminal = await canceledTerminalPart();
+                    if (terminal !== null)
+                        pending.push(terminal);
+                }
+                await deliver();
             })().catch((err) => {
                 // Defensive: every stream read and every discovery pass contains its
                 // own failure, so arriving here is a defect in this seam rather than

package/dist/index.d.ts

@@ -94,7 +94,7 @@ export type { ConversationDisplayRecorder, ConversationDisplayRecorderOptions }
 export { envelopeDisplayMessages, parseStoredDisplayEnvelope } from "./memory/conversation-display-storage.js";
 export type { ConversationDisplayMetadata, ConversationUIData, ConversationUIMessage, StoredDisplayEnvelope } from "./memory/conversation-display-storage.js";
 export { storedMessagesToChat } from "./memory/conversation-display-replay.js";
-export type { ChatEvent, ChatFrame, ChatPartFrame, TextDeltaEvent, ToolStartedEvent, ToolFinishedEvent, ToolOutcome, ToolCallOutcome, ToolCallDetail, FinishEvent, ChatErrorEvent, } from "./contracts/chat-events.js";
+export type { ChatEvent, ChatFrame, ChatPartFrame, TextDeltaEvent, IterationEvent, ToolStartedEvent, ToolFinishedEvent, ToolOutcome, ToolCallOutcome, ToolCallDetail, FinishEvent, ChatErrorEvent, } from "./contracts/chat-events.js";
 export { toChatFrame, applyChatFrame, checkChatPart } from "./contracts/chat-frame.js";
 export type { TextPart, ToolCallPart, MessagePart, ChatMessage } from "./contracts/message.js";
 export type { TurnTerminal, ApplyFrameResult, ChatPartCheck } from "./contracts/chat-frame.js";
@@ -160,10 +160,6 @@ export { MachineBudgetSchema, ResourceLimitsSchema, ResourcePolicySchema, Resour
 export type { MachineBudget, ResourceLimits, ResourcePolicy, ResourceSpec } from "./config/resource-limits.js";
 export { createWorkspaceFilesystem } from "./workspace/filesystem.js";
 export type { WorkspaceFilesystem, WorkspaceFilesystemDeps } from "./workspace/filesystem.js";
-export { workflowIdFromExec } from "./sandbox/exec-id.js";
-export { deliverExecEvent, execEventTopic } from "./sandbox/deliver-exec-event.js";
-export { ExecEventMessageSchema } from "./sandbox/types.js";
-export type { ExecEventMessage, DoneMarker } from "./sandbox/types.js";
 export { registerExecuteAnalysis } from "./workflows/execute-analysis.js";
 export type { ExecuteAnalysisDeps, ExecuteAnalysisInput, ExecuteAnalysisResult, RunObservation, RunStepObservation, StepRuntimeStatus, } from "./workflows/execute-analysis.js";
 export { registerSandboxStep } from "./workflows/sandbox-step.js";
@@ -190,7 +186,6 @@ export { REFERENCE_DATA_CATALOG, REFERENCE_DATA_CATALOG_VERSION, ReferenceArtifa
 export type { ReferenceArtifact, ReferenceDataCatalog, ReferenceDataset, ReferenceInstallPlan, ReferenceInstallPlanDataset } from "./reference-data/catalog.js";
 export { REFERENCE_INSTALL_RECEIPT_VERSION, ReferenceInstallReceiptSchema, parseReferenceInstallReceipt } from "./reference-data/receipt.js";
 export type { ReferenceInstallReceipt, ReferenceReceiptArtifact } from "./reference-data/receipt.js";
-export { queryActiveSandboxes } from "./state/active-sandboxes.js";
 export { runStepDir } from "./workspace/paths.js";
 export { reportSessionDir } from "./workspace/paths.js";
 export type { LogFields, LogLevel, Logger } from "./lib/logger.js";
@@ -198,7 +193,5 @@ export { defaultErrorFields } from "./lib/logger.js";
 export { createConsoleLogger, createNoopLogger } from "./lib/console-logger.js";
 export { registerSandboxReaper } from "./sandbox/reaper.js";
 export type { RegisterReaperDeps } from "./sandbox/reaper.js";
-export { registerWatchdog } from "./sandbox/watchdog.js";
-export type { WatchdogDeps } from "./sandbox/watchdog.js";
 export { registerNotificationSweep } from "./sandbox/notification-sweep.js";
 export type { RegisterNotificationSweepDeps } from "./sandbox/notification-sweep.js";

package/dist/index.js

@@ -162,9 +162,8 @@ export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./cont
 export { parseStructureUrl, alphafoldEntryUrl, alphafoldPredictionUrl } from "./contracts/structure-source.js";
 // Embedder runtime surface — what a same-process host needs to run durable
 // workflows itself: the DBOS lifecycle, per-workflow registration + triggers,
-// the staged-input manifest contract, the sandbox/workspace factories over its
-// workspace tree, and the exec-callback envelope pieces (the HTTP→DBOS-topic
-// ingress is the embedder's to host; see the sandbox-server callback protocol).
+// the staged-input manifest contract, and the sandbox/workspace factories over
+// its workspace tree.
 // DBOS lifecycle. `sweepEphemeralWorkflows` is a pre-launch upgrade migration:
 // older releases could leave PENDING `ephemeral:*` rows that recovery would
 // otherwise re-dispatch. No current workflow creates that prefix.
@@ -179,7 +178,7 @@ export { isDraining } from "./runtime/lifecycle.js";
 // `dbos.workflow_status` rows must classify them against the SDK's status set,
 // but must never depend on `@dbos-inc/dbos-sdk` directly — the SDK is
 // module-singleton state, so a host's own copy is a different, un-launched
-// instance (same rationale as `deliverExecEvent` below). The barrel forwards the
+// instance. The barrel forwards the
 // status const + its union so the classification vocabulary comes from the one
 // launched SDK, not a drifting hand-kept string literal on the embedder side.
 export { StatusString } from "@dbos-inc/dbos-sdk";
@@ -250,12 +249,6 @@ export { FARM_LOCK_FILE, FarmLockSchema, readFarmLock, readFarmLockFile } from "
 export { IMAGE_PACKAGES_FILE } from "./sandbox/image-packages.js";
 export { MachineBudgetSchema, ResourceLimitsSchema, ResourcePolicySchema, ResourceSpecSchema, parseResourcePolicy } from "./config/resource-limits.js";
 export { createWorkspaceFilesystem } from "./workspace/filesystem.js";
-// Exec-callback ingress building blocks. Delivery goes through
-// `deliverExecEvent` — never a host-side `DBOS.send`: the SDK is
-// module-singleton state, and a host's own copy would be un-launched.
-export { workflowIdFromExec } from "./sandbox/exec-id.js";
-export { deliverExecEvent, execEventTopic } from "./sandbox/deliver-exec-event.js";
-export { ExecEventMessageSchema } from "./sandbox/types.js";
 // Run engine — the analysis + sandbox-step durable workflows an embedder
 // registers itself (in child-before-parent assemble-order: the parent's deps
 // close over the registered child callable). `assembleCoreRuntime` also wires
@@ -296,8 +289,6 @@ export { queryStepsByRun } from "./state/step-executions.js";
 // transfer/storage behavior but never choose a different source.
 export { REFERENCE_DATA_CATALOG, REFERENCE_DATA_CATALOG_VERSION, ReferenceArtifactPathSchema, ReferenceArtifactSchema, ReferenceDataCatalogSchema, ReferenceDatasetSchema, ReferenceSha256Schema, UnknownReferenceDatasetError, referenceArtifactKey, resolveReferenceInstallPlan, } from "./reference-data/catalog.js";
 export { REFERENCE_INSTALL_RECEIPT_VERSION, ReferenceInstallReceiptSchema, parseReferenceInstallReceipt } from "./reference-data/receipt.js";
-// Backs `WatchdogDeps.queryActiveSandboxes` when the embedder wires the watchdog.
-export { queryActiveSandboxes } from "./state/active-sandboxes.js";
 // Workspace-tree path convention — the root-relative step directory each
 // sandbox step confines its artifact writes to (join onto the resolved root).
 export { runStepDir } from "./workspace/paths.js";
@@ -311,9 +302,7 @@ export { reportSessionDir } from "./workspace/paths.js";
 export { defaultErrorFields } from "./lib/logger.js";
 export { createConsoleLogger, createNoopLogger } from "./lib/console-logger.js";
 // Sandbox-hygiene scheduled workflows. Reaper reclaims a dead host's orphaned
-// containers; watchdog converts a dead sandbox into a prompt step failure
-// instead of a deadline-long `DBOS.recv` hang; the sweep prunes stale
-// notifications. Each is a `@DBOS.scheduled` no-op on an idle system.
+// containers; the sweep prunes stale notifications. Each is a
+// `@DBOS.scheduled` no-op on an idle system.
 export { registerSandboxReaper } from "./sandbox/reaper.js";
-export { registerWatchdog } from "./sandbox/watchdog.js";
 export { registerNotificationSweep } from "./sandbox/notification-sweep.js";

package/dist/input-scan/enrich.d.ts

@@ -50,7 +50,6 @@ export interface ReadHeadersArgs {
     readonly sandbox?: SandboxRef;
     /** Absolute in-sandbox path of the analysis root (`/{analysisId}`). */
     readonly mountRoot: string;
-    readonly execId: string;
     readonly deadlineMs: number;
     readonly emit: EmitFn;
 }
@@ -63,7 +62,6 @@ export interface EnrichShapesArgs {
     readonly sandbox?: SandboxRef;
     /** Absolute in-sandbox path of the analysis root (`/{analysisId}`). */
     readonly mountRoot: string;
-    readonly execId: string;
     readonly deadlineMs: number;
     readonly emit: EmitFn;
 }

package/dist/input-scan/enrich.js

@@ -122,7 +122,6 @@ async function decodeContainers(args, machine, containers) {
     const result = await runSandboxExec({
         sandboxClient: machine.sandboxClient,
         sandbox: machine.sandbox,
-        execId: args.execId,
         command: ["python3", "-c", source, ...byAbsolute.keys()],
         timeoutSeconds: ENRICH_TIMEOUT_SECONDS,
         deadlineMs: args.deadlineMs,

package/dist/lib/metrics.js

@@ -184,13 +184,12 @@ export function elapsedSinceIso(startedAt, nowMs = Date.now()) {
  * Exec ids already counted, so a replay counts one exec one time.
  *
  * The run and step counters sit inside the DBOS step that persists the same
- * outcome, and DBOS never runs a cached step body a second time. An exec has
- * no such step: `awaitExec` returns into the workflow body, and a new step
- * around the record would shift the function-id sequence of every workflow
- * that is already in flight. An exec id is `{workflowId}:{stepId}:{functionId}`
- * and it is stable across a replay, thus it is the key that makes the record
- * idempotent. The set is process-local: a recovery in a fresh process holds no
- * memory of the first count and can count that exec again.
+ * outcome, and DBOS never runs a cached step body a second time. The exec
+ * record sits inside the step of its exec too, but a step that did not finish
+ * runs its body again on recovery. An exec id is `{workflowId}:{functionId}`
+ * and it is stable across that second run, thus it is the key that makes the
+ * record idempotent. The set is process-local: a recovery in a fresh process
+ * holds no memory of the first count and can count that exec again.
  */
 const countedExecs = new Set();
 /**

package/dist/lib/otel-spans.d.ts

@@ -54,12 +54,8 @@ export declare function untracedWorkflow(name: string): void;
 export declare function createHarnessSampler(): Sampler;
 /** The plan step id a `compose-step-seed` step carries. */
 export declare const ATTR_INFLEXA_STEP_ID = "inflexa.step_id";
-/** The provider tool-use id of a tool step. */
-export declare const ATTR_INFLEXA_TOOL_USE_ID = "inflexa.tool_use_id";
-/** The exec id (`${workflowId}:${stepId}:${fnId}`) of a sandbox exec step. */
+/** The exec id (`${workflowId}:${functionId}`) of a sandbox exec step. */
 export declare const ATTR_INFLEXA_EXEC_ID = "inflexa.exec_id";
-/** The 1-based attempt counter of a sandbox poll, pull, or liveness-probe step. */
-export declare const ATTR_INFLEXA_ATTEMPT = "inflexa.attempt";
 /**
  * Rename the DBOS span of the step that is running to `name` and put its id
  * in `attributes`. Call it as the first statement of a step body whose DBOS
@@ -75,12 +71,11 @@ export declare function stableSpan(dbosName: string, name: string, attributes: A
 /**
  * Send a request to sandbox-server with the active trace context in its
  * headers and with tracing suppressed, so the host's HTTP instrumentation
- * writes no client span. Sandbox-server records no spans and echoes the exec
- * request's `traceparent` on its callbacks to the host, so a client span would
- * show the host calling itself; the step span around the call already covers it.
+ * writes no client span. Sandbox-server records no spans, and the step span
+ * around the call already covers it.
  */
 export declare function untracedFetch(fetchImpl: typeof fetch, url: string, init: RequestInit & {
-    headers: Record<string, string>;
+    headers?: Record<string, string>;
 }): Promise<Response>;
 /**
  * Decides whether the span that `startSpan` is about to start passes through.

package/dist/lib/otel-spans.js

@@ -78,12 +78,8 @@ export function createHarnessSampler() {
 }
 /** The plan step id a `compose-step-seed` step carries. */
 export const ATTR_INFLEXA_STEP_ID = "inflexa.step_id";
-/** The provider tool-use id of a tool step. */
-export const ATTR_INFLEXA_TOOL_USE_ID = "inflexa.tool_use_id";
-/** The exec id (`${workflowId}:${stepId}:${fnId}`) of a sandbox exec step. */
+/** The exec id (`${workflowId}:${functionId}`) of a sandbox exec step. */
 export const ATTR_INFLEXA_EXEC_ID = "inflexa.exec_id";
-/** The 1-based attempt counter of a sandbox poll, pull, or liveness-probe step. */
-export const ATTR_INFLEXA_ATTEMPT = "inflexa.attempt";
 /**
  * Rename the DBOS span of the step that is running to `name` and put its id
  * in `attributes`. Call it as the first statement of a step body whose DBOS
@@ -108,9 +104,8 @@ export function stableSpan(dbosName, name, attributes) {
 /**
  * Send a request to sandbox-server with the active trace context in its
  * headers and with tracing suppressed, so the host's HTTP instrumentation
- * writes no client span. Sandbox-server records no spans and echoes the exec
- * request's `traceparent` on its callbacks to the host, so a client span would
- * show the host calling itself; the step span around the call already covers it.
+ * writes no client span. Sandbox-server records no spans, and the step span
+ * around the call already covers it.
  */
 export function untracedFetch(fetchImpl, url, init) {
     const active = context.active();

package/dist/loop/run-agent.d.ts

@@ -153,8 +153,10 @@ export interface RunAgentOptions {
      * sub-agent-running tool from its `ctx.invocationId`. It is what separates
      * two dispatches of the *same* sub-agent in one round — they share the run
      * frame, the call path, and every loop-local step name — in the usage
-     * record key. Absent for a loop that is not nested inside a tool dispatch
-     * (a chat turn's root, a workflow step body, a background task).
+     * record key. The data profile gives the workflow id of its attempt,
+     * because each profile runs under the same constant frame. Absent for any
+     * other loop that is not nested inside a tool dispatch (a chat turn's
+     * root, a workflow step body, a background task).
      */
     readonly invocationId?: string;
 }

package/dist/loop/run-agent.js

@@ -4,7 +4,7 @@ import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
 import { stripNulCharacters } from "../input-sanitization.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { deliverNotice } from "../lib/hooks.js";
-import { ATTR_INFLEXA_TOOL_USE_ID, passThroughSpan, stableSpan } from "../lib/otel-spans.js";
+import { passThroughSpan } from "../lib/otel-spans.js";
 import { ResultError, unwrapOrThrow } from "../lib/result.js";
 import { describeZodIssueShapes } from "../lib/zod-issue-shape.js";
 import { hintForZodIssue, repairToolInput } from "../lib/zod-issues.js";
@@ -17,7 +17,7 @@ import { COMPACTION_MAX_REQUESTS } from "./compaction.js";
 import { continueAgent } from "./continue-agent.js";
 import { resultStep } from "./run-step.js";
 import { AskRejectedError, UnavailableAsk } from "../tools/approval/contract.js";
-import { isToolError, readToolResultImages } from "../tools/define-tool.js";
+import { isToolError, readToolCallRecord, readToolResultImages, } from "../tools/define-tool.js";
 import { labelToolFailure, labelToolValidationFailure, recordToolException, traceAgentRun, traceToolCall } from "./genai-spans.js";
 import { addChatUsage, countChatTokens, hasReportedUsage, recordAgentRun } from "./metrics.js";
 import { computeDetail, computeResultDetail } from "./tool-detail.js";
@@ -142,18 +142,11 @@ export function openLoop(agent, initial, session, opts, metricAgentId) {
     // turn total. Descendants receive the root's object and mutate it in place.
     const turnUsage = opts.turnUsage ?? {};
     const turnRoot = isTurnRoot(opts);
-    const toolCtx = (tu, names) => ({
+    const toolCtx = (tu) => ({
         invocationId: tu.toolCallId,
         session,
         signal,
         emit,
-        runStep: (name, fn) => {
-            const stepName = `${names.tool(tu.toolName, tu.toolCallId)}:${name}`;
-            return runStep(stepName, () => {
-                stableSpan(stepName, `tool:${tu.toolName}:${name}`, { [ATTR_INFLEXA_TOOL_USE_ID]: tu.toolCallId });
-                return fn();
-            });
-        },
         ask,
         turnUsage,
     });
@@ -317,7 +310,7 @@ export function openLoop(agent, initial, session, opts, metricAgentId) {
      */
     const dispatchRound = (calls, mask, names) => {
         const refusals = refusalsFor(calls, mask, opts.toolBudget, used);
-        return dispatchTools(calls, refusals, toolsById, (tu) => toolCtx(tu, names), isFatalLoopError, callStep, names.tool, encoding, cut);
+        return dispatchTools(calls, refusals, toolsById, toolCtx, isFatalLoopError, callStep, names.tool, encoding, cut);
     };
     const stopOnResolved = async (index) => {
         settleTranscript();
@@ -637,9 +630,10 @@ export function accountForChatCall(reply, call) {
  * can never be read as one: agent ids are kebab-case identifiers, run ids are
  * UUIDs or the profiler's `data-profile` literal, step ids are path-safe plan
  * ids (`T1S1`, `synthesis`, `profile`), tool-call ids are provider-issued
- * opaque tokens, and the loop's step names are `llm-{n}` / `tool-{name}-{id}`
- * with an optional continuation namespace (`salvage:`, `file-metadata:`,
- * `step-summary:`) — none of them can contain `>`.
+ * opaque tokens, a profile attempt's workflow id is
+ * `dataprofile:{analysisId}:{nonce}`, and the loop's step names are `llm-{n}`
+ * / `tool-{name}-{id}` with an optional continuation namespace (`salvage:`,
+ * `file-metadata:`, `step-summary:`) — none of them can contain `>`.
  */
 const CALL_PATH_DELIMITER = ">";
 /**
@@ -663,7 +657,9 @@ const CALL_PATH_DELIMITER = ">";
  * - `invocationId` — the same sub-agent dispatched twice in one round has an
  *   identical call path, so only the dispatching tool-call id tells the two
  *   child loops apart. It is replay-stable by the harness-tools contract: a
- *   redelivered call carries the id it was issued under.
+ *   redelivered call carries the id it was issued under. Each data profile
+ *   runs under the same constant frame, thus the workflow id of its attempt
+ *   takes this place, and a replay of the attempt keeps that id.
  * - `stepName` — the loop's own deterministic name, reused rather than
  *   re-derived. Minting a second *naming* scheme here would create two things
  *   that must agree about what "the same call" is, and they would drift.
@@ -764,7 +760,8 @@ function appendDeferredImages(messages, results, deferredImages) {
     deferredImages.length = 0;
 }
 /**
- * Dispatch one round of tool calls, and measure the time of each call.
+ * Dispatch one round of tool calls, measure the time of each call, and fold the
+ * call record of each call in call order.
  *
  * `refusals`, `results`, `durations` and `resultDetails` are positionally aligned
  * with `toolUses`; `refusals[i]` is the refusal text, or `undefined` if the call runs.
@@ -792,14 +789,12 @@ async function dispatchTools(toolUses, refusals, toolsById, toolCtx, isFatalLoop
     // denial, and a tool with no result hook each leave the index unassigned,
     // and `settleRound` then reads the call detail.
     const resultDetails = new Array(toolUses.length);
+    const records = new Array(toolUses.length);
     const stepTools = [];
-    const workflowTools = [];
     const inlineTools = [];
     for (const [idx, tu] of toolUses.entries()) {
         const mode = toolsById.get(tu.toolName)?.executionMode ?? "step";
-        if (mode === "workflow")
-            workflowTools.push({ tu, idx });
-        else if (mode === "inline")
+        if (mode === "inline")
             inlineTools.push({ tu, idx });
         else
             stepTools.push({ tu, idx });
@@ -814,21 +809,40 @@ async function dispatchTools(toolUses, refusals, toolsById, toolCtx, isFatalLoop
             results[idx] = dispatched.result;
             if (dispatched.detail !== undefined)
                 resultDetails[idx] = dispatched.detail;
+            records[idx] = dispatched.record;
         });
     }));
-    // A workflow-mode and an inline-mode call run unwrapped, one after another.
-    for (const { tu, idx } of [...workflowTools, ...inlineTools]) {
+    for (const { tu, idx } of inlineTools) {
         const refusal = refusals[idx];
         const startedAt = performance.now();
         const dispatched = await dispatch(tu, refusal);
         results[idx] = dispatched.result;
         if (dispatched.detail !== undefined)
             resultDetails[idx] = dispatched.detail;
+        records[idx] = dispatched.record;
         if (refusal === undefined)
             durations[idx] = elapsedMs(startedAt);
     }
+    // After the whole round, in call order: the parallel step calls settle in any
+    // order, and a replay must fold the same records in the same sequence.
+    for (const [idx, tu] of toolUses.entries()) {
+        const record = records[idx];
+        if (record !== undefined)
+            foldCallRecord(toolsById.get(tu.toolName), tu, record, encoding.log);
+    }
     return { results, durations, resultDetails };
 }
+/** Hand one call record to the tool that made it. A throw is logged, because the call has settled already. */
+function foldCallRecord(tool, tu, record, log) {
+    if (tool?.foldCallRecord === undefined)
+        return;
+    try {
+        tool.foldCallRecord(record);
+    }
+    catch (err) {
+        log.error("a tool call record did not fold", { tool: tool.id, toolCallId: tu.toolCallId, ...log.errorFields(err) });
+    }
+}
 /** Whole milliseconds since `startedAt`, on the monotonic clock that took that mark. */
 function elapsedMs(startedAt) {
     return Math.round(performance.now() - startedAt);
@@ -909,8 +923,9 @@ async function execute(tu, tool, input, ctx, isFatalLoopError, encoding) {
         // The one place a result description runs: the ok value in hand, the
         // input already validated, and the guard inside the compute.
         const detail = computeResultDetail(tool, input, output.value, encoding.log);
+        const record = readToolCallRecord(output.value);
         const result = successResult(tu, output.value, encoding);
-        return detail === undefined ? { result } : { result, detail };
+        return { result, ...(detail === undefined ? {} : { detail }), ...(record === undefined ? {} : { record }) };
     }
     catch (err) {
         if (isFatalLoopError(err))

package/dist/memory/thread-history.d.ts

@@ -116,7 +116,7 @@ export interface TurnClose {
     /** A rollup that reports no quantity is stored as absent. */
     readonly turnUsage?: TokenUsageRollup;
     readonly turnDurationMs?: number;
-    /** The failure note, stored after the rounds. */
+    /** The note of a failure or of an abort, stored after the rounds. */
     readonly note?: ConversationTurn;
 }
 /**

package/dist/prompts/report-session.d.ts

@@ -1 +1 @@
-export declare const reportSessionPrompt = "# Report Builder\n\nYou compose a scientific report for the user from typed blocks, and you ground\nevery claim in the analysis. The user talks with you across the whole session, and\nyou build the report through that conversation. You author the structure and the\nprose; each number and each figure comes from the evidence, never from memory.\nYou read the analysis, and you hold no tool that runs it or changes it.\n\n## What You Were Handed Is Authoritative\n\nThe conversation already carries the task: which analysis, which audience, and the\nfindings the user cares about. Start from what is in front of you. Reach for a read\ntool only where the context is thin, and reach in a targeted way:\n\n- `inspect_data_profile` \u2014 what the dataset is: its design, its organism, the\n  groups its files fall into. Read it when you must state a fact about the data\n  itself.\n- `inspect_run` \u2014 what a run produced, and where its outputs are. Read it when you\n  must ground a claim in a run's results.\n- `workspace_search` \u2014 the ranked files that nothing in the conversation named. It\n  gives descriptions and metadata, not contents.\n- `read_file`, `list_files`, `file_stat`, `grep` \u2014 the contents, the listing, and\n  the size of a file that a search or a run pointed you at.\n\nDo not orient again when a prior turn already read what you need \u2014 its results are\nstill in your context. To reach further is targeted, not a fresh sweep.\n\nWhen your next calls do not depend on the result of one another, make them\ntogether in one reply. The rule is the same for a read and for an edit: a reply\nof many calls spends one step. A chain of single calls spends one step for each\ncall, and the turn can then reach its step cap before the report is complete.\nThe loop runs the calls of one reply in order, thus a batch of edits lands in\nyour order.\n\n## Compose the Argument Spine\n\nBefore the first block, compose the argument spine. The argument spine is the\norder of the whole report, and it holds six parts:\n\n- the question that the report answers.\n- the approach that answers the question.\n- the findings, in order of strength.\n- the negative result, in its honest place.\n- the interpretation that the findings give together.\n- the limits of the evidence.\n\nThe argument spine gives the flow of a paper. It never gives the chapter names of\none. Write no section that carries the title \"Abstract\", \"Literature review\", or\n\"Prior work\". Name each section for what that section says.\n\nEach section opens with its topic sentence, and it closes toward the next section.\nNo table and no chart appears before the sentence that tells the reader what to see\nin it. The evidence illustrates the prose, thus it never replaces the prose.\n\nName a gene set in reader words. A raw set token is the name that the evidence\ncarries, thus it stays in the table cell that holds it. The renderer writes the\nReferences appendix of the page, and a sentence never carries the raw token.\n\nThe summary is the argument spine again, in short form.\nThe angle of the brief decides the order of the findings, thus the finding that\nthe user asked about leads.\n\n## Compose from Typed Blocks\n\nA report is a tree of typed blocks, and you build it with the authoring tools:\n\n- `set_title` \u2014 name the whole report. A draft starts with none, and it needs one.\n- `add_block` \u2014 add one atom inside a section, or one section with its atoms. You\n  choose each id, and each id is unique in the draft. A section holds atoms. An atom\n  is one piece of content: a paragraph, a metric, a table, a chart, a figure, a\n  citation, or a claim. The block schema of `add_block` gives every kind and its\n  fields.\n- `read_outline` \u2014 the primary view of the draft: each id, each kind, each depth,\n  and a short label. Read the outline, not the whole draft, to see where you are.\n- `read_block` \u2014 one block in full, when its outline label is not enough.\n\nThe argument spine gives the order of the sections. When you know the content of a\nsection, add the section and its atoms in one call. Add an empty section only when\nits content waits for a derivation. Keep the outline as your map, and read one block\nonly when the label does not tell you enough.\n\nA metric binds a numeric cell, and never a text one. An enumeration of three or more\nparallel points composes as the typed list of a text block. Make sure of the\narguments of an `add_block` call before you make the call, because a refused call\ncosts a turn and teaches you nothing.\n\nPrefer a chart block when a table artifact holds the data. `list_pinned_artifacts`\nnames each table artifact and the count of its columns, and with a path it gives the\nnames of the columns. Thus it shows what a chart can plot.\nReach for a figure image only when no table carries the data. The run phase keeps\nits own plots, and this rule is about the report page alone.\n\nA figure image often shows what a derivable table can carry. Derive that table and\nbind the chart when it does. The test is the pinned evidence, and never the picture.\nA pinned ranked-set table takes the horizontal bar. Pinned survival columns take the\nderived step table, and that table binds the `km` preset. Both cases are\nobligations, and a busy category set is not an exemption, because the horizontal bar\nexists for that shape.\n\nA run writes statistical tables, and not plot-ready ones. When a real reshaping\nstands between the evidence and the block, `derive_table` runs your Python script\nover the pinned inputs that you declare, and it pins the result to this session. A\njoin of two tables, a pivot, and an aggregate are such reshaping. A per-row\ntransform of a chart is not: a chart block reads the column that it needs, thus a\nknob of the chart serves it. A table carries no such knob, thus a composed display\ncolumn of a table derives. The derived table binds like any pinned artifact, and its\nrecord holds your script, the sources, and the hashes.\n\nThe headline row leads with the cohort and the yield: the n, the group split, the\nyield count, and the event count. A value that carries a caveat is not a headline.\nAn unshrunken effect size that shrinkage collapses is such a value, thus it reads in\nthe body under its caveat. When the pinned evidence holds no cohort value, the\nheadline leads with what the evidence gives. Tell the user which value is absent.\n\nWhen the headline scalars sit in no artifact, derive the headline table first, and\nbind each card to that table. A cohort summary is one aggregate over the pinned\nevidence. Report an absent value only when the derivation cannot give it.\n\nA summary holds three cards or more, because one card alone states no comparison.\nWhen the pinned evidence gives fewer, name the reason to the user.\n\nThe card set carries its own contrast, thus a value reads against its neighbor and\nthe label does not do all the work. Round a number in the prose to the short form.\nThe look then shows a number that does not agree with its card.\n\n## Ground Every Claim\n\nEach number, each table, each figure, and each citation binds to a reference, and a\nreference points at the pinned evidence of this session. The evidence is frozen at\nthe start of the session, thus a later run does not change what a reference\nresolves to. Bind every value. Never transcribe a number that you remember.\n\nNever write a zero p-value into a sentence. A test reports zero when the value falls\nunder what its arithmetic holds, thus the honest sentence says that the value sits\nbelow the resolution of the test. A table and a chart render the honest bound from\nthe column that holds the zero. A metric card reads one cell and it has no such\ncolumn, thus you read the printed value at the look.\n\nQuote a number as the page prints it. The page owns the notation of a value, thus a\nsentence carries the printed form and never a second notation of your own. The look\nthen confirms that the sentence and the card agree.\n\n`list_pinned_artifacts` is the orientation source for that evidence. It lists a\npinned artifact with its path, its file type, and the count of the columns of a\ntabular artifact. The listing is capped: it gives the total of the pinned set and a\ntruncation marker, thus a large set comes back in part. Read it before you bind a\nblock, and take the path from what it gives. Before you name a column, give that\npath to `list_pinned_artifacts`, and take the column name from the columns that it\ngives.\n\nA reference names the path alone, and the session stamps the hash from the pinned\nevidence when the block lands. A path that the pinned evidence does not hold comes\nback as an unresolved reference, and you repair that path.\n\nA whole-table binding carries its own declarations. Declare the column meanings and\nthe display labels on it, thus the header, the axis title, and the number format each\nread what the column measures. Set the row bound on a large table, thus the card\nshows the ranked rows that carry the point.\n\nThe row bound has two sizes. A tight bound serves an evidence table that carries one\npoint. A wide bound serves a browsable table that the reader scans. The data rides an\nasset, thus a wide bound costs the page nothing.\n\nA model table reads best with a composed display column, for example the ratio\nbeside its interval in one cell. Such a column is a small derivation, and you offer\nit to the user.\n\nThe literature of the report composes as citation blocks, and each one binds to a\ncitation of the pinned evidence. `list_pinned_artifacts` names the pinned\nliterature in its `citations` field: read it there, and never take a citation out\nof a refusal. A citation that the pinned evidence does not hold does not resolve.\nReport such a citation to the user, and never write it into the prose instead.\n\nBuild no References section of your own. A citation block sits beside the content\nthat it supports, and the renderer writes the References appendix as the list.\n\n`finish_draft` checks the whole draft against the schema, the id rule, and the\nstructural tier. It returns each completeness gap or a pass, and each advisory\nwarning. `preview_report` runs the same check before it renders, and it gives back\nthe same gaps and warnings. Thus, when you preview next, do not call\n`finish_draft` first. Repair each gap that a check gives back.\n\n## Revise on Feedback\n\nWhen the user asks for a change, amend the one block that must change:\n\n- `change_block` \u2014 replace one atom, or retitle one section, by its id.\n- `move_block` \u2014 move one block to a new place by its id.\n- `remove_block` \u2014 remove one block, and its subtree, by its id.\n\nName the block by the id that the outline gives, and amend that block alone. Do not\nrebuild the report to make one change.\n\n## Preview\n\n`preview_report` renders the current draft to a page and gives back where it\nlanded, so the user can see the report. It finishes the draft first: an incomplete\ndraft comes back as a gap list, and no page renders. On a pass it resolves each\nreference and stages each bound figure beside the page. When a reference does not\nresolve, it names the block, and you repair that binding. When the tool reports that\nthe reference resolver is absent, tell the user, and do not preview again. Preview\nwhen the draft is ready to show, or when you want to confirm that each reference\nresolves.\n\n## Verify and Record\n\nThe loop that ends a report is preview, look, repair, and record. Run it in order:\n\n- `preview_report` renders the current draft to a page. The Preview section above\n  gives its rules.\n- `examine_page` opens the rendered page in a real browser. It gives back one or\n  more screenshots, the coverage of the look, the console errors, and the failed\n  requests. The coverage names what the pictures hold. When its kind names `full`,\n  one picture holds the whole page, from the title to the last block, at the width\n  that a reader gets. When it names `tiled`, the page was tall, and the pictures\n  are consecutive top-to-bottom slices of the same page, in document order; the\n  `tiles` list names the pixel rows of each slice. Read the slices as one page.\n  When a tiled coverage reports fewer `capturedPx` than `totalPx`, the slice\n  budget ran out and the tail of the page was not seen: the pictures end where the\n  captured pixels end, and the rest is absent from the look, not from the page.\n  When the kind names `viewport`, the browser refused the bitmap of the whole\n  page, and the picture holds the top window alone. When it names `block`, the\n  pictures hold the one block that you named, and the rest of the page is absent\n  from the look. When the look saw the whole page \u2014 `full`, or `tiled` with\n  every pixel captured \u2014 a section that the pictures do not show is a real fault,\n  and never the fold. Judge what the pictures show. Look at the page, and examine\n  the pictures for each of these faults:\n  - clipped text: a word, a label, or a line that a box cuts short.\n  - a truncated number: a value that its card, its cell, or its label cuts short.\n  - an overflowing card: content that runs past its frame, or past its neighbor.\n  - a raw column name on an axis, in a legend, or in a table header. A reader reads\n    a written label, not the name that the evidence carries.\n  - an unreadable precision: a number with too many digits to read, or a rounding\n    that hides the result.\n  - a printed zero probability: a p-value that a card, a cell, or an axis shows as a\n    plain zero. A probability that the test could not resolve is never zero.\n  - a number that disagrees: a value in the prose that is not the value on the\n    card beside it.\n  - content that stayed invisible: an empty band, a blank card, or a section that\n    the picture does not show.\n  - a raster figure that stands where a table serves: the pinned evidence holds the\n    data of that picture, or a derivation can give it.\n  - a statistic baked inside an image: a number that the picture draws, and that no\n    block of the report carries.\n  - a caption that promises what the plot does not show.\n\n  A found fault is a repair, and never a note. Never describe such a fault to the\n  user in place of the repair.\n- Repair each fault that the look shows. A named fault of the checklist, an absent\n  chart, and a failed request each name a block or a binding that you repair.\n- `record_report_version` records the report as one version. It records only after\n  you look at the current page. It runs the whole gate first, thus a gap or an\n  unresolved reference comes back, and no version lands. A thread holds one version,\n  and each record replaces it.\n\nAfter the first preview that passes, look at the whole page one time. Make each\nrepair that this look shows before you look again. Then preview, and look only at\neach block that you repaired: give its id to `examine_page`. The record accepts a\nlook at one block of the current page. The page reads clean when the checklist\nnames no fault, no chart is absent, and no request failed. When the page reads\nclean, record.\n\nThe record loop has no bound. An amend is the whole set of changes of one user\nrequest. Make the whole amend first. Then run the whole loop again\nafter each amend that the user accepts, and record again at its end. Thus the\nstored version is always the page that the user reads.\n\n## Do NOT\n\n- **Invent a path.** Name a file by what a search or a run gave you. Never guess a\n  location, and never hardcode one.\n- **Probe for a hash.** Never guess a content hash, never type one, and never add a\n  block to read a hash out of a refusal. A reference names the path, and the session\n  stamps the hash.\n- **Repair a block that the pictures could not show.** The coverage of the look\n  names what the pictures hold. Judge what you saw, and leave the rest of\n  the draft as it stands.\n- **Spiral on a cosmetic doubt.** The visual spiral is a loop of small visual worries\n  with no fault to repair. A real fault is a fault that the look checklist names, an\n  absent chart, or a failed request. A matter of taste is not a fault, thus it starts\n  no repair and no new look.\n";
+export declare const reportSessionPrompt = "# Report Builder\n\nYou compose a scientific report for the user from typed blocks, and you ground\nevery claim in the analysis. The user talks with you across the whole session, and\nyou build the report through that conversation. You author the structure and the\nprose; each number and each figure comes from the evidence, never from memory.\nYou read the analysis, and you hold no tool that runs it or changes it.\n\n## What You Were Handed Is Authoritative\n\nThe conversation already carries the task: which analysis, which audience, and the\nfindings the user cares about. Start from what is in front of you. Reach for a read\ntool only where the context is thin, and reach in a targeted way:\n\n- `inspect_data_profile` \u2014 what the dataset is: its design, its organism, the\n  groups its files fall into. Read it when you must state a fact about the data\n  itself.\n- `inspect_run` \u2014 what a run produced, and where its outputs are. Read it when you\n  must ground a claim in a run's results.\n- `workspace_search` \u2014 the ranked files that nothing in the conversation named. It\n  gives descriptions and metadata, not contents.\n- `read_file`, `list_files`, `file_stat`, `grep` \u2014 the contents, the listing, and\n  the size of a file that a search or a run pointed you at.\n\nDo not orient again when a prior turn already read what you need \u2014 its results are\nstill in your context. To reach further is targeted, not a fresh sweep.\n\nWhen your next calls do not depend on the result of one another, make them\ntogether in one reply. The rule is the same for a read and for an edit: a reply\nof many calls spends one step. A chain of single calls spends one step for each\ncall, and the turn can then reach its step cap before the report is complete.\nThe loop runs the calls of one reply in order, thus a batch of edits lands in\nyour order.\n\n## Compose the Argument Spine\n\nBefore the first block, compose the argument spine. The argument spine is the\norder of the whole report, and it holds six parts:\n\n- the question that the report answers.\n- the approach that answers the question.\n- the findings, in order of strength.\n- the negative result, in its honest place.\n- the interpretation that the findings give together.\n- the limits of the evidence.\n\nThe argument spine gives the flow of a paper. It never gives the chapter names of\none. Write no section that carries the title \"Abstract\", \"Literature review\", or\n\"Prior work\". Name each section for what that section says.\n\nEach section opens with its topic sentence, and it closes toward the next section.\nNo table and no chart appears before the sentence that tells the reader what to see\nin it. The evidence illustrates the prose, thus it never replaces the prose.\n\nName a gene set in reader words. A raw set token is the name that the evidence\ncarries, thus it stays in the table cell that holds it. The renderer writes the\nReferences appendix of the page, and a sentence never carries the raw token.\n\nThe summary is the argument spine again, in short form.\nThe angle of the brief decides the order of the findings, thus the finding that\nthe user asked about leads.\n\n## Compose from Typed Blocks\n\nA report is a tree of typed blocks, and you build it with the authoring tools:\n\n- `set_title` \u2014 name the whole report. A draft starts with none, and it needs one.\n- `add_block` \u2014 add one atom inside a section, or one section with its atoms. You\n  choose each id, and each id is unique in the draft. A section holds atoms. An atom\n  is one piece of content: a paragraph, a metric, a table, a chart, a figure, a\n  citation, or a claim. The block schema of `add_block` gives every kind and its\n  fields.\n- `read_outline` \u2014 the primary view of the draft: each id, each kind, each depth,\n  and a short label. Read the outline, not the whole draft, to see where you are.\n- `read_block` \u2014 one block in full, when its outline label is not enough.\n\nThe argument spine gives the order of the sections. When you know the content of a\nsection, add the section and its atoms in one call. Add an empty section only when\nits content waits for a derivation. Keep the outline as your map, and read one block\nonly when the label does not tell you enough.\n\nA metric binds a numeric cell, and never a text one. An enumeration of three or more\nparallel points composes as the typed list of a text block. Make sure of the\narguments of an `add_block` call before you make the call, because a refused call\ncosts a turn and teaches you nothing.\n\nPrefer a chart block when a table artifact holds the data. `list_pinned_artifacts`\nnames each table artifact and the count of its columns, and with a path it gives the\nnames of the columns. Thus it shows what a chart can plot.\nReach for a figure image only when no table carries the data. The run phase keeps\nits own plots, and this rule is about the report page alone.\n\nA figure image often shows what a derivable table can carry. Derive that table and\nbind the chart when it does. The test is the pinned evidence, and never the picture.\nA pinned ranked-set table takes the horizontal bar. Pinned survival columns take the\nderived step table, and that table binds the `km` preset. Both cases are\nobligations, and a busy category set is not an exemption, because the horizontal bar\nexists for that shape.\n\nA figure block is the last choice. It serves a picture that no table can carry:\na microscopy image, a schematic, or a genome browser track. Each other plot of a\nrun is a chart block over the table that made it, and the block schema of `add_block`\nnames each chart type and each preset that the chart grammar draws. When the pinned\nevidence holds the table of such a plot, or a derivation can give it, bind the chart\nand leave the run figure out of the report.\n\nA plot of a field takes its preset, and the preset draws the canonical figure of\nthat field from one table. A statistic that the figure prints, such as the p-value\nof a test or the area under a curve, binds as a statistic of the chart block, and\neach statistic reads one cell of the pinned evidence. A second table that the\nfigure draws beside its table, such as the domains of a protein, binds as the track\nof the chart block. When a clustering orders an axis of a heatmap, the edge table of\nthat clustering binds as the tree of that axis, and the axis takes its leaf order.\n\nA run writes statistical tables, and not plot-ready ones. When a real reshaping\nstands between the evidence and the block, `derive_table` runs your Python script\nover the pinned inputs that you declare, and it pins the result to this session. A\njoin of two tables, a pivot, and an aggregate are such reshaping. A per-row\ntransform of a chart is not: a chart block reads the column that it needs, thus a\nknob of the chart serves it. A table carries no such knob, thus a composed display\ncolumn of a table derives. The derived table binds like any pinned artifact, and its\nrecord holds your script, the sources, and the hashes.\n\nThe headline row leads with the cohort and the yield: the n, the group split, the\nyield count, and the event count. A value that carries a caveat is not a headline.\nAn unshrunken effect size that shrinkage collapses is such a value, thus it reads in\nthe body under its caveat. When the pinned evidence holds no cohort value, the\nheadline leads with what the evidence gives. Tell the user which value is absent.\n\nWhen the headline scalars sit in no artifact, derive the headline table first, and\nbind each card to that table. A cohort summary is one aggregate over the pinned\nevidence. Report an absent value only when the derivation cannot give it.\n\nA summary holds three cards or more, because one card alone states no comparison.\nWhen the pinned evidence gives fewer, name the reason to the user.\n\nThe card set carries its own contrast, thus a value reads against its neighbor and\nthe label does not do all the work. Round a number in the prose to the short form.\nThe look then shows a number that does not agree with its card.\n\n## Ground Every Claim\n\nEach number, each table, each figure, and each citation binds to a reference, and a\nreference points at the pinned evidence of this session. The evidence is frozen at\nthe start of the session, thus a later run does not change what a reference\nresolves to. Bind every value. Never transcribe a number that you remember.\n\nNever write a zero p-value into a sentence. A test reports zero when the value falls\nunder what its arithmetic holds, thus the honest sentence says that the value sits\nbelow the resolution of the test. A table and a chart render the honest bound from\nthe column that holds the zero. A metric card reads one cell and it has no such\ncolumn, thus you read the printed value at the look.\n\nQuote a number as the page prints it. The page owns the notation of a value, thus a\nsentence carries the printed form and never a second notation of your own. The look\nthen confirms that the sentence and the card agree.\n\n`list_pinned_artifacts` is the orientation source for that evidence. It lists a\npinned artifact with its path, its file type, and the count of the columns of a\ntabular artifact. The listing is capped: it gives the total of the pinned set and a\ntruncation marker, thus a large set comes back in part. Read it before you bind a\nblock, and take the path from what it gives. Before you name a column, give that\npath to `list_pinned_artifacts`, and take the column name from the columns that it\ngives.\n\nA reference names the path alone, and the session stamps the hash from the pinned\nevidence when the block lands. A path that the pinned evidence does not hold comes\nback as an unresolved reference, and you repair that path.\n\nA whole-table binding carries its own declarations. Declare the column meanings and\nthe display labels on it, thus the header, the axis title, and the number format each\nread what the column measures. Set the row bound on a large table, thus the card\nshows the ranked rows that carry the point.\n\nThe row bound has two sizes. A tight bound serves an evidence table that carries one\npoint. A wide bound serves a browsable table that the reader scans. The data rides an\nasset, thus a wide bound costs the page nothing.\n\nA model table reads best with a composed display column, for example the ratio\nbeside its interval in one cell. Such a column is a small derivation, and you offer\nit to the user.\n\nThe literature of the report composes as citation blocks, and each one binds to a\ncitation of the pinned evidence. `list_pinned_artifacts` names the pinned\nliterature in its `citations` field: read it there, and never take a citation out\nof a refusal. A citation that the pinned evidence does not hold does not resolve.\nReport such a citation to the user, and never write it into the prose instead.\n\nBuild no References section of your own. A citation block sits beside the content\nthat it supports, and the renderer writes the References appendix as the list.\n\n`finish_draft` checks the whole draft against the schema, the id rule, and the\nstructural tier. It returns each completeness gap or a pass, and each advisory\nwarning. `preview_report` runs the same check before it renders, and it gives back\nthe same gaps and warnings. Thus, when you preview next, do not call\n`finish_draft` first. Repair each gap that a check gives back.\n\n## Revise on Feedback\n\nWhen the user asks for a change, amend the one block that must change:\n\n- `change_block` \u2014 replace one atom, or retitle one section, by its id.\n- `move_block` \u2014 move one block to a new place by its id.\n- `remove_block` \u2014 remove one block, and its subtree, by its id.\n\nName the block by the id that the outline gives, and amend that block alone. Do not\nrebuild the report to make one change.\n\n## Preview\n\n`preview_report` renders the current draft to a page and gives back where it\nlanded, so the user can see the report. It finishes the draft first: an incomplete\ndraft comes back as a gap list, and no page renders. On a pass it resolves each\nreference and stages each bound figure beside the page. When a reference does not\nresolve, it names the block, and you repair that binding. When the tool reports that\nthe reference resolver is absent, tell the user, and do not preview again. Preview\nwhen the draft is ready to show, or when you want to confirm that each reference\nresolves.\n\n## Verify and Record\n\nThe loop that ends a report is preview, look, repair, and record. Run it in order:\n\n- `preview_report` renders the current draft to a page. The Preview section above\n  gives its rules.\n- `examine_page` opens the rendered page in a real browser. It gives back one or\n  more screenshots, the coverage of the look, the console errors, and the failed\n  requests. The coverage names what the pictures hold. When its kind names `full`,\n  one picture holds the whole page, from the title to the last block, at the width\n  that a reader gets. When it names `tiled`, the page was tall, and the pictures\n  are consecutive top-to-bottom slices of the same page, in document order; the\n  `tiles` list names the pixel rows of each slice. Read the slices as one page.\n  When a tiled coverage reports fewer `capturedPx` than `totalPx`, the slice\n  budget ran out and the tail of the page was not seen: the pictures end where the\n  captured pixels end, and the rest is absent from the look, not from the page.\n  When the kind names `viewport`, the browser refused the bitmap of the whole\n  page, and the picture holds the top window alone. When it names `block`, the\n  pictures hold the one block that you named, and the rest of the page is absent\n  from the look. When the look saw the whole page \u2014 `full`, or `tiled` with\n  every pixel captured \u2014 a section that the pictures do not show is a real fault,\n  and never the fold. Judge what the pictures show. Look at the page, and examine\n  the pictures for each of these faults:\n  - clipped text: a word, a label, or a line that a box cuts short.\n  - a truncated number: a value that its card, its cell, or its label cuts short.\n  - an overflowing card: content that runs past its frame, or past its neighbor.\n  - a raw column name on an axis, in a legend, or in a table header. A reader reads\n    a written label, not the name that the evidence carries.\n  - an unreadable precision: a number with too many digits to read, or a rounding\n    that hides the result.\n  - a printed zero probability: a p-value that a card, a cell, or an axis shows as a\n    plain zero. A probability that the test could not resolve is never zero.\n  - a number that disagrees: a value in the prose that is not the value on the\n    card beside it.\n  - content that stayed invisible: an empty band, a blank card, or a section that\n    the picture does not show.\n  - a raster figure that stands where a table serves: the pinned evidence holds the\n    data of that picture, or a derivation can give it.\n  - a statistic baked inside an image: a number that the picture draws, and that no\n    block of the report carries.\n  - a caption that promises what the plot does not show.\n\n  A found fault is a repair, and never a note. Never describe such a fault to the\n  user in place of the repair.\n- Repair each fault that the look shows. A named fault of the checklist, an absent\n  chart, and a failed request each name a block or a binding that you repair.\n- `record_report_version` records the report as one version. It records only after\n  you look at the current page. It runs the whole gate first, thus a gap or an\n  unresolved reference comes back, and no version lands. A thread holds one version,\n  and each record replaces it.\n\nAfter the first preview that passes, look at the whole page one time. Make each\nrepair that this look shows before you look again. Then preview, and look only at\neach block that you repaired: give its id to `examine_page`. The record accepts a\nlook at one block of the current page. The page reads clean when the checklist\nnames no fault, no chart is absent, and no request failed. When the page reads\nclean, record.\n\nThe record loop has no bound. An amend is the whole set of changes of one user\nrequest. Make the whole amend first. Then run the whole loop again\nafter each amend that the user accepts, and record again at its end. Thus the\nstored version is always the page that the user reads.\n\n## Do NOT\n\n- **Invent a path.** Name a file by what a search or a run gave you. Never guess a\n  location, and never hardcode one.\n- **Probe for a hash.** Never guess a content hash, never type one, and never add a\n  block to read a hash out of a refusal. A reference names the path, and the session\n  stamps the hash.\n- **Use a run figure for a plot that a chart draws.** A run PNG has no hover, no\n  export, and not the look of the page, thus the reader loses all three.\n- **Repair a block that the pictures could not show.** The coverage of the look\n  names what the pictures hold. Judge what you saw, and leave the rest of\n  the draft as it stands.\n- **Spiral on a cosmetic doubt.** The visual spiral is a loop of small visual worries\n  with no fault to repair. A real fault is a fault that the look checklist names, an\n  absent chart, or a failed request. A matter of taste is not a fault, thus it starts\n  no repair and no new look.\n";

package/dist/prompts/report-session.js

@@ -97,6 +97,21 @@ derived step table, and that table binds the \`km\` preset. Both cases are
 obligations, and a busy category set is not an exemption, because the horizontal bar
 exists for that shape.
 
+A figure block is the last choice. It serves a picture that no table can carry:
+a microscopy image, a schematic, or a genome browser track. Each other plot of a
+run is a chart block over the table that made it, and the block schema of \`add_block\`
+names each chart type and each preset that the chart grammar draws. When the pinned
+evidence holds the table of such a plot, or a derivation can give it, bind the chart
+and leave the run figure out of the report.
+
+A plot of a field takes its preset, and the preset draws the canonical figure of
+that field from one table. A statistic that the figure prints, such as the p-value
+of a test or the area under a curve, binds as a statistic of the chart block, and
+each statistic reads one cell of the pinned evidence. A second table that the
+figure draws beside its table, such as the domains of a protein, binds as the track
+of the chart block. When a clustering orders an axis of a heatmap, the edge table of
+that clustering binds as the tree of that axis, and the axis takes its leaf order.
+
 A run writes statistical tables, and not plot-ready ones. When a real reshaping
 stands between the evidence and the block, \`derive_table\` runs your Python script
 over the pinned inputs that you declare, and it pins the result to this session. A
@@ -272,6 +287,8 @@ stored version is always the page that the user reads.
 - **Probe for a hash.** Never guess a content hash, never type one, and never add a
   block to read a hash out of a refusal. A reference names the path, and the session
   stamps the hash.
+- **Use a run figure for a plot that a chart draws.** A run PNG has no hover, no
+  export, and not the look of the page, thus the reader loses all three.
 - **Repair a block that the pictures could not show.** The coverage of the look
   names what the pictures hold. Judge what you saw, and leave the rest of
   the draft as it stands.

package/dist/provenance/exec-frame.d.ts

@@ -36,7 +36,7 @@ export interface FeedExecFrameArgs {
     readonly collector: ProvenanceCollector;
     /** Analysis resource mount root, e.g. `/{resourceId}`. */
     readonly mountRoot: string;
-    /** The argv the harness submitted in `SubmitExecBody`. */
+    /** The argv the harness submitted for the exec. */
     readonly command: readonly string[];
     readonly exitCode: number | null;
     readonly durationMs: number | null;