@inflexa-ai/harness 0.41.0 → 0.41.1

package/dist/prompts/briefing.d.ts

@@ -21,6 +21,7 @@
  * field so the field-coverage guard test fails when a new field is added to the
  * schema without a deliberate decision about whether the agent needs to see it.
  */
+import { type WorkingMemory } from "../memory/working-memory.js";
 import type { DataProfileResult } from "../state/data-profile.js";
 import type { AnalysisStep } from "../schemas/workflow-state.js";
 /** Completed dependencies rendered as upstream blocks; the tail is counted, not rendered. */
@@ -50,6 +51,30 @@ export declare const STEP_NON_TASK_FIELDS: readonly ["id", "track", "step_type",
  * improvises the rest.
  */
 export declare function renderTask(step: AnalysisStep): string;
+/**
+ * The heading of the analysis-memory section. The orient core of the sandbox
+ * prompt names this same text, thus a test pins the two together.
+ */
+export declare const ANALYSIS_MEMORY_HEADING = "Analysis memory (read only)";
+/**
+ * The part of the working memory a step agent sees: the goal and the
+ * constraints. Hypotheses and findings stay out — they are the interpretive
+ * state of the conversation, not a rule for a step.
+ */
+export type StepMemory = Pick<WorkingMemory, "goal" | "constraints">;
+/** A memory with no goal and no constraints — the section renders nothing. */
+export declare function emptyStepMemory(): StepMemory;
+/**
+ * The goal and the constraints of the analysis, frozen at dispatch. The heading
+ * differs from the "Constraints" section of {@link renderTask}: those are the
+ * requirements of this plan step, these are the rules of the whole analysis.
+ *
+ * Bounded to `WORKING_MEMORY_LIMITS` the same way the chat render is: a row
+ * written before the caps existed degrades to its newest constraints, and each
+ * text is clamped. No id is rendered, because the step agent cannot address an
+ * entry — it has no memory tool.
+ */
+export declare function renderMemory(memory: StepMemory): string;
 /**
  * What anchors every path the agent writes or reads: the id the tree is mounted
  * at, and the step's writable directory.
@@ -109,10 +134,12 @@ export interface StepBriefing {
     readonly profile: DataProfileResult | null;
     /** The step's completed dependencies, in the plan's declared `depends_on` order. */
     readonly upstream: readonly UpstreamHandoff[];
+    /** The goal and the constraints of the analysis, read from the working memory at dispatch. */
+    readonly memory: StepMemory;
 }
 /**
  * Compose the seed. Absent sections collapse out entirely — an independent step
- * with no profile yields exactly the task and workspace sections, byte-identical
+ * with no profile and an empty memory yields exactly the task and workspace sections, byte-identical
  * to what a step got before any of this existed plus its paths.
  *
  * Pure: the same briefing composes to the same string, which is what makes the

package/dist/prompts/briefing.js

@@ -22,6 +22,7 @@
  * schema without a deliberate decision about whether the agent needs to see it.
  */
 import { DATA_PROFILE_ORIENTATION_MAX_CHARS, buildDataProfileOrientation } from "../app/data-profile-orientation.js";
+import { WORKING_MEMORY_LIMITS } from "../memory/working-memory.js";
 // ── Bounds ────────────────────────────────────────────────────────────
 /** Completed dependencies rendered as upstream blocks; the tail is counted, not rendered. */
 export const MAX_UPSTREAM_DEPS = 5;
@@ -113,6 +114,47 @@ export function renderTask(step) {
     }
     return parts.join("\n\n");
 }
