@aragon-agent/cli 0.4.3

package/dist/skills/service.d.ts

@@ -0,0 +1,256 @@
+/**
+ * SkillService — discovery, lazy loading, prompt-block assembly, and the
+ * lifecycle surface the UI and the agent tools call into (spec §12.2).
+ *
+ * Everything mutating (install / create / remove) delegates to `installer.ts`;
+ * this file owns the read side and the registry.
+ */
+import { SkillRegistry, type SkillFileRef, type SkillHost, type SkillPlatform, type SkillPolicyView, type SkillRecord, type SkillUsageMap, type ToolPolicyDecision, type ToolPolicyVerdict } from '@aragon-agent/core';
+import type { NoticeLevel } from '../agent/reducer.js';
+import type { SkillsConfig, SkillsRuntimeOptions, SkillsToolPolicyMode } from '../config/schema.js';
+import { type ConfirmRequest } from '../tools/index.js';
+/**
+ * Capability-probing approval gate (D17 / §8.3.1).
+ *
+ * NOT `confirm?: (req) => Promise<boolean>`. That shape cannot express "there is
+ * no human here", and the CLI's existing confirm callback resolves `true` when
+ * unattached (`cli.tsx`'s `confirmBridge.handler ? … : Promise.resolve(true)`).
+ * Inheriting that fallback would make `requireApproval: true` a no-op under
+ * `-p`, where the App never mounts and the handler is permanently null.
+ * Probing FIRST makes fail-closed the default path rather than a discipline.
+ */
+export interface ApprovalGate {
+    /** Is there a human channel RIGHT NOW? Must be read live, never cached (Q7). */
+    canPrompt(): boolean;
+    /** Only called when `canPrompt()` returned true. */
+    request(req: ConfirmRequest): Promise<boolean>;
+}
+export interface DiscoverResult {
+    records: SkillRecord[];
+    errors: string[];
+    /** Project roots skipped because the directory is not trusted yet (D13). */
+    pendingTrust: string[];
+}
+export interface SkillServiceDeps {
+    host: SkillHost;
+    getCwd: () => string;
+    config: SkillsConfig;
+    runtime: SkillsRuntimeOptions;
+    approval: ApprovalGate;
+    /** → `controller.refreshSkills()`. */
+    onChange?: () => void;
+    notify?: (level: NoticeLevel, text: string) => void;
+    /** Persist a skills patch. MUST deep-merge (§10.3.2). */
+    persist?: (patch: Partial<SkillsConfig>) => void;
+}
+export declare class SkillService {
+    private readonly deps;
+    private readonly registry;
+    private config;
+    private lastErrors;
+    private pendingTrust;
+    /** Empty when `skills.usageTracking` is off — which is exactly invariant I-A1. */
+    private usage;
+    /** The integrity warning is worth saying once a session, not once a rescan. */
+    private integrityWarned;
+    /**
+     * `/skills policy <mode>` writes here. `null` = this session has no opinion.
+     * NEVER persisted — the config file is written separately by the same command.
+     */
+    private sessionToolPolicy;
+    /**
+     * The previous decision, used to notice when the ceiling WIDENS (§5.6e).
+     *
+     * A skill can tell the model to load a second skill, and because the ceiling
+     * is a union with `skill` permanently in the floor, that works (D-G17). The
+     * path is not blocked — every way of blocking it costs more than it saves —
+     * so instead it leaves a trace. This pair of fields is that trace's memory.
+     */
+    private lastDecisionAllowed;
+    private lastDecisionSources;
+    constructor(deps: SkillServiceDeps);
+    /**
+     * Scan all four roots in ascending precedence and rebuild the registry.
+     *
+     * One unreadable directory must never sink the whole pass: every root and
+     * every candidate is wrapped, and partial results are returned alongside the
+     * errors so `/skills` can show both what loaded and what did not.
+     */
+    discover(): DiscoverResult;
+    /**
+     * Enforce the usage-file cap (§9.2) — and ONLY when it is actually exceeded.
+     *
+     * `pruneUsage()` drops every counter whose skill is absent from the registry,
+     * and the registry is CWD-DEPENDENT: it holds the `project` skills of
+     * whichever directory this process happens to be running in. Calling it on
+     * every scan would therefore make a session in repo B silently erase the
+     * usage history of repo A — and a root that was momentarily unreadable would
+     * erase all of it. Counters for uninstalled skills are worth a few hundred
+     * bytes; the ranking signal they would take with them is not.
+     */
+    private pruneUsageIfOverCap;
+    /**
+     * Tell the user once per session which skills no longer match what they
+     * approved (`warn` mode only — `strict` already refuses them outright, and
+     * repeating the notice on every rescan is how a warning becomes wallpaper).
+     */
+    private reportIntegrity;
+    /** Scan one root. Returns the records it yielded; appends to `errors` in place. */
+    private scanRoot;
+    /** Build a record from a candidate directory, or `null` when it is not a skill. */
+    private readSkillDir;
+    /**
+     * Compare SKILL.md against the hash recorded at install time (§8.1).
+     *
+     * Costs no extra read on the happy path: the text is already in memory from
+     * the scan, and the manifest was already parsed.
+     *
+     * D-A12 — THE SECOND HASH IS NOT REDUNDANT. `readTextFile()` returns a
+     * DECODED string. Re-encoding it round-trips byte-for-byte only for
+     * well-formed UTF-8; a file containing an invalid sequence comes back with
+     * U+FFFD substituted, so the re-encoded bytes differ from what is on disk and
+     * an untouched file would be reported as tampered. A false alarm here is
+     * worse than no alarm at all — it teaches the user that this warning is noise,
+     * and it is the same warning that has to be believed on the day it is real.
+     */
+    private computeIntegrity;
+    /** Reload from disk and notify the controller so the prompt is rebuilt. */
+    reload(): DiscoverResult;
+    list(): SkillRecord[];
+    get(name: string): SkillRecord | undefined;
+    getRegistry(): SkillRegistry;
+    errors(): string[];
+    /** Project roots the trust gate is still holding back (§9.3). */
+    untrustedDirs(): string[];
+    /**
+     * Level 2 load: SKILL.md body + the bundled-file listing.
+     * MAY THROW — see the `SkillHost` error contract; `skill`'s `execute()` and
+     * every UI caller wrap this.
+     *
+     * THE SINGLE USAGE MEASUREMENT POINT (F8). All three consumption paths — the
+     * `skill` tool, a `/<skill-name>` command, and `alwaysBlock()` — funnel
+     * through here, so one call site covers everything.
+     *
+     * `countUse: false` is MANDATORY for `alwaysBlock()`. An always-on skill is
+     * injected automatically on every single turn; counting that would pin it to
+     * the top of the ranking forever and drown out the signal the ranking exists
+     * to capture, which is what a human or a model actually CHOSE to reach for.
+     */
+    loadBody(name: string, opts?: {
+        countUse?: boolean;
+    }): {
+        body: string;
+        files: SkillFileRef[];
+    };
+    /** Walk a skill directory for bundled resources (depth ≤ 3, dotfiles skipped). */
+    private listSkillFiles;
+    /** Level 1 catalog for the system prompt, or `''` when there is nothing to say. */
+    catalogBlock(): string;
+    /**
+     * `activation: always` bodies plus anything forced with `--skill`.
+     * Returns `''` when empty so the caller can concatenate unconditionally
+     * without disturbing invariant I-S1.
+     */
+    alwaysBlock(): string;
+    /** Host shell family, forwarded into every Level 2 / Level 3 render (D-G14). */
+    platform(): SkillPlatform;
+    /**
+     * The mode actually in force, and where it came from.
+     *
+     * THREE LAYERS, not two (D-G19). `SkillsRuntimeOptions` is read-only for the
+     * life of the session, so with only `flag > config` a user who started with
+     * `--skill-tool-policy enforce` could run the very command the refusal text
+     * recommends — `/skills policy off` — and have precisely nothing happen, with
+     * no message either. An iteration about silent failures cannot ship one in its
+     * own escape hatch.
+     */
+    effectiveToolPolicy(): {
+        mode: SkillsToolPolicyMode;
+        from: 'session' | 'flag' | 'config';
+    };
+    setSessionToolPolicy(mode: SkillsToolPolicyMode): void;
+    /** `/skills policy <mode>` — session slot and config file, together. */
+    persistToolPolicy(mode: SkillsToolPolicyMode): void;
+    /**
+     * Compute the ceiling for right now. Constant-time when the frame is empty or
+     * the mode is `off`, which is the overwhelmingly common case on the hot path.
+     */
+    toolPolicyDecision(getRegistered: () => readonly string[]): ToolPolicyDecision;
+    /** The renderer-facing slice of the current decision, or `undefined` for "say nothing". */
+    toolPolicyView(getRegistered: () => readonly string[]): SkillPolicyView | undefined;
+    /**
+     * The ceiling a QUEUED skill is about to impose — for the `/<skill-name>` path,
+     * whose message has not been submitted yet and whose frame is therefore still
+     * pending (§13.2).
+     *
+     * Computed from the pending set alone, which is exactly right for the common
+     * case (`controller.prompt()` replaces the frame with the pending one). When
+     * the agent happens to be running, `steer()` unions instead, so this can
+     * understate — it will never claim a tool is forbidden that is in fact allowed
+     * only because some other skill is also in the frame. Overstating would be the
+     * dangerous direction; a refusal, if one ever happens, prints the true set.
+     *
+     * Emits no announcements: nothing has been decided yet.
+     */
+    pendingToolPolicyView(getRegistered: () => readonly string[]): SkillPolicyView | undefined;
+    /**
+     * One notice per skill per session when a frame member stops constraining
+     * because it was uninstalled, disabled, or turned invalid (D-G20 / AC-G21).
+     *
+     * Without this, `/skills disable`, a `/skills reload` after an uninstall, and a
+     * flip to `integrity: strict` each end with the ceiling gone and nothing said
+     * — a silent lift, which is the same failure class as the silent no-op this
+     * whole iteration set out to remove.
+     */
+    private reportCeilingLifted;
+    /** One notice per skill per session when D-G4 waives it (§5.7 / RG3). */
+    private reportFailOpen;
+    /** Print the union-escalation trace (§5.6e / D-G17) and remember the new state. */
+    private reportCeilingWidened;
+    /**
+     * The single place the three announce-once rules live (§5.4c / P1-2).
+     *
+     * `verdict.message` is MUTATED in the escalate branch rather than being
+     * followed by a second message: the model is already reading this text, and a
+     * separate message is one more thing for it to skip.
+     */
+    reportToolPolicyEvent(e: {
+        tool: string;
+        verdict: ToolPolicyVerdict;
+        sourceNames: string[];
+    }): void;
+    beginUserTurn(): void;
+    absorbPendingFrames(): void;
+    queueFrame(name: string): void;
+    clearFrames(): void;
+    frameNames(): string[];
+    /** Level 2 body budget — shared by the tool path and the slash path (GG3). */
+    bodyMaxBytes(): number;
+    /** Warn once about `--skill <name>` values that match nothing (§7.5). */
+    reportUnknownForcedSkills(): void;
+    setDisabled(name: string, disabled: boolean): void;
+    getConfig(): SkillsConfig;
+    /** Local use counters backing `--sort=recent`; empty when tracking is off. */
+    getUsage(): SkillUsageMap;
+    /** Working directory an install should resolve `--scope project` against. */
+    getCwdForInstall(): string;
+    getRuntime(): SkillsRuntimeOptions;
+    getApproval(): ApprovalGate;
+    notify(level: NoticeLevel, text: string): void;
+    /** Keep the in-memory copy and the config file in step (deep-merged, §10.3.2). */
+    private updateConfig;
+    isTrusted(dir: string): boolean;
+    trustDir(dir: string): boolean;
+    untrustDir(dir: string): boolean;
+    /**
+     * Load a project root for THIS SESSION ONLY, without persisting trust.
+     * Used when the user answers the confirm dialog with "just this once".
+     */
+    trustForSession(dir: string): void;
+    /**
+     * Drop staging directories left behind by a crashed install (P2-10).
+     * Same discipline as the host repo's workspace cleanup: age-based, best
+     * effort, and never allowed to interrupt discovery.
+     */
+    private reclaimStaleStaging;
+}