paseo-dsh-direct 0.2.2 → 0.2.3

package/OVERVIEW.md

@@ -0,0 +1,24 @@
+# DeepSeek Harness for Paseo
+
+Runs DeepSeek Harness (`dsh`) as a native Paseo agent provider. Paseo clients (desktop, web, iOS, Android) drive a local `dsh` agent with streamed responses, visible reasoning, tool approvals, user questions and session lifecycle management, without going through a generic ACP adapter.
+
+## Requirements
+
+- Paseo 0.11.0 or newer.
+- DeepSeek Harness `dsh` on the 0.2 line, installed and configured on the machine that runs the Paseo daemon (model API key and settings are read by `dsh` from its own configuration).
+
+## Features
+
+- Streaming assistant text and reasoning ("thinking") as Paseo timeline items.
+- Tool calls with Paseo approval prompts, and `dsh` user questions answered from the Paseo UI.
+- Create, resume, cancel and close sessions; model list and mode switching from the Paseo UI.
+- DSH branding (name and icon) in the provider list.
+
+## Processes and environment
+
+- **Child process.** For each session the plugin starts the `dsh` executable as a child process and loads a small bridge plugin into it. The two communicate over the child's stdio.
+- **Executable lookup.** In order: the `PASEO_DSH_EXECUTABLE` environment variable, then the Paseo setting `agents.providers.dsh-pi.command`, then `dsh` on `PATH`.
+- **Profile.** The plugin launches `dsh --profile paseo`. If `<DSH_HOME>/profiles/paseo` does not exist, it is created once by running `dsh --profile paseo --from-default-profile web --dump-config`. `DSH_HOME` defaults to `~/.dsh`. Setting `PASEO_DSH_PROFILE` selects another existing profile instead; a missing one is reported as an error, not created.
+- **Environment variables read by the plugin.** `PASEO_DSH_EXECUTABLE`, `PASEO_DSH_PROFILE`, and `DSH_HOME` (to locate the profile directory).
+- **Environment passed to `dsh`.** The child inherits the Paseo daemon's environment.
+- **Network.** The plugin makes no network requests itself. Model API calls are made by `dsh` according to its own configuration.

package/README.md

@@ -36,7 +36,7 @@ Create a conversation with the **DeepSeek Harness** provider. Models and presets
 
 The provider supports streamed assistant and reasoning output, tool execution and approval, user questions, model/preset configuration, interruption, and session recovery. It starts DSH with its own `paseo` profile and does not modify Paseo or DSH core.
 
-The plugin uses the DSH profile `paseo`. On first start it creates that profile from DSH's official `web` template (`~/.dsh/profiles/paseo`, or under `$DSH_HOME` when set). Model routes, the default model, and permission presets go in `~/.dsh/profiles/paseo/cordis.patch.yml`. Set `PASEO_DSH_EXECUTABLE` to use a different `dsh` executable, or `PASEO_DSH_PROFILE` to use another existing profile; a profile named there is not created automatically. If the Paseo Daemon has plugin loading disabled, enable `pluginsEnabled` in its configuration before installing the plugin.
+The plugin uses the DSH profile `paseo`. On first start it creates that profile from DSH's official `web` template (`~/.dsh/profiles/paseo`, or under `$DSH_HOME` when set). Model routes, the default model, and permission presets go in `~/.dsh/profiles/paseo/cordis.patch.yml`. To use a different `dsh` executable, set `agents.providers.dsh-pi.command` in the Paseo configuration or `PASEO_DSH_EXECUTABLE` (which takes precedence); or `PASEO_DSH_PROFILE` to use another existing profile; a profile named there is not created automatically. If the Paseo Daemon has plugin loading disabled, enable `pluginsEnabled` in its configuration before installing the plugin.
 
 If a native session is still held by another DSH client (such as a terminal UI), release it there before importing or resuming it from Paseo.
 

package/README.zh.md

@@ -36,7 +36,7 @@
 
 Provider 支持连续正文和思考输出、工具执行与审批、用户问答、模型和 preset 配置、中断及会话恢复。它用插件专用的 `paseo` profile 启动 DSH，不修改 Paseo 或 DSH 核心。
 