+// ── (1b) Analysis memory ──────────────────────────────────────────────
+/**
+ * The heading of the analysis-memory section. The orient core of the sandbox
+ * prompt names this same text, thus a test pins the two together.
+ */
+export const ANALYSIS_MEMORY_HEADING = "Analysis memory (read only)";
+/** A memory with no goal and no constraints — the section renders nothing. */
+export function emptyStepMemory() {
+    return { goal: "", constraints: [] };
+}
+/**
+ * The goal and the constraints of the analysis, frozen at dispatch. The heading
+ * differs from the "Constraints" section of {@link renderTask}: those are the
+ * requirements of this plan step, these are the rules of the whole analysis.
+ *
+ * Bounded to `WORKING_MEMORY_LIMITS` the same way the chat render is: a row
+ * written before the caps existed degrades to its newest constraints, and each
+ * text is clamped. No id is rendered, because the step agent cannot address an
+ * entry — it has no memory tool.
+ */
+export function renderMemory(memory) {
+    const goal = clamp(memory.goal.trim(), WORKING_MEMORY_LIMITS.goalChars);
+    const all = memory.constraints.filter((c) => c.text.trim().length > 0);
+    const shown = all.slice(Math.max(0, all.length - WORKING_MEMORY_LIMITS.constraints));
+    if (goal.length === 0 && shown.length === 0)
+        return "";
+    const parts = [
+        "These entries come from the working memory of the analysis, read when this step was dispatched. " +
+            "A constraint from the user is binding. A constraint from the agent is context.",
+    ];
+    if (goal.length > 0)
+        parts.push(`Goal: ${goal}`);
+    if (shown.length > 0) {
+        const lines = shown.map((c) => `(${c.origin}) ${clamp(c.text.trim(), WORKING_MEMORY_LIMITS.entryChars)}`);
+        const omitted = all.length - shown.length;
+        if (omitted > 0)
+            lines.push(`(+${omitted} older ${omitted === 1 ? "constraint" : "constraints"} not shown)`);
+        parts.push(`Constraints:\n${bullets(lines)}`);
+    }
+    return section(ANALYSIS_MEMORY_HEADING, parts.join("\n\n"));
+}
 /** The in-sandbox analysis root of a frame — the read-only mount of the whole tree. */
 export function analysisRootOf(frame) {
     return `/${frame.analysisId}`;
@@ -190,7 +232,7 @@ function renderHandoff(handoff) {
 }
 /**
  * Compose the seed. Absent sections collapse out entirely — an independent step
- * with no profile yields exactly the task and workspace sections, byte-identical
+ * with no profile and an empty memory yields exactly the task and workspace sections, byte-identical
  * to what a step got before any of this existed plus its paths.
  *
  * Pure: the same briefing composes to the same string, which is what makes the
@@ -199,6 +241,7 @@ function renderHandoff(handoff) {
 export function composeStepBriefing(briefing) {
     return [
         renderTask(briefing.step),
+        renderMemory(briefing.memory),
         renderWorkspace(briefing.workspace),
         renderResources(briefing.step.resources),
         renderOrientation(briefing.profile, briefing.workspace.analysisId),

package/dist/prompts/compaction.d.ts

@@ -1,4 +1,4 @@
 /** The compaction request of a thread whose agent maintains the working memory. */
-export declare const MEMORY_COMPACTION_REQUEST = "The conversation is too long for the context window. The harness replaces the conversation above with your summary.\n\nFirst, move each lasting fact into the working memory with update_working_memory: the goal, each constraint, each hypothesis, and each finding with its run id. No other tool can run now.\n\nThen reply in plain text with the summary. Leave out what the working memory holds. Give:\n- the goals, and the current request of the user in its exact words\n- the decisions, with their reasons\n- the open questions\n- the file paths and the run ids that the work uses\n- the state of the work in progress\n\nThe conversation continues from your summary, the working memory, and the messages after them.";
+export declare const MEMORY_COMPACTION_REQUEST = "The conversation is too long for the context window. The harness replaces the conversation above with your summary.\n\nFirst, move each lasting fact into the working memory with update_working_memory: the goal, each constraint, each hypothesis, and each finding with its run id. Keep each constraint that the user gave as it is, because the user set it. No other tool can run now. Send all the memory edits in at most 3 replies, and put many calls in one reply. The reply after the edits must be the summary: if it calls a tool, the harness gets no summary.\n\nThen reply in plain text with the summary. Leave out each fact that a memory edit accepted. If the memory refused an edit, put that fact in the summary. Give:\n- the current request of the user in its exact words\n- the decisions, with their reasons\n- the approaches that failed or that the user ruled out, with the reasons\n- the open questions\n- the file paths, the run ids, and the other exact values that the work uses\n- the state of the work in progress\n\nThe conversation continues from your summary, the working memory, and the messages after them.";
 /** The compaction request of a thread that reads a frozen copy of the working memory, for example a report thread. */
-export declare const SUMMARY_COMPACTION_REQUEST = "The conversation is too long for the context window. The harness replaces the conversation above with your summary. No tool can run now.\n\nReply in plain text with the summary. Leave out what the working memory holds. Give:\n- the goals, and the current request of the user in its exact words\n- the decisions, with their reasons\n- the open questions\n- the file paths and the run ids that the work uses\n- the state of the work in progress\n\nThe conversation continues from your summary, the working memory, and the messages after them.";
+export declare const SUMMARY_COMPACTION_REQUEST = "The conversation is too long for the context window. The harness replaces the conversation above with your summary. No tool can run now.\n\nReply in plain text with the summary. Leave out what the working memory holds. Give:\n- the goals, and the current request of the user in its exact words\n- each change that the user made to the brief\n- the decisions, with their reasons\n- the approaches that failed or that the user ruled out, with the reasons\n- the open questions\n- the file paths, the run ids, and the other exact values that the work uses\n- the state of the work in progress\n\nThe conversation continues from your summary, the working memory, and the messages after them.";

package/dist/prompts/compaction.js

@@ -1,13 +1,15 @@
+import { COMPACTION_MAX_REQUESTS } from "../loop/compaction.js";
 /** The compaction request of a thread whose agent maintains the working memory. */
 export const MEMORY_COMPACTION_REQUEST = `The conversation is too long for the context window. The harness replaces the conversation above with your summary.
 
-First, move each lasting fact into the working memory with update_working_memory: the goal, each constraint, each hypothesis, and each finding with its run id. No other tool can run now.
+First, move each lasting fact into the working memory with update_working_memory: the goal, each constraint, each hypothesis, and each finding with its run id. Keep each constraint that the user gave as it is, because the user set it. No other tool can run now. Send all the memory edits in at most ${COMPACTION_MAX_REQUESTS - 1} replies, and put many calls in one reply. The reply after the edits must be the summary: if it calls a tool, the harness gets no summary.
 
-Then reply in plain text with the summary. Leave out what the working memory holds. Give:
-- the goals, and the current request of the user in its exact words
+Then reply in plain text with the summary. Leave out each fact that a memory edit accepted. If the memory refused an edit, put that fact in the summary. Give:
+- the current request of the user in its exact words
 - the decisions, with their reasons
+- the approaches that failed or that the user ruled out, with the reasons
 - the open questions
-- the file paths and the run ids that the work uses
+- the file paths, the run ids, and the other exact values that the work uses
 - the state of the work in progress
 
 The conversation continues from your summary, the working memory, and the messages after them.`;
@@ -16,9 +18,11 @@ export const SUMMARY_COMPACTION_REQUEST = `The conversation is too long for the
 
 Reply in plain text with the summary. Leave out what the working memory holds. Give:
 - the goals, and the current request of the user in its exact words
+- each change that the user made to the brief
 - the decisions, with their reasons
+- the approaches that failed or that the user ruled out, with the reasons
 - the open questions
-- the file paths and the run ids that the work uses
+- the file paths, the run ids, and the other exact values that the work uses
 - the state of the work in progress
 
 The conversation continues from your summary, the working memory, and the messages after them.`;

package/dist/prompts/sandbox-standards.d.ts

@@ -29,7 +29,7 @@
  * each composition stays byte-stable across its own steps.
  */
 import type { ToolchainSource } from "../sandbox/types.js";
-export declare const sandboxOrientCorePrompt = "# Sandbox Orient-Core\n\nThese apply to every agent that talks to a sandbox.\n\n## Your Briefing Is Authoritative\n\nYour first message is your briefing, composed for this step at the instant it was\ndispatched \u2014 after every step it depends on had finished. It names your task, your\nworking directory and the read-only analysis root, what the input dataset is\n(domain, organism, design, quality concerns, files), and what each upstream step\nproduced and where it put it. Work from it.\n\nDo NOT re-derive what it already gives you: no filesystem hunt for your inputs, no\nre-reading an upstream step whose summary you were handed, no re-deriving the\norganism or the dimensions from raw bytes. Reach further only where the briefing is\ngenuinely thin for what you must do:\n\n- `inspect_data_profile` \u2014 the full dataset profile: `scope:'overview'` for the\n  identity and the file census, `scope:'groups'` for the groups and the dimensions\n  that vary across them, `scope:'files'` for the members the profiler annotated\n  individually. It is the ONLY record of what the input data IS; no file on disk\n  carries it. Use it when the briefing's orientation is not enough, or when it\n  carried none.\n- `read_file` on an upstream step's summary \u2014 its path is in your briefing \u2014 when\n  the excerpt you were handed is not enough to build on.\n- `workspace_search({ query })` \u2014 natural-language search for a file the briefing\n  does not name. Optional `type` filter (`input-group` | `input-dimension` |\n  `input` | `output` | `summary` | `synthesis`) and `limit` (1-50, default 8).\n  Returns paths, descriptions, and metadata \u2014 not file contents. Most input files\n  carry no entry of their own; reach them through their group and `list_files`.\n\n## Your Workspace\n\nYour **working directory** \u2014 writable, and your cwd \u2014 and the read-only\n**analysis root** are named in your briefing. Use those paths exactly; do not\ninvent or guess one.\n\n- **Relative paths resolve against your working directory** \u2014 in `read_file`,\n  `list_files`, `file_stat`, `grep`, `write_file`, `edit_file`,\n  `execute_command`, and any script you run. `output/de.csv` means\n  `<working directory>/output/de.csv` everywhere \u2014 a file you write at a\n  relative path is read back at the same relative path.\n- **You may write only inside your working directory.** A write outside it\n  comes back as an `out_of_prefix` result (no I/O performed); fix the path.\n- The rest of the analysis is mounted **read-only** at the analysis root. Reach\n  input data (under `data/inputs/`) and other steps' outputs (under `runs/`)\n  with an **absolute** path beneath it.\n- **Absolute analysis-root paths are canonical** \u2014 use one whenever you\n  reference a file you didn't create in this step.\n\n`write_file` creates parent directories as needed \u2014 no separate mkdir.\n\n## Scope \u2014 Analysis Starts at Processed Data\n\nThis environment does **tertiary analysis**: turning processed data into\nbiological findings. Read processing \u2014 alignment, quantification, variant\ncalling, peak calling \u2014 belongs upstream, wherever the instrument output was\nhandled. No tool for it is installed, and none can be.\n\nYour inputs are count and expression matrices, called variants, peak sets,\nsignal tracks, and the metadata describing them. When a request arrives as raw\nreads or unprocessed instrument output, name the processed form you need and\nstop. Do not improvise a pipeline, do not substitute a Python reimplementation\nof an aligner or peak caller, and do not treat a missing upstream tool as an\nobstacle to route around \u2014 it is the boundary of the product, not a gap.\n\nData that has already been processed can still be **read**: `samtools`,\n`bcftools`, `tabix`, `bedtools` and `vcftools` are installed so you can\ninspect, subset, and convert existing BAM/CRAM, VCF and BED. Reading evidence at\nsites you already have is in scope; producing the calls is not.\n\n## Environment \u2014 No Network, No Installs\n\n**There is no egress from this sandbox.** Outbound connections are blocked at the\nfirewall, not merely discouraged: every download, API call, package install, and\n`ExperimentHub`/`AnnotationHub`/`models.download_*` style fetch fails outright.\nThere is no proxy, no mirror, and no retry that succeeds. Packages and reference\ndata were staged onto read-only mounts by the host **before** this container\nstarted, and that is the whole of what exists. Work that genuinely requires the\ninternet \u2014 fetching a dataset, querying an external API, literature lookup \u2014 is\ndone **outside** the sandbox through the host's tools, not from your scripts.\n\nSo: check what you need when you need it \u2014 a targeted lookup, never a catalog dump\nup front.\n\n- **Packages** \u2014 before importing a package you are not certain is present, look it\n  up with `list_available_packages`, narrowed to the packages you actually intend\n  to import. Importing one that isn't installed fails the script; the lookup costs\n  one call.\n- **Reference data** \u2014 `list_available_refs` resolves reference data into a real\n  path against the store mounted read-only at `/mnt/refs`. **Search by what the\n  data IS, not by where you expect it** (\"TF-target regulons\", \"hallmark gene\n  sets\", \"mouse\"): the store's directory layout is an installer detail, it differs\n  between hosts, and no path you have seen before is guaranteed to exist here.\n  Catalogued entries come back with the organism, the format, and the file's\n  internal shape, so read the entry and use the reader and species it names rather\n  than assuming \u2014 formats vary per dataset, and there is no guarantee any given\n  collection ships in the format your tool prefers.\n  The store is OPTIONAL and may be absent or hold none of what you want \u2014 a normal\n  state, not an error. Never assume a reference path exists and never hardcode one:\n  if a reference you need is not in the inventory, say so plainly and proceed with\n  what you do have (or state what must be provisioned) rather than inventing a path\n  or substituting something else unannounced. Pass reference paths EXPLICITLY to the\n  library \u2014 nothing in the image points a library at the store, so a library that\n  resolves data by name from an env var (CellTypist reads `$CELLTYPIST_FOLDER`)\n  will not find it unless you set that variable in `execute_command`'s `env`\n  for the command that needs it, using a path the inventory actually returned.\n- Do NOT call a library's built-in data fetcher \u2014 `dc.op.collectri()`,\n  `dc.op.progeny()`, `dc.op.msigdb()` and every other `dc.op.*()`, CellTypist's\n  `models.download_models()`, gseapy's Enrichr library names, `ExperimentHub`/\n  `AnnotationHub` \u2014 they all reach for the network and will fail. Load from an\n  inventory path instead. Do NOT download data or install packages at runtime.\n\n## CPU Budget and Parallelism\n\nYour briefing names this step's CPU quota and memory limit. The container's\ncore-count calls (`parallel::detectCores()`, `os.cpu_count()`) report the\nquota, so worker counts sized from them are safe.\n\nBLAS/OpenMP thread pools default to **1 thread** (`OMP_NUM_THREADS`,\n`OPENBLAS_NUM_THREADS`, `MKL_NUM_THREADS`, \u2026). A forked worker inherits its\nparent's pool size, so this default is what keeps `mclapply` /\n`multiprocessing` from running workers \u00D7 threads on a quota sized for one of\nthem. The rule: **workers \u00D7 threads-per-worker must not exceed the quota.** A\nmix is fine while the product stays inside it.\n\n- **Fork/worker parallelism** (`mclapply`, `BiocParallel`, `joblib`,\n  `multiprocessing`): size the workers from the reported core count and leave\n  the thread defaults alone \u2014 there is nothing to raise. `joblib` also\n  divides its own thread budget across its workers; do not manage it.\n- **Thread parallelism** (one process: xgboost, WGCNA, data.table, polars, a\n  single large BLAS fit): raise the thread variables for that command through\n  `execute_command`'s `env`, e.g.\n  `env: { \"OMP_NUM_THREADS\": \"4\", \"OPENBLAS_NUM_THREADS\": \"4\" }` on a 4-CPU\n  quota.\n\nExceeding the quota does not kill the step \u2014 the cgroup throttles it \u2014 but an\noversubscribed step runs slower and can starve the exec server that runs your\ncommands.\n\n## Context7 \u2014 Documentation Lookup\n\nWhen you are not certain of a function's signature or behavior, look it up\nwith context7 before you write the call: `resolve_library_id` with the\npackage name, then `query_docs` with the library ID and the function.\nRapidly-evolving packages (scvi-tools, spatialdata, cellrank, pertpy, muon)\nchange their APIs between releases, so check them against the docs or the\nskill references rather than memory.\n\n## Command Execution\n\n`execute_command` runs analysis work \u2014 scripts, bioinformatics CLI tools,\nshell pipes, and anything the workspace tools don't express. It starts in your\nworking directory; a relative `cwd` argument is resolved against it.\nIts `command` is an argv array. A one-element array runs through `sh -c`,\nso pipes, `&&`, redirection, quoting, and globbing work there. An array of\ntwo or more elements runs directly, with no shell.\n\nFor these tasks, prefer the dedicated workspace tools \u2014 they are faster than\nshelling out and don't waste a turn on path discovery:\n\n| Task                            | Use this tool   | Instead of                 |\n|-|-|-|\n| List files in a directory       | `list_files`    | `ls` / `ls -la`             |\n| Read a text/source/result file  | `read_file`     | `cat` / `less`             |\n| Search file contents by pattern | `grep`          | shell `grep` / `rg`        |\n| Size / type of a path           | `file_stat`     | `stat` / `wc -c`           |\n\n**Use `execute_command` for everything else**, including:\n\n- **Running scripts** \u2014 `python scripts/run.py`, `Rscript scripts/de.R`,\n  `ruff check scripts/foo.py`.\n- **Previewing huge / binary files** \u2014 `wc -l file.tsv`, `zcat file.gz | head`.\n  For text files, prefer `read_file` with `headLines` / `tailLines`.\n- **Shell pipes / chaining** \u2014 `sort | uniq -c | sort -rn | head`.\n- **`find`** \u2014 a recursive search by name, age, or size: `find . -name '*.h5ad'`,\n  `find . -size +10M`. `list_files` lists one directory only.\n- **Real CLI tools** \u2014 `samtools`, `bcftools`, `tabix`, `bedtools`,\n  `vcftools`, version probes like `python -c \"import x; print(x.__version__)\"`.\n\n**Shell behavior to know:**\n\n- `cd` does NOT persist across calls \u2014 each exec starts in your working\n  directory. For cross-call state, pass `cwd` or chain with `&&` in one exec.\n- Quote paths with spaces: `head \"data/inputs/My Folder/file.csv\"`. In Python,\n  use `pathlib.Path` or `os.path`.\n\n## Editing Files\n\n`edit_file` replaces `old_string` with `new_string`. Read the file first to\nget the exact text. When `replace_all` is false (default), `old_string` must\noccur exactly once \u2014 include surrounding context to make it unique.\n";
+export declare const sandboxOrientCorePrompt = "# Sandbox Orient-Core\n\nThese apply to every agent that talks to a sandbox.\n\n## Your Briefing Is Authoritative\n\nYour first message is your briefing, composed for this step at the instant it was\ndispatched \u2014 after every step it depends on had finished. It names your task, your\nworking directory and the read-only analysis root, what the input dataset is\n(domain, organism, design, quality concerns, files), and what each upstream step\nproduced and where it put it. Work from it.\n\nWhen the analysis has a recorded goal or constraints, the briefing carries them\nunder \"Analysis memory (read only)\": obey each constraint from the user, and treat\neach constraint from the agent as context. You cannot change that memory.\n\nDo NOT re-derive what it already gives you: no filesystem hunt for your inputs, no\nre-reading an upstream step whose summary you were handed, no re-deriving the\norganism or the dimensions from raw bytes. Reach further only where the briefing is\ngenuinely thin for what you must do:\n\n- `inspect_data_profile` \u2014 the full dataset profile: `scope:'overview'` for the\n  identity and the file census, `scope:'groups'` for the groups and the dimensions\n  that vary across them, `scope:'files'` for the members the profiler annotated\n  individually. It is the ONLY record of what the input data IS; no file on disk\n  carries it. Use it when the briefing's orientation is not enough, or when it\n  carried none.\n- `read_file` on an upstream step's summary \u2014 its path is in your briefing \u2014 when\n  the excerpt you were handed is not enough to build on.\n- `workspace_search({ query })` \u2014 natural-language search for a file the briefing\n  does not name. Optional `type` filter (`input-group` | `input-dimension` |\n  `input` | `output` | `summary` | `synthesis`) and `limit` (1-50, default 8).\n  Returns paths, descriptions, and metadata \u2014 not file contents. Most input files\n  carry no entry of their own; reach them through their group and `list_files`.\n\n## Your Workspace\n\nYour **working directory** \u2014 writable, and your cwd \u2014 and the read-only\n**analysis root** are named in your briefing. Use those paths exactly; do not\ninvent or guess one.\n\n- **Relative paths resolve against your working directory** \u2014 in `read_file`,\n  `list_files`, `file_stat`, `grep`, `write_file`, `edit_file`,\n  `execute_command`, and any script you run. `output/de.csv` means\n  `<working directory>/output/de.csv` everywhere \u2014 a file you write at a\n  relative path is read back at the same relative path.\n- **You may write only inside your working directory.** A write outside it\n  comes back as an `out_of_prefix` result (no I/O performed); fix the path.\n- The rest of the analysis is mounted **read-only** at the analysis root. Reach\n  input data (under `data/inputs/`) and other steps' outputs (under `runs/`)\n  with an **absolute** path beneath it.\n- **Absolute analysis-root paths are canonical** \u2014 use one whenever you\n  reference a file you didn't create in this step.\n\n`write_file` creates parent directories as needed \u2014 no separate mkdir.\n\n## Scope \u2014 Analysis Starts at Processed Data\n\nThis environment does **tertiary analysis**: turning processed data into\nbiological findings. Read processing \u2014 alignment, quantification, variant\ncalling, peak calling \u2014 belongs upstream, wherever the instrument output was\nhandled. No tool for it is installed, and none can be.\n\nYour inputs are count and expression matrices, called variants, peak sets,\nsignal tracks, and the metadata describing them. When a request arrives as raw\nreads or unprocessed instrument output, name the processed form you need and\nstop. Do not improvise a pipeline, do not substitute a Python reimplementation\nof an aligner or peak caller, and do not treat a missing upstream tool as an\nobstacle to route around \u2014 it is the boundary of the product, not a gap.\n\nData that has already been processed can still be **read**: `samtools`,\n`bcftools`, `tabix`, `bedtools` and `vcftools` are installed so you can\ninspect, subset, and convert existing BAM/CRAM, VCF and BED. Reading evidence at\nsites you already have is in scope; producing the calls is not.\n\n## Environment \u2014 No Network, No Installs\n\n**There is no egress from this sandbox.** Outbound connections are blocked at the\nfirewall, not merely discouraged: every download, API call, package install, and\n`ExperimentHub`/`AnnotationHub`/`models.download_*` style fetch fails outright.\nThere is no proxy, no mirror, and no retry that succeeds. Packages and reference\ndata were staged onto read-only mounts by the host **before** this container\nstarted, and that is the whole of what exists. Work that genuinely requires the\ninternet \u2014 fetching a dataset, querying an external API, literature lookup \u2014 is\ndone **outside** the sandbox through the host's tools, not from your scripts.\n\nSo: check what you need when you need it \u2014 a targeted lookup, never a catalog dump\nup front.\n\n- **Packages** \u2014 before importing a package you are not certain is present, look it\n  up with `list_available_packages`, narrowed to the packages you actually intend\n  to import. Importing one that isn't installed fails the script; the lookup costs\n  one call.\n- **Reference data** \u2014 `list_available_refs` resolves reference data into a real\n  path against the store mounted read-only at `/mnt/refs`. **Search by what the\n  data IS, not by where you expect it** (\"TF-target regulons\", \"hallmark gene\n  sets\", \"mouse\"): the store's directory layout is an installer detail, it differs\n  between hosts, and no path you have seen before is guaranteed to exist here.\n  Catalogued entries come back with the organism, the format, and the file's\n  internal shape, so read the entry and use the reader and species it names rather\n  than assuming \u2014 formats vary per dataset, and there is no guarantee any given\n  collection ships in the format your tool prefers.\n  The store is OPTIONAL and may be absent or hold none of what you want \u2014 a normal\n  state, not an error. Never assume a reference path exists and never hardcode one:\n  if a reference you need is not in the inventory, say so plainly and proceed with\n  what you do have (or state what must be provisioned) rather than inventing a path\n  or substituting something else unannounced. Pass reference paths EXPLICITLY to the\n  library \u2014 nothing in the image points a library at the store, so a library that\n  resolves data by name from an env var (CellTypist reads `$CELLTYPIST_FOLDER`)\n  will not find it unless you set that variable in `execute_command`'s `env`\n  for the command that needs it, using a path the inventory actually returned.\n- Do NOT call a library's built-in data fetcher \u2014 `dc.op.collectri()`,\n  `dc.op.progeny()`, `dc.op.msigdb()` and every other `dc.op.*()`, CellTypist's\n  `models.download_models()`, gseapy's Enrichr library names, `ExperimentHub`/\n  `AnnotationHub` \u2014 they all reach for the network and will fail. Load from an\n  inventory path instead. Do NOT download data or install packages at runtime.\n\n## CPU Budget and Parallelism\n\nYour briefing names this step's CPU quota and memory limit. The container's\ncore-count calls (`parallel::detectCores()`, `os.cpu_count()`) report the\nquota, so worker counts sized from them are safe.\n\nBLAS/OpenMP thread pools default to **1 thread** (`OMP_NUM_THREADS`,\n`OPENBLAS_NUM_THREADS`, `MKL_NUM_THREADS`, \u2026). A forked worker inherits its\nparent's pool size, so this default is what keeps `mclapply` /\n`multiprocessing` from running workers \u00D7 threads on a quota sized for one of\nthem. The rule: **workers \u00D7 threads-per-worker must not exceed the quota.** A\nmix is fine while the product stays inside it.\n\n- **Fork/worker parallelism** (`mclapply`, `BiocParallel`, `joblib`,\n  `multiprocessing`): size the workers from the reported core count and leave\n  the thread defaults alone \u2014 there is nothing to raise. `joblib` also\n  divides its own thread budget across its workers; do not manage it.\n- **Thread parallelism** (one process: xgboost, WGCNA, data.table, polars, a\n  single large BLAS fit): raise the thread variables for that command through\n  `execute_command`'s `env`, e.g.\n  `env: { \"OMP_NUM_THREADS\": \"4\", \"OPENBLAS_NUM_THREADS\": \"4\" }` on a 4-CPU\n  quota.\n\nExceeding the quota does not kill the step \u2014 the cgroup throttles it \u2014 but an\noversubscribed step runs slower and can starve the exec server that runs your\ncommands.\n\n## Context7 \u2014 Documentation Lookup\n\nWhen you are not certain of a function's signature or behavior, look it up\nwith context7 before you write the call: `resolve_library_id` with the\npackage name, then `query_docs` with the library ID and the function.\nRapidly-evolving packages (scvi-tools, spatialdata, cellrank, pertpy, muon)\nchange their APIs between releases, so check them against the docs or the\nskill references rather than memory.\n\n## Command Execution\n\n`execute_command` runs analysis work \u2014 scripts, bioinformatics CLI tools,\nshell pipes, and anything the workspace tools don't express. It starts in your\nworking directory; a relative `cwd` argument is resolved against it.\nIts `command` is an argv array. A one-element array runs through `sh -c`,\nso pipes, `&&`, redirection, quoting, and globbing work there. An array of\ntwo or more elements runs directly, with no shell.\n\nFor these tasks, prefer the dedicated workspace tools \u2014 they are faster than\nshelling out and don't waste a turn on path discovery:\n\n| Task                            | Use this tool   | Instead of                 |\n|-|-|-|\n| List files in a directory       | `list_files`    | `ls` / `ls -la`             |\n| Read a text/source/result file  | `read_file`     | `cat` / `less`             |\n| Search file contents by pattern | `grep`          | shell `grep` / `rg`        |\n| Size / type of a path           | `file_stat`     | `stat` / `wc -c`           |\n\n**Use `execute_command` for everything else**, including:\n\n- **Running scripts** \u2014 `python scripts/run.py`, `Rscript scripts/de.R`,\n  `ruff check scripts/foo.py`.\n- **Previewing huge / binary files** \u2014 `wc -l file.tsv`, `zcat file.gz | head`.\n  For text files, prefer `read_file` with `headLines` / `tailLines`.\n- **Shell pipes / chaining** \u2014 `sort | uniq -c | sort -rn | head`.\n- **`find`** \u2014 a recursive search by name, age, or size: `find . -name '*.h5ad'`,\n  `find . -size +10M`. `list_files` lists one directory only.\n- **Real CLI tools** \u2014 `samtools`, `bcftools`, `tabix`, `bedtools`,\n  `vcftools`, version probes like `python -c \"import x; print(x.__version__)\"`.\n\n**Shell behavior to know:**\n\n- `cd` does NOT persist across calls \u2014 each exec starts in your working\n  directory. For cross-call state, pass `cwd` or chain with `&&` in one exec.\n- Quote paths with spaces: `head \"data/inputs/My Folder/file.csv\"`. In Python,\n  use `pathlib.Path` or `os.path`.\n\n## Editing Files\n\n`edit_file` replaces `old_string` with `new_string`. Read the file first to\nget the exact text. When `replace_all` is false (default), `old_string` must\noccur exactly once \u2014 include surrounding context to make it unique.\n";
 /**
  * The orient-core layer for one declared toolchain. `"image"` states that an
  * acquisition is a host action and directs the agent to report a missing

package/dist/prompts/sandbox-standards.js

@@ -40,6 +40,10 @@ working directory and the read-only analysis root, what the input dataset is
 (domain, organism, design, quality concerns, files), and what each upstream step
 produced and where it put it. Work from it.
 
+When the analysis has a recorded goal or constraints, the briefing carries them
+under "Analysis memory (read only)": obey each constraint from the user, and treat
+each constraint from the agent as context. You cannot change that memory.
+
 Do NOT re-derive what it already gives you: no filesystem hunt for your inputs, no
 re-reading an upstream step whose summary you were handed, no re-deriving the
 organism or the dimensions from raw bytes. Reach further only where the briefing is

package/dist/runtime/assemble.d.ts

@@ -50,11 +50,13 @@ export type SandboxStepCallable = (input: SandboxStepInput) => Promise<SandboxSt
  * conversation agent does not — a half-wired ledger that reads as a complete
  * one. The protection has to hold on both sides of the assembly, not just the
  * conversation side. Each bag omits `toolOutputStore` for the same reason: each
- * loop must keep its texts in the one store that each read tool reads.
+ * loop must keep its texts in the one store that each read tool reads. The
+ * `executeAnalysis` bag omits `workingMemory`, because the step seeds must read
+ * the same memory that the conversation agent writes.
  */
 export interface CoreWorkflowDeps {
     readonly sandboxStep: Omit<SandboxStepDeps, "usageRecorder" | "citationResolver" | "toolOutputStore">;
-    readonly buildExecuteAnalysis: (sandboxStep: SandboxStepCallable) => Omit<ExecuteAnalysisDeps, "usageRecorder" | "citationResolver" | "toolOutputStore">;
+    readonly buildExecuteAnalysis: (sandboxStep: SandboxStepCallable) => Omit<ExecuteAnalysisDeps, "usageRecorder" | "citationResolver" | "toolOutputStore" | "workingMemory">;
     readonly dataProfile: Omit<DataProfileDeps, "usageRecorder" | "toolOutputStore">;
 }
 /** The registered, callable workflow handles. */

package/dist/runtime/assemble.js

@@ -28,6 +28,7 @@ import { bindExtractionTrigger, createExtractionArm, registerExtractValuesWorkfl
 import { registerDeriveTableExecWorkflow, triggerDeriveTableExec } from "../tasks/derive-table-exec.js";
 import { createCitationResolver } from "../citations/resolve.js";
 import { createThreadStore } from "../memory/thread-store.js";
+import { createWorkingMemory } from "../memory/working-memory.js";
 import { createArtifactReadStore, createProductionResolver } from "../report-model/production-resolver.js";
 import { createReportVersionStore } from "../state/report-versions.js";
 import { createToolOutputStore } from "../state/tool-outputs.js";
@@ -86,7 +87,13 @@ export function assembleCoreRuntime(deps) {
     });
     const toolOutputStore = createToolOutputStore(conversation.pool);
     const sandboxStep = registerSandboxStep({ ...wf.sandboxStep, citationResolver, usageRecorder, toolOutputStore });
-    const executeAnalysis = registerExecuteAnalysis({ ...wf.buildExecuteAnalysis(sandboxStep), citationResolver, usageRecorder, toolOutputStore });
+    const executeAnalysis = registerExecuteAnalysis({
+        ...wf.buildExecuteAnalysis(sandboxStep),
+        citationResolver,
+        usageRecorder,
+        toolOutputStore,
+        workingMemory: createWorkingMemory(conversation.pool),
+    });
     const dataProfile = registerDataProfileWorkflow({ ...wf.dataProfile, usageRecorder, toolOutputStore });
     // The extraction workflow shares the profile's sandbox and authorization rails, thus it draws the same
     // three seams from the profile deps. The report resolver factory binds the extraction arm over this

package/dist/schemas/file-metadata.js

@@ -24,16 +24,16 @@ export const FileMetadataSchema = z
  */
 export const SubmittedFileDescriptionSchema = z.object({
     /** Exact path of the file being described, copied from the prompt's list. */
-    path: z.string(),
-    description: z.string(),
-    dataType: z.string(),
-    format: z.string(),
-    rows: z.number().nullish(),
-    cols: z.number().nullish(),
-    tags: z.array(z.string()).optional(),
-    warnings: z.array(z.string()).optional(),
+    path: z.string().describe("The path of the file, copied exactly from the list of files that the harness gave."),
+    description: z.string().describe("One sentence that says what the file contains. A semantic search of the workspace later finds the file by this text."),
+    dataType: z.string().describe('The semantic type of the data, for example "count matrix" or "QC report".'),
+    format: z.string().describe('The file format, for example "csv", "tsv", "h5ad", or "png".'),
+    rows: z.number().nullish().describe("The count of rows, when you know it."),
+    cols: z.number().nullish().describe("The count of columns, when you know it."),
+    tags: z.array(z.string()).optional().describe("Short labels that help a search find the file."),
+    warnings: z.array(z.string()).optional().describe("Known problems of the file that a reader must know before use."),
 });
 /** Input contract for the `submit_file_metadata` tool. */
 export const SubmitFileMetadataInputSchema = z.object({
-    files: z.array(SubmittedFileDescriptionSchema),
+    files: z.array(SubmittedFileDescriptionSchema).describe("One entry per output file. You can cover the files in one call or in several."),
 });

package/dist/schemas/plan-schemas.d.ts

@@ -11,10 +11,10 @@ export declare const PlanStepSchema: z.ZodObject<{
     context: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
     id: z.ZodString;
+    constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
     track: z.ZodString;
     step_type: z.ZodString;
     question: z.ZodString;
-    constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
     acceptance_criteria: z.ZodArray<z.ZodString>;
     caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
     packages: z.ZodNonOptional<z.ZodOptional<z.ZodArray<z.ZodString>>>;
@@ -44,10 +44,10 @@ export declare const PlannerPlanSchema: z.ZodObject<{
         context: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
         id: z.ZodString;
+        constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
         track: z.ZodString;
         step_type: z.ZodString;
         question: z.ZodString;
-        constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
         acceptance_criteria: z.ZodArray<z.ZodString>;
         caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
         packages: z.ZodNonOptional<z.ZodOptional<z.ZodArray<z.ZodString>>>;
@@ -86,10 +86,10 @@ export declare const PlanningAgentOutputSchema: z.ZodObject<{
             context: z.ZodOptional<z.ZodString>;
             description: z.ZodOptional<z.ZodString>;
             id: z.ZodString;
+            constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
             track: z.ZodString;
             step_type: z.ZodString;
             question: z.ZodString;
-            constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
             acceptance_criteria: z.ZodArray<z.ZodString>;
             caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
             packages: z.ZodNonOptional<z.ZodOptional<z.ZodArray<z.ZodString>>>;

package/dist/tools/ad-hoc-router.js

@@ -23,10 +23,15 @@ const resourcesSchema = z.object({
     gpu: z.object({ count: z.number().int().positive() }).optional(),
 });
 const routeSchema = z.object({
-    agentId: z.string().optional(),
-    resources: resourcesSchema.optional(),
-    rationale: z.string().optional(),
-    packages: z.array(z.string()).optional(),
+    agentId: z.string().optional().describe("The id of one specialist from the eligible catalog, copied exactly."),
+    resources: resourcesSchema
+        .optional()
+        .describe("The sandbox resources of the step, inside the stated ranges. Omit to take the defaults; a value outside the ranges is replaced by the defaults."),
+    rationale: z.string().optional().describe("One or two sentences on why this specialist fits the request. The step agent reads it."),
+    packages: z
+        .array(z.string())
+        .optional()
+        .describe("The packages that the scripts of the step import, each as `[python:|r:]<name>[==<version>]`. An empty array is valid."),
 });
 export function defaultAdHocResources(policy) {
     return policy ? { cpu: Math.min(4, policy.perStep.maxCpu), memoryGb: Math.min(8, policy.perStep.maxMemoryGb) } : { cpu: 4, memoryGb: 8 };

package/dist/tools/bio/chembl.js

@@ -38,10 +38,11 @@ const inputSchema = z
         .describe("Which ChEMBL lookup to run; each names its params and return fields.\n" +
         "'compounds' (query + searchType) — molecules by target, name or SMILES: resolve a named compound to its ID and structure, or list " +
         "what was assayed against a target. → chemblId, preferredCompoundName, canonicalSmiles, molecularWeight, alogp, molecularFormula.\n" +
-        "'drug' (query) — approved drugs by indication or by drug name: 'what treats X?', 'is Y approved, since when?'. → moleculeChemblId, " +
-        "preferredName, maxPhase (4 = approved), moleculeType, firstApproval, indication. A disease term reads the curated indication " +
-        "registry, highest phase first; a query that matches no disease term reads the approved molecules (max_phase >= 4) instead, and " +
-        "their indications come back with them.\n" +
+        "'drug' (query) — approved drugs by drug name or by indication: 'is Y approved, since when?', 'what treats X?'. → moleculeChemblId, " +
+        "preferredName, maxPhase (4 = approved), moleculeType, firstApproval, indication. The query is read as a molecule name first: the " +
+        "approved molecules (max_phase 4) that it names come back with their indications. A query that names no approved molecule is then " +
+        "read as a disease term against the curated indication registry, highest phase first, and those rows can hold clinical-stage " +
+        "molecules. Thus a clinical-stage compound queried by name gives an empty array; action 'compounds' resolves it.\n" +
         "'mechanism' (chemblId, molecule only) — curated mechanism of ONE molecule: 'how does X work?'. → mechanismOfAction, actionType " +
         "(INHIBITOR, AGONIST, …), targetChemblId + targetName, moleculeChemblId. Curated mainly for clinical/approved molecules, so tool " +
         "compounds often have none.\n" +
@@ -62,7 +63,9 @@ const inputSchema = z
     searchType: z
         .enum(["target", "compound", "smiles"])
         .optional()
-        .describe("Required for 'compounds' — how to read `query`. 'target': resolve to a ChEMBL target, then return what was assayed against it. " +
+        .describe("Required for 'compounds' — how to read `query`. 'target': resolve `query` to the TOP ChEMBL target hit only — the result does not " +
+        "name that target, and a symbol can hit a non-human ortholog — then return what was assayed against it; a target ChEMBL ID from " +
+        "action 'targets' pins the target. " +
         "'compound': free-text over molecule names. 'smiles': flexmatch structure search."),
     chemblId: z
         .string()

package/dist/tools/bio/comptox.js

@@ -45,8 +45,8 @@ const inputSchema = z
         "HTTK toxicokinetic parameters, reported functional uses, consumer-product composition."),
     query: z
         .string()
-        .describe("Chemical identifier (all datasets). A DTXSID ('DTXSID7020182') is used directly; a CASRN ('80-05-7'), a name ('bisphenol A'), or — for " +
-        "dataset 'chemical' — an InChIKey is resolved by EXACT match, so a non-canonical or misspelled name yields found: false."),
+        .describe("Chemical identifier (all datasets). A DTXSID ('DTXSID7020182') is used directly; a CASRN ('80-05-7'), a name ('bisphenol A'), or " +
+        "an InChIKey is resolved by EXACT match, so a non-canonical or misspelled name yields found: false."),
     dataType: z
         .enum(["toxval", "genetox", "cancer", "seem", "httk", "functional-use", "product-data", "all"])
         .optional()
@@ -103,8 +103,8 @@ export function createComptoxTool(deps) {
             "bioactivity), 'hazard' (in-vivo: " +
             "NOAEL/LOAEL/LD50, genotoxicity, cancer), 'chemical' (identity + physicochemical/ADMET), 'exposure' (SEEM predictions, toxicokinetics, uses, " +
             "products). See `dataset` for what each returns; all four resolve `query` to a DTXSID first.\n" +
-            "ACCEPTED IDENTIFIERS: a DTXSID ('DTXSID7020182') used directly, or a CASRN ('80-05-7'), a chemical name ('bisphenol A') or — for dataset " +
-            "'chemical' — an InChIKey, each resolved by EXACT match.\n" +
+            "ACCEPTED IDENTIFIERS, for every dataset: a DTXSID ('DTXSID7020182') used directly, or a CASRN ('80-05-7'), a chemical name " +
+            "('bisphenol A') or an InChIKey, each resolved by EXACT match.\n" +
             "Requires EPA_CCTE_API_KEY — a missing key fails terminally: do NOT retry, tell the user the key needs configuring and proceed without EPA data.\n" +
             "found: false means the query did not resolve to a chemical; a present-but-empty section is likewise valid no-data. Do not retry either.\n" +
             "This is environmental/industrial-chemical data: for drug-like compounds prefer PubChem or ChEMBL — dataset 'chemical' returns " +

package/dist/tools/bio/drug-gene-interactions.js

@@ -106,11 +106,12 @@ export function createDrugGeneInteractionsTool(deps) {
         description: "Drug↔gene interactions across DGIdb (the Drug Gene Interaction Database), DrugBank and PharmGKB, in one call — 'what drugs hit these " +
             "genes?' and 'what genes does this drug act on?'. See `direction` and `sources` for the modes.\n" +
             "ACCEPTED IDENTIFIERS: a HUGO gene symbol ('EGFR') for direction 'gene_to_drugs'; a drug name ('imatinib'), a DrugBank ID ('DB00619') or a " +
-            "DGIdb concept ID for 'drug_to_genes'. A brand name and a non-HUGO symbol match nothing — resolve the symbol with search_gene and the brand " +
-            "name with search_faers({action:'label'}) first.\n" +
-            "It answers whether an interaction is KNOWN, by whom, and of what type. For quotable POTENCY (IC50/Ki) use chembl({action:'bioactivity'}) instead.\n" +
+            "DGIdb concept ID for 'drug_to_genes'. A brand name and a non-HUGO symbol match nothing — resolve the symbol with search_gene, and pass " +
+            "the generic drug name, not the brand name.\n" +
+            "It answers whether an interaction is KNOWN, by whom, and of what type. It carries no potency value (IC50/Ki).\n" +
             "Verbose fields (`includeAttributes`, `includeDrugRecord`) are off by default — both cost a lot of context and are rarely what the question needs.\n" +
-            "ALWAYS read `perSource` before concluding an interaction is unknown: 'no_data' means that corpus has nothing; 'unavailable' means it could " +
+            "`perSource` gives the outcome of each corpus, and a conclusion that an interaction is unknown rests on it: 'no_data' means that corpus " +
+            "has nothing; 'unavailable' means it could " +
             "not be reached (a missing DRUGBANK_API_KEY lands here — tell the user and proceed with DGIdb). A `found: false` entry means the identifier " +
             "is not in DGIdb at all, usually a non-HUGO symbol or a brand name. Neither is worth retrying unchanged.",
         inputSchema,

package/dist/tools/bio/gene-disease-evidence.js

@@ -156,15 +156,15 @@ export function createGeneDiseaseEvidenceTool(deps) {
         id: "gene_disease_evidence",
         description: "Genetic evidence linking a gene to a disease or trait, across the NHGRI-EBI GWAS Catalog, DisGeNET, NCBI ClinVar and cBioPortal in one call " +
             "— 'is there human genetic support for this target in this indication?'. See `sources` for what each corpus carries.\n" +
-            "For the integrated, pre-scored view prefer opentargets({action:'target'}) FIRST — it folds genetic association together with tractability " +
-            "and the drug landscape. Reach here for the underlying records: actual SNPs, effect sizes, scores, pathogenicity calls and somatic mutation " +
-            "frequencies with their studies and PMIDs.\n" +
+            "It returns the underlying records — actual SNPs, effect sizes, scores, pathogenicity calls and somatic mutation frequencies with their " +
+            "studies and PMIDs — not one integrated score across evidence types.\n" +
             "ACCEPTED IDENTIFIERS, each named by its `queryType`: a HUGO gene symbol or an Entrez ID ('PCSK9', '5008'); a disease or trait name or a UMLS " +
             "CUI ('asthma', 'C0006142'); a dbSNP rsID ('rs11591147'); a GWAS Catalog study accession ('GCST000392'); and a ClinVar accession " +
             "('VCV000012345'). The last two read one record back by the accession that an earlier result of this same tool reported. " +
             "The GWAS Catalog matches the EXACT EFO trait label (case-insensitive): 'asthma' resolves, a paraphrase such as 'LDL cholesterol' reads as " +
             "no_data there ('low density lipoprotein cholesterol measurement' is the label) while the other corpora still answer it.\n" +
-            "ALWAYS read `perSource` before concluding anything is absent. 'no_data' means that corpus genuinely has nothing; 'unavailable' means it " +
+            "`perSource` gives the outcome of each corpus, and a conclusion of absence rests on it. 'no_data' means that corpus genuinely has nothing; " +
+            "'unavailable' means it " +
             "could not be reached (a missing DISGENET_API_KEY lands here — tell the user and proceed with the others); 'not_applicable' means that " +
             "corpus has no lookup for this queryType. Only 'no_data' is evidence of absence, and none is worth retrying unchanged.",
         inputSchema,

package/dist/tools/bio/lookup-annotation.js

@@ -84,7 +84,9 @@ const inputSchema = z
     vocabulary: z
         .enum(["go", "kegg", "reactome", "pathways"])
         .describe("'go' — Gene Ontology via QuickGO (EBI); needs ONE of goId, query, or geneProductId. Returns terms[] { id, name, definition, aspect } " +
-        "and/or annotations[] { geneProductId, goId, goName, aspect, evidenceCode, qualifier }. " +
+        "and/or annotations[] { geneProductId, goId, goName, aspect, evidenceCode, qualifier } — the first `limit` rows that QuickGO " +
+        "serves, one row for each term, evidence and reference, thus a term can repeat, a well-studied protein holds hundreds of rows, " +
+        "and the result gives no total. " +
         "'kegg' / 'reactome' — one pathway database; needs query or pathwayId. 'pathways' — both, in parallel; needs query or pathwayId. " +
         "Returns pathways[] { id, name, source, url, description?, genes? }."),
     query: z
@@ -110,8 +112,10 @@ const inputSchema = z
     includeGenes: z
         .boolean()
         .optional()
-        .describe("Pathway vocabularies only. Default FALSE — member-gene lists cost one request per pathway and run to hundreds of symbols. True only when " +
-        "you need the members, not the pathway identities."),
+        .describe("Pathway vocabularies only. Default FALSE — member lists cost one request per pathway and run to hundreds of entries. KEGG members " +
+        "are NCBI Gene (Entrez) IDs ('7157'), not symbols. Reactome members are participant entity names with their compartment " +
+        "('p-T389/412-RPS6KB1 [cytosol]', 'ATP [cytosol]'), small molecules included. True only when you need the members, not the " +
+        "pathway identities."),
     limit: z
         .number()
         .int()

package/dist/tools/bio/opentargets.js

@@ -32,7 +32,9 @@ const inputSchema = z
     action: z
         .enum(["target", "disease", "resolve_disease"])
         .describe("'target' (needs ensemblId) — the diseases associated with the gene: targetInfo (approvedSymbol, approvedName, " +
-        "tractability across small molecule / antibody / other modalities) plus associations[], each with an overall score and " +
+        "tractability — for smallMolecule, antibody and otherModalities, the labels of the positive Open Targets buckets, from " +
+        "'Approved Drug' and 'Advanced Clinical' down to 'High-Quality Pocket' or 'UniProt loc high conf'; an empty list means no " +
+        "positive bucket and null means no assessment) plus associations[], each with an overall score and " +
         "its per-datatype breakdown — genetic association, known drug, literature, animal model, somatic mutation. " +
         "'disease' (needs efoId) — the targets ranked for that disease; each association carries targetId/targetSymbol/targetName " +
         "and the same score breakdown. " +
@@ -75,11 +77,11 @@ const inputSchema = z
 });
 export const openTargetsTool = defineTool({
     id: "opentargets",
-    description: "Query the Open Targets Platform — the integrated target-disease evidence corpus of EMBL-EBI, GSK and their partners — the preferred FIRST call " +
-        "for target assessment, since one 'target' query yields the genetic evidence, tractability, and drug landscape together, already scored and " +
-        "ranked. See the action parameter for what each mode needs and returns.\n" +
-        "It is the integrated view; the underlying records live elsewhere. For the raw genetic evidence (individual SNPs from the GWAS Catalog, DisGeNET " +
-        "GDA scores, ClinVar variant pathogenicity) use gene_disease_evidence. For this target's mechanism-based safety liabilities use target_safety.\n" +
+    description: "Query the Open Targets Platform — the integrated target-disease evidence corpus of EMBL-EBI, GSK and their partners. One 'target' query " +
+        "gives the tractability of the target and its disease associations, already scored and ranked, each with a per-datatype score for genetic " +
+        "association, known drug, literature, animal model and somatic mutation. See the action parameter for what each mode needs and returns.\n" +
+        "It is the integrated view, not the underlying records: it names no drug, no SNP, no effect size, no ClinVar call and no PMID, and it " +
+        "holds no safety liability.\n" +
         "ACCEPTED IDENTIFIERS: an Ensembl gene ID for action 'target' (ENSG00000141510); an Open Targets disease ID for action 'disease' — EFO " +
         "(EFO_0000311), MONDO (MONDO_0005148) or HP (HP_0001250), because Open Targets keys a disease on EFO and EFO imports the other two; and a plain " +
         "disease NAME for action 'resolve_disease' ('type 2 diabetes'), which is how you obtain that disease ID. A bare gene symbol is NOT accepted by " +

package/dist/tools/bio/pubchem.js

@@ -19,14 +19,16 @@ const inputSchema = z
     action: z
         .enum(["compound", "crossrefs", "assays"])
         .describe("Which PubChem lookup to run. " +
-        "'compound' — resolve `query` (in the namespace named by `searchBy`) to a compound. Returns results[]: identity (cid, canonicalSmiles, inchi, inchiKey, iupacName, " +
+        "'compound' — resolve `query` (in the namespace named by `searchBy`) to a compound. Returns results[]: identity (cid, canonicalSmiles — " +
+        "the PubChem connectivity SMILES, with no stereochemistry and no isotopes, thus inchi is the full structure — inchi, inchiKey, iupacName, " +
         "molecularFormula) and computed properties (molecularWeight, xlogp, tpsa, hbondDonorCount, hbondAcceptorCount, rotatableBondCount, complexity). " +
         "'crossrefs' — external registry ids for a `cid`. Returns crossRefs[]: a flat list of { source, id } entries. `source` names the registry that the id pattern " +
         "identifies — ChEMBL, ChEBI, DrugBank, KEGG, HMDB, CAS, PDB or UNII — and it is null for an id of any other registry; filter by `source` for the one you want. " +
         "This is the bridge out of PubChem. " +
         "'assays' — bioassay screening summaries for a `cid`; answers 'has this compound ever been screened, and against what?'. Returns assays[]: aid, assayName, targetName " +
         "(the target accession, for example a UniProt or PDB id), " +
-        "activityOutcome (Active / Inactive / Inconclusive / Unspecified), activityValue. Broad HTS screening coverage, NOT curated potency — for numbers you intend to quote " +
+        "activityOutcome (Active / Inactive / Inconclusive / Unspecified), activityValue (in µM; null when the assay reports none). Broad HTS " +
+        "screening coverage, NOT curated potency — for numbers you intend to quote " +
         "(IC50/Ki), prefer chembl action='bioactivity'."),
     query: z
         .string()

package/dist/tools/bio/pubmed.d.ts

@@ -37,7 +37,7 @@ type PubMedOutput = {
 } | ({
     pmcId: string;
     available: true;
-} & BoundedFullText);
+} & Omit<BoundedFullText, "sections">);
 export declare function createPubMedTool(deps: {
     ncbiApiKey?: string;
 }): import("../define-tool.js").Tool<{

package/dist/tools/bio/pubmed.js

@@ -34,8 +34,9 @@ const inputSchema = z
     action: z
         .enum(["search", "details", "fulltext"])
         .describe("'search' (needs query) — returns totalFound plus, per hit, PMID, title, journal, year and an author summary. " +
-        "'details' (needs pmids, max 20 per call) — each article's full abstract, journal, year, DOI, pmcId (non-null only when open-access " +
-        "full text exists in PubMed Central), plus the leading authors and MeSH terms with authorCount / meshTermCount giving the true totals. " +
+        "'details' (needs pmids, max 20 per call) — each article's full abstract, journal, year, DOI, pmcId (non-null when the article is in " +
+        "PubMed Central, which includes articles outside the open-access subset), plus the leading authors and MeSH terms with authorCount / " +
+        "meshTermCount giving the true totals. " +
         "'fulltext' (needs pmcId, taken from a 'details' result) — the body of ONE open-access PMC article as plain text with section headers " +
         "preserved, trimmed to maxChars; `outline` lists every section with its size and whether it came back, and truncated says whether " +
         "anything was left out. available: false when the article is not open-access."),
@@ -122,10 +123,10 @@ export function createPubMedTool(deps) {
             "the U.S. National Library of Medicine, through the NCBI E-utilities. The three actions form a chain " +
             "— search, then details on the relevant hits, then fulltext; see the action parameter for what each needs and returns.\n" +
             "ACCEPTED IDENTIFIERS: an Entrez free-text query with optional field tags for 'search' ('PCSK9[Title] AND 2020:2024[dp]'); PMIDs for " +
-            "'details' ('34567890'); and a PMID or a PMC ID for 'fulltext' ('PMC7096066'). For literature outside MEDLINE — a method, a model, a " +
-            "preprint — use search_semantic_scholar or search_arxiv instead.\n" +
+            "'details' ('34567890'); and a PMC ID for 'fulltext' ('PMC7096066'), never a PMID — the PMC number of an article differs from its PMID. " +
+            "PubMed holds MEDLINE and PMC only, thus a method, a model or a preprint outside MEDLINE is often absent here.\n" +
             "Read " +
-            "fulltext sparingly — only where the 'details' abstract is not enough, and only for articles that have a pmcId (open-access). " +
+            "fulltext sparingly — only where the 'details' abstract is not enough, and only for articles that have a pmcId. " +
             "A full article is larger than everything else this tool returns combined, so it comes back trimmed to a character budget: take the " +
             "`outline` from the first call and re-request the specific `sections` you need rather than raising maxChars. " +
             "An empty result set and available: false are expected outcomes, not errors — an article with no PMC record simply has no open full text. " +
@@ -172,7 +173,10 @@ export function createPubMedTool(deps) {
                     // "Not open-access" is an expected outcome — a data variant, not an error.
                     if (!parsed)
                         return ok({ pmcId: input.pmcId, available: false });
-                    return ok({ pmcId: input.pmcId, available: true, ...parsed });
+                    // `fullText` already holds each admitted section under its heading, thus the
+                    // `sections` array would send the same text to the model a second time.
+                    const { sections: _sections, ...bounded } = parsed;
+                    return ok({ pmcId: input.pmcId, available: true, ...bounded });
                 }
             }
         },