dsh-agent-plugins-market 0.8.0 → 0.8.2

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');
 }

package/lib/runtime/core/context.js

@@ -0,0 +1,31 @@
+/**
+ * Tolerant reads of optional services off a cordis context.
+ * @module runtime/core/context
+ */
+/**
+ * Read one optional service off a cordis context, tolerating every access
+ * style the host shows.
+ *
+ * Cordis strict mode throws instead of returning `undefined` for an
+ * unregistered service, and contexts vary in which access style they expose —
+ * some the bare property, some only a `get()` accessor — so each read is
+ * guarded and absence always comes back as `undefined`, never a throw.
+ */
+export function optionalService(ctx, name) {
+    try {
+        const direct = ctx?.[name];
+        if (direct !== undefined && direct !== null)
+            return direct;
+    }
+    catch {
+        // Strict mode throws on the property read too; fall through to `get()`.
+    }
+    try {
+        const get = ctx?.get;
+        const service = typeof get === 'function' ? get.call(ctx, name) : undefined;
+        return service === null ? undefined : service;
+    }
+    catch {
+        return undefined;
+    }
+}

package/lib/runtime/{reconciler.js → core/reconciler.js}

@@ -1,8 +1,8 @@
-import { CommandMountRegistry } from './commands-mounts.js';
-import { HooksMountRegistry } from './hooks-mounts.js';
-import { LspMountRegistry } from './lsp-mounts.js';
-import { McpMountRegistry } from './mcp-mounts.js';
-import { bindHostLocale } from './host-locale.js';
+import { CommandMountRegistry } from '../surfaces/commands-mounts.js';
+import { HooksMountRegistry } from '../surfaces/hooks-mounts.js';
+import { LspMountRegistry } from '../lsp/lsp-mounts.js';
+import { McpMountRegistry } from '../mcp/mcp-mounts.js';
+import { bindHostLocale } from '../host/host-locale.js';
 export class RuntimeReconciler {
     mcp;
     commands;

package/lib/runtime/host/failure-detail.js

@@ -0,0 +1,58 @@
+/**
+ * The messages under one error's `cause` chain.
+ *
+ * The layers under the mount registries put the useful part of a failure in
+ * `cause`: a client wraps a startup failure in one fixed sentence and hands
+ * the spawn, transport, or handshake error beneath it. A status row keeps that
+ * chain so the panel can offer the detail behind a disclosure instead of
+ * showing the wrapper sentence alone.
+ *
+ * @module runtime/failure-detail
+ */
+import { redactErrorMessage } from '../../application/mcp/mcp-redaction.js';
+/** How many cause messages one failure keeps; a mount failure's chain is short. */
+const MAX_CAUSES = 4;
+/** The message text of an error, a thrown string, or an object carrying one. */
+function messageOf(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value instanceof Error)
+        return value.message;
+    if (typeof value === 'object' && value !== null && 'message' in value) {
+        const message = value.message;
+        if (typeof message === 'string')
+            return message;
+    }
+    return undefined;
+}
+/** The next link of a chain: `cause` on an error, or on an object carrying one. */
+function causeOf(value) {
+    if (value instanceof Error)
+        return value.cause;
+    if (typeof value === 'object' && value !== null && 'cause' in value)
+        return value.cause;
+    return undefined;
+}
+/**
+ * The chain of messages below one error, outermost first, redacted and
+ * de-duplicated. A repeated link ends the walk, so a chain that points back at
+ * itself cannot loop.
+ */
+export function causeMessages(error) {
+    const messages = [];
+    const seen = new Set();
+    let current = causeOf(error);
+    while (current !== undefined && current !== null && messages.length < MAX_CAUSES) {
+        if (seen.has(current))
+            break;
+        seen.add(current);
+        const message = messageOf(current);
+        if (message !== undefined) {
+            const redacted = redactErrorMessage(message);
+            if (redacted !== '' && !messages.includes(redacted))
+                messages.push(redacted);
+        }
+        current = causeOf(current);
+    }
+    return messages;
+}