-插件使用名为 `paseo` 的 DSH profile。首次启动时，插件用 DSH 官方的 `web` 模板自动创建它（位置是 `~/.dsh/profiles/paseo`；设置了 `$DSH_HOME` 时在其下）。模型路由、默认模型和权限预设写在 `~/.dsh/profiles/paseo/cordis.patch.yml`。可通过 `PASEO_DSH_EXECUTABLE` 指定其他 `dsh` 可执行文件，通过 `PASEO_DSH_PROFILE` 改用另一个已存在的 profile；这样指定的 profile 不会被自动创建。如果 Paseo Daemon 默认关闭插件加载，请先在配置中启用 `pluginsEnabled`。
+插件使用名为 `paseo` 的 DSH profile。首次启动时，插件用 DSH 官方的 `web` 模板自动创建它（位置是 `~/.dsh/profiles/paseo`；设置了 `$DSH_HOME` 时在其下）。模型路由、默认模型和权限预设写在 `~/.dsh/profiles/paseo/cordis.patch.yml`。可在 Paseo 配置的 `agents.providers.dsh-pi.command` 或 `PASEO_DSH_EXECUTABLE`（后者优先）指定其他 `dsh` 可执行文件，通过 `PASEO_DSH_PROFILE` 改用另一个已存在的 profile；这样指定的 profile 不会被自动创建。如果 Paseo Daemon 默认关闭插件加载，请先在配置中启用 `pluginsEnabled`。
 
 如果原生会话仍被另一个 DSH 客户端（如终端界面）占用，请先在那里释放，再从 Paseo 导入或恢复。
 

package/index.server.ts

@@ -1,10 +1,10 @@
 import type { PluginServerContext } from "@getpaseo/plugin/server";
