@inflexa-ai/harness 0.1.1 → 0.3.0

package/dist/tools/lib/pubchem-ops.js

@@ -0,0 +1,224 @@
+/**
+ * PubChem PUG-REST operations — the three lookups the PubChem tools expose.
+ *
+ * One home for the wire schemas, the URL construction, and the "PubChem 404
+ * means no data" contract, so a caller cannot drift from it: every function
+ * returns an empty collection for a 404 and throws on any other API failure.
+ */
+import { z } from "zod";
+import { apiFetchValidated, describeApiError } from "./api-utils.js";
+import { PUBCHEM_HEADERS as HEADERS, PUBCHEM_BASE } from "./pubchem-config.js";
+const PROPERTY_LIST = [
+    "MolecularFormula",
+    "MolecularWeight",
+    "CanonicalSMILES",
+    "InChI",
+    "InChIKey",
+    "IUPACName",
+    "XLogP",
+    "TPSA",
+    "HBondDonorCount",
+    "HBondAcceptorCount",
+    "RotatableBondCount",
+    "Complexity",
+].join(",");
+// A single schema that both validates and normalizes one PUG-REST property row:
+// the `.object(...)` half is the wire shape (every field optional — PubChem
+// omits absent properties), the `.transform(...)` half maps it to the camelCase
+// `PubChemCompound` we return. Parsing IS the validation, and because the
+// transform rides on the schema, `z.infer` below is the OUTPUT type — no
+// separate raw interface or mapper.
+const PugPropertyRowSchema = z
+    .object({
+    CID: z.number().optional(),
+    CanonicalSMILES: z.string().optional(),
+    MolecularFormula: z.string().optional(),
+    // PUG-REST serializes MolecularWeight as a string (e.g. "180.16") to
+    // preserve significant figures; accept both and let the transform's
+    // `Number(...)` normalize it.
+    MolecularWeight: z.union([z.number(), z.string()]).optional(),
+    IUPACName: z.string().optional(),
+    InChI: z.string().optional(),
+    InChIKey: z.string().optional(),
+    XLogP: z.number().optional(),
+    TPSA: z.number().optional(),
+    HBondDonorCount: z.number().optional(),
+    HBondAcceptorCount: z.number().optional(),
+    RotatableBondCount: z.number().optional(),
+    Complexity: z.number().optional(),
+})
+    .transform((raw) => ({
+    cid: raw.CID ?? 0,
+    canonicalSmiles: raw.CanonicalSMILES ?? null,
+    molecularFormula: raw.MolecularFormula ?? null,
+    molecularWeight: raw.MolecularWeight != null ? Number(raw.MolecularWeight) : null,
+    iupacName: raw.IUPACName ?? null,
+    inchi: raw.InChI ?? null,
+    inchiKey: raw.InChIKey ?? null,
+    xlogp: raw.XLogP ?? null,
+    tpsa: raw.TPSA ?? null,
+    hbondDonorCount: raw.HBondDonorCount ?? null,
+    hbondAcceptorCount: raw.HBondAcceptorCount ?? null,
+    rotatableBondCount: raw.RotatableBondCount ?? null,
+    complexity: raw.Complexity ?? null,
+}));
+const PubChemPropertyResponseSchema = z.object({
+    PropertyTable: z.object({ Properties: z.array(PugPropertyRowSchema).optional() }).optional(),
+});
+// The PUG-REST xrefs wire shape, validated at the fetch boundary: one
+// `Information` entry per CID with parallel `RegistryID[]` / `SourceName[]`
+// arrays. Every field is optional — PubChem omits absent values.
+const PubChemXrefResponseSchema = z.object({
+    InformationList: z
+        .object({
+        Information: z
+            .array(z.object({
+            CID: z.number().optional(),
+            RegistryID: z.array(z.string()).optional(),
+            SourceName: z.array(z.string()).optional(),
+        }))
+            .optional(),
+    })
+        .optional(),
+});
+// The PUG-REST assay-summary wire shape (a table of columns + rows), validated
+// at the fetch boundary; `parseAssaySummary` maps the heading-indexed cells into
+// `PubChemAssay` records. Every field is optional — PubChem omits absent values.
+const PugAssaySummarySchema = z.object({
+    Table: z
+        .object({
+        Columns: z
+            .object({
+            Column: z.array(z.object({ Heading: z.string().optional() })).optional(),
+        })
+            .optional(),
+        Row: z
+            .array(z.object({
+            Cell: z
+                .array(z.object({
+                intval: z.number().optional(),
+                fval: z.number().optional(),
+                sval: z.string().optional(),
+            }))
+                .optional(),
+        }))
+            .optional(),
+    })
+        .optional(),
+});
+/** Build the PUG-REST URL path segment for the given search type. */
+function buildNamespace(searchBy, query) {
+    switch (searchBy) {
+        case "name":
+            return `compound/name/${encodeURIComponent(query)}`;
+        case "smiles":
+            return `compound/smiles/${encodeURIComponent(query)}`;
+        case "inchi":
+            return `compound/inchi/${encodeURIComponent(query)}`;
+        case "inchikey":
+            return `compound/inchikey/${encodeURIComponent(query)}`;
+        case "cid":
+            return `compound/cid/${encodeURIComponent(query)}`;
+        default:
+            return `compound/name/${encodeURIComponent(query)}`;
+    }
+}
+/** Resolve a compound to its identity + computed properties. Empty array = no match. */
+export async function fetchPubchemCompounds(query, searchBy) {
+    const namespace = buildNamespace(searchBy, query);
+    const url = `${PUBCHEM_BASE}/${namespace}/property/${PROPERTY_LIST}/JSON`;
+    const res = await apiFetchValidated(url, PubChemPropertyResponseSchema, { headers: HEADERS });
+    if (res.isErr()) {
+        // PubChem returns 404 when the query matches no compound — expected.
+        if (res.error.type === "http_status" && res.error.status === 404)
+            return [];
+        throw new Error(describeApiError(res.error));
+    }
+    // Already validated + normalized by PugPropertyRowSchema's transform.
+    return res.value.PropertyTable?.Properties ?? [];
+}
+/** External registry ids for a CID. Empty array = the CID is in no external registry. */
+export async function fetchPubchemCrossRefs(cid) {
+    const url = `${PUBCHEM_BASE}/compound/cid/${cid}/xrefs/RegistryID,SourceName/JSON`;
+    const res = await apiFetchValidated(url, PubChemXrefResponseSchema, { headers: HEADERS });
+    if (res.isErr()) {
+        // PubChem returns 404 when the CID has no cross-references — expected.
+        if (res.error.type === "http_status" && res.error.status === 404)
+            return [];
+        throw new Error(describeApiError(res.error));
+    }
+    // PUG-REST xrefs returns an InformationList with one entry per CID.
+    // Each entry has parallel RegistryID[] and SourceName[] arrays.
+    const info = res.value.InformationList?.Information?.[0];
+    if (!info?.RegistryID?.length)
+        return [];
+    const crossRefs = [];
+    const registryIds = info.RegistryID;
+    const sourceNames = info.SourceName ?? [];
+    for (let i = 0; i < registryIds.length; i++) {
+        crossRefs.push({
+            source: sourceNames[i] ?? "Unknown",
+            id: registryIds[i] ?? "",
+        });
+    }
+    return crossRefs;
+}
+/** Bioassay screening summaries for a CID. Empty array = never screened. */
+export async function fetchPubchemAssays(cid, opts) {
+    const url = `${PUBCHEM_BASE}/compound/cid/${cid}/assaysummary/JSON`;
+    const res = await apiFetchValidated(url, PugAssaySummarySchema, { headers: HEADERS });
+    if (res.isErr()) {
+        // PubChem returns 404 when the CID has no assay data — expected.
+        if (res.error.type === "http_status" && res.error.status === 404)
+            return [];
+        throw new Error(describeApiError(res.error));
+    }
+    let assays = parseAssaySummary(res.value);
+    if (opts.activeOnly) {
+        assays = assays.filter((a) => a.activityOutcome?.toLowerCase() === "active");
+    }
+    return assays.slice(0, opts.limit);
+}
+function parseAssaySummary(data) {
+    const columns = data.Table?.Columns?.Column ?? [];
+    const rows = data.Table?.Row ?? [];
+    // Find column indices by heading
+    const headingIndex = new Map();
+    for (let i = 0; i < columns.length; i++) {
+        if (columns[i].Heading) {
+            headingIndex.set(columns[i].Heading, i);
+        }
+    }
+    const aidIdx = headingIndex.get("AID");
+    const nameIdx = headingIndex.get("AssayName");
+    const targetIdx = headingIndex.get("TargetName");
+    const outcomeIdx = headingIndex.get("ActivityOutcome");
+    const valueIdx = headingIndex.get("ActivityValue");
+    const results = [];
+    for (const row of rows) {
+        const cells = row.Cell ?? [];
+        const getCellStr = (idx) => {
+            if (idx === undefined || idx >= cells.length)
+                return null;
+            return cells[idx]?.sval ?? null;
+        };
+        const getCellNum = (idx) => {
+            if (idx === undefined || idx >= cells.length)
+                return null;
+            const cell = cells[idx];
+            if (cell?.fval !== undefined)
+                return cell.fval;
+            if (cell?.intval !== undefined)
+                return cell.intval;
+            return null;
+        };
+        results.push({
+            aid: getCellNum(aidIdx) ?? 0,
+            assayName: getCellStr(nameIdx),
+            targetName: getCellStr(targetIdx),
+            activityOutcome: getCellStr(outcomeIdx),
+            activityValue: getCellNum(valueIdx),
+        });
+    }
+    return results;
+}

