@aragon-agent/cli 0.4.3

package/dist/input/keymap.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Editing keymap (spec §3.10). Pure: maps a raw `useInput` `(input, key)` pair
+ * to a line-editing intent. Ink does not surface Home/End/word keys on its
+ * `key` object — those arrive as raw escape sequences in `input` — so this
+ * recognizer inspects both the parsed `key` flags (for Ctrl/Alt combos) and the
+ * raw sequence (for Home/End/word jumps), and returns `null` for anything it
+ * does not own so the caller can drop unknown control bytes instead of
+ * inserting them into the buffer.
+ */
+export type EditIntent = 'home' | 'end' | 'wordLeft' | 'wordRight' | 'deleteWordBack' | 'killToStart' | 'killToEnd';
+/** Minimal shape of Ink's `Key` we consult (structurally compatible). */
+export interface KeyState {
+    ctrl?: boolean;
+    meta?: boolean;
+    shift?: boolean;
+    leftArrow?: boolean;
+    rightArrow?: boolean;
+}
+/** Recognize a line-editing intent, or `null` if this key is not an edit op. */
+export declare function recognize(input: string, key: KeyState): EditIntent | null;

package/dist/input/keymap.js

@@ -0,0 +1,85 @@
+/**
+ * Editing keymap (spec §3.10). Pure: maps a raw `useInput` `(input, key)` pair
+ * to a line-editing intent. Ink does not surface Home/End/word keys on its
+ * `key` object — those arrive as raw escape sequences in `input` — so this
+ * recognizer inspects both the parsed `key` flags (for Ctrl/Alt combos) and the
+ * raw sequence (for Home/End/word jumps), and returns `null` for anything it
+ * does not own so the caller can drop unknown control bytes instead of
+ * inserting them into the buffer.
+ */
+/** Map a Ctrl-modified key to an intent, if any. */
+function fromCtrl(input, key) {
+    if (key.leftArrow)
+        return 'wordLeft';
+    if (key.rightArrow)
+        return 'wordRight';
+    switch (input) {
+        case 'a':
+            return 'home';
+        case 'e':
+            return 'end';
+        case 'w':
+            return 'deleteWordBack';
+        case 'u':
+            return 'killToStart';
+        case 'k':
+            return 'killToEnd';
+        default:
+            return null;
+    }
+}
+/** Map an Alt/Meta-modified key to an intent, if any. */
+function fromMeta(input) {
+    if (input === 'b')
+        return 'wordLeft';
+    if (input === 'f')
+        return 'wordRight';
+    if (input === '\x7f' || input === '\b')
+        return 'deleteWordBack';
+    return null;
+}
+/** Map a raw terminal escape / control sequence to an intent, if any. */
+function fromRaw(input) {
+    switch (input) {
+        case '\x1b[H':
+        case '\x1b[1~':
+        case '\x1bOH':
+        case '\x01': // Ctrl+A (raw)
+            return 'home';
+        case '\x1b[F':
+        case '\x1b[4~':
+        case '\x1bOF':
+        case '\x05': // Ctrl+E (raw)
+            return 'end';
+        case '\x1b[1;5D':
+        case '\x1bb':
+            return 'wordLeft';
+        case '\x1b[1;5C':
+        case '\x1bf':
+            return 'wordRight';
+        case '\x17': // Ctrl+W (raw)
+        case '\x1b\x7f':
+        case '\x1b\b':
+            return 'deleteWordBack';
+        case '\x15': // Ctrl+U (raw)
+            return 'killToStart';
+        case '\x0b': // Ctrl+K (raw)
+            return 'killToEnd';
+        default:
+            return null;
+    }
+}
+/** Recognize a line-editing intent, or `null` if this key is not an edit op. */
+export function recognize(input, key) {
+    if (key.ctrl) {
+        const hit = fromCtrl(input, key);
+        if (hit)
+            return hit;
+    }
+    if (key.meta) {
+        const hit = fromMeta(input);
+        if (hit)
+            return hit;
+    }
+    return fromRaw(input);
+}

package/dist/session/persist.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Session save/resume (spec §6.3). Persists BOTH the engine `messages` and the
+ * visual `entries`: on abort the loop breaks before pushing the in-flight
+ * assistant message, so `messages` and `entries` legitimately diverge (R9).
+ * `messages` is what the engine resends on resume; `entries` is the faithful
+ * visual replay.
+ */
+import type { Message, ModelRef } from '@aragon-agent/core';
+import type { Entry } from '../agent/reducer.js';
+export interface SavedSession {
+    version: number;
+    savedAt: number;
+    model: ModelRef;
+    messages: Message[];
+    entries: Entry[];
+}
+/** Resolve a `/save` target: absolute/relative path, or a name in the data dir. */
+export declare function resolveSessionPath(nameOrPath: string | undefined, cwd: string): string;
+export declare function saveSession(filePath: string, data: {
+    model: ModelRef;
+    messages: Message[];
+    entries: Entry[];
+}): void;
+export declare function loadSession(filePath: string): SavedSession;

