@aragon-agent/core 0.1.3

package/dist/skills/frontmatter.d.ts

@@ -0,0 +1,27 @@
+/**
+ * SKILL.md frontmatter parser — a deliberately STRICT SUBSET of YAML (D9).
+ *
+ * Why not depend on `yaml`: `@aragon-agent/core` ships zero required runtime
+ * dependencies (only `ajv` / `isolated-vm` as optional), and real SKILL.md
+ * frontmatter only ever uses scalars, quoted strings, inline arrays and block
+ * arrays. Unknown keys are preserved verbatim in `data` so a future Anthropic
+ * field never breaks parsing.
+ *
+ * Every rule below is numbered to match spec §4.3 and has a dedicated test.
+ */
+export interface ParsedFrontmatter {
+    data: Record<string, string | string[]>;
+    /** Everything after the closing delimiter, `trimStart()`-ed. */
+    body: string;
+    /** Non-fatal warnings (duplicate keys, tab indentation, bad key syntax). */
+    errors: string[];
+}
+/**
+ * Parse the frontmatter block of a SKILL.md.
+ *
+ * Returns `null` when there is no usable frontmatter at all — no opening `---`,
+ * no closing delimiter, or a block that blows past the hard limits of rule 8.
+ * `null` is never an exception: a malformed skill degrades to `invalid` in the
+ * registry and stays visible to the user (§4.4), it does not crash discovery.
+ */
+export declare function parseFrontmatter(source: string): ParsedFrontmatter | null;

package/dist/skills/frontmatter.js