package/lib/runtime/{feedback-tool.js → host/feedback-tool.js}

@@ -23,7 +23,7 @@ import { join } from 'node:path';
 import { promisify } from 'node:util';
 import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { platformBrowserOpener } from './mcp-client/oauth.js';
+import { platformBrowserOpener } from '../mcp/bridge/oauth.js';
 import { toolsServiceOf } from './tool-registry-observer.js';
 const execFileAsync = promisify(execFile);
 /** The GitHub repository experience feedback files issues against. */

package/lib/runtime/host/host-locale.js

@@ -0,0 +1,83 @@
+/**
+ * Host-side runtime locale: bilingual copy for the host-facing strings a person
+ * reads, resolved from the harness's `locale.preference` setting.
+ *
+ * The model-facing subagent catalog is not here. It is fixed English, because it
+ * is a contract read alongside the harness's own English tool descriptions and
+ * must not change with the operator's interface language.
+ *
+ * The web client resolves locale through its own injected service. The host
+ * process reads the same setting off the harness settings service, which
+ * projects every active profile entry's live configuration: the `locale` entry
+ * carries `preference`. Every absence — no settings service, the entry not
+ * active, no preference written, a value that is not a string — means zh.
+ */
+const zh = {
+    commandAcknowledged: '/{command} 已转交模型执行',
+    userCommandSourceLabel: '用户命令',
+    feedbackToolCardTitle: '提交市场体验反馈'
+};
+const en = {
+    commandAcknowledged: '/{command} forwarded to the model for execution',
+    userCommandSourceLabel: 'user command',
+    feedbackToolCardTitle: 'File market feedback'
+};
+const DICTS = { zh, en };
+/**
+ * The settings entry the harness locale plugin owns. The web bundle patch
+ * inserts it as `- id: locale` / `name: '@deepseek-ai/dsh-client-locale'`, and
+ * that package's host half declares `Config = { preference: volatile(string) }`.
+ */
+export const LOCALE_SETTINGS_ENTRY = 'locale';
+/** Resolve the active host language from settings; unknown values default to zh. */
+export function bindHostLocale(preference) {
+    const dict = preference !== undefined && preference.toLowerCase().startsWith('en') ? DICTS.en : DICTS.zh;
+    return (key, params) => {
+        let text = dict[key];
+        if (params !== undefined) {
+            for (const [name, value] of Object.entries(params))
+                text = text.replaceAll(`{${name}}`, value);
+        }
+        return text;
+    };
+}
+let hostLocaleSource;
+/**
+ * Wire the reader the host-facing copy resolves through. The caller registers
+ * the returned disposer with its own effects, so the wiring lives exactly as
+ * long as the fiber that installed it; the disposer clears this reader only, so
+ * a reload that installs a newer reader first keeps the newer one.
+ * @param read - reads the active `locale.preference`, or `undefined`.
+ * @returns the disposer that clears this wiring.
+ */
+export function setHostLocaleSource(read) {
+    hostLocaleSource = read;
+    return () => {
+        if (hostLocaleSource === read)
+            hostLocaleSource = undefined;
+    };
+}
+/**
+ * The persisted locale preference: what {@link setHostLocaleSource} wired, and
+ * `undefined` while the entry has not wired a reader.
+ */
+export function readLocalePreference() {
+    return hostLocaleSource?.();
+}
+/**
+ * Read `locale.preference` off the settings service's entry projection.
+ *
+ * `ctx.get` resolves the service from the store, and the store answers for as
+ * long as the provider is active, so the caller can read it from the entry's
+ * own context. The property read this replaces walks the reading fiber's
+ * ancestors and throws `cannot get required service "settings" in inactive
+ * context` once that fiber unloads, the state a profile reload leaves an
+ * injection callback's context in.
+ * @param settings - the host settings service, when the profile mounts one.
+ * @returns the preference string, or `undefined` for every absence.
+ */
+export function readHostLocalePreference(settings) {
+    const locale = settings?.describe().find(entry => entry.ns === LOCALE_SETTINGS_ENTRY);
+    const preference = locale?.value?.preference;
+    return typeof preference === 'string' ? preference : undefined;
+}

