@inflexa-ai/harness 0.39.2 → 0.40.0

package/dist/tools/read-tool-output.js

@@ -0,0 +1,130 @@
+/**
+ * `read_tool_output` — reads the kept text of a tool result that the loop cut, by a window or by a pattern.
+ * Each result stays under the cap of the loop, thus the loop never cuts a result of this tool.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { unwrapOrThrow } from "../lib/result.js";
+import { pairSafeIndex, READ_TOOL_OUTPUT_TOOL_ID, TOOL_RESULT_CAP } from "../loop/tool-output.js";
+import { defineTool } from "./define-tool.js";
+const DEFAULT_PAGE_CHARS = 8 * 1024;
+const MAX_PAGE_CHARS = 16 * 1024;
+const MAX_MATCHES = 20;
+const MATCH_CHARS_BEFORE = 150;
+const MATCH_CHARS_AFTER = 250;
+/** The loop JSON-escapes the text of a result, and an escape can make a text two to six times longer. */
+const RESULT_BUDGET = TOOL_RESULT_CAP - 512;
+const ReadToolOutputInputSchema = z.object({
+    ref: z.string().min(1).max(64).describe("The reference that the excerpt of a cut tool result gives, for example to_3f9a2c41b8d605e7a1c0."),
+    offset: z.number().int().min(0).optional().describe("The index of the first character of the window, from 0. Defaults to 0."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_PAGE_CHARS)
+        .optional()
+        .describe(`The count of characters of the window. A page defaults to ${DEFAULT_PAGE_CHARS}. A search with no limit reaches the end of the text.`),
+    pattern: z
+        .string()
+        .min(1)
+        .max(1024)
+        .optional()
+        .describe("A JavaScript regular expression. The result gives each match in the window with its offset and the text around it."),
+});
+/** The end of a window of `length` characters from `start`, off the middle of a surrogate pair, and past `start`. */
+function windowEnd(text, start, length) {
+    const end = Math.min(text.length, start + length);
+    const safe = pairSafeIndex(text, end, -1);
+    return safe > start ? safe : pairSafeIndex(text, end, 1);
+}
+function fits(result) {
+    return JSON.stringify(result).length <= RESULT_BUDGET;
+}
+function page(ref, text, start, limit) {
+    const at = (stoppedAt) => ({
+        status: "ok",
+        ref,
+        offset: start,
+        end: stoppedAt,
+        keptLength: text.length,
+        more: stoppedAt < text.length,
+        text: text.slice(start, stoppedAt),
+    });
+    let end = windowEnd(text, start, limit);
+    let result = at(end);
+    while (!fits(result)) {
+        end = windowEnd(text, start, Math.floor(((end - start) * 3) / 4));
+        result = at(end);
+    }
+    return result;
+}
+function search(ref, text, start, limit, pattern) {
+    let regex;
+    try {
+        regex = new RegExp(pattern, "g");
+    }
+    catch (err) {
+        return { status: "invalid_pattern", pattern, error: err instanceof Error ? err.message : String(err) };
+    }
+    const stop = limit === undefined ? text.length : windowEnd(text, start, limit);
+    const window = text.slice(start, stop);
+    const matches = [];
+    let end = stop;
+    for (let found = regex.exec(window); found !== null; found = regex.exec(window)) {
+        const offset = start + found.index;
+        // A match past the last one that the result can hold is where the next call continues.
+        if (matches.length === MAX_MATCHES) {
+            end = offset;
+            break;
+        }
+        const from = pairSafeIndex(text, Math.max(0, offset - MATCH_CHARS_BEFORE), 1);
+        const to = pairSafeIndex(text, Math.min(text.length, offset + MATCH_CHARS_AFTER), -1);
+        matches.push({ offset, text: text.slice(from, to) });
+        if (found[0].length === 0)
+            regex.lastIndex++;
+    }
+    if (matches.length === 0)
+        return { status: "no_matches", ref, pattern, offset: start, end };
+    const at = (stoppedAt) => ({
+        status: "matches",
+        ref,
+        pattern,
+        offset: start,
+        end: stoppedAt,
+        keptLength: text.length,
+        more: stoppedAt < text.length,
+        matches: [...matches],
+    });
+    let result = at(end);
+    while (!fits(result) && matches.length > 1) {
+        end = matches.pop().offset;
+        result = at(end);
+    }
+    return result;
+}
+export function createReadToolOutputTool(store) {
+    return defineTool({
+        id: READ_TOOL_OUTPUT_TOOL_ID,
+        description: "Read the full text of a tool result that came back as an excerpt. A result longer than the limit of the context " +
+            "comes back as its start and its end, and the excerpt gives a reference when the harness kept the whole text. " +
+            "Pass that reference as `ref`. Read a window with `offset` and `limit`: an offset counts the characters " +
+            `(UTF-16 code units) of the kept text from 0, and a page has at most ${MAX_PAGE_CHARS} characters, ` +
+            `${DEFAULT_PAGE_CHARS} by default. Or give \`pattern\`, a JavaScript regular expression, to get at most ` +
+            `${MAX_MATCHES} matches, each with its offset and the text around it. When a result gives \`more: true\`, ` +
+            "call again with `offset` set to its `end`.",
+        inputSchema: ReadToolOutputInputSchema,
+        // The reference alone repeats across the pages of one text, and the pattern is what tells two searches apart.
+        describeCall: ({ ref, pattern }) => (pattern === undefined ? ref : `${pattern} in ${ref}`),
+        execute: async ({ ref, offset = 0, limit, pattern }, ctx) => {
+            // The analysis of the session scopes the read, thus a reference cannot reach a text of a different analysis.
+            const kept = unwrapOrThrow(await store.get(ctx.session.scope.analysisId, ref));
+            if (kept === null)
+                return ok({ status: "not_found", ref });
+            const text = kept.content;
+            if (offset >= text.length)
+                return ok({ status: "out_of_range", ref, offset, keptLength: text.length });
+            const start = pairSafeIndex(text, offset, -1);
+            return ok(pattern === undefined ? page(ref, text, start, limit ?? DEFAULT_PAGE_CHARS) : search(ref, text, start, limit, pattern));
+        },
+    });
+}

