@aragon-agent/core 0.1.3

package/dist/skills/skill-registry.js

@@ -0,0 +1,208 @@
+/**
+ * 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 { catalogRecords } from './disclosure.js';
+export class SkillRegistry {
+    byName = new Map();
+    /** Skills loaded via the `skill` tool during THIS session. */
+    active = new Set();
+    // -------------------------------------------------------------------------
+    // Frames (§5.1) — the turn-scoped source set behind the tool ceiling.
+    //
+    // NOT the same thing as `active`, and conflating them is the mistake this
+    // split exists to prevent: `active` answers "has this body already been sent
+    // in this conversation" and only ever grows, whereas a ceiling has to expire
+    // the moment the user's intent changes. Two segments, because a slash command
+    // submits the very message that opens the turn it must constrain (D-G2): it
+    // QUEUES, and `beginUserTurn()` promotes.
+    //
+    // NAMES, NOT RECORDS (D-G20). `discover()` swaps the whole table via
+    // `replaceAll()`, and it runs mid-turn — `/skills reload`, `/skills trust`,
+    // any install. A held record reference would quietly become an orphan whose
+    // `disabled` flag and integrity verdict are frozen in the past.
+    // -------------------------------------------------------------------------
+    frameActive = new Set();
+    framePending = new Set();
+    /**
+     * 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.
+     */
+    warnedThisTurn = new Set();
+    failOpenNoticed = new Set();
+    deniedThisTurn = new Map();
+    /**
+     * 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) {
+        const existing = this.byName.get(record.name);
+        if (!existing) {
+            this.byName.set(record.name, record);
+            return;
+        }
+        // Highest-precedence loser first, so `/skills` can render "~shadowed by
+        // <shadowed[0].scope>" without re-deriving the ordering.
+        record.shadowed = [
+            { scope: existing.scope, dir: existing.dir },
+            ...existing.shadowed,
+            ...record.shadowed,
+        ];
+        this.byName.set(record.name, record);
+    }
+    get(name) {
+        return this.byName.get(name);
+    }
+    /** Every record, including disabled and invalid ones, sorted by name. */
+    list() {
+        return Array.from(this.byName.values()).sort((a, b) => a.name.localeCompare(b.name, 'en'));
+    }
+    names() {
+        return this.list().map((r) => r.name);
+    }
+    /** Level 1-eligible records in canonical order (scope desc, then name asc). */
+    catalog() {
+        return catalogRecords(Array.from(this.byName.values()));
+    }
+    /** Records that should be injected as Level 2 at session start (§5.4). */
+    alwaysOn(extraNames = []) {
+        const forced = new Set(extraNames);
+        return Array.from(this.byName.values()).filter((r) => !r.disabled && !r.invalid && (r.frontmatter.activation === 'always' || forced.has(r.name)));
+    }
+    setDisabled(name, disabled) {
+        const record = this.byName.get(name);
+        if (record)
+            record.disabled = disabled;
+    }
+    /** Idempotent: marks a skill as loaded and reports whether it already was. */
+    activate(name) {
+        const wasActive = this.active.has(name);
+        this.active.add(name);
+        return wasActive;
+    }
+    isActive(name) {
+        return this.active.has(name);
+    }
+    get activeNames() {
+        return Array.from(this.active).sort();
+    }
+    /**
+     * 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() {
+        this.active.clear();
+        this.clearFrames();
+        this.failOpenNoticed.clear();
+    }
+    // -------------------------------------------------------------------------
+    // Frame lifecycle (§5.1). Exactly four events move a name; there is no fifth.
+    // -------------------------------------------------------------------------
+    /** The `skill` tool succeeded: this skill constrains the turn from now on. */
+    enterFrame(name) {
+        this.frameActive.add(name);
+    }
+    /** A `/<skill-name>` command ran: constrain the turn its message is about to open. */
+    queueFrame(name) {
+        this.framePending.add(name);
+    }
+    /** A new user message arrived: the previous turn's ceiling expires, queued ones promote. */
+    beginUserTurn() {
+        this.frameActive.clear();
+        for (const name of this.framePending)
+            this.frameActive.add(name);
+        this.framePending.clear();
+        this.resetTurnLedgers();
+    }
+    /**
+     * 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() {
+        for (const name of this.framePending)
+            this.frameActive.add(name);
+        this.framePending.clear();
+    }
+    /** `/skills unload` — drops the ceiling. Does NOT reclaim context; nothing can. */
+    clearFrames() {
+        this.frameActive.clear();
+        this.framePending.clear();
+        this.resetTurnLedgers();
+    }
+    resetTurnLedgers() {
+        this.warnedThisTurn.clear();
+        this.deniedThisTurn.clear();
+    }
+    get frameNames() {
+        return Array.from(this.frameActive).sort();
+    }
+    /** Names queued by a slash command, awaiting the user message they will constrain. */
+    get pendingFrameNames() {
+        return Array.from(this.framePending).sort();
+    }
+    /**
+     * 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() {
+        const out = [];
+        for (const name of this.frameNames) {
+            const record = this.byName.get(name);
+            if (!record || record.disabled || record.invalid)
+                continue;
+            out.push(record);
+        }
+        return out;
+    }
+    /** True on the first `(skill, tool)` pair this TURN; false afterwards. */
+    noteWarnOnce(skill, tool) {
+        const key = `${skill}::${tool}`;
+        if (this.warnedThisTurn.has(key))
+            return false;
+        this.warnedThisTurn.add(key);
+        return true;
+    }
+    /** True on the first mention of `key` this SESSION; false afterwards. */
+    noteFailOpenOnce(key) {
+        if (this.failOpenNoticed.has(key))
+            return false;
+        this.failOpenNoticed.add(key);
+        return true;
+    }
+    /** Count this refusal and return the running total for the tool, this turn. */
+    countDeny(tool) {
+        const next = (this.deniedThisTurn.get(tool) ?? 0) + 1;
+        this.deniedThisTurn.set(tool, next);
+        return next;
+    }
+    /** Swap the whole table after a rescan, preserving the active set. */
+    replaceAll(records) {
+        this.byName.clear();
+        for (const record of records)
+            this.add(record);
+    }
+}

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