@@ -0,0 +1,177 @@
+/**
+ * SKILL.md frontmatter parser — a deliberately STRICT SUBSET of YAML (D9).
+ *
+ * Why not depend on `yaml`: `@aragon-agent/core` ships zero required runtime
+ * dependencies (only `ajv` / `isolated-vm` as optional), and real SKILL.md
+ * frontmatter only ever uses scalars, quoted strings, inline arrays and block
+ * arrays. Unknown keys are preserved verbatim in `data` so a future Anthropic
+ * field never breaks parsing.
+ *
+ * Every rule below is numbered to match spec §4.3 and has a dedicated test.
+ */
+import { FRONTMATTER_MAX_BYTES, FRONTMATTER_MAX_LINES } from './constants.js';
+const KEY_PATTERN = /^[A-Za-z0-9_-]+$/;
+/** Rule 1: strip a UTF-8 BOM and normalize CRLF / lone CR to LF. */
+function normalizeSource(source) {
+    const noBom = source.charCodeAt(0) === 0xfeff ? source.slice(1) : source;
+    return noBom.replace(/\r\n?/g, '\n');
+}
+/**
+ * Rule 5: `#` only starts a comment at the start of a line or after whitespace,
+ * so a URL fragment (`homepage: https://x/y#v1`) survives. Text inside a leading
+ * quoted string is skipped first — `description: "a # b"` keeps its hash.
+ */
+function stripComment(value) {
+    const quote = value[0];
+    let i = 0;
+    if (quote === '"' || quote === "'") {
+        i = 1;
+        while (i < value.length) {
+            if (value[i] === '\\' && quote === '"') {
+                i += 2;
+                continue;
+            }
+            if (value[i] === quote) {
+                i += 1;
+                break;
+            }
+            i += 1;
+        }
+    }
+    for (; i < value.length; i += 1) {
+        if (value[i] !== '#')
+            continue;
+        if (i === 0 || /\s/.test(value[i - 1]))
+            return value.slice(0, i);
+    }
+    return value;
+}
+/** Rule 4c: remove surrounding quotes, honouring only `\"` and `\\`. */
+function dequote(value) {
+    if (value.length < 2)
+        return value;
+    const quote = value[0];
+    if ((quote !== '"' && quote !== "'") || value[value.length - 1] !== quote)
+        return value;
+    const inner = value.slice(1, -1);
+    if (quote === "'")
+        return inner.replace(/''/g, "'");
+    return inner.replace(/\\(["\\])/g, '$1');
+}
+/** Rule 4b: `[a, b, "c d"]` → `['a', 'b', 'c d']`. */
+function parseInlineArray(value) {
+    const inner = value.slice(1, -1).trim();
+    if (inner.length === 0)
+        return [];
+    return inner
+        .split(',')
+        .map((item) => dequote(item.trim()))
+        .filter((item) => item.length > 0);
+}
+/**
+ * Parse the frontmatter block of a SKILL.md.
+ *
+ * Returns `null` when there is no usable frontmatter at all — no opening `---`,
+ * no closing delimiter, or a block that blows past the hard limits of rule 8.
+ * `null` is never an exception: a malformed skill degrades to `invalid` in the
+ * registry and stays visible to the user (§4.4), it does not crash discovery.
+ */
+export function parseFrontmatter(source) {
+    const text = normalizeSource(source);
+    const lines = text.split('\n');
+    // Rule 2: the opening `---`, optionally preceded by blank lines.
+    let start = 0;
+    while (start < lines.length && lines[start].trim().length === 0)
+        start += 1;
+    if (start >= lines.length || lines[start].trim() !== '---')
+        return null;
+    let end = -1;
+    for (let i = start + 1; i < lines.length; i += 1) {
+        const trimmed = lines[i].trim();
+        if (trimmed === '---' || trimmed === '...') {
+            end = i;
+            break;
+        }
+    }
+    if (end === -1)
+        return null;
+    const blockLines = lines.slice(start + 1, end);
+    // Rule 8: hard limits — a pathological file must not become a parsing DoS.
+    if (blockLines.length > FRONTMATTER_MAX_LINES)
+        return null;
+    if (Buffer.byteLength(blockLines.join('\n'), 'utf-8') > FRONTMATTER_MAX_BYTES)
+        return null;
+    const data = {};
+    const errors = [];
+    let pendingArrayKey = null;
+    /** Keys opened with an empty value — only these may collapse back to `''`. */
+    const emptyValueKeys = new Set();
+    const setKey = (key, value) => {
+        // Rule 7: last one wins, but say so.
+        if (Object.prototype.hasOwnProperty.call(data, key)) {
+            errors.push(`duplicate key "${key}" - the last value wins`);
+        }
+        data[key] = value;
+    };
+    for (let i = 0; i < blockLines.length; i += 1) {
+        const rawLine = blockLines[i];
+        if (rawLine.trim().length === 0)
+            continue;
+        const indent = /^[ \t]*/.exec(rawLine)[0];
+        // Rule 6: tabs are never valid YAML indentation.
+        if (indent.includes('\t')) {
+            errors.push(`line ${i + 1}: tab indentation is not supported`);
+            continue;
+        }
+        const trimmed = rawLine.trim();
+        if (trimmed.startsWith('#'))
+            continue;
+        // Block-array continuation (rule 4a).
+        if (pendingArrayKey !== null && trimmed.startsWith('- ')) {
+            const item = dequote(stripComment(trimmed.slice(2).trim()).trim());
+            if (item.length > 0)
+                data[pendingArrayKey].push(item);
+            continue;
+        }
+        pendingArrayKey = null;
+        if (indent.length > 0) {
+            errors.push(`line ${i + 1}: unexpected indentation outside a block list`);
+            continue;
+        }
+        // Rule 3: split on the FIRST colon.
+        const colon = trimmed.indexOf(':');
+        if (colon === -1) {
+            errors.push(`line ${i + 1}: not a "key: value" pair`);
+            continue;
+        }
+        const key = trimmed.slice(0, colon).trim();
+        if (!KEY_PATTERN.test(key)) {
+            errors.push(`line ${i + 1}: invalid key "${key}"`);
+            continue;
+        }
+        // Trim BEFORE stripping comments: `stripComment` only recognizes a leading
+        // quote at index 0, so a value like ` "a # b"` would otherwise lose its hash.
+        const rawValue = stripComment(trimmed.slice(colon + 1).trim()).trim();
+        if (rawValue.length === 0) {
+            // Empty value: either a block array follows, or it really is empty.
+            setKey(key, []);
+            emptyValueKeys.add(key);
+            pendingArrayKey = key;
+            continue;
+        }
+        emptyValueKeys.delete(key);
+        if (rawValue.startsWith('[') && rawValue.endsWith(']')) {
+            setKey(key, parseInlineArray(rawValue));
+            continue;
+        }
+        setKey(key, dequote(rawValue));
+    }
+    // An empty-valued key with no `- ` items behind it was a scalar all along.
+    // `keywords: []` is NOT touched — it was written as an explicit empty array.
+    for (const key of emptyValueKeys) {
+        const value = data[key];
+        if (Array.isArray(value) && value.length === 0)
+            data[key] = '';
+    }
+    return { data, body: lines.slice(end + 1).join('\n').trimStart(), errors };
+}

package/dist/skills/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Skills submodule barrel — reachable as `@aragon-agent/core/skills`.
+ *
+ * The root barrel (`src/index.ts`) re-exports the documented public face; this
+ * subpath additionally exposes the internals the CLI needs (staged-install
+ * validation, always-block rendering, byte helpers) without widening the frozen
+ * top-level API surface. Same "root barrel + subpath" split the tools module
+ * already uses.
+ */
+export * from './constants.js';
+export * from './types.js';
+export { parseFrontmatter } from './frontmatter.js';
+export type { ParsedFrontmatter } from './frontmatter.js';
+export { validateSkillFrontmatter, validateStagedSkill, normalizeFrontmatter, checkStagedPath, hasControlChar, } from './validate.js';
+export { sanitizeForPromptBlock, renderSkillCatalog, renderSkillBody, renderSkillInvocation, renderAlwaysSkills, renderCatalogLine, renderSkillFindResults, renderSkillFindNoMatch, applySkillArguments, splitArguments, suggestSkillNames, catalogRecords, rankCatalogRecords, classifyBundledFile, byteLength, truncateToBytes, } from './disclosure.js';
+export { normalizeToolAlias, resolveDeclaredTool, computeToolPolicy, evaluateToolCall, renderDenyEscalation, renderDenyEscalationNotice, SKILL_TOOL_ALIASES, SKILL_TOOL_KNOWN_ABSENT, } from './tool-policy.js';
+export { SkillRegistry } from './skill-registry.js';
+export { createSkillTool } from './skill-tool.js';
+export type { SkillToolDeps } from './skill-tool.js';
+export { createSkillFindTool, matchSkills } from './skill-find-tool.js';
+export type { SkillFindToolDeps } from './skill-find-tool.js';

package/dist/skills/index.js

@@ -0,0 +1,18 @@
+/**
+ * Skills submodule barrel — reachable as `@aragon-agent/core/skills`.
+ *
+ * The root barrel (`src/index.ts`) re-exports the documented public face; this
+ * subpath additionally exposes the internals the CLI needs (staged-install
+ * validation, always-block rendering, byte helpers) without widening the frozen
+ * top-level API surface. Same "root barrel + subpath" split the tools module
+ * already uses.
+ */
+export * from './constants.js';
+export * from './types.js';
+export { parseFrontmatter } from './frontmatter.js';
+export { validateSkillFrontmatter, validateStagedSkill, normalizeFrontmatter, checkStagedPath, hasControlChar, } from './validate.js';
+export { sanitizeForPromptBlock, renderSkillCatalog, renderSkillBody, renderSkillInvocation, renderAlwaysSkills, renderCatalogLine, renderSkillFindResults, renderSkillFindNoMatch, applySkillArguments, splitArguments, suggestSkillNames, catalogRecords, rankCatalogRecords, classifyBundledFile, byteLength, truncateToBytes, } from './disclosure.js';
+export { normalizeToolAlias, resolveDeclaredTool, computeToolPolicy, evaluateToolCall, renderDenyEscalation, renderDenyEscalationNotice, SKILL_TOOL_ALIASES, SKILL_TOOL_KNOWN_ABSENT, } from './tool-policy.js';
+export { SkillRegistry } from './skill-registry.js';
+export { createSkillTool } from './skill-tool.js';
+export { createSkillFindTool, matchSkills } from './skill-find-tool.js';

package/dist/skills/skill-find-tool.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The `skill_find` tool — the escape hatch for a truncated Level 1 catalog
+ * (spec §5.4 / D-A1).
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * THIS SEARCHES WHAT IS INSTALLED. IT NEVER TOUCHES THE NETWORK.
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * The boundary is the whole point (D-A4). Iteration 1 deliberately shipped no
+ * search tool, on the reasoning that the catalog already showed everything.
+ * `SKILL_CATALOG_MAX_BYTES` is 6000 and a CJK description can cost 660 bytes a
+ * line, so that premise fails at roughly ten skills — and when it fails, the
+ * omitted skills become invisible to the model with no error anywhere (F1/F2).
+ * This tool restores reachability for exactly that case and nothing more.
+ *
+ * If it ever returned installable-but-not-installed candidates, "the agent can
+ * install skills" would quietly change meaning from "the user pointed at a
+ * source and the model did the work" to "the model picks its own dependencies".
+ * That is a different security model, and it is not this one.
+ *
+ * Pure logic, like `skill-tool.ts`: the registry is injected, and this module
+ * imports no `node:*` (enforced by `no-host-coupling.test.ts`).
+ */
+import type { AgentTool } from '../tools/types.js';
+import type { SkillRegistry } from './skill-registry.js';
+import type { SkillRecord } from './types.js';
+export interface SkillFindToolDeps {
+    registry: SkillRegistry;
+    maxBytes?: number;
+    defaultLimit?: number;
+}
+/**
+ * Deterministic three-stage match; the first stage that yields anything wins.
+ *
+ * Stage 2 is AND across tokens, not OR. With OR, a query like "pdf form" would
+ * drag in every skill whose description happens to contain "form" — and because
+ * the result block has its own byte budget, the one skill the model actually
+ * needed could be the entry that gets dropped off the end.
+ */
+export declare function matchSkills(query: string, records: SkillRecord[]): SkillRecord[];
+export declare function createSkillFindTool(deps: SkillFindToolDeps): AgentTool;

package/dist/skills/skill-find-tool.js

@@ -0,0 +1,117 @@
+/**
+ * The `skill_find` tool — the escape hatch for a truncated Level 1 catalog
+ * (spec §5.4 / D-A1).
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * THIS SEARCHES WHAT IS INSTALLED. IT NEVER TOUCHES THE NETWORK.
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * The boundary is the whole point (D-A4). Iteration 1 deliberately shipped no
+ * search tool, on the reasoning that the catalog already showed everything.
+ * `SKILL_CATALOG_MAX_BYTES` is 6000 and a CJK description can cost 660 bytes a
+ * line, so that premise fails at roughly ten skills — and when it fails, the
+ * omitted skills become invisible to the model with no error anywhere (F1/F2).
+ * This tool restores reachability for exactly that case and nothing more.
+ *
+ * If it ever returned installable-but-not-installed candidates, "the agent can
+ * install skills" would quietly change meaning from "the user pointed at a
+ * source and the model did the work" to "the model picks its own dependencies".
+ * That is a different security model, and it is not this one.
+ *
+ * Pure logic, like `skill-tool.ts`: the registry is injected, and this module
+ * imports no `node:*` (enforced by `no-host-coupling.test.ts`).
+ */
+import { errorResult, textResult } from '../tools/helpers.js';
+import { SKILL_FIND_DEFAULT_LIMIT, SKILL_FIND_MAX_LIMIT, SKILL_FIND_MAX_TOKENS, } from './constants.js';
+import { renderSkillFindResults, suggestSkillNames } from './disclosure.js';
+const DESCRIPTION = 'Search the skills installed on this machine by name, description or keyword. Use this when the ' +
+    'available-skills list says some skills were not shown, or when you suspect a skill exists for ' +
+    'the task but you cannot see it. This searches ONLY what is already installed - it never reaches ' +
+    'the network and never returns skills you could install. If nothing matches, ask the user for a ' +
+    'source instead of inventing one.';
+/**
+ * Skills a search may return.
+ *
+ * `activation: manual` is excluded on purpose (D-A3). Manual means "do not put
+ * this in front of the model; only the user may invoke it with `/<name>`".
+ * Letting search surface it would silently downgrade that setting from an
+ * exclusion to a ranking penalty, which is not what the author asked for.
+ */
+function searchable(registry) {
+    return registry
+        .list()
+        .filter((r) => !r.disabled && !r.invalid && r.frontmatter.activation !== 'manual');
+}
+/** The haystack for one record: name, description and keywords, lowercased. */
+function haystack(record) {
+    return `${record.name} ${record.description} ${record.frontmatter.keywords.join(' ')}`.toLowerCase();
+}
+/**
+ * Deterministic three-stage match; the first stage that yields anything wins.
+ *
+ * Stage 2 is AND across tokens, not OR. With OR, a query like "pdf form" would
+ * drag in every skill whose description happens to contain "form" — and because
+ * the result block has its own byte budget, the one skill the model actually
+ * needed could be the entry that gets dropped off the end.
+ */
+export function matchSkills(query, records) {
+    const normalized = query.trim().toLowerCase();
+    if (normalized.length === 0)
+        return [];
+    const exact = records.filter((r) => r.name.toLowerCase() === normalized);
+    if (exact.length > 0)
+        return exact;
+    const tokens = normalized.split(/\s+/).filter(Boolean).slice(0, SKILL_FIND_MAX_TOKENS);
+    if (tokens.length === 0)
+        return [];
+    return records.filter((r) => {
+        const text = haystack(r);
+        return tokens.every((token) => text.includes(token));
+    });
+}
+export function createSkillFindTool(deps) {
+    return {
+        name: 'skill_find',
+        label: 'Find Skill',
+        description: DESCRIPTION,
+        parameters: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Words describing the capability you need, e.g. "pdf form" or "deploy preview".',
+                },
+                limit: { type: 'integer', description: 'Max results. Default 10, max 25.' },
+            },
+            required: ['query'],
+        },
+        async execute(_id, rawParams) {
+            const params = rawParams;
+            const query = typeof params.query === 'string' ? params.query.trim() : '';
+            if (query.length === 0)
+                return errorResult('skill_find requires a "query" parameter.');
+            const candidates = searchable(deps.registry);
+            const matched = matchSkills(query, candidates);
+            // Out-of-range limits are clamped rather than rejected: a model that asks
+            // for 500 results wants "as many as you have", and failing the call would
+            // cost a turn to relearn a bound it can simply be given.
+            const requested = typeof params.limit === 'number' && Number.isFinite(params.limit)
+                ? Math.floor(params.limit)
+                : (deps.defaultLimit ?? SKILL_FIND_DEFAULT_LIMIT);
+            const limit = Math.min(SKILL_FIND_MAX_LIMIT, Math.max(1, requested));
+            // Stage 3: near-miss names, but only when the first two stages came up
+            // empty — otherwise a good match would be diluted with guesses.
+            const suggestions = matched.length === 0 ? suggestSkillNames(query, candidates.map((r) => r.name), 3) : [];
+            return textResult(renderSkillFindResults(query, matched.slice(0, limit), {
+                total: candidates.length,
+                // The PRE-slice count, so `limit` shows up as "+N more matches not
+                // shown" instead of quietly passing a truncated list off as the
+                // complete one — which is the exact failure mode (F1) this tool was
+                // added to undo, and it would be embarrassing to reintroduce here.
+                matchedTotal: matched.length,
+                ...(deps.maxBytes !== undefined ? { maxBytes: deps.maxBytes } : {}),
+                suggestions,
+            }));
+        },
+    };
+}

