@inflexa-ai/harness 0.35.5 → 0.35.6

package/dist/agents/conversation-agent.js

@@ -27,7 +27,7 @@ import { createWorkingMemory } from "../memory/working-memory.js";
 import { conversationPrompt } from "../prompts/conversation.js";
 import { composeSystemPrompt } from "./system-prompt.js";
 // Bio-lookup leaf tools (pure — no dependencies).
-import { searchGeneTool, lookupAnnotationTool, searchInteractionsTool, chemblTool, pubchemTool, openTargetsTool, searchFaersTool, searchClinicalTrialsTool, searchGeoDatasetsTool, genePreclinicalProfileTool, targetSafetyTool, } from "../tools/bio/index.js";
+import { searchGeneTool, searchProteinTool, lookupAnnotationTool, searchInteractionsTool, alphafoldPredictionTool, chemblTool, pubchemTool, openTargetsTool, searchFaersTool, searchClinicalTrialsTool, searchGeoDatasetsTool, genePreclinicalProfileTool, targetSafetyTool, } from "../tools/bio/index.js";
 import { createNcbiTools, createChemDbTools } from "../tools/bio/keys.js";
 // Dependency-bearing tool factories.
 import { createGeneratePlanTool, createInspectRunTool, createInspectDataProfileTool, createGenerateAnalogyReportTool, createSearchSemanticScholarTool, searchArxivTool, } from "../tools/research/index.js";
@@ -58,12 +58,17 @@ export function createConversationAgent(deps) {
         ...(deps.logger ? { logger: deps.logger } : {}),
     });
     const tools = [
-        // Identifier resolution — the ENSG most other bio tools key off.
+        // Identifier resolution — the ENSG most other bio tools key off, and the
+        // UniProt accession that the structure tools take.
         searchGeneTool,
+        searchProteinTool,
         // Functional annotation (GO / KEGG / Reactome behind one vocabulary) and
         // STRING networks + gene-set enrichment.
         lookupAnnotationTool,
         searchInteractionsTool,
+        // Structural biology — the whole-chain confidence of a predicted 3-D
+        // model, and the URLs of its coordinate and per-residue files.
+        alphafoldPredictionTool,
         // Literature (search / details / fulltext behind one action).
         ncbi.pubmed,
         // Verification of one caller-supplied citation (distinct from discovery).
@@ -131,6 +136,9 @@ export function createConversationAgent(deps) {
             resourcePolicy,
             utilityProvider,
             utilityModel,
+            ...(farmLockFile ? { farmLockFile } : {}),
+            ...(imagePackagesFile ? { imagePackagesFile } : {}),
+            ...(readPoolInventory ? { readPoolInventory } : {}),
             ...(deps.extendAnalysisFarm ? { extendAnalysisFarm: deps.extendAnalysisFarm } : {}),
             ...(deps.logger ? { logger: deps.logger } : {}),
         }),

package/dist/lib/metrics.d.ts

@@ -6,18 +6,25 @@
  *   - cortex.run.duration{status, workflow}       — histogram, start to terminal status
  *   - cortex.step.completed{status, agent_id}     — counter, one per executed step that settled
  *   - cortex.step.duration{status, agent_id}      — histogram, step start to its terminal ledger write
+ *   - cortex.sandbox.execs{outcome}               — counter, one per sandbox exec that returned a terminal result
+ *   - cortex.sandbox.exec.duration{outcome}       — histogram, the runtime the sandbox reported for that exec
+ *   - cortex.sandbox.exec.peak_memory_bytes{outcome} — histogram, the peak resident set of that exec
+ *   - cortex.sandbox.exec.cpu_seconds{outcome}    — histogram, the CPU time of that exec
  *   - cortex.artifact.reconcile.dropped{agent_id}              — counter for missing manifest entries
  *   - cortex.artifact.reconcile.input_dropped{agent_id, reason} — counter for lineage input drops
  *
  * Every label is a bounded vocabulary: `status` is the terminal enum, `workflow`
- * names the workflow family, `agent_id` has about 15 values. No instrument
- * carries a run, step, exec, user, or organization id — a label with unbounded
- * values multiplies the series count.
+ * names the workflow family, `agent_id` has about 15 values, `outcome` has
+ * five. No instrument carries a run, step, exec, user, or organization id — a
+ * label with unbounded values multiplies the series count, and the collector
+ * drops a datapoint that carries one.
  *
  * A run or step outcome is recorded INSIDE the DBOS step that persists the same
  * outcome to the ledger (or behind the ledger's own compare-and-set where the
  * body has no such step). DBOS caches a completed step and does not re-run its
- * body on recovery, so a replayed workflow records nothing twice.
+ * body on recovery, so a replayed workflow records nothing twice. An exec has
+ * no such step, so `recordSandboxExec` carries its own idempotence — see the
+ * note on `countedExecs`.
  *
  * Instruments are lazy so the record site binds to whichever `MeterProvider`
  * is globally registered at first use. The metrics API has no late-binding
@@ -31,12 +38,39 @@ export type RunOutcome = "completed" | "partial" | "failed" | "canceled";
 export type RunWorkflow = "analysis" | "target_assessment" | "data_profile";
 /** Terminal status of an executed step. A blocker is a failure to deliver, so `blocked` maps here to `failed`. */
 export type StepOutcome = "completed" | "failed" | "canceled";
+/**
+ * Terminal outcome of one sandbox exec. `nonzero` is the command's own
+ * verdict; `timeout` is the deadline; the two synthetic values name a machine
+ * that died under the command, which is an outcome of the platform and not of
+ * the analysis. Five values, thus five series for each instrument.
+ */
+export type SandboxExecOutcome = "ok" | "nonzero" | "timeout" | "synthetic-dead" | "synthetic-oom";
 /**
  * Bucket bounds for durations that run from seconds to hours: 30 s, then
  * 1, 2, 5, 10, 30, 60, 120, 240 min. Ten buckets with the overflow, so one
  * histogram costs about ten series per label set.
  */
 export declare const RUN_DURATION_BOUNDS_MS: readonly number[];
