@inflexa-ai/harness 0.12.0 → 0.14.0

package/dist/index.d.ts

@@ -23,7 +23,7 @@ export type { ProvenanceCollector } from "./provenance/collector.js";
 export { UnavailablePreviewPublisher } from "./tools/report/preview-publisher.js";
 export type { PreviewPublisher, PreviewMintResult } from "./tools/report/preview-publisher.js";
 export { createDbosRunLauncher } from "./execution/dbos-run-launcher.js";
-export type { RunLauncher, LaunchOptions, LaunchRunOptions, LaunchOutcome } from "./execution/run-launcher.js";
+export type { RunLauncher, LaunchOptions } from "./execution/run-launcher.js";
 export { defineTool, isToolError } from "./tools/define-tool.js";
 export type { Tool, ToolDefinition, ToolContext, ToolError } from "./tools/define-tool.js";
 export { createAskGateway } from "./tools/approval/gateway.js";
@@ -54,6 +54,7 @@ export { createThreadStore } from "./memory/thread-store.js";
 export type { ThreadStore, Thread, CreateThreadInput, ListThreadsInput, ThreadPage } from "./memory/thread-store.js";
 export { createThreadHistory } from "./memory/thread-history.js";
 export type { ThreadHistory, StoredMessage, MessagePage, RetractOutcome } from "./memory/thread-history.js";
+export { syntheticUserMessage, syntheticRecordMessage, isSyntheticUserMessage, isSyntheticRecordMessage } from "./memory/ai-sdk-message-storage.js";
 export { contentToCortexMessages } from "./memory/content-to-cortex.js";
 export { createCardResolver } from "./memory/reconstruct-cards.js";
 export type { ToolCardResolver, StoredToolCallForCard } from "./memory/reconstruct-cards.js";
@@ -88,9 +89,11 @@ export { deliverExecEvent, execEventTopic } from "./sandbox/deliver-exec-event.j
 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, RunProvenanceEvent } from "./workflows/execute-analysis.js";
+export type { ExecuteAnalysisDeps, ExecuteAnalysisInput, ExecuteAnalysisResult, RunObservation, RunProvenanceEvent, RunStepObservation, StepRuntimeStatus, } from "./workflows/execute-analysis.js";
 export { registerSandboxStep } from "./workflows/sandbox-step.js";
 export type { SandboxStepDeps, SandboxStepInput, SandboxStepResult, SandboxAgentBuildContext } from "./workflows/sandbox-step.js";
+export { createRunEventStream } from "./execution/run-event-stream.js";
+export type { RunEventStream, RunEventStreamDeps, RunEventSubscribeOptions, RunEventPartHandler } from "./execution/run-event-stream.js";
 export { createSandboxAgents, SANDBOX_AGENT_META } from "./agents/sandbox/index.js";
 export type { SandboxAgentDeps, SandboxStepCoords, AgentMeta } from "./agents/sandbox/index.js";
 export { AnalysisPlanSchema } from "./schemas/workflow-state.js";
@@ -101,8 +104,8 @@ export type { ValidatePlanOptions } from "./schemas/validate-plan.js";
 export type { ValidationResult } from "./schemas/validate-plan.js";
 export { upsertPlan, loadPlan } from "./state/plans.js";
 export type { UpsertPlanInput } from "./state/plans.js";
-export { insertRun, queryActiveRun, updateRunStatus, queryRun, queryRunsByAnalysis, RunDedupCollisionError } from "./state/runs.js";
-export type { InsertRunInput } from "./state/runs.js";
+export { insertRun, reserveRunById, queryActiveRun, queryActiveRunsByAnalysis, updateRunStatus, queryRun, queryRunsByAnalysis, RunDedupCollisionError, RunIdentityCollisionError, } from "./state/runs.js";
+export type { InsertRunInput, RunReservation } from "./state/runs.js";
 export { queryStepsByRun } from "./state/step-executions.js";
 export type { CortexRunRow, StepExecutionRow, RunStatus } from "./state/schema.js";
 export type { DbError } from "./lib/db-result.js";

package/dist/index.js

@@ -81,6 +81,16 @@ export { createStreamingChat } from "./providers/streaming-chat.js";
 export { prepareChatTurn } from "./app/chat-turn.js";
 export { createThreadStore } from "./memory/thread-store.js";
 export { createThreadHistory } from "./memory/thread-history.js";
