@inflexa-ai/harness 0.39.2 → 0.40.0

package/README.md

@@ -31,8 +31,7 @@ Import the curated, embedder-facing surface from the package root. Every deep su
 import {
     assembleCoreRuntime,            // host-neutral composition point
     createConversationAgent,
-    createAnthropicProvider,        // ChatProvider — Anthropic
-    createConfiguredAiSdkProvider,  // ChatProvider — any OpenAI-compatible endpoint
+    createConfiguredAiSdkProvider,  // ChatProvider — Anthropic, OpenAI, or an OpenAI-compatible endpoint
     createEmbeddingProvider,
     createLocalRunAuthorizer,       // RunAuthorizer    seam (local default)
     createNoopRunCharge,            // RunCharge        seam
@@ -97,7 +96,7 @@ function pinoAsHarnessLogger(p: pino.Logger, names: readonly string[] = []): Log
 
 ## How it executes
 
-Chat is a plain in-process turn (`prepareChatTurn` → `runAgent` → `appendTurn`); the harness ships no HTTP layer, so the host owns the route. Compute-heavy work runs as **durable workflows** — `executeAnalysis` starts a child workflow per plan step once its dependencies have completed, and each step drives a sandbox agent inside a container. The same `runAgent` primitive runs in both modes; durability and the event sink are injected, so the loop body is identical.
+Chat is a plain in-process turn. A turn is `runChatTurn`, and the harness stores the opening, each round, and the outcome of the turn. The harness ships no HTTP layer, thus the host owns the route. Compute-heavy work runs as **durable workflows** — `executeAnalysis` starts a child workflow per plan step once its dependencies have completed, and each step drives a sandbox agent inside a container. The same `runAgent` primitive runs in both modes; durability and the event sink are injected, so the loop body is identical.
 
 The sandbox protocol is submit-then-retrieve, which is what lets a long run survive a host restart: the host `POST /exec`s a command and retrieves the result over one of two transports — **poll** (the default: the host asks, the sandbox initiates nothing and needs no network egress) or **callback** (opt-in: the sandbox POSTs signed callbacks to an ingress the embedder runs). Both exec endpoints are HMAC signature-authenticated. See the [`harness-sandbox-exec`](./openspec/specs/harness-sandbox-exec/) spec.
 

package/dist/agents/conversation-agent.d.ts

@@ -29,6 +29,7 @@ import type { EnsureSessionStateResult } from "../app/report-session-runtime.js"
 import type { ResourcePolicy } from "../config/resource-limits.js";
 import type { ChromeConfig } from "../lib/chrome.js";
 import type { AcquireEyes } from "../lib/eyes.js";
+import type { ToolOutputStore } from "../loop/tool-output.js";
 import type { AgentDefinition } from "../loop/types.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
 import type { Tool } from "../tools/define-tool.js";
@@ -60,6 +61,8 @@ export interface ConversationAgentDeps extends EnvironmentStorePaths {
      * Omitted falls back to the no-op recorder.
      */
     readonly usageRecorder?: UsageRecorder;
+    /** Adds `read_tool_output`, and each loop-driving tool gives the same store to its sub-agent. */
+    readonly toolOutputStore?: ToolOutputStore;
     /** Shared host-side bibliographic verification service. */
     readonly citationResolver: CitationResolver;
     /** The LLM seam every loop-driving tool runs its sub-agent on. */

package/dist/agents/conversation-agent.js

@@ -23,6 +23,7 @@
  * confined to the analysis root, with one provenance session event per
  * successful write.
  */
+import { createReadToolOutputTool } from "../tools/read-tool-output.js";
 import { createWorkingMemory } from "../memory/working-memory.js";
 import { conversationPrompt } from "../prompts/conversation.js";
 import { composeSystemPrompt } from "./system-prompt.js";
@@ -45,7 +46,7 @@ export const CONVERSATION_AGENT_ID = "conversation-agent";
 const CONVERSATION_MAX_ITERATIONS = 200;
 /** Build the conversation `AgentDefinition` with every tool fully dep-bound. */
 export function createConversationAgent(deps) {
-    const { provider, pool, embedding, workspaceFs, model, utilityProvider, utilityModel, executeAnalysisWorkflow, runAuthorizer, runLauncher, bioKeys, chrome, resourcePolicy, hostTools, refStorePath, farmLockFile, imagePackagesFile, readPoolInventory, usageRecorder, citationResolver, } = deps;
+    const { provider, pool, embedding, workspaceFs, model, utilityProvider, utilityModel, executeAnalysisWorkflow, runAuthorizer, runLauncher, bioKeys, chrome, resourcePolicy, hostTools, refStorePath, farmLockFile, imagePackagesFile, readPoolInventory, usageRecorder, toolOutputStore, citationResolver, } = deps;
     const workingMemory = createWorkingMemory(pool);
     const ncbi = createNcbiTools(bioKeys);
     const chemDb = createChemDbTools(bioKeys, { ...(deps.logger ? { logger: deps.logger } : {}) });
@@ -121,6 +122,7 @@ export function createConversationAgent(deps) {
             pool,
             resourcePolicy,
             usageRecorder,
+            ...(toolOutputStore ? { toolOutputStore } : {}),
             bioKeys,
             ...(refStorePath ? { refStorePath } : {}),
             ...(farmLockFile ? { farmLockFile } : {}),
@@ -141,6 +143,7 @@ export function createConversationAgent(deps) {
             ...(readPoolInventory ? { readPoolInventory } : {}),
             ...(deps.extendAnalysisFarm ? { extendAnalysisFarm: deps.extendAnalysisFarm } : {}),
             ...(deps.logger ? { logger: deps.logger } : {}),
+            ...(usageRecorder ? { usageRecorder } : {}),
         }),
         // The one report path. The tool starts a report thread as a child of the
         // conversation, and the user composes the report there with the Report
@@ -158,13 +161,21 @@ export function createConversationAgent(deps) {
         createShowPlanTool(pool),
         showFileTool,
         // Cross-domain analogy generation (sub-agent as a loop-driving tool).
-        createGenerateAnalogyReportTool({ provider, model, bioKeys, usageRecorder }),
+        createGenerateAnalogyReportTool({
+            provider,
+            model,
+            bioKeys,
+            usageRecorder,
+            ...(toolOutputStore ? { toolOutputStore } : {}),
+            ...(deps.logger ? { logger: deps.logger } : {}),
+        }),
         // Workspace semantic search + raw read/grep over the read seam.
         createWorkspaceSearchTool(pool, embedding),
         createReadFileTool(workspaceFs),
         createListFilesTool(workspaceFs),
         createFileStatTool(workspaceFs),
         createGrepTool(workspaceFs),
+        ...(toolOutputStore ? [createReadToolOutputTool(toolOutputStore)] : []),
         // Workspace write pair over the session-scoped mutate seam. The working
         // directory of this agent is the analysis root, so a write lands
         // anywhere inside its own analysis tree; `..`, a foreign analysis, and

package/dist/agents/report-session-agent.d.ts

@@ -25,6 +25,7 @@
 import type { Pool } from "pg";
 import type { AuthContext } from "../auth/types.js";
 import type { RunAuthorizer } from "../execution/run-authorizer.js";
+import type { ToolOutputStore } from "../loop/tool-output.js";
 import type { AgentDefinition } from "../loop/types.js";
 import type { DeriveTableRunner } from "../tools/report-session/derive-table.js";
 import type { ReportSessionStateStore } from "../state/report-session-state.js";
@@ -125,6 +126,8 @@ export interface ReportSessionAgentDeps {
     readonly provenance?: ProvenanceSeam;
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
+    /** Adds `read_tool_output`. The loop of a report turn must keep its texts in the same store. */
+    readonly toolOutputStore?: ToolOutputStore;
 }
 /** Build the report `AgentDefinition` with every tool bound to its deps. */
 export declare function createReportSessionAgent(deps: ReportSessionAgentDeps): AgentDefinition;

package/dist/agents/report-session-agent.js

@@ -22,6 +22,7 @@
  * same composition as the conversation agent. Thus the prompt prefix stays constant
  * across threads, and the provider cache reuses it.
  */
+import { createReadToolOutputTool } from "../tools/read-tool-output.js";
 import { createReportAuthoringTools } from "../tools/report-authoring/authoring-tools.js";
 import { createDeriveTableTool, createExaminePageTool, createListPinnedArtifactsTool, createPreviewReportTool, createRecordVersionTool, } from "../tools/report-session/index.js";
 import { createFileStatTool, createGrepTool, createListFilesTool, createReadFileTool, createWorkspaceSearchTool } from "../tools/workspace/index.js";
@@ -50,6 +51,7 @@ export function createReportSessionAgent(deps) {
         createListFilesTool(workspaceFs),
         createFileStatTool(workspaceFs),
         createGrepTool(workspaceFs),
+        ...(deps.toolOutputStore ? [createReadToolOutputTool(deps.toolOutputStore)] : []),
         createWorkspaceSearchTool(pool, embedding),
         createInspectRunTool(pool),
         createInspectDataProfileTool(pool),

package/dist/agents/sandbox/cheminformatics-agent.js

@@ -20,8 +20,6 @@ export const meta = {
         "structure-activity relationship",
         "target engagement assessment",
         "occupancy estimation",
-        "drug perturbation signature matching",
-        "CMap-style connectivity scoring",
         "selectivity profiling",
         "kinase selectivity analysis",
     ],
@@ -34,7 +32,6 @@ export const meta = {
         "sar-data",
         "target-engagement-data",
         "selectivity-panel-data",
-        "perturbation-signatures",
     ],
     skills: ["cheminformatics", "shared/omics-general"],
     tools: [...BASE_SANDBOX_TOOLS, "pubmed", "searchGene", "lookupAnnotation", "searchInteractions", "chembl", "drugGeneInteractions", "pubchem"],

package/dist/agents/sandbox/shared.d.ts

@@ -17,6 +17,7 @@
  * so misconfigured agents fail at startup, not at the first LLM call.
  */
 import type { Pool } from "pg";
+import type { ToolOutputStore } from "../../loop/tool-output.js";
 import type { AgentDefinition } from "../../loop/types.js";
 import type { ChatProvider, EmbeddingProvider } from "../../providers/types.js";
 import type { SandboxClient } from "../../sandbox/client.js";
@@ -25,6 +26,7 @@ import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
 import type { ProvenanceCollector as LineageCollector } from "../../provenance/collector.js";
 import { type BioToolKeys } from "../../tools/bio/keys.js";
 import { type BlockerHolder } from "../../tools/sandbox/report-blocker.js";
+import { type FileMetadataCell } from "../../tools/sandbox/submit-file-metadata.js";
 import type { AgentMeta, SandboxToolName } from "./types.js";
 import type { EnvironmentStorePaths } from "../../config/environment-stores.js";
 import type { Logger } from "../../lib/logger.js";
@@ -81,10 +83,17 @@ export interface SandboxAgentDeps extends EnvironmentStorePaths {
     /**
      * Per-run blocker cell (see the harness-sandbox-agents spec). When present, the agent gets a
      * `report_blocker` tool that records `{ kind: "blocker", reason }` into it;
-     * the sandbox-step body reads `holder.outcome` after the loop. Omit for
-     * agents that have no terminal status to declare (such as the data profiler).
+     * the sandbox-step body reads the blocker from the transcript, falling back to
+     * the cell. Omit for agents that have no terminal status to declare (such as the data profiler).
      */
     readonly blockerHolder?: BlockerHolder;
+    /**
+     * When present, the agent declares `submit_file_metadata` from its first request so the
+     * tool list stays stable across continuations; the task masks it, the continuation unmasks it.
+     */
+    readonly fileMetadata?: FileMetadataCell;
+    /** Adds `read_tool_output`. The loop of the agent must keep its texts in the same store. */
+    readonly toolOutputStore?: ToolOutputStore;
     /**
      * The farm-extension seam of the embedder. When it is bound, every
      * sandbox agent gets the `link_packages` tool in its always-on substrate,

package/dist/agents/sandbox/shared.js

@@ -36,7 +36,9 @@ import { createScanInputsTool } from "../../tools/workspace/scan-inputs.js";
 import { createEditFileTool, createExecuteCommandTool, createWorkspaceMutator, createWriteFileTool } from "../../tools/workspace/index.js";
 // Skills (declared per agent via meta.skills).
 import { createSkillTools } from "../../tools/sandbox/skills.js";
+import { createReadToolOutputTool } from "../../tools/read-tool-output.js";
 import { createReportBlockerTool } from "../../tools/sandbox/report-blocker.js";
+import { createSubmitFileMetadataTool } from "../../tools/sandbox/submit-file-metadata.js";
 import { toSandboxPath } from "../../workspace/paths.js";
 import { setActiveExecId } from "../../state/index.js";
 import { SANDBOX_AGENT_DEFAULT_MAX_ITERATIONS } from "./types.js";
@@ -198,6 +200,7 @@ export function createSandboxAgent(deps, meta, body, opts = {}) {
     const skillTools = deps.skillsDir ? Object.values(createSkillTools({ skillsDir: deps.skillsDir, skills: meta.skills })) : [];
     const tools = [
         ...buildWorkspaceTools(deps, opts.readOnly ?? false),
+        ...(deps.toolOutputStore ? [createReadToolOutputTool(deps.toolOutputStore)] : []),
         // Always-on, not in the `meta.tools` allowlist: the data profile is the only
         // record of what the analysis's input dataset IS, and no file carries it (the
         // profiler's scratch tree is deleted on completion). An agent that cannot pull
@@ -211,6 +214,7 @@ export function createSandboxAgent(deps, meta, body, opts = {}) {
         ...skillTools,
         ...resolveSandboxTools(deps, meta.tools),
         ...(deps.blockerHolder ? [createReportBlockerTool(deps.blockerHolder)] : []),
+        ...(deps.fileMetadata ? [createSubmitFileMetadataTool(deps.fileMetadata)] : []),
     ];
     return {
         id: meta.id,

package/dist/app/chat-turn.d.ts

@@ -1,19 +1,18 @@
 /**
- * Chat-turn preparation — the host-agnostic assembly half of one chat turn.
- *
- * This is the PREPARATION half of a conversation turn, lifted out of the HTTP
- * route so callers other than the route (e.g. a CLI) can reuse it. It owns,
- * in order: thread-ownership resolution, best-effort title seeding, analysis
- * status load, and message assembly. It deliberately owns NONE of the
- * transport orchestration (streaming/SSE/queue/status codes) — that stays in
- * the caller. A turn is `prepareChatTurn → runAgent(own emit) → appendTurn`.
- *
- * Returns a typed result: `not_found` when the `threadId` is owned by a
- * different analysis (indistinguishable from absent), otherwise `ok` with the
- * assembled `messages` and the standalone `userMessage` the caller persists.
+ * The chat turn of a host: a turn is `runChatTurn`, and `prepareChatTurn` is its first step. The
+ * host gives only its transport values, and the harness stores the opening, each round, and the outcome.
  */
 import type { Pool } from "pg";
+import type { AgentSession } from "../auth/types.js";
+import type { UsageRecorder } from "../billing/usage-recorder.js";
+import type { TokenUsageRollup } from "../contracts/usage.js";
+import type { DbError } from "../lib/db-result.js";
+import { type AgentFinish } from "../loop/run-agent.js";
+import type { EmitFn } from "../loop/types.js";
 import { type ThreadType } from "../memory/thread-store.js";
+import type { AgentChat, PromptCachePolicy } from "../providers/types.js";
+import type { ThreadAgentResolver } from "../runtime/assemble.js";
+import type { AskApproval, AskRequest } from "../tools/approval/contract.js";
 import { type AssembledMessages } from "./message-assembly.js";
 import type { Logger } from "../lib/logger.js";
 import { type ProvenanceSeam } from "../provenance/seam.js";
@@ -49,3 +48,67 @@ export type PrepareChatTurnResult = ({
  * inside {@link assembleMessages} (applied once to the new user input only).
  */
 export declare function prepareChatTurn(deps: PrepareChatTurnDeps, params: PrepareChatTurnParams): Promise<PrepareChatTurnResult>;
+/** The root loop of a chat turn compacts its view past this estimate, in tokens. */
+export declare const DEFAULT_CONVERSATION_BUDGET = 150000;
+export interface RunChatTurnDeps extends PrepareChatTurnDeps {
+    /** The agent of a turn comes from the thread type, which only the preparation knows. */
+    readonly agents: ThreadAgentResolver;
+}
+/** The transport values of one turn. */
+export interface RunChatTurnParams {
+    readonly analysisId: string;
+    readonly threadId: string;
+    readonly userInput: string;
+    readonly session: AgentSession;
+    /** Makes the provider of the turn over the emit sink of the display recorder. */
+    readonly chat: (emit: EmitFn) => AgentChat;
+    readonly emit: EmitFn;
+    readonly signal: AbortSignal;
+    readonly usageRecorder: UsageRecorder;
+    /** The approval binding. It gets the emit sink of the display recorder, thus the display records each `data-ask`. */
+    readonly ask?: (request: AskRequest, emit: EmitFn) => Promise<AskApproval>;
+    /** Who sent the user message. */
+    readonly author?: string;
+    /** When the host opened the turn. Absent counts from the call. */
+    readonly startedAtMs?: number;
+    /** The cache policy of the root loop. Absent gives {@link CONVERSATION_PROMPT_CACHE}. */
+    readonly promptCache?: PromptCachePolicy;
+    /** The budget of the view of the root loop. Absent gives {@link DEFAULT_CONVERSATION_BUDGET}. */
+    readonly conversationBudget?: number;
+}
+export type ChatTurnOutcome = {
+    readonly status: "done";
+    readonly finish: AgentFinish;
+} | {
+    readonly status: "aborted";
+    readonly finish?: AgentFinish;
+} | {
+    readonly status: "failed";
+    readonly reason: string;
+    readonly cause: unknown;
+};
+export type ChatTurnResult = {
+    readonly kind: "prepare_failed";
+    readonly cause: unknown;
+} | {
+    readonly kind: "not_found";
+} | {
+    readonly kind: "agent_unresolved";
+    readonly threadType: ThreadType;
+} | {
+    readonly kind: "ran";
+    readonly outcome: ChatTurnOutcome;
+    /** True when the opening of the turn landed. */
+    readonly opened: boolean;
+    /** The error of the last write, when rows of the turn or its close did not land. */
+    readonly storeError?: DbError;
+    readonly durationMs: number;
+    readonly turnUsage?: TokenUsageRollup;
+    /** The final text of a run that returned. */
+    readonly fallbackText?: string;
+};
+/**
+ * Run one chat turn: prepare it, resolve its agent, store its opening, run the root loop with a
+ * round sink that stores each round, and close the turn with its outcome.
+ */
+export declare function runChatTurn(deps: RunChatTurnDeps, params: RunChatTurnParams): Promise<ChatTurnResult>;

package/dist/app/chat-turn.js

@@ -1,24 +1,23 @@
 /**
- * Chat-turn preparation — the host-agnostic assembly half of one chat turn.
- *
- * This is the PREPARATION half of a conversation turn, lifted out of the HTTP
- * route so callers other than the route (e.g. a CLI) can reuse it. It owns,
- * in order: thread-ownership resolution, best-effort title seeding, analysis
- * status load, and message assembly. It deliberately owns NONE of the
- * transport orchestration (streaming/SSE/queue/status codes) — that stays in
- * the caller. A turn is `prepareChatTurn → runAgent(own emit) → appendTurn`.
- *
- * Returns a typed result: `not_found` when the `threadId` is owned by a
- * different analysis (indistinguishable from absent), otherwise `ok` with the
- * assembled `messages` and the standalone `userMessage` the caller persists.
+ * The chat turn of a host: a turn is `runChatTurn`, and `prepareChatTurn` is its first step. The
+ * host gives only its transport values, and the harness stores the opening, each round, and the outcome.
  */
 import { unwrapOrThrow } from "../lib/result.js";
+import { finalText, runAgent } from "../loop/run-agent.js";
+import { passthroughStep } from "../loop/run-step.js";
+import { compactionExchangeOf } from "../memory/ai-sdk-message-storage.js";
+import { createConversationDisplayRecorder } from "../memory/conversation-display-recorder.js";
 import { deriveThreadTitle } from "../memory/derive-thread-title.js";
-import { createThreadHistory } from "../memory/thread-history.js";
+import { conversationRecordTurn, createThreadHistory } from "../memory/thread-history.js";
 import { createThreadStore } from "../memory/thread-store.js";
 import { createWorkingMemory } from "../memory/working-memory.js";
+import { findProviderError } from "../providers/errors.js";
+import { MEMORY_COMPACTION_REQUEST, SUMMARY_COMPACTION_REQUEST } from "../prompts/compaction.js";
+import { CONVERSATION_PROMPT_CACHE } from "../providers/prompt-cache.js";
 import { loadAnalysisStatus, queryNonTerminalRunsByAnalysis } from "../state/index.js";
-import { assembleMessages } from "./message-assembly.js";
+import { createToolOutputStore } from "../state/tool-outputs.js";
+import { suspensionOfFailure } from "../workflows/suspension.js";
+import { assembleMessages, contextRecordsFor } from "./message-assembly.js";
 import { renderRunActivity, renderRunActivityUnavailable, RUN_ACTIVITY_DETAIL_LIMIT } from "./run-activity.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { bindSessionEmit } from "../provenance/seam.js";
@@ -42,7 +41,7 @@ export async function prepareChatTurn(deps, params) {
         return { kind: "not_found" };
     }
     // The type a caller resolves the turn's agent from, and the type that the
-    // message assembly reads for its tail. An existing row carries
+    // message assembly reads for its context records. An existing row carries
     // its own. An absent one defaults to `conversation` — the store's own
     // default — so a best-effort create that fails non-fatally still leaves a
     // usable type; a successful create overrides it from the returned row.
@@ -79,19 +78,148 @@ export async function prepareChatTurn(deps, params) {
     catch (err) {
         logger.warn("title-seed failed (non-fatal)", logger.errorFields(err));
     }
-    const analysisState = await loadAnalysisStatus(pool, analysisId).unwrapOr(null);
-    const runActivityContext = await queryNonTerminalRunsByAnalysis(pool, analysisId, RUN_ACTIVITY_DETAIL_LIMIT).match((activity) => renderRunActivity(activity), () => renderRunActivityUnavailable());
     const history = createThreadHistory(pool);
-    const { messages, userMessage } = await assembleMessages({
+    const { messages, userMessage, contextRecords } = await assembleMessages({
         threadId,
         threadType,
         analysisId,
         userInput,
-        analysisContext: analysisState?.context ?? null,
-        runActivityContext,
+        ...(await readTurnContext(pool, analysisId)),
         history,
         workingMemory: createWorkingMemory(pool),
         ...(deps.logger ? { logger: deps.logger } : {}),
     });
-    return { kind: "ok", threadType, messages, userMessage };
+    return { kind: "ok", threadType, messages, userMessage, contextRecords };
+}
+/** The analysis context and the run activity of a turn. A failed read gives the fallback of its kind. */
+async function readTurnContext(pool, analysisId) {
+    const analysisState = await loadAnalysisStatus(pool, analysisId).unwrapOr(null);
+    const runActivityContext = await queryNonTerminalRunsByAnalysis(pool, analysisId, RUN_ACTIVITY_DETAIL_LIMIT).match((activity) => renderRunActivity(activity), () => renderRunActivityUnavailable());
+    return { analysisContext: analysisState?.context ?? null, runActivityContext };
+}
+/** The root loop of a chat turn compacts its view past this estimate, in tokens. */
+export const DEFAULT_CONVERSATION_BUDGET = 150_000;
+/**
+ * Run one chat turn: prepare it, resolve its agent, store its opening, run the root loop with a
+ * round sink that stores each round, and close the turn with its outcome.
+ */
+export async function runChatTurn(deps, params) {
+    const logger = (deps.logger ?? createNoopLogger()).named("harness.chat");
+    const startedAtMs = params.startedAtMs ?? Date.now();
+    let prepared;
+    try {
+        prepared = await prepareChatTurn(deps, { analysisId: params.analysisId, threadId: params.threadId, userInput: params.userInput });
+    }
+    catch (cause) {
+        return { kind: "prepare_failed", cause };
+    }
+    if (prepared.kind === "not_found")
+        return prepared;
+    const agent = deps.agents.forThread(prepared.threadType);
+    if (agent.isErr())
+        return { kind: "agent_unresolved", threadType: prepared.threadType };
+    const history = createThreadHistory(deps.pool, deps.logger);
+    const recorder = createConversationDisplayRecorder({ userText: params.userInput, topLevelCallPath: params.session.provenance.callPath, sink: params.emit });
+    // The groups that did not land yet, in the order of the turn. A failed write keeps them for the next write.
+    let pending = [
+        {
+            modelMessages: [prepared.userMessage, ...prepared.contextRecords],
+            displayMessages: recorder.takeOpening(),
+            ...(params.author === undefined ? {} : { author: params.author }),
+        },
+    ];
+    let startSeq;
+    let storeError;
+    // A store fault never stops the turn: the error rides the result.
+    const flush = async (close) => {
+        if (pending.length === 0 && close === undefined)
+            return;
+        const closing = close === undefined ? {} : { close };
+        const write = startSeq === undefined ? { opening: pending[0], rounds: pending.slice(1), ...closing } : { startSeq, rounds: pending, ...closing };
+        (await history.writeTurn(params.threadId, write)).match((written) => {
+            pending = [];
+            startSeq = written.startSeq;
+            storeError = undefined;
+        }, (error) => {
+            storeError = error;
+            logger.warn("chat turn write failed", { threadId: params.threadId, op: error.op, ...logger.errorFields(error.cause) });
+        });
+    };
+    await flush();
+    const { ask } = params;
+    let outcome;
+    let fallbackText;
+    try {
+        const run = await runAgent(agent.value, prepared.messages, params.session, {
+            provider: params.chat(recorder.emit),
+            signal: params.signal,
+            emit: recorder.emit,
+            runStep: passthroughStep,
+            usageRecorder: params.usageRecorder,
+            toolOutputStore: createToolOutputStore(deps.pool),
+            promptCache: params.promptCache ?? CONVERSATION_PROMPT_CACHE,
+            compaction: compactionPolicy(deps, params, prepared.threadType, agent.value, recorder.emit),
+            ...(deps.logger === undefined ? {} : { logger: deps.logger }),
+            ...(ask === undefined ? {} : { ask: (request) => ask(request, recorder.emit) }),
+            onRound: async (round) => {
+                pending.push({ modelMessages: round.messages, displayMessages: recorder.takeRound(round.messages) });
+                await flush();
+            },
+        });
+        outcome = run.finish.reason === "aborted" ? { status: "aborted", finish: run.finish } : { status: "done", finish: run.finish };
+        // An abort can end the run inside an exchange, and the text of an exchange is a summary, and no reply.
+        fallbackText = finalText(run.messages.filter((message) => compactionExchangeOf(message) === undefined));
+    }
+    catch (cause) {
+        // A provider failure that races an abort stays a failure, thus both facts must hold.
+        const aborted = params.signal.aborted && cause instanceof Error && cause.name === "AbortError";
+        outcome = aborted ? { status: "aborted" } : { status: "failed", reason: failureReasonOf(cause), cause };
+    }
+    const durationMs = Date.now() - startedAtMs;
+    const turnUsage = outcome.status === "failed" ? undefined : outcome.finish?.turnUsage;
+    await flush({
+        status: outcome.status,
+        ...(outcome.status === "failed" ? { reason: outcome.reason, note: conversationRecordTurn(failureNote(outcome.reason)) } : {}),
+        ...(turnUsage === undefined ? {} : { turnUsage }),
+        turnDurationMs: durationMs,
+    });
+    return {
+        kind: "ran",
+        outcome,
+        opened: startSeq !== undefined,
+        ...(storeError === undefined ? {} : { storeError }),
+        durationMs,
+        ...(turnUsage === undefined ? {} : { turnUsage: { ...turnUsage } }),
+        ...(fallbackText === undefined ? {} : { fallbackText }),
+    };
+}
+const WORKING_MEMORY_TOOL_ID = "update_working_memory";
+function compactionPolicy(deps, params, threadType, agent, emit) {
+    // A report thread reads a frozen copy of the working memory, thus its agent declares no memory tool.
+    const remembers = agent.tools.some((tool) => tool.id === WORKING_MEMORY_TOOL_ID);
+    const workingMemory = createWorkingMemory(deps.pool);
+    return {
+        budget: params.conversationBudget ?? DEFAULT_CONVERSATION_BUDGET,
+        // A streaming provider sends each text delta with no source, thus a delta of the summary would show as a reply.
+        provider: params.chat((event) => (event.type === "text-delta" ? undefined : emit(event))),
+        request: remembers ? MEMORY_COMPACTION_REQUEST : SUMMARY_COMPACTION_REQUEST,
+        mask: remembers ? { allow: [WORKING_MEMORY_TOOL_ID] } : "none",
+        keepFirstTurn: threadType === "report",
+        recordsAfter: async (view) => contextRecordsFor({ threadType, analysisId: params.analysisId, workingMemory, ...(await readTurnContext(deps.pool, params.analysisId)) }, view),
+    };
+}
+/** The reason of a failed turn. It never holds the error message, because each later turn sends the note to the vendor. */
+function failureReasonOf(err) {
+    const suspension = suspensionOfFailure(err);
+    if (suspension !== undefined)
+        return suspension.reason;
+    const providerError = findProviderError(err);
+    if (providerError?.type === "auth")
+        return "The model endpoint refused the credential.";
+    if (providerError !== undefined)
+        return "The model request failed.";
+    return "The turn stopped on an internal error.";
+}
+function failureNote(reason) {
+    return ["[Turn Failed]", `The turn stopped before it finished. Reason: ${reason}`, "The rounds above this note ran, and their results are stored."].join("\n");
 }

package/dist/app/message-assembly.d.ts

@@ -1,38 +1,10 @@
 /**
- * Chat-turn message assembly.
+ * Chat-turn message assembly: the view of the latest compaction marker, the user message, and then the
+ * context records. A kind gets a new record only when the view holds none of that kind, or when the hash
+ * of its text differs. The root loop compacts the view past its budget.
  *
- * Builds the `messages` array `runAgent` receives for one conversation turn:
- *
- *   [ ...loadRecent(threadId, budget)            ← stable, cacheable prefix
- *     {user: cortex_analysis_state.context},     ← tail
- *     {user: runActivityContext},                 ← tail
- *     {user: render(workingMemory)},             ← tail, `conversation` thread only
- *     {user: normalizeUnicode(redactSecrets(input))} ]  ← tail
- *
- * `system + tools + history` is the cacheable prefix — it only extends
- * turn-to-turn. Run activity, working memory, and analysis context go in the
- * **tail** as `user` messages: they change every turn, so a system-message
- * placement would bust the Anthropic cache prefix.
- *
- * A `report` thread does not get the working-memory tail. The spawn copies the
- * working-memory render into the child transcript at the anchor. A live render
- * sees state past that anchor, and that breaks the knowledge cap of a report
- * session. The analysis context and the run activity stay on both thread types.
- *
- * The history window of a `report` thread also keeps the first turn. That turn
- * is the seed, and it is the one record of the brief and of the copied render.
- * The window evicts the oldest turn first, thus a long session would drop its
- * own charter and keep only its tools. A `conversation` thread evicts as before,
- * because its live tail carries the working memory on each turn.
- *
- * Sanitization (`redactSecrets`, `normalizeUnicode`) is applied **once**, to
- * the new user input only — never to history, assistant messages, tool
- * results, the analysis context, or the rendered working memory.
- *
- * The returned `userMessage` is the sanitized user input on its own — the
- * route persists `[userMessage, ...loop output]` via `appendTurn`, so the
- * tail injections (ephemeral, re-derived each turn) are never written to the
- * thread store.
+ * The view of a `report` thread keeps the first turn, because that turn is the seed: the one record of
+ * the brief and of the copied working memory.
  */
 import type { ModelMessage } from "ai";
 import type { Logger } from "../lib/logger.js";
@@ -40,16 +12,10 @@ import type { LoopMessage } from "../loop/types.js";
 import type { ThreadHistory } from "../memory/thread-history.js";
 import type { ThreadType } from "../memory/thread-store.js";
 import type { WorkingMemoryStore } from "../memory/working-memory.js";
-/**
- * Token budget for the `loadRecent` history window. Sized to leave headroom
- * under the model context window for the system prompt, tool definitions,
- * the three tail messages, and the output budget.
- */
-export declare const DEFAULT_HISTORY_TOKEN_BUDGET = 120000;
 export interface AssembleMessagesArgs {
     /** The conversation thread — a UI-generated UUID, never the analysisId. */
     readonly threadId: string;
-    /** The type of the thread. A `report` thread drops the working-memory tail, and its window keeps the seed. */
+    /** The type of the thread. A `report` thread gets no working-memory record, and its view keeps the seed. */
     readonly threadType: ThreadType;
     /** The analysis scope — keys working memory and (separately) the context. */
     readonly analysisId: string;
@@ -57,29 +23,27 @@ export interface AssembleMessagesArgs {
     readonly userInput: string;
     /** `cortex_analysis_state.context`, already read by the route. `null` when absent. */
     readonly analysisContext: string | null;
-    /** Fresh, non-persisted analysis-wide run activity rendered by chat-turn preparation. */
+    /** The analysis-wide run activity that chat-turn preparation rendered for this turn. */
     readonly runActivityContext: string;
-    /** The conversation message store — supplies the history window. */
+    /** The conversation message store — supplies the view of the thread. */
     readonly history: ThreadHistory;
-    /** The working-memory store — rendered into the tail. */
+    /** The working-memory store — rendered into a context record. */
     readonly workingMemory: WorkingMemoryStore;
-    /** History-window token budget. Defaults to {@link DEFAULT_HISTORY_TOKEN_BUDGET}. */
-    readonly tokenBudget?: number;
     /** Diagnostic seam for the history repair record; omitted falls back to no-op. */
     readonly logger?: Logger;
 }
 export interface AssembledMessages {
     /** The full message array for `runAgent`. */
     readonly messages: LoopMessage[];
-    /**
-     * The sanitized user input as its own message — the genuine turn start.
-     * The route persists this plus the loop's output; the tail injections are
-     * not persisted.
-     */
+    /** The sanitized user input as its own message — the genuine turn start. */
     readonly userMessage: ModelMessage;
+    /** The context records after the user message. The turn stores them with the user message. */
+    readonly contextRecords: readonly ModelMessage[];
 }
 /**
- * Assemble the message array for one chat turn. Async — it reads the history
- * window and renders working memory.
+ * Assemble the message array for one chat turn. Async — it reads the view of
+ * the thread and renders working memory.
  */
 export declare function assembleMessages(args: AssembleMessagesArgs): Promise<AssembledMessages>;
+/** The context records of one turn, in the order analysis context, run activity, working memory. */
+export declare function contextRecordsFor(args: Pick<AssembleMessagesArgs, "threadType" | "analysisId" | "analysisContext" | "runActivityContext" | "workingMemory">, history: readonly ModelMessage[]): Promise<ModelMessage[]>;