@aragon-agent/cli 0.4.3

package/dist/tools/fs-tools.js

@@ -0,0 +1,215 @@
+/**
+ * Filesystem tools: read_file / write_file / edit_file / list_dir (spec §3.6).
+ *
+ * All relative paths resolve against the session cwd (via the injected
+ * `getCwd`). Every tool returns `errorResult` on bad input — it never throws.
+ * Timeout + 100 KB truncation are owned by the core ToolExecutor (R4); these
+ * tools do not re-implement them.
+ */
+import { promises as fs } from 'node:fs';
+import { isAbsolute, join, resolve, dirname } from 'node:path';
+import { defineTool, errorResult, textResult, } from '@aragon-agent/core';
+import { renderUnifiedDiff } from './diff.js';
+function resolvePath(cwd, p) {
+    return isAbsolute(p) ? p : resolve(cwd, p);
+}
+/** Heuristic binary detection: a NUL byte in the first chunk. */
+function looksBinary(buf) {
+    const scan = buf.subarray(0, Math.min(buf.length, 8000));
+    return scan.includes(0);
+}
+// ---------------------------------------------------------------------------
+// read_file
+// ---------------------------------------------------------------------------
+export function makeReadFile(deps) {
+    return defineTool({
+        name: 'read_file',
+        label: 'Read File',
+        description: 'Read a UTF-8 text file and return its contents as numbered lines. ' +
+            'Optionally read a window with `offset` (1-based start line) and `limit` (line count).',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path (relative to the working directory or absolute).' },
+                offset: { type: 'number', description: '1-based line to start from.' },
+                limit: { type: 'number', description: 'Maximum number of lines to return.' },
+            },
+            required: ['path'],
+        },
+        async execute(_id, rawParams) {
+            const params = rawParams;
+            const target = resolvePath(deps.getCwd(), params.path);
+            try {
+                const buf = await fs.readFile(target);
+                if (looksBinary(buf)) {
+                    return errorResult(`File appears to be binary: ${params.path}`);
+                }
+                const content = buf.toString('utf-8');
+                const allLines = content.split('\n');
+                const offset = params.offset && params.offset > 0 ? params.offset : 1;
+                const start = offset - 1;
+                const end = params.limit && params.limit > 0 ? start + params.limit : allLines.length;
+                const slice = allLines.slice(start, end);
+                const numbered = slice
+                    .map((line, i) => `${String(start + i + 1).padStart(5)}  ${line}`)
+                    .join('\n');
+                return textResult(numbered.length > 0 ? numbered : '(empty file)');
+            }
+            catch (err) {
+                return errorResult(readError(err, params.path));
+            }
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// write_file
+// ---------------------------------------------------------------------------
+export function makeWriteFile(deps) {
+    return defineTool({
+        name: 'write_file',
+        label: 'Write File',
+        description: 'Create or overwrite a file with the given content, creating parent ' +
+            'directories as needed. Returns the number of bytes written.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path (relative or absolute).' },
+                content: { type: 'string', description: 'Full file content to write.' },
+            },
+            required: ['path', 'content'],
+        },
+        async execute(_id, rawParams) {
+            const params = rawParams;
+            const target = resolvePath(deps.getCwd(), params.path);
+            try {
+                await fs.mkdir(dirname(target), { recursive: true });
+                await fs.writeFile(target, params.content, 'utf-8');
+                const bytes = Buffer.byteLength(params.content, 'utf-8');
+                return textResult(`Wrote ${bytes} bytes to ${params.path}`);
+            }
+            catch (err) {
+                return errorResult(readError(err, params.path));
+            }
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// edit_file
+// ---------------------------------------------------------------------------
+export function makeEditFile(deps) {
+    return defineTool({
+        name: 'edit_file',
+        label: 'Edit File',
+        description: 'Replace an exact string in a file with a new string. Unless ' +
+            '`replace_all` is true, `old_string` must occur exactly once. Returns a ' +
+            'unified-diff preview of the change.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path (relative or absolute).' },
+                old_string: { type: 'string', description: 'Exact text to replace.' },
+                new_string: { type: 'string', description: 'Replacement text.' },
+                replace_all: {
+                    type: 'boolean',
+                    description: 'Replace every occurrence instead of requiring uniqueness.',
+                },
+            },
+            required: ['path', 'old_string', 'new_string'],
+        },
+        async execute(_id, rawParams) {
+            const params = rawParams;
+            const target = resolvePath(deps.getCwd(), params.path);
+            try {
+                const original = await fs.readFile(target, 'utf-8');
+                if (params.old_string === params.new_string) {
+                    return errorResult('old_string and new_string are identical - nothing to change.');
+                }
+                const occurrences = countOccurrences(original, params.old_string);
+                if (occurrences === 0) {
+                    return errorResult(`old_string not found in ${params.path}.`);
+                }
+                if (occurrences > 1 && !params.replace_all) {
+                    return errorResult(`old_string occurs ${occurrences} times in ${params.path}; pass replace_all:true or make it unique.`);
+                }
+                // Use a function replacer so `$`-patterns (`$&`, `$'`, `` $` ``, `$$`,
+                // `$n`) in new_string are inserted literally rather than interpreted by
+                // String.prototype.replace. The replace_all branch is already literal.
+                const updated = params.replace_all
+                    ? original.split(params.old_string).join(params.new_string)
+                    : original.replace(params.old_string, () => params.new_string);
+                await fs.writeFile(target, updated, 'utf-8');
+                const diff = renderUnifiedDiff(original, updated, { path: params.path });
+                return textResult(`Applied edit to ${params.path}:\n${diff}`);
+            }
+            catch (err) {
+                return errorResult(readError(err, params.path));
+            }
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// list_dir
+// ---------------------------------------------------------------------------
+export function makeListDir(deps) {
+    return defineTool({
+        name: 'list_dir',
+        label: 'List Directory',
+        description: 'List entries in a directory with type (dir/file) and size in bytes.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Directory path (default: working directory).' },
+            },
+        },
+        async execute(_id, rawParams) {
+            const params = rawParams;
+            const dir = resolvePath(deps.getCwd(), params.path ?? '.');
+            try {
+                const entries = await fs.readdir(dir, { withFileTypes: true });
+                if (entries.length === 0)
+                    return textResult('(empty directory)');
+                const rows = await Promise.all(entries
+                    .sort((a, b) => a.name.localeCompare(b.name))
+                    .map(async (e) => {
+                    if (e.isDirectory())
+                        return `dir   ${e.name}/`;
+                    try {
+                        const st = await fs.stat(join(dir, e.name));
+                        return `file  ${e.name}  (${st.size}b)`;
+                    }
+                    catch {
+                        return `file  ${e.name}`;
+                    }
+                }));
+                return textResult(rows.join('\n'));
+            }
+            catch (err) {
+                return errorResult(readError(err, params.path ?? '.'));
+            }
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function countOccurrences(haystack, needle) {
+    if (needle.length === 0)
+        return 0;
+    let count = 0;
+    let idx = haystack.indexOf(needle);
+    while (idx !== -1) {
+        count += 1;
+        idx = haystack.indexOf(needle, idx + needle.length);
+    }
+    return count;
+}
+function readError(err, path) {
+    const code = err.code;
+    if (code === 'ENOENT')
+        return `No such file or directory: ${path}`;
+    if (code === 'EISDIR')
+        return `Path is a directory: ${path}`;
+    if (code === 'EACCES')
+        return `Permission denied: ${path}`;
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Built-in toolset assembly (spec §3.6). The core engine ships no tools, so the
+ * CLI supplies the entire `tools: AgentTool[]` array: filesystem, search, and
+ * shell — all at full permission.
+ *
+ * An optional `confirmTools` mode wraps the mutating tools (write_file /
+ * edit_file / bash) in a Yes/No gate. It is off by default per the max-permission
+ * requirement; when enabled, a `confirm` callback (wired by the TUI) is awaited
+ * before the tool runs.
+ */
+import { type AgentTool, type ToolPolicyDecision, type ToolPolicyVerdict } from '@aragon-agent/core';
+export interface ConfirmRequest {
+    tool: string;
+    summary: string;
+}
+export interface BuiltinToolsOptions {
+    getCwd: () => string;
+    /** When true (and `confirm` is provided), mutating tools are gated. */
+    confirmTools?: boolean;
+    /** Awaited before a mutating tool runs; resolve `false` to cancel. */
+    confirm?: (req: ConfirmRequest) => Promise<boolean>;
+    /**
+     * `skill` / `skill_install` / `skill_create`, appended verbatim.
+     *
+     * Deliberately NOT added to `MUTATING_TOOLS`: the installer runs its own
+     * `ApprovalGate` (§8.3.1), which is strictly stronger than the `--confirm`
+     * wrapper. Adding them here too would ask the user twice for one action and,
+     * worse, the outer wrapper would auto-approve where the inner gate refuses.
+     *
+     * An empty array (the `--no-skills` path) leaves the tool list byte-identical
+     * to the pre-Skills seven — invariant I-S1 / AC-10.
+     */
+    skillTools?: AgentTool[];
+    /**
+     * Read the ceiling AT CALL TIME. Never cache the returned decision: the frame
+     * changes mid-turn (a `skill` call adds to it, a rescan can empty it), and a
+     * cached decision would ignore the skill the model just loaded.
+     *
+     * Omitting this leaves every tool unwrapped — see the early return below.
+     */
+    toolPolicy?: () => ToolPolicyDecision;
+    /**
+     * Report a refusal or a warn-mode pass so the user hears about it (D-G10).
+     *
+     * The field is `sourceNames`, NOT `sources`. `ToolPolicyDecision.sources` is a
+     * list of structured `ToolPolicySource` objects; two same-named fields of
+     * different shape in one flow is the easiest possible thing to mix up, so the
+     * event carries the plain names under a different name.
+     */
+    onToolPolicyEvent?: (e: {
+        tool: string;
+        verdict: ToolPolicyVerdict;
+        sourceNames: string[];
+    }) => void;
+}
+/**
+ * Tools the ceiling always permits (D-G6). The ONLY place that knows which of
+ * this host's tools are read-only — core must not (D-G7).
+ *
+ * Two groups, two different arguments. The read-only tools cannot change the
+ * world, so an author who simply forgot to declare `read_file` gets an annoyance
+ * rather than an incident. `skill` / `skill_find` have to stay reachable or the
+ * Level 1 escape hatch would be visible to the model and uncallable inside a
+ * frame — reintroducing the exact dead end iteration 2 spent a round removing.
+ *
+ * What is left under actual control is therefore `write_file` / `edit_file` /
+ * `bash` / `skill_install` / `skill_create`: the five that change something. That
+ * is the whole of what this mechanism is worth, and saying so plainly beats
+ * implying it covers more.
+ */
+export declare const SKILL_TOOL_FLOOR: readonly ["read_file", "list_dir", "glob", "grep", "skill", "skill_find"];
+/**
+ * Every tool name this host CAN register (7 built-ins + 4 skill tools).
+ *
+ * Exists because `aragon skills doctor` runs in a one-shot process with no
+ * `AgentController` and therefore no live tool array, yet it is the primary
+ * mitigation for "your declaration will never be enforceable" (RG1 / RG3 / RG5).
+ * Without this it would have to report every skill as NOT ENFORCEABLE or check
+ * nothing at all.
+ *
+ * Deliberately the SUPERSET rather than "what is registered right now": doctor
+ * answers "can this declaration ever take effect?", not "is it in effect at this
+ * instant". So `--no-skills` must still resolve `skill_create`. The runtime
+ * ceiling keeps using the live `toolNames()` (§5.4c); these two lists are not
+ * interchangeable, and a test asserts they agree.
+ *
+ * `/skills info` and the `/skills` ceiling summary use it for the same reason,
+ * even though a TUI session does have a live tool array: both describe what a
+ * declaration MEANS, and that reading must not change with how the CLI was
+ * started.
+ */
+export declare const HOST_TOOL_NAMES: readonly ["read_file", "write_file", "edit_file", "list_dir", "glob", "grep", "bash", "skill", "skill_find", "skill_install", "skill_create"];
+export declare function createBuiltinTools(options: BuiltinToolsOptions): AgentTool[];

package/dist/tools/index.js

@@ -0,0 +1,157 @@
+/**
+ * Built-in toolset assembly (spec §3.6). The core engine ships no tools, so the
+ * CLI supplies the entire `tools: AgentTool[]` array: filesystem, search, and
+ * shell — all at full permission.
+ *
+ * An optional `confirmTools` mode wraps the mutating tools (write_file /
+ * edit_file / bash) in a Yes/No gate. It is off by default per the max-permission
+ * requirement; when enabled, a `confirm` callback (wired by the TUI) is awaited
+ * before the tool runs.
+ */
+import { errorResult, evaluateToolCall, } from '@aragon-agent/core';
+import { makeReadFile, makeWriteFile, makeEditFile, makeListDir } from './fs-tools.js';
+import { makeGlob, makeGrep } from './search-tools.js';
+import { makeBash } from './bash-tool.js';
+const MUTATING_TOOLS = new Set(['write_file', 'edit_file', 'bash']);
+/**
+ * Tools the ceiling always permits (D-G6). The ONLY place that knows which of
+ * this host's tools are read-only — core must not (D-G7).
+ *
+ * Two groups, two different arguments. The read-only tools cannot change the
+ * world, so an author who simply forgot to declare `read_file` gets an annoyance
+ * rather than an incident. `skill` / `skill_find` have to stay reachable or the
+ * Level 1 escape hatch would be visible to the model and uncallable inside a
+ * frame — reintroducing the exact dead end iteration 2 spent a round removing.
+ *
+ * What is left under actual control is therefore `write_file` / `edit_file` /
+ * `bash` / `skill_install` / `skill_create`: the five that change something. That
+ * is the whole of what this mechanism is worth, and saying so plainly beats
+ * implying it covers more.
+ */
+export const SKILL_TOOL_FLOOR = [
+    'read_file',
+    'list_dir',
+    'glob',
+    'grep',
+    'skill',
+    'skill_find',
+];
+/**
+ * Every tool name this host CAN register (7 built-ins + 4 skill tools).
+ *
+ * Exists because `aragon skills doctor` runs in a one-shot process with no
+ * `AgentController` and therefore no live tool array, yet it is the primary
+ * mitigation for "your declaration will never be enforceable" (RG1 / RG3 / RG5).
+ * Without this it would have to report every skill as NOT ENFORCEABLE or check
+ * nothing at all.
+ *
+ * Deliberately the SUPERSET rather than "what is registered right now": doctor
+ * answers "can this declaration ever take effect?", not "is it in effect at this
+ * instant". So `--no-skills` must still resolve `skill_create`. The runtime
+ * ceiling keeps using the live `toolNames()` (§5.4c); these two lists are not
+ * interchangeable, and a test asserts they agree.
+ *
+ * `/skills info` and the `/skills` ceiling summary use it for the same reason,
+ * even though a TUI session does have a live tool array: both describe what a
+ * declaration MEANS, and that reading must not change with how the CLI was
+ * started.
+ */
+export const HOST_TOOL_NAMES = [
+    'read_file',
+    'write_file',
+    'edit_file',
+    'list_dir',
+    'glob',
+    'grep',
+    'bash',
+    'skill',
+    'skill_find',
+    'skill_install',
+    'skill_create',
+];
+function summarize(toolName, params) {
+    if (toolName === 'bash')
+        return `Run: ${String(params.command ?? '')}`;
+    if (toolName === 'write_file')
+        return `Write: ${String(params.path ?? '')}`;
+    if (toolName === 'edit_file')
+        return `Edit: ${String(params.path ?? '')}`;
+    return toolName;
+}
+/** Wrap a tool so its execution is gated behind a confirmation callback. */
+function withConfirmation(tool, confirm) {
+    const original = tool.execute;
+    return {
+        ...tool,
+        async execute(id, params, ctx) {
+            const approved = await confirm({
+                tool: tool.name,
+                summary: summarize(tool.name, params),
+            });
+            if (!approved)
+                return errorResult('Cancelled by user.');
+            return original(id, params, ctx);
+        },
+    };
+}
+/**
+ * Wrap a tool in the turn-scoped ceiling (§5.4b). Same shape as
+ * `withConfirmation` — `{...tool, execute}` — so nothing in the engine needs to
+ * know this happened.
+ *
+ * NO DEDUPLICATION HERE. Announce-once bookkeeping belongs to `SkillRegistry`,
+ * the only object that knows when a turn starts; a `Set` closed over in this
+ * function would be session-scoped and would mute `warn` mode after one message.
+ */
+function withToolPolicy(tool, getDecision, notify) {
+    const original = tool.execute;
+    return {
+        ...tool,
+        async execute(id, params, ctx) {
+            const decision = getDecision();
+            const verdict = evaluateToolCall(tool.name, decision);
+            if (verdict.notice) {
+                // Runs BEFORE the refusal is returned, which is what lets the service
+                // append its escalation line to `verdict.message` in place.
+                notify?.({ tool: tool.name, verdict, sourceNames: decision.sourceNames });
+            }
+            if (!verdict.allow)
+                return errorResult(verdict.message ?? `Tool "${tool.name}" is not permitted.`);
+            return original(id, params, ctx);
+        },
+    };
+}
+export function createBuiltinTools(options) {
+    const deps = { getCwd: options.getCwd };
+    let tools = [
+        makeReadFile(deps),
+        makeWriteFile(deps),
+        makeEditFile(deps),
+        makeListDir(deps),
+        makeGlob(deps),
+        makeGrep(deps),
+        makeBash(deps),
+    ];
+    if (options.confirmTools && options.confirm) {
+        const confirm = options.confirm;
+        tools = tools.map((t) => (MUTATING_TOOLS.has(t.name) ? withConfirmation(t, confirm) : t));
+    }
+    if (options.skillTools && options.skillTools.length > 0) {
+        tools = [...tools, ...options.skillTools];
+    }
+    // No decision provider (`--no-skills`, or a caller that never enabled the
+    // policy) means the tools go out exactly as they came in.
+    //
+    // A ceiling that always says "allow" would behave identically, so this early
+    // return buys nothing at run time — it buys the ability to PROVE the claim.
+    // AC-G17 asserts object identity on this path; with a wrapper in place, "the
+    // `--no-skills` path is unchanged from iteration 2" would demote from a fact
+    // anyone can check to an argument someone has to trust.
+    if (!options.toolPolicy)
+        return tools;
+    // Outermost on purpose (D-G11). Asking a human "run bash?", waiting for them
+    // to say yes, and only then reporting that policy refused it is the worst
+    // available ordering. The ceiling needs no I/O, so it goes first.
+    const getDecision = options.toolPolicy;
+    return tools.map((t) => withToolPolicy(t, getDecision, options.onToolPolicyEvent));
+}

package/dist/tools/search-tools.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Search tools: glob / grep (spec §3.6).
+ *
+ * `glob` uses tinyglobby and sorts matches by mtime (newest first). `grep`
+ * prefers ripgrep when it is on PATH and falls back to a pure-JS scan otherwise;
+ * both produce `path:line:text` output.
+ */
+import { type AgentTool } from '@aragon-agent/core';
+import type { ToolDeps } from './fs-tools.js';
+export declare function makeGlob(deps: ToolDeps): AgentTool;
+export declare function makeGrep(deps: ToolDeps): AgentTool;