@inflexa-ai/harness 0.1.1

package/dist/tools/report/version-fs.d.ts

@@ -0,0 +1,15 @@
+/**
+ * In-process workspace surface for the report-builder agent.
+ *
+ * Tight read/write/mkdir surface scoped to the version directory.
+ * Agent-supplied paths are resolved against `versionDir`; any path that
+ * escapes is rejected as `out_of_scope`. Constructed inside the
+ * iterate-report runner so it always shares the same `versionDir` as the
+ * rest of the report tools.
+ */
+import { type Tool } from "../define-tool.js";
+export interface VersionFsToolsState {
+    /** Absolute path to the version directory. All paths resolve under this. */
+    readonly versionDir: string;
+}
+export declare function createVersionFsTools(state: VersionFsToolsState): Tool[];

package/dist/tools/report/version-fs.js

@@ -0,0 +1,154 @@
+/**
+ * In-process workspace surface for the report-builder agent.
+ *
+ * Tight read/write/mkdir surface scoped to the version directory.
+ * Agent-supplied paths are resolved against `versionDir`; any path that
+ * escapes is rejected as `out_of_scope`. Constructed inside the
+ * iterate-report runner so it always shares the same `versionDir` as the
+ * rest of the report tools.
+ */
+import { mkdir as fsMkdir, readFile as fsReadFile, stat as fsStat, writeFile as fsWriteFile } from "node:fs/promises";
+import { dirname, resolve as resolvePath, sep } from "node:path";
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+const MAX_READ_BYTES = 256 * 1024;
+const MAX_WRITE_BYTES = 1 * 1024 * 1024;
+/** Resolve an agent-supplied path against `versionDir`, rejecting escapes. */
+function resolveAgentPath(agentPath, versionDir) {
+    if (agentPath.length === 0 || agentPath.includes("\0")) {
+        return { kind: "out_of_scope", reason: "empty or null-byte path" };
+    }
+    // Strip a leading slash so an agent typing "/index.html" is treated as
+    // "index.html" relative to versionDir (the version dir is the root).
+    const stripped = agentPath.replace(/^\/+/, "");
+    if (!stripped) {
+        return { kind: "out_of_scope", reason: "path resolves to the version dir itself" };
+    }
+    const absolute = resolvePath(versionDir, stripped);
+    if (absolute !== versionDir && !absolute.startsWith(versionDir + sep)) {
+        return { kind: "out_of_scope", reason: `path escapes version dir: ${agentPath}` };
+    }
+    return { kind: "ok", absolute };
+}
+export function createVersionFsTools(state) {
+    const writeFile = defineTool({
+        id: "write_file",
+        description: "Write a UTF-8 text file under the report's version directory. Use " +
+            "relative paths (e.g. `report.html.j2`, `assets/foo.csv`). Returns " +
+            "`out_of_scope` for any path that escapes the version dir.",
+        inputSchema: z.object({
+            path: z.string().min(1),
+            content: z.string(),
+        }),
+        execute: async ({ path, content }) => {
+            const resolved = resolveAgentPath(path, state.versionDir);
+            if (resolved.kind === "out_of_scope") {
+                return ok({ status: "out_of_scope", reason: resolved.reason });
+            }
+            const bytes = Buffer.byteLength(content, "utf8");
+            if (bytes > MAX_WRITE_BYTES) {
+                return ok({
+                    status: "too_large",
+                    reason: `write rejected: ${bytes} bytes exceeds ${MAX_WRITE_BYTES} cap`,
+                });
+            }
+            await fsMkdir(dirname(resolved.absolute), { recursive: true });
+            await fsWriteFile(resolved.absolute, content, "utf8");
+            return ok({ status: "ok", bytesWritten: bytes });
+        },
+    });
+    const editFile = defineTool({
+        id: "edit_file",
+        description: "Surgical edit of an existing UTF-8 file inside the report's version " +
+            "directory: replace the first occurrence of `oldText` with `newText`. " +
+            "Returns `not_found` if the file doesn't exist, `no_match` if " +
+            "`oldText` isn't present.",
+        inputSchema: z.object({
+            path: z.string().min(1),
+            oldText: z.string().min(1),
+            newText: z.string(),
+        }),
+        execute: async ({ path, oldText, newText }) => {
+            const resolved = resolveAgentPath(path, state.versionDir);
+            if (resolved.kind === "out_of_scope") {
+                return ok({ status: "out_of_scope", reason: resolved.reason });
+            }
+            let content;
+            try {
+                content = await fsReadFile(resolved.absolute, "utf8");
+            }
+            catch (err) {
+                if (err.code === "ENOENT") {
+                    return ok({ status: "not_found" });
+                }
+                throw err;
+            }
+            const idx = content.indexOf(oldText);
+            if (idx === -1) {
+                return ok({ status: "no_match" });
+            }
+            const next = content.slice(0, idx) + newText + content.slice(idx + oldText.length);
+            const bytes = Buffer.byteLength(next, "utf8");
+            if (bytes > MAX_WRITE_BYTES) {
+                return ok({
+                    status: "too_large",
+                    reason: `post-edit size ${bytes} bytes exceeds ${MAX_WRITE_BYTES} cap`,
+                });
+            }
+            await fsWriteFile(resolved.absolute, next, "utf8");
+            return ok({ status: "ok", bytesWritten: bytes });
+        },
+    });
+    const readFile = defineTool({
+        id: "read_file",
+        description: "Read a UTF-8 file inside the report's version directory. Returns " + "truncated content (capped at 256 KiB) for large files.",
+        inputSchema: z.object({
+            path: z.string().min(1),
+        }),
+        execute: async ({ path }) => {
+            const resolved = resolveAgentPath(path, state.versionDir);
+            if (resolved.kind === "out_of_scope") {
+                return ok({ status: "out_of_scope", reason: resolved.reason });
+            }
+            let st;
+            try {
+                st = await fsStat(resolved.absolute);
+            }
+            catch (err) {
+                if (err.code === "ENOENT") {
+                    return ok({ status: "not_found" });
+                }
+                throw err;
+            }
+            if (!st.isFile()) {
+                return ok({ status: "not_found" });
+            }
+            const buf = await fsReadFile(resolved.absolute);
+            const truncated = buf.length > MAX_READ_BYTES;
+            const sliced = truncated ? buf.subarray(0, MAX_READ_BYTES) : buf;
+            return ok({
+                status: "ok",
+                content: sliced.toString("utf8"),
+                truncated,
+                totalBytes: st.size,
+            });
+        },
+    });
+    const mkdir = defineTool({
+        id: "mkdir",
+        description: "Create a directory (recursive) inside the report's version directory.",
+        inputSchema: z.object({
+            path: z.string().min(1),
+        }),
+        execute: async ({ path }) => {
+            const resolved = resolveAgentPath(path, state.versionDir);
+            if (resolved.kind === "out_of_scope") {
+                return ok({ status: "out_of_scope", reason: resolved.reason });
+            }
+            await fsMkdir(resolved.absolute, { recursive: true });
+            return ok({ status: "ok" });
+        },
+    });
+    return [writeFile, editFile, readFile, mkdir];
+}

