agency-lang 0.18.0 → 0.18.1

package/dist/lib/cli/hostedModels.js

@@ -1,4 +1,5 @@
 import { _listHostedModels, _fetchModelData, _loadModelData, } from "../stdlib/llm.js";
+import { wholePath } from "../stdlib/contained.js";
 // Filter predicate mirrors the Agency `filterHostedModels` in
 // lib/agents/agency-agent/lib/modelFilters.agency (the agent can't call this TS
 // and vice-versa) — keep the two in sync; both are unit-tested.
@@ -40,7 +41,7 @@ export function formatHostedCatalog(models) {
 // doesn't mistake a baked-only list for the merged one.
 export async function modelsList(opts, files = []) {
     for (const file of files) {
-        const res = _loadModelData(file);
+        const res = _loadModelData(file, wholePath);
         if (!res.ok) {
             console.error(`Cannot load ${file}: ${res.error}`);
             process.exitCode = 1;

package/dist/lib/cli/mcp.js

@@ -1,13 +1,9 @@
-import * as os from "os";
 import * as path from "path";
 import { isFailure } from "../runtime/index.js";
+import { agentHomeDir } from "../runtime/agentHome.js";
 import { _addMcpServer, _removeMcpServer, _readMcpServersFromFile } from "../stdlib/mcp.js";
-function agentHome() {
-    const override = process.env.AGENCY_AGENT_HOME;
-    return override ? path.resolve(override) : path.join(os.homedir(), ".agency-agent");
-}
 const projectFile = () => path.resolve(process.cwd(), "agency.json");
-const globalFile = () => path.join(agentHome(), "settings.json");
+const globalFile = () => path.join(agentHomeDir(), "settings.json");
 const scopeFile = (o) => (o.global ? globalFile() : projectFile());
 const scopeName = (o) => (o.global ? "global" : "project");
 function transportSummary(config) {

package/dist/lib/preprocessors/typescriptPreprocessor.js

@@ -374,40 +374,7 @@ export class TypescriptPreprocessor {
     // TODO: Update collectSkillsInFunction to work with llm() as FunctionCall.
     // Skills are now passed in the config object (2nd arg to llm()), but skill
     // statements still need to be collected and merged with config skills.
-    collectSkillsInFunction(body) {
-        /* Original implementation (used PromptLiteral nodes, needs rewrite for FunctionCall):
-        let skillsUsed: Skill[] = [];
-    
-        const setSkillsForPrompt = (promptNode: PromptLiteral) => {
-          promptNode.skills = skillsUsed;
-    
-          if (skillsUsed.length > 0) {
-            const hasReadSkillTool = promptNode.tools?.toolNames.some(
-              (t) => t === "readSkill",
-            );
-            if (!hasReadSkillTool) {
-              promptNode.tools = promptNode.tools || {
-                type: "usesTool",
-                toolNames: [],
-              };
-              promptNode.tools.toolNames.push("readSkill");
-            }
-          }
-    
-          skillsUsed = [];
-        };
-    
-        for (const { node } of walkNodesArray(body)) {
-          if (node.type === "skill") {
-            skillsUsed.push(node);
-          } else if (node.type === "prompt") {
-            setSkillsForPrompt(node);
-          } else if (node.type === "assignment" && node.value.type === "prompt") {
-            setSkillsForPrompt(node.value);
-          }
-        }
-        */
-    }
+    collectSkillsInFunction(body) { }
     findChildren(body, type) {
         const children = [];
         for (const { node } of walkNodesArray(body)) {

package/dist/lib/runtime/agentHome.d.ts

@@ -0,0 +1,6 @@
+/** The agent home directory: `AGENCY_AGENT_HOME`, or `~/.agency-agent`.
+ *  An empty variable counts as unset, so a set-but-blank value never
+ *  turns the home into the current directory. A relative override is
+ *  resolved against the process cwd, the way the `--agent-home` launcher
+ *  resolves it. */
+export declare function agentHomeDir(): string;

package/dist/lib/runtime/agentHome.js

@@ -0,0 +1,14 @@
+import os from "os";
+import path from "path";
+/** The agent home directory: `AGENCY_AGENT_HOME`, or `~/.agency-agent`.
+ *  An empty variable counts as unset, so a set-but-blank value never
+ *  turns the home into the current directory. A relative override is
+ *  resolved against the process cwd, the way the `--agent-home` launcher
+ *  resolves it. */
+export function agentHomeDir() {
+    const override = process.env.AGENCY_AGENT_HOME;
+    if (override !== undefined && override !== "") {
+        return path.resolve(override);
+    }
+    return path.join(os.homedir(), ".agency-agent");
+}

package/dist/lib/runtime/builtinPolicies.js

@@ -1,4 +1,4 @@
-import { AGENCY_INSTALL_DIR_PLACEHOLDER as INSTALL, escapeGlob, } from "./policy.js";
+import { AGENCY_INSTALL_DIR_PLACEHOLDER as INSTALL, AGENT_HOME_PLACEHOLDER as AGENT_HOME, escapeGlob, } from "./policy.js";
 // Read-only `agency` subcommands the code agent runs via its exec-based
 // `agencyCli` tool. Matched on command + subcommand (no shell chaining);
 // other subcommands (run, compile, ...) still prompt.
@@ -22,21 +22,35 @@ function agencyExecApproveRules() {
     }));
 }
 const approve = [{ action: "approve" }];
-// Where the read-only file tools may look without asking: the launch
-// directory and, because the agent's docs tools (`agencyGuide` and friends)
-// and bundled skills are plain reads of shipped files, the agency install
-// itself. Both are placeholders the matcher expands at match time (`.` to
-// the process cwd, `<agency>` to the package root; see
-// docs/dev/agents/approval-policies.md), so a saved copy of this policy keeps
-// meaning "wherever the agent runs, wherever agency is installed now".
-// Reads anywhere else fall through: a prompt in an interactive session, an
-// automatic rejection in a headless one.
+// Where the read-only file tools may look without asking. The launch
+// directory. The agency install itself, because the agent's docs tools
+// (`agencyGuide` and friends) and bundled skills are plain reads of
+// shipped files. The agent home's learned skills and tools, which only
+// enter those directories through a review interrupt. All three are
+// placeholders the matcher expands at match time (`.` to the process cwd,
+// `<agency>` to the package root, `<agent-home>` to the agent home, see
+// docs/dev/agents/approval-policies.md), so a saved copy of this policy
+// keeps meaning "wherever the agent runs, wherever agency is installed
+// now". Reads anywhere else fall through: a prompt in an interactive
+// session, an automatic rejection in a headless one.
 export function readScopeRules() {
     return [
         { match: { dir: "{.,./**}" }, action: "approve" },
         { match: { dir: `{${INSTALL}/stdlib/**,${INSTALL}/dist/**}` }, action: "approve" },
+        {
+            match: {
+                dir: `{${AGENT_HOME}/skills,${AGENT_HOME}/skills/**,${AGENT_HOME}/tools,${AGENT_HOME}/tools/**}`,
+            },
+            action: "approve",
+        },
     ];
 }
+// runTool's use count in a tool's meta.json. An effect of its own, never
+// a std::write rule on the file; docs/dev/agents/approval-policies.md
+// says why.
+function toolboxRecordUseRules() {
+    return [{ match: { dir: `${AGENT_HOME}/tools/**` }, action: "approve" }];
+}
 export const minimalAutoApprovePolicy = {
     "std::memory::remember": approve,
     "std::memory::forget": approve,
@@ -66,11 +80,12 @@ export const recommendedAutoApprovePolicy = {
     "std::weather": approve,
     "std::search": approve,
     "std::tavilySearch": approve,
-    "std::skills::skillsDir": approve,
-    "std::skills::commandsDir": approve,
-    // A scan reads tool sources and meta.json under a directory, so it
-    // takes the read scope.
+    // A scan reads every skill, command, or tool file under a directory,
+    // so it takes the read scope.
+    "std::skills::skillsDir": readScopeRules(),
+    "std::skills::commandsDir": readScopeRules(),
     "std::toolbox::scan": readScopeRules(),
+    "std::toolbox::recordUse": toolboxRecordUseRules(),
     "std::notify": approve,
     "std::clipboardCopy": approve,
     "std::git::status": approve,
@@ -126,7 +141,7 @@ export const approveAllPolicy = {
 export const BUILTIN_POLICIES = [
     {
         name: "recommended",
-        description: "Auto-approve reads under the current directory (and the agency install's own docs and skills) and web/search; prompt for reads elsewhere, writes, shell, and git changes.",
+        description: "Auto-approve reads under the current directory, the agency install's own docs and skills, and the agent home's learned skills and tools (plus the toolbox use count there), and web/search; prompt for reads elsewhere, writes, shell, and git changes.",
     },
     {
         name: "minimal",

package/dist/lib/runtime/builtins.d.ts

@@ -6,7 +6,3 @@ export declare function builtinRead(args: {
     dirname: string;
 }): string;
 export declare function builtinSleep(seconds: number): Promise<void>;
-export declare function readSkill(args: {
-    filepath: string;
-    dirname: string;
-}): string;

package/dist/lib/runtime/builtins.js

@@ -14,6 +14,3 @@ export function builtinSleep(seconds) {
         setTimeout(resolve, seconds * 1000);
     });
 }
-export function readSkill(args) {
-    return builtinRead({ filename: args.filepath, dirname: args.dirname });
-}

package/dist/lib/runtime/index.d.ts

@@ -36,8 +36,7 @@ export type { FuncParam, CallType, ToolDefinition, AgencyFunctionOpts } from "./
 export { __call, __callMethod } from "./call.js";
 export { callHook, registerGlobalHook } from "./hooks.js";
 export type { AgencyCallbacks, CallbackMap, CallbackReturn } from "./hooks.js";
-export { head, tail, empty, builtinRead, builtinSleep, readSkill } from "./builtins.js";
-export { readSkillTool, readSkillToolParams } from "./builtinTools.js";
+export { head, tail, empty, builtinRead, builtinSleep } from "./builtins.js";
 export { interrupt, isInterrupt, hasInterrupts, reportUnhandledInterrupts, isDebugger, isRejected, isApproved, approve, reject, pass, interruptWithHandlers, respondToInterrupts, respondToInterruptsForServe, } from "./interrupts.js";
 export { checkPolicy, checkPolicyExplicit, validatePolicy } from "./policy.js";
 export { resolveCliInterrupts } from "./cliInterruptResolution.js";

package/dist/lib/runtime/index.js

@@ -25,8 +25,7 @@ export { functionRefReviver } from "./revivers/index.js";
 export { AgencyFunction, UNSET } from "./agencyFunction.js";
 export { __call, __callMethod } from "./call.js";
 export { callHook, registerGlobalHook } from "./hooks.js";
-export { head, tail, empty, builtinRead, builtinSleep, readSkill } from "./builtins.js";
-export { readSkillTool, readSkillToolParams } from "./builtinTools.js";
+export { head, tail, empty, builtinRead, builtinSleep } from "./builtins.js";
 export { interrupt, isInterrupt, hasInterrupts, reportUnhandledInterrupts, isDebugger, isRejected, isApproved, approve, reject, pass, interruptWithHandlers, respondToInterrupts, respondToInterruptsForServe, } from "./interrupts.js";
 export { checkPolicy, checkPolicyExplicit, validatePolicy } from "./policy.js";
 export { resolveCliInterrupts } from "./cliInterruptResolution.js";

package/dist/lib/runtime/policy.d.ts

@@ -56,6 +56,14 @@ export declare function resolveDotDirPattern(pattern: string, cwd?: string): str
  *  path of one machine or one version. */
 export declare const AGENCY_INSTALL_DIR_PLACEHOLDER = "<agency>";
 export declare function expandAgencyInstallDir(pattern: string, root?: () => string): string;
+/** In a `dir` pattern, `<agent-home>` stands for the agent home directory
+ *  (`AGENCY_AGENT_HOME`, or `~/.agency-agent`). The built-in read scope
+ *  uses it for the learned skills and tools directories, so a saved policy
+ *  keeps meaning "wherever the agent home is now". */
+export declare const AGENT_HOME_PLACEHOLDER = "<agent-home>";
+/** Expand `<agent-home>` at match time, like `<agency>`. The home is
+ *  escaped so a path containing glob or brace characters stays literal. */
+export declare function expandAgentHomeDir(pattern: string, home?: () => string): string;
 export declare function validatePolicy(policy: any): {
     success: boolean;
     error?: string;

package/dist/lib/runtime/policy.js

@@ -2,6 +2,8 @@ import picomatch from "picomatch";
 import { realpathSync } from "fs";
 import { z } from "zod";
 import { getPackageRoot } from "../importPaths.js";
+import { agentHomeDir } from "./agentHome.js";
+import { root } from "../stdlib/contained.js";
 export const PolicyRuleSchema = z
     .object({
     match: z.record(z.string(), z.string()).optional(),
@@ -75,9 +77,6 @@ function stripDotSlash(s) {
 // whose name contains glob characters (say `v*1`) would widen the rule to
 // its siblings — a safety boundary, so the substituted prefix must match
 // itself only. Glob syntax stays live only in the user-written suffix.
-function escapeForGlob(s) {
-    return s.replace(/[\\*?[\]{}()!+@|]/g, "\\$&");
-}
 // In a `dir` pattern, `.` also means "wherever the agent was launched".
 // Tools absolutize the dir they put in interrupt data, so a literal `.` in
 // a policy file could never match those; resolving it lets a static policy
@@ -103,7 +102,7 @@ export function resolveDotDirPattern(pattern, cwd = process.cwd()) {
     }
     // Callback, not a replacement string: a legal cwd containing `$&`/`$'`
     // would otherwise be interpreted as replacement-string syntax.
-    return pattern.replace(/(^|\{|,)\.(?=$|\/|,|\})/g, (_match, prefix) => prefix + escapeForGlob(realCwd));
+    return pattern.replace(/(^|\{|,)\.(?=$|\/|,|\})/g, (_match, prefix) => prefix + escapeGlob(realCwd));
 }
 /** In a `dir` pattern, `<agency>` stands for the directory the agency
  *  package is installed in. A rule approving reads of the shipped docs and
@@ -124,7 +123,30 @@ export function expandAgencyInstallDir(pattern, root = getPackageRoot) {
     catch {
         return pattern;
     }
-    return pattern.split(AGENCY_INSTALL_DIR_PLACEHOLDER).join(escapeForGlob(resolved));
+    return pattern.split(AGENCY_INSTALL_DIR_PLACEHOLDER).join(escapeGlob(resolved));
+}
+/** In a `dir` pattern, `<agent-home>` stands for the agent home directory
+ *  (`AGENCY_AGENT_HOME`, or `~/.agency-agent`). The built-in read scope
+ *  uses it for the learned skills and tools directories, so a saved policy
+ *  keeps meaning "wherever the agent home is now". */
+export const AGENT_HOME_PLACEHOLDER = "<agent-home>";
+/** Expand `<agent-home>` at match time, like `<agency>`. The home is
+ *  escaped so a path containing glob or brace characters stays literal. */
+export function expandAgentHomeDir(pattern, home = canonicalAgentHome) {
+    if (!pattern.includes(AGENT_HOME_PLACEHOLDER))
+        return pattern;
+    return pattern.split(AGENT_HOME_PLACEHOLDER).join(escapeGlob(home()));
+}
+/** The real spelling of the agent home, the spelling file effects put in
+ *  their payloads. A home that does not exist yet keeps a lexical tail. */
+function canonicalAgentHome() {
+    const home = agentHomeDir();
+    try {
+        return root(home).real;
+    }
+    catch {
+        return home;
+    }
 }
 function matchesRule(rule, interrupt) {
     if (!rule.match)
@@ -151,11 +173,11 @@ function matchesRule(rule, interrupt) {
         const viaDot = !raw &&
             key === "dir" &&
             picomatch.isMatch(stripDotSlash(value), stripDotSlash(resolveDotDirPattern(pattern)));
-        const viaInstall = !raw &&
+        const viaPlaceholders = !raw &&
             !viaDot &&
             key === "dir" &&
-            picomatch.isMatch(stripDotSlash(value), expandAgencyInstallDir(pattern));
-        if (!raw && !viaDot && !viaInstall) {
+            picomatch.isMatch(stripDotSlash(value), expandAgentHomeDir(expandAgencyInstallDir(pattern)));
+        if (!raw && !viaDot && !viaPlaceholders) {
             return false;
         }
     }

package/dist/lib/runtime/toolLoopGuards.d.ts

@@ -20,6 +20,11 @@ export declare const DEFAULT_MAX_REPEATED_TOOL_CALLS = 3;
  *  a transcript or XML tool may legitimately be given. */
 export declare function markupArgument(args: Record<string, unknown>, params: readonly FuncParam[]): string | null;
 export declare function markupArgumentMessage(toolName: string, argument: string): string;
+/** The key is stored on the checkpoint, and checkpoints are kept as JSON
+ *  in places that reject U+0000 (Postgres jsonb, for one), so the two parts
+ *  are joined with a colon. A namespaced tool name has colons of its own,
+ *  but the digest is always 64 hex characters, so two different calls can
+ *  never produce the same key. */
 export declare function repeatKey(toolName: string, args: Record<string, unknown>): string;
 /** The current run of identical calls: one record, because only calls in a
  *  row count. Any other call, a different result, or a refusal resets it. */

package/dist/lib/runtime/toolLoopGuards.js

@@ -66,8 +66,13 @@ function canonicalJson(value) {
 function digest(text) {
     return createHash("sha256").update(text).digest("hex");
 }
+/** The key is stored on the checkpoint, and checkpoints are kept as JSON
+ *  in places that reject U+0000 (Postgres jsonb, for one), so the two parts
+ *  are joined with a colon. A namespaced tool name has colons of its own,
+ *  but the digest is always 64 hex characters, so two different calls can
+ *  never produce the same key. */
 export function repeatKey(toolName, args) {
-    return `${toolName}\u0000${digest(canonicalJson(args))}`;
+    return `${toolName}:${digest(canonicalJson(args))}`;
 }
 export function freshRepeatStreak() {
     return { key: "", result: "", count: 0 };

package/dist/lib/stdlib/agentSessions.js

@@ -1,28 +1,22 @@
-import * as fs from "fs";
-import * as path from "path";
+import { root, list, stat, mkdir, readText, writeText } from "./contained.js";
 import { __call } from "../runtime/call.js";
 import { checkpoint, getCheckpoint } from "../runtime/checkpoint.js";
 import { Checkpoint } from "../runtime/state/checkpointStore.js";
 import { _contentToString } from "./threads.js";
 const META_SUFFIX = ".meta.json";
-function checkpointFile(dir, id) {
-    return path.join(dir, `${id}.json`);
+function checkpointFile(id) {
+    return `${id}.json`;
 }
-function metaFile(dir, id) {
-    return path.join(dir, `${id}${META_SUFFIX}`);
+function metaFile(id) {
+    return `${id}${META_SUFFIX}`;
 }
-/** Write via a sibling temp file and rename, so a crash mid-write never
- *  leaves a half-written file (the same pattern as the REPL history). */
-function writeAtomic(file, data) {
-    const tmp = `${file}.tmp-${process.pid}`;
-    fs.writeFileSync(tmp, data, "utf8");
-    fs.renameSync(tmp, file);
-}
-function readJson(file) {
-    if (!fs.existsSync(file))
-        return null;
+/** The parsed JSON of `name` under `dir`, or null when it is missing or
+ *  malformed. */
+function readJson(dir, name) {
     try {
-        return JSON.parse(fs.readFileSync(file, "utf-8"));
+        if (stat(dir, name) === null)
+            return null;
+        return JSON.parse(readText(dir, name));
     }
     catch {
         return null;
@@ -45,13 +39,14 @@ function isRecord(value) {
 /** Every session in `dir`, most recently active first. A malformed
  *  record file is skipped. */
 export function _listSessions(dir) {
-    if (!fs.existsSync(dir))
+    const sessions = root(dir);
+    if (stat(sessions, ".") === null)
         return [];
     const records = [];
-    for (const name of fs.readdirSync(dir)) {
-        if (!name.endsWith(META_SUFFIX))
+    for (const entry of list(sessions, ".")) {
+        if (entry.type !== "file" || !entry.name.endsWith(META_SUFFIX))
             continue;
-        const parsed = readJson(path.join(dir, name));
+        const parsed = readJson(sessions, entry.name);
         if (isRecord(parsed))
             records.push(parsed);
     }
@@ -62,9 +57,12 @@ export function _listSessions(dir) {
  *  error message. */
 export function _saveSession(dir, record, checkpoint) {
     try {
-        fs.mkdirSync(dir, { recursive: true });
-        writeAtomic(checkpointFile(dir, record.id), JSON.stringify(checkpoint));
-        writeAtomic(metaFile(dir, record.id), JSON.stringify(record));
+        const sessions = root(dir);
+        mkdir(sessions, ".");
+        // writeText renames a finished sibling over the target, so a crash
+        // mid-write never leaves a half-written file.
+        writeText(sessions, checkpointFile(record.id), JSON.stringify(checkpoint));
+        writeText(sessions, metaFile(record.id), JSON.stringify(record));
         return "";
     }
     catch (err) {
@@ -73,7 +71,7 @@ export function _saveSession(dir, record, checkpoint) {
 }
 /** The parsed checkpoint, or null when the file is missing or malformed. */
 export function _readCheckpointFile(dir, id) {
-    return readJson(checkpointFile(dir, id));
+    return readJson(root(dir), checkpointFile(id));
 }
 /**
  * The user and assistant messages of a saved session's conversation

package/dist/lib/stdlib/cli.js

@@ -1,7 +1,6 @@
 import * as readline from "readline";
 import process from "process";
-import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from "fs";
-import { dirname } from "path";
+import { wholePath, stat, readText, writeText, mkdir } from "./contained.js";
 import { __call } from "../runtime/call.js";
 import { getRuntimeContext } from "../runtime/asyncContext.js";
 import { RESET, styles } from "../utils/termcolors.js";
@@ -53,10 +52,13 @@ function summarizeMultiline(text) {
  *  startup. */
 function loadHistory(file, max) {
     const empty = { entries: [], expansions: {} };
-    if (!file || !existsSync(file))
+    if (!file)
         return empty;
     try {
-        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        const located = wholePath(file);
+        if (stat(located.root, located.target) === null)
+            return empty;
+        const parsed = JSON.parse(readText(located.root, located.target));
         if (!Array.isArray(parsed))
             return empty;
         const entries = [];
@@ -87,19 +89,17 @@ function saveHistory(file, history, max, expansions = {}) {
     if (!file)
         return;
     try {
-        mkdirSync(dirname(file), { recursive: true });
+        const located = wholePath(file);
+        mkdir(located.root, ".");
         const oldestFirst = history.slice(0, max).slice().reverse();
         const records = oldestFirst.map((entry) => Object.prototype.hasOwnProperty.call(expansions, entry)
             ? { preview: entry, text: expansions[entry] }
             : entry);
         const data = JSON.stringify(records, null, 2) + "\n";
-        // Write to a sibling temp file, then rename into place. The rename is an
-        // atomic swap (POSIX, and Windows via libuv's REPLACE_EXISTING), so a crash
-        // mid-write can't leave a half-written file — which, as JSON, would parse to
-        // empty and silently wipe the user's history on the next load.
-        const tmp = `${file}.tmp-${process.pid}`;
-        writeFileSync(tmp, data, "utf8");
-        renameSync(tmp, file);
+        // writeText replaces the file by renaming a finished sibling over it, so
+        // a crash mid-write cannot leave half-written JSON that would parse to
+        // empty and wipe the user's history on the next load.
+        writeText(located.root, located.target, data);
     }
     catch {
         // Ignore — best-effort persistence.

package/dist/lib/stdlib/contained.d.ts

@@ -1,3 +1,22 @@
+/**
+ * Every file operation the standard library performs on a path an Agency
+ * program chose goes through this module. The rule it enforces: under an
+ * approval that names directory D, no byte is read from or written to any
+ * path outside D. A symlink in the caller's own spelling of D (a linked
+ * /tmp, a linked home) resolves normally, once, in `root`. A symlink at
+ * any component below D is refused, because the approver never named
+ * where it points.
+ *
+ * How strong that rule is depends on the operation. Reads and writes,
+ * `readStream`, and `copy`, which is built on them, move bytes only through a
+ * descriptor that is validated after it is open, so a directory swapped
+ * to a link while the operation runs cannot redirect them. `list`,
+ * `stat`, `mkdir`, `remove`, and `move` act on a pathname that was
+ * checked a moment earlier. Node has no openat, so a swap between that
+ * check and the action is not closed here. Process containment is the
+ * answer for that window. See docs/dev/stdlib/contained-files.md.
+ */
+import fs from "fs";
 import type { Stats } from "fs";
 /** A directory an approval named, realpathed once. Every operation in this
  *  module takes one. Nothing takes a bare string root. */
@@ -57,6 +76,10 @@ export declare function readText(root: Root, target: string, seams?: Seams): str
  *  inside the root, and require the same (dev, ino) as the descriptor so a
  *  swap undone after the open is caught too. */
 export declare function readBytes(root: Root, target: string, seams?: Seams): Buffer;
+/** A read stream over a validated descriptor, for a file too large to
+ *  buffer, such as a downloaded model being hashed. The stream owns the
+ *  descriptor and closes it when it ends. */
+export declare function readStream(root: Root, target: string, seams?: Seams): fs.ReadStream;
 export declare function writeText(root: Root, target: string, content: string, options?: WriteOptions): void;
 export declare function writeBytes(root: Root, target: string, data: Buffer, options?: WriteOptions): void;
 export type Entry = {
@@ -83,6 +106,6 @@ export declare function copy(from: Located, to: Located): void;
 export declare function move(from: Located, to: Located): void;
 /** Every operation this module performs. The symlink battery runs each
  *  one; adding an operation without a row here fails the registry test. */
-export declare const PRIMITIVES: readonly ["readText", "readBytes", "writeText", "writeBytes", "list", "stat", "mkdir", "remove", "copy", "move"];
+export declare const PRIMITIVES: readonly ["readText", "readBytes", "readStream", "writeText", "writeBytes", "list", "stat", "mkdir", "remove", "copy", "move"];
 /** Exports that are not operations: they resolve, they do not touch bytes. */
 export declare const HELPERS: readonly ["root", "fixedRoot", "resolveUnder", "wholePath", "fixedPath", "isContained", "_realDir", "_realTarget"];