@inflexa-ai/harness 0.45.1 → 0.46.0

package/dist/tools/report-session/page-faults.js

@@ -8,8 +8,10 @@ const MAX_FAULT_TEXT = 300;
 /** The most distinct entries of one list. */
 const MAX_FAULT_ENTRIES = 20;
 /** A data URI. A fault text quotes a URI in quotes or parentheses, thus those characters end the data. */
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the data-URI grammar of an inlined fault (media type, parameters, payload) with the quote and bracket characters that end it.
 const DATA_URI = /data:([a-z0-9.+-]+\/[a-z0-9.+-]+)?((?:;[^,;\s'"()<>]*)*),([^\s'"()<>]*)/gi;
 /** A base64 run of 100 characters or more. A content hash in hex is 64 characters, thus a hash stays. */
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the base64 charset run with its padding; the length floor keeps a 64-character hex hash outside the match.
 const BASE64_RUN = /[A-Za-z0-9+/]{100,}={0,2}/g;
 /** Shorten one fault text: the inline data becomes placeholders, and the text stops at the cap. */
 export function shortenFaultText(text) {
@@ -43,6 +45,6 @@ export function digestPageFaults(consoleErrors, failedRequests) {
     return {
         consoleErrors: errors.slice(0, MAX_FAULT_ENTRIES),
         failedRequests: requests.slice(0, MAX_FAULT_ENTRIES),
-        ...(omittedErrors + omittedRequests > 0 ? { omittedFaults: { consoleErrors: omittedErrors, failedRequests: omittedRequests } } : {}),
+        omittedFaults: omittedErrors + omittedRequests > 0 ? { consoleErrors: omittedErrors, failedRequests: omittedRequests } : undefined,
     };
 }

package/dist/tools/report-session/preview-report.d.ts

@@ -39,7 +39,7 @@
  */
 import { z } from "zod";
 import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
-import type { AuthContext } from "../../auth/types.js";
+import type { AuthContext, Identity } from "../../auth/types.js";
 import { type Logger } from "../../lib/logger.js";
 import type { ThreadStore } from "../../memory/thread-store.js";
 import { type ReportWarning } from "../../report-model/block-walk.js";
@@ -134,10 +134,11 @@ export type ResolvePageAsset = (specifier: string) => string;
  * lands, and attaches the URL beside the path. A refused mint rides the `rendered` arm as data, and it
  * never fails the render.
  */
-export interface PreviewReportToolDeps {
+export type PreviewReportToolDeps = {
     readonly gateway: ReportSessionStateGateway;
     readonly makeResolver?: (scope: {
         analysisId: string;
+        identity: Identity;
         auth: AuthContext;
     }) => Promise<ReferenceResolver>;
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
@@ -152,7 +153,7 @@ export interface PreviewReportToolDeps {
     /** Names the report thread after the rendered document. Omitted, the thread keeps its title. */
     readonly threads?: Pick<ThreadStore, "setAutoTitle">;
     readonly logger?: Logger;
-}
+};
 /**
  * Make the render-and-preview tool over the session-state gateway and the render seams.
  *

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

@@ -38,7 +38,6 @@
  * control-flow exception propagate.
  */
 import { err, ok } from "neverthrow";
-import { randomUUID } from "node:crypto";
 import { copyFile, mkdir, readdir, rm, writeFile } from "node:fs/promises";
 import { extname, join } from "node:path";
 import { relative as relativePosix } from "node:path/posix";
@@ -70,9 +69,26 @@ const previewReportInput = z.object({});
  * collide on the staged name.
  */
 function assetFileName(file) {
-    const slug = file.hash.replace(/[^a-z0-9]+/gi, "-");
+    const slug = dashUnsafeRuns(file.hash);
     return slug + extname(file.path);
 }
+/** Each run of characters outside the letters and digits becomes one dash. */
+function dashUnsafeRuns(text) {
+    let out = "";
+    let inRun = false;
+    for (const char of text) {
+        const isNameChar = (char >= "a" && char <= "z") || (char >= "A" && char <= "Z") || (char >= "0" && char <= "9");
+        if (isNameChar) {
+            out += char;
+            inRun = false;
+        }
+        else if (!inRun) {
+            out += "-";
+            inRun = true;
+        }
+    }
+    return out;
+}
 /** The relative source of a staged figure. The page directory is self-contained, thus the source is `assets/<name>`. */
 function figureSourcePolicy(file) {
     return `assets/${assetFileName(file)}`;
@@ -360,7 +376,6 @@ export function createPreviewReportTool(deps) {
             "The render marks the page that examine_page looks at next. " +
             "Use it to see the report, and to confirm that each reference resolves.",
         inputSchema: previewReportInput,
-        executionMode: "inline",
         describeCall: "none",
         // The page path is the one fact of a preview that a watcher wants, and it exists only in the
         // result. Each other arm is a degraded condition whose kind already names it, thus the kind
@@ -387,7 +402,7 @@ export function createPreviewReportTool(deps) {
             // control-flow exception propagates and the unresolvable root does not.
             let resolver;
             try {
-                resolver = await deps.makeResolver({ analysisId, auth: ctx.session.auth });
+                resolver = await deps.makeResolver({ analysisId, identity: ctx.session.identity, auth: ctx.session.auth });
             }
             catch (cause) {
                 logger.warn("the workspace root did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });
@@ -464,16 +479,20 @@ export function createPreviewReportTool(deps) {
                 }
             }
             // The part rides the rendered arm only. Each degraded arm shows no
-            // fresh page, thus it emits nothing.
+            // fresh page, thus it emits nothing. The part id is the id of the call,
+            // thus a rerun of the call gives the same part again.
             await ctx.emit({
                 type: "data-report-rendered",
-                data: { id: randomUUID(), renderedAt: new Date().toISOString(), title: document.title },
+                data: { id: ctx.invocationId, renderedAt: new Date().toISOString(), title: document.title },
             });
             // The event rides the rendered arm alone, the same as the part above. The hash is the hash of
             // the draft that the page shows, thus a consumer ties the page to the document that made it.
             observe({ type: "preview", analysisId, threadId, pagePath: written.value, documentHash: renderedHash });
             const access = await mintAccess(deps.makeSessionPages, analysisId, threadId, ctx.session.auth, logger);
-            return ok({ outcome: "rendered", pagePath: written.value, ...(access !== undefined ? { access } : {}), warnings: finished.warnings });
+            const renderedOk = { outcome: "rendered", pagePath: written.value, warnings: finished.warnings };
+            if (access !== undefined)
+                return ok({ ...renderedOk, access });
+            return ok(renderedOk);
         },
     });
 }

package/dist/tools/report-session/record-version.d.ts

@@ -21,7 +21,9 @@
  * the thread row. A record on a thread that holds a version replaces that version whole, under the same
  * version id. Thus the loop is unbounded: the agent amends, looks again, and records again, and the stored
  * version equals the page that the last look accepted. A refused record leaves the stored version as it was.
- * The outcome of a pass carries the version id, and it names a replacement.
+ * The outcome of a pass carries the version id, and it names a replacement. Inside a durable step, the id
+ * of a new version is the UUIDv5 of the key of the step. Thus a rerun of the step gives the same version, and
+ * it does not read as a replacement.
  *
  * The prune runs after the version lands. It removes the output file of each derivation that the recorded
  * document does not reference, under the `derived/` directory of the session alone. The records stay
@@ -29,7 +31,7 @@
  * changes no outcome.
  */
 import { z } from "zod";
-import type { AuthContext } from "../../auth/types.js";
+import type { AuthContext, Identity } from "../../auth/types.js";
 import type { Logger } from "../../lib/logger.js";
 import type { ThreadStore } from "../../memory/thread-store.js";
 import { type ReportWarning } from "../../report-model/block-walk.js";
@@ -97,19 +99,22 @@ export type RecordVersionResult = {
  * derived directory of the session under that root, thus the seam is mandatory: a composition that bound
  * none would record a version and leave every unused derivation on disk.
  */
-export interface RecordVersionToolDeps {
+export type RecordVersionToolDeps = {
     readonly gateway: ReportSessionStateGateway;
     readonly store: ReportVersionStore;
     readonly threads: Pick<ThreadStore, "getThread">;
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
     readonly makeResolver?: (scope: {
         analysisId: string;
+        identity: Identity;
         auth: AuthContext;
     }) => Promise<ReferenceResolver>;
     /** The provenance seam; an unbound session emit emits nothing and the record runs the same. */
     readonly provenance?: ProvenanceSeam;
     readonly logger?: Logger;
-}
+    /** The key of the durable step that runs the call, `undefined` outside one. Defaults to {@link durableStepKey}. */
+    readonly stepKey?: () => string | undefined;
+};
 /**
  * Make the record tool over the session-state gateway, the version store, the thread store, and the
  * resolver.

package/dist/tools/report-session/record-version.js

@@ -21,7 +21,9 @@
  * the thread row. A record on a thread that holds a version replaces that version whole, under the same
  * version id. Thus the loop is unbounded: the agent amends, looks again, and records again, and the stored
  * version equals the page that the last look accepted. A refused record leaves the stored version as it was.
- * The outcome of a pass carries the version id, and it names a replacement.
+ * The outcome of a pass carries the version id, and it names a replacement. Inside a durable step, the id
+ * of a new version is the UUIDv5 of the key of the step. Thus a rerun of the step gives the same version, and
+ * it does not read as a replacement.
  *
  * The prune runs after the version lands. It removes the output file of each derivation that the recorded
  * document does not reference, under the `derived/` directory of the session alone. The records stay
@@ -41,6 +43,7 @@ import { computeDraftHash } from "../../report-model/draft-hash.js";
 import { validateReport } from "../../report-model/validate.js";
 import { reportSessionDerivedDir, resolveWorkspacePath } from "../../workspace/paths.js";
 import { defineTool } from "../define-tool.js";
+import { durableStepKey, stepUuid } from "../workspace/edit-file.js";
 import { openReportThread } from "../report-authoring/authoring-tools.js";
 import { bindSessionEmit } from "../../provenance/seam.js";
 /** The empty input. The tool records the current draft of the thread, thus it needs no field. */
@@ -124,6 +127,7 @@ async function pruneUnusedDerivations(args) {
 export function createRecordVersionTool(deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("record-report-version");
     const observe = bindSessionEmit(deps.provenance, logger);
+    const stepKey = deps.stepKey ?? durableStepKey;
     return defineTool({
         id: "record_report_version",
         description: "Record the current draft as one report version. The tool runs the whole gate first: it finishes the draft, " +
@@ -134,7 +138,6 @@ export function createRecordVersionTool(deps) {
             "A thread holds one version, thus a later record replaces it whole. Amend the draft, look at the page again, and record again. " +
             "After the version lands, the tool removes the file of each derived table that no block of the recorded report binds.",
         inputSchema: recordVersionInput,
-        executionMode: "inline",
         describeCall: "none",
         // The version id is the one durable product of the first record, thus the created arm names it. A
         // later record writes over that same id, thus the line names the update and never reads as a
@@ -174,7 +177,7 @@ export function createRecordVersionTool(deps) {
             // control-flow exception propagates and the unresolvable root does not.
             let resolver;
             try {
-                resolver = await deps.makeResolver({ analysisId, auth: ctx.session.auth });
+                resolver = await deps.makeResolver({ analysisId, identity: ctx.session.identity, auth: ctx.session.auth });
             }
             catch (cause) {
                 logger.warn("the workspace root did not resolve", { threadId, analysisId, ...logger.errorFields(cause) });
@@ -182,12 +185,14 @@ export function createRecordVersionTool(deps) {
             }
             const validation = await validateReport(finished.document, snapshot, resolver);
             if (!validation.valid) {
-                return ok({
-                    outcome: "invalid",
-                    ...(validation.schemaIssues ? { schemaIssues: validation.schemaIssues } : {}),
-                    ...(validation.duplicateIds ? { duplicateIds: validation.duplicateIds } : {}),
-                    ...(validation.resolutionFailures ? { resolutionFailures: validation.resolutionFailures } : {}),
-                });
+                const invalid = { outcome: "invalid" };
+                if (validation.schemaIssues)
+                    invalid.schemaIssues = validation.schemaIssues;
+                if (validation.duplicateIds)
+                    invalid.duplicateIds = validation.duplicateIds;
+                if (validation.resolutionFailures)
+                    invalid.resolutionFailures = validation.resolutionFailures;
+                return ok(invalid);
             }
             const thread = await deps.threads.getThread(threadId);
             if (thread.isErr()) {
@@ -205,6 +210,8 @@ export function createRecordVersionTool(deps) {
                 threadId,
                 parentThreadId: thread.value.parentThreadId,
                 parentSeq: thread.value.parentSeq,
+                // A rerun of the step gives the same id, thus the version that its first run made reads as created.
+                versionId: stepUuid(stepKey()),
             });
             if (recorded.isOk()) {
                 // The version stands from here, thus the event states a version that a reader can open.

package/dist/tools/report-session/session-page-publisher.d.ts

@@ -17,18 +17,18 @@
 import { type ResultAsync } from "neverthrow";
 import type { AuthContext } from "../../auth/types.js";
 /** The grant of one session page: the content-server base, the token, and its expiry. */
-export interface SessionPageGrant {
+export type SessionPageGrant = {
     readonly baseUrl: string;
     readonly token: string;
     readonly expiresAt: string;
-}
+};
 /** What a failed mint is allowed to carry. */
-export interface SessionPageMintFailure {
+export type SessionPageMintFailure = {
     readonly status?: number;
     readonly error: {
         readonly message?: string;
     };
-}
+};
 /**
  * Renders a failed mint as the line an agent reads back from the preview tool.
  *
@@ -38,7 +38,7 @@ export interface SessionPageMintFailure {
  * It lives beside the type because its whole job is to honour that type's optionality.
  */
 export declare function describeSessionPageMintFailure(failure: SessionPageMintFailure): string;
-export interface SessionPagePublisher {
+export type SessionPagePublisher = {
     /**
      * Mint the access grant of one session page. The publisher binds the analysis, thus the mint takes
      * the thread id alone. `baseUrl` is the base URL of the content server, with no res path — the
@@ -46,7 +46,7 @@ export interface SessionPagePublisher {
      * contract and never in a realization.
      */
     mintSessionPageAccess(threadId: string): ResultAsync<SessionPageGrant, SessionPageMintFailure>;
-}
+};
 /**
  * The per-call construction of the publisher. The factory binds one analysis and the auth of the tool
  * call, thus a realization mints under the credential of the caller and holds no ambient state.

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

@@ -2,18 +2,25 @@
  * generateAnalogyReport — cross-domain analogy report as a sub-agent tool.
  *
  * An inline harness `AgentDefinition` (mirroring `createLiteratureReviewerTool`)
- * driven by `runToTerminal`. The result reaches the wrapper through one of two
- * terminal tools because the output envelope is a union and `defineTool` takes
- * only a top-level object. A run with no outcome gets one salvage continuation,
- * then an `extraction-failed` envelope, so the frontend never renders raw prose.
+ * 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.
  */
 import { z } from "zod";
+import { type AnalogyReport } from "@inflexa-ai/harness/contracts/analogy-report.js";
 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 { 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;
 export declare const generateAnalogyReportInputSchema: z.ZodObject<{
     problem: z.ZodString;
     context: z.ZodOptional<z.ZodString>;
@@ -29,7 +36,7 @@ export type GenerateAnalogyReportInput = z.infer<typeof generateAnalogyReportInp
  * Exported for unit testing.
  */
 export declare function buildResearchPrompt(input: GenerateAnalogyReportInput): string;
-export interface GenerateAnalogyReportDeps {
+export type GenerateAnalogyReportDeps = {
     /** The LLM seam the child loop runs on. */
     readonly provider: ChatProvider;
     /** Model id — provenance / metric label; the provider owns the wire model. */
@@ -42,6 +49,6 @@ export interface 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;
-}
+};
 /** Build the `generate_analogy_report` delegation tool bound to its provider. */
-export declare function createGenerateAnalogyReportTool(deps: GenerateAnalogyReportDeps): Tool;
+export declare function createGenerateAnalogyReportTool(deps: GenerateAnalogyReportDeps, registerSubAgent: SubAgentRegistrar): Tool;

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

@@ -2,11 +2,15 @@
  * generateAnalogyReport — cross-domain analogy report as a sub-agent tool.
  *
  * An inline harness `AgentDefinition` (mirroring `createLiteratureReviewerTool`)
- * driven by `runToTerminal`. The result reaches the wrapper through one of two
- * terminal tools because the output envelope is a union and `defineTool` takes
- * only a top-level object. A run with no outcome gets one salvage continuation,
- * then an `extraction-failed` envelope, so the frontend never renders raw prose.
+ * 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.
  */
+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";
@@ -14,11 +18,11 @@ import { analogicalReasonerPrompt } from "../../prompts/analogical-reasoner.js";
 import { composeSystemPrompt } from "../../agents/system-prompt.js";
 import { forSubAgent } from "../../auth/types.js";
 import { createNoopLogger } from "../../lib/console-logger.js";
-import { passthroughStep } from "../../loop/run-step.js";
-import { runToTerminal } from "../../loop/run-to-terminal.js";
+import { runWithSalvage } from "../../loop/run-loop.js";
+import { recordedInputOf } from "../../loop/tool-adapter.js";
 import { defineTool } from "../define-tool.js";
 import { createReadToolOutputTool } from "../read-tool-output.js";
-import { createReportBlockerToolFor } from "../sandbox/report-blocker.js";
+import { blockerOf, createReportBlockerToolFor, REPORT_BLOCKER_TOOL_ID } from "../sandbox/report-blocker.js";
 // Cross-domain search tools the analogical-reasoner uses.
 import { createSearchSemanticScholarTool } from "./search-semantic-scholar.js";
 import { searchArxivTool } from "./search-arxiv.js";
@@ -32,33 +36,34 @@ const RESEARCH_MAX_ITERATIONS = 40;
 const ANALOGY_SALVAGE_NUDGE = "You ended without a terminal outcome. Call submit_analogy_report with " +
     "your report now, or report_blocker if phase 1 cannot run. Do not reply " +
     "with prose.";
-function createSubmitAnalogyReportTool(cell) {
+const SUBMIT_ANALOGY_REPORT_TOOL_ID = "submit_analogy_report";
+function createSubmitAnalogyReportTool() {
     return defineTool({
-        id: "submit_analogy_report",
-        description: "Terminal. Submit the analogy report: the problem summary, objects, " +
+        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. An accepted call ends the run.",
+            "names and call it again. The last accepted report is the result.",
         inputSchema: AnalogyReportSchema,
         describeCall: "none",
-        execute: async (report) => {
-            // A report replaces a blocker, thus the report wins when one round records both.
-            cell.outcome = { kind: "report", report };
-            return ok({
-                recorded: true,
-                message: "Report recorded.",
-            });
-        },
+        execute: () => Promise.resolve(ok({ recorded: true, message: "Report recorded. Stop now." })),
     });
 }
-function createAnalogyBlockerTool(cell) {
+/** The last report of a run that its call accepted. The input schema of the tool checked it. */
+export function acceptedReportOf(steps) {
+    let accepted;
+    for (const step of steps) {
+        for (const call of step.calls) {
+            if (call.toolName !== SUBMIT_ANALOGY_REPORT_TOOL_ID || call.output?.outcome !== "ok")
+                continue;
+            accepted = recordedInputOf(AnalogyReportSchema, call.input) ?? accepted;
+        }
+    }
+    return accepted;
+}
+function createAnalogyBlockerTool() {
     return createReportBlockerToolFor({
-        // A blocker never replaces a recorded outcome, thus it never replaces a report.
-        record: (outcome) => {
-            if (cell.outcome === null)
-                cell.outcome = outcome;
-        },
         blockedWhen: "Ends the analogy research with no report. Call it only when the " +
             "problem is empty or incoherent, thus phase 1 cannot extract its " +
             "objects and relations.",
@@ -119,17 +124,63 @@ export function buildResearchPrompt(input) {
     return lines.join("\n");
 }
 /** Build the `generate_analogy_report` delegation tool bound to its provider. */
-export function createGenerateAnalogyReportTool(deps) {
+export function createGenerateAnalogyReportTool(deps, registerSubAgent) {
     const logger = (deps.logger ?? createNoopLogger()).named("generate-analogy-report");
     const ncbi = createNcbiTools(deps.bioKeys);
     const searchTools = [
-        createSearchSemanticScholarTool({ ...(deps.bioKeys.semanticScholar === undefined ? {} : { apiKey: deps.bioKeys.semanticScholar }) }),
+        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,
+        };
+        let steps;
+        try {
+            const run = await runWithSalvage(agent, [{ role: "user", content: buildResearchPrompt(input) }], childSession, {
+                ...loop,
+                provider: deps.provider,
+                logger,
+                usageRecorder: deps.usageRecorder,
+                toolOutputStore: deps.toolOutputStore,
+            }, {
+                tools: [SUBMIT_ANALOGY_REPORT_TOOL_ID, REPORT_BLOCKER_TOOL_ID],
+                nudge: ANALOGY_SALVAGE_NUDGE,
+                hasOutcome: (done) => acceptedReportOf(done) !== undefined || blockerOf(done) !== null,
+            });
+            steps = run.steps;
+        }
+        catch (err) {
+            const message = errorMessageOf(err) ?? textOf(err);
+            return {
+                schemaVersion: "1",
+                error: {
+                    kind: "extraction-failed",
+                    message: `Analogy research failed: ${message}`.slice(0, 240),
+                },
+            };
+        }
+        // A report wins over a blocker.
+        const report = acceptedReportOf(steps);
+        if (report !== undefined)
+            return report;
+        const blocker = blockerOf(steps);
+        if (blocker !== null)
+            return { schemaVersion: "1", error: { kind: "extraction-failed", message: blocker.reason } };
+        return buildExtractionFailedEnvelope();
+    });
     return defineTool({
         id: "generate_analogy_report",
         description: "Idea-generation engine. Extracts structural analogies for an open-ended " +
@@ -156,55 +207,8 @@ export function createGenerateAnalogyReportTool(deps) {
             "failure, thus surface the message and ask the user to narrow the problem.",
         inputSchema: generateAnalogyReportInputSchema,
         describeCall: "none",
-        execute: async (input, ctx) => {
-            const childSession = forSubAgent(ctx.session, AGENT_ID);
-            // Each call builds fresh tool closures over its own cell. Their order and
-            // definitions stay fixed across calls so the cache-keyed prefix holds.
-            const cell = { outcome: null };
-            const submitReportTool = createSubmitAnalogyReportTool(cell);
-            const blockerTool = createAnalogyBlockerTool(cell);
-            const agent = {
-                id: AGENT_ID,
-                systemPrompt,
-                model: deps.model,
-                tools: [...searchTools, submitReportTool, blockerTool],
-                maxIterations: RESEARCH_MAX_ITERATIONS,
-            };
-            try {
-                await runToTerminal(agent, [{ role: "user", content: buildResearchPrompt(input) }], childSession, {
-                    provider: deps.provider,
-                    signal: ctx.signal,
-                    emit: ctx.emit,
-                    runStep: passthroughStep,
-                    resolved: () => cell.outcome !== null,
-                    logger,
-                    usageRecorder: deps.usageRecorder,
-                    toolOutputStore: deps.toolOutputStore,
-                    // Fold the child's calls into the turn total the root loop reports.
-                    turnUsage: ctx.turnUsage,
-                    // Keeps the usage record keys of two parallel dispatches disjoint —
-                    // same frame, same call path, same loop-local step names.
-                    invocationId: ctx.invocationId,
-                }, { tools: [submitReportTool, blockerTool], nudge: ANALOGY_SALVAGE_NUDGE });
-            }
-            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),
-                    },
-                });
-            }
-            const outcome = cell.outcome;
-            if (outcome?.kind === "report")
-                return ok(outcome.report);
-            if (outcome?.kind === "blocker") {
-                return ok({ schemaVersion: "1", error: { kind: "extraction-failed", message: outcome.reason } });
-            }
-            return ok(buildExtractionFailedEnvelope());
-        },
+        startsWorkflow: true,
+        execute: async (input, ctx) => ok(await research(input, ctx)),
     });
 }
 /** The envelope of a run that recorded no outcome, also after its salvage. */

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

@@ -1,6 +1,6 @@
 /**
- * generatePlan — a loop-driving tool: a focused `runAgent` loop that builds
- * an analysis plan (a DAG of steps).
+ * generatePlan — a loop-driving tool: a focused agent loop that builds an
+ * analysis plan (a DAG of steps).
  *
  * The dataset's facts are NOT an input. They are read here, server-side, from
  * the analysis's persisted data profile — the one durable record of what the
@@ -10,20 +10,20 @@
  * caller-typed dataset summary would be a model re-transcribing a record the
  * database already holds, and it would lose fidelity at every hop.
  *
- * The tool drives an internal "planner" agent that communicates outcomes
- * EXCLUSIVELY via three terminal tool calls:
+ * The tool drives an internal "planner" agent that gives its outcome through
+ * three terminal tools. None of them ends the run, and none writes:
  *
- *   - submit_plan(plan)         → terminal success: re-validates + persists;
- *                                 rejected candidates return structured issues
- *   - request_clarification(…)  → terminal: planner needs more context
- *   - report_blocker(reason)    → terminal: no viable plan
+ *   - submit_plan(plan)         → checks a candidate; gives back the accepted
+ *                                 plan or structured issues
+ *   - request_clarification(…)  → the planner needs more context
+ *   - report_blocker(reason)    → 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.
+ * After the run, the tool selects the outcome from the recorded calls — the
+ * 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 { Pool } from "pg";
+import type { SubAgentRegistrar } from "../../loop/sub-agent.js";
 import type { ToolOutputStore } from "../../loop/tool-output.js";
 import { type ChatProvider } from "../../providers/types.js";
 import type { UsageRecorder } from "../../billing/usage-recorder.js";
@@ -33,7 +33,7 @@ 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";
-export interface GeneratePlanDeps extends EnvironmentStorePaths {
+export type GeneratePlanDeps = EnvironmentStorePaths & {
     /**
      * The conversation-role backend the planner is pinned to. Keeping the
      * provider and its model label in one value prevents composition roots from
@@ -51,7 +51,7 @@ export interface GeneratePlanDeps extends EnvironmentStorePaths {
      * default guidance and validation skips the ceiling check.
      */
     readonly resourcePolicy?: ResourcePolicy;
-    /** Diagnostic sink. Absent, the tool runs silently — see `RunAgentOptions.logger`. */
+    /** 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. */
     readonly usageRecorder?: UsageRecorder;
@@ -66,7 +66,7 @@ export interface GeneratePlanDeps extends EnvironmentStorePaths {
      * the open-source host.
      */
     readonly knowledge?: KnowledgeClient;
-}
+};
 /**
  * The search tools of the planner — built one time, not per invocation.
  *
@@ -83,4 +83,4 @@ export declare function buildPlannerSearchTools(deps: GeneratePlanDeps, hooks?:
     readonly onRecommend?: (answer: KnowledgeRecommendAnswer) => void;
 }): Tool[];
 /** Build the `generate_plan` tool bound to its provider and pool. */
-export declare function createGeneratePlanTool(deps: GeneratePlanDeps): Tool;
+export declare function createGeneratePlanTool(deps: GeneratePlanDeps, registerSubAgent: SubAgentRegistrar): Tool;