ysagc-agent 0.3.0 → 0.5.0

package/dist/tools.js

@@ -0,0 +1,694 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolError = void 0;
+exports.preExecute = preExecute;
+exports.postExecute = postExecute;
+exports.createToolRegistry = createToolRegistry;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const path_utils_1 = require("./path-utils");
+const security_1 = require("./security");
+const skills_1 = require("./skills");
+const executor_1 = require("./executor");
+/** Thrown when a tool invocation is invalid or unsafe. */
+class ToolError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = 'ToolError';
+        this.code = code;
+    }
+}
+exports.ToolError = ToolError;
+const MAX_WRITE_BYTES = 10 * 1024 * 1024;
+// ---------------------------------------------------------------------------
+// argument coercion helpers
+// ---------------------------------------------------------------------------
+function requireString(args, key) {
+    const v = args[key];
+    if (typeof v !== 'string' || v.trim() === '') {
+        throw new ToolError('INVALID_ARG', `"${key}" is required and must be a non-empty string.`);
+    }
+    return v;
+}
+function optionalString(args, key, fallback) {
+    const v = args[key];
+    if (v === undefined || v === null)
+        return fallback;
+    if (typeof v !== 'string') {
+        throw new ToolError('INVALID_ARG', `"${key}" must be a string.`);
+    }
+    return v;
+}
+function optionalInt(args, key, fallback, opts = {}) {
+    const v = args[key];
+    if (v === undefined || v === null)
+        return fallback;
+    const n = typeof v === 'number' ? v : Number(v);
+    if (!Number.isFinite(n) || !Number.isInteger(n)) {
+        throw new ToolError('INVALID_ARG', `"${key}" must be an integer.`);
+    }
+    if (opts.min !== undefined && n < opts.min) {
+        throw new ToolError('INVALID_ARG', `"${key}" must be >= ${opts.min}.`);
+    }
+    if (opts.max !== undefined && n > opts.max) {
+        throw new ToolError('INVALID_ARG', `"${key}" must be <= ${opts.max}.`);
+    }
+    return n;
+}
+function requiredArray(args, key) {
+    const v = args[key];
+    if (!Array.isArray(v)) {
+        throw new ToolError('INVALID_ARG', `"${key}" must be an array.`);
+    }
+    return v;
+}
+function abortIfRequested(signal) {
+    if (signal?.aborted) {
+        throw new ToolError('ABORTED', 'Operation was cancelled.');
+    }
+}
+function assertNotRoot(realRoot, target) {
+    if (path.relative(realRoot, target) === '') {
+        throw new ToolError('ROOT_PATH', 'The authorisation root itself cannot be written as a file.');
+    }
+}
+function assertNotSensitive(target) {
+    if ((0, security_1.isSensitivePath)(target)) {
+        throw new ToolError('SENSITIVE_PATH', `Path is sensitive and cannot be accessed: ${target}`);
+    }
+}
+function isUtf8(buf) {
+    try {
+        new TextDecoder('utf-8', { fatal: true }).decode(buf);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readUpTo(target, length) {
+    const fd = fs.openSync(target, 'r');
+    try {
+        const buf = Buffer.alloc(length);
+        const bytesRead = fs.readSync(fd, buf, 0, length, 0);
+        return buf.subarray(0, Math.max(0, bytesRead));
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function rel(root, target) {
+    return path.relative(root, target).replace(/\\/g, '/');
+}
+function shellQuote(arg) {
+    if (arg === '')
+        return `''`;
+    // Commands are run through a shell on Windows; safer to reject metacharacters.
+    if (/[|&;<>`\n]/.test(arg)) {
+        throw new ToolError('UNSAFE_ARG', 'git argument contains shell metacharacters.');
+    }
+    if (/[\s]/.test(arg)) {
+        return `"${arg.replace(/"/g, '\\"')}"`;
+    }
+    return arg;
+}
+/** Tools that mutate the workspace or execute commands (blocked by read-only). */
+const WRITE_OR_COMMAND_TOOLS = new Set([
+    'write_file',
+    'edit_file',
+    'generate',
+    'run_command',
+    'git',
+]);
+/** Reconstruct the shell command a command-tool intends to run, if any. */
+function commandForTool(tool, args) {
+    if (tool === 'run_command') {
+        return typeof args.cmd === 'string' ? args.cmd : undefined;
+    }
+    if (tool === 'git') {
+        if (typeof args.command === 'string' && args.command.trim() !== '') {
+            return `git ${args.command.trim()}`;
+        }
+        if (Array.isArray(args.args)) {
+            return ['git', ...args.args.map((a) => String(a))].join(' ');
+        }
+    }
+    return undefined;
+}
+/** Collect the path-bearing argument values for a tool, if any. */
+function pathArgsForTool(tool, args) {
+    const keys = ['path', 'cwd'];
+    if (tool === 'generate')
+        keys.push('name');
+    const out = [];
+    for (const key of keys) {
+        const v = args[key];
+        if (typeof v === 'string' && v.trim() !== '')
+            out.push(v);
+    }
+    return out;
+}
+/** Default preset used when the caller did not specify one on the context. */
+const DEFAULT_PRESET = 'workspace-write';
+/** Whether the active preset permits a danger-flagged command without an
+ * approval prompt. Only the most-permissive mode allows non-critical danger
+ * commands; every other mode blocks them at the gate. */
+function permitsDangerCommand(preset, severity) {
+    return preset === 'danger-full-access' && severity !== 'critical';
+}
+/**
+ * The guarded pre-execution hook. Runs before every tool:
+ *  1. enforces the permission preset (read-only blocks writes/commands);
+ *  2. flags dangerous commands (workspace-write asks for approval, most
+ *     permissive mode only blocks critical commands, read-only blocks all);
+ *  3. canonicalises and validates every path argument (inside-root + sensitive
+ *     path check).
+ * Returns `{ ok: true }` when execution may proceed, otherwise a structured
+ * block with an error and optional `needsApproval`.
+ */
+function preExecute(ctx, tool, args) {
+    const preset = ctx.permissionPreset ?? DEFAULT_PRESET;
+    // 1) Permission preset: read-only denies anything that writes or executes.
+    if (preset === 'read-only') {
+        if (WRITE_OR_COMMAND_TOOLS.has(tool)) {
+            return {
+                ok: false,
+                error: `Tool "${tool}" is blocked in read-only mode (preset: read-only).`,
+                reason: 'read-only preset denies writes and commands',
+            };
+        }
+    }
+    // 2) Dangerous-command gate for shell tools.
+    const cmd = commandForTool(tool, args);
+    if (cmd !== undefined) {
+        const assessment = (0, security_1.isDangerCommand)(cmd);
+        if (assessment.danger) {
+            if (preset === 'danger-full-access' && assessment.severity === 'danger') {
+                // Most permissive: allow non-critical danger commands but record why.
+                // (critical severity falls through and is blocked below.)
+            }
+            else if (preset === 'workspace-write') {
+                return {
+                    ok: false,
+                    needsApproval: true,
+                    error: `Dangerous command requires approval (${assessment.severity}): ${assessment.reason}`,
+                    reason: assessment.reason,
+                };
+            }
+            else {
+                return {
+                    ok: false,
+                    error: `Blocked dangerous command (${assessment.severity}): ${assessment.reason}`,
+                    reason: assessment.reason,
+                };
+            }
+        }
+    }
+    // 3) Canonicalise + sensitive-path check for every path argument.
+    let realRoot;
+    for (const p of pathArgsForTool(tool, args)) {
+        try {
+            realRoot = realRoot ?? (0, path_utils_1.canonicalize)(ctx.root);
+            const target = (0, path_utils_1.safeResolve)(ctx.root, p, realRoot, { allowEqual: true });
+            if ((0, security_1.isSensitivePath)(target)) {
+                return {
+                    ok: false,
+                    error: `Sensitive path is blocked: ${p}`,
+                    reason: 'sensitive path',
+                };
+            }
+        }
+        catch (err) {
+            if (err instanceof path_utils_1.PathError) {
+                return { ok: false, error: err.message, reason: 'path validation failed' };
+            }
+            throw err;
+        }
+    }
+    return { ok: true };
+}
+/** Deep-mask secrets in a tool result so internal keys never leak out. */
+function maskSecretsDeep(value) {
+    if (typeof value === 'string')
+        return (0, security_1.maskSecrets)(value);
+    if (Array.isArray(value))
+        return value.map((v) => maskSecretsDeep(v));
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = maskSecretsDeep(v);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * The guarded post-execution hook. Runs after every tool: masks secrets in the
+ * result and records the reason the invocation ended up here.
+ */
+function postExecute(_ctx, tool, result) {
+    if (result.result !== undefined) {
+        result.result = maskSecretsDeep(result.result);
+    }
+    if (typeof result.error === 'string') {
+        result.error = (0, security_1.maskSecrets)(result.error);
+    }
+    return {
+        ok: true,
+        reason: `tool ${tool} completed; secrets masked`,
+    };
+}
+// ---------------------------------------------------------------------------
+// executors
+// ---------------------------------------------------------------------------
+const listDir = async (ctx, args) => {
+    const p = optionalString(args, 'path', '.') ?? '.';
+    const depth = optionalInt(args, 'depth', 1, { min: 0, max: 10 });
+    const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
+    const target = (0, path_utils_1.safeResolve)(ctx.root, p, realRoot, { allowEqual: true });
+    assertNotSensitive(target);
+    let stat;
+    try {
+        stat = fs.statSync(target);
+    }
+    catch {
+        throw new ToolError('NOT_FOUND', `Path does not exist: ${p}`);
+    }
+    if (!stat.isDirectory()) {
+        throw new ToolError('NOT_A_DIR', `Path is not a directory: ${p}`);
+    }
+    const entries = [];
+    const walkDepth = (dir, cur) => {
+        if (cur >= depth)
+            return;
+        let names;
+        try {
+            names = fs.readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            const full = path.join(dir, name);
+            let st;
+            try {
+                st = fs.lstatSync(full);
+            }
+            catch {
+                continue;
+            }
+            const type = st.isDirectory() ? 'dir' : st.isSymbolicLink() ? 'symlink' : 'file';
+            entries.push({
+                name,
+                path: rel(realRoot, full),
+                type,
+                ...(st.isFile() ? { size: st.size } : {}),
+                mtime: st.mtimeMs,
+            });
+            if (st.isDirectory() && cur + 1 < depth) {
+                walkDepth(full, cur + 1);
+            }
+        }
+    };
+    walkDepth(target, 0);
+    entries.sort((a, b) => String(a.name).localeCompare(String(b.name)));
+    return { ok: true, result: { path: rel(realRoot, target), depth, entries } };
+};
+const readFile = async (ctx, args, signal) => {
+    abortIfRequested(signal);
+    const targetStr = requireString(args, 'path');
+    const maxBytes = optionalInt(args, 'maxBytes', ctx.maxBytes, { min: 1, max: MAX_WRITE_BYTES });
+    const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
+    const target = (0, path_utils_1.safeResolve)(ctx.root, targetStr, realRoot);
+    assertNotSensitive(target);
+    let stat;
+    try {
+        stat = fs.statSync(target);
+    }
+    catch {
+        throw new ToolError('NOT_FOUND', `Path does not exist: ${targetStr}`);
+    }
+    if (stat.isDirectory()) {
+        throw new ToolError('IS_DIR', `Path is a directory, not a file: ${targetStr}`);
+    }
+    const totalBytes = stat.size;
+    const readLen = Math.min(maxBytes + 1, totalBytes);
+    const buf = readUpTo(target, readLen);
+    const truncated = totalBytes > maxBytes;
+    const bytesRead = buf.length;
+    const utf8 = isUtf8(buf);
+    const content = utf8 ? buf.toString('utf8') : buf.toString('hex');
+    return {
+        ok: true,
+        result: {
+            path: rel(realRoot, target),
+            bytesRead,
+            totalBytes,
+            truncated,
+            encoding: utf8 ? 'utf8' : 'hex',
+            content,
+        },
+    };
+};
+const writeFile = async (ctx, args, signal) => {
+    abortIfRequested(signal);
+    const targetStr = requireString(args, 'path');
+    const rawContent = args.content ?? args.contents;
+    const content = typeof rawContent === 'string' ? rawContent : '';
+    if (typeof rawContent !== 'string') {
+        throw new ToolError('INVALID_ARG', '"content" must be a string.');
+    }
+    const mode = optionalInt(args, 'mode', 0o644, { min: 0, max: 0o777 });
+    const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
+    const target = (0, path_utils_1.safeResolve)(ctx.root, targetStr, realRoot);
+    assertNotRoot(realRoot, target);
+    assertNotSensitive(target);
+    const totalBytes = Buffer.byteLength(content);
+    if (totalBytes > MAX_WRITE_BYTES) {
+        throw new ToolError('TOO_LARGE', `Content exceeds ${MAX_WRITE_BYTES} bytes.`);
+    }
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content, { mode });
+    return {
+        ok: true,
+        result: { path: rel(realRoot, target), bytesWritten: totalBytes, mode },
+    };
+};
+const editFile = async (ctx, args, signal) => {
+    abortIfRequested(signal);
+    const targetStr = requireString(args, 'path');
+    const oldText = requireString(args, 'oldText');
+    const newText = typeof args.newText === 'string' ? args.newText : '';
+    const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
+    const target = (0, path_utils_1.safeResolve)(ctx.root, targetStr, realRoot);
+    assertNotRoot(realRoot, target);
+    assertNotSensitive(target);
+    let stat;
+    try {
+        stat = fs.statSync(target);
+    }
+    catch {
+        throw new ToolError('NOT_FOUND', `Path does not exist: ${targetStr}`);
+    }
+    if (stat.isDirectory()) {
+        throw new ToolError('IS_DIR', `Path is a directory, not a file: ${targetStr}`);
+    }
+    const buf = fs.readFileSync(target);
+    if (!isUtf8(buf)) {
+        throw new ToolError('BINARY_FILE', 'edit_file only supports UTF-8 text files.');
+    }
+    const text = buf.toString('utf8');
+    const count = text.split(oldText).length - 1;
+    if (count === 0) {
+        throw new ToolError('NO_MATCH', 'oldText was not found in the file.');
+    }
+    fs.writeFileSync(target, text.split(oldText).join(newText), 'utf8');
+    return { ok: true, result: { path: rel(realRoot, target), replacements: count } };
+};
+const runCommandTool = async (ctx, args, signal) => {
+    const cmd = requireString(args, 'cmd');
+    const cwdArg = optionalString(args, 'cwd', '.') ?? '.';
+    const timeout = optionalInt(args, 'timeout', ctx.timeoutMs, { min: 1 });
+    const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
+    const cwd = (0, path_utils_1.safeResolve)(ctx.root, cwdArg, realRoot, { allowEqual: true });
+    const assessment = (0, security_1.isDangerCommand)(cmd);
+    if (assessment.danger && !permitsDangerCommand(ctx.permissionPreset, assessment.severity)) {
+        return {
+            ok: false,
+            error: `Blocked dangerous command (${assessment.severity}): ${assessment.reason}`,
+        };
+    }
+    if (ctx.mode === 'supervise') {
+        return { ok: false, error: 'run_command requires supervision; denied in supervise mode.' };
+    }
+    try {
+        const res = await (0, executor_1.runCommand)({
+            command: cmd,
+            cwd,
+            timeoutMs: timeout,
+            maxBytes: ctx.maxBytes,
+            signal,
+        });
+        return {
+            ok: true,
+            result: {
+                exitCode: res.exitCode,
+                stdout: (0, security_1.maskSecrets)(res.stdout),
+                stderr: (0, security_1.maskSecrets)(res.stderr),
+                durationMs: res.durationMs,
+                timedOut: res.timedOut,
+                truncated: res.truncated,
+                ...(res.stdoutFile ? { stdoutFile: res.stdoutFile } : {}),
+                ...(res.stderrFile ? { stderrFile: res.stderrFile } : {}),
+            },
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `run_command failed: ${msg}` };
+    }
+};
+const webSearch = async (ctx, args) => {
+    const query = optionalString(args, 'query', '') ?? '';
+    const base = {
+        stub: true,
+        provider: 'platform',
+        // The real search runs platform-side; the local agent never touches a
+        // search backend, so it cannot leak anything.
+        note: 'Placeholder: real web search is performed by the platform, not the local agent.',
+        query,
+        results: [],
+    };
+    if (!ctx.webEnabled) {
+        return {
+            ok: true,
+            result: { ...base, enabled: false, note: 'web_search is disabled on this agent.' },
+        };
+    }
+    return { ok: true, result: { ...base, enabled: true } };
+};
+const git = async (ctx, args, signal) => {
+    const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
+    const cwdArg = optionalString(args, 'cwd', '.') ?? '.';
+    const cwd = (0, path_utils_1.safeResolve)(ctx.root, cwdArg, realRoot, { allowEqual: true });
+    const timeout = optionalInt(args, 'timeout', ctx.timeoutMs, { min: 1 });
+    let cmdStr;
+    if (typeof args.command === 'string' && args.command.trim() !== '') {
+        cmdStr = `git ${args.command.trim()}`;
+    }
+    else if (Array.isArray(args.args)) {
+        const parts = requiredArray(args, 'args').map((a) => shellQuote(String(a)));
+        cmdStr = ['git', ...parts].join(' ');
+    }
+    else {
+        throw new ToolError('INVALID_ARG', '"git" requires either "args" (array) or "command" (string).');
+    }
+    const assessment = (0, security_1.isDangerCommand)(cmdStr);
+    if (assessment.danger && !permitsDangerCommand(ctx.permissionPreset, assessment.severity)) {
+        return { ok: false, error: `Blocked dangerous git command (${assessment.severity}): ${assessment.reason}` };
+    }
+    if (ctx.mode === 'supervise') {
+        return { ok: false, error: 'git requires supervision; denied in supervise mode.' };
+    }
+    try {
+        const res = await (0, executor_1.runCommand)({ command: cmdStr, cwd, timeoutMs: timeout, maxBytes: ctx.maxBytes, signal });
+        return {
+            ok: true,
+            result: {
+                exitCode: res.exitCode,
+                stdout: (0, security_1.maskSecrets)(res.stdout),
+                stderr: (0, security_1.maskSecrets)(res.stderr),
+                durationMs: res.durationMs,
+                timedOut: res.timedOut,
+                truncated: res.truncated,
+                ...(res.stdoutFile ? { stdoutFile: res.stdoutFile } : {}),
+                ...(res.stderrFile ? { stderrFile: res.stderrFile } : {}),
+            },
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `git failed: ${msg}` };
+    }
+};
+const TEMPLATES = {
+    node: [
+        { path: 'package.json', content: JSON.stringify({ name: 'project', version: '0.0.1', main: 'index.js', scripts: { start: 'node index.js' } }, null, 2) + '\n' },
+        { path: 'index.js', content: "console.log('hello from node');\n" },
+        { path: 'README.md', content: '# Node project\n\nA generated skeleton.\n' },
+    ],
+    react: [
+        { path: 'index.html', content: '<!doctype html>\n<html><body><div id="root"></div><script src="./src/main.tsx"></script></body></html>\n' },
+        { path: 'src/main.tsx', content: "import { createRoot } from 'react-dom/client';\ncreateRoot(document.getElementById('root')!).render(<h1>Hello React</h1>);\n" },
+        { path: 'package.json', content: JSON.stringify({ name: 'project', version: '0.0.1', scripts: { dev: 'vite', build: 'vite build' } }, null, 2) + '\n' },
+    ],
+    vue: [
+        { path: 'src/App.vue', content: '<template><h1>Hello Vue</h1></template>\n<script setup>\n</script>\n' },
+        { path: 'index.html', content: '<!doctype html>\n<html><body><div id="app"></div><script src="/src/main.ts"></script></body></html>\n' },
+        { path: 'package.json', content: JSON.stringify({ name: 'project', version: '0.0.1', scripts: { dev: 'vite', build: 'vite build' } }, null, 2) + '\n' },
+    ],
+    python: [
+        { path: 'main.py', content: "def main():\n    print('hello from python')\n\nif __name__ == '__main__':\n    main()\n" },
+        { path: 'requirements.txt', content: '# runtime dependencies\n' },
+        { path: 'README.md', content: '# Python project\n\nA generated skeleton.\n' },
+    ],
+    cli: [
+        { path: 'cli.js', content: "#!/usr/bin/env node\nconsole.log('cli');\n" },
+        { path: 'package.json', content: JSON.stringify({ name: 'project', version: '0.0.1', bin: { project: 'cli.js' } }, null, 2) + '\n' },
+    ],
+    readme: [
+        { path: 'README.md', content: '# {NAME}\n\nGenerated by ysagc-agent.\n' },
+    ],
+};
+const generate = async (ctx, args, signal) => {
+    abortIfRequested(signal);
+    const template = (optionalString(args, 'template', 'node') ?? 'node').toLowerCase();
+    const name = requireString(args, 'name');
+    if (!/^[A-Za-z0-9._-]+$/.test(name)) {
+        throw new ToolError('INVALID_NAME', 'name may only contain letters, digits, ".", "_" and "-".');
+    }
+    const files = TEMPLATES[template];
+    if (!files) {
+        throw new ToolError('BAD_TEMPLATE', `Unknown template "${template}". Available: ${Object.keys(TEMPLATES).join(', ')}.`);
+    }
+    const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
+    const targetDir = (0, path_utils_1.safeResolve)(ctx.root, name, realRoot);
+    assertNotSensitive(targetDir);
+    const written = [];
+    for (const tpl of files) {
+        const dest = (0, path_utils_1.safeResolve)(ctx.root, path.join(name, tpl.path), realRoot);
+        assertNotSensitive(dest);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        const content = tpl.content.replace(/\{NAME\}/g, name);
+        const bytes = Buffer.byteLength(content);
+        fs.writeFileSync(dest, content, 'utf8');
+        written.push({ path: rel(realRoot, dest), bytes });
+    }
+    return {
+        ok: true,
+        result: { template, name, root: rel(realRoot, targetDir), files: written },
+    };
+};
+// --- skills ----------------------------------------------------------------
+/** Load a skill (`.dsh/skills/<name>.md` under the workspace root). No-op when
+ * no skills directory or no matching skill exists. */
+const skillTool = async (ctx, args, signal) => {
+    abortIfRequested(signal);
+    const name = optionalString(args, 'name', '') ?? '';
+    if (name === '') {
+        const available = (0, skills_1.listSkills)(ctx.root);
+        const note = available.length === 0
+            ? 'No skills are configured.'
+            : `Name required; available skills: ${available.join(', ')}.`;
+        return { ok: true, result: { loaded: false, available, note } };
+    }
+    const record = (0, skills_1.loadSkillRecord)(ctx.root, name);
+    return { ok: true, result: record };
+};
+const TOOLS = {
+    list_dir: listDir,
+    read_file: readFile,
+    write_file: writeFile,
+    edit_file: editFile,
+    run_command: runCommandTool,
+    web_search: webSearch,
+    git,
+    generate,
+    skill: skillTool,
+};
+/** Build a tool registry bound to a single execution context. */
+function createToolRegistry(ctx) {
+    const names = Object.keys(TOOLS);
+    return {
+        ctx,
+        tools: names,
+        has(name) {
+            return Object.prototype.hasOwnProperty.call(TOOLS, name);
+        },
+        async dispatch(name, args, signal) {
+            const started = Date.now();
+            const executor = TOOLS[name];
+            if (!executor) {
+                return { ok: false, error: `Unknown tool: ${name}`, durationMs: 0 };
+            }
+            try {
+                // Guarded gate: pre-execution check (permission preset, danger
+                // commands, canonicalise + sensitive-path).
+                const pre = preExecute(ctx, name, args ?? {});
+                if (!pre.ok) {
+                    const durationMs = Date.now() - started;
+                    return {
+                        ok: false,
+                        error: pre.error,
+                        durationMs,
+                        ...(pre.needsApproval ? { needsApproval: true } : {}),
+                    };
+                }
+                // A cancel message may arrive while pre-checking; honour it.
+                abortIfRequested(signal);
+                const outcome = await executor(ctx, args ?? {}, signal);
+                const result = {
+                    ok: outcome.ok,
+                    result: outcome.result,
+                    error: outcome.error,
+                    durationMs: Date.now() - started,
+                    ...(outcome.needsApproval ? { needsApproval: true } : {}),
+                };
+                // Guarded gate: post-execution check (mask secrets + record reason).
+                const post = postExecute(ctx, name, result);
+                if (!post.ok) {
+                    const durationMs = Date.now() - started;
+                    return {
+                        ok: false,
+                        error: post.error ?? 'post-execution check failed',
+                        durationMs,
+                    };
+                }
+                return result;
+            }
+            catch (err) {
+                const durationMs = Date.now() - started;
+                if (err instanceof path_utils_1.PathError || err instanceof ToolError) {
+                    return { ok: false, error: err.message, durationMs };
+                }
+                const msg = err instanceof Error ? err.message : String(err);
+                ctx.logger.error('tool crashed', { tool: name, error: msg });
+                return { ok: false, error: `Internal error executing ${name}: ${msg}`, durationMs };
+            }
+        },
+    };
+}
+//# sourceMappingURL=tools.js.map