@inflexa-ai/harness 0.46.2 → 0.47.0

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 {};

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

@@ -22,6 +22,8 @@
  * 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 { createReadScriptTools } from "../script/file-tools.js";
+import { createReadSurfaceTools } from "../workspace/read-surface.js";
 import { errorMessageOf } from "../../lib/thrown.js";
 import { textOf } from "../../lib/unknown-text.js";
 import { createHash } from "node:crypto";
@@ -51,6 +53,7 @@ import { createSearchSemanticScholarTool } from "./search-semantic-scholar.js";
 import { DATA_PROFILE_ORIENTATION_MAX_CHARS, buildDataProfileOrientation } from "../../app/data-profile-orientation.js";
 import { DEFAULT_SANDBOX_MAX_STEPS } from "../../config/resource-limits.js";
 import { plannerPrompt } from "../../prompts/planner.js";
+import { planCardOf } from "../../memory/card-builders.js";
 import { hydratePlanSteps, PlannerPlanSchema } from "../../schemas/plan-schemas.js";
 import { validatePlan } from "../../schemas/validate-plan.js";
 import { AnalysisPlanSchema } from "../../schemas/workflow-state.js";
@@ -169,10 +172,9 @@ function traceOf(steps) {
     return { submitAttempts, rejectedAttempts, rejections };
 }
 // ── Prompt / catalog ────────────────────────────────────────────────
