@inflexa-ai/harness 0.1.1 → 0.2.0

package/dist/execution/ephemeral-runner.d.ts

@@ -72,6 +72,19 @@ export interface EphemeralResult {
  * so the `run_ephemeral` tool can dispatch via `DBOS.startWorkflow`.
  */
 export declare function registerEphemeralWorkflow(deps: EphemeralDeps): (input: EphemeralWorkflowInput) => Promise<EphemeralResult>;
+/**
+ * The executor's seed: its workspace frame, then the caller's ask.
+ *
+ * An ephemeral run is not scheduled by `executeAnalysis`, so no step briefing is
+ * composed for it — and the sandbox system prompt names no paths (it is static
+ * per agent type, so the provider's prompt cache can reuse it). The analysis
+ * root would otherwise reach the agent nowhere: `run_ephemeral`'s `prompt` is
+ * free text authored by the conversation agent.
+ *
+ * The frame differs from a step's, so this does not reuse `renderWorkspace`:
+ * there is no writable directory to name. The read-only tree IS the cwd.
+ */
+export declare function ephemeralSeed(analysisId: string, prompt: string): string;
 /**
  * Run the ephemeral-executor agent against a fresh read-only sandbox.
  * Throws on sandbox start failure; otherwise returns the agent's final

package/dist/execution/ephemeral-runner.js

@@ -51,6 +51,28 @@ const EPHEMERAL_SANDBOX_RESOURCES = { cpu: 4, memoryGb: 8 };
 export function registerEphemeralWorkflow(deps) {
     return DBOS.registerWorkflow((input) => runEphemeralBody(input, deps), { name: "ephemeral" });
 }
+/**
+ * The executor's seed: its workspace frame, then the caller's ask.
+ *
+ * An ephemeral run is not scheduled by `executeAnalysis`, so no step briefing is
+ * composed for it — and the sandbox system prompt names no paths (it is static
+ * per agent type, so the provider's prompt cache can reuse it). The analysis
+ * root would otherwise reach the agent nowhere: `run_ephemeral`'s `prompt` is
+ * free text authored by the conversation agent.
+ *
+ * The frame differs from a step's, so this does not reuse `renderWorkspace`:
+ * there is no writable directory to name. The read-only tree IS the cwd.
+ */
+export function ephemeralSeed(analysisId, prompt) {
+    const root = `/${analysisId}`;
+    return [
+        "## Workspace",
+        `- Analysis root (read-only): \`${root}\` — inputs at \`${root}/data/inputs/\`, prior runs at \`${root}/runs/\`.`,
+        `- The analysis root is also your cwd, and what relative paths resolve against. The sandbox is read-only: there is nowhere to write, so return every result inline.`,
+        "",
+        prompt,
+    ].join("\n");
+}
 /**
  * Run the ephemeral-executor agent against a fresh read-only sandbox.
  * Throws on sandbox start failure; otherwise returns the agent's final
@@ -116,7 +138,7 @@ export async function runEphemeralBody(input, deps) {
         const agentDef = createEphemeralExecutorAgent(sandboxAgentDeps);
         const agent = input.maxIterations !== undefined ? { ...agentDef, maxIterations: input.maxIterations } : agentDef;
         const signal = new AbortController().signal;
-        const { messages: finalMessages } = await runAgent(agent, [{ role: "user", content: input.prompt }], childSession, {
+        const { messages: finalMessages } = await runAgent(agent, [{ role: "user", content: ephemeralSeed(analysisId, input.prompt) }], childSession, {
             provider: deps.provider,
             signal,
             emit: () => { },

package/dist/execution/run-synthesis.js

@@ -25,10 +25,12 @@ import { z } from "zod";
 import { writeFileWithinRoot } from "../lib/fs-helpers.js";
 import { RunSynthesisSchema } from "../schemas/run-synthesis.js";
 import { synthesisAgentPrompt } from "../prompts/synthesis-agent.js";
+import { composeSystemPrompt } from "../agents/system-prompt.js";
 import { runDir } from "../workspace/paths.js";
 import { runToTerminal } from "../loop/run-to-terminal.js";
 import { passthroughStep } from "../loop/run-step.js";
 import { defineTool } from "../tools/define-tool.js";
+import { createReportBlockerToolFor } from "../tools/sandbox/report-blocker.js";
 import { createLiteratureReviewerTool } from "../tools/research/literature-reviewer.js";
 // ── Agent identity / budgets ────────────────────────────────────────
 const AGENT_ID = "run-synthesizer";
@@ -125,13 +127,14 @@ function fullyValidate(candidate, ctx) {
 function buildSubmitTool(holder, ctx) {
     return defineTool({
         id: "submit_synthesis",
-        description: "Submit the final synthesis. Re-validates payload against the schema " +
-            "and semantic checks (stepId refs, theme→finding refs, keyReferences " +
-            "PMIDs cited, numeric PMIDs). On success returns {accepted: true} — " +
-            "STOP after this. On rejection returns {accepted: false, issues} — " +
-            "fix the specific fields at each issue path and call again, or switch " +
-            "to report_blocker if the synthesis cannot be made valid.",
-        inputSchema: z.object({ synthesis: z.unknown() }),
+        description: "Submit the final synthesis. Re-validates the payload against the " +
+            "semantic checks the arg schema cannot express (stepId refs, " +
+            "theme→finding refs, keyReferences PMIDs cited, numeric PMIDs). On " +
+            "success returns {accepted: true} — STOP after this. On rejection " +
+            "returns {accepted: false, issues} — fix the specific fields at each " +
+            "issue path and call again, or switch to report_blocker if the " +
+            "synthesis cannot be made valid.",
+        inputSchema: z.object({ synthesis: RunSynthesisSchema }),
         execute: async (input) => {
             if (holder.outcome !== null) {
                 return ok({
@@ -155,18 +158,16 @@ function buildSubmitTool(holder, ctx) {
     });
 }
 function buildBlockerTool(holder) {
-    return defineTool({
-        id: "report_blocker",
-        description: "Terminal. Use when the run produced no synthesizable content (all " +
-            "summaries empty, contradictory to the point of incoherence, or no " +
-            "findings worth surfacing). Pass a short reason. Stop after calling.",
-        inputSchema: z.object({ reason: z.string().min(1) }),
-        execute: async (input) => {
-            if (holder.outcome === null) {
-                holder.outcome = { kind: "blocker", reason: input.reason };
-            }
-            return ok({ recorded: true });
+    return createReportBlockerToolFor({
+        record: (outcome) => {
+            if (holder.outcome === null)
+                holder.outcome = outcome;
         },
+        blockedWhen: "Ends run synthesis with no synthesis written. Use it when the run " +
+            "produced no synthesizable content (all step summaries empty, " +
+            "contradictory to the point of incoherence, or no findings worth " +
+            "surfacing) — not as an escape from a synthesis you could fix and " +
+            "submit.",
     });
 }
 /**
@@ -207,7 +208,7 @@ export async function generateRunSynthesis(input) {
     const tools = [submitTool, blockerTool, reviewer];
     const agent = {
         id: AGENT_ID,
-        systemPrompt: synthesisAgentPrompt,
+        systemPrompt: composeSystemPrompt(synthesisAgentPrompt),
         model: input.model,
         tools,
         maxIterations: SYNTHESIZER_MAX_ITERATIONS,

package/dist/execution/step-summary.js

@@ -28,6 +28,7 @@ import { forSubAgent } from "../auth/types.js";
 import { finalText, runAgent } from "../loop/run-agent.js";
 import { passthroughStep } from "../loop/run-step.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";
@@ -72,7 +73,7 @@ export async function generateStepSummary(opts) {
     const userPrompt = stepSummaryPrompt(opts.artifactPaths.join("\n"));
     const writer = {
         id: SUMMARY_AGENT_ID,
-        systemPrompt: SYSTEM_PROMPT,
+        systemPrompt: composeSystemPrompt(SYSTEM_PROMPT),
         model: opts.modelId,
         tools: [createReadFileTool(opts.workspaceFs, opts.workingDir)],
         maxIterations: opts.maxIterations ?? DEFAULT_MAX_ITERATIONS,

package/dist/index.d.ts

@@ -39,7 +39,8 @@ export { createConfiguredAiSdkProvider } from "./providers/ai-sdk.js";
 export type { AiSdkProviderConfig, ConfiguredAiSdkProviderDeps } 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, ModelMessage } from "./providers/types.js";
+export type { AgentChat, ChatProvider, EmbeddingProvider, ChatRequest, ChatResponse, ChatStreamEvent, ChatUsage, ModelMessage, PromptCachePolicy, } from "./providers/types.js";
+export { DEFAULT_PROMPT_CACHE, promptCacheProviderOptions } from "./providers/prompt-cache.js";
 export { toProviderError, isProviderError } from "./providers/errors.js";
 export type { ProviderError } from "./providers/errors.js";
 export { createStreamingChat } from "./providers/streaming-chat.js";
@@ -94,7 +95,6 @@ export type { PlanStep } from "./workflows/execute-analysis-scheduler.js";
 export { validatePlan } from "./schemas/validate-plan.js";
 export type { ValidatePlanOptions } from "./schemas/validate-plan.js";
 export type { ValidationResult } from "./schemas/validate-plan.js";
-export { renderStepPrompt } from "./schemas/render-step-prompt.js";
 export { upsertPlan, loadPlan } from "./state/plans.js";
 export type { UpsertPlanInput } from "./state/plans.js";
 export { insertRun, queryActiveRun, updateRunStatus, queryRun, queryRunsByAnalysis, RunDedupCollisionError } from "./state/runs.js";
@@ -102,6 +102,10 @@ export type { InsertRunInput } from "./state/runs.js";
 export { queryStepsByRun } from "./state/step-executions.js";
 export type { CortexRunRow, StepExecutionRow, RunStatus } from "./state/schema.js";
 export type { DbError } from "./lib/db-result.js";
+export { REFERENCE_DATA_CATALOG, REFERENCE_DATA_CATALOG_VERSION, ReferenceArtifactPathSchema, ReferenceArtifactSchema, ReferenceDataCatalogSchema, ReferenceDatasetSchema, ReferenceSha256Schema, UnknownReferenceDatasetError, referenceArtifactKey, resolveReferenceInstallPlan, } from "./reference-data/catalog.js";
+export type { ReferenceArtifact, ReferenceDataCatalog, ReferenceDataset, ReferenceInstallPlan, ReferenceInstallPlanDataset, ReferenceIntegrity, } from "./reference-data/catalog.js";
+export { REFERENCE_INSTALL_RECEIPT_VERSION, ReferenceInstallReceiptSchema, parseReferenceInstallReceipt } from "./reference-data/receipt.js";
+export type { ReferenceInstallReceipt, ReferenceReceiptArtifact } from "./reference-data/receipt.js";
 export { queryActiveSandboxes } from "./state/active-sandboxes.js";
 export { runStepDir } from "./workspace/paths.js";
 export { registerSandboxReaper } from "./sandbox/reaper.js";

package/dist/index.js

@@ -43,6 +43,14 @@ export { createAnthropicProvider } from "./providers/anthropic.js";
 // above is a convenience over this union's `anthropic` arm.
 export { createConfiguredAiSdkProvider } 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.
+export { DEFAULT_PROMPT_CACHE, promptCacheProviderOptions } from "./providers/prompt-cache.js";
 // Provider error channel. `ProviderError` is the value `chat`/`embed` fail
 // with; `toProviderError` is its sole constructor. Exposed so an embedder
 // realizing its own `ChatProvider`/`EmbeddingProvider` fails with the exact
@@ -129,20 +137,26 @@ export { registerSandboxStep } from "./workflows/sandbox-step.js";
 // `SandboxAgentDeps`, then selects the per-step agent by id from this record;
 // `SANDBOX_AGENT_META` is the planner-facing meta the same ids key.
 export { createSandboxAgents, SANDBOX_AGENT_META } from "./agents/sandbox/index.js";
-// Plan schema, structural validation, and per-step prompt rendering — the gates
-// a plan passes before it can trigger a run, plus the prompt each step's agent
-// receives. `PlanStep` is the minimal `{ id, depends_on }` element type that
+// Plan schema and structural validation — the gates a plan passes before it can
+// trigger a run. `PlanStep` is the minimal `{ id, depends_on }` element type that
 // `ExecuteAnalysisInput.steps` is typed against; a parsed `AnalysisPlan`'s
-// richer `AnalysisStep[]` is assignable to it.
+// richer `AnalysisStep[]` is assignable to it, and is also what
+// `ExecuteAnalysisInput.planStepById` carries. There is no prompt renderer here:
+// an embedder supplies the plan's step DATA and the harness composes each step's
+// seed at dispatch, when the step's dependencies have actually produced something.
 export { AnalysisPlanSchema } from "./schemas/workflow-state.js";
 export { validatePlan } from "./schemas/validate-plan.js";
-export { renderStepPrompt } from "./schemas/render-step-prompt.js";
 // Plan + run + step ledgers around a trigger. `upsertPlan` takes a
 // caller-derived id and inserts-if-absent (the deterministic-id intake path);
 // the run-state calls mirror the chat trigger's reserve → dedup → status flow.
 export { upsertPlan, loadPlan } from "./state/plans.js";
 export { insertRun, queryActiveRun, updateRunStatus, queryRun, queryRunsByAnalysis, RunDedupCollisionError } from "./state/runs.js";
 export { queryStepsByRun } from "./state/step-executions.js";
+// Host-neutral reference-data catalog and shared installation receipts. Each
+// artifact names the third-party upstream it is fetched from; embedders own all
+// transfer/storage behavior but never choose a different source.
+export { REFERENCE_DATA_CATALOG, REFERENCE_DATA_CATALOG_VERSION, ReferenceArtifactPathSchema, ReferenceArtifactSchema, ReferenceDataCatalogSchema, ReferenceDatasetSchema, ReferenceSha256Schema, UnknownReferenceDatasetError, referenceArtifactKey, resolveReferenceInstallPlan, } from "./reference-data/catalog.js";
+export { REFERENCE_INSTALL_RECEIPT_VERSION, ReferenceInstallReceiptSchema, parseReferenceInstallReceipt } from "./reference-data/receipt.js";
 // Backs `WatchdogDeps.queryActiveSandboxes` when the embedder wires the watchdog.
 export { queryActiveSandboxes } from "./state/active-sandboxes.js";
 // Workspace-tree path convention — the root-relative step directory each

package/dist/loop/__fixtures__/scripted-provider.d.ts

@@ -1,4 +1,4 @@
-import type { ChatResponse, ChatProvider, ChatRequest } from "../../providers/types.js";
+import type { ChatResponse, ChatProvider, ChatRequest, ChatUsage } from "../../providers/types.js";
 import type { AgentSession as Session } from "../../auth/types.js";
 export type TextBlock = {
     type: "text";
@@ -20,7 +20,7 @@ export type ToolUseBlock = {
     input: unknown;
 };
 export type ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock;
-export declare function makeMessage(content: ContentBlock[], finishReason: ChatResponse["finishReason"] | "tool_use" | "end_turn" | "max_tokens" | "refusal"): ChatResponse;
+export declare function makeMessage(content: ContentBlock[], finishReason: ChatResponse["finishReason"] | "tool_use" | "end_turn" | "max_tokens" | "refusal", usage?: ChatUsage): ChatResponse;
 export declare function textBlock(text: string): TextBlock;
 export declare function thinkingBlock(thinking: string, signature: string): ThinkingBlock;
 export declare function toolUseBlock(id: string, name: string, input: unknown): ToolUseBlock;

package/dist/loop/__fixtures__/scripted-provider.js

@@ -13,10 +13,11 @@ function mapFinishReason(finishReason) {
             return finishReason;
     }
 }
-export function makeMessage(content, finishReason) {
+export function makeMessage(content, finishReason, usage) {
     return {
         message: { role: "assistant", content },
         finishReason: mapFinishReason(finishReason),
+        usage,
     };
 }
 export function textBlock(text) {

package/dist/loop/metrics.d.ts

@@ -1,21 +1,53 @@
 /**
  * Agent-loop OTel metrics → Middleware.io.
  *
- * Every `runAgent` completion records two signals:
+ * Every `runAgent` completion records, keyed by `agent_id`:
  *   - 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).
+ *
+ * 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.
+ *
+ * Token counters are recorded only from what a provider actually reports; a
+ * provider that reports no usage contributes nothing rather than zero.
  *
  * Instruments are created lazily on first use so the loop binds to whatever
  * `MeterProvider` is registered globally at runtime (production: the OTLP
  * exporter from `harness/lib/otel.ts`; tests: an in-memory reader).
  */
+import type { 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.
+ */
+export interface AgentRunUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheCreationInputTokens?: number;
+    cacheReadInputTokens?: number;
+}
+/** Fold one call's reported usage into a run's running total. */
+export declare function addChatUsage(total: AgentRunUsage, usage: ChatUsage | undefined): 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

package/dist/loop/metrics.js

@@ -1,11 +1,28 @@
 /**
  * Agent-loop OTel metrics → Middleware.io.
  *
- * Every `runAgent` completion records two signals:
+ * Every `runAgent` completion records, keyed by `agent_id`:
  *   - 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).
+ *
+ * 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.
+ *
+ * Token counters are recorded only from what a provider actually reports; a
+ * provider that reports no usage contributes nothing rather than zero.
  *
  * Instruments are created lazily on first use so the loop binds to whatever
  * `MeterProvider` is registered globally at runtime (production: the OTLP
@@ -24,17 +41,54 @@ function getInstruments() {
             capHits: meter.createCounter("cortex.harness.agent.cap_hits", {
                 description: "runAgent completions that exhausted maxIterations and took the " + "forced tool-less wrap-up path",
             }),
+            inputTokens: meter.createCounter("cortex.harness.agent.input_tokens", {
+                description: "Input tokens billed across every LLM call in a runAgent completion, cache reads included",
+                unit: "{token}",
+            }),
+            outputTokens: meter.createCounter("cortex.harness.agent.output_tokens", {
+                description: "Output tokens generated across every LLM call in a runAgent completion",
+                unit: "{token}",
+            }),
+            cacheReadTokens: meter.createCounter("cortex.harness.agent.cache_read_tokens", {
+                description: "Prompt-prefix tokens served from the provider's prompt cache",
+                unit: "{token}",
+            }),
+            cacheWriteTokens: meter.createCounter("cortex.harness.agent.cache_write_tokens", {
+                description: "Prompt-prefix tokens written into the provider's prompt cache",
+                unit: "{token}",
+            }),
         };
     }
     return instruments;
 }
+/** Fold one call's reported usage into a run's running total. */
+export function addChatUsage(total, usage) {
+    if (usage === undefined)
+        return;
+    for (const key of ["inputTokens", "outputTokens", "cacheCreationInputTokens", "cacheReadInputTokens"]) {
+        const value = usage[key];
+        if (value !== undefined)
+            total[key] = (total[key] ?? 0) + value;
+    }
+}
 /** Record one completed `runAgent` invocation. */
 export function recordAgentRun(run) {
-    const { iterations, capHits } = getInstruments();
+    const { iterations, capHits, inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens } = getInstruments();
     const attributes = { agent_id: run.agentId };
     iterations.record(run.iterations, attributes);
     if (run.cappedOut)
         capHits.add(1, attributes);
+    const usage = run.usage;
+    if (usage === undefined)
+        return;
+    if (usage.inputTokens !== undefined)
+        inputTokens.add(usage.inputTokens, attributes);
+    if (usage.outputTokens !== undefined)
+        outputTokens.add(usage.outputTokens, attributes);
+    if (usage.cacheReadInputTokens !== undefined)
+        cacheReadTokens.add(usage.cacheReadInputTokens, attributes);
+    if (usage.cacheCreationInputTokens !== undefined)
+        cacheWriteTokens.add(usage.cacheCreationInputTokens, attributes);
 }
 /**
  * Drop the memoized instruments so the next `recordAgentRun` rebinds to a

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

@@ -1,6 +1,6 @@
 import { type FinishReason } from "ai";
 import type { AgentSession } from "../auth/types.js";
-import type { AgentChat } from "../providers/types.js";
+import type { AgentChat, PromptCachePolicy } from "../providers/types.js";
 import type { AgentDefinition, EmitFn, LoopMessage, RunStep } from "./types.js";
 export interface AgentFinish {
     readonly reason: FinishReason | "max_iterations";
@@ -23,6 +23,18 @@ export interface RunAgentOptions {
     readonly runStep: RunStep;
     readonly formatStepName?: StepNameFormatter;
     readonly isFatalLoopError?: (err: unknown) => 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
+     * it breaks even by the second iteration. A host whose endpoint ignores or
+     * charges badly for cache directives passes `"off"`.
+     *
+     * The policy lives here, on the run, rather than on the provider, precisely
+     * so it applies to loops and *not* to the one-shot LLM calls made elsewhere
+     * (report generation, target-assessment steps): those would pay the
+     * cache-write premium for a cache nothing ever reads back.
+     */
+    readonly promptCache?: PromptCachePolicy;
 }
 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,8 +1,9 @@
 import { jsonSchema, tool as aiTool } from "ai";
 import { classifyProviderError } from "../providers/errors.js";
