@inflexa-ai/harness 0.1.1 → 0.2.0

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

@@ -1,7 +1,81 @@
 /**
- * listAvailablePackages — list R/Python/CLI packages available in the sandbox.
+ * 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
+ * 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.
+ *
+ *     # Available packages in the sandbox environment.
+ *     # Do NOT attempt to install packages — ...
+ *
+ *     ## 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.
  */
-export declare const listAvailablePackagesTool: import("../define-tool.js").Tool<Record<string, never>, {
-    available: boolean;
-    content: string;
-}>;
+/** 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. */
+export type CheckedPackage = {
+    readonly requested: string;
+    readonly present: true;
+    readonly name: string;
+    readonly section: string;
+} | {
+    readonly requested: string;
+    readonly present: false;
+};
+/**
+ * Three shapes, one per call path: the store is unmounted; a `names` presence
+ * check; a (possibly filtered) listing bounded by `limit`, whose `total` and
+ * `hasMore` make truncation explicit.
+ */
+export type PackagesResult = {
+    readonly available: false;
+    readonly content: string;
+} | {
+    readonly available: true;
+    readonly checked: readonly CheckedPackage[];
+} | {
+    readonly available: true;
+    readonly total: number;
+    readonly returned: number;
+    readonly hasMore: boolean;
+    readonly content: string;
+};
+/**
+ * Parse `packages.txt` into its sections. `#` lines are the advisory header,
+ * `## X` opens a section, and every other non-empty line contributes
+ * comma-separated package names to the open section. Unknown section headings
+ * are preserved as-is — a downstream image may add its own track.
+ */
+export declare function parsePackagesFile(content: string): Section[];
+/** The tool's input, as parsed from `inputSchema`. */
+export interface PackagesQuery {
+    readonly names?: readonly string[];
+    readonly query?: string;
+    readonly language?: "r" | "python" | "cli" | "node";
+    readonly limit?: number;
+}
+/**
+ * Answer a packages query against a parsed catalog. Pure — the tool's `execute`
+ * 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<{
+    names?: string[] | undefined;
+    query?: string | undefined;
+    language?: "r" | "python" | "cli" | "node" | undefined;
+    limit?: number | undefined;
+}, PackagesResult>;

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

@@ -1,27 +1,169 @@
 /**
- * listAvailablePackages — list R/Python/CLI packages available in the sandbox.
+ * 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
+ * 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.
+ *
+ *     # Available packages in the sandbox environment.
+ *     # Do NOT attempt to install packages — ...
+ *
+ *     ## 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.
  */
 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.";
+/** The `language` filter values, mapped onto the concrete section headings. */
+const LANGUAGE_MATCHERS = {
+    // The R triple: `R (CRAN)`, `R (Bioconductor)`, `R (GitHub)`.
+    r: (t) => /^r\b/i.test(t),
+    python: (t) => /^python\b/i.test(t),
+    // `System tools (CLI)` — the conda-installed bioinformatics executables.
+    cli: (t) => /system tools|\bcli\b/i.test(t),
+    node: (t) => /^node\b/i.test(t),
+};
+/**
+ * Parse `packages.txt` into its sections. `#` lines are the advisory header,
+ * `## X` opens a section, and every other non-empty line contributes
+ * comma-separated package names to the open section. Unknown section headings
+ * are preserved as-is — a downstream image may add its own track.
+ */
+export function parsePackagesFile(content) {
+    const sections = [];
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        if (trimmed.startsWith("##")) {
+            sections.push({ title: trimmed.slice(2).trim(), packages: [] });
+            continue;
+        }
+        if (trimmed.startsWith("#"))
+            continue;
+        const open = sections.at(-1);
+        if (!open)
+            continue;
+        for (const name of trimmed.split(",")) {
+            const pkg = name.trim();
+            if (pkg)
+                open.packages.push(pkg);
+        }
+    }
+    return sections;
+}
+/** Render sections to the agent-facing listing, bounded at `limit` packages. */
+function renderListing(sections, limit) {
+    const lines = [];
+    let returned = 0;
+    for (const section of sections) {
+        if (section.packages.length === 0)
+            continue;
+        const room = limit - returned;
+        if (room <= 0) {
+            lines.push(`\n## ${section.title}`, `  ${section.packages.length} package(s) — not shown (limit reached).`);
+            continue;
+        }
+        const shown = section.packages.slice(0, room);
+        returned += shown.length;
+        lines.push(`\n## ${section.title}`, `  ${shown.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\`).`);
+    }
+    return { content: lines.join("\n").trim(), returned };
+}
+/**
+ * Answer a packages query against a parsed catalog. Pure — the tool's `execute`
+ * is only the file read plus this call.
+ */
+export function queryPackages(sections, { names, query, language, limit }) {
+    // Presence check — the cheap, targeted path. Answers "is X available, and in
+    // which track" without returning the catalog.
+    if (names && names.length > 0) {
+        const index = new Map();
+        for (const section of sections) {
+            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 });
+            }
+        }
+        const checked = names.map((requested) => {
+            const hit = index.get(requested.trim().toLowerCase());
+            // `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 };
+        });
+        return { available: true, checked };
+    }
+    const matchesLanguage = language ? LANGUAGE_MATCHERS[language] : () => true;
+    const needle = query?.trim().toLowerCase();
+    const filtered = sections
+        .filter((s) => matchesLanguage(s.title))
+        .map((s) => ({
+        title: s.title,
+        packages: needle ? s.packages.filter((p) => p.toLowerCase().includes(needle)) : s.packages,
+    }))
+        .filter((s) => s.packages.length > 0);
+    const total = filtered.reduce((n, s) => n + s.packages.length, 0);
+    if (total === 0) {
+        const scope = [language ? `language: ${language}` : null, query ? `query: "${query}"` : null].filter(Boolean).join(", ");
+        return {
+            available: true,
+            total: 0,
+            returned: 0,
+            hasMore: false,
+            content: `No packages match this filter${scope ? ` (${scope})` : ""}. Nothing can be installed at runtime.`,
+        };
+    }
+    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: "List all R, Python, and CLI packages available in the sandbox environment. Use this before writing analysis scripts to verify which packages you can import. No packages can be installed at runtime — only what this tool returns is available.",
-    inputSchema: z.object({}),
-    execute: async () => {
+    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 {
-            const content = await readFile(PACKAGES_FILE, "utf-8");
-            return ok({ available: true, content });
+            raw = await readFile(PACKAGES_FILE, "utf-8");
         }
         catch {
-            return ok({
-                available: false,
-                content: "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.",
-            });
+            return ok({ available: false, content: UNAVAILABLE_NOTE });
         }
+        return ok(queryPackages(parsePackagesFile(raw), input));
     },
 });

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