package/dist/session/persist.js

@@ -0,0 +1,51 @@
+/**
+ * Session save/resume (spec §6.3). Persists BOTH the engine `messages` and the
+ * visual `entries`: on abort the loop breaks before pushing the in-flight
+ * assistant message, so `messages` and `entries` legitimately diverge (R9).
+ * `messages` is what the engine resends on resume; `entries` is the faithful
+ * visual replay.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { getSessionsDir } from '../config/store.js';
+const SESSION_VERSION = 1;
+/** Resolve a `/save` target: absolute/relative path, or a name in the data dir. */
+export function resolveSessionPath(nameOrPath, cwd) {
+    if (!nameOrPath || nameOrPath.trim().length === 0) {
+        return join(getSessionsDir(), `session-${defaultStamp()}.json`);
+    }
+    const value = nameOrPath.trim();
+    if (isAbsolute(value))
+        return ensureJsonExt(value);
+    if (value.includes('/') || value.includes('\\'))
+        return ensureJsonExt(resolve(cwd, value));
+    return join(getSessionsDir(), ensureJsonExt(value));
+}
+function ensureJsonExt(p) {
+    return p.endsWith('.json') ? p : `${p}.json`;
+}
+function defaultStamp() {
+    // Filesystem-safe timestamp without punctuation that breaks on Windows.
+    return new Date().toISOString().replace(/[:.]/g, '-');
+}
+export function saveSession(filePath, data) {
+    const dir = dirname(filePath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const payload = {
+        version: SESSION_VERSION,
+        savedAt: Date.now(),
+        model: data.model,
+        messages: data.messages,
+        entries: data.entries,
+    };
+    writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
+}
+export function loadSession(filePath) {
+    const raw = readFileSync(filePath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || !Array.isArray(parsed.messages) || !Array.isArray(parsed.entries)) {
+        throw new Error('Invalid session file (missing messages/entries).');
+    }
+    return parsed;
+}

package/dist/skills/archive.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Zip extraction with runtime gates (spec §9.2.1 / P1-4).
+ *
+ * WHY STREAMING AND NOT `fflate.unzipSync()`:
+ *
+ *   `unzipSync` inflates the whole archive into memory in one call. There is
+ *   literally no "before extraction" moment at which a size check could run,
+ *   and no way to abort partway. A 5 MB upload at a 1000:1 ratio is 5 GB in the
+ *   process before anything gets a vote.
+ *
+ *   The earlier design proposed summing the entries' DECLARED uncompressed
+ *   sizes first. That is not a check: the zip central directory is written by
+ *   whoever built the archive, so an attacker declares 1 KB and ships 50 MB.
+ *   The only judge that cannot be lied to is the count of bytes we have
+ *   actually written, which is why all three gates below sit on the write path
+ *   and every one of them can abort mid-entry.
+ */
+/** Cap on the COMPRESSED download. The 20 MB below is the inflated total. */
+export declare const ARCHIVE_MAX_DOWNLOAD_BYTES: number;
+/** Cap on bytes actually written to disk across the whole archive. */
+export declare const ARCHIVE_MAX_TOTAL_BYTES: number;
+/** Cap on bytes actually written for one entry. */
+export declare const ARCHIVE_MAX_ENTRY_BYTES: number;
+/** Inflated:compressed ratio ceiling, applied only to non-trivial entries. */
+export declare const ARCHIVE_MAX_RATIO = 200;
+/** Entries below this compressed size skip the ratio gate (a 20-byte file
+ *  legitimately expands enormously and would false-positive). */
+export declare const ARCHIVE_RATIO_MIN_COMPRESSED = 1024;
+export declare const ARCHIVE_MAX_ENTRIES = 200;
+export declare class ArchiveError extends Error {
+}
+/**
+ * Extract a zip into `targetDir`, enforcing the four gates.
+ *
+ * On ANY violation the target directory is removed entirely — a partially
+ * extracted bomb left on disk would be indistinguishable from a successful
+ * install to the next `discover()` pass.
+ */
+export declare function extractZip(buffer: Buffer, targetDir: string): Promise<string[]>;
+/** Convenience for tests and callers that want the relative view. */
+export declare function relativePaths(root: string, files: string[]): string[];

package/dist/skills/archive.js

@@ -0,0 +1,152 @@
+/**
+ * Zip extraction with runtime gates (spec §9.2.1 / P1-4).
+ *
+ * WHY STREAMING AND NOT `fflate.unzipSync()`:
+ *
+ *   `unzipSync` inflates the whole archive into memory in one call. There is
+ *   literally no "before extraction" moment at which a size check could run,
+ *   and no way to abort partway. A 5 MB upload at a 1000:1 ratio is 5 GB in the
+ *   process before anything gets a vote.
+ *
+ *   The earlier design proposed summing the entries' DECLARED uncompressed
+ *   sizes first. That is not a check: the zip central directory is written by
+ *   whoever built the archive, so an attacker declares 1 KB and ships 50 MB.
+ *   The only judge that cannot be lied to is the count of bytes we have
+ *   actually written, which is why all three gates below sit on the write path
+ *   and every one of them can abort mid-entry.
+ */
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { Unzip, UnzipInflate } from 'fflate';
+import { checkStagedPath } from '@aragon-agent/core/skills';
+/** Cap on the COMPRESSED download. The 20 MB below is the inflated total. */
+export const ARCHIVE_MAX_DOWNLOAD_BYTES = 5 * 1024 * 1024;
+/** Cap on bytes actually written to disk across the whole archive. */
+export const ARCHIVE_MAX_TOTAL_BYTES = 20 * 1024 * 1024;
+/** Cap on bytes actually written for one entry. */
+export const ARCHIVE_MAX_ENTRY_BYTES = 5 * 1024 * 1024;
+/** Inflated:compressed ratio ceiling, applied only to non-trivial entries. */
+export const ARCHIVE_MAX_RATIO = 200;
+/** Entries below this compressed size skip the ratio gate (a 20-byte file
+ *  legitimately expands enormously and would false-positive). */
+export const ARCHIVE_RATIO_MIN_COMPRESSED = 1024;
+export const ARCHIVE_MAX_ENTRIES = 200;
+export class ArchiveError extends Error {
+}
+/**
+ * Extract a zip into `targetDir`, enforcing the four gates.
+ *
+ * On ANY violation the target directory is removed entirely — a partially
+ * extracted bomb left on disk would be indistinguishable from a successful
+ * install to the next `discover()` pass.
+ */
+export async function extractZip(buffer, targetDir) {
+    mkdirSync(targetDir, { recursive: true });
+    const written = [];
+    let totalInflated = 0;
+    let entryCount = 0;
+    let failure = null;
+    const fail = (message) => {
+        if (!failure)
+            failure = new ArchiveError(message);
+    };
+    await new Promise((resolvePromise, rejectPromise) => {
+        const unzip = new Unzip((file) => {
+            if (failure)
+                return;
+            entryCount += 1;
+            if (entryCount > ARCHIVE_MAX_ENTRIES) {
+                fail(`archive has more than ${ARCHIVE_MAX_ENTRIES} entries`);
+                return;
+            }
+            const name = file.name.replace(/\\/g, '/');
+            // Directory entries carry no data; the parent mkdir below covers them.
+            if (name.endsWith('/'))
+                return;
+            // FIRST of the two path defences (§8.3 validate is the second). Applied
+            // before a single byte is written, so a zip-slip entry never exists.
+            const pathIssue = checkStagedPath(name);
+            if (pathIssue) {
+                fail(`${pathIssue.code}: ${pathIssue.message}`);
+                return;
+            }
+            const absolute = resolve(targetDir, name);
+            const rel = relative(targetDir, absolute);
+            if (rel.startsWith('..') || rel.length === 0) {
+                fail(`entry escapes the extraction root: ${name}`);
+                return;
+            }
+            const pending = { path: absolute, chunks: [], written: 0 };
+            // fflate names the COMPRESSED size `size` and the uncompressed one
+            // `originalSize`; both are absent for streaming-built archives, in which
+            // case the ratio gate simply does not apply and the byte gates carry it.
+            const compressed = file.size ?? 0;
+            file.ondata = (err, chunk, final) => {
+                if (failure)
+                    return;
+                if (err) {
+                    fail(`failed to inflate ${name}: ${err.message}`);
+                    return;
+                }
+                if (chunk && chunk.length > 0) {
+                    pending.written += chunk.length;
+                    totalInflated += chunk.length;
+                    // Gate 1 + 2: real bytes, checked as they arrive so we can stop.
+                    if (pending.written > ARCHIVE_MAX_ENTRY_BYTES) {
+                        fail(`${name} inflates to more than ${ARCHIVE_MAX_ENTRY_BYTES} bytes`);
+                        return;
+                    }
+                    if (totalInflated > ARCHIVE_MAX_TOTAL_BYTES) {
+                        fail(`archive inflates to more than ${ARCHIVE_MAX_TOTAL_BYTES} bytes`);
+                        return;
+                    }
+                    pending.chunks.push(Buffer.from(chunk));
+                }
+                if (!final)
+                    return;
+                // Gate 3: compression ratio, computed from what we actually produced.
+                if (compressed >= ARCHIVE_RATIO_MIN_COMPRESSED &&
+                    pending.written / compressed > ARCHIVE_MAX_RATIO) {
+                    fail(`${name} has a compression ratio above ${ARCHIVE_MAX_RATIO}:1 ` +
+                        `(${pending.written} from ${compressed} bytes)`);
+                    return;
+                }
+                try {
+                    mkdirSync(dirname(pending.path), { recursive: true });
+                    writeFileSync(pending.path, Buffer.concat(pending.chunks));
+                    written.push(pending.path);
+                }
+                catch (writeErr) {
+                    fail(`could not write ${name}: ${writeErr.message}`);
+                }
+            };
+            file.start();
+        });
+        unzip.register(UnzipInflate);
+        try {
+            unzip.push(new Uint8Array(buffer), true);
+            resolvePromise();
+        }
+        catch (err) {
+            rejectPromise(err instanceof Error ? err : new Error(String(err)));
+        }
+    }).catch((err) => {
+        fail(`malformed zip archive: ${err.message}`);
+    });
+    // fflate's streaming reader does not throw on garbage — it simply never
+    // yields an entry. Left unchecked, "this .zip is actually an HTML error page"
+    // would surface much later as a puzzling SKILL_MD_MISSING instead of the
+    // truth, so zero entries is treated as a malformed archive here.
+    if (!failure && entryCount === 0) {
+        fail('no entries found - the file is not a valid zip archive');
+    }
+    if (failure) {
+        rmSync(targetDir, { recursive: true, force: true });
+        throw failure;
+    }
+    return written;
+}
+/** Convenience for tests and callers that want the relative view. */
+export function relativePaths(root, files) {
+    return files.map((f) => relative(root, f).replace(/\\/g, '/')).sort();
+}

package/dist/skills/cli-commands.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `aragon skills …` — the non-interactive surface (spec §7.3).
+ *
+ * Exit codes match the existing `runConfigSet` convention:
+ *   0 success · 1 run-time failure (network / fs / git) · 2 usage or validation.
+ *
+ * Nothing here renders Ink. These commands run in a one-shot process, so there
+ * is no App and therefore no human channel unless `--yes` says otherwise — the
+ * same fail-closed rule the agent tools follow, reached through the same gate.
+ */
+import { type UpdateResult } from './updater.js';
+import { type CliFlags } from '../config/load.js';
+import { type SkillRecord } from '@aragon-agent/core';
+export interface SkillsCliOptions {
+    scope?: string;
+    name?: string;
+    description?: string;
+    yes?: boolean;
+    json?: boolean;
+    all?: boolean;
+    force?: boolean;
+    dryRun?: boolean;
+    check?: boolean;
+    sort?: string;
+    /** `skills usage --reset` — delete the local counters. */
+    reset?: boolean;
+}
+/** Dispatch an `aragon skills <sub>` invocation and return the exit code. */
+export declare function runSkillsCommand(sub: string, argument: string | undefined, opts: SkillsCliOptions, flags: CliFlags, version: string): Promise<number>;
+/**
+ * Can this skill's `allowed-tools` ever take effect?
+ *
+ * Resolved against `HOST_TOOL_NAMES`, not a live tool array: this process has no
+ * `AgentController` at all (P1-8), and the question doctor answers is "will this
+ * declaration work?", not "is it working at this instant". Using the superset
+ * also makes the output independent of how the CLI happened to be invoked, which
+ * is what lets it be snapshot-tested.
+ */
+export declare function checkDeclaredTools(record: SkillRecord): string[];
+/** Bundled scripts that cannot run on this host's shell (§8.4). Warn, never error. */
+export declare function checkScriptPlatform(record: SkillRecord, files: Array<{
+    path: string;
+}>): string[];
+/**
+ * One row of the `--all` summary, in the tense the user will read it in.
+ *
+ * The tense comes from the FLAG, not from the shape of the result. A successful
+ * real update also carries `changedFiles`, so inferring "dry run" from its
+ * presence made every genuine `--all` run report "would update" for work it had
+ * already committed to disk.
+ */
+export declare function describeResult(result: UpdateResult, dryRun: boolean): string;