@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/tools/research/web-search.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `web_search` — the web step of the conversation agent's research.
+ *
+ * The tool queries a `WebSearchEngine` the embedder injects at the composition
+ * root; the SearXNG realization ships beside it in `searxng-engine.ts`. The
+ * tool owns the input contract and the search semantics the spec pins — the
+ * domain-filter terms and the host re-filter, the queries merge, the bound —
+ * and every engine failure rides the ok channel as a data-status variant,
+ * never as an error of the turn.
+ */
+import { type Result } from "neverthrow";
+import { z } from "zod";
+import { type Tool } from "../define-tool.js";
+export type WebSearchAnswer = {
+    readonly answer?: string;
+    readonly url?: string;
+};
+export type WebSearchResult = {
+    readonly title: string;
+    readonly url: string;
+    readonly snippet?: string;
+};
+export type WebSearchOutput = {
+    readonly status: "ok";
+    readonly answers: readonly WebSearchAnswer[];
+    readonly results: readonly WebSearchResult[];
+} | {
+    readonly status: "http_error";
+    readonly httpStatus: number;
+    readonly text: string;
+} | {
+    readonly status: "retryable_status";
+    readonly httpStatus: number;
+    readonly text: string;
+} | {
+    readonly status: "schema_mismatch";
+    readonly text: string;
+} | {
+    readonly status: "not_json";
+    readonly text: string;
+    readonly detail?: string;
+};
+/** One query with its terms already composed: the engine adds transport, not semantics. */
+export type WebSearchRequest = {
+    /** The final query text, `site:` / `-site:` terms included. */
+    readonly query: string;
+    readonly recencyFilter?: "day" | "week" | "month" | "year";
+};
+/** What one query returned: the mapped answers and the mapped result rows. */
+export type WebSearchPage = {
+    readonly answers: readonly WebSearchAnswer[];
+    readonly results: readonly WebSearchResult[];
+};
+/** The error side of the engine result: the data-status variants the tool reports as normal results. */
+export type WebSearchEngineError = Exclude<WebSearchOutput, {
+    readonly status: "ok";
+}>;
+/**
+ * The injected web-search engine: an embedder supplies one realization, and the
+ * conversation agent attaches `web_search` iff it did. `search` gets the final
+ * query terms and the optional recency filter, and resolves to the page or to
+ * the error variant that names the failure.
+ */
+export type WebSearchEngine = {
+    search(request: WebSearchRequest): Promise<Result<WebSearchPage, WebSearchEngineError>>;
+};
+export type WebSearchToolDeps = {
+    /** The web-search engine the embedder injected. */
+    readonly engine: WebSearchEngine;
+};
+declare const WebSearchInputSchema: z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    queries: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    numResults: z.ZodDefault<z.ZodNumber>;
+    recencyFilter: z.ZodOptional<z.ZodEnum<{
+        day: "day";
+        month: "month";
+        week: "week";
+        year: "year";
+    }>>;
+    domainFilter: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare function createWebSearchTool(deps: WebSearchToolDeps): Tool<z.infer<typeof WebSearchInputSchema>, WebSearchOutput>;
+export {};

package/dist/tools/research/web-search.js