-import { launchDshBridge, resolveDshExecutable } from "./server/bridge-client.js";
+import { launchDshBridge } from "./server/bridge-client.js";
 import { DSH_BRIDGE_SOURCE } from "./server/generated-bridge.js";
 import { createDshProvider } from "./server/provider.js";
 
 export default function contribute(server: PluginServerContext) {
-  const executable = resolveDshExecutable(process.env.PASEO_DSH_EXECUTABLE);
+  const executable = process.env.PASEO_DSH_EXECUTABLE;
   server.registerProvider(
     createDshProvider({
       executable,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paseo-dsh-direct",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "DeepSeek Harness Direct Provider Plugin for Paseo",
   "repository": {
     "type": "git",
@@ -25,6 +25,7 @@
     "paseo-plugin.json",
     "dsh.svg",
     "dsh.png",
+    "OVERVIEW.md",
     "!server/**/*.test.ts",
     "!server/generated-bridge.ts",
     "!server/generated-version.ts"

package/server/bridge-client.ts

@@ -3,6 +3,8 @@ import { mkdtemp, rm, stat, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import path from "node:path";
 import { createInterface } from "node:readline";
+import { detectDshVersion } from "./dsh-version.js";
+import type { ProviderLaunch } from "@getpaseo/plugin/server/provider";
 import type {
   BridgeInitializeResult,
   BridgeMethods,
@@ -16,8 +18,10 @@ type Notification = keyof BridgeNotifications;
 
 export interface DshBridge {
   readonly initialized: BridgeInitializeResult;
-  /** The resolved `dsh` executable this bridge was launched with (see `PASEO_DSH_EXECUTABLE`). */
+  /** The resolved `dsh` executable this bridge was launched with (see `resolveDshLaunch`). */
   readonly executable: string;
+  /** Arguments that precede dsh's own arguments, from Paseo's resolved `command`. */
+  readonly args?: readonly string[];
   request<Name extends Method>(
     method: Name,
     params: BridgeMethods[Name]["params"],
@@ -52,9 +56,12 @@ export interface SessionLaunch {
   /** Store sessions under the bridge's temporary directory, removed on close. */
   ephemeral?: boolean;
   mcpServers?: readonly BridgeMcpServer[];
+  /** The `launch` Paseo resolved for the provider connection: command, leading arguments and the complete daemon environment. */
+  providerLaunch?: ProviderLaunch;
 }
 
 export interface LaunchBridgeOptions extends SessionLaunch {
+  /** The `PASEO_DSH_EXECUTABLE` value; it takes precedence over `providerLaunch.command`. */
   executable?: string;
   profile?: string;
   bridgeSource: string;
@@ -123,6 +130,7 @@ export function createBridgePatch(options: {
  */
 export async function ensureDshProfile(options: {
   executable: string;
+  args?: readonly string[];
   profile: string;
   env: Readonly<Record<string, string | undefined>>;
   timeoutMs?: number;
@@ -139,7 +147,13 @@ export async function ensureDshProfile(options: {
   // Concurrent first launches share one creation run.
   let creation = profileCreations.get(directory);
   if (!creation) {
-    creation = runProfileInit(options.executable, options.profile, options.env, options.timeoutMs ?? 60_000).finally(
+    creation = runProfileInit(
+      options.executable,
+      options.args ?? [],
+      options.profile,
+      options.env,
+      options.timeoutMs ?? 60_000,
+    ).finally(
       () => profileCreations.delete(directory),
     );
     profileCreations.set(directory, creation);
@@ -162,6 +176,7 @@ async function isDirectory(directory: string): Promise<boolean> {
 
 function runProfileInit(
   executable: string,
+  leadingArgs: readonly string[],
   profile: string,
   env: Readonly<Record<string, string | undefined>>,
   timeoutMs: number,
@@ -169,7 +184,7 @@ function runProfileInit(
   return new Promise((resolve, reject) => {
     const child = spawn(
       executable,
-      ["--profile", profile, "--from-default-profile", DEFAULT_PROFILE_TEMPLATE, "--dump-config"],
+      [...leadingArgs, "--profile", profile, "--from-default-profile", DEFAULT_PROFILE_TEMPLATE, "--dump-config"],
       { env, stdio: ["ignore", "ignore", "pipe"], windowsHide: true },
     );
     let stderr = "";
@@ -199,16 +214,135 @@ function runProfileInit(
   });
 }
 
-/** The `dsh` executable for a configured `PASEO_DSH_EXECUTABLE` value: the trimmed value, or `dsh` from `PATH` when it is blank or unset. */
-export function resolveDshExecutable(configured: string | undefined): string {
-  return configured?.trim() || "dsh";
+/** The command and leading arguments that start dsh. */
+export interface DshLaunch {
+  command: string;
+  args: readonly string[];
+}
+
+/**
+ * The dsh launch, by precedence: a non-blank `PASEO_DSH_EXECUTABLE` (the most
+ * specific signal, kept for existing installs), then the `launch` Paseo
+ * resolved from `command` / `agents.providers.dsh-pi.command`, then `dsh` from
+ * `PATH`. `launch.args` belong to `launch.command`, so they are dropped when
+ * the environment variable wins.
+ */
+export function resolveDshLaunch(configured: string | undefined, launch?: Pick<ProviderLaunch, "command" | "args">): DshLaunch {
+  const override = configured?.trim();
+  if (override) return { command: override, args: [] };
+  if (launch) return { command: launch.command, args: launch.args };
+  return { command: "dsh", args: [] };
+}
+
+/** The `dsh` executable chosen by `resolveDshLaunch`. */
+export function resolveDshExecutable(configured: string | undefined, launch?: Pick<ProviderLaunch, "command" | "args">): string {
+  return resolveDshLaunch(configured, launch).command;
+}
+
+/** Text for diagnostics: the command line with its leading arguments. */
+export function describeDshLaunch(launch: DshLaunch): string {
+  return [launch.command, ...launch.args].join(" ");
+}
+
+/** Row ids found in a dumped DSH configuration, in YAML (`id: x`) or JSON (`"id": "x"`) form. */
+export function dumpedRowIds(dump: string): Set<string> {
+  const ids = new Set<string>();
+  for (const match of dump.matchAll(/(?:^|[\s{,\-])["']?id["']?\s*:\s*["']?([A-Za-z0-9_.@/-]+)["']?/gm)) {
+    ids.add(match[1]!);
+  }
+  return ids;
+}
+
+/** The surface rows the launcher disables that the dumped configuration does not contain. */
+export function missingSurfaceRows(dump: string): string[] {
+  const present = dumpedRowIds(dump);
+  return DISABLED_SURFACE_ROWS.filter((row) => !present.has(row));
+}
+
+/**
+ * Fail loudly when the profile no longer has a row the launcher disables.
+ * Disabling an absent row has no effect, so a renamed row would leave the
+ * browser surface running beside the bridge. Returns normally when the dump
+ * cannot be obtained or is empty: the guard has no evidence then, and the real
+ * launch reports its own errors.
+ */
+export async function assertSurfaceRowsPresent(options: {
+  launch: DshLaunch;
+  profile: string;
+  env: Readonly<Record<string, string | undefined>>;
+  dshVersionOf: (launch: DshLaunch) => Promise<string>;
+  dump?: (launch: DshLaunch, profile: string, env: Readonly<Record<string, string | undefined>>) => Promise<string>;
+}): Promise<void> {
+  const dump = await (options.dump ?? dumpProfileConfig)(options.launch, options.profile, options.env).catch(() => "");
+  if (!dump.trim()) return;
+  const missing = missingSurfaceRows(dump);
+  if (missing.length === 0) return;
+  const version = (await options.dshVersionOf(options.launch).catch(() => "")) || "unknown";
+  throw new Error(
+    `DSH ${version} profile "${options.profile}" has no ${missing.map((row) => `"${row}"`).join(", ")} row. ` +
+      `The plugin disables ${DISABLED_SURFACE_ROWS.join(", ")} to keep the web surface from running beside the bridge, ` +
+      `so this dsh does not match the plugin. Install the dsh line this plugin release supports, ` +
+      `or recreate the profile from the web template.`,
+  );
+}
+
+/** `dsh --profile <profile> --dump-config` stdout; rejects when dsh fails or exceeds the timeout. */
+function dumpProfileConfig(
+  launch: DshLaunch,
+  profile: string,
+  env: Readonly<Record<string, string | undefined>>,
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(launch.command, [...launch.args, "--profile", profile, "--dump-config"], {
+      env,
+      stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true,
+    });
+    let stdout = "";
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk: string) => {
+      stdout = (stdout + chunk).slice(-1_048_576);
+    });
+    const timeout = setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(new Error("dsh --dump-config timed out"));
+    }, 20_000);
+    child.once("error", (error) => {
+      clearTimeout(timeout);
+      reject(error);
+    });
+    child.once("exit", (code) => {
+      clearTimeout(timeout);
+      if (code === 0) resolve(stdout);
+      else reject(new Error(`dsh --dump-config exited with code ${String(code)}`));
+    });
+  });
+}
+
+/** Names of host services or methods the bridge needs that the handshake reported missing. */
+export function assertBridgeHandshake(initialized: BridgeInitializeResult, dshVersion: string): void {
+  if (initialized.protocolVersion !== 1) {
+    throw new Error(`Unsupported DSH bridge protocol ${initialized.protocolVersion}`);
+  }
+  const missing = initialized.missing ?? [];
+  if (missing.length === 0) return;
+  throw new Error(
+    `DSH ${dshVersion || "unknown"} does not provide what the bridge depends on: ${missing.join(", ")}. ` +
+      `This dsh does not match the plugin; install the dsh line this plugin release supports.`,
+  );
 }
 
 export async function launchDshBridge(options: LaunchBridgeOptions): Promise<DshBridge> {
   const profile = options.profile?.trim() || DEFAULT_PROFILE;
-  const executable = resolveDshExecutable(options.executable);
-  const env = { ...process.env, ...options.env };
-  await ensureDshProfile({ executable, profile, env });
+  const launch = resolveDshLaunch(options.executable, options.providerLaunch);
+  const env = { ...(options.providerLaunch?.env ?? process.env), ...options.env };
+  await ensureDshProfile({ executable: launch.command, args: launch.args, profile, env });
+  await assertSurfaceRowsPresent({
+    launch,
+    profile,
+    env,
+    dshVersionOf: (target) => detectDshVersion(target.command, { args: target.args, env }),
+  });
   const directory = await mkdtemp(path.join(tmpdir(), "paseo-dsh-direct-"));
   const bridgePath = path.join(directory, "dsh-bridge.mjs");
   const patchPath = path.join(directory, "patch.json");
@@ -226,17 +360,18 @@ export async function launchDshBridge(options: LaunchBridgeOptions): Promise<Dsh
     { mode: 0o600 },
   );
 
-  const child = spawn(executable, ["--profile", profile, "--patch", patchPath], {
+  const child = spawn(launch.command, [...launch.args, "--profile", profile, "--patch", patchPath], {
     env,
     stdio: ["pipe", "pipe", "pipe"],
     windowsHide: true,
   });
-  const client = new JsonlBridgeClient(child, directory, executable);
+  const client = new JsonlBridgeClient(child, directory, launch);
   try {
     await client.waitUntilReady(options.startupTimeoutMs ?? 15_000);
     client.initialized = await client.request("bridge.initialize", {});
-    if (client.initialized.protocolVersion !== 1) {
-      throw new Error(`Unsupported DSH bridge protocol ${client.initialized.protocolVersion}`);
+    if (client.initialized.protocolVersion !== 1 || (client.initialized.missing?.length ?? 0) > 0) {
+      const version = await detectDshVersion(launch.command, { args: launch.args, env }).catch(() => "");
+      assertBridgeHandshake(client.initialized, version);
     }
     return client;
   } catch (error) {
@@ -248,6 +383,7 @@ export async function launchDshBridge(options: LaunchBridgeOptions): Promise<Dsh
 class JsonlBridgeClient implements DshBridge {
   initialized!: BridgeInitializeResult;
   readonly executable: string;
+  readonly args: readonly string[];
   private nextId = 1;
   private readonly pending = new Map<string | number, PendingRequest>();
   private readonly notifications = new Map<string, Set<(params: never) => void>>();
@@ -263,9 +399,10 @@ class JsonlBridgeClient implements DshBridge {
   constructor(
     private readonly child: ChildProcessWithoutNullStreams,
     private readonly temporaryDirectory: string,
-    executable: string,
+    launch: DshLaunch,
   ) {
-    this.executable = executable;
+    this.executable = launch.command;
+    this.args = launch.args;
     this.exited = new Promise((resolve) => {
       this.resolveExited = resolve;
     });

package/server/dsh/service.ts

@@ -24,6 +24,7 @@ import type {
   HostContext,
   HostHandle,
   HostHelpers,
+  HostServices,
   ModelSelectionRef,
 } from "./host.js";
 
@@ -93,6 +94,38 @@ export function savedModel(
   return pending ?? used;
 }
 
+/** Host services and methods every bridge method relies on; `service` alone means the service itself. */
+const REQUIRED_HOST_SURFACE = {
+  agents: ["get", "create", "resume"],
+  sessionQuery: ["listSessions", "readSession", "observeSession"],
+  agentPresets: ["list", "resolve", "mount", "select"],
+  llm: ["listProviders", "listModels"],
+} as const;
+
+/** The required host services and methods this DSH does not provide. */
+export function missingHostSurface(ctx: HostContext): string[] {
+  const missing: string[] = [];
+  for (const [service, methods] of Object.entries(REQUIRED_HOST_SURFACE)) {
+    let provided: unknown;
+    try {
+      provided = ctx.get(service as keyof HostServices);
+    } catch {
+      // A service that is not registered may throw instead of returning undefined.
+      provided = undefined;
+    }
+    if (provided === null || typeof provided !== "object") {
+      missing.push(service);
+      continue;
+    }
+    for (const method of methods) {
+      if (typeof (provided as Record<string, unknown>)[method] !== "function") {
+        missing.push(`${service}.${method}`);
+      }
+    }
+  }
+  return missing;
+}
+
 export class BridgeService {
   private readonly owned = new Map<string, RecordEntry>();
   private readonly opening = new Map<string, Promise<SessionOpenResult>>();
@@ -317,7 +350,14 @@ export class BridgeService {
     const params = record(input);
     let result: unknown;
     switch (method) {
-      case "bridge.initialize":
+      case "bridge.initialize": {
+        const missing = missingHostSurface(this.ctx);
+        if (missing.length > 0) {
+          result = { protocolVersion: 1, profile: this.profile, capabilities: {
+            stream: true, approvals: false, questions: false, history: true, cancel: true,
+          }, catalog: { models: [], presets: [] }, missing } satisfies BridgeInitializeResult;
+          break;
+        }
         result = {
           protocolVersion: 1,
           profile: this.profile,
@@ -331,6 +371,7 @@ export class BridgeService {
           catalog: await this.catalog(),
         } satisfies BridgeInitializeResult;
         break;
+      }
       case "session.list": {
         const query = this.ctx.get("sessionQuery");
         const records = await query.listSessions();

package/server/dsh-version.ts

@@ -8,6 +8,8 @@ const cache = new Map<string, Promise<string>>();
 export interface DetectDshVersionOptions {
   timeoutMs?: number;
   env?: Readonly<Record<string, string | undefined>>;
+  /** Arguments placed before `--version`, from Paseo's resolved command. */
+  args?: readonly string[];
 }
 
 /**
@@ -18,10 +20,11 @@ export interface DetectDshVersionOptions {
  * executable path for the life of the process.
  */
 export function detectDshVersion(executable: string, options: DetectDshVersionOptions = {}): Promise<string> {
-  const cached = cache.get(executable);
+  const key = JSON.stringify([executable, ...(options.args ?? [])]);
+  const cached = cache.get(key);
   if (cached) return cached;
   const probe = runVersionProbe(executable, options);
-  cache.set(executable, probe);
+  cache.set(key, probe);
   return probe;
 }
 
@@ -38,7 +41,7 @@ function runVersionProbe(executable: string, options: DetectDshVersionOptions):
 
     let child;
     try {
-      child = spawn(executable, ["--version"], {
+      child = spawn(executable, [...(options.args ?? []), "--version"], {
         env: options.env ?? process.env,
         stdio: ["ignore", "pipe", "ignore"],
         windowsHide: true,

package/server/provider.ts

@@ -24,7 +24,14 @@ import type {
   SlashCommand,
 } from "../shared/bridge-protocol.js";
 import { slashLine } from "../shared/bridge-protocol.js";
-import type { BridgeMcpServer, DshBridge, SessionLaunch } from "./bridge-client.js";
+import {
+  describeDshLaunch,
+  resolveDshLaunch,
+  type BridgeMcpServer,
+  type DshBridge,
+  type DshLaunch,
+  type SessionLaunch,
+} from "./bridge-client.js";
 import { detectDshVersion } from "./dsh-version.js";
 import { PLUGIN_VERSION } from "./plugin-version.js";
 import { displayText, toPromptParts } from "./prompt-content.js";
@@ -47,12 +54,17 @@ const CAPABILITIES = [
 const PERMISSION_PRESET_SETTING = "permissionPreset";
 const PLAN_MODE_SETTING = "planMode";
 
+type DetectVersion = (
+  executable: string,
+  options?: { args?: readonly string[]; env?: Readonly<Record<string, string | undefined>> },
+) => Promise<string>;
+
 interface DshProviderOptions {
   createBridge(launch?: SessionLaunch): Promise<DshBridge>;
-  /** The dsh executable `createBridge` launches; `status()` probes this same path. */
-  executable: string;
+  /** The `PASEO_DSH_EXECUTABLE` value; it outranks the `launch` Paseo resolves. `status()` and `createBridge` use the same precedence. */
+  executable?: string;
   /** Detects the local dsh version for the startup compatibility check; defaults to spawning `<exe> --version`. */
-  detectDshVersion?: (executable: string) => Promise<string>;
+  detectDshVersion?: DetectVersion;
 }
 
 /** A prompt or command RPC in flight; it owns any turn DSH starts before the RPC returns. */
@@ -91,12 +103,20 @@ export function createDshProvider(options: DshProviderOptions): ProviderRegistra
     icon: "dsh.svg",
     getCatalogCacheKey: async (options) =>
       options.scope === "workspace" ? `dsh-pi:${options.cwd}` : "dsh-pi:global",
-    async status() {
-      return dshStatus(options.executable, options.detectDshVersion ?? detectDshVersion);
+    command: ["dsh"],
+    async status(request) {
+      return dshStatus(
+        resolveDshLaunch(options.executable, request?.launch),
+        request?.launch?.env,
+        options.detectDshVersion ?? detectDshVersion,
+      );
     },
     async connect(request) {
       if (!request.versions.includes(1)) throw new Error("Provider protocol version 1 is required");
-      const bridge = await options.createBridge();
+      const providerLaunch = request.launch;
+      const createBridge = (launch?: SessionLaunch) =>
+        options.createBridge(providerLaunch ? { ...launch, providerLaunch } : launch);
+      const bridge = await createBridge();
       const supported = CAPABILITIES.filter(
         (capability) =>
           capability !== "permission" ||
@@ -105,9 +125,10 @@ export function createDshProvider(options: DshProviderOptions): ProviderRegistra
       );
       return createConnection(
         bridge,
-        options.createBridge,
+        createBridge,
         negotiateProviderCapabilities(request.capabilities, supported),
         options.detectDshVersion ?? detectDshVersion,
+        providerLaunch?.env,
       );
     },
   };
@@ -120,15 +141,17 @@ export function createDshProvider(options: DshProviderOptions): ProviderRegistra
  * shows, since only DSH's own handshake can reject a session.
  */
 async function dshStatus(
-  executable: string,
-  detectVersion: (executable: string) => Promise<string>,
+  launch: DshLaunch,
+  env: Readonly<Record<string, string>> | undefined,
+  detectVersion: DetectVersion,
 ): Promise<ProviderStatus> {
-  const dshVersion = await detectVersion(executable).catch(() => "");
+  const dshVersion = await detectVersion(launch.command, { args: launch.args, ...(env ? { env } : {}) }).catch(() => "");
   if (!dshVersion) {
     return {
       available: false,
       diagnostic:
-        `Could not run "${executable} --version". Install dsh or set PASEO_DSH_EXECUTABLE to its path, ` +
+        `Could not run "${describeDshLaunch(launch)} --version". Install dsh, ` +
+        `set agents.providers.dsh-pi.command in Paseo config, or set PASEO_DSH_EXECUTABLE, ` +
         `then restart the Paseo daemon.`,
     };
   }
@@ -139,9 +162,10 @@ async function dshStatus(
 
 function createConnection(
   discoveryBridge: DshBridge,
-  createBridge: DshProviderOptions["createBridge"],
+  createBridge: (launch?: SessionLaunch) => Promise<DshBridge>,
   capabilities: readonly string[],
-  detectVersion: (executable: string) => Promise<string>,
+  detectVersion: DetectVersion,
+  launchEnv: Readonly<Record<string, string>> | undefined,
 ): ProviderConnection {
   const listeners = new Set<(event: ProviderEvent) => void>();
   const sessions = new Map<string, SessionState>();
@@ -158,7 +182,7 @@ function createConnection(
       if (closed) throw new Error("Provider connection is closed");
       validateAdmission(input, sessions, capabilities);
       queueMicrotask(() => {
-        void dispatch(input, { discoveryBridge, createBridge, sessions, emit, capabilities, detectVersion }).catch(
+        void dispatch(input, { discoveryBridge, createBridge, sessions, emit, capabilities, detectVersion, launchEnv }).catch(
           (error) => failInput(input, error, emit),
         );
       });
@@ -305,11 +329,12 @@ function failSession(
 
 interface DispatchState {
   discoveryBridge: DshBridge;
-  createBridge: DshProviderOptions["createBridge"];
+  createBridge: (launch?: SessionLaunch) => Promise<DshBridge>;
   sessions: Map<string, SessionState>;
   emit(event: ProviderEvent): void;
   capabilities: readonly string[];
-  detectVersion: (executable: string) => Promise<string>;
+  detectVersion: DetectVersion;
+  launchEnv: Readonly<Record<string, string>> | undefined;
 }
 
 async function dispatch(input: ProviderInput, state: DispatchState): Promise<void> {
@@ -470,7 +495,10 @@ async function openSession(
  * Never blocks the session: DSH's own handshake is what can fail startup.
  */
 async function warnOnDshVersionMismatch(session: SessionState, state: DispatchState): Promise<void> {
-  const dshVersion = await state.detectVersion(session.bridge.executable).catch(() => "");
+  const dshVersion = await state.detectVersion(session.bridge.executable, {
+    args: session.bridge.args ?? [],
+    ...(state.launchEnv ? { env: state.launchEnv } : {}),
+  }).catch(() => "");
   const status = matchVersionLine(PLUGIN_VERSION, dshVersion);
   if (status === "match") return;
   const message = versionWarningMessage(status, PLUGIN_VERSION, dshVersion);

package/shared/bridge-protocol.ts

@@ -86,6 +86,12 @@ export interface BridgeInitializeResult {
     cancel: true;
   };
   catalog: BridgeCatalog;
+  /**
+   * DSH services or methods the bridge requires that this DSH does not provide,
+   * as `service` or `service.method`. Absent or empty when nothing is missing;
+   * the plugin refuses to connect otherwise.
+   */
+  missing?: string[];
 }
 export interface SessionOpenParams {
   sessionId?: string;