package/dist/tools/research/context7-docs.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Context7 documentation lookup tools for sandbox agents.
+ *
+ * Wraps the Context7 REST API to let agents look up current package
+ * documentation and code examples at runtime. Two-step flow:
+ * 1. resolveLibraryId — find the Context7 library ID for a package name
+ * 2. queryDocs — query documentation for a resolved library
+ */
+type ResolveLibraryIdOutput = {
+    found: false;
+} | {
+    found: true;
+    libraryId: string;
+    name: string;
+    description: string;
+};
+type QueryDocsOutput = {
+    found: false;
+} | {
+    found: true;
+    documentation: string;
+};
+export declare const resolveLibraryIdTool: import("../define-tool.js").Tool<{
+    libraryName: string;
+    query: string;
+}, ResolveLibraryIdOutput>;
+export declare const queryDocsTool: import("../define-tool.js").Tool<{
+    libraryId: string;
+    query: string;
+}, QueryDocsOutput>;
+export {};

package/dist/tools/research/context7-docs.js

@@ -0,0 +1,61 @@
+/**
+ * Context7 documentation lookup tools for sandbox agents.
+ *
+ * Wraps the Context7 REST API to let agents look up current package
+ * documentation and code examples at runtime. Two-step flow:
+ * 1. resolveLibraryId — find the Context7 library ID for a package name
+ * 2. queryDocs — query documentation for a resolved library
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { apiFetchValidated, describeApiError } from "../lib/api-utils.js";
+const CONTEXT7_BASE = "https://context7.com/api/v1";
+// Raw Context7 wire shapes, validated at the fetch boundary. `id`/`name` stay
+// required — they are read without a guard — while genuinely-optional fields
+// carry `.optional()` so a partial-but-valid response still parses.
+const Context7SearchResponseSchema = z.object({
+    results: z.array(z.object({ id: z.string(), name: z.string(), description: z.string().nullable().optional() })).optional(),
+});
+const Context7DocsResponseSchema = z.object({ content: z.string().optional() });
+export const resolveLibraryIdTool = defineTool({
+    id: "resolve_library_id",
+    description: "Resolve a package name (e.g., 'scanpy', 'DESeq2', 'scikit-learn') to a Context7 library ID. Call this BEFORE queryDocs to get the library ID needed for documentation lookup. Returns matching libraries ranked by relevance.",
+    inputSchema: z.object({
+        libraryName: z.string().describe("Package or library name to search for (e.g., 'scanpy', 'pysam', 'lifelines')."),
+        query: z.string().describe("What you need help with — used to rank results by relevance (e.g., 'how to run differential expression')."),
+    }),
+    execute: async ({ libraryName, query }) => {
+        const result = await apiFetchValidated(`${CONTEXT7_BASE}/search?query=${encodeURIComponent(libraryName)}&topic=${encodeURIComponent(query)}`, Context7SearchResponseSchema, { maxRetries: 1 });
+        if (result.isErr())
+            throw new Error(`Context7 search failed: ${describeApiError(result.error)}`);
+        const best = (result.value.results ?? [])[0];
+        // No match is an expected outcome — a `found: false` data variant.
+        if (!best)
+            return ok({ found: false });
+        return ok({
+            found: true,
+            libraryId: best.id,
+            name: best.name,
+            description: best.description ?? "",
+        });
+    },
+});
+export const queryDocsTool = defineTool({
+    id: "query_docs",
+    description: "Query up-to-date documentation and code examples for a library. You must call resolve-library-id first to get the libraryId. Use this to verify function signatures, parameters, and usage patterns before writing code.",
+    inputSchema: z.object({
+        libraryId: z.string().describe("Context7 library ID from resolve-library-id (e.g., '/scverse/scanpy')."),
+        query: z.string().describe("Specific question about the library (e.g., 'rank_genes_groups function parameters and usage')."),
+    }),
+    execute: async ({ libraryId, query }) => {
+        const result = await apiFetchValidated(`${CONTEXT7_BASE}/docs?libraryId=${encodeURIComponent(libraryId)}&query=${encodeURIComponent(query)}`, Context7DocsResponseSchema, { maxRetries: 1 });
+        if (result.isErr())
+            throw new Error(`Context7 query failed: ${describeApiError(result.error)}`);
+        const documentation = result.value.content ?? "";
+        // No documentation for the query is an expected outcome.
+        if (!documentation)
+            return ok({ found: false });
+        return ok({ found: true, documentation });
+    },
+});

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

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ */
+import { z } from "zod";
+import { type AnalogicalReasonerOutput } from "@inflexa-ai/harness/contracts/analogy-report.js";
+import type { ChatProvider } from "../../providers/types.js";
+import { type Tool } from "../define-tool.js";
+import { type BioToolKeys } from "../bio/keys.js";
+export declare const generateAnalogyReportInputSchema: z.ZodObject<{
+    problem: z.ZodString;
+    context: z.ZodOptional<z.ZodString>;
+    numDomains: z.ZodOptional<z.ZodNumber>;
+    solutionsPerDomain: z.ZodOptional<z.ZodNumber>;
+    preferredDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    excludeDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type GenerateAnalogyReportInput = z.infer<typeof generateAnalogyReportInputSchema>;
+/**
+ * Render the structured input as a brief that maps 1-to-1 to the
+ * `analogical-reasoner` prompt's "Inputs you may see in the brief" section.
+ * Exported for unit testing.
+ */
+export declare function buildResearchPrompt(input: GenerateAnalogyReportInput): string;
+export interface GenerateAnalogyReportDeps {
+    /** The LLM seam the child loop runs on. */
+    readonly provider: ChatProvider;
+    /** Model id — provenance / metric label; the provider owns the wire model. */
+    readonly model: string;
+    /** API keys for the bio/chem + GitHub data sources the reasoner searches. */
+    readonly bioKeys: BioToolKeys;
+}
+/** 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

@@ -0,0 +1,288 @@
+/**
+ * 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.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { AnalogicalReasonerOutputSchema } from "@inflexa-ai/harness/contracts/analogy-report.js";
+import { analogicalReasonerPrompt } from "../../prompts/analogical-reasoner.js";
+import { forSubAgent } from "../../auth/types.js";
+import { unwrapOrThrow } from "../../lib/result.js";
+import { finalText, runAgent } from "../../loop/run-agent.js";
+import { passthroughStep } from "../../loop/run-step.js";
+import { defineTool } from "../define-tool.js";
+// Cross-domain search tools the analogical-reasoner uses.
+import { searchSemanticScholarTool } from "./search-semantic-scholar.js";
+import { searchArxivTool } from "./search-arxiv.js";
+import { createSearchGithubReposTool } from "./search-github-repos.js";
+// Biology literature — reused for analogies that land back in biology.
+import { createNcbiTools } from "../bio/keys.js";
+/** Sub-agent identity — appended to `callPath`, set as `agentId`. */
+const AGENT_ID = "analogical-reasoner";
+/** Tool-call budget for the inner research agent. */
+const RESEARCH_MAX_ITERATIONS = 40;
+export const generateAnalogyReportInputSchema = z.object({
+    problem: z
+        .string()
+        .min(1)
+        .describe("The scientific problem in natural language. The single most important " +
+        "field — describes what the user is trying to do and the system-level " +
+        "constraints. Keep it focused; the inner agent reads this verbatim."),
+    context: z
+        .string()
+        .optional()
+        .describe("Optional supporting context: data profile excerpt, prior findings, " +
+        "experimental design notes, user constraints. Keep under ~500 tokens. " +
+        "Do NOT paste full files — the inner agent does not need them."),
+    numDomains: z.number().int().min(2).max(5).optional().describe("How many cross-domain analogies to extract. Defaults to 3."),
+    solutionsPerDomain: z.number().int().min(1).max(5).optional().describe("How many real, cited solutions to surface per analogy. Defaults to 3."),
+    preferredDomains: z
+        .array(z.string())
+        .optional()
+        .describe("Soft preferences for analogy domains (e.g., " + '`["control_theory", "ecology"]`). The agent treats these as hints, ' + "not constraints."),
+    excludeDomains: z
+        .array(z.string())
+        .optional()
+        .describe("Hard exclusions — domains the agent must avoid. Use to force a " +
+        'cross-domain search (e.g., `["biology"]` when the source problem is ' +
+        "biological)."),
+});
+/**
+ * Render the structured input as a brief that maps 1-to-1 to the
+ * `analogical-reasoner` prompt's "Inputs you may see in the brief" section.
+ * Exported for unit testing.
+ */
+export function buildResearchPrompt(input) {
+    const lines = ["## Problem", input.problem];
+    if (input.context) {
+        lines.push("", "## Context", input.context);
+    }
+    const knobs = [];
+    if (input.numDomains !== undefined) {
+        knobs.push(`- numDomains: ${input.numDomains}`);
+    }
+    if (input.solutionsPerDomain !== undefined) {
+        knobs.push(`- solutionsPerDomain: ${input.solutionsPerDomain}`);
+    }
+    if (input.preferredDomains && input.preferredDomains.length > 0) {
+        knobs.push(`- preferredDomains: ${input.preferredDomains.join(", ")}`);
+    }
+    if (input.excludeDomains && input.excludeDomains.length > 0) {
+        knobs.push(`- excludeDomains: ${input.excludeDomains.join(", ")}`);
+    }
+    if (knobs.length > 0) {
+        lines.push("", "## Knobs", ...knobs);
+    }
+    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 ncbi = createNcbiTools(deps.bioKeys);
+    const reasonerTools = [
+        searchSemanticScholarTool,
+        searchArxivTool,
+        createSearchGithubReposTool({ githubToken: deps.bioKeys.github }),
+        ncbi.searchPubMed,
+        ncbi.getArticleDetails,
+        ncbi.getArticleFullText,
+    ];
+    const agent = {
+        id: AGENT_ID,
+        systemPrompt: analogicalReasonerPrompt,
+        model: deps.model,
+        tools: reasonerTools,
+        maxIterations: RESEARCH_MAX_ITERATIONS,
+    };
+    return defineTool({
+        id: "generate_analogy_report",
+        description: "Generate a cross-domain analogy report for an open-ended scientific " +
+            "problem. Pass the user's problem as a single field plus optional " +
+            "context (data profile excerpts, prior findings) and knobs (domain " +
+            "counts, preferred/excluded domains). Returns a structured " +
+            "AnalogyReport envelope — analogies with object mappings, shared " +
+            "relations, and cited solutions from other domains. The UI renders " +
+            "the envelope as an inline card; reach for this tool whenever the " +
+            "user is in exploratory or hypothesis-generation mode.",
+        inputSchema: generateAnalogyReportInputSchema,
+        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;
+            try {
+                const { messages: transcript } = await runAgent(agent, [{ role: "user", content: buildResearchPrompt(input) }], childSession, {
+                    provider: deps.provider,
+                    signal: ctx.signal,
+                    emit: ctx.emit,
+                    runStep: passthroughStep,
+                });
+                rawText = finalText(transcript);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return ok({
+                    schemaVersion: "1",
+                    error: {
+                        kind: "extraction-failed",
+                        message: `Analogy research failed: ${message}`.slice(0, 240),
+                    },
+                });
+            }
+            // 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 harness anthropic provider
+            // silently drops `temperature` on 4.7+ models, so an explicit
+            // Sonnet-vs-Opus split is unnecessary — the parse+validate+envelope
+            // cascade below is the real 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());
+            }
+        },
+    });
+}
+/** Single source of truth for the wrapper's terminal "could not recover" envelope. */
+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.",
+        },
+    };
+}
+/**
+ * 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

@@ -0,0 +1,39 @@
+/**
+ * generatePlan — a loop-driving tool: a focused `runAgent` loop that builds
+ * an analysis plan (a DAG of steps).
+ *
+ * The outer tool receives structured context from the conversation agent
+ * (data profile, research question, prior runs, constraints) and drives an
+ * internal "planner" agent that communicates outcomes EXCLUSIVELY via four
+ * terminal tool calls:
+ *
+ *   - validate_plan(plan)       → non-terminal dry-run (Zod + semantic)
+ *   - submit_plan(plan)         → terminal success: re-validates + persists
+ *   - request_clarification(…)  → terminal: planner needs more context
+ *   - report_blocker(reason)    → terminal: no viable plan
+ *
+ * The planner is an `AgentDefinition` driven by `runAgent`; the pool and
+ * resource id are an explicit `Pool` dependency and the request-scoped
+ * `Session`. The planner prompt injects the agent catalog and exposes the
+ * terminal-tool surface above.
+ */
+import type { Pool } from "pg";
+import { type ChatProvider } from "../../providers/types.js";
+import { type Tool } from "../define-tool.js";
+import { type ResourcePolicy } from "../../config/resource-limits.js";
+export interface GeneratePlanDeps {
+    /** The LLM seam the planner loop runs on. */
+    readonly provider: ChatProvider;
+    /** Database pool — plan persistence and prior-plan loading. */
+    readonly pool: Pool;
+    /** Model id — provenance / metric label; the provider owns the wire model. */
+    readonly model: string;
+    /**
+     * Host resource policy — stated to the planner as concrete per-step
+     * ceilings and enforced by `validate_plan`. Absent, the prompt keeps its
+     * default guidance and validation skips the ceiling check.
+     */
+    readonly resourcePolicy?: ResourcePolicy;
+}
+/** Build the `generate_plan` tool bound to its provider and pool. */
+export declare function createGeneratePlanTool(deps: GeneratePlanDeps): Tool;