dsh-agent-plugins-market 0.8.1 → 0.8.2

package/lib/application/panel-resources.js

@@ -1,11 +1,12 @@
 /** Installed suite and user resources share one inventory; paths never come from HTTP callers. */
-import { realpath, stat, unlink } from 'node:fs/promises';
+import { realpath, stat } from 'node:fs/promises';
+import { isDeepStrictEqual as deepEqual } from 'node:util';
 import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
 import { defaultMarkdownResources, resourceText } from '../catalog/component-files.js';
 import { pluginRootOf } from '../catalog/plugin-variables.js';
 import { isWithin, suiteDataDir } from '../catalog/paths.js';
 import { stripFrontmatter } from '../catalog/skills-parse.js';
-import { parseFrontmatterRecord } from '../runtime/user-store.js';
+import { parseFrontmatterRecord } from './panels/user-store.js';
 /**
  * Id of one panel entry backed by a file inside an installed suite's checkout.
  * The leading `[` is what distinguishes a plugin entry from a user-authored
@@ -18,6 +19,16 @@ export function pluginResourceId(sourceId, suiteId, kind, name) {
 export function isPluginResourceId(id) {
     return id.startsWith('[');
 }
+/**
+ * Frontmatter keys beyond the enable switch that a panel control may diff on a
+ * plugin document, per kind: the harness invocation pair on skills, and the
+ * model-routing keys the persona form edits on agents.
+ */
+const FLIPPABLE_KEYS = {
+    skills: ['disable-model-invocation', 'user-invocable'],
+    commands: [],
+    agents: ['model', 'provider', 'reasoning_effort', 'reasoningEffort']
+};
 export function createPanelResources(catalog, users) {
     return {
         skills: new PanelResources(catalog, users.skills, 'skills'),
@@ -96,11 +107,12 @@ class PanelResources {
      * A plugin resource is writable only when it sits inside the user dimension
      * root; suite checkouts elsewhere on disk stay read-only. The user-panel
      * store lives in the shared Agent layout root instead, so containment is
-     * measured against the catalog's root, not the panel directory.
+     * measured against the catalog's root, not the panel directory. Callers pass
+     * the entry they already fetched: a full inventory scan per call would read
+     * every suite document twice per write.
      */
-    async pluginPath(id) {
-        const entry = await this.get(id);
-        if (entry?.origin !== 'plugin')
+    async pluginPath(entry) {
+        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');
@@ -113,12 +125,37 @@ class PanelResources {
     async update(id, text) {
         if (!isPluginResourceId(id))
             return this.users.update(id, text);
-        parseFrontmatterRecord(text);
-        await writeFileAtomic(await this.pluginPath(id), text, { mode: 0o644 });
+        const previous = await this.get(id);
+        if (previous === undefined)
+            throw new Error('Unknown installed plugin resource');
+        this.assertStateFlipOnly(previous.rawText, text);
+        await writeFileAtomic(await this.pluginPath(previous), text, { mode: 0o644 });
+    }
+    /**
+     * A suite owns its files' content: the panel may only flip state frontmatter.
+     * The document body must stay byte-identical, and the frontmatter diff is
+     * confined to `disabled` everywhere, plus {@link FLIPPABLE_KEYS}'s per-kind
+     * control keys — the harness invocation pair on skills, model routing on
+     * agents.
+     */
+    assertStateFlipOnly(previousText, text) {
+        if (stripFrontmatter(previousText) !== stripFrontmatter(text))
+            throw new Error('plugin resources are read-only; the suite owns their content');
+        const before = parseFrontmatterRecord(previousText);
+        const after = parseFrontmatterRecord(text);
+        const flippable = new Set(['disabled', ...FLIPPABLE_KEYS[this.kind]]);
+        for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
+            if (flippable.has(key))
+                continue;
+            if (!deepEqual(before[key], after[key])) {
+                throw new Error('plugin resources are read-only; only the enable state can be changed');
+            }
+        }
     }
     async remove(id) {
-        if (!isPluginResourceId(id))
-            return this.users.remove(id);
-        await unlink(await this.pluginPath(id));
+        // Plugin files belong to their suite checkout; install/uninstall manages them.
+        if (isPluginResourceId(id))
+            throw new Error('plugin resources are managed by their suite; uninstall the suite instead');
+        return this.users.remove(id);
     }
 }

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

@@ -11,8 +11,8 @@
  */
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { normalizeHookDocuments, standaloneHookDocument } from '../catalog/project-hooks.js';
-import { effectiveSurfaces } from '../model/types.js';
+import { normalizeHookDocuments, standaloneHookDocument } from '../../catalog/project-hooks.js';
+import { effectiveSurfaces } from '../../model/types.js';
 export const USER_HOOKS_SOURCE = '@user-hooks';
 export const USER_HOOKS_SUITE = 'user-hooks';
 /**

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

@@ -11,13 +11,13 @@
  * to that directory. Skills also accept the cross-tool directory spelling
  * (`<name>/SKILL.md`) that other Agent tools and the harness's own reader of
  * `~/.agents/skills` author, and read it from the top level only.
- * @module runtime/user-store
+ * @module application/user-store
  */
 import { readdir, readFile, rmdir, rm, stat } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
 import { parseDocument, stringify } from 'yaml';
-import { parseSkillFrontmatter, stripFrontmatter } from '../catalog/skills-parse.js';
+import { parseSkillFrontmatter, stripFrontmatter } from '../../catalog/skills-parse.js';
 /** Where user panel entries persist: `<agentsRoot>/<kind>/`. */
 export function userEntryDir(agentsRoot, kind) {
     return join(agentsRoot, kind);

package/lib/application/ports.js

@@ -10,6 +10,7 @@ export const defaultCatalogPorts = {
     mcpServerOwner: () => undefined,
     lspStatusSource: { diagnosticsSnapshot: () => new Map(), hasLiveMounts: () => false },
     mcpBackend: async () => 'builtin',
+    localePreference: () => 'zh',
     setMcpBackend: async () => {
         throw new Error('the settings service is not mounted');
     },

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

@@ -2,7 +2,7 @@
 import { defaultMarkdownResources, resourceText } from '../catalog/component-files.js';
 import { pluginRootOf } from '../catalog/plugin-variables.js';
 import { suiteDataDir } from '../catalog/paths.js';
-import { parseAgentRole } from '../runtime/agent-role-router.js';
+import { parseAgentRole } from './agent-roles.js';
 export async function projectAgentRoles(catalog, parent) {
     const cwd = parent?.session?.header?.cwd;
     if (typeof cwd !== 'string' || cwd === '')

package/lib/{runtime → application}/server-config.js

@@ -1,10 +1,9 @@
-import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
+import { readJsonFile, writeJsonDocument } from './json-file.js';
 import { MCP_SCHEMA_ID, validateAgainstSchema, validateMcpJson } from '../catalog/validate.js';
 import { parseLspServers } from '../catalog/lsp-spec.js';
 import { qualifiedSuiteId } from '../catalog/paths.js';
-import { redactMcpConfig } from './mcp-redaction.js';
+import { redactMcpConfig } from './mcp/mcp-redaction.js';
 /**
  * The errors the closed-set package shape produces. A user-owned service does
  * not obey that shape, and the per-transport checks still require what it needs.
@@ -85,24 +84,15 @@ export function lspConfig(spec) {
     return Object.fromEntries(Object.entries(spec).filter(([key]) => key !== 'key'));
 }
 export async function loadLspOverrides(root) {
-    try {
-        const raw = JSON.parse(await readFile(join(root, 'lsp-overrides.json'), 'utf8'));
-        return Object.fromEntries(Object.entries(raw).map(([id, config]) => [id, validateServerLsp(id.slice(id.lastIndexOf('/') + 1), config)]));
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return {};
-        throw error;
-    }
+    const raw = await readJsonFile(join(root, 'lsp-overrides.json'));
+    if (typeof raw !== 'object' || raw === null)
+        return {};
+    return Object.fromEntries(Object.entries(raw).map(([id, config]) => [id, validateServerLsp(id.slice(id.lastIndexOf('/') + 1), config)]));
 }
 export async function saveLspOverride(root, id, config) {
     const overrides = await loadLspOverrides(root);
     overrides[id] = config;
-    const path = join(root, 'lsp-overrides.json');
-    await writeFileAtomic(path, JSON.stringify(Object.fromEntries(Object.entries(overrides).map(([key, value]) => [key, lspConfig(value)])), null, 2), {
-        mode: 0o600,
-        dirMode: 0o700
-    });
+    await writeJsonDocument(join(root, 'lsp-overrides.json'), Object.fromEntries(Object.entries(overrides).map(([key, value]) => [key, lspConfig(value)])));
 }
 export async function applyLspOverrides(root, suites) {
     const overrides = await loadLspOverrides(root);

package/lib/application/snapshot-cache.js

@@ -12,7 +12,7 @@
 import { join, resolve } from 'node:path';
 import { resolveProjectRoot, STATE_FILE_NAME } from '../catalog/paths.js';
 import { discoverSourceListWithNotes } from '../catalog/source-catalog.js';
-import { loadState } from '../runtime/state-store.js';
+import { loadState } from './state/state-store.js';
 export const SCAN_CACHE_TTL_MS = 30_000;
 const SCAN_CACHE_MAX_ENTRIES = 8;
 export class SnapshotCache {

package/lib/application/source-store.js

@@ -15,8 +15,7 @@ import { repoName } from '../catalog/manifests.js';
 import { deriveSourceIdCandidates, expandHome, sanitizeId, sourceCheckoutDir, sourcesDir } from '../catalog/paths.js';
 import { isDirectory, pathExists } from '../catalog/fs-probes.js';
 import { canonicalGitUrl } from '../catalog/scan-resolvers.js';
-import { readLocalePreference } from '../runtime/host-locale.js';
-import { githubCloneUrl, resolveRegion } from '../runtime/regions.js';
+import { githubCloneUrl, resolveRegion } from './regions.js';
 import { resolveSourceKind } from '../model/types.js';
 export class SourceStore {
     context;
@@ -280,7 +279,7 @@ export class SourceStore {
                 // source.url) are re-pointed — a foreign remote is left untouched.
                 if (source.kind === 'git' || (source.kind === undefined && source.local !== true)) {
                     try {
-                        const region = resolveRegion(await this.ports.downloadRegion(), await readLocalePreference());
+                        const region = resolveRegion(await this.ports.downloadRegion(), this.ports.localePreference());
                         const routed = githubCloneUrl(region, source.url);
                         const origin = await gitRemoteUrl(checkout);
                         if (origin !== routed && (origin === source.url || origin === githubCloneUrl('china', source.url))) {
@@ -401,7 +400,7 @@ export class SourceStore {
         try {
             // The region routes github.com clones through the China mirror prefix;
             // the proxied URL becomes `origin`, so refreshes follow the same route.
-            const region = resolveRegion(await this.ports.downloadRegion(), await readLocalePreference());
+            const region = resolveRegion(await this.ports.downloadRegion(), this.ports.localePreference());
             await gitClone(githubCloneUrl(region, source.url), source.branch, checkout, this.context.git);
             return undefined;
         }

package/lib/{runtime → application/state}/state-store.js

@@ -7,15 +7,13 @@
  * like the market profile state this pattern follows. The record shapes live
  * in `src/model/types.ts`; only the reading and writing live here.
  */
-import { readFile } from 'node:fs/promises';
-import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
-import { SUITE_SURFACE_KEYS } from '../model/types.js';
+import { readJsonFile, writeJsonDocument } from '../json-file.js';
+import { SUITE_SURFACE_KEYS } from '../../model/types.js';
 export const EMPTY_STATE = { version: 1, sources: [], installed: {} };
 /** Parse persisted state; unreadable or wrong-version files yield a contained empty state. */
 export async function loadState(statePath) {
     try {
-        const text = await readFile(statePath, 'utf8');
-        const parsed = JSON.parse(text);
+        const parsed = await readJsonFile(statePath);
         if (typeof parsed !== 'object' || parsed === null)
             return EMPTY_STATE;
         const record = parsed;
@@ -87,7 +85,7 @@ function parseSurfaceOverrides(raw) {
     }
     return hasAny ? { surfaces: overrides } : {};
 }
-/** Persist state atomically through the harness's atomic-write helper. */
+/** Persist state atomically through the shared JSON document writer. */
 export async function saveState(statePath, state) {
-    await writeFileAtomic(statePath, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600, dirMode: 0o700 });
+    await writeJsonDocument(statePath, state);
 }

package/lib/{runtime → application/state}/storage-migration.js

@@ -2,8 +2,8 @@
 import { constants } from 'node:fs';
 import { copyFile, lstat, mkdir, readdir, readFile, rmdir, unlink } from 'node:fs/promises';
 import { dirname, join, relative, resolve } from 'node:path';
-import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
-import { expandHome, isWithin, resolveAgentsRoot, resolveDataRoot, resolveDshHome, resolveUserRoot } from '../catalog/paths.js';
+import { readJsonFile, writeJsonDocument } from '../json-file.js';
+import { expandHome, isWithin, resolveAgentsRoot, resolveDataRoot, resolveDshHome, resolveUserRoot } from '../../catalog/paths.js';
 async function info(path) {
     try {
         return await lstat(path);
@@ -156,7 +156,7 @@ async function relocateManagedSourceUrls(userRoot, legacyUserRoot) {
     const path = join(userRoot, 'state.json');
     if ((await info(path)) === undefined)
         return;
-    const state = JSON.parse(await readFile(path, 'utf8'));
+    const state = await readJsonFile(path);
     if (typeof state !== 'object' || state === null || !('sources' in state) || !Array.isArray(state.sources))
         return;
     let changed = false;
@@ -170,7 +170,7 @@ async function relocateManagedSourceUrls(userRoot, legacyUserRoot) {
         changed = true;
     }
     if (changed) {
-        await writeFileAtomic(path, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600, dirMode: 0o700 });
+        await writeJsonDocument(path, state);
     }
 }
 async function collectUnsupportedEntries(path, conflicts) {

package/lib/catalog/source-catalog.js

@@ -13,10 +13,6 @@ import { expandHome, sourcesDir } from './paths.js';
 import { isDirectory } from './fs-probes.js';
 import { scanSource as scanSourceWithNotes } from './suite-scanner.js';
 import { discoverNativeProjectSuites } from './native-project.js';
-/** Discover suites from the selected configured or project checkouts. */
-export async function discoverSourceList(sources, dimension, dimensionRoot) {
-    return (await discoverSourceListWithNotes(sources, dimension, dimensionRoot, true)).suites;
-}
 /**
  * Discover suites plus per-source scan diagnostics for one dimension.
  * @param scanProjectLayouts - whether the project's own native Agent directories

package/lib/contracts/lsp.js

@@ -0,0 +1 @@
+export {};

package/lib/contracts/market.js

@@ -6,7 +6,6 @@ export const MARKET_ROUTES = {
     overview: `${MARKET_API_PREFIX}overview`,
     mcpStatus: `${MARKET_API_PREFIX}mcp-status`,
     addMcpServer: `${MARKET_API_PREFIX}mcp-servers/add`,
-    importMcpServers: `${MARKET_API_PREFIX}mcp-servers/import`,
     lspStatus: `${MARKET_API_PREFIX}lsp-status`,
     lspServers: `${MARKET_API_PREFIX}lsp-servers`,
     addLspServer: `${MARKET_API_PREFIX}lsp-servers/add`,

package/lib/contracts/mcp.js

@@ -0,0 +1 @@
+export {};

package/lib/index.js

@@ -1,28 +1,28 @@
 import z from '@deepseek-ai/schemastery';
-import { MarketSettingsFields } from './runtime/mcp-backend.js';
+import { MarketSettingsFields } from './application/mcp/mcp-backend.js';
 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, toolsServiceOf } from './runtime/tool-registry-observer.js';
-import { migratePluginStorage } from './runtime/storage-migration.js';
-import { mountAgentRoleTool } from './runtime/agent-role-router.js';
+import { settlesWithin } from './application/deadline.js';
+import { RuntimeReconciler } from './runtime/core/reconciler.js';
+import { ReconcileScheduler } from './runtime/core/reconcile-scheduler.js';
+import { MarketSettingsNamespace } from './runtime/host/settings-namespace.js';
+import { deleteMcpAuthGrant } from './runtime/mcp/mcp-auth-record.js';
+import { inspectToolRegistry, toolsServiceOf } from './runtime/host/tool-registry-observer.js';
+import { migratePluginStorage } from './application/state/storage-migration.js';
+import { mountAgentRoleTool } from './runtime/agents/agent-role-router.js';
 import { projectAgentRoles } from './application/project-agent-roles.js';
-import { mountProjectCommands, mountProjectMcp, mountProjectHooks, mountSuiteInstructions } from './runtime/project-runtime.js';
+import { mountProjectCommands, mountProjectMcp, mountProjectHooks, mountSuiteInstructions } from './runtime/surfaces/project-runtime.js';
 import { createPanelResources } from './application/panel-resources.js';
 import { resolveAgentsRoot, resolveDataRoot, resolveUserRoot } from './catalog/paths.js';
 import { mountSuiteRoutes } from './routes.js';
-import { SuiteSkillProvider } from './runtime/skills-provider.js';
-import { shellSeamOf } from './runtime/dynamic-context.js';
-import { loadLspServers } from './runtime/lsp-direct-config.js';
-import { loadDisabledLspServers } from './runtime/lsp-server-state.js';
-import { bindHostLocale, loadHostLocale, readHostLocalePreference, setHostLocaleSource } from './runtime/host-locale.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';
+import { SuiteSkillProvider } from './runtime/surfaces/skills-provider.js';
+import { shellSeamOf } from './runtime/surfaces/dynamic-context.js';
+import { loadLspServers } from './application/lsp/lsp-direct-config.js';
+import { loadDisabledLspServers } from './application/lsp/lsp-server-state.js';
+import { bindHostLocale, LOCALE_SETTINGS_ENTRY, readHostLocalePreference, readLocalePreference, setHostLocaleSource } from './runtime/host/host-locale.js';
+import { createUserPanelStores } from './runtime/panels/user-panels.js';
+import { SourceAutoUpdater } from './runtime/core/source-auto-update.js';
+import { UserPanelSkillProvider } from './runtime/panels/user-panels.js';
+import { UserCommandMountRegistry } from './runtime/panels/user-commands.js';
 import { presetSourceRef } from './model/preset-source.js';
 export const name = 'dsh-agent-plugins-market';
 export const inject = ['skills', 'commands'];
@@ -54,24 +54,32 @@ export async function apply(ctx, config = { mcpEnhanced: undefinedRef, scanProje
         throw new Error(`Plugin storage migration conflicts (original files retained): ${migration.conflicts.join(', ')}`);
     let providerControl;
     let userPanelControl;
-    // Host runtime copy resolves from the harness `locale.preference` setting;
-    // the async settings read lands before the first session starts in practice.
+    // Host runtime copy resolves from the harness `locale.preference` setting.
     const hostLocale = { t: bindHostLocale(undefined) };
     const refreshHostLocale = () => {
-        void loadHostLocale().then(locale => {
-            hostLocale.t = locale.t;
-            providerControl?.invalidate();
-            userPanelControl?.invalidate();
-        });
+        hostLocale.t = bindHostLocale(readLocalePreference());
+        providerControl?.invalidate();
+        userPanelControl?.invalidate();
     };
-    void refreshHostLocale();
-    // The locale preference the GUI writes is owned by the host settings service:
-    // read it there rather than re-parsing the document, and re-bind once the
-    // service lands (the locale namespace may register after this plugin).
-    ctx.inject(['settings'], settingsCtx => {
-        setHostLocaleSource(() => readHostLocalePreference(settingsCtx));
+    // The preference is the `locale` entry's live configuration, projected by the
+    // host settings service. Resolve that service through the store from this
+    // entry's own context, and register the wiring as an effect so it lives
+    // exactly as long as this fiber: a context captured from an injection
+    // callback throws `cannot get required service "settings" in inactive
+    // context` once a profile reload disposes that fiber, and the unhandled
+    // rejection ends the host. Re-read once the service lands, because it may
+    // mount after this plugin.
+    ctx.effect(() => setHostLocaleSource(() => readHostLocalePreference(ctx.get('settings'))), 'dsh-agent-plugins-market: host locale source');
+    refreshHostLocale();
+    ctx.inject(['settings'], () => {
         refreshHostLocale();
     });
+    // A language switch writes the `locale` entry's form; re-read so the copy the
+    // market renders follows it without a reload.
+    ctx.effect(() => ctx.on('settings/document-updated', (ns) => {
+        if (ns === LOCALE_SETTINGS_ENTRY)
+            refreshHostLocale();
+    }), 'dsh-agent-plugins-market: host locale refresh');
     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.
@@ -162,7 +170,8 @@ export async function apply(ctx, config = { mcpEnhanced: undefinedRef, scanProje
         lspStatusSource: runtime.lsp,
         mcpBackend: () => settings.backend(),
         setMcpBackend: backend => settings.setBackend(backend),
-        downloadRegion: () => settings.downloadRegion()
+        downloadRegion: () => settings.downloadRegion(),
+        localePreference: () => readLocalePreference() ?? 'zh'
     };
     const catalog = new Catalog({ userRoot, dataRoot, agentsRoot, onChanged, ports, ...(config.git === undefined ? {} : { git: config.git }) });
     await catalog.load();

package/lib/routes.js

@@ -9,8 +9,8 @@
 import { isAbsolute } from 'node:path';
 import { MARKET_ROUTES, userPanelRoute } from './contracts/market.js';
 import { expandHome } from './catalog/paths.js';
-import { sanitizeOverridePatch } from './runtime/mcp-overrides.js';
-import { readModelCatalog } from './runtime/model-catalog.js';
+import { sanitizeOverridePatch } from './application/mcp/mcp-overrides.js';
+import { readModelCatalog } from './runtime/host/model-catalog.js';
 const MAX_BODY_BYTES = 64 * 1024;
 /** Mount every route; returns the disposer releasing them all. */
 export function mountSuiteRoutes(hostCtx, manager, panels) {
@@ -93,13 +93,6 @@ export function mountSuiteRoutes(hostCtx, manager, panels) {
         await manager.addMcpServer(body.name, body.config);
         return {};
     });
-    // Paste import: many services in one write. Each entry reports its own
-    // outcome, so one rejected definition never fails the whole paste.
-    post(MARKET_ROUTES.importMcpServers, async (body) => {
-        const overwrite = body['overwrite'] === true;
-        const result = await manager.importMcpServers(body['servers'], overwrite);
-        return { imported: result.imported, skipped: result.skipped };
-    });
     get(MARKET_ROUTES.lspStatus, async (_request, response) => {
         sendJson(response, 200, await manager.lspStatus());
     });

package/lib/runtime/{agent-role-router.js → agents/agent-role-router.js}

@@ -1,62 +1,17 @@
 /** Execute user and installed-suite agent cards through the host subagent service. */
 import { readFile } from 'node:fs/promises';
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { parse as parseYaml } from 'yaml';
 import { mountSubagentCatalog } from './subagent-catalog.js';
 import { namedAgentRoles } from './agent-role-names.js';
-import { expandPluginPaths } from '../catalog/plugin-variables.js';
+import { expandPluginPaths } from '../../catalog/plugin-variables.js';
+import { parseAgentRole } from '../../application/agent-roles.js';
+export { parseAgentRole };
 export const AGENT_ROLE_TOOL_NAME = 'subagent_role';
 /**
  * Absolute delegation-depth cap applied to every role child. The host default is
  * the same value; keeping it explicit preserves the shipped recursion budget.
  */
 const MAX_AGENT_ROLE_DEPTH = 3;
-function optionalText(value, key) {
-    if (value === undefined)
-        return undefined;
-    if (typeof value !== 'string' || value.trim() === '')
-        throw new Error(`agent metadata ${key} must be a non-empty string`);
-    return value.trim();
-}
-/** Strict YAML parsing prevents malformed routing metadata from silently inheriting wider privileges. */
-export function parseAgentRole(text) {
-    const match = /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(text);
-    if (match === null) {
-        if (/^(?:\uFEFF)?---(?:\r?\n|$)/.test(text))
-            throw new Error('agent frontmatter is not closed');
-        return { content: text, disabled: false };
-    }
-    // A matched block always carries its body; the check keeps the type honest.
-    const frontmatter = match[1];
-    if (frontmatter === undefined)
-        throw new Error('agent frontmatter is not closed');
-    const parsed = parseYaml(frontmatter);
-    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
-        throw new Error('agent frontmatter must be a YAML object');
-    const metadata = parsed;
-    if (metadata.disabled !== undefined && typeof metadata.disabled !== 'boolean')
-        throw new Error('agent metadata disabled must be a boolean');
-    const model = optionalText(metadata.model, 'model');
-    const provider = optionalText(metadata.provider, 'provider');
-    const effort = optionalText(metadata.reasoning_effort, 'reasoning_effort');
-    const camelEffort = optionalText(metadata.reasoningEffort, 'reasoningEffort');
-    if (effort !== undefined && camelEffort !== undefined && effort !== camelEffort)
-        throw new Error('agent metadata reasoning_effort and reasoningEffort conflict');
-    const reasoningEffort = effort ?? camelEffort;
-    const title = optionalText(metadata.name, 'name');
-    const description = optionalText(metadata.description, 'description');
-    if (model === 'inherit' && provider !== undefined)
-        throw new Error('agent model inherit cannot specify a provider');
-    return {
-        content: text.slice(match[0].length),
-        disabled: metadata.disabled === true,
-        ...(model === undefined || model === 'inherit' ? {} : { model }),
-        ...(provider === undefined ? {} : { provider }),
-        ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
-        ...(title === undefined ? {} : { title }),
-        ...(description === undefined ? {} : { description })
-    };
-}
 function parentRouteOf(parent) {
     const agent = parent;
     return agent?.session?.requestHeader?.()?.config ?? agent?.options ?? {};
@@ -287,11 +242,10 @@ export function mountAgentRoleTool(ctx, listRoles) {
     const host = ctx;
     const tool = defineTool({
         name: AGENT_ROLE_TOOL_NAME,
-        description: "Delegate a task to a role child defined by an installed plugin: the named role's own instructions and its configured model apply, and the child starts without this conversation. This tool runs in " +
-            'the background by default, immediately returns a durable subagent id, and keeps the child available for later turns; when that run settles, the runtime sends the parent a notice carrying its outcome ' +
-            'and final reply. Set `run_in_background: false` only when your next action depends on receiving the result. A child usually runs for minutes, so while it works on the background path, continue with ' +
-            'independent work instead of waiting. `prompt` must stand alone, since the child cannot see this conversation and a question it asks while it runs goes unanswered. When the notice arrives, verify its ' +
-            "assertions against the files and relay the result to the user; the child's output is not visible to them. The current catalog lists the available roles and states the usage guidance; when no listed " +
+        description: "Delegate a task to a named role child from the session's role catalog: the role's own instructions and its configured model apply, and the child starts without this conversation. Use it proactively for self-contained work — codebase exploration whose raw reads would fill this context, a scoped implementation, a review, or an analysis you can brief in one prompt — and start independent children together in one message. The child runs in " +
+            'the background by default and returns a durable subagent id at once, keeping the child available for later turns; when the run settles, the runtime sends the parent a notice carrying its outcome and ' +
+            'final reply. A child usually runs for minutes, so continue with independent work instead of waiting. `prompt` must stand alone, since the child cannot see this conversation and a question it asks while it runs goes unanswered. When the notice arrives, verify its ' +
+            "assertions against the files and relay the result to the user; the child's output is not visible to them. The current catalog lists the available roles and the full usage guidance; when no listed " +
             "role matches, use the host's own `subagent` tools instead.",
         parameters: {
             agent: { type: 'string', required: true, description: 'Exact callable role name from the current subagent catalog.' },

package/lib/runtime/{subagent-catalog.js → agents/subagent-catalog.js}

@@ -61,26 +61,34 @@ const CATALOG_UPDATED = 'The available subagent roles changed. This complete lis
 const CATALOG_PROMPT = 'Writing the prompt: brief the child like a colleague who just walked into the room — it has not seen this conversation, does not know what you tried, and does not know why the task matters. Explain what you are trying to accomplish, describe what you learned and ruled out, and give enough context for the child to make judgment calls. The child cannot see this conversation, so prompt must be self-contained: the task itself, the relevant files and known findings, the output you expect, and the boundaries of the task (research only, or may edit files). Terse command-style prompts produce shallow, generic work.';
 const CATALOG_USAGE = [
     'Usage notes:',
-    '- Call subagent_role with the exact catalog name as agent. A child has its own context: it starts without this conversation, so it suits self-contained work that one briefing can state in full.',
+    "- Call subagent_role with the exact catalog name as agent. A child has its own context: it starts without this conversation, so it suits self-contained work that one briefing can state in full. If no listed role matches, do not substitute a similarly named one — delegate through one of the host's general delegation channels instead, and do not load these roles through skill or slash commands.",
     '- By default the call returns a durable subagent id immediately and runs in the background without blocking you. A child usually runs for minutes: spend that time advancing independent work that does not depend on it, rather than idling — and do not poll it or re-check its progress. While it runs, send_message adds an instruction or more material and list_agents reports its status.',
-    '- run_in_background true runs the same child as a tracked background job and returns a job id instead: collect it with job_output and stop it with job_kill. Use it when the result should be collected later through the job tools; leave the parameter out when you want the child reachable with send_message and list_agents.',
-    "- run_in_background false runs one foreground child and returns its report as this call's result instead of a settlement notice. Use it only when your next action depends on the result.",
+    "- run_in_background true runs the same child as a tracked background job and returns a job id instead: collect it with job_output and stop it with job_kill. run_in_background false runs one foreground child and returns its report as this call's result — use it when your next action depends on the result and no independent work remains.",
     '- A question a child asks while it runs goes unanswered: nothing will reply on your behalf. So state the prompt in full the first time, and a child should decide for itself, keep going, and list in its final reply which choices it made alone and what information it still lacked.',
-    "- A background child's output is not visible to the user. When it finishes, summarize the result to the user yourself.",
-    "- The child's settlement notice arrives as a user message, not as a tool result. Until it arrives, do not assume or predict its findings, and do not deliver anything that depends on them; act on them once it lands, by verifying or delegating further as needed.",
+    "- The settlement notice arrives as a user message, not as a tool result. Until it arrives, do not assume or predict its findings, and do not deliver anything that depends on them. A background child's output is not visible to the user: when it finishes, summarize the result to the user yourself.",
     "- The child's final reply is its own report: check its assertions against the files themselves, and treat its statements about its own configuration the same way — a child cannot see how its role instructions were installed.",
-    "- The route parameters override the route the role card declares; omit them to use the card's route, or the parent route when the card declares none.",
-    '- Do not duplicate work a child is already doing.',
-    '- When several children run at once, give each its own git worktree and name the files it owns in prompt.'
+    '- Do not duplicate work a child is already doing. When several children run at once, give each its own git worktree and name the files it owns in prompt.'
 ].join('\n');
-const CATALOG_WHEN_NOT_TO_USE = "When NOT to use a role child: no listed role matches; your next action needs the result; or another child is already doing this work. When no role matches, do not substitute a similarly named one — delegate through one of the host's general delegation channels instead. Do not load these roles through skill or slash commands.";
 /**
- * Model-facing catalog text: the role list followed by the same guidance on
- * first publication and on every update, so a replacement never arrives without
- * the rules that govern it. The guidance covers how to brief a child, how to
- * work with one while it runs, and when a role child is the wrong answer; the
- * per-channel arbitration between the host's delegation tools stays in the tool
- * descriptions the harness owns.
+ * The positive half of the delegation decision, published with every catalog
+ * ahead of the role list so the model reads the triggers before the names.
+ * Delegation had only negative framing before this block: every other paragraph
+ * states what must not happen, and none states when delegating is the default.
+ */
+const CATALOG_WHEN_TO_DELEGATE = [
+    'Delegate proactively: hand self-contained work to a role child by default instead of doing it inline. Delegate when any of these holds:',
+    '- The task would burn many tool calls or file reads whose raw output would flood this conversation — codebase exploration, tracing behavior across files, digesting long logs or reports. The child reads everything and returns only the distilled result.',
+    '- The task is a complete unit one briefing can state: a scoped implementation, a review, an analysis, a document.',
+    '- Two or more such tasks are independent: start all the children in one message and let them run in parallel.',
+    'Decide by the briefing test: if you can state the task in full and it needs no further input from the user, delegate it and keep working.'
+].join('\n');
+/**
+ * Model-facing catalog text: the delegation triggers, then the role list, then
+ * the same guidance on first publication and on every update, so a replacement
+ * never arrives without the rules that govern it. The guidance covers when a
+ * role child is the default, how to brief one, and how to work with one while
+ * it runs; the per-channel arbitration between the host's delegation tools
+ * stays in the tool descriptions the harness owns.
  *
  * Role lines carry a name and a description only. The configured route stays in
  * the durable entries for execution and change detection; publishing it would
@@ -91,12 +99,12 @@ export function renderCatalogText(entries, update) {
     return [
         '<system-reminder>',
         update ? CATALOG_UPDATED : CATALOG_INTRO,
+        CATALOG_WHEN_TO_DELEGATE,
         '<available_subagents>',
         ...lines,
         '</available_subagents>',
         CATALOG_PROMPT,
         CATALOG_USAGE,
-        CATALOG_WHEN_NOT_TO_USE,
         '</system-reminder>'
     ].join('\n');
 }