@inflexa-ai/harness 0.5.0 → 0.7.0

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

@@ -52,6 +52,18 @@ export interface DataProfileDeps {
     readonly embedding: EmbeddingProvider;
     /** Absolute path to the skills tree (one subdirectory per skill). */
     readonly skillsDir: string;
+    /**
+     * Host path of the library store's `packages.txt`. Omit when the host mounts the
+     * store at the sandbox's own path; a host whose store is baked into the image must
+     * inject its extracted copy, or the profiler reads the inventory as unknown.
+     */
+    readonly packagesFile?: string;
+    /**
+     * Host path of the reference store. Omit only when none is provisioned: the
+     * profiler carries reference discovery, and without this it reports an installed
+     * store as absent.
+     */
+    readonly refStorePath?: string;
 }
 /**
  * Workflow input. JSON-serialisable — DBOS persists it as the workflow's

package/dist/tasks/data-profile.js

@@ -216,6 +216,8 @@ export async function runDataProfileBody(input, deps) {
                 embedding: deps.embedding,
                 model: deps.model,
                 skillsDir: deps.skillsDir,
+                ...(deps.packagesFile ? { packagesFile: deps.packagesFile } : {}),
+                ...(deps.refStorePath ? { refStorePath: deps.refStorePath } : {}),
                 bioKeys: deps.bioKeys,
                 step: {
                     sandbox,

package/dist/tools/approval/contract.d.ts

@@ -21,6 +21,14 @@ export interface AskRequest {
     readonly title: string;
     readonly command: string;
     readonly detail?: string;
+    /**
+     * Keys the standing grant an `always` records when the class being blessed is
+     * broader than the displayed `command` — a tool that grants a whole family of
+     * operations passes the family's key here while still showing one concrete
+     * command. It is a generic, opaque key string, not a tool- or domain-specific
+     * field, and the surface never renders it. Absent, the grant keys on `command`.
+     */
+    readonly grantKey?: string;
 }
 /**
  * A user's decision on an approval request — three distinct outcomes, never a

package/dist/tools/approval/gateway.js

@@ -27,11 +27,13 @@ export function createAskGateway(deps) {
             title: request.title,
             command: request.command,
             detail: request.detail ?? null,
+            grantKey: request.grantKey ?? null,
             createdAt: now,
         };
-        // A standing grant for this exact command short-circuits the prompt: record
-        // the invocation as `resolved` for the audit trail and return without pausing.
-        if (unwrapOrThrow(await selectGrant(pool, ctx.analysisId, request.command))) {
+        // A standing grant for this ask's grant key — the command unless the tool
+        // supplied a broader key — short-circuits the prompt: record the invocation as
+        // `resolved` for the audit trail and return without pausing.
+        if (unwrapOrThrow(await selectGrant(pool, ctx.analysisId, request.grantKey ?? request.command))) {
             unwrapOrThrow(await insertGrantedAsk(pool, row, now));
             return { kind: "always" };
         }

package/dist/tools/approval/queries.d.ts

@@ -40,6 +40,8 @@ export interface AskRow {
     readonly title: string;
     readonly command: string;
     readonly detail: string | null;
+    /** Grant key an `always` keys its standing grant under; `null` falls back to `command`. */
+    readonly grantKey: string | null;
     readonly createdAt: string;
 }
 /** Insert a fresh `pending` ask before its decision is awaited. */
@@ -50,8 +52,8 @@ export declare function insertPendingAsk(querier: Querier, row: AskRow): ResultA
  * every approval-gated action. The recorded reply is `{ kind: "always" }`.
  */
 export declare function insertGrantedAsk(querier: Querier, row: AskRow, resolvedAt: string): ResultAsync<void, DbError>;