@@ -0,0 +1,117 @@
+/**
+ * `web_search` — the web step of the conversation agent's research.
+ *
+ * The tool queries a `WebSearchEngine` the embedder injects at the composition
+ * root; the SearXNG realization ships beside it in `searxng-engine.ts`. The
+ * tool owns the input contract and the search semantics the spec pins — the
+ * domain-filter terms and the host re-filter, the queries merge, the bound —
+ * and every engine failure rides the ok channel as a data-status variant,
+ * never as an error of the turn.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+function parseDomainFilter(raw) {
+    const trimmed = (raw ?? "").trim().toLowerCase();
+    if (trimmed === "" || trimmed === "-")
+        return null;
+    if (trimmed.startsWith("-")) {
+        const domain = trimmed.slice(1).trim();
+        return domain === "" ? null : { include: false, domain };
+    }
+    return { include: true, domain: trimmed };
+}
+function queryTerms(query, filter) {
+    if (!filter)
+        return query;
+    return `${query} ${filter.include ? "" : "-"}site:${filter.domain}`;
+}
+/** A domain matches a host and each subdomain of the domain. */
+function hostMatchesDomain(host, domain) {
+    return host === domain || host.endsWith(`.${domain}`);
+}
+function hostOf(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return null;
+    }
+}
+/** Filter the merged rows by host again, because an engine can ignore `site:`. */
+function applyDomainFilter(results, filter) {
+    if (!filter)
+        return [...results];
+    return results.filter((result) => {
+        const host = hostOf(result.url);
+        if (host === null)
+            return !filter.include;
+        const matches = hostMatchesDomain(host, filter.domain);
+        return filter.include ? matches : !matches;
+    });
+}
+const WebSearchInputSchema = z
+    .object({
+    query: z.string().min(1).optional().describe("One free-text search, for example a method name with its domain."),
+    queries: z
+        .array(z.string().min(1))
+        .min(1)
+        .max(5)
+        .optional()
+        .describe("Up to 5 searches that run in one pass. Answers and results merge into one bounded list."),
+    numResults: z.number().int().min(1).max(20).default(5).describe("Maximum merged results (1–20, default 5)."),
+    recencyFilter: z.enum(["day", "week", "month", "year"]).optional().describe("Keep only results from this recency."),
+    domainFilter: z.string().optional().describe('One domain the search stays in, for example "nih.gov". A leading "-" excludes the domain instead.'),
+})
+    .refine((input) => (input.query !== undefined) !== (input.queries !== undefined), {
+    message: "Give exactly one of `query` or `queries`.",
+});
+export function createWebSearchTool(deps) {
+    return defineTool({
+        id: "web_search",
+        description: "Search the web for pages: titles, URLs, and short snippets, plus any direct answers the engines returned. " +
+            "Give `query` for one search, or `queries` (at most 5) for one pass whose answers and results merge into a single " +
+            "list of at most `numResults` results, duplicates by URL removed. `domainFilter` restricts the search to one domain " +
+            'and a leading "-" excludes it, for example "-pinterest.com". `recencyFilter` keeps only results from the last day, ' +
+            "week, month, or year. Read one of the returned pages with `web_fetch`.\n" +
+            "ABSENCE IS NORMAL: an empty results array means no page matched, and a status of http_error, retryable_status, " +
+            "schema_mismatch, or not_json names a search that did not answer. Report either one and continue, do not retry unchanged.",
+        inputSchema: WebSearchInputSchema,
+        describeCall: "none",
+        execute: async ({ query, queries, numResults, recencyFilter, domainFilter }) => {
+            const filter = parseDomainFilter(domainFilter);
+            // The input refine guarantees exactly one of `query` and `queries`.
+            let queryList;
+            if (queries !== undefined)
+                queryList = queries;
+            else {
+                if (query === undefined)
+                    throw new Error("search requires query");
+                queryList = [query];
+            }
+            const requests = queryList.map((raw) => deps.engine.search({ query: queryTerms(raw, filter), recencyFilter }));
+            const responses = [];
+            for (const response of await Promise.all(requests)) {
+                // An engine failure is the data-status variant the tool reports, not a turn error.
+                if (response.isErr())
+                    return ok(response.error);
+                responses.push(response.value);
+            }
+            const answers = [];
+            const seen = new Set();
+            const results = [];
+            for (const response of responses) {
+                answers.push(...response.answers);
+                for (const result of applyDomainFilter(response.results, filter)) {
+                    if (results.length >= numResults)
+                        break;
+                    if (seen.has(result.url))
+                        continue;
+                    seen.add(result.url);
+                    results.push(result);
+                }
+            }
+            return ok({ status: "ok", answers, results });
+        },
+    });
+}

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

@@ -14,22 +14,26 @@
  * the prompt layer.
  */
 import { type Result } from "neverthrow";
+import { z } from "zod";
+import { type Tool } from "../define-tool.js";
 import { type PackageQuery } from "../../sandbox/package-identity.js";
 import type { ExtendAnalysisFarm, PackageRequestOutcome } from "../../sandbox/types.js";
