@inflexa-ai/harness 0.13.0 → 0.14.1

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,
@@ -49,11 +60,23 @@ export async function runAgent(agent, initial, session, opts) {
     });
     let iterations = 0;
     let truncationRecoveries = 0;
+    // Counted rather than listed: the finish record stays one bounded line for a run of
+    // any length, and "50 iterations, 49 tool calls, 47 of them errored" already separates
+    // a productive long run from a loop stuck retrying one failing call. The per-iteration
+    // `debug` records name the tools when that distinction is not enough.
+    let toolCallCount = 0;
+    let toolErrorCount = 0;
     // Resolved once, not per iteration: an identical options object across every
     // call is itself part of the cache contract — the request prefix has to be
     // 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, toolCalls: toolCallCount, toolErrors: toolErrorCount, 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
@@ -62,14 +85,44 @@ 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 } };
     };
+    /**
+     * Fold one dispatch round into the run's counters and the event sink, returning the
+     * tools whose results the model will read as errors.
+     *
+     * Shared by both dispatch paths so a truncated round and a normal one cannot drift
+     * in what they count. An error tool result is otherwise invisible to every sink —
+     * it is not a thrown failure, so nothing reports it and the loop simply feeds it
+     * back — and a run that ends badly is usually a run whose tool calls were failing.
+     */
+    const settleRound = async (calls, results) => {
+        const errored = [];
+        for (let idx = 0; idx < calls.length; idx++) {
+            const tu = calls[idx];
+            const isError = isErrorOutput(results[idx]);
+            toolCallCount++;
+            if (isError) {
+                toolErrorCount++;
+                errored.push(tu.toolName);
+            }
+            await emit({ type: "tool-finished", source, toolUseId: tu.toolCallId, name: tu.toolName, isError });
+        }
+        return errored;
+    };
+    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));
@@ -93,6 +146,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
@@ -107,45 +163,43 @@ export async function runAgent(agent, initial, session, opts) {
                 await emit({ type: "tool-started", source, toolUseId: tu.toolCallId, name: tu.toolName, input: tu.input });
             }
             const results = await dispatchTools(earlier, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool);
-            for (let idx = 0; idx < earlier.length; idx++) {
-                const tu = earlier[idx];
-                await emit({
-                    type: "tool-finished",
-                    source,
-                    toolUseId: tu.toolCallId,
-                    name: tu.toolName,
-                    isError: isErrorOutput(results[idx]),
-                });
-            }
+            const errored = await settleRound(earlier, results);
             results.push(errorResult(trailing, TRUNCATED_TOOL_USE_ERROR));
+            // The trailing call was never dispatched, but it reaches the model as an error
+            // result like any other — so it counts, or `toolErrors` reports a cleaner run
+            // than the model actually read. It gets no `tool-finished` event: no
+            // `tool-started` was emitted for it either, and the pair must stay balanced.
+            toolCallCount++;
+            toolErrorCount++;
+            errored.push(trailing.toolName);
+            log.debug("tool results returned errors", { iteration: i, tools: errored });
             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 });
         }
         const results = await dispatchTools(toolCalls, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool);
-        for (let idx = 0; idx < toolCalls.length; idx++) {
-            const tu = toolCalls[idx];
-            await emit({
-                type: "tool-finished",
-                source,
-                toolUseId: tu.toolCallId,
-                name: tu.toolName,
-                isError: isErrorOutput(results[idx]),
-            });
-        }
+        const errored = await settleRound(toolCalls, results);
+        if (errored.length > 0)
+            log.debug("tool results returned errors", { iteration: i, tools: errored });
         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
