dsh-agent-plugins-market 0.8.0 → 0.8.2

package/lib/runtime/{lsp-mounts.js → lsp/lsp-mounts.js}

@@ -1,9 +1,11 @@
-import { DIRECT_LSP_SUITE_ID } from './lsp-status.js';
-import { SerialPassQueue, RetryScheduler } from './mount-lifecycle.js';
-import { describeLegacySeam, findLegacyLspSeams } from './profile-seam.js';
-import { qualifiedSuiteId, suiteDataDir } from '../catalog/paths.js';
-import { expandPluginPaths, pluginRootOf } from '../catalog/plugin-variables.js';
-import { effectiveSurfaces } from '../model/types.js';
+import { DIRECT_LSP_SUITE_ID } from '../../application/lsp/lsp-status.js';
+import { SerialPassQueue, RetryScheduler } from '../core/mount-lifecycle.js';
+import { describeLegacySeam, findLegacyLspSeams } from '../../application/lsp/profile-seam.js';
+import { qualifiedSuiteId, suiteDataDir } from '../../catalog/paths.js';
+import { expandPluginPaths, pluginRootOf } from '../../catalog/plugin-variables.js';
+import { causeMessages } from '../host/failure-detail.js';
+import { resolveDeclaredCommand } from '../host/shell-path.js';
+import { effectiveSurfaces } from '../../model/types.js';
 /** Build one dsh-lsp-stdio Config.servers entry from a normalized spec. */
 export function toLspServerConfig(spec) {
     return {
@@ -110,16 +112,21 @@ export class LspMountRegistry {
             // otherwise shadow each other's mount and diagnostics.
             const key = qualifiedSuiteId(suite.sourceId, suite.id);
             const config = {};
+            const facts = [];
+            const pathExtensions = [];
             const root = pluginRootOf(suite);
             const context = {
                 ...(root === undefined ? {} : { root }),
                 ...(root === undefined || this.pluginDataRoot === undefined ? {} : { data: suiteDataDir(this.pluginDataRoot, suite.sourceId, suite.id) })
             };
-            for (const spec of servers)
-                if (!disabled.has(`${key}/${spec.key}`))
-                    config[`${key}/${spec.key}`] = expandLspServerConfig(toLspServerConfig(spec), context);
+            for (const spec of servers) {
+                if (disabled.has(`${key}/${spec.key}`))
+                    continue;
+                const serverConfig = expandLspServerConfig(toLspServerConfig(spec), context);
+                config[`${key}/${spec.key}`] = await this.resolveServerCommand(serverConfig, spec.key, facts, pathExtensions);
+            }
             if (Object.keys(config).length > 0)
-                wanted.set(key, { suite, config });
+                wanted.set(key, { suite, config, facts, pathExtensions });
         }
         // Direct user-configured servers ride the same mount path under the
         // sentinel suite id, so their lifecycle (retries, diagnostics, disposal)
@@ -128,9 +135,13 @@ export class LspMountRegistry {
         const directKeys = Object.keys(direct);
         if (directKeys.length > 0) {
             const config = {};
-            for (const [key, spec] of Object.entries(direct))
-                if (!disabled.has(`${DIRECT_LSP_SUITE_ID}/${key}`))
-                    config[`${DIRECT_LSP_SUITE_ID}/${key}`] = toLspServerConfig(spec);
+            const facts = [];
+            const pathExtensions = [];
+            for (const [key, spec] of Object.entries(direct)) {
+                if (disabled.has(`${DIRECT_LSP_SUITE_ID}/${key}`))
+                    continue;
+                config[`${DIRECT_LSP_SUITE_ID}/${key}`] = await this.resolveServerCommand(toLspServerConfig(spec), key, facts, pathExtensions);
+            }
             if (Object.keys(config).length > 0)
                 wanted.set(DIRECT_LSP_SUITE_ID, {
                     suite: {
@@ -147,7 +158,9 @@ export class LspMountRegistry {
                         activeSurfaces: effectiveSurfaces(undefined),
                         errors: []
                     },
-                    config
+                    config,
+                    facts,
+                    pathExtensions
                 });
         }
         // The last remaining server releases the capability seam; the first one mounts it.
@@ -168,9 +181,16 @@ export class LspMountRegistry {
                 this.lastDiagnostics.delete(key);
                 continue;
             }
+            const causes = [...(capabilityFailure?.causes ?? []), ...entry.facts];
             const failure = capabilityFailure === undefined
-                ? await this.mountWith(key, entry.suite, entry.config)
-                : { suiteId: key, serverKey: Object.keys(entry.config).join(','), reason: capabilityFailure.reason, code: capabilityFailure.code };
+                ? await this.mountWith(key, entry.suite, entry.config, entry.facts, entry.pathExtensions)
+                : {
+                    suiteId: key,
+                    serverKey: Object.keys(entry.config).join(','),
+                    reason: capabilityFailure.reason,
+                    code: capabilityFailure.code,
+                    ...(causes.length === 0 ? {} : { causes })
+                };
             if (failure !== undefined) {
                 diagnostics.push(failure);
                 this.lastDiagnostics.set(key, failure);
@@ -182,6 +202,30 @@ export class LspMountRegistry {
         }
         return diagnostics;
     }
+    /**
+     * Resolve one server's declared command, extending its `PATH` from the
+     * login shell only when the current environment cannot find the command.
+     *
+     * An explicit `env.PATH` is a declaration and is left verbatim; the command
+     * itself is never rewritten. A resolution fact (the extension, or the
+     * searched `PATH` when it still failed) is appended to the suite's facts so
+     * it reaches the mount diagnostic; a fact is also a PATH extension exactly
+     * when `resolution.path` is set, and rides `pathExtensions` for the trace log.
+     */
+    async resolveServerCommand(config, serverKey, facts, pathExtensions) {
+        const resolution = await resolveDeclaredCommand(this.ctx, config.command, config.env ?? {});
+        if (resolution === undefined)
+            return config;
+        if (resolution.diagnostic !== undefined) {
+            const fact = `${serverKey}: ${resolution.diagnostic}`;
+            facts.push(fact);
+            if (resolution.path !== undefined)
+                pathExtensions.push(fact);
+        }
+        if (resolution.path === undefined)
+            return config;
+        return { ...config, env: { ...(config.env ?? {}), PATH: resolution.path } };
+    }
     /**
      * Mount the capability seam this plugin delivers end to end: `ctx.lsp`, then the model-facing
      * `lsp` tool.
@@ -238,9 +282,9 @@ export class LspMountRegistry {
             // `service "lsp" has been registered` / `tool "lsp" is already registered`: another layer
             // owns the seam. Report the layer to drop rather than falling back to its version.
             if (/already registered|has been registered/.test(message)) {
-                return { reason: await this.seamConflictReason(specifier, message), code: 'seam-conflict' };
+                return { reason: await this.seamConflictReason(specifier, message), code: 'seam-conflict', causes: causeMessages(error) };
             }
-            return { reason: `mount failed: ${message}`, code: 'mount-failed' };
+            return { reason: `mount failed: ${message}`, code: 'mount-failed', causes: causeMessages(error) };
         }
         this.capability.push(handle);
         return undefined;
@@ -297,7 +341,7 @@ export class LspMountRegistry {
         return this.live.size > 0;
     }
     /** Mount one suite's full server table as a single `dsh-lsp-stdio` instance. */
-    async mountWith(key, suite, servers) {
+    async mountWith(key, suite, servers, facts = [], pathExtensions = []) {
         const hostKeys = Object.keys(servers).join(',');
         const module = await this.loadHost();
         if (module === undefined) {
@@ -330,9 +374,14 @@ export class LspMountRegistry {
                 suiteId: key,
                 serverKey: hostKeys,
                 reason: `mount failed: ${message}`,
-                code: conflict ? 'seam-conflict' : 'mount-failed'
+                code: conflict ? 'seam-conflict' : 'mount-failed',
+                causes: [...causeMessages(error), ...facts]
             };
         }
+        // The mount is live: only a genuine PATH extension is worth a trace, and
+        // resolveServerCommand already marked those facts structurally.
+        for (const fact of pathExtensions)
+            this.ctx.logger?.info?.(`[dsh-agent-plugins-market] ${key}: ${fact}`);
         this.live.set(key, { fingerprint: JSON.stringify(servers), suiteId: key, serverKeys: Object.keys(servers), disposer: () => handle.dispose() });
         return undefined;
     }

package/lib/runtime/{mcp-client → mcp/bridge}/bridge.js

@@ -20,7 +20,9 @@
  * @module runtime/mcp-client/bridge
  */
 import { resolveReconnectPolicy, startConnection } from './connection.js';
-import { validateConfig } from './config.js';
+import { validateConfig } from '../../../application/mcp/mcp-bridge-config.js';
+import { resolveDeclaredCommand } from '../../host/shell-path.js';
+import { optionalService } from '../../core/context.js';
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'market-mcp-client';
 /** Services required by this plugin. */
@@ -33,19 +35,6 @@ export const inject = ['tools'];
  * defense for direct programmatic loads.
  */
 const activeServerNames = new WeakMap();
-/** Tolerantly read an optional service from the cordis context. */
-function optionalService(ctx, serviceName) {
-    try {
-        const reader = ctx;
-        const service = reader.get?.(serviceName);
-        // A missing service either reads as undefined or throws (cordis strict
-        // mode); both mean "not mounted".
-        return service === null ? undefined : service;
-    }
-    catch {
-        return undefined;
-    }
-}
 /** Adapt the cordis context onto the structural host the bridge modules use. */
 function toToolHost(ctx) {
     const logger = {
@@ -74,6 +63,32 @@ function toToolHost(ctx) {
         getService: serviceName => optionalService(ctx, serviceName)
     };
 }
+/**
+ * Resolve one stdio command before the SDK spawns it, extending the child
+ * `PATH` from the login shell only when the current environment cannot find
+ * the command.
+ *
+ * An explicit `env.PATH` is the author's or user's declaration and is never
+ * touched: the bridge respects it verbatim and does not even probe. Without
+ * one, the child inherits the scrubbed parent `PATH`; when that cannot resolve
+ * the command (the desktop case, where `npx` is absent) the login shell's
+ * directories are appended, and the extension travels beside the config as
+ * `config.env.PATH`.
+ *
+ * Resolution never rejects: a command that stays unresolved keeps today's
+ * behavior (a spawn that fails with its own `ENOENT`), and the searched `PATH`
+ * is returned as a diagnostic so the failure can say what was tried.
+ */
+async function resolveStdioCommand(ctx, config) {
+    if (config.transport !== 'stdio')
+        return { config };
+    const resolution = await resolveDeclaredCommand(ctx, config.command, config.env);
+    if (resolution === undefined)
+        return { config };
+    const { path, diagnostic } = resolution;
+    const resolved = path === undefined ? config : { ...config, env: { ...config.env, PATH: path } };
+    return { config: resolved, ...(diagnostic === undefined ? {} : { diagnostic }) };
+}
 /**
  * Connect one MCP server and publish its initial tool generation before
  * activation. Remains explicitly `async`: Cordis treats a prototype-bearing
@@ -87,7 +102,9 @@ export async function apply(ctx, config) {
     // Fail loud at load: programmatic construction bypasses any schema layer,
     // so every invariant is re-judged here before any effect registers.
     validateConfig(config);
-    const reconnect = resolveReconnectPolicy(config.reconnect, `mcp-client(${config.serverName}): reconnect`);
+    const resolution = await resolveStdioCommand(ctx, config);
+    const resolvedConfig = resolution.config;
+    const reconnect = resolveReconnectPolicy(resolvedConfig.reconnect, `mcp-client(${resolvedConfig.serverName}): reconnect`);
     // Reserve the namespace next: a duplicate `serverName` fails THIS instance
     // at load with an actionable error and leaves the earlier instance intact.
     ctx.effect(() => {
@@ -96,11 +113,11 @@ export async function apply(ctx, config) {
             names = new Set();
             activeServerNames.set(ctx.root, names);
         }
-        if (names.has(config.serverName)) {
-            throw new Error(`market-mcp-client: serverName "${config.serverName}" is already in use by another bridge instance — pick a unique serverName`);
+        if (names.has(resolvedConfig.serverName)) {
+            throw new Error(`market-mcp-client: serverName "${resolvedConfig.serverName}" is already in use by another bridge instance — pick a unique serverName`);
         }
-        names.add(config.serverName);
-        return () => void names.delete(config.serverName);
+        names.add(resolvedConfig.serverName);
+        return () => void names.delete(resolvedConfig.serverName);
     }, 'market-mcp-client.serverName');
     // The supervisor owns the client/transport generations, the reconnect
     // loop, and the live tool registrations; disposal stops reconnection,
@@ -110,7 +127,7 @@ export async function apply(ctx, config) {
     // no-persistence configuration.
     const host = toToolHost(ctx);
     const credentials = optionalService(ctx, 'credentials');
-    const connection = startConnection(host, config, reconnect, credentials);
+    const connection = startConnection(host, resolvedConfig, reconnect, credentials);
     ctx.effect(() => {
         return () => connection.dispose();
     }, 'market-mcp-client.connection');
@@ -120,7 +137,20 @@ export async function apply(ctx, config) {
     // fiber (Cordis rolls it back); otherwise the error is logged and the
     // supervisor enters its reconnect loop.
     const outcome = await connection.ready;
-    if (outcome.error !== undefined && config.failOnStartupError) {
-        throw new Error(`mcp-client(${config.serverName}): initial connection or tool synchronization failed`, { cause: outcome.error });
+    if (outcome.error !== undefined && resolvedConfig.failOnStartupError) {
+        // The resolution fact explains why the spawn failed (or what was searched),
+        // so it rides the cause chain into the mount diagnostic ahead of the raw
+        // spawn error. On the happy path there is nothing to add and the chain is
+        // exactly today's.
+        const cause = resolution.diagnostic === undefined ? outcome.error : new Error(resolution.diagnostic, { cause: outcome.error });
+        throw new Error(`mcp-client(${resolvedConfig.serverName}): initial connection or tool synchronization failed`, { cause });
+    }
+    // A command that resolved only after the login shell extended PATH leaves a
+    // trace, so "why does this work now" is answerable from the log. With
+    // failOnStartupError=false a failed resolution reaches here too; the env.PATH
+    // guard excludes it, because PATH is only set on a successful extension —
+    // the transport check is the narrowing that makes env exist at all.
+    if (resolvedConfig.transport === 'stdio' && resolvedConfig.env.PATH !== undefined && resolution.diagnostic !== undefined) {
+        ctx.logger?.info?.(`market-mcp-client(${resolvedConfig.serverName}): ${resolution.diagnostic}`);
     }
 }

package/lib/runtime/{mcp-client → mcp/bridge}/connection.js

@@ -23,11 +23,11 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { ToolListChangedNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
 import { MAX_TIMER_DELAY_MS } from './host-seams.js';
-import { redactErrorMessage } from '../mcp-redaction.js';
+import { redactErrorMessage } from '../../../application/mcp/mcp-redaction.js';
 import { PLUGIN_NAME, PLUGIN_VERSION } from './plugin-identity.js';
 import { createTransport } from './transport.js';
 import { syncTools } from './tools.js';
-import { DEFAULT_STARTUP_TIMEOUT_MS } from './config.js';
+import { DEFAULT_STARTUP_TIMEOUT_MS } from '../../../application/mcp/mcp-bridge-config.js';
 /** Defaults shared by the config and {@link resolveReconnectPolicy}. */
 export const RECONNECT_DEFAULTS = Object.freeze({
     enabled: true,

package/lib/runtime/{mcp-client → mcp/bridge}/oauth.js

@@ -31,7 +31,7 @@ import { createServer } from 'node:http';
 import { randomBytes } from 'node:crypto';
 import { isDeepStrictEqual } from 'node:util';
 import { credentialKey, scrubbedParentEnv } from './host-seams.js';
-import { redactErrorMessage, redactUrl } from '../mcp-redaction.js';
+import { redactErrorMessage, redactUrl } from '../../../application/mcp/mcp-redaction.js';
 import { PLUGIN_NAME, PLUGIN_VERSION } from './plugin-identity.js';
 /** OAuth client identity presented during dynamic registration. */
 const CLIENT_NAME = `DeepSeek Harness (${PLUGIN_NAME})`;

package/lib/runtime/{mcp-client → mcp/bridge}/tools.js

@@ -19,9 +19,9 @@ import { createHash } from 'node:crypto';
 import { isDeepStrictEqual } from 'node:util';
 import { ListToolsResultSchema } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
-import { assertSupportedJsonSchema } from './json-schema-subset.js';
+import { assertSupportedJsonSchema } from '@deepseek-ai/dsh-tools';
 import { containsImage, extractText, prepareImageProjection } from './projection.js';
-import { redactErrorMessage } from '../mcp-redaction.js';
+import { redactErrorMessage } from '../../../application/mcp/mcp-redaction.js';
 /**
  * DeepSeek function-name contract: at most 64 characters. Wire-protocol
  * constant, not configuration.

package/lib/runtime/{mcp-auth-record.js → mcp/mcp-auth-record.js}

@@ -8,7 +8,7 @@
  *
  * @module runtime/mcp-auth-record
  */
-import { credentialKey } from './mcp-client/host-seams.js';
+import { credentialKey } from './bridge/host-seams.js';
 /** Credential-record scope for MCP OAuth state; per-server ids follow it. */
 export const MCP_AUTH_RECORD_SCOPE = 'mcp-auth';
 /**

package/lib/runtime/{mcp-mounts.js → mcp/mcp-mounts.js}

@@ -1,11 +1,12 @@
 import { createHash } from 'node:crypto';
 import { mkdir } from 'node:fs/promises';
-import * as mcpBridge from './mcp-client/bridge.js';
-import { toMcpMounts } from './mcp-config.js';
+import * as mcpBridge from './bridge/bridge.js';
+import { toMcpMounts } from '../../application/mcp/mcp-config.js';
 import { mcpCredentialResolver } from './mcp-credentials.js';
-import { SerialPassQueue, RetryScheduler } from './mount-lifecycle.js';
-import { qualifiedSuiteId, suiteDataDir } from '../catalog/paths.js';
-import { redactErrorMessage } from './mcp-redaction.js';
+import { SerialPassQueue, RetryScheduler } from '../core/mount-lifecycle.js';
+import { qualifiedSuiteId, suiteDataDir } from '../../catalog/paths.js';
+import { redactErrorMessage } from '../../application/mcp/mcp-redaction.js';
+import { causeMessages } from '../host/failure-detail.js';
 export class McpMountRegistry {
     ctx;
     pluginDataRoot;
@@ -157,7 +158,13 @@ export class McpMountRegistry {
             // reported so a transient error does not shadow the final state.
             const failure = await this.mountWith(entry.request);
             if (failure !== undefined) {
-                diagnostics.push({ suiteId: qualifiedSuiteId(entry.suite.sourceId, entry.suite.id), serverKey: entry.serverKey, reason: failure.reason, code: failure.code });
+                diagnostics.push({
+                    suiteId: qualifiedSuiteId(entry.suite.sourceId, entry.suite.id),
+                    serverKey: entry.serverKey,
+                    reason: failure.reason,
+                    code: failure.code,
+                    ...(failure.causes === undefined || failure.causes.length === 0 ? {} : { causes: failure.causes })
+                });
                 // Foreign and duplicate skips are deterministic, not transient:
                 // retrying them just burns the attempt budget and log lines. The
                 // next full reconcile re-checks them anyway, so the self-heal path
@@ -263,7 +270,7 @@ export class McpMountRegistry {
                     // Ignore teardown errors: the startup failure is the real signal.
                 }
             }
-            return { reason: `mount failed: ${redactErrorMessage(error instanceof Error ? error.message : String(error))}`, code: 'mount-failed' };
+            return { reason: `mount failed: ${redactErrorMessage(error instanceof Error ? error.message : String(error))}`, code: 'mount-failed', causes: causeMessages(error) };
         }
         this.live.set(mountKey(request.suiteId, request.serverKey), {
             suiteId: request.suiteId,

package/lib/runtime/{user-commands.js → panels/user-commands.js}

@@ -10,9 +10,9 @@
  * @module runtime/user-commands
  */
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
-import { commandCallName } from '../model/command-names.js';
-import { USER_ENTRY_PATH } from './user-store.js';
-import { pluginMarketSource } from './plugin-message-source.js';
+import { commandCallName } from '../../model/command-names.js';
+import { USER_ENTRY_PATH } from '../../application/panels/user-store.js';
+import { pluginMarketSource } from '../host/plugin-message-source.js';
 /** Register/unregister user-panel commands to match the panel's enabled entries. */
 export class UserCommandMountRegistry {
     ctx;

package/lib/runtime/{user-panels.js → panels/user-panels.js}

@@ -30,8 +30,8 @@
  * @module runtime/user-panels
  */
 import { dirname } from 'node:path';
-import { skillEntryRejection } from '../catalog/skills-parse.js';
-import { deleteEntryDocument, entryExists, listEntryDocuments, listEntryFiles, readEntryDocument, resolveEntryDocument, SKILL_ENTRY_SHAPES, USER_ENTRY_NAME, USER_ENTRY_PATH, userEntryDir, writeEntryDocument, writeEntryFile } from './user-store.js';
+import { skillEntryRejection } from '../../catalog/skills-parse.js';
+import { deleteEntryDocument, entryExists, listEntryDocuments, listEntryFiles, readEntryDocument, resolveEntryDocument, SKILL_ENTRY_SHAPES, USER_ENTRY_NAME, USER_ENTRY_PATH, userEntryDir, writeEntryDocument, writeEntryFile } from '../../application/panels/user-store.js';
 /** The skill-source label user-panel entries carry into the skill registry. */
 export const USER_PANEL_SKILL_SOURCE = 'user-panel';
 /**

package/lib/runtime/{commands-mounts.js → surfaces/commands-mounts.js}

@@ -1,13 +1,13 @@
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { parse as parseYaml } from 'yaml';
-import { stripFrontmatter } from '../catalog/skills-parse.js';
-import { parseFrontmatterRecord } from './user-store.js';
-import { qualifiedSuiteId, suiteDataDir } from '../catalog/paths.js';
-import { expandPluginPaths, pluginRootOf } from '../catalog/plugin-variables.js';
-import { defaultMarkdownResources, resourceText, resourceCommandName } from '../catalog/component-files.js';
-import { bindHostLocale } from './host-locale.js';
+import { stripFrontmatter } from '../../catalog/skills-parse.js';
+import { parseFrontmatterRecord } from '../../application/panels/user-store.js';
+import { qualifiedSuiteId, suiteDataDir } from '../../catalog/paths.js';
+import { expandPluginPaths, pluginRootOf } from '../../catalog/plugin-variables.js';
+import { defaultMarkdownResources, resourceText, resourceCommandName } from '../../catalog/component-files.js';
+import { bindHostLocale } from '../host/host-locale.js';
 import { injectDynamicContext, shellSeamOf } from './dynamic-context.js';
-import { pluginMarketSource } from './plugin-message-source.js';
+import { pluginMarketSource } from '../host/plugin-message-source.js';
 const COMMAND_NAME = /^[a-z][a-z0-9_-]*$/;
 export class CommandMountRegistry {
     ctx;

package/lib/runtime/{hooks-mounts.js → surfaces/hooks-mounts.js}

@@ -18,8 +18,8 @@ import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
 import { tmpdir } from 'node:os';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
-import { SerialPassQueue } from './mount-lifecycle.js';
-import { qualifiedSuiteId } from '../catalog/paths.js';
+import { SerialPassQueue } from '../core/mount-lifecycle.js';
+import { qualifiedSuiteId } from '../../catalog/paths.js';
 export class HooksMountRegistry {
     ctx;
     live = new Map();

package/lib/runtime/{project-runtime.js → surfaces/project-runtime.js}

@@ -1,11 +1,11 @@
 import { CommandMountRegistry } from './commands-mounts.js';
-import { expandPluginPaths, pluginRootOf } from '../catalog/plugin-variables.js';
-import { suiteDataDir } from '../catalog/paths.js';
-import { McpMountRegistry } from './mcp-mounts.js';
+import { expandPluginPaths, pluginRootOf } from '../../catalog/plugin-variables.js';
+import { suiteDataDir } from '../../catalog/paths.js';
+import { McpMountRegistry } from '../mcp/mcp-mounts.js';
 import { HooksMountRegistry } from './hooks-mounts.js';
 import { readFile } from 'node:fs/promises';
-import { stripFrontmatter } from '../catalog/skills-parse.js';
-import { parseFrontmatterRecord } from './user-store.js';
+import { stripFrontmatter } from '../../catalog/skills-parse.js';
+import { parseFrontmatterRecord } from '../../application/panels/user-store.js';
 /** Mount under existing and newly created agents; the caller owns refresh and teardown. */
 export function mountProjectCommands(ctx, catalog, t, dataRoot) {
     return mountProjectSurface(ctx, catalog, 'commands', scope => new CommandMountRegistry(scope, t, dataRoot));

package/lib/runtime/{skills-provider.js → surfaces/skills-provider.js}

@@ -14,10 +14,10 @@
  * directory, so CC-authored skills work verbatim under the harness.
  */
 import { readFile } from 'node:fs/promises';
-import { parseSkillFrontmatter, stripFrontmatter } from '../catalog/skills-parse.js';
-import { parseFrontmatterRecord } from './user-store.js';
-import { expandPluginPaths, pluginRootOf } from '../catalog/plugin-variables.js';
-import { suiteDataDir } from '../catalog/paths.js';
+import { parseSkillFrontmatter, stripFrontmatter } from '../../catalog/skills-parse.js';
+import { parseFrontmatterRecord } from '../../application/panels/user-store.js';
+import { expandPluginPaths, pluginRootOf } from '../../catalog/plugin-variables.js';
+import { suiteDataDir } from '../../catalog/paths.js';
 import { injectDynamicContext } from './dynamic-context.js';
 export const SUITE_PROJECT_SOURCE = 'agent-plugin-project';
 export const SUITE_USER_SOURCE = 'agent-plugin-user';

package/lib/types/application/agent-roles.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Panel identity is preserved so identically named cards from different suites remain addressable.
+ */
+export interface AgentRoleEntry {
+    name: string;
+    path: string;
+    description: string;
+    disabled: boolean;
+    title?: string;
+    rawText?: string;
+    /** Suite checkout root the card's `${PLUGIN_ROOT}` variables resolve to; absent for project-native files. */
+    suiteRoot?: string;
+    /** The suite's `${PLUGIN_DATA}` directory; absent for project-native files. */
+    suiteData?: string;
+}
+/**
+ * The executable part of one card. `tools` / `disallowedTools` stay in the file
+ * and are preserved by the editors, but they are not applied.
+ */
+export interface AgentRolePolicy {
+    content: string;
+    model?: string;
+    provider?: string;
+    reasoningEffort?: string;
+    title?: string;
+    description?: string;
+    disabled: boolean;
+}
+/** Strict YAML parsing prevents malformed routing metadata from silently inheriting wider privileges. */
+export declare function parseAgentRole(text: string): AgentRolePolicy;

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

@@ -1,11 +1,10 @@
 import type { LspLegacySeamMigration, LspStatusPayload } from '../contracts/lsp-status.js';
 import type { OverviewPayload, ServerConfigPayload, SkillContent, SourceProgress, SuiteDetail } from '../contracts/market.js';
-import type { McpStatusPayload } from '../contracts/mcp-status.js';
+import type { McpStatusPayload } from './mcp/mcp-status.js';
 import type { SourceRef, Suite, SuiteSurfaceKey } from '../model/types.js';
-import type { McpBackend } from '../runtime/mcp-backend.js';
-import { type McpImportResult } from '../runtime/mcp-direct-config.js';
-import type { McpMountDiagnostic } from '../runtime/mcp-mounts.js';
-import { type McpServerOverride, type McpSuiteOverrides } from '../runtime/mcp-overrides.js';
+import type { McpBackend } from '../contracts/mcp.js';
+import type { McpMountDiagnostic } from '../contracts/mcp.js';
+import { type McpServerOverride, type McpSuiteOverrides } from './mcp/mcp-overrides.js';
 import { type CatalogGitOptions, type CatalogOptions } from './catalog-context.js';
 import { type LspServerTable, type McpBackendInfo, type SourceInput, type SourcePatch } from './ports.js';
 import { type CatalogSnapshot } from './snapshot-cache.js';
@@ -95,8 +94,6 @@ export declare class Catalog implements MarketService {
     mcpStatus(): Promise<McpStatusPayload>;
     /** Persist a user-owned MCP service and reconcile its bridge mount. */
     addMcpServer(name: string, server: unknown): Promise<void>;
-    /** Import several pasted services in one write; each entry reports its own outcome. */
-    importMcpServers(servers: unknown, overwrite: boolean): Promise<McpImportResult>;
     /** Read effective service configuration without exposing credential literals. */
     serverConfig(kind: 'mcp' | 'lsp', id: string): Promise<ServerConfigPayload>;
     /** Validate a complete replacement before writing; plugin checkouts remain untouched. */

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

@@ -1,6 +1,6 @@
 import type { SkillContent, SuiteDetail } from '../contracts/market.js';
 import { type InstalledEntry, type Suite } from '../model/types.js';
-import type { McpMountDiagnostic as McpDiagnostic } from '../runtime/mcp-mounts.js';
+import type { McpMountDiagnostic as McpDiagnostic } from '../contracts/mcp.js';
 /** Build the detail response for one normalized suite. */
 export declare function buildSuiteDetail(suite: Suite, installed: InstalledEntry | undefined, diagnostics: readonly McpDiagnostic[], mcpOverrides?: Record<string, Record<string, unknown>>): Promise<SuiteDetail>;
 /** Read one skill body from a normalized suite. */

package/lib/types/application/json-file.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Read one JSON document. Resolves `undefined` when the file is absent or its
+ * text is empty; a `parse` that wants an absent file to read as a default
+ * handles `undefined` itself.
+ */
+export declare function readJsonFile(path: string): Promise<unknown>;
+/**
+ * Write one JSON document atomically: two-space indent, trailing newline, and
+ * the private-file modes the plugin's state files carry (0o600 file, 0o700
+ * directory).
+ */
+export declare function writeJsonDocument(path: string, document: unknown): Promise<void>;

package/lib/types/{runtime → application/lsp}/lsp-direct-config.d.ts

@@ -1,4 +1,4 @@
-import type { LspServerSpec } from '../model/types.js';
+import type { LspServerSpec } from '../../model/types.js';
 /** The direct LSP server configuration file path. */
 export declare function lspServersPath(agentsRoot: string): string;
 /** Load the user-configured LSP servers; unreadable or invalid files yield an empty table. */

package/lib/types/{runtime → application/lsp}/lsp-status.d.ts

@@ -12,9 +12,9 @@
  * Direct user-configured rows follow the same model under the sentinel suite
  * id `direct` (mirroring mcp-status's `plugin`/`direct` split).
  */
-import type { LspStatusPayload } from '../contracts/lsp-status.js';
-import type { LspMountDiagnostic } from './lsp-mounts.js';
-import type { LspServerSpec, Suite } from '../model/types.js';
+import type { LspStatusPayload } from '../../contracts/lsp-status.js';
+import type { LspMountDiagnostic } from '../../contracts/lsp.js';
+import type { LspServerSpec, Suite } from '../../model/types.js';
 /** Sentinel suite id for user-configured (non-suite) LSP servers. */
 export declare const DIRECT_LSP_SUITE_ID = "direct";
 /** The subset of LspMountRegistry the aggregator consumes (structural, for tests). */