-export interface LinkPackagesDeps {
+export type LinkPackagesDeps = {
     readonly extendAnalysisFarm: ExtendAnalysisFarm;
     readonly analysisId: string;
-}
+};
 /** The tool result: one outcome per requested query, index-aligned. */
-export interface LinkPackagesResult {
+export type LinkPackagesResult = {
     readonly outcomes: readonly PackageRequestOutcome[];
-}
+};
 /**
  * Call the seam, and give the outcomes or the one reason that the call gave
  * no answer. An `err` and a rejected realization each give that reason, thus
  * no call site sees a throw.
  */
 export declare function callExtendAnalysisFarm(extendAnalysisFarm: ExtendAnalysisFarm, analysisId: string, queries: readonly PackageQuery[]): Promise<Result<readonly PackageRequestOutcome[], string>>;
-export declare function createLinkPackagesTool(deps: LinkPackagesDeps): import("../define-tool.js").Tool<{
-    packages: string[];
-}, LinkPackagesResult>;
+declare const LinkPackagesInputSchema: z.ZodObject<{
+    packages: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare function createLinkPackagesTool(deps: LinkPackagesDeps): Tool<z.infer<typeof LinkPackagesInputSchema>, LinkPackagesResult>;
+export {};

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

@@ -13,6 +13,8 @@
  * capability, thus the agent learns one grammar for the plan, the tool, and
  * the prompt layer.
  */
+import { errorMessageOf } from "../../lib/thrown.js";
+import { textOf } from "../../lib/unknown-text.js";
 import { err, ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
@@ -44,9 +46,16 @@ export async function callExtendAnalysisFarm(extendAnalysisFarm, analysisId, que
         return (await extendAnalysisFarm(analysisId, queries)).mapErr((failure) => failure.reason);
     }
     catch (cause) {
-        return err(cause instanceof Error ? cause.message : String(cause));
+        return err(errorMessageOf(cause) ?? textOf(cause));
     }
 }
+const LinkPackagesInputSchema = z.object({
+    packages: z
+        .array(z.string().min(1))
+        .min(1)
+        .max(50)
+        .describe('The packages to link into the farm, each as `[python:|r:]<name>[==<version>]`, for example ["scanpy", "r:Seurat", "numpy==1.26.4"]. A bare name searches both tracks.'),
+});
 export function createLinkPackagesTool(deps) {
     return defineTool({
         id: "link_packages",
@@ -60,13 +69,7 @@ export function createLinkPackagesTool(deps) {
             "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). " +
             "After a `collision` of one name that BOTH tracks hold, call this tool again for that package with the prefixed form, `python:<name>` or `r:<name>`. " +
             "A collision is terminal only after that second call also refuses, or when it names two versions of one distribution — then report it and continue without the package.",
-        inputSchema: z.object({
-            packages: z
-                .array(z.string().min(1))
-                .min(1)
-                .max(50)
-                .describe('The packages to link into the farm, each as `[python:|r:]<name>[==<version>]`, for example ["scanpy", "r:Seurat", "numpy==1.26.4"]. A bare name searches both tracks.'),
-        }),
+        inputSchema: LinkPackagesInputSchema,
         describeCall: ({ packages }) => packages.join(", "),
         execute: async (input) => {
             // Every entry parses before any link lands. A partial link over a

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

@@ -19,6 +19,8 @@
  * content hash where the source records them. A full listing carries no
  * hashes — a thousand rows of sha256 would bury the signal.
  */
+import { z } from "zod";
+import { type Tool } from "../define-tool.js";
 import type { EnvironmentStorePaths, PoolInventoryPackage, PoolInventorySection } from "../../config/environment-stores.js";
 import { type Track } from "../../sandbox/package-identity.js";
 import { type FarmLock } from "../../sandbox/farm.js";
@@ -41,13 +43,16 @@ export declare function trackOfLockSubtree(subtree: string): Track | undefined;
  */
 export declare function lockSections(lock: FarmLock): Section[];
 /**
- * Group the image record into its two sections, in the order of the record.
- * An empty track yields no section, so the report never carries a heading
- * with nothing under it.
+ * Group the image record into its sections, in the order of the record. An
+ * empty or absent track yields no section, so the report never carries a
+ * heading with nothing under it.
  *
  * A `system_tools` row renders its `executable` name where the record gives
  * one, because an agent invokes the binary rather than the conda package
- * (the manifest `binaries:` map holds the pairs that differ).
+ * (the manifest `binaries:` map holds the pairs that differ). The `r_base`
+ * rows are the R track: a `names` lookup of `survival` or `MASS` resolves
+ * there, with the version the runtime ships, and the `language: "r"` filter
+ * lists them beside the farm packages.
  */
 export declare function imageSections(record: ImagePackages): Section[];
 /** One package entry of a section, with the store identity where the source records it. */
@@ -97,12 +102,12 @@ export type PackagesResult = {
     readonly content: string;
 };
 /** The tool's input, as parsed from `inputSchema`. */
-export interface PackagesQuery {
+export type 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.
@@ -147,9 +152,16 @@ export declare function readInventorySections(deps: ListAvailablePackagesDeps, a
  * host-readable farm `inflexa.lock` otherwise (a sandbox agent). The image
  * record merges into either report.
  */
-export declare function createListAvailablePackagesTool(deps?: ListAvailablePackagesDeps): import("../define-tool.js").Tool<{
-    names?: string[] | undefined;
-    query?: string | undefined;
-    language?: "r" | "python" | "node" | "cli" | undefined;
-    limit?: number | undefined;
-}, PackagesResult>;
+declare const ListAvailablePackagesInputSchema: z.ZodObject<{
+    names: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    query: z.ZodOptional<z.ZodString>;
+    language: z.ZodOptional<z.ZodEnum<{
+        cli: "cli";
+        node: "node";
+        python: "python";
+        r: "r";
+    }>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare function createListAvailablePackagesTool(deps?: ListAvailablePackagesDeps): Tool<z.infer<typeof ListAvailablePackagesInputSchema>, PackagesResult>;
+export {};

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

@@ -20,6 +20,9 @@
  * hashes — a thousand rows of sha256 would bury the signal.
  */
 import { ok } from "neverthrow";
+import { presentGet } from "../../lib/present.js";
+import { errorMessageOf } from "../../lib/thrown.js";
+import { textOf } from "../../lib/unknown-text.js";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
 import { identityAddress, identityKey, identityOf, parseQuery, resolveQuery, } from "../../sandbox/package-identity.js";
@@ -53,6 +56,8 @@ const DEFAULT_IMAGE_PACKAGES_FILE = `${LIBS_CONTAINER_PATH}/${IMAGE_PACKAGES_FIL
  */
 const CLI_TITLE = "System tools (CLI)";
 const NODE_TITLE = "Node (npm)";
+/** The R packages that ship with the R runtime of the image: the base and the recommended packages. */
+const R_BASE_TITLE = "R (ships with R)";
 /** The section title of each known lock track. An unknown track titles itself. */
 const TRACK_TITLES = {
     python: "Python (pip)",
@@ -97,20 +102,26 @@ export function lockSections(lock) {
         .filter(([, packages]) => packages.length > 0)
         .map(([subtree, packages]) => {
         const track = trackOfLockSubtree(subtree);
-        return { title: TRACK_TITLES[subtree] ?? subtree, packages, ...(track === undefined ? {} : { track }) };
+        return { title: TRACK_TITLES[subtree] ?? subtree, packages, track };
     });
 }
 /**
- * Group the image record into its two sections, in the order of the record.
- * An empty track yields no section, so the report never carries a heading
- * with nothing under it.
+ * Group the image record into its sections, in the order of the record. An
+ * empty or absent track yields no section, so the report never carries a
+ * heading with nothing under it.
  *
  * A `system_tools` row renders its `executable` name where the record gives
  * one, because an agent invokes the binary rather than the conda package
- * (the manifest `binaries:` map holds the pairs that differ).
+ * (the manifest `binaries:` map holds the pairs that differ). The `r_base`
+ * rows are the R track: a `names` lookup of `survival` or `MASS` resolves
+ * there, with the version the runtime ships, and the `language: "r"` filter
+ * lists them beside the farm packages.
  */
 export function imageSections(record) {
     const sections = [];
+    if (record.r_base !== undefined && record.r_base.length > 0) {
+        sections.push({ title: R_BASE_TITLE, track: "r", packages: record.r_base.map((pkg) => ({ name: pkg.name, version: pkg.version })) });
+    }
     if (record.system_tools.length > 0) {
         sections.push({
             title: CLI_TITLE,
@@ -152,7 +163,7 @@ function foldSections(sections) {
             open.packages.push(pkg);
         }
     }
-    return [...byTitle.values()].map(({ title, track, packages }) => ({ title, packages, ...(track === undefined ? {} : { track }) }));
+    return [...byTitle.values()].map(({ title, track, packages }) => ({ title, packages, track }));
 }
 /**
  * Default cap on a listing — high enough that the real store is never truncated.
@@ -188,7 +199,9 @@ const POOL_UNAVAILABLE_NOTE = "Package list not available — the package pool c
  */
 const LANGUAGE_MATCHERS = {
     // `CLI_TITLE` — the conda-installed bioinformatics executables.
+    // oxlint-disable-next-line eslint-js/no-restricted-syntax -- the section heading names the executables section or the standalone word CLI, matched in display text.
     cli: (t) => /system tools|\bcli\b/i.test(t),
+    // oxlint-disable-next-line eslint-js/no-restricted-syntax -- the heading opens with the word node, the display form of the section name.
     node: (t) => /^node\b/i.test(t),
 };
 /** Whether one section answers the `language` filter of a call. */
@@ -197,7 +210,7 @@ function matchesLanguage(section, language) {
         return true;
     if (language === "r" || language === "python")
         return section.track === language;
-    return LANGUAGE_MATCHERS[language](section.title);
+    return presentGet(LANGUAGE_MATCHERS, language, `the heading matcher for ${language}`)(section.title);
 }
 /**
  * The identity names that the Python track and the R track both hold.
@@ -287,9 +300,9 @@ function presentEntry(requested, row) {
         present: true,
         name: row.entry.name,
         section: row.section,
-        ...(row.entry.version === undefined ? {} : { version: row.entry.version }),
-        ...(row.entry.storeDir === undefined ? {} : { storeDir: row.entry.storeDir }),
-        ...(row.entry.hash === undefined ? {} : { hash: row.entry.hash }),
+        version: row.entry.version,
+        storeDir: row.entry.storeDir,
+        hash: row.entry.hash,
     };
 }
 /**
@@ -357,7 +370,7 @@ export function queryPackages(rawSections, { names, query, language, limit }) {
             if (hits.length > 0)
                 return hits;
             const suggestion = resolution.kind === "unknown" ? resolution.suggestion : undefined;
-            return [{ requested, present: false, ...(suggestion === undefined ? {} : { suggestion: suggestion.name }) }];
+            return [{ requested, present: false, suggestion: suggestion?.name }];
         });
         return { available: true, checked };
     }
@@ -371,7 +384,7 @@ export function queryPackages(rawSections, { names, query, language, limit }) {
         .map((s) => ({
         title: s.title,
         packages: needle ? s.packages.filter((p) => p.name.toLowerCase().includes(needle)) : s.packages,
-        ...(s.track === undefined ? {} : { track: s.track }),
+        track: s.track,
     }))
         .filter((s) => s.packages.length > 0);
     const total = filtered.reduce((n, s) => n + s.packages.length, 0);
@@ -414,7 +427,7 @@ export async function readInventorySections(deps, analysisId) {
     if (deps.readPoolInventory) {
         const pool = await deps.readPoolInventory().catch((cause) => ({
             kind: "unavailable",
-            reason: cause instanceof Error ? cause.message : String(cause),
+            reason: errorMessageOf(cause) ?? textOf(cause),
         }));
         if (pool.kind === "unavailable")
             return { kind: "unavailable", reason: pool.reason };
@@ -441,6 +454,22 @@ export async function readInventorySections(deps, analysisId) {
  * host-readable farm `inflexa.lock` otherwise (a sandbox agent). The image
  * record merges into either report.
  */
+const ListAvailablePackagesInputSchema = z.object({
+    names: z
+        .array(z.string())
+        .max(100)
+        .optional()
+        .describe("Check these packages for presence. Each entry is a query in the one grammar, `[python:|r:]<name>`. Returns one entry for each track that holds the name: present/absent + the language track it lives in. An absent name carries the spelling the pool holds, where there is one."),
+    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.`),
+});
 export function createListAvailablePackagesTool(deps = {}) {
     const readPoolInventory = deps.readPoolInventory;
     // The scope decides the framing sentence: a sandbox agent reads what it can
@@ -465,22 +494,7 @@ export function createListAvailablePackagesTool(deps = {}) {
             "`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. " +
             "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())
-                .max(100)
-                .optional()
-                .describe("Check these packages for presence. Each entry is a query in the one grammar, `[python:|r:]<name>`. Returns one entry for each track that holds the name: present/absent + the language track it lives in. An absent name carries the spelling the pool holds, where there is one."),
-            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.`),
-        }),
+        inputSchema: ListAvailablePackagesInputSchema,
         // `queryPackages` returns on `names` before it reads another field, thus
         // the presence check comes first. An empty array is not a presence check.
         // `names` are exact identifiers a caller checks for, thus they name the

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

@@ -27,9 +27,17 @@
  * 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 { z } from "zod";
 import type { EnvironmentStorePaths } from "../../config/environment-stores.js";
+import { type Tool } from "../define-tool.js";
+declare const ListAvailableRefsInputSchema: z.ZodObject<{
+    path: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    query: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 export type ListAvailableRefsDeps = Pick<EnvironmentStorePaths, "refStorePath">;
-export interface ReferenceInventoryMetadata {
+export type ReferenceInventoryMetadata = {
     readonly datasetId?: string;
     readonly version?: string;
     readonly title?: string;
@@ -45,11 +53,11 @@ export interface ReferenceInventoryMetadata {
     readonly contents?: string;
     readonly rows?: number;
     readonly endpoint?: string;
-}
-interface ReferenceInventoryEntryBase {
+};
+type ReferenceInventoryEntryBase = {
     readonly path: string;
     readonly metadata?: ReferenceInventoryMetadata;
-}
+};
 /** A bounded, no-follow observation of the reference store. */
 export type ReferenceInventoryEntry = (ReferenceInventoryEntryBase & {
     readonly kind: "file";
@@ -69,7 +77,7 @@ export type ReferenceInventoryEntry = (ReferenceInventoryEntryBase & {
  * 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 {
+export type ReferenceInventoryResult = {
     readonly available: boolean;
     readonly state: RawScan["state"] | "out_of_scope";
     readonly path: string;
@@ -81,20 +89,36 @@ export interface ReferenceInventoryResult {
     readonly hasMore: boolean;
     readonly categories: readonly string[];
     readonly content: string;
-}
-interface RawScan {
+};
+type 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[];
-}
+};
+/**
+ * The dataset ids the install receipts of the store report, for a caller that must know whether a
+ * declared dataset is present BEFORE a run starts.
+ *
+ * `undefined` means the store itself could not be answered for: an unreadable root, a `.inflexa`
+ * that crosses a symlink, or a receipts directory that exists and cannot be listed. That is NOT an
+ * empty install, and a caller must never collapse the two — every dataset would read as absent, and
+ * a launch would be refused over data that is sitting in the store.
+ *
+ * An empty set is a real answer: the store is readable and it holds no receipt.
+ */
+export declare function readInstalledDatasetIds(deps: ListAvailableRefsDeps): Promise<ReadonlySet<string> | undefined>;
 /** 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>;
+/**
+ * The whole enriched inventory of the store, for a host-side join: which
+ * collection a procedure names is present, and where. No envelope bound,
+ * because the caller keeps the join and drops the listing.
+ */
+export declare function readReferenceInventory(storeRoot: string): Promise<{
+    readonly available: boolean;
+    readonly entries: readonly ReferenceInventoryEntry[];
+}>;
+export declare function createListAvailableRefsTool(deps: ListAvailableRefsDeps): Tool<z.infer<typeof ListAvailableRefsInputSchema>, ReferenceInventoryResult>;
 export {};