@inflexa-ai/harness 0.32.0 → 0.33.0

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({

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

@@ -8,6 +8,7 @@ import type { RunAuthorizer } from "../execution/run-authorizer.js";
 import type { RunLauncher } from "../execution/run-launcher.js";
 import type { Logger } from "../lib/logger.js";
 import type { ChatProvider } from "../providers/types.js";
+import type { ExtendAnalysisFarm } from "../sandbox/types.js";
 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";
@@ -21,6 +22,12 @@ export interface ExecuteAnalysisToolDeps {
     readonly utilityProvider: ChatProvider;
     readonly utilityModel: string;
     readonly logger?: Logger;
+    /**
+     * The farm-extension seam of the embedder. When it is bound, the launch
+     * links the packages of the plan into the farm of the analysis before the
+     * run reserves anything. Without it, the link pass returns at once.
+     */
+    readonly extendAnalysisFarm?: ExtendAnalysisFarm;
 }
 export declare class PlanNotFoundError extends Error {
     constructor(planId: string);
@@ -32,6 +39,17 @@ export declare class PlanValidationError extends Error {
     readonly errors: string[];
     constructor(planId: string, errors: string[]);
 }
+/**
+ * A pool miss at the pre-launch link pass. The message names the missing
+ * packages and no remedy command — the remedy belongs to the embedder, and
+ * its wrapper appends it.
+ */
+export declare class PlanPackagesMissingError extends Error {
+    readonly missing: string[];
+    readonly collisions: string[];
+    readonly unavailable?: string | undefined;
+    constructor(missing: string[], collisions: string[], unavailable?: string | undefined);
+}
 export declare function buildAdHocPlan(request: string, route: AdHocRoute, createdAt?: string): AnalysisPlan;
 export declare function createExecuteAnalysisTool(deps: ExecuteAnalysisToolDeps): import("./define-tool.js").Tool<{
     mode: "plan" | "adhoc";