@khorsheed/dsh-capability-catalog 0.1.95

package/lib/types/index.js

@@ -0,0 +1,739 @@
+/**
+ * Capability catalog host service: a Typert Remote over the running skill and
+ * tool registries. It projects `ctx.skills.snapshot()` into catalog rows,
+ * attributes `ctx.tools.schemas()` to a channel (mcp prefix / official
+ * whitelist / baseline-diff), loads per-skill detail on demand, writes
+ * declared credentials, and adds skills into the managed root. The browser
+ * half binds through the generated `capabilityCatalog` Remote namespace.
+ *
+ * Zero host edits: everything rides existing official services (`ctx.skills`,
+ * `ctx.tools`, `ctx.credentials`) through `ctx.get`, degrading silently when a
+ * capability is absent.
+ * @module @khorsheed/dsh-capability-catalog
+ */
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { catalogAddSkill, catalogDetail, catalogListDirSkills, catalogReadSkillFile, catalogSetCredential, catalogSnapshot, catalogDeleteSkill, catalogPickDirectory } from './remote.js';
+import { resolveServices } from './skills.js';
+import { definitionFor, scanManagedSkills, ScopedSkillDelivery, scopedSkillsRoot, } from './scoped-delivery.js';
+import { adoptManagedSkill, releaseManagedSkill, setManagedPresetScope, } from './scoped-edits.js';
+import { installSkillEnvInjection } from './shellEnv.js';
+import { McpStore } from './mcpStore.js';
+import { reconcileRegisteredMcpTools, desiredMcpTools } from './mcpTools.js';
+import { maskConfig } from './mcps.js';
+import { installSkillEnvHint } from './envHint.js';
+import { MCP_TOOL_PREFIX } from './channels.js';
+import { toolOrigin, isValidOrigin } from './tool-origin.js';
+import { CAPABILITY_CATALOG_NS } from './namespace.js';
+import { CapabilityCatalogSettingsSchema } from './settings.js';
+import { capsTag, hashOf } from './capabilities.js';
+import { resolvePresetScope } from './preset-scope.js';
+import { modeOptions, readModeFaces } from './modes.js';
+// Community tool-origin convention: re-export the tag helpers so any plugin can
+// `import { setToolOrigin } from '@khorsheed/dsh-capability-catalog'`.
+export { TOOL_ORIGIN, setToolOrigin, toolOrigin } from './tool-origin.js';
+export { resolveSkillNameFromContent } from './import.js';
+export { resolvePresetScope } from './preset-scope.js';
+// The mode view: the roster a picker offers and one face per mode.
+export { modeOptions, readModeFaces } from './modes.js';
+export { ScopedSkillDelivery, scopedSkillsRoot, scanManagedSkills, managedSkillFrom, parsePresetScopeFrontmatter, defaultSkillRoots, detectConflicts, SCOPED_PROVIDER_NAME, MANAGED_SKILL_RANK, } from './scoped-delivery.js';
+export { adoptManagedSkill, releaseManagedSkill, setManagedPresetScope, withPresetScope, findSkillSource, managedLocation, isDirectory, } from './scoped-edits.js';
+// The capability fingerprint: the canonical form, its digest, and the tag.
+// Exported from the package root so a host reader can hash a snapshot it
+// already holds without a second Remote round-trip.
+export { canonicalCapabilities, canonicalJson, capsTag, hashOf, hashSkillBody, CAPS_TAG_PREFIX, } from './capabilities.js';
+/** The remote namespace name (matches the generated remote-client type). */
+export const REMOTE_NS = 'capabilityCatalog';
+/** Custom inject: subscribe no extra service beyond the two we probe. */
+function resolveServicesHelper(ctx) {
+    return resolveServices(ctx);
+}
+/**
+ * Capability catalog Remote service.
+ * @module @khorsheed/dsh-capability-catalog
+ */
+let CapabilityCatalogService = (() => {
+    let _classSuper = TypertRemoteService;
+    let _instanceExtraInitializers = [];
+    let _presetScopeStatus_decorators;
+    let _presetScopeRoster_decorators;
+    let _modeFaces_decorators;
+    let _presetScopeSet_decorators;
+    let _presetScopeAdopt_decorators;
+    let _presetScopeRelease_decorators;
+    let _snapshot_decorators;
+    let _snapshotAt_decorators;
+    let _snapshotFor_decorators;
+    let _detail_decorators;
+    let _readSkillFile_decorators;
+    let _listDirSkills_decorators;
+    let _setCredential_decorators;
+    let _addSkill_decorators;
+    let _deleteSkill_decorators;
+    let _pickDirectory_decorators;
+    let _mcpList_decorators;
+    let _mcpAdd_decorators;
+    let _mcpRemove_decorators;
+    let _mcpSetEnabled_decorators;
+    let _mcpSetCredential_decorators;
+    let _mcpSetToolEnabled_decorators;
+    let _mcpDiscover_decorators;
+    let _mcpSnapshot_decorators;
+    return class CapabilityCatalogService extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _presetScopeStatus_decorators = [Remote('presetScopeStatus')];
+            _presetScopeRoster_decorators = [Remote('presetScopeRoster')];
+            _modeFaces_decorators = [Remote('modeFaces')];
+            _presetScopeSet_decorators = [Remote('presetScopeSet')];
+            _presetScopeAdopt_decorators = [Remote('presetScopeAdopt')];
+            _presetScopeRelease_decorators = [Remote('presetScopeRelease')];
+            _snapshot_decorators = [Remote('snapshot')];
+            _snapshotAt_decorators = [Remote('snapshotAt')];
+            _snapshotFor_decorators = [Remote('snapshotFor')];
+            _detail_decorators = [Remote('detail')];
+            _readSkillFile_decorators = [Remote('readSkillFile')];
+            _listDirSkills_decorators = [Remote('listDirSkills')];
+            _setCredential_decorators = [Remote('setCredential')];
+            _addSkill_decorators = [Remote('addSkill')];
+            _deleteSkill_decorators = [Remote('deleteSkill')];
+            _pickDirectory_decorators = [Remote('pickDirectory')];
+            _mcpList_decorators = [Remote('mcpList')];
+            _mcpAdd_decorators = [Remote('mcpAdd')];
+            _mcpRemove_decorators = [Remote('mcpRemove')];
+            _mcpSetEnabled_decorators = [Remote('mcpSetEnabled')];
+            _mcpSetCredential_decorators = [Remote('mcpSetCredential')];
+            _mcpSetToolEnabled_decorators = [Remote('mcpSetToolEnabled')];
+            _mcpDiscover_decorators = [Remote('mcpDiscover')];
+            _mcpSnapshot_decorators = [Remote('mcpSnapshot')];
+            __esDecorate(this, null, _presetScopeStatus_decorators, { kind: "method", name: "presetScopeStatus", static: false, private: false, access: { has: obj => "presetScopeStatus" in obj, get: obj => obj.presetScopeStatus }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _presetScopeRoster_decorators, { kind: "method", name: "presetScopeRoster", static: false, private: false, access: { has: obj => "presetScopeRoster" in obj, get: obj => obj.presetScopeRoster }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _modeFaces_decorators, { kind: "method", name: "modeFaces", static: false, private: false, access: { has: obj => "modeFaces" in obj, get: obj => obj.modeFaces }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _presetScopeSet_decorators, { kind: "method", name: "presetScopeSet", static: false, private: false, access: { has: obj => "presetScopeSet" in obj, get: obj => obj.presetScopeSet }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _presetScopeAdopt_decorators, { kind: "method", name: "presetScopeAdopt", static: false, private: false, access: { has: obj => "presetScopeAdopt" in obj, get: obj => obj.presetScopeAdopt }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _presetScopeRelease_decorators, { kind: "method", name: "presetScopeRelease", static: false, private: false, access: { has: obj => "presetScopeRelease" in obj, get: obj => obj.presetScopeRelease }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _snapshot_decorators, { kind: "method", name: "snapshot", static: false, private: false, access: { has: obj => "snapshot" in obj, get: obj => obj.snapshot }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _snapshotAt_decorators, { kind: "method", name: "snapshotAt", static: false, private: false, access: { has: obj => "snapshotAt" in obj, get: obj => obj.snapshotAt }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _snapshotFor_decorators, { kind: "method", name: "snapshotFor", static: false, private: false, access: { has: obj => "snapshotFor" in obj, get: obj => obj.snapshotFor }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _detail_decorators, { kind: "method", name: "detail", static: false, private: false, access: { has: obj => "detail" in obj, get: obj => obj.detail }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _readSkillFile_decorators, { kind: "method", name: "readSkillFile", static: false, private: false, access: { has: obj => "readSkillFile" in obj, get: obj => obj.readSkillFile }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _listDirSkills_decorators, { kind: "method", name: "listDirSkills", static: false, private: false, access: { has: obj => "listDirSkills" in obj, get: obj => obj.listDirSkills }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _setCredential_decorators, { kind: "method", name: "setCredential", static: false, private: false, access: { has: obj => "setCredential" in obj, get: obj => obj.setCredential }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _addSkill_decorators, { kind: "method", name: "addSkill", static: false, private: false, access: { has: obj => "addSkill" in obj, get: obj => obj.addSkill }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _deleteSkill_decorators, { kind: "method", name: "deleteSkill", static: false, private: false, access: { has: obj => "deleteSkill" in obj, get: obj => obj.deleteSkill }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _pickDirectory_decorators, { kind: "method", name: "pickDirectory", static: false, private: false, access: { has: obj => "pickDirectory" in obj, get: obj => obj.pickDirectory }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _mcpList_decorators, { kind: "method", name: "mcpList", static: false, private: false, access: { has: obj => "mcpList" in obj, get: obj => obj.mcpList }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _mcpAdd_decorators, { kind: "method", name: "mcpAdd", static: false, private: false, access: { has: obj => "mcpAdd" in obj, get: obj => obj.mcpAdd }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _mcpRemove_decorators, { kind: "method", name: "mcpRemove", static: false, private: false, access: { has: obj => "mcpRemove" in obj, get: obj => obj.mcpRemove }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _mcpSetEnabled_decorators, { kind: "method", name: "mcpSetEnabled", static: false, private: false, access: { has: obj => "mcpSetEnabled" in obj, get: obj => obj.mcpSetEnabled }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _mcpSetCredential_decorators, { kind: "method", name: "mcpSetCredential", static: false, private: false, access: { has: obj => "mcpSetCredential" in obj, get: obj => obj.mcpSetCredential }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _mcpSetToolEnabled_decorators, { kind: "method", name: "mcpSetToolEnabled", static: false, private: false, access: { has: obj => "mcpSetToolEnabled" in obj, get: obj => obj.mcpSetToolEnabled }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _mcpDiscover_decorators, { kind: "method", name: "mcpDiscover", static: false, private: false, access: { has: obj => "mcpDiscover" in obj, get: obj => obj.mcpDiscover }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _mcpSnapshot_decorators, { kind: "method", name: "mcpSnapshot", static: false, private: false, access: { has: obj => "mcpSnapshot" in obj, get: obj => obj.mcpSnapshot }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        config = __runInitializers(this, _instanceExtraInitializers);
+        static inject = [];
+        static Config = CapabilityCatalogSettingsSchema;
+        baseline;
+        appearedAfterApply;
+        mcp;
+        /** The live `ctx.tools` (traceable proxy) captured from the tools inject. */
+        mcpToolsRegistry;
+        /** Registered MCP tool disposers, keyed by model-facing public name. */
+        mcpToolDisposers = new Map();
+        /** Preset-scoped delivery of the plugin's own managed skill root. */
+        scoped;
+        /** The workspace the catalog was last asked about, for project-root conflict checks. */
+        observedWorkdir;
+        constructor(ctx, config) {
+            super(ctx, 'capabilityCatalog');
+            this.config = config;
+            this.mcp = new McpStore();
+            this.baseline = new Set();
+            this.appearedAfterApply = new Set();
+            // Persist the MCP state so servers survive a restart: seed the in-process
+            // store at boot, persist every mutation, and reload when the config
+            // document changes externally. Two host lines, one outcome: 0.1.5 serves a
+            // free-form `settings.register` namespace (whose scope.watch round-trips
+            // both our own and external writes); 0.1.7 persists the plugin Config's
+            // volatile `mcp` field through SettingsForms (writes ride the profile
+            // patch, the running fiber's Volatile reference tracks them, and
+            // `settings/document-updated` is the round-trip channel). The card reads
+            // its data through the Remote on both lines. Degrades silently when
+            // settings is absent (in-process store only, resets on restart).
+            ctx.inject(['settings'], (settingsCtx) => {
+                const svc = settingsCtx.settings;
+                if (typeof svc.register === 'function') {
+                    const scope = svc.register(CAPABILITY_CATALOG_NS, CapabilityCatalogSettingsSchema);
+                    const persisted = scope.get()?.mcp;
+                    if (persisted !== undefined)
+                        this.mcp.loadFrom(persisted);
+                    this.mcp.onPersist = () => {
+                        void scope.update({ mcp: this.mcp.toPersisted() }).catch((error) => this.ctx.logger.error(error));
+                    };
+                    scope.watch((next) => {
+                        this.mcp.loadFrom(next?.mcp);
+                        this.afterMcpMutation();
+                    });
+                }
+                else if (typeof svc.update === 'function') {
+                    // The catalog ships its own card; keep the machine-state block out of
+                    // any auto-generated form.
+                    svc.configure?.({ auto: false }, ctx.fiber);
+                    const readVolatile = () => {
+                        const field = this.config.mcp;
+                        if (field !== null && typeof field === 'object' && typeof field.get === 'function') {
+                            return field.get();
+                        }
+                        return field;
+                    };
+                    const persisted = readVolatile();
+                    if (persisted !== undefined)
+                        this.mcp.loadFrom(persisted);
+                    this.mcp.onPersist = () => {
+                        // Wholesale write, NOT merge: `update` mergeLayers recurses plain
+                        // objects, so a REMOVED server/credential/tool key would survive in
+                        // the document and come back through the document-updated
+                        // round-trip below. `replace` resets the live fields first; the mcp
+                        // block is this entry's only volatile field, so a replace is exactly
+                        // the block swap. rc.1's SettingsForms carries both.
+                        const write = typeof svc.replace === 'function'
+                            ? svc.replace(CAPABILITY_CATALOG_NS, { mcp: this.mcp.toPersisted() })
+                            : svc.update(CAPABILITY_CATALOG_NS, { mcp: this.mcp.toPersisted() });
+                        void write.catch((error) => this.ctx.logger.error(error));
+                    };
+                    settingsCtx.on('settings/document-updated', (ns) => {
+                        if (ns !== CAPABILITY_CATALOG_NS)
+                            return;
+                        this.mcp.loadFrom(readVolatile());
+                        this.afterMcpMutation();
+                    });
+                }
+                // Re-sync after loading persisted state (the tools inject may have fired
+                // before the store was seeded).
+                this.syncRegisteredMcpTools();
+                // The persisted block stores only tool names + toggles (descriptions and
+                // parameter schemas would bloat settings.yaml and go stale), so refill
+                // them by re-connecting the enabled servers at boot, async so boot is not
+                // blocked. Re-syncs registration once the descriptions are back.
+                void this.reconnectEnabledMcp();
+            });
+            // Baseline snapshot of the tools visible once the registry is ready; tools
+            // that appear later (a tools/change diff) are marked plugin/inferred. Set it
+            // inside the DEFERRED tools inject — an apply-time ctx.get probe races the
+            // registry's own mount order and can lose on the real composition tree (tools
+            // may compose after the catalog), yielding an empty baseline and mislabeling
+            // every visible tool as post-apply/plugin.
+            ctx.inject(['tools'], (toolCtx) => {
+                this.mcpToolsRegistry = toolCtx.tools;
+                this.syncRegisteredMcpTools();
+                this.registerListTool(toolCtx.tools);
+                // Baseline for the channel heuristics (set where the registry is known).
+                this.baseline = new Set(toolCtx.tools.schemas().map(t => t.name) ?? []);
+                this.appearedAfterApply.clear();
+                ctx.on('tools/change', () => this.markNewTools());
+            });
+            // Expose each configured skill credential as a trusted per-execution
+            // `DSH_<KEY>` env var so the agent's shell can use it (shell expansion),
+            // without the raw value entering the model's context (default-hide). The
+            // catalog is service-agnostic — it knows nothing about the specific service;
+            // the skill tells the agent how to query. Defer to composition time via
+            // inject so the env-injection runs once shellEnv/credentials/skills are
+            // registered (at the catalog's apply they may not be composed yet).
+            ctx.inject(['shellEnv', 'credentials', 'skills'], () => {
+                installSkillEnvInjection(ctx, () => this.catalogScope());
+            });
+            // Runtime companion hint (generic): when the skill tool loads a skill,
+            // tell the model the configured credential env mappings so it uses the
+            // DSH_<KEY> alias without the skill being modified.
+            installSkillEnvHint(ctx, () => this.catalogScope());
+            // Preset-scoped delivery: the plugin's own managed root holds skills whose
+            // frontmatter names the presets they belong to, and each of those presets
+            // gets a provider registered into ITS scope layer. Deferred via inject so
+            // the registry is present, and owned by an effect so the delivery scopes
+            // (and the filesystem watcher) unwind with the plugin.
+            ctx.inject(['skills'], (skillsCtx) => {
+                const delivery = new ScopedSkillDelivery(skillsCtx, {
+                    dshHome: () => this.dshHome(),
+                    roster: () => this.agentPresets(),
+                    registry: () => this.ctx.get?.('skills'),
+                    workdir: () => this.observedWorkdir,
+                    log: (message) => this.ctx.logger.warn(message),
+                });
+                this.scoped = delivery;
+                skillsCtx.effect(() => {
+                    void delivery.start().catch((error) => {
+                        this.ctx.logger.warn(`capability-catalog: preset-scoped delivery failed to start: ${error instanceof Error ? error.message : String(error)}`);
+                    });
+                    return () => { void delivery.dispose(); };
+                }, 'capability-catalog: preset-scoped skills');
+            });
+        }
+        /** The preset-scoped delivery's current state, for the settings surface. */
+        async presetScopeStatus() {
+            const status = this.scoped?.status();
+            return status === undefined
+                ? {
+                    enabled: false,
+                    reason: 'preset-scoped delivery is not composed',
+                    root: scopedSkillsRoot(this.dshHome()),
+                    watching: false,
+                    skills: [],
+                    presets: [],
+                    customRootsUnverifiable: true,
+                }
+                : status;
+        }
+        /** Every preset the roster supplies, for the scope picker. */
+        async presetScopeRoster() {
+            return modeOptions(await this.rosterRows(), this.agentPresets()?.defaultId);
+        }
+        /**
+         * Every mode's capability face in ONE call, for the cross-mode comparison
+         * view ("which modes load this tool/skill?").
+         *
+         * This is the expensive verb of the pair: a mode whose standing scope has not
+         * been composed yet is MOUNTED by its read (see modes.ts — there is no cheap
+         * honest source, because a composition file names plugins, not the tools and
+         * skills those plugins register). The browser therefore calls it only when a
+         * human chooses to compare modes, never on opening the section.
+         *
+         * A mode that cannot be read keeps its row with `unavailable` set rather than
+         * an empty face, so the comparison never claims that a broken mode loads
+         * nothing. `preset` on a face is always the id that was asked for: a read
+         * that silently degraded to the global layer is reported as unavailable, not
+         * as that mode's face.
+         * @param workdir - optional cwd for project-scoped skill roots.
+         */
+        async modeFaces(workdir) {
+            const options = modeOptions(await this.rosterRows(), this.agentPresets()?.defaultId);
+            return readModeFaces(options, async (id) => {
+                try {
+                    const face = await this.collect(id, workdir, false);
+                    if (face.preset !== id) {
+                        this.ctx.logger.warn(`capability-catalog: preset "${id}" resolved no standing scope — its mode face reads as unavailable`);
+                        return undefined;
+                    }
+                    return face;
+                }
+                catch (error) {
+                    this.ctx.logger.warn(`capability-catalog: mode face read for preset "${id}" failed: ${error instanceof Error ? error.message : String(error)}`);
+                    return undefined;
+                }
+            });
+        }
+        /** The roster rows, or [] when this composition mounts no agent-preset service. */
+        async rosterRows() {
+            const roster = this.agentPresets();
+            if (roster?.list === undefined)
+                return [];
+            try {
+                return await roster.list();
+            }
+            catch (error) {
+                this.ctx.logger.warn(`capability-catalog: the preset roster could not be listed: ${error instanceof Error ? error.message : String(error)}`);
+                return [];
+            }
+        }
+        /** Declare which presets one managed skill is delivered to. */
+        async presetScopeSet(request) {
+            const result = await setManagedPresetScope(this.dshHome(), request.name, request.presets);
+            await this.reconcileScoped();
+            return result;
+        }
+        /** Move an installed skill into the managed root with a preset scope. */
+        async presetScopeAdopt(request) {
+            const result = await adoptManagedSkill(this.dshHome(), request.name, request.presets, request.workdir ?? this.observedWorkdir);
+            await this.reconcileScoped();
+            return result;
+        }
+        /** Move a managed skill back to the user skill root (the recovery direction). */
+        async presetScopeRelease(name) {
+            const result = await releaseManagedSkill(this.dshHome(), name);
+            await this.reconcileScoped();
+            return result;
+        }
+        /** Re-deliver after a write; a delivery that is absent is not an error. */
+        async reconcileScoped() {
+            try {
+                await this.scoped?.reconcile();
+            }
+            catch (error) {
+                this.ctx.logger.warn(`capability-catalog: scoped skill reconcile failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        /** Record tools that appeared after the apply-time baseline (reads the live
+         * registry each time, so a change event never sees a stale/undefined ref). */
+        markNewTools() {
+            const tools = this.ctx.get?.('tools');
+            const current = new Set(tools?.schemas().map(t => t.name) ?? []);
+            for (const name of current) {
+                if (!this.baseline.has(name))
+                    this.appearedAfterApply.add(name);
+            }
+        }
+        /** The managed skills root under `$DSH_HOME`. */
+        dshHome() {
+            const settings = this.ctx.get?.('settings');
+            const home = settings?.home;
+            return home ?? process.env.DSH_HOME ?? join(homedir(), '.dsh-official');
+        }
+        /**
+         * The standing skill view scope of ONE preset. In the web bundle the
+         * host-global skill-filesystem provider is mounted under each agent
+         * preset's standing scope, so a host-global snapshot sees only runtime
+         * skills; reading at the preset's scope surfaces the official/plugin/user
+         * skills the model actually sees. When the presets service is absent the
+         * catalog degrades to the global layer alone.
+         *
+         * `presetId` names WHICH preset — the deployment default when omitted, the
+         * way every reader before `snapshotFor` behaved. The roster's scope face
+         * (0.1.5's `standingKeyFor`, rc.1's leased `acquireScope`) has always taken
+         * an id; the catalog simply never passed one, so "the capability face of
+         * preset X" was unaskable and a condition declaring `preset: X` could only
+         * be believed.
+         *
+         * `strict` is the listing/fingerprint split — see
+         * {@link resolvePresetScope}, which owns the policy.
+         * @param presetId - the preset to read, or undefined for the default.
+         * @param strict - throw instead of degrading when the roster cannot answer.
+         */
+        async catalogScope(presetId, strict = false) {
+            const { scope, dispose } = await resolvePresetScope(this.agentPresets(), presetId, strict);
+            // Release before the caller reads: the roster reaps a generation only
+            // once its preset is unregistered AND unleased, so a live preset's scope
+            // survives the release — the same guarantee a lease-free 0.1.5 key had.
+            await this.releaseScope(dispose);
+            return scope;
+        }
+        /** Release a scope lease, logging rather than failing the read it followed. */
+        async releaseScope(dispose) {
+            if (dispose === undefined)
+                return;
+            try {
+                await dispose();
+            }
+            catch (error) {
+                this.ctx.logger.warn(`capability-catalog: scope lease release failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        /** The optional agent-preset roster (absent in a rosterless composition). */
+        agentPresets() {
+            return this.ctx.get?.('agentPresets');
+        }
+        /** Register the model-facing `list_capabilities` tool (optional; called from the
+         * tools inject so the registry is guaranteed present). */
+        registerListTool(tools) {
+            if (tools.register === undefined)
+                return;
+            tools.register(defineTool({
+                name: 'list_capabilities',
+                description: 'List the capabilities (skills and tools) registered in this instance and their source channels. Call to discover what is available.',
+                parameters: {
+                    kind: {
+                        type: 'string',
+                        enum: ['skill', 'tool'],
+                        description: 'Optional: filter to skills or tools.',
+                    },
+                },
+                output: {
+                    schema: { type: 'string' },
+                    render: (_args, value) => [{ type: 'text', text: String(value) }],
+                },
+                // Arrow captures `this` so the tool can read the live registries. It runs
+                // in the caller agent's scope (exec.agent), so it sees the model's actual
+                // view: official, plugin and user/project skills alike.
+                execute: async (args, exec) => {
+                    const { registry } = resolveServicesHelper(this.ctx);
+                    if (registry === undefined)
+                        return 'skills service absent in this composition';
+                    // The FULL face is fingerprinted even when the answer is filtered:
+                    // `sha` names the instance's capabilities, so it must not change with
+                    // what the caller asked to see.
+                    const scope = exec?.agent ?? await this.catalogScope();
+                    const snapshot = await catalogSnapshot(undefined, registry, this.toolSchemasIn(scope), this.mcpServerNamesIn(scope), this.appearedAfterApply, [scope], this.toolOriginsMap(scope), { fingerprint: true });
+                    const filter = args?.kind;
+                    const skills = filter === undefined || filter === 'skill' ? snapshot.skills : [];
+                    const toolsRows = filter === undefined || filter === 'tool' ? snapshot.tools : [];
+                    return JSON.stringify({ capabilities: capsTag(snapshot.sha), skills, tools: toolsRows }, null, 2);
+                },
+            }));
+        }
+        async snapshot(workdir) {
+            return this.collect(undefined, workdir, false);
+        }
+        /**
+         * The capability face of ONE mode as a LISTING — {@link snapshot} scoped to a
+         * named preset, for the settings surface's mode picker.
+         *
+         * The LISTING/FINGERPRINT split matters here the way it does everywhere else:
+         * a viewer wants rows as fast as the registries can produce them, not every
+         * skill body loaded and digested. Asking for a preset's IDENTITY is
+         * {@link snapshotFor}. Like every scope resolution, this MOUNTS a preset
+         * nothing has composed yet.
+         *
+         * Degrades like {@link snapshot}: a preset whose standing scope refuses
+         * answers with the global layer and NO `preset` stamp, which is how a caller
+         * tells "this mode" from "the fallback" and says so.
+         * @param presetId - the mode to read, or undefined for the deployment default.
+         * @param workdir - optional cwd for project-scoped skill roots.
+         */
+        async snapshotAt(presetId, workdir) {
+            return this.collect(presetId, workdir, false);
+        }
+        /**
+         * The capability face of ONE preset, with its {@link hashOf} digest.
+         *
+         * This is the fingerprint verb: every skill body is loaded (so the rows
+         * carry `bodySha`) and `sha` is stamped, which is what makes the answer an
+         * identity rather than a listing. `presetId` omitted reads the deployment
+         * default — the same face `snapshot` reads, now hashable.
+         *
+         * Degrades like every other verb: without a skills registry the answer is
+         * an empty face with the hash of an empty face, not a throw. Note that a
+         * preset nobody has composed yet is MOUNTED by the read (the roster's
+         * single-flight standing mount), so asking is not free.
+         * @param presetId - the preset to fingerprint, or undefined for the default.
+         * @param workdir - optional cwd for project-scoped skill roots.
+         */
+        async snapshotFor(presetId, workdir) {
+            return this.collect(presetId, workdir, true);
+        }
+        /**
+         * Shared body of {@link snapshot} and {@link snapshotFor}. The scope is
+         * resolved ONCE — three resolutions of a mounting preset would race the
+         * roster's single-flight for no reason — and `fingerprint` makes the
+         * resolution strict.
+         */
+        async collect(presetId, workdir, fingerprint) {
+            const { registry } = resolveServicesHelper(this.ctx);
+            if (workdir !== undefined && workdir !== '')
+                this.observedWorkdir = workdir;
+            // The scope may be LEASED (rc.1 roster): every read below must finish
+            // before the release, so the whole body sits in one try.
+            const { scope, preset, dispose } = await resolvePresetScope(this.agentPresets(), presetId, fingerprint);
+            try {
+                if (registry === undefined) {
+                    const empty = {
+                        skills: [], tools: [], mcpServers: [], channels: [],
+                        ...preset !== undefined ? { preset } : {},
+                    };
+                    return fingerprint ? { ...empty, sha: hashOf(empty) } : empty;
+                }
+                return await catalogSnapshot(workdir, registry, this.toolSchemasIn(scope), this.mcpServerNamesIn(scope), this.appearedAfterApply, [scope], this.toolOriginsMap(scope), { fingerprint, ...preset !== undefined ? { preset } : {} });
+            }
+            finally {
+                await this.releaseScope(dispose);
+            }
+        }
+        async detail(name, workdir, presetId) {
+            const { registry } = resolveServicesHelper(this.ctx);
+            if (registry === undefined)
+                return undefined;
+            // A managed skill scoped to another preset is absent from the default
+            // preset's scope; the plugin's own copy keeps it visible and editable here.
+            // `presetId` carries the mode the viewer is LOOKING AT, so a card opened in
+            // mode X reads mode X's body rather than the default mode's.
+            return catalogDetail(this.ctx, registry, name, workdir, await this.catalogScope(presetId), await this.managedDefinition(name));
+        }
+        async readSkillFile(name, filePath, workdir, presetId) {
+            const { registry } = resolveServicesHelper(this.ctx);
+            if (registry === undefined)
+                return undefined;
+            return catalogReadSkillFile(registry, name, filePath, workdir, await this.catalogScope(presetId), await this.managedDefinition(name));
+        }
+        /** One managed skill's definition, for management reads outside its scope. */
+        async managedDefinition(name) {
+            const skill = (await scanManagedSkills(scopedSkillsRoot(this.dshHome()))).find(entry => entry.name === name);
+            return skill === undefined ? undefined : definitionFor(skill);
+        }
+        async listDirSkills(dirPath) {
+            return catalogListDirSkills(dirPath);
+        }
+        async setCredential(request) {
+            return catalogSetCredential(this.ctx, request);
+        }
+        async addSkill(request) {
+            return catalogAddSkill(this.ctx, request, this.dshHome());
+        }
+        async deleteSkill(name, workdir, presetId) {
+            const { registry } = resolveServicesHelper(this.ctx);
+            if (registry === undefined)
+                return { ok: false, error: 'skills service absent in this composition' };
+            return catalogDeleteSkill(registry, name, workdir, await this.catalogScope(presetId));
+        }
+        async pickDirectory() {
+            return catalogPickDirectory(this.ctx);
+        }
+        async mcpList() {
+            // Masked DTO: never surface secretRef markers (or the secret key names) to the browser.
+            return this.mcp.list().map(maskConfig);
+        }
+        async mcpAdd(config) {
+            if (config.serverName.trim() === '')
+                return false;
+            this.mcp.add(config);
+            this.afterMcpMutation();
+            return true;
+        }
+        async mcpRemove(serverName) {
+            this.mcp.remove(serverName);
+            this.afterMcpMutation();
+            return true;
+        }
+        async mcpSetEnabled(serverName, enabled) {
+            this.mcp.setEnabled(serverName, enabled);
+            this.afterMcpMutation();
+        }
+        async mcpSetCredential(ref, value) {
+            this.mcp.setCredential(ref, value);
+            return true;
+        }
+        async mcpSetToolEnabled(serverName, tool, enabled) {
+            this.mcp.setToolEnabled(serverName, tool, enabled);
+            this.afterMcpMutation();
+        }
+        async mcpDiscover(serverName) {
+            const tools = await this.mcp.discover(serverName);
+            this.afterMcpMutation();
+            return tools;
+        }
+        async mcpSnapshot() {
+            return {
+                servers: this.mcp.list().map(maskConfig),
+                tools: this.mcp.toolsByServer(),
+                credentials: this.mcp.credentials(),
+            };
+        }
+        /** The visible tool schemas in the standing scope (the set the model sees),
+         * or the global layer when no preset standing key resolves. Skills already
+         * enumerate through the same scope; tools must use it too so the
+         * settings reader sees the official/plugin/MCP tools the model actually has. */
+        toolSchemasIn(scope) {
+            const tools = this.ctx.get?.('tools');
+            if (tools?.schemas === undefined)
+                return [];
+            return scope === undefined ? tools.schemas() : tools.schemas(scope);
+        }
+        /** tool name → author-declared origin, read via `ctx.tools.get(name)` so the
+         * `Symbol.for('dsh.tool.origin')` tag on the retained definition survives (the
+         * system-prompt assembly strips it, but `get()` returns the full definition). */
+        toolOriginsMap(scope) {
+            const tools = this.ctx.get?.('tools');
+            if (tools?.get === undefined)
+                return new Map();
+            const schemas = scope === undefined ? tools.schemas() : tools.schemas(scope);
+            const out = new Map();
+            for (const schema of schemas) {
+                const def = scope === undefined ? tools.get(schema.name) : tools.get(schema.name, scope);
+                if (def === undefined) {
+                    // `schemas()` and `get()` disagree for this scope — the author's origin
+                    // tag (if any) cannot be read, so the tool falls back to heuristics.
+                    this.ctx.logger.warn(`capability-catalog: tool "${schema.name}" is visible but ctx.tools.get() is undefined in this scope — its origin tag cannot be read; it will be classified by heuristics`);
+                    continue;
+                }
+                const origin = toolOrigin(def);
+                if (origin !== undefined) {
+                    if (!isValidOrigin(origin)) {
+                        this.ctx.logger.warn(`capability-catalog: tool "${schema.name}" origin channel "${String(origin.channel)}" is not a known channel (plugin/builtin/mcp) — ignoring the tag, falling back to heuristics`);
+                        continue;
+                    }
+                    out.set(schema.name, origin);
+                }
+            }
+            return out;
+        }
+        /** MCP server names from live `mcp__`-prefixed tools (prefix-derived baseline). */
+        mcpServerNamesIn(scope) {
+            const names = [];
+            for (const schema of this.toolSchemasIn(scope)) {
+                if (!schema.name.startsWith(MCP_TOOL_PREFIX))
+                    continue;
+                const rest = schema.name.slice(MCP_TOOL_PREFIX.length);
+                const sep = rest.indexOf('__');
+                const server = sep > 0 ? rest.slice(0, sep) : rest;
+                if (server.length > 0 && !names.includes(server))
+                    names.push(server);
+            }
+            return names;
+        }
+        /**
+         * Reconcile which discovered MCP tools are registered on `ctx.tools` so the
+         * model can call them. `mcpToolsRegistry` is the traceable `ctx.tools` proxy,
+         * so `register` is always invoked as a MEMBER call (`reconcile` calls
+         * `registry.register(...)`) — extracting it to a standalone variable loses the
+         * `this.ctx` binding and breaks the disposal effect.
+         */
+        syncRegisteredMcpTools() {
+            const registry = this.mcpToolsRegistry;
+            if (registry === undefined)
+                return;
+            const desired = desiredMcpTools(this.mcp.list(), this.mcp.toolsByServer());
+            reconcileRegisteredMcpTools(desired, {
+                register: (definition) => registry.register(definition),
+                onRegisterError: (error) => this.ctx.logger.error(`capability-catalog: MCP tool registration failed: ${String(error)}`),
+            }, this.mcpToolDisposers, (serverName, rawName, args) => this.mcp.callTool(serverName, rawName, args));
+        }
+        /** Re-sync registered MCP tools after any MCP store mutation. */
+        afterMcpMutation() {
+            this.syncRegisteredMcpTools();
+        }
+        /** Refill the persisted MCP tools' descriptions/parameters by re-connecting the
+         * enabled servers at boot (the persisted `mcp` block stores only name+enabled to
+         * keep settings.yaml small). Async: boot is not blocked; each server's errors are
+         * contained, and registration is re-synced once the descriptions are back. */
+        async reconnectEnabledMcp() {
+            const enabled = this.mcp.list().filter(s => s.enabled);
+            if (enabled.length === 0)
+                return;
+            for (const server of enabled) {
+                try {
+                    await this.mcp.discover(server.serverName);
+                }
+                catch (error) {
+                    this.ctx.logger.error(`capability-catalog: reconnect ${server.serverName} failed: ${String(error)}`);
+                }
+            }
+            this.syncRegisteredMcpTools();
+        }
+    };
+})();
+export { CapabilityCatalogService };
+export default CapabilityCatalogService;