@inflexa-ai/harness 0.6.0 → 0.7.0

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

@@ -32,6 +32,7 @@ import { runToTerminal } from "../../loop/run-to-terminal.js";
 import { passthroughStep } from "../../loop/run-step.js";
 import { forSubAgent, scopeResource } from "../../auth/types.js";
 import { defineTool } from "../define-tool.js";
+import { createListAvailableRefsTool } from "../sandbox/list-available-refs.js";
 import { createReportBlockerToolFor } from "../sandbox/report-blocker.js";
 import { DATA_PROFILE_ORIENTATION_MAX_CHARS, buildDataProfileOrientation } from "../../app/data-profile-orientation.js";
 import { isDataProfileStale } from "../../app/data-profile-policy.js";
@@ -249,7 +250,7 @@ function fullyValidate(candidate, resourcePolicy) {
  * shared `holder` so the outer `execute` reads the terminal outcome after the
  * loop finishes.
  */
-function buildInnerTools(holder, persistCtx, pool, resourcePolicy) {
+function buildInnerTools(holder, persistCtx, pool, resourcePolicy, refStorePath) {
     const validatePlanTool = defineTool({
         id: "validate_plan",
         description: "Dry-run a candidate plan and get back everything that is wrong with it. " +
@@ -353,8 +354,12 @@ function buildInnerTools(holder, persistCtx, pool, resourcePolicy) {
             "incompatible with every available agent, etc.) — not for a plan you " +
             "could fix and submit.",
     });
+    // Reference discovery is non-terminal and read-only: it lets the planner check what
+    // reference data this environment actually holds before committing a step to needing
+    // it. It reads the store host-side, so no sandbox exists or is needed at plan time.
+    const listAvailableRefs = createListAvailableRefsTool(refStorePath === undefined ? {} : { refStorePath });
     const terminal = [submitPlanTool, requestClarificationTool, reportBlockerTool];
-    return { all: [validatePlanTool, ...terminal], terminal };
+    return { all: [validatePlanTool, listAvailableRefs, ...terminal], terminal };
 }
 /**
  * Translate the captured `PlannerOutcome` (plus any loop error) into the
@@ -486,7 +491,7 @@ export function createGeneratePlanTool(deps) {
                 analysisId,
                 parentPlanId: input.parentPlanId ?? null,
             };
-            const innerTools = buildInnerTools(holder, persistCtx, deps.pool, deps.resourcePolicy);
+            const innerTools = buildInnerTools(holder, persistCtx, deps.pool, deps.resourcePolicy, deps.refStorePath);
             const planner = {
                 id: PLANNER_AGENT_ID,
                 systemPrompt: composeSystemPrompt(plannerInstructions(deps.resourcePolicy)),

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

@@ -2,8 +2,10 @@
  * listAvailablePackages — query the R/Python/CLI/Node packages available in the
  * sandbox.
  *
- * The data source is `/mnt/libs/current/packages.txt`, assembled by the
- * library-store build (see the lib-store-build spec). Its shape is fixed by the
+ * 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.
@@ -73,7 +75,18 @@ 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 declare const listAvailablePackagesTool: import("../define-tool.js").Tool<{
+export interface ListAvailablePackagesDeps {
+    /**
+     * Path to the store's `packages.txt` AS THE HOST SEES IT. Defaults to the
+     * container path, which is correct only when the host mounts the same store.
+     * A host that does not — one whose store is baked into the sandbox image and
+     * never bind-mounted — must inject the path to its own extracted copy, or the
+     * read fails and every caller is told the inventory is unknown.
+     */
+    readonly packagesFile?: string;
+}
+/** Create the package inventory over a host-readable `packages.txt`. */
+export declare function createListAvailablePackagesTool(deps?: ListAvailablePackagesDeps): import("../define-tool.js").Tool<{
     names?: string[] | undefined;
     query?: string | undefined;
     language?: "r" | "python" | "cli" | "node" | undefined;

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

@@ -2,8 +2,10 @@
  * listAvailablePackages — query the R/Python/CLI/Node packages available in the
  * sandbox.
  *
- * The data source is `/mnt/libs/current/packages.txt`, assembled by the
- * library-store build (see the lib-store-build spec). Its shape is fixed by the
+ * 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.
@@ -24,10 +26,32 @@ import { readFile } from "node:fs/promises";
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
-const PACKAGES_FILE = "/mnt/libs/current/packages.txt";
-/** Default number of packages a filtered/unfiltered listing returns. */
-const DEFAULT_LIMIT = 100;
-const UNAVAILABLE_NOTE = "Package list not available. The library store may not be mounted. Assume standard bioinformatics packages (numpy, pandas, scanpy, DESeq2, etc.) are available, but do not attempt to install anything.";
+/**
+ * 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.
+ */
+const DEFAULT_PACKAGES_FILE = "/mnt/libs/current/packages.txt";
+/**
+ * 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
+ * a low default bought nothing and cost correctness: a partial listing reads as a
+ * complete one, and an agent concludes a package is absent when it was merely not
+ * rendered. The cap survives only as a backstop for a downstream `FROM` image
+ * that adds a pathological number of packages.
+ */
+const DEFAULT_LIMIT = 2_000;
+/**
+ * Naming packages here would be worse than saying nothing: this state means the
+ * list could not be read, so any roll-call is a guess the agent has no way to
+ * 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. " +
+    "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 `language` filter values, mapped onto the concrete section headings. */
 const LANGUAGE_MATCHERS = {
     // The R triple: `R (CRAN)`, `R (Bioconductor)`, `R (GitHub)`.
@@ -135,35 +159,45 @@ 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 };
 }
-export const listAvailablePackagesTool = 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. " +
-        "Results are ALWAYS bounded; prefer a targeted query over a full listing. " +
-        '`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`: max packages listed (default 100); 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__)"`).',
-    inputSchema: z.object({
-        names: z
-            .array(z.string())
-            .max(100)
-            .optional()
-            .describe("Check these exact package names for presence (case-insensitive). Returns one entry per name: present/absent + the language track it lives in."),
-        query: z.string().optional().describe("Case-insensitive substring filter over package names."),
-        language: z.enum(["r", "python", "cli", "node"]).optional().describe("Restrict results to one language track."),
-        limit: z.number().int().min(1).max(2000).optional().describe(`Max packages to list (default ${DEFAULT_LIMIT}). Ignored when \`names\` is given.`),
-    }),
-    execute: async (input) => {
-        // A missing library-store mount is an expected environment state — model
-        // it as an `available: false` data variant with a helpful fallback note.
-        let raw;
-        try {
-            raw = await readFile(PACKAGES_FILE, "utf-8");
-        }
-        catch {
-            return ok({ available: false, content: UNAVAILABLE_NOTE });
-        }
-        return ok(queryPackages(parsePackagesFile(raw), input));
-    },
-});
+/** Create the package inventory over a host-readable `packages.txt`. */
+export function createListAvailablePackagesTool(deps = {}) {
+    const packagesFile = deps.packagesFile ?? DEFAULT_PACKAGES_FILE;
+    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. " +
+            "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__)"`).',
+        inputSchema: z.object({
+            names: z
+                .array(z.string())
+                .max(100)
+                .optional()
+                .describe("Check these exact package names for presence (case-insensitive). Returns one entry per name: present/absent + the language track it lives in."),
+            query: z.string().optional().describe("Case-insensitive substring filter over package names."),
+            language: z.enum(["r", "python", "cli", "node"]).optional().describe("Restrict results to one language track."),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(DEFAULT_LIMIT)
+                .optional()
+                .describe(`Cap the packages listed. Omit to get the whole set — the store fits well within the ${DEFAULT_LIMIT} ceiling. Ignored when \`names\` is given.`),
+        }),
+        execute: async (input) => {
+            // 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");
+            }
+            catch {
+                return ok({ available: false, content: UNAVAILABLE_NOTE });
+            }
+            return ok(queryPackages(parsePackagesFile(raw), input));
+        },
+    });
+}

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

