@inflexa-ai/harness 0.1.1 → 0.3.0

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

package/dist/memory/thread-history.js

@@ -79,6 +79,28 @@ function getInstruments() {
 export function __resetThreadHistoryMetricsForTest() {
     instruments = undefined;
 }
+/**
+ * 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 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
@@ -125,9 +147,22 @@ export function createThreadHistory(pool) {
             const turns = groupTurns(parsed, (row) => isGenuineUserStart(row.message));
             const turnTokens = turns.map((turn) => turn.reduce((sum, row) => sum + row.tokens, 0));
             const threadTotal = turnTokens.reduce((sum, n) => sum + n, 0);
-            // Walk turns newest-first, accumulating token cost. The most recent turn
-            // is always included — even if it alone exceeds the budget, a valid
-            // sequence beats an under-budget one. Older turns join while they fit.
+            // Chunked eviction holds the prompt-cache prefix still. The budget alone
+            // evicts the OLDEST turns newest-first, so the window START — the stable
+            // head of the tools+system+history cache prefix — advances by ~one turn
+            // per appended turn; every turn then ships a shifted `messages[0]` and
+            // rewrites the whole message cache instead of reading it back (watch
+            // `cortex.harness.agent.cache_read_tokens` collapse on long threads).
+            // Instead, take the budget-minimal eviction and snap it UP to a whole
+            // `EVICTION_BLOCK_TURNS` block: `evicted` stays constant while the minimum
+            // sits inside a block and jumps by a block when it crosses, so
+            // `messages[0]` is byte-identical for a block of appends (the cache reads
+            // survive) and shifts only once per block. Snapping UP retains a subset of
+            // the budget-minimal window, so the kept tokens never exceed `tokenBudget`.
+            //
+            // Budget-minimal fill: walk newest-first, always keeping the most recent
+            // turn (a valid over-budget single turn beats an under-budget cut), then
+            // add older turns while they fit.
             let included = 0;
             let cumulative = 0;
             for (let t = turns.length - 1; t >= 0; t--) {
@@ -136,13 +171,18 @@ export function createThreadHistory(pool) {
                 cumulative += turnTokens[t];
                 included++;
             }
-            const turnsEvicted = turns.length - included;
+            const minimalEvicted = turns.length - included;
+            // Snap the eviction count up to a block boundary, clamped below the last
+            // turn so the most recent turn always ships. Both terms of the min are
+            // >= `minimalEvicted`, so `turnsEvicted >= minimalEvicted`: the retained
+            // suffix is a subset of the budget-minimal one and stays within budget.
+            const turnsEvicted = turns.length === 0 ? 0 : Math.min(Math.ceil(minimalEvicted / EVICTION_BLOCK_TURNS) * EVICTION_BLOCK_TURNS, turns.length - 1);
             const { totalTokens, turnsEvicted: turnsEvictedHist } = getInstruments();
             const attributes = { eviction: turnsEvicted > 0 };
             totalTokens.record(threadTotal, attributes);
             turnsEvictedHist.record(turnsEvicted, attributes);
             return turns
-                .slice(turns.length - included)
+                .slice(turnsEvicted)
                 .flat()
                 .map((row) => row.message);
         });

package/dist/memory/working-memory.d.ts

@@ -6,18 +6,48 @@
  * to Markdown only when injected (see the harness-thread-store spec).
  *
  * Four sections. `goal`, `constraints`, `hypotheses` are analysis-flat;
- * `findings` is run-scoped, keyed by `runId`, so a finding stays attributable
- * to the run that produced it. There is deliberately no `context` section —
+ * `findings` is stored keyed by `runId`, so a finding stays attributable to
+ * the run that produced it. There is deliberately no `context` section —
  * analysis context lives in `cortex_analysis_state.context` and is injected
  * separately by the chat route.
  *
  * `updateSection` is a section-addressable read-modify-write: the named
  * section is replaced or amended and the other three are left byte-identical.
+ *
+ * **Working memory is re-injected, in full, into the uncached tail of every
+ * turn** — so every stored character is re-paid on every later turn for the
+ * life of the analysis. Two consequences shape this module:
+ *
+ *  - **Every section is bounded at write time** (`WORKING_MEMORY_LIMITS`). An
+ *    over-cap write is *rejected* with a model-actionable message, never
+ *    silently truncated: the agent must shorten the text or retire a stale
+ *    entry. Every section — findings included — therefore supports
+ *    add/revise/retire, so memory can shrink as well as grow.
+ *  - **Memory holds references to runs, never run content.** A finding cites
+ *    the `runId` that produced it and renders as one line in a single flat
+ *    list; the run's detail stays retrievable via `inspect_run`.
  */
-import type { ResultAsync } from "neverthrow";
+import { type ResultAsync } from "neverthrow";
 import type { Pool } from "pg";
 import { z } from "zod";
 import { type DbError } from "../lib/db-result.js";
+/**
+ * The write-time bounds on working memory. `updateSection` enforces them, the
+ * `update_working_memory` input schema declares them to the model (importing
+ * these same numbers), and `renderWorkingMemory` uses them to bound its output.
+ */
+export declare const WORKING_MEMORY_LIMITS: {
+    /** Max characters in the goal. */
+    readonly goalChars: 500;
+    /** Max characters in one constraint / hypothesis / finding entry. */
+    readonly entryChars: 300;
+    /** Max constraint entries. */
+    readonly constraints: 20;
+    /** Max hypothesis entries. */
+    readonly hypotheses: 10;
+    /** Max finding entries, summed across every run. */
+    readonly findings: 30;
+};
 /** A binding rule — user-stated or agent-derived. The highest-value section. */
 export declare const constraintSchema: z.ZodObject<{
     id: z.ZodString;
@@ -43,6 +73,11 @@ export type Finding = z.infer<typeof findingSchema>;
 /**
  * The persisted `data` shape — one JSONB object per analysis. `findings` is
  * keyed by `runId`; an analysis with no recorded findings has an empty map.
+ *
+ * Deliberately unbounded: the caps are a *write-time* rule, not a read-time
+ * one. A row written before the caps existed must still `load` — so this
+ * schema validates shape only, and `renderWorkingMemory` bounds what an
+ * oversized row is allowed to cost.
  */
 export declare const workingMemorySchema: z.ZodObject<{
     goal: z.ZodString;
@@ -66,6 +101,20 @@ export declare const workingMemorySchema: z.ZodObject<{
 export type WorkingMemory = z.infer<typeof workingMemorySchema>;
 /** The shape `load` returns for an analysis with no working-memory row. */
 export declare function emptyWorkingMemory(): WorkingMemory;
+/**
+ * A refused write: a cap was hit, or an id addresses nothing. Not a storage
+ * failure — it is an expected outcome the *model* can correct, so `message` is
+ * written for the model and says what to do next (shorten this, retire that).
+ * The tool surfaces it as an `is_error` tool result; the row is untouched.
+ */
+export interface WorkingMemoryRejection {
+    readonly type: "working_memory_rejected";
+    readonly message: string;
+}
+/** `updateSection`'s error channel: a storage failure, or a refused write. */
+export type WorkingMemoryError = DbError | WorkingMemoryRejection;
+/** Narrow a `WorkingMemoryError` to the model-correctable branch. */
+export declare function isWorkingMemoryRejection(error: WorkingMemoryError): error is WorkingMemoryRejection;
 /**
  * A list-section amendment: append a new entry, revise an existing one's
  * text, or retire a stale one. `revise`/`retire` address an entry by the
@@ -95,6 +144,23 @@ export type ConstraintOp = {
     readonly op: "retire";
     readonly id: string;
 };
+/**
+ * As `ListOp`, but `add` also carries the `runId` the finding is attributed
+ * to. `revise`/`retire` address the finding by its own id — the run holding it
+ * is found from that id, so the agent never has to re-cite the run.
+ */
+export type FindingOp = {
+    readonly op: "add";
+    readonly runId: string;
+    readonly text: string;
+} | {
+    readonly op: "revise";
+    readonly id: string;
+    readonly text: string;
+} | {
+    readonly op: "retire";
+    readonly id: string;
+};
 /** The `value` argument of `updateSection`, keyed by the `section` name. */
 export interface SectionValue {
     readonly goal: {
@@ -102,10 +168,7 @@ export interface SectionValue {
     };
     readonly constraint: ConstraintOp;
     readonly hypothesis: ListOp;
-    readonly finding: {
-        readonly runId: string;
-        readonly text: string;
-    };
+    readonly finding: FindingOp;
 }
 export type Section = keyof SectionValue;
 /**
@@ -118,13 +181,33 @@ export interface WorkingMemoryStore {
     load(analysisId: string): ResultAsync<WorkingMemory, DbError>;
     /**
      * Atomically read-modify-write one section. The other three sections are
-     * left byte-identical; the row is upserted if absent.
+     * left byte-identical; the row is upserted if absent. A write that breaks a
+     * cap or addresses an unknown id is refused — `err(WorkingMemoryRejection)`,
+     * and the row is left exactly as it was.
      */
-    updateSection<S extends Section>(analysisId: string, section: S, value: SectionValue[S]): ResultAsync<void, DbError>;
+    updateSection<S extends Section>(analysisId: string, section: S, value: SectionValue[S]): ResultAsync<void, WorkingMemoryError>;
     /** Serialize working memory to a Markdown document for injection. */
     render(analysisId: string): ResultAsync<string, DbError>;
 }
-/** Serialize working memory to the Markdown document injected each turn. */
+/**
+ * Serialize working memory to the Markdown document injected each turn.
+ *
+ * Renders only what exists: an empty section is omitted entirely — no heading,
+ * no placeholder — and an entirely empty memory renders to the **empty
+ * string**, costing nothing. The chat route injects the render
+ * unconditionally, and the provider's outbound sanitizer drops a message whose
+ * content is `""` before the wire call (`providers/ai-sdk.ts`), so an empty
+ * memory reaches the model as no message at all.
+ *
+ * Findings render as ONE flat list, each line citing the run it came from —
+ * never a per-run heading block. Memory holds the reference; `inspect_run`
+ * holds the run.
+ *
+ * The output is bounded to `WORKING_MEMORY_LIMITS` no matter what the row
+ * holds. Writes are capped, so only a row written before the caps existed can
+ * exceed them — and it degrades to its newest entries rather than exploding
+ * the context window.
+ */
 export declare function renderWorkingMemory(wm: WorkingMemory): string;
 /**
  * Create a `WorkingMemoryStore` bound to a Postgres pool — a factory closure