+// The synthetic-message primitives. A host appends a record of out-of-band work (an analysis run's
+// outcome) into a thread through `appendTurn`, and needs a message the model reads but that is not
+// user input — which is exactly what the marker denotes. The constructor is exported rather than
+// the marker key so a host can never hand-assemble a message that the turn-boundary predicates
+// (`isGenuineUserStart` and its SQL twin) would then fail to recognise; `isSyntheticUserMessage`
+// lets a host renderer tell such a message apart from a genuine user turn on the way back out.
+// `syntheticRecordMessage` is the one a HOST reaches for: equally non-turn-opening, but rendered —
+// the display reconstruction emits it as a `system` message rather than dropping it as loop
+// machinery, so an appended run outcome is visible in the transcript instead of silently absent.
+export { syntheticUserMessage, syntheticRecordMessage, isSyntheticUserMessage, isSyntheticRecordMessage } from "./memory/ai-sdk-message-storage.js";
 export { contentToCortexMessages } from "./memory/content-to-cortex.js";
 export { createCardResolver } from "./memory/reconstruct-cards.js";
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./contracts/part-registry.js";
@@ -89,11 +99,9 @@ export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./cont
 // 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).
-// DBOS lifecycle. `sweepEphemeralWorkflows` is a pre-launch boot duty: once the
-// `ephemeral` workflow is registered, a host crash mid-run leaves a PENDING
-// `ephemeral:*` row that the next launch's recovery would re-dispatch (a sandbox
-// for a chat turn that no longer exists). The embedder sweeps it with a direct
-// system-DB UPDATE between state-init and `launchDbos` — the only race-free point.
+// 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.
 export { launchDbos, shutdownDbos, sweepEphemeralWorkflows } from "./runtime/dbos.js";
 // DBOS workflow-status vocabulary. An embedder that reads its own
 // `dbos.workflow_status` rows must classify them against the SDK's status set,
@@ -140,6 +148,15 @@ export { ExecEventMessageSchema } from "./sandbox/types.js";
 // these, but an embedder running only the run engine registers them directly.
 export { registerExecuteAnalysis } from "./workflows/execute-analysis.js";
 export { registerSandboxStep } from "./workflows/sandbox-step.js";
+// Run-event read seam — the fine-grained durable channel beside `observeRun`.
+// The two are a deliberate pair, not a duplication: `observeRun` is the coarse,
+// in-process run/step snapshot a workflow hands its host synchronously, and it
+// defers sub-step detail to the run's durable event stream. This is that stream,
+// read back — the per-tool-call activity, file trees, and step summaries a run
+// writes, fanned in from the parent workflow and every sandbox-step child.
+// Nothing in the signature belongs to the durability engine, so an embedder
+// consumes run events without depending on it.
+export { createRunEventStream } from "./execution/run-event-stream.js";
 // Sandbox-agent catalog. `buildAgent` maps a `SandboxAgentBuildContext` onto
 // `SandboxAgentDeps`, then selects the per-step agent by id from this record;
 // `SANDBOX_AGENT_META` is the planner-facing meta the same ids key.
@@ -157,7 +174,7 @@ export { validatePlan } from "./schemas/validate-plan.js";
 // caller-derived id and inserts-if-absent (the deterministic-id intake path);
 // the run-state calls mirror the chat trigger's reserve → dedup → status flow.
 export { upsertPlan, loadPlan } from "./state/plans.js";
-export { insertRun, queryActiveRun, updateRunStatus, queryRun, queryRunsByAnalysis, RunDedupCollisionError } from "./state/runs.js";
+export { insertRun, reserveRunById, queryActiveRun, queryActiveRunsByAnalysis, updateRunStatus, queryRun, queryRunsByAnalysis, RunDedupCollisionError, RunIdentityCollisionError, } from "./state/runs.js";
 export { queryStepsByRun } from "./state/step-executions.js";
 // Host-neutral reference-data catalog and shared installation receipts. Each
 // artifact names the third-party upstream it is fetched from; embedders own all

package/dist/input-sanitization.d.ts

@@ -1,9 +1,10 @@
 /**
- * Input sanitization — two pure, always-on functions applied once to the
- * incoming user message by the chat route (change 6). Never applied to
- * assistant messages or tool results.
+ * Input sanitization — pure, always-on text functions, not a plug-in pipeline.
+ * What runs is exactly what is declared here.
  *
- * Two pure functions, not a plug-in pipeline. What runs is exactly these two.
+ * `normalizeUnicode` and `redactSecrets` are applied once to the incoming user
+ * message by the chat route (change 6), and never to assistant messages or tool
+ * results. `stripNulCharacters` is the exception — it applies to tool results.
  */
 /**
  * NFC-normalize and strip control characters.
@@ -13,6 +14,15 @@
  * that could smuggle formatting or terminal escapes.
  */
 export declare function normalizeUnicode(text: string): string;