@@ -1,7 +1,143 @@
 /**
- * listAvailableRefs — list reference data available in the sandbox.
+ * Reference-store discovery — two coordinated surfaces over the read-only
+ * store at /mnt/refs:
+ *
+ * - `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`.
  */
-export declare const listAvailableRefsTool: import("../define-tool.js").Tool<Record<string, never>, {
-    available: boolean;
-    content: string;
-}>;
+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;
+}
+export interface ReferenceInventoryMetadata {
+    readonly datasetId?: string;
+    readonly version?: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly sourceUrl?: string;
+    readonly license?: string;
+    readonly category?: string;
+    readonly subtype?: string;
+    readonly organism?: string;
+    readonly rows?: number;
+    readonly endpoint?: string;
+}
+interface ReferenceInventoryEntryBase {
+    readonly path: string;
+    readonly metadata?: ReferenceInventoryMetadata;
+}
+/** A bounded, no-follow observation from the live reference mount. */
+export type ReferenceInventoryEntry = (ReferenceInventoryEntryBase & {
+    readonly kind: "file";
+    readonly bytes: number;
+}) | (ReferenceInventoryEntryBase & {
+    readonly kind: "symlink";
+    readonly bytes: 0;
+}) | (ReferenceInventoryEntryBase & {
+    readonly kind: "directory";
+    readonly bytes: number;
+    readonly fileCount: number;
+    readonly fileTypes: readonly string[];
+    readonly truncated: boolean;
+});
+/**
+ * Structured result returned for every expected reference-store state. Bounding
+ * is explicit: `returned`/`total`/`hasMore` describe how much of the match set
+ * this response carries, and `categories` is the drill-in index.
+ */
+export interface ReferenceInventoryResult {
+    readonly available: boolean;
+    readonly state: RawScan["state"] | "out_of_scope";
+    readonly path: string;
+    readonly entries: readonly ReferenceInventoryEntry[];
+    readonly scannedEntries: number;
+    readonly returned: number;
+    readonly total: number;
+    readonly truncated: boolean;
+    readonly hasMore: boolean;
+    readonly categories: readonly string[];
+    readonly content: string;
+}
+interface RawScan {
+    readonly state: "unavailable" | "empty" | "populated" | "not_found" | "not_a_directory" | "symlink";
+    readonly entries: ReferenceInventoryEntry[];
+    readonly scannedEntries: number;
+    readonly truncated: boolean;
+    readonly receipts?: unknown[];
+    readonly legacyEntries?: unknown[];
+}
+/** Create replay-safe reference discovery bound to the active sandbox. */
+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 {};