@inflexa-ai/harness 0.36.1 → 0.36.2

package/dist/contracts/chat-parts.d.ts

@@ -46,6 +46,18 @@ export type PresentationContent =
     headers: string[];
     rows: string[][];
     caption?: string;
+}
+/** A versioned AlphaFold DB model file, normalized by the harness from the URL the agent named
+ *  (`contracts/structure-source.ts`). `version` is the model version that was shown — a host that
+ *  substitutes a newer file after AlphaFold purges this one labels the substitution and never
+ *  rewrites the card. The host fetches `url` directly; the coordinates never ride the wire. */
+ | {
+    kind: "structure";
+    format: "pdb" | "mmcif";
+    url: string;
+    provider: "alphafold";
+    accession: string;
+    version: number;
 };
 export interface PresentationPart {
     type: "data-presentation";

package/dist/contracts/index.d.ts

@@ -15,3 +15,5 @@ export type { CortexChatPartType, PartDescriptor, PartEmitter, PartConsumer } fr
 export { AnalogyCoverageSchema, AnalogyReportSchema, AnalogyReportErrorSchema, AnalogicalReasonerOutputSchema } from "./analogy-report.js";
 export type { AnalogyCoverage, AnalogyReport, AnalogyReportError, AnalogicalReasonerOutput } from "./analogy-report.js";
 export { buildReportSessionUrl, reportSessionResourceId } from "./content-url.js";
+export { parseStructureUrl, alphafoldEntryUrl, alphafoldPredictionUrl } from "./structure-source.js";
+export type { StructureSource, StructureFormat } from "./structure-source.js";

package/dist/contracts/index.js

@@ -5,3 +5,4 @@ export { DIMENSION_CATEGORIES, DIMENSION_CATEGORY_IDS, DIMENSION_PROBE_IDS, DIME
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./part-registry.js";
 export { AnalogyCoverageSchema, AnalogyReportSchema, AnalogyReportErrorSchema, AnalogicalReasonerOutputSchema } from "./analogy-report.js";
 export { buildReportSessionUrl, reportSessionResourceId } from "./content-url.js";
+export { parseStructureUrl, alphafoldEntryUrl, alphafoldPredictionUrl } from "./structure-source.js";

package/dist/contracts/schemas/chat-parts.d.ts

@@ -33,6 +33,16 @@ export declare const PresentationContentSchema: z.ZodDiscriminatedUnion<[z.ZodOb
     headers: z.ZodArray<z.ZodString>;
     rows: z.ZodArray<z.ZodArray<z.ZodString>>;
     caption: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"structure">;
+    format: z.ZodEnum<{
+        pdb: "pdb";
+        mmcif: "mmcif";
+    }>;
+    url: z.ZodURL;
+    provider: z.ZodLiteral<"alphafold">;
+    accession: z.ZodString;
+    version: z.ZodNumber;
 }, z.core.$strip>], "kind">;
 export declare const PresentationPartSchema: z.ZodObject<{
     type: z.ZodLiteral<"data-presentation">;
@@ -57,6 +67,16 @@ export declare const PresentationPartSchema: z.ZodObject<{
         headers: z.ZodArray<z.ZodString>;
         rows: z.ZodArray<z.ZodArray<z.ZodString>>;
         caption: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"structure">;
+        format: z.ZodEnum<{
+            pdb: "pdb";
+            mmcif: "mmcif";
+        }>;
+        url: z.ZodURL;
+        provider: z.ZodLiteral<"alphafold">;
+        accession: z.ZodString;
+        version: z.ZodNumber;
     }, z.core.$strip>], "kind">;
 }, z.core.$strip>;
 export declare const PlanPartSchema: z.ZodObject<{
@@ -476,6 +496,16 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         headers: z.ZodArray<z.ZodString>;
         rows: z.ZodArray<z.ZodArray<z.ZodString>>;
         caption: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"structure">;
+        format: z.ZodEnum<{
+            pdb: "pdb";
+            mmcif: "mmcif";
+        }>;
+        url: z.ZodURL;
+        provider: z.ZodLiteral<"alphafold">;
+        accession: z.ZodString;
+        version: z.ZodNumber;
     }, z.core.$strip>], "kind">;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"data-plan">;

package/dist/contracts/schemas/chat-parts.js

@@ -40,6 +40,14 @@ export const PresentationContentSchema = z.discriminatedUnion("kind", [
         rows: z.array(z.array(z.string())),
         caption: z.string().optional(),
     }),
