@qvac/harness 0.8.9 → 0.8.10

package/dist-lib/lib/tools/exec/obsidian/vault-write.js

@@ -1,15 +1,16 @@
 import fs from 'fs';
 import path from 'path';
+import { HarnessError } from '../../../errors.js';
 import { markdownFileName } from './note-name.js';
 import { appendToFile, dailyCandidates, ensureWithinRoot, FRONTMATTER_RE, getArg, getContentArg, moveFile, readFileSnapshot, resolveNotePath, todayStamp, updateFileText, writeIfUnchanged } from './vault-paths.js';
 export function handleAppend(vaultPath, args) {
     const notePath = resolveNotePath(vaultPath, args);
     if (!notePath || !fs.existsSync(notePath)) {
-        throw new Error(`Note not found. Args: ${args.join(', ')}`);
+        throw new HarnessError('OBSIDIAN_NOTE_NOT_FOUND', [args]);
     }
     const content = getContentArg(args);
     if (!content) {
-        throw new Error('Missing required argument: content=');
+        throw new HarnessError('OBSIDIAN_MISSING_ARGUMENT', ['content=']);
     }
     appendToFile(notePath, content);
     return `Appended to: ${path.relative(vaultPath, notePath)}`;
@@ -17,11 +18,11 @@ export function handleAppend(vaultPath, args) {
 export function handlePrepend(vaultPath, args) {
     const notePath = resolveNotePath(vaultPath, args);
     if (!notePath || !fs.existsSync(notePath)) {
-        throw new Error(`Note not found. Args: ${args.join(', ')}`);
+        throw new HarnessError('OBSIDIAN_NOTE_NOT_FOUND', [args]);
     }
     const content = getContentArg(args);
     if (!content) {
-        throw new Error('Missing required argument: content=');
+        throw new HarnessError('OBSIDIAN_MISSING_ARGUMENT', ['content=']);
     }
     updateFileText(notePath, (existing) => content + existing);
     return `Prepended to: ${path.relative(vaultPath, notePath)}`;
@@ -40,7 +41,7 @@ function uniqueTrashPath(base) {
 export function handleDelete(vaultPath, args) {
     const notePath = resolveNotePath(vaultPath, args);
     if (!notePath || !fs.existsSync(notePath)) {
-        throw new Error(`Note not found. Args: ${args.join(', ')}`);
+        throw new HarnessError('OBSIDIAN_NOTE_NOT_FOUND', [args]);
     }
     const root = path.resolve(vaultPath);
     const trashPath = uniqueTrashPath(ensureWithinRoot(vaultPath, path.join('.trash', path.relative(root, notePath))));
@@ -51,11 +52,11 @@ export function handleDelete(vaultPath, args) {
 export function handleMove(vaultPath, args) {
     const notePath = resolveNotePath(vaultPath, args);
     if (!notePath || !fs.existsSync(notePath)) {
-        throw new Error(`Note not found. Args: ${args.join(', ')}`);
+        throw new HarnessError('OBSIDIAN_NOTE_NOT_FOUND', [args]);
     }
     const to = getArg(args, 'to');
     if (!to) {
-        throw new Error('Missing required argument: to=');
+        throw new HarnessError('OBSIDIAN_MISSING_ARGUMENT', ['to=']);
     }
     const destDir = ensureWithinRoot(vaultPath, to);
     if (!fs.existsSync(destDir)) {
@@ -68,11 +69,11 @@ export function handleMove(vaultPath, args) {
 export function handleRename(vaultPath, args) {
     const notePath = resolveNotePath(vaultPath, args);
     if (!notePath || !fs.existsSync(notePath)) {
-        throw new Error(`Note not found. Args: ${args.join(', ')}`);
+        throw new HarnessError('OBSIDIAN_NOTE_NOT_FOUND', [args]);
     }
     const newName = getArg(args, 'name');
     if (!newName) {
-        throw new Error('Missing required argument: name=');
+        throw new HarnessError('OBSIDIAN_MISSING_ARGUMENT', ['name=']);
     }
     const fileName = markdownFileName(newName);
     const relativeDir = path.relative(path.resolve(vaultPath), path.dirname(notePath));
@@ -96,11 +97,11 @@ function mergeIntoFrontmatter(fmBlock, newProps) {
 export function handlePropertySet(vaultPath, args) {
     const notePath = resolveNotePath(vaultPath, args);
     if (!notePath || !fs.existsSync(notePath)) {
-        throw new Error(`Note not found. Args: ${args.join(', ')}`);
+        throw new HarnessError('OBSIDIAN_NOTE_NOT_FOUND', [args]);
     }
     const propArgs = args.filter((a) => !a.startsWith('file=') && !a.startsWith('path=') && a.includes('='));
     if (propArgs.length === 0) {
-        throw new Error('No property key=value pairs provided.');
+        throw new HarnessError('OBSIDIAN_NO_PROPERTIES');
     }
     const newProps = propArgs.map((a) => {
         const eqIdx = a.indexOf('=');
@@ -120,7 +121,7 @@ export function handlePropertySet(vaultPath, args) {
 export function handleDailyAppend(vaultPath, args) {
     const content = getContentArg(args);
     if (!content) {
-        throw new Error('Missing required argument: content=');
+        throw new HarnessError('OBSIDIAN_MISSING_ARGUMENT', ['content=']);
     }
     const dateStr = todayStamp();
     let target = null;

package/dist-lib/lib/tools/exec/runner.js

@@ -1,5 +1,6 @@
 import b4a from 'b4a';
 import process from 'process';
+import { HarnessError } from '../../errors.js';
 import { AbortedError } from '../../helpers/race-abort.js';
 const DEFAULT_TIMEOUT_MS = 120_000;
 export const MAX_OUTPUT_CHARS = 8_192;
@@ -74,7 +75,7 @@ export function runCommand(command, options) {
         };
         options.signal?.addEventListener('abort', onAbort, { once: true });
         const timer = setTimeout(() => {
-            finish(() => reject(new Error(`Command timed out after ${timeoutMs}ms`)));
+            finish(() => reject(new HarnessError('COMMAND_TIMED_OUT', [timeoutMs])));
             terminateProcessTree(child, options.killProcess);
         }, timeoutMs);
         child.stdout?.on('data', (chunk) => appendOutput(stdout, chunk, maxOutputChars));

package/dist-lib/lib/tools/files/edit-file.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from '../../capabilities/completion.ts';
+import { type FsToolOptions } from '../fs/scope.ts';
+export declare function createEditFileTool({ realpath, deniedRoots }?: FsToolOptions): ToolDefinition;

package/dist-lib/lib/tools/files/edit-file.js

@@ -0,0 +1,73 @@
+import b4a from 'b4a';
+import { errorMessage } from '../../guards.js';
+import { editMatch } from '../fs/edit-match.js';
+import { defaultRealpath } from '../fs/scope.js';
+import { resolveRooted, rootedLabel, stringArg } from '../fs/tool-path.js';
+import { writeText } from '../fs/write.js';
+export function createEditFileTool({ realpath = defaultRealpath, deniedRoots } = {}) {
+    return {
+        name: 'edit_file',
+        toolset: 'files',
+        description: 'Change part of a file in the shared folder: replaces the text in old with new. old must match ' +
+            'one place in the file (copy it from read_file, without the line numbers); set replaceAll to ' +
+            'change every match. Asks the user first.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path, relative to the shared folder' },
+                old: { type: 'string', description: 'The exact text to replace' },
+                new: { type: 'string', description: 'The text to put in its place' },
+                replaceAll: { type: 'boolean', description: 'Replace every match instead of exactly one' }
+            },
+            required: ['path', 'old', 'new']
+        },
+        effect: () => 'write',
+        autoApprove: false,
+        writeRootsRequired: true,
+        validate(args) {
+            if (!stringArg(args, 'path'))
+                return 'path is required';
+            if (typeof args.old !== 'string' || !args.old) {
+                return 'old must be the text to replace';
+            }
+            return typeof args.new === 'string' ? null : 'new must be a string';
+        },
+        resource: (args, ctx) => ({
+            kind: 'file',
+            label: rootedLabel('edit', { grants: ctx, paths: [String(args.path)] })
+        }),
+        async execute(args, ctx) {
+            const requested = String(args.path);
+            const resolved = await resolveRooted(requested, {
+                grants: ctx,
+                write: true,
+                realpath,
+                deniedRoots
+            });
+            if ('error' in resolved) {
+                return resolved;
+            }
+            try {
+                const { drive } = resolved.root;
+                const entry = await drive.entry(resolved.key);
+                const blob = entry === null ? null : await drive.get(resolved.key);
+                if (entry === null || blob === null) {
+                    return { error: `no such file: ${requested}` };
+                }
+                const result = editMatch(b4a.toString(blob, 'utf8'), {
+                    old: String(args.old),
+                    replacement: String(args.new),
+                    replaceAll: args.replaceAll === true
+                });
+                if (result.error) {
+                    return { error: result.error };
+                }
+                await writeText(drive, resolved.key, result.content, { executable: entry.value.executable });
+                return { edited: requested, replacements: result.count };
+            }
+            catch (err) {
+                return { error: errorMessage(err) };
+            }
+        }
+    };
+}

package/dist-lib/lib/tools/files/glob.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from '../../capabilities/completion.ts';
+import { type FsToolOptions } from '../fs/scope.ts';
+export declare function createGlobTool({ realpath, deniedRoots }?: FsToolOptions): ToolDefinition;

package/dist-lib/lib/tools/files/glob.js

@@ -0,0 +1,63 @@
+import { relativeKey, searchTargets } from '../fs/targets.js';
+import { compileGlob } from '../fs/glob.js';
+import { canonicalDenyRoots, defaultRealpath, isDeniedPath } from '../fs/scope.js';
+import { anchorOf, shownPath, stringArg } from '../fs/tool-path.js';
+import { walkFiles } from '../fs/walk.js';
+import { folderArg } from './list-dir.js';
+const GLOB_MATCHES = 100;
+export function createGlobTool({ realpath = defaultRealpath, deniedRoots } = {}) {
+    return {
+        name: 'glob',
+        toolset: 'files',
+        description: 'Find files in the shared folder by name pattern, newest first. "**" crosses folders: ' +
+            '"**/*.md" finds every Markdown file, "*report*" matches names anywhere.',
+        parameters: {
+            type: 'object',
+            properties: {
+                pattern: { type: 'string', description: 'Name or path pattern, e.g. "**/*.pdf"' },
+                dir: {
+                    type: 'string',
+                    description: 'Folder to search, relative to the shared folder (optional)'
+                }
+            },
+            required: ['pattern']
+        },
+        effect: () => 'read',
+        stableRead: true,
+        autoApprove: true,
+        rootsRequired: true,
+        validate: (args) => (stringArg(args, 'pattern') ? null : 'pattern is required'),
+        resource: (args) => ({ kind: 'file', label: `glob ${String(args.pattern ?? '')}` }),
+        async execute(args, ctx) {
+            const roots = ctx?.fsRoots ?? [];
+            const deny = await canonicalDenyRoots(deniedRoots, realpath);
+            const scoped = await searchTargets(folderArg(args, ctx), roots, { realpath, deny });
+            if ('error' in scoped) {
+                return scoped;
+            }
+            const pattern = String(args.pattern);
+            const test = compileGlob(pattern);
+            const byName = !pattern.includes('/');
+            const hits = [];
+            let walkTruncated = false;
+            for (const target of scoped.targets) {
+                const walk = await walkFiles(target.root, target.folder);
+                walkTruncated ||= walk.truncated;
+                for (const file of walk.files) {
+                    const rel = relativeKey(file.key, target.folder);
+                    const name = rel.slice(rel.lastIndexOf('/') + 1);
+                    if (isDeniedPath(file.path, deny) || !(test(rel) || (byName && test(name)))) {
+                        continue;
+                    }
+                    const entry = await target.root.drive.entry(file.key);
+                    hits.push({ path: shownPath(file.path, anchorOf(ctx)), mtime: entry?.mtime ?? 0 });
+                }
+            }
+            hits.sort((a, b) => b.mtime - a.mtime);
+            return {
+                matches: hits.slice(0, GLOB_MATCHES).map((hit) => hit.path),
+                truncated: walkTruncated || hits.length > GLOB_MATCHES || undefined
+            };
+        }
+    };
+}

package/dist-lib/lib/tools/files/grep.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from '../../capabilities/completion.ts';
+import { type FsToolOptions } from '../fs/scope.ts';
+export declare function createGrepTool({ realpath, deniedRoots }?: FsToolOptions): ToolDefinition;

package/dist-lib/lib/tools/files/grep.js

@@ -0,0 +1,114 @@
+import { errorMessage } from '../../guards.js';
+import { searchTargets } from '../fs/targets.js';
+import { compileGlob } from '../fs/glob.js';
+import { readLines } from '../fs/read.js';
+import { canonicalDenyRoots, defaultRealpath, isDeniedPath } from '../fs/scope.js';
+import { anchorOf, shownPath, stringArg } from '../fs/tool-path.js';
+import { walkFiles } from '../fs/walk.js';
+import { folderArg } from './list-dir.js';
+const GREP_MATCHES = 100;
+const MAX_LINE_CHARS = 300;
+export function createGrepTool({ realpath = defaultRealpath, deniedRoots } = {}) {
+    return {
+        name: 'grep',
+        toolset: 'files',
+        description: 'Search inside the files of the shared folder. The pattern is plain text, case-insensitive; set ' +
+            'regex for a regular expression. Returns "path:line: text". Narrow with include (e.g. "*.ts").',
+        parameters: {
+            type: 'object',
+            properties: {
+                pattern: { type: 'string', description: 'Text to find' },
+                dir: {
+                    type: 'string',
+                    description: 'Folder to search, relative to the shared folder (optional)'
+                },
+                include: {
+                    type: 'string',
+                    description: 'Only files whose name matches this pattern (optional)'
+                },
+                regex: { type: 'boolean', description: 'Treat pattern as a regular expression' }
+            },
+            required: ['pattern']
+        },
+        effect: () => 'read',
+        stableRead: true,
+        autoApprove: true,
+        rootsRequired: true,
+        validate(args) {
+            if (!stringArg(args, 'pattern'))
+                return 'pattern is required';
+            if (args.regex !== true)
+                return null;
+            try {
+                new RegExp(String(args.pattern), 'i');
+                return null;
+            }
+            catch (err) {
+                return `invalid regex: ${errorMessage(err)}`;
+            }
+        },
+        resource: (args) => ({ kind: 'file', label: `grep ${String(args.pattern ?? '')}` }),
+        async execute(args, ctx) {
+            const roots = ctx?.fsRoots ?? [];
+            const deny = await canonicalDenyRoots(deniedRoots, realpath);
+            const scoped = await searchTargets(folderArg(args, ctx), roots, { realpath, deny });
+            if ('error' in scoped) {
+                return scoped;
+            }
+            const include = stringArg(args, 'include') ? compileGlob(String(args.include)) : null;
+            const scan = { matches: matcher(args), anchor: anchorOf(ctx), rows: [] };
+            const walkTruncated = await scanTargets(scoped.targets, scan, { deny, include });
+            return {
+                matches: scan.rows.slice(0, GREP_MATCHES).join('\n') || 'no matches',
+                truncated: walkTruncated || scan.rows.length > GREP_MATCHES || undefined
+            };
+        }
+    };
+}
+function matcher(args) {
+    const pattern = String(args.pattern);
+    if (args.regex === true) {
+        const rx = new RegExp(pattern, 'i');
+        return (line) => rx.test(line);
+    }
+    const needle = pattern.toLowerCase();
+    return (line) => line.toLowerCase().includes(needle);
+}
+async function scanTargets(targets, scan, { deny, include }) {
+    let truncated = false;
+    for (const target of targets) {
+        const walk = await walkFiles(target.root, target.folder);
+        truncated ||= walk.truncated;
+        for (const file of walk.files) {
+            const name = file.key.slice(file.key.lastIndexOf('/') + 1);
+            if (isDeniedPath(file.path, deny) || (include && !include(name))) {
+                continue;
+            }
+            await scanFile(target.root.drive, file, scan);
+            if (scan.rows.length > GREP_MATCHES) {
+                return truncated;
+            }
+        }
+    }
+    return truncated;
+}
+async function scanFile(drive, file, { matches, anchor, rows }) {
+    let index = 0;
+    try {
+        for await (const line of readLines(drive, file.key)) {
+            index++;
+            if (line.includes('\0')) {
+                break;
+            }
+            if (matches(line)) {
+                rows.push(`${shownPath(file.path, anchor)}:${index}: ${line.slice(0, MAX_LINE_CHARS)}`);
+            }
+            if (rows.length > GREP_MATCHES) {
+                break;
+            }
+        }
+    }
+    catch {
+        return;
+    }
+}

package/dist-lib/lib/tools/files/index.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from '../../capabilities/completion.ts';
+import type { FsToolOptions } from '../fs/scope.ts';
+export declare function createFileTools(options?: FsToolOptions): ToolDefinition[];

package/dist-lib/lib/tools/files/index.js

@@ -0,0 +1,23 @@
+import { createEditFileTool } from './edit-file.js';
+import { createGlobTool } from './glob.js';
+import { createGrepTool } from './grep.js';
+import { createListDirTool } from './list-dir.js';
+import { createMakeDirTool } from './make-dir.js';
+import { createReadFileTool } from './read-file.js';
+import { createCopyFileTool, createMoveFileTool } from './transfer.js';
+import { createTrashFileTool } from './trash-file.js';
+import { createWriteFileTool } from './write-file.js';
+export function createFileTools(options = {}) {
+    return [
+        createReadFileTool(options),
+        createListDirTool(options),
+        createGlobTool(options),
+        createGrepTool(options),
+        createWriteFileTool(options),
+        createEditFileTool(options),
+        createMoveFileTool(options),
+        createCopyFileTool(options),
+        createMakeDirTool(options),
+        createTrashFileTool(options)
+    ];
+}

package/dist-lib/lib/tools/files/list-dir.d.ts

@@ -0,0 +1,5 @@
+import type { ToolDefinition } from '../../capabilities/completion.ts';
+import { type FsToolOptions } from '../fs/scope.ts';
+import { type Grants } from '../fs/tool-path.ts';
+export declare function createListDirTool({ realpath, deniedRoots }?: FsToolOptions): ToolDefinition;
+export declare function folderArg(args: Record<string, unknown>, grants: Grants | undefined): string | undefined;

package/dist-lib/lib/tools/files/list-dir.js

@@ -0,0 +1,130 @@
+import fs from 'fs';
+import { relativeKey, searchTargets } from '../fs/targets.js';
+import { canonicalDenyRoots, defaultRealpath, displayPath, hostPath, isDeniedPath } from '../fs/scope.js';
+import { anchorOf, rootedPath, stringArg } from '../fs/tool-path.js';
+import { WALK_SKIP_DIRS, walkFiles } from '../fs/walk.js';
+const LIST_ENTRIES = 200;
+export function createListDirTool({ realpath = defaultRealpath, deniedRoots } = {}) {
+    return {
+        name: 'list_dir',
+        toolset: 'files',
+        description: 'List a folder inside the shared folder: each entry with its type, size and last change. ' +
+            'Leave path empty for the shared folder itself. Use this, not exec, to look inside it.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Folder, relative to the shared folder (optional)' }
+            }
+        },
+        effect: () => 'read',
+        stableRead: true,
+        autoApprove: true,
+        rootsRequired: true,
+        resource: (args, ctx) => ({
+            kind: 'file',
+            label: `list ${folderArg(args, ctx) ?? 'shared folder'}`
+        }),
+        async execute(args, ctx) {
+            const roots = ctx?.fsRoots ?? [];
+            const deny = await canonicalDenyRoots(deniedRoots, realpath);
+            const scoped = await searchTargets(folderArg(args, ctx), roots, { realpath, deny });
+            if ('error' in scoped) {
+                return scoped;
+            }
+            const { entries, truncated } = await collect(scoped.targets, { deny, anchor: anchorOf(ctx) });
+            const rows = await describe([...entries].slice(0, LIST_ENTRIES));
+            return {
+                entries: rows.join('\n') || '(empty)',
+                truncated: truncated || entries.size > LIST_ENTRIES || undefined
+            };
+        }
+    };
+}
+export function folderArg(args, grants) {
+    const folder = stringArg(args, 'dir') ?? stringArg(args, 'path');
+    return folder && folder !== '.' && folder !== '/'
+        ? rootedPath(folder, anchorOf(grants))
+        : undefined;
+}
+async function collect(targets, { deny, anchor }) {
+    const entries = new Map();
+    let truncated = false;
+    for (const target of targets) {
+        const own = targets.length === 1 || target.root === anchor;
+        const level = target.root.kind === 'local'
+            ? await localLevel(target.root, target.folder, deny)
+            : await walkedLevel(target, deny);
+        truncated ||= level.truncated;
+        for (const child of level.children) {
+            const name = own ? child.name : displayPath(target.root, child.key);
+            entries.set(name, { ...child, drive: target.root.drive });
+        }
+    }
+    return { entries, truncated };
+}
+async function localLevel(root, folder, deny) {
+    const children = [];
+    for (const dirent of await readdir(hostPath(root, folder))) {
+        const key = childKey(folder, dirent.name);
+        if (dirent.isSymbolicLink() || isDeniedPath(hostPath(root, key), deny)) {
+            continue;
+        }
+        if (dirent.isDirectory() && !WALK_SKIP_DIRS.has(dirent.name)) {
+            const items = (await readdir(hostPath(root, key))).length;
+            children.push({ name: dirent.name, key, folder: true, items });
+        }
+        else if (dirent.isFile()) {
+            children.push({ name: dirent.name, key, folder: false, items: 0 });
+        }
+        if (children.length > LIST_ENTRIES) {
+            return { children, truncated: true };
+        }
+    }
+    return { children, truncated: false };
+}
+async function walkedLevel(target, deny) {
+    const walk = await walkFiles(target.root, target.folder);
+    const children = [];
+    const folders = new Map();
+    for (const file of walk.files) {
+        if (isDeniedPath(file.path, deny))
+            continue;
+        const [name, below] = relativeKey(file.key, target.folder).split('/');
+        if (below === undefined) {
+            children.push({ name, key: file.key, folder: false, items: 0 });
+            continue;
+        }
+        folders.set(name, (folders.get(name) ?? new Set()).add(below));
+    }
+    for (const [name, items] of folders) {
+        children.push({ name, key: childKey(target.folder, name), folder: true, items: items.size });
+    }
+    return { children, truncated: walk.truncated };
+}
+async function readdir(dir) {
+    try {
+        return await fs.promises.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+}
+function childKey(folder, name) {
+    return folder === '/' ? `/${name}` : `${folder}/${name}`;
+}
+async function describe(entries) {
+    const rows = [];
+    for (const [name, entry] of entries) {
+        if (entry.folder) {
+            rows.push(`${name}/  (folder, ${entry.items} ${entry.items === 1 ? 'item' : 'items'})`);
+            continue;
+        }
+        const stat = await entry.drive.entry(entry.key);
+        const size = stat?.value.blob?.byteLength ?? 0;
+        const changed = stat?.mtime
+            ? `, changed ${new Date(stat.mtime).toISOString().slice(0, 16)}`
+            : '';
+        rows.push(`${name}  (${size} bytes${changed})`);
+    }
+    return rows;
+}

package/dist-lib/lib/tools/files/make-dir.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from '../../capabilities/completion.ts';
+import { type FsToolOptions } from '../fs/scope.ts';
+export declare function createMakeDirTool({ realpath, deniedRoots }?: FsToolOptions): ToolDefinition;

package/dist-lib/lib/tools/files/make-dir.js

@@ -0,0 +1,47 @@
+import fs from 'fs';
+import { errorMessage } from '../../guards.js';
+import { defaultRealpath } from '../fs/scope.js';
+import { localPathOf, resolveRooted, rootedLabel, stringArg } from '../fs/tool-path.js';
+export function createMakeDirTool({ realpath = defaultRealpath, deniedRoots } = {}) {
+    return {
+        name: 'make_dir',
+        toolset: 'files',
+        description: 'Create a folder (and any missing parents) inside the shared folder.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Folder path, relative to the shared folder' }
+            },
+            required: ['path']
+        },
+        effect: () => 'read',
+        writeRootsRequired: true,
+        validate: (args) => (stringArg(args, 'path') ? null : 'path is required'),
+        resource: (args, ctx) => ({
+            kind: 'file',
+            label: rootedLabel('mkdir', { grants: ctx, paths: [String(args.path)] })
+        }),
+        async execute(args, ctx) {
+            const resolved = await resolveRooted(String(args.path), {
+                grants: ctx,
+                write: true,
+                realpath,
+                deniedRoots
+            });
+            if ('error' in resolved) {
+                return resolved;
+            }
+            const target = localPathOf(resolved);
+            if (!target) {
+                return { error: 'folders can only be created in a folder on this device' };
+            }
+            try {
+                await fs.promises.mkdir(target, { recursive: true });
+                return { created: String(args.path) };
+            }
+            catch (err) {
+                return { error: errorMessage(err) };
+            }
+        }
+    };
+}

package/dist-lib/lib/tools/files/read-file.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from '../../capabilities/completion.ts';
+import { type FsToolOptions } from '../fs/scope.ts';
+export declare function createReadFileTool({ realpath, deniedRoots }?: FsToolOptions): ToolDefinition;