package/dist/tools/memory/update-working-memory.d.ts

@@ -2,24 +2,62 @@
  * update-working-memory — the agent's single interface for maintaining
  * working memory.
  *
- * Dependency-bearing: the `WorkingMemoryStore` is captured by the factory
- * (see the harness-durable-runtime spec). The analysis id is read from the request-scoped `Session`.
+ * Dependency-bearing: the `WorkingMemoryStore` and the database `Pool` are
+ * captured by the factory (see the harness-durable-runtime spec). The analysis
+ * id is read from the request-scoped `Session`.
  *
  * The input is a flat object with a `section` discriminator — not a
  * `z.discriminatedUnion`, which `defineTool` rejects (Anthropic needs a
  * top-level `"type":"object"`). The variant fields are validated by
  * `.refine` so a malformed call (e.g. a `finding` with no `runId`) fails
  * at the loop boundary and surfaces as an `is_error` tool result.
+ *
+ * Working memory is re-injected in full on every turn, so it is bounded at the
+ * write. The text caps are declared in the input schema — a violation is a
+ * validation error the model sees before `execute` runs — and the entry-count
+ * caps are enforced by the store under its row lock. Neither ever truncates: an
+ * over-cap write is refused with a message telling the model to shorten the
+ * text or retire a stale entry first.
+ *
+ * A finding cites the run that produced it, so adding one verifies the run
+ * exists AND belongs to this analysis (`cortex_runs.analysis_id`) before it is
+ * stored: an unknown runId is an `err(ToolError)` the model can correct from,
+ * not a silent reference to a run that never existed.
  */