+    z.object({
+        kind: z.literal("structure"),
+        format: z.enum(["pdb", "mmcif"]),
+        url: z.url(),
+        provider: z.literal("alphafold"),
+        accession: z.string().min(1),
+        version: z.number().int().positive(),
+    }),
 ]);
 export const PresentationPartSchema = z.object({
     type: z.literal("data-presentation"),

package/dist/contracts/structure-source.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The source of a `kind: "structure"` presentation card — the one grammar that
+ * admits a coordinate-file URL, shared by the harness (card construction) and
+ * by a host (render time).
+ *
+ * Admission is a path grammar over one host, not a host check: a hostname test
+ * alone would admit the prediction API and the PAE image on the same host. The
+ * grammar names the one kind of object a card can hold — a versioned AlphaFold
+ * DB model file — and derives from it what the host displays (`accession`,
+ * `version`) and what its purged-version fallback needs. A host re-runs the same
+ * parse over a persisted `url` before it fetches, so a card the harness would
+ * refuse today is refused at render time too.
+ *
+ * This module is browser-safe: it imports nothing.
+ */
+export type StructureFormat = "pdb" | "mmcif";
+export interface StructureSource {
+    readonly provider: "alphafold";
+    /** The UniProt accession the model is keyed by, isoform suffix included (`P38398-2`). */
+    readonly accession: string;
+    /** The AlphaFold DB model version the URL names. */
+    readonly version: number;
+    readonly format: StructureFormat;
+    /** The normalized file URL — what a host fetches and what the transcript attests to. */
+    readonly url: string;
+}
+/**
+ * Parse a structure URL into its source, or `null` when the grammar refuses it.
+ *
+ * Admits exactly: scheme `https`, host `alphafold.ebi.ac.uk` with no port or
+ * credential, the AlphaFold file path, and no query or fragment. `.pdb` maps to
+ * `pdb` and `.cif` to `mmcif`; the binary `.bcif` is not admitted.
+ */
+export declare function parseStructureUrl(url: string): StructureSource | null;
+/** The AlphaFold DB entry page of an accession. */
+export declare function alphafoldEntryUrl(accession: string): string;
+/** The AlphaFold DB prediction endpoint of an accession — what a host re-resolves a purged version through. */
+export declare function alphafoldPredictionUrl(accession: string): string;

package/dist/contracts/structure-source.js

@@ -0,0 +1,61 @@
+/**
+ * The source of a `kind: "structure"` presentation card — the one grammar that
+ * admits a coordinate-file URL, shared by the harness (card construction) and
+ * by a host (render time).
+ *
+ * Admission is a path grammar over one host, not a host check: a hostname test
+ * alone would admit the prediction API and the PAE image on the same host. The
+ * grammar names the one kind of object a card can hold — a versioned AlphaFold
+ * DB model file — and derives from it what the host displays (`accession`,
+ * `version`) and what its purged-version fallback needs. A host re-runs the same
+ * parse over a persisted `url` before it fetches, so a card the harness would
+ * refuse today is refused at render time too.
+ *
+ * This module is browser-safe: it imports nothing.
+ */
+const ALPHAFOLD_ORIGIN = "https://alphafold.ebi.ac.uk";
+/** `/files/AF-{accession}-F{fragment}-model_v{version}.{pdb|cif}` — the AlphaFold DB file path shape. */
+const ALPHAFOLD_FILE_PATH = /^\/files\/AF-([A-Z0-9]+(?:-\d+)?)-F\d+-model_v(\d+)\.(pdb|cif)$/;
+/**
+ * Parse a structure URL into its source, or `null` when the grammar refuses it.
+ *
+ * Admits exactly: scheme `https`, host `alphafold.ebi.ac.uk` with no port or
+ * credential, the AlphaFold file path, and no query or fragment. `.pdb` maps to
+ * `pdb` and `.cif` to `mmcif`; the binary `.bcif` is not admitted.
+ */
+export function parseStructureUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.origin !== ALPHAFOLD_ORIGIN)
+        return null;
+    if (parsed.username !== "" || parsed.password !== "")
+        return null;
+    if (parsed.search !== "" || parsed.hash !== "")
+        return null;
+    const match = ALPHAFOLD_FILE_PATH.exec(parsed.pathname);
+    if (match === null)
+        return null;
+    const version = Number(match[2]);
+    if (!Number.isInteger(version) || version < 1)
+        return null;
+    return {
+        provider: "alphafold",
+        accession: match[1],
+        version,
+        format: match[3] === "pdb" ? "pdb" : "mmcif",
+        url: parsed.href,
+    };
+}
+/** The AlphaFold DB entry page of an accession. */
+export function alphafoldEntryUrl(accession) {
+    return `${ALPHAFOLD_ORIGIN}/entry/${encodeURIComponent(accession)}`;
+}
+/** The AlphaFold DB prediction endpoint of an accession — what a host re-resolves a purged version through. */
+export function alphafoldPredictionUrl(accession) {
+    return `${ALPHAFOLD_ORIGIN}/api/prediction/${encodeURIComponent(accession)}`;
+}

