dsh-agent-plugins-market 0.6.0 → 0.6.2

package/lib/application/catalog.js

@@ -16,13 +16,16 @@ import { discoverSuitesInSource } from '../catalog/suite-scanner.js';
 import { archiveInstall } from '../catalog/archive.js';
 import { gitClone, gitCurrentBranch, gitHead, gitRemoteUrl, gitRemove, gitSetRemoteUrl, gitSync } from '../catalog/git.js';
 import { buildMcpStatus } from '../runtime/mcp-status.js';
+import { addUserMcpServer, loadUserMcpSuite, USER_MCP_SOURCE, USER_MCP_SUITE } from '../runtime/mcp-direct-config.js';
 import { buildLspStatus } from '../runtime/lsp-status.js';
 import { loadLspServers, saveLspServers } from '../runtime/lsp-direct-config.js';
-import { loadSuiteOverrides, mergeOverridePatch, saveSuiteOverrides } from '../runtime/mcp-overrides.js';
+import { loadDisabledLspServers, saveDisabledLspServers } from '../runtime/lsp-server-state.js';
+import { applyOverride, loadSuiteOverrides, mergeOverridePatch, saveSuiteOverrides } from '../runtime/mcp-overrides.js';
+import { applyLspOverrides, lspConfig, restoreRedactedConfig, saveLspOverride, validateServerLsp, validateServerMcp } from '../runtime/server-config.js';
 import { probeHostMcpClient } from '../runtime/mcp-backend.js';
 import { githubCloneUrl, resolveRegion } from '../runtime/regions.js';
 import { readLocalePreference } from '../runtime/host-locale.js';
-import { redactMcpOverrides } from '../runtime/mcp-redaction.js';
+import { redactMcpConfig, redactMcpOverrides } from '../runtime/mcp-redaction.js';
 import { buildSuiteDetail, readSkillContent } from './details.js';
 import { deriveSourceIdCandidates, expandHome, isDirectory, pathExists, qualifiedSuiteId, resolveProjectRoot, sanitizeId, sourceCheckoutDir, sourcesDir, STATE_FILE_NAME } from '../catalog/paths.js';
 import { loadState, saveState, EMPTY_STATE } from '../model/state.js';
@@ -44,12 +47,13 @@ export class Catalog {
      * discovery (cheap mapping) instead of re-walking every checkout — a full
      * rescan of a 2,500-suite catalog costs ~1s and UI mutations happen in
      * bursts. Content-changing mutations (add / update / remove / adopt /
-     * refresh / acquire) set {@link scanCacheDirty}, which bypasses the cache
-     * until the next scan; the TTL bounds staleness for in-place working-tree
+     * refresh / acquire) clear every cached discovery generation; the TTL
+     * bounds staleness for in-place working-tree
      * edits of local sources.
      */
     scanCache = new Map();
-    scanCacheDirty = true;
+    scanGeneration = 0;
+    scanPromises = new Map();
     static SCAN_CACHE_TTL_MS = 30_000;
     static SCAN_CACHE_MAX_ENTRIES = 8;
     /**
@@ -83,6 +87,14 @@ export class Catalog {
     };
     /** Download-region source (the host settings namespace scope). */
     downloadRegionProvider = async () => 'auto';