+import type { Pool } from "pg";
+import { z } from "zod";
 import type { WorkingMemoryStore } from "../../memory/working-memory.js";
-export declare function createUpdateWorkingMemoryTool(workingMemory: WorkingMemoryStore): import("../define-tool.js").Tool<{
+declare const inputSchema: z.ZodObject<{
+    section: z.ZodEnum<{
+        constraint: "constraint";
+        goal: "goal";
+        hypothesis: "hypothesis";
+        finding: "finding";
+    }>;
+    operation: z.ZodOptional<z.ZodEnum<{
+        add: "add";
+        revise: "revise";
+        retire: "retire";
+    }>>;
+    text: z.ZodOptional<z.ZodString>;
+    id: z.ZodOptional<z.ZodString>;
+    origin: z.ZodOptional<z.ZodEnum<{
+        user: "user";
+        agent: "agent";
+    }>>;
+    runId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Input = z.infer<typeof inputSchema>;
+interface UpdateOutput {
+    readonly ok: true;
+    readonly section: Input["section"];
+}
+export declare function createUpdateWorkingMemoryTool(workingMemory: WorkingMemoryStore, pool: Pool): import("../define-tool.js").Tool<{
     section: "constraint" | "goal" | "hypothesis" | "finding";
     operation?: "add" | "revise" | "retire" | undefined;
     text?: string | undefined;
     id?: string | undefined;
     origin?: "user" | "agent" | undefined;
     runId?: string | undefined;
-}, {
-    ok: boolean;
-    section: "constraint" | "goal" | "hypothesis" | "finding";
-}>;
+}, UpdateOutput>;
+export {};

package/dist/tools/memory/update-working-memory.js

@@ -2,31 +2,54 @@
  * update-working-memory — the agent's single interface for maintaining
  * working memory.
  *
- * Dependency-bearing: the `WorkingMemoryStore` is captured by the factory
- * (see the harness-durable-runtime spec). The analysis id is read from the request-scoped `Session`.
+ * Dependency-bearing: the `WorkingMemoryStore` and the database `Pool` are
+ * captured by the factory (see the harness-durable-runtime spec). The analysis
+ * id is read from the request-scoped `Session`.
  *
  * The input is a flat object with a `section` discriminator — not a
  * `z.discriminatedUnion`, which `defineTool` rejects (Anthropic needs a
  * top-level `"type":"object"`). The variant fields are validated by
  * `.refine` so a malformed call (e.g. a `finding` with no `runId`) fails
  * at the loop boundary and surfaces as an `is_error` tool result.
+ *
+ * Working memory is re-injected in full on every turn, so it is bounded at the
+ * write. The text caps are declared in the input schema — a violation is a
+ * validation error the model sees before `execute` runs — and the entry-count
+ * caps are enforced by the store under its row lock. Neither ever truncates: an
+ * over-cap write is refused with a message telling the model to shorten the
+ * text or retire a stale entry first.
+ *
+ * A finding cites the run that produced it, so adding one verifies the run
+ * exists AND belongs to this analysis (`cortex_runs.analysis_id`) before it is
+ * stored: an unknown runId is an `err(ToolError)` the model can correct from,
+ * not a silent reference to a run that never existed.
  */
-import { ok } from "neverthrow";
+import { err, ok } from "neverthrow";
 import { z } from "zod";
 import { scopeResource } from "../../auth/types.js";
-import { unwrapOrThrow } from "../../lib/result.js";
+import { toThrowable, unwrapOrThrow } from "../../lib/result.js";
+import { isWorkingMemoryRejection, WORKING_MEMORY_LIMITS } from "../../memory/working-memory.js";
+import { queryRun } from "../../state/index.js";
 import { defineTool } from "../define-tool.js";
+const { goalChars, entryChars, constraints, hypotheses, findings } = WORKING_MEMORY_LIMITS;
 const inputSchema = z
     .object({
     section: z.enum(["goal", "constraint", "hypothesis", "finding"]).describe("Which working-memory section to update."),
     operation: z
         .enum(["add", "revise", "retire"])
         .optional()
-        .describe("For constraint/hypothesis: add a new entry (default), revise an " + "existing entry's text, or retire a stale one. Ignored for goal/finding."),
+        .describe("For constraint/hypothesis/finding: add a new entry (default), revise an " +
+        "existing entry's text, or retire one that no longer earns its place. " +
+        "Ignored for goal — a goal write always replaces the previous goal."),
     text: z
         .string()
+        .min(1)
+        .max(goalChars, `text is over the ${goalChars}-character cap — nothing was recorded; shorten it and retry.`)
         .optional()
-        .describe("Entry text. Required for goal, finding, and constraint/hypothesis " + "add/revise. Omit when retiring."),
+        .describe(`Entry text. Required for goal, and for add/revise on any section; omit when retiring. ` +
+        `Max ${entryChars} characters for a constraint/hypothesis/finding, ${goalChars} for the goal. ` +
+        `Over the cap is REJECTED, never truncated — write one concise line and leave the detail ` +
+        `in the run, which inspect_run still serves.`),
     id: z
         .string()
         .optional()
@@ -35,30 +58,33 @@ const inputSchema = z
         .enum(["user", "agent"])
         .optional()
         .describe("For a new constraint: whether the user stated the rule or you " + "derived it. Defaults to 'agent'."),
-    runId: z.string().optional().describe("The run that produced the finding. Required when section is 'finding'."),
+    runId: z
+        .string()
+        .optional()
+        .describe("The run that produced the finding. Required when ADDING a finding (revise " +
+        "and retire address the finding by its own id instead). Must be an existing " +
+        "run of this analysis — copy it verbatim from inspect_run. A runId that does " +
+        "not exist is rejected; never invent one."),
 })
-    .refine((d) => d.section !== "goal" || d.text !== undefined, {
+    .refine((d) => d.section !== "goal" || (d.text !== undefined && d.text.trim().length > 0), {
     message: "text is required when section is 'goal'",
     path: ["text"],
 })
-    .refine((d) => d.section !== "finding" || (d.runId !== undefined && d.runId.length > 0), {
-    message: "runId is required when section is 'finding'",
+    .refine((d) => d.section !== "finding" || (d.operation ?? "add") !== "add" || (d.runId !== undefined && d.runId.length > 0), {
+    message: "runId is required when adding a finding — copy an existing runId from inspect_run",
     path: ["runId"],
-})
-    .refine((d) => d.section !== "finding" || (d.text !== undefined && d.text.length > 0), {
-    message: "text is required when section is 'finding'",
-    path: ["text"],
 })
     .refine((d) => !(d.operation === "revise" || d.operation === "retire") || (d.id !== undefined && d.id.length > 0), {
     message: "id is required when operation is 'revise' or 'retire'",
     path: ["id"],
 })
-    .refine((d) => {
-    const isList = d.section === "constraint" || d.section === "hypothesis";
-    const op = d.operation ?? "add";
-    return !(isList && op !== "retire") || (d.text !== undefined && d.text.length > 0);
-}, {
-    message: "text is required to add or revise a constraint/hypothesis",
+    .refine((d) => d.section === "goal" || (d.operation ?? "add") === "retire" || (d.text !== undefined && d.text.trim().length > 0), {
+    message: "text is required to add or revise a constraint/hypothesis/finding",
+    path: ["text"],
+})
+    .refine((d) => d.section === "goal" || d.text === undefined || d.text.trim().length <= entryChars, {
+    message: `a constraint/hypothesis/finding is capped at ${entryChars} characters (only the goal may reach ` +
+        `${goalChars}). Nothing was recorded — rewrite it as one concise line and retry.`,
     path: ["text"],
 });
 /** Map a validated flat input to a constraint/hypothesis list amendment. */
@@ -76,37 +102,81 @@ function toConstraintOp(input) {
     const base = toListOp(input);
     return base.op === "add" ? { ...base, origin: input.origin ?? "agent" } : base;
 }
-export function createUpdateWorkingMemoryTool(workingMemory) {
+/** As `toListOp`, but an added finding also carries the run it is attributed to. */
+function toFindingOp(input) {
+    const base = toListOp(input);
+    return base.op === "add" ? { ...base, runId: input.runId } : base;
+}
+export function createUpdateWorkingMemoryTool(workingMemory, pool) {
+    /** Write one amendment, mapping a refused write to a model-visible error. */
+    async function apply(analysisId, section, value) {
+        const written = await workingMemory.updateSection(analysisId, section, value);
+        if (written.isErr()) {
+            // A refused write (cap hit, unknown id) is an expected outcome the model
+            // can act on — its message carries the remedy. A DbError is not: it throws,
+            // and the loop's dispatch catch maps it to a generic error tool result.
+            if (isWorkingMemoryRejection(written.error)) {
+                return err({ error: written.error.message, retryable: true });
+            }
+            throw toThrowable(written.error);
+        }
+        return ok({ ok: true, section });
+    }
     return defineTool({
         id: "update_working_memory",
-        description: "Maintain the analysis's working memory — its durable interpretive " +
-            "layer that survives token-window eviction. Section-addressable: set " +
-            "the 'goal', add/revise/retire a 'constraint' (a binding rule) or a " +
-            "'hypothesis', or record a 'finding' under a runId. Updates one " +
-            "section at a time; the others are untouched.",
+        description: "Maintain the analysis's working memory — the durable interpretive layer that survives " +
+            "context-window eviction. It is re-injected IN FULL on every turn, so every entry is re-read " +
+            "for the life of the analysis: promote only what must outlive the window, and retire what no " +
+            "longer earns its place.\n\n" +
+            "Sections (one per call; the other three are left untouched):\n" +
+            `- goal — the analysis's current objective as you understand it. A write replaces it. Max ${goalChars} chars.\n` +
+            `- constraint — a binding rule the rest of the analysis must obey. origin 'user' (the user ` +
+            `stated it: "use FDR 0.01") or 'agent' (you derived it: "the data is paired, so every test must ` +
+            `be paired"). Max ${constraints} entries.\n` +
+            `- hypothesis — a hypothesis under active exploration. Retire it once it is resolved or ` +
+            `abandoned. Max ${hypotheses} entries.\n` +
+            `- finding — a durable conclusion, cited to the run that produced it (runId, copied verbatim ` +
+            `from inspect_run). Record the conclusion, never the run's contents — the run itself stays ` +
+            `retrievable with inspect_run. Max ${findings} entries across all runs.\n\n` +
+            "Operations (constraint / hypothesis / finding): 'add' (default), 'revise' (id + new text), " +
+            "'retire' (id). Copy the id from the [id] shown against each entry in the rendered working memory.\n\n" +
+            `Caps are enforced, never truncated: text over the cap (${entryChars} chars; ${goalChars} for the goal), or an ` +
+            "add into a full section, is REJECTED and nothing is stored. Shorten the text, or retire a stale " +
+            "entry before adding the new one.\n\n" +
+            "PROMOTE: a binding rule the user states or you derive; a durable conclusion a run produced; a " +
+            "shift in the analysis's objective; a hypothesis you are actively testing.\n" +
+            'DO NOT PROMOTE: transient conversational asks ("show me the top genes"), restatements of the ' +
+            "user's last message, run contents (tables, gene lists, file paths), or anything you can retrieve " +
+            "again with inspect_run, read_file, or search.",
         inputSchema,
         execute: async (input, ctx) => {
             const analysisId = scopeResource(ctx.session.scope).resourceId;
             switch (input.section) {
                 case "goal":
-                    unwrapOrThrow(await workingMemory.updateSection(analysisId, "goal", {
-                        text: input.text,
-                    }));
-                    break;
+                    return apply(analysisId, "goal", { text: input.text });
                 case "constraint":
-                    unwrapOrThrow(await workingMemory.updateSection(analysisId, "constraint", toConstraintOp(input)));
-                    break;
+                    return apply(analysisId, "constraint", toConstraintOp(input));
                 case "hypothesis":
-                    unwrapOrThrow(await workingMemory.updateSection(analysisId, "hypothesis", toListOp(input)));
-                    break;
-                case "finding":
-                    unwrapOrThrow(await workingMemory.updateSection(analysisId, "finding", {
-                        runId: input.runId,
-                        text: input.text,
-                    }));
-                    break;
+                    return apply(analysisId, "hypothesis", toListOp(input));
+                case "finding": {
+                    const op = toFindingOp(input);
+                    if (op.op === "add") {
+                        // A run of another analysis is as wrong as one that does not exist —
+                        // both are "no such run here", so they share one message.
+                        const run = unwrapOrThrow(await queryRun(pool, op.runId));
+                        if (!run || run.analysisId !== analysisId) {
+                            return err({
+                                error: `unknown runId "${op.runId}" — this analysis has no such run, so the ` +
+                                    `finding was NOT recorded. Call inspect_run with no arguments to list ` +
+                                    `this analysis's runs, copy an exact runId from that list, and retry. ` +
+                                    `Do not guess a runId.`,
+                                retryable: true,
+                            });
+                        }
+                    }
+                    return apply(analysisId, "finding", op);
+                }
             }
-            return ok({ ok: true, section: input.section });
         },
     });
 }

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

@@ -3,8 +3,9 @@
  * agent — they are constructed inside `harness/execution/report-runner.ts`
  * so each tool factory shares the runner's closure-captured outcome state
  * and preview-dir paths. The conversation agent reaches the report-builder
- * through the `iterate_report` tool, which orchestrates the whole
- * iteration.
+ * through its `submit_report` tool, which orchestrates the whole iteration.
+ * (That conversation-agent tool shares the id `submit_report` with this
+ * barrel's builder-side terminal tool — different rosters, never mixed.)
  */
 export { createBuildReportTool, type BuildReportToolState } from "./build-report.js";
 export { createSubmitReportTool, type ReportOutcome, type SubmitReportToolState } from "./submit-report.js";

package/dist/tools/report/index.js

@@ -3,8 +3,9 @@
  * agent — they are constructed inside `harness/execution/report-runner.ts`
  * so each tool factory shares the runner's closure-captured outcome state
  * and preview-dir paths. The conversation agent reaches the report-builder
- * through the `iterate_report` tool, which orchestrates the whole
- * iteration.
+ * through its `submit_report` tool, which orchestrates the whole iteration.
+ * (That conversation-agent tool shares the id `submit_report` with this
+ * barrel's builder-side terminal tool — different rosters, never mixed.)
  */
 export { createBuildReportTool } from "./build-report.js";
 export { createSubmitReportTool } from "./submit-report.js";

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

@@ -16,6 +16,7 @@ import { ok } from "neverthrow";
 import { z } from "zod";
 import { AnalogicalReasonerOutputSchema } from "@inflexa-ai/harness/contracts/analogy-report.js";
 import { analogicalReasonerPrompt } from "../../prompts/analogical-reasoner.js";
+import { composeSystemPrompt } from "../../agents/system-prompt.js";
 import { forSubAgent } from "../../auth/types.js";
 import { unwrapOrThrow } from "../../lib/result.js";
 import { finalText, runAgent } from "../../loop/run-agent.js";
@@ -158,27 +159,39 @@ export function createGenerateAnalogyReportTool(deps) {
         searchSemanticScholarTool,
         searchArxivTool,
         createSearchGithubReposTool({ githubToken: deps.bioKeys.github }),
-        ncbi.searchPubMed,
-        ncbi.getArticleDetails,
-        ncbi.getArticleFullText,
+        ncbi.pubmed,
     ];
     const agent = {
         id: AGENT_ID,
-        systemPrompt: analogicalReasonerPrompt,
+        systemPrompt: composeSystemPrompt(analogicalReasonerPrompt),
         model: deps.model,
         tools: reasonerTools,
         maxIterations: RESEARCH_MAX_ITERATIONS,
     };
     return defineTool({
         id: "generate_analogy_report",
-        description: "Generate a cross-domain analogy report for an open-ended scientific " +
-            "problem. Pass the user's problem as a single field plus optional " +
-            "context (data profile excerpts, prior findings) and knobs (domain " +
-            "counts, preferred/excluded domains). Returns a structured " +
-            "AnalogyReport envelope — analogies with object mappings, shared " +
-            "relations, and cited solutions from other domains. The UI renders " +
-            "the envelope as an inline card; reach for this tool whenever the " +
-            "user is in exploratory or hypothesis-generation mode.",
+        description: "Idea-generation engine. Extracts structural analogies for an open-ended " +
+            "scientific problem and returns real, cited solutions from other fields " +
+            "(control theory, ML, ecology, logistics, economics…).\n" +
+            "WHEN: any exploratory or hypothesis-generation turn — 'what could we do " +
+            "about X', 'what should we try', 'how could we approach this', 'we're " +
+            "stuck', 'brainstorm ideas', 'are there precedents outside biology'. The " +
+            "trigger is exploratory INTENT, not the words 'analogy' or 'cross-domain' " +
+            "— users rarely name it, so infer it and reach for the tool proactively.\n" +
+            "NOT for: in-domain literature review (use `literature_reviewer` or " +
+            "`pubmed`), single-gene factual lookup (use `search_gene`), or " +
+            "execution-mode turns where the user just wants the next step done. It " +
+            "drives a multi-step research sub-agent over live literature search, so " +
+            "it is slow — never spend it on a fact you could look up.\n" +
+            "RETURNS an AnalogyReport envelope the UI renders as an inline card. An " +
+            "analogy the search could not fill carries a `coverage` tag " +
+            "(`queried_no_data` | `search_failed` | `not_loaded`) with an empty " +
+            "`solutions` array — informational, NOT an error. A top-level `error` " +
+            "field means no report was produced: on `error.kind === " +
+            '"extraction-failed"` do NOT retry with the same or a similar problem ' +
+            "statement (the wrapper already retried internally — you would burn " +
+            "latency on the same failure). Surface the message and ask the user to " +
+            "narrow the problem.",
         inputSchema: generateAnalogyReportInputSchema,
         execute: async (input, ctx) => {
             const childSession = forSubAgent(ctx.session, AGENT_ID);

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

@@ -2,12 +2,19 @@
  * generatePlan — a loop-driving tool: a focused `runAgent` loop that builds
  * an analysis plan (a DAG of steps).
  *
- * The outer tool receives structured context from the conversation agent
- * (data profile, research question, prior runs, constraints) and drives an
- * internal "planner" agent that communicates outcomes EXCLUSIVELY via four
- * terminal tool calls:
+ * 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
+ * input data is — and projected into the planner's seed. The caller supplies
+ * only what the profile cannot hold: the research question, facts the user
+ * volunteered (`analystNotes`), prior run results, and plan constraints. A
+ * caller-typed dataset summary would be a model re-transcribing a record the
+ * database already holds, and it would lose fidelity at every hop.
  *
- *   - validate_plan(plan)       → non-terminal dry-run (Zod + semantic)
+ * The tool drives an internal "planner" agent that communicates outcomes
+ * EXCLUSIVELY via four terminal tool calls:
+ *
+ *   - validate_plan(plan)       → non-terminal dry-run: an any-shape candidate
+ *                                 in, {valid, issues} out (schema + semantic)
  *   - submit_plan(plan)         → terminal success: re-validates + persists
  *   - request_clarification(…)  → terminal: planner needs more context
  *   - report_blocker(reason)    → terminal: no viable plan