@qvac/harness 0.1.0 → 0.1.2

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

@@ -0,0 +1,459 @@
+import fs from 'fs';
+import path from 'path';
+import { AbortedError } from "../helpers/race-abort.js";
+import { spawnEnv } from "../helpers/spawn-path.js";
+import { checkPdfBuildSource, checkBareLengthArgs, checkPptxBuildSource, checkPythonSource, checkUnstagedRead, createPythonAdapter, isPythonLanguage, looksLikePythonSource, parseInputs, parseOutputs, parsePackages, parseWorkdir, runsThroughPyodide, unwrapPythonSource } from "./exec/adapters/python/python-adapter.js";
+import { pythonCreateEffect } from "./exec/adapters/python/create-effect.js";
+import { createShellAdapter } from "./exec/adapters/shell/shell-adapter.js";
+import { routeObsidianCommand } from "./exec/obsidian/route.js";
+import { MAX_OUTPUT_CHARS_LIMIT } from "./exec/runner.js";
+import { bareBin, firstCommandToken, sanitizeCommand } from "./exec/scope.js";
+import { shellArgv } from "./exec/shell-argv.js";
+import { canonicalDenyRoots, defaultRealpath, hostPath, resolveKey } from "./fs/scope.js";
+import { unquoteArg } from "./model-args.js";
+import { settingsEnv } from "./skills/skill-settings.js";
+import { checkCliOps } from "./skills/cli-schema.js";
+function parsePositiveInt(value, name, max) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    const n = typeof value === 'number' ? value : Number(value);
+    if (!Number.isInteger(n) || n <= 0 || n > max) {
+        return { error: `${name} must be a positive integer ≤ ${max}` };
+    }
+    return n;
+}
+function resolveShellOps(command, toolOps) {
+    const bin = bareBin(firstCommandToken(command));
+    return { ops: (bin ? toolOps?.get(bin) : undefined) ?? [], argv: shellArgv(command).slice(1) };
+}
+function checkShellScope(command, toolOps) {
+    const unsafe = sanitizeCommand(command);
+    if (unsafe)
+        return unsafe;
+    const { ops, argv } = resolveShellOps(command, toolOps);
+    if (ops.length === 0)
+        return null;
+    return checkCliOps(argv, ops);
+}
+function shellEffect(command, toolOps) {
+    const { ops, argv } = resolveShellOps(command, toolOps);
+    const matched = ops.filter((op) => op.check(argv) === null);
+    if (matched.length === 0)
+        return 'write';
+    return matched.every((op) => op.annotation(argv) === 'read') ? 'read' : 'write';
+}
+export async function bareRuntime() {
+    const [{ spawn }, { default: process }] = await Promise.all([
+        import('bare-subprocess'),
+        import('bare-process')
+    ]);
+    const rawSpawn = spawn;
+    const spawnFn = (command, opts = {}) => rawSpawn(command, { ...opts, env: spawnEnv(process.env, process.platform, opts.env) });
+    return { spawn: spawnFn, killProcess: process.kill.bind(process) };
+}
+function resolveExecution(adapters, fallback, args, ctx) {
+    for (const adapter of adapters) {
+        const plan = adapter.resolve(args, ctx);
+        if (plan)
+            return plan;
+    }
+    return fallback.resolve(args, ctx);
+}
+function checkFileArgs(args, python) {
+    const inputs = parseInputs(args.inputs);
+    if (inputs && 'error' in inputs)
+        return inputs.error;
+    const outputs = parseOutputs(args.outputs);
+    if (outputs && 'error' in outputs)
+        return outputs.error;
+    if ((inputs || outputs) && !python) {
+        return 'inputs and outputs require language "python" with Pyodide enabled';
+    }
+    if (!python)
+        return null;
+    const workdir = parseWorkdir(args.workdir);
+    return workdir && typeof workdir === 'object' ? workdir.error : null;
+}
+function truncateLabel(text) {
+    return text.length > 120 ? `${text.slice(0, 120)}…` : text;
+}
+function packageSuffix(args) {
+    if (!Array.isArray(args.packages) || args.packages.length === 0)
+        return '';
+    const count = args.packages.length;
+    return ` (+${count} pkg${count === 1 ? '' : 's'}: ${truncateLabel(args.packages.join(', '))})`;
+}
+function uploadOrdinal(inputs, index) {
+    return inputs.slice(0, index + 1).filter((i) => i.attachmentId === undefined).length;
+}
+function fileSuffix(args) {
+    const inputs = parseInputs(args.inputs);
+    const outputs = parseOutputs(args.outputs);
+    const from = Array.isArray(inputs) && inputs.length > 0
+        ? ` ← ${inputs.length} file${inputs.length === 1 ? '' : 's'} (${truncateLabel(inputs
+            .map((i, n) => `${i.attachmentId ?? `upload-${uploadOrdinal(inputs, n)}`}→${i.path}`)
+            .join(', '))})`
+        : '';
+    const to = Array.isArray(outputs) && outputs.length > 0 ? ` → ${truncateLabel(outputs.join(', '))}` : '';
+    return `${from}${to}`;
+}
+const PYTHON_BINS = new Set(['python', 'python3', 'py', 'pip', 'pip3']);
+function commandRequiredError(args) {
+    const staged = Array.isArray(args.inputs) || Array.isArray(args.outputs);
+    return staged
+        ? 'command is required: keep these same inputs/outputs and add either command (the bare ' +
+            'python source) or script + scriptArgs exactly as the loaded skill reference shows'
+        : 'command is required';
+}
+function parseScriptArgs(value) {
+    if (Array.isArray(value))
+        return value.map(String);
+    if (typeof value === 'string' && value.trim().startsWith('[')) {
+        try {
+            const parsed = JSON.parse(value);
+            if (Array.isArray(parsed))
+                return parsed.map(String);
+        }
+        catch {
+        }
+    }
+    return [];
+}
+function normalizeScriptCall(rawArgs) {
+    let script = typeof rawArgs.script === 'string' ? unquoteArg(rawArgs.script) : '';
+    let scriptArgs = parseScriptArgs(rawArgs.scriptArgs);
+    if (!script || script.includes('\n'))
+        return { script, scriptArgs };
+    if (script.includes(' ')) {
+        const tokens = script.split(/\s+/).filter(Boolean);
+        script = tokens[0] ?? '';
+        if (!scriptArgs.length)
+            scriptArgs = tokens.slice(1);
+    }
+    if (!script.startsWith('scripts/') && !script.includes('/'))
+        script = `scripts/${script}`;
+    return { script, scriptArgs };
+}
+export function resolveScriptRun(rawArgs, skillsDir) {
+    const { script, scriptArgs } = normalizeScriptCall(rawArgs);
+    if (!script) {
+        if (scriptArgs.length) {
+            return {
+                error: 'scriptArgs need `script`: pass the scripts/*.py path exactly as the skill instructions name it'
+            };
+        }
+        return null;
+    }
+    if (script.includes('\n')) {
+        return {
+            args: { ...rawArgs, language: 'python', command: script, script: undefined },
+            trusted: false
+        };
+    }
+    const skill = typeof rawArgs.skill === 'string' ? unquoteArg(rawArgs.skill) : '';
+    if (!skill)
+        return { error: 'script runs need the owning skill name in `skill`' };
+    if (!skillsDir)
+        return { error: 'script execution is not available on this device' };
+    if (String(rawArgs.command ?? '').trim()) {
+        return { error: 'pass either command or script, never both' };
+    }
+    if (!script.startsWith('scripts/') || !script.endsWith('.py')) {
+        return {
+            error: `script must be a scripts/*.py path from the skill instructions, got: ${script}`
+        };
+    }
+    const segments = [...skill.split('/'), ...script.split('/')];
+    if (segments.some((segment) => segment === '' || segment === '..' || segment.includes('\\'))) {
+        return { error: `script not found in skill ${skill}: ${script}` };
+    }
+    let source;
+    try {
+        source = fs.readFileSync(path.join(skillsDir, skill, script), 'utf8');
+    }
+    catch {
+        return { error: `script not found in skill ${skill}: ${script}` };
+    }
+    const staged = stagingGap(rawArgs, scriptArgs);
+    if (staged)
+        return { error: staged };
+    const argv = JSON.stringify([script.slice('scripts/'.length), ...scriptArgs]);
+    const command = `import sys\nsys.argv = ${argv}\n${source}`;
+    return { args: { ...rawArgs, language: 'python', command, scriptArgs }, trusted: true };
+}
+const SCRIPT_FILE_ARG = /^[\w][\w.-]*\.(pdf|txt|md|csv|docx|xlsx|pptx|png|jpe?g)$/i;
+function stagingGap(rawArgs, scriptArgs) {
+    const inputs = parseInputs(rawArgs.inputs);
+    const outputs = parseOutputs(rawArgs.outputs);
+    const known = new Set([
+        ...(Array.isArray(inputs) ? inputs.map((input) => input.path) : []),
+        ...(Array.isArray(outputs) ? outputs : [])
+    ]);
+    const missing = scriptArgs.filter((arg) => SCRIPT_FILE_ARG.test(arg) && !known.has(arg));
+    if (!missing.length)
+        return null;
+    return (`scriptArgs name ${missing.map((name) => `"${name}"`).join(', ')} but the working directory ` +
+        'starts empty: stage each existing file in inputs [{ attachmentId, path }] and declare each ' +
+        'produced file in outputs');
+}
+function scriptLabel(args) {
+    const { script, scriptArgs } = normalizeScriptCall(args);
+    const argsSuffix = scriptArgs.length ? ` ${scriptArgs.join(' ')}` : '';
+    return `python script ${unquoteArg(args.skill ?? '?')}/${script}${argsSuffix}`;
+}
+const WORKDIR_NO_ROOTS_ERROR = 'workdir is not available: no directories are granted to this device, so a working directory ' +
+    'cannot be validated. Omit workdir and use absolute paths in the command.';
+function checkExecutionScope(args, toolOps, disablePyodide) {
+    const command = String(args.command ?? '').trim();
+    if (runsThroughPyodide(args.language, disablePyodide))
+        return null;
+    if (!disablePyodide && PYTHON_BINS.has(bareBin(firstCommandToken(command)) ?? '')) {
+        return 'run Python by passing language="python" with the bare Python source in command; the exec shell path does not run python or pip';
+    }
+    const callsFirst = /^[A-Za-z_][\w.]*\s*\(/.test(command);
+    const sourceShaped = (/^from\s+\w+\s+import\b/.test(command) || command.includes('\n')) &&
+        looksLikePythonSource(command);
+    if (!disablePyodide && (callsFirst || sourceShaped)) {
+        return 'this command is Python source: pass language "python" with the bare source in command (dependencies in packages, produced files in outputs)';
+    }
+    return checkShellScope(command, toolOps);
+}
+async function skillsEnv(skillSettings, ctx) {
+    const skills = ctx?.skills ?? [];
+    if (skills.length === 0)
+        return undefined;
+    const env = {};
+    for (const skill of skills) {
+        Object.assign(env, settingsEnv(skill, await skillSettings(skill, ctx?.agentId)));
+    }
+    return Object.keys(env).length > 0 ? env : undefined;
+}
+export function createExecTool({ spawn, killProcess, loadPyodide, disablePyodide = false, credentialStore, skillSettings, realpath = defaultRealpath, deniedRoots, skillsDir } = {}) {
+    const adapters = [createPythonAdapter(disablePyodide, loadPyodide)];
+    const fallback = createShellAdapter({ spawn, killProcess, loadRuntime: bareRuntime });
+    return {
+        name: 'exec',
+        toolset: 'exec',
+        description: "Execute a shell command on the user's device, or Python via in-process Pyodide. " +
+            'One program per call: chaining, pipes, redirection and shell expansion are rejected. ' +
+            'Returns stdout, stderr, and exit code. ' +
+            'For Python: pass language="python" with the bare Python source in command — the first line of ' +
+            'command is the first line of the program, there is no shell or interpreter to invoke, and ' +
+            'packages are declared in packages rather than installed. ' +
+            'When a loaded skill names a bundled script, run it by passing skill and script (with scriptArgs) ' +
+            'instead of command — never retype a script as source. ' +
+            'Prefer one-shot commands; do not use for long-running daemons.',
+        parameters: {
+            type: 'object',
+            properties: {
+                command: {
+                    type: 'string',
+                    description: 'Shell command, or — when language is python — the Python source itself, ' +
+                        'whose first line is the first line of the program (no shell, no interpreter, no quoting)'
+                },
+                language: {
+                    type: 'string',
+                    description: 'Optional runtime. "python" runs command as Python via in-process Pyodide. Default is shell.'
+                },
+                packages: {
+                    type: 'array',
+                    description: 'Optional array of PyPI package names (strings) to install (via micropip) before the code runs. Only with language "python".'
+                },
+                inputs: {
+                    type: 'array',
+                    description: 'Optional chat attachments to place in the working directory before the code runs, as objects {attachmentId, path}. path is a bare file name (no directories). Omit attachmentId to stage the image the user attached to their latest message. Any other uploaded file — PDF, .docx, .xlsx, .pptx — is staged by attachmentId, copied verbatim from the [Attached file "…"] line on the user\'s message; ids also come from earlier tool results. Only with language "python".'
+                },
+                outputs: {
+                    type: 'array',
+                    description: 'Optional bare file names (strings) the code writes in the working directory; each is attached to the chat when the run succeeds. Only with language "python".'
+                },
+                workdir: {
+                    type: 'string',
+                    description: 'Optional working directory: a host path on the shell path, a bare directory name inside the in-memory Python filesystem with language "python".'
+                },
+                timeoutMs: {
+                    type: 'number',
+                    description: 'Optional timeout in milliseconds (default 120000, max 600000)'
+                },
+                maxOutputChars: {
+                    type: 'number',
+                    description: 'Optional stdout/stderr cap in characters (default 8192, max 65536). Raise when reading long content, e.g. a full note.'
+                },
+                script: {
+                    type: 'string',
+                    description: 'Run a python script bundled with a loaded skill instead of passing source: a scripts/*.py path exactly as the skill instructions name it (e.g. "scripts/extract_text.py"). Requires skill; leave command unset; pass arguments in scriptArgs and stage files via inputs/outputs as the instructions show.'
+                },
+                skill: {
+                    type: 'string',
+                    description: 'With script: the name of the skill that bundles the script (e.g. "pdf").'
+                },
+                scriptArgs: {
+                    type: 'array',
+                    description: 'With script: string arguments handed to the script as its command line, in order.'
+                }
+            },
+            required: []
+        },
+        autoApprove: false,
+        effect(args, ctx) {
+            if (typeof args.script === 'string' && args.script.trim() && !args.script.includes('\n')) {
+                return 'read';
+            }
+            if (runsThroughPyodide(args.language, disablePyodide))
+                return pythonCreateEffect(args);
+            return shellEffect(String(args.command ?? '').trim(), ctx?.toolOps);
+        },
+        validate(args, ctx) {
+            const scriptRun = resolveScriptRun(args, skillsDir);
+            if (scriptRun && 'error' in scriptRun)
+                return scriptRun.error;
+            const rawArgs = scriptRun ? scriptRun.args : args;
+            const command = String(rawArgs.command ?? '').trim();
+            if (!command)
+                return commandRequiredError(rawArgs);
+            const scopeError = checkExecutionScope(rawArgs, ctx?.toolOps, disablePyodide);
+            if (scopeError)
+                return scopeError;
+            const python = runsThroughPyodide(rawArgs.language, disablePyodide);
+            const workdirGiven = rawArgs.workdir !== undefined && rawArgs.workdir !== null;
+            if (workdirGiven && !python && (ctx?.fsRoots ?? []).length === 0) {
+                return WORKDIR_NO_ROOTS_ERROR;
+            }
+            if (python) {
+                const outputs = parseOutputs(rawArgs.outputs);
+                if (outputs && 'error' in outputs)
+                    return outputs.error;
+                const packages = parsePackages(rawArgs.packages);
+                if (packages && 'error' in packages)
+                    return packages.error;
+                if (!scriptRun || !scriptRun.trusted) {
+                    const sourceError = checkPythonSource(command);
+                    if (sourceError)
+                        return sourceError;
+                    const pptxError = checkPptxBuildSource(unwrapPythonSource(command) ?? command, outputs, packages);
+                    if (pptxError)
+                        return pptxError;
+                    const pdfError = checkPdfBuildSource(unwrapPythonSource(command) ?? command, outputs, packages);
+                    if (pdfError)
+                        return pdfError;
+                    const bareLength = checkBareLengthArgs(unwrapPythonSource(command) ?? command, packages);
+                    if (bareLength)
+                        return bareLength;
+                    const inputs = parseInputs(rawArgs.inputs);
+                    const unstagedRead = checkUnstagedRead(unwrapPythonSource(command) ?? command, Array.isArray(inputs) ? inputs : undefined);
+                    if (unstagedRead)
+                        return unstagedRead;
+                }
+            }
+            const parsed = parsePackages(rawArgs.packages);
+            if (parsed && 'error' in parsed)
+                return parsed.error;
+            if (parsed && !python) {
+                return 'packages require language "python" with Pyodide enabled';
+            }
+            return checkFileArgs(rawArgs, python);
+        },
+        resource(args) {
+            const script = typeof args.script === 'string' ? args.script : '';
+            if (script.trim() && !script.includes('\n')) {
+                return { kind: 'command', label: scriptLabel(args) };
+            }
+            const command = String(args.command ?? '').trim() || script.trim();
+            if (!command)
+                return null;
+            const workdir = typeof args.workdir === 'string' && args.workdir.trim() ? args.workdir.trim() : null;
+            const body = runsThroughPyodide(args.language, disablePyodide)
+                ? `python${packageSuffix(args)}${fileSuffix(args)}: ${(unwrapPythonSource(command) ?? command).slice(0, 120)}`
+                : command;
+            return {
+                kind: 'command',
+                label: workdir ? `${body}  (cwd: ${workdir})` : body
+            };
+        },
+        async execute(args, ctx) {
+            const scriptRun = resolveScriptRun(args, skillsDir);
+            if (scriptRun && 'error' in scriptRun)
+                return { error: scriptRun.error };
+            const rawArgs = scriptRun ? scriptRun.args : args;
+            const command = String(rawArgs.command ?? '').trim();
+            if (!command)
+                return { error: commandRequiredError(rawArgs) };
+            const scopeError = checkExecutionScope(rawArgs, ctx?.toolOps, disablePyodide);
+            if (scopeError)
+                return { error: scopeError };
+            const workdir = rawArgs.workdir === undefined || rawArgs.workdir === null
+                ? undefined
+                : String(rawArgs.workdir);
+            const onShellPath = !runsThroughPyodide(rawArgs.language, disablePyodide);
+            let cwd = workdir;
+            if (workdir !== undefined && onShellPath) {
+                const roots = ctx?.fsRoots ?? [];
+                if (roots.length === 0)
+                    return { error: WORKDIR_NO_ROOTS_ERROR };
+                const deny = await canonicalDenyRoots(deniedRoots, realpath);
+                const resolved = await resolveKey(workdir, roots, realpath, deny);
+                if ('error' in resolved)
+                    return { error: resolved.error };
+                if (resolved.root.kind !== 'local') {
+                    return { error: 'workdir must be a local directory, not a drive' };
+                }
+                if (!resolved.exists)
+                    return { error: `workdir does not exist: ${workdir}` };
+                cwd = hostPath(resolved.root, resolved.key);
+            }
+            let timeout = parsePositiveInt(rawArgs.timeoutMs, 'timeoutMs', 600_000);
+            if (timeout && typeof timeout === 'object')
+                return timeout;
+            if (ctx?.runBudget) {
+                const remaining = ctx.runBudget.deadlineMs - Date.now();
+                if (remaining <= 0) {
+                    return {
+                        error: 'run wall-clock budget exhausted; no time remains for this call',
+                        guidance: true
+                    };
+                }
+                if (timeout !== undefined)
+                    timeout = Math.min(timeout, remaining);
+            }
+            const maxOutputChars = parsePositiveInt(rawArgs.maxOutputChars, 'maxOutputChars', MAX_OUTPUT_CHARS_LIMIT);
+            if (maxOutputChars && typeof maxOutputChars === 'object')
+                return maxOutputChars;
+            if (!isPythonLanguage(rawArgs.language)) {
+                const obsidian = await routeObsidianCommand(command, ctx, {
+                    credentialStore,
+                    spawn,
+                    killProcess,
+                    loadRuntime: spawn ? undefined : bareRuntime,
+                    timeoutMs: timeout,
+                    maxOutputChars
+                });
+                if (obsidian)
+                    return obsidian;
+            }
+            const skillEnv = skillSettings ? await skillsEnv(skillSettings, ctx) : undefined;
+            try {
+                const execution = resolveExecution(adapters, fallback, rawArgs, {
+                    attach: ctx?.attach,
+                    fetchAttachment: ctx?.fetchAttachment,
+                    turnImages: ctx?.turnImages,
+                    runBudget: ctx?.runBudget
+                });
+                return await execution.run({
+                    cwd,
+                    timeoutMs: timeout,
+                    maxOutputChars,
+                    signal: ctx?.signal,
+                    ...(skillEnv ? { env: skillEnv } : {})
+                });
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                return {
+                    error: error instanceof AbortedError || error.name === 'AbortError'
+                        ? 'command aborted'
+                        : error.message
+                };
+            }
+        }
+    };
+}

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

@@ -0,0 +1,15 @@
+import type { ToolDefinition } from '../capabilities/completion.ts';
+import { type DriveRoot, type FsToolOptions, type Realpath } from './fs/scope.ts';
+export declare const DEFAULT_GLOB_MATCHES = 100;
+export declare const MAX_GLOB_MATCHES = 1000;
+export interface SearchTarget {
+    root: DriveRoot;
+    folder: string;
+}
+export declare function searchTargets(dir: unknown, roots: readonly DriveRoot[], realpath: Realpath, deny?: readonly string[]): Promise<{
+    targets: SearchTarget[];
+} | {
+    error: string;
+}>;
+export declare function relativeKey(key: string, folder: string): string;
+export declare function createFileGlobTool({ realpath, deniedRoots }?: FsToolOptions): ToolDefinition;

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

@@ -0,0 +1,112 @@
+import { compileGlob } from "./fs/glob.js";
+import { NO_DIRS_GRANTED, canonicalDenyRoots, defaultRealpath, isDeniedPath, resolveKey } from "./fs/scope.js";
+import { walkFiles } from "./fs/walk.js";
+export const DEFAULT_GLOB_MATCHES = 100;
+export const MAX_GLOB_MATCHES = 1000;
+export async function searchTargets(dir, roots, realpath, deny) {
+    if (typeof dir === 'string' && dir.trim()) {
+        const resolved = await resolveKey(dir, roots, realpath, deny);
+        if ('error' in resolved)
+            return resolved;
+        if (resolved.root.kind === 'local') {
+            if (!resolved.exists)
+                return { error: `no such file: ${dir}` };
+        }
+        else {
+            let hasEntry = false;
+            for await (const _entry of resolved.root.drive.list(resolved.key)) {
+                hasEntry = true;
+                break;
+            }
+            if (!hasEntry && (await resolved.root.drive.entry(resolved.key)) === null) {
+                return { error: `no such file: ${dir}` };
+            }
+        }
+        return { targets: [{ root: resolved.root, folder: resolved.key }] };
+    }
+    if (roots.length === 0)
+        return { error: NO_DIRS_GRANTED };
+    return { targets: roots.map((root) => ({ root, folder: '/' })) };
+}
+export function relativeKey(key, folder) {
+    return folder === '/' ? key.slice(1) : key.slice(folder.length + 1);
+}
+export function createFileGlobTool({ realpath = defaultRealpath, deniedRoots } = {}) {
+    return {
+        name: 'file_glob',
+        toolset: 'files',
+        description: 'List files matching a glob pattern inside the granted directories. ' +
+            'Use ** to cross directories (e.g. "**/*.ts"). Returns absolute paths. ' +
+            'Symlinks are never followed; skippedLinks counts the ones left out.',
+        parameters: {
+            type: 'object',
+            properties: {
+                pattern: { type: 'string', description: 'Glob pattern relative to the searched directory' },
+                dir: {
+                    type: 'string',
+                    description: 'Optional directory to search (default: every granted directory)'
+                },
+                limit: {
+                    type: 'number',
+                    description: `Optional match cap (default ${DEFAULT_GLOB_MATCHES}, max ${MAX_GLOB_MATCHES})`
+                }
+            },
+            required: ['pattern']
+        },
+        effect: () => 'read',
+        autoApprove: true,
+        rootsRequired: true,
+        validate(rawArgs) {
+            if (typeof rawArgs.pattern !== 'string' || !rawArgs.pattern.trim()) {
+                return 'pattern is required';
+            }
+            const limit = rawArgs.limit;
+            if (limit !== undefined && limit !== null) {
+                const n = Number(limit);
+                if (!Number.isInteger(n) || n <= 0 || n > MAX_GLOB_MATCHES) {
+                    return `limit must be a positive integer ≤ ${MAX_GLOB_MATCHES}`;
+                }
+            }
+            return null;
+        },
+        resource(args) {
+            const pattern = String(args.pattern ?? '').trim();
+            return pattern ? { kind: 'file', label: `glob ${pattern}` } : null;
+        },
+        async execute(rawArgs, ctx) {
+            const roots = ctx?.fsRoots ?? [];
+            const pattern = String(rawArgs.pattern ?? '').trim();
+            if (!pattern)
+                return { error: 'pattern is required' };
+            const limit = rawArgs.limit ? Number(rawArgs.limit) : DEFAULT_GLOB_MATCHES;
+            const deny = await canonicalDenyRoots(deniedRoots, realpath);
+            const scoped = await searchTargets(rawArgs.dir, roots, realpath, deny);
+            if ('error' in scoped)
+                return scoped;
+            const match = compileGlob(pattern);
+            const matches = [];
+            let truncated = false;
+            let skippedLinks = 0;
+            for (const target of scoped.targets) {
+                const walk = await walkFiles(target.root, target.folder);
+                truncated ||= walk.truncated;
+                skippedLinks += walk.skippedLinks;
+                for (const file of walk.files) {
+                    if (isDeniedPath(file.path, deny))
+                        continue;
+                    if (!match(relativeKey(file.key, target.folder)))
+                        continue;
+                    matches.push(file.path);
+                    if (matches.length >= limit) {
+                        return { matches, truncated: true, ...(skippedLinks ? { skippedLinks } : {}) };
+                    }
+                }
+            }
+            return {
+                matches,
+                ...(truncated ? { truncated } : {}),
+                ...(skippedLinks ? { skippedLinks } : {})
+            };
+        }
+    };
+}

package/dist-lib/lib/tools/fs/drive.d.ts

@@ -0,0 +1,26 @@
+import type { Writable } from 'streamx';
+export interface DriveEntry {
+    key: string;
+    value: {
+        executable: boolean;
+        linkname: string | null;
+        blob: {
+            byteLength: number;
+        } | null;
+        metadata: unknown;
+    };
+    mtime?: number;
+}
+export interface Drive {
+    entry(key: string, opts?: {
+        follow?: boolean;
+    }): Promise<DriveEntry | null>;
+    get(key: string): Promise<Uint8Array | null>;
+    list(folder?: string, opts?: {
+        skip?: ReadonlySet<string>;
+    }): AsyncIterable<DriveEntry>;
+    createReadStream(key: string): AsyncIterable<Uint8Array>;
+    createWriteStream(key: string, opts?: {
+        executable?: boolean;
+    }): Writable;
+}

package/dist-lib/lib/tools/fs/drive.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export declare function compileGlob(pattern: string): (relPath: string) => boolean;

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

@@ -0,0 +1,34 @@
+export function compileGlob(pattern) {
+    let source = '';
+    let i = 0;
+    while (i < pattern.length) {
+        const c = pattern[i];
+        if (c === '*') {
+            if (pattern[i + 1] === '*') {
+                if (pattern[i + 2] === '/') {
+                    source += '(?:.*/)?';
+                    i += 3;
+                }
+                else {
+                    source += '.*';
+                    i += 2;
+                }
+            }
+            else {
+                source += '[^/]*';
+                i += 1;
+            }
+        }
+        else if (c === '?') {
+            source += '[^/]';
+            i += 1;
+        }
+        else {
+            const ch = c;
+            source += /[.+^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
+            i += 1;
+        }
+    }
+    const regex = new RegExp(`^${source}$`);
+    return (relPath) => regex.test(relPath);
+}

package/dist-lib/lib/tools/fs/local.d.ts

@@ -0,0 +1,2 @@
+import { type LocalRoot, type Realpath } from './scope.ts';
+export declare function createLocalRoots(dirs: readonly string[], realpath?: Realpath): Promise<LocalRoot[]>;