dsh-agent-plugins-market 0.6.2 → 0.7.0

package/lib/index.js

@@ -1,21 +1,23 @@
 import { Catalog } from './application/catalog.js';
+import { settlesWithin } from './runtime/deadline.js';
 import { RuntimeReconciler } from './runtime/reconciler.js';
+import { ReconcileScheduler } from './runtime/reconcile-scheduler.js';
+import { MarketSettingsNamespace } from './runtime/settings-namespace.js';
+import { deleteMcpAuthGrant } from './runtime/mcp-auth-record.js';
 import { inspectToolRegistry } from './runtime/tool-registry-observer.js';
 import { migratePluginStorage } from './runtime/storage-migration.js';
 import { mountAgentRoleTool } from './runtime/agent-role-router.js';
 import { projectAgentRoles } from './application/project-agent-roles.js';
 import { mountProjectCommands, mountProjectMcp, mountProjectHooks, mountSuiteInstructions } from './runtime/project-runtime.js';
 import { createPanelResources } from './application/panel-resources.js';
-import { resolveDataRoot, resolveUserRoot } from './catalog/paths.js';
+import { resolveAgentsRoot, resolveDataRoot, resolveUserRoot } from './catalog/paths.js';
 import { mountSuiteRoutes } from './routes.js';
-import { MCP_SETTINGS_NAMESPACE, MarketSettingsSchema, readMcpBackend } from './runtime/mcp-backend.js';
-import { narrowDownloadRegion } from './runtime/regions.js';
 import { SuiteSkillProvider } from './runtime/skills-provider.js';
 import { loadLspServers } from './runtime/lsp-direct-config.js';
 import { loadDisabledLspServers } from './runtime/lsp-server-state.js';
 import { bindHostLocale, loadHostLocale } from './runtime/host-locale.js';
-import { mountFeedbackTool } from './runtime/feedback-tool.js';
 import { createUserPanelStores } from './runtime/user-panels.js';
+import { SourceAutoUpdater } from './runtime/source-auto-update.js';
 import { UserPanelSkillProvider } from './runtime/user-panels.js';
 import { UserCommandMountRegistry } from './runtime/user-commands.js';
 export const name = 'dsh-agent-plugins-market';
