@inflexa-ai/harness 0.35.5 → 0.35.7

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>;

package/dist/sandbox/k8s-client.js

@@ -30,6 +30,13 @@ const REFS_VOLUME_NAME = "refs";
 const SANDBOX_SERVER_PORT = 8765;
 const POD_READY_TIMEOUT_MS = 5 * 60_000;
 const POD_POLL_INTERVAL_MS = 1_000;
+/**
+ * How long a pod can take to reach Running before the wait is worth a warning.
+ * A sandbox pod on a warm agent node starts in seconds; a minute means the
+ * scheduler is waiting for something — a node to come up, a quota, a volume —
+ * and the run pays that minute before any command executes.
+ */
+const POD_READY_SLOW_MS = 60_000;
 const MANAGED_BY_LABEL = "app.kubernetes.io/managed-by";
 const MANAGED_BY_VALUE = "cortex";
 /**
@@ -311,7 +318,15 @@ function buildJobSpec(meta, config, identity, farm, libsMounted) {
         },
     };
 }
-function waitForPodReady(coreApi, namespace, sandboxId) {
+/**
+ * The reason of the first condition the pod does not meet. `PodScheduled` and
+ * `Ready` both carry one, and it names what the wait is actually on.
+ */
+function pendingConditionReason(pod) {
+    const unmet = pod?.status?.conditions?.find((condition) => condition.status !== "True" && (condition.reason ?? "") !== "");
+    return unmet?.reason;
+}
+export function waitForPodReady(coreApi, namespace, sandboxId, deps = {}) {
     const createFailed = (status, cause) => ({
         type: "container_create_failed",
         op: "k8s.waitForPodReady",
@@ -319,10 +334,15 @@ function waitForPodReady(coreApi, namespace, sandboxId) {
         status,
         cause,
     });
+    const now = deps.now ?? (() => Date.now());
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const logger = (deps.logger ?? createNoopLogger()).named("k8s-client");
     return new ResultAsync((async () => {
-        const deadline = Date.now() + POD_READY_TIMEOUT_MS;
+        const startedAt = now();
+        const deadline = startedAt + POD_READY_TIMEOUT_MS;
+        let warnedSlow = false;
         let lastSnapshot = {};
-        while (Date.now() < deadline) {
+        while (now() < deadline) {
             const listed = await trySandbox(() => coreApi.listNamespacedPod({
                 namespace,
                 labelSelector: `cortex/sandbox-id=${sandboxId}`,
@@ -334,6 +354,7 @@ function waitForPodReady(coreApi, namespace, sandboxId) {
                 phase: pod?.status?.phase,
                 podIP: pod?.status?.podIP,
                 podName: pod?.metadata?.name,
+                reason: pendingConditionReason(pod),
             };
             if (pod && pod.status?.phase === "Running" && typeof pod.status.podIP === "string" && pod.metadata?.name) {
                 return ok({ podIP: pod.status.podIP, podName: pod.metadata.name });
@@ -341,7 +362,21 @@ function waitForPodReady(coreApi, namespace, sandboxId) {
             if (pod?.status?.phase === "Failed") {
                 return err(createFailed(undefined, new Error(`K8sSandbox ${sandboxId}: pod phase=Failed before becoming ready`)));
             }
-            await new Promise((r) => setTimeout(r, POD_POLL_INTERVAL_MS));
+            // One warning for one wait: the pod is still pending a minute in, and
+            // the condition reason says what it waits on. The timeout error
+            // below reports the five-minute give-up.
+            const waitedMs = now() - startedAt;
+            if (!warnedSlow && waitedMs >= POD_READY_SLOW_MS) {
+                warnedSlow = true;
+                logger.warn("sandbox pod is slow to reach Running", {
+                    sandboxId,
+                    namespace,
+                    waitedMs,
+                    phase: lastSnapshot.phase ?? null,
+                    conditionReason: lastSnapshot.reason ?? null,
+                });
+            }
+            await sleep(POD_POLL_INTERVAL_MS);
         }
         return err(createFailed(undefined, new Error(`K8sSandbox ${sandboxId}: pod did not reach Running within ` + `${POD_READY_TIMEOUT_MS}ms (last: ${JSON.stringify(lastSnapshot)})`)));
     })());
@@ -505,7 +540,7 @@ export function createK8sSandboxOps(config) {
                 // finishes) — the Job controller retries pod creation forever. Delete
                 // the Job on any startup failure so a failed create can't leak a
                 // zombie that floods k8s events indefinitely.
-                const ready = await waitForPodReady(coreApi, config.namespace, sandboxId);
+                const ready = await waitForPodReady(coreApi, config.namespace, sandboxId, { ...(config.logger ? { logger: config.logger } : {}) });
                 if (ready.isOk()) {
                     const ref = {
                         sandboxId,

package/dist/sandbox/liveness.d.ts

@@ -51,10 +51,12 @@ export declare function createEscalationPolicy(threshold?: number): {
  * caller resumes polling.
  */
 export declare function probeLiveness(isAlive: (ref: SandboxRef) => Promise<SandboxLiveness>, ref: SandboxRef): Promise<ProbeVerdict>;
+/** The closed set of reasons a synthetic failure carries. */
+export type SyntheticFailureReason = "sandbox-oom-killed" | "sandbox-dead";
 /**
  * An OOM-killed machine gets a distinguishable reason so the step failure
  * reads "exceeded its memory limit", not a mystery death.
  */
-export declare function syntheticFailureReason(liveness: Pick<SandboxLiveness, "oomKilled">): "sandbox-oom-killed" | "sandbox-dead";
+export declare function syntheticFailureReason(liveness: Pick<SandboxLiveness, "oomKilled">): SyntheticFailureReason;
 /** The synthetic-failure `ExecResult` for an exec whose machine died under it. */
 export declare function syntheticFailureResult(execId: string, reason: string): ExecResult;

package/dist/sandbox/types.d.ts

@@ -204,6 +204,22 @@ export declare const ProvenanceFrameSchema: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type ProvenanceFrame = z.infer<typeof ProvenanceFrameSchema>;
+/**
+ * What one exec cost the sandbox, as the kernel accounted it at reap time.
+ * Mirrors Go's `resourceUsage` (`images/sandbox-base/server/executor.go`):
+ * the peak resident set of the command and of every descendant it waited for,
+ * and the CPU that same tree burned.
+ *
+ * Every member is tolerant. A sandbox image that predates the frame sends no
+ * `usage` at all, an older or newer one can send a subset, and a malformed
+ * frame falls back to absent rather than failing the parse — telemetry never
+ * costs a caller its exec result.
+ */
+export declare const ExecUsageSchema: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+    peakMemoryBytes: z.ZodOptional<z.ZodNumber>;
+    cpuMillis: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>>>;
+export type ExecUsage = z.infer<typeof ExecUsageSchema>;
 /**
  * Final outcome of a single exec, returned by `awaitExec`. Mirrors the
  * sandbox-server completion payload plus a discriminant for synthetic
@@ -238,6 +254,10 @@ export declare const ExecResultSchema: z.ZodObject<{
             layers: z.ZodDefault<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
+    usage: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        peakMemoryBytes: z.ZodOptional<z.ZodNumber>;
+        cpuMillis: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type ExecResult = z.infer<typeof ExecResultSchema>;
 /**
@@ -320,6 +340,10 @@ export declare const PollResponseSchema: z.ZodObject<{
                 layers: z.ZodDefault<z.ZodArray<z.ZodString>>;
             }, z.core.$strip>>>;
         }, z.core.$strip>>;
+        usage: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+            peakMemoryBytes: z.ZodOptional<z.ZodNumber>;
+            cpuMillis: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type PollResponse = z.infer<typeof PollResponseSchema>;

package/dist/sandbox/types.js

@@ -67,6 +67,24 @@ export const ProvenanceFrameSchema = z.object({
      */
     deletes: z.array(ProvenanceFrameEntrySchema).default([]),
 });
+/**
+ * What one exec cost the sandbox, as the kernel accounted it at reap time.
+ * Mirrors Go's `resourceUsage` (`images/sandbox-base/server/executor.go`):
+ * the peak resident set of the command and of every descendant it waited for,
+ * and the CPU that same tree burned.
+ *
+ * Every member is tolerant. A sandbox image that predates the frame sends no
+ * `usage` at all, an older or newer one can send a subset, and a malformed
+ * frame falls back to absent rather than failing the parse — telemetry never
+ * costs a caller its exec result.
+ */
+export const ExecUsageSchema = z
+    .object({
+    peakMemoryBytes: z.number().nonnegative().optional(),
+    cpuMillis: z.number().nonnegative().optional(),
+})
+    .optional()
+    .catch(undefined);
 /**
  * Final outcome of a single exec, returned by `awaitExec`. Mirrors the
  * sandbox-server completion payload plus a discriminant for synthetic
@@ -104,6 +122,12 @@ export const ExecResultSchema = z.object({
      * the recv payload into the durable DBOS step output.
      */
     provenance: ProvenanceFrameSchema.optional(),
+    /**
+     * Kernel accounting of the exec, for the sandbox-sizing histograms. Absent
+     * from a synthetic watchdog failure, from a sandbox image that predates the
+     * frame, and from any exec whose command never spawned.
+     */
+    usage: ExecUsageSchema,
 });
 /**
  * Per-message envelope on the per-exec DBOS topic. Real callbacks carry

package/dist/tools/ad-hoc-router.d.ts

@@ -3,13 +3,29 @@ import { type AgentSession } from "../auth/types.js";
 import type { ResourcePolicy, ResourceSpec } from "../config/resource-limits.js";
 import type { Logger } from "../lib/logger.js";
 import { type ChatProvider } from "../providers/types.js";
+import type { CheckedPackage } from "./sandbox/list-available-packages.js";
 export declare const AD_HOC_ROUTER_AGENT_ID = "adhoc-router";
 export declare const AD_HOC_ROUTER_TIMEOUT_MS = 10000;
 export declare const AD_HOC_FALLBACK_AGENT_ID = "scientific-executor";
+/**
+ * A package entry that the step does not carry.
+ *
+ * - `unparsable` — the entry is not a query of the one grammar.
+ * - `absent` — the bound resolution answered that the pool holds no such
+ *   package, and it offered no other spelling.
+ */
+export interface DroppedPackage {
+    readonly entry: string;
+    readonly reason: "unparsable" | "absent";
+}
 export interface AdHocRoute {
     readonly agentId: string;
     readonly resources: ResourceSpec;
     readonly rationale: string;
+    /** The validated package entries of the step. Empty is a normal answer. */
+    readonly packages: readonly string[];
+    /** Every entry that the validation removed, with the reason for the caveat. */
+    readonly droppedPackages: readonly DroppedPackage[];
     readonly fallbackClass?: "timeout" | "provider_error" | "malformed" | "no_match" | "invalid_agent" | "invalid_resources";
 }
 export interface AdHocRouterDeps {
@@ -25,6 +41,13 @@ export interface AdHocRouterDeps {
      * provider advertises.
      */
     readonly timeoutMs?: number;
+    /**
+     * A targeted presence check of the names that the route emits. `null` means
+     * that the inventory could not answer at all, and every parsed entry then
+     * stays — an unreadable inventory says nothing about a package. Unbound,
+     * the entries reach the link pass as the model wrote them.
+     */
+    readonly resolvePackages?: (names: readonly string[]) => Promise<readonly CheckedPackage[] | null>;
 }
 export declare function defaultAdHocResources(policy?: ResourcePolicy): ResourceSpec;
 export declare function validAdHocResources(value: unknown, policy?: ResourcePolicy): ResourceSpec | null;

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

@@ -5,8 +5,9 @@ import { forSubAgent } from "../auth/types.js";
 import { DATA_PROFILE_ORIENTATION_MAX_CHARS, buildDataProfileOrientation } from "../app/data-profile-orientation.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { unwrapOrThrow } from "../lib/result.js";
-import { resourceEstimationSection } from "../prompts/planner.js";
+import { packagesSection, resourceEstimationSection } from "../prompts/planner.js";
 import { effectiveDeadlineMs } from "../providers/types.js";
+import { formatQuery, parseQuery } from "../sandbox/package-identity.js";
 import { loadDataProfileStatus } from "../state/index.js";
 export const AD_HOC_ROUTER_AGENT_ID = "adhoc-router";
 export const AD_HOC_ROUTER_TIMEOUT_MS = 10_000;
@@ -20,6 +21,7 @@ const routeSchema = z.object({
     agentId: z.string().optional(),
     resources: resourcesSchema.optional(),
     rationale: z.string().optional(),
+    packages: z.array(z.string()).optional(),
 });
 export function defaultAdHocResources(policy) {
     return policy ? { cpu: Math.min(4, policy.perStep.maxCpu), memoryGb: Math.min(8, policy.perStep.maxMemoryGb) } : { cpu: 4, memoryGb: 8 };
@@ -60,10 +62,90 @@ async function profileOrientation(pool, analysisId, logger) {
         return "The persisted data profile could not be loaded; route from the request alone.";
     }
 }
+/** The spelling that the pool holds for a missed entry, where the resolution offers one. */
+function suggestedSpelling(rows) {
+    for (const row of rows) {
+        if (!row.present && row.suggestion !== undefined)
+            return row.suggestion;
+    }
+    return undefined;
+}
+/**
+ * Validate the package entries of a route on their own axis: a bad entry costs
+ * that entry and nothing else, because the specialist and the resources are
+ * sound without it.
+ *
+ * A guess of a model reaches here, and no person reviewed it. Thus a name that
+ * the pool does not hold leaves the step with a caveat, where the same name in
+ * a plan step — which a person approved — refuses the launch instead.
+ */
+async function routePackages(raw, resolve, logger) {
+    const entries = Array.isArray(raw) ? raw : [];
+    const droppedPackages = [];
+    const kept = [];
+    const seen = new Set();
+    for (const element of entries) {
+        if (typeof element !== "string") {
+            droppedPackages.push({ entry: String(element), reason: "unparsable" });
+            continue;
+        }
+        const entry = element.trim();
+        const parsed = parseQuery(entry);
+        if (parsed.isErr()) {
+            droppedPackages.push({ entry, reason: "unparsable" });
+            continue;
+        }
+        // Two equal entries are one ask, and the link pass unions them anyway.
+        if (seen.has(entry))
+            continue;
+        seen.add(entry);
+        kept.push({ entry, query: parsed.value });
+    }
+    const asWritten = () => kept.map((candidate) => candidate.entry);
+    if (!resolve || kept.length === 0)
+        return { packages: asWritten(), droppedPackages };
+    let rows;
+    try {
+        rows = await resolve(asWritten());
+    }
+    catch (error) {
+        // A resolution that throws is the same condition as an inventory that
+        // reports itself unavailable: it says nothing about the packages.
+        logger.warn("ad hoc package resolution failed", { error: error instanceof Error ? error.message : String(error) });
+        rows = null;
+    }
+    if (rows === null)
+        return { packages: asWritten(), droppedPackages };
+    const packages = [];
+    const emitted = new Set();
+    for (const { entry, query } of kept) {
+        // One name that both tracks hold answers with one row per track, thus a
+        // present row anywhere in the answer keeps the entry as it was written.
+        // The link pass then refuses the bare form with the two prefixed ones.
+        const answer = rows.filter((row) => row.requested === entry);
+        const held = answer.length === 0 || answer.some((row) => row.present);
+        const suggestion = held ? undefined : suggestedSpelling(answer);
+        if (!held && suggestion === undefined) {
+            droppedPackages.push({ entry, reason: "absent" });
+            continue;
+        }
+        // The track and the version of the ask survive the rewrite: only the
+        // spelling missed, and the entry asked for that exact pin.
+        const resolved = suggestion === undefined ? entry : formatQuery({ ...query, spelling: suggestion });
+        // A rewrite can land on the spelling that another entry already carries,
+        // thus the answer dedupes as well as the input: `r:seurat` and
+        // `r:SEURAT` are one ask once both take the spelling that the pool holds.
+        if (emitted.has(resolved))
+            continue;
+        emitted.add(resolved);
+        packages.push(resolved);
+    }
+    return { packages, droppedPackages };
+}
 function routeTool() {
     return {
         submit_route: aiTool({
-            description: "Submit the single specialist and resource recommendation. This is the only valid response.",
+            description: "Submit the single specialist, the resource recommendation, and the packages of the step. This is the only valid response.",
             inputSchema: jsonSchema(z.toJSONSchema(routeSchema)),
         }),
     };
@@ -80,10 +162,12 @@ export async function routeAdHocRequest(deps, input) {
     try {
         const response = unwrapOrThrow(await deps.provider.chat({
             system: [
-                "Select exactly one specialist for a targeted one-step analysis and estimate its sandbox resources.",
+                "Select exactly one specialist for a targeted one-step analysis, estimate its sandbox resources, and name the packages that the step imports.",
                 "Choose only from the supplied catalog. Do not create a plan, reject the request, or select scientific-executor.",
                 resourceEstimationSection(deps.resourcePolicy),
                 resourceBounds(deps.resourcePolicy),
+                packagesSection(),
+                "You hold no package census. For a name that both ecosystems hold, the language of the specialist you select and the wording of the request decide the track.",
                 "Respond only by calling submit_route.",
             ].join("\n\n"),
             messages: [
@@ -128,6 +212,10 @@ export async function routeAdHocRequest(deps, input) {
         : failure
             ? `Deterministic fallback: ${failure}`
             : `Selected ${agentId}`;
-    logger.info("ad hoc route selected", { agentId, resources, rationale, failure });
-    return { agentId, resources, rationale, ...(failure ? { fallbackClass: failure } : {}) };
+    // The packages validate last and on their own axis: a package failure
+    // never becomes a `fallbackClass`, because that class describes the route
+    // as a whole and a step agent reads it as "the routing itself fell back".
+    const { packages, droppedPackages } = await routePackages(candidate.packages, deps.resolvePackages, logger);
+    logger.info("ad hoc route selected", { agentId, resources, rationale, failure, packages, droppedPackages });
+    return { agentId, resources, rationale, packages, droppedPackages, ...(failure ? { fallbackClass: failure } : {}) };
 }

package/dist/tools/bio/alphafold-prediction.d.ts

@@ -0,0 +1,19 @@
+/**
+ * alphafoldPrediction — the AlphaFold DB predicted 3-D structure of one
+ * UniProt accession.
+ *
+ * Returns model metadata, confidence, and artifact URLs only — never file
+ * contents. A predicted `.pdb` or `.cif` file holds megabytes of coordinates
+ * that give the model no benefit in a chat turn. A download of one belongs in
+ * the sandbox, where a step can fetch a URL that this tool returns.
+ */
+import { type AlphaFoldPrediction } from "../lib/alphafold-client.js";
+export type AlphaFoldPredictionOutput = {
+    readonly found: false;
+    readonly uniprotAccession: string;
+} | ({
+    readonly found: true;
+} & AlphaFoldPrediction);
+export declare const alphafoldPredictionTool: import("../define-tool.js").Tool<{
+    uniprotAccession: string;
+}, AlphaFoldPredictionOutput>;

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

@@ -0,0 +1,40 @@
+/**
+ * alphafoldPrediction — the AlphaFold DB predicted 3-D structure of one
+ * UniProt accession.
+ *
+ * Returns model metadata, confidence, and artifact URLs only — never file
+ * contents. A predicted `.pdb` or `.cif` file holds megabytes of coordinates
+ * that give the model no benefit in a chat turn. A download of one belongs in
+ * the sandbox, where a step can fetch a URL that this tool returns.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { fetchAlphaFoldPrediction } from "../lib/alphafold-client.js";
+export const alphafoldPredictionTool = defineTool({
+    id: "alphafold_prediction",
+    description: "AlphaFold DB — the predicted 3-D protein structure of EMBL-EBI and DeepMind, keyed by a UniProt accession ('P38398'). Predicted confidence " +
+        "(pLDDT), not experimental certainty: it tells apart a folded domain from a disordered loop, it does not replace a solved structure.\n" +
+        "`globalMetricValue` is the mean pLDDT over the whole chain, and each `fractionPlddt*` is the fraction of residues in one band: above 90 is " +
+        "very high, 70 to 90 is confident, 50 to 70 is low, and below 50 is very low or disordered. A LOW globalMetricValue is not a failed " +
+        "prediction — BRCA1 scores about 41 because BRCA1 is largely disordered, and AlphaFold reports that correctly. Both values describe the whole " +
+        "chain and neither locates a region: `plddtDocUrl` holds the per-residue pLDDT that does.\n" +
+        "Returns URLs only (`pdbUrl`, `cifUrl`, `paeImageUrl`, `plddtDocUrl` — the per-residue confidence, `paeDocUrl` — the predicted aligned error " +
+        "matrix, `amAnnotationsUrl` — AlphaMissense pathogenicity annotations, present for a HUMAN canonical accession only, thus absent on a " +
+        "non-human protein and on an isoform): fetch one from the sandbox to inspect the coordinates, the per-residue confidence, or the annotation " +
+        "table, do not expect the file contents here.\n" +
+        "found: false means AlphaFold holds no model for the accession (not every UniProt entry has one) — report it and continue, do not retry.",
+    inputSchema: z.object({
+        uniprotAccession: z.string().min(1).describe("A UniProt accession, for example 'P38398' (BRCA1) or 'P69905' (hemoglobin subunit alpha)."),
+    }),
+    describeCall: ({ uniprotAccession }) => uniprotAccession,
+    execute: async ({ uniprotAccession }) => {
+        // The client trims before it builds the URL, thus a miss echoes the same
+        // accession that the request carried and not the padded argument.
+        const accession = uniprotAccession.trim();
+        const prediction = await fetchAlphaFoldPrediction(accession);
+        if (!prediction)
+            return ok({ found: false, uniprotAccession: accession });
+        return ok({ found: true, ...prediction });
+    },
+});

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

@@ -20,8 +20,10 @@
  * sparse one and widen deliberately.
  */
 export * from "./search-gene.js";
+export * from "./search-protein.js";
 export * from "./lookup-annotation.js";
 export * from "./search-interactions.js";
+export * from "./alphafold-prediction.js";
 export * from "./pubmed.js";
 export * from "./chembl.js";
 export * from "./pubchem.js";

package/dist/tools/bio/index.js

@@ -21,9 +21,12 @@
  */
 // Identifier resolution
 export * from "./search-gene.js";
+export * from "./search-protein.js";
 // Functional annotation / networks
 export * from "./lookup-annotation.js";
 export * from "./search-interactions.js";
+// Structural biology
+export * from "./alphafold-prediction.js";
 // Literature
 export * from "./pubmed.js";
 // Cheminformatics

package/dist/tools/bio/search-protein.d.ts

@@ -0,0 +1,20 @@
+/**
+ * searchProtein — resolve a protein against UniProtKB.
+ *
+ * `search_gene` accepts a UniProt accession, but it answers with Ensembl gene
+ * records, thus nothing gave an agent the protein itself: the name, the length,
+ * the curated function, and where in the cell it acts. This tool answers that,
+ * and its accession is the key that the structural tools take.
+ */
+import { type UniProtProtein } from "../lib/uniprot-client.js";
+export interface SearchProteinOutput {
+    readonly proteins: UniProtProtein[];
+    /** True when UniProt held at least one row beyond `limit`. */
+    readonly hasMore: boolean;
+}
+export declare const searchProteinTool: import("../define-tool.js").Tool<{
+    query: string;
+    organismId: number | null;
+    reviewedOnly: boolean;
+    limit: number;
+}, SearchProteinOutput>;

package/dist/tools/bio/search-protein.js

@@ -0,0 +1,61 @@
+/**
+ * searchProtein — resolve a protein against UniProtKB.
+ *
+ * `search_gene` accepts a UniProt accession, but it answers with Ensembl gene
+ * records, thus nothing gave an agent the protein itself: the name, the length,
+ * the curated function, and where in the cell it acts. This tool answers that,
+ * and its accession is the key that the structural tools take.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { searchProteins } from "../lib/uniprot-client.js";
+/** Rows returned by default. An exact gene symbol resolves to one reviewed protein. */
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 50;
+export const searchProteinTool = defineTool({
+    id: "search_protein",
+    description: "UniProtKB — the curated protein knowledgebase of EMBL-EBI, SIB and PIR. Resolves a protein and answers with its accession, its UniProtKB ID " +
+        "('BRCA1_HUMAN'), its recommended name, its gene names, its sequence length, its curated FUNCTION summary, and its subcellular locations.\n" +
+        "ACCEPTED IDENTIFIERS: a HUGO gene symbol ('BRCA1'), matched exactly, or a UniProt accession ('P38398', 'A0A0B4J1Y9'). The two spaces overlap — " +
+        "'P2RY12' is both a real symbol and a valid accession shape — so an accession-shaped input searches BOTH, and either kind resolves. A protein " +
+        "NAME is not accepted; resolve the symbol first.\n" +
+        "This is the tool that produces a UniProt accession, which is the key that the structure tools take. Prefer it over search_gene when the " +
+        "question is about the PROTEIN — what it does, how long it is, where it acts — and search_gene when the question is about the gene locus, its " +
+        "coordinates or its Ensembl ID.\n" +
+        "`reviewedOnly` defaults to true, thus an answer holds Swiss-Prot entries only: manually curated, one entry per gene, and the right default for " +
+        "a human question. Set it false to reach TrEMBL as well, which is machine-annotated and holds many isoform-level rows per gene — needed for a " +
+        "protein that Swiss-Prot has not curated.\n" +
+        "`organismId` takes an NCBI Taxonomy ID and defaults to 9606 (human); pass 10090 for mouse, or null to search every organism. Both this and " +
+        "`reviewedOnly` narrow a SYMBOL match only — an accession is a unique key, so it resolves whatever its organism or review status.\n" +
+        "An empty `proteins` array is valid no-data (an unrecognized symbol, or one this organism has no entry for) — report it and continue, do not " +
+        "retry the same call. `hasMore` true means the answer was trimmed to `limit`.",
+    inputSchema: z.object({
+        query: z.string().min(1).describe("A gene symbol ('BRCA1') or a UniProt accession ('P38398')."),
+        organismId: z
+            .number()
+            .int()
+            .positive()
+            .nullable()
+            .default(9606)
+            .describe("NCBI Taxonomy ID (9606 = human, 10090 = mouse). Null searches every organism, which is how to reach a non-model species."),
+        reviewedOnly: z.boolean().default(true).describe("True (default) keeps Swiss-Prot entries only. False also returns machine-annotated TrEMBL entries."),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(MAX_LIMIT)
+            .default(DEFAULT_LIMIT)
+            .describe(`Max proteins returned (default ${DEFAULT_LIMIT}, max ${MAX_LIMIT}). An exact symbol under reviewedOnly resolves to one entry, so raise ` +
+            "this only for a reviewedOnly=false survey, where a gene carries many TrEMBL rows."),
+    }),
+    describeCall: ({ query }) => query,
+    execute: async ({ query, organismId, reviewedOnly, limit }) => {
+        const result = await searchProteins(query, {
+            ...(organismId === null ? {} : { organismId }),
+            reviewedOnly,
+            limit,
+        });
+        return ok(result);
+    },
+});

package/dist/tools/execute-analysis.d.ts

@@ -3,6 +3,7 @@
  * hoc analyses. Both modes launch the ordinary executeAnalysis workflow.
  */
 import type { Pool } from "pg";
+import type { EnvironmentStorePaths } from "../config/environment-stores.js";
 import type { ResourcePolicy } from "../config/resource-limits.js";
 import type { RunAuthorizer } from "../execution/run-authorizer.js";
 import type { RunLauncher } from "../execution/run-launcher.js";
@@ -13,7 +14,7 @@ import { type AnalysisPlan } from "../schemas/workflow-state.js";
 import type { ExecuteAnalysisInput, ExecuteAnalysisResult } from "../workflows/execute-analysis.js";
 import { type AdHocRoute } from "./ad-hoc-router.js";
 type ExecuteAnalysisWorkflow = (input: ExecuteAnalysisInput) => Promise<ExecuteAnalysisResult>;
-export interface ExecuteAnalysisToolDeps {
+export interface ExecuteAnalysisToolDeps extends Pick<EnvironmentStorePaths, "farmLockFile" | "imagePackagesFile" | "readPoolInventory"> {
     readonly pool: Pool;
     readonly executeAnalysisWorkflow: ExecuteAnalysisWorkflow;
     readonly runAuthorizer: RunAuthorizer;