@@ -167,11 +221,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) {
@@ -257,8 +313,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 {
@@ -268,12 +330,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) {
@@ -281,7 +346,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

@@ -22,14 +22,32 @@
  */
 import type { AgentSession } from "../auth/types.js";
 import type { Tool } from "../tools/define-tool.js";
-import { type RunAgentOptions, type RunAgentResult } from "./run-agent.js";
+import { type AgentFinish, type RunAgentOptions, type RunAgentResult } from "./run-agent.js";
 import type { AgentDefinition, LoopMessage } from "./types.js";
 /** Default salvage budget: one submit plus a validation-fix retry or two. */
 export declare const DEFAULT_SALVAGE_ITERATIONS = 3;
+/**
+ * What a salvage continuation was and how it went — present only when one ran.
+ *
+ * The two finishes answer different questions and a diagnostician needs both: a
+ * first run that ended `max_iterations` spent its whole budget failing to submit,
+ * while one that ended `stop` gave up on prose after a single turn. Those call for
+ * opposite responses, and the returned `RunAgentResult` carries only the second
+ * run's finish, which is the same for either.
+ */
+export interface SalvageRecord {
+    /** How the FIRST run ended — the reason a salvage was needed at all. */
+    readonly firstFinish: AgentFinish;
+    /** How the salvage continuation itself ended. */
+    readonly finish: AgentFinish;
+}
+/** A `runToTerminal` outcome: the driving run's result, plus the salvage account. */
+export interface RunToTerminalResult extends RunAgentResult {
+    /** Null when the first run reached its terminal tool and no salvage was needed. */
+    readonly salvage: SalvageRecord | null;
+}
 /** 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[];
@@ -43,4 +61,4 @@ export interface TerminalSalvage {
  * Returns the salvage run's result when a salvage occurred (its message array
  * already includes the first run's), otherwise the first run's result.
  */
-export declare function runToTerminal(agent: AgentDefinition, initial: readonly LoopMessage[], session: AgentSession, opts: RunAgentOptions, salvage: TerminalSalvage): Promise<RunAgentResult>;
+export declare function runToTerminal(agent: AgentDefinition, initial: readonly LoopMessage[], session: AgentSession, opts: RunAgentOptions, salvage: TerminalSalvage): Promise<RunToTerminalResult>;

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,16 +37,31 @@ 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)
-        return first;
+    if (opts.resolved?.() || opts.signal.aborted)
+        return { ...first, salvage: null };
+    const salvageBudget = salvage.maxIterations ?? DEFAULT_SALVAGE_ITERATIONS;
+    // 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.
+    // The first run's finish rides along because it is the whole diagnosis of WHY a
+    // salvage was needed, and it is the field the second run's result overwrites.
+    (opts.logger ?? createNoopLogger()).named("loop").warn("salvaging a run that never reached its terminal tool", {
+        agentId: agent.id,
+        callPath: session.provenance.callPath,
+        firstFinishReason: first.finish.reason,
+        firstCappedOut: first.finish.cappedOut,
+        salvageTools: salvage.tools.map((t) => t.id),
+        salvageMaxIterations: salvageBudget,
+    });
     const salvageAgent = {
         ...agent,
         tools: [...salvage.tools],
-        maxIterations: salvage.maxIterations ?? DEFAULT_SALVAGE_ITERATIONS,
+        maxIterations: salvageBudget,
     };
     const salvageOpts = {
         ...opts,
         formatStepName: salvageStepNames(opts.formatStepName ?? DEFAULT_STEP_NAME_FORMATTER),
     };
-    return runAgent(salvageAgent, [...first.messages, { role: "user", content: salvage.nudge }], session, salvageOpts);
+    const salvaged = await runAgent(salvageAgent, [...first.messages, { role: "user", content: salvage.nudge }], session, salvageOpts);
+    return { ...salvaged, salvage: { firstFinish: first.finish, finish: salvaged.finish } };
 }

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;

package/dist/memory/ai-sdk-message-storage.js

