@inflexa-ai/harness 0.45.0 → 0.46.0

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,29 +10,30 @@
  * 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";
 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";
-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
@@ -50,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;
@@ -58,6 +59,28 @@ export interface GeneratePlanDeps extends EnvironmentStorePaths {
     readonly toolOutputStore?: ToolOutputStore;
     /** API keys for the search tools the planner uses to ground a plan. */
     readonly bioKeys: BioToolKeys;
-}
+    /**
+     * The knowledge service client. Bound, the planner gains `knowledge_recommend`
+     * and `knowledge_check`. Absent, no knowledge tool attaches and no
+     * description of one enters the context, which is the default state of
+     * the open-source host.
+     */
+    readonly knowledge?: KnowledgeClient;
+};
+/**
+ * The search tools of the planner — built one time, not per invocation.
+ *
+ * The set answers the two questions that a seed cannot. "What did a study of
+ * this kind do before?" reaches the public dataset records and the literature.
+ * "What does this package actually give me?" reaches the developer docs. The
+ * planner reads its reference and package inventories from the seed, thus the
+ * docs pair is what turns a package name into a real function.
+ *
+ * A tool here never writes and never computes. Thus the worst outcome of a
+ * needless call is latency, and the prompt is what bounds that.
+ */
+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;