+    scanProjectLayouts = true;
+    /** Apply the host's project-layout switch and invalidate every project snapshot. */
+    async setScanProjectLayouts(enabled) {
+        if (this.scanProjectLayouts === enabled)
+            return;
+        this.scanProjectLayouts = enabled;
+        await this.notifyChanged();
+    }
     constructor(options) {
         this.options = options;
         this.statePath = join(options.userRoot, STATE_FILE_NAME);
@@ -140,18 +152,119 @@ export class Catalog {
     /** Build the flat MCP service inventory for the status surface. */
     async mcpStatus() {
         const snapshot = await this.readUserCatalog();
-        return buildMcpStatus(snapshot.suites, this.mcpDiagnostics, this.toolSnapshotProvider(), await this.allMcpOverrides());
+        const suites = [...snapshot.suites, await loadUserMcpSuite(this.options.dataRoot)];
+        const payload = buildMcpStatus(suites, this.mcpDiagnostics, this.toolSnapshotProvider(), await this.allMcpOverrides(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.mcpBackend()) === 'builtin' && this.mcpReauthorizeAvailable();
+        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 addMcpServer(name, server) {
+        return this.enqueue(async () => {
+            await addUserMcpServer(this.options.dataRoot, name, server);
+            await this.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) };
+    }
+    async resolveServerConfig(kind, id) {
+        if (kind === 'lsp' && id.startsWith('direct/')) {
+            const key = id.slice(7);
+            const server = (await loadLspServers(this.options.dataRoot)).servers[key];
+            if (server === undefined)
+                throw new Error('LSP server not found');
+            return { key, suiteKey: 'direct', root: this.options.dataRoot, value: lspConfig(server) };
+        }
+        const suites = [...(await this.readUserCatalog()).suites, await loadUserMcpSuite(this.options.dataRoot)];
+        for (const suite of await applyLspOverrides(this.options.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.options.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');
+    }
+    /** Validate a complete replacement before writing; plugin checkouts remain untouched. */
+    async saveServerConfig(kind, id, config) {
+        return this.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.options.dataRoot, current.suiteKey);
+                const enabled = overrides[current.key]?.enabled;
+                overrides[current.key] = { config: server, ...(enabled === undefined ? {} : { enabled }) };
+                await saveSuiteOverrides(this.options.dataRoot, current.suiteKey, overrides);
+            }
+            else {
+                const server = validateServerLsp(current.key, value);
+                if (current.suiteKey === 'direct') {
+                    const direct = await loadLspServers(this.options.dataRoot);
+                    if (direct.errors.length > 0)
+                        throw new Error(direct.errors.join('; '));
+                    direct.servers[current.key] = server;
+                    await saveLspServers(this.options.dataRoot, { lspServers: Object.fromEntries(Object.entries(direct.servers).map(([key, spec]) => [key, lspConfig(spec)])) });
+                }
+                else
+                    await saveLspOverride(this.options.dataRoot, id, server);
+            }
+            await this.notifyChanged(true);
+        });
     }
     /** The LSP status surface: declared servers merged with mount diagnostics. */
     async lspStatus() {
         const snapshot = await this.readUserCatalog();
         const direct = await loadLspServers(this.options.dataRoot);
-        return buildLspStatus(snapshot.suites, this.lspStatusSource ?? { diagnosticsSnapshot: () => new Map(), hasLiveMounts: () => false }, direct);
+        return buildLspStatus(await applyLspOverrides(this.options.dataRoot, snapshot.suites), this.lspStatusSource ?? { diagnosticsSnapshot: () => new Map(), hasLiveMounts: () => false }, direct);
     }
     /** The user's direct LSP server table (normalized specs). */
     async lspServers() {
         return (await loadLspServers(this.options.dataRoot)).servers;
     }
+    /** Create one direct LSP declaration without replacing other user servers. */
+    async addLspServer(name, config) {
+        return this.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.options.dataRoot);
+            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.options.dataRoot, {
+                lspServers: { ...Object.fromEntries(Object.entries(direct.servers).map(([key, value]) => [key, lspConfig(value)])), [name]: lspConfig(spec) }
+            });
+            await this.notifyChanged(true);
+        });
+    }
     /** Validate and persist the user's direct LSP server table. */
     async setLspServers(raw) {
         return this.enqueue(async () => {
@@ -160,6 +273,17 @@ export class Catalog {
             return servers;
         });
     }
+    async setLspServerEnabled(id, enabled) {
+        return this.enqueue(async () => {
+            const disabled = await loadDisabledLspServers(this.options.dataRoot);
+            if (enabled)
+                disabled.delete(id);
+            else
+                disabled.add(id);
+            await saveDisabledLspServers(this.options.dataRoot, disabled);
+            await this.notifyChanged(true);
+        });
+    }
     /** One suite's persisted MCP overrides, addressed by qualified suite id. */
     async mcpOverrides(sourceId, suiteId) {
         const suiteKey = qualifiedSuiteId(sourceId, suiteId);
@@ -177,12 +301,18 @@ export class Catalog {
         return this.enqueue(async () => {
             const suiteKey = qualifiedSuiteId(sourceId, suiteId);
             const source = this.state.sources.find(entry => entry.id === sourceId);
-            if (source === undefined)
-                throw new Error(`unknown source "${sourceId}"`);
-            const checkout = this.sourceCheckoutPath(source);
-            if (!(await isDirectory(checkout)))
-                await this.acquire(source);
-            const suites = await discoverSuitesInSource(checkout, sourceId, 'user', source.url);
+            let suites;
+            if (sourceId === USER_MCP_SOURCE && suiteId === USER_MCP_SUITE) {
+                suites = [await loadUserMcpSuite(this.options.dataRoot)];
+            }
+            else {
+                if (source === undefined)
+                    throw new Error(`unknown source "${sourceId}"`);
+                const checkout = this.sourceCheckoutPath(source);
+                if (!(await isDirectory(checkout)))
+                    await this.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}"`);
@@ -246,11 +376,10 @@ export class Catalog {
     setDownloadRegionProvider(provider) {
         this.downloadRegionProvider = provider;
     }
-    /** All persisted MCP overrides keyed by qualified suite id (mount-time provider). */
-    async allMcpOverrides() {
-        const snapshot = await this.readUserCatalog();
+    /** MCP overrides for a supplied runtime selection, or the full market catalog when omitted. */
+    async allMcpOverrides(suites) {
         const map = new Map();
-        for (const suite of snapshot.suites) {
+        for (const suite of suites ?? (await this.readUserCatalog()).suites) {
             const suiteKey = qualifiedSuiteId(suite.sourceId, suite.id);
             const overrides = await loadSuiteOverrides(this.options.dataRoot, suiteKey);
             if (Object.keys(overrides).length > 0)
@@ -261,7 +390,7 @@ export class Catalog {
     /** Load persisted user state once at plugin activation. */
     async load() {
         this.state = await loadState(this.statePath);
-        this.scanCacheDirty = true;
+        this.invalidateScans();
         this.invalidateSnapshot(false);
     }
     get sources() {
@@ -279,16 +408,24 @@ export class Catalog {
             return this.buildSnapshot(this.state, 'user', this.options.userRoot);
         if (this.userSnapshot !== undefined && Date.now() < this.userSnapshotExpiresAt)
             return this.userSnapshot;
-        this.userSnapshotPromise ??= this.buildSnapshot(this.state, 'user', this.options.userRoot)
+        if (this.userSnapshotPromise !== undefined)
+            return this.userSnapshotPromise;
+        const revision = this.revision;
+        const generation = this.scanGeneration;
+        const promise = this.buildSnapshot(this.state, 'user', this.options.userRoot)
             .then(snapshot => {
-            this.userSnapshot = snapshot;
-            this.userSnapshotExpiresAt = Date.now() + this.userSnapshotTtlMs;
+            if (revision === this.revision && generation === this.scanGeneration) {
+                this.userSnapshot = snapshot;
+                this.userSnapshotExpiresAt = Date.now() + this.userSnapshotTtlMs;
+            }
             return snapshot;
         })
             .finally(() => {
-            this.userSnapshotPromise = undefined;
+            if (this.userSnapshotPromise === promise)
+                this.userSnapshotPromise = undefined;
         });
-        return this.userSnapshotPromise;
+        this.userSnapshotPromise = promise;
+        return promise;
     }
     /** Read one coherent project-dimension snapshot for a workspace cwd. */
     async readProjectCatalog(cwd) {
@@ -301,13 +438,18 @@ export class Catalog {
         const inFlight = this.projectSnapshotPromises.get(projectRoot);
         if (inFlight !== undefined)
             return inFlight;
+        const revision = this.revision;
+        const generation = this.scanGeneration;
         const promise = this.buildProjectSnapshot(projectRoot)
             .then(snapshot => {
-            this.projectSnapshots.set(projectRoot, { snapshot, expiresAt: Date.now() + this.projectSnapshotTtlMs });
+            if (revision === this.revision && generation === this.scanGeneration) {
+                this.projectSnapshots.set(projectRoot, { snapshot, expiresAt: Date.now() + this.projectSnapshotTtlMs });
+            }
             return snapshot;
         })
             .finally(() => {
-            this.projectSnapshotPromises.delete(projectRoot);
+            if (this.projectSnapshotPromises.get(projectRoot) === promise)
+                this.projectSnapshotPromises.delete(projectRoot);
         });
         this.projectSnapshotPromises.set(projectRoot, promise);
         return promise;
@@ -423,14 +565,20 @@ export class Catalog {
             unmanaged: await this.unmanagedSources()
         };
     }
-    /** Enabled user-dimension suites from one user snapshot. */
+    /** Runtime discovery scans only sources containing an enabled install. No acquisition or network access. */
     async enabledUserSuites() {
-        return (await this.readUserCatalog()).enabledSuites;
+        const enabledSources = new Set(Object.entries(this.state.installed)
+            .filter(([, entry]) => entry.enabled)
+            .map(([key]) => key.slice(0, key.indexOf('/'))));
+        const sources = this.state.sources.filter(source => enabledSources.has(source.id));
+        const suites = sources.length === 0 ? [] : (await this.buildSnapshot({ ...this.state, sources }, 'user', this.options.userRoot)).enabledSuites;
+        const direct = await loadUserMcpSuite(this.options.dataRoot);
+        return applyLspOverrides(this.options.dataRoot, Object.keys(direct.mcp.servers).length === 0 ? suites : [...suites, direct]);
     }
     /** Enabled user- and project-dimension suites for a workspace cwd. */
     async enabledSuitesForCwd(cwd) {
-        const [user, project] = await Promise.all([this.readUserCatalog(), this.readProjectCatalog(cwd)]);
-        return { user: user.enabledSuites, project: project.enabledSuites };
+        const [user, project] = await Promise.all([this.enabledUserSuites(), this.readProjectCatalog(cwd)]);
+        return { user, project: project.enabledSuites };
     }
     /** All suites of one dimension. */
     async suitesForDimension(dimension, dimensionRoot) {
@@ -681,8 +829,16 @@ export class Catalog {
             await this.notifyChanged();
         });
     }
-    /** Remove a source, its install entries, and its managed checkout. */
-    async removeSource(sourceId) {
+    /**
+     * Remove a source and its install entries. `deleteCheckout` (the UI's
+     * "also delete the managed market directory" option) physically removes the
+     * `.sources/<id>` checkout — including an adopted one, since a directory
+     * under `.sources` is manager-owned storage. A `local` source whose URL
+     * points outside `.sources` is registration-only: its directory is never
+     * touched. Deleting the checkout is what keeps a removed source from
+     * reappearing as an unmanaged entry.
+     */
+    async removeSource(sourceId, deleteCheckout = false) {
         return this.enqueue(async () => {
             const source = this.state.sources.find(entry => entry.id === sourceId);
             this.state = {
@@ -692,10 +848,11 @@ export class Catalog {
             };
             await saveState(this.statePath, this.state);
             this.headCache.delete(sourceId);
-            // Adopted checkouts (manual clones) and local paths are user-owned
-            // directories; only self-acquired checkouts are deleted.
-            const userOwned = source !== undefined && (source.local === true || source.adopted === true);
-            if (!userOwned)
+            // A checkout under `.sources` is manager-owned even when it was first
+            // discovered/adopted. Only an explicit local path points outside the
+            // manager's storage and must remain untouched.
+            const externalLocal = source?.local === true && source.url !== sourceCheckoutDir(this.options.userRoot, sourceId);
+            if (!externalLocal && deleteCheckout)
                 await gitRemove(sourceCheckoutDir(this.options.userRoot, sourceId));
             await this.notifyChanged();
         });
@@ -853,9 +1010,18 @@ export class Catalog {
         await saveState(this.statePath, this.state);
         // New sources change the fingerprint, but their content arrives through
         // an acquire, so mark the scan cache dirty conservatively.
-        this.scanCacheDirty = true;
+        this.invalidateScans();
         this.invalidateSnapshot(true);
     }
+    /**
+     * Panel changed hook: the HTTP layer notifies after a user-panel mutation
+     * (skills / commands / agent personas). Catalog state is untouched — this
+     * only runs the change pipeline so the runtime remounts commands and the
+     * skill providers re-read their catalogs.
+     */
+    async notifyPanelsChanged() {
+        await this.notifyChanged();
+    }
     async setInstalled(sourceId, suiteId, entry) {
         this.state = { ...this.state, installed: { ...this.state.installed, [installKey(sourceId, suiteId)]: entry } };
         await saveState(this.statePath, this.state);
@@ -910,12 +1076,12 @@ export class Catalog {
         return source.local === true ? expandHome(source.url) : sourceCheckoutDir(this.options.userRoot, source.id);
     }
     async buildSnapshot(state, dimension, dimensionRoot, skipScanCache = false) {
-        const fingerprint = JSON.stringify([dimension, dimensionRoot, state.sources]);
+        const fingerprint = JSON.stringify([dimension, dimensionRoot, state.sources, this.scanProjectLayouts]);
         const cached = this.scanCache.get(fingerprint);
         // The user snapshot's TTL also bounds scan reuse: a snapshot rebuild that
         // replays a 30s scan cache would silently outlive its own staleness bound.
         const scanCacheTtl = dimension === 'user' ? Math.min(this.userSnapshotTtlMs, Catalog.SCAN_CACHE_TTL_MS) : Catalog.SCAN_CACHE_TTL_MS;
-        const cacheFresh = !skipScanCache && !this.scanCacheDirty && cached !== undefined && Date.now() - cached.at < scanCacheTtl;
+        const cacheFresh = !skipScanCache && cached !== undefined && Date.now() - cached.at < scanCacheTtl;
         let discovered;
         let scanNotes;
         if (cacheFresh && cached !== undefined) {
@@ -923,15 +1089,28 @@ export class Catalog {
             scanNotes = cached.scanNotes;
         }
         else {
-            const result = await discoverSourceListWithNotes(state.sources, dimension, dimensionRoot);
+            const generation = this.scanGeneration;
+            let pending = this.scanPromises.get(fingerprint);
+            if (pending === undefined) {
+                pending = discoverSourceListWithNotes(state.sources, dimension, dimensionRoot, this.scanProjectLayouts);
+                this.scanPromises.set(fingerprint, pending);
+            }
+            let result;
+            try {
+                result = await pending;
+            }
+            finally {
+                if (this.scanPromises.get(fingerprint) === pending)
+                    this.scanPromises.delete(fingerprint);
+            }
             discovered = result.suites;
             scanNotes = result.scanNotes;
-            // The fresh scan satisfies the invalidation: content mutations mark the
-            // cache dirty, and the next scan (this one) makes it clean again.
-            this.scanCacheDirty = false;
-            if (this.scanCache.size >= Catalog.SCAN_CACHE_MAX_ENTRIES)
-                this.scanCache.clear();
-            this.scanCache.set(fingerprint, { at: Date.now(), discovered, scanNotes });
+            // A scan started before a content mutation must not repopulate its cache.
+            if (generation === this.scanGeneration) {
+                if (this.scanCache.size >= Catalog.SCAN_CACHE_MAX_ENTRIES)
+                    this.scanCache.clear();
+                this.scanCache.set(fingerprint, { at: Date.now(), discovered, scanNotes });
+            }
         }
         const suites = discovered.map(suite => {
             const installed = state.installed[installKey(suite.sourceId, suite.id)];
@@ -941,7 +1120,11 @@ export class Catalog {
             return {
                 ...suite,
                 enabled,
-                activeSurfaces: effectiveSurfaces(installed?.surfaces),
+                activeSurfaces: {
+                    ...effectiveSurfaces(installed?.surfaces),
+                    ...(suite.manifest.layout === 'project-native' ? suite.activeSurfaces : {}),
+                    ...(dimension === 'project' ? { lsp: false } : {})
+                },
                 ...(installed?.lockCommit === undefined ? {} : { lockCommit: installed.lockCommit }),
                 ...(installed?.installedAt === undefined ? {} : { installedAt: installed.installedAt })
             };
@@ -961,6 +1144,12 @@ export class Catalog {
         this.userSnapshotExpiresAt = 0;
         this.userSnapshotPromise = undefined;
         this.projectSnapshots.clear();
+        this.projectSnapshotPromises.clear();
+    }
+    invalidateScans() {
+        this.scanGeneration++;
+        this.scanCache.clear();
+        this.scanPromises.clear();
     }
     /**
      * Invalidate snapshots and run the change pipeline. `keepScanCache` marks
@@ -970,7 +1159,7 @@ export class Catalog {
      */
     async notifyChanged(keepScanCache = false) {
         if (!keepScanCache)
-            this.scanCacheDirty = true;
+            this.invalidateScans();
         this.invalidateSnapshot(true);
         await this.options.onChanged();
         for (const listener of this.listeners)

package/lib/application/details.js

@@ -1,7 +1,8 @@
 /** Suite detail and preview projections owned by the application layer. */
 import { readFile } from 'node:fs/promises';
 import { parse as parseYaml } from 'yaml';
-import { discoverLspEntries, listMdFiles } from '../catalog/surfaces.js';
+import { discoverLspEntries } from '../catalog/surfaces.js';
+import { defaultMarkdownResources, resourceText } from '../catalog/component-files.js';
 import { credentialRefsInServer } from '../runtime/mcp-config.js';
 import { redactMcpConfig, redactMcpOverrides } from '../runtime/mcp-redaction.js';
 import { applyOverride } from '../runtime/mcp-overrides.js';
@@ -41,9 +42,15 @@ export async function buildSuiteDetail(suite, installed, diagnostics, mcpOverrid
                     credentialRefs: credentialRefsInServer(effective)
                 };
             }),
-        hooks: remoteUrl === undefined ? await hooksPreviews(suite.root) : { count: 0, entries: [] },
-        commands: remoteUrl === undefined ? await markdownPreviews(`${suite.root}/commands`) : [],
-        agents: remoteUrl === undefined ? await markdownPreviews(`${suite.root}/agents`) : [],
+        hooks: remoteUrl === undefined
+            ? suite.hooks === undefined
+                ? suite.resources === undefined
+                    ? await hooksPreviews(suite.root)
+                    : { count: 0, entries: [] }
+                : normalizedHookPreviews(suite)
+            : { 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'))) : [],
         lsp: remoteUrl === undefined ? await lspDetail(suite) : { servers: [], raw: [] },
         errors: suite.errors,
         mcpErrors: diagnostics.filter(diagnostic => diagnostic.suiteId === suite.id).map(diagnostic => `${diagnostic.serverKey}: ${diagnostic.reason}`)
@@ -67,13 +74,11 @@ async function readPreview(path, capBytes = 64 * 1024) {
     const text = await readFile(path, 'utf8');
     return text.length > capBytes ? `${text.slice(0, capBytes)}\n… (truncated)` : text;
 }
-async function markdownPreviews(dir) {
-    const names = await listMdFiles(dir);
+async function markdownPreviews(resources) {
     const previews = [];
-    for (const name of names) {
-        const file = `${dir}/${name}`;
+    for (const resource of resources) {
         try {
-            const content = await readPreview(file);
+            const content = (await resourceText(resource)).slice(0, 64 * 1024);
             const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
             let description;
             if (match !== null) {
@@ -84,7 +89,7 @@ async function markdownPreviews(dir) {
                         description = desc;
                 }
             }
-            previews.push({ name: name.slice(0, -3), ...(description === undefined ? {} : { description }), content });
+            previews.push({ name: resource.name, ...(description === undefined ? {} : { description }), content });
         }
         catch {
             // Unreadable preview files are omitted from the detail response.
@@ -92,6 +97,10 @@ async function markdownPreviews(dir) {
     }
     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 }))));
+    return { count: entries.length, entries };
+}
 async function hooksPreviews(root) {
     for (const relative of ['hooks/hooks.json', 'hooks.json']) {
         let text;

package/lib/application/panel-resources.js

@@ -0,0 +1,95 @@
+/** 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 { defaultMarkdownResources, resourceText } from '../catalog/component-files.js';
+import { stripFrontmatter } from '../catalog/skills-parse.js';
+import { parseFrontmatterRecord } from '../runtime/user-store.js';
+export function createPanelResources(catalog, users) {
+    return {
+        skills: new PanelResources(catalog, users.skills, 'skills'),
+        commands: new PanelResources(catalog, users.commands, 'commands'),
+        agents: new PanelResources(catalog, users.agents, 'agents')
+    };
+}
+class PanelResources {
+    catalog;
+    users;
+    kind;
+    constructor(catalog, users, kind) {
+        this.catalog = catalog;
+        this.users = users;
+        this.kind = kind;
+    }
+    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)
+                continue;
+            const files = this.kind === 'skills'
+                ? suite.skills.map(skill => ({ name: skill.name, file: skill.file }))
+                : (suite.resources?.[this.kind] ?? (await defaultMarkdownResources(suite.root, this.kind)));
+            for (const resource of files) {
+                const { name, file } = resource;
+                const rawText = await resourceText(resource).catch(error => {
+                    if (strict && error.code !== 'ENOENT')
+                        throw error;
+                    return undefined;
+                });
+                if (rawText === undefined)
+                    continue;
+                let metadata;
+                try {
+                    metadata = parseFrontmatterRecord(rawText);
+                }
+                catch (error) {
+                    metadata = { disabled: true, validationError: String(error) };
+                }
+                entries.push({
+                    id: JSON.stringify([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,
+                    metadata,
+                    rawText,
+                    content: stripFrontmatter(rawText),
+                    path: file,
+                    description: typeof metadata.description === 'string' ? metadata.description : ''
+                });
+            }
+        }
+        return entries;
+    }
+    async get(id) {
+        return (await this.list()).find(entry => (entry.id ?? entry.name) === id);
+    }
+    create(name, text) {
+        return this.users.create(name, text);
+    }
+    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 path = await realpath(entry.path);
+        const rel = relative(root, path);
+        if (rel === '..' || rel.startsWith('../') || isAbsolute(rel))
+            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('['))
+            return this.users.update(id, text);
+        parseFrontmatterRecord(text);
+        await writeFile(await this.pluginPath(id), text, 'utf8');
+    }
+    async remove(id) {
+        if (!id.startsWith('['))
+            return this.users.remove(id);
+        await unlink(await this.pluginPath(id));
+    }
+}

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

@@ -0,0 +1,39 @@
+/** Resolve read-only project roles from the calling session, never from tool-supplied paths. */
+import { defaultMarkdownResources, resourceText } from '../catalog/component-files.js';
+import { parseAgentRole } from '../runtime/agent-role-router.js';
+export async function projectAgentRoles(catalog, parent) {
+    const cwd = parent?.session?.header?.cwd;
+    if (typeof cwd !== 'string' || cwd === '')
+        return [];
+    const snapshot = await catalog.readProjectCatalog(cwd);
+    const entries = [];
+    for (const suite of snapshot.enabledSuites) {
+        if (suite.activeSurfaces?.agents === false)
+            continue;
+        for (const resource of suite.resources?.agents ?? (await defaultMarkdownResources(suite.root, 'agents'))) {
+            const path = resource.file;
+            const rawText = await resourceText(resource).catch(error => {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                return undefined;
+            });
+            if (rawText === undefined)
+                continue;
+            try {
+                const policy = parseAgentRole(rawText);
+                entries.push({
+                    name: JSON.stringify([suite.sourceId, suite.id, 'agents', resource.name]),
+                    path,
+                    rawText,
+                    title: policy.title ?? resource.name.replace(/\.agent$/, ''),
+                    description: policy.description ?? `${suite.manifest.name}: ${resource.name}`,
+                    disabled: policy.disabled
+                });
+            }
+            catch {
+                // Malformed routing metadata cannot authorize a project role.
+            }
+        }
+    }
+    return entries;
+}