+/**
+ * Strip every NUL from `text`. Applied where a tool result is built — so the
+ * loop's in-memory message and the stored row agree byte-for-byte and the
+ * prompt-cache prefix survives the round trip — and again where the turn is
+ * written, which holds the invariant for writers that are not the loop. User
+ * input needs no separate treatment: `normalizeUnicode` already strips NUL along
+ * with the rest of the C0 range.
+ */
+export declare function stripNulCharacters(text: string): string;
 /**
  * Replace structured secret formats with `[REDACTED: <name>]`.
  *

package/dist/input-sanitization.js

@@ -1,9 +1,10 @@
 /**
- * Input sanitization — two pure, always-on functions applied once to the
- * incoming user message by the chat route (change 6). Never applied to
- * assistant messages or tool results.
+ * Input sanitization — pure, always-on text functions, not a plug-in pipeline.
+ * What runs is exactly what is declared here.
  *
- * Two pure functions, not a plug-in pipeline. What runs is exactly these two.
+ * `normalizeUnicode` and `redactSecrets` are applied once to the incoming user
+ * message by the chat route (change 6), and never to assistant messages or tool
+ * results. `stripNulCharacters` is the exception — it applies to tool results.
  */
 /**
  * C0/C1 control characters and DEL, excluding `\t` (U+0009) and `\n`
@@ -21,6 +22,28 @@ const CONTROL_CHARS = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
 export function normalizeUnicode(text) {
     return text.normalize("NFC").replace(CONTROL_CHARS, "");
 }
+/**
+ * NUL (U+0000) — the one character a stored message cannot carry. Postgres
+ * refuses it inside JSON: a `jsonb` column rejects the insert outright, and a
+ * `json` column accepts it but errors the moment a JSON operator reads that row
+ * ("U+0000 cannot be converted to text"), which is what `retractLastTurn`'s
+ * boundary predicate does. Either way one NUL byte poisons a thread, and it
+ * arrives through no fault of the model: tool results carry raw command output
+ * and file bytes, which is why they are otherwise left unsanitized.
+ */
+// eslint-disable-next-line no-control-regex -- matching NUL is the intent; see above.
+const NUL = /\u0000/g;
+/**
+ * Strip every NUL from `text`. Applied where a tool result is built — so the
+ * loop's in-memory message and the stored row agree byte-for-byte and the
+ * prompt-cache prefix survives the round trip — and again where the turn is
+ * written, which holds the invariant for writers that are not the loop. User
+ * input needs no separate treatment: `normalizeUnicode` already strips NUL along
+ * with the rest of the C0 range.
+ */
+export function stripNulCharacters(text) {
+    return text.replace(NUL, "");
+}
 /**
  * Each entry redacts one structured, prefixed secret format. Every pattern
  * has a prefix (`AKIA`, `sk-`, `gh*_`, `eyJ`, `Bearer`, a DB scheme) that

package/dist/lib/storage.js

@@ -7,7 +7,7 @@
  * the composition root and threaded as a constructor dep (see the harness-durable-runtime spec).
  */
 import pg from "pg";
