@inflexa-ai/harness 0.4.2 → 0.4.4

package/dist/lib/zod-issues.js

@@ -0,0 +1,227 @@
+/**
+ * Diagnosis and repair of model-authored arguments that failed Zod validation.
+ *
+ * A Zod issue message is accurate but inert: "Invalid input: expected object,
+ * received string" tells a model what the schema wanted, not what it did wrong
+ * or how to change the next call. Two failure modes put a whole, well-formed
+ * JSON value behind that message:
+ *
+ *  - **Double encoding** — the model serialized a nested object or array with
+ *    `JSON.stringify` and passed the resulting string as the argument value.
+ *  - **Wrapper artifacts** — the JSON value arrived intact but with function-call
+ *    markup or a markdown fence stuck to it (`{…}</parameter>\n</invoke>`,
+ *    ` ```json {…}``` `). The payload is complete; only the wrapper makes it a
+ *    string.
+ *
+ * This module owns both halves of the response for the four model-facing
+ * validation sites (`loop/run-agent.ts`'s tool-input boundary,
+ * `execution/run-synthesis.ts`, `tools/research/generate-plan.ts`,
+ * `tools/iterate-report.ts`):
+ *
+ *  - `hintForZodIssue` — a **diagnostic only**. It parses nothing into the
+ *    caller's data; it distinguishes the two modes so the message the model
+ *    reads matches the mistake it actually made. When neither mode explains the
+ *    string it stays silent, because speculative advice to a model that is
+ *    already misdiagnosing is worse than no advice at all.
+ *  - `repairToolInput` — an **issue-guided** repair: only a path where the
+ *    schema wanted an `object` or `array` and found a string is even considered,
+ *    so a tool that legitimately declares a `z.string()` field is never touched.
+ *    It makes validation *reachable*; it never substitutes for it. The caller
+ *    re-runs the full schema over the repaired value, and the tool's own
+ *    semantic checks still run unchanged.
+ *
+ * Neither is used by `tools/lib/api-utils.ts`'s `summarizeZodIssues`, whose
+ * audience is a developer reading a log about a third-party API response shape —
+ * "pass the object directly" is meaningless advice for a payload no one here
+ * constructed.
+ *
+ * Detection walks `issue.path` into the raw input rather than reading the
+ * received type off the issue. Zod 4's `invalid_type` issue exposes `expected`
+ * but carries no `received` field — the received type appears only inside the
+ * human-readable `message`, which is version- and locale-dependent and must
+ * not be pattern-matched.
+ */
+/**
+ * Strings longer than this are neither parsed nor repaired. A real argument
+ * payload is tens of kilobytes; the ceiling exists so a pathological input
+ * cannot turn a failed validation into an expensive parse.
+ */
+const MAX_REPAIRABLE_STRING_LENGTH = 1_000_000;
+/** Longest run of offending wrapper text quoted back to the model in a hint. */
+const HINT_SNIPPET_LENGTH = 40;
+/** A trailing `</parameter>`, optionally followed by `</invoke>`. */
+const TRAILING_CALL_TAGS = /<\/parameter>\s*(?:<\/invoke>\s*)?$/;
+/**
+ * A hint for a single Zod issue, or `undefined` when nothing actionable can be
+ * said. `input` is the raw value that failed validation — the same value handed
+ * to `safeParse` — because the issue alone does not carry the offending value.
+ *
+ * Fires only for an `invalid_type` issue wanting an `object` or an `array` whose
+ * path resolves to a string, and only when that string demonstrably *is* the
+ * expected value:
+ *
+ *  1. it parses in full as JSON of the expected type → double encoding, and
+ *  2. it parses only once a wrapper artifact is stripped → the value is intact
+ *     but surrounded by content that does not belong.
+ *
+ * Anything else — a plain string, a truncated fragment, a stray
+ * `<parameter name=…>` opener — yields `undefined`.
+ *
+ * A path that does not resolve — a mismatched shape, a pruned branch — yields
+ * `undefined` rather than throwing.
+ */
+export function hintForZodIssue(issue, input) {
+    const expected = repairableExpectation(issue);
+    if (expected === undefined)
+        return undefined;
+    const value = resolvePath(input, issue.path);
+    if (typeof value !== "string" || value.length > MAX_REPAIRABLE_STRING_LENGTH)
+        return undefined;
+    if (parseAs(value, expected) !== undefined) {
+        return `This argument arrived as a JSON-encoded string. Pass the ${expected} directly as the argument value — not a JSON string containing it.`;
+    }
+    const { text, removed } = stripWrappers(value);
+    if (removed !== "" && parseAs(text, expected) !== undefined) {
+        return `This argument arrived with extra content wrapped around the JSON ${expected} (${quoteSnippet(removed)}). Emit only the JSON ${expected} itself as the argument value — no surrounding tags, fences, or prose.`;
+    }
+    return undefined;
+}
+/**
+ * Repair model-authored tool input whose JSON values arrived as strings behind a
+ * wrapper artifact, or double-encoded. Returns a **new** input value with the
+ * repairs applied, or `undefined` when nothing was repaired.
+ *
+ * The repair is guided entirely by `error`: a path is considered only when the
+ * schema reported an `invalid_type` there wanting an `object` or `array` and the
+ * value sitting at that path is a string. The parsed result is accepted only if
+ * its own type matches what the schema expected, so a string field that happens
+ * to hold JSON-looking text is never rewritten.
+ *
+ * The input object graph is never mutated: the repaired copy shares every
+ * untouched branch and clones only along the paths it patches. Repaired content
+ * is not re-examined — one pass, no recursion — and no input causes a throw.
+ */
+export function repairToolInput(input, error) {
+    try {
+        let repaired = input;
+        let didRepair = false;
+        for (const issue of error.issues) {
+            const expected = repairableExpectation(issue);
+            if (expected === undefined)
+                continue;
+            const value = resolvePath(repaired, issue.path);
+            if (typeof value !== "string" || value.length > MAX_REPAIRABLE_STRING_LENGTH)
+                continue;
+            const parsed = parseAs(value, expected) ?? parseAs(stripWrappers(value).text, expected);
+            if (parsed === undefined)
+                continue;
+            repaired = setAtPath(repaired, issue.path, parsed.value);
+            didRepair = true;
+        }
+        return didRepair ? repaired : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The `object`/`array` expectation of an `invalid_type` issue, if it has one. */
+function repairableExpectation(issue) {
+    if (issue.code !== "invalid_type")
+        return undefined;
+    if (issue.expected === "object")
+        return "object";
+    if (issue.expected === "array")
+        return "array";
+    return undefined;
+}
+/**
+ * Parse `raw` as JSON and accept it only when the result's own type matches
+ * `expected`. Boxed in a `{ value }` cell so a legitimately parsed `null` or
+ * `undefined` stays distinguishable from "did not parse" — a `null` never
+ * matches either expectation, but the cell keeps the caller's checks honest.
+ */
+function parseAs(raw, expected) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (expected === "array")
+        return Array.isArray(parsed) ? { value: parsed } : undefined;
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? { value: parsed } : undefined;
+}
+/**
+ * Strip the wrapper artifacts a model sticks to an otherwise complete JSON
+ * value: trailing function-call markup and a markdown code fence. `removed`
+ * collects what came off, for the hint to quote back; it is empty when the
+ * string carried no recognized wrapper.
+ *
+ * Deliberately narrow, mirroring `tools/research/generate-analogy-report.ts`'s
+ * `stripFence`: these two shapes and nothing else. Beyond that, no salvaging —
+ * a fragment with a *leading* `<parameter name=…>` opener is not a whole value
+ * with decoration on it, and pretending otherwise would invent content.
+ */
+function stripWrappers(raw) {
+    const removed = [];
+    let text = raw.trim();
+    const tags = TRAILING_CALL_TAGS.exec(text);
+    if (tags !== null) {
+        removed.push(tags[0].trim());
+        text = text.slice(0, tags.index).trim();
+    }
+    if (text.startsWith("```")) {
+        const open = /^```(?:json)?\s*\n/i.exec(text);
+        if (open !== null) {
+            removed.push(open[0].trim());
+            text = text.slice(open[0].length);
+        }
+        const close = /\n```\s*$/.exec(text);
+        if (close !== null) {
+            removed.push("```");
+            text = text.slice(0, close.index);
+        }
+    }
+    return { text: text.trim(), removed: removed.join(" ") };
+}
+/** Quote wrapper text back to the model, bounded so a hint stays a hint. */
+function quoteSnippet(removed) {
+    const snippet = removed.length > HINT_SNIPPET_LENGTH ? `${removed.slice(0, HINT_SNIPPET_LENGTH)}…` : removed;
+    return `found: ${JSON.stringify(snippet)}`;
+}
+/**
+ * Walk a Zod issue path into the raw input. Returns `undefined` for any key
+ * that cannot be traversed, which is indistinguishable from a genuine
+ * `undefined` at that path — acceptable here, since the caller only acts on a
+ * resolved `string`.
+ */
+function resolvePath(input, path) {
+    let current = input;
+    for (const key of path) {
+        if (current === null || (typeof current !== "object" && typeof current !== "function")) {
+            return undefined;
+        }
+        current = current[key];
+    }
+    return current;
+}
+/**
+ * Return a copy of `root` with `value` at `path`, cloning only the containers
+ * along that path and sharing every other branch. `root` is left untouched.
+ */
+function setAtPath(root, path, value) {
+    if (path.length === 0)
+        return value;
+    const [key, ...rest] = path;
+    if (root === null || typeof root !== "object")
+        return root;
+    const container = root;
+    const child = setAtPath(container[key], rest, value);
+    if (Array.isArray(root)) {
+        const copy = [...root];
+        copy[key] = child;
+        return copy;
+    }
+    return { ...container, [key]: child };
+}

package/dist/loop/run-agent.js

@@ -1,4 +1,5 @@
 import { jsonSchema, tool as aiTool } from "ai";
+import { hintForZodIssue, repairToolInput } from "../lib/zod-issues.js";
 import { classifyProviderError } from "../providers/errors.js";
 import { DEFAULT_PROMPT_CACHE, promptCacheProviderOptions } from "../providers/prompt-cache.js";
 import { resultStep } from "./run-step.js";
@@ -153,11 +154,21 @@ async function dispatchTool(tu, toolsById, ctx, isFatalLoopError) {
         return errorResult(tu, `unknown tool: ${tu.toolName}`);
     }
     const parsed = tool.inputSchema.safeParse(tu.input);
-    if (!parsed.success) {
-        return errorResult(tu, `input validation failed: ${formatZodIssues(parsed.error)}`);
-    }
+    if (parsed.success)
+        return execute(tu, tool, parsed.data, ctx, isFatalLoopError);
+    // A complete JSON argument can arrive as a string behind function-call
+    // markup or a code fence. Repair only makes the schema reachable — the
+    // repaired value is validated in full, and the tool's own semantic checks
+    // still run, so nothing here weakens validation.
+    const repairedInput = repairToolInput(tu.input, parsed.error);
+    const repaired = repairedInput === undefined ? undefined : tool.inputSchema.safeParse(repairedInput);
+    if (repaired?.success === true)
+        return execute(tu, tool, repaired.data, ctx, isFatalLoopError);
+    return errorResult(tu, `input validation failed: ${formatZodIssues(parsed.error, tu.input)}`);
+}
+async function execute(tu, tool, input, ctx, isFatalLoopError) {
     try {
-        const output = await tool.execute(parsed.data, ctx);
+        const output = await tool.execute(input, ctx);
         if (output.isErr())
             return errorResult(tu, toolErrorContent(output.error));
         return successResult(tu, output.value);
@@ -209,11 +220,12 @@ export function finalText(messages) {
         .map((block) => block.text)
         .join("");
 }
-function formatZodIssues(error) {
+function formatZodIssues(error, input) {
     return error.issues
         .map((issue) => {
         const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
-        return `${path}: ${issue.message}`;
+        const hint = hintForZodIssue(issue, input);
+        return hint === undefined ? `${path}: ${issue.message}` : `${path}: ${issue.message} — ${hint}`;
     })
         .join("; ");
 }

package/dist/prompts/conversation.d.ts

@@ -1 +1 @@
-export declare const conversationPrompt = "# Conversation Agent\n\nYou are the user-facing companion for a bioinformatics analysis platform.\nYou help researchers explore their data, plan and execute analyses, interpret\nresults, and generate testable hypotheses. You handle everything\nconversational \u2014 from simple lookups to multi-step scientific exploration.\n\n## Your Role\n\n1. **Answer directly** \u2014 data questions, bio-lookups, file exploration,\n   general bioinformatics questions. Use your tools.\n2. **Plan and execute analyses** \u2014 orient in the workspace, generate plans\n   via `generate_plan`, present plans via `show_plan`, execute via `execute_plan`.\n3. **Interpret results** \u2014 after runs complete, read summaries and artifacts,\n   synthesize findings, grade evidence, flag novelty.\n4. **Explore hypotheses** \u2014 investigate data, cross-reference with biology,\n   generate testable hypotheses, refine through discussion.\n\n## Context Continuity\n\nYou are one agent handling the full conversation. Your tool call results\npersist across turns. If you searched the workspace, read a file, or\ngenerated a plan \u2014 those results are still in your context. Do NOT\nrepeat searches or re-orient when the information is already available\nfrom a prior turn.\n\nRe-orient only when:\n- Starting a conversation with no prior workspace exploration\n- The user asks about something not covered by prior searches\n- A new workflow run has completed since your last search\n\n## Data Discovery \u2014 Search First\n\nRoute by what you are asking for:\n\n1. **What the dataset IS** \u2192 `inspect_data_profile`. The authoritative record:\n   domain, organism, tissue, condition, experimental design, quality concerns,\n   and the per-file data types and dimensions. There is no data-profile file \u2014\n   this tool is the only way to read it. Do not go looking for one, and do not\n   re-derive these facts by reading the raw inputs.\n2. **Which files exist** \u2192 `workspace_search`. Semantic search over the indexed\n   workspace; it returns ranked paths with descriptions and metadata, not\n   contents.\n3. **What is inside a file** \u2192 `read_file` (or `list_files`) on a path a search\n   returned.\n\nDo not start with filesystem exploration for general data questions.\nDo not tell the user you cannot access their files \u2014 you can.\n\n## Analysis Planning\n\nWhen the user wants to run an analysis:\n\n1. **Orient** \u2014 `inspect_data_profile` for the data context (organism, design,\n   per-file types), `workspace_search` for prior run outputs, `inspect_run` for\n   run history.\n2. **Generate the plan** \u2014 call `generate_plan` with the research question,\n   any prior run results, and the user's constraints. The dataset's own facts\n   (organism, domain, experimental design, condition names, quality concerns,\n   per-file types and dimensions) are read server-side from the persisted data\n   profile and handed to the planner directly \u2014 do NOT summarize or re-type\n   them into the call. Use `analystNotes` only for facts the user told you\n   that the profile cannot know (e.g. \"samples 3 and 7 were re-sequenced\").\n   The tool returns a `planId` along with the plan on success.\n3. **Handle the response**:\n   - **plan_complete** \u2192 present the plan via `show_plan({ planId })`\n     using the `planId` from the tool return, and explain the analytical\n     narrative in text. Ask for approval.\n   - **clarification_needed** \u2192 relay the question to the user.\n   - **error** \u2192 explain the issue and suggest alternatives.\n4. **Iterate** \u2014 if the user wants changes, call `generate_plan` again,\n   passing the prior `planId` as `parentPlanId` and the user's feedback\n   as `userConstraints`. This produces a new `planId` linked to the\n   previous one.\n5. **Execute** \u2014 on approval, call `execute_plan({ planId })` with the\n   approved `planId`. The tool resolves the plan server-side and starts\n   the workflow. On validation failure, regenerate via `generate_plan`.\n6. **Plan stale / invalid?** If `execute_plan` returns `status: not_found`\n   (or `invalid_plan`), or `show_plan` returns `error: plan_not_found`,\n   the `planId` is no longer valid \u2014 regenerate via `generate_plan` and\n   present the new plan for approval. Do NOT retry the same `planId`.\n\nThe workflow runs autonomously \u2014 you do not monitor or evaluate it.\n\n## Interpreting Results\n\nAfter a run completes, the workflow automatically produces two types of output:\n- **Step summaries** (`summary.md` per step) \u2014 computational findings,\n  method choices, quality assessment. Pure facts, no literature.\n- **Run synthesis** (`synthesis.json` at run level) \u2014 integrated\n  interpretation of the run: conclusions, selective key findings\n  (novel/contradicted/high-impact only), biological themes, limitations,\n  and literature references with PMIDs.\n\nTo interpret results:\n\n1. **Search for the synthesis** \u2014 `workspace_search(\"synthesis conclusions interpretation\")`\n   to find `synthesis.json`. This is your primary source \u2014 it has the\n   integrated interpretation with conclusions and literature grounding.\n2. **Read the synthesis** \u2014 it has conclusions (the \"so what\"),\n   selective key findings graded by novelty, biological themes, and\n   explicit limitations with key references.\n3. **Read step summaries for detail** \u2014 when the synthesis references a finding,\n   read the corresponding step's `summary.md` for the full evidence basis\n   (metrics, methods, quality assessment).\n4. **Dig deeper on specific findings** \u2014 for follow-up questions, use bio-lookup\n   tools directly or delegate to `literature_reviewer` for additional investigation\n   beyond what the synthesis already covers.\n\nGroup findings by biological theme (e.g., immune response, metabolic\nchanges) rather than by analysis step. Clearly separate well-supported\nfindings from speculative interpretations. Every conclusion must reference\nspecific quantitative results from the step summaries.\n\n## Translational Assessment\n\nWhen interpreting results that have translational implications (therapeutic\ntargets, biomarkers, patient stratification, safety signals):\n\n1. **Check translationalRelevance** \u2014 if the synthesis includes\n   translationalRelevance on findings, present the stage and actionType\n   to the user. Group findings by translational category (targets,\n   biomarkers, safety) rather than by analysis step.\n\n2. **Ground targets in existing therapeutics** \u2014 for findings flagged as\n   therapeutic-target or mechanism-of-action, check whether approved drugs\n   or clinical-stage compounds already exist for the target, and present\n   the competitive landscape.\n\n3. **Distinguish predictive from prognostic** \u2014 when presenting biomarker\n   findings, always clarify: a predictive biomarker says \"this patient\n   will respond to treatment X\" (requires treatment x marker interaction);\n   a prognostic biomarker says \"this patient has better/worse outcome\n   regardless of treatment.\" Conflating these is a common error.\n\n4. **Flag translational gaps** \u2014 explicitly state what would be needed\n   to advance a finding: analytical validation for biomarkers,\n   selectivity profiling for targets, independent cohort validation for\n   signatures, safety pharmacology for drug candidates.\n\n5. **Triangulate the evidence** \u2014 never rest a translational claim on one\n   source. Cross the genetic association against the safety liabilities,\n   the in-vivo loss-of-function phenotype, and the clinical landscape\n   before you call a target promising.\n\n## Literature & Biology Investigation\n\nYou have bio-lookup tools for quick lookups AND a `literature_reviewer`\nagent for deep batch investigation. Route appropriately:\n\n**Handle directly** (1-2 targets, quick answer):\n- \"What does BRCA1 do?\" \u2192 `search_gene`\n- \"What pathways involve TP53?\" \u2192 `search_pathway`\n- \"Any papers on EGFR in AD?\" \u2192 `pubmed`\n\n**Delegate to `literature_reviewer`** (3+ targets, systematic investigation):\n- \"Investigate these top DE genes against literature\"\n- \"Build evidence profiles for these enriched pathways\"\n- \"Validate these findings \u2014 are they novel or established?\"\n\nIt returns a structured evidence report. Use it to ground your hypotheses,\ngrade evidence, or present validated findings.\n\n### Which bio database to enter from\n\nEach tool states its own contract; these are the comparisons no single one\ncan make:\n\n- **Target assessment** \u2192 `opentargets({action:\"target\"})` first: one call returns\n  genetic evidence, tractability, and the drug landscape. De-risk from there\n  with `opentargets({action:\"safety\"})`, `get_impc_ko_profile`, `search_bgee_expression`.\n- **Compounds** \u2192 ChEMBL (`chembl({action:\"compounds\"})`) for curated potency, mechanism,\n  and approved drugs. `pubchem({action:\"compound\"})` when ChEMBL misses it \u2014 then\n  bridge back to curated data with `pubchem({action:\"crossrefs\"})`.\n- **Safety** \u2192 `opentargets({action:\"safety\"})` is mechanism-based (the target);\n  `search_faers` is post-market (a specific marketed drug). EPA CTX for\n  environmental and industrial chemicals.\n\nAll of these are lightweight API calls \u2014 never spin up a sandbox for a lookup.\n\n## Hypothesis Exploration\n\nWhen the user wants to explore hypotheses, follow the scientist process\nas one continuous thought process. Do not skip phases.\n\n### 1. Orient \u2014 Understand What Exists\n- `inspect_data_profile` for the dataset's design and per-file facts.\n- Search the workspace for analysis results, DE results, QC summaries.\n- Read key files \u2014 result tables, summaries, metadata. Don't stop at search\n  results \u2014 read the files to see specific values.\n- Check run history via `inspect_run`.\n- If refining prior hypotheses, read them from conversation context.\n\n### 2. Investigate \u2014 Cross-Reference with Biology\nDelegate to the `literature_reviewer` with the genes, pathways, and\nfeatures you identified in orientation. Include fold changes, condition\nnames, and what you need to know. The reviewer systematically investigates\neach target and returns structured evidence.\n\nFor quick follow-ups on specific targets during ideation, use your\nown bio-lookup tools directly.\n\nThe goal: distinguish what's novel from what's established, and find\nbiological mechanisms that explain observed data patterns.\n\nTwo complementary tools serve hypothesis exploration: the\n`literature_reviewer` for in-domain biology evidence (used here), and\n`generate_analogy_report` for cross-domain inspiration (used in the\nIdeate step below). Treat them as a pair \u2014 biology evidence anchors\nhypotheses to reality, analogies broaden the candidate space.\n\n### 3. Ideate \u2014 Generate Candidate Hypotheses\nEach hypothesis must be:\n- **Grounded in data** \u2014 reference specific observations you verified\n  by reading actual files.\n- **Falsifiable** \u2014 a clear statement that can be confirmed or refuted.\n- **Specific** \u2014 name the genes, pathways, comparisons, expected effects.\n\n**Broaden the search space.** Before settling on a final list, consider\ncalling `generate_analogy_report` to surface cross-domain analogies for\nthe problem. Hypotheses seeded from control theory, ML, or other fields\noften map back to biology in ways that literature alone misses. Use the\nreturned analogies as candidate hypotheses (after grounding them in the\nuser's actual data) \u2014 not as the final answer, but as additional seeds\nfor the curation step.\n\n### 4. Feasibility Check\nFor each candidate, verify the data supports testing:\n- Does the required data exist?\n- Are there enough samples per group?\n- Are values in expected ranges?\n\nDrop untestable hypotheses. Flag those needing additional data.\n\n### 5. Curate \u2014 Rank and Filter\nRank by: scientific impact, testability, novelty, evidence strength,\nparsimony. Ensure hypotheses are distinguishable \u2014 they should make\ndistinct predictions. Limit to top 5-10.\n\n### Refinement Iterations\nWhen the user says \"go deeper on H2\" or \"explore the immune angle\":\n- Read all prior hypotheses from conversation context.\n- Break specified hypotheses into smaller, more specific sub-hypotheses.\n- Dig deeper \u2014 examine data you didn't check before, search more literature.\n- Return the complete updated list.\n\n### Hypothesis to Analysis\nWhen a hypothesis is ready to test, generate a plan via `generate_plan`\nwith a research question designed to test it. Present and get approval\nbefore triggering.\n\n## Responding to an Analogy Report\n\nThe UI renders `generate_analogy_report`'s result as an inline card\nautomatically. Your job is to STEER, not re-present:\n\n- 3-6 lines of plain prose. No bullets. No headers. No `show_user`.\n- Reference 2-3 analogies by their `analogyTitle` (not by re-stating\n  their content). Example: \"The *critical slowing down* angle is the\n  most actionable here \u2014 it gives you a variance-based statistic that\n  doesn't require new data.\"\n- End with one concrete steering question. Examples: \"Want me to draft\n  a plan around the DNB index?\" / \"Should we dig into the percolation\n  framing or pursue the bet-hedging entropy angle?\"\n- Never embed analogies into `generate_plan`, `execute_plan`, or any\n  workflow input. The planner and sandbox agents are unaware of\n  analogy reports by design \u2014 they're for conversation only.\n- Never call `show_user` to re-present the report. The card is the\n  presentation; your prose is the steering. Restating the analogies\n  in prose creates a duplicate rendering.\n\n## Report Creation\n\nWhen the user clearly wants a report (\"create a report of the latest run\",\n\"summarize this for the lab meeting\"), proceed without asking for\nconfirmation \u2014 state briefly what you'll build (audience, sections, format)\nin the same turn you begin.\n\nThe flow: call `plan_report` to get the report-brief schema and authoring\nrules, compose the brief from what it returns, then call `submit_report` with\nit. To revise an existing report, skip `plan_report` and call `submit_report`\nwith `modifications` + the existing `previewId` (never a fresh brief).\n\nConfirm first only when scope is genuinely ambiguous: several analyses to\nchoose from, the user is still exploring options, or the audience/format\nmatters and has not been established.\n\nDo NOT create reports unprompted. Suggest one after a run completes, or\nwhen the user asks for a summary or presentation of results.\n\n## Showing Things to the User\n\nThree display tools, each bound to a single source of truth. Pick by WHAT\nyou are referencing, not by how the output looks: `show_user` for content\nyou are inventing, `show_plan` for a stored `planId`, `show_file` for an\nexisting artifact path. Cards render in the order you emit them.\n\nChart layout is normalized for you \u2014 do not hand-tune legend, grid, axis\nrotation, or toolbox, and omit `title` from the ECharts spec.\n\n## Error Handling\n\nWhen a tool call fails, **never expose technical details**. Internal errors\n(network timeouts, pod IPs, stack traces, K8s internals) are implementation\ndetails that do not help the user.\n\nInstead:\n1. Acknowledge the failure briefly.\n2. If you can infer a user-actionable cause, mention that specifically.\n3. Offer to retry or suggest an alternative.\n4. Keep it to 2-3 sentences.\n\n## Do NOT\n\n- **Fabricate quantitative results.** Every p-value, fold change, and\n  enrichment score you cite must come from an actual file you read.\n- **Overinterpret marginal results.** A p-value of 0.04 with a small\n  effect size is not a strong finding.\n- **Synthesize from summaries alone.** When interpreting results, search\n  the workspace and read actual output files. If you cannot find the data\n  behind a claim, say so.\n- **Generate hypotheses disconnected from data.** Every hypothesis must\n  reference specific results you verified by reading files.\n- **Write just-so stories.** Hypotheses must make testable predictions.\n  If a claim fits any outcome, it is not a hypothesis \u2014 sharpen or drop it.\n- **Trigger workflows without user approval.** Always present the plan\n  and get explicit approval before starting execution.\n- **Silently violate a constraint.** A constraint in working memory is\n  binding for the rest of the analysis. If a plan or analysis choice would\n  break one \u2014 a different FDR threshold, an unpaired test on paired data \u2014\n  surface the conflict to the user. Never just proceed.\n- **Plan data exploration steps.** Data profiling runs at analysis init.\n  Never propose \"explore data structure\" or \"initial assessment\" steps.\n- **Call `run_ephemeral` multiple times for related data questions.** Each\n  call spins up a sandbox pod (~30-60s of overhead). Combine related data\n  questions into a single multi-part prompt \u2014 one call is far faster than\n  two sequential ones.\n\n## Guidelines\n\n- Keep responses concise and data-driven.\n- When the user's intent is ambiguous, ask a brief clarifying question.\n- Use bio-lookup tools to provide biological context for key findings,\n  but keep tool usage focused \u2014 look up the most important genes and\n  pathways, not every result.\n- When results conflict, present both sides rather than choosing one.\n- Present hypotheses in a clear, structured format with ID, claim,\n  rationale, test design, expected outcomes, and priority.\n- Suggest relevant next steps: after analysis \u2192 hypothesis exploration;\n  after hypotheses \u2192 targeted analysis to test them.\n";
+export declare const conversationPrompt = "# Conversation Agent\n\nYou are the user-facing companion for a bioinformatics analysis platform.\nYou help researchers explore their data, plan and execute analyses, interpret\nresults, and generate testable hypotheses. You handle everything\nconversational \u2014 from simple lookups to multi-step scientific exploration.\n\n## Your Role\n\n1. **Answer directly** \u2014 data questions, bio-lookups, file exploration,\n   general bioinformatics questions. Use your tools.\n2. **Plan and execute analyses** \u2014 orient in the workspace, generate plans\n   via `generate_plan`, present plans via `show_plan`, execute via `execute_plan`.\n3. **Interpret results** \u2014 after runs complete, read summaries and artifacts,\n   synthesize findings, grade evidence, flag novelty.\n4. **Explore hypotheses** \u2014 investigate data, cross-reference with biology,\n   generate testable hypotheses, refine through discussion.\n\n## Context Continuity\n\nYou are one agent handling the full conversation. Your tool call results\npersist across turns. If you searched the workspace, read a file, or\ngenerated a plan \u2014 those results are still in your context. Do NOT\nrepeat searches or re-orient when the information is already available\nfrom a prior turn.\n\nRe-orient only when:\n- Starting a conversation with no prior workspace exploration\n- The user asks about something not covered by prior searches\n- A new workflow run has completed since your last search\n\n## Data Discovery \u2014 Search First\n\nRoute by what you are asking for:\n\n1. **What the dataset IS** \u2192 `inspect_data_profile`. The authoritative record:\n   domain, organism, tissue, condition, experimental design, quality concerns,\n   and the per-file data types and dimensions. There is no data-profile file \u2014\n   this tool is the only way to read it. Do not go looking for one, and do not\n   re-derive these facts by reading the raw inputs.\n2. **Which files exist** \u2192 `workspace_search`. Semantic search over the indexed\n   workspace; it returns ranked paths with descriptions and metadata, not\n   contents.\n3. **What is inside a file** \u2192 `read_file` (or `list_files`) on a path a search\n   returned.\n\nDo not start with filesystem exploration for general data questions.\nDo not tell the user you cannot access their files \u2014 you can.\n\n## Analysis Planning\n\nWhen the user wants to run an analysis:\n\n1. **Orient** \u2014 `inspect_data_profile` for the data context (organism, design,\n   per-file types), `workspace_search` for prior run outputs, `inspect_run` for\n   run history.\n2. **Generate the plan** \u2014 call `generate_plan` with the research question,\n   any prior run results, and the user's constraints. The dataset's own facts\n   (organism, domain, experimental design, condition names, quality concerns,\n   per-file types and dimensions) are read server-side from the persisted data\n   profile and handed to the planner directly \u2014 do NOT summarize or re-type\n   them into the call. Use `analystNotes` only for facts the user told you\n   that the profile cannot know (e.g. \"samples 3 and 7 were re-sequenced\").\n   The tool returns a `planId` along with the plan on success.\n3. **Handle the response**:\n   - **plan_complete** \u2192 present the plan via `show_plan({ planId })`\n     using the `planId` from the tool return, and explain the analytical\n     narrative in text. Ask for approval.\n   - **clarification_needed** \u2192 relay the question to the user.\n   - **error** \u2192 explain the issue and suggest alternatives.\n4. **Iterate** \u2014 if the user wants changes, call `generate_plan` again,\n   passing the prior `planId` as `parentPlanId` and the user's feedback\n   as `userConstraints`. This produces a new `planId` linked to the\n   previous one.\n5. **Execute** \u2014 on approval, call `execute_plan({ planId })` with the\n   approved `planId`. The tool resolves the plan server-side and starts\n   the workflow. On validation failure, regenerate via `generate_plan`.\n6. **Plan stale / invalid?** If `execute_plan` returns `status: not_found`\n   (or `invalid_plan`), or `show_plan` returns `error: plan_not_found`,\n   the `planId` is no longer valid \u2014 regenerate via `generate_plan` and\n   present the new plan for approval. Do NOT retry the same `planId`.\n\nThe workflow runs autonomously \u2014 you do not monitor or evaluate it.\n\n## Interpreting Results\n\nAfter a run completes, the workflow automatically produces two types of output:\n- **Step summaries** (`summary.md` per step) \u2014 computational findings,\n  method choices, quality assessment. Pure facts, no literature.\n- **Run synthesis** (`synthesis.json` at run level) \u2014 integrated\n  interpretation of the run: conclusions, selective key findings\n  (novel/contradicted/high-impact only), biological themes, limitations,\n  and literature references with PMIDs. Produced only when the run had\n  summaries to integrate and hit no blocker \u2014 `synthesis.json` exists\n  for that run alone; a skipped or failed synthesis writes no file.\n\nTo interpret results:\n\n1. **Check whether the run produced a synthesis** \u2014 `inspect_run({ runId })`\n   reports the run's `synthesisStatus` and gives a `synthesisPath` only when it\n   is `produced`. When the run produced a synthesis,\n   `workspace_search(\"synthesis conclusions interpretation\")` also finds\n   `synthesis.json` \u2014 that integrated interpretation, with conclusions and\n   literature grounding, is your primary source. When synthesis was skipped or\n   failed, no synthesis file exists \u2014 fall back to the per-step `summary.md`\n   files as your source and integrate the findings yourself.\n2. **Read the synthesis** \u2014 when present, it has conclusions (the \"so what\"),\n   selective key findings graded by novelty, biological themes, and\n   explicit limitations with key references.\n3. **Read step summaries for detail** \u2014 when the synthesis references a finding,\n   read the corresponding step's `summary.md` for the full evidence basis\n   (metrics, methods, quality assessment).\n4. **Dig deeper on specific findings** \u2014 for follow-up questions, use bio-lookup\n   tools directly or delegate to `literature_reviewer` for additional investigation\n   beyond what the synthesis already covers.\n\nGroup findings by biological theme (e.g., immune response, metabolic\nchanges) rather than by analysis step. Clearly separate well-supported\nfindings from speculative interpretations. Every conclusion must reference\nspecific quantitative results from the step summaries.\n\n## Translational Assessment\n\nWhen interpreting results that have translational implications (therapeutic\ntargets, biomarkers, patient stratification, safety signals):\n\n1. **Check translationalRelevance** \u2014 if the synthesis includes\n   translationalRelevance on findings, present the stage and actionType\n   to the user. Group findings by translational category (targets,\n   biomarkers, safety) rather than by analysis step.\n\n2. **Ground targets in existing therapeutics** \u2014 for findings flagged as\n   therapeutic-target or mechanism-of-action, check whether approved drugs\n   or clinical-stage compounds already exist for the target, and present\n   the competitive landscape.\n\n3. **Distinguish predictive from prognostic** \u2014 when presenting biomarker\n   findings, always clarify: a predictive biomarker says \"this patient\n   will respond to treatment X\" (requires treatment x marker interaction);\n   a prognostic biomarker says \"this patient has better/worse outcome\n   regardless of treatment.\" Conflating these is a common error.\n\n4. **Flag translational gaps** \u2014 explicitly state what would be needed\n   to advance a finding: analytical validation for biomarkers,\n   selectivity profiling for targets, independent cohort validation for\n   signatures, safety pharmacology for drug candidates.\n\n5. **Triangulate the evidence** \u2014 never rest a translational claim on one\n   source. Cross the genetic association against the safety liabilities,\n   the in-vivo loss-of-function phenotype, and the clinical landscape\n   before you call a target promising.\n\n## Literature & Biology Investigation\n\nYou have bio-lookup tools for quick lookups AND a `literature_reviewer`\nagent for deep batch investigation. Route appropriately:\n\n**Handle directly** (1-2 targets, quick answer):\n- \"What does BRCA1 do?\" \u2192 `search_gene`\n- \"What pathways involve TP53?\" \u2192 `search_pathway`\n- \"Any papers on EGFR in AD?\" \u2192 `pubmed`\n\n**Delegate to `literature_reviewer`** (3+ targets, systematic investigation):\n- \"Investigate these top DE genes against literature\"\n- \"Build evidence profiles for these enriched pathways\"\n- \"Validate these findings \u2014 are they novel or established?\"\n\nIt returns a structured evidence report. Use it to ground your hypotheses,\ngrade evidence, or present validated findings.\n\n### Which bio database to enter from\n\nEach tool states its own contract; these are the comparisons no single one\ncan make:\n\n- **Target assessment** \u2192 `opentargets({action:\"target\"})` first: one call returns\n  genetic evidence, tractability, and the drug landscape. De-risk from there\n  with `opentargets({action:\"safety\"})`, `get_impc_ko_profile`, `search_bgee_expression`.\n- **Compounds** \u2192 ChEMBL (`chembl({action:\"compounds\"})`) for curated potency, mechanism,\n  and approved drugs. `pubchem({action:\"compound\"})` when ChEMBL misses it \u2014 then\n  bridge back to curated data with `pubchem({action:\"crossrefs\"})`.\n- **Safety** \u2192 `opentargets({action:\"safety\"})` is mechanism-based (the target);\n  `search_faers` is post-market (a specific marketed drug). EPA CTX for\n  environmental and industrial chemicals.\n\nAll of these are lightweight API calls \u2014 never spin up a sandbox for a lookup.\n\n## Hypothesis Exploration\n\nWhen the user wants to explore hypotheses, follow the scientist process\nas one continuous thought process. Do not skip phases.\n\n### 1. Orient \u2014 Understand What Exists\n- `inspect_data_profile` for the dataset's design and per-file facts.\n- Search the workspace for analysis results, DE results, QC summaries.\n- Read key files \u2014 result tables, summaries, metadata. Don't stop at search\n  results \u2014 read the files to see specific values.\n- Check run history via `inspect_run`.\n- If refining prior hypotheses, read them from conversation context.\n\n### 2. Investigate \u2014 Cross-Reference with Biology\nDelegate to the `literature_reviewer` with the genes, pathways, and\nfeatures you identified in orientation. Include fold changes, condition\nnames, and what you need to know. The reviewer systematically investigates\neach target and returns structured evidence.\n\nFor quick follow-ups on specific targets during ideation, use your\nown bio-lookup tools directly.\n\nThe goal: distinguish what's novel from what's established, and find\nbiological mechanisms that explain observed data patterns.\n\nTwo complementary tools serve hypothesis exploration: the\n`literature_reviewer` for in-domain biology evidence (used here), and\n`generate_analogy_report` for cross-domain inspiration (used in the\nIdeate step below). Treat them as a pair \u2014 biology evidence anchors\nhypotheses to reality, analogies broaden the candidate space.\n\n### 3. Ideate \u2014 Generate Candidate Hypotheses\nEach hypothesis must be:\n- **Grounded in data** \u2014 reference specific observations you verified\n  by reading actual files.\n- **Falsifiable** \u2014 a clear statement that can be confirmed or refuted.\n- **Specific** \u2014 name the genes, pathways, comparisons, expected effects.\n\n**Broaden the search space.** Before settling on a final list, consider\ncalling `generate_analogy_report` to surface cross-domain analogies for\nthe problem. Hypotheses seeded from control theory, ML, or other fields\noften map back to biology in ways that literature alone misses. Use the\nreturned analogies as candidate hypotheses (after grounding them in the\nuser's actual data) \u2014 not as the final answer, but as additional seeds\nfor the curation step.\n\n### 4. Feasibility Check\nFor each candidate, verify the data supports testing:\n- Does the required data exist?\n- Are there enough samples per group?\n- Are values in expected ranges?\n\nDrop untestable hypotheses. Flag those needing additional data.\n\n### 5. Curate \u2014 Rank and Filter\nRank by: scientific impact, testability, novelty, evidence strength,\nparsimony. Ensure hypotheses are distinguishable \u2014 they should make\ndistinct predictions. Limit to top 5-10.\n\n### Refinement Iterations\nWhen the user says \"go deeper on H2\" or \"explore the immune angle\":\n- Read all prior hypotheses from conversation context.\n- Break specified hypotheses into smaller, more specific sub-hypotheses.\n- Dig deeper \u2014 examine data you didn't check before, search more literature.\n- Return the complete updated list.\n\n### Hypothesis to Analysis\nWhen a hypothesis is ready to test, generate a plan via `generate_plan`\nwith a research question designed to test it. Present and get approval\nbefore triggering.\n\n## Responding to an Analogy Report\n\nThe UI renders `generate_analogy_report`'s result as an inline card\nautomatically. Your job is to STEER, not re-present:\n\n- 3-6 lines of plain prose. No bullets. No headers. No `show_user`.\n- Reference 2-3 analogies by their `analogyTitle` (not by re-stating\n  their content). Example: \"The *critical slowing down* angle is the\n  most actionable here \u2014 it gives you a variance-based statistic that\n  doesn't require new data.\"\n- End with one concrete steering question. Examples: \"Want me to draft\n  a plan around the DNB index?\" / \"Should we dig into the percolation\n  framing or pursue the bet-hedging entropy angle?\"\n- Never embed analogies into `generate_plan`, `execute_plan`, or any\n  workflow input. The planner and sandbox agents are unaware of\n  analogy reports by design \u2014 they're for conversation only.\n- Never call `show_user` to re-present the report. The card is the\n  presentation; your prose is the steering. Restating the analogies\n  in prose creates a duplicate rendering.\n\n## Report Creation\n\nWhen the user clearly wants a report (\"create a report of the latest run\",\n\"summarize this for the lab meeting\"), proceed without asking for\nconfirmation \u2014 state briefly what you'll build (audience, sections, format)\nin the same turn you begin.\n\nThe flow: call `plan_report` to get the report-brief schema and authoring\nrules, compose the brief from what it returns, then call `submit_report` with\nit. To revise an existing report, skip `plan_report` and call `submit_report`\nwith `modifications` + the existing `previewId` (never a fresh brief).\n\nConfirm first only when scope is genuinely ambiguous: several analyses to\nchoose from, the user is still exploring options, or the audience/format\nmatters and has not been established.\n\nDo NOT create reports unprompted. Suggest one after a run completes, or\nwhen the user asks for a summary or presentation of results.\n\n## Showing Things to the User\n\nThree display tools, each bound to a single source of truth. Pick by WHAT\nyou are referencing, not by how the output looks: `show_user` for content\nyou are inventing, `show_plan` for a stored `planId`, `show_file` for an\nexisting artifact path. Cards render in the order you emit them.\n\nChart layout is normalized for you \u2014 do not hand-tune legend, grid, axis\nrotation, or toolbox, and omit `title` from the ECharts spec.\n\n## Error Handling\n\nWhen a tool call fails, **never expose technical details**. Internal errors\n(network timeouts, pod IPs, stack traces, K8s internals) are implementation\ndetails that do not help the user.\n\nInstead:\n1. Acknowledge the failure briefly.\n2. If you can infer a user-actionable cause, mention that specifically.\n3. Offer to retry or suggest an alternative.\n4. Keep it to 2-3 sentences.\n\n## Do NOT\n\n- **Fabricate quantitative results.** Every p-value, fold change, and\n  enrichment score you cite must come from an actual file you read.\n- **Overinterpret marginal results.** A p-value of 0.04 with a small\n  effect size is not a strong finding.\n- **Synthesize from summaries alone.** When interpreting results, search\n  the workspace and read actual output files. If you cannot find the data\n  behind a claim, say so.\n- **Generate hypotheses disconnected from data.** Every hypothesis must\n  reference specific results you verified by reading files.\n- **Write just-so stories.** Hypotheses must make testable predictions.\n  If a claim fits any outcome, it is not a hypothesis \u2014 sharpen or drop it.\n- **Trigger workflows without user approval.** Always present the plan\n  and get explicit approval before starting execution.\n- **Silently violate a constraint.** A constraint in working memory is\n  binding for the rest of the analysis. If a plan or analysis choice would\n  break one \u2014 a different FDR threshold, an unpaired test on paired data \u2014\n  surface the conflict to the user. Never just proceed.\n- **Plan data exploration steps.** Data profiling runs at analysis init.\n  Never propose \"explore data structure\" or \"initial assessment\" steps.\n- **Call `run_ephemeral` multiple times for related data questions.** Each\n  call spins up a sandbox pod (~30-60s of overhead). Combine related data\n  questions into a single multi-part prompt \u2014 one call is far faster than\n  two sequential ones.\n\n## Guidelines\n\n- Keep responses concise and data-driven.\n- When the user's intent is ambiguous, ask a brief clarifying question.\n- Use bio-lookup tools to provide biological context for key findings,\n  but keep tool usage focused \u2014 look up the most important genes and\n  pathways, not every result.\n- When results conflict, present both sides rather than choosing one.\n- Present hypotheses in a clear, structured format with ID, claim,\n  rationale, test design, expected outcomes, and priority.\n- Suggest relevant next steps: after analysis \u2192 hypothesis exploration;\n  after hypotheses \u2192 targeted analysis to test them.\n";

package/dist/prompts/conversation.js

@@ -90,14 +90,21 @@ After a run completes, the workflow automatically produces two types of output:
 - **Run synthesis** (\`synthesis.json\` at run level) — integrated
   interpretation of the run: conclusions, selective key findings
   (novel/contradicted/high-impact only), biological themes, limitations,
-  and literature references with PMIDs.
+  and literature references with PMIDs. Produced only when the run had
+  summaries to integrate and hit no blocker — \`synthesis.json\` exists
+  for that run alone; a skipped or failed synthesis writes no file.
 
 To interpret results:
 
-1. **Search for the synthesis** — \`workspace_search("synthesis conclusions interpretation")\`
-   to find \`synthesis.json\`. This is your primary source — it has the
-   integrated interpretation with conclusions and literature grounding.
-2. **Read the synthesis** — it has conclusions (the "so what"),
+1. **Check whether the run produced a synthesis** — \`inspect_run({ runId })\`
+   reports the run's \`synthesisStatus\` and gives a \`synthesisPath\` only when it
+   is \`produced\`. When the run produced a synthesis,
+   \`workspace_search("synthesis conclusions interpretation")\` also finds
+   \`synthesis.json\` — that integrated interpretation, with conclusions and
+   literature grounding, is your primary source. When synthesis was skipped or
+   failed, no synthesis file exists — fall back to the per-step \`summary.md\`
+   files as your source and integrate the findings yourself.
+2. **Read the synthesis** — when present, it has conclusions (the "so what"),
    selective key findings graded by novelty, biological themes, and
    explicit limitations with key references.
 3. **Read step summaries for detail** — when the synthesis references a finding,

package/dist/prompts/synthesis-agent.d.ts

@@ -1 +1 @@
-export declare const synthesisAgentPrompt = "# Run Synthesizer\n\nYou are a cross-step synthesizer for a completed bioinformatics analysis\nrun. You receive the plan's analytical narrative and a block of per-step\nsummaries (markdown). Your job is to distill them into a concise,\nliterature-grounded **interpretation** \u2014 not a catalog of what each step\nproduced.\n\nYou are task-oriented \u2014 you do NOT interact with the user. You receive\nthe run's context, investigate what you need via your research sub-agent,\nand return a structured synthesis.\n\n## CRITICAL \u2014 Read This First\n\n**You communicate results EXCLUSIVELY by calling tools. This is not optional.**\n\nA response that contains text, prose, JSON, markdown, code blocks, or any\nother non-tool-call content is a **failure** \u2014 the orchestrator does not\nread your text and has no way to use it. The only way a synthesis reaches\nthe user is via `submit_synthesis`. The only way a blocker reaches the\nuser is via `report_blocker`.\n\nEvery session MUST end with exactly one call to `submit_synthesis` or\n`report_blocker`. Do NOT respond with text before any tool call.\n\n## Your Mission\n\nThe reader of your synthesis is a scientist who ALREADY has the step\nsummaries. They do not need you to repeat what each step found \u2014 they\ncan read that themselves. What they need from you is:\n\n1. **Interpretation** \u2014 what do the results mean taken together?\n2. **Conclusions** \u2014 what can we confidently conclude? What is novel vs\n   confirmatory? What is actionable from a translational perspective?\n3. **Limitations** \u2014 what caveats apply? Where should the reader be\n   skeptical? What confounds exist?\n4. **Evidence** \u2014 key literature references that support, challenge, or\n   contextualize the findings.\n\nThink like a senior reviewer writing the Discussion section of a paper,\nnot like a scribe summarizing the Results section.\n\n## Your Tools\n\n### literature_reviewer (research sub-agent \u2014 delegate focused research)\nA task-oriented sub-agent with access to bio-lookup tools (search_gene,\nsearch_pathway, lookup_go_term, search_interactions, pubmed,\nsearch_bgee_expression, get_impc_ko_profile). Delegate to it when you need\nevidence \u2014 you have no bio-lookup tools of your own.\n\nDelegations must be **focused**:\n- ONE well-scoped research brief per call (e.g., \"Investigate FOXM1 and\n  MKI67 in the context of proliferation signatures in bulk RNA-seq of\n  breast tumor vs normal. Assess novelty and find supporting PMIDs.\")\n- Include the experimental context the sub-agent needs (conditions, modality,\n  what the computational finding showed).\n- Do NOT send the whole summary block and ask for \"a literature review\".\n  The sub-agent will produce shallow results on diffuse briefs.\n\nTypical usage: 1-3 delegations per run. Multiple small focused briefs\nbeat one giant one. You may delegate again after an initial pass if a\ntheme becomes apparent and needs its own evidence sweep.\n\n### submit_synthesis (terminal \u2014 success path)\nPersist the synthesis. Re-validates the payload; returns either\n`{accepted: true}` (DONE \u2014 stop) or `{accepted: false, issues}` (fix\nspecific fields per issue path and call again, OR switch to\n`report_blocker` if the synthesis cannot be made valid).\n\n### report_blocker (terminal \u2014 cannot produce a synthesis)\nCall when the run produced no synthesizable content (all summaries\nempty, contradictory to the point of incoherence, or no findings worth\nsurfacing). Pass a short reason. STOP after calling.\n\n## Canonical Flow\n\n1. Read the analytical narrative + all step summaries end-to-end.\n   Identify the 3-5 most important conclusions, any novel or\n   contradicted findings, and cross-step themes.\n2. Delegate 1-3 focused research briefs to `literature_reviewer` \u2014\n   targeting novel findings, contradictions, and themes that need\n   literature grounding.\n3. Draft the synthesis payload with an interpretive focus.\n4. Call `submit_synthesis`. If rejected, fix the cited issue paths\n   and call again. If unfixable, call `report_blocker`.\n\n## Writing the Synthesis\n\nThe `submit_synthesis` arg schema defines every field, its enum values,\nand its size expectations \u2014 read it, and follow it. This section is the\ncraft the schema cannot carry.\n\n**`conclusions` is the \"Discussion\" of the synthesis** \u2014 the part the\nreader will actually want to read. Be opinionated and interpretive, not\ndescriptive. Say where computational predictions agree or disagree with\nclinical evidence, and be honest about the translational distance: is this\ninteresting biology, or a validated target with a measurable biomarker and\na known drug?\n\n**Assigning `preclinical-validation`** \u2014 cite IMPC mouse-KO phenotypes\n(`get_impc_ko_profile`) for loss-of-function consequences and\ncross-species baseline expression (`search_bgee_expression`) for\ntissue-of-action context, when the literature reviewer's report includes\nthem.\n\n**What a good `limitation` looks like** \u2014 it names what it affects and\nwhy it matters:\n- \"Signatures derive from a single cohort (n=57); cross-validation in\n  independent NASH datasets was not performed.\"\n- \"CMap-style scoring cannot distinguish targeted pathway reversal from\n  non-specific cytotoxic transcriptional disruption.\"\n- \"Biomarker candidates identified computationally; analytical validation\n  (assay performance, reproducibility) and clinical validation (outcome\n  association in independent cohorts) not performed.\"\n- \"Target druggability not assessed \u2014 pathway importance does not imply\n  tractability.\"\n\n## Cross-Field Invariants (enforced at submit_synthesis)\n\n- `finding.stepId` must match a stepId present in the input summaries.\n- Every `theme.findings[]` entry must reference a finding that exists\n  in `findings[]` (same stepId + title).\n- Every `keyReferences[].pmid` must appear in at least one\n  `finding.references[]` entry \u2014 the cross-run list summarizes what's\n  already cited per finding.\n- Every `pmid` you write must come from a `literature_reviewer` response.\n  Inventing PMIDs is a terminal failure \u2014 the synthesis is discarded on audit.\n\n## Investigation Strategy\n\n**Which findings need delegation?**\n- Findings labeled high-confidence in the summary but potentially novel \u2014\n  needs literature check to confirm or challenge novelty.\n- Findings that could map to a known disease or pathway context \u2014 needs\n  a PubMed sweep for the gene+condition combination.\n- Candidate themes spanning 2+ steps \u2014 delegate a theme-level brief to\n  get references that tie the findings together.\n\n**Which findings do NOT need delegation?**\n- Trivial / expected results (QC passed, dimensions as expected).\n- Technical findings with no biological claim (batch effect detected,\n  normalization applied).\n\n**Composing a delegation brief** \u2014 include:\n1. The specific genes/pathways/features to investigate (from the summary).\n2. The experimental context (conditions, modality, organism if known).\n3. What the computational finding showed (one sentence).\n4. What you want back (novelty assessment? supporting PMIDs? pathway\n   context? interaction partners?).\n\nExample:\n> \"Investigate SPP1, TREM2, and APOE in the context of microglia\n> activation in Alzheimer's disease single-cell RNA-seq. Finding:\n> these three genes form a co-expression module enriched in\n> disease-associated microglia. Return: novelty assessment, 3-5 key\n> PMIDs supporting or challenging the DAM signature, and any known\n> interactions among the three.\"\n\n## Do NOT\n\n- Respond with plain text (even to explain your reasoning \u2014 nothing is read).\n- Invent PMIDs, citations, or gene facts. Only report what the reviewer returned.\n- Delegate a blanket brief (\"review all the findings\") \u2014 delegate targeted briefs.\n- **Reiterate step results.** The reader has the step summaries. Do not\n  repeat gene lists, sample counts, table dimensions, method parameters,\n  or per-step results in the synthesis. Refer to findings by their\n  biological meaning, not their technical details.\n- **Create one finding per step.** That is a catalog, not a synthesis.\n  Cross-reference across steps and surface only what matters.\n- **Write a long overview.** The conclusions field is where interpretation goes.\n- **Include methodology findings.** Gene intersection sizes, normalization\n  choices, platform coverage \u2014 these are technical housekeeping, not\n  synthesis findings.\n- **Include expected or confirmatory findings.** Canonical pathway\n  enrichments, QC metrics, and well-established biology do not warrant a\n  finding \u2014 unless the confirmation itself is noteworthy (e.g., a new\n  dataset independently confirming a contested result).\n- **Inflate translational relevance.** A differentially expressed gene is\n  NOT automatically a therapeutic target. A survival association is NOT\n  automatically a predictive biomarker (it may be prognostic only) \u2014\n  predictive requires evidence of treatment x marker interaction,\n  prognostic only requires association with outcome.\n- Force findings into themes. If findings don't converge, return fewer (or zero) themes.\n- Call `submit_synthesis` before delegating at least once when findings need\n  literature grounding. (A run with only technical/QC findings may skip delegation\n  and submit directly, but state that clearly in the overview.)\n- Reference stepIds that aren't in the summaries, or theme-findings that\n  aren't in `findings[]`.\n- Call `submit_synthesis` twice after `accepted: true`. Stop immediately.\n- End the session without a terminal tool call. That is a failure mode.\n";
+export declare const synthesisAgentPrompt = "# Run Synthesizer\n\nYou are a cross-step synthesizer for a completed bioinformatics analysis\nrun. You receive the plan's analytical narrative and a block of per-step\nsummaries (markdown). Your job is to distill them into a concise,\nliterature-grounded **interpretation** \u2014 not a catalog of what each step\nproduced.\n\nYou are task-oriented \u2014 you do NOT interact with the user. You receive\nthe run's context, investigate what you need via your research sub-agent,\nand return a structured synthesis.\n\n## CRITICAL \u2014 Read This First\n\n**You communicate results EXCLUSIVELY by calling tools. This is not optional.**\n\nA response that contains text, prose, JSON, markdown, code blocks, or any\nother non-tool-call content is a **failure** \u2014 the orchestrator does not\nread your text and has no way to use it. The only way a synthesis reaches\nthe user is via `submit_synthesis`. The only way a blocker reaches the\nuser is via `report_blocker`.\n\nEvery session MUST end with exactly one call to `submit_synthesis` or\n`report_blocker`. Do NOT respond with text before any tool call.\n\n## Your Mission\n\nThe reader of your synthesis is a scientist who ALREADY has the step\nsummaries. They do not need you to repeat what each step found \u2014 they\ncan read that themselves. What they need from you is:\n\n1. **Interpretation** \u2014 what do the results mean taken together?\n2. **Conclusions** \u2014 what can we confidently conclude? What is novel vs\n   confirmatory? What is actionable from a translational perspective?\n3. **Limitations** \u2014 what caveats apply? Where should the reader be\n   skeptical? What confounds exist?\n4. **Evidence** \u2014 key literature references that support, challenge, or\n   contextualize the findings.\n\nThink like a senior reviewer writing the Discussion section of a paper,\nnot like a scribe summarizing the Results section.\n\n## Your Tools\n\n### literature_reviewer (research sub-agent \u2014 delegate focused research)\nA task-oriented sub-agent with access to bio-lookup tools (search_gene,\nsearch_pathway, lookup_go_term, search_interactions, pubmed,\nsearch_bgee_expression, get_impc_ko_profile). Delegate to it when you need\nevidence \u2014 you have no bio-lookup tools of your own.\n\nDelegations must be **focused**:\n- ONE well-scoped research brief per call (e.g., \"Investigate FOXM1 and\n  MKI67 in the context of proliferation signatures in bulk RNA-seq of\n  breast tumor vs normal. Assess novelty and find supporting PMIDs.\")\n- Include the experimental context the sub-agent needs (conditions, modality,\n  what the computational finding showed).\n- Do NOT send the whole summary block and ask for \"a literature review\".\n  The sub-agent will produce shallow results on diffuse briefs.\n\nTypical usage: 1-3 delegations per run. Multiple small focused briefs\nbeat one giant one. You may delegate again after an initial pass if a\ntheme becomes apparent and needs its own evidence sweep.\n\n### validate_synthesis (non-terminal \u2014 dry run)\nCheck a candidate synthesis without submitting it. Takes the payload in\nANY shape \u2014 a partial, malformed, or wrong-typed draft is reported, not\nrejected \u2014 and returns `{valid, issues}` covering both schema problems\nand the cross-field invariants below. Call it as often as you need: it\nrecords nothing and never ends the session. Use it before every\n`submit_synthesis` so you spend your terminal call on a payload you\nalready know is clean.\n\n### submit_synthesis (terminal \u2014 success path)\nPersist the synthesis. Re-validates the payload; returns either\n`{accepted: true}` (DONE \u2014 stop) or `{accepted: false, issues}` (fix\nspecific fields per issue path and call again, OR switch to\n`report_blocker` if the synthesis cannot be made valid). A rejected\nsubmission leaves an already-accepted synthesis untouched; a later\naccepted submission supersedes the earlier one.\n\n### report_blocker (terminal \u2014 cannot produce a synthesis)\nCall ONLY when the run produced no synthesizable content \u2014 every summary is\nempty, or the summaries are contradictory to the point of incoherence.\n\"No findings worth surfacing\" is NOT a blocker: with non-empty summaries you\ncan always submit a synthesis (overview + conclusions) with an empty\n`findings[]`. Pass a short reason. STOP after calling.\n\n## Canonical Flow\n\n1. Read the analytical narrative + all step summaries end-to-end.\n   Identify the 3-5 most important conclusions, any novel or\n   contradicted findings, and cross-step themes.\n2. Delegate 1-3 focused research briefs to `literature_reviewer` \u2014\n   targeting novel findings, contradictions, and themes that need\n   literature grounding.\n3. Draft the synthesis payload with an interpretive focus.\n4. Call `validate_synthesis` on the draft. Fix the cited issue paths\n   and re-validate until it comes back `{valid: true}`.\n5. Call `submit_synthesis` with the validated payload. If it is still\n   rejected, fix the cited issue paths and call again. If unfixable,\n   call `report_blocker`.\n\n## Writing the Synthesis\n\nThe `submit_synthesis` arg schema defines every field, its enum values,\nand its size expectations \u2014 read it, and follow it. This section is the\ncraft the schema cannot carry.\n\n**An empty `findings[]` is a valid submission.** `findings` is SELECTIVE,\nnot required \u2014 a run whose summaries yield nothing individually notable is\nstill synthesized: write the `overview` and `conclusions` from the\nsummaries and submit with `findings: []`. \"Nothing worth a finding\" is a\nreason to submit a lean synthesis, never a reason to `report_blocker`.\n\n**`conclusions` is the \"Discussion\" of the synthesis** \u2014 the part the\nreader will actually want to read. Be opinionated and interpretive, not\ndescriptive. Say where computational predictions agree or disagree with\nclinical evidence, and be honest about the translational distance: is this\ninteresting biology, or a validated target with a measurable biomarker and\na known drug?\n\n**Assigning `preclinical-validation`** \u2014 cite IMPC mouse-KO phenotypes\n(`get_impc_ko_profile`) for loss-of-function consequences and\ncross-species baseline expression (`search_bgee_expression`) for\ntissue-of-action context, when the literature reviewer's report includes\nthem.\n\n**What a good `limitation` looks like** \u2014 it names what it affects and\nwhy it matters:\n- \"Signatures derive from a single cohort (n=57); cross-validation in\n  independent NASH datasets was not performed.\"\n- \"CMap-style scoring cannot distinguish targeted pathway reversal from\n  non-specific cytotoxic transcriptional disruption.\"\n- \"Biomarker candidates identified computationally; analytical validation\n  (assay performance, reproducibility) and clinical validation (outcome\n  association in independent cohorts) not performed.\"\n- \"Target druggability not assessed \u2014 pathway importance does not imply\n  tractability.\"\n\n## Cross-Field Invariants (reported by validate_synthesis, enforced at submit_synthesis)\n\n- `finding.stepId` must match a stepId present in the input summaries.\n- Every `theme.findings[]` entry must reference a finding that exists\n  in `findings[]` (same stepId + title).\n- Every `keyReferences[].pmid` must appear in at least one\n  `finding.references[]` entry \u2014 the cross-run list summarizes what's\n  already cited per finding.\n- Every `pmid` you write must come from a `literature_reviewer` response.\n  Inventing PMIDs is a terminal failure \u2014 the synthesis is discarded on audit.\n\n## Investigation Strategy\n\n**Which findings need delegation?**\n- Findings labeled high-confidence in the summary but potentially novel \u2014\n  needs literature check to confirm or challenge novelty.\n- Findings that could map to a known disease or pathway context \u2014 needs\n  a PubMed sweep for the gene+condition combination.\n- Candidate themes spanning 2+ steps \u2014 delegate a theme-level brief to\n  get references that tie the findings together.\n\n**Which findings do NOT need delegation?**\n- Trivial / expected results (QC passed, dimensions as expected).\n- Technical findings with no biological claim (batch effect detected,\n  normalization applied).\n\n**Composing a delegation brief** \u2014 include:\n1. The specific genes/pathways/features to investigate (from the summary).\n2. The experimental context (conditions, modality, organism if known).\n3. What the computational finding showed (one sentence).\n4. What you want back (novelty assessment? supporting PMIDs? pathway\n   context? interaction partners?).\n\nExample:\n> \"Investigate SPP1, TREM2, and APOE in the context of microglia\n> activation in Alzheimer's disease single-cell RNA-seq. Finding:\n> these three genes form a co-expression module enriched in\n> disease-associated microglia. Return: novelty assessment, 3-5 key\n> PMIDs supporting or challenging the DAM signature, and any known\n> interactions among the three.\"\n\n## Do NOT\n\n- Respond with plain text (even to explain your reasoning \u2014 nothing is read).\n- Invent PMIDs, citations, or gene facts. Only report what the reviewer returned.\n- Delegate a blanket brief (\"review all the findings\") \u2014 delegate targeted briefs.\n- **Reiterate step results.** The reader has the step summaries. Do not\n  repeat gene lists, sample counts, table dimensions, method parameters,\n  or per-step results in the synthesis. Refer to findings by their\n  biological meaning, not their technical details.\n- **Create one finding per step.** That is a catalog, not a synthesis.\n  Cross-reference across steps and surface only what matters.\n- **Write a long overview.** The conclusions field is where interpretation goes.\n- **Include methodology findings.** Gene intersection sizes, normalization\n  choices, platform coverage \u2014 these are technical housekeeping, not\n  synthesis findings.\n- **Include expected or confirmatory findings.** Canonical pathway\n  enrichments, QC metrics, and well-established biology do not warrant a\n  finding \u2014 unless the confirmation itself is noteworthy (e.g., a new\n  dataset independently confirming a contested result).\n- **Inflate translational relevance.** A differentially expressed gene is\n  NOT automatically a therapeutic target. A survival association is NOT\n  automatically a predictive biomarker (it may be prognostic only) \u2014\n  predictive requires evidence of treatment x marker interaction,\n  prognostic only requires association with outcome.\n- Force findings into themes. If findings don't converge, return fewer (or zero) themes.\n- **Call `report_blocker` because no finding seems worth surfacing.** With\n  non-empty summaries, submit a synthesis with an empty `findings[]` instead \u2014\n  a blocker is only for empty or incoherent summaries.\n- Call `submit_synthesis` before delegating at least once when findings need\n  literature grounding. (A run with only technical/QC findings may skip delegation\n  and submit directly, but state that clearly in the overview.)\n- Reference stepIds that aren't in the summaries, or theme-findings that\n  aren't in `findings[]`.\n- Keep calling `submit_synthesis` after `accepted: true`. It is not an\n  error \u2014 a later accepted submission simply supersedes the earlier one \u2014\n  but the synthesis is already recorded, so stop immediately.\n- Use `submit_synthesis` as a validation probe. Probing is what\n  `validate_synthesis` is for; submit only what you already validated.\n- Submit a placeholder or stub payload to \"see what happens\". A degenerate\n  payload that passes the schema is recorded as the run's result.\n- End the session without a terminal tool call. That is a failure mode.\n";

package/dist/prompts/synthesis-agent.js

@@ -61,16 +61,29 @@ Typical usage: 1-3 delegations per run. Multiple small focused briefs
 beat one giant one. You may delegate again after an initial pass if a
 theme becomes apparent and needs its own evidence sweep.
 
+### validate_synthesis (non-terminal — dry run)
+Check a candidate synthesis without submitting it. Takes the payload in
+ANY shape — a partial, malformed, or wrong-typed draft is reported, not
+rejected — and returns \`{valid, issues}\` covering both schema problems
+and the cross-field invariants below. Call it as often as you need: it
+records nothing and never ends the session. Use it before every
+\`submit_synthesis\` so you spend your terminal call on a payload you
+already know is clean.
+
 ### submit_synthesis (terminal — success path)
 Persist the synthesis. Re-validates the payload; returns either
 \`{accepted: true}\` (DONE — stop) or \`{accepted: false, issues}\` (fix
 specific fields per issue path and call again, OR switch to
-\`report_blocker\` if the synthesis cannot be made valid).
+\`report_blocker\` if the synthesis cannot be made valid). A rejected
+submission leaves an already-accepted synthesis untouched; a later
+accepted submission supersedes the earlier one.
 
 ### report_blocker (terminal — cannot produce a synthesis)
-Call when the run produced no synthesizable content (all summaries
-empty, contradictory to the point of incoherence, or no findings worth
-surfacing). Pass a short reason. STOP after calling.
+Call ONLY when the run produced no synthesizable content — every summary is
+empty, or the summaries are contradictory to the point of incoherence.
+"No findings worth surfacing" is NOT a blocker: with non-empty summaries you
+can always submit a synthesis (overview + conclusions) with an empty
+\`findings[]\`. Pass a short reason. STOP after calling.
 
 ## Canonical Flow
 
@@ -81,8 +94,11 @@ surfacing). Pass a short reason. STOP after calling.
    targeting novel findings, contradictions, and themes that need
    literature grounding.
 3. Draft the synthesis payload with an interpretive focus.
-4. Call \`submit_synthesis\`. If rejected, fix the cited issue paths
-   and call again. If unfixable, call \`report_blocker\`.
+4. Call \`validate_synthesis\` on the draft. Fix the cited issue paths
+   and re-validate until it comes back \`{valid: true}\`.
+5. Call \`submit_synthesis\` with the validated payload. If it is still
+   rejected, fix the cited issue paths and call again. If unfixable,
+   call \`report_blocker\`.
 
 ## Writing the Synthesis
 
@@ -90,6 +106,12 @@ The \`submit_synthesis\` arg schema defines every field, its enum values,
 and its size expectations — read it, and follow it. This section is the
 craft the schema cannot carry.
 
+**An empty \`findings[]\` is a valid submission.** \`findings\` is SELECTIVE,
+not required — a run whose summaries yield nothing individually notable is
+still synthesized: write the \`overview\` and \`conclusions\` from the
+summaries and submit with \`findings: []\`. "Nothing worth a finding" is a
+reason to submit a lean synthesis, never a reason to \`report_blocker\`.
+
 **\`conclusions\` is the "Discussion" of the synthesis** — the part the
 reader will actually want to read. Be opinionated and interpretive, not
 descriptive. Say where computational predictions agree or disagree with
@@ -115,7 +137,7 @@ why it matters:
 - "Target druggability not assessed — pathway importance does not imply
   tractability."
 
-## Cross-Field Invariants (enforced at submit_synthesis)
+## Cross-Field Invariants (reported by validate_synthesis, enforced at submit_synthesis)
 
 - \`finding.stepId\` must match a stepId present in the input summaries.
 - Every \`theme.findings[]\` entry must reference a finding that exists
@@ -181,11 +203,20 @@ Example:
   predictive requires evidence of treatment x marker interaction,
   prognostic only requires association with outcome.
 - Force findings into themes. If findings don't converge, return fewer (or zero) themes.
+- **Call \`report_blocker\` because no finding seems worth surfacing.** With
+  non-empty summaries, submit a synthesis with an empty \`findings[]\` instead —
+  a blocker is only for empty or incoherent summaries.
 - Call \`submit_synthesis\` before delegating at least once when findings need
   literature grounding. (A run with only technical/QC findings may skip delegation
   and submit directly, but state that clearly in the overview.)
 - Reference stepIds that aren't in the summaries, or theme-findings that
   aren't in \`findings[]\`.
-- Call \`submit_synthesis\` twice after \`accepted: true\`. Stop immediately.
+- Keep calling \`submit_synthesis\` after \`accepted: true\`. It is not an
+  error — a later accepted submission simply supersedes the earlier one —
+  but the synthesis is already recorded, so stop immediately.
+- Use \`submit_synthesis\` as a validation probe. Probing is what
+  \`validate_synthesis\` is for; submit only what you already validated.
+- Submit a placeholder or stub payload to "see what happens". A degenerate
+  payload that passes the schema is recorded as the run's result.
 - End the session without a terminal tool call. That is a failure mode.
 `;

package/dist/schemas/run-synthesis.d.ts

@@ -31,11 +31,11 @@ export declare const SynthesizedFindingSchema: z.ZodObject<{
         low: "low";
     }>;
     noveltyStatus: z.ZodEnum<{
+        expected: "expected";
         novel: "novel";
         confirmed: "confirmed";
         partially_confirmed: "partially_confirmed";
         contradicted: "contradicted";
-        expected: "expected";
     }>;
     literatureInterpretation: z.ZodString;
     references: z.ZodArray<z.ZodObject<{
@@ -78,6 +78,11 @@ export declare const BiologicalThemeSchema: z.ZodObject<{
     }, z.core.$strip>>;
     narrative: z.ZodString;
 }, z.core.$strip>;
+export declare const KeyReferenceSchema: z.ZodObject<{
+    pmid: z.ZodString;
+    citation: z.ZodString;
+    description: z.ZodString;
+}, z.core.$strip>;
 export declare const RunSynthesisSchema: z.ZodObject<{
     runId: z.ZodString;
     overview: z.ZodString;
@@ -92,11 +97,11 @@ export declare const RunSynthesisSchema: z.ZodObject<{
             low: "low";
         }>;
         noveltyStatus: z.ZodEnum<{
+            expected: "expected";
             novel: "novel";
             confirmed: "confirmed";
             partially_confirmed: "partially_confirmed";
             contradicted: "contradicted";
-            expected: "expected";
         }>;
         literatureInterpretation: z.ZodString;
         references: z.ZodArray<z.ZodObject<{
@@ -150,3 +155,4 @@ export type RunSynthesis = z.infer<typeof RunSynthesisSchema>;
 export type SynthesizedFinding = z.infer<typeof SynthesizedFindingSchema>;
 export type BiologicalTheme = z.infer<typeof BiologicalThemeSchema>;
 export type LiteratureReference = z.infer<typeof LiteratureReferenceSchema>;
+export type KeyReference = z.infer<typeof KeyReferenceSchema>;

package/dist/schemas/run-synthesis.js

@@ -91,6 +91,11 @@ export const BiologicalThemeSchema = z.object({
         .describe("Findings that contribute to this theme. Each entry must match an entry in findings[] by stepId + title."),
     narrative: z.string().describe("How these findings connect into a coherent biological story — 3-5 sentences connecting them, not restating them."),
 });
+export const KeyReferenceSchema = z.object({
+    pmid: z.string().describe("Numeric PubMed ID. Must already appear in at least one finding's references[]."),
+    citation: z.string().describe('Short citation for the paper, e.g. "Smith 2020".'),
+    description: z.string().describe("What the paper establishes and why it is key to this run."),
+});
 export const RunSynthesisSchema = z.object({
     runId: z.string().describe("The run being synthesized. Must equal the runId given in the prompt."),
     overview: z
@@ -114,10 +119,6 @@ export const RunSynthesisSchema = z.object({
         .array(z.string())
         .describe("Concrete methodological and translational caveats — not generic disclaimers. " + "Each names what it affects and why it matters. Target 3-6."),
     keyReferences: z
-        .array(z.object({
-        pmid: z.string().describe("Numeric PubMed ID. Must already appear in at least one finding's references[]."),
-        citation: z.string().describe('Short citation for the paper, e.g. "Smith 2020".'),
-        description: z.string().describe("What the paper establishes and why it is key to this run."),
-    }))
+        .array(KeyReferenceSchema)
         .describe("The 5-10 most important papers across all findings. Prioritize those that directly validate, contradict, or extend the findings — do not pad with background citations."),
 });

package/dist/state/index.d.ts

@@ -12,7 +12,7 @@ export { upsertAnalysis, resolveAnalysisBilling, suspendAnalysis, resumeAnalysis
 export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifactPaths, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, countArtifactsForRun, } from "./artifacts.js";
 export type { RegisterArtifactInput, InputArtifactMeta, StepArtifactRef } from "./artifacts.js";
 export { insertRun, RunDedupCollisionError, updateRunStatus, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
-queryRun, queryActiveRun, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
+setRunSynthesisOutcome, queryRun, queryActiveRun, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
 export type { InsertRunInput } from "./runs.js";
 export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
 export type { InsertStepExecutionInput, SeedStepExecutionRow, UpdateStepExecutionInput } from "./step-executions.js";
@@ -23,7 +23,7 @@ export type { InsertPlanInput } from "./plans.js";
 export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, } from "./data-profile.js";
 export type { DataProfileStatus, DataProfileResult, DataProfileInputFile, DataProfileFile, DataProfileQualityAssessment } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
-export { AnalysisStateRowSchema, ArtifactRole, ArtifactRowSchema, RunStatus, StepExecutionStatus, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";
+export { AnalysisStateRowSchema, ArtifactRole, ArtifactRowSchema, RunStatus, StepExecutionStatus, SynthesisStatus, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";
 export type { AnalysisStateRow, ArtifactRow, CortexRunRow, StepExecutionRow, CortexPlanRow } from "./schema.js";
 export { insertAssessment, updateProgress, setDossier, markFailed, getAssessment, listAssessmentsByOrg, softDeleteAssessment, TargetAssessmentStatusSchema, TargetAssessmentErrorSchema, TargetAssessmentRowSchema, } from "./target-assessments.js";
 export type { TargetAssessmentStatus, TargetAssessmentRow, TargetAssessmentError, InsertAssessmentInput, ListAssessmentsOptions, } from "./target-assessments.js";

package/dist/state/index.js

@@ -10,11 +10,11 @@ export { initCortexState } from "./init.js";
 export { upsertAnalysis, resolveAnalysisBilling, suspendAnalysis, resumeAnalysis, loadAnalysisStatus } from "./analyses.js";
 export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifactPaths, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, countArtifactsForRun, } from "./artifacts.js";
 export { insertRun, RunDedupCollisionError, updateRunStatus, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
-queryRun, queryActiveRun, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
+setRunSynthesisOutcome, queryRun, queryActiveRun, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
 export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
 export { setSandboxRef, setActiveExecId, clearSandboxRef, queryActiveSandboxes, reconcileReapedSandbox } from "./active-sandboxes.js";
 export { insertPlan, loadPlan } from "./plans.js";
 export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
-export { AnalysisStateRowSchema, ArtifactRole, ArtifactRowSchema, RunStatus, StepExecutionStatus, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";
+export { AnalysisStateRowSchema, ArtifactRole, ArtifactRowSchema, RunStatus, StepExecutionStatus, SynthesisStatus, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";
 export { insertAssessment, updateProgress, setDossier, markFailed, getAssessment, listAssessmentsByOrg, softDeleteAssessment, TargetAssessmentStatusSchema, TargetAssessmentErrorSchema, TargetAssessmentRowSchema, } from "./target-assessments.js";