package/dist/tools/research/generate-analogy-report.d.ts

@@ -2,18 +2,14 @@
  * generateAnalogyReport — cross-domain analogy report as a sub-agent tool.
  *
  * An inline harness `AgentDefinition` (mirroring `createLiteratureReviewerTool`)
- * driven by `runAgent`. The inner research agent runs Phase 1 extraction +
- * Phase 2 cross-domain search; the wrapper parses + schema-validates the text
- * output; on parse failure a single-shot conversion call (no tools) transforms
- * raw markdown into a valid envelope; on hard failure an `extraction-failed`
- * error envelope surfaces — the frontend never has to render raw prose.
- *
- * One provider serves both the research agent and the conversion retry; the
- * wrapper's parse + validate + error-envelope cascade is the correctness
- * boundary.
+ * driven by `runToTerminal`. The result reaches the wrapper through one of two
+ * terminal tools because the output envelope is a union and `defineTool` takes
+ * only a top-level object. A run with no outcome gets one salvage continuation,
+ * then an `extraction-failed` envelope, so the frontend never renders raw prose.
  */
 import { z } from "zod";
-import { type AnalogicalReasonerOutput } from "@inflexa-ai/harness/contracts/analogy-report.js";
+import type { Logger } from "../../lib/logger.js";
+import type { ToolOutputStore } from "../../loop/tool-output.js";
 import type { ChatProvider } from "../../providers/types.js";
 import type { UsageRecorder } from "../../billing/usage-recorder.js";
 import { type Tool } from "../define-tool.js";
