paseo-dsh-direct 0.2.2 → 0.2.4

package/OVERVIEW.md

@@ -0,0 +1,25 @@
+# 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.
+- Token usage and context-window fill in Paseo's usage meter.
+- 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

@@ -25,6 +25,7 @@ Most dsh integrations go through ACP, a generic protocol that every agent can sp
 - Tool approvals and dsh's questions to you appear as Paseo's own approval and question cards.
 - Your existing dsh sessions can be imported and resumed in Paseo.
 - dsh's slash commands (`/compact`, `/plan`, ...) appear in Paseo's `/` menu.
+- Paseo's usage meter shows dsh's token counts and how full the context window is.
 
 ## Versioning
 
@@ -36,7 +37,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

@@ -25,6 +25,7 @@
 - 工具审批和 dsh 向你提的问题，显示成 Paseo 自带的审批卡片和问答卡片。
 - 已有的 dsh 会话可以导入 Paseo 接着用。
 - dsh 的斜杠命令（`/compact`、`/plan` 等）出现在 Paseo 的 `/` 菜单里。
+- Paseo 的用量表显示 dsh 的 token 用量和上下文占用。
 
 ## 版本号
 
@@ -36,7 +37,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/dsh.svg

@@ -1,11 +1,3 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="DeepSeek Harness">
-  <defs>
-    <linearGradient id="wave" x1="8" y1="10" x2="56" y2="54" gradientUnits="userSpaceOnUse">
-      <stop stop-color="#6A8DFF"/>
-      <stop offset="1" stop-color="#3158E6"/>
-    </linearGradient>
-  </defs>
-  <path fill="url(#wave)" d="M8 34c7-13 18-20 33-20 6 0 11 1 15 4-2 13-8 23-18 29-8 5-17 6-27 3 7-2 12-6 15-11-7 2-13 0-18-5Z"/>
-  <circle cx="43" cy="25" r="3" fill="#fff"/>
-  <path d="M13 42c8 4 17 3 25-2" fill="none" stroke="#fff" stroke-width="3" stroke-linecap="round" opacity=".9"/>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 50 50" fill="currentColor" role="img" aria-label="DeepSeek Harness">
+  <path fill-rule="nonzero" d="M48.8354 10.0479C48.3232 9.79199 48.1025 10.2798 47.8032 10.5278C47.7007 10.6079 47.6143 10.7119 47.5273 10.8076C46.7793 11.624 45.9048 12.1597 44.7622 12.0957C43.0923 12 41.666 12.5356 40.4058 13.8398C40.1377 12.2319 39.2476 11.272 37.8926 10.6558C37.1836 10.3359 36.4668 10.0156 35.9702 9.31982C35.6235 8.82373 35.5293 8.27197 35.356 7.72754C35.2456 7.3999 35.1353 7.06396 34.7651 7.00781C34.3633 6.94385 34.2056 7.2876 34.0479 7.57568C33.418 8.75195 33.1733 10.0479 33.1973 11.3599C33.2524 14.312 34.4736 16.6641 36.8999 18.3359C37.1758 18.5278 37.2466 18.7197 37.1597 19C36.9946 19.5757 36.7974 20.1357 36.624 20.7119C36.5137 21.0801 36.3486 21.1597 35.9624 21C34.6309 20.4321 33.481 19.5918 32.4644 18.5757C30.7393 16.8721 29.1792 14.9917 27.2334 13.52C26.7764 13.1758 26.3193 12.856 25.8467 12.5518C23.8618 10.584 26.1069 8.96777 26.627 8.77588C27.1704 8.57568 26.8159 7.8877 25.0591 7.896C23.3022 7.90381 21.6953 8.50391 19.647 9.30371C19.3477 9.42383 19.0322 9.51172 18.7095 9.58398C16.8501 9.22363 14.9199 9.14355 12.9033 9.37598C9.10596 9.80762 6.07275 11.6396 3.84326 14.7681C1.16455 18.5278 0.53418 22.7998 1.30664 27.2559C2.11768 31.9521 4.46582 35.8398 8.07373 38.8799C11.8159 42.0322 16.1255 43.5762 21.041 43.2803C24.0269 43.104 27.3516 42.6963 31.1016 39.4561C32.0469 39.936 33.0396 40.1279 34.686 40.272C35.9546 40.3921 37.1758 40.208 38.1211 40.0078C39.6021 39.688 39.4995 38.2881 38.9639 38.0322C34.623 35.9678 35.5762 36.8081 34.71 36.1279C36.9155 33.4639 40.2402 30.6958 41.54 21.728C41.6426 21.0161 41.5557 20.5679 41.54 19.9917C41.5322 19.6396 41.6108 19.5039 42.0049 19.4639C43.0923 19.3359 44.1479 19.0317 45.1167 18.4878C47.9292 16.9199 49.064 14.3438 49.3315 11.2559C49.3711 10.7837 49.3237 10.2959 48.8354 10.0479ZM24.3262 37.8398C20.1196 34.4639 18.0791 33.3521 17.2358 33.3999C16.4482 33.4482 16.5898 34.3682 16.7632 34.9678C16.9443 35.5601 17.1812 35.9683 17.5117 36.4878C17.7402 36.832 17.8979 37.3442 17.2832 37.728C15.9282 38.584 13.5728 37.4399 13.4624 37.3838C10.7207 35.7358 8.42822 33.5601 6.81348 30.584C5.25342 27.7197 4.34766 24.6479 4.19775 21.3677C4.1582 20.5757 4.38672 20.2959 5.15869 20.1519C6.17529 19.96 7.22314 19.9199 8.23926 20.0718C12.5327 20.7119 16.1885 22.6719 19.2529 25.7759C21.002 27.5439 22.3252 29.6558 23.6885 31.7202C25.1377 33.9121 26.6978 36 28.6831 37.7119C29.3843 38.312 29.9434 38.7681 30.479 39.104C28.8643 39.2881 26.1699 39.3281 24.3262 37.8398ZM26.3433 24.6001C26.3433 24.248 26.6191 23.9678 26.9658 23.9678C27.0444 23.9678 27.1152 23.9839 27.1782 24.0078C27.2651 24.04 27.3438 24.0879 27.4067 24.1602C27.5171 24.272 27.5801 24.4321 27.5801 24.6001C27.5801 24.9521 27.3042 25.2319 26.9575 25.2319C26.6108 25.2319 26.3433 24.9521 26.3433 24.6001ZM32.6064 27.8799C32.2046 28.0479 31.8027 28.1919 31.4165 28.208C30.8179 28.2397 30.1641 27.9922 29.8096 27.688C29.2583 27.2158 28.8643 26.9521 28.6987 26.1279C28.6279 25.7759 28.6675 25.2319 28.7305 24.9199C28.8721 24.248 28.7144 23.8159 28.2495 23.4238C27.8716 23.104 27.3911 23.0161 26.8633 23.0161C26.666 23.0161 26.4849 22.9277 26.3511 22.856C26.1304 22.7441 25.9492 22.4639 26.1226 22.1201C26.1777 22.0078 26.4458 21.7358 26.5088 21.688C27.2256 21.272 28.0527 21.4077 28.8169 21.7197C29.5259 22.0161 30.0615 22.5601 30.834 23.3281C31.6216 24.2559 31.7632 24.5117 32.2124 25.208C32.5669 25.752 32.8901 26.312 33.1104 26.9521C33.2446 27.3521 33.0713 27.6802 32.6064 27.8799Z"/>
 </svg>

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.4",
   "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/scripts/build.mjs