package/lib/runtime/{settings-namespace.js → host/settings-namespace.js}

@@ -1,12 +1,11 @@
-import { MARKET_SETTINGS_NAMESPACE, resolveMarketSettings } from '../contracts/settings.js';
+import { resolveMarketSettings } from '../../contracts/settings.js';
 import { FEEDBACK_TOOL_NAME, mountFeedbackTool } from './feedback-tool.js';
-import { MarketSettingsSchema, readMcpBackend } from './mcp-backend.js';
 export class MarketSettingsNamespace {
     ctx;
+    refs;
     dataRoot;
     locale;
     host;
-    scope;
     watchers = [];
     feedbackDisposer;
     /**
@@ -16,87 +15,66 @@ export class MarketSettingsNamespace {
      * switch, or skipped because the host has no tools registry to register on.
      */
     feedbackMountState;
-    constructor(ctx, dataRoot, locale, host) {
+    constructor(ctx, refs, dataRoot, locale, host) {
         this.ctx = ctx;
+        this.refs = refs;
         this.dataRoot = dataRoot;
         this.locale = locale;
         this.host = host;
     }
-    /** Register the namespace; the host resolves it whenever the settings service mounts. */
+    /** Subscribe the runtime reactions to live settings updates. */
     mount() {
-        this.ctx.inject(['settings'], settingsCtx => this.register(settingsCtx));
+        this.syncProjectLayouts();
+        this.syncAutoUpdateSources();
+        this.syncFeedbackTool();
+        let previousBackend = this.settings().mcpEnhanced;
+        const watcher = this.ctx.on('loader/volatile-update', () => {
+            const backend = this.settings().mcpEnhanced;
+            if (backend !== previousBackend) {
+                previousBackend = backend;
+                this.host.refreshMcpMounts();
+            }
+            this.syncProjectLayouts();
+            this.syncAutoUpdateSources();
+            this.syncFeedbackTool();
+        });
+        this.watchers.push(watcher);
+    }
+    /** Release every watcher and unmount the feedback tool. */
+    dispose() {
+        for (const release of this.watchers.splice(0))
+            release();
+        this.feedbackDisposer?.();
+        this.feedbackDisposer = undefined;
+    }
+    /**
+     * The resolved settings, from the volatile references the host updates in place.
+     */
+    settings() {
+        return resolveMarketSettings({
+            mcpEnhanced: this.refs.mcpEnhanced.get(),
+            scanProjectLayouts: this.refs.scanProjectLayouts.get(),
+            downloadRegion: this.refs.downloadRegion.get(),
+            feedbackEnabled: this.refs.feedbackEnabled.get(),
+            autoUpdateSources: this.refs.autoUpdateSources.get()
+        });
     }
-    /** The persisted MCP backend choice; the built-in client until registration lands. */
+    /** The persisted MCP backend choice; the built-in client until the host applies a value. */
     async backend() {
         return this.settings().mcpEnhanced ? 'builtin' : 'host';
     }
     /**
-     * Persist a backend choice.
-     * @throws when the settings service is not mounted.
+     * Legacy write path for the backend choice: the value now lives in the host
+     * settings document, edited from the Plugins panel's configuration page, so
+     * this accepts the request and lets the volatile reference decide.
      */
     async setBackend(backend) {
-        if (this.scope === undefined)
-            throw new Error('the settings service is not mounted');
-        await this.scope.update({ mcpEnhanced: backend !== 'host' });
+        this.ctx.logger?.info?.(`[dsh-agent-plugins-market] legacy MCP backend write (${backend}) ignored — the value lives in the host settings document`);
     }
     /** The persisted download-region setting. */
     async downloadRegion() {
         return this.settings().downloadRegion;
     }
-    /**
-     * The resolved settings, whether or not the namespace is registered yet.
-     *
-     * Every reader goes through here so "the field is absent" has exactly one
-     * answer — {@link resolveMarketSettings} — instead of each caller inventing
-     * its own fallback for the window before registration lands.
-     */
-    settings() {
-        return resolveMarketSettings(this.scope?.get());
-    }
-    /** Release every watcher and unmount the feedback tool. */
-    dispose() {
-        for (const release of this.watchers.splice(0))
-            release();
-        this.feedbackDisposer?.();
-        this.feedbackDisposer = undefined;
-    }
-    register(settingsCtx) {
-        try {
-            this.ctx.logger?.info?.('[dsh-agent-plugins-market] settings inject resolved — registering namespace');
-            const settings = settingsCtx.settings;
-            const scope = settings.register(MARKET_SETTINGS_NAMESPACE, MarketSettingsSchema);
-            this.scope = scope;
-            this.ctx.logger?.info?.('[dsh-agent-plugins-market] settings namespace registered — plugin-config card will serve');
-            this.syncProjectLayouts();
-            this.watchers.push(scope.watch(() => this.syncProjectLayouts()));
-            this.syncAutoUpdateSources();
-            this.watchers.push(scope.watch(() => this.syncAutoUpdateSources()));
-            // One-time migration from the earlier data-root settings.json choice.
-            void readMcpBackend(this.dataRoot).then(backend => {
-                if (backend === 'host')
-                    void scope.update({ mcpEnhanced: false }).catch(() => { });
-            });
-            let previousBackend = this.settings().mcpEnhanced;
-            this.watchers.push(scope.watch(() => {
-                const backend = this.settings().mcpEnhanced;
-                if (backend === previousBackend)
-                    return;
-                previousBackend = backend;
-                this.host.refreshMcpMounts();
-            }));
-            // 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. The
-            // mount outcome is logged on every transition so an absent
-            // `report_market_issue` in a session is traceable to its cause.
-            this.syncFeedbackTool();
-            this.watchers.push(scope.watch(() => this.syncFeedbackTool()));
-        }
-        catch (error) {
-            this.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)}`);
-        }
-    }
     /** Apply the background source-update switch. */
     syncAutoUpdateSources() {
         try {

package/lib/runtime/host/shell-path.js

@@ -0,0 +1,196 @@
+/**
+ * Login-shell command resolution for bare commands a suite declares
+ * (`npx`, `uvx`, a language-server bare name…).
+ *
+ * The desktop Host starts from Finder/Dock, so its `PATH` comes from launchd
+ * and holds only the system directories; the user's toolchain (`npx`, `uvx`,
+ * language servers) lives in directories a login shell adds. The plugin
+ * therefore probes the user's login shell once, lazily, and appends the
+ * directories the current `PATH` lacks — after the current entries, never
+ * before, so no existing priority changes. Nothing here rewrites a declared
+ * command: the bare name stays the command and the child inherits a `PATH`
+ * that can find it.
+ *
+ * The probe is deliberately narrow: only `darwin`, only the user's own login
+ * shell, and only when a first resolution against the current environment
+ * failed. A healthy environment therefore behaves exactly as before; only a
+ * command that would fail with `ENOENT` today takes the extra step. Every
+ * failure falls back to the unmodified environment and leaves a diagnostic
+ * line behind, so a resolution that still fails can explain what was searched.
+ *
+ * @module runtime/shell-path
+ */
+import { execFile } from 'node:child_process';
+import { delimiter, isAbsolute } from 'node:path';
+import { SubprocessExecutableNotFoundError, scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess';
+import { optionalService } from '../core/context.js';
+/** Unique line a login shell prints before the `PATH` it resolved. */
+const PATH_MARKER = '__DSH_MARKET_LOGIN_PATH__';
+/** How long the login-shell probe may take before it is abandoned. */
+const PROBE_TIMEOUT_MS = 3_000;
+/**
+ * In-process memo of the login-shell probe. A spawn resolution can run on
+ * every reconcile pass, but the user's shell environment does not change
+ * within one Host process, so the shell is asked at most once. The promise
+ * (not its value) is cached so concurrent first callers share one probe.
+ */
+let loginShellProbe;
+/**
+ * Probe the user's login shell for the `PATH` it exports, once per process.
+ *
+ * `-i` is required, not incidental: Homebrew's `shellenv` line lives in
+ * `.zshrc`, which a non-interactive `zsh -lc` never reads. The probe prints
+ * one marker line and then the value, so a shell that writes banners or
+ * prompts to stdout cannot be mistaken for the value. Every failure —
+ * non-darwin, no shell, timeout, malformed output — resolves to `undefined`
+ * rather than throwing, because a caller must be able to fall back silently
+ * to today's behavior.
+ *
+ * @returns the absolute directories the login shell resolves, or `undefined`
+ *   when the probe could not produce a usable `PATH`.
+ */
+export function loginShellPathEntries() {
+    loginShellProbe ??= probeLoginShellPath();
+    return loginShellProbe;
+}
+async function probeLoginShellPath() {
+    if (process.platform !== 'darwin')
+        return undefined;
+    const stdout = await new Promise(resolve => {
+        execFile('/bin/zsh', ['-ilc', `print -r -- ${PATH_MARKER} && print -r -- "$PATH"`], { timeout: PROBE_TIMEOUT_MS }, (error, output) => {
+            resolve(error === null ? output : undefined);
+        });
+    });
+    if (stdout === undefined)
+        return undefined;
+    const markerIndex = stdout.lastIndexOf(PATH_MARKER);
+    if (markerIndex === -1)
+        return undefined;
+    const afterMarker = stdout.slice(markerIndex + PATH_MARKER.length);
+    const line = afterMarker
+        .split('\n')
+        .map(part => part.trim())
+        .find(part => part !== '');
+    if (line === undefined)
+        return undefined;
+    const entries = [];
+    for (const entry of line.split(delimiter)) {
+        if (entry !== '' && isAbsolute(entry) && !entries.includes(entry))
+            entries.push(entry);
+    }
+    return entries.length > 0 ? entries : undefined;
+}
+/**
+ * Read the executable lookup path out of the environment the way the host
+ * subprocess provider does: a non-empty `PATH` entry, or the platform
+ * default when the variable is absent (as `child_process.spawn` itself
+ * resolves it).
+ */
+export function environmentPath(env) {
+    const value = env?.PATH;
+    if (value !== undefined && value !== '')
+        return value;
+    return process.env.PATH ?? '/usr/bin:/bin';
+}
+/**
+ * Append every directory the login shell has and `basePath` lacks, keeping
+ * `basePath`'s order and precedence intact.
+ *
+ * @returns the merged `PATH` and the appended directories, or `undefined`
+ *   when the probe failed or added nothing.
+ */
+export async function augmentChildPath(basePath) {
+    const entries = await loginShellPathEntries();
+    if (entries === undefined)
+        return undefined;
+    const current = basePath === '' ? [] : basePath.split(delimiter);
+    const present = new Set(current);
+    const added = entries.filter(entry => !present.has(entry));
+    if (added.length === 0)
+        return undefined;
+    return { path: [...current, ...added].join(delimiter), added };
+}
+/**
+ * Read the host's executable lookup seam from a cordis context, tolerantly.
+ * The service is optional — a context without a subprocess runtime resolves
+ * nothing and the caller keeps today's behavior.
+ */
+export function subprocessResolver(ctx) {
+    const subprocess = optionalService(ctx, 'subprocess');
+    const resolve = subprocess?.resolveExecutable;
+    if (typeof resolve !== 'function')
+        return undefined;
+    return (command, env) => resolve.call(subprocess, command, env);
+}
+/**
+ * Per-context memo of command resolutions, keyed by `${command}\u0000${basePath}`.
+ * The lsp-mounts and MCP-bridge reconciles ask on every pass, and a resolution
+ * walks a subprocess per attempt, so the promise (not its value) is cached —
+ * concurrent first callers share one walk. Keyed first by `ctx` so tests and
+ * fresh contexts stay isolated.
+ */
+const resolutionMemo = new WeakMap();
+/**
+ * Resolve one command a suite or the user declared, against the environment a
+ * spawn would inherit, extending `PATH` from the login shell only when that
+ * environment cannot find the command.
+ *
+ * The rule the two consumers share: an explicit `env.PATH` is a declaration
+ * and is never touched, so the caller gets `undefined` and keeps it verbatim.
+ * The plugin never rewrites the command itself — the bare name stays the
+ * command, and only the child's `PATH` grows.
+ *
+ * @param ctx - the cordis context carrying the host subprocess seam.
+ * @param command - the declared command, exactly as written.
+ * @param declaredEnv - the environment the suite/user declared for the child.
+ * @returns the extension to apply and its fact, or `undefined` when there is
+ *   nothing to do (no seam, or an explicit `PATH`).
+ */
+export function resolveDeclaredCommand(ctx, command, declaredEnv) {
+    const resolveExecutable = subprocessResolver(ctx);
+    // A context without the seam must not pin a stale no-seam result: the memo
+    // only exists once the seam is real. A declared `env.PATH` is a declaration
+    // and stays verbatim.
+    if (resolveExecutable === undefined || declaredEnv.PATH !== undefined)
+        return Promise.resolve(undefined);
+    if (!((typeof ctx === 'object' || typeof ctx === 'function') && ctx !== null))
+        return Promise.resolve(undefined);
+    const environment = { ...scrubbedParentEnv(), ...declaredEnv };
+    const basePath = environmentPath(environment);
+    let byCommand = resolutionMemo.get(ctx);
+    if (byCommand === undefined) {
+        byCommand = new Map();
+        resolutionMemo.set(ctx, byCommand);
+    }
+    const memoKey = `${command}\u0000${basePath}`;
+    const memoized = byCommand.get(memoKey);
+    if (memoized !== undefined)
+        return memoized;
+    const resolution = resolveOnce(resolveExecutable, command, environment, basePath);
+    byCommand.set(memoKey, resolution);
+    return resolution;
+}
+/** One full resolution walk: resolve, and extend `PATH` from the login shell only on a lookup miss. */
+async function resolveOnce(resolveExecutable, command, environment, basePath) {
+    try {
+        await resolveExecutable(command, { ...environment, PATH: basePath });
+        return {};
+    }
+    catch (error) {
+        // Only a genuine lookup miss earns the extra probe; any other failure
+        // (a relative-path rejection, a provider fault) keeps today's behavior.
+        if (!(error instanceof SubprocessExecutableNotFoundError))
+            return undefined;
+        const augmented = await augmentChildPath(basePath);
+        if (augmented === undefined) {
+            return { diagnostic: `could not resolve "${command}" on the Host PATH (${basePath}); the login shell could not supply a usable PATH to extend it` };
+        }
+        try {
+            await resolveExecutable(command, { ...environment, PATH: augmented.path });
+        }
+        catch {
+            return { diagnostic: `could not resolve "${command}" even after extending PATH from the login shell (searched: ${augmented.path})` };
+        }
+        return { path: augmented.path, diagnostic: `PATH extended from the login shell: ${augmented.added.join(', ')}` };
+    }
+}

package/lib/runtime/{tool-registry-observer.js → host/tool-registry-observer.js}

@@ -1,4 +1,5 @@
 /** Reading the model-facing MCP tools the host registry currently exposes. */
+import { optionalService } from '../core/context.js';
 /**
  * The MCP tools the host currently publishes to the model.
  *
@@ -35,5 +36,5 @@ export function inspectToolRegistry(tools) {
 }
 /** Read the tools service off the plugin context, when the host mounts one. */
 export function toolsServiceOf(ctx) {
-    return ctx.get?.('tools');
+    return optionalService(ctx, 'tools');
 }