@@ -1,29 +1,32 @@
 /**
- * Reference-store discovery — two coordinated surfaces over the read-only
- * store at /mnt/refs:
+ * Reference-store discovery: `createListAvailableRefsTool`, a bounded, no-follow
+ * inventory of what is ACTUALLY provisioned in the reference store (managed
+ * installs and user-added files alike). Narrow with `path`/`category`, filter
+ * with `query`, cap with `limit`; every response carries `returned`/`total`/
+ * `hasMore` and the `categories` present, so a listing is never an unbounded
+ * dump. Symlinks are never followed; nothing can be downloaded at runtime.
  *
- * - `createListAvailableRefsTool` — the wired sandbox tool. A bounded, no-follow
- *   inventory of what is ACTUALLY mounted (managed installs, user-added files),
- *   scanned live inside the sandbox. Narrow with `path`/`category`, filter with
- *   `query`, cap with `limit`; every response carries `returned`/`total`/
- *   `hasMore` and the `categories` present, so a listing is never an unbounded
- *   dump. Symlinks are never followed; nothing can be downloaded at runtime.
- * - `queryRefs` — a pure query over a parsed `/mnt/refs/registry.json` manifest
- *   (`files.by_category`), filtering on fields the registry carries: `local_path`,
- *   `category`, `subtype`, `organism`, `tax_id`, `dataset`, `rows`.
+ * The store is read from the host filesystem at the embedder-supplied
+ * `refStorePath` and reported at `/mnt/refs`, the container path sandboxes mount
+ * it at — read where it lives, render where the caller will open it. Reading it
+ * host-side is what lets a planner ask what reference data exists before any
+ * sandbox is created; a step agent asking mid-run sees the same store, because
+ * the mount and this path are the same bytes.
+ *
+ * The scan reports paths; meaning is joined on afterwards from the install
+ * receipt and the catalog it names (organism, format, and each file's internal
+ * shape). Callers search by what the data IS, so the store's directory layout
+ * stays an installer detail rather than an interface anything encodes. Metadata
+ * only ever ENRICHES an entry — a file with no receipt and no catalog match is
+ * still returned, because a user-provided store is as valid as a managed one.
  */
