@inflexa-ai/harness 0.32.0 → 0.33.1

package/dist/sandbox/k8s-client.js

@@ -6,15 +6,17 @@
  * Storage is wired via the shared session PVC: a flat read-only `volumeMount`
  * of the analysis tree at `/{resourceId}` plus a nested read-write mount of the
  * step's artifact dir, with the lib/ref stores mounted read-only at `/mnt/libs`
- * / `/mnt/refs` when their PVCs are set. Container paths and lib-store env come
- * from the shared mount plan; the PVC `subPath`s are derived from the same
- * `resolveWorkspaceRoot` seam the harness pre-creates the step tree under, so
- * both sides address one directory by construction.
+ * / `/mnt/refs` when their PVCs are set. The farm of the analysis mounts as a
+ * read-only `subPath` of the libs PVC, after the store mount. Container paths
+ * and lib-store env come from the shared mount plan; the PVC `subPath`s are
+ * derived from the same `resolveWorkspaceRoot` seam the harness pre-creates
+ * the step tree under, so both sides address one directory by construction.
  */
-import { relative as relativePath, sep } from "node:path";
+import { join, relative as relativePath, sep } from "node:path";
 import { BatchV1Api, CoreV1Api, KubeConfig, } from "@kubernetes/client-node";
 import { ResultAsync, err, ok } from "neverthrow";
 import { trySandbox } from "./sandbox-error.js";
+import { readFarmLock, resolveFarmSource } from "./farm.js";
 import { buildMountPlan, buildSessionSubPaths } from "./mount-plan.js";
 import { threadLimitEnv } from "./thread-env.js";
 import { createNoopLogger } from "../lib/console-logger.js";
@@ -108,11 +110,30 @@ function workspaceSubPathFor(config, analysisId) {
     }
     return posix;
 }