@@ -31,8 +31,19 @@ export function parseStoredMessageEnvelope(value, identity) {
  * harness fact from the loop, through `appendTurn`, into a row.
  */
 export 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 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 const SYNTHETIC_RECORD_KEY = "syntheticRecord";
 /** The {@link HARNESS_PROVIDER_NAMESPACE} key marking an assistant message whose production a client abort cut off. */
 export const INTERRUPTED_MESSAGE_KEY = "interrupted";
 /**
@@ -62,14 +73,18 @@ export function isInterruptedMessage(message) {
     return message.providerOptions?.[HARNESS_PROVIDER_NAMESPACE]?.[INTERRUPTED_MESSAGE_KEY] === true;
 }
 /**
- * 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 function syntheticUserMessage(text) {
     return {
@@ -78,10 +93,36 @@ export function syntheticUserMessage(text) {
         providerOptions: { [HARNESS_PROVIDER_NAMESPACE]: { [SYNTHETIC_MESSAGE_KEY]: true } },
     };
 }
-/** 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 function syntheticRecordMessage(text) {
+    return {
+        role: "user",
+        content: text,
+        providerOptions: { [HARNESS_PROVIDER_NAMESPACE]: { [SYNTHETIC_MESSAGE_KEY]: true, [SYNTHETIC_RECORD_KEY]: true } },
+    };
+}
+/** Whether the loop or the host synthesized this message (see {@link syntheticUserMessage}) rather than a human sending it. */
 export function isSyntheticUserMessage(message) {
     return message.providerOptions?.[HARNESS_PROVIDER_NAMESPACE]?.[SYNTHETIC_MESSAGE_KEY] === true;
 }
+/** Whether this is a host-appended record of out-of-band work (see {@link syntheticRecordMessage}) — synthetic, but displayed. */
+export function isSyntheticRecordMessage(message) {
+    return message.providerOptions?.[HARNESS_PROVIDER_NAMESPACE]?.[SYNTHETIC_RECORD_KEY] === true;
+}
 function providerOptionsFromLegacy(block) {
     // A block may carry both a signed thinking signature and cache_control;
     // both are required for valid continuation, so both must survive.

package/dist/memory/content-to-cortex.js

@@ -20,7 +20,7 @@
  * only tool-result continuation parts) is omitted entirely, so the rendered
  * conversation has no empty bubbles. Storage is never mutated.
  */
-import { isInterruptedMessage, isSyntheticUserMessage } from "./ai-sdk-message-storage.js";
+import { isInterruptedMessage, isSyntheticRecordMessage, isSyntheticUserMessage } from "./ai-sdk-message-storage.js";
 function genericToolCall(block) {
     return {
         type: "tool-call",
@@ -84,7 +84,15 @@ export async function contentToCortexMessages(messages, resolveCard) {
         // interruption marker — that rides assistant rows — so this cannot interact
         // with the marker-fold logic below. The assistant rows it separated then
         // become adjacent and coalesce into one bubble, which is the shape we want.
-        if (isSyntheticUserMessage(message.message))
+        //
+        // A host-appended RECORD is the exception, and the distinction is exactly why the
+        // two markers exist separately: it is equally synthetic for every turn-boundary
+        // reader, but it is a fact the reader is entitled to see — the only trace in the
+        // conversation that out-of-band work happened at all. Dropping it here would make
+        // an embedder's durable record write successfully and then be invisible, with
+        // nothing to indicate why.
+        const isRecord = isSyntheticRecordMessage(message.message);
+        if (isSyntheticUserMessage(message.message) && !isRecord)
             continue;
         const parts = await rowToParts(message.message, resolveCard);
         // The marker is read before the zero-parts drop so the flag can never be lost to it:
@@ -100,7 +108,15 @@ export async function contentToCortexMessages(messages, resolveCard) {
             }
             continue;
         }
-        const role = message.message.role === "tool" ? "assistant" : message.message.role;
+        // A record carries the `user` role for the wire format and for the turn-boundary
+        // predicates, but nobody said it. Emitting it AS `user` would attribute
+        // system-authored text to the reader — a lie about who spoke, and one that would
+        // also mislead them about what they can retract. `system` is what it actually is.
+        const role = isRecord
+            ? "system"
+            : message.message.role === "tool"
+                ? "assistant"
+                : message.message.role;
         const prev = out[out.length - 1];
         if (prev && prev.role === role && role === "assistant") {
             prev.parts.push(...parts);

package/dist/memory/message-backfill.js

@@ -15,7 +15,7 @@ export async function backfillAiSdkMessageEnvelopes(client) {
                 role: row.role,
                 content: row.content_jsonb,
             });
-            await client.query("UPDATE messages SET message_envelope = $1::jsonb WHERE thread_id = $2 AND seq = $3::bigint", [
+            await client.query("UPDATE messages SET message_envelope = $1::json WHERE thread_id = $2 AND seq = $3::bigint", [
                 JSON.stringify(envelopeMessage(message)),
                 row.thread_id,
                 row.seq,

package/dist/memory/thread-history.js

@@ -22,6 +22,7 @@
  */
 import { metrics } from "@opentelemetry/api";
 import { ResultAsync, ok, okAsync } from "neverthrow";
+import { stripNulCharacters } from "../input-sanitization.js";
 import { tryMutation, tryQuery, withTransaction } from "../lib/db-result.js";
 import { countTokens } from "./count-tokens.js";
 import { HARNESS_PROVIDER_NAMESPACE, SYNTHETIC_MESSAGE_KEY, envelopeMessage, isSyntheticUserMessage, parseStoredMessageEnvelope, } from "./ai-sdk-message-storage.js";
@@ -36,11 +37,18 @@ function okVoid() {
  *
  * - a tool result, which in AI SDK terms is a `tool`-role message, so a mid-turn
  *   tool continuation never matches in the first place;
- * - a message the LOOP synthesized mid-turn — the truncated-reply nudge
- *   (`syntheticUserMessage`) — which must carry the `user` role for the wire
- *   format but is not user input. Reading it as a boundary would split one turn
- *   into two: the token window would evict half a turn, and `retractLastTurn`
- *   would cut its tail in the middle of a turn rather than at its head.
+ * - a message the LOOP or the HOST synthesized (`syntheticUserMessage`) — the
+ *   truncated-reply nudge the loop inserts mid-turn, and the record an embedder
+ *   appends between turns for work that happened outside the conversation, such as
+ *   an analysis run's outcome. Both carry the `user` role for the wire format and
+ *   neither is user input. Reading one as a boundary would split one turn into
+ *   two: the token window would evict half a turn, and `retractLastTurn` would cut
+ *   its tail in the middle of a turn rather than at its head.
+ *
+ *   A host-appended record therefore belongs to the turn preceding it, so a tail
+ *   retraction that removes that turn removes the record with it. That is the
+ *   accepted consequence of the exclusion, not a defect — the alternative, letting
+ *   it open a turn, is the exact failure the marker exists to prevent.
  *
  * {@link GENUINE_USER_START_SQL} is the twin of this predicate over stored
  * envelopes; the two are built from the same constants so they cannot drift.
@@ -61,6 +69,22 @@ function isGenuineUserStart(message) {
  */
 const GENUINE_USER_START_SQL = `message_envelope->'message'->>'role' = 'user'
                          AND message_envelope->'message'->'providerOptions'->'${HARNESS_PROVIDER_NAMESPACE}'->>'${SYNTHETIC_MESSAGE_KEY}' IS DISTINCT FROM 'true'`;
+/**
+ * Serialize a message's storage envelope, dropping NUL from every string it
+ * carries ({@link stripNulCharacters}).
+ *
+ * A stored NUL does not break the insert on a `json` column, nor the whole-row
+ * reads — it breaks {@link GENUINE_USER_START_SQL}, whose JSON operators refuse
+ * to walk a document containing one, so a single poisoned row would make the
+ * thread's tail unretractable. The loop already strips NUL where it builds a
+ * tool result, so this scrubs nothing on the harness's own path; it holds the
+ * invariant for every other writer.
+ *
+ * The replacer sees values, not keys — the same accepted limit as the loop's.
+ */
+function serializeEnvelope(message) {
+    return JSON.stringify(envelopeMessage(message), (_key, value) => (typeof value === "string" ? stripNulCharacters(value) : value));
+}
 /**
  * Group rows (oldest-first) into turns at genuine-user-start boundaries.
  * Generic over the row shape so the token-windowed read (`loadRecent`) and
@@ -148,11 +172,13 @@ export function createThreadHistory(pool) {
         // prior so the first `err` short-circuits — and `withTransaction`
         // re-throws it to force ROLLBACK (a returned `err` that does not
         // reach `withTransaction` would COMMIT silently).
-        messages.reduce((chain, message, i) => chain.andThen(() => tryMutation("thread-history.appendTurn.insert", () => client.query(`INSERT INTO messages (thread_id, seq, message_envelope, tokens)
-                     VALUES ($1, $2, $3::jsonb, $4)
+        messages.reduce((chain, message, i) => chain.andThen(() => tryMutation("thread-history.appendTurn.insert", () => client.query(
+        // `::json`, never `::jsonb` — see the column comment in the state-init DDL.
+        `INSERT INTO messages (thread_id, seq, message_envelope, tokens)
+                     VALUES ($1, $2, $3::json, $4)
                      ON CONFLICT (thread_id, seq) DO UPDATE
                        SET message_envelope = EXCLUDED.message_envelope,
-                           tokens = EXCLUDED.tokens`, [threadId, startSeq + i, JSON.stringify(envelopeMessage(message)), countTokens(message.content)])).map(() => undefined)), okVoid()))
+                           tokens = EXCLUDED.tokens`, [threadId, startSeq + i, serializeEnvelope(message), countTokens(message.content)])).map(() => undefined)), okVoid()))
             .andThen(() => 
         // Thread listings sort on `cortex_analysis_threads.updated_at`, and
         // the only other writer of it is the title update — so without this