dsh-agent-plugins-market 0.6.0 → 0.6.2

package/lib/runtime/server-config.js

@@ -0,0 +1,75 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { MCP_SCHEMA_ID, validateAgainstSchema, validateMcpJson } from '../catalog/validate.js';
+import { parseLspServers } from '../catalog/lsp-spec.js';
+import { qualifiedSuiteId } from '../catalog/paths.js';
+import { redactMcpConfig } from './mcp-redaction.js';
+/** Restore only unchanged redacted leaves, rejecting invented masked values. */
+export function restoreRedactedConfig(input, original, redacted = redactMcpConfig(original)) {
+    if (typeof input === 'string' && input.includes('[redacted]')) {
+        if (input !== redacted)
+            throw new Error('masked values must remain unchanged or be replaced');
+        return original;
+    }
+    if (Array.isArray(input))
+        return input.map((value, index) => restoreRedactedConfig(value, Array.isArray(original) ? original[index] : undefined, Array.isArray(redacted) ? redacted[index] : undefined));
+    if (typeof input === 'object' && input !== null) {
+        const source = typeof original === 'object' && original !== null ? original : {};
+        const safe = typeof redacted === 'object' && redacted !== null ? redacted : {};
+        return Object.fromEntries(Object.entries(input).map(([key, value]) => [key, restoreRedactedConfig(value, source[key], safe[key])]));
+    }
+    return input;
+}
+export async function validateServerMcp(root, key, config) {
+    const document = { $schema: MCP_SCHEMA_ID, mcpServers: { [key]: config } };
+    const errors = await validateAgainstSchema(MCP_SCHEMA_ID, document);
+    if (errors.length > 0)
+        throw new Error(`invalid MCP configuration: ${errors.join('; ')}`);
+    const result = await validateMcpJson(root, document);
+    const server = result.config?.servers[key];
+    if (server === undefined || result.errors.length > 0)
+        throw new Error(`invalid MCP configuration: ${result.errors.join('; ')}`);
+    return server;
+}
+export function validateServerLsp(key, config) {
+    const errors = [];
+    const server = parseLspServers({ [key]: config }, errors)[key];
+    if (server === undefined || errors.length > 0)
+        throw new Error(`invalid LSP configuration: ${errors.join('; ')}`);
+    return server;
+}
+/** Public configuration excludes the parser's derived identity. */
+export function lspConfig(spec) {
+    return Object.fromEntries(Object.entries(spec).filter(([key]) => key !== 'key'));
+}
+export async function loadLspOverrides(root) {
+    try {
+        const raw = JSON.parse(await readFile(join(root, 'lsp-overrides.json'), 'utf8'));
+        return Object.fromEntries(Object.entries(raw).map(([id, config]) => [id, validateServerLsp(id.slice(id.lastIndexOf('/') + 1), config)]));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return {};
+        throw error;
+    }
+}
+export async function saveLspOverride(root, id, config) {
+    const overrides = await loadLspOverrides(root);
+    overrides[id] = config;
+    await mkdir(root, { recursive: true });
+    const path = join(root, 'lsp-overrides.json');
+    await writeFile(`${path}.tmp`, JSON.stringify(Object.fromEntries(Object.entries(overrides).map(([key, value]) => [key, lspConfig(value)])), null, 2), { mode: 0o600 });
+    await rename(`${path}.tmp`, path);
+}
+export async function applyLspOverrides(root, suites) {
+    const overrides = await loadLspOverrides(root);
+    return suites.map(suite => suite.lsp === undefined
+        ? suite
+        : {
+            ...suite,
+            lsp: {
+                ...suite.lsp,
+                servers: Object.fromEntries(Object.entries(suite.lsp.servers).map(([key, spec]) => [key, overrides[`${qualifiedSuiteId(suite.sourceId, suite.id)}/${key}`] ?? spec]))
+            }
+        });
+}

package/lib/runtime/skills-provider.js