+/**
+ * Bucket bounds for one exec, which runs from a sub-second probe to an
+ * hours-long analysis: 1, 5, 15, 30 s, then 1, 5, 15, 30, 60 min. The run
+ * bounds start at 30 s and would put almost every exec in the first bucket.
+ */
+export declare const EXEC_DURATION_BOUNDS_MS: readonly number[];
+/**
+ * Bucket bounds for the peak resident set of one exec, in bytes: 128 MiB up to
+ * 128 GiB by doubling. The top bound is the largest memory a step can request
+ * (`SANDBOX_MAX_MEMORY_GB`), thus the overflow bucket holds only a sandbox that
+ * outgrew its own ceiling.
+ */
+export declare const SANDBOX_PEAK_MEMORY_BOUNDS_BYTES: readonly number[];
+/**
+ * Bucket bounds for the CPU time of one exec, in seconds: sub-second up to four
+ * hours. Read against `cortex.sandbox.exec.duration` it gives the mean core
+ * count the command held, which is what says whether its CPU request was worth
+ * granting.
+ */
+export declare const SANDBOX_CPU_SECONDS_BOUNDS: readonly number[];
 /**
  * Record one run that reached a terminal status. Call it inside the DBOS step
  * that persists that status, or behind the ledger compare-and-set that accepted
@@ -71,6 +105,23 @@ export declare function stepOutcomeOf(status: StepExecutionStatus): StepOutcome
  * without a duration instead of recording a bogus one.
  */
 export declare function elapsedSinceIso(startedAt: string | null | undefined, nowMs?: number): number | undefined;
