@inflexa-ai/harness 0.46.2 → 0.48.0

package/dist/tools/report-session/script-tools.js

@@ -0,0 +1,186 @@
+/**
+ * The script tools of a report session: `read_table` over the pinned evidence, and `write_derived`, which pins a
+ * derived table to the session.
+ *
+ * A script reshapes the evidence into the table that a block binds: a join, a pivot, or an aggregate. The script
+ * runs in the VM of `run_script`, thus a derivation starts no container. A table over 16 MiB does not derive.
+ *
+ * `read_table` reads only a member of the served snapshot, and it refuses bytes whose hash is not the pinned hash.
+ * `write_derived` keeps the rules of a session derivation: the output lands under the derived directory of the session,
+ * each declared input must be a member, a name that the session holds is refused, and the record chains the
+ * table to its inputs and to the code of the script. A rerun of a call whose record landed gives that record
+ * back, and it emits the derivation again.
+ */
+import { join } from "node:path";
+import { ok, err } from "neverthrow";
+import { z } from "zod";
+import { createNoopLogger } from "../../lib/console-logger.js";
+import { computeSha256 } from "../../lib/fs-helpers.js";
+import { bindSessionEmit } from "../../provenance/seam.js";
+import { snapshotEntry } from "../../report-model/reference-resolver.js";
+import { isSafeId, reportSessionDerivedDir } from "../../workspace/paths.js";
+import { defineTool, withToolCallRecord } from "../define-tool.js";
+import { openReportThread } from "../report-authoring/authoring-tools.js";
+import { ReadTableOutputSchema, readTableRows, rowsText } from "../script/file-tools.js";
+import { DERIVED_FILE_CAP_BYTES } from "../script/scratch.js";
+import { confinedWrite } from "../workspace/mutator.js";
+import { syncWrittenFile } from "../../workspace/session-files.js";
+function refused(error) {
+    return err({ error, retryable: false });
+}
+const readTableInput = z.object({
+    path: z.string().min(1).describe("The path of a pinned artifact or of a derived table of this session, as `list_pinned_artifacts` gives it."),
+    columns: z.array(z.string()).min(1).optional().describe("Keep only these columns. Absent: each column."),
+});
+function createReadTableTool(deps) {
+    return defineTool({
+        id: "read_table",
+        description: "Read one table of the pinned evidence as rows: CSV, TSV, JSON (an array of flat objects), or parquet, up to 16 MiB. " +
+            "Each row is an object keyed by column, and a cell that holds a plain number reads as a number. " +
+            "A larger table does not derive; tell the user which table is absent.",
+        inputSchema: readTableInput,
+        outputSchema: ReadTableOutputSchema,
+        describeCall: ({ path }) => path,
+        describeResult: (_input, result) => `${String(result.rowCount)} rows`,
+        execute: async ({ path, columns }, ctx) => {
+            const opened = await openReportThread(deps.gateway, ctx.session.scope);
+            if (opened.isErr())
+                return refused(opened.error.detail);
+            const entry = snapshotEntry(opened.value.state.snapshot, path);
+            if (entry === undefined)
+                return refused(`the pinned evidence of this session holds no artifact at ${path}; list_pinned_artifacts gives the paths`);
+            const table = await readTableRows({
+                workspaceFs: deps.workspaceFs,
+                session: ctx.session,
+                path,
+                columns,
+                tooLarge: "a larger table does not derive",
+            });
+            if (table.isErr())
+                return refused(table.error);
+            const hash = computeSha256(table.value.source);
+            if (hash !== entry.hash)
+                return refused(`${path} changed after the session pinned it, thus its bytes are not the evidence of this session`);
+            const { rows } = table.value;
+            return ok(withToolCallRecord({ path, columns: table.value.columns, rowCount: rows.length, rows }, { reads: [{ path, hash }] }));
+        },
+    });
+}
+const writeDerivedInput = z.object({
+    name: z
+        .string()
+        .min(1)
+        .describe("The file name of the table, with no directory, for example 'yield_by_group.csv'. The extension picks the format: .csv, .tsv, or .json."),
+    rows: z
+        .array(z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()])))
+        .describe("The rows of the table, each an object keyed by column."),
+    inputs: z.array(z.string()).min(1).describe("The path of each pinned table that the script read for this table. The record pins the hash of each one."),
+});
+const DerivedOutputSchema = z.object({ path: z.string(), hash: z.string(), columns: z.array(z.string()).readonly() });
+function derivedOutput(record, size, columns) {
+    return withToolCallRecord({ path: record.outputPath, hash: record.outputHash, columns }, { writes: [{ path: record.outputPath, hash: record.outputHash, size }] });
+}
+function createWriteDerivedTool(deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("report-write-derived");
+    const observe = bindSessionEmit(deps.provenance, logger);
+    const observeDerived = (analysisId, threadId, record) => {
+        observe({
+            type: "run-derivation",
+            analysisId,
+            threadId,
+            outputPath: record.outputPath,
+            outputHash: record.outputHash,
+            scriptHash: record.scriptHash,
+            sources: record.sources.map((source) => ({ path: source.path, hash: source.hash })),
+        });
+    };
+    return defineTool({
+        id: "write_derived",
+        description: "Pin one derived table to this session, and give its path for a block to bind. " +
+            "Name each pinned table that the script read in `inputs`. A name that this session already holds is refused, thus a second derivation of one table takes a new name.",
+        inputSchema: writeDerivedInput,
+        outputSchema: DerivedOutputSchema,
+        describeCall: ({ name }) => name,
+        describeResult: (_input, result) => result.path,
+        execute: async ({ name, rows, inputs }, ctx) => {
+            if (ctx.script === undefined)
+                return refused("write_derived runs inside a script only");
+            const opened = await openReportThread(deps.gateway, ctx.session.scope);
+            if (opened.isErr())
+                return refused(opened.error.detail);
+            const { threadId, analysisId, state, derivations } = opened.value;
+            const columns = [...new Set(rows.flatMap((row) => Object.keys(row)))];
+            // A rerun of a call whose record landed gives that record back. The membership holds the output of
+            // the record by now, thus the name test below would refuse the call its own table.
+            const recorded = derivations.find((record) => record.toolCallId === ctx.invocationId);
+            if (recorded !== undefined) {
+                observeDerived(analysisId, threadId, recorded);
+                return ok(derivedOutput(recorded, Buffer.byteLength(rowsText(name, rows) ?? "", "utf8"), columns));
+            }
+            if (!isSafeId(name))
+                return refused("the name is one file name, with no directory, no separator, and no traversal");
+            const text = rowsText(name, rows);
+            if (text === undefined)
+                return refused(`${name} names no table format: end the name in .csv, .tsv, or .json`);
+            const bytes = Buffer.byteLength(text, "utf8");
+            if (bytes > DERIVED_FILE_CAP_BYTES)
+                return refused(`the table is ${String(bytes)} bytes, and the cap of a derived table is ${String(DERIVED_FILE_CAP_BYTES)} bytes`);
+            const sources = [];
+            for (const path of new Set(inputs)) {
+                const entry = snapshotEntry(state.snapshot, path);
+                if (entry === undefined)
+                    return refused(`the pinned evidence of this session holds no artifact at ${path}`);
+                sources.push({ path, hash: entry.hash });
+            }
+            const dir = reportSessionDerivedDir(threadId);
+            const outputPath = `${dir}/${name}`;
+            if (snapshotEntry(state.snapshot, outputPath) !== undefined) {
+                return refused(`the evidence of this session already holds ${outputPath}, thus this table takes a new name`);
+            }
+            const workspaceRoot = await deps.resolveWorkspaceRoot(analysisId);
+            const landed = await confinedWrite({
+                workspaceRoot,
+                analysisId,
+                workingDir: join(workspaceRoot, dir),
+                path: name,
+                content: text,
+                invocationId: ctx.invocationId,
+                beforeLand: undefined,
+                refuseStagedInputs: true,
+            });
+            if (landed.status !== "ok")
+                return refused(`the write of ${outputPath} was refused (${landed.status})`);
+            const record = {
+                outputPath,
+                outputHash: computeSha256(landed.bytes),
+                sources,
+                scriptHash: computeSha256(Buffer.from(ctx.script.code, "utf8")),
+                script: ctx.script.code,
+                toolCallId: ctx.invocationId,
+            };
+            const appended = await deps.derivations.appendDerivation(threadId, record);
+            if (appended.isErr()) {
+                logger.error("the derivation record did not land", { threadId, ...logger.errorFields(appended.error.cause) });
+                return err({ error: "the derivation record did not land, thus the table is not evidence of this session", retryable: true });
+            }
+            if (appended.value === "duplicate")
+                return refused(`another turn recorded ${outputPath} first, thus this table takes a new name`);
+            if (appended.value === "absent")
+                return refused("no report session state row exists to hold the derivation");
+            observeDerived(analysisId, threadId, record);
+            await syncWrittenFile(deps.syncSessionFile, logger, {
+                session: ctx.session,
+                owner: { kind: "thread", threadId },
+                path: outputPath,
+                hash: record.outputHash,
+                size: landed.bytes.length,
+                content: landed.bytes,
+            });
+            return ok(derivedOutput(record, landed.bytes.length, columns));
+        },
+    });
+}
+/** The script tools of a report session. */
+export function createReportScriptTools(deps) {
+    return [createReadTableTool(deps), createWriteDerivedTool(deps)];
+}

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