-/** Does a standing grant cover `(analysisId, command)` in this analysis? */
-export declare function selectGrant(querier: Querier, analysisId: string, command: string): ResultAsync<boolean, DbError>;
+/** Does a standing grant cover `(analysisId, grantKey)` in this analysis? */
+export declare function selectGrant(querier: Querier, analysisId: string, grantKey: string): ResultAsync<boolean, DbError>;
 /** Read a row's current status + recorded reply. `null` when no such row exists. */
 export declare function selectAskResolution(querier: Querier, id: string): ResultAsync<AskResolution | null, DbError>;
 /**

package/dist/tools/approval/queries.js

@@ -15,9 +15,9 @@ export function insertPendingAsk(querier, row) {
     return tryMutation("asks.insertPending", async () => {
         await querier.query({
             text: `INSERT INTO cortex_asks
-              (id, analysis_id, thread_id, title, command, detail, status, created_at)
-              VALUES ($1, $2, $3, $4, $5, $6, 'pending', $7)`,
-            values: [row.id, row.analysisId, row.threadId, row.title, row.command, row.detail, row.createdAt],
+              (id, analysis_id, thread_id, title, command, detail, grant_key, status, created_at)
+              VALUES ($1, $2, $3, $4, $5, $6, $7, 'pending', $8)`,
+            values: [row.id, row.analysisId, row.threadId, row.title, row.command, row.detail, row.grantKey ?? row.command, row.createdAt],
         });
     });
 }
@@ -30,18 +30,29 @@ export function insertGrantedAsk(querier, row, resolvedAt) {
     return tryMutation("asks.insertGranted", async () => {
         await querier.query({
             text: `INSERT INTO cortex_asks
-              (id, analysis_id, thread_id, title, command, detail, status, reply, created_at, resolved_at)
-              VALUES ($1, $2, $3, $4, $5, $6, 'resolved', $7::jsonb, $8, $9)`,
-            values: [row.id, row.analysisId, row.threadId, row.title, row.command, row.detail, JSON.stringify({ kind: "always" }), row.createdAt, resolvedAt],
+              (id, analysis_id, thread_id, title, command, detail, grant_key, status, reply, created_at, resolved_at)
+              VALUES ($1, $2, $3, $4, $5, $6, $7, 'resolved', $8::jsonb, $9, $10)`,
+            values: [
+                row.id,
+                row.analysisId,
+                row.threadId,
+                row.title,
+                row.command,
+                row.detail,
+                row.grantKey ?? row.command,
+                JSON.stringify({ kind: "always" }),
+                row.createdAt,
+                resolvedAt,
+            ],
         });
     });
 }
-/** Does a standing grant cover `(analysisId, command)` in this analysis? */
-export function selectGrant(querier, analysisId, command) {
+/** Does a standing grant cover `(analysisId, grantKey)` in this analysis? */
+export function selectGrant(querier, analysisId, grantKey) {
     return tryQuery("asks.selectGrant", async () => {
         const result = await querier.query({
-            text: `SELECT 1 FROM cortex_ask_grants WHERE analysis_id = $1 AND command = $2`,
-            values: [analysisId, command],
+            text: `SELECT 1 FROM cortex_ask_grants WHERE analysis_id = $1 AND grant_key = $2`,
+            values: [analysisId, grantKey],
         });
         return (result.rowCount ?? 0) > 0;
     });
@@ -114,19 +125,23 @@ export function answerAsk(pool, id, reply, now) {
     return withTransaction(pool, "asks.answer", (client) => tryMutation("asks.answer:update", () => client.query({
         text: `UPDATE cortex_asks SET status = $1, reply = $2::jsonb, resolved_at = $3
                   WHERE id = $4 AND status = 'pending'
-                  RETURNING analysis_id, command`,
+                  RETURNING analysis_id, COALESCE(grant_key, command) AS grant_key`,
         values: [status, JSON.stringify(reply), now, id],
     })).andThen((updated) => {
         if ((updated.rowCount ?? 0) === 0)
             return discriminateMiss(client, id);
         if (reply.kind !== "always")
             return okAsync("applied");
+        // The cast's non-null `grant_key` is sound without any boot-order
+        // caveat: every insert writes grant_key (command when the tool supplied
+        // none), and the COALESCE above covers any pending row that predates
+        // the column — `command` is NOT NULL, so the key can never be null.
         const granted = updated.rows[0];
         return tryMutation("asks.answer:grant", async () => {
             await client.query({
-                text: `INSERT INTO cortex_ask_grants (analysis_id, command, created_at)
-                      VALUES ($1, $2, $3) ON CONFLICT (analysis_id, command) DO NOTHING`,
-                values: [granted.analysis_id, granted.command, now],
+                text: `INSERT INTO cortex_ask_grants (analysis_id, grant_key, created_at)
+                      VALUES ($1, $2, $3) ON CONFLICT (analysis_id, grant_key) DO NOTHING`,
+                values: [granted.analysis_id, granted.grant_key, now],
             });
         }).map(() => "applied");
     }));

package/dist/tools/research/generate-plan.d.ts

@@ -41,6 +41,13 @@ export interface GeneratePlanDeps {
      * default guidance and validation skips the ceiling check.
      */
     readonly resourcePolicy?: ResourcePolicy;
+    /**
+     * Host path of the reference store, giving the planner reference discovery.
+     * Absent, the tool reports the store as unavailable and the planner keeps
+     * planning as though nothing is guaranteed present — which is what the prompt
+     * already tells it to do.
+     */
+    readonly refStorePath?: string;
 }
 /** Build the `generate_plan` tool bound to its provider and pool. */
 export declare function createGeneratePlanTool(deps: GeneratePlanDeps): Tool;

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 {};