@@ -12,21 +12,19 @@
  * resource base points at the skill directory, so CC-authored skills work
  * verbatim under the harness.
  */
-import { readFile, readdir, stat } from 'node:fs/promises';
-import { join } from 'node:path';
+import { readFile } from 'node:fs/promises';
 import { parseSkillFrontmatter, stripFrontmatter } from '../catalog/skills-parse.js';
-import { bindHostLocale } from './host-locale.js';
+import { parseFrontmatterRecord } from './user-store.js';
+import { PLUGIN_ROOT_VARIABLES } from '../model/layouts.js';
 export const SUITE_PROJECT_SOURCE = 'agent-plugin-project';
 export const SUITE_USER_SOURCE = 'agent-plugin-user';
 const PROJECT_RANK = 250;
 const USER_RANK = 450;
 export class SuiteSkillProvider {
     manager;
-    t;
     name = 'agent-plugin';
-    constructor(manager, t = bindHostLocale(undefined)) {
+    constructor(manager) {
         this.manager = manager;
-        this.t = t;
     }
     async list(options) {
         const located = await this.locate(options.cwd);
@@ -44,85 +42,28 @@ export class SuiteSkillProvider {
         }
         return unique.map(entry => this.candidateFor(entry));
     }
-    /** Parse `agents/*.md` of one suite into agent-definition candidates. */
-    async agentsOf(suite) {
-        if (suite.activeSurfaces?.agents === false)
-            return [];
-        const dir = join(suite.root, 'agents');
-        let entries;
-        try {
-            entries = await readdir(dir);
-        }
-        catch {
-            return [];
-        }
-        const located = [];
-        for (const entry of entries) {
-            if (!entry.endsWith('.md'))
-                continue;
-            const file = join(dir, entry);
-            try {
-                const info = await stat(file);
-                if (!info.isFile())
-                    continue;
-            }
-            catch {
-                continue;
-            }
-            const agentName = entry.slice(0, -3);
-            let text;
-            try {
-                text = await readFile(file, 'utf8');
-            }
-            catch {
-                continue;
-            }
-            const parsed = parseSkillFrontmatter(text, agentName);
-            const description = typeof parsed === 'string' ? (suite.manifest.description ?? agentName) : parsed.description;
-            const skill = {
-                name: `agent-${agentName}`,
-                directory: dir,
-                file,
-                description,
-                ...(typeof parsed !== 'string' && parsed.whenToUse !== undefined ? { whenToUse: parsed.whenToUse } : {}),
-                invocation: typeof parsed === 'string' ? { modelInvocable: true, userInvocable: false } : parsed.invocation
-            };
-            located.push({
-                rank: suite.dimension === 'project' ? PROJECT_RANK : USER_RANK,
-                source: suite.dimension === 'project' ? SUITE_PROJECT_SOURCE : SUITE_USER_SOURCE,
-                suite,
-                skill
-            });
-        }
-        return located;
-    }
     async get(candidate, _options) {
         const locator = candidate.locator;
         let text;
         try {
-            text = await readFile(locator.file, 'utf8');
+            text = locator.content ?? (await readFile(locator.file, 'utf8'));
         }
         catch {
             return undefined;
         }
-        if (locator.kind === 'agent') {
-            const suiteName = locator.suiteRoot.split(/[\\/]/).at(-1) ?? 'suite';
-            const content = [this.t('agentDefinitionTitle', { suite: suiteName }), '', this.t('agentDefinitionIntro'), '', '```markdown', text, '```'].join('\n');
-            return {
-                name: candidate.name,
-                description: candidate.description,
-                invocation: candidate.invocation,
-                source: candidate.source,
-                provider: this.name,
-                resourceBase: { kind: 'directory', path: locator.directory },
-                path: locator.file,
-                content
-            };
+        try {
+            if (parseFrontmatterRecord(text).disabled === true)
+                return undefined;
+        }
+        catch {
+            return undefined;
         }
         const parsed = parseSkillFrontmatter(text, candidate.name);
         if (typeof parsed === 'string')
             return undefined;
-        const content = stripFrontmatter(text).replaceAll('${CLAUDE_PLUGIN_ROOT}', locator.suiteRoot);
+        const content = [stripFrontmatter(text), ...(locator.skillInstructions === undefined ? [] : [locator.skillInstructions])]
+            .join('\n\n')
+            .replace(/\$\{([A-Z_]+)\}/g, (match, name) => (PLUGIN_ROOT_VARIABLES.has(name) ? locator.suiteRoot : match));
         return {
             name: parsed.name,
             description: candidate.description,
@@ -145,10 +86,11 @@ export class SuiteSkillProvider {
             provider: this.name,
             rank: entry.rank,
             locator: {
+                ...(entry.content === undefined ? {} : { content: entry.content }),
+                ...(entry.suite.manifest.skillInstructions === undefined ? {} : { skillInstructions: entry.suite.manifest.skillInstructions }),
                 file: entry.skill.file,
                 directory: entry.skill.directory,
-                suiteRoot: entry.suite.root,
-                kind: entry.skill.name.startsWith('agent-') ? 'agent' : 'skill'
+                suiteRoot: entry.suite.root
             },
             path: entry.skill.file,
             resourceBase: { kind: 'directory', path: entry.skill.directory }
@@ -159,9 +101,15 @@ export class SuiteSkillProvider {
         const userSuites = await this.manager.enabledUserSuites();
         for (const suite of userSuites) {
             for (const skill of suite.activeSurfaces?.skills === false ? [] : suite.skills) {
+                try {
+                    if (parseFrontmatterRecord(await readFile(skill.file, 'utf8')).disabled === true)
+                        continue;
+                }
+                catch {
+                    continue;
+                }
                 located.push({ rank: USER_RANK, source: SUITE_USER_SOURCE, suite, skill });
             }
-            located.push(...(await this.agentsOf(suite)));
         }
         if (cwd !== undefined) {
             located.push(...(await this.locateProject(cwd)));
@@ -173,9 +121,15 @@ export class SuiteSkillProvider {
         const located = [];
         for (const suite of snapshot.enabledSuites) {
             for (const skill of suite.activeSurfaces?.skills === false ? [] : suite.skills) {
+                try {
+                    if (parseFrontmatterRecord(await readFile(skill.file, 'utf8')).disabled === true)
+                        continue;
+                }
+                catch {
+                    continue;
+                }
                 located.push({ rank: PROJECT_RANK, source: SUITE_PROJECT_SOURCE, suite, skill });
             }
-            located.push(...(await this.agentsOf(suite)));
         }
         return located;
     }

package/lib/runtime/storage-migration.js

@@ -0,0 +1,169 @@
+/** Consolidate plugin-owned storage before stores, routes, or providers are exposed. */
+import { constants } from 'node:fs';
+import { copyFile, lstat, mkdir, readdir, readFile, rename, rmdir, unlink, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { expandHome, resolveDataRoot, resolveDshHome, resolveUserRoot } from '../catalog/paths.js';
+async function info(path) {
+    try {
+        return await lstat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+/** Move only successfully copied entries; never traverse links or overwrite a destination. */
+export async function mergeStorageTree(from, to, result) {
+    if (resolve(from) === resolve(to))
+        return;
+    const source = await info(from);
+    if (source === undefined)
+        return;
+    const destination = await info(to);
+    if (source.isSymbolicLink() || destination?.isSymbolicLink() === true) {
+        result.conflicts.push(from);
+        return;
+    }
+    if (source.isDirectory()) {
+        if (destination !== undefined && !destination.isDirectory()) {
+            result.conflicts.push(from);
+            return;
+        }
+        await mkdir(to, { recursive: true });
+        for (const name of await readdir(from))
+            await mergeStorageTree(join(from, name), join(to, name), result);
+        if ((await readdir(from)).length === 0)
+            await rmdir(from);
+        return;
+    }
+    if (!source.isFile() || (destination !== undefined && !destination.isFile())) {
+        result.conflicts.push(from);
+        return;
+    }
+    if (destination !== undefined) {
+        if (!(await readFile(from)).equals(await readFile(to))) {
+            result.conflicts.push(from);
+            return;
+        }
+    }
+    else {
+        await mkdir(dirname(to), { recursive: true });
+        // COPYFILE_EXCL also protects against a destination created during migration.
+        await copyFile(from, to, constants.COPYFILE_EXCL);
+    }
+    await unlink(from);
+}
+function contains(parent, child) {
+    const path = relative(parent, child);
+    return path === '' || (!path.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) && path !== '..' && !isAbsolute(path));
+}
+/**
+ * Migrate former root overrides and data/user panels into the canonical root.
+ * Unknown files in override directories remain untouched. Conflicts remain at
+ * the old path and are returned to block activation; reruns are safe.
+ */
+export async function migratePluginStorage(config = {}) {
+    const userRoot = resolveUserRoot();
+    const dataRoot = resolveDataRoot();
+    const result = { conflicts: [] };
+    for (const path of [resolveDshHome(), userRoot, dataRoot, join(userRoot, 'user'), join(userRoot, '.sources')]) {
+        if ((await info(path))?.isSymbolicLink() === true)
+            throw new Error(`Plugin storage cannot use a symbolic-link directory: ${path}`);
+    }
+    const legacyUserRoot = resolve(expandHome(config.userRoot ?? userRoot));
+    const legacyDataRoot = resolve(expandHome(config.dataRoot ?? join(legacyUserRoot, 'data')));
+    for (const path of new Set([legacyUserRoot, legacyDataRoot, join(resolveDshHome(), 'agent-plugins-data')])) {
+        if ((await info(path))?.isSymbolicLink() === true)
+            throw new Error(`Plugin storage migration cannot traverse a symbolic-link root: ${path}`);
+    }
+    if (legacyUserRoot !== userRoot) {
+        if (contains(legacyUserRoot, userRoot) || contains(userRoot, legacyUserRoot))
+            throw new Error('Legacy userRoot overlaps canonical plugin storage');
+        const legacySources = join(legacyUserRoot, '.sources');
+        const sourceInfo = await info(legacySources);
+        const sourceNames = sourceInfo?.isDirectory() === true ? await readdir(legacySources) : [];
+        const rootConflicts = [];
+        if (sourceInfo !== undefined && !sourceInfo.isDirectory())
+            rootConflicts.push(legacySources);
+        for (const name of sourceNames) {
+            if ((await info(join(userRoot, '.sources', name))) !== undefined)
+                rootConflicts.push(join(legacySources, name));
+            await collectUnsupportedEntries(join(legacySources, name), rootConflicts);
+        }
+        const legacyState = join(legacyUserRoot, 'state.json');
+        const currentState = join(userRoot, 'state.json');
+        const previous = await info(legacyState);
+        const current = await info(currentState);
+        // Validate before relocating any checkouts: malformed state must remain
+        // beside its original sources so recovery does not require finding them.
+        if (previous?.isFile() === true)
+            JSON.parse(await readFile(legacyState, 'utf8'));
+        if (previous !== undefined && (!previous.isFile() || (current !== undefined && (!current.isFile() || !(await readFile(legacyState)).equals(await readFile(currentState)))))) {
+            rootConflicts.push(legacyState);
+        }
+        if (rootConflicts.length > 0) {
+            // The install state and its checkouts are one ownership unit. Moving only
+            // one half would orphan installs or make the retained state unusable.
+            result.conflicts.push(...rootConflicts);
+        }
+        else {
+            if (sourceInfo?.isDirectory() === true) {
+                for (const name of sourceNames)
+                    await mergeStorageTree(join(legacySources, name), join(userRoot, '.sources', name), result);
+                if ((await readdir(legacySources)).length === 0)
+                    await rmdir(legacySources);
+            }
+            await mergeStorageTree(legacyState, currentState, result);
+            await relocateManagedSourceUrls(userRoot, legacyUserRoot);
+        }
+        for (const entry of ['data', 'user'])
+            await mergeStorageTree(join(legacyUserRoot, entry), join(userRoot, entry), result);
+    }
+    for (const legacy of new Set([legacyDataRoot, join(resolveDshHome(), 'agent-plugins-data')])) {
+        if (legacy === dataRoot)
+            continue;
+        if (contains(legacy, dataRoot) || contains(dataRoot, legacy))
+            throw new Error('Legacy dataRoot overlaps canonical plugin data storage');
+        for (const entry of ['data', 'overrides', 'user', 'settings.json', 'lsp-servers.json', 'feedback']) {
+            await mergeStorageTree(join(legacy, entry), join(dataRoot, entry), result);
+        }
+    }
+    await mergeStorageTree(join(dataRoot, 'user'), join(userRoot, 'user'), result);
+    return result;
+}
+/** Retain all state fields while rebasing adopted checkouts moved with a root. */
+async function relocateManagedSourceUrls(userRoot, legacyUserRoot) {
+    const path = join(userRoot, 'state.json');
+    if ((await info(path)) === undefined)
+        return;
+    const state = JSON.parse(await readFile(path, 'utf8'));
+    if (typeof state !== 'object' || state === null || !('sources' in state) || !Array.isArray(state.sources))
+        return;
+    let changed = false;
+    for (const source of state.sources) {
+        if (typeof source !== 'object' || source === null || !('local' in source) || source.local !== true || !('url' in source) || typeof source.url !== 'string')
+            continue;
+        const oldCheckout = join(legacyUserRoot, '.sources');
+        if (!contains(oldCheckout, resolve(expandHome(source.url))))
+            continue;
+        source.url = join(userRoot, '.sources', relative(oldCheckout, resolve(expandHome(source.url))));
+        changed = true;
+    }
+    if (changed) {
+        const temp = `${path}.migration-${process.pid}.tmp`;
+        await writeFile(temp, `${JSON.stringify(state, null, 2)}\n`, { flag: 'wx' });
+        await rename(temp, path);
+    }
+}
+async function collectUnsupportedEntries(path, conflicts) {
+    const entry = await info(path);
+    if (entry === undefined)
+        return;
+    if (entry.isDirectory()) {
+        for (const name of await readdir(path))
+            await collectUnsupportedEntries(join(path, name), conflicts);
+    }
+    else if (!entry.isFile())
+        conflicts.push(path);
+}

package/lib/runtime/subagent-catalog.js

@@ -0,0 +1,129 @@
+/** Durable role catalogs follow DSH tool-skill's pre-step publication and session-surface recovery. */
+import { createHash } from 'node:crypto';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+/** Register after the exact tool definition; teardown removes guidance before execution. */
+export function mountSubagentCatalog(ctx, tool, snapshot, t) {
+    const host = ctx;
+    let disposed = false;
+    const dispose = host.on('agent/pre-step', async ({ agent, signal }, next) => {
+        const decision = await next();
+        if (decision.kind === 'reject' || disposed)
+            return decision;
+        signal.throwIfAborted();
+        let entries;
+        try {
+            entries = host.tools.get(tool.name, agent) === tool ? await snapshot(agent, signal) : [];
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            host.logger?.warn(`subagent catalog snapshot incomplete: ${String(error)}`);
+            return decision;
+        }
+        signal.throwIfAborted();
+        if (disposed)
+            return decision;
+        if (host.tools.get(tool.name, agent) !== tool)
+            entries = [];
+        const digest = digestEntries(entries);
+        const history = catalogHistory(agent);
+        const existing = catalogMessage(decision.messages);
+        if (history.visibleDigest === digest) {
+            return existing === undefined ? decision : { ...decision, messages: decision.messages.filter(message => message.id !== existing.message.id) };
+        }
+        if (existing !== undefined && digestEntries(existing.entries) === digest)
+            return decision;
+        if (!history.published && entries.length === 0) {
+            return existing === undefined ? decision : { ...decision, messages: decision.messages.filter(message => message.id !== existing.message.id) };
+        }
+        const message = renderCatalog(entries, history.published, t);
+        return {
+            ...decision,
+            messages: existing === undefined ? [...decision.messages, message] : decision.messages.map(item => (item.id === existing.message.id ? message : item))
+        };
+    });
+    return () => {
+        disposed = true;
+        dispose();
+    };
+}
+function escapeText(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
+}
+function renderCatalog(entries, update, t) {
+    const lines = entries.map(entry => {
+        const route = [entry.provider, entry.model].filter(value => value !== undefined).join('/') || t('subagentCatalogInherit');
+        return `<subagent id="${escapeText(entry.name)}" name="${escapeText(entry.title)}" model="${escapeText(route)}" reasoning_effort="${escapeText(entry.reasoningEffort ?? t('subagentCatalogDefaultEffort'))}">${escapeText(entry.description)}</subagent>`;
+    });
+    return createUserMessage({
+        content: [
+            {
+                type: 'text',
+                text: [
+                    '<system-reminder>',
+                    t(update ? 'subagentCatalogUpdated' : 'subagentCatalogIntro'),
+                    '<available_subagents>',
+                    ...lines,
+                    '</available_subagents>',
+                    t(entries.length === 0 ? 'subagentCatalogEmpty' : 'subagentCatalogCall'),
+                    '</system-reminder>'
+                ].join('\n')
+            }
+        ],
+        source: { kind: 'subagent-catalog', form: 'catalog', ...(update ? { update: true } : {}), entries }
+    });
+}
+function digestEntries(entries) {
+    return createHash('sha256')
+        .update(entries.map(entry => JSON.stringify([entry.name, entry.title, entry.description, entry.provider, entry.model, entry.reasoningEffort])).join('\n'))
+        .digest('hex');
+}
+/** Resumed and forked seeds may carry unvalidated source fields; ignore unreadable catalogs. */
+function readEntries(source) {
+    if (typeof source !== 'object' || source === null || !('kind' in source) || source.kind !== 'subagent-catalog' || !('entries' in source) || !Array.isArray(source.entries))
+        return undefined;
+    const entries = [];
+    for (const raw of source.entries) {
+        if (typeof raw !== 'object' || raw === null)
+            return undefined;
+        const entry = raw;
+        if (typeof entry.name !== 'string' || entry.name === '' || typeof entry.title !== 'string' || typeof entry.description !== 'string')
+            return undefined;
+        if (['provider', 'model', 'reasoningEffort'].some(key => entry[key] !== undefined && (typeof entry[key] !== 'string' || entry[key] === '')))
+            return undefined;
+        entries.push({
+            name: entry.name,
+            title: entry.title,
+            description: entry.description,
+            ...(entry.provider === undefined ? {} : { provider: entry.provider }),
+            ...(entry.model === undefined ? {} : { model: entry.model }),
+            ...(entry.reasoningEffort === undefined ? {} : { reasoningEffort: entry.reasoningEffort })
+        });
+    }
+    return entries;
+}
+function catalogHistory(agent) {
+    const visible = new Set(agent.session.surface.nodes);
+    let published = false;
+    for (let index = agent.session.seq - 1; index >= 0; index--) {
+        const event = agent.session.eventAt(index);
+        if (event === undefined)
+            throw new Error(`subagent catalog cannot read seq ${index} below the current Session length`);
+        if (event.type !== 'user/message')
+            continue;
+        const entries = readEntries(event.data.source);
+        if (entries === undefined)
+            continue;
+        published = true;
+        if (visible.has(event.seq))
+            return { visibleDigest: digestEntries(entries), published };
+    }
+    return { published };
+}
+function catalogMessage(messages) {
+    for (const message of messages) {
+        const entries = readEntries(message.source);
+        if (entries !== undefined)
+            return { message, entries };
+    }
+    return undefined;
+}

package/lib/runtime/user-commands.js

@@ -0,0 +1,86 @@
+/**
+ * User command mounting: every enabled entry of the user commands panel
+ * registers as a dsh slash command, so user-authored quick replies behave
+ * exactly like suite commands — the body with `$ARGUMENTS` substituted rides
+ * one follow-up message on the receiving agent. Reconciled on every catalog
+ * change, keyed `user/<name>`.
+ * @module runtime/user-commands
+ */
+import { USER_ENTRY_NAME } from './user-store.js';
+/** Register/unregister user-panel commands to match the panel's enabled entries. */
+export class UserCommandMountRegistry {
+    ctx;
+    store;
+    t;
+    fingerprints = new Map();
+    live = new Map();
+    constructor(ctx, store, t) {
+        this.ctx = ctx;
+        this.store = store;
+        this.t = t;
+    }
+    /** Sync the live registrations with the panel's enabled entries. */
+    async reconcile() {
+        const diagnostics = [];
+        const entries = await this.store.list();
+        const wanted = new Map();
+        for (const entry of entries) {
+            if (entry.disabled)
+                continue;
+            if (!USER_ENTRY_NAME.test(entry.name))
+                continue;
+            wanted.set(entry.name, {
+                name: entry.name,
+                description: entry.description === '' ? `[${this.t('userCommandSourceLabel')}] ${entry.name}` : `[${this.t('userCommandSourceLabel')}] ${entry.description}`,
+                ...(typeof entry.metadata['argument-hint'] === 'string' && entry.metadata['argument-hint'] !== '' ? { hint: entry.metadata['argument-hint'] } : {}),
+                body: entry.content
+            });
+        }
+        for (const [key, disposer] of [...this.live]) {
+            if (!wanted.has(key)) {
+                disposer();
+                this.live.delete(key);
+            }
+        }
+        const host = this.ctx;
+        if (typeof host.commands?.register !== 'function') {
+            if (wanted.size > 0)
+                diagnostics.push('ctx.commands is not available in this profile; user commands stay unregistered');
+            return diagnostics;
+        }
+        for (const [key, spec] of wanted) {
+            const fingerprint = JSON.stringify(spec);
+            if (this.live.has(key) && this.fingerprints.get(key) === fingerprint)
+                continue;
+            this.live.get(key)?.();
+            this.live.delete(key);
+            this.fingerprints.delete(key);
+            try {
+                const disposer = host.commands.register({
+                    name: spec.name,
+                    description: spec.description,
+                    ...(spec.hint === undefined ? {} : { input: { hint: spec.hint } }),
+                    handler: invocation => {
+                        const agent = invocation.agent;
+                        const text = [this.t('userCommandForwardTitle', { command: spec.name }), '', spec.body.replaceAll('$ARGUMENTS', invocation.rawInput.trim())].join('\n');
+                        agent.followup({ content: [{ type: 'text', text }], source: { kind: 'plugin', plugin: 'dsh-agent-plugins-market' } });
+                        return { kind: 'success', text: this.t('userCommandAcknowledged', { command: spec.name }) };
+                    }
+                });
+                this.live.set(key, disposer);
+                this.fingerprints.set(key, fingerprint);
+            }
+            catch (error) {
+                diagnostics.push(`command "${spec.name}": ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        return diagnostics;
+    }
+    /** Dispose every registration (plugin teardown). */
+    disposeAll() {
+        for (const disposer of [...this.live.values()])
+            disposer();
+        this.live.clear();
+        this.fingerprints.clear();
+    }
+}