+import { DEFAULT_PROMPT_CACHE, promptCacheProviderOptions } from "../providers/prompt-cache.js";
 import { resultStep } from "./run-step.js";
 import { isToolError } from "../tools/define-tool.js";
-import { recordAgentRun } from "./metrics.js";
+import { addChatUsage, recordAgentRun } from "./metrics.js";
 const TRUNCATED_PROSE_STEER = "Your previous reply was cut off at the output-token limit; continue concisely, or finish via your terminal tool.";
 const TRUNCATED_TOOL_USE_ERROR = "Your previous tool call was cut off at the output-token limit and was not executed. Retry with a smaller payload, writing in incremental pieces.";
 export const DEFAULT_STEP_NAME_FORMATTER = {
@@ -37,14 +38,21 @@ export async function runAgent(agent, initial, session, opts) {
     });
     let iterations = 0;
     let truncationRecoveries = 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 = {};
     for (let i = 0; i < agent.maxIterations; i++) {
         iterations = i + 1;
         const request = {
             system: agent.systemPrompt,
             messages,
             tools: toolDefs,
+            providerOptions,
         };
         const reply = await resultStep(runStep)(formatStepName.llm(i), () => provider.chat(request, session, signal));
+        addChatUsage(usage, reply.usage);
         messages.push(reply.message);
         const toolCalls = toolCallParts(reply.message);
         if (reply.finishReason === "length") {
@@ -76,7 +84,7 @@ export async function runAgent(agent, initial, session, opts) {
         }
         if (reply.finishReason !== "tool-calls") {
             await emit({ type: "iteration", source, index: i, final: true });
-            recordAgentRun({ agentId: agent.id, iterations, cappedOut: false });
+            recordAgentRun({ agentId: agent.id, iterations, cappedOut: false, usage });
             return { messages, finish: { reason: reply.finishReason, cappedOut: false, truncationRecoveries } };
         }
         await emit({ type: "iteration", source, index: i, final: false });
@@ -96,10 +104,17 @@ export async function runAgent(agent, initial, session, opts) {
         }
         messages.push({ role: "tool", content: results });
     }
-    const wrapUp = await resultStep(runStep)(formatStepName.llm(agent.maxIterations), () => provider.chat({ system: agent.systemPrompt, messages, tools: {}, toolChoice: "none" }, session, signal));
+    // Cache defeater (known; not fixed here). Emptying the tool set changes the
+    // very front of the request prefix — tool definitions are cached ahead of
+    // system and history — so this call reads *nothing* back from the cache and
+    // rewrites the whole prefix from scratch. It still carries the cache options
+    // because it is the one call whose write is pure waste, and the
+    // cache_write_tokens counter is what makes that waste visible.
+    const wrapUp = await resultStep(runStep)(formatStepName.llm(agent.maxIterations), () => provider.chat({ system: agent.systemPrompt, messages, tools: {}, toolChoice: "none", providerOptions }, session, signal));
+    addChatUsage(usage, wrapUp.usage);
     messages.push(wrapUp.message);
     await emit({ type: "iteration", source, index: agent.maxIterations, final: true });
-    recordAgentRun({ agentId: agent.id, iterations, cappedOut: true });
+    recordAgentRun({ agentId: agent.id, iterations, cappedOut: true, usage });
     return { messages, finish: { reason: "max_iterations", cappedOut: true, truncationRecoveries } };
 }
 function toolCallParts(message) {

package/dist/memory/card-builders.d.ts

@@ -63,7 +63,14 @@ export declare function buildRunCardData(pool: Pool, opts: {
     runId?: string;
 }): ResultAsync<RunCardData | null, DbError>;
 /** Build the `data-presentation` payload from the `show_user` tool input.
- *  Self-contained — the card lives entirely in the input. */
+ *  Self-contained — the card lives entirely in the input.
+ *
+ *  An `echart` spec passes through `normalizeEchartSpec` HERE rather than in the tool body, because
+ *  this builder is the single construction site of a `PresentationContent`: normalizing in
+ *  `show_user.execute` alone would leave the reconstruct-on-read path (which sees only the persisted
+ *  raw `tool_use` input) rendering the un-normalized chart, breaking the byte-identical live/replay
+ *  card this module exists to guarantee. The `id` stays keyed to the raw input, which both paths
+ *  hold identically, so normalization cannot move a card's identity. */
 export declare function buildPresentationCardData(input: Record<string, unknown>): PresentationCardData | null;
 /** Max files a `show_file` group may reference; multiple render as a gallery. */
 export declare const MAX_FILES = 10;

package/dist/memory/card-builders.js

@@ -23,9 +23,13 @@ import { tryQuery } from "../lib/db-result.js";
 import { tryFs } from "../lib/fs-result.js";
 import { AnalysisPlanSchema } from "../schemas/workflow-state.js";
 import { loadPlan } from "../state/index.js";
+import { normalizeEchartSpec } from "../tools/display/normalize-echart-spec.js";
 import { validatePath } from "../tools/lib/path-validation.js";
 import { latestPreviewVersion, previewDir, PREVIEWS_ROOT } from "../workspace/paths.js";
 const PREVIEW_META_FILE = "preview-meta.json";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 /** Deterministic presentation id — must match `show_user`'s. */
 function presentationId(input) {
     const hash = createHash("sha256")
@@ -101,15 +105,28 @@ export function buildRunCardData(pool, opts) {
     });
 }
 /** Build the `data-presentation` payload from the `show_user` tool input.
- *  Self-contained — the card lives entirely in the input. */
+ *  Self-contained — the card lives entirely in the input.
+ *
+ *  An `echart` spec passes through `normalizeEchartSpec` HERE rather than in the tool body, because
+ *  this builder is the single construction site of a `PresentationContent`: normalizing in
+ *  `show_user.execute` alone would leave the reconstruct-on-read path (which sees only the persisted
+ *  raw `tool_use` input) rendering the un-normalized chart, breaking the byte-identical live/replay
+ *  card this module exists to guarantee. The `id` stays keyed to the raw input, which both paths
+ *  hold identically, so normalization cannot move a card's identity. */
 export function buildPresentationCardData(input) {
     const { kind, title, ...rest } = input;
     if (typeof kind !== "string")
         return null;
+    const cardTitle = typeof title === "string" ? title : undefined;
+    const content = kind === "echart" && isRecord(rest.spec)
+        ? { kind, ...rest, spec: normalizeEchartSpec(rest.spec, { title: cardTitle }) }
+        : // Every other kind (and an echart the model called without a `spec`) is carried through
+            // untouched — there is no layout to normalize, and no spec to invent.
+            { kind, ...rest };
     return {
         id: presentationId(input),
-        ...(typeof title === "string" ? { title } : {}),
-        content: { kind, ...rest },
+        ...(cardTitle !== undefined ? { title: cardTitle } : {}),
+        content,
     };
 }
 /** Max files a `show_file` group may reference; multiple render as a gallery. */