package/dist/skills/skill-registry.d.ts

@@ -0,0 +1,96 @@
+/**
+ * In-memory skill registry (spec §10.1). Pure state: no filesystem, no network.
+ *
+ * Precedence (D7) is decided by the ORDER records are added — the CLI scanner
+ * walks roots low-to-high (bundled → user → project → env), so a later `add()`
+ * of the same name wins and the loser is recorded in `shadowed[]` rather than
+ * silently dropped. `/skills` renders that as `~shadowed by project`, which is
+ * the difference between "my edit did nothing" being a mystery and being a
+ * one-line answer.
+ */
+import type { SkillRecord } from './types.js';
+export declare class SkillRegistry {
+    private readonly byName;
+    /** Skills loaded via the `skill` tool during THIS session. */
+    private readonly active;
+    private readonly frameActive;
+    private readonly framePending;
+    /**
+     * Announce-once ledgers (§5.5 / P1-2). They live here rather than in the tool
+     * wrapper because this class is already the sole authority on when a turn
+     * begins — a `Set` closed over in `withToolPolicy` would be session-scoped and
+     * would silence `warn` mode after its very first message.
+     */
+    private readonly warnedThisTurn;
+    private readonly failOpenNoticed;
+    private readonly deniedThisTurn;
+    /**
+     * Insert a record, resolving a same-name collision in favour of the newcomer
+     * (higher-precedence root) while preserving the loser as a shadow entry.
+     */
+    add(record: SkillRecord): void;
+    get(name: string): SkillRecord | undefined;
+    /** Every record, including disabled and invalid ones, sorted by name. */
+    list(): SkillRecord[];
+    names(): string[];
+    /** Level 1-eligible records in canonical order (scope desc, then name asc). */
+    catalog(): SkillRecord[];
+    /** Records that should be injected as Level 2 at session start (§5.4). */
+    alwaysOn(extraNames?: string[]): SkillRecord[];
+    setDisabled(name: string, disabled: boolean): void;
+    /** Idempotent: marks a skill as loaded and reports whether it already was. */
+    activate(name: string): boolean;
+    isActive(name: string): boolean;
+    get activeNames(): string[];
+    /**
+     * Drop the session's loaded-skill set. Called by `/reset` (P2-9) — without it
+     * the "already loaded earlier in this conversation" hint would keep claiming
+     * a skill is in a context that no longer exists.
+     *
+     * Clearing the frames here rather than at the call site is deliberate (§7.3):
+     * "remember to call the other method too" is not a design, and the symptom of
+     * forgetting — a ceiling surviving a `/reset` — would be attributed to
+     * anything but this.
+     */
+    clearActive(): void;
+    /** The `skill` tool succeeded: this skill constrains the turn from now on. */
+    enterFrame(name: string): void;
+    /** A `/<skill-name>` command ran: constrain the turn its message is about to open. */
+    queueFrame(name: string): void;
+    /** A new user message arrived: the previous turn's ceiling expires, queued ones promote. */
+    beginUserTurn(): void;
+    /**
+     * A user message arrived MID-RUN (`steer`). Promotes the queue without
+     * clearing what is already in force (D-G3): the turn has not ended, so neither
+     * has the skill procedure — and letting an interjection lift the ceiling would
+     * make "ask a follow-up question" the documented way around it.
+     *
+     * The turn ledgers are deliberately NOT reset: this is the same turn.
+     */
+    absorbPendingFrames(): void;
+    /** `/skills unload` — drops the ceiling. Does NOT reclaim context; nothing can. */
+    clearFrames(): void;
+    private resetTurnLedgers;
+    get frameNames(): string[];
+    /** Names queued by a slash command, awaiting the user message they will constrain. */
+    get pendingFrameNames(): string[];
+    /**
+     * The frame's records that STILL EXIST and are still usable.
+     *
+     * Unresolvable / disabled / invalid names are dropped from the result but KEPT
+     * in `frameActive`, so `frameNames` can still say which skill was supposed to
+     * be constraining this turn. The caller owes the user one notice per lifted
+     * skill (§5.6f): uninstall, disable and a flip to `integrity: strict` all end
+     * with the ceiling gone, and a ceiling that disappears without a word is the
+     * exact failure class this whole iteration exists to remove.
+     */
+    frameRecords(): SkillRecord[];
+    /** True on the first `(skill, tool)` pair this TURN; false afterwards. */
+    noteWarnOnce(skill: string, tool: string): boolean;
+    /** True on the first mention of `key` this SESSION; false afterwards. */
+    noteFailOpenOnce(key: string): boolean;
+    /** Count this refusal and return the running total for the tool, this turn. */
+    countDeny(tool: string): number;
+    /** Swap the whole table after a rescan, preserving the active set. */
+    replaceAll(records: SkillRecord[]): void;
+}