@aragon-agent/core 0.1.3

package/dist/skills/tool-policy.js

@@ -0,0 +1,272 @@
+/**
+ * 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';
+// ---------------------------------------------------------------------------
+// Name resolution (§5.3)
+// ---------------------------------------------------------------------------
+/** Lower-case and strip `_`, `-` and whitespace: `Read`→`read`, `read_file`→`readfile`. */
+export function normalizeToolAlias(name) {
+    return name.toLowerCase().replace(/[_\-\s]/g, '');
+}
+/**
+ * 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 const SKILL_TOOL_ALIASES = Object.freeze({
+    read: 'read_file',
+    readfile: 'read_file',
+    view: 'read_file',
+    cat: 'read_file',
+    write: 'write_file',
+    writefile: 'write_file',
+    create: 'write_file',
+    edit: 'edit_file',
+    editfile: 'edit_file',
+    multiedit: 'edit_file',
+    strreplaceeditor: 'edit_file',
+    strreplacebasededitor: 'edit_file',
+    bash: 'bash',
+    shell: 'bash',
+    sh: 'bash',
+    runcommand: 'bash',
+    terminal: 'bash',
+    ls: 'list_dir',
+    listdir: 'list_dir',
+    listdirectory: 'list_dir',
+    glob: 'glob',
+    findfiles: 'glob',
+    grep: 'grep',
+    search: 'grep',
+    ripgrep: 'grep',
+    skill: 'skill',
+    skillfind: 'skill_find',
+    skillinstall: 'skill_install',
+    skillcreate: 'skill_create',
+});
+/**
+ * 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 const SKILL_TOOL_KNOWN_ABSENT = new Set([
+    'webfetch',
+    'websearch',
+    'task',
+    'agent',
+    'todowrite',
+    'todoread',
+    'notebookedit',
+    'notebookread',
+    'bashoutput',
+    'killshell',
+    'slashcommand',
+    'exitplanmode',
+    'askuserquestion',
+    'computer',
+]);
+/**
+ * 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 function resolveDeclaredTool(name, registered) {
+    const trimmed = name.trim();
+    if (trimmed.length === 0)
+        return null;
+    // 1. Exact match against what is registered right now.
+    if (registered.includes(trimmed))
+        return trimmed;
+    const key = normalizeToolAlias(trimmed);
+    // 2. Known alias. Resolving to a tool this host does NOT have is a miss, not a
+    //    drop: the author asked for a capability we cannot grant, and pretending
+    //    otherwise would narrow their declaration behind their back.
+    const candidate = SKILL_TOOL_ALIASES[key];
+    if (candidate !== undefined)
+        return registered.includes(candidate) ? candidate : null;
+    // 3. A real tool elsewhere that does not exist here.
+    if (SKILL_TOOL_KNOWN_ABSENT.has(key))
+        return 'absent';
+    // 4. Anything else — a typo, or a tool nobody here has heard of.
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Decision (§5.2)
+// ---------------------------------------------------------------------------
+function noCeiling(mode, ignored = []) {
+    return { mode, allowed: null, sources: [], sourceNames: [], ignored };
+}
+function contributes(record) {
+    if (record.disabled || record.invalid)
+        return false;
+    // Redundant with the frame's own gate, and deliberately so (D-G9): an
+    // `activation: always` skill is ambient reference material, not a procedure
+    // the model chose to run, so it must never constrain a turn.
+    if (record.frontmatter.activation === 'always')
+        return false;
+    return record.frontmatter.allowedTools.length > 0;
+}
+/**
+ * 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 function computeToolPolicy(input) {
+    const { mode, registered, floor } = input;
+    if (mode === 'off')
+        return noCeiling(mode);
+    const sources = [];
+    const ignored = [];
+    const granted = new Set();
+    for (const record of input.frame) {
+        if (!contributes(record))
+            continue;
+        const declared = record.frontmatter.allowedTools;
+        const resolved = [];
+        const unresolved = [];
+        for (const declaredName of declared) {
+            const outcome = resolveDeclaredTool(declaredName, registered);
+            if (outcome === null)
+                unresolved.push(declaredName);
+            else if (outcome !== 'absent')
+                resolved.push(outcome);
+        }
+        if (unresolved.length > 0) {
+            ignored.push({ name: record.name, unresolved });
+            continue;
+        }
+        for (const toolName of resolved)
+            granted.add(toolName);
+        sources.push({
+            name: record.name,
+            declared: [...declared],
+            granted: [...new Set(resolved)].sort((a, b) => a.localeCompare(b, 'en')),
+        });
+    }
+    if (sources.length === 0)
+        return noCeiling(mode, ignored);
+    sources.sort((a, b) => a.name.localeCompare(b.name, 'en'));
+    const allowed = new Set([...floor, ...granted]);
+    // I-G2's structural guard. Reachable only when the floor is empty AND every
+    // declaration resolved to `absent` — pathological, but the consequence would
+    // be a fully locked agent, so it is checked rather than argued about.
+    if (allowed.size === 0)
+        return noCeiling(mode, ignored);
+    return { mode, allowed, sources, sourceNames: sources.map((s) => s.name), ignored };
+}
+// ---------------------------------------------------------------------------
+// Verdict (§5.2)
+// ---------------------------------------------------------------------------
+function sorted(values) {
+    return [...values].sort((a, b) => a.localeCompare(b, 'en'));
+}
+/**
+ * How to name the skills responsible, for both the model and the user.
+ *
+ * Multi-source turns list EVERY name. Picking one would be wrong in some
+ * arrangement of skills every time, and a confidently wrong attribution is worse
+ * than a slightly longer sentence.
+ */
+function describeSources(names) {
+    if (names.length === 1)
+        return `skill "${names[0]}"`;
+    return `skills ${names.map((n) => `"${n}"`).join(', ')}`;
+}
+/** The union of what the frame's skills actually asked for, floor excluded. */
+function grantedUnion(decision) {
+    return sorted(new Set(decision.sources.flatMap((s) => s.granted)));
+}
+/**
+ * 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 function evaluateToolCall(tool, d) {
+    if (d.allowed === null || d.allowed.has(tool))
+        return { allow: true };
+    const subject = describeSources(d.sourceNames);
+    const declaredList = grantedUnion(d).join(', ');
+    if (d.mode === 'warn') {
+        return {
+            allow: true,
+            notice: `${tool} is outside the tool ceiling of ${subject} (declared: ${declaredList}). ` +
+                'Running it anyway - skills.toolPolicy is "warn".',
+        };
+    }
+    const message = [
+        `Tool "${tool}" is not permitted while ${subject} is in effect.`,
+        // The RAW declaration, not the mapped names: the author has to be able to
+        // find this word in the frontmatter line they wrote.
+        ...d.sources.map((s) => `- "${s.name}" declares allowed-tools: ${s.declared.join(', ')}`),
+        `Permitted right now: ${sorted(d.allowed).join(', ')}.`,
+        `Use one of those, or tell the user "${tool}" must be added to allowed-tools.`,
+        'Do not retry this tool for the rest of this turn.',
+    ].join('\n');
+    return {
+        allow: false,
+        message,
+        notice: `Blocked ${tool}: ${subject} limits this turn to ${declaredList}. ` +
+            'Run /skills policy off to disable.',
+    };
+}
+/**
+ * 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 function renderDenyEscalation(tool, count) {
+    return (`You have now been refused "${tool}" ${count} times this turn. Stop calling it; ` +
+        "tell the user which tool the skill's allowed-tools is missing.");
+}
+/** The matching one-liner for the user, emitted once per (turn, tool). */
+export function renderDenyEscalationNotice(skill, tool, count) {
+    return (`Skill "${skill}" blocked ${tool} ${count}x this turn - the skill's allowed-tools ` +
+        'may be wrong (/skills policy off to bypass).');
+}
+export { TOOL_POLICY_DENY_ESCALATE_AT };