@@ -42,22 +38,10 @@ export interface GenerateAnalogyReportDeps {
     readonly bioKeys: BioToolKeys;
     /** LLM usage-accounting seam for the child loop; omitted falls back to the no-op recorder. */
     readonly usageRecorder?: UsageRecorder;
+    /** The store of the child loop and of its read tool. */
+    readonly toolOutputStore?: ToolOutputStore;
+    /** Logging seam; omitted falls back to no-op. Logs the salvage warning and an accounting error of the reasoner loop. */
+    readonly logger?: Logger;
 }
 /** Build the `generate_analogy_report` delegation tool bound to its provider. */
 export declare function createGenerateAnalogyReportTool(deps: GenerateAnalogyReportDeps): Tool;
-interface ParseSuccess {
-    ok: true;
-    value: AnalogicalReasonerOutput;
-}
-interface ParseFailure {
-    ok: false;
-    reason: "not-json" | "schema-mismatch";
-}
-/**
- * Trim leading whitespace and strip a single wrapping ```json fence before
- * parsing — the inner agent's prompt forbids code fences but a relaxed
- * parse here avoids burning a conversion retry on trivial slips. Beyond
- * that, no salvaging. Exported for unit testing.
- */
-export declare function tryParseEnvelope(raw: string): ParseSuccess | ParseFailure;
-export {};

package/dist/tools/research/generate-analogy-report.js

@@ -2,26 +2,23 @@
  * generateAnalogyReport — cross-domain analogy report as a sub-agent tool.
  *
  * An inline harness `AgentDefinition` (mirroring `createLiteratureReviewerTool`)
- * driven by `runAgent`. The inner research agent runs Phase 1 extraction +
- * Phase 2 cross-domain search; the wrapper parses + schema-validates the text
- * output; on parse failure a single-shot conversion call (no tools) transforms
- * raw markdown into a valid envelope; on hard failure an `extraction-failed`
- * error envelope surfaces — the frontend never has to render raw prose.
- *
- * One provider serves both the research agent and the conversion retry; the
- * wrapper's parse + validate + error-envelope cascade is the correctness
- * boundary.
+ * driven by `runToTerminal`. The result reaches the wrapper through one of two
+ * terminal tools because the output envelope is a union and `defineTool` takes
+ * only a top-level object. A run with no outcome gets one salvage continuation,
+ * then an `extraction-failed` envelope, so the frontend never renders raw prose.
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
-import { AnalogicalReasonerOutputSchema } from "@inflexa-ai/harness/contracts/analogy-report.js";
+import { AnalogyReportSchema } from "@inflexa-ai/harness/contracts/analogy-report.js";
 import { analogicalReasonerPrompt } from "../../prompts/analogical-reasoner.js";
 import { composeSystemPrompt } from "../../agents/system-prompt.js";
 import { forSubAgent } from "../../auth/types.js";
-import { unwrapOrThrow } from "../../lib/result.js";
-import { finalText, runAgent } from "../../loop/run-agent.js";
+import { createNoopLogger } from "../../lib/console-logger.js";
 import { passthroughStep } from "../../loop/run-step.js";
+import { runToTerminal } from "../../loop/run-to-terminal.js";
 import { defineTool } from "../define-tool.js";
+import { createReadToolOutputTool } from "../read-tool-output.js";
+import { createReportBlockerToolFor } from "../sandbox/report-blocker.js";
 // Cross-domain search tools the analogical-reasoner uses.
 import { createSearchSemanticScholarTool } from "./search-semantic-scholar.js";
 import { searchArxivTool } from "./search-arxiv.js";
@@ -32,6 +29,41 @@ import { createNcbiTools } from "../bio/keys.js";
 const AGENT_ID = "analogical-reasoner";
 /** Tool-call budget for the inner research agent. */
 const RESEARCH_MAX_ITERATIONS = 40;
