@khorsheed/dsh-capability-catalog 0.1.97 → 0.1.99

package/lib/types/index.js

@@ -51,6 +51,7 @@ 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 { toolSchemasFacing, toolOriginsFacing, mcpServerNamesFacing } from './tool-face.js';
 import { definitionFor, scanManagedSkills, ScopedSkillDelivery, scopedSkillsRoot, } from './scoped-delivery.js';
 import { adoptManagedSkill, releaseManagedSkill, setManagedPresetScope, } from './scoped-edits.js';
 import { installSkillEnvInjection } from './shellEnv.js';
@@ -58,8 +59,6 @@ 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';
@@ -72,12 +71,20 @@ 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 { ScopedSkillDelivery, scopedSkillsRoot, scanManagedSkills, managedSkillFrom, 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';
+// Capability-composition EVIDENCE: the pure-data production face a target
+// side runs where the composition lives. It reuses this package's own
+// snapshot/digest algorithms (parity by construction), mounts no standing
+// scope, registers no service, and returns plain JSON-safe data: the digest,
+// the per-section completeness, the measurement object, and the caller's
+// coverage declaration. Consumers never recompute the digest and never treat
+// a partial/unavailable section as verified.
+export { produceCapabilityEvidence } from './evidence.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. */
@@ -107,7 +114,6 @@ let CapabilityCatalogService = (() => {
     let _addSkill_decorators;
     let _deleteSkill_decorators;
     let _pickDirectory_decorators;
-    let _mcpList_decorators;
     let _mcpAdd_decorators;
     let _mcpRemove_decorators;
     let _mcpSetEnabled_decorators;
@@ -134,7 +140,6 @@ let CapabilityCatalogService = (() => {
             _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')];
@@ -158,7 +163,6 @@ let CapabilityCatalogService = (() => {
             __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);
@@ -278,7 +282,7 @@ let CapabilityCatalogService = (() => {
             // 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());
+                installSkillEnvInjection(ctx, () => this.catalogScope(), () => this.dshHome());
             });
             // Runtime companion hint (generic): when the skill tool loads a skill,
             // tell the model the configured credential env mappings so it uses the
@@ -402,18 +406,26 @@ let CapabilityCatalogService = (() => {
         /** 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 tools = this.toolsRegistry();
             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`. */
+        /**
+         * The managed skills root under the harness home. Mirrors the official
+         * precedence (`resolveDshHome` in `@deepseek-ai/dsh-home-paths`):
+         * the settings service's home, then a non-blank `$DSH_HOME`, then the
+         * `~/.dsh` installation default. The fallback was once hardcoded to
+         * `.dsh-official`, which silently pointed a desktop instance (no settings
+         * home, no env) at ANOTHER instance's managed skills (2026-09-30).
+         */
         dshHome() {
             const settings = this.ctx.get?.('settings');
-            const home = settings?.home;
-            return home ?? process.env.DSH_HOME ?? join(homedir(), '.dsh-official');
+            const fromEnv = process.env.DSH_HOME;
+            const envHome = fromEnv !== undefined && fromEnv.trim().length > 0 ? fromEnv : undefined;
+            return settings?.home ?? envHome ?? join(homedir(), '.dsh');
         }
         /**
          * The standing skill view scope of ONE preset. In the web bundle the
@@ -602,10 +614,6 @@ let CapabilityCatalogService = (() => {
         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;
@@ -642,57 +650,28 @@ let CapabilityCatalogService = (() => {
                 credentials: this.mcp.credentials(),
             };
         }
+        /** The live tools registry, when the composition provides one. */
+        toolsRegistry() {
+            return this.ctx.get?.('tools');
+        }
         /** 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);
+            return toolSchemasFacing(this.toolsRegistry(), 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;
+            const tools = this.toolsRegistry();
+            const { origins } = toolOriginsFacing(tools, toolSchemasFacing(tools, scope), scope, (message) => this.ctx.logger.warn(message));
+            return origins;
         }
         /** 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;
+            return mcpServerNamesFacing(this.toolSchemasIn(scope));
         }
         /**
          * Reconcile which discovered MCP tools are registered on `ctx.tools` so the

package/lib/types/mcpStore.d.ts

@@ -8,7 +8,8 @@
 import type { CatalogMcpCredentialDecl, CatalogMcpServerConfig, CatalogMcpTool } from './types.ts';
 /** One tool's persisted record: the user's toggle choice only. Descriptions and
  * parameter schemas are discovered at connect time and deliberately NOT persisted
- * (they bloat settings.yaml and go stale); `reconnectAll` re-fills them at boot. */
+ * (they bloat settings.yaml and go stale); the service re-fills them at boot by
+ * re-connecting the enabled servers. */
 export interface PersistedMcpTool {
     readonly name: string;
     readonly enabled: boolean;
@@ -50,15 +51,12 @@ export declare class McpStore {
     setToolEnabled(serverName: string, toolName: string, enabled: boolean): void;
     /** Connect + discover tools for a server; caches the list (connect errors surface). */
     discover(serverName: string): Promise<readonly CatalogMcpTool[]>;
-    /** Re-connect + re-discover every enabled server — boot-time refill of the
-     * discovered descriptions/parameters (the persisted block stores only
-     * name+enabled). Preserves per-tool enable flags; per-server errors are
-     * recorded and do not stop the others. */
-    reconnectAll(): Promise<void>;
-    /** A server's most recent connection/dev error. */
-    errorOf(serverName: string): string | undefined;
     /** Forward one tool call to a server (connect → call → close). Resolves secrets. */
     callTool(serverName: string, rawName: string, args: Record<string, unknown>): Promise<unknown>;
+    /** The `resolveConfigSecrets` callback for one server: a bare secret ref
+     * resolves to the stored credential under the server's env/header/query
+     * namespace (the same namespaces {@link credentialRefsOf} writes). */
+    private secretResolver;
     /** Extract credential reference paths from a config (env/header/url-query).
      * Namespaced `mcp.<serverName>.env.<KEY>` so multiple servers don't collide. */
     private credentialRefsOf;

package/lib/types/mcpStore.js

@@ -32,7 +32,6 @@ export class McpStore {
                 config: server.config,
                 credentials: existing?.credentials ?? new Map(),
                 tools,
-                error: undefined,
             });
         }
         for (const [ref, value] of Object.entries(state.credentials ?? {})) {
@@ -83,7 +82,6 @@ export class McpStore {
             config,
             credentials: existing?.credentials ?? new Map(),
             tools: existing?.tools ?? [],
-            error: existing?.error,
         });
         this.persist();
     }
@@ -130,56 +128,41 @@ export class McpStore {
             const { connectMcpServer } = await import('./mcpConnector.js');
             // Resolve secretRef markers to the stored credential values before connecting,
             // so a configured API key is sent as its real value (never the secretRef).
-            const resolved = await resolveConfigSecrets(s.config, async (ref) => {
-                const candidates = [
-                    `mcp.${serverName}.env.${ref}`,
-                    `mcp.${serverName}.header.${ref}`,
-                    `mcp.${serverName}.query.${ref}`,
-                ];
-                for (const candidate of candidates) {
-                    const value = s.credentials.get(candidate);
-                    if (value !== undefined)
-                        return value;
-                }
-                return undefined;
-            });
+            const resolved = await resolveConfigSecrets(s.config, this.secretResolver(serverName, s));
             const connection = await connectMcpServer(resolved);
             // Preserve the user's per-tool enable flags — re-discovering refreshes
             // descriptions/parameters without resetting toggles (new tools default on).
             const prevEnabled = new Map(s.tools.map(t => [t.name, t.enabled]));
             s.tools = connection.tools.map(t => ({ ...t, enabled: prevEnabled.get(t.name) ?? true }));
-            s.error = undefined;
             await connection.close();
             this.persist();
             return s.tools;
         }
-        catch (error) {
-            s.error = String(error);
+        catch {
             this.persist();
             return s.tools;
         }
     }
-    /** Re-connect + re-discover every enabled server — boot-time refill of the
-     * discovered descriptions/parameters (the persisted block stores only
-     * name+enabled). Preserves per-tool enable flags; per-server errors are
-     * recorded and do not stop the others. */
-    async reconnectAll() {
-        for (const server of this.list()) {
-            if (!server.enabled)
-                continue;
-            await this.discover(server.serverName);
-        }
-    }
-    /** A server's most recent connection/dev error. */
-    errorOf(serverName) {
-        return this.servers.get(serverName)?.error;
-    }
     /** Forward one tool call to a server (connect → call → close). Resolves secrets. */
     async callTool(serverName, rawName, args) {
         const s = this.servers.get(serverName);
         if (s === undefined)
             throw new Error(`unknown MCP server: ${serverName}`);
-        const resolved = await resolveConfigSecrets(s.config, async (ref) => {
+        const resolved = await resolveConfigSecrets(s.config, this.secretResolver(serverName, s));
+        const { connectMcpServer } = await import('./mcpConnector.js');
+        const connection = await connectMcpServer(resolved);
+        try {
+            return await connection.call(rawName, args);
+        }
+        finally {
+            await connection.close();
+        }
+    }
+    /** The `resolveConfigSecrets` callback for one server: a bare secret ref
+     * resolves to the stored credential under the server's env/header/query
+     * namespace (the same namespaces {@link credentialRefsOf} writes). */
+    secretResolver(serverName, s) {
+        return async (ref) => {
             const candidates = [
                 `mcp.${serverName}.env.${ref}`,
                 `mcp.${serverName}.header.${ref}`,
@@ -191,15 +174,7 @@ export class McpStore {
                     return value;
             }
             return undefined;
-        });
-        const { connectMcpServer } = await import('./mcpConnector.js');
-        const connection = await connectMcpServer(resolved);
-        try {
-            return await connection.call(rawName, args);
-        }
-        finally {
-            await connection.close();
-        }
+        };
     }
     /** Extract credential reference paths from a config (env/header/url-query).
      * Namespaced `mcp.<serverName>.env.<KEY>` so multiple servers don't collide. */

package/lib/types/mcps.d.ts

@@ -10,7 +10,7 @@
  * the catalog's own thin client).
  * @module @khorsheed/dsh-capability-catalog/mcps
  */
-import type { CatalogJsonValue, CatalogMcpCredentialDecl, CatalogMcpServerConfig, CatalogMcpTool, McpTransport } from './types.ts';
+import type { CatalogJsonValue, CatalogMcpServerConfig, McpTransport } from './types.ts';
 /** Secret marker put in a config field whose value lives in the credential store. */
 export declare const SECRET_REF_PREFIX = "secretRef:";
 /** A parsed server from a pasted mcp.json server entry. */
@@ -41,15 +41,11 @@ export declare function maskSecret(value: string): string;
  * marker (bare or scheme-prefixed) with `·secretRef·`, so neither the secret key
  * name nor the marker is exposed to the browser. */
 export declare function maskConfig(config: CatalogMcpServerConfig): CatalogMcpServerConfig;
-/** Whether the config still has an unfilled credential (= prompts for it). */
-export declare function hasUnconfiguredCredentials(credentials: readonly CatalogMcpCredentialDecl[]): boolean;
 /** Resolve `secretRef:` markers in a config into plaintext before connecting
  * (the catalog resolves via the stored credential values, then connects).
  * Replaces embedded markers too, so a scheme-prefixed value (`Bearer secretRef:a`)
  * resolves to `Bearer <value>`. */
 export declare function resolveConfigSecrets(config: CatalogMcpServerConfig, resolve: (ref: string) => Promise<string | undefined>): Promise<CatalogMcpServerConfig>;
-/** Sort tools by name and default each to enabled. */
-export declare function finalizeTools(tools: readonly CatalogMcpTool[]): CatalogMcpTool[];
 /**
  * Map each bare secret config key (env/header name, or a query param) to its
  * catalog-stored, namespaced credential ref (`mcp.<server>.<kind>.<key>`). The
@@ -59,6 +55,5 @@ export declare function finalizeTools(tools: readonly CatalogMcpTool[]): Catalog
  * next snapshot round-trips the namespaced refs.
  */
 export declare function credentialStoredRefs(serverName: string, config: CatalogMcpServerConfig): Readonly<Record<string, string>>;
-export { SECRET_REF_PREFIX as _SECRET_REF_PREFIX };
 export type { CatalogJsonValue };
 //# sourceMappingURL=mcps.d.ts.map

package/lib/types/mcps.js

@@ -92,10 +92,6 @@ export function maskConfig(config) {
         ...(url !== undefined ? { url } : {}),
     };
 }
-/** Whether the config still has an unfilled credential (= prompts for it). */
-export function hasUnconfiguredCredentials(credentials) {
-    return credentials.some(c => !c.configured);
-}
 /** Resolve `secretRef:` markers in a config into plaintext before connecting
  * (the catalog resolves via the stored credential values, then connects).
  * Replaces embedded markers too, so a scheme-prefixed value (`Bearer secretRef:a`)
@@ -124,10 +120,6 @@ export async function resolveConfigSecrets(config, resolve) {
         ...(url !== undefined ? { url } : {}),
     };
 }
-/** Sort tools by name and default each to enabled. */
-export function finalizeTools(tools) {
-    return [...tools].sort((a, b) => a.name.localeCompare(b.name));
-}
 /**
  * Map each bare secret config key (env/header name, or a query param) to its
  * catalog-stored, namespaced credential ref (`mcp.<server>.<kind>.<key>`). The
@@ -154,4 +146,3 @@ export function credentialStoredRefs(serverName, config) {
     }
     return out;
 }
-export { SECRET_REF_PREFIX as _SECRET_REF_PREFIX }; // re-export for tests if needed

package/lib/types/namespace.d.ts

@@ -1,8 +1,7 @@
 /**
  * The settings namespace owned by the capability-catalog plugin. Plain string
- * so both the host half (settings registration) and the browser half (the
- * settings.plugin.item card key) import it without dragging host-only
- * dependencies into the client bundle.
+ * so both the host half (settings registration) and the browser half import
+ * it without dragging host-only dependencies into the client bundle.
  */
 /** Settings namespace owned by the capability-catalog plugin. */
 export declare const CAPABILITY_CATALOG_NS = "capability-catalog";

package/lib/types/namespace.js

@@ -1,8 +1,7 @@
 /**
  * The settings namespace owned by the capability-catalog plugin. Plain string
- * so both the host half (settings registration) and the browser half (the
- * settings.plugin.item card key) import it without dragging host-only
- * dependencies into the client bundle.
+ * so both the host half (settings registration) and the browser half import
+ * it without dragging host-only dependencies into the client bundle.
  */
 /** Settings namespace owned by the capability-catalog plugin. */
 export const CAPABILITY_CATALOG_NS = 'capability-catalog';

package/lib/types/remote.d.ts

@@ -6,10 +6,10 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { CapabilityCatalogSnapshot, CatalogAddSkillRequest, CatalogAddSkillResult, CatalogCredentialSetRequest, CatalogDeleteSkillResult, CatalogDirSkillInfo, CatalogJsonValue, CatalogSkillDetail, CatalogSkillFileRead, CatalogToolRow } from './types.ts';
-import { type CredentialsSlice, type RegistrySlice, type SkillDefinitionLike } from './skills.ts';
+import { type CredentialsSlice, type RegistrySlice, type SkillDefinitionLike, type SkillsCollectionReport } from './skills.ts';
 import type { ToolOrigin } from './tool-origin.ts';
 import { resolveSkillNameFromContent } from './import.ts';
-export type { CredentialsSlice, RegistrySlice };
+export type { CredentialsSlice, RegistrySlice, SkillsCollectionReport };
 /** Project visible tools onto catalog rows with channel attribution. */
 export declare function projectTools(schemas: readonly ToolSchemaLike[], mcpServers: readonly string[], appearedAfterApply: Set<string>, toolOrigins?: ReadonlyMap<string, ToolOrigin>): CatalogToolRow[];
 /** Minimal ToolSchema shape (model-facing name/description/parameters). */
@@ -18,6 +18,14 @@ interface ToolSchemaLike {
     readonly description?: string;
     readonly parameters?: CatalogJsonValue;
 }
+/**
+ * Out-bag a snapshot caller may pass to receive the collection health the
+ * rows were gathered with. Evidence production reads it to build the
+ * per-section completeness descriptors; the Remote verbs never pass one.
+ */
+export interface CatalogSnapshotReport {
+    skills?: SkillsCollectionReport;
+}
 /**
  * Build the full catalog snapshot (skills + tools).
  *
@@ -29,6 +37,7 @@ interface ToolSchemaLike {
 export declare function catalogSnapshot(workdir: string | undefined, registry: RegistrySlice, toolsSchemas: readonly ToolSchemaLike[], mcpServers: readonly string[], appearedAfterApply: ReadonlySet<string>, scopes?: readonly unknown[], toolOrigins?: ReadonlyMap<string, ToolOrigin>, options?: {
     fingerprint?: boolean;
     preset?: string;
+    report?: CatalogSnapshotReport;
 }): Promise<CapabilityCatalogSnapshot>;
 /** Load one skill detail. */
 export declare function catalogDetail(ctx: Context, registry: RegistrySlice, name: string, workdir: string | undefined, scope?: unknown, fallback?: SkillDefinitionLike): Promise<CatalogSkillDetail | undefined>;

package/lib/types/remote.js

@@ -41,7 +41,10 @@ export function projectTools(schemas, mcpServers, appearedAfterApply, toolOrigin
  */
 export async function catalogSnapshot(workdir, registry, toolsSchemas, mcpServers, appearedAfterApply, scopes = [undefined], toolOrigins = new Map(), options = {}) {
     const fingerprint = options.fingerprint === true;
-    const base = await collectSkills(registry, workdir, scopes, { bodySha: fingerprint });
+    const skillsReport = { attemptedScopes: 0, failedScopes: 0, incompleteReads: 0, unreadableBodies: 0 };
+    const base = await collectSkills(registry, workdir, scopes, { bodySha: fingerprint, report: skillsReport });
+    if (options.report !== undefined)
+        options.report.skills = skillsReport;
     const tools = projectTools(toolsSchemas, mcpServers, appearedAfterApply, toolOrigins);
     const snapshot = {
         skills: base.skills,

package/lib/types/scoped-delivery.d.ts

@@ -57,6 +57,8 @@ export interface ManagedSkill {
     readonly userInvocable: boolean;
     /** Preset ids this skill is delivered to; absent/empty means "not scoped". */
     readonly presetScope: readonly string[] | undefined;
+    /** The frontmatter's full `metadata:` block, preserved verbatim when parseable. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
     /** The skill's own directory (its `resourceBase`). */
     readonly dir: string;
     /** Absolute `SKILL.md` path. */
@@ -115,31 +117,15 @@ export interface ScopedDeliveryDeps {
 export interface ScopedDeliveryRegistry {
     readonly registerProvider?: (create: (control: SkillProviderControl) => SkillProvider) => () => void;
 }
-/**
- * Read the `presetScope` list out of a frontmatter block.
- *
- * Accepted forms, at any indentation (the canonical one is
- * `metadata.presetScope`):
- *
- * ```yaml
- * metadata:
- *   presetScope: [dsh-writing, dev]
- *   presetScope:
- *     - dsh-writing
- * ```
- * @param front - the frontmatter text without its `---` fences.
- * @returns the declared ids, or undefined when the key is absent.
- */
-export declare function parsePresetScopeFrontmatter(front: string): readonly string[] | undefined;
-/** Whether a string is a usable skill / preset id. */
-export declare function isKebabId(value: string): boolean;
-/** Split a SKILL.md into its frontmatter block and body. */
-export declare function splitFrontmatter(content: string): {
-    front: string;
-    body: string;
-} | undefined;
 /**
  * Parse one managed `SKILL.md` into its delivery record.
+ *
+ * The frontmatter is ONE real-YAML parse (see `./frontmatter.ts`): name and
+ * description read top-level only, the invocation flags accept the host
+ * loader's boolean variants, and the scope list comes from the canonical
+ * `metadata.presetScope` (falling back to a legacy top-level key). A malformed
+ * `metadata:` block degrades to no-metadata — the skill still delivers —
+ * rather than rejecting a file the rest of the block could still serve.
  * @param content - the file text.
  * @param dir - the skill's directory (its resource base).
  * @param path - the absolute `SKILL.md` path.
@@ -194,6 +180,9 @@ export declare class ScopedSkillDelivery {
     private failure;
     private started;
     private disposed;
+    /** Reconcile gate: one pass in flight, one queued rerun (see reconcile). */
+    private reconcileInFlight;
+    private reconcileQueued;
     /** The probed registry's mount list (undefined until start()'s probe resolves). */
     private presetMounts;
     /**
@@ -203,8 +192,22 @@ export declare class ScopedSkillDelivery {
     constructor(ctx: Context, deps: ScopedDeliveryDeps);
     /** Start watching the managed root and deliver what it currently holds. */
     start(): Promise<void>;
-    /** Re-read policy and files, then converge the delivery registrations. */
+    /**
+     * Re-read policy and files, then converge the delivery registrations.
+     *
+     * Triggers arrive concurrently — the filesystem watcher, the
+     * `agent-preset/selected` event, and the management Remotes — and two
+     * overlapping passes can both decide a preset has no registration and each
+     * register one, leaving two same-named providers serving one preset. The
+     * gate allows ONE pass in flight and coalesces every trigger that arrives
+     * during it into ONE queued rerun (the pass re-reads policy and files from
+     * scratch, so a rerun loses no update). A caller that finds a pass in
+     * flight waits for the chain its flag provoked, so an awaited reconcile
+     * still reflects the write that triggered it.
+     */
     reconcile(): Promise<void>;
+    /** One reconcile pass (call only through {@link reconcile}'s gate). */
+    private reconcileNow;
     /** The current status, for the settings surface and the model-facing tool. */
     status(): ScopedDeliveryStatus;
     /** Stop watching and dispose every delivery registration. */
@@ -233,6 +236,13 @@ export declare class ScopedSkillDelivery {
     private providerFor;
     /** The managed skills one delivery currently serves. */
     private skillsFor;
+    /** The managed skills readable through one preset's reader: its own scoped
+     * delivery plus the unscoped ones every preset sees through the global layer. */
+    private readableFor;
+    /** The read-only bundle-file reader served with one preset's delivery. */
+    private bundleFileTool;
+    /** Serve one bundle file (or the bundle's file list) to a delivered skill's caller. */
+    private readBundleFile;
     /** Invalidate every registration's completed catalogs. */
     private invalidateAll;
     /** Dispose every registration. */
@@ -240,4 +250,6 @@ export declare class ScopedSkillDelivery {
     /** Dispose one registration and forget it. */
     private dropEntry;
 }
+/** The scoped bundle-file reader's tool name. */
+export declare const READ_SKILL_FILE_TOOL = "read_skill_file";
 //# sourceMappingURL=scoped-delivery.d.ts.map