@@ -13,7 +13,8 @@ const result = await build({
   write: false,
 })
 
-const bridge = result.outputFiles.find(file => file.path.endsWith('/dsh-bridge.mjs'))
+// esbuild reports output paths with the platform separator (backslashes on Windows).
+const bridge = result.outputFiles.find(file => file.path.replace(/\\/g, '/').endsWith('/dsh-bridge.mjs'))
 if (!bridge) throw new Error('esbuild did not produce dist/dsh-bridge.mjs')
 await mkdir('dist', { recursive: true })
 await writeFile('dist/dsh-bridge.mjs', bridge.contents)

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/host.ts

@@ -125,6 +125,26 @@ export interface HostServices {
     }>;
   };
   agentDefaultModel: { currentSelection(): ModelSelection } | undefined;
+  /**
+   * Projection registry read cut. The `tokenUsage` and `contextPressure` units
+   * carry the figures Paseo renders as session usage; absent when the profile
+   * mounts no projection registry.
+   */
+  sessionProjections?: {
+    snapshot(
+      session: HostSession,
+      keys?: readonly string[],
+    ): { values: Partial<Record<string, unknown>> };
+    /** Change feed: fires once per client-visible unit whose raw view changed. */
+    onChanged(
+      listener: (
+        session: HostSession,
+        key: string,
+        value: unknown,
+        seq: number,
+      ) => void,
+    ): () => void;
+  };
   sessionTitle:
     { rename(session: HostSession, title: string): void } | undefined;
   approval: object | undefined;