package/dist/skills/types.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Skill data model (spec §10.1).
+ *
+ * Pure types + one injected port. This module must stay free of `node:*` — the
+ * host filesystem is reached only through `SkillHost`, which the CLI implements
+ * (D1). `no-host-coupling.test.ts` enforces that red line mechanically.
+ */
+export type SkillScope = 'bundled' | 'user' | 'project' | 'env';
+export type SkillActivation = 'auto' | 'always' | 'manual';
+export interface SkillFrontmatter {
+    name: string;
+    description: string;
+    version: string;
+    license?: string;
+    author?: string;
+    homepage?: string;
+    keywords: string[];
+    allowedTools: string[];
+    activation: SkillActivation;
+    /** Every parsed key, including unknown ones (forward compat). */
+    raw: Record<string, string | string[]>;
+}
+export interface SkillFileRef {
+    /** Path relative to the skill directory, always with `/` separators. */
+    path: string;
+    bytes: number;
+}
+export interface SkillValidationIssue {
+    level: 'error' | 'warn';
+    code: string;
+    message: string;
+}
+export interface SkillManifestFile {
+    path: string;
+    bytes: number;
+    sha256: string;
+}
+export interface SkillManifestSource {
+    kind: 'local-dir' | 'local-file' | 'git' | 'https-md' | 'https-zip' | 'inline';
+    url: string;
+    ref: string | null;
+    subdir: string | null;
+    /**
+     * The commit sha a git source resolved to at install time; `null` for every
+     * other kind and whenever `git rev-parse` did not answer.
+     *
+     * OPTIONAL ON PURPOSE (F10): `readManifest()` returns `null` for any
+     * `schema !== 1`, so bumping the schema would demote every already-installed
+     * skill to "no provenance" the moment an older CLI read it. New fields are
+     * therefore always additive and always optional.
+     */
+    resolvedRef?: string | null;
+}
+export interface SkillManifest {
+    schema: number;
+    name: string;
+    version: string;
+    installedAt: number;
+    installer: string;
+    source: SkillManifestSource;
+    files: SkillManifestFile[];
+    totalBytes: number;
+    /** Set by `skills update`; absent for a skill that was never updated. */
+    updatedAt?: number;
+    /** The version this skill carried before the last update. */
+    previousVersion?: string;
+}
+/**
+ * How a skill's `SKILL.md` compares to what the install manifest recorded (§8).
+ *
+ *   `unverified` — no manifest, or the check is switched off. Hand-authored,
+ *                  bundled and `.claude/skills` skills live here permanently.
+ *   `ok`         — byte-identical to the approved copy.
+ *   `modified`   — the file on disk is not the one that was approved.
+ */
+export type SkillIntegrity = 'unverified' | 'ok' | 'modified';
+export interface SkillUsageStat {
+    useCount: number;
+    /** epoch ms; `0` means never used. */
+    lastUsedAt: number;
+}
+/** Skill name → usage counters. Local-only; see `usage.ts`. */
+export type SkillUsageMap = Record<string, SkillUsageStat>;
+export interface SkillRecord {
+    name: string;
+    description: string;
+    scope: SkillScope;
+    /** Absolute skill directory. */
+    dir: string;
+    /** Absolute path to SKILL.md. */
+    entryPath: string;
+    frontmatter: SkillFrontmatter;
+    /** Lazily filled at Level 2. */
+    body: string | null;
+    /** Lazily filled at Level 2. */
+    files: SkillFileRef[] | null;
+    /** Size of SKILL.md in bytes. */
+    bytes: number;
+    disabled: boolean;
+    issues: SkillValidationIssue[];
+    invalid: boolean;
+    /** Same-name records from lower-precedence roots. */
+    shadowed: Array<{
+        scope: SkillScope;
+        dir: string;
+    }>;
+    /** Parsed .aragon-skill.json when present. */
+    manifest: SkillManifest | null;
+    /** False for `bundled`, `env`, and `.claude/skills` roots. */
+    writable: boolean;
+    /** SKILL.md vs. the manifest, computed during discovery at no extra I/O (§8.1). */
+    integrity: SkillIntegrity;
+}
+/**
+ * The injected filesystem port — keeps core free of `node:*`.
+ *
+ * ERROR CONTRACT (P2-8): every method here MAY THROW (the Node implementation
+ * wraps sync fs calls: ENOENT / EACCES / EISDIR / ELOOP all surface as
+ * exceptions). Core callers are responsible for try/catch; "never throws" is an
+ * obligation of a tool's `execute()` (§5.2), never of this port.
+ */
+export interface SkillHost {
+    readTextFile(path: string): string;
+    listDir(path: string): Array<{
+        name: string;
+        isDirectory: boolean;
+        bytes: number;
+    }>;
+    exists(path: string): boolean;
+    join(...parts: string[]): string;
+    relative(from: string, to: string): string;
+    isAbsolute(p: string): boolean;
+}
+export interface SkillCatalogOptions {
+    /** UTF-8 byte ceiling for the whole block. */
+    maxBytes?: number;
+    /** Character cap for a single entry's description. */
+    descLineMax?: number;
+    /** Append the `Skill tools: …` footer line. Default true. */
+    includeToolLine?: boolean;
+    /**
+     * Usage counters used to rank entries within a scope (§5.2). Omitting this
+     * reproduces the pre-ranking order byte for byte (invariant I-A1).
+     */
+    usage?: SkillUsageMap;
+    /** Injected clock for the recency buckets; defaults to `Date.now()`. */
+    now?: number;
+}
+export interface SkillFindOptions {
+    /** Total number of installed skills searched, for the `of="N"` attribute. */
+    total?: number;
+    /**
+     * How many skills matched BEFORE the caller applied its own `limit`. Defaults
+     * to `matched.length`. Pass it whenever the array handed in has already been
+     * sliced, so the `matched="N"` attribute stays truthful and the overflow line
+     * still appears — a silently shortened result list is the same failure this
+     * whole tool exists to undo.
+     */
+    matchedTotal?: number;
+    /** UTF-8 byte ceiling for the whole result block. */
+    maxBytes?: number;
+    /** Character cap for a single entry's description. */
+    descLineMax?: number;
+    /** Near-miss names offered when nothing matched. */
+    suggestions?: string[];
+}
+export type SkillToolPolicyMode = 'off' | 'warn' | 'enforce';
+/**
+ * The host's shell family. Injected by the CLI (D-G14) — core never reads
+ * `process`, because that would make the renderers untestable across platforms:
+ * a snapshot taken on Windows could never cover the POSIX branch.
+ */
+export type SkillPlatform = 'win32' | 'posix';
+/**
+ * One skill's COMPLETE contribution to the ceiling.
+ *
+ * Not a bare name (evaluated P0-1): the refusal text has to say what THAT skill
+ * declared, and a union `allowed` set — which also carries the floor — cannot be
+ * reverse-engineered back into per-skill declarations.
+ */
+export interface ToolPolicySource {
+    name: string;
+    /** The raw declaration, verbatim and unmapped, so an author can grep for it. */
+    declared: string[];
+    /** Declared names that resolved to a tool on this host (ascending, deduped). */
+    granted: string[];
+}
+export interface ToolPolicyInput {
+    /** Skill records in the current turn's frame (order irrelevant). */
+    frame: SkillRecord[];
+    /** Tool names actually registered in this session (host-supplied). */
+    registered: readonly string[];
+    /** Always-permitted tools (host-supplied; D-G6 / D-G7). */
+    floor: readonly string[];
+    mode: SkillToolPolicyMode;
+}
+export interface ToolPolicyDecision {
+    mode: SkillToolPolicyMode;
+    /** `null` = no ceiling at all. Non-null is the permitted set. NEVER empty (I-G2). */
+    allowed: ReadonlySet<string> | null;
+    /** Skills that contributed, ascending by `name`. */
+    sources: ToolPolicySource[];
+    /** Convenience mirror of `sources.map(s => s.name)` for display / events. */
+    sourceNames: string[];
+    /** Skills waived wholesale by D-G4, with the names that could not be resolved. */
+    ignored: Array<{
+        name: string;
+        unresolved: string[];
+    }>;
+}
+export interface ToolPolicyVerdict {
+    allow: boolean;
+    /**
+     * Present only when `allow === false`: the actionable explanation the MODEL
+     * reads. Mutable on purpose — `SkillService` appends the escalation line to it
+     * on the Nth refusal rather than emitting a second message (§5.5).
+     */
+    message?: string;
+    /** Present whenever the user should hear about it: one line for the transcript. */
+    notice?: string;
+}
+/** The slice of a decision the renderers need. Kept flat so it can be snapshotted. */
+export interface SkillPolicyView {
+    mode: SkillToolPolicyMode;
+    /** The full permitted set, ascending. */
+    allowed: string[];
+}
+export interface SkillBodyOptions {
+    bodyMaxBytes?: number;
+    /** Hard ceiling on the whole rendered string. */
+    resultMaxBytes?: number;
+    filesMax?: number;
+    alreadyLoaded?: boolean;
+    arguments?: string;
+    /** `'digest'` omits the body and points at the earlier copy (§7.2). */
+    mode?: 'full' | 'digest';
+    /**
+     * Drives the one-line tool-ceiling statement.
+     *
+     * OMITTING IT MEANS "SAY NOTHING" — and that is the default for a reason
+     * (P0-2 / D-G18). `activation: always` and `--skill` skills are exempt from the
+     * ceiling, so telling the model every single turn that "only these tools are
+     * permitted" would impose a restriction that does not exist, invisibly.
+     */
+    policy?: SkillPolicyView;
+    platform?: SkillPlatform;
+}
+/** Options for the `/<skill-name>` invocation message (§6). */
+export interface SkillInvocationOptions {
+    bodyMaxBytes?: number;
+    /** Defaults to `SKILL_INVOCATION_MAX_BYTES`. */
+    resultMaxBytes?: number;
+    filesMax?: number;
+    platform?: SkillPlatform;
+    policy?: SkillPolicyView;
+}
+/** A staged (not yet installed) file, as seen by `validateStagedSkill`. */
+export interface StagedFile {
+    /** Path relative to the staging root, `/`-separated. */
+    path: string;
+    bytes: number;
+    /** True for symlinks and any non-regular entry. */
+    isSymlink?: boolean;
+}
+export interface StagedValidationResult {
+    ok: boolean;
+    issues: SkillValidationIssue[];
+    frontmatter: SkillFrontmatter | null;
+    fileCount: number;
+    totalBytes: number;
+}

