@daweifu/capability-menu 0.1.1 → 0.1.3

package/lib/registry.js

@@ -6,11 +6,24 @@
 import z from '@deepseek-ai/schemastery';
 import { isModelInvocable } from '@deepseek-ai/dsh-skill';
 import yaml from 'js-yaml';
-import { readFile, readdir, stat } from 'node:fs/promises';
-import { dirname, resolve, sep } from 'node:path';
-/** Stable identifier prefixes: MCP tools keep `mcp__...`, skills use `skill:<name>`. */
-export const SKILL_ID_PREFIX = 'skill:';
-export const MCP_ID_PREFIX = 'mcp__';
+import { readFile, readdir, realpath, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve, sep } from 'node:path';
+import { BUILT_IN_SERVER, MCP_ID_PREFIX } from "./constants.js";
+// Re-exported for the package's public surface (`/registry` subpath).
+export { BUILT_IN_SERVER, MCP_ID_PREFIX };
+/**
+ * Tool names that never enter the capability catalog: this plugin's own
+ * control plane (`meta_search`/`meta_invoke`, always Resident) and the
+ * reserved Code Mode presentation transport (`run_code`).
+ *
+ * Tool ids (the key everything else uses) are the REAL registered tool name:
+ * MCP tools are registered as `mcp__<server>__<raw>` by the harness MCP client
+ * and natives keep their bare name (`bash`/`read`/…). Skills have no
+ * name-level namespace: a skill's id IS its bare name and `kind` disambiguates
+ * it from a same-named tool.
+ */
+export const CATALOG_EXCLUDED_TOOLS = new Set(['meta_search', 'meta_invoke', 'run_code']);
 /** Validate and default the registry configuration. */
 export const Config = z.object({
     summaryMaxChars: z.number().default(160),
@@ -19,7 +32,8 @@ export const Config = z.object({
     weighting: z.number().default(0.1),
     // schemastery object properties are optional-by-default: a missing key or
     // undefined value is accepted (no `meta.required`), so no `.optional()` needed.
-    progressiveSkillCatalog: z.string(),
+    catalogFile: z.string(),
+    refreshDebounceMs: z.number().default(200),
 });
 function assertPositiveInteger(name, value, min) {
     if (!Number.isInteger(value) || value < min) {
@@ -31,6 +45,26 @@ function assertWeight(name, value) {
         throw new Error(`${name} must be a number in [0, 1]`);
     }
 }
+/** True when `target` is `root` itself or sits below it. */
+function isUnder(root, target) {
+    return target === root || target.startsWith(`${root}${sep}`);
+}
+/**
+ * Containment check for skill-directory access: `target` must stay inside
+ * `root`, both lexically (`resolve` already collapsed `..`) and physically —
+ * a symlink inside the skill directory must not lead out of it. Paths that do
+ * not exist yet cannot be resolved physically; those stay governed by the
+ * lexical check and the caller's own stat/read failure handling.
+ */
+async function isInside(root, target) {
+    if (!isUnder(root, target))
+        return false;
+    const realRoot = await realpath(root).catch(() => undefined);
+    const realTarget = await realpath(target).catch(() => undefined);
+    if (realRoot === undefined || realTarget === undefined)
+        return true;
+    return isUnder(realRoot, realTarget);
+}
 /** Trim a description to a model-friendly summary. */
 function toSummary(description, maxChars) {
     const collapsed = description.replace(/\s+/g, ' ').trim();
@@ -72,24 +106,46 @@ export function apply(ctx, config = {}) {
     const detailIncludesBody = config.detailIncludesBody ?? false;
     const maxResults = config.maxResults ?? 20;
     const weighting = config.weighting ?? 0.1;
+    const catalogFile = (config.catalogFile ?? join(homedir(), '.dsh', 'capability-catalog.yaml')).trim();
+    const refreshDebounceMs = config.refreshDebounceMs ?? 200;
     assertPositiveInteger('summaryMaxChars', summaryMaxChars, 20);
     assertPositiveInteger('maxResults', maxResults, 1);
+    assertPositiveInteger('refreshDebounceMs', refreshDebounceMs, 0);
     assertWeight('weighting', weighting);
-    /** MCP tool records keyed by tool name; skills keyed by `skill:<name>`. */
+    /** Tool records keyed by tool name (MCP tools plus native tools under `built-in`); skills keyed by bare skill name. */
     let toolRecords = new Map();
     let skillRecords = new Map();
     /** The scope each indexed skill was collected from; undefined = global layer. */
     let skillScopes = new Map();
+    /** On-demand count of the latest catalog emission (0 until first write). */
+    let onDemandCount = 0;
+    /** Last emitted catalog text, so an unchanged rebuild skips the write. */
+    let lastCatalogContent;
     const statsOf = (record) => record.stats;
+    /**
+     * Kind-aware record lookup. With `kind` only that table is consulted; without
+     * it a name present in BOTH tables is ambiguous and resolves to undefined
+     * (never silently pick one kind over the other).
+     */
+    const resolveRecord = (key, kind) => {
+        if (kind === 'tool')
+            return toolRecords.get(key);
+        if (kind === 'skill')
+            return skillRecords.get(key);
+        const tool = toolRecords.get(key);
+        const skill = skillRecords.get(key);
+        if (tool !== undefined && skill !== undefined)
+            return undefined;
+        return tool ?? skill;
+    };
     /**
      * Resolve a skill's root directory from the live skill registry. The
      * directory comes from the skill provider's own locator (`resourceBase` for
-     * bundle skills, the SKILL.md parent for flat files) or the indexed origin
-     * path for progressive-catalog entries — never from caller input.
+     * bundle skills, the SKILL.md parent for flat files) — never from caller input.
      */
     const skillRootOf = async (id) => {
-        const name = skillNameOf(id);
-        const scope = skillScopes.get(id);
+        const name = id;
+        const scope = skillScopes.get(name);
         const lookup = scope === undefined ? {} : { scope };
         const definition = await ctx.skills.get(name, lookup).catch(() => undefined);
         if (definition !== undefined) {
@@ -99,85 +155,84 @@ export function apply(ctx, config = {}) {
             if (definition.path !== undefined)
                 return dirname(definition.path);
         }
-        // Progressive-catalog skills are not registered with a provider; fall
-        // back to the catalog-declared path (a directory holding the SKILL.md).
-        const record = skillRecords.get(id);
-        if (record?.origin.path !== undefined)
-            return record.origin.path;
         return undefined;
     };
-    /** Rebuild the MCP tool index synchronously from the visible tool registry. */
-    const rebuildTools = () => {
-        const next = new Map();
-        for (const schema of ctx.tools.schemas()) {
-            // 只编目 mcp__ 工具：原生工具（bash/read 等非 mcp__ 前缀）不进能力目录，
-            // 因此不被 meta_search/meta_invoke 覆盖、也不在能力管理（classifyAll）
-            // 枚举中；它们由 dsh 原生暴露面直连，仅受投影链可见性裁剪，须在
-            // tools.exposed 保活。与 invoke 的 id 前缀守卫保持一致。
-            if (!schema.name.startsWith(MCP_ID_PREFIX))
-                continue;
-            const existing = toolRecords.get(schema.name);
-            const stats = existing?.stats ?? { uses: 0, successes: 0, failures: 0, totalMs: 0 };
-            const serverName = serverNameOf(schema.name);
-            next.set(schema.name, {
-                id: schema.name,
-                kind: 'tool',
-                actions: ['execute'],
-                name: schema.name,
-                description: schema.description,
-                origin: { provider: serverName, serverName },
-                parameters: schema.parameters,
-                invocation: { modelInvocable: true, userInvocable: false },
-                tags: [serverName, 'tool'],
-                stats,
-                summary: toSummary(schema.description, summaryMaxChars),
-            });
-        }
-        toolRecords = next;
+    /**
+     * Index one visible tool schema into `next`, the accumulator owned by the
+     * current rebuild pass, deduped by name.
+     * 全部可见工具都进编目，仅排除 meta_search/meta_invoke（本插件控制面，
+     * 恒常驻）与 run_code（Code Mode 保留传输层）。mcp__ 工具按真实 server
+     * 分组；原生工具（无 mcp__ 前缀）统一归入保留的 built-in server，使能力
+     * 菜单能统一按 server 分组、三档管理，meta_invoke 也能派发它们。
+     * A schema may surface from several preset scope views; the first wins.
+     */
+    const indexToolSchema = (next, schema) => {
+        if (CATALOG_EXCLUDED_TOOLS.has(schema.name))
+            return;
+        if (next.has(schema.name))
+            return;
+        const existing = toolRecords.get(schema.name);
+        const stats = existing?.stats ?? { uses: 0, successes: 0, failures: 0, totalMs: 0 };
+        const isMcp = schema.name.startsWith(MCP_ID_PREFIX);
+        const serverName = isMcp ? serverNameOf(schema.name) : BUILT_IN_SERVER;
+        next.set(schema.name, {
+            id: schema.name,
+            kind: 'tool',
+            actions: ['execute'],
+            name: schema.name,
+            description: schema.description,
+            origin: { provider: serverName, serverName },
+            parameters: schema.parameters,
+            invocation: { modelInvocable: true, userInvocable: false },
+            tags: [serverName, 'tool'],
+            stats,
+            summary: toSummary(schema.description, summaryMaxChars),
+        });
     };
-    /** Read and parse the Progressive-skill catalog YAML into entries (empty when unconfigured/unreadable). */
-    const loadProgressiveSkills = async () => {
-        const file = config.progressiveSkillCatalog;
-        if (file === undefined || file.length === 0)
-            return [];
-        const path = resolve(process.cwd(), file);
-        let text;
-        try {
-            text = await readFile(path, 'utf8');
-        }
-        catch (error) {
-            ctx.logger.warn(`meta-registry: progressive skill catalog not readable (${path}): ${String(error)}`);
-            return [];
-        }
-        let parsed;
-        try {
-            parsed = yaml.load(text);
-        }
-        catch (error) {
-            ctx.logger.warn(`meta-registry: progressive skill catalog parse failed (${path}): ${String(error)}`);
-            return [];
-        }
-        if (parsed === null || typeof parsed !== 'object')
-            return [];
-        const list = parsed.skills;
-        if (!Array.isArray(list))
-            return [];
-        const entries = [];
-        for (const raw of list) {
-            if (raw === null || typeof raw !== 'object')
-                continue;
-            const item = raw;
-            if (typeof item.name !== 'string' || item.name.length === 0)
-                continue;
-            const description = typeof item.description === 'string' ? item.description : '';
-            entries.push({
-                name: item.name,
-                description,
-                ...typeof item.whenToUse === 'string' ? { whenToUse: item.whenToUse } : {},
-                ...typeof item.path === 'string' ? { path: item.path } : {},
-            });
+    /**
+     * Rebuild the tool index from the visible tool registries.
+     *
+     * Harness-native tools are registered on the agent plane (per agent preset's
+     * standing scope), not the root/global layer the plugin's own `ctx.tools`
+     * view sees — exactly the layout the skills side enumerates below. Mirror
+     * that: index the global view first, then every mountable preset's standing
+     * scope, so natives land under the reserved `built-in` pseudo-server.
+     */
+    // Rebuilds can overlap (eager mount-time run vs. a change-event refresh);
+    // the epoch guard drops a superseded run so its older snapshot never
+    // clobbers a newer one. The accumulator is local to each run for the same
+    // reason: a shared one would be reset by the newer run mid-flight, letting
+    // the older run publish a partial catalog when it wins the epoch check.
+    let toolIndexEpoch = 0;
+    const rebuildTools = async () => {
+        const epoch = ++toolIndexEpoch;
+        const nextToolRecords = new Map();
+        for (const schema of ctx.tools.schemas())
+            indexToolSchema(nextToolRecords, schema);
+        const agentPresets = ctx.get('agentPresets');
+        if (agentPresets !== undefined) {
+            let presets = [];
+            try {
+                presets = await agentPresets.list();
+            }
+            catch (error) {
+                ctx.logger.warn(`meta-registry: agent-presets enumeration failed: ${String(error)}`);
+            }
+            for (const preset of presets) {
+                if (preset.broken !== undefined)
+                    continue;
+                try {
+                    const scope = await agentPresets.standingKeyFor(preset.id);
+                    for (const schema of ctx.tools.schemas(scope))
+                        indexToolSchema(nextToolRecords, schema);
+                }
+                catch (error) {
+                    ctx.logger.warn(`meta-registry: preset "${preset.id}" tool scope unavailable: ${String(error)}`);
+                }
+            }
         }
-        return entries;
+        if (epoch === toolIndexEpoch)
+            toolRecords = nextToolRecords;
     };
     /**
      * Rebuild the skill index asynchronously; resolves when the refresh completes.
@@ -187,14 +242,19 @@ export function apply(ctx, config = {}) {
      * registers into that preset's layer, so the host-plane global read alone
      * sees nothing). The management catalog enumerates the global layer and then
      * every mountable preset's standing scope, so preset-scoped skills surface.
+     *
+     * Same epoch guard as the tool side: overlapping refreshes resolve out of
+     * order, and a stale snapshot must not overwrite a newer one.
      */
+    let skillIndexEpoch = 0;
     const refreshSkills = async () => {
+        const epoch = ++skillIndexEpoch;
         const nextSkills = new Map();
         const nextSkillScopes = new Map();
         const indexSkill = (skill, scope) => {
             if (!isModelInvocable(skill))
                 return;
-            const id = skillId(skill.name);
+            const id = skill.name;
             const existing = skillRecords.get(id);
             const stats = existing?.stats ?? { uses: 0, successes: 0, failures: 0, totalMs: 0 };
             nextSkills.set(id, {
@@ -206,9 +266,13 @@ export function apply(ctx, config = {}) {
                 ...skill.whenToUse !== undefined ? { whenToUse: skill.whenToUse } : {},
                 origin: {
                     provider: skill.provider,
+                    ...typeof skill.source === 'string' ? { source: skill.source } : {},
+                    // The skill's own directory, when its provider has one. It is what lets
+                    // the location manager address project-scoped skills for edit/remove.
+                    ...skill.resourceBase?.kind === 'directory' ? { path: skill.resourceBase.path } : {},
                 },
                 parameters: { type: 'object', properties: {}, additionalProperties: false },
-                invocation: { modelInvocable: true, userInvocable: skill.invocation.userInvocable },
+                invocation: { modelInvocable: skill.invocation.modelInvocable, userInvocable: skill.invocation.userInvocable },
                 tags: [skill.provider, 'skill'],
                 stats,
                 summary: toSummary(skill.description, summaryMaxChars),
@@ -253,53 +317,227 @@ export function apply(ctx, config = {}) {
                 }
             }
         }
-        // Additionally index Progressive skills from the independent YAML catalog.
-        // Exposed skills (from ctx.skills) win on a name collision so an Exposed
-        // skill is never shadowed by a stale Progressive catalog entry.
-        const progressive = await loadProgressiveSkills();
-        for (const entry of progressive) {
-            const id = skillId(entry.name);
-            if (nextSkills.has(id))
-                continue;
-            const existing = skillRecords.get(id);
-            const stats = existing?.stats ?? { uses: 0, successes: 0, failures: 0, totalMs: 0 };
-            nextSkills.set(id, {
-                id,
-                kind: 'skill',
-                actions: ['load'],
-                name: entry.name,
-                description: entry.description,
-                ...entry.whenToUse !== undefined ? { whenToUse: entry.whenToUse } : {},
-                origin: {
-                    provider: 'progressive-catalog',
-                    ...entry.path !== undefined ? { path: entry.path } : {},
-                },
-                parameters: { type: 'object', properties: {}, additionalProperties: false },
-                invocation: { modelInvocable: true, userInvocable: false },
-                tags: ['progressive-catalog', 'skill'],
-                stats,
-                summary: toSummary(entry.description, summaryMaxChars),
-            });
-            nextSkillScopes.set(id, undefined);
-        }
+        if (epoch !== skillIndexEpoch)
+            return;
         skillRecords = nextSkills;
         skillScopes = nextSkillScopes;
     };
-    /** Refresh the whole catalog: MCP tools synchronously, skills asynchronously. */
+    /**
+     * Emit the on-demand capability catalog as a YAML file the model can browse
+     * with grep/read. Only On-demand capabilities are written; Resident ones are
+     * already in the model surface and Disabled ones must stay undiscoverable.
+     * Skips emission when the policy plugin is not mounted (no classification) or
+     * the file path is disabled.
+     */
+    const writeCatalog = async () => {
+        onDemandCount = 0;
+        if (catalogFile.length === 0)
+            return;
+        const policy = ctx.get('capabilityPolicy');
+        if (policy === undefined)
+            return;
+        const onDemand = [...toolRecords.values(), ...skillRecords.values()]
+            .filter(record => policy.classifyCapability(record.id, record.kind) === 'on-demand')
+            .map(record => ({
+            id: record.id,
+            kind: record.kind,
+            name: record.name,
+            // Use the trimmed summary (160 chars), not the full description: the
+            // file is for grep/read discovery, and a few hundred tools would
+            // otherwise balloon to tens of KB of context.
+            description: record.summary,
+            ...record.whenToUse !== undefined ? { whenToUse: record.whenToUse } : {},
+            ...record.origin.serverName !== undefined ? { server: record.origin.serverName } : {},
+        }));
+        onDemandCount = onDemand.length;
+        const content = yaml.dump({ capabilities: onDemand });
+        // A rebuild that changed nothing must not touch the disk: at debounce rate
+        // this was rewriting the file several times a second.
+        if (content === lastCatalogContent)
+            return;
+        try {
+            await writeFile(catalogFile, content, 'utf8');
+            lastCatalogContent = content;
+        }
+        catch (error) {
+            ctx.logger.warn(`capability-registry: on-demand catalog write failed (${catalogFile}): ${String(error)}`);
+        }
+    };
+    // --- Refresh scheduling --------------------------------------------------
+    // Change events (`tools/change` / `skills/change`) arrive in bursts: the
+    // skill/preset lifecycle invalidates caches and re-registers providers in
+    // quick succession, and a rebuild's own registry access can emit further
+    // change events. Rebuilding once per event produced an unbounded CPU storm
+    // (a full preset re-scan per event), so the scheduler:
+    //   1. runs at most one rebuild at a time (single flight);
+    //   2. coalesces every event landing during a run into at most one
+    //      debounced follow-up rebuild;
+    //   3. lets an explicit `refresh()` await the rebuild chain covering its own
+    //      call, so callers never observe a stale (or empty) catalog.
+    // The epoch guards inside `rebuildTools`/`refreshSkills` stay as the last
+    // line of defence for concurrent correctness.
+    /** Monotonic count of rebuild requests received (events + explicit calls). */
+    let eventSeq = 0;
+    /** The `eventSeq` value fully applied by the last completed rebuild. */
+    let appliedSeq = 0;
+    let rebuilding = false;
+    let stopped = false;
+    let timer;
+    const waiters = [];
+    /** Resolve every waiter whose snapshot is already covered by `appliedSeq`. */
+    const settleWaiters = () => {
+        if (waiters.length === 0)
+            return;
+        const ready = waiters.filter(waiter => waiter.seq <= appliedSeq);
+        if (ready.length === 0)
+            return;
+        for (const waiter of ready)
+            waiters.splice(waiters.indexOf(waiter), 1);
+        for (const waiter of ready)
+            waiter.resolve();
+    };
+    /**
+     * Consecutive rebuilds that reproduced the previous catalog. A noisy event
+     * stream that never changes anything (session re-registrations, the skill
+     * watcher) would otherwise keep the scheduler at the debounce rate, and each
+     * rebuild re-enumerates every preset's tools and skills — measured at ~1.5s
+     * CPU each, enough to starve the event loop and stall unrelated UI calls.
+     */
+    let idleStreak = 0;
+    /** Upper bound for the backoff, so a real change is never pending long. */
+    const BACKOFF_MAX_MS = 10_000;
+    const currentDelay = () => {
+        // The ceiling can never fall below the configured base, or a large
+        // `refreshDebounceMs` would be clamped *down* into a faster schedule.
+        const ceiling = Math.max(BACKOFF_MAX_MS, refreshDebounceMs);
+        return Math.min(refreshDebounceMs * 2 ** idleStreak, ceiling);
+    };
+    /** Queue a coalesced rebuild after the (possibly backed-off) window. */
+    const schedule = () => {
+        if (stopped || rebuilding || timer !== undefined)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            if (stopped || rebuilding)
+                return;
+            void runRebuild();
+        }, currentDelay());
+    };
+    /**
+     * Fingerprint of the indexed catalog — capability ids only, order-insensitive.
+     * Used to tell a rebuild that found something new from one that merely
+     * reproduced the previous catalog.
+     */
+    const catalogSignature = () => {
+        const ids = [];
+        for (const id of toolRecords.keys())
+            ids.push(`t:${id}`);
+        for (const id of skillRecords.keys())
+            ids.push(`s:${id}`);
+        ids.sort();
+        return ids.join('\u0000');
+    };
+    let lastSignature;
+    /** Consecutive follow-up runs that reproduced the previous catalog. */
+    let unchangedChain = 0;
+    /** One full rebuild; never rejects (a failed run must not hang waiters). */
+    const runRebuild = async () => {
+        rebuilding = true;
+        // Every request received so far is covered by this run.
+        const seqAtStart = eventSeq;
+        const startedAt = Date.now();
+        try {
+            await rebuildTools();
+            await refreshSkills();
+            await writeCatalog();
+        }
+        catch (error) {
+            ctx.logger.warn(`capability-registry: catalog rebuild failed: ${String(error)}`);
+        }
+        finally {
+            rebuilding = false;
+            if (seqAtStart > appliedSeq)
+                appliedSeq = seqAtStart;
+            settleWaiters();
+            // Requests that landed mid-run are not covered yet, so chain a
+            // follow-up — but never indefinitely. Two runs in a row that reproduce
+            // the same catalog mean the pending events carried no new capability:
+            // our own registry reads can emit change events, and dsh's skill watcher
+            // can stream them, so chaining on would spin at the debounce rate
+            // forever. One follow-up is still allowed before stopping, because a
+            // real change that lands mid-run is only visible to the *next* run.
+            const signature = catalogSignature();
+            const changed = signature !== lastSignature;
+            lastSignature = signature;
+            // One line per full rebuild. These are the expensive runs (every tool plus
+            // every agent-preset skill scope); if they are repeating, this is where it
+            // shows — and a caller blocked behind one sees that as the UI stalling.
+            ctx.logger.info(`capability-registry: rebuild took ${Date.now() - startedAt}ms (catalog changed: ${changed}, ${toolRecords.size} tools, ${skillRecords.size} skills)`);
+            if (changed)
+                idleStreak = 0;
+            else if (idleStreak < 10)
+                idleStreak += 1;
+            if (!stopped && eventSeq > appliedSeq) {
+                if (changed) {
+                    unchangedChain = 0;
+                    schedule();
+                }
+                else if (unchangedChain === 0) {
+                    unchangedChain = 1;
+                    schedule();
+                }
+            }
+        }
+    };
+    /** Start a rebuild immediately, skipping the debounce window. */
+    const runNow = () => {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+        if (!stopped && !rebuilding)
+            void runRebuild();
+    };
+    /**
+     * Refresh the whole catalog, resolving once the rebuild chain covering this
+     * call has converged (including any coalesced follow-up).
+     */
     const refresh = async () => {
-        rebuildTools();
-        await refreshSkills();
+        if (stopped)
+            return;
+        const seq = ++eventSeq;
+        runNow();
+        if (seq <= appliedSeq)
+            return;
+        await new Promise(resolve => {
+            waiters.push({ seq, resolve });
+        });
     };
     /** Register once; also subscribe to change events. */
     const disposers = [];
-    disposers.push(ctx.on('tools/change', () => void refresh()));
-    disposers.push(ctx.on('skills/change', () => void refresh()));
-    // Build the synchronous tool index eagerly; the skill index is left to
-    // the first explicit `refresh()` (or a change event) so an eager load never
-    // snapshots — and caches inside the skill registry — an incomplete catalog.
-    rebuildTools();
+    disposers.push(ctx.on('tools/change', () => {
+        eventSeq++;
+        schedule();
+    }));
+    disposers.push(ctx.on('skills/change', () => {
+        eventSeq++;
+        schedule();
+    }));
+    // Index the global tool view eagerly (the synchronous part of
+    // `rebuildTools`); preset standing scopes and skills are enumerated by the
+    // first explicit `refresh()` (policy mounts it before the surface is used)
+    // or a change event, so an eager load never snapshots — and caches inside the
+    // tool/skill registries — an incomplete catalog.
+    void rebuildTools();
     void refreshSkills();
     ctx.effect(() => () => {
+        stopped = true;
+        if (timer !== undefined)
+            clearTimeout(timer);
+        // Unblock any in-flight `refresh()`: the plugin is going away and no
+        // further rebuild will run.
+        for (const waiter of waiters.splice(0))
+            waiter.resolve();
         for (const dispose of disposers)
             dispose();
     });
@@ -312,11 +550,11 @@ export function apply(ctx, config = {}) {
             const id = options.id?.trim();
             const all = [];
             // Index/source is the GLOBAL registry — no visibility filter here.
-            // Exposed/Progressive is a projection-layer concern (`dsh-capability-policy`),
-            // so a Progressive tool hidden from the model's exposure surface must still
-            // be searchable so `meta_search` can return it for `meta_invoke`. Blocked
+            // Resident/On-demand is a projection-layer concern (`dsh-capability-policy`),
+            // so an On-demand tool hidden from the model's exposure surface must still
+            // be searchable so `meta_search` can return it for `meta_invoke`. Disabled
             // enforcement lives at the model-facing tools (meta_search/meta_invoke),
-            // keeping the management surface able to list Blocked capabilities.
+            // keeping the management surface able to list Disabled capabilities.
             if (kind === 'all' || kind === 'tool') {
                 for (const record of toolRecords.values())
                     all.push(record);
@@ -360,19 +598,18 @@ export function apply(ctx, config = {}) {
                     name: record.name,
                     summary: record.summary,
                     ...record.origin.serverName !== undefined ? { server: record.origin.serverName } : {},
+                    ...record.origin.source !== undefined ? { source: record.origin.source } : {},
                     tags: record.tags,
                     ...rate !== undefined ? { success_rate: rate } : {},
                     uses: record.stats.uses,
                 };
             });
         },
-        get(id) {
-            const key = id.trim();
-            return toolRecords.get(key) ?? skillRecords.get(key);
+        get(id, kind) {
+            return resolveRecord(id.trim(), kind);
         },
-        async getDetail(id, context = {}) {
-            const key = id.trim();
-            const record = toolRecords.get(key) ?? skillRecords.get(key);
+        async getDetail(id, kind, context = {}) {
+            const record = resolveRecord(id.trim(), kind);
             if (record === undefined)
                 return undefined;
             if (record.kind === 'tool') {
@@ -421,8 +658,10 @@ export function apply(ctx, config = {}) {
             if (root === undefined)
                 return undefined;
             const target = relPath.length === 0 ? root : resolve(root, relPath);
-            // Containment: the resolved path must stay inside the skill root.
-            if (target !== root && !target.startsWith(`${root}${sep}`))
+            // Containment: the resolved path must stay inside the skill root, both
+            // lexically (`..`) and after resolving symlinks (a link inside the skill
+            // directory must not lead out of it).
+            if (!(await isInside(root, target)))
                 return undefined;
             try {
                 const entries = await readdir(target, { withFileTypes: true });
@@ -441,8 +680,8 @@ export function apply(ctx, config = {}) {
             if (root === undefined)
                 return undefined;
             const target = resolve(root, relPath);
-            // Containment: the resolved path must stay inside the skill root.
-            if (target !== root && !target.startsWith(`${root}${sep}`))
+            // Containment: see `listSkillDir` — lexical `..` and symlinks both checked.
+            if (!(await isInside(root, target)))
                 return undefined;
             try {
                 const info = await stat(target);
@@ -457,25 +696,52 @@ export function apply(ctx, config = {}) {
                 return undefined;
             }
         },
+        skillDirs() {
+            const out = [];
+            for (const record of skillRecords.values()) {
+                const skillDir = record.origin.path;
+                if (skillDir === undefined)
+                    continue;
+                out.push({
+                    name: record.name,
+                    skillDir,
+                    ...record.origin.source !== undefined ? { source: record.origin.source } : {},
+                });
+            }
+            return out;
+        },
         size() {
             return toolRecords.size + skillRecords.size;
         },
+        catalogPath() {
+            return catalogFile.length === 0 ? undefined : catalogFile;
+        },
+        onDemandCount() {
+            return onDemandCount;
+        },
         refresh() {
             return refresh();
         },
+        requestRefresh() {
+            if (stopped)
+                return;
+            eventSeq++;
+            schedule();
+        },
+        rewriteCatalog() {
+            return writeCatalog();
+        },
     };
     // Observe tool results to write back objective stats. Nested dispatches
     // (parent set by meta_invoke) attribute to the target capability; the
     // meta_invoke wrapper itself records nothing for any capability.
     ctx.on('tools/result', (exec, result) => {
         const name = exec.name;
-        if (!name.startsWith(MCP_ID_PREFIX))
-            return;
         const record = toolRecords.get(name);
         if (record === undefined)
             return;
-        // meta_invoke never carries the `mcp__` prefix (filtered above), so a nested
-        // dispatch from meta_invoke attributes stats only to the target capability.
+        // Nested dispatches (a meta_invoke call or a native-tool forward) carry the
+        // target tool's own name, so stats always attribute to the target capability.
         const durationMs = result.meta !== undefined && typeof result.meta === 'object'
             && result.meta !== null && 'durationMs' in result.meta
             ? result.meta.durationMs
@@ -498,12 +764,4 @@ export function serverNameOf(publicName) {
     const index = rest.indexOf('__');
     return index === -1 ? rest : rest.slice(0, index);
 }
-/** Build the stable skill identifier `skill:<name>`. */
-export function skillId(name) {
-    return `${SKILL_ID_PREFIX}${name}`;
-}
-/** Strip the `skill:` prefix from a capability id. */
-export function skillNameOf(id) {
-    return id.startsWith(SKILL_ID_PREFIX) ? id.slice(SKILL_ID_PREFIX.length) : id;
-}
 //# sourceMappingURL=registry.js.map