-/** The planner system prompt is deterministic per policy — build it once per
- *  factory (the policy is a construction-time dep, fixed for the process). */
-function plannerInstructions(resourcePolicy) {
-    return plannerPrompt(formatAgentCatalog(), resourcePolicy);
+/** The planner system prompt is deterministic for the process: the catalog is fixed at load. */
+export function plannerInstructions() {
+    return plannerPrompt(formatAgentCatalog());
 }
 const ValidationIssueSchema = z.object({ path: z.string(), code: z.enum(["schema", "semantic"]), message: z.string(), hint: z.string().optional() });
 const SubmitPlanOutputSchema = z.discriminatedUnion("accepted", [
@@ -226,7 +228,7 @@ function selectedOutcomeOf(steps) {
  * Format a loaded prior plan as a markdown block the planner can read —
  * narrative + one line per step. Used only when `parentPlanId` is set.
  */
-function formatPriorPlan(parentPlanId, plan) {
+export function formatPriorPlan(parentPlanId, plan) {
     const parsed = AnalysisPlanSchema.safeParse(plan);
     if (!parsed.success)
         return null;
@@ -243,10 +245,9 @@ function formatPriorPlan(parentPlanId, plan) {
         "**Steps:**",
         ...stepLines,
         "",
-        "The user is iterating on this plan. Preserve steps and IDs that are " +
-            "not being changed; modify only what `userConstraints` describes. " +
-            "Reuse step IDs when a step's purpose is unchanged so downstream " +
-            "references survive.",
+        "The user is revising this plan, not asking for a new one. The changes are in `## User Constraints`. " +
+            "Each step keeps its id, its agent, and its order, also a step that the user asked to change: apply the change to that step. " +
+            "Thus `depends_on` and the stored artifacts survive. Give a new id to new work only.",
     ].join("\n");
 }
 /**
@@ -305,7 +306,7 @@ const NO_FACTS_GUIDANCE = "Plan from the research question alone, do not invent
  *
  * Pure — the same grounding renders the same string.
  */
-function renderDataContext(grounding, analysisId) {
+export function renderDataContext(grounding, analysisId) {
     switch (grounding.kind) {
         case "absent":
             return "";
@@ -356,7 +357,7 @@ async function persistPlan(plan, ctx, pool, logger) {
         unwrapOrThrow(await upsertPlan(pool, {
             planId,
             analysisId: ctx.analysisId,
-            plan: hydratePlanSteps(plan),
+            plan: { ...hydratePlanSteps(plan), request: ctx.request },
             parentPlanId: ctx.parentPlanId,
         }));
         return { ok: true, planId };
@@ -523,7 +524,7 @@ function restoreSkeletonGrounding(candidate, memory) {
  * Full validation: Zod schema + semantic checks. The plan is valid only if
  * BOTH pass.
  */
-function fullyValidate(candidate, resourcePolicy) {
+function fullyValidate(candidate) {
     // The permissive arg schema of the planner tools accepts a string, thus the
     // loop-boundary repair never sees a plan that a model sent as a JSON-encoded
     // string. A small model does this on a large nested schema. Decode it here,
@@ -546,7 +547,7 @@ function fullyValidate(candidate, resourcePolicy) {
         created_at: parsed.data.created_at,
         omicsType: parsed.data.omicsType,
         omicsSubtype: parsed.data.omicsSubtype,
-    }, { perStepCeiling: resourcePolicy?.perStep });
+    });
     if (!semantic.valid) {
         return {
             valid: false,
@@ -559,11 +560,30 @@ function fullyValidate(candidate, resourcePolicy) {
     }
     return { valid: true, plan: parsed.data };
 }
+/** The planner agent over its search tools and its terminal tools. */
+export function plannerAgentOf(deps, searchTools, terminal) {
+    const readTools = deps.toolOutputStore ? [createReadToolOutputTool(deps.toolOutputStore)] : [];
+    return {
+        id: PLANNER_AGENT_ID,
+        systemPrompt: composeSystemPrompt(plannerInstructions()),
+        model: deps.conversation.model,
+        // 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, ...createReadSurfaceTools(deps.workspace), ...readTools, ...terminal],
+        scriptTools: createReadScriptTools(deps.workspace),
+        scriptRuntime: deps.scriptRuntime,
+        maxIterations: PLANNER_MAX_ITERATIONS,
+    };
+}
+/** The terminal tools of a planner with no knowledge answer, for a consumer that runs the planner outside this tool. */
+export function plannerTerminalTools(logger) {
+    return buildInnerTools(logger, { steps: new Map(), claims: new Set() }).terminal;
+}
 /**
  * Build the planner's inner tools for one invocation. `memory` holds the last
  * `knowledge_recommend` answer of the run, which the loop folds after each round.
  */
-function buildInnerTools(resourcePolicy, logger, memory) {
+function buildInnerTools(logger, memory) {
     const submitPlanTool = defineTool({
         id: SUBMIT_PLAN_TOOL_ID,
         description: "Submit the plan. Checks the plan; on success returns {accepted: true, plan} " +
@@ -592,7 +612,7 @@ function buildInnerTools(resourcePolicy, logger, memory) {
                 logger.info("submit_plan restored the template of skeleton steps", { steps: restored });
             if (repaired.length > 0)
                 logger.info("submit_plan repaired the claim ids of plan steps", { claims: repaired });
-            const result = fullyValidate(candidate, resourcePolicy);
+            const result = fullyValidate(candidate);
             // An unknown claim rejects a plan that the schema accepts, beside the
             // schema issues when the schema rejects it, thus one attempt shows both.
             if (!result.valid || unknown.length > 0) {
@@ -644,7 +664,7 @@ function buildInnerTools(resourcePolicy, logger, memory) {
  * no outcome distinguishes. The record is what makes "the planner produced a plan
  * naming packages this install does not have" traceable to its cause.
  */
-function inventoryContent(label, result, logger) {
+export function inventoryContent(label, result, logger) {
     if (result.isErr()) {
         logger.warn("planner grounding inventory lookup failed", { inventory: label, error: result.error.error });
         return `## ${label}\n\nInventory lookup failed: ${result.error.error}`;
@@ -855,8 +875,28 @@ export function buildPlannerSearchTools(deps, hooks = {}) {
         }),
     ];
 }
+/**
+ * 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 function composePlannerSeed(parts) {
+    const { priorPlanBlock, dataContextBlock, groundingBlock, input } = parts;
+    return [
+        ...(priorPlanBlock ? [priorPlanBlock, ""] : []),
+        ...(dataContextBlock ? [dataContextBlock, ""] : []),
+        groundingBlock,
+        "",
+        "## Research Question",
+        input.researchQuestion,
+        ...(input.analystNotes ? ["", "## Analyst Notes (from the user — facts about the data the profile does not record)", input.analystNotes] : []),
+        ...(input.priorRuns ? ["", "## Prior Run Results", input.priorRuns] : []),
+        ...(input.userConstraints ? ["", "## User Constraints", input.userConstraints] : []),
+    ].join("\n");
+}
 const generatePlanInputSchema = z.object({
-    researchQuestion: z.string().describe("What the user wants to analyze — their goal and specific questions."),
+    researchQuestion: z
+        .string()
+        .describe("The request of the user, in the words of the user: the goal, the questions, and each deliverable that the user named, with its format. The plan stores it, and each step of the run reads it."),
     analystNotes: z
         .string()
         .optional()
@@ -983,17 +1023,7 @@ export function createGeneratePlanTool(deps, registerSubAgent) {
             const refsBlock = inventoryContent("Available Reference Data", refsResult, logger);
             const packagesBlock = inventoryContent("Available Packages", packagesResult, logger);
             const groundingBlock = [refsBlock, packagesBlock].join("\n\n");
-            const prompt = [
-                ...(priorPlanBlock ? [priorPlanBlock, ""] : []),
-                ...(dataContextBlock ? [dataContextBlock, ""] : []),
-                groundingBlock,
-                "",
-                "## Research Question",
-                input.researchQuestion,
-                ...(input.analystNotes ? ["", "## Analyst Notes (from the user — facts about the data the profile does not record)", input.analystNotes] : []),
-                ...(input.priorRuns ? ["", "## Prior Run Results", input.priorRuns] : []),
-                ...(input.userConstraints ? ["", "## User Constraints", input.userConstraints] : []),
-            ].join("\n");
+            const prompt = composePlannerSeed({ priorPlanBlock, dataContextBlock, groundingBlock, input });
             return {
                 prompt,
                 grounding: grounding.kind,
@@ -1037,13 +1067,14 @@ export function createGeneratePlanTool(deps, registerSubAgent) {
             analysisId,
             parentPlanId: input.parentPlanId ?? null,
             invocationId: ctx.invocationId,
+            request: input.researchQuestion,
         };
         // The last recommend answer of this invocation, thus `submit_plan`
         // stamps the snapshot digest, restores a template the model dropped,
         // and repairs or refuses a claim id the answer did not return. The loop
         // folds each answer after its round, on the first run and on a replay.
         const memory = { steps: new Map(), claims: new Set() };
-        const innerTools = buildInnerTools(deps.resourcePolicy, logger, memory);
+        const innerTools = buildInnerTools(logger, memory);
         // Built here rather than at construction: a `describeCall` hook reads no
         // dep, thus the tool must stay constructible from an empty bag. The tool
         // definitions are identical across invocations, thus the request prefix
@@ -1051,17 +1082,7 @@ export function createGeneratePlanTool(deps, registerSubAgent) {
         const searchTools = buildPlannerSearchTools(deps, {
             onRecommend: (answer) => rememberAnswer(memory, answer),
         });
-        const readTools = deps.toolOutputStore ? [createReadToolOutputTool(deps.toolOutputStore)] : [];
-        const planner = {
-            id: PLANNER_AGENT_ID,
-            systemPrompt: composeSystemPrompt(plannerInstructions(deps.resourcePolicy)),
-            model: deps.conversation.model,
-            // 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, ...readTools, ...innerTools.terminal],
-            maxIterations: PLANNER_MAX_ITERATIONS,
-        };
+        const planner = plannerAgentOf(deps, searchTools, innerTools.terminal);
         // Merge the outer abort signal with a wall-clock timeout — either
         // cancels the planner promptly.
         const signal = AbortSignal.any([ctx.signal, AbortSignal.timeout(planTimeoutMs)]);
@@ -1155,13 +1176,23 @@ export function createGeneratePlanTool(deps, registerSubAgent) {
             "record more faithfully than the record itself. Pass only what the profile cannot hold: the research " +
             "question, facts the user told you (analystNotes), prior run results, and their constraints. " +
             "The planner is a multi-step sub-agent, thus a call can take many minutes. " +
-            "The result carries an `event`: `plan_complete` with {planId, plan} — the plan is saved and ready for show_plan and " +
-            "execute_analysis plan mode, and this call neither shows nor runs it; `clarification_needed` with {question, questionContext?} " +
+            "The result carries an `event`: `plan_complete` with {planId, plan} — the plan is saved, the call shows its plan card to the user, " +
+            "and it does not run it (execute_analysis plan mode does, after the approval); `clarification_needed` with {question, questionContext?} " +
             "when the planner is missing a fact it cannot infer; or `error` with {error} when no plan was saved (the planner reported " +
             "a blocker, the save failed, the call timed out or was cancelled, or parentPlanId is not a plan of this analysis).",
         inputSchema: generatePlanInputSchema,
         describeCall: ({ researchQuestion }) => researchQuestion,
         startsWorkflow: true,
-        execute: async (input, ctx) => ok(await plan(input, ctx)),
+        execute: async (input, ctx) => {
+            const output = await plan(input, ctx);
+            // The card comes from the result of the planner, with no read of the store, thus a replay of the body
+            // gives the same card under the same id, and a reader keeps one card.
+            if (output.event === "plan_complete" && output.planId !== undefined && output.plan !== undefined) {
+                const card = planCardOf({ planId: output.planId, plan: hydratePlanSteps(output.plan), parentPlanId: input.parentPlanId ?? null });
+                if (card !== null)
+                    await ctx.emit({ type: "data-plan", source: ctx.session.provenance, data: card });
+            }
+            return ok(output);
+        },
     });
 }

package/dist/tools/research/index.d.ts

@@ -1,14 +1,15 @@
 /**
  * Research barrel — dependency-bearing planning, run inspection, the
- * literature-reviewer and analogical-reasoner sub-agents, developer-docs
- * lookup, and the cross-domain search tools the analogical-reasoner uses.
+ * analogical-reasoner sub-agent, the lookups of the run synthesizer,
+ * developer-docs lookup, and the cross-domain search tools the
+ * analogical-reasoner uses.
  * Dep-bearing tools are factory closures (`createXTool(deps)`); pure tools
  * are module-scope `defineTool` values.
  */
 export * from "./generate-plan.js";
 export * from "./inspect-run.js";
 export * from "./inspect-data-profile.js";
-export * from "./literature-reviewer.js";
+export * from "./synthesis-lookups.js";
 export * from "./generate-analogy-report.js";
 export * from "./context7-docs.js";
 export * from "./search-semantic-scholar.js";

package/dist/tools/research/index.js

@@ -1,14 +1,15 @@
 /**
  * Research barrel — dependency-bearing planning, run inspection, the
- * literature-reviewer and analogical-reasoner sub-agents, developer-docs
- * lookup, and the cross-domain search tools the analogical-reasoner uses.
+ * analogical-reasoner sub-agent, the lookups of the run synthesizer,
+ * developer-docs lookup, and the cross-domain search tools the
+ * analogical-reasoner uses.
  * Dep-bearing tools are factory closures (`createXTool(deps)`); pure tools
  * are module-scope `defineTool` values.
  */
 export * from "./generate-plan.js";
 export * from "./inspect-run.js";
 export * from "./inspect-data-profile.js";
-export * from "./literature-reviewer.js";
+export * from "./synthesis-lookups.js";
 export * from "./generate-analogy-report.js";
 export * from "./context7-docs.js";
 export * from "./search-semantic-scholar.js";