@inflexa-ai/harness 0.45.0 → 0.46.0

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

@@ -32,6 +32,10 @@ import { join as hostJoin, posix as posixPath } from "node:path";
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { capCodePoints, DETAIL_MAX_LENGTH, DETAIL_NEEDLE_MAX_LENGTH } from "../../loop/tool-detail.js";
+import { errnoOf } from "../../lib/fs-result.js";
+import { parseJsonAs } from "../../lib/parse-json.js";
+import { isUnknownArray } from "../../lib/unknown-array.js";
+import { parseUnknownRecord } from "../../lib/unknown-containers.js";
 import { REFERENCE_DATA_CATALOG } from "../../reference-data/catalog.js";
 import { parseReferenceInstallReceipt } from "../../reference-data/receipt.js";
 import { REFS_CONTAINER_PATH } from "../../sandbox/mount-plan.js";
@@ -158,6 +162,8 @@ async function summarizeDirectory(directory, scanned) {
     const stack = [directory];
     while (stack.length > 0 && scanned < MAX_SCANNED_ENTRIES) {
         const current = stack.pop();
+        if (current === undefined)
+            break;
         const { values, cut } = await cappedEntries(current, MAX_SCANNED_ENTRIES - scanned);
         truncated = truncated || cut;
         const childDirectories = [];
@@ -196,7 +202,7 @@ async function readReceipts(root) {
         // A shared try would abandon the loop and silently drop every receipt sorting
         // after the bad one, quietly stripping metadata from datasets that are fine.
         try {
-            receipts.push(JSON.parse(await readFile(hostJoin(receiptsDirectory, entry.name), "utf-8")));
+            receipts.push(parseJsonAs(await readFile(hostJoin(receiptsDirectory, entry.name), "utf-8"), z.json()));
             totalBytes += entry.bytes;
         }
         catch {
@@ -205,6 +211,54 @@ async function readReceipts(root) {
     }
     return receipts;
 }
+/**
+ * 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 async function readInstalledDatasetIds(deps) {
+    const storeRoot = deps.refStorePath ?? REFS_ROOT;
+    try {
+        await lstat(storeRoot);
+    }
+    catch {
+        return undefined;
+    }
+    if (await crossesSymlink(storeRoot, ".inflexa"))
+        return undefined;
+    const receiptsDirectory = hostJoin(storeRoot, ".inflexa", "receipts");
+    let names;
+    try {
+        names = (await readdir(receiptsDirectory)).slice(0, MAX_RECEIPT_FILES);
+    }
+    catch (error) {
+        // An absent directory is a readable store with nothing installed. Any other failure is the
+        // store declining to answer, which is a different fact and gets the honest `undefined`.
+        if (errnoOf(error) === "ENOENT")
+            return new Set();
+        return undefined;
+    }
+    const ids = new Set();
+    for (const name of names) {
+        // Per-file, so one malformed receipt costs only its own dataset. A shared try would drop
+        // every receipt after the bad one and read as a store that holds almost nothing.
+        try {
+            const receipt = parseReferenceInstallReceipt(parseJsonAs(await readFile(hostJoin(receiptsDirectory, name), "utf-8"), z.json()));
+            if (receipt)
+                ids.add(receipt.datasetId);
+        }
+        catch {
+            continue;
+        }
+    }
+    return ids;
+}
 /** Labels from a `registry.json` an externally-provisioned store may carry. */
 async function readLegacyEntries(root) {
     const legacyEntries = [];
@@ -214,21 +268,24 @@ async function readLegacyEntries(root) {
         const registryPath = hostJoin(root, "registry.json");
         if ((await lstat(registryPath)).size > MAX_REGISTRY_BYTES)
             return [];
-        const registry = JSON.parse(await readFile(registryPath, "utf-8"));
-        if (!registry || typeof registry !== "object")
+        const registry = parseJsonAs(await readFile(registryPath, "utf-8"), z.json());
+        const registryRecord = parseUnknownRecord(registry);
+        if (!registryRecord)
             return [];
-        const byCategory = registry.files?.by_category;
-        if (!byCategory || typeof byCategory !== "object")
+        const files = parseUnknownRecord(registryRecord.files);
+        const categories = parseUnknownRecord(files?.by_category);
+        if (!categories)
             return [];
-        for (const category of Object.keys(byCategory).sort()) {
-            const values = byCategory[category];
-            if (!Array.isArray(values))
+        for (const category of Object.keys(categories).sort()) {
+            const values = categories[category];
+            if (!isUnknownArray(values))
                 continue;
             for (const item of values) {
                 if (legacyEntries.length >= MAX_LEGACY_ENTRIES)
                     break;
-                if (item && typeof item === "object" && typeof item.local_path === "string") {
-                    legacyEntries.push({ ...item, category });
+                const itemRecord = parseUnknownRecord(item);
+                if (itemRecord && typeof itemRecord.local_path === "string") {
+                    legacyEntries.push({ ...itemRecord, category });
                 }
             }
         }
@@ -253,6 +310,8 @@ async function collectFiles(directory, relative, budget) {
     const stack = [{ path: directory, relative }];
     while (stack.length > 0 && budget.scanned < MAX_SCANNED_ENTRIES) {
         const current = stack.pop();
+        if (current === undefined)
+            break;
         const { values, cut } = await cappedEntries(current.path, MAX_SCANNED_ENTRIES - budget.scanned);
         truncated = truncated || cut;
         for (const child of values) {
@@ -391,41 +450,55 @@ function enrichEntries(entries, raw) {
             // Per-artifact, not per-dataset: format and contents differ between files of the
             // same dataset (a Seurat object and its Annoy index are read nothing alike).
             const catalogArtifact = dataset?.artifacts.find((candidate) => candidate.path === artifact.path);
-            metadata.set(`${REFS_ROOT}/managed/${receipt.datasetId}/${receipt.datasetVersion}/${artifact.path}`, {
+            const managedMetadata = {
                 datasetId: receipt.datasetId,
                 version: receipt.datasetVersion,
-                ...(dataset
-                    ? {
-                        title: dataset.title,
-                        description: dataset.description,
-                        sourceUrl: dataset.sourceUrl,
-                        license: dataset.license.url ?? dataset.license.identifier,
-                        category: dataset.recommendation.group,
-                        ...(dataset.organism ? { organism: dataset.organism } : {}),
-                    }
-                    : {}),
-                ...(catalogArtifact ? { format: catalogArtifact.format, contents: catalogArtifact.contents } : {}),
-            });
+            };
+            if (dataset) {
+                managedMetadata.title = dataset.title;
+                managedMetadata.description = dataset.description;
+                managedMetadata.sourceUrl = dataset.sourceUrl;
+                managedMetadata.license = dataset.license.url ?? dataset.license.identifier;
+                managedMetadata.category = dataset.recommendation.group;
+                if (dataset.organism)
+                    managedMetadata.organism = dataset.organism;
+            }
+            if (catalogArtifact) {
+                managedMetadata.format = catalogArtifact.format;
+                managedMetadata.contents = catalogArtifact.contents;
+            }
+            metadata.set(`${REFS_ROOT}/managed/${receipt.datasetId}/${receipt.datasetVersion}/${artifact.path}`, managedMetadata);
         }
     }
     for (const value of raw.legacyEntries ?? []) {
-        if (!value || typeof value !== "object")
+        const item = parseUnknownRecord(value);
+        if (!item)
             continue;
-        const item = value;
         const localPath = stringValue(item.local_path);
         if (!localPath)
             continue;
         const resolved = resolveRequestedPath(localPath);
         if (!resolved.ok)
             continue;
-        const legacyMetadata = {
-            ...(stringValue(item.dataset) ? { datasetId: stringValue(item.dataset) } : {}),
-            ...(stringValue(item.category) ? { category: stringValue(item.category) } : {}),
-            ...(stringValue(item.subtype) ? { subtype: stringValue(item.subtype) } : {}),
-            ...(stringValue(item.organism) ? { organism: stringValue(item.organism) } : {}),
-            ...(numberValue(item.rows) !== undefined ? { rows: numberValue(item.rows) } : {}),
-            ...(stringValue(item.endpoint) ? { endpoint: stringValue(item.endpoint) } : {}),
-        };
+        const datasetId = stringValue(item.dataset);
+        const category = stringValue(item.category);
+        const subtype = stringValue(item.subtype);
+        const organism = stringValue(item.organism);
+        const rows = numberValue(item.rows);
+        const endpoint = stringValue(item.endpoint);
+        const legacyMetadata = {};
+        if (datasetId)
+            legacyMetadata.datasetId = datasetId;
+        if (category)
+            legacyMetadata.category = category;
+        if (subtype)
+            legacyMetadata.subtype = subtype;
+        if (organism)
+            legacyMetadata.organism = organism;
+        if (rows !== undefined)
+            legacyMetadata.rows = rows;
+        if (endpoint)
+            legacyMetadata.endpoint = endpoint;
         metadata.set(resolved.path, { ...legacyMetadata, ...metadata.get(resolved.path) });
     }
     return entries.map((entry) => {
@@ -465,8 +538,8 @@ function collectCategories(entries) {
 }
 function renderContent(path, scan, entries) {
     if (scan.state === "unavailable")
-        return ("No reference store is provisioned. Nothing in the analysis environment can fetch reference data — the host stages it, " +
-            "so a store provisioned through the host's own path will show up on a later call.");
+        return ("No reference store is provisioned for this session. Nothing in the analysis environment can fetch reference data, and a later call " +
+            "in this run gives the same answer. Plan with the data at hand, or ask for the reference by what it is.");
     if (scan.state === "not_found")
         return `Reference path does not exist: ${path}`;
     if (scan.state === "not_a_directory")
@@ -499,6 +572,15 @@ function renderContent(path, scan, entries) {
     return lines.join("\n");
 }
 /** Create reference discovery over the host-visible reference store. */
+/**
+ * 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 async function readReferenceInventory(storeRoot) {
+    const raw = await scanStore(storeRoot, ".", true);
+    return { available: raw.state !== "unavailable", entries: enrichEntries(raw.entries, raw) };
+}
 export function createListAvailableRefsTool(deps) {
     const storeRoot = deps.refStorePath ?? REFS_ROOT;
     return defineTool({
@@ -516,7 +598,7 @@ export function createListAvailableRefsTool(deps) {
             "pass a group label as `query`, because `category` inspects a top-level directory by name and a label that is not a directory reads as `not_found`; " +
             "`limit` caps the entries returned. The response carries `returned`, `total`, and `hasMore`, so truncation is never silent. " +
             "An empty result means the dataset is absent right now — not that it is unobtainable. Say so; never guess a path, and never silently substitute a different dataset. " +
-            "The store is provisioned by the host and is NOT frozen: datasets can be added through the host's own provisioning path, and whatever is added shows up on a later call.",
+            "The store is provisioned by the host and is NOT frozen: datasets can be added through the host's own provisioning path between runs, and whatever is added shows up in a later run. Within one run the listing does not change, thus one call per question is enough.",
         inputSchema: ListAvailableRefsInputSchema,
         // `execute` resolves `path ?? category` for the subtree it inspects, and
         // it ignores `category` when `path` is present. `query` is an ADDITIVE
@@ -551,7 +633,7 @@ export function createListAvailableRefsTool(deps) {
             // The budget comes off the rendered filter, never off a count of its
             // parts, thus it cannot drift from the template above. One code point
             // pays for the joining space.
-            return `${capCodePoints(named, DETAIL_MAX_LENGTH - [...filter].length - 1)} ${filter}`;
+            return `${capCodePoints(named, DETAIL_MAX_LENGTH - Array.from(filter).length - 1)} ${filter}`;
         },
         execute: async ({ path, category, query, limit }) => {
             // `category` is shorthand for a top-level path; an explicit `path` wins.

package/dist/tools/sandbox/report-blocker.d.ts

@@ -10,57 +10,50 @@
  * sandbox step agent, the planner (`tools/research/generate-plan.ts`), the
  * run synthesizer (`execution/run-synthesis.ts`) and the analogical reasoner
  * (`tools/research/generate-analogy-report.ts`) — and all four share one id,
- * one input schema and one terminal contract via `createReportBlockerToolFor`.
- * What differs per loop is only what a blocker *means* there, so each call site
- * injects its own `blockedWhen` prose and its own capture closure. The tool
- * records the reason and tells the agent to stop; the driving body reads the
- * outcome after the loop and decides the terminal status. The sandbox step body
- * runs in durable steps, so it reads the blocker back from the transcript
- * (`recordedBlocker`) on replay, not only from its cell.
+ * one input schema and one result via `createReportBlockerToolFor`. What
+ * differs per loop is only what a blocker *means* there, so each call site
+ * injects its own `blockedWhen` prose. The result of the call carries the
+ * reason, and the driving body selects the blocker from the recorded calls of
+ * the run (`blockerOf`). Thus a replay selects the same blocker.
  */
-import type { ModelMessage } from "ai";
+import { z } from "zod";
+import type { LoopStep } from "../../loop/run-loop.js";
 import { type Tool } from "../define-tool.js";
 export declare const REPORT_BLOCKER_TOOL_ID = "report_blocker";
-export interface BlockerOutcome {
+export type BlockerOutcome = {
     readonly kind: "blocker";
     readonly reason: string;
-}
-/** Per-run mutable cell the sandbox-step body reads after the loop. */
-export interface BlockerHolder {
-    outcome: BlockerOutcome | null;
-}
-export declare function createBlockerHolder(): BlockerHolder;
-export interface ReportBlockerDeps {
-    /**
-     * The calling loop's blocker-capture side effect — writes the outcome into
-     * whatever cell that body reads after its loop. Invoked on every call; the
-     * closure owns the first-call-wins guard, because only the call site knows
-     * what else may already have terminated its loop.
-     */
-    readonly record: (outcome: BlockerOutcome) => void;
+};
+/** The one input every `report_blocker` takes, wherever it is offered. */
+declare const ReportBlockerInputSchema: z.ZodObject<{
+    reason: z.ZodString;
+}, z.core.$strip>;
+/** The result of a call: the blocker that the call recorded. */
+declare const BlockerResultSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"blocker">;
+    reason: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+type BlockerResult = z.infer<typeof BlockerResultSchema>;
+export type ReportBlockerDeps = {
     /**
      * What a blocker means in THIS loop: which loop the call ends and the
      * conditions that warrant it. Composed into the shared terminal contract,
      * so a description can never promise a loop this instance does not end.
      */
     readonly blockedWhen: string;
-}
+};
 /**
  * Build the `report_blocker` tool for one loop. The id, the input schema and
  * the terminal contract ("pass a reason, then stop") are fixed here; the call
- * site supplies only the per-loop meaning and the capture closure.
- */
-export declare function createReportBlockerToolFor(deps: ReportBlockerDeps): Tool;
-/**
- * The blocker that a run recorded, read from its transcript: the reason of the
- * first `report_blocker` call, in call order, whose result is ok.
- *
- * A replay returns each tool step's cached result without re-running
- * `execute`, so the in-memory cell is empty on replay; the transcript is not.
+ * site supplies only the per-loop meaning.
  */
-export declare function recordedBlocker(messages: readonly ModelMessage[]): BlockerOutcome | null;
+export declare function createReportBlockerToolFor(deps: ReportBlockerDeps): Tool<z.infer<typeof ReportBlockerInputSchema>, BlockerResult>;
+/** The blocker that a run recorded: the reason of the first `report_blocker` call, in call order, whose result is ok. */
+export declare function blockerOf(steps: readonly LoopStep[]): BlockerOutcome | null;
 /**
- * The sandbox step agent's `report_blocker`, bound to the step body's holder.
- * A blocker here ends the step with no deliverables and a blocked reason.
+ * The sandbox step agent's `report_blocker`. A blocker here ends the step with
+ * no deliverables and a blocked reason.
  */
-export declare function createReportBlockerTool(holder: BlockerHolder): Tool;
+export declare function createReportBlockerTool(): Tool;
+export {};

package/dist/tools/sandbox/report-blocker.js

@@ -10,34 +10,27 @@
  * sandbox step agent, the planner (`tools/research/generate-plan.ts`), the
  * run synthesizer (`execution/run-synthesis.ts`) and the analogical reasoner
  * (`tools/research/generate-analogy-report.ts`) — and all four share one id,
- * one input schema and one terminal contract via `createReportBlockerToolFor`.
- * What differs per loop is only what a blocker *means* there, so each call site
- * injects its own `blockedWhen` prose and its own capture closure. The tool
- * records the reason and tells the agent to stop; the driving body reads the
- * outcome after the loop and decides the terminal status. The sandbox step body
- * runs in durable steps, so it reads the blocker back from the transcript
- * (`recordedBlocker`) on replay, not only from its cell.
+ * one input schema and one result via `createReportBlockerToolFor`. What
+ * differs per loop is only what a blocker *means* there, so each call site
+ * injects its own `blockedWhen` prose. The result of the call carries the
+ * reason, and the driving body selects the blocker from the recorded calls of
+ * the run (`blockerOf`). Thus a replay selects the same blocker.
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
-import { repairToolInput } from "../../lib/zod-issues.js";
-import { toolOutcomeForOutputType } from "../../loop/tool-outcome.js";
+import { terminalTextSchema } from "../terminal-text.js";
 import { defineTool } from "../define-tool.js";
 export const REPORT_BLOCKER_TOOL_ID = "report_blocker";
-export function createBlockerHolder() {
-    return { outcome: null };
-}
 /** The one input every `report_blocker` takes, wherever it is offered. */
 const ReportBlockerInputSchema = z.object({
-    reason: z
-        .string()
-        .min(1)
-        .describe("What blocks the work, stated as a fact: the missing or unreadable input, or the capability that is not available, and what you tried."),
+    reason: terminalTextSchema("What blocks the work, stated as a fact: the missing or unreadable input, or the capability that is not available, and what you tried."),
 });
+/** The result of a call: the blocker that the call recorded. */
+const BlockerResultSchema = z.object({ kind: z.literal("blocker"), reason: z.string(), message: z.string() });
 /**
  * Build the `report_blocker` tool for one loop. The id, the input schema and
  * the terminal contract ("pass a reason, then stop") are fixed here; the call
- * site supplies only the per-loop meaning and the capture closure.
+ * site supplies only the per-loop meaning.
  */
 export function createReportBlockerToolFor(deps) {
     return defineTool({
@@ -45,67 +38,28 @@ export function createReportBlockerToolFor(deps) {
         description: `Terminal. ${deps.blockedWhen} Pass a clear reason. Stop immediately after calling — take no further actions.`,
         inputSchema: ReportBlockerInputSchema,
         describeCall: "none",
-        execute: async (input) => {
-            deps.record({ kind: "blocker", reason: input.reason });
-            return ok({
-                recorded: true,
-                message: "Blocker recorded. You are done — stop now and do not take further actions.",
-            });
-        },
+        execute: (input) => Promise.resolve(ok({ kind: "blocker", reason: input.reason, message: "Blocker recorded. You are done — stop now and do not take further actions." })),
     });
 }
-/**
- * The blocker that a run recorded, read from its transcript: the reason of the
- * first `report_blocker` call, in call order, whose result is ok.
- *
- * A replay returns each tool step's cached result without re-running
- * `execute`, so the in-memory cell is empty on replay; the transcript is not.
- */
-export function recordedBlocker(messages) {
-    const recorded = new Set();
-    for (const message of messages) {
-        if (message.role !== "tool")
-            continue;
-        for (const part of message.content) {
-            if (part.type === "tool-result" && part.toolName === REPORT_BLOCKER_TOOL_ID && toolOutcomeForOutputType(part.output.type) === "ok") {
-                recorded.add(part.toolCallId);
-            }
-        }
-    }
-    for (const message of messages) {
-        if (message.role !== "assistant" || typeof message.content === "string")
-            continue;
-        for (const part of message.content) {
-            if (part.type !== "tool-call" || part.toolName !== REPORT_BLOCKER_TOOL_ID || !recorded.has(part.toolCallId))
+/** The blocker that a run recorded: the reason of the first `report_blocker` call, in call order, whose result is ok. */
+export function blockerOf(steps) {
+    for (const step of steps) {
+        for (const call of step.calls) {
+            if (call.toolName !== REPORT_BLOCKER_TOOL_ID || call.output?.outcome !== "ok")
                 continue;
-            const reason = blockerReason(part.input);
-            if (reason !== undefined)
-                return { kind: "blocker", reason };
+            const result = BlockerResultSchema.safeParse(call.output.value);
+            if (result.success)
+                return { kind: "blocker", reason: result.data.reason };
         }
     }
     return null;
 }
-/** The reason of a `report_blocker` input, validated as the dispatch validates it. */
-function blockerReason(input) {
-    const parsed = ReportBlockerInputSchema.safeParse(input);
-    if (parsed.success)
-        return parsed.data.reason;
-    const repaired = repairToolInput(input, parsed.error);
-    if (repaired === undefined)
-        return undefined;
-    const reparsed = ReportBlockerInputSchema.safeParse(repaired);
-    return reparsed.success ? reparsed.data.reason : undefined;
-}
 /**
- * The sandbox step agent's `report_blocker`, bound to the step body's holder.
- * A blocker here ends the step with no deliverables and a blocked reason.
+ * The sandbox step agent's `report_blocker`. A blocker here ends the step with
+ * no deliverables and a blocked reason.
  */
-export function createReportBlockerTool(holder) {
+export function createReportBlockerTool() {
     return createReportBlockerToolFor({
-        record: (outcome) => {
-            if (holder.outcome === null)
-                holder.outcome = outcome;
-        },
         blockedWhen: "Ends this analysis step with no deliverables. Call it when you cannot " +
             "fulfil the step — required inputs are missing or unreadable, the " +
             "requested analysis is infeasible with the available data/packages, or " +

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

@@ -13,19 +13,21 @@
  * reference. Expected outcomes are data variants — never throws on a missing
  * skill, an undeclared skill, or no matches.
  */
-export interface SkillToolsDeps {
+import { z } from "zod";
+import { type Tool } from "../define-tool.js";
+export type SkillToolsDeps = {
     /** Absolute path to the skills tree (one subdirectory per skill). */
     readonly skillsDir: string;
     /** The agent's declared skills (`meta.skills`) — the access allowlist. */
     readonly skills: readonly string[];
-}
-interface SkillMatch {
+};
+type SkillMatch = {
     readonly skill: string;
     readonly path: string;
     readonly line: number;
     readonly snippet: string;
     readonly score: number;
-}
+};
 type SkillSearchOutput = {
     status: "no_skills";
 } | {
@@ -59,14 +61,16 @@ type SkillReadOutput = {
     path: string;
     content: string;
 };
+declare const SkillSearchInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    topK: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const SkillReadInputSchema: z.ZodObject<{
+    skill: z.ZodString;
+    path: z.ZodString;
+}, z.core.$strip>;
 export declare function createSkillTools(deps: SkillToolsDeps): {
-    skillSearch: import("../define-tool.js").Tool<{
-        query: string;
-        topK?: number | undefined;
-    }, SkillSearchOutput>;
-    skillRead: import("../define-tool.js").Tool<{
-        skill: string;
-        path: string;
-    }, SkillReadOutput>;
+    skillSearch: Tool<z.infer<typeof SkillSearchInputSchema>, SkillSearchOutput>;
+    skillRead: Tool<z.infer<typeof SkillReadInputSchema>, SkillReadOutput>;
 };
 export {};

package/dist/tools/sandbox/skills.js

@@ -18,12 +18,14 @@ import { join, relative, resolve, sep } from "node:path";
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
+import { collapseWhitespace, splitLines } from "../../lib/text.js";
 /** Bounds — keep a search over a deep skill tree cheap and context-safe. */
 const MAX_FILE_BYTES = 512 * 1024;
 const MAX_SNIPPET = 240;
 const DEFAULT_TOP_K = 10;
 const MAX_TOP_K = 25;
-const TEXT_EXT = /\.(md|markdown|txt|py|r|R|json|ya?ml|csv|tsv)$/;
+/** The file-name extensions a skill may carry text in. */
+const TEXT_EXTENSIONS = [".md", ".markdown", ".txt", ".py", ".r", ".R", ".json", ".yaml", ".yml", ".csv", ".tsv"];
 async function collectTextFiles(dir, acc) {
     let entries;
     try {
@@ -37,11 +39,19 @@ async function collectTextFiles(dir, acc) {
         if (e.isDirectory()) {
             await collectTextFiles(full, acc);
         }
-        else if (TEXT_EXT.test(e.name)) {
+        else if (TEXT_EXTENSIONS.some((extension) => e.name.endsWith(extension))) {
             acc.push(full);
         }
     }
 }
+const SkillSearchInputSchema = z.object({
+    query: z.string().min(1).describe("Keywords to match (e.g. 'PyDESeq2 contrast syntax')."),
+    topK: z.number().int().min(1).max(MAX_TOP_K).optional().describe(`Max results to return. Defaults to ${DEFAULT_TOP_K}.`),
+});
+const SkillReadInputSchema = z.object({
+    skill: z.string().min(1).describe("Skill name (one of your declared skills)."),
+    path: z.string().min(1).describe("File path within the skill, e.g. 'SKILL.md' or 'references/pydeseq2-api.md'."),
+});
 export function createSkillTools(deps) {
     const allowed = new Set(deps.skills);
     const skillSearch = defineTool({
@@ -52,16 +62,13 @@ export function createSkillTools(deps) {
             "case-insensitive substring. Returns one entry per matching skill file — its skill, its path, " +
             "and the first line that holds a query word — ranked by how many distinct query words the file " +
             "holds. Then `skill_read` the file. No matches returns a data variant.",
-        inputSchema: z.object({
-            query: z.string().min(1).describe("Keywords to match (e.g. 'PyDESeq2 contrast syntax')."),
-            topK: z.number().int().min(1).max(MAX_TOP_K).optional().describe(`Max results to return. Defaults to ${DEFAULT_TOP_K}.`),
-        }),
+        inputSchema: SkillSearchInputSchema,
         describeCall: "none",
         execute: async ({ query, topK }) => {
             if (allowed.size === 0) {
                 return ok({ status: "no_skills" });
             }
-            const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+            const tokens = collapseWhitespace(query.toLowerCase()).split(" ").filter(Boolean);
             const matches = [];
             for (const skill of allowed) {
                 const skillRoot = resolve(deps.skillsDir, skill);
@@ -82,7 +89,7 @@ export function createSkillTools(deps) {
                     const distinct = tokens.filter((t) => lower.includes(t)).length;
                     if (distinct === 0)
                         continue;
-                    const lines = content.split(/\r?\n/);
+                    const lines = splitLines(content);
                     const hitIdx = lines.findIndex((l) => {
                         const ll = l.toLowerCase();
                         return tokens.some((t) => ll.includes(t));
@@ -113,10 +120,7 @@ export function createSkillTools(deps) {
         description: "Read a file from one of your skills (e.g. its SKILL.md or a reference " +
             "found via skill_search). Confined to your declared skills. Undeclared " +
             "skills and missing paths return a data variant.",
-        inputSchema: z.object({
-            skill: z.string().min(1).describe("Skill name (one of your declared skills)."),
-            path: z.string().min(1).describe("File path within the skill, e.g. 'SKILL.md' or 'references/pydeseq2-api.md'."),
-        }),
+        inputSchema: SkillReadInputSchema,
         describeCall: "none",
         execute: async ({ skill, path }) => {
             if (!allowed.has(skill)) {

package/dist/tools/sandbox/submit-file-metadata.d.ts

@@ -10,21 +10,24 @@
  * index, so a dropped, reordered, or extra entry can never attach a
  * description to the wrong file.
  */
-import { type SubmittedFileDescription } from "../../schemas/file-metadata.js";
 import { type Tool } from "../define-tool.js";
 export declare const SUBMIT_FILE_METADATA_TOOL_ID = "submit_file_metadata";
 /**
- * The per-step cell of the file-metadata continuation. The step body makes it
- * beside the blocker cell, and the agent factory binds the output tool to it.
+ * The per-step cell of the file-metadata follow-up request. The step body makes
+ * it beside the step agent, and the agent factory binds the output tool to it.
+ * The descriptions themselves live in the inputs of the calls: the post-step
+ * code reads them from the recorded calls.
  */
-export interface FileMetadataCell {
-    /** The paths that the continuation describes, or `null` before the first `expect`. */
+export type FileMetadataCell = {
+    /** The paths that the follow-up request describes, or `null` before the first `expect`. */
     readonly knownPaths: ReadonlySet<string> | null;
-    /** The accepted description of each described path, keyed by the path. The tool writes only a known path. */
-    readonly descriptions: Map<string, SubmittedFileDescription>;
-    /** Arm the cell for one continuation: set the known paths, and drop each accepted description. */
+    /** The known paths that the earlier calls described. The loop folds each call record into it. */
+    readonly described: ReadonlySet<string>;
+    /** Arm the cell for one follow-up request: set the known paths, and forget each described path. */
     expect(paths: readonly string[]): void;
-}
+    /** Add the paths of one call record. */
+    fold(paths: readonly string[]): void;
+};
 export declare function createFileMetadataCell(): FileMetadataCell;
 /** Build the `submit_file_metadata` tool bound to the cell of one step. */
 export declare function createSubmitFileMetadataTool(cell: FileMetadataCell): Tool;