-import { resolveAppPoolSize } from "../runtime/pools.js";
+import { APP_POOL_ACQUIRE_TIMEOUT_MS, resolveAppPoolSize } from "../runtime/pools.js";
 function poolOptions(config) {
     return {
         host: config.host,
@@ -18,6 +18,9 @@ function poolOptions(config) {
         // Per-pod app pool; DBOS owns its system-DB connections separately
         // (see the postgres-storage-backend spec). The boot guard checks this fits `max_connections`.
         max: resolveAppPoolSize(config.poolMax),
+        // Acquisition is bounded so a saturated pool fails a caller instead of
+        // hanging it — see `APP_POOL_ACQUIRE_TIMEOUT_MS` for the invariant.
+        connectionTimeoutMillis: APP_POOL_ACQUIRE_TIMEOUT_MS,
         // `pg` accepts `ssl: false` to disable entirely, or an object with
         // `rejectUnauthorized` to tune TLS. We map sslmode to those forms.
         ssl: config.sslMode === "disable"

package/dist/loop/budget-exceeded.d.ts

@@ -6,15 +6,31 @@
  * is wasteful because every subsequent call charged to the same budget will
  * also fail until the user tops up.
  *
- * Classification order (first hit wins):
+ * Classification order (first hit wins), and the order is load-bearing:
  *   1. Structured `statusCode === 402` (or `status === 402`) on any
  *      link of the cause chain. The gateway emits 402 exclusively for
  *      `budget_exceeded`, so a structured 402 is unambiguous.
- *   2. Pattern fallback: `/budget.?exceeded/i` on the stringified
+ *   2. A `ProviderError` on the value or its cause chain that was decided on
+ *      a status: its `type` answers, and the text patterns are skipped.
+ *   3. Pattern fallback: `/budget.?exceeded/i` on the stringified
  *      top-level error message. Covers stringified throws and paths
  *      where no `statusCode` is attached (ops scripts, sandbox-server
  *      surfacing upstream billing errors as text).
  *
+ * Step 2 exists because the text heuristic must never outrank a real
+ * classification. A `ProviderError` message carries an excerpt of the provider's
+ * response body, so a non-retryable 400 whose body merely mentions a budget would
+ * otherwise match step 3 — and the callers of this predicate act on it fatally
+ * (`sandbox-step` self-cancels the workflow, `execute-analysis` re-raises it as a
+ * budget throw). A phrase inside a quoted body is not evidence against the status
+ * the failure actually carried.
+ *
+ * "Decided on a status" is the load-bearing qualifier. `toProviderError` wraps
+ * every throwable, including ones `classifyProviderError` had no status for — it
+ * returns `provider` as a fall-through default there, which is an absence of
+ * classification, not a determination. Treating that as authoritative would
+ * silence step 3 in precisely the case it was written for.
+ *
  * Returns `false` for all other errors. Safe to call with any value;
  * non-Error inputs hit the stringified-pattern branch and return `false`
  * unless the string happens to match.

package/dist/loop/budget-exceeded.js

@@ -6,19 +6,36 @@
  * is wasteful because every subsequent call charged to the same budget will
  * also fail until the user tops up.
  *
- * Classification order (first hit wins):
+ * Classification order (first hit wins), and the order is load-bearing:
  *   1. Structured `statusCode === 402` (or `status === 402`) on any
  *      link of the cause chain. The gateway emits 402 exclusively for
  *      `budget_exceeded`, so a structured 402 is unambiguous.
- *   2. Pattern fallback: `/budget.?exceeded/i` on the stringified
+ *   2. A `ProviderError` on the value or its cause chain that was decided on
+ *      a status: its `type` answers, and the text patterns are skipped.
+ *   3. Pattern fallback: `/budget.?exceeded/i` on the stringified
  *      top-level error message. Covers stringified throws and paths
  *      where no `statusCode` is attached (ops scripts, sandbox-server
  *      surfacing upstream billing errors as text).
  *
+ * Step 2 exists because the text heuristic must never outrank a real
+ * classification. A `ProviderError` message carries an excerpt of the provider's
+ * response body, so a non-retryable 400 whose body merely mentions a budget would
+ * otherwise match step 3 — and the callers of this predicate act on it fatally
+ * (`sandbox-step` self-cancels the workflow, `execute-analysis` re-raises it as a
+ * budget throw). A phrase inside a quoted body is not evidence against the status
+ * the failure actually carried.
+ *
+ * "Decided on a status" is the load-bearing qualifier. `toProviderError` wraps
+ * every throwable, including ones `classifyProviderError` had no status for — it
+ * returns `provider` as a fall-through default there, which is an absence of
+ * classification, not a determination. Treating that as authoritative would
+ * silence step 3 in precisely the case it was written for.
+ *
  * Returns `false` for all other errors. Safe to call with any value;
  * non-Error inputs hit the stringified-pattern branch and return `false`
  * unless the string happens to match.
  */
+import { extractStatus, isProviderError } from "../providers/errors.js";
 const BUDGET_EXCEEDED_PATTERNS = [/budget.?exceeded/i];
 /** Max depth walked on the cause chain looking for a structured statusCode. */
 const MAX_CAUSE_HOPS = 5;
@@ -33,9 +50,39 @@ function hasStatus402(err) {
     }
     return false;
 }
+/**
+ * Find a `ProviderError` on the value or its cause chain. A `ResultError`
+ * thrown at a step boundary carries the structured value on `.cause`, which is
+ * the shape the callers of this predicate actually catch.
+ */
+function findProviderError(err) {
+    let cursor = err;
+    for (let i = 0; i < MAX_CAUSE_HOPS && cursor; i++) {
+        if (isProviderError(cursor))
+            return cursor;
+        cursor = cursor.cause;
+    }
+    return undefined;
+}
 export function isBudgetExceeded(err) {
     if (hasStatus402(err))
         return true;
+    const classified = findProviderError(err);
+    if (classified) {
+        if (classified.type === "budget")
+            return true;
+        // `auth` and `tenant-blocked` exist only because a status produced them, and
+        // a `provider` arm that carried a status was decided on it. None can be
+        // overturned by a phrase inside a response body the message merely quotes.
+        //
+        // A `provider` arm with NO status is the one exception: there
+        // `classifyProviderError` had nothing to key on and applied a fall-through
+        // default, so it made no determination to respect. That is exactly the shape
+        // a gateway reporting `budget_exceeded` as plain text arrives in, and the
+        // patterns below are the reason it is still caught.
+        if (classified.type !== "provider" || extractStatus(classified) !== undefined)
+            return false;
+    }
     const msg = err instanceof Error ? err.message : String(err ?? "");
     return BUDGET_EXCEEDED_PATTERNS.some((p) => p.test(msg));
 }

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

@@ -1,6 +1,7 @@
 import { type FinishReason } from "ai";
 import type { AgentSession } from "../auth/types.js";
-import type { AgentChat, PromptCachePolicy } from "../providers/types.js";
+import type { Logger } from "../lib/logger.js";
+import type { AgentChat, ChatRequest, PromptCachePolicy } from "../providers/types.js";
 import { type AskApproval, type AskRequest } from "../tools/approval/contract.js";
 import type { AgentDefinition, EmitFn, LoopMessage, RunStep } from "./types.js";
 export interface AgentFinish {
@@ -34,6 +35,15 @@ export interface RunAgentOptions {
     readonly runStep: RunStep;
     readonly formatStepName?: StepNameFormatter;
     readonly isFatalLoopError?: (err: unknown) => boolean;
+    /** Tool-selection policy for in-loop model calls. The cap wrap-up remains
+     * tool-less regardless. */
+    readonly toolChoice?: ChatRequest["toolChoice"];
+    /**
+     * Optional outcome predicate for loop-driving agents whose result is
+     * recorded by a tool into closure state. Checked immediately after each
+     * dispatch round, once every sibling tool result has been appended.
+     */
+    readonly resolved?: () => boolean;
     /**
      * Prompt-cache policy for every LLM call this run makes. Defaults to
      * `DEFAULT_PROMPT_CACHE` (5m) — an agent loop always re-sends its prefix, so
@@ -46,6 +56,17 @@ export interface RunAgentOptions {
      * cache-write premium for a cache nothing ever reads back.
      */
     readonly promptCache?: PromptCachePolicy;
+    /**
+     * Diagnostic sink for the run's own lifecycle. Optional because `runAgent` is
+     * called from tools, workflow bodies, and test rigs alike — silence is the
+     * correct behaviour for a caller that wires nothing, and the noop fallback
+     * gives it without every call site threading `?.`.
+     *
+     * Distinct from `emit`, which feeds a user-facing surface: every host filters
+     * sub-agent events off that surface by `callPath` depth, so a sub-agent's
+     * progress is emitted and then dropped. This is where it survives.
+     */
+    readonly logger?: Logger;
 }
 export declare function runAgent(agent: AgentDefinition, initial: readonly LoopMessage[], session: AgentSession, opts: RunAgentOptions): Promise<RunAgentResult>;
 export declare function finalText(messages: readonly LoopMessage[]): string;

package/dist/loop/run-agent.js

@@ -1,4 +1,6 @@
 import { jsonSchema, tool as aiTool } from "ai";
+import { stripNulCharacters } from "../input-sanitization.js";
+import { createNoopLogger } from "../lib/console-logger.js";
 import { hintForZodIssue, repairToolInput } from "../lib/zod-issues.js";
 import { markInterruptedMessage, syntheticUserMessage } from "../memory/ai-sdk-message-storage.js";
 import { classifyProviderError } from "../providers/errors.js";
@@ -16,7 +18,11 @@ export const DEFAULT_STEP_NAME_FORMATTER = {
 export async function runAgent(agent, initial, session, opts) {
     const { provider, signal, emit, runStep } = opts;
     const formatStepName = opts.formatStepName ?? DEFAULT_STEP_NAME_FORMATTER;
-    const isFatalLoopError = opts.isFatalLoopError ?? (() => false);
+    const configuredFatalLoopError = opts.isFatalLoopError ?? (() => false);
+    // AbortError is control flow, not a tool failure. Always compose it with the
+    // host's fatal predicate so request cancellation cannot be converted into a
+    // model-visible error result and retried by the loop.
+    const isFatalLoopError = (err) => ((err instanceof Error || err instanceof DOMException) && err.name === "AbortError") || configuredFatalLoopError(err);
     if (agent.tools.length > 0 && !provider.capabilities.toolCalling) {
         throw new Error(`Provider/model cannot run tool-required agent "${agent.id}"`);
     }
@@ -25,6 +31,11 @@ export async function runAgent(agent, initial, session, opts) {
         agentId: session.provenance.agentId ?? agent.id,
         callPath: session.provenance.callPath,
     };
+    // Bound from the same `source` the emitted events carry: one derivation feeding
+    // both sinks, so a record and an event cannot disagree about who produced them.
+    // `callPath` rides as an array rather than a joined string — the queryable form;
+    // rendering `parent > child` is the sink's choice, not a published package's.
+    const log = (opts.logger ?? createNoopLogger()).named("loop").with({ agentId: source.agentId, callPath: source.callPath });
     const toolsById = new Map(agent.tools.map((t) => [t.id, t]));
     const toolDefs = Object.fromEntries(agent.tools.map((t) => [
         t.id,
@@ -40,6 +51,7 @@ export async function runAgent(agent, initial, session, opts) {
     const unavailableAsk = new UnavailableAsk();
     const ask = opts.ask ?? ((request) => unavailableAsk.ask(request));
     const toolCtx = (tu) => ({
+        invocationId: tu.toolCallId,
         session,
         signal,
         emit,
@@ -53,6 +65,12 @@ export async function runAgent(agent, initial, session, opts) {
     // byte-identical to be read back.
     const providerOptions = promptCacheProviderOptions(opts.promptCache ?? DEFAULT_PROMPT_CACHE);
     const usage = {};
+    // Exactly one record per completed run — never one per iteration. That bound is
+    // what keeps the default level affordable for an agent that runs long; the
+    // per-iteration detail lives at `debug`, where paying per iteration is the point.
+    const logFinish = (level, reason, cappedOut) => {
+        log[level]("run finished", { iterations, reason, cappedOut, truncationRecoveries, usage });
+    };
     // The user said no. A subsequent model call would only let the agent argue
     // with the decision, or spend a call acknowledging it; the denial tool result
     // is itself what the surface renders, so the turn ends the moment a denial
@@ -61,14 +79,21 @@ export async function runAgent(agent, initial, session, opts) {
     const stopOnDenial = async (i) => {
         await emit({ type: "iteration", source, index: i, final: true });
         recordAgentRun({ agentId: agent.id, iterations, cappedOut: false, usage });
+        logFinish("warn", "denied", false);
         return { messages, finish: { reason: "denied", cappedOut: false, truncationRecoveries } };
     };
+    const stopOnResolved = async (i) => {
+        await emit({ type: "iteration", source, index: i, final: true });
+        recordAgentRun({ agentId: agent.id, iterations, cappedOut: false, usage });
+        return { messages, finish: { reason: "stop", cappedOut: false, truncationRecoveries } };
+    };
     for (let i = 0; i < agent.maxIterations; i++) {
         iterations = i + 1;
         const request = {
             system: agent.systemPrompt,
             messages,
             tools: toolDefs,
+            ...(opts.toolChoice !== undefined ? { toolChoice: opts.toolChoice } : {}),
             providerOptions,
         };
         const reply = await resultStep(runStep)(formatStepName.llm(i), () => provider.chat(request, session, signal));
@@ -92,6 +117,9 @@ export async function runAgent(agent, initial, session, opts) {
         if (reply.finishReason === "length") {
             truncationRecoveries++;
             await emit({ type: "iteration", source, index: i, final: false });
+            // `tools` is what the model asked for; the trailing call was cut off at the
+            // output limit and is never dispatched, which the distinct message records.
+            log.debug("iteration truncated at output limit", { iteration: i, tools: toolCalls.map((t) => t.toolName), truncationRecoveries });
             if (toolCalls.length === 0) {
                 // Stamped synthetic, not left as a bare `user` message: the wire format needs a user turn
                 // after a truncated assistant message, but this one is the loop's own nudge, and thread
@@ -120,14 +148,18 @@ export async function runAgent(agent, initial, session, opts) {
             messages.push({ role: "tool", content: results });
             if (hasDenial(results))
                 return stopOnDenial(i);
+            if (opts.resolved?.())
+                return stopOnResolved(i);
             continue;
         }
         if (reply.finishReason !== "tool-calls") {
             await emit({ type: "iteration", source, index: i, final: true });
             recordAgentRun({ agentId: agent.id, iterations, cappedOut: false, usage });
+            logFinish("info", reply.finishReason, false);
             return { messages, finish: { reason: reply.finishReason, cappedOut: false, truncationRecoveries } };
         }
         await emit({ type: "iteration", source, index: i, final: false });
+        log.debug("iteration", { iteration: i, tools: toolCalls.map((t) => t.toolName) });
         for (const tu of toolCalls) {
             await emit({ type: "tool-started", source, toolUseId: tu.toolCallId, name: tu.toolName, input: tu.input });
         }
@@ -145,6 +177,8 @@ export async function runAgent(agent, initial, session, opts) {
         messages.push({ role: "tool", content: results });
         if (hasDenial(results))
             return stopOnDenial(i);
+        if (opts.resolved?.())
+            return stopOnResolved(i);
     }
     // Cache defeater (known; not fixed here). Emptying the tool set changes the
     // very front of the request prefix — tool definitions are cached ahead of
@@ -166,11 +200,13 @@ export async function runAgent(agent, initial, session, opts) {
         markLastLoopAssistant(messages, initial.length);
         await emit({ type: "iteration", source, index: agent.maxIterations, final: true });
         recordAgentRun({ agentId: agent.id, iterations, cappedOut: true, usage });
+        logFinish("warn", "aborted", true);
         return { messages, finish: { reason: "aborted", cappedOut: true, truncationRecoveries } };
     }
     messages.push(wrapUp.message);
     await emit({ type: "iteration", source, index: agent.maxIterations, final: true });
     recordAgentRun({ agentId: agent.id, iterations, cappedOut: true, usage });
+    logFinish("warn", "max_iterations", true);
     return { messages, finish: { reason: "max_iterations", cappedOut: true, truncationRecoveries } };
 }
 function toolCallParts(message) {
@@ -256,8 +292,14 @@ async function execute(tu, tool, input, ctx, isFatalLoopError) {
         return errorResult(tu, toolErrorContent(err));
     }
 }
+/**
+ * Normalize a tool's return value to plain JSON, stripping NUL from every string
+ * it holds ({@link stripNulCharacters}). The reviver sees values, not keys — a
+ * NUL in an object KEY would still reach the row, but keys come from tool result
+ * types rather than scanned bytes, so nothing produces one.
+ */
 function jsonValue(value) {
-    return JSON.parse(JSON.stringify(value ?? null));
+    return JSON.parse(JSON.stringify(value ?? null), (_key, v) => (typeof v === "string" ? stripNulCharacters(v) : v));
 }
 function successResult(toolCall, value) {
     return {
@@ -267,12 +309,15 @@ function successResult(toolCall, value) {
         output: { type: "json", value: jsonValue(value) },
     };
 }
+// NUL is stripped from the prose BEFORE it is serialized: past the stringify it
+// is the six-character escape \u0000 — legitimate JSON text, and no longer
+// distinguishable from an error that happens to quote that escape.
 function toolErrorContent(value) {
     if (isToolError(value)) {
-        return JSON.stringify({ error: value.error, retryable: value.retryable });
+        return JSON.stringify({ error: stripNulCharacters(value.error), retryable: value.retryable });
     }
     const { retryable } = classifyProviderError(value);
-    const error = value instanceof Error ? value.message : String(value);
+    const error = stripNulCharacters(value instanceof Error ? value.message : String(value));
     return JSON.stringify({ error, retryable });
 }
 function errorResult(toolCall, content) {
@@ -280,7 +325,8 @@ function errorResult(toolCall, content) {
         type: "tool-result",
         toolCallId: toolCall.toolCallId,
         toolName: toolCall.toolName,
-        output: { type: "error-text", value: content },
+        // A thrown tool error routinely quotes stderr verbatim — as exposed to NUL as a success payload.
+        output: { type: "error-text", value: stripNulCharacters(content) },
     };
 }
 function isAskRejected(err) {

package/dist/loop/run-to-terminal.d.ts

@@ -28,8 +28,6 @@ import type { AgentDefinition, LoopMessage } from "./types.js";
 export declare const DEFAULT_SALVAGE_ITERATIONS = 3;
 /** Describes how to salvage a run that never reached its terminal tool. */
 export interface TerminalSalvage {
-    /** True once the agent recorded its terminal outcome (reads the closure cell). */
-    readonly resolved: () => boolean;
     /** Terminal tools offered on the salvage turn (submit / blocker / …). Must be
      *  the same instances the first run used — they close over the outcome cell. */
     readonly tools: readonly Tool[];

package/dist/loop/run-to-terminal.js

@@ -20,6 +20,7 @@
  * not collide the continuation's `llm-*` / `tool-*` cache keys with the first
  * run's — replaying them would silently return the first run's cached results.
  */
+import { createNoopLogger } from "../lib/console-logger.js";
 import { DEFAULT_STEP_NAME_FORMATTER, runAgent } from "./run-agent.js";
 /** Default salvage budget: one submit plus a validation-fix retry or two. */
 export const DEFAULT_SALVAGE_ITERATIONS = 3;
@@ -36,8 +37,14 @@ function salvageStepNames(base) {
  */
 export async function runToTerminal(agent, initial, session, opts, salvage) {
     const first = await runAgent(agent, initial, session, opts);
-    if (salvage.resolved() || opts.signal.aborted)
+    if (opts.resolved?.() || opts.signal.aborted)
         return first;
+    // Reported here rather than in `runAgent` because the loop cannot know it is being
+    // salvaged: it sees an ordinary run with a small budget and a restricted tool set.
+    // Only this wrapper holds the fact that a first attempt ended without its outcome.
+    (opts.logger ?? createNoopLogger())
+        .named("loop")
+        .warn("salvaging a run that never reached its terminal tool", { agentId: agent.id, callPath: session.provenance.callPath });
     const salvageAgent = {
         ...agent,
         tools: [...salvage.tools],

package/dist/memory/ai-sdk-message-storage.d.ts

@@ -20,8 +20,19 @@ export declare function parseStoredMessageEnvelope(value: unknown, identity: str
  * harness fact from the loop, through `appendTurn`, into a row.
  */
 export declare const HARNESS_PROVIDER_NAMESPACE = "cortex";
-/** The {@link HARNESS_PROVIDER_NAMESPACE} key marking a message the loop synthesized rather than one a human sent. */
+/** The {@link HARNESS_PROVIDER_NAMESPACE} key marking a message the loop or host synthesized rather than one a human sent. */
 export declare const SYNTHETIC_MESSAGE_KEY = "synthetic";
+/**
+ * The {@link HARNESS_PROVIDER_NAMESPACE} key marking a synthetic message that is a RECORD OF FACT
+ * the reader is meant to see, as opposed to loop machinery they are not.
+ *
+ * Always accompanies {@link SYNTHETIC_MESSAGE_KEY} — a record is synthetic in the sense that matters
+ * to every turn-boundary reader, and must never open a turn. This key answers the one question
+ * `synthetic` alone cannot: whether the message should be RENDERED. The loop's truncation nudge must
+ * not be (it would show words nobody typed); an embedder's out-of-band record must be (it is the
+ * only trace in the conversation that the work happened at all).
+ */
+export declare const SYNTHETIC_RECORD_KEY = "syntheticRecord";
 /** The {@link HARNESS_PROVIDER_NAMESPACE} key marking an assistant message whose production a client abort cut off. */
 export declare const INTERRUPTED_MESSAGE_KEY = "interrupted";
 /**
@@ -39,18 +50,40 @@ export declare function markInterruptedMessage(message: ModelMessage): ModelMess
 /** Whether a client abort cut off this message's production (see {@link markInterruptedMessage}); an absent key reads as not interrupted. */
 export declare function isInterruptedMessage(message: ModelMessage): boolean;
 /**
- * Build a `user` message the agent loop synthesized — today, the nudge that continues a reply the model
- * truncated at its output-token limit.
+ * Build a `user` message the LOOP synthesized rather than a human typing it — today, the nudge that
+ * continues a reply the model truncated at its output-token limit.
  *
  * It has to carry the `user` role because the wire format requires a user turn after a truncated
  * assistant message, but it is not user input, and the difference is load-bearing: a `user` message is
  * what OPENS a conversation turn, so an unmarked synthetic one reads as a spurious turn boundary —
  * splitting one turn into two for the token window and, worse, giving a tail-turn removal a cut point in
  * the middle of a turn. Marking it is what lets {@link isSyntheticUserMessage} keep those readers honest.
+ *
+ * This one is loop MACHINERY and is not rendered: showing it would put words on screen nobody typed.
+ * An embedder recording out-of-band work — an analysis run's outcome — wants
+ * {@link syntheticRecordMessage} instead, which is equally non-turn-opening but IS displayed.
  */
 export declare function syntheticUserMessage(text: string): ModelMessage;
-/** Whether the loop synthesized this message (see {@link syntheticUserMessage}) rather than a human sending it. */
+/**
+ * Build a record of out-of-band work for an embedder to append between turns — an analysis run's
+ * outcome, which the model should read on its next turn but which nobody said.
+ *
+ * Synthetic in every sense that matters to a turn-boundary reader ({@link isSyntheticUserMessage} is
+ * true of it), so it cannot split a turn for the token window nor hand a tail retraction a mid-turn
+ * cut point. It differs from {@link syntheticUserMessage} in exactly one respect, and it is the
+ * decisive one: this is a fact the reader is entitled to see, so the display reconstruction emits it
+ * — as a `system` message, which is what it is — rather than dropping it as loop machinery.
+ *
+ * A host MUST build these here rather than assembling the `providerOptions` markers itself: the keys
+ * and namespace are shared with the turn-boundary and display predicates, and a hand-rolled copy
+ * would fork them silently — the message would store fine and then be read as a genuine turn start,
+ * or be dropped from the transcript with no indication why.
+ */
+export declare function syntheticRecordMessage(text: string): ModelMessage;
+/** Whether the loop or the host synthesized this message (see {@link syntheticUserMessage}) rather than a human sending it. */
 export declare function isSyntheticUserMessage(message: ModelMessage): boolean;
+/** Whether this is a host-appended record of out-of-band work (see {@link syntheticRecordMessage}) — synthetic, but displayed. */
+export declare function isSyntheticRecordMessage(message: ModelMessage): boolean;
 type LegacyContent = string | Array<Record<string, unknown>>;
 export interface LegacyMessageRow {
     readonly threadId: string;