dsh-agent-plugins-market 0.6.2 → 0.7.0

package/lib/application/details.js

@@ -47,7 +47,7 @@ export async function buildSuiteDetail(suite, installed, diagnostics, mcpOverrid
                 ? suite.resources === undefined
                     ? await hooksPreviews(suite.root)
                     : { count: 0, entries: [] }
-                : normalizedHookPreviews(suite)
+                : normalizedHookPreviews(suite.hooks)
             : { count: 0, entries: [] },
         commands: remoteUrl === undefined ? await markdownPreviews(suite.resources?.commands ?? (await defaultMarkdownResources(suite.root, 'commands'))) : [],
         agents: remoteUrl === undefined ? await markdownPreviews(suite.resources?.agents ?? (await defaultMarkdownResources(suite.root, 'agents'))) : [],
@@ -79,10 +79,10 @@ async function markdownPreviews(resources) {
     for (const resource of resources) {
         try {
             const content = (await resourceText(resource)).slice(0, 64 * 1024);
-            const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+            const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content)?.[1];
             let description;
-            if (match !== null) {
-                const yaml = parseYaml(match[1]);
+            if (frontmatter !== undefined) {
+                const yaml = parseYaml(frontmatter);
                 if (typeof yaml === 'object' && yaml !== null) {
                     const desc = yaml['description'];
                     if (typeof desc === 'string')
@@ -97,8 +97,8 @@ async function markdownPreviews(resources) {
     }
     return previews;
 }
-function normalizedHookPreviews(suite) {
-    const entries = Object.entries(suite.hooks.events).flatMap(([event, groups]) => groups.flatMap(group => group.hooks.map(hook => ({ event, ...(group.matcher === undefined ? {} : { matcher: group.matcher }), command: hook.command }))));
+function normalizedHookPreviews(hooks) {
+    const entries = Object.entries(hooks.events).flatMap(([event, groups]) => groups.flatMap(group => group.hooks.map(hook => ({ event, ...(group.matcher === undefined ? {} : { matcher: group.matcher }), command: hook.command }))));
     return { count: entries.length, entries };
 }
 async function hooksPreviews(root) {

package/lib/application/install-store.js

@@ -0,0 +1,95 @@
+/**
+ * Install-state mutations over the persisted record: which suites are
+ * installed and enabled, which of their surfaces are on, and the config-seeded
+ * sources merged in at activation.
+ *
+ * The checkout a suite is read from stays source-owned: installing writes an
+ * entry, never a file inside the source.
+ */
+import { isDirectory } from '../catalog/fs-probes.js';
+import { discoverSuitesInSource } from '../catalog/suite-scanner.js';
+import { SUITE_SURFACE_KEYS } from '../model/types.js';
+import { installKey } from './catalog-context.js';
+import { tryHead } from './source-store.js';
+export class InstallStore {
+    context;
+    sources;
+    constructor(context, sources) {
+        this.context = context;
+        this.sources = sources;
+    }
+    /** Install a suite from a source and enable it. The client confirms the
+     * injected surfaces (skills / MCP / hooks / commands) in a pre-install
+     * dialog before this runs; disabling afterwards is always available. */
+    async install(sourceId, suiteId) {
+        return this.context.enqueue(async () => {
+            const source = this.context.state.sources.find(entry => entry.id === sourceId);
+            if (source === undefined)
+                throw new Error(`unknown source "${sourceId}"`);
+            const checkout = this.sources.checkoutPath(source);
+            let freshLock;
+            if (!(await isDirectory(checkout)))
+                freshLock = await this.sources.acquire(source);
+            const suites = await discoverSuitesInSource(checkout, sourceId, 'user', source.url);
+            const suite = suites.find(entry => entry.id === suiteId);
+            if (suite === undefined)
+                throw new Error(`suite "${suiteId}" not found in source "${sourceId}"`);
+            if (suite.remote !== undefined)
+                throw new Error(`suite "${suiteId}" is a remote reference (${suite.remote.url}); add its repository as a source before installing`);
+            // Archive (or tarball-fallback) sources have no git HEAD; their digest
+            // is the lock value.
+            const lockCommit = (await tryHead(checkout)) ?? freshLock ?? this.sources.knownHead(sourceId);
+            await this.setInstalled(sourceId, suiteId, { enabled: true, installedAt: new Date().toISOString(), lockCommit });
+            await this.context.notifyChanged(true);
+        });
+    }
+    /** Uninstall a suite while retaining the source checkout. */
+    async uninstall(sourceId, suiteId) {
+        return this.context.enqueue(async () => {
+            const key = installKey(sourceId, suiteId);
+            if (this.context.state.installed[key] === undefined)
+                throw new Error(`suite "${suiteId}" is not installed`);
+            const rest = Object.fromEntries(Object.entries(this.context.state.installed).filter(([entryKey]) => entryKey !== key));
+            await this.context.commit({ ...this.context.state, installed: rest });
+            await this.context.notifyChanged(true);
+        });
+    }
+    /** Enable or disable an installed suite. */
+    async setEnabled(sourceId, suiteId, enabled) {
+        return this.context.enqueue(async () => {
+            const entry = this.context.installed(sourceId, suiteId);
+            if (entry === undefined)
+                throw new Error(`suite "${suiteId}" is not installed`);
+            await this.setInstalled(sourceId, suiteId, { ...entry, enabled });
+            await this.context.notifyChanged(true);
+        });
+    }
+    /** Enable or disable one runtime surface of an installed suite. */
+    async setSurface(sourceId, suiteId, surface, enabled) {
+        return this.context.enqueue(async () => {
+            const entry = this.context.installed(sourceId, suiteId);
+            if (entry === undefined)
+                throw new Error(`suite "${suiteId}" is not installed`);
+            if (!SUITE_SURFACE_KEYS.includes(surface))
+                throw new Error(`surface "${surface}" is not toggleable`);
+            const surfaces = { ...(entry.surfaces ?? {}), [surface]: enabled };
+            await this.setInstalled(sourceId, suiteId, { ...entry, surfaces });
+            await this.context.notifyChanged(true);
+        });
+    }
+    /** Append config-seeded sources missing from user state and persist them. */
+    async mergeSources(sources) {
+        const existing = new Set(this.context.state.sources.map(source => source.id));
+        const additions = sources.filter(source => !existing.has(source.id));
+        if (additions.length === 0)
+            return;
+        await this.context.commit({ ...this.context.state, sources: [...this.context.state.sources, ...additions] });
+        // New sources change the fingerprint, but their content arrives through
+        // an acquire, so mark the scan cache dirty conservatively.
+        this.context.invalidateScans();
+        this.context.invalidateSnapshot(true);
+    }
+    async setInstalled(sourceId, suiteId, entry) {
+        await this.context.commit({ ...this.context.state, installed: { ...this.context.state.installed, [installKey(sourceId, suiteId)]: entry } });
+    }
+}

package/lib/application/lsp-service.js

@@ -0,0 +1,97 @@
+import { loadLspServers, saveLspServers } from '../runtime/lsp-direct-config.js';
+import { loadDisabledLspServers, saveDisabledLspServers } from '../runtime/lsp-server-state.js';
+import { buildLspStatus } from '../runtime/lsp-status.js';
+import { describeLegacySeam, findLegacyLspSeams, migrateLegacyLspSeam } from '../runtime/profile-seam.js';
+import { applyLspOverrides, lspConfig, validateServerLsp } from '../runtime/server-config.js';
+export class LspService {
+    context;
+    ports;
+    constructor(context, ports) {
+        this.context = context;
+        this.ports = ports;
+    }
+    /** The LSP status surface: declared servers merged with mount diagnostics. */
+    async status() {
+        const snapshot = await this.context.snapshots.readUserCatalog();
+        const direct = await loadLspServers(this.context.agentsRoot);
+        const payload = buildLspStatus(await applyLspOverrides(this.context.dataRoot, snapshot.suites), this.ports.lspStatusSource, direct);
+        // The profile scan is filesystem work, so it runs only while the conflict
+        // it explains is actually on screen — the panel polls this while rows start.
+        if (payload.entries.some(entry => entry.state === 'conflict'))
+            payload.legacySeam = await this.legacySeam();
+        return payload;
+    }
+    /** The profile layer behind a reported seam conflict, when one can be found. */
+    async legacySeam() {
+        const seams = await findLegacyLspSeams();
+        const seam = seams[0];
+        if (seam === undefined)
+            return undefined;
+        return {
+            profile: seam.profile,
+            patchPath: seam.patchPath,
+            rows: seam.rows.map(row => ({ id: row.id, name: row.name })),
+            otherProfiles: seams.slice(1).map(other => other.profile),
+            restartRequired: seam.patchReload !== 'live',
+            summary: describeLegacySeam(seam)
+        };
+    }
+    /**
+     * Remove one profile's legacy LSP layer, then re-reconcile.
+     *
+     * The removal edits a file the user owns, so the profile is matched against
+     * what was actually found on disk instead of trusting the request.
+     */
+    async migrateLegacySeam(profile) {
+        return this.context.enqueue(async () => {
+            const seams = await findLegacyLspSeams();
+            const seam = seams.find(candidate => candidate.profile === profile);
+            if (seam === undefined)
+                throw new Error(`the profile "${profile}" no longer registers an LSP layer`);
+            const result = await migrateLegacyLspSeam(seam);
+            await this.context.notifyChanged(true);
+            return { profile: result.profile, patchPath: result.patchPath, backupPath: result.backupPath, restartRequired: result.restartRequired };
+        });
+    }
+    /** The user's direct LSP server table (normalized specs). */
+    async servers() {
+        return (await loadLspServers(this.context.agentsRoot)).servers;
+    }
+    /** Create one direct LSP declaration without replacing other user servers. */
+    async addServer(name, config) {
+        return this.context.enqueue(async () => {
+            if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(name))
+                throw new Error('invalid LSP server name');
+            const direct = await loadLspServers(this.context.agentsRoot);
+            if (direct.errors.length > 0)
+                throw new Error(direct.errors.join('; '));
+            if (Object.hasOwn(direct.servers, name))
+                throw new Error('LSP server already exists');
+            const spec = validateServerLsp(name, config);
+            await saveLspServers(this.context.agentsRoot, {
+                lspServers: { ...Object.fromEntries(Object.entries(direct.servers).map(([key, value]) => [key, lspConfig(value)])), [name]: lspConfig(spec) }
+            });
+            await this.context.notifyChanged(true);
+        });
+    }
+    /** Validate and persist the user's direct LSP server table. */
+    async setServers(raw) {
+        return this.context.enqueue(async () => {
+            const { servers } = await saveLspServers(this.context.agentsRoot, raw);
+            await this.context.notifyChanged(true);
+            return servers;
+        });
+    }
+    /** Enable or disable one declared language server by row id. */
+    async setEnabled(id, enabled) {
+        return this.context.enqueue(async () => {
+            const disabled = await loadDisabledLspServers(this.context.dataRoot);
+            if (enabled)
+                disabled.delete(id);
+            else
+                disabled.add(id);
+            await saveDisabledLspServers(this.context.dataRoot, disabled);
+            await this.context.notifyChanged(true);
+        });
+    }
+}

package/lib/application/mcp-service.js

@@ -0,0 +1,246 @@
+/**
+ * MCP use cases: the flat service inventory, per-server overrides, the direct
+ * user servers, the mount-backend choice, and dropping one server's OAuth
+ * grant so the next mount re-runs the browser authorization.
+ *
+ * Server configuration is edited through saved overrides — a suite's own
+ * `mcp.json` stays source-owned and is never rewritten.
+ */
+import { qualifiedSuiteId } from '../catalog/paths.js';
+import { isDirectory } from '../catalog/fs-probes.js';
+import { discoverSuitesInSource } from '../catalog/suite-scanner.js';
+import { readLocalePreference } from '../runtime/host-locale.js';
+import { probeHostMcpClient } from '../runtime/mcp-backend.js';
+import { loadLspServers, saveLspServers } from '../runtime/lsp-direct-config.js';
+import { addUserMcpServer, loadUserMcpSuite, USER_MCP_SOURCE, USER_MCP_SUITE } from '../runtime/mcp-direct-config.js';
+import { applyOverride, loadSuiteOverrides, mergeOverridePatch, saveSuiteOverrides } from '../runtime/mcp-overrides.js';
+import { redactMcpConfig, redactMcpOverrides } from '../runtime/mcp-redaction.js';
+import { buildMcpStatus } from '../runtime/mcp-status.js';
+import { resolveRegion } from '../runtime/regions.js';
+import { applyLspOverrides, lspConfig, restoreRedactedConfig, saveLspOverride, validateServerLsp, validateServerMcp } from '../runtime/server-config.js';
+export class McpService {
+    context;
+    ports;
+    sources;
+    /** Latest MCP mount diagnostics (suiteId -> reasons), fed by host reconcile. */
+    diagnostics = [];
+    constructor(context, ports, sources) {
+        this.context = context;
+        this.ports = ports;
+        this.sources = sources;
+    }
+    /** Build the flat MCP service inventory for the status surface. */
+    async status() {
+        const snapshot = await this.context.snapshots.readUserCatalog();
+        const suites = [...snapshot.suites, await loadUserMcpSuite(this.context.agentsRoot)];
+        const payload = buildMcpStatus(suites, this.diagnostics, this.ports.mcpToolSnapshot(), await this.allOverrides(suites));
+        for (const entry of payload.entries)
+            if (entry.suiteId === `${USER_MCP_SOURCE}/${USER_MCP_SUITE}`) {
+                entry.kind = 'direct';
+                entry.managed = true;
+            }
+        const oauthBackend = (await this.backend()) === 'builtin' && this.reauthorizeAvailable();
+        for (const entry of payload.entries) {
+            const auth = entry.config?.auth;
+            entry.canReauthorize =
+                oauthBackend &&
+                    (entry.kind === 'plugin' || entry.managed === true) &&
+                    (entry.transport === 'sse' || entry.transport === 'streamable-http') &&
+                    auth?.enabled !== false &&
+                    !['disabled', 'foreign', 'orphaned'].includes(entry.state);
+        }
+        return payload;
+    }
+    /** Persist a user-owned MCP service and reconcile its bridge mount. */
+    async addServer(name, server) {
+        return this.context.enqueue(async () => {
+            await addUserMcpServer(this.context.agentsRoot, name, server);
+            await this.context.notifyChanged(true);
+        });
+    }
+    /** Read effective service configuration without exposing credential literals. */
+    async serverConfig(kind, id) {
+        const config = await this.resolveServerConfig(kind, id);
+        return { kind, id, editable: true, config: redactMcpConfig(config.value) };
+    }
+    /** Validate a complete replacement before writing; plugin checkouts remain untouched. */
+    async saveServerConfig(kind, id, config) {
+        return this.context.enqueue(async () => {
+            const current = await this.resolveServerConfig(kind, id);
+            const value = restoreRedactedConfig(config, current.value);
+            if (kind === 'mcp') {
+                const server = await validateServerMcp(current.root, current.key, value);
+                const overrides = await loadSuiteOverrides(this.context.dataRoot, current.suiteKey);
+                const enabled = overrides[current.key]?.enabled;
+                overrides[current.key] = { config: server, ...(enabled === undefined ? {} : { enabled }) };
+                await saveSuiteOverrides(this.context.dataRoot, current.suiteKey, overrides);
+            }
+            else {
+                const server = validateServerLsp(current.key, value);
+                if (current.suiteKey === 'direct') {
+                    const direct = await loadLspServers(this.context.agentsRoot);
+                    if (direct.errors.length > 0)
+                        throw new Error(direct.errors.join('; '));
+                    direct.servers[current.key] = server;
+                    await saveLspServers(this.context.agentsRoot, { lspServers: Object.fromEntries(Object.entries(direct.servers).map(([key, spec]) => [key, lspConfig(spec)])) });
+                }
+                else
+                    await saveLspOverride(this.context.dataRoot, id, server);
+            }
+            await this.context.notifyChanged(true);
+        });
+    }
+    /** One suite's persisted MCP overrides, addressed by qualified suite id. */
+    async overrides(sourceId, suiteId) {
+        const suiteKey = qualifiedSuiteId(sourceId, suiteId);
+        const snapshot = await this.context.snapshots.readUserCatalog();
+        if (!snapshot.suites.some(suite => suite.sourceId === sourceId && suite.id === suiteId))
+            throw new Error(`suite "${suiteKey}" not found`);
+        return redactMcpOverrides(await loadSuiteOverrides(this.context.dataRoot, suiteKey));
+    }
+    /**
+     * Set or clear one server's MCP override and remount it. `override === null`
+     * clears the override (back to the source config). The serverKey must exist
+     * in the suite's parsed mcp.json.
+     */
+    async setOverride(sourceId, suiteId, serverKey, override) {
+        return this.context.enqueue(async () => {
+            const suiteKey = qualifiedSuiteId(sourceId, suiteId);
+            const source = this.context.state.sources.find(entry => entry.id === sourceId);
+            // Only the suite's declared servers matter here, and one branch reads
+            // freshly scanned suites — the scan shape covers both.
+            let suites;
+            if (sourceId === USER_MCP_SOURCE && suiteId === USER_MCP_SUITE) {
+                suites = [await loadUserMcpSuite(this.context.agentsRoot)];
+            }
+            else {
+                if (source === undefined)
+                    throw new Error(`unknown source "${sourceId}"`);
+                const checkout = this.sources.checkoutPath(source);
+                if (!(await isDirectory(checkout)))
+                    await this.sources.acquire(source);
+                suites = await discoverSuitesInSource(checkout, sourceId, 'user', source.url);
+            }
+            const suite = suites.find(entry => entry.id === suiteId);
+            if (suite === undefined)
+                throw new Error(`suite "${suiteId}" not found in source "${sourceId}"`);
+            if (suite.mcp?.servers[serverKey] === undefined)
+                throw new Error(`server "${serverKey}" is not defined by suite "${suiteId}"`);
+            // Override files are keyed by the qualified id so two sources' same-named
+            // suites never share one override record.
+            const overrides = await loadSuiteOverrides(this.context.dataRoot, suiteKey);
+            if (override === null) {
+                delete overrides[serverKey];
+            }
+            else {
+                // Merge onto the stored record: the UI never receives literal secret
+                // values, so a verbatim write would drop keys it simply redacted.
+                overrides[serverKey] = mergeOverridePatch(overrides[serverKey] ?? {}, override);
+            }
+            await saveSuiteOverrides(this.context.dataRoot, suiteKey, overrides);
+            await this.context.notifyChanged(true);
+        });
+    }
+    /**
+     * Re-run the MCP reconcile pass: retries failed mounts and clears residual
+     * tools, without changing any catalog state.
+     *
+     * Every live mount is rebuilt rather than fingerprinted: a bridge whose
+     * server died underneath it keeps matching its own resolved config, so a
+     * retry is the only path that re-verifies a mount that looks connected. The
+     * wait is bounded — the pass keeps running, so a slow server reports its
+     * outcome to the status surface instead of holding the request open.
+     */
+    async retryMounts() {
+        this.ports.mcpRemountAll();
+        await this.context.notifyChanged(true);
+        await this.context.refreshSettled();
+    }
+    /** The persisted backend choice without the host-client probe (mount-time provider). */
+    async backend() {
+        return this.ports.mcpBackend();
+    }
+    /**
+     * The active MCP mount backend plus a live probe of the host client, and
+     * the download-region setting with its locale-resolved effective route —
+     * everything the plugin-config card renders.
+     */
+    async backendInfo() {
+        const [backend, hostClient, regionSetting, locale] = await Promise.all([this.ports.mcpBackend(), probeHostMcpClient(), this.ports.downloadRegion(), readLocalePreference()]);
+        return { backend, hostClient, downloadRegion: { setting: regionSetting, effective: resolveRegion(regionSetting, locale) } };
+    }
+    /**
+     * Switch the MCP mount backend and remount every suite server through it.
+     * A host-client switch takes effect only where the host package resolves;
+     * unresolvable or unsupported transports surface as per-server diagnostics.
+     */
+    async setBackend(backend) {
+        return this.context.enqueue(async () => {
+            await this.ports.setMcpBackend(backend);
+            await this.context.notifyChanged(true);
+        });
+    }
+    /**
+     * Drop one MCP server's OAuth grant record so the next mount re-runs the
+     * browser authorization — the path for "I picked too narrow a scope".
+     * @param serverName - the derived serverName whose folded form keys the record.
+     * @throws when the credentials service is not mounted.
+     */
+    async reauthorize(serverName) {
+        return this.context.enqueue(async () => {
+            await this.ports.credentialsStore?.deleteGrantRecord(serverName);
+            // Dropping a grant changes no resolved config field, so a fingerprint
+            // reconcile would keep the live bridge — with its in-memory tokens —
+            // untouched. The serverName maps back to exactly one mount key (the
+            // registry reserved the name), so flag it for an explicit rebuild.
+            const key = this.ports.mcpServerOwner(serverName);
+            if (key !== undefined)
+                this.ports.mcpRemount(key.suiteId, key.serverKey);
+            await this.context.notifyChanged(true);
+        });
+    }
+    /** Whether the re-authorize action can run in this composition. */
+    reauthorizeAvailable() {
+        return this.ports.credentialsStore !== undefined;
+    }
+    /** MCP overrides for a supplied runtime selection, or the full market catalog when omitted. */
+    async allOverrides(suites) {
+        const map = new Map();
+        for (const suite of suites ?? (await this.context.snapshots.readUserCatalog()).suites) {
+            const suiteKey = qualifiedSuiteId(suite.sourceId, suite.id);
+            const overrides = await loadSuiteOverrides(this.context.dataRoot, suiteKey);
+            if (Object.keys(overrides).length > 0)
+                map.set(suiteKey, overrides);
+        }
+        return map;
+    }
+    /** Resolve one editable server: its key, owning suite, root, and effective config. */
+    async resolveServerConfig(kind, id) {
+        if (kind === 'lsp' && id.startsWith('direct/')) {
+            const key = id.slice(7);
+            const server = (await loadLspServers(this.context.agentsRoot)).servers[key];
+            if (server === undefined)
+                throw new Error('LSP server not found');
+            return { key, suiteKey: 'direct', root: this.context.agentsRoot, value: lspConfig(server) };
+        }
+        const suites = [...(await this.context.snapshots.readUserCatalog()).suites, await loadUserMcpSuite(this.context.agentsRoot)];
+        for (const suite of await applyLspOverrides(this.context.dataRoot, suites)) {
+            const suiteKey = qualifiedSuiteId(suite.sourceId, suite.id);
+            if (kind === 'mcp') {
+                for (const [key, server] of Object.entries(suite.mcp?.servers ?? {})) {
+                    if (id !== `plugin:${suiteKey}/${key}`)
+                        continue;
+                    const overrides = await loadSuiteOverrides(this.context.dataRoot, suiteKey);
+                    return { key, suiteKey, root: suite.root, value: { ...applyOverride(server, overrides[key]) } };
+                }
+            }
+            else {
+                for (const [key, server] of Object.entries(suite.lsp?.servers ?? {})) {
+                    if (id === `${suiteKey}/${key}`)
+                        return { key, suiteKey, root: suite.root, value: lspConfig(server) };
+                }
+            }
+        }
+        throw new Error('service configuration is not managed by this plugin');
+    }
+}

package/lib/application/panel-resources.js

@@ -1,9 +1,22 @@
 /** Installed suite and user resources share one inventory; paths never come from HTTP callers. */
-import { realpath, unlink, writeFile } from 'node:fs/promises';
-import { isAbsolute, relative } from 'node:path';
+import { realpath, unlink } from 'node:fs/promises';
+import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
 import { defaultMarkdownResources, resourceText } from '../catalog/component-files.js';
+import { isWithin } from '../catalog/paths.js';
 import { stripFrontmatter } from '../catalog/skills-parse.js';
 import { parseFrontmatterRecord } from '../runtime/user-store.js';
+/**
+ * Id of one panel entry backed by a file inside an installed suite's checkout.
+ * The leading `[` is what distinguishes a plugin entry from a user-authored
+ * one; `update`/`remove` use {@link isPluginResourceId} to tell them apart.
+ */
+export function pluginResourceId(sourceId, suiteId, kind, name) {
+    return JSON.stringify([sourceId, suiteId, kind, name]);
+}
+/** Whether a panel entry id addresses a file inside an installed suite. */
+export function isPluginResourceId(id) {
+    return id.startsWith('[');
+}
 export function createPanelResources(catalog, users) {
     return {
         skills: new PanelResources(catalog, users.skills, 'skills'),
@@ -23,9 +36,8 @@ class PanelResources {
     async list(strict = false) {
         const entries = await this.users.list(strict);
         const snapshot = await this.catalog.readUserCatalog();
-        const installed = new Set((await this.catalog.overview()).suites.filter(suite => suite.installed).map(suite => JSON.stringify([suite.sourceId, suite.suiteId])));
         for (const suite of snapshot.suites) {
-            if (!installed.has(JSON.stringify([suite.sourceId, suite.id])) || suite.remote !== undefined)
+            if (!this.catalog.isInstalled(suite.sourceId, suite.id) || suite.remote !== undefined)
                 continue;
             const files = this.kind === 'skills'
                 ? suite.skills.map(skill => ({ name: skill.name, file: skill.file }))
@@ -47,11 +59,11 @@ class PanelResources {
                     metadata = { disabled: true, validationError: String(error) };
                 }
                 entries.push({
-                    id: JSON.stringify([suite.sourceId, suite.id, this.kind, name]),
+                    id: pluginResourceId(suite.sourceId, suite.id, this.kind, name),
                     name,
                     origin: 'plugin',
                     suiteName: suite.manifest.name,
-                    disabled: !suite.enabled || suite.activeSurfaces?.[this.kind] === false || metadata.disabled === true,
+                    disabled: !suite.enabled || suite.activeSurfaces[this.kind] === false || metadata.disabled === true,
                     metadata,
                     rawText,
                     content: stripFrontmatter(rawText),
@@ -68,27 +80,32 @@ class PanelResources {
     create(name, text) {
         return this.users.create(name, text);
     }
+    /**
+     * A plugin resource is writable only when it sits inside the user dimension
+     * root; suite checkouts elsewhere on disk stay read-only. The user-panel
+     * store lives in the shared Agent layout root instead, so containment is
+     * measured against the catalog's root, not the panel directory.
+     */
     async pluginPath(id) {
         const entry = await this.get(id);
         if (entry?.origin !== 'plugin')
             throw new Error('Unknown installed plugin resource');
         if (entry.path.endsWith('.json'))
             throw new Error('Inline manifest resources are read-only; edit their source manifest');
-        const root = await realpath(this.users.root());
+        const root = await realpath(this.catalog.userRoot);
         const path = await realpath(entry.path);
-        const rel = relative(root, path);
-        if (rel === '..' || rel.startsWith('../') || isAbsolute(rel))
+        if (!isWithin(root, path))
             throw new Error('External source files are read-only; create a user resource to customize them');
         return path;
     }
     async update(id, text) {
-        if (!id.startsWith('['))
+        if (!isPluginResourceId(id))
             return this.users.update(id, text);
         parseFrontmatterRecord(text);
-        await writeFile(await this.pluginPath(id), text, 'utf8');
+        await writeFileAtomic(await this.pluginPath(id), text, { mode: 0o644 });
     }
     async remove(id) {
-        if (!id.startsWith('['))
+        if (!isPluginResourceId(id))
             return this.users.remove(id);
         await unlink(await this.pluginPath(id));
     }

package/lib/application/ports.js

@@ -0,0 +1,21 @@
+/**
+ * The seams a catalog runs on when nothing is wired. The MCP backend writer
+ * rejects rather than silently accepting a choice nothing can persist.
+ */
+export const defaultCatalogPorts = {
+    mcpToolSnapshot: () => [],
+    credentialsStore: undefined,
+    mcpRemount: () => { },
+    mcpRemountAll: () => { },
+    mcpServerOwner: () => undefined,
+    lspStatusSource: { diagnosticsSnapshot: () => new Map(), hasLiveMounts: () => false },
+    mcpBackend: async () => 'builtin',
+    setMcpBackend: async () => {
+        throw new Error('the settings service is not mounted');
+    },
+    downloadRegion: async () => 'auto'
+};
+/** Fill in every seam the composition root left unwired. */
+export function resolveCatalogPorts(overrides = {}) {
+    return { ...defaultCatalogPorts, ...overrides };
+}

package/lib/application/project-agent-roles.js

@@ -8,7 +8,7 @@ export async function projectAgentRoles(catalog, parent) {
     const snapshot = await catalog.readProjectCatalog(cwd);
     const entries = [];
     for (const suite of snapshot.enabledSuites) {
-        if (suite.activeSurfaces?.agents === false)
+        if (suite.activeSurfaces.agents === false)
             continue;
         for (const resource of suite.resources?.agents ?? (await defaultMarkdownResources(suite.root, 'agents'))) {
             const path = resource.file;