-function buildJobSpec(meta, config, identity) {
+/**
+ * A farm location on K8s is a `subPath` into the libs PVC. A subPath must be
+ * a relative path with no `..` — an absolute or escaping value would mount a
+ * directory nothing resolved. `createSandbox` runs inside a DBOS workflow
+ * body, where a throw is the durable failure signal.
+ */
+function pvcSubPath(value, what) {
+    if (value.length === 0 || value.startsWith("/") || value.split("/").includes("..")) {
+        throw new Error(`k8s sandbox: ${what} must be a non-empty PVC-relative path without '..' (got ${JSON.stringify(value)})`);
+    }
+    return value;
+}
+function buildJobSpec(meta, config, identity, farm, libsMounted) {
     const { sandboxId } = identity;
+    // The lock gate of the package-store spec: `farmPath` is PVC-relative,
+    // thus this host can prove the lock only through `libStorePvcRoot`. The
+    // caller runs that proof and hands the verdict in `libsMounted`. Without
+    // the root, the proof duty stays whole on the farm resolver — see
+    // {@link ResolveAnalysisFarm}.
     const plan = buildMountPlan(meta, {
-        libs: !!config.libStorePvc,
+        libs: libsMounted,
         refs: !!config.refStorePvc,
+        toolchainSource: config.toolchainSource,
+        cache: libsMounted && farm?.cachePath !== undefined,
     });
     const transport = config.transport ?? "poll";
     const spec = meta.resources;
@@ -168,15 +189,36 @@ function buildJobSpec(meta, config, identity) {
         }
     }
     if (config.libStorePvc && plan.libsPath) {
+        const cacheSubPath = farm?.cachePath !== undefined && plan.cachePath ? pvcSubPath(farm.cachePath, "the farm cache") : undefined;
         volumes.push({
             name: LIBS_VOLUME_NAME,
-            persistentVolumeClaim: { claimName: config.libStorePvc, readOnly: true },
+            // Volume-level readOnly only when nothing writes through the claim:
+            // the cache mount needs write access, and the per-mount flags keep
+            // the store and the farm read-only either way.
+            persistentVolumeClaim: { claimName: config.libStorePvc, ...(cacheSubPath === undefined ? { readOnly: true } : {}) },
         });
         volumeMounts.push({
             name: LIBS_VOLUME_NAME,
             mountPath: plan.libsPath,
             readOnly: true,
         });
+        // The farm mount comes after the store mount, thus the nesting is stable.
+        if (farm && plan.farmPath) {
+            volumeMounts.push({
+                name: LIBS_VOLUME_NAME,
+                mountPath: plan.farmPath,
+                subPath: pvcSubPath(farm.farmPath, "the farm"),
+                readOnly: true,
+            });
+        }
+        if (cacheSubPath !== undefined && plan.cachePath) {
+            volumeMounts.push({
+                name: LIBS_VOLUME_NAME,
+                mountPath: plan.cachePath,
+                subPath: cacheSubPath,
+                readOnly: false,
+            });
+        }
     }
     if (config.refStorePvc && plan.refsPath) {
         volumes.push({
@@ -410,7 +452,34 @@ export function createK8sSandboxOps(config) {
         createSandbox(meta, identity) {
             return new ResultAsync((async () => {
                 const { sandboxId } = identity;
-                const job = buildJobSpec(meta, config, identity);
+                // Farm resolution comes before any cluster work: a resolver
+                // refusal and a resolver throw refuse the whole call, and no
+                // Job is made.
+                let farm;
+                if (config.libStorePvc) {
+                    const resolved = await resolveFarmSource(config.farmSource, meta.analysisId, "k8s.createSandbox");
+                    if (resolved.isErr())
+                        return err(resolved.error);
+                    farm = resolved.value;
+                }
+                // The `inflexa.lock` gate, for a host that mounts the libs
+                // volume itself. The resolver owes the proof either way,
+                // but a farm half-written between the resolution and this
+                // create still mounts without a second look. A gate failure
+                // degrades exactly as the Docker backend does: no store
+                // mount, the Job is still made, and the sandbox reports the
+                // store as unavailable.
+                let libsMounted = !!config.libStorePvc;
+                if (config.libStorePvc && config.libStorePvcRoot && farm) {
+                    const lock = readFarmLock(join(config.libStorePvcRoot, farm.farmPath));
+                    libsMounted = lock.isOk();
+                    if (lock.isErr()) {
+                        (config.logger ?? createNoopLogger())
+                            .named("k8s-client")
+                            .warn("the farm of the analysis has no usable inflexa.lock at sandbox creation — mounting no package store (sandbox degrades to available:false)", { libStorePvc: config.libStorePvc, farmPath: farm.farmPath, lockError: lock.error.type, sandboxId });
+                    }
+                }
+                const job = buildJobSpec(meta, config, identity, farm, libsMounted);
                 const adopted = await createOrAdoptJob(batchApi, coreApi, config.namespace, sandboxId, meta.childWorkflowId, job);
                 if (adopted.isErr())
                     return err(adopted.error);

package/dist/sandbox/mount-plan.d.ts

@@ -27,6 +27,7 @@
  * resolved root directly, K8s addresses it as a `subPath` into the session PVC
  * (see {@link buildSessionSubPaths}).
  */
+import type { ToolchainSource } from "./types.js";
 export declare const STEP_SUBDIRS: readonly ["output", "scripts", "figures", "logs", "notebooks"];
 /**
  * Container mountpoints of the two read-only stores. Exported because they are
@@ -35,6 +36,15 @@ export declare const STEP_SUBDIRS: readonly ["output", "scripts", "figures", "lo
  */
 export declare const LIBS_CONTAINER_PATH = "/mnt/libs";
 export declare const REFS_CONTAINER_PATH = "/mnt/refs";
+/** Container path of the per-analysis read-write cache, when a farm resolution carries a cache location. */
+export declare const FARM_CACHE_CONTAINER_PATH = "/mnt/libs/cache";
+/**
+ * Container path of the mounted farm, keyed on the declared toolchain. With
+ * `"image"` the farm mounts at `/mnt/libs/farm`. With `"store"` (or absent)
+ * it stays `/mnt/libs/current`, because the baked resolvers of the old
+ * images name that path.
+ */
+export declare function farmContainerPath(toolchainSource: ToolchainSource | undefined): string;
 export interface MountPlanCoords {
     analysisId: string;
     runId: string;
@@ -55,10 +65,18 @@ export interface MountPlanCoords {
     writableTail?: string;
 }
 export interface MountPlanStores {
-    /** Lib store is mounted at `/mnt/libs` and its env is emitted. */
+    /** Lib store is mounted at `/mnt/libs`, with the farm nested inside it, and its env is emitted. */
     libs: boolean;
     /** Ref store is mounted at `/mnt/refs`. */
     refs: boolean;
+    /**
+     * The declared toolchain owner. Keys the farm container path and the
+     * resolver env. Absent means `"store"`: the legacy environment,
+     * byte-identical to the one before the field existed.
+     */
+    toolchainSource?: ToolchainSource;
+    /** The farm resolution carries a cache location, mounted read-write at `/mnt/libs/cache`. */
+    cache?: boolean;
 }
 export interface MountPlan {
     /** Flat read-only mount of the whole analysis tree. */
@@ -75,6 +93,10 @@ export interface MountPlan {
     workingDir: string;
     /** Container path of the lib store, present only when `libs`. */
     libsPath?: string;
+    /** Container path of the farm of the analysis, present only when `libs`. Keyed on the toolchain source. */
+    farmPath?: string;
+    /** Container path of the read-write cache, present only when `libs` and `cache`. */
+    cachePath?: string;
     /** Container path of the ref store, present only when `refs`. */
     refsPath?: string;
     /** Pre-created subdirectories under the writable mount. Empty when read-only

package/dist/sandbox/mount-plan.js

@@ -36,6 +36,17 @@ export const STEP_SUBDIRS = ["output", "scripts", "figures", "logs", "notebooks"
  */
 export const LIBS_CONTAINER_PATH = "/mnt/libs";
 export const REFS_CONTAINER_PATH = "/mnt/refs";
+/** Container path of the per-analysis read-write cache, when a farm resolution carries a cache location. */
+export const FARM_CACHE_CONTAINER_PATH = "/mnt/libs/cache";
+/**
+ * Container path of the mounted farm, keyed on the declared toolchain. With
+ * `"image"` the farm mounts at `/mnt/libs/farm`. With `"store"` (or absent)
+ * it stays `/mnt/libs/current`, because the baked resolvers of the old
+ * images name that path.
+ */
+export function farmContainerPath(toolchainSource) {
+    return toolchainSource === "image" ? `${LIBS_CONTAINER_PATH}/farm` : `${LIBS_CONTAINER_PATH}/current`;
+}
 /**
  * The step tail beneath an analysis's workspace root, in both container and
  * PVC-relative space. The harness owns this layout (workspace-layout spec).
@@ -94,14 +105,37 @@ export function buildSessionSubPaths(coords, workspaceSubPath) {
     };
 }
 /**
- * Lib-store package-discovery env. PYTHONPATH is intentionally omitted —
- * system Python resolves via a `.pth` file in the lib store.
+ * Lib-store package-discovery env, keyed on the declared toolchain.
+ * PYTHONPATH is intentionally omitted — system Python resolves through a
+ * `.pth` file in the lib store.
+ *
+ * With `"store"` (or absent) the env is byte-identical to the legacy one:
+ * the conda `bin` under `/mnt/libs/current`, thus an old embedder keeps its
+ * exact environment. With `"image"` the image owns the toolchain: `PATH`
+ * holds `/opt/conda/bin` before the farm `python/bin` at the end, thus a
+ * farm script never shadows an image tool. The cache env points into the
+ * read-write cache mount only when it is present — the entrypoint fallback
+ * covers the caches otherwise.
  */
-function libStoreEnv() {
+function libStoreEnv(toolchainSource, cache) {
+    if (toolchainSource !== "image") {
+        return {
+            R_LIBS_SITE: "/mnt/libs/current/r/github:/mnt/libs/current/r/bioconductor:/mnt/libs/current/r/cran",
+            NODE_PATH: "/mnt/libs/current/node/node_modules",
+            PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/mnt/libs/current/conda/bin",
+        };
+    }
+    const farm = farmContainerPath(toolchainSource);
     return {
-        R_LIBS_SITE: "/mnt/libs/current/r/github:/mnt/libs/current/r/bioconductor:/mnt/libs/current/r/cran",
-        NODE_PATH: "/mnt/libs/current/node/node_modules",
-        PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/mnt/libs/current/conda/bin",
+        R_LIBS_SITE: `${farm}/r/github:${farm}/r/bioconductor:${farm}/r/cran`,
+        NODE_PATH: "/opt/node/node_modules",
+        PATH: `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/opt/conda/bin:${farm}/python/bin`,
+        ...(cache
+            ? {
+                NUMBA_CACHE_DIR: `${FARM_CACHE_CONTAINER_PATH}/numba-cache`,
+                MPLCONFIGDIR: `${FARM_CACHE_CONTAINER_PATH}/matplotlib_config`,
+            }
+            : {}),
     };
 }
 export function buildMountPlan(coords, stores) {
@@ -112,16 +146,19 @@ export function buildMountPlan(coords, stores) {
     const readonlyTreePath = `/${analysisId}`;
     const write = sandboxWriteTail(coords);
     const writableStepPath = write === undefined ? undefined : `${readonlyTreePath}/${write.tail}`;
+    const cache = stores.libs && stores.cache === true;
     return {
         readonlyTreePath,
         writableStepPath,
         workingDir: writableStepPath ?? readonlyTreePath,
         libsPath: stores.libs ? LIBS_CONTAINER_PATH : undefined,
+        farmPath: stores.libs ? farmContainerPath(stores.toolchainSource) : undefined,
+        cachePath: cache ? FARM_CACHE_CONTAINER_PATH : undefined,
         refsPath: stores.refs ? REFS_CONTAINER_PATH : undefined,
         stepSubdirs: write?.subdirs ?? [],
         env: {
             PROVENANCE_WATCH_DIRS: readonlyTreePath,
-            ...(stores.libs ? libStoreEnv() : {}),
+            ...(stores.libs ? libStoreEnv(stores.toolchainSource, cache) : {}),
         },
     };
 }

package/dist/sandbox/sandbox-error.d.ts

@@ -79,6 +79,18 @@ export type SandboxError = {
     readonly sandboxId?: string;
     readonly status?: number;
     readonly cause: unknown;
+} | {
+    /**
+     * The farm source refused the analysis: the resolver returned
+     * `unavailable`, or it threw. `reason` carries the text of the
+     * embedder verbatim, thus the surface can show why the farm is
+     * not usable yet.
+     */
+    readonly type: "farm_unavailable";
+    readonly op: string;
+    readonly analysisId: string;
+    readonly reason: string;
+    readonly cause?: unknown;
 };
 /**
  * The HTTP/driver status a backend SDK error carries. dockerode exposes it on

package/dist/sandbox/sandbox-error.js

@@ -66,6 +66,8 @@ export function describeSandboxError(e) {
             return `sandbox teardown failed (${e.op}${e.sandboxId ? `: ${e.sandboxId}` : ""})`;
         case "liveness_failed":
             return `sandbox liveness probe failed (${e.op}${e.sandboxId ? `: ${e.sandboxId}` : ""})`;
+        case "farm_unavailable":
+            return `farm unavailable (${e.op}: ${e.analysisId}) — ${e.reason}`;
     }
 }
 /**

package/dist/sandbox/types.d.ts

@@ -30,6 +30,124 @@ export declare const SandboxTransportSchema: z.ZodEnum<{
     callback: "callback";
 }>;
 export type SandboxTransport = z.infer<typeof SandboxTransportSchema>;
+/**
+ * The declared owner of the sandbox toolchain. `"image"` states that the
+ * image owns the interpreters, conda, and Node. `"store"` states that the
+ * mounted store owns them. An absent config field means `"store"`, thus an
+ * old embedder keeps its environment and its prompt prefix. The harness keys
+ * the resolver env and the orient-core prompt text on this declared value
+ * only, and it never infers its host.
+ */
+export type ToolchainSource = "image" | "store";
+/**
+ * A resolved farm. `farmPath` is a host directory for the Docker backend,
+ * and a PVC-relative path for the K8s backend. `cachePath` is the optional
+ * per-analysis read-write cache. When it is present, the backend mounts it
+ * at `/mnt/libs/cache`.
+ */
+export interface FarmLocation {
+    readonly farmPath: string;
+    readonly cachePath?: string;
+}
+/** The answer of a farm resolver: a usable farm, or a refusal that carries the reason of the embedder. */
+export type FarmResolution = {
+    readonly kind: "available";
+    readonly location: FarmLocation;
+} | {
+    readonly kind: "unavailable";
+    readonly reason: string;
+};
+/**
+ * Resolve the farm of one analysis. A backend calls this at each
+ * `createSandbox`, thus a new farm reaches the next sandbox with no restart.
+ *
+ * The resolver carries the mount gate when the backend cannot. On a
+ * volume-backed farm (K8s) the host cannot stat `farmPath`, thus the
+ * resolver MUST answer `unavailable` when the `inflexa.lock` of the farm
+ * does not parse. A backend with a host-readable path (Docker) proves the
+ * lock itself, after the resolution.
+ */
+export type ResolveAnalysisFarm = (analysisId: string) => Promise<FarmResolution>;
+/**
+ * Where the farm of an analysis comes from. A required field of each sandbox
+ * backend config — the harness never invents a farm location, and it reads
+ * no store-root `current` pointer. `fixed` names one farm for every
+ * analysis. `per-analysis` supplies a resolver.
+ */
+export type FarmSource = {
+    readonly kind: "fixed";
+    readonly location: FarmLocation;
+} | {
+    readonly kind: "per-analysis";
+    readonly resolve: ResolveAnalysisFarm;
+};
+/**
+ * One package ask of the farm-extension seam. `version` pins one exact
+ * version. `ecosystem` qualifies a name that both tracks can hold. Without
+ * it, a name that both tracks hold comes back as a `collision` outcome.
+ */
+export interface PackageRequest {
+    readonly name: string;
+    readonly version?: string;
+    readonly ecosystem?: "python" | "r";
+}
+/**
+ * One outcome per request, index-aligned with the request array.
+ *
+ * `name` echoes the REQUESTED spelling verbatim, never a normalized form. A
+ * caller quotes it into a remedy (`inflexa store add <name>`), and an R name
+ * is case-sensitive with dots, thus a normalized echo would name a package
+ * that no repository holds.
+ *
+ * - `linked` — the pool held the package, and this call linked it.
+ * - `present` — the farm linked it already.
+ * - `absent` — the pool does not hold it. `acquisitionPossible` states that
+ *   the host can acquire that ecosystem, or that it cannot. `detail`, when
+ *   the realization gives one, classifies the miss in host terms — in
+ *   flight, failed with a recorded reason, or never requested — and the
+ *   launch refusal renders it beside the name.
+ * - `collision` — the request resolves to two store directories: two
+ *   versions of one distribution, or one name that both tracks hold. The
+ *   outcome is terminal for the request. `detail`, when the realization
+ *   gives one, names the two pins and the packages that need each side —
+ *   without it, a caller must guess which package pulls each pin, and a
+ *   wrong guess sends it into store surgery.
+ * - `unavailable` — the link pass itself could not answer: an unreadable
+ *   dependency graph, a locked farm. The reason says why. It says NOTHING
+ *   about the presence of the package, and it must never render as an
+ *   absence — a false absence sends a caller chasing packages the pool
+ *   holds.
+ */
+export type PackageRequestOutcome = {
+    readonly kind: "linked";
+    readonly name: string;
+    readonly version: string;
+} | {
+    readonly kind: "present";
+    readonly name: string;
+    readonly version: string;
+} | {
+    readonly kind: "absent";
+    readonly name: string;
+    readonly acquisitionPossible: boolean;
+    readonly detail?: string;
+} | {
+    readonly kind: "collision";
+    readonly name: string;
+    readonly storeDirs: readonly [string, string];
+    readonly detail?: string;
+} | {
+    readonly kind: "unavailable";
+    readonly name: string;
+    readonly reason: string;
+};
+/**
+ * The farm-extension seam. The realization of the embedder links host-staged
+ * packages into the farm of the analysis. It never installs, downloads, or
+ * acquires. A link is live in a sandbox that already runs, because the farm
+ * rides a bind mount.
+ */
+export type ExtendAnalysisFarm = (analysisId: string, requests: readonly PackageRequest[]) => Promise<readonly PackageRequestOutcome[]>;
 /**
  * Per-sandbox-machine liveness verdict. `oomKilled` is meaningful only when
  * `alive` is false: true when the backend reports the machine was killed for

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

@@ -17,6 +17,7 @@ export declare const PlanStepSchema: z.ZodObject<{
     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>>>;
     depends_on: z.ZodArray<z.ZodString>;
     resources: z.ZodNonOptional<z.ZodOptional<z.ZodObject<{
         cpu: z.ZodNumber;
@@ -49,6 +50,7 @@ export declare const PlannerPlanSchema: z.ZodObject<{
         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>>>;
         depends_on: z.ZodArray<z.ZodString>;
         resources: z.ZodNonOptional<z.ZodOptional<z.ZodObject<{
             cpu: z.ZodNumber;
@@ -90,6 +92,7 @@ export declare const PlanningAgentOutputSchema: z.ZodObject<{
             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>>>;
             depends_on: z.ZodArray<z.ZodString>;
             resources: z.ZodNonOptional<z.ZodOptional<z.ZodObject<{
                 cpu: z.ZodNumber;

package/dist/schemas/plan-schemas.js

@@ -17,7 +17,7 @@ export const PlanStepSchema = AnalysisStepSchema.omit({
     error: true,
     maxSteps: true,
 })
-    .required({ agent: true, resources: true })
+    .required({ agent: true, resources: true, packages: true })
     .extend({
     agent: z.enum(plannableAgentIds).describe("Sandbox agent ID, routed by the step's primary data object. Must be one of the available agents."),
 });

package/dist/schemas/validate-plan.js

@@ -109,7 +109,26 @@ export function validatePlan(plan, options) {
                 `step-directory convention; "${SYNTHESIS_STEP_ID}" is the run-level synthesis phase)`);
         }
     }
-    // 6. Step-id path safety. The id becomes the `runs/{runId}/{stepId}` directory
+    // 6. Package entries are requirements, never locations. A path, a URL, or
+    //    a store directory in a plan would publish an installer detail as an
+    //    interface — the link pass resolves names against the pool. An absent
+    //    array passes, because stored plans from before the field carry none.
+    //    The specifier check exists because the link pass splits on `==` only:
+    //    an unrefused `numpy>=1.26` becomes a package NAME, and the pool then
+    //    refuses a package it holds.
+    for (const step of plan.steps) {
+        for (const entry of step.packages ?? []) {
+            if (/^[.~]|[/\\]|:\/\//.test(entry)) {
+                errors.push(`Step "${step.id}" names a package location "${entry}" — name each package as a requirement ` +
+                    `(a bare name, or name==version), never a path, a URL, or a store directory`);
+            }
+            else if (/[<>!~]/.test(entry) || (entry.includes("=") && !entry.includes("=="))) {
+                errors.push(`Step "${step.id}" pins "${entry}" with a specifier the link pass cannot honor — ` +
+                    `use a bare name, or name==version with one exact version`);
+            }
+        }
+    }
+    // 7. Step-id path safety. The id becomes the `runs/{runId}/{stepId}` directory
     //    segment and a `/{analysisId}/…` container mount path; an unsafe segment
     //    (a slash, or `.`/`..`) could traverse or widen the mount. The sandbox
     //    mount boundary also rejects these (assertSafeId), but catching it here

package/dist/schemas/workflow-state.d.ts

@@ -21,6 +21,7 @@ export declare const AnalysisStepSchema: z.ZodObject<{
     constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
     acceptance_criteria: z.ZodArray<z.ZodString>;
     caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
     depends_on: z.ZodArray<z.ZodString>;
     status: z.ZodDefault<z.ZodEnum<{
         pending: "pending";
@@ -57,6 +58,7 @@ export declare const AnalysisPlanSchema: z.ZodObject<{
         constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
         acceptance_criteria: z.ZodArray<z.ZodString>;
         caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
         depends_on: z.ZodArray<z.ZodString>;
         status: z.ZodDefault<z.ZodEnum<{
             pending: "pending";
@@ -128,6 +130,7 @@ export declare const ContentBlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
             acceptance_criteria: z.ZodArray<z.ZodString>;
             caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
             depends_on: z.ZodArray<z.ZodString>;
             status: z.ZodDefault<z.ZodEnum<{
                 pending: "pending";
@@ -247,6 +250,7 @@ export declare const SuspensionPayloadSchema: z.ZodObject<{
                 constraints: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 acceptance_criteria: z.ZodArray<z.ZodString>;
                 caveats: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 depends_on: z.ZodArray<z.ZodString>;
                 status: z.ZodDefault<z.ZodEnum<{
                     pending: "pending";

package/dist/schemas/workflow-state.js

@@ -24,6 +24,16 @@ export const AnalysisStepSchema = z.object({
     constraints: z.array(z.string()).optional().describe("Requirements the sandbox agent must follow exactly — not suggestions."),
     acceptance_criteria: z.array(z.string()).describe("What the result must satisfy for the step to count as successful."),
     caveats: z.array(z.string()).optional().describe("Pitfalls the sandbox agent should watch for."),
+    // Optional on the persistence schema so historical plans (pre-packages)
+    // still parse on the read side. `PlanStepSchema` re-requires it for
+    // planner output. The briefing withholds it from the rendered task — the
+    // pre-launch link pass consumes it, and a step agent must not re-litigate it.
+    packages: z
+        .array(z.string())
+        .optional()
+        .describe('The packages this step imports, each 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. An empty array means the step needs nothing beyond the baked toolchain. " +
+        "The set is not a promise of completeness — the execution agent can still link a missing package."),
     depends_on: z
         .array(z.string())
         .describe("IDs of steps in this plan that must complete before this one runs. Empty when the step has no prerequisites. The graph must be acyclic."),

package/dist/tasks/data-profile.d.ts

@@ -20,8 +20,10 @@
 import type { Pool } from "pg";
 import { type AuthContext, type RunSession } from "../auth/types.js";
 import type { EnvironmentStorePaths } from "../config/environment-stores.js";
+import type { ExtendAnalysisFarm } from "../sandbox/types.js";
 import type { RunAuthorization, RunAuthorizer } from "../execution/run-authorizer.js";
 import type { StagedInput } from "../execution/staged-input.js";
+import type { SandboxAgentDeps } from "../agents/sandbox/shared.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
 import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
@@ -65,6 +67,13 @@ export interface DataProfileDeps extends EnvironmentStorePaths {
      * the pod then carries the harness's own labels only.
      */
     readonly resolvePodLabels?: (session: RunSession) => Promise<Record<string, string>>;
+    /**
+     * The farm-extension seam of the embedder. Bound, it rides into the
+     * profiler agent deps, and the substrate attaches `link_packages`. Thus
+     * the profiler links a reader by need before the first plan exists.
+     * Unbound keeps the current shape: no link tool, and no error.
+     */
+    readonly extendAnalysisFarm?: ExtendAnalysisFarm;
 }
 /**
  * Workflow input. JSON-serialisable — DBOS persists it as the workflow's
@@ -125,6 +134,12 @@ export declare function buildAbsorbedResult(prior: DataProfileResult, resolution
  * Register the data-profile workflow with DBOS. Returns the registered
  * callable so `triggerDataProfile` can dispatch via `DBOS.startWorkflow`.
  */
+/**
+ * Project the workflow deps onto the profiler agent bag. The farm-extension
+ * seam rides only when the embedder bound one, and the substrate then gates
+ * `link_packages` on its presence (the data-profile-init spec).
+ */
+export declare function profilerSandboxAgentDeps(deps: DataProfileDeps, step: SandboxAgentDeps["step"]): SandboxAgentDeps;
 export declare function registerDataProfileWorkflow(deps: DataProfileDeps): (input: DataProfileWorkflowInput) => Promise<void>;
 /**
  * Body extracted so tests can drive it without registering a workflow.

package/dist/tasks/data-profile.js

@@ -247,6 +247,28 @@ function logProfileMonitoring(logger, args) {
  * Register the data-profile workflow with DBOS. Returns the registered
  * callable so `triggerDataProfile` can dispatch via `DBOS.startWorkflow`.
  */
+/**
+ * Project the workflow deps onto the profiler agent bag. The farm-extension
+ * seam rides only when the embedder bound one, and the substrate then gates
+ * `link_packages` on its presence (the data-profile-init spec).
+ */
+export function profilerSandboxAgentDeps(deps, step) {
+    return {
+        provider: deps.provider,
+        pool: deps.pool,
+        sandboxClient: deps.sandboxClient,
+        workspaceFs: deps.workspaceFs,
+        embedding: deps.embedding,
+        model: deps.model,
+        skillsDir: deps.skillsDir,
+        ...(deps.farmLockFile ? { farmLockFile: deps.farmLockFile } : {}),
+        ...(deps.imagePackagesFile ? { imagePackagesFile: deps.imagePackagesFile } : {}),
+        ...(deps.refStorePath ? { refStorePath: deps.refStorePath } : {}),
+        ...(deps.extendAnalysisFarm ? { extendAnalysisFarm: deps.extendAnalysisFarm } : {}),
+        bioKeys: deps.bioKeys,
+        step,
+    };
+}
 export function registerDataProfileWorkflow(deps) {
     return DBOS.registerWorkflow((input) => runDataProfileBody(input, deps), { name: "data-profile" });
 }
@@ -454,32 +476,20 @@ export async function runDataProfileBody(input, deps) {
                         `description needs content the scan did not capture, then call \`submit_profile\` once.`,
                     ]),
             ].join("\n");
-            const sandboxAgentDeps = {
-                provider: deps.provider,
-                pool: deps.pool,
-                sandboxClient: deps.sandboxClient,
-                workspaceFs: deps.workspaceFs,
-                embedding: deps.embedding,
-                model: deps.model,
-                skillsDir: deps.skillsDir,
-                ...(deps.packagesFile ? { packagesFile: deps.packagesFile } : {}),
-                ...(deps.refStorePath ? { refStorePath: deps.refStorePath } : {}),
-                bioKeys: deps.bioKeys,
-                step: {
-                    sandbox,
-                    workspaceRoot,
-                    analysisId,
-                    runId: DATA_PROFILE_RUN_LITERAL,
-                    stepId: DATA_PROFILE_STEP_LITERAL,
-                    workflowId,
-                    // The profiler writes Python scripts and intermediate artifacts under
-                    // the synthetic step path; the post-agent `rm -rf runs/data-profile/`
-                    // cleanup wipes them.
-                    allowedWritePrefix: profileWritePrefix,
-                    nextFunctionId,
-                    deadlineMs: () => deadlineAbs,
-                },
-            };
+            const sandboxAgentDeps = profilerSandboxAgentDeps(deps, {
+                sandbox,
+                workspaceRoot,
+                analysisId,
+                runId: DATA_PROFILE_RUN_LITERAL,
+                stepId: DATA_PROFILE_STEP_LITERAL,
+                workflowId,
+                // The profiler writes Python scripts and intermediate artifacts under
+                // the synthetic step path; the post-agent `rm -rf runs/data-profile/`
+                // cleanup wipes them.
+                allowedWritePrefix: profileWritePrefix,
+                nextFunctionId,
+                deadlineMs: () => deadlineAbs,
+            });
             let accepted = null;
             let rounds = 0;
             const submitProfileTool = defineTool({