package/dist/memory/reconstruct-cards.js

@@ -19,9 +19,10 @@ export function createCardResolver(pool, analysisId, workspaceRoot) {
         if (block.type !== "tool_use")
             return null;
         const input = (block.input ?? {});
-        // The harness tool id is `iterate_report`; legacy transcripts carry
-        // `iterateReport` — accept both.
-        if (block.name === "iterate_report" || block.name === "iterateReport") {
+        // The report tool is `submit_report`; legacy transcripts carry the
+        // former ids `iterate_report` / `iterateReport` — accept all three. The
+        // brief-carrying field is still `report`, so the card reads identically.
+        if (block.name === "submit_report" || block.name === "iterate_report" || block.name === "iterateReport") {
             const report = (input.report ?? null);
             const card = await buildPreviewCardData(workspaceRoot, {
                 previewId: typeof input.previewId === "string" ? input.previewId : undefined,

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

@@ -54,8 +54,11 @@ export interface ThreadHistory {
      */
     appendTurn(threadId: string, messages: readonly ModelMessage[]): ResultAsync<void, DbError>;
     /**
-     * Return the most recent messages whose cumulative `tokens` fit
-     * `tokenBudget`, oldest-first, snapped to a valid AI SDK model-message sequence.
+     * Return a recent-turns window that fits `tokenBudget`, oldest-first,
+     * snapped to a valid AI SDK model-message sequence. The window START advances
+     * in whole `EVICTION_BLOCK_TURNS` blocks (see the constant) so the prompt-cache
+     * prefix stays byte-stable across appends; the window may therefore carry a
+     * little less than the budget would strictly allow, but never more.
      */
     loadRecent(threadId: string, tokenBudget: number): ResultAsync<ModelMessage[], DbError>;
     /**
@@ -72,6 +75,28 @@ export interface ThreadHistory {
  * freshly-registered `MeterProvider`. Test-only.
  */
 export declare function __resetThreadHistoryMetricsForTest(): void;
+/**
+ * Chunked-eviction block size, in whole turns — the granularity at which
+ * `loadRecent`'s retained window may advance its START turn.
+ *
+ * `loadRecent` snaps its eviction count UP to a multiple of this block, so the
+ * window's first turn — hence `messages[0]` and the whole tools+system+history
+ * prompt-cache prefix — stays byte-identical across a run of appends and shifts
+ * only once per block instead of once per turn. That single shift is the only
+ * message-cache miss the block costs.
+ *
+ * The block is at once (a) the cache-miss cadence — one prefix shift per
+ * `EVICTION_BLOCK_TURNS` appends once a thread is over budget — and (b) the most
+ * extra context ever sacrificed: snapping up drops up to `EVICTION_BLOCK_TURNS -
+ * 1` oldest turns the budget alone would have kept, trading a little history for
+ * a still prefix. 4 holds the prefix for ~4 turns at a cost of at most 3 turns of
+ * headroom — negligible against a ~120k-token budget that spans far more turns,
+ * while cutting cache misses on a long thread roughly fourfold. A turn-count
+ * block (not a token block) is deliberate: a cache miss is triggered by the START
+ * turn moving, a per-turn event, so counting in turns makes the miss cadence
+ * exact and independent of how large any individual turn is.
+ */
+export declare const EVICTION_BLOCK_TURNS = 4;
 /**
  * Create a `ThreadHistory` bound to a Postgres pool — a factory closure
  * capturing `pool` (dependency injection per the harness-durable-runtime spec). The `messages` table is