@aragon-agent/cli 0.4.3

package/dist/skills/usage.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Local skill-usage counters (spec §9) — the input that decides which skills
+ * survive Level 1 truncation.
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHAT IS STORED: skill name, use count, last-used timestamp. NOTHING ELSE.
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * No arguments, no conversation content, no working directory, no machine id.
+ * It never leaves this machine and it is never attached to any request. The
+ * whole file can be deleted at any time — the only consequence is that the
+ * catalog falls back to its pre-ranking order (I-A1). `skills.usageTracking:
+ * false` switches it off entirely, and then nothing here reads or writes disk.
+ *
+ * FAILURE POLICY (D-A14): every function swallows its errors. This is ranking
+ * metadata for a display list, not business data. A read-only home directory or
+ * a half-written JSON file must degrade to "no usage data" — surfacing an error
+ * would spend the user's attention on something whose worst outcome is a
+ * slightly worse sort order.
+ */
+import type { SkillUsageMap } from '@aragon-agent/core/skills';
+export declare const USAGE_FILENAME = "skill-usage.json";
+export declare const USAGE_SCHEMA = 1;
+/** Coalescing window for disk writes. Losing this much on exit costs nothing. */
+export declare const USAGE_FLUSH_DEBOUNCE_MS = 2000;
+/** Entries kept before pruning kicks in. */
+export declare const USAGE_MAX_ENTRIES = 500;
+/**
+ * `<data>/skill-usage.json` — deliberately a SIBLING of `<data>/skills/`, not a
+ * child. The skills directory is a scan root; every extra file inside it is one
+ * more thing the discovery walk has to recognise and skip.
+ */
+export declare function getUsagePath(): string;
+/** Read the usage map, caching it for the life of the process. */
+export declare function loadUsage(): SkillUsageMap;
+/**
+ * Drop entries for skills that no longer exist, then — if still over the cap —
+ * the least recently used ones. Called opportunistically, never on a hot path.
+ */
+export declare function pruneUsage(knownNames: string[]): void;
+/** Record one deliberate use of a skill. Cheap, in-memory, never throws. */
+export declare function recordUse(name: string, now?: number): void;
+/** Write the map to disk now, if anything changed. Safe to call repeatedly. */
+export declare function flushUsage(): void;
+export interface UsageRow {
+    name: string;
+    useCount: number;
+    lastUsedAt: number;
+}
+/**
+ * Every counter on disk, most recently used first (ties broken by name).
+ *
+ * Reads even when `skills.usageTracking` is off: switching tracking off stops
+ * new writes, but a user who wants to know what is already stored — and then
+ * delete it — must not be told "nothing here" while the file still exists.
+ */
+export declare function listUsage(): UsageRow[];
+/**
+ * Delete the file, empty the cache, cancel any pending write, and clear `dirty`.
+ * Returns how many entries were removed. Never throws (D-A14).
+ *
+ * CLEARING `dirty` IS NOT OPTIONAL. `recordUse()` sets it, and `flushUsage()`
+ * only returns early when `!dirty || memory === null`. Reset the map without
+ * resetting the flag and the very next flush — a scheduled one, or the explicit
+ * call at the end of a CLI command — rebuilds the file from an empty map. The
+ * user then sees `skill-usage.json` reappear seconds after deleting it, and only
+ * under certain call orders, which is the worst possible way to learn that
+ * "erase my data" did not.
+ */
+export declare function resetUsage(): number;
+/** Test-only: forget the cached map and any pending write. */
+export declare function resetUsageForTests(): void;

package/dist/skills/usage.js

