@inflexa-ai/harness 0.39.2 → 0.41.0

package/dist/execution/run-synthesis.js

@@ -37,6 +37,7 @@ import { decodeObjectString } from "../lib/zod-issues.js";
 import { runToTerminal } from "../loop/run-to-terminal.js";
 import { passthroughStep } from "../loop/run-step.js";
 import { defineTool } from "../tools/define-tool.js";
+import { createReadToolOutputTool } from "../tools/read-tool-output.js";
 import { createReportBlockerToolFor } from "../tools/sandbox/report-blocker.js";
 import { createLiteratureReviewerTool } from "../tools/research/literature-reviewer.js";
 // ── Agent identity / budgets ────────────────────────────────────────
@@ -52,6 +53,11 @@ export const SYNTHESIS_AGENT_ID = "run-synthesizer";
  * + draft + 1–2 submit/fix cycles + headroom.
  */
 const SYNTHESIZER_MAX_ITERATIONS = 25;
+/**
+ * Cap on `literature_reviewer` calls per run. Not named in the prompt: a
+ * model treats a stated call-count limit as a target to hit, not a maximum.
+ */
+const LITERATURE_REVIEWER_BUDGET = 3;
 // ── Validation ──────────────────────────────────────────────────────
 function zodIssuesToValidationIssues(error, input, rootPath = "synthesis") {
     return error.issues.map((i) => ({
@@ -358,11 +364,13 @@ export async function generateRunSynthesis(input) {
         bioKeys: input.bioKeys,
         citationResolver: input.citationResolver,
         usageRecorder: input.usageRecorder,
+        ...(input.toolOutputStore ? { toolOutputStore: input.toolOutputStore } : {}),
     });
     const validateTool = buildValidateTool(innerCtx);
     const submitTool = buildSubmitTool(holder, innerCtx);
     const blockerTool = buildBlockerTool(holder);
-    const tools = [validateTool, submitTool, blockerTool, reviewer];
+    const readTools = input.toolOutputStore ? [createReadToolOutputTool(input.toolOutputStore)] : [];
+    const tools = [validateTool, submitTool, blockerTool, reviewer, ...readTools];
     const agent = {
         id: SYNTHESIS_AGENT_ID,
         systemPrompt: composeSystemPrompt(synthesisAgentPrompt),
@@ -380,6 +388,8 @@ export async function generateRunSynthesis(input) {
         runStep: passthroughStep,
         resolved: () => holder.outcome !== null,
         usageRecorder: input.usageRecorder,
+        toolOutputStore: input.toolOutputStore,
+        toolBudget: { [reviewer.id]: LITERATURE_REVIEWER_BUDGET },
     };
     await runToTerminal(agent, [{ role: "user", content: prompt }], input.session, loopDeps, {
         tools: [submitTool, blockerTool],

package/dist/execution/step-summary.d.ts

@@ -1,61 +1,52 @@
 /**
- * Per-step interpretive markdown summary — a focused `runAgent` tool-loop on
- * the harness `ChatProvider` that consumes the step's in-memory transcript
- * (the `runAgent` `messages` array the workflow body already holds) AND a
- * scoped `read_file` so it grounds every quantitative claim in the persisted
- * output files rather than confabulating from `execute_command` stdout.
+ * Per-step interpretive summary. Continues the step agent's conversation
+ * (`continueAgent`) so the request reuses the cached prefix and keeps
+ * signed thinking blocks valid.
  *
  * Contract:
- *   - `runAgent` loop with a single `read_file` tool scoped to the step's
- *     writable output tree (via `createReadFileTool(workspaceFs, workingDir)`).
- *     The summarizer reads any output file it needs, then emits the markdown
+ *   - Sends the step agent's system prompt and tools, masked to `read_file`
+ *     and `grep` in the step's output tree plus `read_tool_output`, and emits the markdown
  *     summary as its final assistant text.
  *   - Returns `{ stepId, agentId, markdown }` on non-empty final text;
- *     `undefined` on empty/empty-after-trim, on a loop throw, or on no
- *     text in the final assistant turn. Non-fatal — the workflow body decides
- *     whether to write `output/summary.md`.
+ *     `undefined` on empty text, on a throw, or when the request cap is hit
+ *     before a final answer (a continuation runs no wrap-up). Non-fatal.
  *   - `Session` is taken explicitly (see the harness-durable-runtime spec).
  *
- * Honest empty: with no output artifacts the prompt directs the model to
+ * Honest empty: with no output artifacts the request directs the model to
  * state plainly that the step produced no output files — no synthesized
  * results. Blocked steps skip this producer entirely (handled upstream).
  *
  * Transcript-from-memory: per the harness-thread-store spec, workflow loops have no `messages`
  * table; reconstruction from `operation_outputs` is read-side only. At
- * step time the workflow body already holds the array — pass it in.
+ * step time the workflow body already holds the array — pass it in. The task
+ * always closes its unanswered calls, so the transcript needs no repair.
  */
 import type { AgentSession } from "../auth/types.js";
-import type { LoopMessage } from "../loop/types.js";
+import { type ToolOutputStore } from "../loop/tool-output.js";
+import type { AgentDefinition, LoopMessage } from "../loop/types.js";
 import type { AgentChat } from "../providers/types.js";
-import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
 import { type StepSummary } from "../schemas/step-summary.js";
 import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 export interface GenerateStepSummaryOptions {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
-    /** LLM usage-accounting seam for the summary loop; omitted falls back to the no-op recorder. */
+    /** LLM usage-accounting seam for the continuation; omitted falls back to the no-op recorder. */
     readonly usageRecorder?: UsageRecorder;
+    /** The store of the task, thus the loop of the continuation keeps its texts where the read tool of the agent reads them. */
+    readonly toolOutputStore?: ToolOutputStore;
+    /** The provider of the task, thus each request extends the prefix that the task cached. */
     readonly provider: AgentChat;
     readonly session: AgentSession;
-    readonly modelId: string;
-    /** In-memory transcript from `runAgent` — assistant + tool-result rounds. */
-    readonly messages: readonly LoopMessage[];
+    /** The step agent: the continuation sends its system prompt and its declared tools. */
+    readonly agent: AgentDefinition;
+    /** Task transcript, then the file-metadata exchange messages if one ran. */
+    readonly conversation: readonly LoopMessage[];
     readonly artifactPaths: readonly string[];
-    /** Workspace read seam — backs the scoped `read_file` tool. */
-    readonly workspaceFs: WorkspaceFilesystem;
-    /** Absolute host path to the step's writable output tree — `read_file`'s working dir. */
-    readonly workingDir: string;
     readonly stepId: string;
     readonly agentId: string;
     readonly runId: string;
-    readonly maxIterations?: number;
     readonly signal?: AbortSignal;
 }
-/**
- * Run the post-step summary loop on the harness provider against the supplied
- * transcript, grounding claims in persisted files via `read_file`. Returns
- * `undefined` on any non-fatal failure mode; the workflow body proceeds
- * without `summary.md` in that case.
- */
+/** Returns `undefined` on non-fatal failure instead of throwing. */
 export declare function generateStepSummary(opts: GenerateStepSummaryOptions): Promise<StepSummary | undefined>;

package/dist/execution/step-summary.js

@@ -1,35 +1,31 @@
 /**
- * Per-step interpretive markdown summary — a focused `runAgent` tool-loop on
- * the harness `ChatProvider` that consumes the step's in-memory transcript
- * (the `runAgent` `messages` array the workflow body already holds) AND a
- * scoped `read_file` so it grounds every quantitative claim in the persisted
- * output files rather than confabulating from `execute_command` stdout.
+ * Per-step interpretive summary. Continues the step agent's conversation
+ * (`continueAgent`) so the request reuses the cached prefix and keeps
+ * signed thinking blocks valid.
  *
  * Contract:
- *   - `runAgent` loop with a single `read_file` tool scoped to the step's
- *     writable output tree (via `createReadFileTool(workspaceFs, workingDir)`).
- *     The summarizer reads any output file it needs, then emits the markdown
+ *   - Sends the step agent's system prompt and tools, masked to `read_file`
+ *     and `grep` in the step's output tree plus `read_tool_output`, and emits the markdown
  *     summary as its final assistant text.
  *   - Returns `{ stepId, agentId, markdown }` on non-empty final text;
- *     `undefined` on empty/empty-after-trim, on a loop throw, or on no
- *     text in the final assistant turn. Non-fatal — the workflow body decides
- *     whether to write `output/summary.md`.
+ *     `undefined` on empty text, on a throw, or when the request cap is hit
+ *     before a final answer (a continuation runs no wrap-up). Non-fatal.
  *   - `Session` is taken explicitly (see the harness-durable-runtime spec).
  *
- * Honest empty: with no output artifacts the prompt directs the model to
+ * Honest empty: with no output artifacts the request directs the model to
  * state plainly that the step produced no output files — no synthesized
  * results. Blocked steps skip this producer entirely (handled upstream).
  *
  * Transcript-from-memory: per the harness-thread-store spec, workflow loops have no `messages`
  * table; reconstruction from `operation_outputs` is read-side only. At
- * step time the workflow body already holds the array — pass it in.
+ * step time the workflow body already holds the array — pass it in. The task
+ * always closes its unanswered calls, so the transcript needs no repair.
  */
-import { forSubAgent } from "../auth/types.js";
-import { finalText, runAgent } from "../loop/run-agent.js";
+import { continueAgent } from "../loop/continue-agent.js";
+import { finalText } from "../loop/run-agent.js";
 import { passthroughStep } from "../loop/run-step.js";
+import { READ_TOOL_OUTPUT_TOOL_ID } from "../loop/tool-output.js";
 import { stepSummaryPrompt } from "../prompts/execute-analysis/step-summary.js";
-import { composeSystemPrompt } from "../agents/system-prompt.js";
-import { createReadFileTool } from "../tools/workspace/read-file.js";
 import { StepSummarySchema } from "../schemas/step-summary.js";
 import { incrementSummaryNullCount } from "./step-summary-metrics.js";
 import { createNoopLogger } from "../lib/console-logger.js";
@@ -40,59 +36,36 @@ Your prior conversation — tool calls, code output, intermediate results — is
 Ground every quantitative claim in a PERSISTED output file: open it with the read_file tool and report what the file actually contains. A number that appears only in command stdout is NOT a citable result — read the artifact that holds it. If there are no output files, say so plainly; do not invent numbers and do not synthesize results no artifact backs.
 
 When finished, write the markdown summary as your final message. It is stored as the step summary exactly as you write it.`;
-/** Sub-agent identity for the summary loop — provenance only. */
 const SUMMARY_AGENT_ID = "step-summary-writer";
-/** Iteration budget: a handful of read_file reads plus the final write-up. */
-const DEFAULT_MAX_ITERATIONS = 12;
-/**
- * Sanitize a transcript that came from the loop so it can prefix a fresh
- * loop turn: any final assistant `tool_use` block needs a matching
- * `tool_result` we are not going to produce. Drop the trailing partial round.
- */
-function sanitizeTranscript(messages) {
-    const out = [...messages];
-    while (out.length > 0) {
-        const last = out[out.length - 1];
-        const blocks = Array.isArray(last.content) ? last.content : [];
-        const hasOpenToolUse = last.role === "assistant" && blocks.some((b) => b.type === "tool-call");
-        if (hasOpenToolUse) {
-            out.pop();
-            continue;
-        }
-        break;
-    }
-    return out;
+/** A handful of read_file reads plus the final write-up. */
+const SUMMARY_MAX_REQUESTS = 12;
+/** Must already be declared tools of the step agent — the mask only narrows. */
+const SUMMARY_TOOLS = ["read_file", "grep", READ_TOOL_OUTPUT_TOOL_ID];
+function summaryRequest(artifactPaths) {
+    return `${SYSTEM_PROMPT}\n\n${stepSummaryPrompt(artifactPaths.join("\n"))}`;
 }
-/**
- * Run the post-step summary loop on the harness provider against the supplied
- * transcript, grounding claims in persisted files via `read_file`. Returns
- * `undefined` on any non-fatal failure mode; the workflow body proceeds
- * without `summary.md` in that case.
- */
+/** Returns `undefined` on non-fatal failure instead of throwing. */
 export async function generateStepSummary(opts) {
     const logger = (opts.logger ?? createNoopLogger()).named("step-summary").with({ runId: opts.runId, stepId: opts.stepId, agentId: opts.agentId });
-    const transcript = sanitizeTranscript(opts.messages);
-    const userPrompt = stepSummaryPrompt(opts.artifactPaths.join("\n"));
-    const writer = {
-        id: SUMMARY_AGENT_ID,
-        systemPrompt: composeSystemPrompt(SYSTEM_PROMPT),
-        model: opts.modelId,
-        tools: [createReadFileTool(opts.workspaceFs, opts.workingDir)],
-        maxIterations: opts.maxIterations ?? DEFAULT_MAX_ITERATIONS,
-    };
-    const signal = opts.signal ?? new AbortController().signal;
     let result;
     try {
-        result = await runAgent(writer, [...transcript, { role: "user", content: userPrompt }], forSubAgent(opts.session, SUMMARY_AGENT_ID), {
+        result = await continueAgent(opts.agent, opts.conversation, {
+            text: summaryRequest(opts.artifactPaths),
+            mask: { allow: SUMMARY_TOOLS },
+            maxRequests: SUMMARY_MAX_REQUESTS,
+            stepNamespace: "step-summary",
+            accountingAgentId: SUMMARY_AGENT_ID,
+        }, opts.session, {
             provider: opts.provider,
-            signal,
+            signal: opts.signal ?? new AbortController().signal,
             emit: () => { },
             runStep: passthroughStep,
             usageRecorder: opts.usageRecorder,
+            toolOutputStore: opts.toolOutputStore,
         });
     }
     catch (err) {
-        logger.warn("summary loop failed", logger.errorFields(err));
+        logger.warn("summary continuation failed", logger.errorFields(err));
         incrementSummaryNullCount(opts.agentId, "throw");
         return undefined;
     }

package/dist/index.d.ts

@@ -59,20 +59,21 @@ export type { AskGateway, AskGatewayDeps, AskContext, AnswerOutcome, PendingAsk
 export { UnavailableAsk, AskRejectedError } from "./tools/approval/contract.js";
 export type { Ask, AskRequest, AskReply, AskApproval } from "./tools/approval/contract.js";
 export { runAgent, finalText } from "./loop/run-agent.js";
-export type { RunAgentOptions, RunAgentResult, AgentFinish } from "./loop/run-agent.js";
+export type { RunAgentOptions, RunAgentResult, AgentFinish, AgentRound } from "./loop/run-agent.js";
+export type { CompactionPolicy } from "./loop/compaction.js";
+export type { ToolMask } from "./loop/tool-mask.js";
 export type { AgentDefinition, RunStep, EmitFn, EmitEvent, EventSource } from "./loop/types.js";
+export type { KeptToolOutput, ToolOutputStore } from "./loop/tool-output.js";
 export { passthroughStep } from "./loop/run-step.js";
 export { forStep, forSubAgent, scopeResource, scopeWorkloadId } from "./auth/types.js";
 export type { AgentSession, RequestSession, RunSession, Identity, Scope, Credential, Provenance, RunFrame, AuthContext, ResourceCoordinates, HookSessionView, ResolvableSession, } from "./auth/types.js";
 export { makeLocalAuth } from "./auth/local-auth-context.js";
-export { createAnthropicProvider } from "./providers/anthropic.js";
-export type { AnthropicProviderDeps } from "./providers/anthropic.js";
 export { createConfiguredAiSdkProvider, DEFAULT_MAX_OUTPUT_TOKENS } from "./providers/ai-sdk.js";
 export type { AiSdkProviderConfig, ConfiguredAiSdkProviderDeps, ProviderHostPolicy } from "./providers/ai-sdk.js";
 export { createEmbeddingProvider } from "./providers/embedding.js";
 export type { EmbeddingProviderDeps } from "./providers/embedding.js";
 export type { AgentChat, ChatProvider, EmbeddingProvider, ChatRequest, ChatResponse, ChatStreamEvent, ChatUsage, ModelMessage, PromptCachePolicy, ReasoningPolicy, } from "./providers/types.js";
-export { DEFAULT_PROMPT_CACHE, promptCacheProviderOptions, withPromptCacheBreakpoint } from "./providers/prompt-cache.js";
+export { CONVERSATION_PROMPT_CACHE, DEFAULT_PROMPT_CACHE, promptCacheProviderOptions, withPromptCacheBreakpoint } from "./providers/prompt-cache.js";
 export { DEFAULT_REASONING } from "./providers/reasoning.js";
 export { toProviderError, isProviderError } from "./providers/errors.js";
 export type { ProviderError } from "./providers/errors.js";
@@ -81,12 +82,12 @@ export type { SuspendOn } from "./providers/errors.js";
 export { suspensionOfFailure } from "./workflows/suspension.js";
 export type { Suspension } from "./workflows/suspension.js";
 export { createStreamingChat } from "./providers/streaming-chat.js";
-export { prepareChatTurn } from "./app/chat-turn.js";
-export type { PrepareChatTurnDeps, PrepareChatTurnParams, PrepareChatTurnResult } from "./app/chat-turn.js";
+export { DEFAULT_CONVERSATION_BUDGET, openChatTurn, prepareChatTurn, runChatTurn } from "./app/chat-turn.js";
+export type { ChatTurnOutcome, ChatTurnRan, ChatTurnRefusal, ChatTurnResult, ChatTurnSession, OpenChatTurn, OpenChatTurnParams, PrepareChatTurnDeps, PrepareChatTurnParams, PrepareChatTurnResult, RunChatTurnDeps, RunChatTurnParams, RunOpenChatTurnParams, } from "./app/chat-turn.js";
 export { createThreadStore } from "./memory/thread-store.js";
 export type { ThreadStore, Thread, ThreadType, ThreadInputError, CreateThreadInput, ListThreadsInput, ThreadPage } from "./memory/thread-store.js";
 export { createThreadHistory, conversationRecordTurn } from "./memory/thread-history.js";
-export type { ThreadHistory, StoredMessage, RetractOutcome, ConversationTurn } from "./memory/thread-history.js";
+export type { ThreadHistory, StoredMessage, RetractOutcome, ConversationTurn, TurnWrite, TurnWriteResult, TurnClose, TurnStatus, StoredTurnRecord, } from "./memory/thread-history.js";
 export { syntheticUserMessage, syntheticRecordMessage, isSyntheticUserMessage, isSyntheticRecordMessage } from "./memory/ai-sdk-message-storage.js";
 export { createConversationDisplayRecorder } from "./memory/conversation-display-recorder.js";
 export type { ConversationDisplayRecorder, ConversationDisplayRecorderOptions } from "./memory/conversation-display-recorder.js";
@@ -95,7 +96,7 @@ export type { ConversationDisplayMetadata, ConversationUIData, ConversationUIMes
 export { storedMessagesToCortex } from "./memory/conversation-display-replay.js";
 export type { CortexChatEvent, TextDeltaEvent, ToolStartedEvent, ToolFinishedEvent, ToolOutcome, ToolCallOutcome, ToolCallDetail, FinishEvent, ChatErrorEvent, } from "./contracts/chat-events.js";
 export type { TokenUsageRollup } from "./contracts/usage.js";
-export type { CortexChatPart, PresentationPart, PresentationContent, PlanPart, RunCardPart, FileReferencePart, FileReferenceEntry, RunStartedPart, DagStatePart, DagStepState, StepStatus, StepActivityPart, StepPhase, StepFileTreePart, FileTreeEntry, StepOutputPart, StepOutputFile, StepSummaryPart, StepUsagePart, StepBlockedPart, RunSynthesisPart, SynthesizedFinding, BiologicalTheme, SynthesisProgressPart, SynthesisPhase, RunCompletedPart, RunCompletedFinding, RunFailedPart, } from "./contracts/chat-parts.js";
+export type { CortexChatPart, PresentationPart, PresentationContent, PlanPart, RunCardPart, FileReferencePart, FileReferenceEntry, RunStartedPart, DagStatePart, DagStepState, StepStatus, StepActivityPart, StepPhase, StepFileTreePart, FileTreeEntry, StepOutputPart, StepOutputFile, StepSummaryPart, StepUsagePart, StepBlockedPart, RunSynthesisPart, SynthesizedFinding, BiologicalTheme, SynthesisProgressPart, SynthesisPhase, RunCompletedPart, RunCompletedFinding, RunFailedPart, CompactionPart, } from "./contracts/chat-parts.js";
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./contracts/part-registry.js";
 export type { CortexChatPartType, PartDescriptor, PartEmitter, PartConsumer } from "./contracts/part-registry.js";
 export { parseStructureUrl, alphafoldEntryUrl, alphafoldPredictionUrl } from "./contracts/structure-source.js";

package/dist/index.js

@@ -94,36 +94,18 @@ export { passthroughStep } from "./loop/run-step.js";
 export { forStep, forSubAgent, scopeResource, scopeWorkloadId } from "./auth/types.js";
 export { makeLocalAuth } from "./auth/local-auth-context.js";
 // Providers.
-export { createAnthropicProvider } from "./providers/anthropic.js";
-// The general provider-configuration path: `createConfiguredAiSdkProvider`
-// builds a `ChatProvider` from an `AiSdkProviderConfig` — the connection+model
-// union discriminated over the `anthropic` and `openai-compatible` kinds — with
-// `ConfiguredAiSdkProviderDeps` as its argument shape. `createAnthropicProvider`
-// above is a convenience over this union's `anthropic` arm.
+// `AiSdkProviderConfig` discriminates by `kind`: `anthropic`, `openai`, or
+// `openai-compatible`.
 export { createConfiguredAiSdkProvider, DEFAULT_MAX_OUTPUT_TOKENS } from "./providers/ai-sdk.js";
 export { createEmbeddingProvider } from "./providers/embedding.js";
-// Prompt caching. `PromptCachePolicy` is the harness's vendor-neutral cache
-// directive; a composition root sets it per run via `RunAgentOptions.promptCache`
-// (defaulting to `DEFAULT_PROMPT_CACHE` — 5m — when omitted, since an agent loop
-// re-sends its prefix every iteration and breaks even immediately). Hosts whose
-// endpoint ignores cache directives — notably the Claude Max OAuth path — pass
-// `"off"`; the `cortex.harness.agent.cache_*_tokens` metrics show which case a
-// deployment is actually in. `withPromptCacheBreakpoint` is the placement: it
-// puts the ONE marker of a request on its last message, where every hop upstream
-// can count it, in the namespace of each vendor that needs an explicit
-// breakpoint (Anthropic and Bedrock; the OpenAI family and Gemini cache without
-// one). Never attach `promptCacheProviderOptions` to a request itself — that
-// emits a top-level field an intermediary cannot see, and a proxy that trims to
-// Anthropic's cap of four breakpoints then sends five.
-export { DEFAULT_PROMPT_CACHE, promptCacheProviderOptions, withPromptCacheBreakpoint } from "./providers/prompt-cache.js";
-// Reasoning depth. `ReasoningPolicy` is the vendor-neutral name for how deep a
-// model reasons; a composition root sets it per run through
-// `RunAgentOptions.reasoning`. It defaults to `DEFAULT_REASONING` — `xhigh` —
-// because an agent loop drives tools over many iterations, and a shallow turn
-// there wastes more calls than the deeper turn costs in tokens. The provider
-// package resolves the name for the model that it is bound to, thus a model
-// that accepts no `xhigh` gets the nearest name that it accepts. A host on a
-// model with no reasoning support passes `"provider-default"`.
+// Two cache markers (loop + `withPromptCacheBreakpoint`) count against a vendor's
+// breakpoint cap (four for Anthropic). Never attach `promptCacheProviderOptions`
+// to the request itself, or a proxy miscounts. The root chat loop gets
+// `CONVERSATION_PROMPT_CACHE` (1h), because a person can reply minutes later.
+export { CONVERSATION_PROMPT_CACHE, DEFAULT_PROMPT_CACHE, promptCacheProviderOptions, withPromptCacheBreakpoint } from "./providers/prompt-cache.js";
+// Effort resolves in order: `ChatRequest.reasoning`, the provider config's
+// `reasoning`, then `DEFAULT_REASONING`, downgraded to what the model accepts.
+// A model with no reasoning support takes `"provider-default"`.
 export { DEFAULT_REASONING } from "./providers/reasoning.js";
 // Provider error channel. `ProviderError` is the value `chat`/`embed` fail
 // with; `toProviderError` is its sole constructor. Exposed so an embedder
@@ -144,12 +126,11 @@ export { suspensionOfFailure } from "./workflows/suspension.js";
 // `chatStream` and forwards each text delta to `onText`, so a same-process host
 // gets live token streaming out of the otherwise non-streaming loop.
 export { createStreamingChat } from "./providers/streaming-chat.js";
-// Conversation turn + thread memory — the transport-free halves of one chat
-// turn a same-process host drives itself. `prepareChatTurn` assembles the model
-// message array; `createConversationDisplayRecorder` records the independently
-// replayable UI projection while forwarding live events; `appendTurn` persists
-// both atomically. `createThreadStore` owns thread metadata (create/list/title).
-export { prepareChatTurn } from "./app/chat-turn.js";
+// Conversation turn + thread memory. A host runs a chat turn with `runChatTurn`
+// and gives only its transport values: the harness stores the opening, each round,
+// and the outcome. `appendTurn` stays for a record of a host. `createThreadStore`
+// owns thread metadata (create/list/title).
+export { DEFAULT_CONVERSATION_BUDGET, openChatTurn, prepareChatTurn, runChatTurn } from "./app/chat-turn.js";
 export { createThreadStore } from "./memory/thread-store.js";
 export { createThreadHistory, conversationRecordTurn } from "./memory/thread-history.js";
 // The synthetic-message primitives. A host appends a record of out-of-band work (an analysis run's

package/dist/lib/zod-issues.js

@@ -201,10 +201,8 @@ function parseAs(raw, expected) {
  * collects what came off, for the hint to quote back; it is empty when the
  * string carried no recognized wrapper.
  *
- * Deliberately narrow, mirroring `tools/research/generate-analogy-report.ts`'s
- * `stripFence`: these two shapes and nothing else. Beyond that, no salvaging —
- * a fragment with a *leading* `<parameter name=…>` opener is not a whole value
- * with decoration on it, and pretending otherwise would invent content.
+ * Deliberately narrow: only these two shapes. A fragment with a *leading*
+ * `<parameter name=…>` opener is not salvageable without inventing content.
  */
 function stripWrappers(raw) {
     const removed = [];

package/dist/loop/compaction.d.ts

@@ -0,0 +1,20 @@
+import type { AgentChat } from "../providers/types.js";
+import type { ToolMask } from "./tool-mask.js";
+import type { LoopMessage } from "./types.js";
+/** The cap of requests of one compaction exchange: up to 3 rounds of memory edits, and then the summary. */
+export declare const COMPACTION_MAX_REQUESTS = 4;
+/** How the loop compacts its conversation when the view passes the budget. */
+export interface CompactionPolicy {
+    /** The budget of the view, in estimated tokens. */
+    readonly budget: number;
+    /** The provider of the conversation, with no text stream to the surface: the summary is no reply. */
+    readonly provider: AgentChat;
+    /** The text of the compaction request. */
+    readonly request: string;
+    /** The tools that can run in the exchange. */
+    readonly mask: ToolMask;
+    /** Keep the first turn, the seed of a report thread, in front of each view. */
+    readonly keepFirstTurn: boolean;
+    /** The context records that come after a new marker, for the view that starts at the marker. */
+    readonly recordsAfter: (view: readonly LoopMessage[]) => Promise<readonly LoopMessage[]>;
+}

package/dist/loop/compaction.js

@@ -0,0 +1,2 @@
+/** The cap of requests of one compaction exchange: up to 3 rounds of memory edits, and then the summary. */
+export const COMPACTION_MAX_REQUESTS = 4;

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

@@ -0,0 +1,40 @@
+/**
+ * A signed thinking block is bound to the exact prefix of its request, and the
+ * prompt cache keys on that same prefix.
+ * A continuation must extend the conversation, never replay it under a new
+ * system prompt or tool set.
+ */
+import type { AgentSession } from "../auth/types.js";
+import { type AgentFinish, type RequestRefusal, type RunAgentOptions, type StepNameFormatter } from "./run-agent.js";
+import type { ToolMask } from "./tool-mask.js";
+import type { AgentDefinition, LoopMessage } from "./types.js";
+export interface ContinuationRequest {
+    /** Appended as a synthetic user message. */
+    readonly text: string;
+    /** The requests still declare every tool of the agent, even when masked. */
+    readonly mask: ToolMask;
+    /** The continuation runs no wrap-up at its cap. */
+    readonly maxRequests: number;
+    /** Prefixes each step name (`<namespace>:<name>`) so its cache key cannot match the conversation's own. */
+    readonly stepNamespace: string;
+    /**
+     * When set, metrics and token counts are attributed to this id instead of
+     * `agent.id`, through `forSubAgent`. Omitted, both stay the agent's own.
+     */
+    readonly accountingAgentId?: string;
+    /** A `provider` error with the status `400` or `413` ends the continuation with the finish reason `error`, and no throw. */
+    readonly endOnRequestRefusal?: boolean;
+}
+export interface ContinuationResult {
+    /** The new messages only, starting with the synthetic request. */
+    readonly messages: LoopMessage[];
+    readonly finish: AgentFinish;
+    /** The refusal that ended a continuation with `endOnRequestRefusal`. */
+    readonly refusal?: RequestRefusal;
+}
+export declare function namespacedStepNames(base: StepNameFormatter, namespace: string): StepNameFormatter;
+/**
+ * `agent` and `opts` must match the conversation's own, since each request
+ * extends its cached prefix. `conversation` itself is never changed.
+ */
+export declare function continueAgent(agent: AgentDefinition, conversation: readonly LoopMessage[], request: ContinuationRequest, session: AgentSession, opts: RunAgentOptions): Promise<ContinuationResult>;

package/dist/loop/continue-agent.js

@@ -0,0 +1,38 @@
+/**
+ * A signed thinking block is bound to the exact prefix of its request, and the
+ * prompt cache keys on that same prefix.
+ * A continuation must extend the conversation, never replay it under a new
+ * system prompt or tool set.
+ */
+import { forSubAgent } from "../auth/types.js";
+import { traceAgentRun } from "./genai-spans.js";
+import { DEFAULT_STEP_NAME_FORMATTER, isTurnRoot, openLoop, } from "./run-agent.js";
+export function namespacedStepNames(base, namespace) {
+    return {
+        llm: (i) => `${namespace}:${base.llm(i)}`,
+        tool: (name, id) => `${namespace}:${base.tool(name, id)}`,
+    };
+}
+/**
+ * `agent` and `opts` must match the conversation's own, since each request
+ * extends its cached prefix. `conversation` itself is never changed.
+ */
+export function continueAgent(agent, conversation, request, session, opts) {
+    const accountingAgentId = request.accountingAgentId;
+    const runSession = accountingAgentId === undefined ? session : forSubAgent(session, accountingAgentId);
+    const metricAgentId = accountingAgentId ?? agent.id;
+    return traceAgentRun(metricAgentId, runSession, isTurnRoot(opts), async () => {
+        const loop = openLoop(agent, conversation, runSession, opts, metricAgentId);
+        const outcome = await loop.runSegment({
+            mask: request.mask,
+            maxRequests: request.maxRequests,
+            stepNames: namespacedStepNames(opts.formatStepName ?? DEFAULT_STEP_NAME_FORMATTER, request.stepNamespace),
+            firstIndex: 0,
+            requestText: request.text,
+            ...(request.endOnRequestRefusal === true ? { endsOnRequestRefusal: true } : {}),
+        });
+        const result = outcome === "capped" ? await loop.endCapped() : outcome;
+        const refusal = outcome === "capped" ? undefined : outcome.refusal;
+        return { messages: result.messages.slice(conversation.length), finish: result.finish, ...(refusal === undefined ? {} : { refusal }) };
+    });
+}

package/dist/loop/metrics.d.ts

@@ -1,25 +1,29 @@
 /**
  * Agent-loop OTel metrics, exported through the global MeterProvider.
  *
- * Every `runAgent` completion records, keyed by `agent_id`:
+ * Each LLM call records its token counters when it completes. A durable step
+ * that a recovery replays returns its stored reply and skips the body, so a
+ * replay never double-counts a call.
+ *
+ * Cache-write tokens are billed at a premium and only pay off once something
+ * reads them. Each counter carries `agent_id`, plus `model` and `provider`
+ * when the response reports them. Session provenance is not a label: agents
+ * that share one root provenance also share one series. Providers do not
+ * agree on whether `outputTokens` includes the reasoning tokens, so the
+ * reasoning counter keeps a `provider` label.
+ *
+ * Each `runAgent` completion also records, with the `agent_id` label only:
  *   - cortex.harness.agent.iterations — histogram of LLM iterations per run.
  *     A creeping distribution is a leading indicator of prompt drift.
- *   - cortex.harness.agent.cap_hits   — counter, incremented once per run
- *     that exhausted `maxIterations` and took the forced wrap-up path.
- *   - cortex.harness.agent.input_tokens / .output_tokens — counters, summed
- *     over every LLM call the run made (the wrap-up included).
- *   - cortex.harness.agent.cache_read_tokens  — counter, prefix tokens served
- *     from the prompt cache.
- *   - cortex.harness.agent.cache_write_tokens — counter, prefix tokens written
- *     into it (billed at a premium; only pays off once something reads it).
+ *   - cortex.harness.agent.cap_hits — counter, incremented once per run that
+ *     exhausted `maxIterations` and took the forced wrap-up path.
  *
  * The two cache counters are what make prompt caching *observable*: the hit
  * rate for an agent type is `cache_read_tokens / input_tokens` (the harness's
  * `inputTokens` is the total billed prefix, cache reads included). A flat-zero
  * `cache_read_tokens` against a non-zero `cache_write_tokens` means every write
  * is being thrown away — either a cache defeater is shifting the prefix (see
- * `providers/prompt-cache.ts`) or the endpoint ignores cache directives
- * outright, as the Claude Max OAuth path does.
+ * `providers/prompt-cache.ts`) or the endpoint ignores cache directives.
  *
  * Token counters are recorded only from what a provider actually reports; a
  * provider that reports no usage contributes nothing rather than zero.
@@ -29,16 +33,11 @@
  * exporter from `harness/lib/otel.ts`; tests: an in-memory reader).
  */
 import { type TokenUsageRollup } from "../contracts/usage.js";
-import type { ChatUsage } from "../providers/types.js";
+import type { ChatResponse, ChatUsage } from "../providers/types.js";
 /**
- * Token usage summed over every LLM call one `runAgent` made. Each field stays
- * `undefined` until some call actually reports it, so "the provider told us
- * nothing" never masquerades as a measured zero.
- *
- * The fold is wider than the instruments: `reasoningTokens` is carried for the
- * usage records and the finish rollups, and deliberately has no OTel counter —
- * whether a provider counts reasoning inside `outputTokens` varies, so a
- * cross-agent counter would sum figures that do not mean the same thing.
+ * Token usage summed over LLM calls, either one `runAgent` run or a whole
+ * turn. A field stays `undefined` until a call reports it, so an unreported
+ * field never masquerades as a measured zero.
  */
 export interface AgentRunUsage {
     inputTokens?: number;
@@ -60,15 +59,24 @@ export declare function addChatUsage(total: AgentRunUsage, usage: ChatUsage | un
  * at either end is how the two would come to disagree.
  */
 export declare function hasReportedUsage(usage: AgentRunUsage | ChatUsage | TokenUsageRollup | undefined): boolean;
+/**
+ * Maps a step's response to grow its token counters. Use inside the step
+ * body, `provider.chat(...).map(countChatTokens(agentId))`. A call that gives
+ * `err` counts nothing.
+ */
+export declare function countChatTokens(agentId: string): (response: ChatResponse) => ChatResponse;
+export declare function recordChatCall(call: {
+    readonly agentId: string;
+    readonly response: ChatResponse;
+}): void;
 /** Record one completed `runAgent` invocation. */
 export declare function recordAgentRun(run: {
     readonly agentId: string;
     readonly iterations: number;
     readonly cappedOut: boolean;
-    readonly usage?: AgentRunUsage;
 }): void;
 /**
- * Drop the memoized instruments so the next `recordAgentRun` rebinds to a
+ * Drop the memoized instruments so the next record rebinds to a
  * freshly-registered `MeterProvider`. Test-only — production registers its
  * provider once at startup.
  */