package/server/dsh/service.ts

@@ -6,6 +6,7 @@ import type {
   BridgeInitializeResult,
   BridgeMethods,
   BridgeNotifications,
+  BridgeUsage,
   DshSessionEvent,
   InteractionRequest,
   ModelSelection,
@@ -24,6 +25,8 @@ import type {
   HostContext,
   HostHandle,
   HostHelpers,
+  HostServices,
+  HostSession,
   ModelSelectionRef,
 } from "./host.js";
 
@@ -93,6 +96,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>>();
@@ -103,6 +138,8 @@ export class BridgeService {
   private readonly preapproved = new Map<string, ReadonlySet<string>>();
   private readonly interactions = new Map<string, PendingInteraction>();
   private readonly subscriptions: Array<() => void> = [];
+  /** Last usage payload sent per session, so an unchanged fold is not re-sent. */
+  private readonly lastUsage = new Map<string, string>();
   private stopping = false;
   private stopTask?: Promise<{}>;
 
@@ -139,6 +176,19 @@ export class BridgeService {
           notify("session.status", { sessionId: String(agent.id), status });
       }),
     );
+    // Usage rides the projection change feed rather than the session event
+    // stream: it fires exactly when the harness's token fold moves, so no
+    // session-event name has to be guessed and an idle session costs nothing.
+    const projections = ctx.get("sessionProjections");
+    if (projections) {
+      this.subscriptions.push(
+        projections.onChanged((session, key) => {
+          if (key === "tokenUsage" || key === "contextPressure") {
+            this.publishUsage(session);
+          }
+        }),
+      );
+    }
     this.subscriptions.push(
       ctx.on("approval/request", (request, next) => {
         const sessionId = this.rootFor(request.agent);
@@ -183,6 +233,70 @@ export class BridgeService {
     );
   }
 
+  /**
+   * Fold the harness's token projections into Paseo's usage vocabulary.
+   *
+   * `tokenUsage` totals and `contextPressure` carry every figure Paseo can
+   * render, and both are plain numbers, so no live harness object crosses the
+   * wire. Returns undefined when no projection registry is mounted or neither
+   * unit is registered: a profile without them degrades to no usage rather
+   * than failing the turn.
+   */
+  private readUsage(session: HostSession): BridgeUsage | undefined {
+    const projections = this.ctx.get("sessionProjections");
+    if (!projections) return undefined;
+    let values: Partial<Record<string, unknown>>;
+    try {
+      values = projections.snapshot(session, [
+        "tokenUsage",
+        "contextPressure",
+      ]).values;
+    } catch {
+      return undefined;
+    }
+    const tokens = values.tokenUsage as
+      | {
+          uncachedInputTokens?: number;
+          outputTokens?: number;
+          cacheReadTokens?: number;
+        }
+      | undefined;
+    const pressure = values.contextPressure as
+      | { contextWindow?: number; pressureTokens?: number }
+      | undefined;
+    const usage: BridgeUsage = {};
+    if (typeof tokens?.uncachedInputTokens === "number")
+      usage.inputTokens = tokens.uncachedInputTokens;
+    if (typeof tokens?.cacheReadTokens === "number")
+      usage.cachedInputTokens = tokens.cacheReadTokens;
+    if (typeof tokens?.outputTokens === "number")
+      usage.outputTokens = tokens.outputTokens;
+    if (typeof pressure?.pressureTokens === "number")
+      usage.contextWindowUsedTokens = pressure.pressureTokens;
+    if (typeof pressure?.contextWindow === "number")
+      usage.contextWindowMaxTokens = pressure.contextWindow;
+    // The units materialize at zero before any provider usage lands, so a
+    // payload carrying no measured token is warm-up noise, not a reading.
+    const measured =
+      (usage.inputTokens ?? 0) > 0 ||
+      (usage.cachedInputTokens ?? 0) > 0 ||
+      (usage.outputTokens ?? 0) > 0 ||
+      (usage.contextWindowUsedTokens ?? 0) > 0;
+    return measured ? usage : undefined;
+  }
+
+  /** Publish one tracked session's usage, skipping an unchanged fold. */
+  private publishUsage(session: HostSession): void {
+    const sessionId = String(session.id);
+    if (!this.tracked.has(sessionId)) return;
+    const usage = this.readUsage(session);
+    if (!usage) return;
+    const signature = JSON.stringify(usage);
+    if (this.lastUsage.get(sessionId) === signature) return;
+    this.lastUsage.set(sessionId, signature);
+    this.notify("session.usage", { sessionId, usage });
+  }
+
   private rootFor(agent: HostAgent | undefined): string | undefined {
     let id = agent?.id && String(agent.id);
     const seen = new Set<string>();
@@ -317,7 +431,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 +452,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();
@@ -611,6 +733,7 @@ export class BridgeService {
         this.opening.delete(id);
         this.tracked.delete(id);
         this.preapproved.delete(id);
+        this.lastUsage.delete(id);
       },
     );
     return task;
@@ -759,6 +882,7 @@ export class BridgeService {
       this.owned.delete(id);
       this.tracked.delete(id);
       this.preapproved.delete(id);
+      this.lastUsage.delete(id);
     })();
     this.closing.set(id, task);
     void task.finally(() => this.closing.delete(id)).catch(() => undefined);

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),
         );
       });