@@ -1,13 +1,11 @@
 /**
  * generateAnalogyReport — cross-domain analogy report as a sub-agent tool.
  *
- * An inline harness `AgentDefinition` (mirroring `createLiteratureReviewerTool`)
- * driven by `runWithSalvage`. The result reaches the wrapper through one of two
- * submit tools because the output envelope is a union and `defineTool` takes
- * only a top-level object. Neither tool ends the run: the wrapper selects the
- * last accepted report from the recorded calls, else the first blocker. A run
- * with no outcome gets one salvage request, then an `extraction-failed`
- * envelope, so the frontend never renders raw prose.
+ * An inline harness `AgentDefinition` driven by `runWithSalvage`. The reasoner records its report in parts: the
+ * problem with its planned analogies, then each analogy when its search is done. A provider filter can stop a reply in
+ * the middle of a call, and a cut call is lost whole, thus a small part loses little. The wrapper assembles the report
+ * from the last accepted record of each part, else it gives the first blocker. A run with no outcome gets one salvage
+ * request, then an `extraction-failed` envelope, so the frontend never renders raw prose.
  */
 import { z } from "zod";
 import { type AnalogyReport } from "@inflexa-ai/harness/contracts/analogy-report.js";
@@ -15,12 +13,17 @@ import type { Logger } from "../../lib/logger.js";
 import { type LoopStep } from "../../loop/run-loop.js";
 import type { SubAgentRegistrar } from "../../loop/sub-agent.js";
 import type { ToolOutputStore } from "../../loop/tool-output.js";