-import type { SandboxClient } from "../../sandbox/client.js";
-import type { SandboxRef } from "../../sandbox/types.js";
 export interface ListAvailableRefsDeps {
-    readonly sandboxClient: SandboxClient;
-    readonly sandbox: SandboxRef;
-    readonly workflowId: string;
-    readonly stepId: string;
-    readonly nextFunctionId: () => string;
-    readonly deadlineMs: () => number;
-    readonly markExecActive?: (execId: string) => Promise<void>;
-    /** Filesystem root used by the scanner; production callers omit this. */
-    readonly scanRoot?: string;
+    /**
+     * Host path of the reference store — the same bytes sandboxes see at
+     * `/mnt/refs`. Omitted (or absent on disk) means no store is provisioned,
+     * which is a normal state reported as `unavailable`, not an error.
+     */
+    readonly refStorePath?: string;
 }
 export interface ReferenceInventoryMetadata {
     readonly datasetId?: string;
@@ -35,6 +38,10 @@ export interface ReferenceInventoryMetadata {
     readonly category?: string;
     readonly subtype?: string;
     readonly organism?: string;
+    /** Logical content format, independent of compression — which reader to reach for. */
+    readonly format?: string;
+    /** The file's internal shape (key columns, identifier space), so a caller can use it without opening it first. */
+    readonly contents?: string;
     readonly rows?: number;
     readonly endpoint?: string;
 }
@@ -42,7 +49,7 @@ interface ReferenceInventoryEntryBase {
     readonly path: string;
     readonly metadata?: ReferenceInventoryMetadata;
 }
-/** A bounded, no-follow observation from the live reference mount. */
+/** A bounded, no-follow observation of the reference store. */
 export type ReferenceInventoryEntry = (ReferenceInventoryEntryBase & {
     readonly kind: "file";
     readonly bytes: number;
@@ -82,62 +89,11 @@ interface RawScan {
     readonly receipts?: unknown[];
     readonly legacyEntries?: unknown[];
 }
-/** Create replay-safe reference discovery bound to the active sandbox. */
+/** Create reference discovery over the host-visible reference store. */
 export declare function createListAvailableRefsTool(deps: ListAvailableRefsDeps): import("../define-tool.js").Tool<{
     path?: string | undefined;
     category?: string | undefined;
     query?: string | undefined;
     limit?: number | undefined;
 }, ReferenceInventoryResult>;
-export interface RegistryEntry {
-    local_path: string;
-    sha256: string;
-    bytes: number;
-    rows: number | null;
-    category: string | null;
-    subtype: string | null;
-    organism: string | null;
-    tax_id: string | null;
-    dataset: string | null;
-    endpoint: string | null;
-}
-export interface Registry {
-    registry_version: string;
-    build_id: string;
-    generated_at: string;
-    files: {
-        by_category: Record<string, RegistryEntry[]>;
-    };
-    summary: {
-        total_output_files: number;
-        categories: string[];
-    };
-}
-/**
- * Either the store is unmounted, or a bounded listing: `categories` always names
- * the full valid set (the drill-in index), and `total`/`hasMore` make truncation
- * explicit.
- */
-export type RefsResult = {
-    readonly available: false;
-    readonly content: string;
-} | {
-    readonly available: true;
-    readonly total: number;
-    readonly returned: number;
-    readonly hasMore: boolean;
-    readonly categories: readonly string[];
-    readonly content: string;
-};
-/** The tool's input, as parsed from `inputSchema`. */
-export interface RefsQuery {
-    readonly category?: string;
-    readonly query?: string;
-    readonly limit?: number;
-}
-/**
- * Answer a refs query against a parsed registry. Pure — the tool's `execute` is
- * only the file read plus this call.
- */
-export declare function queryRefs(registry: Registry, { category, query, limit }: RefsQuery): RefsResult;
 export {};