@inflexa-ai/harness 0.32.0 → 0.33.1

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

package/dist/tools/execute-analysis.js

@@ -54,6 +54,90 @@ export class PlanValidationError extends Error {
 function isDedupCollision(err) {
     return err instanceof RunDedupCollisionError || (err instanceof Error && err.name === "RunDedupCollisionError");
 }
+/**
+ * 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 class PlanPackagesMissingError extends Error {
+    missing;
+    collisions;
+    unavailable;
+    constructor(missing, collisions, unavailable) {
+        const parts = [
+            // The store-level reason FIRST, because it invalidates the rest: with an
+            // unreadable graph, no per-package claim below it is trustworthy.
+            unavailable !== undefined
+                ? `the store cannot answer (${unavailable}) — this says nothing about the packages themselves, so do not re-request them`
+                : null,
+            missing.length > 0 ? `the pool does not hold: ${missing.join(", ")}` : null,
+            collisions.length > 0 ? `a collision refused: ${collisions.join(", ")}` : null,
+        ].filter((p) => p !== null);
+        super(`The packages of this plan cannot link — ${parts.join("; ")}`);
+        this.missing = missing;
+        this.collisions = collisions;
+        this.unavailable = unavailable;
+        this.name = "PlanPackagesMissingError";
+    }
+}
+/** One plan package entry, in requirement form: a bare name, or a name with one exact version. */
+function parseRequirement(entry) {
+    const split = entry.indexOf("==");
+    if (split < 0)
+        return { name: entry.trim() };
+    return { name: entry.slice(0, split).trim(), version: entry.slice(split + 2).trim() };
+}
+/**
+ * Link the packages of the plan into the farm of the analysis, before the
+ * run reserves anything. The linked set is the union of the packages of each
+ * step. A pool miss and a collision refuse the launch with the names. Without
+ * a bound seam, the pass returns at once.
+ */
+async function linkPlanPackages(extendAnalysisFarm, analysisId, plan) {
+    if (!extendAnalysisFarm)
+        return;
+    const union = new Map();
+    for (const step of plan.steps) {
+        for (const entry of step.packages ?? []) {
+            // The FIRST spelling of the plan rides the request. An outcome
+            // echoes the requested spelling, and a last-writer fold could
+            // echo `seurat` where the plan said `Seurat` — a remedy in that
+            // case names a package that no repository holds.
+            const key = entry.trim().toLowerCase();
+            if (!union.has(key))
+                union.set(key, parseRequirement(entry));
+        }
+    }
+    if (union.size === 0)
+        return;
+    let outcomes;
+    try {
+        outcomes = await extendAnalysisFarm(analysisId, [...union.values()]);
+    }
+    catch (cause) {
+        // A realization throw is an `unavailable` answer, not a driver error.
+        // The sibling resolver seam maps a throw the same way (farm.ts), and
+        // the planner can act on "the store cannot answer" — not on a stack.
+        throw new PlanPackagesMissingError([], [], cause instanceof Error ? cause.message : String(cause));
+    }
+    // An `unavailable` outcome preempts everything: the link pass could not
+    // answer at all (an unreadable graph, a locked farm), so a per-package
+    // absence list would be a fabrication. One reason covers the batch.
+    const unavailable = outcomes.find((o) => o.kind === "unavailable");
+    if (unavailable !== undefined) {
+        throw new PlanPackagesMissingError([], [], unavailable.reason);
+    }
+    // A seam-supplied detail classifies the miss in host terms (in flight,
+    // failed with its reason, never requested), and it rides beside the name
+    // so the agent replans from the true state instead of re-asking. A
+    // collision's detail names the two pins and what needs each side — the
+    // remedy is to drop or re-pin a DEPENDENT, so the refusal must name it.
+    const missing = outcomes.filter((o) => o.kind === "absent").map((o) => (o.detail === undefined ? o.name : `${o.name} — ${o.detail}`));
+    const collisions = outcomes.filter((o) => o.kind === "collision").map((o) => (o.detail === undefined ? o.name : `${o.name} — ${o.detail}`));
+    if (missing.length > 0 || collisions.length > 0) {
+        throw new PlanPackagesMissingError(missing, collisions);
+    }
+}
 function planSummary(plan) {
     return plan.title?.trim() || plan.analytical_narrative.trim().slice(0, 280);
 }
@@ -183,6 +267,9 @@ export function createExecuteAnalysisTool(deps) {
             else {
                 plan = await persistedAdHocPlan(deps, { analysisId, request: input.request, ctx, planId });
             }
+            // The link pass comes before the run reserves anything, thus a pool
+            // miss leaves no run row and no revoked authorization behind.
+            await linkPlanPackages(deps.extendAnalysisFarm, analysisId, plan);
             const runId = input.mode === "plan" ? randomUUID() : adHocRunId(analysisId, ctx.invocationId);
             if (input.mode === "plan") {
                 try {

package/dist/tools/research/generate-plan.js

@@ -677,7 +677,13 @@ function buildPlannerSearchTools(deps) {
         // collection of the reference store, or one package name that a step is
         // about to import.
         createListAvailableRefsTool(deps.refStorePath === undefined ? {} : { refStorePath: deps.refStorePath }),
-        createListAvailablePackagesTool(deps.packagesFile === undefined ? {} : { packagesFile: deps.packagesFile }),
+        // The planner is a conversation surface, thus the pool-scope reader binds
+        // when the embedder gives one, and the answer names what the store HOLDS.
+        createListAvailablePackagesTool({
+            ...(deps.farmLockFile === undefined ? {} : { farmLockFile: deps.farmLockFile }),
+            ...(deps.imagePackagesFile === undefined ? {} : { imagePackagesFile: deps.imagePackagesFile }),
+            ...(deps.readPoolInventory === undefined ? {} : { readPoolInventory: deps.readPoolInventory }),
+        }),
     ];
 }
 /** Build the `generate_plan` tool bound to its provider and pool. */
@@ -804,7 +810,11 @@ export function createGeneratePlanTool(deps) {
             // not optional planner lookups. Read both inventories host-side before
             // the loop and put their rendered content in the planner's seed.
             const listAvailableRefs = createListAvailableRefsTool(deps.refStorePath === undefined ? {} : { refStorePath: deps.refStorePath });
-            const listAvailablePackages = createListAvailablePackagesTool(deps.packagesFile === undefined ? {} : { packagesFile: deps.packagesFile });
+            const listAvailablePackages = createListAvailablePackagesTool({
+                ...(deps.farmLockFile === undefined ? {} : { farmLockFile: deps.farmLockFile }),
+                ...(deps.imagePackagesFile === undefined ? {} : { imagePackagesFile: deps.imagePackagesFile }),
+                ...(deps.readPoolInventory === undefined ? {} : { readPoolInventory: deps.readPoolInventory }),
+            });
             // A path-separator query matches every reference path and selects the
             // tool's recursive leaf scan, so the seed contains usable file paths,
             // not only top-level directory summaries.

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

@@ -2,6 +2,7 @@
  * Sandbox barrel — sandbox-environment introspection (available lib-store
  * packages and reference datasets). Consumed by sandbox agents.
  */
+export * from "./link-packages.js";
 export * from "./list-available-packages.js";
 export * from "./list-available-refs.js";
 export * from "./report-blocker.js";

package/dist/tools/sandbox/index.js

@@ -2,6 +2,7 @@
  * Sandbox barrel — sandbox-environment introspection (available lib-store
  * packages and reference datasets). Consumed by sandbox agents.
  */
+export * from "./link-packages.js";
 export * from "./list-available-packages.js";
 export * from "./list-available-refs.js";
 export * from "./report-blocker.js";

package/dist/tools/sandbox/link-packages.d.ts

@@ -0,0 +1,27 @@
+/**
+ * link_packages — extend the farm of the analysis with host-staged packages.
+ *
+ * The tool is the agent face of the `ExtendAnalysisFarm` seam. It exists only
+ * when the embedder binds the seam (the harness-sandbox-agents spec): the
+ * composition adds it to the always-on substrate, and no `meta.tools`
+ * allowlist names it. The realization of the embedder links what the host
+ * staged — the tool never installs, downloads, or acquires anything. A link
+ * is live in a container that already runs, because the farm rides a bind
+ * mount.
+ */
+import type { ExtendAnalysisFarm, PackageRequestOutcome } from "../../sandbox/types.js";
+export interface LinkPackagesDeps {
+    readonly extendAnalysisFarm: ExtendAnalysisFarm;
+    readonly analysisId: string;
+}
+/** The tool result: one outcome per requested package, index-aligned. */
+export interface LinkPackagesResult {
+    readonly outcomes: readonly PackageRequestOutcome[];
+}
+export declare function createLinkPackagesTool(deps: LinkPackagesDeps): import("../define-tool.js").Tool<{
+    packages: {
+        name: string;
+        version?: string | undefined;
+        ecosystem?: "r" | "python" | undefined;
+    }[];
+}, LinkPackagesResult>;

package/dist/tools/sandbox/link-packages.js

@@ -0,0 +1,52 @@
+/**
+ * link_packages — extend the farm of the analysis with host-staged packages.
+ *
+ * The tool is the agent face of the `ExtendAnalysisFarm` seam. It exists only
+ * when the embedder binds the seam (the harness-sandbox-agents spec): the
+ * composition adds it to the always-on substrate, and no `meta.tools`
+ * allowlist names it. The realization of the embedder links what the host
+ * staged — the tool never installs, downloads, or acquires anything. A link
+ * is live in a container that already runs, because the farm rides a bind
+ * mount.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+export function createLinkPackagesTool(deps) {
+    return defineTool({
+        id: "link_packages",
+        description: "Link host-staged packages into the farm of this analysis, so an import that failed works without a restart. " +
+            "This tool links what the host already staged — it NEVER installs, downloads, or acquires anything. " +
+            "Pass each module name verbatim, exactly as the import names it. " +
+            "One outcome comes back per request: `linked` (the pool held it, and it is importable now), " +
+            "`present` (the farm held it already), " +
+            "`absent` (the pool does not hold it — a real answer, and `acquisitionPossible` states whether the host can acquire that ecosystem; report the package as missing, do not retry), " +
+            "`collision` (the request resolves to two store directories — terminal for that package; the `detail` names the two pins and the packages that need each; report it and continue without it), " +
+            "or `unavailable` (the link pass itself could not answer — the `reason` says why; it says nothing about the package's presence, so report the reason and do not re-request packages).",
+        inputSchema: z.object({
+            packages: z
+                .array(z.object({
+                name: z.string().min(1).describe("The module or package name, verbatim."),
+                version: z.string().optional().describe("One exact version, when the requirement pins one."),
+                ecosystem: z.enum(["python", "r"]).optional().describe("The ecosystem, when the bare name is ambiguous."),
+            }))
+                .min(1)
+                .max(50)
+                .describe("The packages to link into the farm."),
+        }),
+        describeCall: ({ packages }) => packages.map((p) => p.name).join(", "),
+        execute: async (input) => {
+            // A realization throw reads as `unavailable` per request. The loop
+            // would render the throw as a raw tool error, and a raw driver
+            // message teaches the agent nothing that `reason` does not.
+            try {
+                const outcomes = await deps.extendAnalysisFarm(deps.analysisId, input.packages);
+                return ok({ outcomes });
+            }
+            catch (cause) {
+                const reason = cause instanceof Error ? cause.message : String(cause);
+                return ok({ outcomes: input.packages.map((request) => ({ kind: "unavailable", name: request.name, reason })) });
+            }
+        },
+    });
+}

package/dist/tools/sandbox/list-available-packages.d.ts

@@ -1,40 +1,48 @@
 /**
- * listAvailablePackages — query the R/Python/CLI/Node packages available in the
- * sandbox.
+ * listAvailablePackages — query the R/Python/CLI/Node packages of the
+ * environment, from the inventory source the embedder binds.
  *
- * The data source is the store's `packages.txt`, assembled by the library-store
- * build (see the lib-store-build spec) and read from wherever the HOST can see
- * it — the container path when the host mounts the same store, an injected path
- * when it does not. Its shape is fixed by the
- * producers (`scripts/lib-store-common.sh`, `images/sandbox-python/inflexa-libs-refresh`):
- * two `#` advisory lines, then one `## <Section>` heading per language track
- * followed by that track's packages as a single comma-separated line.
+ * Two sources exist, one per vantage. A SANDBOX agent reads the
+ * `inflexa.lock` of the mounted farm — what a step can import right now —
+ * from wherever the HOST can see it: the farm container path when the host
+ * mounts the same farm, an injected path when it does not. A CONVERSATION or
+ * planning surface reads the pool-scope inventory (`readPoolInventory`) —
+ * everything the store holds, whether or not a farm links it yet — because
+ * the ask flow marks the packages the POOL does not hold, and the farm of a
+ * new analysis is empty. The baked image inventory fragment
+ * (`image-packages.txt`, at `/opt/inflexa` in the image) merges into either
+ * report when the host can read one. The fragment keeps the section format:
  *
- *     # Available packages in the sandbox environment.
- *     # Do NOT attempt to install packages — ...
+ *     ## System tools (CLI)
+ *     samtools, bcftools, ...
  *
- *     ## R (CRAN)
- *     Seurat, dplyr, ggplot2, ...
- *
- *     ## Python (pip)
- *     anndata, scanpy, ...
- *
- * The file carries **names only — there are no version strings in it**, so this
- * tool reports presence and language track and cannot report a version.
+ * Each entry renders as `name==version` where the source pins a version, and
+ * a targeted `names` lookup also carries the store directory and the full
+ * content hash where the source records them. A full listing carries no
+ * hashes — a thousand rows of sha256 would bury the signal.
  */
-import type { EnvironmentStorePaths } from "../../config/environment-stores.js";
-/** One language track of the store, in `packages.txt` section order. */
-export interface Section {
-    /** The section heading verbatim, e.g. `R (CRAN)`, `Python (pip)`. */
-    readonly title: string;
-    readonly packages: readonly string[];
-}
-/** One `names` lookup: present + canonical spelling + track, or absent. */
+import type { EnvironmentStorePaths, PoolInventoryPackage, PoolInventorySection } from "../../config/environment-stores.js";
+import { type FarmLock } from "../../sandbox/farm.js";
+/**
+ * Group the lock packages into sections, one per track, in a stable order:
+ * the known tracks first, then an unknown track at its first occurrence.
+ * Each entry keeps the lock's version, store directory, and hash, so the
+ * targeted `names` path can report the exact store identity.
+ */
+export declare function lockSections(lock: FarmLock): Section[];
+/** One package entry of a section, with the store identity where the source records it. */
+export type SectionPackage = PoolInventoryPackage;
+/** One language track of the store, in `packages.txt` section order. The seam shape and the render shape are one. */
+export type Section = PoolInventorySection;
+/** One `names` lookup: present + canonical spelling + track + store identity, or absent. */
 export type CheckedPackage = {
     readonly requested: string;
     readonly present: true;
     readonly name: string;
     readonly section: string;
+    readonly version?: string;
+    readonly storeDir?: string;
+    readonly hash?: string;
 } | {
     readonly requested: string;
     readonly present: false;
@@ -76,11 +84,23 @@ export interface PackagesQuery {
  * is only the file read plus this call.
  */
 export declare function queryPackages(sections: readonly Section[], { names, query, language, limit }: PackagesQuery): PackagesResult;
-export type ListAvailablePackagesDeps = Pick<EnvironmentStorePaths, "packagesFile">;
-/** Create the package inventory over a host-readable `packages.txt`. */
+export type ListAvailablePackagesDeps = Pick<EnvironmentStorePaths, "farmLockFile" | "imagePackagesFile" | "readPoolInventory"> & {
+    /**
+     * True when the composition also attaches the `link_packages` tool. The
+     * framing sentence must not close the world on the farm then: a package
+     * absent from the farm lock can still link in from the pool.
+     */
+    readonly linkToolPresent?: boolean;
+};
+/**
+ * Create the package inventory over the bound source: the pool-scope reader
+ * when the embedder binds one (a conversation or planning surface), the
+ * host-readable farm `inflexa.lock` otherwise (a sandbox agent). The image
+ * fragment merges into either report.
+ */
 export declare function createListAvailablePackagesTool(deps?: ListAvailablePackagesDeps): import("../define-tool.js").Tool<{
     names?: string[] | undefined;
     query?: string | undefined;
-    language?: "r" | "python" | "cli" | "node" | undefined;
+    language?: "r" | "python" | "node" | "cli" | undefined;
     limit?: number | undefined;
 }, PackagesResult>;

package/dist/tools/sandbox/list-available-packages.js

@@ -1,26 +1,25 @@
 /**
- * listAvailablePackages — query the R/Python/CLI/Node packages available in the
- * sandbox.
+ * listAvailablePackages — query the R/Python/CLI/Node packages of the
+ * environment, from the inventory source the embedder binds.
  *
- * The data source is the store's `packages.txt`, assembled by the library-store
- * build (see the lib-store-build spec) and read from wherever the HOST can see
- * it — the container path when the host mounts the same store, an injected path
- * when it does not. Its shape is fixed by the
- * producers (`scripts/lib-store-common.sh`, `images/sandbox-python/inflexa-libs-refresh`):
- * two `#` advisory lines, then one `## <Section>` heading per language track
- * followed by that track's packages as a single comma-separated line.
+ * Two sources exist, one per vantage. A SANDBOX agent reads the
+ * `inflexa.lock` of the mounted farm — what a step can import right now —
+ * from wherever the HOST can see it: the farm container path when the host
+ * mounts the same farm, an injected path when it does not. A CONVERSATION or
+ * planning surface reads the pool-scope inventory (`readPoolInventory`) —
+ * everything the store holds, whether or not a farm links it yet — because
+ * the ask flow marks the packages the POOL does not hold, and the farm of a
+ * new analysis is empty. The baked image inventory fragment
+ * (`image-packages.txt`, at `/opt/inflexa` in the image) merges into either
+ * report when the host can read one. The fragment keeps the section format:
  *
- *     # Available packages in the sandbox environment.
- *     # Do NOT attempt to install packages — ...
+ *     ## System tools (CLI)
+ *     samtools, bcftools, ...
  *
- *     ## R (CRAN)
- *     Seurat, dplyr, ggplot2, ...
- *
- *     ## Python (pip)
- *     anndata, scanpy, ...
- *
- * The file carries **names only — there are no version strings in it**, so this
- * tool reports presence and language track and cannot report a version.
+ * Each entry renders as `name==version` where the source pins a version, and
+ * a targeted `names` lookup also carries the store directory and the full
+ * content hash where the source records them. A full listing carries no
+ * hashes — a thousand rows of sha256 would bury the signal.
  */
 import { readFile } from "node:fs/promises";
 import { ok } from "neverthrow";
@@ -28,12 +27,45 @@ import { z } from "zod";
 import { defineTool } from "../define-tool.js";
 import { capCodePoints, DETAIL_NEEDLE_MAX_LENGTH } from "../../loop/tool-detail.js";
 import { LIBS_CONTAINER_PATH } from "../../sandbox/mount-plan.js";
+import { readFarmLockFile } from "../../sandbox/farm.js";
 /**
- * Where the list lives when the host mounts the library store at the same path
- * the sandbox does. Hosts that do not — the store is baked into the image and
- * never bind-mounted — inject their own path instead.
+ * Where the lock lives when the host mounts the farm at the same path the
+ * sandbox does. Both farm container paths are tried, because the path keys on
+ * the declared toolchain (`/mnt/libs/farm` under `"image"`, `/mnt/libs/current`
+ * under `"store"`), and the tool does not carry that declaration. A host that
+ * reads the farm somewhere else injects its own path instead.
  */
-const DEFAULT_PACKAGES_FILE = `${LIBS_CONTAINER_PATH}/current/packages.txt`;
+const DEFAULT_FARM_LOCK_FILES = [`${LIBS_CONTAINER_PATH}/farm/inflexa.lock`, `${LIBS_CONTAINER_PATH}/current/inflexa.lock`];
+/** Where the baked image inventory fragment lives inside the image. */
+const DEFAULT_IMAGE_PACKAGES_FILE = "/opt/inflexa/image-packages.txt";
+/** The section title of each known lock track. An unknown track titles itself. */
+const TRACK_TITLES = {
+    python: "Python (pip)",
+    cran: "R (CRAN)",
+    bioconductor: "R (Bioconductor)",
+    github: "R (GitHub)",
+    node: "Node (npm)",
+};
+/**
+ * Group the lock packages into sections, one per track, in a stable order:
+ * the known tracks first, then an unknown track at its first occurrence.
+ * Each entry keeps the lock's version, store directory, and hash, so the
+ * targeted `names` path can report the exact store identity.
+ */
+export function lockSections(lock) {
+    const byTrack = new Map();
+    for (const track of Object.keys(TRACK_TITLES))
+        byTrack.set(track, []);
+    for (const pkg of lock.packages) {
+        const entry = { name: pkg.name, version: pkg.version, storeDir: pkg.store_dir, hash: pkg.hash };
+        const open = byTrack.get(pkg.track);
+        if (open)
+            open.push(entry);
+        else
+            byTrack.set(pkg.track, [entry]);
+    }
+    return [...byTrack.entries()].filter(([, packages]) => packages.length > 0).map(([track, packages]) => ({ title: TRACK_TITLES[track] ?? track, packages }));
+}
 /**
  * Default cap on a listing — high enough that the real store is never truncated.
  * The shipped catalog is ~270 packages (~3 KB, well under a thousand tokens), so
@@ -49,11 +81,18 @@ const DEFAULT_LIMIT = 2_000;
  * check, and an agent told to "assume numpy is available" will import it and
  * fail at runtime instead of probing first.
  */
-const UNAVAILABLE_NOTE = "Package list not available — the library store's inventory could not be read, so what is installed is UNKNOWN. " +
+const UNAVAILABLE_NOTE = "Package list not available — the inventory of the farm could not be read, so what is installed is UNKNOWN. " +
     "Do not assume any package is present, and do not infer one from the analysis you were asked to run. " +
     "Probe each package you intend to use before relying on it (`python3 -c 'import <pkg>'`, " +
     'R `requireNamespace("<pkg>", quietly = TRUE)`) and degrade gracefully when it is absent. ' +
     "Nothing can be installed at runtime.";
+/**
+ * The pool-scope twin of {@link UNAVAILABLE_NOTE}. It names no runtime probe,
+ * because a conversation surface has no runtime to probe, and an unreadable
+ * pool must read as UNKNOWN rather than as empty.
+ */
+const POOL_UNAVAILABLE_NOTE = "Package list not available — the package pool could not be read, so what the store holds is UNKNOWN. " +
+    "Do not assume a package is present, and do not report a package as absent.";
 /** The `language` filter values, mapped onto the concrete section headings. */
 const LANGUAGE_MATCHERS = {
     // The R triple: `R (CRAN)`, `R (Bioconductor)`, `R (GitHub)`.
@@ -87,11 +126,15 @@ export function parsePackagesFile(content) {
         for (const name of trimmed.split(",")) {
             const pkg = name.trim();
             if (pkg)
-                open.packages.push(pkg);
+                open.packages.push({ name: pkg });
         }
     }
     return sections;
 }
+/** One entry as the listing renders it: `name==version` where the source pins a version, the bare name otherwise. */
+function renderPackage(entry) {
+    return entry.version === undefined ? entry.name : `${entry.name}==${entry.version}`;
+}
 /** Render sections to the agent-facing listing, bounded at `limit` packages. */
 function renderListing(sections, limit) {
     const lines = [];
@@ -106,7 +149,7 @@ function renderListing(sections, limit) {
         }
         const shown = section.packages.slice(0, room);
         returned += shown.length;
-        lines.push(`\n## ${section.title}`, `  ${shown.join(", ")}`);
+        lines.push(`\n## ${section.title}`, `  ${shown.map(renderPackage).join(", ")}`);
         const hidden = section.packages.length - shown.length;
         if (hidden > 0)
             lines.push(`  … and ${hidden} more in this section (raise \`limit\` or narrow with \`query\`).`);
@@ -126,15 +169,26 @@ export function queryPackages(sections, { names, query, language, limit }) {
             for (const pkg of section.packages) {
                 // First writer wins: `packages.txt` sections are ordered, so a name
                 // colliding across tracks resolves to the earliest one.
-                if (!index.has(pkg.toLowerCase()))
-                    index.set(pkg.toLowerCase(), { name: pkg, section: section.title });
+                if (!index.has(pkg.name.toLowerCase()))
+                    index.set(pkg.name.toLowerCase(), { entry: pkg, section: section.title });
             }
         }
         const checked = names.map((requested) => {
             const hit = index.get(requested.trim().toLowerCase());
+            if (!hit)
+                return { requested, present: false };
             // `name` echoes the catalog's canonical spelling — R package names are
             // case-sensitive at `library()`, so the exact one is what the caller needs.
-            return hit ? { requested, present: true, name: hit.name, section: hit.section } : { requested, present: false };
+            // The store identity rides only where the source records it.
+            return {
+                requested,
+                present: true,
+                name: hit.entry.name,
+                section: hit.section,
+                ...(hit.entry.version === undefined ? {} : { version: hit.entry.version }),
+                ...(hit.entry.storeDir === undefined ? {} : { storeDir: hit.entry.storeDir }),
+                ...(hit.entry.hash === undefined ? {} : { hash: hit.entry.hash }),
+            };
         });
         return { available: true, checked };
     }
@@ -144,7 +198,7 @@ export function queryPackages(sections, { names, query, language, limit }) {
         .filter((s) => matchesLanguage(s.title))
         .map((s) => ({
         title: s.title,
-        packages: needle ? s.packages.filter((p) => p.toLowerCase().includes(needle)) : s.packages,
+        packages: needle ? s.packages.filter((p) => p.name.toLowerCase().includes(needle)) : s.packages,
     }))
         .filter((s) => s.packages.length > 0);
     const total = filtered.reduce((n, s) => n + s.packages.length, 0);
@@ -161,18 +215,36 @@ export function queryPackages(sections, { names, query, language, limit }) {
     const { content, returned } = renderListing(filtered, limit ?? DEFAULT_LIMIT);
     return { available: true, total, returned, hasMore: returned < total, content };
 }
-/** Create the package inventory over a host-readable `packages.txt`. */
+/**
+ * Create the package inventory over the bound source: the pool-scope reader
+ * when the embedder binds one (a conversation or planning surface), the
+ * host-readable farm `inflexa.lock` otherwise (a sandbox agent). The image
+ * fragment merges into either report.
+ */
 export function createListAvailablePackagesTool(deps = {}) {
-    const packagesFile = deps.packagesFile ?? DEFAULT_PACKAGES_FILE;
+    const lockCandidates = deps.farmLockFile ? [deps.farmLockFile] : DEFAULT_FARM_LOCK_FILES;
+    const imagePackagesFile = deps.imagePackagesFile ?? DEFAULT_IMAGE_PACKAGES_FILE;
+    const readPoolInventory = deps.readPoolInventory;
+    // The scope decides the framing sentence: a sandbox agent reads what it can
+    // import NOW, and a conversation surface reads what the store HOLDS — a
+    // package absent from the pool needs an acquisition, not a shrug. A sandbox
+    // composition with the link seam gets a third framing. There the farm is
+    // not the boundary of an import, and a closed-world sentence would send the
+    // agent to report a package that one link call supplies.
+    const scopeSentence = readPoolInventory
+        ? "Query the R, Python, CLI, and Node packages the package pool holds — the set a run can link into an analysis. A package reported present needs no acquisition; a package absent here is not in the store yet. "
+        : deps.linkToolPresent
+            ? "Query the R, Python, CLI, and Node packages importable in the sandbox right now. Nothing installs at runtime; a package absent here can still be linkable from the host's staged pool — call `link_packages` before treating it as missing. "
+            : "Query the R, Python, CLI, and Node packages installed in the sandbox. No packages can be installed at runtime — only what this tool reports is importable. ";
     return defineTool({
         id: "list_available_packages",
-        description: "Query the R, Python, CLI, and Node packages installed in the sandbox. No packages can be installed at runtime — only what this tool reports is importable. " +
+        description: scopeSentence +
             "A full listing is small (a few hundred packages) and is returned whole by default, so a listing you get back is the complete set unless `hasMore` says otherwise. " +
             '`names`: check specific packages (e.g. ["Seurat", "scanpy"]) — returns present/absent plus the language track for each, case-insensitively; this is the cheapest call and the right one for \'is X available?\'. ' +
             "`query`: case-insensitive substring filter over package names. " +
             "`language`: restrict to one track (r | python | cli | node). " +
             "`limit`: cap the packages listed; the response always carries the true `total` and a `hasMore` flag, so truncation is never silent. " +
-            'The package list carries NO version numbers — this tool cannot report a package\'s version. Check a version at runtime instead (e.g. `python -c "import scanpy; print(scanpy.__version__)"`).',
+            "Each entry renders as `name==version` where the source pins a version, and a `names` check also reports the store directory and the content hash where the source records them.",
         inputSchema: z.object({
             names: z
                 .array(z.string())
@@ -212,16 +284,35 @@ export function createListAvailablePackagesTool(deps = {}) {
             return "full package list";
         },
         execute: async (input) => {
+            // The baked image fragment merges in when the host can read one; a
+            // missing fragment merges nothing, and that is the normal state for
+            // a host that runs outside the image.
+            const fragmentSections = await readFile(imagePackagesFile, "utf-8")
+                .then(parsePackagesFile)
+                .catch(() => []);
             // An unreadable inventory is an expected environment state — model it as an
-            // `available: false` data variant telling the caller the set is UNKNOWN.
-            let raw;
-            try {
-                raw = await readFile(packagesFile, "utf-8");
+            // `available: false` data variant telling the caller the set is UNKNOWN,
+            // WITH the reason: without it, a structural fault (a damaged dependency
+            // graph) reads as a transient flake, and the caller retries for ever.
+            if (readPoolInventory) {
+                const pool = await readPoolInventory().catch((cause) => ({
+                    kind: "unavailable",
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                }));
+                if (pool.kind === "unavailable")
+                    return ok({ available: false, content: `${POOL_UNAVAILABLE_NOTE} The reason: ${pool.reason}.` });
+                return ok(queryPackages([...pool.sections, ...fragmentSections], input));
+            }
+            let lock = null;
+            for (const candidate of lockCandidates) {
+                lock = readFarmLockFile(candidate).unwrapOr(null);
+                if (lock !== null)
+                    break;
             }
-            catch {
+            if (lock === null) {
                 return ok({ available: false, content: UNAVAILABLE_NOTE });
             }
-            return ok(queryPackages(parsePackagesFile(raw), input));
+            return ok(queryPackages([...lockSections(lock), ...fragmentSections], input));
         },
     });
 }