+/**
+ * Record one sandbox exec that returned a terminal result. Call it at the one
+ * seam where an `ExecResult` crosses from the wire into the process. A result
+ * that carries no runtime (a synthetic failure) is counted, not timed.
+ *
+ * `peakMemoryBytes` and `cpuMillis` are the kernel accounting the sandbox
+ * reports for the command. Each one is independent: a sandbox image that
+ * predates the accounting, and an exec whose command never spawned, report
+ * neither, thus a missing member records nothing rather than a zero.
+ */
+export declare function recordSandboxExec(args: {
+    readonly execId: string;
+    readonly outcome: SandboxExecOutcome;
+    readonly durationMs?: number | null;
+    readonly peakMemoryBytes?: number | undefined;
+    readonly cpuMillis?: number | undefined;
+}): void;
 /** Record one manifest entry dropped at reconcile. */
 export declare function recordArtifactReconcileDropped(args: {
     readonly agentId: string;

package/dist/lib/metrics.js

@@ -6,18 +6,25 @@
  *   - cortex.run.duration{status, workflow}       — histogram, start to terminal status
  *   - cortex.step.completed{status, agent_id}     — counter, one per executed step that settled
  *   - cortex.step.duration{status, agent_id}      — histogram, step start to its terminal ledger write
+ *   - cortex.sandbox.execs{outcome}               — counter, one per sandbox exec that returned a terminal result
+ *   - cortex.sandbox.exec.duration{outcome}       — histogram, the runtime the sandbox reported for that exec
+ *   - cortex.sandbox.exec.peak_memory_bytes{outcome} — histogram, the peak resident set of that exec
+ *   - cortex.sandbox.exec.cpu_seconds{outcome}    — histogram, the CPU time of that exec
  *   - cortex.artifact.reconcile.dropped{agent_id}              — counter for missing manifest entries
  *   - cortex.artifact.reconcile.input_dropped{agent_id, reason} — counter for lineage input drops
  *
  * Every label is a bounded vocabulary: `status` is the terminal enum, `workflow`
- * names the workflow family, `agent_id` has about 15 values. No instrument
- * carries a run, step, exec, user, or organization id — a label with unbounded
- * values multiplies the series count.
+ * names the workflow family, `agent_id` has about 15 values, `outcome` has
+ * five. No instrument carries a run, step, exec, user, or organization id — a
+ * label with unbounded values multiplies the series count, and the collector
+ * drops a datapoint that carries one.
  *
  * A run or step outcome is recorded INSIDE the DBOS step that persists the same
  * outcome to the ledger (or behind the ledger's own compare-and-set where the
  * body has no such step). DBOS caches a completed step and does not re-run its
- * body on recovery, so a replayed workflow records nothing twice.
+ * body on recovery, so a replayed workflow records nothing twice. An exec has
+ * no such step, so `recordSandboxExec` carries its own idempotence — see the
+ * note on `countedExecs`.
  *
  * Instruments are lazy so the record site binds to whichever `MeterProvider`
  * is globally registered at first use. The metrics API has no late-binding
@@ -31,6 +38,28 @@ import { metrics } from "@opentelemetry/api";
  * histogram costs about ten series per label set.
  */
 export const RUN_DURATION_BOUNDS_MS = [30_000, 60_000, 120_000, 300_000, 600_000, 1_800_000, 3_600_000, 7_200_000, 14_400_000];
+/**
+ * Bucket bounds for one exec, which runs from a sub-second probe to an
+ * hours-long analysis: 1, 5, 15, 30 s, then 1, 5, 15, 30, 60 min. The run
+ * bounds start at 30 s and would put almost every exec in the first bucket.
+ */
+export const EXEC_DURATION_BOUNDS_MS = [1_000, 5_000, 15_000, 30_000, 60_000, 300_000, 900_000, 1_800_000, 3_600_000];
+/**
+ * Bucket bounds for the peak resident set of one exec, in bytes: 128 MiB up to
+ * 128 GiB by doubling. The top bound is the largest memory a step can request
+ * (`SANDBOX_MAX_MEMORY_GB`), thus the overflow bucket holds only a sandbox that
+ * outgrew its own ceiling.
+ */
+export const SANDBOX_PEAK_MEMORY_BOUNDS_BYTES = [
+    134_217_728, 536_870_912, 1_073_741_824, 2_147_483_648, 4_294_967_296, 8_589_934_592, 17_179_869_184, 34_359_738_368, 68_719_476_736, 137_438_953_472,
+];
+/**
+ * Bucket bounds for the CPU time of one exec, in seconds: sub-second up to four
+ * hours. Read against `cortex.sandbox.exec.duration` it gives the mean core
+ * count the command held, which is what says whether its CPU request was worth
+ * granting.
+ */
+export const SANDBOX_CPU_SECONDS_BOUNDS = [0.5, 1, 5, 15, 60, 300, 900, 1_800, 3_600, 14_400];
 let instruments;
 function getInstruments() {
     if (instruments === undefined) {
@@ -55,6 +84,25 @@ function getInstruments() {
                 unit: "ms",
                 advice,
             }),
+            sandboxExecs: meter.createCounter("cortex.sandbox.execs", {
+                description: "Sandbox execs that returned a terminal result. Tagged by outcome.",
+                unit: "{exec}",
+            }),
+            sandboxExecDuration: meter.createHistogram("cortex.sandbox.exec.duration", {
+                description: "Runtime the sandbox reported for one exec. Tagged by outcome.",
+                unit: "ms",
+                advice: { explicitBucketBoundaries: [...EXEC_DURATION_BOUNDS_MS] },
+            }),
+            sandboxExecPeakMemory: meter.createHistogram("cortex.sandbox.exec.peak_memory_bytes", {
+                description: "Peak resident set of one sandbox exec and of every descendant it waited for. Tagged by outcome.",
+                unit: "By",
+                advice: { explicitBucketBoundaries: [...SANDBOX_PEAK_MEMORY_BOUNDS_BYTES] },
+            }),
+            sandboxExecCpuSeconds: meter.createHistogram("cortex.sandbox.exec.cpu_seconds", {
+                description: "User plus system CPU time of one sandbox exec. Tagged by outcome.",
+                unit: "s",
+                advice: { explicitBucketBoundaries: [...SANDBOX_CPU_SECONDS_BOUNDS] },
+            }),
             artifactReconcileDropped: meter.createCounter("cortex.artifact.reconcile.dropped", {
                 description: "Manifest entries dropped because their on-disk file was missing at " +
                     "registration time (writes-then-deletes, renames). Tagged by agent_id.",
@@ -132,6 +180,54 @@ export function elapsedSinceIso(startedAt, nowMs = Date.now()) {
         return undefined;
     return Math.max(0, nowMs - startedMs);
 }
+/**
+ * Exec ids already counted, so a replay counts one exec one time.
+ *
+ * The run and step counters sit inside the DBOS step that persists the same
+ * outcome, and DBOS never runs a cached step body a second time. An exec has
+ * no such step: `awaitExec` returns into the workflow body, and a new step
+ * around the record would shift the function-id sequence of every workflow
+ * that is already in flight. An exec id is `{workflowId}:{stepId}:{functionId}`
+ * and it is stable across a replay, thus it is the key that makes the record
+ * idempotent. The set is process-local: a recovery in a fresh process holds no
+ * memory of the first count and can count that exec again.
+ */
+const countedExecs = new Set();
+/**
+ * How many exec ids the guard remembers. A host runs far fewer concurrent
+ * execs than this, and a replay follows its original within one run, thus the
+ * cap only drops an id that no live workflow can present again.
+ */
+const MAX_COUNTED_EXECS = 4096;
+/**
+ * Record one sandbox exec that returned a terminal result. Call it at the one
+ * seam where an `ExecResult` crosses from the wire into the process. A result
+ * that carries no runtime (a synthetic failure) is counted, not timed.
+ *
+ * `peakMemoryBytes` and `cpuMillis` are the kernel accounting the sandbox
+ * reports for the command. Each one is independent: a sandbox image that
+ * predates the accounting, and an exec whose command never spawned, report
+ * neither, thus a missing member records nothing rather than a zero.
+ */
+export function recordSandboxExec(args) {
+    if (countedExecs.has(args.execId))
+        return;
+    if (countedExecs.size >= MAX_COUNTED_EXECS) {
+        const oldest = countedExecs.values().next();
+        if (!oldest.done)
+            countedExecs.delete(oldest.value);
+    }
+    countedExecs.add(args.execId);
+    const attributes = { outcome: args.outcome };
+    const { sandboxExecs, sandboxExecDuration, sandboxExecPeakMemory, sandboxExecCpuSeconds } = getInstruments();
+    sandboxExecs.add(1, attributes);
+    if (args.durationMs !== undefined && args.durationMs !== null)
+        sandboxExecDuration.record(Math.max(0, args.durationMs), attributes);
+    if (args.peakMemoryBytes !== undefined)
+        sandboxExecPeakMemory.record(Math.max(0, args.peakMemoryBytes), attributes);
+    if (args.cpuMillis !== undefined)
+        sandboxExecCpuSeconds.record(Math.max(0, args.cpuMillis) / 1000, attributes);
+}
 /** Record one manifest entry dropped at reconcile. */
 export function recordArtifactReconcileDropped(args) {
     getInstruments().artifactReconcileDropped.add(1, { agent_id: args.agentId });
@@ -143,4 +239,5 @@ export function recordLineageInputDropped(args) {
 /** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
 export function __resetMetricsForTest() {
     instruments = undefined;
+    countedExecs.clear();
 }

package/dist/prompts/briefing.js

@@ -62,9 +62,12 @@ export const STEP_NON_TASK_FIELDS = [
     "summary",
     "artifactIds",
     "error",
-    // Withheld on purpose: the pre-launch link pass consumes the packages of a
-    // step, and a step agent must not re-litigate them (the
-    // planning-enhancements spec).
+    // Withheld on purpose: every step reaches an agent through a launch, and
+    // the pre-launch link pass consumes the packages of every step it carries —
+    // an ad hoc step as much as a planned one. Thus the set is settled before
+    // the agent reads its task, and a step agent must not re-litigate it. What
+    // the agent does need to know about them — a dropped entry, or a step that
+    // declares none — rides in `caveats`.
     "packages",
 ];
 // ── Formatting primitives ─────────────────────────────────────────────

package/dist/prompts/literature-reviewer.d.ts

@@ -1 +1 @@
-export declare const literatureReviewerPrompt = "# Literature Reviewer\n\nYou are a systematic biology investigator. You receive a research brief\ncontaining genes, pathways, or biological features to investigate, along\nwith the experimental context. Your job is to use your tools to build a\ncomprehensive evidence profile and return a structured report.\n\nYou are task-oriented \u2014 you do NOT interact with the user. You receive\na brief, investigate, and return results.\n\n## Tool usage notes (read before calling any tool)\n\nSeveral tools have strict input shapes. Mis-shaping your call wastes a\nturn and forces a retry.\n\n- `pubmed({action:\"search\"})` \u2014 pass a focused query string. Shape: `{ action: \"search\", query: \"BRCA1 AND breast cancer\", maxResults: 10 }`.\n- `pubmed({action:\"details\"})` \u2014 MUST be called with `pmids`, a non-empty array of\n  PMID strings. Shape: `{ action: \"details\", pmids: [\"12345678\", \"87654321\"] }`.\n- `search_interactions` \u2014 accepts up to **100 identifiers per call**. If you\n  need more, **batch across multiple calls** rather than truncating your\n  list. Shape: `{ identifiers: [\"TP53\", \"BRCA1\", ...], limit: 50 }`.\n- `search_gene` \u2014 batches up to 200 symbols; `lookup_annotation` takes one\n  term or accession per call.\n- `gene_preclinical_profile` \u2014 single human gene symbol per call; returns\n  baseline expression and mouse-KO phenotype together. Empty/null fields are\n  valid \"no data\" outcomes (Bgee may have no calls for dog or macaque; many\n  human genes are not yet IMPC-phenotyped). Do NOT retry on empty output.\n- `pubmed({action:\"fulltext\"})` \u2014 single `pmcId` per call (from a `details` result). Use sparingly.\n- `resolve_citation` \u2014 verify one citation already supplied in the brief or returned by another source. Use it for identity/metadata verification, not topical discovery. Preserve its verdict and coverage exactly: `inconclusive` is not `not_found`, and an unavailable authority is not proof of fabrication.\n\nBatching beats truncation: if you have 300 identifiers to look up in\n`search_interactions`, make three calls of 100 rather than one call of 100\nthat silently drops the other 200.\n\n## Investigation Process\n\nFor each gene, pathway, or feature in the brief:\n\n1. **Gene/protein lookup** \u2014 use `search_gene` to get function, aliases,\n   associated diseases, and expression patterns.\n2. **Pathway context** \u2014 use `lookup_annotation({vocabulary:\"pathways\"})` to\n   find pathways involving the gene. Note which pathways connect multiple\n   genes from the brief.\n3. **GO terms** \u2014 use `lookup_annotation({vocabulary:\"go\"})` for functional\n   annotations when the gene's role is unclear from the gene search alone.\n4. **Protein interactions** \u2014 use `search_interactions` to find\n   interaction partners, especially those that also appear in the brief.\n5. **Literature evidence** \u2014 use `pubmed({action:\"search\"})` with targeted queries\n   combining the gene name with the disease/condition from the brief.\n   Use `pubmed({action:\"details\"})` for the most relevant hits. Use\n   `pubmed({action:\"fulltext\"})` only for highly relevant papers that need\n   deeper reading.\n6. **Preclinical grounding** \u2014 when the brief asks about tissue expression,\n   model-organism suitability, or KO consequences, call\n   `gene_preclinical_profile`, which returns cross-species baseline\n   expression and mouse-KO phenotype + viability together. It takes a single\n   human gene symbol and tolerates \"no data\" cleanly.\n\n## Depth Guidelines\n\n- **Top priority targets** (top DE genes, hub genes, user-specified):\n  Full investigation \u2014 all 5 steps above.\n- **Supporting targets** (enriched pathways, interaction partners):\n  Gene lookup + pathway + literature. Skip GO terms and interactions\n  unless results are ambiguous.\n- **Limit PubMed searches**: max 2-3 queries per gene. Combine terms\n  effectively (e.g., \"BRCA1 AND breast cancer AND RNA-seq\") rather\n  than running many narrow queries.\n- **Limit article deep-reads**: use `pubmed({action:\"fulltext\"})` on at most\n  3-5 articles total, only for papers directly relevant to the\n  experimental context.\n\n## Output Format\n\nReturn a structured report in this format:\n\n### Evidence Summary\n\nFor each investigated target:\n\n**[Gene/Pathway Name]**\n- **Function**: Brief description of known function\n- **Relevance to context**: How it connects to the experimental\n  conditions (e.g., \"known role in AD pathology\")\n- **Literature support**: Key findings from PubMed (cite PMIDs)\n- **Interaction network**: Notable interaction partners found,\n  especially those also in the data\n- **Novelty assessment**: Is this finding well-established, recently\n  emerging, or potentially novel?\n\n### Cross-Target Patterns\n- Genes that share pathways or interact directly\n- Convergent biological themes (e.g., multiple genes in immune signaling)\n- Contradictions or unexpected associations\n\n### Key References\n- List the most important PMIDs with one-line descriptions\n\n## Do NOT\n\n- **Fabricate results.** If a search returns no results, say so.\n- **Turn resolver uncertainty into certainty.** Never describe a weak candidate, partial coverage, or an unavailable source as proof that a citation is fabricated.\n- **Skip tool calls.** Do not claim knowledge about a gene without\n  looking it up. Your value is in systematic, verified investigation.\n- **Over-read articles.** Use `pubmed({action:\"fulltext\"})` sparingly \u2014 abstracts\n  from `pubmed({action:\"details\"})` are sufficient for most assessments.\n- **Investigate targets not in the brief.** Stay focused on what was\n  requested. Note interesting leads for follow-up but do not chase them.\n- **Produce conversational text.** You are returning a structured report,\n  not chatting with a user.\n";
+export declare const literatureReviewerPrompt = "# Literature Reviewer\n\nYou are a systematic biology investigator. You receive a research brief\ncontaining genes, pathways, or biological features to investigate, along\nwith the experimental context. Your job is to use your tools to build a\ncomprehensive evidence profile and return a structured report.\n\nYou are task-oriented \u2014 you do NOT interact with the user. You receive\na brief, investigate, and return results.\n\n## Tool usage notes (read before calling any tool)\n\nSeveral tools have strict input shapes. Mis-shaping your call wastes a\nturn and forces a retry.\n\n- `pubmed({action:\"search\"})` \u2014 pass a focused query string. Shape: `{ action: \"search\", query: \"BRCA1 AND breast cancer\", maxResults: 10 }`.\n- `pubmed({action:\"details\"})` \u2014 MUST be called with `pmids`, a non-empty array of\n  PMID strings. Shape: `{ action: \"details\", pmids: [\"12345678\", \"87654321\"] }`.\n- `search_interactions` \u2014 accepts up to **100 identifiers per call**. If you\n  need more, **batch across multiple calls** rather than truncating your\n  list. Shape: `{ identifiers: [\"TP53\", \"BRCA1\", ...], limit: 50 }`.\n- `search_gene` \u2014 batches up to 200 symbols; `lookup_annotation` takes one\n  term or accession per call.\n- `search_protein` \u2014 one gene symbol or UniProt accession per call. It answers\n  with the protein: the accession, the recommended name, the sequence length,\n  the curated function, and the subcellular locations. An empty `proteins`\n  array is a valid \"no data\" outcome; do NOT retry the same call.\n- `gene_preclinical_profile` \u2014 single human gene symbol per call; returns\n  baseline expression and mouse-KO phenotype together. Empty/null fields are\n  valid \"no data\" outcomes (Bgee may have no calls for dog or macaque; many\n  human genes are not yet IMPC-phenotyped). Do NOT retry on empty output.\n- `pubmed({action:\"fulltext\"})` \u2014 single `pmcId` per call (from a `details` result). Use sparingly.\n- `resolve_citation` \u2014 verify one citation already supplied in the brief or returned by another source. Use it for identity/metadata verification, not topical discovery. Preserve its verdict and coverage exactly: `inconclusive` is not `not_found`, and an unavailable authority is not proof of fabrication.\n\nBatching beats truncation: if you have 300 identifiers to look up in\n`search_interactions`, make three calls of 100 rather than one call of 100\nthat silently drops the other 200.\n\n## Investigation Process\n\nFor each gene, pathway, or feature in the brief:\n\n1. **Gene lookup** \u2014 use `search_gene` to get the gene: its Ensembl ID,\n   coordinates, biotype, and aliases.\n2. **Protein lookup** \u2014 use `search_protein` when the claim is about the\n   protein rather than the locus: what it does, how long it is, and where in\n   the cell it acts. It also returns the UniProt accession, which is the key\n   the structure tools take.\n3. **Pathway context** \u2014 use `lookup_annotation({vocabulary:\"pathways\"})` to\n   find pathways involving the gene. Note which pathways connect multiple\n   genes from the brief.\n4. **GO terms** \u2014 use `lookup_annotation({vocabulary:\"go\"})` for functional\n   annotations when the gene's role is unclear from the gene search alone.\n5. **Protein interactions** \u2014 use `search_interactions` to find\n   interaction partners, especially those that also appear in the brief.\n6. **Literature evidence** \u2014 use `pubmed({action:\"search\"})` with targeted queries\n   combining the gene name with the disease/condition from the brief.\n   Use `pubmed({action:\"details\"})` for the most relevant hits. Use\n   `pubmed({action:\"fulltext\"})` only for highly relevant papers that need\n   deeper reading.\n7. **Preclinical grounding** \u2014 when the brief asks about tissue expression,\n   model-organism suitability, or KO consequences, call\n   `gene_preclinical_profile`, which returns cross-species baseline\n   expression and mouse-KO phenotype + viability together. It takes a single\n   human gene symbol and tolerates \"no data\" cleanly.\n\n## Depth Guidelines\n\n- **Top priority targets** (top DE genes, hub genes, user-specified):\n  Full investigation \u2014 every step above.\n- **Supporting targets** (enriched pathways, interaction partners):\n  Gene lookup + pathway + literature. Skip GO terms and interactions\n  unless results are ambiguous.\n- **Limit PubMed searches**: max 2-3 queries per gene. Combine terms\n  effectively (e.g., \"BRCA1 AND breast cancer AND RNA-seq\") rather\n  than running many narrow queries.\n- **Limit article deep-reads**: use `pubmed({action:\"fulltext\"})` on at most\n  3-5 articles total, only for papers directly relevant to the\n  experimental context.\n\n## Output Format\n\nReturn a structured report in this format:\n\n### Evidence Summary\n\nFor each investigated target:\n\n**[Gene/Pathway Name]**\n- **Function**: Brief description of known function\n- **Relevance to context**: How it connects to the experimental\n  conditions (e.g., \"known role in AD pathology\")\n- **Literature support**: Key findings from PubMed (cite PMIDs)\n- **Interaction network**: Notable interaction partners found,\n  especially those also in the data\n- **Novelty assessment**: Is this finding well-established, recently\n  emerging, or potentially novel?\n\n### Cross-Target Patterns\n- Genes that share pathways or interact directly\n- Convergent biological themes (e.g., multiple genes in immune signaling)\n- Contradictions or unexpected associations\n\n### Key References\n- List the most important PMIDs with one-line descriptions\n\n## Do NOT\n\n- **Fabricate results.** If a search returns no results, say so.\n- **Turn resolver uncertainty into certainty.** Never describe a weak candidate, partial coverage, or an unavailable source as proof that a citation is fabricated.\n- **Skip tool calls.** Do not claim knowledge about a gene without\n  looking it up. Your value is in systematic, verified investigation.\n- **Over-read articles.** Use `pubmed({action:\"fulltext\"})` sparingly \u2014 abstracts\n  from `pubmed({action:\"details\"})` are sufficient for most assessments.\n- **Investigate targets not in the brief.** Stay focused on what was\n  requested. Note interesting leads for follow-up but do not chase them.\n- **Produce conversational text.** You are returning a structured report,\n  not chatting with a user.\n";

package/dist/prompts/literature-reviewer.js

@@ -21,6 +21,10 @@ turn and forces a retry.
   list. Shape: \`{ identifiers: ["TP53", "BRCA1", ...], limit: 50 }\`.
 - \`search_gene\` — batches up to 200 symbols; \`lookup_annotation\` takes one
   term or accession per call.
+- \`search_protein\` — one gene symbol or UniProt accession per call. It answers
+  with the protein: the accession, the recommended name, the sequence length,
+  the curated function, and the subcellular locations. An empty \`proteins\`
+  array is a valid "no data" outcome; do NOT retry the same call.
 - \`gene_preclinical_profile\` — single human gene symbol per call; returns
   baseline expression and mouse-KO phenotype together. Empty/null fields are
   valid "no data" outcomes (Bgee may have no calls for dog or macaque; many
@@ -36,21 +40,25 @@ that silently drops the other 200.
 
 For each gene, pathway, or feature in the brief:
 
-1. **Gene/protein lookup** — use \`search_gene\` to get function, aliases,
-   associated diseases, and expression patterns.
-2. **Pathway context** — use \`lookup_annotation({vocabulary:"pathways"})\` to
+1. **Gene lookup** — use \`search_gene\` to get the gene: its Ensembl ID,
+   coordinates, biotype, and aliases.
+2. **Protein lookup** — use \`search_protein\` when the claim is about the
+   protein rather than the locus: what it does, how long it is, and where in
+   the cell it acts. It also returns the UniProt accession, which is the key
+   the structure tools take.
+3. **Pathway context** — use \`lookup_annotation({vocabulary:"pathways"})\` to
    find pathways involving the gene. Note which pathways connect multiple
    genes from the brief.
-3. **GO terms** — use \`lookup_annotation({vocabulary:"go"})\` for functional
+4. **GO terms** — use \`lookup_annotation({vocabulary:"go"})\` for functional
    annotations when the gene's role is unclear from the gene search alone.
-4. **Protein interactions** — use \`search_interactions\` to find
+5. **Protein interactions** — use \`search_interactions\` to find
    interaction partners, especially those that also appear in the brief.
-5. **Literature evidence** — use \`pubmed({action:"search"})\` with targeted queries
+6. **Literature evidence** — use \`pubmed({action:"search"})\` with targeted queries
    combining the gene name with the disease/condition from the brief.
    Use \`pubmed({action:"details"})\` for the most relevant hits. Use
    \`pubmed({action:"fulltext"})\` only for highly relevant papers that need
    deeper reading.
-6. **Preclinical grounding** — when the brief asks about tissue expression,
+7. **Preclinical grounding** — when the brief asks about tissue expression,
    model-organism suitability, or KO consequences, call
    \`gene_preclinical_profile\`, which returns cross-species baseline
    expression and mouse-KO phenotype + viability together. It takes a single
@@ -59,7 +67,7 @@ For each gene, pathway, or feature in the brief:
 ## Depth Guidelines
 
 - **Top priority targets** (top DE genes, hub genes, user-specified):
-  Full investigation — all 5 steps above.
+  Full investigation — every step above.
 - **Supporting targets** (enriched pathways, interaction partners):
   Gene lookup + pathway + literature. Skip GO terms and interactions
   unless results are ambiguous.

package/dist/prompts/planner.d.ts

@@ -2,4 +2,8 @@ import type { ResourcePolicy } from "../config/resource-limits.js";
 /** The Resource Estimation planning rules — concrete host limits when a
  *  policy is supplied, the historical default guidance otherwise. */
 export declare function resourceEstimationSection(policy?: ResourcePolicy): string;
+/** The one grammar of a `packages` entry. Every surface that asks a model for
+ *  that array teaches it from here: two texts of one grammar drift, and a
+ *  spelling rule that only one surface states is a launch refusal on the other. */
+export declare function packagesSection(): string;
 export declare function plannerPrompt(agentCatalog: string, resourcePolicy?: ResourcePolicy): string;

package/dist/prompts/planner.js

@@ -25,6 +25,27 @@ need 18 GB of RAM.`;
   restructuring or downsizing yields a viable plan — call \`report_blocker\`
   naming the resource shortfall as the reason.`;
 }
+/** The one grammar of a `packages` entry. Every surface that asks a model for
+ *  that array teaches it from here: two texts of one grammar drift, and a
+ *  spelling rule that only one surface states is a launch refusal on the other. */
+export function packagesSection() {
+    return `### The Packages of Each Step
+Every step carries a \`packages\` array — the packages its scripts import.
+
+- Name each package as a requirement: a bare name (\`"scanpy"\`), or a name with
+  one exact version (\`"numpy==1.26.4"\`). Never a path, a URL, or a store
+  directory — a location is an installer detail, and validation refuses it.
+- An empty array is valid: the step needs nothing beyond the baked toolchain.
+- When the package census shows one name under a Python section AND under an R
+  section, write the prefixed form the census shows: \`"python:igraph"\` or
+  \`"r:igraph"\`. A bare name that both tracks hold refuses the launch, because
+  the pool cannot tell which package you mean.
+- Write a bare name for every other package. The prefix is for a both-track
+  name only.
+- The set is not a promise of completeness. The execution agent can still link a
+  missing package mid-step. Name what you know the step imports; do not pad the
+  list defensively.`;
+}
 export function plannerPrompt(agentCatalog, resourcePolicy) {
     return `# Analysis Planner
 
@@ -160,22 +181,7 @@ only once the run reaches it, which is the most expensive moment to learn it.
   absent reference: \`request_clarification\`, rather than plan a step that can
   only report failure.
 
-### The Packages of Each Step
-Every step carries a \`packages\` array — the packages its scripts import.
-
-- Name each package as a requirement: a bare name (\`"scanpy"\`), or a name with
-  one exact version (\`"numpy==1.26.4"\`). Never a path, a URL, or a store
-  directory — a location is an installer detail, and validation refuses it.
-- An empty array is valid: the step needs nothing beyond the baked toolchain.
-- When the package census shows one name under a Python section AND under an R
-  section, write the prefixed form the census shows: \`"python:igraph"\` or
-  \`"r:igraph"\`. A bare name that both tracks hold refuses the launch, because
-  the pool cannot tell which package you mean.
-- Write a bare name for every other package. The prefix is for a both-track
-  name only.
-- The set is not a promise of completeness. The execution agent can still link a
-  missing package mid-step. Name what you know the step imports; do not pad the
-  list defensively.
+${packagesSection()}
 
 ### Resource Estimation
 ${resourceEstimationSection(resourcePolicy)}

package/dist/sandbox/create-sandbox.js

@@ -13,6 +13,7 @@
  */
 import { chmod, mkdir } from "node:fs/promises";
 import { join } from "node:path";
+import { recordSandboxExec } from "../lib/metrics.js";
 import { clampResources } from "../config/resource-limits.js";
 import { tailWritePrefix } from "../workspace/paths.js";
 import { tryMutation } from "../lib/db-result.js";
@@ -21,6 +22,7 @@ import { clearSandboxRef, setSandboxRef } from "../state/index.js";
 import { capExecStreams, EXEC_STREAM_BYTE_CAP } from "../tools/workspace/result-bounds.js";
 import { awaitExec } from "./await-exec.js";
 import { createDockerSandboxOps } from "./docker-client.js";
+import { noteExecOutcome, sandboxExecOutcomeOf, summarizeExec } from "./exec-outcome.js";
 import { createK8sSandboxOps } from "./k8s-client.js";
 import { sandboxWriteTail } from "./mount-plan.js";
 import { SandboxFailure } from "./sandbox-error.js";
@@ -198,7 +200,27 @@ export function createSandboxClient(config) {
         // tool results, workflow return values, durable step outputs — is bounded
         // by construction, including against a sandbox image that predates the
         // retention budget and still returns whole streams.
-        awaitExec: async (ref, execId, emit, deadline) => capExecStreams(await awaitExec(ref, execId, emit, deadline, composeAwaitOptions(config.awaitOptions, transport, isAlive)), config.execStreamByteCap ?? EXEC_STREAM_BYTE_CAP),
+        //
+        // The same seam is where an exec becomes observable. It sees every exec
+        // of every caller — the step agent, the data profile, the derivations —
+        // and it sees the outcome the caller then folds into a tool result, so
+        // one record here counts what a consumer would each have to count for
+        // itself. `recordSandboxExec` is idempotent over the exec id, because a
+        // replayed body reaches this line again. `capExecStreams` cuts the
+        // streams and keeps every other field, thus the kernel accounting the
+        // sandbox reported reaches the record intact.
+        awaitExec: async (ref, execId, emit, deadline) => {
+            const result = capExecStreams(await awaitExec(ref, execId, emit, deadline, composeAwaitOptions(config.awaitOptions, transport, isAlive)), config.execStreamByteCap ?? EXEC_STREAM_BYTE_CAP);
+            recordSandboxExec({
+                execId,
+                outcome: sandboxExecOutcomeOf(result),
+                durationMs: result.durationMs,
+                peakMemoryBytes: result.usage?.peakMemoryBytes,
+                cpuMillis: result.usage?.cpuMillis,
+            });
+            noteExecOutcome(ref.sandboxId, summarizeExec(result));
+            return result;
+        },
         isAlive,
         isAliveById: async (sandboxId) => unwrapOrThrow((await ops.isAliveById(sandboxId)).mapErr(failing)),
         teardown,

package/dist/sandbox/exec-outcome.d.ts

@@ -0,0 +1,45 @@
+/**
+ * What one settled exec is worth to an operator: the bounded outcome that
+ * `cortex.sandbox.execs` counts, and the summary that the `step failure`
+ * record of `workflows/sandbox-step.ts` carries.
+ *
+ * No stream text crosses this module. Sandbox output is generated code and the
+ * output of that code, thus it is untrusted, and the sandbox-exec-logging spec
+ * keeps that text on the sandbox side of the boundary. A summary gives the
+ * SIZE of stderr and never a byte of it.
+ *
+ * The summary of the last exec of a sandbox lives in one process-local cell,
+ * keyed by sandbox id. A sandbox belongs to one step (see the teardown of
+ * `create-sandbox.ts`), thus the cell is step-scoped in effect and the step
+ * body reads it without a new dependency through the agent factory. A replay
+ * re-runs the await loop and writes the cell again, thus a recovered body
+ * reads the summary of the same exec. The map is capped, so a sandbox whose
+ * step never reaches the read site cannot hold memory.
+ */
+import type { SandboxExecOutcome } from "../lib/metrics.js";
+import type { ExecResult } from "./types.js";
+/**
+ * The outcome one result carries. A synthetic failure names a dead machine and
+ * not a command, thus it wins over every other field. A timeout wins over the
+ * exit code that the kill produced. `ok` is exit code 0 and nothing else, thus
+ * a result with no code counts as `nonzero`.
+ */
+export declare function sandboxExecOutcomeOf(result: ExecResult): SandboxExecOutcome;
+/** The account of one exec that a failure record can hold. Text-free by construction. */
+export interface ExecOutcomeSummary {
+    readonly exitCode: number | null;
+    readonly timedOut: boolean;
+    /**
+     * What the command wrote to stderr, in bytes. The sandbox reports the total
+     * when it dropped output past its retention budget; without that total the
+     * retained slice IS the whole stream, so its length is the total.
+     */
+    readonly stderrTotalBytes: number;
+    readonly syntheticFailureReason?: string;
+}
+/** Reduce a result to its summary. */
+export declare function summarizeExec(result: ExecResult): ExecOutcomeSummary;
+/** Keep `summary` as the last known exec of `sandboxId`. */
+export declare function noteExecOutcome(sandboxId: string, summary: ExecOutcomeSummary): void;
+/** The last known exec of `sandboxId`, or `undefined` when it ran none. */
+export declare function lastExecOutcome(sandboxId: string): ExecOutcomeSummary | undefined;

package/dist/sandbox/exec-outcome.js

@@ -0,0 +1,65 @@
+/**
+ * What one settled exec is worth to an operator: the bounded outcome that
+ * `cortex.sandbox.execs` counts, and the summary that the `step failure`
+ * record of `workflows/sandbox-step.ts` carries.
+ *
+ * No stream text crosses this module. Sandbox output is generated code and the
+ * output of that code, thus it is untrusted, and the sandbox-exec-logging spec
+ * keeps that text on the sandbox side of the boundary. A summary gives the
+ * SIZE of stderr and never a byte of it.
+ *
+ * The summary of the last exec of a sandbox lives in one process-local cell,
+ * keyed by sandbox id. A sandbox belongs to one step (see the teardown of
+ * `create-sandbox.ts`), thus the cell is step-scoped in effect and the step
+ * body reads it without a new dependency through the agent factory. A replay
+ * re-runs the await loop and writes the cell again, thus a recovered body
+ * reads the summary of the same exec. The map is capped, so a sandbox whose
+ * step never reaches the read site cannot hold memory.
+ */
+/** The reason that names a machine the kernel killed for its memory limit. */
+const OOM_KILLED = "sandbox-oom-killed";
+/**
+ * The outcome one result carries. A synthetic failure names a dead machine and
+ * not a command, thus it wins over every other field. A timeout wins over the
+ * exit code that the kill produced. `ok` is exit code 0 and nothing else, thus
+ * a result with no code counts as `nonzero`.
+ */
+export function sandboxExecOutcomeOf(result) {
+    if (result.syntheticFailure)
+        return result.syntheticFailure.reason === OOM_KILLED ? "synthetic-oom" : "synthetic-dead";
+    if (result.timedOut)
+        return "timeout";
+    return result.exitCode === 0 ? "ok" : "nonzero";
+}
+/** Reduce a result to its summary. */
+export function summarizeExec(result) {
+    return {
+        exitCode: result.exitCode,
+        timedOut: result.timedOut,
+        stderrTotalBytes: result.stderrTotalBytes ?? Buffer.byteLength(result.stderr, "utf8"),
+        ...(result.syntheticFailure ? { syntheticFailureReason: result.syntheticFailure.reason } : {}),
+    };
+}
+/**
+ * How many sandboxes keep a summary. A host runs far fewer sandboxes at once
+ * than this, thus the cap only drops the summary of a step that ended long ago.
+ */
+const MAX_TRACKED_SANDBOXES = 256;
+const lastExecBySandbox = new Map();
+/** Keep `summary` as the last known exec of `sandboxId`. */
+export function noteExecOutcome(sandboxId, summary) {
+    // Delete before set so the key moves to the end of the insertion order and
+    // the eviction below drops the least recently written sandbox.
+    lastExecBySandbox.delete(sandboxId);
+    lastExecBySandbox.set(sandboxId, summary);
+    while (lastExecBySandbox.size > MAX_TRACKED_SANDBOXES) {
+        const oldest = lastExecBySandbox.keys().next();
+        if (oldest.done)
+            break;
+        lastExecBySandbox.delete(oldest.value);
+    }
+}
+/** The last known exec of `sandboxId`, or `undefined` when it ran none. */
+export function lastExecOutcome(sandboxId) {
+    return lastExecBySandbox.get(sandboxId);
+}

package/dist/sandbox/k8s-client.d.ts

@@ -95,6 +95,16 @@ export interface K8sClientConfig {
     coreApi?: CoreV1Api;
     registerSandbox: (meta: CreateSandboxMeta, ref: SandboxRef) => Promise<void>;
 }
+/** Clock and sleep seams, so a test can drive the slow-pod warning without waiting a minute. */
+export interface WaitForPodReadyDeps {
+    readonly logger?: Logger;
+    readonly now?: () => number;
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+export declare function waitForPodReady(coreApi: CoreV1Api, namespace: string, sandboxId: string, deps?: WaitForPodReadyDeps): ResultAsync<{
+    podIP: string;
+    podName: string;
+}, SandboxError>;
 export declare function createK8sSandboxOps(config: K8sClientConfig): {
     createSandbox(meta: CreateSandboxMeta, identity: SandboxIdentity): ResultAsync<SandboxRef, SandboxError>;
     teardown(ref: SandboxRef): ResultAsync<void, SandboxError>;