package/dist/index.d.ts

@@ -94,6 +94,8 @@ export type { TokenUsageRollup } from "./contracts/usage.js";
 export type { CortexChatPart, PresentationPart, PresentationContent, PlanPart, RunCardPart, FileReferencePart, FileReferenceEntry, RunStartedPart, DagStatePart, DagStepState, StepStatus, StepActivityPart, StepPhase, StepFileTreePart, FileTreeEntry, StepOutputPart, StepOutputFile, StepSummaryPart, StepUsagePart, StepBlockedPart, RunSynthesisPart, SynthesizedFinding, BiologicalTheme, SynthesisProgressPart, SynthesisPhase, RunCompletedPart, RunCompletedFinding, RunFailedPart, } from "./contracts/chat-parts.js";
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./contracts/part-registry.js";
 export type { CortexChatPartType, PartDescriptor, PartEmitter, PartConsumer } from "./contracts/part-registry.js";
+export { parseStructureUrl, alphafoldEntryUrl, alphafoldPredictionUrl } from "./contracts/structure-source.js";
+export type { StructureSource, StructureFormat } from "./contracts/structure-source.js";
 export { launchDbos, shutdownDbos, sweepEphemeralWorkflows } from "./runtime/dbos.js";
 export type { DbosConfig } from "./runtime/dbos.js";
 export { dbosState } from "./runtime/dbos.js";

package/dist/index.js

@@ -171,6 +171,9 @@ export { envelopeDisplayMessages, parseStoredDisplayEnvelope } from "./memory/co
 // by dropping that part, so one stale row cannot fail a whole thread.
 export { storedMessagesToCortex } from "./memory/conversation-display-replay.js";
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./contracts/part-registry.js";
+// The source grammar of a `structure` presentation card — a host re-runs the same parse over a
+// persisted `url` before it fetches, so the rule lives in one place for both sides.
+export { parseStructureUrl, alphafoldEntryUrl, alphafoldPredictionUrl } from "./contracts/structure-source.js";
 // Embedder runtime surface — what a same-process host needs to run durable
 // workflows itself: the DBOS lifecycle, per-workflow registration + triggers,
 // the staged-input manifest contract, the sandbox/workspace factories over its

package/dist/memory/card-builders.d.ts