@@ -0,0 +1,44 @@
+/**
+ * The `skill` tool — Level 2 of progressive disclosure (spec §5.2).
+ *
+ * WHY A TOOL RESULT AND NOT A SYSTEM-PROMPT REWRITE (D2): `Agent.prompt()`
+ * snapshots `this.systemPrompt` when the loop starts, so mutating it mid-run is
+ * a no-op for the current turn. A tool result, by contrast, enters the message
+ * history immediately, survives `/save` + `/resume` for free, and costs nothing
+ * on turns where no skill is used.
+ *
+ * NAMING (D4): lowercase `skill`, matching the seven existing snake_case tools,
+ * rather than Claude Code's `Skill`. The catalog block spells out the mapping so
+ * community skills that say "call the Skill tool" still resolve.
+ */
+import type { AgentTool } from '../tools/types.js';
+import type { SkillRegistry } from './skill-registry.js';
+import type { SkillFileRef, SkillPlatform, SkillPolicyView } from './types.js';
+export interface SkillToolDeps {
+    registry: SkillRegistry;
+    /**
+     * Read SKILL.md + list bundled files for a skill.
+     * MAY THROW — the Node host wraps sync fs calls (§10.1 error contract), so
+     * `execute()` below owns the try/catch. "Never throws" is the TOOL's promise.
+     */
+    loadBody: (name: string) => {
+        body: string;
+        files: SkillFileRef[];
+    };
+    bodyMaxBytes?: number;
+    resultMaxBytes?: number;
+    /**
+     * Take a policy snapshot for the ceiling line in the rendered body.
+     * `undefined` (the port, or its return value) means "render no policy line".
+     *
+     * MUST BE CALLED AFTER `enterFrame(name)` — see the numbered sequence in
+     * `execute()`. The skill being loaded is itself one of the ceiling's sources,
+     * so a snapshot taken first would print a permitted set missing the very
+     * tools this skill just granted: the one wrong answer a model would act on
+     * without hesitating.
+     */
+    policySnapshot?: () => SkillPolicyView | undefined;
+    /** Host shell family for the Level 3 guidance (D-G14; core never reads `process`). */
+    platform?: SkillPlatform;
+}
+export declare function createSkillTool(deps: SkillToolDeps): AgentTool;

package/dist/skills/skill-tool.js