@@ -251,6 +275,15 @@ function listenToSessionBridge(
         session.dispatch.deferred = terminal;
       }
     }),
+    session.bridge.on("session.usage", ({ sessionId, usage }) => {
+      if (!isCurrentSession(sessionId)) return;
+      emit({
+        type: "session.usage",
+        sessionId: session.paseoId,
+        ...(session.activeTurnId ? { turnId: session.activeTurnId } : {}),
+        usage,
+      });
+    }),
     session.bridge.on("interaction.request", (interaction) => {
       if (!isCurrentSession(interaction.sessionId)) return;
       session.pendingInteractions.set(interaction.requestId, interaction);
@@ -305,11 +338,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 +504,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;
@@ -202,11 +208,30 @@ export interface BridgeMethods {
   };
   "bridge.shutdown": { params: {}; result: {} };
 }
+/**
+ * One session's token and context figures, in Paseo's usage vocabulary.
+ *
+ * Field names match `ProviderUsage` so the provider forwards this straight
+ * onto `session.usage` without a second translation table.
+ */
+export interface BridgeUsage {
+  /** Uncached prompt tokens reported by the provider. */
+  inputTokens?: number;
+  /** Prompt tokens served from the provider's cache. */
+  cachedInputTokens?: number;
+  /** Completion tokens produced by the model. */
+  outputTokens?: number;
+  /** Provider-reported prompt size of the newest request. */
+  contextWindowUsedTokens?: number;
+  /** Route context capacity paired with that pressure. */
+  contextWindowMaxTokens?: number;
+}
 export interface BridgeNotifications {
   "bridge.ready": { protocolVersion: 1 };
   "session.event": { sessionId: string; event: DshSessionEvent };
   "session.stream": { sessionId: string; frame: DshStreamFrame };
   "session.status": { sessionId: string; status: "idle" | "running" };
+  "session.usage": { sessionId: string; usage: BridgeUsage };
   "interaction.request": InteractionRequest;
   "interaction.closed": { requestId: string; sessionId: string };
 }