package/dist/skills/types.js

@@ -0,0 +1,8 @@
+/**
+ * Skill data model (spec §10.1).
+ *
+ * Pure types + one injected port. This module must stay free of `node:*` — the
+ * host filesystem is reached only through `SkillHost`, which the CLI implements
+ * (D1). `no-host-coupling.test.ts` enforces that red line mechanically.
+ */
+export {};

package/dist/skills/validate.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Skill validation — frontmatter contract (§4.4) and staged-install safety (§8.3).
+ *
+ * Pure functions only: no filesystem, no process. The staged validator takes a
+ * pre-listed file table so the same rules run identically over a real staging
+ * directory (CLI) and over a fixture (tests).
+ */
+import type { SkillFrontmatter, SkillValidationIssue, StagedFile, StagedValidationResult } from './types.js';
+/** True when `s` holds a C0/DEL control character. */
+export declare function hasControlChar(s: string): boolean;
+/**
+ * Validate a parsed frontmatter map against the §4.2 contract.
+ *
+ * Error codes are a stable public surface — the UI and the tests both key off
+ * them, so renaming one is a breaking change.
+ */
+export declare function validateSkillFrontmatter(data: Record<string, string | string[]>, dirName: string): SkillValidationIssue[];
+/** Build the normalized frontmatter view, applying every documented default. */
+export declare function normalizeFrontmatter(data: Record<string, string | string[]>, fallbackName: string): SkillFrontmatter;
+/**
+ * Reject a relative path that could escape the staging root or is unusable on
+ * Windows. This is the SECOND line of defence — the archive extractor applies
+ * the same rules while writing (§9.2.1). Both are required: the extractor
+ * guards what lands on disk, this guards what we then promote into the skills
+ * root (a plain local-directory source never goes through the extractor).
+ */
+export declare function checkStagedPath(path: string): SkillValidationIssue | null;
+/**
+ * Validate a staged skill before it is promoted into a skills root.
+ *
+ * `entryText` is the raw SKILL.md; `files` is the full staged file table
+ * (SKILL.md included). Returns `ok: false` if ANY error-level issue is found —
+ * the installer must then abort and leave the target untouched.
+ */
+export declare function validateStagedSkill(entryText: string | null, files: StagedFile[], dirName: string, parse: (source: string) => {
+    data: Record<string, string | string[]>;
+} | null): StagedValidationResult;