+const ANALOGY_SALVAGE_NUDGE = "You ended without a terminal outcome. Call submit_analogy_report with " +
+    "your report now, or report_blocker if phase 1 cannot run. Do not reply " +
+    "with prose.";
+function createSubmitAnalogyReportTool(cell) {
+    return defineTool({
+        id: "submit_analogy_report",
+        description: "Terminal. Submit the analogy report: the problem summary, objects, " +
+            "relations, and key terms of phase 1, and each analogy with its " +
+            "coverage and its cited solutions from phase 2. Call it one time with " +
+            "the full report. If it rejects the report, correct the fields that it " +
+            "names and call it again. Stop immediately after an accepted call.",
+        inputSchema: AnalogyReportSchema,
+        describeCall: "none",
+        execute: async (report) => {
+            // A report replaces a blocker, thus the report wins when one round records both.
+            cell.outcome = { kind: "report", report };
+            return ok({
+                recorded: true,
+                message: "Report recorded. You are done — stop now and do not take further actions.",
+            });
+        },
+    });
+}
+function createAnalogyBlockerTool(cell) {
+    return createReportBlockerToolFor({
+        // A blocker never replaces a recorded outcome, thus it never replaces a report.
+        record: (outcome) => {
+            if (cell.outcome === null)
+                cell.outcome = outcome;
+        },
+        blockedWhen: "Ends the analogy research with no report. Call it only when the " +
+            "problem is empty or incoherent, thus phase 1 cannot extract its " +
+            "objects and relations.",
+    });
+}
 export const generateAnalogyReportInputSchema = z.object({
     problem: z
         .string()
@@ -86,88 +118,18 @@ export function buildResearchPrompt(input) {
     }
     return lines.join("\n");
 }
-/**
- * Conversion prompt the retry uses when the inner research agent's output
- * is not valid JSON. Quotes the raw output verbatim and asks for a strict
- * AnalogyReportSchema-shaped object back. No tools — single shot.
- */
-function buildConversionPrompt(rawOutput) {
-    return [
-        "Convert the analogical-reasoner output below into a single JSON",
-        "object matching the AnalogyReport schema. Return ONLY raw JSON — no",
-        "prose, no markdown fences, no commentary, no apology. The first",
-        "character of your response must be `{`. The final character must be `}`.",
-        "",
-        "## Required shape (AnalogyReportSchema)",
-        "",
-        "```json",
-        "{",
-        '  "schemaVersion": "1",',
-        '  "problemSummary": "1-2 sentence summary of the source problem.",',
-        '  "problemObjects": [{ "name": "...", "role": "..." }],',
-        '  "problemRelations": ["short bullet phrase", "..."],',
-        '  "keyTerms": ["term1", "term2"],',
-        '  "analogies": [',
-        "    {",
-        '      "targetDomain": "control_theory",',
-        '      "analogyTitle": "Adaptive control of an unseen plant",',
-        '      "objectMappings": [{ "source": "...", "target": "...", "rationale": "..." }],',
-        '      "sharedRelations": "...",',
-        '      "coverage": "available",',
-        '      "solutions": [',
-        "        {",
-        '          "title": "Method or paper title (verbatim from input)",',
-        '          "sourceDomain": "control_theory",',
-        '          "description": "2-3 sentences.",',
-        '          "keyConcepts": ["..."],',
-        '          "relevance": "How this transfers back to the source problem.",',
-        '          "sources": [{ "url": "https://...", "title": "Exact paper title" }],',
-        '          "githubRepos": []',
-        "        }",
-        "      ]",
-        "    }",
-        "  ]",
-        "}",
-        "```",
-        "",
-        "## Field rules",
-        "",
-        "- Preserve every analogy, object mapping, shared relation, solution, and",
-        "  citation that appears in the input. Do not invent content.",
-        "- Each analogy needs `coverage`:",
-        "  - `available` when the input lists concrete solutions for it,",
-        "  - `queried_no_data` when the input says searches returned no usable results,",
-        "  - `search_failed` when the input says the search tool errored out,",
-        "  - `not_loaded` when the input says the analogy was skipped (budget).",
-        "  When `coverage` is not `available`, `solutions` must be `[]`.",
-        "- Each `solutions[].sources[]` entry needs a valid `url` (http/https)",
-        "  AND a `title`. If a paper is mentioned without a URL, omit that source.",
-        "- `githubRepos` must always be an array (use `[]` when not mentioned).",
-        "- If the input has no extractable analogy content at all (pure apology,",
-        "  empty, off-topic), return the envelope with `analogies: []`. The",
-        "  wrapper translates that into an error envelope.",
-        "",
-        "--- INPUT ---",
-        rawOutput,
-        "--- END INPUT ---",
-    ].join("\n");
-}
 /** Build the `generate_analogy_report` delegation tool bound to its provider. */
 export function createGenerateAnalogyReportTool(deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("generate-analogy-report");
     const ncbi = createNcbiTools(deps.bioKeys);
-    const reasonerTools = [
+    const searchTools = [
         createSearchSemanticScholarTool({ ...(deps.bioKeys.semanticScholar === undefined ? {} : { apiKey: deps.bioKeys.semanticScholar }) }),
         searchArxivTool,
         createSearchGithubReposTool({ githubToken: deps.bioKeys.github }),
         ncbi.pubmed,
+        ...(deps.toolOutputStore ? [createReadToolOutputTool(deps.toolOutputStore)] : []),
     ];
-    const agent = {
-        id: AGENT_ID,
-        systemPrompt: composeSystemPrompt(analogicalReasonerPrompt),
-        model: deps.model,
-        tools: reasonerTools,
-        maxIterations: RESEARCH_MAX_ITERATIONS,
-    };
+    const systemPrompt = composeSystemPrompt(analogicalReasonerPrompt);
     return defineTool({
         id: "generate_analogy_report",
         description: "Idea-generation engine. Extracts structural analogies for an open-ended " +
@@ -189,29 +151,41 @@ export function createGenerateAnalogyReportTool(deps) {
             "`solutions` array — informational, NOT an error. A top-level `error` " +
             "field means no report was produced: on `error.kind === " +
             '"extraction-failed"` do NOT retry with the same or a similar problem ' +
-            "statement (the wrapper already retried internally — you would burn " +
-            "latency on the same failure). Surface the message and ask the user to " +
-            "narrow the problem.",
+            "statement (the wrapper already salvaged the run one time — you would " +
+            "burn latency on the same failure). Surface the message and ask the " +
+            "user to narrow the problem.",
         inputSchema: generateAnalogyReportInputSchema,
         describeCall: "none",
         execute: async (input, ctx) => {
             const childSession = forSubAgent(ctx.session, AGENT_ID);
-            // Phase 1+2: drive the research agent over the cross-domain toolset.
-            let rawText;
+            // Each call builds fresh tool closures over its own cell. Their order and
+            // definitions stay fixed across calls so the cache-keyed prefix holds.
+            const cell = { outcome: null };
+            const submitReportTool = createSubmitAnalogyReportTool(cell);
+            const blockerTool = createAnalogyBlockerTool(cell);
+            const agent = {
+                id: AGENT_ID,
+                systemPrompt,
+                model: deps.model,
+                tools: [...searchTools, submitReportTool, blockerTool],
+                maxIterations: RESEARCH_MAX_ITERATIONS,
+            };
             try {
-                const { messages: transcript } = await runAgent(agent, [{ role: "user", content: buildResearchPrompt(input) }], childSession, {
+                await runToTerminal(agent, [{ role: "user", content: buildResearchPrompt(input) }], childSession, {
                     provider: deps.provider,
                     signal: ctx.signal,
                     emit: ctx.emit,
                     runStep: passthroughStep,
+                    resolved: () => cell.outcome !== null,
+                    logger,
                     usageRecorder: deps.usageRecorder,
+                    toolOutputStore: deps.toolOutputStore,
                     // Fold the child's calls into the turn total the root loop reports.
                     turnUsage: ctx.turnUsage,
                     // Keeps the usage record keys of two parallel dispatches disjoint —
                     // same frame, same call path, same loop-local step names.
                     invocationId: ctx.invocationId,
-                });
-                rawText = finalText(transcript);
+                }, { tools: [submitReportTool, blockerTool], nudge: ANALOGY_SALVAGE_NUDGE });
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
@@ -223,84 +197,23 @@ export function createGenerateAnalogyReportTool(deps) {
                     },
                 });
             }
-            // Fast path: the agent emitted valid JSON matching the schema.
-            const directParse = tryParseEnvelope(rawText);
-            if (directParse.ok)
-                return ok(directParse.value);
-            // Slow path: a single-shot conversion call (no tools) transforms the
-            // raw output into a valid envelope. The parse+validate+envelope
-            // cascade below is the safety net.
-            try {
-                const reply = unwrapOrThrow(await deps.provider.chat({
-                    tools: {},
-                    toolChoice: "none",
-                    system: "You convert an analogical-reasoner's free-text output " +
-                        "into a strict AnalogyReportSchema JSON envelope. You " +
-                        "preserve information faithfully and never invent content. " +
-                        "You return ONLY raw JSON — no prose, no markdown fences, " +
-                        "no commentary.",
-                    messages: [{ role: "user", content: buildConversionPrompt(rawText) }],
-                }, childSession, ctx.signal));
-                const content = reply.message.content;
-                const convertedText = typeof content === "string"
-                    ? content
-                    : content
-                        .filter((b) => b.type === "text")
-                        .map((b) => b.text)
-                        .join("");
-                const parse = tryParseEnvelope(convertedText);
-                if (!parse.ok)
-                    return ok(buildExtractionFailedEnvelope());
-                // If the conversion model produced an error envelope verbatim,
-                // surface it (it knows something we don't about the input).
-                if ("error" in parse.value)
-                    return ok(parse.value);
-                // Empty `analogies: []` means the input had no extractable content
-                // (apology, off-topic) — surface as extraction-failed.
-                if (parse.value.analogies.length === 0) {
-                    return ok(buildExtractionFailedEnvelope());
-                }
-                return ok(parse.value);
-            }
-            catch {
-                return ok(buildExtractionFailedEnvelope());
+            const outcome = cell.outcome;
+            if (outcome?.kind === "report")
+                return ok(outcome.report);
+            if (outcome?.kind === "blocker") {
+                return ok({ schemaVersion: "1", error: { kind: "extraction-failed", message: outcome.reason } });
             }
+            return ok(buildExtractionFailedEnvelope());
         },
     });
 }
-/** Single source of truth for the wrapper's terminal "could not recover" envelope. */
+/** The envelope of a run that recorded no outcome, also after its salvage. */
 function buildExtractionFailedEnvelope() {
     return {
         schemaVersion: "1",
         error: {
             kind: "extraction-failed",
-            message: "The analogical reasoner returned malformed output that could not " + "be recovered. Try narrowing the problem statement.",
+            message: "The analogical reasoner submitted no report and no blocker, also after a corrective request. Try narrowing the problem statement.",
         },
     };
 }
-/**
- * Trim leading whitespace and strip a single wrapping ```json fence before
- * parsing — the inner agent's prompt forbids code fences but a relaxed
- * parse here avoids burning a conversion retry on trivial slips. Beyond
- * that, no salvaging. Exported for unit testing.
- */
-export function tryParseEnvelope(raw) {
-    const stripped = stripFence(raw);
-    let candidate;
-    try {
-        candidate = JSON.parse(stripped);
-    }
-    catch {
-        return { ok: false, reason: "not-json" };
-    }
-    const result = AnalogicalReasonerOutputSchema.safeParse(candidate);
-    if (!result.success)
-        return { ok: false, reason: "schema-mismatch" };
-    return { ok: true, value: result.data };
-}
-function stripFence(raw) {
-    const trimmed = raw.trim();
-    if (!trimmed.startsWith("```"))
-        return trimmed;
-    return trimmed.replace(/^```(?:json)?\s*\n/i, "").replace(/\n```\s*$/i, "");
-}

package/dist/tools/research/generate-plan.d.ts

@@ -24,6 +24,7 @@
  * terminal-tool surface above.
  */
 import type { Pool } from "pg";
+import type { ToolOutputStore } from "../../loop/tool-output.js";
 import { type ChatProvider } from "../../providers/types.js";
 import type { UsageRecorder } from "../../billing/usage-recorder.js";
 import { type Tool } from "../define-tool.js";
@@ -53,6 +54,8 @@ export interface GeneratePlanDeps extends EnvironmentStorePaths {
     readonly logger?: Logger;
     /** LLM usage-accounting seam for the planner loop; omitted falls back to the no-op recorder. */
     readonly usageRecorder?: UsageRecorder;
+    /** The store of the planner loop and of its read tool. */
+    readonly toolOutputStore?: ToolOutputStore;
     /** API keys for the search tools the planner uses to ground a plan. */
     readonly bioKeys: BioToolKeys;
 }

package/dist/tools/research/generate-plan.js

@@ -32,6 +32,7 @@ import { passthroughStep } from "../../loop/run-step.js";
 import { forSubAgent, scopeResource } from "../../auth/types.js";
 import { effectiveDeadlineMs } from "../../providers/types.js";
 import { defineTool } from "../define-tool.js";
+import { createReadToolOutputTool } from "../read-tool-output.js";
 import { createListAvailablePackagesTool } from "../sandbox/list-available-packages.js";
 import { createListAvailableRefsTool } from "../sandbox/list-available-refs.js";
 import { createReportBlockerToolFor } from "../sandbox/report-blocker.js";
@@ -872,6 +873,7 @@ export function createGeneratePlanTool(deps) {
             // definitions are identical across invocations, thus the request prefix
             // that the cache keys on does not move.
             const searchTools = buildPlannerSearchTools(deps);
+            const readTools = deps.toolOutputStore ? [createReadToolOutputTool(deps.toolOutputStore)] : [];
             const planner = {
                 id: PLANNER_AGENT_ID,
                 systemPrompt: composeSystemPrompt(plannerInstructions(deps.resourcePolicy)),
@@ -879,7 +881,7 @@ export function createGeneratePlanTool(deps) {
                 // The search tools come first, and the terminal tools come last.
                 // The order is the order of the prompt, and it is stable across
                 // every invocation, thus the cached request prefix holds.
-                tools: [...searchTools, ...innerTools.terminal],
+                tools: [...searchTools, ...readTools, ...innerTools.terminal],
                 maxIterations: PLANNER_MAX_ITERATIONS,
             };
             // Merge the outer abort signal with a wall-clock timeout — either
@@ -899,6 +901,7 @@ export function createGeneratePlanTool(deps) {
                     // turn below recovers a run that ends on prose.
                     logger,
                     usageRecorder: deps.usageRecorder,
+                    toolOutputStore: deps.toolOutputStore,
                     // Fold the planner's calls into the turn total the root loop reports.
                     turnUsage: ctx.turnUsage,
                     // Keeps the usage record keys of two parallel dispatches disjoint —

package/dist/tools/research/literature-reviewer.d.ts

@@ -14,6 +14,7 @@
  * entire tool call is one step in the parent loop (PR #3 caches it whole,
  * so the child never replays).
  */
+import type { ToolOutputStore } from "../../loop/tool-output.js";
 import { type ChatProvider } from "../../providers/types.js";
 import { type Tool } from "../define-tool.js";
 import { type BioToolKeys } from "../bio/keys.js";
@@ -31,6 +32,8 @@ export interface LiteratureReviewerDeps {
     readonly bioKeys: BioToolKeys;
     /** LLM usage-accounting seam for the child loop; omitted falls back to the no-op recorder. */
     readonly usageRecorder?: UsageRecorder;
+    /** The store of the child loop and of its read tool. */
+    readonly toolOutputStore?: ToolOutputStore;
     /** Shared bibliographic verification service; all agent surfaces share its pacing/cache. */
     readonly citationResolver: CitationResolver;
 }

package/dist/tools/research/literature-reviewer.js

@@ -22,6 +22,7 @@ import { literatureReviewerPrompt } from "../../prompts/literature-reviewer.js";
 import { composeSystemPrompt } from "../../agents/system-prompt.js";
 import { forSubAgent } from "../../auth/types.js";
 import { defineTool } from "../define-tool.js";
+import { createReadToolOutputTool } from "../read-tool-output.js";
 import { createChemDbTools, createNcbiTools } from "../bio/keys.js";
 import { genePreclinicalProfileTool } from "../bio/gene-preclinical-profile.js";
 import { lookupAnnotationTool } from "../bio/lookup-annotation.js";
@@ -46,6 +47,7 @@ export function createLiteratureReviewerTool(deps) {
         createResolveCitationTool(deps.citationResolver),
         chemDb.drugGeneInteractions,
         genePreclinicalProfileTool,
+        ...(deps.toolOutputStore ? [createReadToolOutputTool(deps.toolOutputStore)] : []),
     ];
     const agent = {
         id: AGENT_ID,
@@ -78,6 +80,7 @@ export function createLiteratureReviewerTool(deps) {
                 emit: ctx.emit,
                 runStep: passthroughStep,
                 usageRecorder: deps.usageRecorder,
+                toolOutputStore: deps.toolOutputStore,
                 // Fold the child's calls into the turn total the root loop reports.
                 turnUsage: ctx.turnUsage,
                 // Keeps the usage record keys of two parallel reviews disjoint —

package/dist/tools/sandbox/report-blocker.d.ts

@@ -6,16 +6,21 @@
  * `report_blocker` is the alternative to improvising an inline result the
  * harness would launder into a green run.
  *
- * This module is the canonical home of the tool. Three loops offer it — the
- * sandbox step agent, the planner (`tools/research/generate-plan.ts`) and the
- * run synthesizer (`execution/run-synthesis.ts`) — and all three share one id,
+ * This module is the canonical home of the tool. Four loops offer it — the
+ * sandbox step agent, the planner (`tools/research/generate-plan.ts`), the
+ * run synthesizer (`execution/run-synthesis.ts`) and the analogical reasoner
+ * (`tools/research/generate-analogy-report.ts`) — and all four share one id,
  * one input schema and one terminal contract via `createReportBlockerToolFor`.
  * What differs per loop is only what a blocker *means* there, so each call site
  * injects its own `blockedWhen` prose and its own capture closure. The tool
- * records the reason and tells the agent to stop; the driving body reads its
- * own outcome cell after the loop and decides the terminal status.
+ * records the reason and tells the agent to stop; the driving body reads the
+ * outcome after the loop and decides the terminal status. The sandbox step body
+ * runs in durable steps, so it reads the blocker back from the transcript
+ * (`recordedBlocker`) on replay, not only from its cell.
  */
+import type { ModelMessage } from "ai";
 import { type Tool } from "../define-tool.js";
+export declare const REPORT_BLOCKER_TOOL_ID = "report_blocker";
 export interface BlockerOutcome {
     readonly kind: "blocker";
     readonly reason: string;
@@ -46,6 +51,14 @@ export interface ReportBlockerDeps {
  * site supplies only the per-loop meaning and the capture closure.
  */
 export declare function createReportBlockerToolFor(deps: ReportBlockerDeps): Tool;
+/**
+ * The blocker that a run recorded, read from its transcript: the reason of the
+ * first `report_blocker` call, in call order, whose result is ok.
+ *
+ * A replay returns each tool step's cached result without re-running
+ * `execute`, so the in-memory cell is empty on replay; the transcript is not.
+ */
+export declare function recordedBlocker(messages: readonly ModelMessage[]): BlockerOutcome | null;
 /**
  * The sandbox step agent's `report_blocker`, bound to the step body's holder.
  * A blocker here ends the step with no deliverables and a blocked reason.