dsh-agent-plugins-market 0.7.0 → 0.7.1

package/lib/runtime/tool-registry-observer.js

@@ -1,31 +1,27 @@
-/** Host-private adapter for observing model-facing MCP tools. */
+/** Reading the model-facing MCP tools the host registry currently exposes. */
 /**
- * Read MCP tool names from the dsh-tools runtime when available.
+ * The MCP tools the host currently publishes to the model.
  *
- * The registry has no public listing API in the current host release. This
- * adapter uses the observed `layers.merge(...).tools.entries()` data shape and
- * returns an empty observation when a host changes it.
+ * Read through the tools service's own listing API rather than its internal
+ * layer structure. `schemas()` deep-clones each tool's parameter schema, which
+ * this snapshot has no use for, so a failure inside it degrades to an empty
+ * observation instead of taking the status surface down.
+ * @param tools - the host tools service, when it is mounted.
+ * @returns one entry per `mcp__`-namespaced tool.
  */
-export function inspectToolRegistry(runtime) {
-    if (typeof runtime !== 'object' || runtime === null)
+export function inspectToolRegistry(tools) {
+    const service = tools;
+    if (service === undefined || typeof service !== 'object' || service === null)
         return [];
-    const layers = runtime.layers;
-    if (typeof layers !== 'object' || layers === null)
+    if (typeof service.schemas !== 'function')
         return [];
-    const merge = layers.merge;
-    if (typeof merge !== 'function')
-        return [];
-    const empty = { entries: () => [] };
     try {
-        const visible = merge.call(layers, undefined, layer => layer.tools ?? empty);
         const output = [];
-        for (const [name, definition] of visible.entries()) {
-            if (!name.startsWith('mcp__'))
+        for (const schema of service.schemas()) {
+            if (!schema.name.startsWith('mcp__'))
                 continue;
-            const description = typeof definition === 'object' && definition !== null && typeof definition.description === 'string'
-                ? definition.description
-                : undefined;
-            output.push({ name, ...(description === undefined ? {} : { description }) });
+            const description = typeof schema.description === 'string' ? schema.description : undefined;
+            output.push({ name: schema.name, ...(description === undefined ? {} : { description }) });
         }
         return output;
     }
@@ -33,3 +29,7 @@ export function inspectToolRegistry(runtime) {
         return [];
     }
 }
+/** Read the tools service off the plugin context, when the host mounts one. */
+export function toolsServiceOf(ctx) {
+    return ctx.get?.('tools');
+}

package/lib/runtime/user-commands.js

@@ -6,6 +6,7 @@
  * change, keyed `user/<name>`.
  * @module runtime/user-commands
  */
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { USER_ENTRY_NAME } from './user-store.js';
 /** Register/unregister user-panel commands to match the panel's enabled entries. */
 export class UserCommandMountRegistry {
@@ -63,7 +64,10 @@ export class UserCommandMountRegistry {
                     handler: invocation => {
                         const agent = invocation.agent;
                         const text = spec.body.replaceAll('$ARGUMENTS', invocation.rawInput.trim());
-                        agent.followup({ content: [{ type: 'text', text }], source: { kind: 'plugin', plugin: 'dsh-agent-plugins-market' } });
+                        agent.followup(createUserMessage({
+                            content: [{ type: 'text', text }],
+                            source: { kind: 'plugin', plugin: 'dsh-agent-plugins-market' }
+                        }));
                         return { kind: 'success', text: this.t('commandAcknowledged', { command: spec.name }) };
                     }
                 });

package/lib/runtime/user-panels.js

@@ -1,9 +1,9 @@
 /**
  * User panel storage: the persistence layer behind the skills / commands /
- * agent-personas panels. Each surface owns one directory of Markdown files
- * under the shared Agent layout root (`~/.agents/<kind>/`), so user-authored
- * entries survive restarts, are trivially hand-editable, and stay outside
- * suite checkouts.
+ * agent-personas panels. Each surface owns one directory of Markdown
+ * documents under the shared Agent layout root (`~/.agents/<kind>/`), so
+ * user-authored entries survive restarts, are trivially hand-editable, and
+ * stay outside suite checkouts.
  *
  * Skills entries follow the SKILL.md frontmatter grammar (`name`,
  * `description`, optional `whenToUse`, invocation controls) plus a
@@ -11,37 +11,52 @@
  * frontmatter (`description`, optional `argument-hint`, `disabled`); agent
  * personas follow Claude Code agents frontmatter (`name`, `description`,
  * optional `whenToUse`, `tools`, `model`, `disabled`).
+ *
+ * Only the skills panel serves the cross-tool `<name>/SKILL.md` directory
+ * spelling beside its own flat entries; commands and personas stay flat.
+ *
+ * An entry's name is the one its document declares — the same name the
+ * harness reader derives from that file — and the panel addresses, edits, and
+ * deletes the entry by that name. A document that reader would reject is
+ * listed disabled with the reason instead of joining the catalog, and a skill
+ * is switched off by writing that reader's own invocation controls, so the off
+ * state lives in the file rather than in this provider.
  * @module runtime/user-panels
  */
-import { join } from 'node:path';
-import { deleteEntryFile, entryExists, listEntryFiles, readEntryFile, USER_ENTRY_NAME, userEntryDir, writeEntryFile } from './user-store.js';
+import { dirname } from 'node:path';
+import { skillEntryRejection } from '../catalog/skills-parse.js';
+import { deleteEntryDocument, entryExists, listEntryDocuments, listEntryFiles, readEntryDocument, resolveEntryDocument, SKILL_ENTRY_SHAPES, USER_ENTRY_NAME, userEntryDir, writeEntryDocument, writeEntryFile } from './user-store.js';
 /** The skill-source label user-panel entries carry into the skill registry. */
 export const USER_PANEL_SKILL_SOURCE = 'user-panel';
 /**
- * Panel skills outrank both the harness's reader of this directory and the
- * suite skills an install adds.
+ * Panel skills register ahead of the harness reader that maps this same
+ * directory (`dsh-skill-filesystem` roots `~/.agents/skills` as `user-agents`
+ * at rank 500), so the panel's localized description and its name precedence
+ * apply to the entries it serves. Project roots (100-300) and the user's
+ * `~/.dsh` skills (400) still outrank it, and it beats the suite user rank
+ * (450), so a skill the user wrote by hand wins over one an installed suite
+ * ships under the same name.
  *
- * `dsh-skill-filesystem` maps `~/.agents/skills` as its `user-agents` root at
- * rank 500, and a lower rank wins a duplicated skill name. Sitting behind it
- * handed every entry to that reader, which knows neither this panel's
- * `disabled` frontmatter nor its localized description, so a skill the user
- * disabled stayed loaded. At 440 the panel keeps its own controls; project
- * roots (100-300) and the user's `~/.dsh` skills (400) still outrank it, while
- * a skill the user wrote by hand now beats one an installed suite ships under
- * the same name (the suite user rank is 450).
+ * Switching a skill off is not this provider's job: the panel writes the
+ * harness's own invocation pair into the document, which every reader of that
+ * file honors.
  */
 const USER_PANEL_RANK = 440;
 /** Throwing CRUD over one panel directory, shared by the three panels. */
 export class UserPanelStore {
     agentsRoot;
     kind;
+    shapes;
     extraNameCheck;
-    constructor(agentsRoot, kind, 
-    /** Extra name grammar for this panel (runs after USER_ENTRY_NAME). */
-    extraNameCheck = () => true) {
+    validate;
+    honorInvocationControls;
+    constructor(agentsRoot, kind, options = {}) {
         this.agentsRoot = agentsRoot;
         this.kind = kind;
-        this.extraNameCheck = extraNameCheck;
+        this.shapes = options.shapes ?? ['file'];
+        this.extraNameCheck = options.extraNameCheck ?? (() => true);
+        this.validate = options.validate;
+        this.honorInvocationControls = options.honorInvocationControls === true;
     }
     /** The panel's directory under the Agent layout root. */
     dirPath() {
@@ -50,44 +65,79 @@ export class UserPanelStore {
     get dir() {
         return this.dirPath();
     }
+    validName(name) {
+        return USER_ENTRY_NAME.test(name) && this.extraNameCheck(name);
+    }
+    /**
+     * Resolve the document one entry name addresses. The name a panel entry
+     * carries is the one its document declares, which is only the file name by
+     * convention, so a name that matches no path is matched against the
+     * declared names of the served documents.
+     */
+    async document(name) {
+        const direct = await resolveEntryDocument(this.dir, name, this.shapes);
+        if (direct !== undefined)
+            return direct;
+        for (const candidate of await listEntryDocuments(this.dir, false, this.shapes)) {
+            const file = await readEntryDocument(candidate);
+            if (file?.name === name)
+                return candidate;
+        }
+        return undefined;
+    }
     /** Every entry, sorted by name; strict snapshots propagate temporary I/O failures. */
     async list(strict = false) {
-        const files = await listEntryFiles(this.dir, strict);
+        const files = await listEntryFiles(this.dir, strict, this.shapes);
         return files.map(file => this.serialize(file));
     }
     /** One entry's full record, including the raw file text. */
     async get(name) {
-        if (!USER_ENTRY_NAME.test(name))
-            return undefined;
-        const file = await readEntryFile(join(this.dir, `${name}.md`), name);
-        if (file === undefined)
+        const document = await this.document(name);
+        if (document === undefined)
             return undefined;
-        return this.serialize(file);
+        const file = await readEntryDocument(document);
+        return file === undefined ? undefined : this.serialize(file);
     }
     /**
      * Project one parsed file onto the wire shape. The description prefers the
      * strict frontmatter parse (multi-line YAML like `description: |` survives
      * intact there) and falls back to the shallow line record.
+     *
+     * A document the panel must not register stays listed and editable but reads
+     * as disabled with the reason in its metadata, the same shape an unparseable
+     * frontmatter already produced — hiding it would leave the user no way to
+     * find or fix it.
      */
     serialize(file) {
         const strictDescription = typeof file.description === 'string' && file.description !== '' ? file.description : undefined;
         const shallowDescription = typeof file.meta['description'] === 'string' && file.meta['description'] !== '' ? file.meta['description'] : '';
+        const parseError = typeof file.meta['validationError'] === 'string' ? file.meta['validationError'] : undefined;
+        const rejection = parseError ?? this.validate?.(file);
+        // Both invocation controls off is the panel's off state as well: the switch
+        // writes that pair, and either key alone is an authoring choice (a
+        // user-invocable-only skill, for instance) that stays switched on.
+        const invocationOff = this.honorInvocationControls && file.invocation !== undefined && !file.invocation.modelInvocable && !file.invocation.userInvocable;
         return {
-            name: file.fallbackName,
+            // The declared name is the entry's name; a document that declares none
+            // the registry would accept is listed under its own file name, which is
+            // the name that keeps it addressable and fixable. `path` carries the
+            // document either way.
+            name: rejection === undefined ? file.name : file.documentName,
             description: strictDescription ?? shallowDescription,
-            disabled: file.meta['disabled'] === true,
-            metadata: file.meta,
+            disabled: file.meta['disabled'] === true || invocationOff || rejection !== undefined,
+            metadata: rejection === undefined ? file.meta : { ...file.meta, disabled: true, validationError: rejection },
             path: file.file,
+            shape: file.shape,
             content: file.body,
             rawText: file.text,
             origin: 'user'
         };
     }
-    /** Create an entry; refuses an occupied name. */
+    /** Create an entry; refuses an occupied name. New entries use the flat spelling. */
     async create(name, text) {
-        if (!USER_ENTRY_NAME.test(name) || !this.extraNameCheck(name))
+        if (!this.validName(name))
             throw new Error(`invalid name "${name}" — use lowercase letters, digits, and dashes, starting with a letter or digit`);
-        if (await entryExists(this.dir, name))
+        if (await entryExists(this.dir, name, this.shapes))
             throw new Error(`an entry named "${name}" already exists`);
         await writeEntryFile(this.dir, name, text);
         const created = await this.get(name);
@@ -95,27 +145,36 @@ export class UserPanelStore {
             throw new Error(`entry "${name}" vanished after write`);
         return created;
     }
-    /** Replace one entry's file content wholesale. */
+    /** Replace one entry's content wholesale, keeping the spelling it already has. */
     async update(name, text) {
-        if (!USER_ENTRY_NAME.test(name) || !this.extraNameCheck(name))
+        if (!this.validName(name))
             throw new Error(`invalid entry name "${name}"`);
-        if (!(await entryExists(this.dir, name)))
+        const document = await this.document(name);
+        if (document === undefined)
             throw new Error(`no entry named "${name}"`);
-        await writeEntryFile(this.dir, name, text);
+        await writeEntryDocument(document, text);
     }
     /** Delete one entry; a missing file is a no-op (idempotent delete). */
     async remove(name) {
         if (!USER_ENTRY_NAME.test(name))
             throw new Error(`invalid entry name "${name}"`);
-        await deleteEntryFile(this.dir, name);
+        const document = await this.document(name);
+        if (document === undefined)
+            return;
+        await deleteEntryDocument(document);
     }
 }
 /** Locate the three stores; constructed once per plugin activation. */
 export function createUserPanelStores(agentsRoot) {
     return {
-        skills: new UserPanelStore(agentsRoot, 'skills', isUserSkillEntryName),
+        skills: new UserPanelStore(agentsRoot, 'skills', {
+            extraNameCheck: isUserSkillEntryName,
+            shapes: SKILL_ENTRY_SHAPES,
+            validate: file => skillEntryRejection(file.text),
+            honorInvocationControls: true
+        }),
         commands: new UserPanelStore(agentsRoot, 'commands'),
-        agents: new UserPanelStore(agentsRoot, 'agents', isUserSkillEntryName)
+        agents: new UserPanelStore(agentsRoot, 'agents', { extraNameCheck: isUserSkillEntryName })
     };
 }
 /**
@@ -145,6 +204,8 @@ export class UserPanelSkillProvider {
             if (entry.disabled || !isUserSkillEntryName(entry.name))
                 continue;
             candidates.push({
+                // The entry's name is the one its document declares, which is also the
+                // name the harness's own reader derives from the same file.
                 name: entry.name,
                 // The entry's own description verbatim; a user-entry label is our
                 // packaging, and this description reaches the same model-facing
@@ -160,7 +221,7 @@ export class UserPanelSkillProvider {
                 rank: USER_PANEL_RANK,
                 locator: { name: entry.name },
                 path: entry.path,
-                resourceBase: { kind: 'directory', path: this.skills.dirPath() }
+                resourceBase: { kind: 'directory', path: this.resourceDirectory(entry) }
             });
         }
         return candidates;
@@ -178,9 +239,17 @@ export class UserPanelSkillProvider {
             invocation: candidate.invocation,
             source: candidate.source,
             provider: this.name,
-            resourceBase: { kind: 'directory', path: store.dirPath() },
+            resourceBase: { kind: 'directory', path: this.resourceDirectory(entry) },
             path: entry.path,
             content: entry.content
         };
     }
+    /**
+     * Relative resources resolve beside the document that references them: a
+     * directory-shaped skill owns `references/`, `scripts/` and the like next to
+     * its `SKILL.md`, while a flat entry resolves against the panel directory.
+     */
+    resourceDirectory(entry) {
+        return entry.shape === 'skill-directory' ? dirname(entry.path) : this.skills.dirPath();
+    }
 }

package/lib/runtime/user-store.js

@@ -1,13 +1,17 @@
 /**
  * Shared persistence primitives for the market's user-authored panels:
  * skills, commands, and agent personas. Each panel owns one directory of
- * Markdown files under the plugin data root, parsed with the same frontmatter
- * rules the catalog uses, so user entries look exactly like suite entries to
- * the runtime mounts.
+ * Markdown documents under the Agent layout root, parsed with the same
+ * frontmatter rules the catalog uses, so user entries look exactly like suite
+ * entries to the runtime mounts.
+ *
+ * An entry is one document. Skills also accept the cross-tool directory
+ * spelling (`<name>/SKILL.md`) that other Agent tools and the harness's own
+ * reader of `~/.agents/skills` author; commands and personas are flat only.
  * @module runtime/user-store
  */
-import { readdir, readFile, rm, stat } from 'node:fs/promises';
-import { join } from 'node:path';
+import { readdir, readFile, rmdir, rm, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
 import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
 import { parseDocument, stringify } from 'yaml';
 import { parseSkillFrontmatter, stripFrontmatter } from '../catalog/skills-parse.js';
@@ -17,6 +21,70 @@ export function userEntryDir(agentsRoot, kind) {
 }
 /** `[a-z][a-z0-9_-]*` — the grammar every panel entry name must satisfy. */
 export const USER_ENTRY_NAME = /^[a-z][a-z0-9_-]*$/;
+/** The file name of a directory-shaped skill's document. */
+export const SKILL_ENTRY_FILE = 'SKILL.md';
+/**
+ * The spellings the skills panel serves, most preferred first: a name present
+ * as both a directory and a file resolves to the directory, which is the
+ * canonical cross-tool spelling and the one the harness's own reader of
+ * `~/.agents/skills` reaches first.
+ */
+export const SKILL_ENTRY_SHAPES = ['skill-directory', 'file'];
+/** The document path one entry name maps to under its kind directory. */
+export function entryDocumentPath(dir, name, shape) {
+    return shape === 'skill-directory' ? join(dir, name, SKILL_ENTRY_FILE) : join(dir, `${name}.md`);
+}
+/** Whether a path is a regular file; strict runtime snapshots propagate real I/O failures. */
+async function isFile(file, strict) {
+    try {
+        return (await stat(file)).isFile();
+    }
+    catch (error) {
+        if (strict && error.code !== 'ENOENT')
+            throw error;
+        return false;
+    }
+}
+/**
+ * Resolve one entry name to its document, taking the first shape the path
+ * exists in. Names outside the entry grammar never touch the filesystem.
+ */
+export async function resolveEntryDocument(dir, name, shapes, strict = false) {
+    if (!USER_ENTRY_NAME.test(name))
+        return undefined;
+    for (const shape of shapes) {
+        const file = entryDocumentPath(dir, name, shape);
+        if (await isFile(file, strict))
+            return { name, file, directory: dirname(file), shape };
+    }
+    return undefined;
+}
+/** Every entry document the served shapes expose, deduplicated by name at the first shape that has it. */
+export async function listEntryDocuments(dir, strict = false, shapes = ['file']) {
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch (error) {
+        if (strict && error.code !== 'ENOENT')
+            throw error;
+        return [];
+    }
+    const found = new Map();
+    for (const entry of entries.sort()) {
+        const name = entry.endsWith('.md') ? entry.slice(0, -3) : shapes.includes('skill-directory') ? entry : undefined;
+        if (name === undefined || !USER_ENTRY_NAME.test(name))
+            continue;
+        for (const shape of shapes) {
+            const file = entryDocumentPath(dir, name, shape);
+            if (!(await isFile(file, strict)))
+                continue;
+            found.set(name, { name, file, directory: dirname(file), shape });
+            break;
+        }
+    }
+    return [...found.values()];
+}
 /** Parse full YAML metadata without flattening arrays, mappings, or multiline strings. */
 export function parseFrontmatterRecord(text) {
     const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text)?.[1];
@@ -36,13 +104,11 @@ export function parseFrontmatterRecord(text) {
         throw new Error('Frontmatter must be a mapping');
     return value;
 }
-/** Read one entry; strict runtime snapshots throw on I/O errors other than a vanished file. */
-export async function readEntryFile(file, fallbackName, strict = false) {
-    if (fallbackName !== '' && !USER_ENTRY_NAME.test(fallbackName))
-        return undefined;
+/** Read one resolved entry; strict runtime snapshots throw on I/O errors other than a vanished file. */
+export async function readEntryDocument(document, strict = false) {
     let text;
     try {
-        text = await readFile(file, 'utf8');
+        text = await readFile(document.file, 'utf8');
     }
     catch (error) {
         if (strict && error.code !== 'ENOENT')
@@ -56,55 +122,45 @@ export async function readEntryFile(file, fallbackName, strict = false) {
     catch (error) {
         meta = { disabled: true, validationError: String(error) };
     }
-    const parsed = parseSkillFrontmatter(text, fallbackName);
-    const name = typeof parsed === 'string' ? fallbackName : typeof parsed.name === 'string' && parsed.name !== '' ? parsed.name : fallbackName;
+    // The declared name is read without an expected-value check: the harness's
+    // own reader of this directory takes the frontmatter name as the skill's
+    // name and never compares it to the file or directory name.
+    const parsed = parseSkillFrontmatter(text, undefined);
+    const name = typeof parsed === 'string' ? document.name : typeof parsed.name === 'string' && parsed.name !== '' ? parsed.name : document.name;
     return {
-        fallbackName,
+        documentName: document.name,
         name,
-        file,
+        file: document.file,
+        directory: document.directory,
+        shape: document.shape,
         text,
         body: stripFrontmatter(text),
         meta,
         ...(typeof parsed === 'string' ? {} : parsed)
     };
 }
-/** List `.md` entries; strict runtime snapshots propagate I/O errors instead of publishing partial inventories. */
-export async function listEntryFiles(dir, strict = false) {
-    let entries;
-    try {
-        entries = await readdir(dir);
-    }
-    catch (error) {
-        if (strict && error.code !== 'ENOENT')
-            throw error;
-        return [];
-    }
+/** List entries across the served shapes; strict runtime snapshots propagate I/O errors instead of publishing partial inventories. */
+export async function listEntryFiles(dir, strict = false, shapes = ['file']) {
+    const documents = await listEntryDocuments(dir, strict, shapes);
     const found = [];
-    for (const entry of entries.sort()) {
-        if (!entry.endsWith('.md'))
-            continue;
-        const file = join(dir, entry);
-        try {
-            const info = await stat(file);
-            if (!info.isFile())
-                continue;
-        }
-        catch (error) {
-            if (strict && error.code !== 'ENOENT')
-                throw error;
-            continue;
-        }
-        const parsed = await readEntryFile(file, entry.slice(0, -3), strict);
+    for (const document of documents) {
+        const parsed = await readEntryDocument(document, strict);
         if (parsed !== undefined)
             found.push(parsed);
     }
     return found;
 }
-/** Write one panel entry; the name becomes `<name>.md`. */
-export async function writeEntryFile(dir, name, text) {
+/** Create one panel entry's document from its name: `<name>.md`, or `<name>/SKILL.md` in the directory shape. */
+export async function writeEntryFile(dir, name, text, shape = 'file') {
     assertEntryName(name);
+    const file = entryDocumentPath(dir, name, shape);
+    await writeEntryDocument({ name, file, directory: dirname(file), shape }, text);
+}
+/** Replace one resolved entry's document in place, wherever it lives. */
+export async function writeEntryDocument(document, text) {
+    assertEntryName(document.name);
     parseFrontmatterRecord(text);
-    await writeFileAtomic(join(dir, `${name}.md`), text, { mode: 0o644, dirMode: 0o700 });
+    await writeFileAtomic(document.file, text, { mode: 0o644, dirMode: 0o700 });
 }
 /**
  * Enforce the entry-name grammar at every filesystem choke point. The name
@@ -116,22 +172,22 @@ function assertEntryName(name) {
     if (!USER_ENTRY_NAME.test(name))
         throw new Error(`invalid entry name "${name}" — use lowercase letters, digits, dashes, or underscores, starting with a letter`);
 }
-/** Delete one panel entry file; missing files resolve silently. */
-export async function deleteEntryFile(dir, name) {
-    assertEntryName(name);
-    await rm(join(dir, `${name}.md`), { force: true });
+/**
+ * Delete one resolved entry's document; a missing file resolves silently. A
+ * skill directory belongs to whichever tool authored it, so removal deletes
+ * the document it served and the directory only once nothing else is left in
+ * it — never the `references/`, `scripts/`, or persona files beside its
+ * `SKILL.md`.
+ */
+export async function deleteEntryDocument(document) {
+    assertEntryName(document.name);
+    await rm(document.file, { force: true });
+    if (document.shape === 'skill-directory')
+        await rmdir(dirname(document.file)).catch(() => undefined);
 }
-/** Whether an entry file with that name already exists. */
-export async function entryExists(dir, name) {
-    if (!USER_ENTRY_NAME.test(name))
-        return false;
-    try {
-        await stat(join(dir, `${name}.md`));
-        return true;
-    }
-    catch {
-        return false;
-    }
+/** Whether an entry document with that name exists in any served shape. */
+export async function entryExists(dir, name, shapes = ['file']) {
+    return (await resolveEntryDocument(dir, name, shapes)) !== undefined;
 }
 /** Serialize a frontmatter block from a shallow record (deterministic key order). */
 export function serializeFrontmatter(meta) {

package/lib/types/application/catalog-context.d.ts

@@ -53,6 +53,12 @@ export declare class CatalogContext implements SnapshotHost {
     private mutationQueue;
     private currentRevision;
     private currentScanGeneration;
+    /**
+     * The project-layout switch in effect. The host settings document owns the
+     * value and pushes it here on registration and on every change; the initial
+     * value is the contract's declared default, which is what the catalog would
+     * read from the document before the settings service resolves.
+     */
     private scanProjectLayoutsEnabled;
     /** The derived refresh in flight, shared by every change that lands while it runs. */
     private refreshPass;

package/lib/types/application/catalog.d.ts

@@ -24,6 +24,8 @@ export declare class Catalog implements MarketService {
     set mcpDiagnostics(value: McpMountDiagnostic[]);
     /** The user-dimension suite root this catalog operates. */
     get userRoot(): string;
+    /** The plugin storage root holding per-suite `${PLUGIN_DATA}` directories and overrides. */
+    get dataRoot(): string;
     get sources(): SourceRef[];
     /** Whether one suite currently carries an install entry. */
     isInstalled(sourceId: string, suiteId: string): boolean;
@@ -100,6 +102,13 @@ export declare class Catalog implements MarketService {
     mcpOverrides(sourceId: string, suiteId: string): Promise<McpSuiteOverrides>;
     /** Set or clear one server's MCP override and remount it. */
     setMcpOverride(sourceId: string, suiteId: string, serverKey: string, override: McpServerOverride | null): Promise<void>;
+    /**
+     * Enable or disable one declared MCP server, addressed by the same
+     * source-qualified suite id its status row carries. Disabling writes an
+     * override rather than editing the suite's `mcp.json`, so a refresh cannot
+     * clobber the user's choice.
+     */
+    setMcpServerEnabled(suiteKey: string, serverKey: string, enabled: boolean): Promise<void>;
     /** Re-run the MCP reconcile pass without changing any catalog state. */
     retryMounts(): Promise<void>;
     /** The persisted MCP backend choice without the host-client probe. */

package/lib/types/application/mcp-service.d.ts

@@ -30,6 +30,12 @@ export declare class McpService {
      * in the suite's parsed mcp.json.
      */
     setOverride(sourceId: string, suiteId: string, serverKey: string, override: McpServerOverride | null): Promise<void>;
+    /**
+     * Enable or disable one declared server, addressed by the source-qualified
+     * suite id the status rows carry. The qualified id is split here rather than
+     * by callers so the separator stays a server-side detail.
+     */
+    setServerEnabled(suiteKey: string, serverKey: string, enabled: boolean): Promise<void>;
     /**
      * Re-run the MCP reconcile pass: retries failed mounts and clears residual
      * tools, without changing any catalog state.

package/lib/types/application/ports.d.ts

@@ -11,8 +11,8 @@
  */
 import type { LspServerSpec, SourceKind } from '../model/types.js';
 export type { McpBackendInfo } from '../contracts/market.js';
+import type { DownloadRegionSetting } from '../contracts/settings.js';
 import type { McpBackend } from '../runtime/mcp-backend.js';
-import type { DownloadRegionSetting } from '../runtime/regions.js';
 import type { LspMountStatusSource } from '../runtime/lsp-status.js';
 import type { McpToolSnapshot } from '../runtime/mcp-status.js';
 /** A new source: its location, optional branch, and acquisition kind. */

package/lib/types/application/queries.d.ts

@@ -40,6 +40,8 @@ export interface MarketMutations {
     setEnabled(sourceId: string, suiteId: string, enabled: boolean): Promise<void>;
     setSurface(sourceId: string, suiteId: string, surface: SuiteSurfaceKey, enabled: boolean): Promise<void>;
     setMcpOverride(sourceId: string, suiteId: string, serverKey: string, override: McpServerOverride | null): Promise<void>;
+    /** Enable or disable one declared MCP server by its source-qualified suite id. */
+    setMcpServerEnabled(suiteKey: string, serverKey: string, enabled: boolean): Promise<void>;
     /** Validate and persist the user's direct LSP server table. */
     setLspServers(raw: unknown): Promise<LspServerTable>;
     setLspServerEnabled(id: string, enabled: boolean): Promise<void>;

package/lib/types/catalog/paths.d.ts

@@ -45,6 +45,12 @@ export declare function sourceCheckoutDir(dimensionRoot: string, sourceId: strin
  * bare suite id silently collides across sources.
  */
 export declare function qualifiedSuiteId(sourceId: string, suiteId: string): string;
+/**
+ * The data directory `${PLUGIN_DATA}` resolves to for one suite: a
+ * source-qualified directory under the plugin storage root, shared by every
+ * surface of that suite so MCP servers, skills and commands see one location.
+ */
+export declare function suiteDataDir(dataRoot: string, sourceId: string, suiteId: string): string;
 /** The slice of a `node:path` implementation a containment test needs. */
 export interface PathFlavor {
     relative(from: string, to: string): string;