@@ -23,6 +25,7 @@ export const inject = ['skills', 'commands'];
 export async function apply(ctx, config = {}) {
     const userRoot = resolveUserRoot(config.userRoot);
     const dataRoot = resolveDataRoot(config.dataRoot, userRoot);
+    const agentsRoot = resolveAgentsRoot();
     const migration = await migratePluginStorage(config);
     if (migration.conflicts.length > 0)
         throw new Error(`Plugin storage migration conflicts (original files retained): ${migration.conflicts.join(', ')}`);
@@ -30,240 +33,126 @@ export async function apply(ctx, config = {}) {
     let userPanelControl;
     // Host runtime copy resolves from the harness `locale.preference` setting;
     // the async settings read lands before the first session starts in practice.
-    const t = bindHostLocale(undefined);
+    const hostLocale = { t: bindHostLocale(undefined) };
     void loadHostLocale().then(locale => {
         hostLocale.t = locale.t;
         providerControl?.invalidate();
         userPanelControl?.invalidate();
     });
-    const hostLocale = { t };
-    /** Settings watchers to release at teardown (backend watch + feedback switch). */
-    const settingsWatchers = [];
     const runtime = new RuntimeReconciler(ctx, dataRoot, key => hostLocale.t(key));
     // User panel stores (skills / commands / agent personas) and their runtime
     // contributions: one extra skill provider plus one command mount registry.
-    const panels = createUserPanelStores(userRoot);
+    const panels = createUserPanelStores(agentsRoot);
     const userCommands = new UserCommandMountRegistry(ctx, panels.commands, key => hostLocale.t(key));
     let disposed = false;
     let projectCommands;
     let projectMcp;
     let projectHooks;
     let suitePrompts;
-    let reconcileRequested = false;
-    let reconciliation;
-    const reconcileOnce = async () => {
-        try {
-            const suites = await catalog.enabledUserSuites();
-            if (disposed)
-                return;
-            const diagnostics = await runtime.reconcile(suites);
-            catalog.mcpDiagnostics = diagnostics.mcp;
-            for (const diagnostic of diagnostics.mcp) {
-                ctx.logger?.warn(`[dsh-agent-plugins-market] suite "${diagnostic.suiteId}" mcp server "${diagnostic.serverKey}": ${diagnostic.reason}`);
-            }
-            for (const diagnostic of diagnostics.lsp) {
-                ctx.logger?.warn(`[dsh-agent-plugins-market] suite "${diagnostic.suiteId}" lsp server "${diagnostic.serverKey}": ${diagnostic.reason}`);
-            }
-            for (const diagnostic of diagnostics.commands) {
-                if (diagnostic.reason !== '')
-                    ctx.logger?.warn(`[dsh-agent-plugins-market] suite "${diagnostic.suiteId}" command "${diagnostic.command}": ${diagnostic.reason}`);
-            }
-            for (const diagnostic of diagnostics.hooks) {
-                ctx.logger?.warn(`[dsh-agent-plugins-market] suite "${diagnostic.suiteId}" hooks: ${diagnostic.reason}`);
-            }
-            for (const error of diagnostics.errors) {
-                ctx.logger?.warn(`[dsh-agent-plugins-market] ${error.surface} reconcile failed: ${error.reason}`);
-            }
+    const scheduler = new ReconcileScheduler(ctx, runtime, {
+        enabledSuites: () => catalog.enabledUserSuites(),
+        publishMcpDiagnostics: diagnostics => {
+            catalog.mcpDiagnostics = diagnostics;
         }
-        catch (error) {
-            ctx.logger?.warn(`[dsh-agent-plugins-market] runtime reconcile failed: ${error instanceof Error ? error.message : String(error)}`);
-            throw error;
+    });
+    /** Reconcile the user command mounts and report each failure once. */
+    const reconcileUserCommands = async () => {
+        const diagnostics = await userCommands.reconcile().catch(() => []);
+        for (const reason of diagnostics) {
+            ctx.logger?.warn(`[dsh-agent-plugins-market] user commands: ${reason}`);
         }
     };
-    // Settings, credential and catalog events can arrive during a slow MCP
-    // connection. Keep one current pass and one fresh follow-up, not a queue
-    // of stale snapshots that all reconnect the same servers.
-    const reconcileMounts = () => {
-        if (disposed)
-            return Promise.resolve();
-        reconcileRequested = true;
-        reconciliation ??= (async () => {
-            try {
-                do {
-                    reconcileRequested = false;
-                    await reconcileOnce();
-                } while (reconcileRequested && !disposed);
-            }
-            finally {
-                reconciliation = undefined;
-            }
-        })();
-        return reconciliation;
-    };
     /**
-     * Coalesce credential updates.
-     *
-     * `runtime.usesCredential(ref)` reflects the last completed pass, so an event
-     * arriving while the first reconcile is still running would be filtered out
-     * and the remount lost. Pending refs are therefore kept until the next pass
-     * observes them, and bursts are collapsed into one reconcile.
+     * How long the change pipeline holds the queue on one stage. A mount that
+     * stops responding — a stdio server that never finishes its handshake, a
+     * browser authorization nobody completed — delays its own surface only; the
+     * stage keeps running while the pipeline moves on to the next change.
      */
-    const pendingCredentialRefs = new Set();
-    let credentialFlush;
-    const flushCredentialUpdates = () => {
-        credentialFlush = undefined;
-        const refs = [...pendingCredentialRefs];
-        pendingCredentialRefs.clear();
-        // Re-read the catalog first: an unknown ref means the snapshot predates
-        // this change, so reconcile anyway to refresh the known reference set.
-        void reconcileMounts().catch(() => { });
-        if (refs.length > 0) {
-            ctx.logger?.info?.(`[dsh-agent-plugins-market] reconciling after credential update: ${refs.join(', ')}`);
+    const CHANGE_STAGE_DEADLINE_MS = 20_000;
+    /** Run one pipeline stage, logging its failure or its overrun instead of holding the pipeline. */
+    const runStage = async (stage, work) => {
+        const running = (async () => await work())();
+        void running.catch(error => {
+            ctx.logger?.warn(`[dsh-agent-plugins-market] ${stage} failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+        if (!(await settlesWithin(running, CHANGE_STAGE_DEADLINE_MS))) {
+            ctx.logger?.warn(`[dsh-agent-plugins-market] ${stage} is still running after ${CHANGE_STAGE_DEADLINE_MS}ms; the change pipeline continues without waiting for it`);
         }
     };
+    /**
+     * Catalog change pipeline: invalidate the derived skill and command
+     * surfaces, refresh the project mounts, then reconcile every runtime mount.
+     * `CatalogContext` schedules it in the background, so a stage that overruns
+     * costs freshness, never the mutation that asked for it.
+     */
     const onChanged = async () => {
         if (disposed)
             return;
         providerControl?.invalidate();
         userPanelControl?.invalidate();
-        await projectCommands?.refresh();
-        await suitePrompts?.refresh();
-        await Promise.all([projectMcp?.refresh(), projectHooks?.refresh()]);
-        const userCommandDiagnostics = await userCommands.reconcile().catch(() => []);
-        for (const reason of userCommandDiagnostics) {
-            ctx.logger?.warn(`[dsh-agent-plugins-market] user commands: ${reason}`);
-        }
-        await reconcileMounts();
+        await runStage('project commands', () => projectCommands?.refresh());
+        await runStage('suite instructions', () => suitePrompts?.refresh());
+        await runStage('project MCP and hooks', () => Promise.all([projectMcp?.refresh(), projectHooks?.refresh()]));
+        await runStage('user commands', () => reconcileUserCommands());
+        await runStage('runtime mounts', () => scheduler.request());
+    };
+    // Background source updates: off until the settings switch says otherwise.
+    const autoUpdate = new SourceAutoUpdater(ctx, () => catalog.refreshSource());
+    const settings = new MarketSettingsNamespace(ctx, dataRoot, hostLocale, {
+        setScanProjectLayouts: enabled => catalog.setScanProjectLayouts(enabled),
+        refreshMcpMounts: () => {
+            void Promise.all([scheduler.request(), projectMcp?.refresh()]).catch(() => { });
+        },
+        setAutoUpdateSources: enabled => autoUpdate.setEnabled(enabled)
+    });
+    // The credentials store powers the MCP re-authorize action (dropping a grant
+    // record forces the next mount through a fresh browser authorization). Every
+    // port below is read at call time: this plugin's apply may run before the
+    // credentials, tools and settings services provision, and a snapshot taken
+    // here would be permanently undefined even after the service is live.
+    let toolsRegistry;
+    const ports = {
+        mcpToolSnapshot: () => (toolsRegistry === undefined ? [] : inspectToolRegistry(toolsRegistry)),
+        credentialsStore: {
+            deleteGrantRecord: async (serverName) => {
+                const store = ctx.get?.('credentials');
+                await deleteMcpAuthGrant(store, serverName);
+            }
+        },
+        // Re-authorize must rebuild the live bridge, not just drop the grant: the
+        // registry flags the mount and the following reconcile tears it down and
+        // remounts, so the server's 401 restarts the browser authorization.
+        mcpRemount: (suiteId, serverKey) => runtime.forceMcpRemount(suiteId, serverKey),
+        mcpRemountAll: () => runtime.forceMcpRemountAll(),
+        mcpServerOwner: serverName => runtime.mcpServerOwner(serverName),
+        lspStatusSource: runtime.lsp,
+        mcpBackend: () => settings.backend(),
+        setMcpBackend: backend => settings.setBackend(backend),
+        downloadRegion: () => settings.downloadRegion()
     };
-    // The credential store powers the MCP re-authorize action (dropping a grant
-    // record forces the next mount through a fresh browser authorization).
-    // Resolved lazily at call time: this plugin's apply may run before the
-    // credentials plugin provisions, and a snapshot taken here would be
-    // permanently undefined even after the service is live.
-    const catalog = new Catalog({ userRoot, dataRoot, onChanged, ...(config.git === undefined ? {} : { git: config.git }) });
+    const catalog = new Catalog({ userRoot, dataRoot, agentsRoot, onChanged, ports, ...(config.git === undefined ? {} : { git: config.git }) });
     await catalog.load();
     await catalog.mergeSources(config.sources ?? []);
     const resources = createPanelResources(catalog, panels);
-    // Mirror oauth.ts's `credentialIdFor`: the record is stored under the folded
-    // serverName, so the delete must fold the same way or it misses the record.
-    const credentialIdFor = (serverName) => serverName
-        .toLowerCase()
-        .replace(/[^a-z0-9-]+/g, '-')
-        .replace(/^-+|-+$/g, '') || 'server';
-    catalog.setCredentialsStore({
-        deleteGrantRecord: async (serverName) => {
-            const store = ctx.get?.('credentials');
-            if (store?.deleteRecord === undefined)
-                throw new Error('credentials service is not mounted');
-            await store.deleteRecord(`mcp-auth/${credentialIdFor(serverName)}`);
-        }
-    });
     runtime.setMcpOverridesProvider(async () => catalog.allMcpOverrides(await catalog.enabledUserSuites()));
-    // Re-authorize must rebuild the live bridge, not just drop the grant: the
-    // registry flags the mount and the following reconcile tears it down and
-    // remounts, so the server's 401 restarts the browser authorization.
-    catalog.setMcpRemountHook((suiteId, serverKey) => runtime.forceMcpRemount(suiteId, serverKey), serverName => runtime.mcpServerOwner(serverName));
-    catalog.setLspStatusSource(runtime.lsp);
-    runtime.lsp.setDirectProvider(async () => (await loadLspServers(dataRoot)).servers);
+    runtime.lsp.setDirectProvider(async () => (await loadLspServers(agentsRoot)).servers);
     runtime.lsp.setDisabledProvider(() => loadDisabledLspServers(dataRoot));
-    // The MCP backend choice is a host settings namespace (the registration is
-    // also what makes the plugin-config tab serve our card). The node half owns
-    // it: the provider derives the mount backend from the scope, the writer
-    // flips the switch, and the watcher remounts servers when it flips. The
-    // same single registration also gates the experience-feedback tool —
-    // `settings.register` throws on a duplicate namespace, so there is exactly
-    // one inject block and one `register` call.
-    //
-    // The whole callback is failure-contained on purpose: a throw here is
-    // INVISIBLE in the UI (the inject resolves asynchronously and cordis only
-    // logs), and it silently removes the namespace from settings.describe —
-    // which is exactly what hides the plugin-config card. Every failure mode
-    // lands in the logger with a loud prefix instead.
-    let feedbackDisposer;
-    ctx.inject(['settings'], settingsCtx => {
-        try {
-            ctx.logger?.info?.('[dsh-agent-plugins-market] settings inject resolved — registering namespace');
-            const settings = settingsCtx.settings;
-            const scope = settings.register(MCP_SETTINGS_NAMESPACE, MarketSettingsSchema, {
-                base: { mcpEnhanced: true, downloadRegion: 'auto', feedbackEnabled: true, scanProjectLayouts: true }
-            });
-            ctx.logger?.info?.('[dsh-agent-plugins-market] settings namespace registered — plugin-config card will serve');
-            catalog.setMcpBackendProvider(async () => (scope.get().mcpEnhanced === false ? 'host' : 'builtin'));
-            catalog.setMcpBackendWriter(async (backend) => {
-                await scope.update({ mcpEnhanced: backend !== 'host' });
-            });
-            catalog.setDownloadRegionProvider(async () => narrowDownloadRegion(scope.get().downloadRegion));
-            const syncProjectLayouts = () => {
-                void catalog.setScanProjectLayouts(scope.get().scanProjectLayouts !== false).catch(error => {
-                    ctx.logger?.error?.(`[dsh-agent-plugins-market] project layout reconciliation failed: ${String(error)}`);
-                });
-            };
-            syncProjectLayouts();
-            settingsWatchers.push(scope.watch(syncProjectLayouts));
-            // One-time migration from the earlier data-root settings.json choice.
-            void readMcpBackend(dataRoot).then(backend => {
-                if (backend === 'host')
-                    void scope.update({ mcpEnhanced: false }).catch(() => { });
-            });
-            let previousBackend = scope.get().mcpEnhanced !== false;
-            settingsWatchers.push(scope.watch(() => {
-                const backend = scope.get().mcpEnhanced !== false;
-                if (backend === previousBackend)
-                    return;
-                previousBackend = backend;
-                void Promise.all([reconcileMounts(), projectMcp?.refresh()]).catch(() => { });
-            }));
-            // The experience-feedback model tool: gated by the namespace's
-            // `feedbackEnabled` field (default on); the switch unregisters it. The
-            // tool mount is doubly contained — its failure must never take the
-            // settings namespace (and with it the config card) down with it.
-            const syncFeedbackTool = () => {
-                try {
-                    const state = scope.get();
-                    const wanted = state.feedbackEnabled !== false;
-                    if (wanted && feedbackDisposer === undefined) {
-                        feedbackDisposer = mountFeedbackTool(ctx, dataRoot, (key, params) => hostLocale.t(key, params)) ?? undefined;
-                    }
-                    else if (!wanted && feedbackDisposer !== undefined) {
-                        feedbackDisposer();
-                        feedbackDisposer = undefined;
-                    }
-                }
-                catch (error) {
-                    ctx.logger?.error?.(`[dsh-agent-plugins-market] feedback tool mount failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
-                }
-            };
-            syncFeedbackTool();
-            settingsWatchers.push(scope.watch(() => syncFeedbackTool()));
-        }
-        catch (error) {
-            ctx.logger?.error?.(`[dsh-agent-plugins-market] settings namespace registration failed — the plugin-config card will be hidden this boot: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
-        }
-    });
     runtime.setMcpBackendProvider(() => catalog.mcpBackend());
-    const eventHost = ctx;
-    const disposeCredentialUpdates = eventHost.on?.('credentials/reference-updated', ref => {
-        pendingCredentialRefs.add(ref);
-        if (credentialFlush !== undefined)
-            clearTimeout(credentialFlush);
-        credentialFlush = setTimeout(flushCredentialUpdates, 150);
-        credentialFlush.unref?.();
-    }) ?? (() => { });
+    // The namespace must be registered after the catalog exists: the host
+    // resolves the inject callback synchronously when the settings service is
+    // already mounted, and the registration reads back the project-layout switch.
+    settings.mount();
     ctx.inject(['tools'], toolsCtx => {
-        const registry = toolsCtx.tools;
-        catalog.setMcpToolSnapshotProvider(() => inspectToolRegistry(registry));
+        toolsRegistry = toolsCtx.tools;
         // Foreign-namespace guard: a native host MCP client (or another plugin)
         // owning `mcp__<serverName>__` names makes the mount registry skip its
         // own server with a clear diagnostic instead of failing mid-registration.
-        runtime.setMcpToolNamesProvider(() => inspectToolRegistry(registry).map(tool => tool.name));
+        runtime.setMcpToolNamesProvider(() => inspectToolRegistry(toolsRegistry).map(tool => tool.name));
     });
     void Promise.resolve()
         .then(async () => {
-        const userCommandDiagnostics = await userCommands.reconcile().catch(() => []);
-        for (const reason of userCommandDiagnostics) {
-            ctx.logger?.warn(`[dsh-agent-plugins-market] user commands: ${reason}`);
-        }
-        await reconcileMounts();
+        await reconcileUserCommands();
+        await scheduler.request();
     })
         .catch(() => { });
     ctx.skills.registerProvider(control => {
@@ -274,7 +163,7 @@ export async function apply(ctx, config = {}) {
     // edit invalidates only its own catalog contribution.
     ctx.skills.registerProvider(control => {
         userPanelControl = control;
-        return new UserPanelSkillProvider(panels.skills, key => hostLocale.t(key));
+        return new UserPanelSkillProvider(panels.skills);
     });
     ctx.inject(['tools', 'llm', 'subagents', 'agents'], hostCtx => {
         hostCtx.effect(() => mountAgentRoleTool(hostCtx, async (parent) => [
@@ -310,15 +199,9 @@ export async function apply(ctx, config = {}) {
     });
     ctx.effect(() => () => {
         disposed = true;
-        disposeCredentialUpdates();
-        if (credentialFlush !== undefined)
-            clearTimeout(credentialFlush);
-        credentialFlush = undefined;
-        pendingCredentialRefs.clear();
-        for (const dispose of settingsWatchers.splice(0))
-            dispose();
-        feedbackDisposer?.();
-        feedbackDisposer = undefined;
+        scheduler.dispose();
+        autoUpdate.dispose();
+        settings.dispose();
         userCommands.disposeAll();
         void runtime.dispose();
     }, 'dsh-agent-plugins-market: lifecycle');

package/lib/model/types.js

@@ -7,11 +7,34 @@
  * Codex `.codex-plugin/plugin.json`). Discovery maps every layout onto this
  * internal shape; runtime injection consumes only the internal shape.
  */
-/** Archive URL extensions the archive acquisition path understands. */
-const ARCHIVE_URL_PATTERN = /\.(zip|tgz|tar\.gz|tar)$/i;
+/**
+ * Archive URL suffixes with the payload kind each names, longest suffix first
+ * so `.tar.gz` wins over `.tar`. Source-kind inference, source-id derivation,
+ * and archive extraction all read this one table.
+ */
+export const ARCHIVE_SUFFIXES = [
+    ['.tar.gz', 'targz'],
+    ['.tgz', 'targz'],
+    ['.zip', 'zip'],
+    ['.tar', 'tar']
+];
+/** The archive suffix `url` ends with, or undefined when it names no known payload. */
+function matchArchiveSuffix(url) {
+    const clean = url.trim().toLowerCase();
+    return ARCHIVE_SUFFIXES.find(([suffix]) => clean.endsWith(suffix));
+}
+/** Classify an archive URL by extension; undefined when unsupported. */
+export function archiveFormatOf(url) {
+    return matchArchiveSuffix(url)?.[1];
+}
 /** Whether a URL points at a downloadable archive. */
 export function isArchiveUrl(url) {
-    return ARCHIVE_URL_PATTERN.test(url.trim());
+    return matchArchiveSuffix(url) !== undefined;
+}
+/** Drop a trailing archive suffix (`plugin-0.1.zip` → `plugin-0.1`); other values pass through. */
+export function stripArchiveSuffix(value) {
+    const suffix = matchArchiveSuffix(value)?.[0];
+    return suffix === undefined ? value : value.slice(0, -suffix.length);
 }
 /**
  * Effective acquisition kind of a source: the explicit `kind` wins, the

package/lib/routes.js

@@ -130,7 +130,7 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
         }
     });
     post(MARKET_ROUTES.addSource, async (body) => {
-        const url = String(body['url'] ?? '').trim();
+        const url = textField(body['url'] ?? '', 'source url').trim();
         if (url === '')
             throw new Error('missing source url');
         const local = body['local'] === true;
@@ -145,11 +145,11 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
             if (!url.startsWith('~/') && url !== '~' && !isAbsolute(expanded))
                 throw new Error('local source url must be an absolute path or start with ~/');
         }
-        const branch = body['branch'];
+        const branch = body['branch'] === undefined ? undefined : textField(body['branch'], 'branch');
         const sha256 = parseSha256(body['sha256']);
         const source = await manager.addSource({
             url: local || kind === 'local' ? expandHome(url) : url,
-            ...(typeof branch === 'string' && branch.trim() !== '' ? { branch: branch.trim() } : {}),
+            ...(branch !== undefined && branch.trim() !== '' ? { branch: branch.trim() } : {}),
             ...(local ? { local: true } : {}),
             ...(kind === undefined ? {} : { kind }),
             ...(sha256 === undefined ? {} : { sha256 })
@@ -162,13 +162,13 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
             throw new Error('missing source id');
         const patch = {};
         if (body['url'] !== undefined) {
-            const url = String(body['url']).trim();
+            const url = textField(body['url'], 'source url').trim();
             if (url === '')
                 throw new Error('missing source url');
             patch.url = url;
         }
         if (body['branch'] !== undefined)
-            patch.branch = String(body['branch']).trim();
+            patch.branch = textField(body['branch'], 'branch').trim();
         if (body['local'] !== undefined)
             patch.local = body['local'] === true;
         const kind = parseSourceKind(body['kind']);
@@ -197,8 +197,8 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
         return {};
     });
     post(MARKET_ROUTES.refreshSource, async (body) => {
-        const id = body['id'];
-        await manager.refreshSource(typeof id === 'string' && id !== '' ? id : undefined);
+        const id = body['id'] === undefined ? undefined : textField(body['id'], 'source id');
+        await manager.refreshSource(id === '' ? undefined : id);
         return {};
     });
     post(MARKET_ROUTES.install, async (body) => {
@@ -299,12 +299,24 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
         return {};
     });
     post(`${MARKET_ROUTES.lspServers}/enabled`, async (body) => {
-        const id = String(body['id'] ?? '');
+        const id = textField(body['id'] ?? '', 'LSP server id');
         if (id === '')
             throw new Error('missing LSP server id');
-        await manager.setLspServerEnabled(id, body['enabled'] !== false);
+        const enabled = body['enabled'];
+        if (typeof enabled !== 'boolean')
+            throw new Error('missing boolean enabled');
+        await manager.setLspServerEnabled(id, enabled);
         return {};
     });
+    // Upgrade repair: drop the hand-written profile layer an older release told
+    // the user to add for LSP. It edits a file the user owns, so the profile
+    // name is matched against what is on disk and nothing else is touched.
+    post(MARKET_ROUTES.migrateLspSeam, async (body) => {
+        const profile = textField(body['profile'] ?? '', 'profile name').trim();
+        if (profile === '')
+            throw new Error('missing profile name');
+        return { migration: await manager.migrateLegacyLspSeam(profile) };
+    });
     // User panel CRUD (skills / commands / agent personas). The host web
     // server matches exact pathnames, so the entry name rides the `name` query
     // parameter (GET read, POST replace, POST .../delete remove). The routes
@@ -327,8 +339,8 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
                 sendJson(response, 200, { entry });
             });
             post(`${userPanelRoute(kind)}/create`, async (body) => {
-                const name = String(body['name'] ?? '').trim();
-                const text = String(body['text'] ?? '');
+                const name = textField(body['name'] ?? '', 'entry name').trim();
+                const text = textField(body['text'] ?? '', 'entry text');
                 if (name === '')
                     throw new Error('missing entry name');
                 const entry = await storeOf(kind).create(name, text);
@@ -337,7 +349,7 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
             });
             post(`${userPanelRoute(kind)}/update`, async (body, request) => {
                 const name = queryOf(request).get('name') ?? '';
-                const text = String(body['text'] ?? '');
+                const text = textField(body['text'] ?? '', 'entry text');
                 if (name === '')
                     throw new Error('missing entry name');
                 await storeOf(kind).update(name, text);
@@ -345,7 +357,7 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
                 return {};
             });
             post(`${userPanelRoute(kind)}/delete`, async (body) => {
-                const name = String(body['name'] ?? '');
+                const name = textField(body['name'] ?? '', 'entry name');
                 if (name === '')
                     throw new Error('missing entry name');
                 await storeOf(kind).remove(name);
@@ -359,6 +371,23 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
             dispose();
     };
 }
+/**
+ * Read a request field this route documents as a string. Bodies are arbitrary
+ * JSON, so the field may arrive as any value; anything but a string is
+ * rejected rather than coerced, because `String({})` is `"[object Object]"` —
+ * a non-empty value that every check downstream would accept and store as a
+ * source url, a branch name, or an entry name. Empty stays empty so each
+ * caller keeps owning whether that means "missing".
+ */
+function textField(value, label) {
+    if (typeof value !== 'string')
+        throw new Error(`${label} must be a string`);
+    return value;
+}
+/** Render an untrusted field for a diagnostic message. Never a value reader — see `textField`. */
+function describe(value) {
+    return String(value);
+}
 function parseTarget(body) {
     const sourceId = body['sourceId'];
     const suiteId = body['suiteId'];
@@ -374,13 +403,13 @@ function parseSourceKind(raw) {
         return undefined;
     if (raw === 'git' || raw === 'local' || raw === 'archive')
         return raw;
-    throw new Error(`invalid source kind "${String(raw)}"`);
+    throw new Error(`invalid source kind "${describe(raw)}"`);
 }
 /** Parse an optional SHA-256 hex digest; rejects malformed values. */
 function parseSha256(raw) {
     if (raw === undefined || raw === null || raw === '')
         return undefined;
-    const value = String(raw).trim().toLowerCase();
+    const value = textField(raw, 'sha256').trim().toLowerCase();
     if (!/^[0-9a-f]{64}$/.test(value))
         throw new Error('sha256 must be a 64-character hex digest');
     return value;
@@ -396,6 +425,7 @@ function sameOrigin(request) {
         return false;
     }
 }
+/** Parses the request body; `undefined` for an oversized, unparsable, or failed read. */
 function readJsonBody(request) {
     return new Promise(resolve => {
         let size = 0;

package/lib/runtime/agent-role-names.js

@@ -0,0 +1,70 @@
+import { createHash } from 'node:crypto';
+/**
+ * The `[source, suite, kind, name]` identity the host encodes into a discovery
+ * name, or `undefined` for a name that is not one — a user-authored role name
+ * is a plain string, and anything else carries no identity.
+ */
+function roleIdentity(name) {
+    let parsed;
+    try {
+        parsed = JSON.parse(name);
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(parsed))
+        return undefined;
+    const parts = parsed;
+    if (parts.length !== 4)
+        return undefined;
+    const [source, suite, kind, id] = parts;
+    if (typeof source !== 'string' || typeof suite !== 'string' || typeof kind !== 'string' || typeof id !== 'string')
+        return undefined;
+    return [source, suite, kind, id];
+}
+/** Internal IDs stay opaque to callers; only colliding resource names need qualification. */
+export function namedAgentRoles(entries) {
+    const roles = entries.map(entry => {
+        const identity = roleIdentity(entry.name);
+        const base = identity === undefined ? entry.name : identity[3].replace(/\.agent$/, '');
+        return { entry, base, suite: identity?.[1] ?? 'user', source: identity?.[0] ?? 'user', level: 0 };
+    });
+    const baseCounts = new Map();
+    for (const role of roles)
+        baseCounts.set(role.base, (baseCounts.get(role.base) ?? 0) + 1);
+    for (const role of roles)
+        if ((baseCounts.get(role.base) ?? 0) > 1)
+            role.level = 1;
+    const candidate = (role) => {
+        if (role.level === 0)
+            return role.base;
+        const qualified = `${role.suite}/${role.base}`;
+        const fullyQualified = `${role.source}/${role.suite}/${role.base}`;
+        if (role.level === 1)
+            return qualified;
+        if (role.level === 2)
+            return fullyQualified;
+        return `${fullyQualified}~${createHash('sha256').update(role.entry.name).digest('hex')}`;
+    };
+    // Recheck all names: a qualified collision may overlap another role's literal name.
+    for (;;) {
+        const groups = new Map();
+        for (const role of roles) {
+            const key = candidate(role);
+            groups.set(key, [...(groups.get(key) ?? []), role]);
+        }
+        let changed = false;
+        for (const group of groups.values()) {
+            if (group.length < 2)
+                continue;
+            for (const role of group) {
+                if (role.level < 3) {
+                    role.level++;
+                    changed = true;
+                }
+            }
+        }
+        if (!changed)
+            return roles.map(role => ({ ...role.entry, callName: candidate(role) }));
+    }
+}