@zenera/neo 1.1.0 → 1.1.3

package/dist/skills.js

@@ -6,7 +6,17 @@ export function skillContentHash(s) {
 }
 export function renderSkills(skills) {
     return skills
-        .map((s) => `## Skill: ${s.name}${s.version ? ` (${s.version})` : ''}\n${s.content}`)
+        .map((s) => {
+        const head = `## Skill: ${s.name}${s.version ? ` (${s.version})` : ''}`;
+        // One line, and only when the files are reachable. Without it the
+        // model has the instructions and no way to act on the half of them
+        // that names a file.
+        const where = s.path
+            ? `\nThis skill's files are at ${s.path}, read-only. Paths written in it are ` +
+                'relative to that directory.\n'
+            : '';
+        return `${head}${where}\n${s.content}`;
+    })
         .join('\n\n');
 }
 export function renderSkillIndex(summaries, max) {

package/dist/tools/sandbox.d.ts

@@ -29,6 +29,17 @@ export interface SandboxSpec {
     persist?: boolean;
     /** environment inside the container — resolved values, never a passthrough */
     env?: Record<string, string>;
+    /**
+     * Variables forwarded from this process by *name*, for credentials.
+     *
+     * Separate from `env` for two reasons, both about the value never being
+     * written down. `--env NAME` without an `=` tells podman to read the value
+     * out of its own environment, so the secret never appears on a command
+     * line, in `ps`, or in `podman inspect`. And the container's identity is
+     * computed from the names alone, so rotating a key does not abandon a
+     * persisted container's filesystem.
+     */
+    secrets?: readonly string[];
 }
 export type SandboxNetwork = 'bridge' | 'none' | 'host';
 export interface SandboxMount {

package/dist/tools/sandbox.js

@@ -212,6 +212,14 @@ export class Sandbox {
         for (const [k, v] of Object.entries(s.env)) {
             args.push('--env', `${k}=${v}`);
         }
+        // No `=`, and so no value: podman reads each one from its own
+        // environment. A key passed this way is not in the argv of a process
+        // any user on the machine can list.
+        for (const name of s.secrets) {
+            if (process.env[name]) {
+                args.push('--env', name);
+            }
+        }
         args.push(s.image, 'sleep', 'infinity');
         return args;
     }
@@ -422,6 +430,7 @@ function resolveSpec(opts) {
         user: opts.user,
         persist: opts.persist ?? false,
         env: opts.env ?? {},
+        secrets: opts.secrets ?? [],
         readOnly: opts.readOnly ?? false,
         mounts: opts.mounts ?? [],
         engine: opts.engine ?? 'podman',
@@ -431,6 +440,11 @@ function resolveSpec(opts) {
  * The container's name is a function of its configuration. Change the image
  * and a new container appears rather than an old one quietly persisting with
  * the wrong rootfs — which is the failure mode `persist` would otherwise have.
+ *
+ * Secrets contribute their names and not their values: what a container is
+ * depends on which credentials reach it, not on what they happen to say today,
+ * and hashing the values would throw away a persisted container's filesystem
+ * every time a key was rotated.
  */
 function containerName(spec) {
     const digest = createHash('sha256')
@@ -445,6 +459,7 @@ function containerName(spec) {
         spec.readOnly,
         spec.mounts,
         Object.entries(spec.env).sort(),
+        [...spec.secrets].sort(),
     ]))
         .digest('hex')
         .slice(0, 10);

package/dist/tools/workspace.d.ts

@@ -1,4 +1,22 @@
 import { type AnyTool } from '../types.ts';
+/** Where a project's `assets/` directory appears in the agent's namespace. */
+export declare const ASSETS_MOUNT = "/assets";
+/** ...and where its skill catalog does, so a skill's scripts can be run. */
+export declare const SKILLS_MOUNT = "/skills";
+/**
+ * A second tree the agent can reach, under a name of its own. Structurally the
+ * same as a `SandboxMount` on purpose: one directory is one mount, and the host
+ * hands the identical array to the file tools and to the container so that both
+ * call it by the same name.
+ */
+export interface WorkspaceMount {
+    /** absolute host path; must already exist */
+    host: string;
+    /** absolute path the agent names it by, e.g. `/assets` */
+    at: string;
+    /** defaults to true — an extra tree is reference material unless said otherwise */
+    readOnly?: boolean;
+}
 export interface WorkspaceOptions {
     root: string;
     /** refuse every mutating tool; `zen run --read-only` */
@@ -11,22 +29,28 @@ export interface WorkspaceOptions {
      * it and both spellings reach the same file.
      */
     mount?: string;
+    /** further trees, each under its own name; read-only unless one says otherwise */
+    mounts?: readonly WorkspaceMount[];
 }
 export declare class Workspace {
     #private;
     readonly root: string;
     readonly readOnly: boolean;
     readonly mount: string | undefined;
+    /** the extra trees, resolved — the primary root is not among them */
+    readonly mounts: readonly Required<WorkspaceMount>[];
     constructor(opts: WorkspaceOptions);
     /**
-     * The one gate. Returns an absolute path inside the workspace, or throws.
+     * The one gate. Returns an absolute path inside one of the roots, or throws.
      *
      * A path that does not exist yet cannot be realpath'd, so the nearest
      * existing ancestor is resolved instead and the remainder appended — which
      * is exactly what a create needs and closes the same hole a create opens.
      */
-    within(input: string): string;
-    /** Where a path sits under the root, in posix form. `.` is the root. */
+    within(input: string, opts?: {
+        write?: boolean;
+    }): string;
+    /** Where a path sits under its own root, in posix form. `.` is that root. */
     rel(path: string): string;
     /**
      * How a path is written back to the model, and the reason `mount` is not
@@ -39,6 +63,8 @@ export declare class Workspace {
      * is exact. Without one, everything stays relative as before.
      */
     show(path: string): string;
+    /** Whether a resolved path *is* one of the roots. Nothing may move or delete one. */
+    isRoot(path: string): boolean;
     mutable(): void;
 }
 export type FileFormat = 'text' | 'binary' | 'image' | 'audio' | 'video' | 'pdf' | 'archive';

package/dist/tools/workspace.js

@@ -1,4 +1,4 @@
-import { realpathSync } from 'node:fs';
+import { realpathSync, statSync } from 'node:fs';
 import { mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname, extname, join, relative, resolve, sep } from 'node:path';
 import { tool } from "../types.js";
@@ -28,68 +28,117 @@ const SNIFF_BYTES = 8 * 1024;
 const MAX_SCAN = 1024 * 1024;
 /** ...and one listing only spends this much on line counting in total. */
 const LIST_SCAN_BUDGET = 8 * 1024 * 1024;
+/** Where a project's `assets/` directory appears in the agent's namespace. */
+export const ASSETS_MOUNT = '/assets';
+/** ...and where its skill catalog does, so a skill's scripts can be run. */
+export const SKILLS_MOUNT = '/skills';
 export class Workspace {
     root;
     readOnly;
     mount;
+    /** the extra trees, resolved — the primary root is not among them */
+    mounts;
+    /** primary first */
+    #roots;
+    /** the ones with a name, longest name first */
+    #named;
+    /** every root, deepest host path first, for attributing a resolved path to one */
+    #deep;
     constructor(opts) {
         // Resolve the root's own symlinks once, so a workspace that *is* a
         // symlink does not fail every containment check against itself.
         this.root = realpathSync(resolve(opts.root));
         this.readOnly = opts.readOnly ?? false;
-        // A trailing slash — or a mount of `/`, which would make everything on
-        // the machine look like it was inside — is not a mount point.
-        const mount = opts.mount?.replace(/\/+$/, '');
-        this.mount = mount ? mount : undefined;
+        this.mount = mountPoint(opts.mount);
+        const roots = [{ path: this.root, at: this.mount, readOnly: this.readOnly }];
+        const mounts = [];
+        for (const m of opts.mounts ?? []) {
+            const at = mountPoint(m.at);
+            if (at === undefined) {
+                throw new Error(`a workspace mount needs an absolute name of its own: ${m.at}`);
+            }
+            // Overlapping names would make one path mean two directories, and
+            // which one won would depend on the order they were passed in.
+            for (const taken of roots) {
+                if (taken.at && (at === taken.at || under(at, taken.at) || under(taken.at, at))) {
+                    throw new Error(`workspace mounts overlap: ${at} and ${taken.at}`);
+                }
+            }
+            const host = directory(m.host, at);
+            const readOnly = m.readOnly ?? true;
+            roots.push({ path: host, at, readOnly });
+            mounts.push({ host, at, readOnly });
+        }
+        this.mounts = mounts;
+        this.#roots = roots;
+        this.#named = roots
+            .filter((r) => r.at !== undefined)
+            .sort((a, b) => b.at.length - a.at.length);
+        // A mount may sit inside the workspace root; the deeper one owns the path.
+        this.#deep = [...roots].sort((a, b) => b.path.length - a.path.length);
     }
     /**
-     * The one gate. Returns an absolute path inside the workspace, or throws.
+     * The one gate. Returns an absolute path inside one of the roots, or throws.
      *
      * A path that does not exist yet cannot be realpath'd, so the nearest
      * existing ancestor is resolved instead and the remainder appended — which
      * is exactly what a create needs and closes the same hole a create opens.
      */
-    within(input) {
+    within(input, opts = {}) {
         if (typeof input !== 'string' || input.length === 0) {
             throw new Error('path is required');
         }
         if (input.includes('\0')) {
             throw new Error('path contains a null byte');
         }
-        // A lone `/` is the model's other name for "the top of what I can see".
-        // There is nothing above the root for it to mean, so it means the root
-        // — refusing it teaches nothing and costs a turn. This is the only
-        // absolute path treated as rooted: `/etc/passwd` still names the
-        // machine's file and still fails containment below.
-        const wanted = resolve(this.root, /^[\\/]+$/.test(input) ? '.' : this.#unmount(input));
-        const real = this.#realish(wanted);
-        if (real !== this.root && !real.startsWith(this.root + sep)) {
+        const { root, rest } = this.#locate(input);
+        const real = this.#realish(resolve(root.path, rest));
+        if (real !== root.path && !real.startsWith(root.path + sep)) {
             throw new Error(`outside the workspace: ${input}`);
         }
+        if (opts.write && root.readOnly) {
+            throw new Error(root.path === this.root
+                ? 'the workspace is read-only for this run'
+                : `${root.at} is read-only`);
+        }
         return real;
     }
     /**
-     * `/workspace/src/a.ts` and `src/a.ts` are one file under two names, and
-     * only the second resolves against the root, so the mounted spelling is
-     * rewritten before anything else looks at it.
+     * Which tree a path names, and where in it. `/workspace/src/a.ts` and
+     * `src/a.ts` are one file under two names, and only the second resolves
+     * against the root, so the mounted spelling is rewritten before anything
+     * else looks at it.
      *
-     * This is renaming, not permission. What comes out is still relative, still
-     * resolved, still symlink-followed and still checked against the root
-     * above: `/workspace/../etc/passwd` loses its prefix and then fails
-     * containment exactly as `../etc/passwd` does.
+     * This is renaming, not permission. What comes out is still resolved, still
+     * symlink-followed and still checked against its root by the caller:
+     * `/workspace/../etc/passwd` loses its prefix and then fails containment
+     * exactly as `../etc/passwd` does.
      */
-    #unmount(input) {
-        if (this.mount === undefined) {
-            return input;
+    #locate(input) {
+        const primary = this.#roots[0];
+        // A lone `/` is the model's other name for "the top of what I can see".
+        // There is nothing above the root for it to mean, so it means the root
+        // — refusing it teaches nothing and costs a turn. This is the only
+        // absolute path treated as rooted: `/etc/passwd` still names the
+        // machine's file and still fails containment.
+        if (/^[\\/]+$/.test(input)) {
+            return { root: primary, rest: '.' };
         }
         const at = input.replace(/\\/g, '/');
-        if (at === this.mount) {
-            return '.';
-        }
-        if (!at.startsWith(this.mount + '/')) {
-            return input;
+        for (const root of this.#named) {
+            if (at === root.at) {
+                return { root, rest: '.' };
+            }
+            if (at.startsWith(root.at + '/')) {
+                return { root, rest: at.slice(root.at.length + 1).replace(/^\/+/, '') || '.' };
+            }
         }
-        return at.slice(this.mount.length).replace(/^\/+/, '') || '.';
+        return { root: primary, rest: input };
+    }
+    /** The root a resolved path belongs to; the primary when nothing else claims it. */
+    #owner(path) {
+        return (this.#deep.find((r) => path === r.path || path.startsWith(r.path + sep)) ??
+            this.#roots[0]);
     }
     #realish(path) {
         const missing = [];
@@ -113,9 +162,9 @@ export class Workspace {
             }
         }
     }
-    /** Where a path sits under the root, in posix form. `.` is the root. */
+    /** Where a path sits under its own root, in posix form. `.` is that root. */
     rel(path) {
-        return relative(this.root, path).split(sep).join('/') || '.';
+        return relative(this.#owner(path).path, path).split(sep).join('/') || '.';
     }
     /**
      * How a path is written back to the model, and the reason `mount` is not
@@ -128,11 +177,16 @@ export class Workspace {
      * is exact. Without one, everything stays relative as before.
      */
     show(path) {
-        const rel = this.rel(path);
-        if (this.mount === undefined) {
+        const root = this.#owner(path);
+        const rel = relative(root.path, path).split(sep).join('/') || '.';
+        if (root.at === undefined) {
             return rel;
         }
-        return rel === '.' ? this.mount : `${this.mount}/${rel}`;
+        return rel === '.' ? root.at : `${root.at}/${rel}`;
+    }
+    /** Whether a resolved path *is* one of the roots. Nothing may move or delete one. */
+    isRoot(path) {
+        return this.#roots.some((r) => r.path === path);
     }
     mutable() {
         if (this.readOnly) {
@@ -140,6 +194,39 @@ export class Workspace {
         }
     }
 }
+/**
+ * An absolute name a tree is known by, with any trailing slash removed. A mount
+ * of `/` would make everything on the machine look like it was inside, so it is
+ * not a mount point; nor is a relative one, which would resolve against nothing.
+ */
+function mountPoint(at) {
+    const clean = at?.replace(/\\/g, '/').replace(/\/+$/, '');
+    return clean && clean.startsWith('/') ? clean : undefined;
+}
+function under(inner, outer) {
+    return inner.startsWith(outer + '/');
+}
+/** The host side of a mount, resolved. It has to exist: a mount of nothing is a typo. */
+function directory(host, at) {
+    let path;
+    try {
+        path = realpathSync(resolve(host));
+    }
+    catch {
+        throw new Error(`workspace mount ${at}: no such directory: ${host}`);
+    }
+    if (!statSync(path).isDirectory()) {
+        throw new Error(`workspace mount ${at}: not a directory: ${host}`);
+    }
+    return path;
+}
+/** `a`, `a and b`, `a, b and c` — these end up in sentences the model reads. */
+function nameList(items) {
+    if (items.length < 2) {
+        return items[0] ?? '';
+    }
+    return `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`;
+}
 /**
  * Formats that are decided by name alone. Everything absent from here is
  * sniffed, so an unknown extension still lands on text or binary correctly.
@@ -531,18 +618,35 @@ export function workspaceTools(opts) {
     // `read_file`, which is the first of these any model reaches for; the short
     // one is repeated on every `path` argument, which is where the value is
     // actually written and where a wrong guess costs a turn.
-    const scope = ws.mount
-        ? `The workspace is mounted at ${ws.mount}, which is the name commands running in the ` +
-            `sandbox print and the name these tools answer with, so a path from a command's ` +
-            `output can be used here unchanged. A path relative to the workspace root names the ` +
-            `same file: ${ws.mount}/src/a.ts and src/a.ts are one file. That directory is the ` +
-            'whole of what can be reached: nothing outside it can be read or written.'
-        : 'Paths are relative to the workspace root, and that directory is the whole of what ' +
-            'can be reached: nothing outside it can be read or written.';
-    const inside = ws.mount
-        ? `Path in the workspace: ${ws.mount}/src/a.ts, or src/a.ts relative to the root — the ` +
-            `same file either way. The root itself is "${ws.mount}", "/" or ".".`
-        : 'Path in the workspace, relative to its root: src/a.ts. The root itself is "." or "/".';
+    //
+    // This is also the only place an extra tree is named. Nothing else in the
+    // prompt mentions one, and a directory the model has not been told about is
+    // a directory it never opens.
+    const extras = ws.mounts.map((m) => m.at);
+    const bounds = extras.length === 0
+        ? ' That directory is the whole of what can be reached: nothing outside it can be ' +
+            'read or written.'
+        : ` ${nameList(extras)} ${extras.length > 1 ? 'are' : 'is'} mounted alongside it: ` +
+            `read, list and search ${extras.length > 1 ? 'them' : 'it'} like anything else, ` +
+            'but nothing there can be written, moved or deleted. Nothing outside those ' +
+            'directories can be reached at all.';
+    const scope = (ws.mount
+        ? `The workspace is mounted at ${ws.mount}, which is the name commands running in ` +
+            `the sandbox print and the name these tools answer with, so a path from a ` +
+            `command's output can be used here unchanged. A path relative to the workspace ` +
+            `root names the same file: ${ws.mount}/src/a.ts and src/a.ts are one file.`
+        : 'Paths are relative to the workspace root.') + bounds;
+    const inside = (ws.mount
+        ? `Path in the workspace: ${ws.mount}/src/a.ts, or src/a.ts relative to the root — ` +
+            `the same file either way. The root itself is "${ws.mount}" or ".".`
+        : 'Path in the workspace, relative to its root: src/a.ts. The root itself is "." ' +
+            'or "/".') + (extras.length === 0 ? '' : ` Read-only: ${nameList(extras)}.`);
+    // With more than one tree in reach, "/" is not another name for the
+    // workspace root: it is where the trees hang, and listing it names them.
+    // One tree has nothing above it, so there "/" stays the root.
+    const trees = ws.mount && ws.mounts.length > 0
+        ? [ws.mount, ...extras].map((name) => ({ name, kind: 'dir' }))
+        : undefined;
     /**
      * `.`, `/`, the mount and nothing at all are four spellings of the root, and
      * a tool whose path is optional takes all four. A model that means "the top"
@@ -625,13 +729,20 @@ export function workspaceTools(opts) {
             properties: {
                 path: {
                     type: 'string',
-                    description: `${inside} Omit it to list the root.`,
+                    description: trees
+                        ? `${inside} Omit it, or give "/", to list the directories that can be ` +
+                            `reached: ${nameList(trees.map((t) => t.name))}.`
+                        : `${inside} Omit it to list the root.`,
                 },
             },
             required: [],
             additionalProperties: false,
         },
         execute: async ({ path }) => {
+            const asked = path?.trim() ?? '';
+            if (trees && (asked === '' || /^[\\/]+$/.test(asked))) {
+                return { path: '/', entries: trees };
+            }
             const at = root(path);
             const entries = await readdir(at, { withFileTypes: true });
             const listed = [];
@@ -687,7 +798,7 @@ export function workspaceTools(opts) {
             if (content.length > MAX_WRITE) {
                 return { error: `content exceeds ${MAX_WRITE} bytes` };
             }
-            const at = ws.within(path);
+            const at = ws.within(path, { write: true });
             await mkdir(dirname(at), { recursive: true });
             await writeFile(at, content, 'utf8');
             return {
@@ -770,12 +881,12 @@ export function workspaceTools(opts) {
         },
         execute: async ({ from, to, overwrite }) => {
             ws.mutable();
-            const source = ws.within(from);
-            const target = ws.within(to);
-            if (source === ws.root) {
+            const source = ws.within(from, { write: true });
+            const target = ws.within(to, { write: true });
+            if (ws.isRoot(source)) {
                 return { error: 'refusing to move the workspace root' };
             }
-            if (target === ws.root) {
+            if (ws.isRoot(target)) {
                 return { error: 'refusing to overwrite the workspace root' };
             }
             if (source === target) {
@@ -819,8 +930,8 @@ export function workspaceTools(opts) {
         },
         execute: async ({ path, recursive }) => {
             ws.mutable();
-            const at = ws.within(path);
-            if (at === ws.root) {
+            const at = ws.within(path, { write: true });
+            if (ws.isRoot(at)) {
                 return { error: 'refusing to delete the workspace root' };
             }
             const info = await stat(at);
@@ -857,24 +968,78 @@ export function workspaceTools(opts) {
             additionalProperties: false,
         },
         execute: async ({ pattern, path }) => {
-            const at = root(path);
+            // Omitting the path means "everywhere I can see", and what the
+            // model can see now includes the mounted trees. Searching only the
+            // workspace would leave them behind a path it has to know to ask
+            // for. A tree nested inside the workspace is walked twice, so the
+            // hits are a set: `show` gives one file one name either way.
+            const where = path?.trim()
+                ? [ws.within(path)]
+                : [ws.root, ...ws.mounts.map((m) => m.host)];
             const needle = pattern.toLowerCase();
-            const hits = [];
-            await walk(at, ws, (file) => {
-                // Matched on the path within the workspace, reported under the
-                // name the model uses: a mount prefix is on every candidate, so
-                // matching it would mean nothing.
-                if (ws.rel(file).toLowerCase().includes(needle)) {
-                    hits.push(ws.show(file));
+            const hits = new Set();
+            for (const dir of where) {
+                const room = await walk(dir, ws, (file) => {
+                    // Matched on the path within its own tree, reported under
+                    // the name the model uses: a mount prefix is on every
+                    // candidate, so matching it would mean nothing.
+                    if (ws.rel(file).toLowerCase().includes(needle)) {
+                        hits.add(ws.show(file));
+                    }
+                    return hits.size < MAX_ENTRIES;
+                });
+                if (!room) {
+                    break;
                 }
-                return hits.length < MAX_ENTRIES;
-            });
-            return { pattern, matches: hits, truncated: hits.length >= MAX_ENTRIES };
+            }
+            return {
+                pattern,
+                matches: [...hits],
+                truncated: hits.size >= MAX_ENTRIES,
+            };
         },
     });
-    return opts.readOnly
+    return named(ws, opts.readOnly
         ? [readFileTool, listDir, findFiles]
-        : [readFileTool, listDir, findFiles, writeFileTool, applyPatch, movePath, deleteFile];
+        : [readFileTool, listDir, findFiles, writeFileTool, applyPatch, movePath, deleteFile]);
+}
+/** What each errno means, said the way the rest of these tools say things. */
+const ERRNO = {
+    ENOENT: 'does not exist',
+    ENOTDIR: 'is not a directory',
+    EISDIR: 'is a directory',
+    EEXIST: 'already exists',
+    ENOTEMPTY: 'is not empty',
+    EACCES: 'cannot be reached',
+    EPERM: 'cannot be reached',
+    ELOOP: 'is a loop of symlinks',
+};
+/**
+ * Every path these tools are given comes back under the name the model wrote
+ * it — except when the filesystem itself fails, because Node's errors name the
+ * host path: `ENOENT: no such file or directory, scandir '/Users/me/proj/src'`.
+ * That is a name the model has never been shown, cannot pass to another tool,
+ * and will read as evidence about where it is running. So a failure is
+ * rewritten into the same vocabulary as a success before it leaves.
+ */
+function named(ws, tools) {
+    return tools.map((t) => ({
+        ...t,
+        execute: async (args, tc) => {
+            try {
+                return await t.execute(args, tc);
+            }
+            catch (err) {
+                const e = err;
+                if (typeof e?.code !== 'string' || typeof e.path !== 'string') {
+                    throw err;
+                }
+                throw new Error(`${ws.show(e.path)} ${ERRNO[e.code] ?? `failed: ${e.code}`}`, {
+                    cause: err,
+                });
+            }
+        },
+    }));
 }
 async function runPatch(ws, patch) {
     const ops = parsePatch(patch);
@@ -883,8 +1048,8 @@ async function runPatch(ws, patch) {
     const seen = new Set();
     let fuzz = 0;
     for (const op of ops) {
-        const at = ws.within(op.path);
-        if (at === ws.root) {
+        const at = patchPath(ws, op.path);
+        if (ws.isRoot(at)) {
             throw new PatchError(`${op.path} is the workspace root`);
         }
         if (seen.has(at)) {
@@ -953,8 +1118,8 @@ async function runPatch(ws, patch) {
             lines: patched.lines.length,
         };
         if (op.moveTo) {
-            const to = ws.within(op.moveTo);
-            if (to === ws.root) {
+            const to = patchPath(ws, op.moveTo);
+            if (ws.isRoot(to)) {
                 throw new PatchError('cannot move a file onto the workspace root');
             }
             if (to !== at) {
@@ -1000,6 +1165,21 @@ async function statOrNull(at) {
         return null;
     }
 }
+/**
+ * A path in a patch, checked for containment and for write permission before
+ * the first byte is written. Both refusals become patch errors, because the
+ * promise apply_patch makes is that a patch it will not finish leaves nothing
+ * behind — a read-only file named halfway down is a reason to reject the whole
+ * patch, not to write the files above it and then throw.
+ */
+function patchPath(ws, path) {
+    try {
+        return ws.within(path, { write: true });
+    }
+    catch (err) {
+        throw new PatchError(err instanceof Error ? err.message : String(err));
+    }
+}
 /** Depth-first, skipping the noise nobody means to search. */
 const SKIP = new Set(['.git', 'node_modules', '.data', 'dist', '.venv', '__pycache__']);
 async function walk(dir, ws, visit) {

package/dist/types.d.ts

@@ -174,9 +174,10 @@ export interface ToolSelection {
 }
 /**
  * Resolves selectors against the tools a host provided, in the order written
- * and without duplicates. A selector is a tool name, `<group>:*` for every tool
- * in a group, or `*` for everything; any of them prefixed with `-` removes
- * what it matches from the selection so far.
+ * and without duplicates. A selector is a tool name, `<group>:<name>` for the
+ * same tool written out in full, `<group>:*` for every tool in a group, or `*`
+ * for everything; any of them prefixed with `-` removes what it matches from
+ * the selection so far.
  */
 export declare function selectTools<TCtx>(available: AnyTool<TCtx>[], selectors: string[], opts: ToolSelection): AnyTool<TCtx>[];
 export declare const HANDOFF_PREFIX = "transfer_to_";