+import type { AgentDefinition } from "../../loop/types.js";
+import type { ScriptRuntime } from "../script/run-script.js";
 import type { ChatProvider } from "../../providers/types.js";
 import type { UsageRecorder } from "../../billing/usage-recorder.js";
 import { type Tool } from "../define-tool.js";
 import { type BioToolKeys } from "../bio/keys.js";
-/** The last report of a run that its call accepted. The input schema of the tool checked it. */
-export declare function acceptedReportOf(steps: readonly LoopStep[]): AnalogyReport | undefined;
+/**
+ * The report that a run recorded, or nothing when it recorded no problem. The analogies keep the planned order, and a
+ * recorded analogy that the plan does not name follows them. A planned analogy with no record is not loaded.
+ */
+export declare function assembledReportOf(steps: readonly LoopStep[]): AnalogyReport | undefined;
 export declare const generateAnalogyReportInputSchema: z.ZodObject<{
     problem: z.ZodString;
     context: z.ZodOptional<z.ZodString>;
@@ -49,6 +52,10 @@ export type GenerateAnalogyReportDeps = {
     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;
+    /** Where the VM of `run_script` comes from. See {@link ScriptRuntime}. */
+    readonly scriptRuntime?: ScriptRuntime;
 };
 /** Build the `generate_analogy_report` delegation tool bound to its provider. */
+/** The analogical reasoner: its searches run in a script, and it records its report and a blocker directly. */
+export declare function analogyAgentOf(deps: Pick<GenerateAnalogyReportDeps, "bioKeys" | "model" | "toolOutputStore" | "scriptRuntime">): AgentDefinition;
 export declare function createGenerateAnalogyReportTool(deps: GenerateAnalogyReportDeps, registerSubAgent: SubAgentRegistrar): Tool;

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

@@ -1,19 +1,17 @@
 /**
  * generateAnalogyReport — cross-domain analogy report as a sub-agent tool.
  *
- * An inline harness `AgentDefinition` (mirroring `createLiteratureReviewerTool`)
- * driven by `runWithSalvage`. The result reaches the wrapper through one of two
- * submit tools because the output envelope is a union and `defineTool` takes
- * only a top-level object. Neither tool ends the run: the wrapper selects the
- * last accepted report from the recorded calls, else the first blocker. A run
- * with no outcome gets one salvage request, then an `extraction-failed`
- * envelope, so the frontend never renders raw prose.
+ * An inline harness `AgentDefinition` driven by `runWithSalvage`. The reasoner records its report in parts: the
+ * problem with its planned analogies, then each analogy when its search is done. A provider filter can stop a reply in
+ * the middle of a call, and a cut call is lost whole, thus a small part loses little. The wrapper assembles the report
+ * from the last accepted record of each part, else it gives the first blocker. A run with no outcome gets one salvage
+ * request, then an `extraction-failed` envelope, so the frontend never renders raw prose.
  */
 import { errorMessageOf } from "../../lib/thrown.js";
 import { textOf } from "../../lib/unknown-text.js";
 import { ok } from "neverthrow";
 import { z } from "zod";
-import { AnalogyReportSchema } from "@inflexa-ai/harness/contracts/analogy-report.js";
+import { AnalogyProblemSchema, AnalogySchema, } 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";
@@ -33,34 +31,80 @@ 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.";
-const SUBMIT_ANALOGY_REPORT_TOOL_ID = "submit_analogy_report";
-function createSubmitAnalogyReportTool() {
+const ANALOGY_SALVAGE_NUDGE = "You ended without a terminal outcome. Record the problem with record_problem and each analogy with " +
+    "record_analogy now, or call report_blocker if phase 1 cannot run. Do not reply with prose.";
+const RECORD_PROBLEM_TOOL_ID = "record_problem";
+const RECORD_ANALOGY_TOOL_ID = "record_analogy";
+const RecordProblemInputSchema = AnalogyProblemSchema.extend({
+    plannedAnalogies: z
+        .array(z.object({ analogyTitle: z.string(), targetDomain: z.string() }))
+        .min(1)
+        .describe("Each analogy of phase 1. An analogy that gets no record_analogy call arrives in the report as not loaded."),
+});
+function createRecordProblemTool() {
     return defineTool({
-        id: SUBMIT_ANALOGY_REPORT_TOOL_ID,
-        description: "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. The last accepted report is the result.",
-        inputSchema: AnalogyReportSchema,
+        id: RECORD_PROBLEM_TOOL_ID,
+        description: "Record the extraction of phase 1: the problem summary, objects, relations, key terms, and the analogies " +
+            "that phase 2 searches. A later call replaces the record.",
+        inputSchema: RecordProblemInputSchema,
         describeCall: "none",
-        execute: () => Promise.resolve(ok({ recorded: true, message: "Report recorded. Stop now." })),
+        execute: () => Promise.resolve(ok({ recorded: true })),
+    });
+}
+function createRecordAnalogyTool() {
+    return defineTool({
+        id: RECORD_ANALOGY_TOOL_ID,
+        description: "Record one analogy with its coverage and its cited solutions, when its search is done. A later call " +
+            "with the same analogyTitle replaces the record.",
+        inputSchema: AnalogySchema,
+        describeCall: ({ analogyTitle }) => analogyTitle,
+        execute: () => Promise.resolve(ok({ recorded: true })),
     });
 }
-/** The last report of a run that its call accepted. The input schema of the tool checked it. */
-export function acceptedReportOf(steps) {
-    let accepted;
+/** The parts that a run recorded: the last accepted problem, and the last accepted record of each analogy title. */
+function recordedParts(steps) {
+    let problem;
+    const analogies = new Map();
     for (const step of steps) {
         for (const call of step.calls) {
-            if (call.toolName !== SUBMIT_ANALOGY_REPORT_TOOL_ID || call.output?.outcome !== "ok")
+            if (call.output?.outcome !== "ok")
                 continue;
-            accepted = recordedInputOf(AnalogyReportSchema, call.input) ?? accepted;
+            if (call.toolName === RECORD_PROBLEM_TOOL_ID)
+                problem = recordedInputOf(RecordProblemInputSchema, call.input) ?? problem;
+            if (call.toolName === RECORD_ANALOGY_TOOL_ID) {
+                const analogy = recordedInputOf(AnalogySchema, call.input);
+                if (analogy !== undefined)
+                    analogies.set(analogy.analogyTitle, analogy);
+            }
         }
     }
-    return accepted;
+    return { problem, analogies };
+}
+/**
+ * The report that a run recorded, or nothing when it recorded no problem. The analogies keep the planned order, and a
+ * recorded analogy that the plan does not name follows them. A planned analogy with no record is not loaded.
+ */
+export function assembledReportOf(steps) {
+    const { problem, analogies } = recordedParts(steps);
+    if (problem === undefined)
+        return undefined;
+    const { plannedAnalogies, ...extraction } = problem;
+    const planned = plannedAnalogies.map((plan) => analogies.get(plan.analogyTitle) ?? {
+        targetDomain: plan.targetDomain,
+        analogyTitle: plan.analogyTitle,
+        objectMappings: [],
+        sharedRelations: "",
+        coverage: "not_loaded",
+        solutions: [],
+    });
+    const titles = new Set(plannedAnalogies.map((plan) => plan.analogyTitle));
+    const extra = [...analogies.values()].filter((analogy) => !titles.has(analogy.analogyTitle));
+    return { schemaVersion: "1", ...extraction, analogies: [...planned, ...extra] };
+}
+/** The run recorded the problem and each analogy that it planned, thus nothing is left to record. */
+function everyPartRecorded(steps) {
+    const { problem, analogies } = recordedParts(steps);
+    return problem !== undefined && problem.plannedAnalogies.every((plan) => analogies.has(plan.analogyTitle));
 }
 function createAnalogyBlockerTool() {
     return createReportBlockerToolFor({
@@ -124,29 +168,35 @@ export function buildResearchPrompt(input) {
     return lines.join("\n");
 }
 /** Build the `generate_analogy_report` delegation tool bound to its provider. */
+/** The analogical reasoner: its searches run in a script, and it records its report and a blocker directly. */
+export function analogyAgentOf(deps) {
+    const ncbi = createNcbiTools(deps.bioKeys);
+    return {
+        id: AGENT_ID,
+        systemPrompt: composeSystemPrompt(analogicalReasonerPrompt),
+        model: deps.model,
+        // The order and the definitions of the tools stay fixed across calls so the cache-keyed prefix holds.
+        tools: [
+            ...(deps.toolOutputStore ? [createReadToolOutputTool(deps.toolOutputStore)] : []),
+            createRecordProblemTool(),
+            createRecordAnalogyTool(),
+            createAnalogyBlockerTool(),
+        ],
+        scriptTools: [
+            createSearchSemanticScholarTool({ apiKey: deps.bioKeys.semanticScholar }),
+            searchArxivTool,
+            createSearchGithubReposTool({ githubToken: deps.bioKeys.github }),
+            ncbi.pubmed,
+        ],
+        scriptRuntime: deps.scriptRuntime,
+        maxIterations: RESEARCH_MAX_ITERATIONS,
+    };
+}
 export function createGenerateAnalogyReportTool(deps, registerSubAgent) {
     const logger = (deps.logger ?? createNoopLogger()).named("generate-analogy-report");
-    const ncbi = createNcbiTools(deps.bioKeys);
-    const searchTools = [
-        createSearchSemanticScholarTool({ apiKey: deps.bioKeys.semanticScholar }),
-        searchArxivTool,
-        createSearchGithubReposTool({ githubToken: deps.bioKeys.github }),
-        ncbi.pubmed,
-        ...(deps.toolOutputStore ? [createReadToolOutputTool(deps.toolOutputStore)] : []),
-    ];
-    const systemPrompt = composeSystemPrompt(analogicalReasonerPrompt);
     const research = registerSubAgent(AGENT_ID, async ({ payload: input, ctx, loop }) => {
         const childSession = forSubAgent(ctx.session, AGENT_ID);
-        // The order and the definitions of the tools stay fixed across calls so the cache-keyed prefix holds.
-        const submitReportTool = createSubmitAnalogyReportTool();
-        const blockerTool = createAnalogyBlockerTool();
-        const agent = {
-            id: AGENT_ID,
-            systemPrompt,
-            model: deps.model,
-            tools: [...searchTools, submitReportTool, blockerTool],
-            maxIterations: RESEARCH_MAX_ITERATIONS,
-        };
+        const agent = analogyAgentOf(deps);
         let steps;
         try {
             const run = await runWithSalvage(agent, [{ role: "user", content: buildResearchPrompt(input) }], childSession, {
@@ -155,10 +205,12 @@ export function createGenerateAnalogyReportTool(deps, registerSubAgent) {
                 logger,
                 usageRecorder: deps.usageRecorder,
                 toolOutputStore: deps.toolOutputStore,
+                // The run ends when each planned analogy has a record, because the wrapper reads no prose.
+                stopWhen: everyPartRecorded,
             }, {
-                tools: [SUBMIT_ANALOGY_REPORT_TOOL_ID, REPORT_BLOCKER_TOOL_ID],
+                tools: [RECORD_PROBLEM_TOOL_ID, RECORD_ANALOGY_TOOL_ID, REPORT_BLOCKER_TOOL_ID],
                 nudge: ANALOGY_SALVAGE_NUDGE,
-                hasOutcome: (done) => acceptedReportOf(done) !== undefined || blockerOf(done) !== null,
+                hasOutcome: (done) => assembledReportOf(done) !== undefined || blockerOf(done) !== null,
             });
             steps = run.steps;
         }
@@ -173,12 +225,22 @@ export function createGenerateAnalogyReportTool(deps, registerSubAgent) {
             };
         }
         // A report wins over a blocker.
-        const report = acceptedReportOf(steps);
+        const report = assembledReportOf(steps);
         if (report !== undefined)
             return report;
         const blocker = blockerOf(steps);
         if (blocker !== null)
             return { schemaVersion: "1", error: { kind: "extraction-failed", message: blocker.reason } };
+        if (steps.some((step) => step.finishReason === "content-filter")) {
+            logger.warn("the content filter of the provider stopped the analogical reasoner", { steps: steps.length });
+            return {
+                schemaVersion: "1",
+                error: {
+                    kind: "extraction-failed",
+                    message: "The content filter of the model provider stopped the reasoner before it recorded the problem. A different wording of the problem can pass the filter.",
+                },
+            };
+        }
         return buildExtractionFailedEnvelope();
     });
     return defineTool({

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

@@ -22,17 +22,94 @@
  * last accepted plan, else the last clarification, else the first blocker —
  * and persists an accepted plan under an id that a rerun of the call gives again.
  */
+import type { ResolveWorkspaceRoot } from "../../workspace/paths.js";
+import type { ScriptRuntime } from "../script/run-script.js";
+import { type ReadSurfaceDeps } from "../workspace/read-surface.js";
 import type { Pool } from "pg";
+import { z } from "zod";
 import type { SubAgentRegistrar } from "../../loop/sub-agent.js";
 import type { ToolOutputStore } from "../../loop/tool-output.js";
+import type { AgentDefinition } from "../../loop/types.js";
 import { type ChatProvider } from "../../providers/types.js";
 import type { UsageRecorder } from "../../billing/usage-recorder.js";
 import { type Tool } from "../define-tool.js";
 import type { EnvironmentStorePaths } from "../../config/environment-stores.js";
 import { type BioToolKeys } from "../bio/keys.js";
 import { type KnowledgeClient, type KnowledgeRecommendAnswer } from "../knowledge/index.js";
-import { type ResourcePolicy } from "../../config/resource-limits.js";
 import type { Logger } from "../../lib/logger.js";
+import { type DataProfileResult } from "../../state/index.js";
+/** The planner system prompt is deterministic for the process: the catalog is fixed at load. */
+export declare function plannerInstructions(): string;
+/**
+ * Format a loaded prior plan as a markdown block the planner can read —
+ * narrative + one line per step. Used only when `parentPlanId` is set.
+ */
+export declare function formatPriorPlan(parentPlanId: string, plan: unknown): string | null;
+/**
+ * What the planner actually holds about the dataset.
+ *
+ * Every lifecycle state is a variant because every one of them is ordinary: an
+ * analysis can be planned before it has been profiled, while profiling is in
+ * flight, after an attempt failed, and against a profile whose input files have
+ * since changed. None of those is an error, and none of them may stop a plan
+ * being produced — a planner told which state it is in can plan accordingly; a
+ * planner told nothing plans on facts it cannot know are rotten.
+ */
+export type DataGrounding = {
+    kind: "ready";
+    result: DataProfileResult;
+}
+/** A profile IS available, but may not describe the analysis's current inputs. */
+ | {
+    kind: "provisional";
+    result: DataProfileResult;
+    reasons: readonly string[];
+}
+/** Profiling is in flight and no earlier profile exists. */
+ | {
+    kind: "pending";
+}
+/** Profiling failed and no earlier profile exists. */
+ | {
+    kind: "failed";
+    error: string | null;
+}
+/** Never profiled, cleared, or nothing to profile. */
+ | {
+    kind: "absent";
+};
+/**
+ * Render the seed's `## Data Context` from the grounding.
+ *
+ * The facts come from `buildDataProfileOrientation` — the same bounded projector
+ * the sandbox step seed uses, so a step and the plan that produced it are oriented
+ * by identical text. It is not re-derived here, and the planner cannot reach past
+ * it: the planner has no `inspect_data_profile` tool, so what this section does not
+ * say is simply not known to it.
+ *
+ * An absent profile renders NOTHING — no heading, no apology. Planning without
+ * dataset facts is worse-grounded but entirely possible, and a section announcing
+ * its own emptiness is an invitation to fill it. Every other state renders,
+ * including the two that carry no facts either: a planner told that its record is
+ * still being built, or that its facts may have moved, can act on that; one handed
+ * stale facts silently cannot.
+ *
+ * Pure — the same grounding renders the same string.
+ */
+export declare function renderDataContext(grounding: DataGrounding, analysisId: string): string;
+/** The planner agent over its search tools and its terminal tools. */
+export declare function plannerAgentOf(deps: GeneratePlanDeps, searchTools: readonly Tool[], terminal: readonly Tool[]): AgentDefinition;
+/** The terminal tools of a planner with no knowledge answer, for a consumer that runs the planner outside this tool. */
+export declare function plannerTerminalTools(logger: Logger): Tool[];
+/**
+ * Render one environment inventory into the seed, reporting a lookup that failed.
+ *
+ * A failed lookup is written INTO the prompt as prose the planner then plans
+ * around — a silent degradation of its grounding that no caller is told about and
+ * no outcome distinguishes. The record is what makes "the planner produced a plan
+ * naming packages this install does not have" traceable to its cause.
+ */
+export declare function inventoryContent(label: string, result: Awaited<ReturnType<Tool["execute"]>>, logger: Logger): string;
 export type GeneratePlanDeps = EnvironmentStorePaths & {
     /**
      * The conversation-role backend the planner is pinned to. Keeping the
@@ -45,12 +122,6 @@ export type GeneratePlanDeps = EnvironmentStorePaths & {
     };
     /** Database pool — plan persistence and prior-plan loading. */
     readonly pool: Pool;
-    /**
-     * Host resource policy — stated to the planner as concrete per-step
-     * ceilings and enforced by `submit_plan`. Absent, the prompt keeps its
-     * default guidance and validation skips the ceiling check.
-     */
-    readonly resourcePolicy?: ResourcePolicy;
     /** Diagnostic sink. Absent, the tool runs silently — see `LoopOptions.logger`. */
     readonly logger?: Logger;
     /** LLM usage-accounting seam for the planner loop; omitted falls back to the no-op recorder. */
@@ -59,6 +130,12 @@ export type GeneratePlanDeps = EnvironmentStorePaths & {
     readonly toolOutputStore?: ToolOutputStore;
     /** API keys for the search tools the planner uses to ground a plan. */
     readonly bioKeys: BioToolKeys;
+    /** The read-only workspace: the file tools, the search, the data profile, and the script reads of a PDF and a table. */
+    readonly workspace: ReadSurfaceDeps & {
+        readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    };
+    /** Where the VM of `run_script` comes from, for the script reads. See `ScriptRuntime`. */
+    readonly scriptRuntime?: ScriptRuntime;
     /**
      * The knowledge service client. Bound, the planner gains `knowledge_recommend`
      * and `knowledge_check`. Absent, no knowledge tool attaches and no
@@ -82,5 +159,23 @@ export type GeneratePlanDeps = EnvironmentStorePaths & {
 export declare function buildPlannerSearchTools(deps: GeneratePlanDeps, hooks?: {
     readonly onRecommend?: (answer: KnowledgeRecommendAnswer) => void;
 }): Tool[];
+/**
+ * The seed of the planner: the prior plan when the call revises one, the data context, the two censuses, and then
+ * what the caller gave. Each block is optional where the call holds none.
+ */
+export declare function composePlannerSeed(parts: {
+    readonly priorPlanBlock: string | null;
+    readonly dataContextBlock: string;
+    readonly groundingBlock: string;
+    readonly input: Pick<z.infer<typeof generatePlanInputSchema>, "researchQuestion" | "analystNotes" | "priorRuns" | "userConstraints">;
+}): string;
+declare const generatePlanInputSchema: z.ZodObject<{
+    researchQuestion: z.ZodString;
+    analystNotes: z.ZodOptional<z.ZodString>;
+    priorRuns: z.ZodOptional<z.ZodString>;
+    userConstraints: z.ZodOptional<z.ZodString>;
+    parentPlanId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 /** Build the `generate_plan` tool bound to its provider and pool. */
 export declare function createGeneratePlanTool(deps: GeneratePlanDeps, registerSubAgent: SubAgentRegistrar): Tool;
+export {};