@@ -0,0 +1,216 @@
+/**
+ * Local skill-usage counters (spec §9) — the input that decides which skills
+ * survive Level 1 truncation.
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHAT IS STORED: skill name, use count, last-used timestamp. NOTHING ELSE.
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * No arguments, no conversation content, no working directory, no machine id.
+ * It never leaves this machine and it is never attached to any request. The
+ * whole file can be deleted at any time — the only consequence is that the
+ * catalog falls back to its pre-ranking order (I-A1). `skills.usageTracking:
+ * false` switches it off entirely, and then nothing here reads or writes disk.
+ *
+ * FAILURE POLICY (D-A14): every function swallows its errors. This is ranking
+ * metadata for a display list, not business data. A read-only home directory or
+ * a half-written JSON file must degrade to "no usage data" — surfacing an error
+ * would spend the user's attention on something whose worst outcome is a
+ * slightly worse sort order.
+ */
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getUserDataDir } from './paths.js';
+export const USAGE_FILENAME = 'skill-usage.json';
+export const USAGE_SCHEMA = 1;
+/** Coalescing window for disk writes. Losing this much on exit costs nothing. */
+export const USAGE_FLUSH_DEBOUNCE_MS = 2000;
+/** Entries kept before pruning kicks in. */
+export const USAGE_MAX_ENTRIES = 500;
+/**
+ * `<data>/skill-usage.json` — deliberately a SIBLING of `<data>/skills/`, not a
+ * child. The skills directory is a scan root; every extra file inside it is one
+ * more thing the discovery walk has to recognise and skip.
+ */
+export function getUsagePath() {
+    return join(getUserDataDir(), USAGE_FILENAME);
+}
+// ---------------------------------------------------------------------------
+// In-memory state
+// ---------------------------------------------------------------------------
+let memory = null;
+let dirty = false;
+let timer = null;
+function isStat(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    return typeof v.useCount === 'number' && typeof v.lastUsedAt === 'number';
+}
+function readFromDisk() {
+    try {
+        const parsed = JSON.parse(readFileSync(getUsagePath(), 'utf-8'));
+        if (!parsed || typeof parsed !== 'object')
+            return {};
+        if (parsed.schema !== USAGE_SCHEMA)
+            return {};
+        if (!parsed.skills || typeof parsed.skills !== 'object')
+            return {};
+        const out = {};
+        for (const [name, stat] of Object.entries(parsed.skills)) {
+            // A hand-edited file is a normal thing to encounter; keep the rows that
+            // still make sense and drop the rest rather than discarding everything.
+            if (!isStat(stat))
+                continue;
+            out[name] = {
+                useCount: Math.max(0, Math.floor(stat.useCount)),
+                lastUsedAt: Math.max(0, Math.floor(stat.lastUsedAt)),
+            };
+        }
+        return out;
+    }
+    catch {
+        // Missing / unreadable / corrupt — all the same answer, and the file is
+        // left alone: the user may have been editing it, and deleting their work to
+        // tidy up our own state would be a strictly worse trade.
+        return {};
+    }
+}
+/** Read the usage map, caching it for the life of the process. */
+export function loadUsage() {
+    if (memory === null)
+        memory = readFromDisk();
+    return memory;
+}
+/**
+ * Drop entries for skills that no longer exist, then — if still over the cap —
+ * the least recently used ones. Called opportunistically, never on a hot path.
+ */
+export function pruneUsage(knownNames) {
+    const map = loadUsage();
+    const known = new Set(knownNames);
+    let changed = false;
+    for (const name of Object.keys(map)) {
+        if (!known.has(name)) {
+            delete map[name];
+            changed = true;
+        }
+    }
+    const names = Object.keys(map);
+    if (names.length > USAGE_MAX_ENTRIES) {
+        const oldestFirst = names.sort((a, b) => (map[a]?.lastUsedAt ?? 0) - (map[b]?.lastUsedAt ?? 0));
+        for (const name of oldestFirst.slice(0, names.length - USAGE_MAX_ENTRIES)) {
+            delete map[name];
+            changed = true;
+        }
+    }
+    if (changed) {
+        dirty = true;
+        scheduleFlush();
+    }
+}
+/** Record one deliberate use of a skill. Cheap, in-memory, never throws. */
+export function recordUse(name, now = Date.now()) {
+    if (name.length === 0)
+        return;
+    const map = loadUsage();
+    const current = map[name];
+    map[name] = {
+        useCount: (current?.useCount ?? 0) + 1,
+        lastUsedAt: now,
+    };
+    dirty = true;
+    scheduleFlush();
+}
+function scheduleFlush() {
+    if (timer !== null)
+        return;
+    timer = setTimeout(() => {
+        timer = null;
+        flushUsage();
+    }, USAGE_FLUSH_DEBOUNCE_MS);
+    // A pending counter write must never be the reason a one-shot `aragon skills
+    // list` sits there for two seconds before exiting.
+    timer.unref?.();
+}
+/** Write the map to disk now, if anything changed. Safe to call repeatedly. */
+export function flushUsage() {
+    if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+    }
+    if (!dirty || memory === null)
+        return;
+    const path = getUsagePath();
+    // Same tmp+rename discipline the config store uses: a process killed
+    // mid-write must not leave a truncated file that reads back as "no usage".
+    const tmp = `${path}.tmp-${process.pid}`;
+    try {
+        mkdirSync(getUserDataDir(), { recursive: true });
+        const payload = { schema: USAGE_SCHEMA, skills: memory };
+        writeFileSync(tmp, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
+        renameSync(tmp, path);
+        dirty = false;
+    }
+    catch {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            // Nothing further to try; the counters simply stay in memory.
+        }
+    }
+}
+/**
+ * Every counter on disk, most recently used first (ties broken by name).
+ *
+ * Reads even when `skills.usageTracking` is off: switching tracking off stops
+ * new writes, but a user who wants to know what is already stored — and then
+ * delete it — must not be told "nothing here" while the file still exists.
+ */
+export function listUsage() {
+    const map = loadUsage();
+    return Object.entries(map)
+        .map(([name, stat]) => ({ name, useCount: stat.useCount, lastUsedAt: stat.lastUsedAt }))
+        .sort((a, b) => b.lastUsedAt !== a.lastUsedAt
+        ? b.lastUsedAt - a.lastUsedAt
+        : a.name.localeCompare(b.name, 'en'));
+}
+/**
+ * Delete the file, empty the cache, cancel any pending write, and clear `dirty`.
+ * Returns how many entries were removed. Never throws (D-A14).
+ *
+ * CLEARING `dirty` IS NOT OPTIONAL. `recordUse()` sets it, and `flushUsage()`
+ * only returns early when `!dirty || memory === null`. Reset the map without
+ * resetting the flag and the very next flush — a scheduled one, or the explicit
+ * call at the end of a CLI command — rebuilds the file from an empty map. The
+ * user then sees `skill-usage.json` reappear seconds after deleting it, and only
+ * under certain call orders, which is the worst possible way to learn that
+ * "erase my data" did not.
+ */
+export function resetUsage() {
+    const removed = Object.keys(loadUsage()).length;
+    if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+    }
+    memory = {};
+    dirty = false;
+    try {
+        rmSync(getUsagePath(), { force: true });
+    }
+    catch {
+        // Same policy as everywhere else in this file: a counter file we could not
+        // delete is not worth an error the user can do nothing about.
+    }
+    return removed;
+}
+/** Test-only: forget the cached map and any pending write. */
+export function resetUsageForTests() {
+    if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+    }
+    memory = null;
+    dirty = false;
+}