@@ -60,7 +60,13 @@ export declare function buildRunCardData(pool: Pool, opts: {
  *  `show_user.execute` alone would leave the reconstruct-on-read path (which sees only the persisted
  *  raw `tool_use` input) rendering the un-normalized chart, breaking the byte-identical live/replay
  *  card this module exists to guarantee. The `id` stays keyed to the raw input, which both paths
- *  hold identically, so normalization cannot move a card's identity. */
+ *  hold identically, so normalization cannot move a card's identity.
+ *
+ *  A `structure` is normalized here for the same reason: the URL the model named is parsed by the one
+ *  grammar (`parseStructureUrl`) and the content is built from the parse alone — never by spreading the
+ *  flat tool input, so a stray field cannot ride along. A URL the grammar refuses yields `null` on BOTH
+ *  paths; the transcript persists the raw `tool_use` input, and this is what keeps a refused URL from
+ *  being resurrected into a card on reload. */
 export declare function buildPresentationCardData(input: Record<string, unknown>): PresentationCardData | null;
 /** Max files a `show_file` group may reference; multiple render as a gallery. */
 export declare const MAX_FILES = 10;

package/dist/memory/card-builders.js

@@ -18,6 +18,7 @@ import { okAsync } from "neverthrow";
 import { tryQuery } from "../lib/db-result.js";
 import { AnalysisPlanSchema } from "../schemas/workflow-state.js";
 import { loadPlan } from "../state/index.js";
+import { parseStructureUrl } from "../contracts/structure-source.js";
 import { normalizeEchartSpec } from "../tools/display/normalize-echart-spec.js";
 import { validatePath } from "../tools/lib/path-validation.js";
 function isRecord(value) {
@@ -105,17 +106,33 @@ export function buildRunCardData(pool, opts) {
  *  `show_user.execute` alone would leave the reconstruct-on-read path (which sees only the persisted
  *  raw `tool_use` input) rendering the un-normalized chart, breaking the byte-identical live/replay
  *  card this module exists to guarantee. The `id` stays keyed to the raw input, which both paths
- *  hold identically, so normalization cannot move a card's identity. */
+ *  hold identically, so normalization cannot move a card's identity.
+ *
+ *  A `structure` is normalized here for the same reason: the URL the model named is parsed by the one
+ *  grammar (`parseStructureUrl`) and the content is built from the parse alone — never by spreading the
+ *  flat tool input, so a stray field cannot ride along. A URL the grammar refuses yields `null` on BOTH
+ *  paths; the transcript persists the raw `tool_use` input, and this is what keeps a refused URL from
+ *  being resurrected into a card on reload. */
 export function buildPresentationCardData(input) {
     const { kind, title, ...rest } = input;
     if (typeof kind !== "string")
         return null;
     const cardTitle = typeof title === "string" ? title : undefined;
-    const content = kind === "echart" && isRecord(rest.spec)
-        ? { kind, ...rest, spec: normalizeEchartSpec(rest.spec, { title: cardTitle }) }
-        : // Every other kind (and an echart the model called without a `spec`) is carried through
-            // untouched — there is no layout to normalize, and no spec to invent.
-            { kind, ...rest };
+    let content;
+    if (kind === "structure") {
+        const source = typeof rest.url === "string" ? parseStructureUrl(rest.url) : null;
+        if (source === null)
+            return null;
+        content = { kind, format: source.format, url: source.url, provider: source.provider, accession: source.accession, version: source.version };
+    }
+    else if (kind === "echart" && isRecord(rest.spec)) {
+        content = { kind, ...rest, spec: normalizeEchartSpec(rest.spec, { title: cardTitle }) };
+    }
+    else {
+        // Every other kind (and an echart the model called without a `spec`) is carried through
+        // untouched — there is no layout to normalize, and no spec to invent.
+        content = { kind, ...rest };
+    }
     return {
         id: presentationId(input),
         ...(cardTitle !== undefined ? { title: cardTitle } : {}),

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\n   `execute_analysis`. For an explicitly requested targeted computation, use\n   `execute_analysis` in ad hoc mode without generating a 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`. Do not re-derive these\n   facts by reading the raw inputs.\n2. **Which files exist** \u2192 `workspace_search`, then `list_files`.\n3. **What is inside a file** \u2192 `read_file` on a path a search 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\nWhen the user points to data by name or location that is not yet an input of\nthis analysis, adding it as an input may be available to you as a host tool.\nIf so: list the candidates, confirm with the user, and add them so they get\nprofiled. Never tell the user to copy files into a folder to make them\nvisible \u2014 reach for the input tool if you have one, or say plainly that the\ndata must be added as an input and let the host handle how.\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\n   `execute_analysis({ mode: \"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_analysis` 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. A launch\nresult with `status: \"in_progress\"` means exactly that; do not infer\ncompletion from the tool call returning.\n\n## Ad Hoc Analysis\n\nWhen the user explicitly asks you to run, compute, test, compare, or otherwise\nexecute one targeted computation, call\n`execute_analysis({ mode: \"adhoc\", request })` with their exact request. Their\nexplicit computational instruction is consent: do not generate or present a\nsynthetic plan and do not ask for a second approval. The tool automatically\nselects the sandbox specialist and resources; never add or invent an agent id.\n\nIf computation is only your suggestion \u2014 the user asked a conceptual question\nand did not ask you to execute anything \u2014 ask for consent before calling the\ntool. Ad hoc runs are asynchronous, writable, durable analysis runs. Retrieve\ntheir results later with `inspect_run`. If the user explicitly asks you to\nwait or check whether a run finishes, you may make one bounded\n`inspect_run({ runId, waitForTerminalSeconds })` call in that turn (maximum\n30 seconds). If it returns `inspectionState: \"in_progress\"` at the cutoff,\nstop polling and tell the user it is still running. Never loop on\n`inspect_run`; otherwise inspect on a later turn.\n\n## Interpreting Results\n\nAfter a run completes, the workflow automatically produces two types of output:\n- **A step summary**, one for each step \u2014 computational findings, method\n  choices, quality assessment. Pure facts, no literature.\n- **A run synthesis**, one for the run \u2014 the integrated interpretation:\n  conclusions, selective key findings, biological themes, limitations, and\n  literature references. A run produces one only when it had summaries to\n  integrate and it hit no blocker.\n\nTo interpret results:\n\n1. **Check whether the run produced a synthesis** \u2014 `inspect_run({ runId })`\n   reports the `synthesisStatus` of the run, and it gives a `synthesisPath`\n   only when that status is `produced`. The synthesis is your primary source\n   when it exists. When it was skipped or failed, read the step summaries and\n   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 summary of that step for the full evidence basis\n   (metrics, methods, quality assessment).\n4. **Dig deeper on specific findings** \u2014 for follow-up questions, use your\n   bio-lookup tools directly to investigate beyond what the synthesis\n   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\nYour bio-lookup tools are how you answer a biology question. Reach for them\nfreely and often \u2014 a lookup is cheap next to any computation, and each call\nstreams to the user, so they watch the evidence accumulate and can redirect\nyou mid-investigation.\n\n**A quick answer** is one or two calls:\n- \"What does BRCA1 do?\" \u2192 `search_gene`\n- \"What pathways involve TP53?\" \u2192 `lookup_annotation`\n- \"Any papers on EGFR in AD?\" \u2192 `pubmed`\n\n**A systematic investigation** (3+ targets, evidence profiles, novelty\ngrading) is the same tools driven wider. Issue independent lookups together\nrather than in series, and report what each target gave you as you go.\n\nEvery tool names the corpora it searches and the identifiers it accepts.\nRead that before you conclude a database holds nothing on a question \u2014 the\nentry point is usually a different tool, not a dead end. When a tool does\nreport nothing, say so plainly and continue with what the others gave you.\n\nGround every claim in a record you actually retrieved. Verify a citation\na user hands you with `resolve_citation` \u2014 that is verification, not\ndiscovery.\n\nEach tool names the corpora it searches and the identifiers it takes, and it\nsays which tool to prefer over it. Read that rather than a list here. All of\nthem are lightweight API calls \u2014 never start 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, its groups, and its dimensions.\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\nInvestigate the genes, pathways, and features you identified in\norientation, with your own bio-lookup tools. Carry the fold changes and\nthe condition names into what you look up.\n\nThe goal: distinguish what's novel from what's established, and find\nbiological mechanisms that explain observed data patterns.\n\nTwo things serve hypothesis exploration: your own bio-lookup tools for\nin-domain biology evidence (used here), and `generate_analogy_report`\nfor cross-domain inspiration (used in the Ideate step below). Treat them\nas a pair \u2014 biology evidence anchors hypotheses to reality, analogies\nbroaden 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_analysis`, 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.\n\nCall `start_report_session`. It opens a report chat as a child of this\nconversation. Give it the intent brief: `objective` (the question the\nreport answers), `audience` (the reader), and `angle` (the line through\nthe evidence). Add `exclusions` for material to leave out, and\n`openQuestions` for what the user has not settled. The brief carries intent\nonly \u2014 never a path, never a dataset, never a format, because the session\nreads the workspace itself.\n\nThen tell the user where the report is. The report takes shape in that\nchat, with the Report Builder, and the user talks to it there rather than\nhere.\n\nWhen the tool returns `existing-session`, no new session started. Tell the\nuser to continue the report in that chat. Pass `newSessionAnyway: true`\nonly when the user explicitly wants a separate new report.\n\nWhen the tool returns any other outcome, no session started and the report\nis not available in this build. Say that in one line, and give the detail\nthat the outcome carries. Do not compose the report here instead.\n\nConfirm first only when scope is genuinely ambiguous: several analyses to\nchoose from, the user is still exploring options, or the audience matters\nand 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 unrequested computation.** Planned analyses require an approved plan.\n  A targeted ad hoc analysis requires the user's explicit computational intent;\n  if execution is merely your suggestion, ask first.\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 whenever the analysis\n  has inputs \u2014 at init, and again when inputs are added or removed during the\n  conversation. Never propose \"explore data structure\" or \"initial\n  assessment\" steps.\n- **Split one targeted request into multiple ad hoc runs.** Keep one explicit\n  computational request in one ad hoc call. Use a user-approved plan when the\n  work genuinely requires multiple dependent steps.\n- **Compose a report in the conversation.** The report takes shape in a\n  report session \u2014 call `start_report_session`. Never write report prose\n  here in place of a session.\n- **Report an environment gap as permanent without checking.** \"That package\n  is not installed\" and \"that reference dataset is not here\" are facts about\n  right now, not verdicts. Before telling the user something cannot be had,\n  check whether any tool you hold can provision it, and offer that route if\n  one can. Call it impossible only after you have looked and found no path.\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- 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\n   `execute_analysis`. For an explicitly requested targeted computation, use\n   `execute_analysis` in ad hoc mode without generating a 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`. Do not re-derive these\n   facts by reading the raw inputs.\n2. **Which files exist** \u2192 `workspace_search`, then `list_files`.\n3. **What is inside a file** \u2192 `read_file` on a path a search 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\nWhen the user points to data by name or location that is not yet an input of\nthis analysis, adding it as an input may be available to you as a host tool.\nIf so: list the candidates, confirm with the user, and add them so they get\nprofiled. Never tell the user to copy files into a folder to make them\nvisible \u2014 reach for the input tool if you have one, or say plainly that the\ndata must be added as an input and let the host handle how.\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\n   `execute_analysis({ mode: \"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_analysis` 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. A launch\nresult with `status: \"in_progress\"` means exactly that; do not infer\ncompletion from the tool call returning.\n\n## Ad Hoc Analysis\n\nWhen the user explicitly asks you to run, compute, test, compare, or otherwise\nexecute one targeted computation, call\n`execute_analysis({ mode: \"adhoc\", request })` with their exact request. Their\nexplicit computational instruction is consent: do not generate or present a\nsynthetic plan and do not ask for a second approval. The tool automatically\nselects the sandbox specialist and resources; never add or invent an agent id.\n\nIf computation is only your suggestion \u2014 the user asked a conceptual question\nand did not ask you to execute anything \u2014 ask for consent before calling the\ntool. Ad hoc runs are asynchronous, writable, durable analysis runs. Retrieve\ntheir results later with `inspect_run`. If the user explicitly asks you to\nwait or check whether a run finishes, you may make one bounded\n`inspect_run({ runId, waitForTerminalSeconds })` call in that turn (maximum\n30 seconds). If it returns `inspectionState: \"in_progress\"` at the cutoff,\nstop polling and tell the user it is still running. Never loop on\n`inspect_run`; otherwise inspect on a later turn.\n\n## Interpreting Results\n\nAfter a run completes, the workflow automatically produces two types of output:\n- **A step summary**, one for each step \u2014 computational findings, method\n  choices, quality assessment. Pure facts, no literature.\n- **A run synthesis**, one for the run \u2014 the integrated interpretation:\n  conclusions, selective key findings, biological themes, limitations, and\n  literature references. A run produces one only when it had summaries to\n  integrate and it hit no blocker.\n\nTo interpret results:\n\n1. **Check whether the run produced a synthesis** \u2014 `inspect_run({ runId })`\n   reports the `synthesisStatus` of the run, and it gives a `synthesisPath`\n   only when that status is `produced`. The synthesis is your primary source\n   when it exists. When it was skipped or failed, read the step summaries and\n   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 summary of that step for the full evidence basis\n   (metrics, methods, quality assessment).\n4. **Dig deeper on specific findings** \u2014 for follow-up questions, use your\n   bio-lookup tools directly to investigate beyond what the synthesis\n   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\nYour bio-lookup tools are how you answer a biology question. Reach for them\nfreely and often \u2014 a lookup is cheap next to any computation, and each call\nstreams to the user, so they watch the evidence accumulate and can redirect\nyou mid-investigation.\n\n**A quick answer** is one or two calls:\n- \"What does BRCA1 do?\" \u2192 `search_gene`\n- \"What pathways involve TP53?\" \u2192 `lookup_annotation`\n- \"Any papers on EGFR in AD?\" \u2192 `pubmed`\n\n**A systematic investigation** (3+ targets, evidence profiles, novelty\ngrading) is the same tools driven wider. Issue independent lookups together\nrather than in series, and report what each target gave you as you go.\n\nEvery tool names the corpora it searches and the identifiers it accepts.\nRead that before you conclude a database holds nothing on a question \u2014 the\nentry point is usually a different tool, not a dead end. When a tool does\nreport nothing, say so plainly and continue with what the others gave you.\n\nGround every claim in a record you actually retrieved. Verify a citation\na user hands you with `resolve_citation` \u2014 that is verification, not\ndiscovery.\n\nEach tool names the corpora it searches and the identifiers it takes, and it\nsays which tool to prefer over it. Read that rather than a list here. All of\nthem are lightweight API calls \u2014 never start 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, its groups, and its dimensions.\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\nInvestigate the genes, pathways, and features you identified in\norientation, with your own bio-lookup tools. Carry the fold changes and\nthe condition names into what you look up.\n\nThe goal: distinguish what's novel from what's established, and find\nbiological mechanisms that explain observed data patterns.\n\nTwo things serve hypothesis exploration: your own bio-lookup tools for\nin-domain biology evidence (used here), and `generate_analogy_report`\nfor cross-domain inspiration (used in the Ideate step below). Treat them\nas a pair \u2014 biology evidence anchors hypotheses to reality, analogies\nbroaden 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_analysis`, 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.\n\nCall `start_report_session`. It opens a report chat as a child of this\nconversation. Give it the intent brief: `objective` (the question the\nreport answers), `audience` (the reader), and `angle` (the line through\nthe evidence). Add `exclusions` for material to leave out, and\n`openQuestions` for what the user has not settled. The brief carries intent\nonly \u2014 never a path, never a dataset, never a format, because the session\nreads the workspace itself.\n\nThen tell the user where the report is. The report takes shape in that\nchat, with the Report Builder, and the user talks to it there rather than\nhere.\n\nWhen the tool returns `existing-session`, no new session started. Tell the\nuser to continue the report in that chat. Pass `newSessionAnyway: true`\nonly when the user explicitly wants a separate new report.\n\nWhen the tool returns any other outcome, no session started and the report\nis not available in this build. Say that in one line, and give the detail\nthat the outcome carries. Do not compose the report here instead.\n\nConfirm first only when scope is genuinely ambiguous: several analyses to\nchoose from, the user is still exploring options, or the audience matters\nand 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 or looked up that exists in no artifact, `show_plan` for a\nstored `planId`, `show_file` for an existing artifact path. Cards render in\nthe order you emit them.\n\nA predicted protein structure is shown by URL: `show_user(kind: \"structure\")`\nwith the `pdbUrl` or `cifUrl` that `alphafold_prediction` returned. A\n`.pdb` or `.cif` a step wrote is an existing artifact \u2014 `show_file`.\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 unrequested computation.** Planned analyses require an approved plan.\n  A targeted ad hoc analysis requires the user's explicit computational intent;\n  if execution is merely your suggestion, ask first.\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 whenever the analysis\n  has inputs \u2014 at init, and again when inputs are added or removed during the\n  conversation. Never propose \"explore data structure\" or \"initial\n  assessment\" steps.\n- **Split one targeted request into multiple ad hoc runs.** Keep one explicit\n  computational request in one ad hoc call. Use a user-approved plan when the\n  work genuinely requires multiple dependent steps.\n- **Compose a report in the conversation.** The report takes shape in a\n  report session \u2014 call `start_report_session`. Never write report prose\n  here in place of a session.\n- **Report an environment gap as permanent without checking.** \"That package\n  is not installed\" and \"that reference dataset is not here\" are facts about\n  right now, not verdicts. Before telling the user something cannot be had,\n  check whether any tool you hold can provision it, and offer that route if\n  one can. Call it impossible only after you have looked and found no path.\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- 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

@@ -323,8 +323,13 @@ when the user asks for a summary or presentation of results.
 
 Three display tools, each bound to a single source of truth. Pick by WHAT
 you are referencing, not by how the output looks: \`show_user\` for content
-you are inventing, \`show_plan\` for a stored \`planId\`, \`show_file\` for an
-existing artifact path. Cards render in the order you emit them.
+you are inventing or looked up that exists in no artifact, \`show_plan\` for a
+stored \`planId\`, \`show_file\` for an existing artifact path. Cards render in
+the order you emit them.
+
+A predicted protein structure is shown by URL: \`show_user(kind: "structure")\`
+with the \`pdbUrl\` or \`cifUrl\` that \`alphafold_prediction\` returned. A
+\`.pdb\` or \`.cif\` a step wrote is an existing artifact — \`show_file\`.
 
 Chart layout is normalized for you — do not hand-tune legend, grid, axis
 rotation, or toolbox, and omit \`title\` from the ECharts spec.

package/dist/tools/bio/alphafold-prediction.js

@@ -23,6 +23,8 @@ export const alphafoldPredictionTool = defineTool({
         "matrix, `amAnnotationsUrl` — AlphaMissense pathogenicity annotations, present for a HUMAN canonical accession only, thus absent on a " +
         "non-human protein and on an isoform): fetch one from the sandbox to inspect the coordinates, the per-residue confidence, or the annotation " +
         "table, do not expect the file contents here.\n" +
+        'To SHOW the predicted structure to the user, call `show_user(kind: "structure", url: <pdbUrl or cifUrl>)` with the URL ' +
+        "verbatim — the chat renders an interactive 3-D view colored by pLDDT. Do not download the file to show it.\n" +
         "found: false means AlphaFold holds no model for the accession (not every UniProt entry has one) — report it and continue, do not retry.",
     inputSchema: z.object({
         uniprotAccession: z.string().min(1).describe("A UniProt accession, for example 'P38398' (BRCA1) or 'P69905' (hemoglobin subunit alpha)."),

package/dist/tools/display/show-user.d.ts

@@ -2,7 +2,10 @@
  * showUser tool — emits agent-synthesized content as a UI stream event.
  *
  * For content the agent is INVENTING — charts, markdown, code snippets,
- * SVG diagrams, tables. Content is serialized inline (bytes on the wire).
+ * SVG diagrams, tables — or LOOKED UP and holds as a reference that exists in
+ * no artifact: a `structure` names an AlphaFold DB model file by URL, and the
+ * host fetches the coordinates at render time. Content is serialized inline
+ * (bytes on the wire); a structure card carries only the normalized reference.
  *
  * The presentation `id` is derived deterministically from the content, so
  * an identical re-emission carries the same id — duplicate suppression is a
@@ -18,12 +21,12 @@
  */
 type ShowUserOutput = {
     shown: false;
-    reason: "invalid_path";
+    reason: "invalid_path" | "invalid_source";
 } | {
     id: string;
 };
 export declare const showUserTool: import("../define-tool.js").Tool<{
-    kind: "code" | "markdown" | "table" | "echart" | "svg";
+    kind: "code" | "markdown" | "table" | "echart" | "svg" | "structure";
     title?: string | undefined;
     spec?: Record<string, unknown> | undefined;
     dataPath?: string | undefined;
@@ -34,5 +37,6 @@ export declare const showUserTool: import("../define-tool.js").Tool<{
     headers?: string[] | undefined;
     rows?: string[][] | undefined;
     caption?: string | undefined;
+    url?: string | undefined;
 }, ShowUserOutput>;
 export {};

package/dist/tools/display/show-user.js

@@ -2,7 +2,10 @@
  * showUser tool — emits agent-synthesized content as a UI stream event.
  *
  * For content the agent is INVENTING — charts, markdown, code snippets,
- * SVG diagrams, tables. Content is serialized inline (bytes on the wire).
+ * SVG diagrams, tables — or LOOKED UP and holds as a reference that exists in
+ * no artifact: a `structure` names an AlphaFold DB model file by URL, and the
+ * host fetches the coordinates at render time. Content is serialized inline
+ * (bytes on the wire); a structure card carries only the normalized reference.
  *
  * The presentation `id` is derived deterministically from the content, so
  * an identical re-emission carries the same id — duplicate suppression is a
@@ -26,7 +29,7 @@ import { validatePath } from "../lib/path-validation.js";
 // "type", which the API rejects. Variant-specific fields are optional; the
 // LLM picks the right ones based on `kind`.
 const ShowUserInputSchema = z.object({
-    kind: z.enum(["echart", "markdown", "code", "svg", "table"]).describe("The type of agent-synthesized content to display"),
+    kind: z.enum(["echart", "markdown", "code", "svg", "table", "structure"]).describe("The type of content to display"),
     title: z
         .string()
         .optional()
@@ -46,11 +49,16 @@ const ShowUserInputSchema = z.object({
     headers: z.array(z.string()).optional().describe("Column headers (kind=table)"),
     rows: z.array(z.array(z.string())).optional().describe("Row data as array of string arrays (kind=table)"),
     caption: z.string().optional().describe("Caption (kind=table)"),
+    url: z
+        .string()
+        .optional()
+        .describe("kind=structure only: the `pdbUrl` or `cifUrl` that `alphafold_prediction` returned, verbatim. Only an AlphaFold DB model-file URL is accepted; any other URL is refused as `invalid_source`. The chat fetches the coordinates when the user views the card and renders an interactive 3-D view colored by pLDDT — never read, download, or paste the file to show it."),
 });
 export const showUserTool = defineTool({
     id: "show_user",
-    description: "Display content you are INVENTING — a chart you composed, a code snippet you are proposing, a markdown " +
-        "synthesis, an SVG diagram, a table you built. The content is inlined on the wire. " +
+    description: "Display content you are INVENTING or LOOKED UP that exists in no artifact — a chart you composed, a code snippet you are " +
+        "proposing, a markdown synthesis, an SVG diagram, a table you built, or a 3-D protein structure from AlphaFold DB " +
+        "(kind=structure, by the URL `alphafold_prediction` returned). The content is inlined on the wire. " +
         "Pick this tool by what you are referencing, not by how the output looks: " +
         "NOT for an existing analysis file — never read an artifact and paste its bytes here, reference it with `show_file` " +
         "(images, CSVs, PDFs, notebooks). NOT for a stored plan — use `show_plan`. " +
@@ -69,8 +77,13 @@ export const showUserTool = defineTool({
         if (typeof input.dataPath === "string" && validatePath(input.dataPath) !== null) {
             return ok({ shown: false, reason: "invalid_path" });
         }
-        // Non-null: the input passed Zod validation, so `kind` is present.
+        // The input passed Zod validation, so `kind` is present and the builder refuses exactly one thing:
+        // a structure whose `url` the source grammar does not admit — an expected outcome the model can
+        // self-correct with the URL the lookup tool actually returned.
         const card = buildPresentationCardData(input);
+        if (card === null) {
+            return ok({ shown: false, reason: "invalid_source" });
+        }
         await ctx.emit({
             type: "data-presentation",
             source: ctx.session.provenance,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.36.1",
+    "version": "0.36.2",
     "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",