@@ -0,0 +1,96 @@
+/**
+ * The `skill` tool — Level 2 of progressive disclosure (spec §5.2).
+ *
+ * WHY A TOOL RESULT AND NOT A SYSTEM-PROMPT REWRITE (D2): `Agent.prompt()`
+ * snapshots `this.systemPrompt` when the loop starts, so mutating it mid-run is
+ * a no-op for the current turn. A tool result, by contrast, enters the message
+ * history immediately, survives `/save` + `/resume` for free, and costs nothing
+ * on turns where no skill is used.
+ *
+ * NAMING (D4): lowercase `skill`, matching the seven existing snake_case tools,
+ * rather than Claude Code's `Skill`. The catalog block spells out the mapping so
+ * community skills that say "call the Skill tool" still resolve.
+ */
+import { errorResult, textResult } from '../tools/helpers.js';
+import { renderSkillBody, suggestSkillNames } from './disclosure.js';
+const DESCRIPTION = 'Load the full instructions of an installed skill before doing work it covers. ' +
+    'Pick the exact name from <available_skills>. Returns the skill body plus a list of ' +
+    'bundled files you can then read with read_file or run with bash. ' +
+    'Loading a skill is cheap - prefer it over re-deriving a procedure yourself.';
+export function createSkillTool(deps) {
+    return {
+        name: 'skill',
+        label: 'Skill',
+        description: DESCRIPTION,
+        parameters: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Exact skill name from <available_skills>.' },
+                arguments: { type: 'string', description: 'Optional free-form arguments for the skill.' },
+                force: {
+                    type: 'boolean',
+                    description: 'Re-send the full body even if this skill was already loaded in this conversation. ' +
+                        'Only needed if you cannot find the earlier copy.',
+                },
+            },
+            required: ['name'],
+        },
+        async execute(_id, rawParams) {
+            const params = rawParams;
+            const name = typeof params.name === 'string' ? params.name.trim() : '';
+            if (name.length === 0)
+                return errorResult('skill requires a "name" parameter.');
+            const record = deps.registry.get(name);
+            if (!record) {
+                const suggestions = suggestSkillNames(name, deps.registry.names());
+                const hint = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(', ')}?` : '';
+                return errorResult(`Unknown skill "${name}".${hint} Run /skills to list all.`);
+            }
+            if (record.disabled) {
+                return errorResult(`Skill "${name}" is disabled. Enable it with /skills enable ${name}.`);
+            }
+            if (record.invalid) {
+                const first = record.issues.find((i) => i.level === 'error');
+                return errorResult(`Skill "${name}" failed validation: ${first ? `${first.code} - ${first.message}` : 'unknown error'}.`);
+            }
+            // The single place where a host-side throw is converted into a diagnosable
+            // tool error. The engine would otherwise turn it into a generic stack trace.
+            let loaded;
+            try {
+                loaded = deps.loadBody(name);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return errorResult(`Could not read SKILL.md for "${name}": ${message}`);
+            }
+            // ── The order below is load-bearing; do not reorder (§7.2). ──────────
+            // 1. Hydrate.
+            record.body = loaded.body;
+            record.files = loaded.files;
+            // 2. Record the session-level load and learn whether it is a repeat.
+            const alreadyLoaded = deps.registry.activate(name);
+            // 3. Enter the frame BEFORE step 4 — this skill is one of the ceiling's
+            //    own sources, and a digest counts as a "I am using this" statement
+            //    just as much as a full load does, so the ceiling applies either way.
+            deps.registry.enterFrame(name);
+            // 4. Only now is a policy snapshot truthful.
+            const policy = deps.policySnapshot?.();
+            // 5. Repeat loads get the digest unless the model explicitly asks otherwise.
+            const force = params.force === true;
+            const mode = alreadyLoaded && !force ? 'digest' : 'full';
+            const args = typeof params.arguments === 'string' ? params.arguments : '';
+            // 6. Render.
+            return textResult(renderSkillBody(record, {
+                ...(deps.bodyMaxBytes !== undefined ? { bodyMaxBytes: deps.bodyMaxBytes } : {}),
+                ...(deps.resultMaxBytes !== undefined ? { resultMaxBytes: deps.resultMaxBytes } : {}),
+                // The legacy one-line hint belongs to the full re-send only; the digest
+                // states the same fact in its own opening line.
+                ...(mode === 'full' && alreadyLoaded ? { alreadyLoaded: true } : {}),
+                mode,
+                ...(policy ? { policy } : {}),
+                ...(deps.platform ? { platform: deps.platform } : {}),
+                ...(args.length > 0 ? { arguments: args } : {}),
+            }));
+        },
+    };
+}

package/dist/skills/tool-policy.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The turn-scoped tool ceiling (spec §5) — what turns `allowed-tools` from a
+ * decorative frontmatter field into an executable declaration.
+ *
+ * PURE FUNCTIONS ONLY. This module does not know which tools the host has; the
+ * caller passes `registered` and `floor` in (D-G7). Core owns the SKILL.md
+ * FORMAT — which includes knowing that `Read` is what Claude Code calls its
+ * read-a-file tool — while the CLI owns the inventory of what actually exists.
+ *
+ * THE DIRECTION OF FAILURE IS THE WHOLE DESIGN (D-G4). A declaration this host
+ * cannot fully resolve waives that skill's contribution ENTIRELY rather than
+ * narrowing it: honouring the half we understood would silently constrain an
+ * author to something they never wrote, and the reason (one mistyped tool name)
+ * would be invisible. Fail-open plus a loud notice is correct here; the
+ * fail-closed rule lives on the install gate, where the adversary is a person
+ * rather than a typo.
+ */
+import { TOOL_POLICY_DENY_ESCALATE_AT } from './constants.js';
+import type { ToolPolicyDecision, ToolPolicyInput, ToolPolicyVerdict } from './types.js';
+/** Lower-case and strip `_`, `-` and whitespace: `Read`→`read`, `read_file`→`readfile`. */
+export declare function normalizeToolAlias(name: string): string;
+/**
+ * Claude Code's vocabulary → this host's snake_case names.
+ *
+ * Keys are already normalized. This table is why `.claude/skills` interop — the
+ * README's headline feature — survives enforcement at all: without it every
+ * community declaration (`allowed-tools: [Read, Bash]`) would resolve to nothing
+ * and every such skill would take the fail-open path, making the whole ceiling
+ * ornamental (FG2 / RG2).
+ */
+export declare const SKILL_TOOL_ALIASES: Readonly<Record<string, string>>;
+/**
+ * Capabilities this host simply does not have. A declaration naming one is
+ * DROPPED, not treated as unresolvable (D-G5).
+ *
+ * If these counted as "cannot resolve", nearly every community skill would take
+ * the fail-open path and enforcement would be theatre. Dropping them changes no
+ * executable set — the model could never have called them — while leaving the
+ * rest of the declaration in force. That is precision, not a concession.
+ *
+ * THIS TABLE ONLY GROWS. Removing an entry pushes already-working skills into
+ * fail-open with no symptom whatsoever.
+ */
+export declare const SKILL_TOOL_KNOWN_ABSENT: ReadonlySet<string>;
+/**
+ * Resolve one declared name against the live tool list.
+ *
+ *   `string`   — a tool on this host.
+ *   `'absent'` — a real Claude Code tool this host lacks; drop it silently.
+ *   `null`     — unrecognisable; the whole skill then waives its contribution.
+ *
+ * THE ORDER OF THE FOUR STEPS IS THE SEMANTICS — do not reshuffle it. Exact
+ * match first means a host that adds a new tool needs no table maintenance. The
+ * alias table is consulted BEFORE the absent table so that mistakenly listing a
+ * tool this host actually has could never silently downgrade a skill.
+ */
+export declare function resolveDeclaredTool(name: string, registered: readonly string[]): string | 'absent' | null;
+/**
+ * Compute the ceiling for a turn.
+ *
+ * TWO INVARIANTS THIS FUNCTION OWNS (I-G1 / I-G2, pinned by AC-G23):
+ *
+ *   I-G1  `registered.length === 0` ⇒ `allowed === null`.
+ *   I-G2  `allowed !== null` ⇒ the set is NON-EMPTY.
+ *
+ * Both matter because the failure they exclude is catastrophic and silent: an
+ * empty permitted set is not "a tight ceiling", it is an agent that can no
+ * longer do anything, for a reason no user could ever guess. The construction
+ * makes them hold — every unresolved name waives its whole skill, and the final
+ * guard below refuses to hand back an empty set — rather than leaving them to be
+ * re-derived by whoever refactors this next.
+ */
+export declare function computeToolPolicy(input: ToolPolicyInput): ToolPolicyDecision;
+/**
+ * Decide a single call. Deterministic, allocation-light, and safe to run on
+ * every tool invocation — `allowed === null` short-circuits before any string
+ * work, which is the common case.
+ */
+export declare function evaluateToolCall(tool: string, d: ToolPolicyDecision): ToolPolicyVerdict;
+/**
+ * The line appended to a refusal once the same tool has been refused
+ * `TOOL_POLICY_DENY_ESCALATE_AT` times in one turn (§5.5).
+ *
+ * Appended to the SAME message rather than emitted as a new one: a second
+ * message would be one more thing for the model to skim past, whereas a longer
+ * version of the text it is already reading is unavoidable.
+ */
+export declare function renderDenyEscalation(tool: string, count: number): string;
+/** The matching one-liner for the user, emitted once per (turn, tool). */
+export declare function renderDenyEscalationNotice(skill: string, tool: string, count: number): string;
+export { TOOL_POLICY_DENY_ESCALATE_AT };