package/dist/tools/bash-tool.d.ts

@@ -0,0 +1,12 @@
+/**
+ * bash tool — run a shell command at full permission (spec §3.6).
+ *
+ * Shell selection: Windows uses `process.env.ComSpec` (cmd.exe by default);
+ * POSIX uses `/bin/sh -c`. The command's stdout+stderr and exit code are
+ * captured. The `timeout?` param can only SHRINK within the executor ceiling
+ * (the core ToolExecutor owns the real timeout + 100 KB truncation — R4), so
+ * this tool does not re-implement an output cap.
+ */
+import { type AgentTool } from '@aragon-agent/core';
+import type { ToolDeps } from './fs-tools.js';
+export declare function makeBash(deps: ToolDeps): AgentTool;

package/dist/tools/bash-tool.js

@@ -0,0 +1,131 @@
+/**
+ * bash tool — run a shell command at full permission (spec §3.6).
+ *
+ * Shell selection: Windows uses `process.env.ComSpec` (cmd.exe by default);
+ * POSIX uses `/bin/sh -c`. The command's stdout+stderr and exit code are
+ * captured. The `timeout?` param can only SHRINK within the executor ceiling
+ * (the core ToolExecutor owns the real timeout + 100 KB truncation — R4), so
+ * this tool does not re-implement an output cap.
+ */
+import { spawn } from 'node:child_process';
+import process from 'node:process';
+import { defineTool, errorResult, textResult, } from '@aragon-agent/core';
+/**
+ * Kill the whole process tree. With `shell:true` the direct child is the shell
+ * wrapper, so on Windows we must `taskkill /t` to reach the grandchild; a plain
+ * `child.kill()` would orphan it (leaving pipes open and cwd locked).
+ */
+function killTree(child) {
+    if (child.pid === undefined)
+        return;
+    if (process.platform === 'win32') {
+        try {
+            spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { windowsHide: true });
+        }
+        catch {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    else {
+        try {
+            child.kill('SIGKILL');
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+export function makeBash(deps) {
+    return defineTool({
+        name: 'bash',
+        label: 'Shell',
+        description: 'Run a shell command at full permission and return its combined ' +
+            'stdout+stderr and exit code. `timeout` (ms) may only shrink within the ' +
+            'agent tool-timeout ceiling; `cwd` defaults to the working directory. ' +
+            'Emit shell syntax compatible with the OS/shell stated in the system prompt.',
+        parameters: {
+            type: 'object',
+            properties: {
+                command: { type: 'string', description: 'The shell command to run.' },
+                timeout: { type: 'number', description: 'Optional timeout in milliseconds (shrinks within the ceiling).' },
+                cwd: { type: 'string', description: 'Working directory for this command.' },
+            },
+            required: ['command'],
+        },
+        async execute(_id, rawParams, ctx) {
+            const params = rawParams;
+            const command = params.command;
+            const cwd = params.cwd ? params.cwd : deps.getCwd();
+            return new Promise((resolvePromise) => {
+                let child;
+                try {
+                    // shell:true delegates to ComSpec (Windows) / /bin/sh (POSIX) and
+                    // handles command-line quoting far more reliably than a hand-built
+                    // cmd.exe arg array, which double-escapes nested quotes on Windows.
+                    child = spawn(command, {
+                        shell: true,
+                        cwd,
+                        env: process.env,
+                        windowsHide: true,
+                    });
+                }
+                catch (err) {
+                    resolvePromise(errorResult(err instanceof Error ? err.message : String(err)));
+                    return;
+                }
+                let output = '';
+                let killedByTimeout = false;
+                let settled = false;
+                const finish = (fn) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    resolvePromise(fn());
+                };
+                // Self-timer for the `timeout` param (shrinks within the executor ceiling).
+                let timer;
+                if (params.timeout && params.timeout > 0) {
+                    timer = setTimeout(() => {
+                        killedByTimeout = true;
+                        killTree(child);
+                    }, params.timeout);
+                }
+                // Cooperative cancellation via the executor/agent AbortSignal.
+                const onAbort = () => {
+                    killTree(child);
+                };
+                ctx.signal?.addEventListener('abort', onAbort, { once: true });
+                function cleanup() {
+                    if (timer)
+                        clearTimeout(timer);
+                    ctx.signal?.removeEventListener('abort', onAbort);
+                }
+                child.stdout?.on('data', (d) => {
+                    output += d.toString();
+                });
+                child.stderr?.on('data', (d) => {
+                    output += d.toString();
+                });
+                child.on('error', (err) => {
+                    finish(() => errorResult(`Failed to run command: ${err.message}`));
+                });
+                child.on('close', (code, signalName) => {
+                    const trimmed = output.length > 0 ? output : '(no output)';
+                    if (killedByTimeout) {
+                        finish(() => errorResult(`Command timed out after ${params.timeout}ms.\n${trimmed}`));
+                        return;
+                    }
+                    const status = code === null ? `signal ${signalName}` : `exit code ${code}`;
+                    const body = `$ ${command}\n${trimmed}\n[${status}]`;
+                    finish(() => (code === 0 ? textResult(body) : errorResult(body)));
+                });
+            });
+        },
+    });
+}

package/dist/tools/diff.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Minimal unified-diff renderer for `edit_file` previews (spec §4).
+ *
+ * Not a full Myers diff: it trims the common leading/trailing lines and renders
+ * the differing middle as removed (`-`) / added (`+`) blocks with a small
+ * amount of surrounding context. That is enough for a legible edit preview
+ * without pulling in a diff dependency.
+ */
+export interface DiffOptions {
+    /** File path shown in the `---`/`+++` header. */
+    path?: string;
+    /** Context lines around the change (default 2). */
+    context?: number;
+}
+export declare function renderUnifiedDiff(oldStr: string, newStr: string, options?: DiffOptions): string;

package/dist/tools/diff.js

@@ -0,0 +1,50 @@
+/**
+ * Minimal unified-diff renderer for `edit_file` previews (spec §4).
+ *
+ * Not a full Myers diff: it trims the common leading/trailing lines and renders
+ * the differing middle as removed (`-`) / added (`+`) blocks with a small
+ * amount of surrounding context. That is enough for a legible edit preview
+ * without pulling in a diff dependency.
+ */
+const CONTEXT_LINES = 2;
+export function renderUnifiedDiff(oldStr, newStr, options = {}) {
+    const context = options.context ?? CONTEXT_LINES;
+    const oldLines = oldStr.split('\n');
+    const newLines = newStr.split('\n');
+    // Common leading lines.
+    let start = 0;
+    const maxStart = Math.min(oldLines.length, newLines.length);
+    while (start < maxStart && oldLines[start] === newLines[start])
+        start += 1;
+    // Common trailing lines (not overlapping the common prefix).
+    let endOld = oldLines.length - 1;
+    let endNew = newLines.length - 1;
+    while (endOld >= start &&
+        endNew >= start &&
+        oldLines[endOld] === newLines[endNew]) {
+        endOld -= 1;
+        endNew -= 1;
+    }
+    const header = options.path
+        ? [`--- ${options.path}`, `+++ ${options.path}`]
+        : [];
+    const lines = [];
+    const ctxStart = Math.max(0, start - context);
+    for (let i = ctxStart; i < start; i += 1) {
+        lines.push(`  ${oldLines[i]}`);
+    }
+    for (let i = start; i <= endOld; i += 1) {
+        lines.push(`- ${oldLines[i]}`);
+    }
+    for (let i = start; i <= endNew; i += 1) {
+        lines.push(`+ ${newLines[i]}`);
+    }
+    const ctxEnd = Math.min(oldLines.length - 1, endOld + context);
+    for (let i = endOld + 1; i <= ctxEnd; i += 1) {
+        lines.push(`  ${oldLines[i]}`);
+    }
+    if (lines.length === 0) {
+        return `${header.join('\n')}${header.length ? '\n' : ''}(no textual change)`;
+    }
+    return [...header, ...lines].join('\n');
+}

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

@@ -0,0 +1,16 @@
+/**
+ * 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 { type AgentTool } from '@aragon-agent/core';
+export interface ToolDeps {
+    getCwd: () => string;
+}
+export declare function makeReadFile(deps: ToolDeps): AgentTool;
+export declare function makeWriteFile(deps: ToolDeps): AgentTool;
+export declare function makeEditFile(deps: ToolDeps): AgentTool;
+export declare function makeListDir(deps: ToolDeps): AgentTool;