dsh-ccgui 1.0.1 → 1.0.2

package/lib/index.d.ts

@@ -50,6 +50,7 @@ export default class CliBridge extends Service {
     private readonly catalog;
     /** Ends any model probe still running when this plugin goes away. */
     private readonly probes;
+    private readonly loginPath;
     constructor(ctx: Context, config: Config);
     /** Read in the background: the menu works without it, and fills in once it arrives. */
     private restoreModels;

package/lib/index.js

@@ -19,6 +19,8 @@ import { npxCacheDir, startFromNpxCache } from "./npx-cache.js";
 import { gitHandler, registerGitRoutes } from "./git/git-routes.js";
 import { CliSessionRegistry } from "./session-registry.js";
 import { openStdioTransport } from "./stdio-transport.js";
+import { startOnWindows } from "./windows-command.js";
+import { LoginPath, diskDirs, runShell } from "./login-path.js";
 /**
  * Shown to turns cut off when this plugin stops. Besides shutdown, the harness restarts a
  * plugin whose files changed, which takes every CLI it started down with it.
@@ -50,9 +52,20 @@ export default class CliBridge extends Service {
     catalog;
     /** Ends any model probe still running when this plugin goes away. */
     probes = new AbortController();
+    loginPath;
     constructor(ctx, config) {
         super(ctx, 'cliBridge');
         this.config = config;
+        this.loginPath = new LoginPath({
+            platform: process.platform,
+            env: process.env,
+            home: homedir(),
+            dirs: diskDirs,
+            run: runShell,
+            warn: (message) => ctx.logger.warn(message),
+        });
+        // Started first so the answer is likely in before the first CLI starts; until then the fallback holds.
+        void this.loginPath.load(this.probes.signal);
         this.registry = new CliSessionRegistry(config.agents, {
             getAgent: (sessionId) => ctx.agents.get(sessionId),
             composedPreset: (agent) => ctx.get('agentPresets')?.composedPreset(agent.ctx),
@@ -165,10 +178,11 @@ export default class CliBridge extends Service {
         });
     }
     openTransport(agent, cwd, handlers) {
-        const { argv, env } = startFromNpxCache({ argv: [agent.command, ...agent.args], env: agent.env }, {
+        const fromCache = startFromNpxCache({ argv: [agent.command, ...agent.args], env: this.loginPath.apply(agent.env) }, {
             npxCache: npxCacheDir(process.env, homedir(), process.platform),
             path: process.env.PATH,
         });
+        const { argv, env } = startOnWindows(fromCache, process.platform, process.env);
         return openStdioTransport({
             argv,
             cwd,

package/lib/login-path.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Gives CLIs the PATH a terminal would give them. On macOS an app started from the Dock gets
+ * launchd's PATH, `/usr/bin:/bin:/usr/sbin:/sbin`, and never reads the shell's rc files, so a
+ * node installed through nvm, fnm or Volta is out of sight. Every npx-based CLI then dies
+ * with exit code 127 from `/usr/bin/env node`, while the same CLI works in a terminal.
+ *
+ * The login shell is asked for its PATH once, in the background, since rc files can take
+ * seconds. Until it answers, or when it fails, the usual install places are appended to the
+ * inherited PATH, which already covers the common nvm and Homebrew setups.
+ * @module dsh-ccgui/login-path
+ */
+/** What the lookup needs from the file system; separate so tests need not touch the disk. */
+export interface DirProbe {
+    readonly isDir: (path: string) => boolean;
+    readonly list: (path: string) => readonly string[];
+}
+/** Runs a command and resolves with its stdout. */
+export type ShellRunner = (argv: readonly string[], signal: AbortSignal) => Promise<string>;
+export interface LoginPathOptions {
+    readonly platform: NodeJS.Platform;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly home: string;
+    readonly dirs: DirProbe;
+    readonly run: ShellRunner;
+    readonly warn: (message: string) => void;
+}
+/**
+ * Read the PATH out of the login shell's output.
+ * @param stdout - everything the shell printed.
+ * @returns the PATH, or undefined when the output does not hold one.
+ */
+export declare function parseShellPath(stdout: string): string | undefined;
+/**
+ * Join PATH values, keeping the first occurrence of each directory.
+ * @param paths - PATH values, in order of precedence.
+ * @returns one PATH value.
+ */
+export declare function mergePaths(...paths: readonly (string | undefined)[]): string;
+/**
+ * The usual install places for CLIs and node that exist on this machine.
+ * @param home - the user's home directory.
+ * @param dirs - the file system.
+ * @returns existing directories, newest nvm node first since nvm's default is usually it.
+ */
+export declare function knownBinDirs(home: string, dirs: DirProbe): readonly string[];
+/** The PATH handed to CLIs: the login shell's when known, the inherited one plus fallbacks otherwise. */
+export declare class LoginPath {
+    private readonly options;
+    private login;
+    constructor(options: LoginPathOptions);
+    /**
+     * Ask the login shell for its PATH. Never rejects: a failure only keeps the fallback.
+     * @param signal - ends the shell when the plugin goes away.
+     */
+    load(signal: AbortSignal): Promise<void>;
+    /**
+     * Give a CLI's environment a full PATH, unless it is configured with one.
+     * @param env - the environment configured for the CLI.
+     * @returns the environment to start the CLI with.
+     */
+    apply(env: Readonly<Record<string, string>>): Readonly<Record<string, string>>;
+}
+/**
+ * Run a command outside the harness's subprocess service: this is a fact about the machine
+ * the plugin runs on, read once, like the npx cache next to it.
+ * @param argv - program and arguments.
+ * @param signal - ends the command.
+ * @returns the command's stdout.
+ */
+export declare function runShell(argv: readonly string[], signal: AbortSignal): Promise<string>;
+/** The real file system. */
+export declare const diskDirs: DirProbe;

package/lib/login-path.js

@@ -0,0 +1,143 @@
+/**
+ * Gives CLIs the PATH a terminal would give them. On macOS an app started from the Dock gets
+ * launchd's PATH, `/usr/bin:/bin:/usr/sbin:/sbin`, and never reads the shell's rc files, so a
+ * node installed through nvm, fnm or Volta is out of sight. Every npx-based CLI then dies
+ * with exit code 127 from `/usr/bin/env node`, while the same CLI works in a terminal.
+ *
+ * The login shell is asked for its PATH once, in the background, since rc files can take
+ * seconds. Until it answers, or when it fails, the usual install places are appended to the
+ * inherited PATH, which already covers the common nvm and Homebrew setups.
+ * @module dsh-ccgui/login-path
+ */
+import { execFile } from 'node:child_process';
+import { readdirSync, statSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+/** Brackets the value, since rc files are free to print greetings around it. */
+const MARKER = '__DSH_CCGUI_PATH__';
+/** `printenv` reads the exported value, so it prints the same in sh, zsh, bash and fish. */
+const PRINT_PATH = `echo ${MARKER}; printenv PATH; echo ${MARKER}`;
+const SHELL_TIMEOUT_MS = 5_000;
+const SHELL_MAX_OUTPUT_BYTES = 1024 * 1024;
+/** The shell macOS gives new accounts; elsewhere the one every system has. */
+const DARWIN_SHELL = '/bin/zsh';
+const POSIX_SHELL = '/bin/sh';
+const SYSTEM_DIRS = ['/opt/homebrew/bin', '/opt/homebrew/sbin', '/usr/local/bin'];
+const HOME_DIRS = [
+    '.local/bin',
+    '.volta/bin',
+    '.bun/bin',
+    '.cargo/bin',
+    '.local/share/mise/shims',
+    '.asdf/shims',
+    'Library/pnpm',
+    '.local/share/pnpm',
+];
+const NVM_VERSIONS = '.nvm/versions/node';
+/**
+ * Read the PATH out of the login shell's output.
+ * @param stdout - everything the shell printed.
+ * @returns the PATH, or undefined when the output does not hold one.
+ */
+export function parseShellPath(stdout) {
+    const parts = stdout.split(MARKER);
+    // The last pair is ours; an rc file that echoes commands adds an earlier one.
+    const value = parts.length < 3 ? undefined : parts[parts.length - 2]?.trim();
+    return value === undefined || value === '' ? undefined : value;
+}
+/**
+ * Join PATH values, keeping the first occurrence of each directory.
+ * @param paths - PATH values, in order of precedence.
+ * @returns one PATH value.
+ */
+export function mergePaths(...paths) {
+    const entries = paths.flatMap((path) => (path ?? '').split(delimiter)).filter((dir) => dir !== '');
+    return [...new Set(entries)].join(delimiter);
+}
+function versionParts(version) {
+    return (version.match(/\d+/g) ?? []).map(Number);
+}
+function newestFirst(a, b) {
+    const [left, right] = [versionParts(a), versionParts(b)];
+    const index = left.findIndex((part, i) => part !== right[i]);
+    return index === -1 ? right.length - left.length : (right[index] ?? 0) - (left[index] ?? 0);
+}
+/**
+ * The usual install places for CLIs and node that exist on this machine.
+ * @param home - the user's home directory.
+ * @param dirs - the file system.
+ * @returns existing directories, newest nvm node first since nvm's default is usually it.
+ */
+export function knownBinDirs(home, dirs) {
+    const nvm = join(home, NVM_VERSIONS);
+    const nvmBins = [...dirs.list(nvm)].sort(newestFirst).map((version) => join(nvm, version, 'bin'));
+    return [...SYSTEM_DIRS, ...HOME_DIRS.map((dir) => join(home, dir)), ...nvmBins].filter((dir) => dirs.isDir(dir));
+}
+/** The PATH handed to CLIs: the login shell's when known, the inherited one plus fallbacks otherwise. */
+export class LoginPath {
+    options;
+    login;
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Ask the login shell for its PATH. Never rejects: a failure only keeps the fallback.
+     * @param signal - ends the shell when the plugin goes away.
+     */
+    async load(signal) {
+        const { platform, env, run, warn } = this.options;
+        if (platform === 'win32')
+            return;
+        const shell = env.SHELL ?? (platform === 'darwin' ? DARWIN_SHELL : POSIX_SHELL);
+        try {
+            this.login = parseShellPath(await run([shell, '-ilc', PRINT_PATH], signal));
+        }
+        catch (error) {
+            if (!signal.aborted)
+                warn(`ccgui: could not read the login shell's PATH: ${String(error)}`);
+        }
+    }
+    /**
+     * Give a CLI's environment a full PATH, unless it is configured with one.
+     * @param env - the environment configured for the CLI.
+     * @returns the environment to start the CLI with.
+     */
+    apply(env) {
+        const { platform, env: inherited, home, dirs } = this.options;
+        if (platform === 'win32' || env.PATH !== undefined)
+            return env;
+        return { ...env, PATH: mergePaths(this.login, inherited.PATH, ...knownBinDirs(home, dirs)) };
+    }
+}
+/**
+ * Run a command outside the harness's subprocess service: this is a fact about the machine
+ * the plugin runs on, read once, like the npx cache next to it.
+ * @param argv - program and arguments.
+ * @param signal - ends the command.
+ * @returns the command's stdout.
+ */
+export function runShell(argv, signal) {
+    const [program, ...args] = argv;
+    return new Promise((resolve, reject) => {
+        const child = execFile(program ?? POSIX_SHELL, args, { signal, timeout: SHELL_TIMEOUT_MS, maxBuffer: SHELL_MAX_OUTPUT_BYTES, encoding: 'utf8' }, (error, stdout) => {
+            if (error === null)
+                resolve(stdout);
+            else
+                reject(new Error(`${program ?? POSIX_SHELL} failed: ${error.message}`, { cause: error }));
+        });
+        // An interactive shell must not sit waiting for input nobody will type.
+        child.stdin?.end();
+    });
+}
+/** The real file system. */
+export const diskDirs = {
+    isDir: (path) => statSync(path, { throwIfNoEntry: false })?.isDirectory() ?? false,
+    list: (path) => {
+        try {
+            return readdirSync(path);
+        }
+        catch {
+            // No such directory (no nvm installed) simply means nothing to add.
+            return [];
+        }
+    },
+};

package/lib/model-options.js

@@ -4,6 +4,7 @@
  */
 import { DEFAULT_MODEL_ID } from "./constants.js";
 const CONVENTIONAL_MODEL_OPTION_ID = 'model';
+const NAME_SEPARATOR = ' · ';
 const isObject = (value) => typeof value === 'object' && value !== null;
 const isText = (value) => typeof value === 'string' && value.length > 0;
 function flattenEntries(entries) {
@@ -23,7 +24,26 @@ function readEntry(entry) {
     if (!isObject(entry) || !isText(entry.value))
         return [];
     const name = entry.value === DEFAULT_MODEL_ID && isText(entry.description) ? entry.description : entry.name;
-    return [{ value: entry.value, name: isText(name) ? name : entry.value }];
+    const description = isText(entry.description) ? entry.description : undefined;
+    return [{ value: entry.value, name: isText(name) ? name : entry.value, description }];
+}
+/**
+ * A CLI can list several models under one name, CodeBuddy's free and paid tiers of Hy4 among
+ * them, which would leave rows nobody can tell apart. Such names gain what does tell them apart:
+ * the descriptions when those differ, otherwise the ids. The default entry is left alone, as the
+ * catalog labels it on its own and it is expected to share its model's name.
+ */
+function distinguishNames(entries) {
+    const named = entries.filter(({ value }) => value !== DEFAULT_MODEL_ID);
+    const peersOf = (name) => named.filter((entry) => entry.name === name);
+    return entries.map(({ value, name, description }) => {
+        const peers = peersOf(name);
+        if (value === DEFAULT_MODEL_ID || peers.length < 2)
+            return { value, name };
+        const descriptions = new Set(peers.map((peer) => peer.description));
+        const byDescription = descriptions.size === peers.length && !descriptions.has(undefined);
+        return { value, name: `${name}${NAME_SEPARATOR}${(byDescription ? description : undefined) ?? value}` };
+    });
 }
 /**
  * Find the model option. ACP marks it with a category, so that wins; the id is only
@@ -41,6 +61,6 @@ export function readModelList(configOptions) {
         selects.find((candidate) => candidate.category == null && candidate.id === CONVENTIONAL_MODEL_OPTION_ID);
     if (option === undefined || !isText(option.id) || !isText(option.currentValue))
         return undefined;
-    const options = flattenEntries(option.options).flatMap(readEntry);
+    const options = distinguishNames(flattenEntries(option.options).flatMap(readEntry));
     return options.length === 0 ? undefined : { configId: option.id, current: option.currentValue, options };
 }

package/lib/session/read-step.js

@@ -5,6 +5,7 @@
  */
 import { appendDelta, closeOpenBlock, EMPTY_BLOCKS } from "../stream-blocks.js";
 import { toolCallStep, turnEndStep, turnFailure } from "./outcomes.js";
+import { addUsage, toTokenUsage, withUsage } from "./turn-usage.js";
 /**
  * Read until the next tool call or the end of the CLI turn.
  * @param source - the session being read.
@@ -13,11 +14,15 @@ import { toolCallStep, turnEndStep, turnFailure } from "./outcomes.js";
  */
 export async function* readStep(source, signal) {
     let blocks = EMPTY_BLOCKS;
+    // Steering can end several CLI turns inside one step; the step reports them all.
+    let usage;
     while (source.hasWork()) {
         const event = await source.nextEvent(signal);
         if (source.owesInput() && event.type === 'turn-end')
             continue;
-        const step = applyEvent(source, blocks, event);
+        if (event.type === 'turn-end')
+            usage = addUsage(usage, toTokenUsage(event.usage));
+        const step = applyEvent(source, blocks, event, usage);
         blocks = step.state;
         yield* step.chunks;
         if (step.done)
@@ -25,10 +30,11 @@ export async function* readStep(source, signal) {
     }
     if (source.owesInput())
         throw source.failure();
-    yield* closeOpenBlock(blocks).chunks;
-    yield { type: 'finish', reason: { kind: 'stop' }, ...source.replay() };
+    const { state, chunks } = closeOpenBlock(blocks);
+    const finish = { type: 'finish', reason: { kind: 'stop' }, ...source.replay() };
+    yield* withUsage({ state, chunks: [...chunks, finish], done: true }, usage).chunks;
 }
-function applyEvent(source, blocks, event) {
+function applyEvent(source, blocks, event, usage) {
     switch (event.type) {
         case 'text':
         case 'reasoning':
@@ -40,14 +46,14 @@ function applyEvent(source, blocks, event) {
                 : toolCallStep(blocks, record, source.replay());
         }
         case 'turn-end':
-            return applyTurnEnd(source, blocks, event.stopReason);
+            return applyTurnEnd(source, blocks, event, usage);
         case 'failure':
             throw turnFailure(event.error, source.label);
     }
 }
 /** Queued steering runs as the next CLI turn inside the same harness turn. */
-function applyTurnEnd(source, blocks, stopReason) {
+function applyTurnEnd(source, blocks, end, usage) {
     if (source.hasWork())
         return { state: blocks, chunks: [], done: false };
-    return turnEndStep(blocks, stopReason, source.label, source.replay());
+    return withUsage(turnEndStep(blocks, end.stopReason, source.label, source.replay()), usage);
 }

package/lib/session/start-hint.d.ts

@@ -0,0 +1,13 @@
+/**
+ * What to tell the user after a CLI fails to start. The default asks them to
+ * install and log in, but an adapter pulled by `npx` can fail because npm left
+ * its cache half-installed (a skipped optional dependency, an interrupted
+ * download). Reinstalling globally does not help there: npx keeps reusing the
+ * broken cache until that directory is deleted.
+ * @module dsh-ccgui/session/start-hint
+ */
+/**
+ * @param message - the startup error's text.
+ * @returns the sentence to append to the startup failure.
+ */
+export declare function startHint(message: string): string;

package/lib/session/start-hint.js

@@ -0,0 +1,33 @@
+/**
+ * What to tell the user after a CLI fails to start. The default asks them to
+ * install and log in, but an adapter pulled by `npx` can fail because npm left
+ * its cache half-installed (a skipped optional dependency, an interrupted
+ * download). Reinstalling globally does not help there: npx keeps reusing the
+ * broken cache until that directory is deleted.
+ * @module dsh-ccgui/session/start-hint
+ */
+import { fileURLToPath } from 'node:url';
+const INSTALL_HINT = '请确认它已安装并完成登录。';
+const REINSTALL_HINT = '它的安装不完整，请按上面的提示重新安装。';
+/** Errors that mean files are missing from the install, not that the CLI itself refused. */
+const INCOMPLETE_INSTALL = /Missing optional dependency|Cannot find module|ERR_MODULE_NOT_FOUND/;
+/** An npx cache entry, `<npm cache>/_npx/<hash>`, as a path or a `file://` URL. */
+const NPX_ENTRY = /[^\s'"()]*[\\/]_npx[\\/][0-9a-f]+/;
+function npxEntry(message) {
+    const found = NPX_ENTRY.exec(message)?.[0];
+    if (found === undefined)
+        return undefined;
+    return found.startsWith('file:') ? fileURLToPath(found) : found;
+}
+/**
+ * @param message - the startup error's text.
+ * @returns the sentence to append to the startup failure.
+ */
+export function startHint(message) {
+    if (!INCOMPLETE_INSTALL.test(message))
+        return INSTALL_HINT;
+    const entry = npxEntry(message);
+    if (entry === undefined)
+        return REINSTALL_HINT;
+    return `npx 缓存里的安装不完整，请删除 ${entry} 后重试，下次启动会重新下载。`;
+}

package/lib/session/turn-queue.d.ts

@@ -4,13 +4,12 @@
  * runs as the next turn.
  * @module dsh-ccgui/session/turn-queue
  */
-import type { ContentBlock as AcpContentBlock, StopReason } from '@agentclientprotocol/sdk';
-import type { AcpTransport } from '../transport.ts';
+import type { ContentBlock as AcpContentBlock } from '@agentclientprotocol/sdk';
+import type { AcpTransport, PromptOutcome } from '../transport.ts';
 /** How a CLI turn ended. */
-export type TurnEnd = {
+export type TurnEnd = (PromptOutcome & {
     readonly type: 'turn-end';
-    readonly stopReason: StopReason;
-} | {
+}) | {
     readonly type: 'failure';
     readonly error: Error;
 };

package/lib/session/turn-queue.js

@@ -93,8 +93,8 @@ export class TurnQueue {
         this.running = true;
         this.ended = Promise.withResolvers();
         this.lifetime = new AbortController();
-        target.transport.prompt(target.acpSessionId, next.blocks).then((stopReason) => {
-            this.end({ type: 'turn-end', stopReason });
+        target.transport.prompt(target.acpSessionId, next.blocks).then((outcome) => {
+            this.end({ type: 'turn-end', ...outcome });
         }, (error) => {
             this.end({ type: 'failure', error: error instanceof Error ? error : new Error(String(error)) });
         });

package/lib/session/turn-usage.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Token usage a CLI reports for its turn, restated in the harness's terms so the
+ * conversation shows speed and cache hits for CLI sessions too.
+ *
+ * ACP's `PromptResponse.usage` and the harness's `TokenUsage` agree that input
+ * excludes cache reads (Claude Code reports Anthropic's split as is; Codex
+ * subtracts cached input before reporting), so the counts map one to one.
+ * @module dsh-ccgui/session/turn-usage
+ */
+import type { Usage } from '@agentclientprotocol/sdk';
+import type { TokenUsage } from '@deepseek-ai/dsh-llm';
+import type { StepResult } from './outcomes.ts';
+/**
+ * @param usage - what the CLI reported with its turn's stop reason.
+ * @returns the harness's usage, or undefined when the CLI reported none it can use.
+ */
+export declare function toTokenUsage(usage: Usage | null | undefined): TokenUsage | undefined;
+/**
+ * Combine the usage of CLI turns that end within one harness step, as queued steering does.
+ * The total stays only when both turns state one, because it must be exact.
+ * @returns the combined usage, or undefined when neither turn reported any.
+ */
+export declare function addUsage(a: TokenUsage | undefined, b: TokenUsage | undefined): TokenUsage | undefined;
+/**
+ * The harness expects usage right before the terminal finish and nothing after it.
+ * @param step - a step whose last chunk is its finish.
+ * @param usage - the usage to report, if any.
+ * @returns the step with its usage in place.
+ */
+export declare function withUsage(step: StepResult, usage: TokenUsage | undefined): StepResult;

package/lib/session/turn-usage.js

@@ -0,0 +1,73 @@
+/**
+ * Token usage a CLI reports for its turn, restated in the harness's terms so the
+ * conversation shows speed and cache hits for CLI sessions too.
+ *
+ * ACP's `PromptResponse.usage` and the harness's `TokenUsage` agree that input
+ * excludes cache reads (Claude Code reports Anthropic's split as is; Codex
+ * subtracts cached input before reporting), so the counts map one to one.
+ * @module dsh-ccgui/session/turn-usage
+ */
+/** Counts that are summed across turns whenever either turn reports them. */
+const SUMMED_COUNTS = ['cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens'];
+function isCount(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+/** Omitting a count, rather than setting it to undefined, keeps "not reported" distinct from zero. */
+function optionalCounts(counts) {
+    return Object.fromEntries(Object.entries(counts).filter(([, value]) => isCount(value)));
+}
+/**
+ * @param usage - what the CLI reported with its turn's stop reason.
+ * @returns the harness's usage, or undefined when the CLI reported none it can use.
+ */
+export function toTokenUsage(usage) {
+    if (usage === null || usage === undefined)
+        return undefined;
+    const { inputTokens, outputTokens } = usage;
+    if (!isCount(inputTokens) || !isCount(outputTokens))
+        return undefined;
+    return {
+        inputTokens,
+        outputTokens,
+        ...optionalCounts({
+            totalTokens: usage.totalTokens,
+            cacheReadTokens: usage.cachedReadTokens,
+            cacheWriteTokens: usage.cachedWriteTokens,
+            reasoningTokens: usage.thoughtTokens,
+        }),
+    };
+}
+/**
+ * Combine the usage of CLI turns that end within one harness step, as queued steering does.
+ * The total stays only when both turns state one, because it must be exact.
+ * @returns the combined usage, or undefined when neither turn reported any.
+ */
+export function addUsage(a, b) {
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    const summed = SUMMED_COUNTS.flatMap((key) => a[key] === undefined && b[key] === undefined ? [] : [[key, (a[key] ?? 0) + (b[key] ?? 0)]]);
+    return {
+        inputTokens: a.inputTokens + b.inputTokens,
+        outputTokens: a.outputTokens + b.outputTokens,
+        ...(a.totalTokens === undefined || b.totalTokens === undefined
+            ? {}
+            : { totalTokens: a.totalTokens + b.totalTokens }),
+        ...Object.fromEntries(summed),
+    };
+}
+/**
+ * The harness expects usage right before the terminal finish and nothing after it.
+ * @param step - a step whose last chunk is its finish.
+ * @param usage - the usage to report, if any.
+ * @returns the step with its usage in place.
+ */
+export function withUsage(step, usage) {
+    if (usage === undefined)
+        return step;
+    return {
+        ...step,
+        chunks: [...step.chunks.slice(0, -1), { type: 'usage', usage }, ...step.chunks.slice(-1)],
+    };
+}

package/lib/stdio-transport.js

@@ -124,8 +124,8 @@ function sessionOperations(agent, untilClosed) {
             await untilClosed(agent.request(session.close, { sessionId }));
         },
         prompt: async (sessionId, blocks) => {
-            const { stopReason } = await untilClosed(agent.request(session.prompt, { sessionId, prompt: [...blocks] }));
-            return stopReason;
+            const { stopReason, usage } = await untilClosed(agent.request(session.prompt, { sessionId, prompt: [...blocks] }));
+            return { stopReason, usage };
         },
         cancel: (sessionId) => {
             // Best effort: if the process is already gone, `closed` has reported it.

package/lib/transport.d.ts

@@ -2,7 +2,7 @@
  * The ACP operations a CLI session needs, separated from process and SDK details.
  * @module dsh-ccgui/transport
  */
-import type { ContentBlock, InitializeResponse, RequestPermissionRequest, RequestPermissionResponse, SessionConfigOption, SessionUpdate, StopReason } from '@agentclientprotocol/sdk';
+import type { ContentBlock, InitializeResponse, RequestPermissionRequest, RequestPermissionResponse, SessionConfigOption, SessionUpdate, StopReason, Usage } from '@agentclientprotocol/sdk';
 /** Callbacks from the CLI to its session. */
 export interface TransportHandlers {
     /** One `session/update` notification. */
@@ -17,6 +17,12 @@ export interface SessionInfo {
     readonly sessionId: string;
     readonly configOptions?: readonly SessionConfigOption[] | null | undefined;
 }
+/** How a CLI turn ended, as the CLI reported it. */
+export interface PromptOutcome {
+    readonly stopReason: StopReason;
+    /** Token usage for the turn; many CLIs do not report it. */
+    readonly usage?: Usage | null | undefined;
+}
 /** Client side of one ACP connection. */
 export interface AcpTransport {
     initialize(): Promise<InitializeResponse>;
@@ -28,7 +34,7 @@ export interface AcpTransport {
     deleteSession(sessionId: string): Promise<void>;
     closeSession(sessionId: string): Promise<void>;
     /** Resolves when the whole CLI turn ends, however many tools it ran. */
-    prompt(sessionId: string, blocks: readonly ContentBlock[]): Promise<StopReason>;
+    prompt(sessionId: string, blocks: readonly ContentBlock[]): Promise<PromptOutcome>;
     cancel(sessionId: string): void;
     /** Stops the CLI. `force` skips the wait for it to exit by itself. */
     dispose(force?: boolean): Promise<void>;

package/lib/windows-command.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Turns a configured command into one Windows can start without a shell. The harness spawns
+ * with CreateProcess and never through `cmd.exe`, which finds only `.exe` and `.com` files by
+ * bare name and, since Node's fix for CVE-2024-27980, refuses `.cmd` and `.bat` outright. Yet
+ * `npx`, `codebuddy`, `opencode` and most CLIs installed through a package manager are `.cmd`
+ * shims on Windows.
+ *
+ * Wrapping the shim in `cmd.exe /c` is not an option: the spawn seam has no verbatim-argument
+ * switch, so Node's quoting of the command line would break cmd's own parsing. Instead, the
+ * shim is read for the script it starts, and that script is run with the shim's interpreter
+ * directly, the way the shim would have run it. The interpreter is often not node: npm writes
+ * `bun` into the shim of a package whose bin has a bun shebang, such as OMP CLI.
+ * @module dsh-ccgui/windows-command
+ */
+import type { CliCommand } from './npx-cache.ts';
+/** What the lookup needs from the file system; separate so tests need not run on Windows. */
+export interface FileProbe {
+    readonly isFile: (path: string) => boolean;
+    readonly read: (path: string) => string | undefined;
+}
+/** Where to look. */
+export interface WindowsLookup {
+    readonly path: string | undefined;
+    readonly pathExt: string | undefined;
+    readonly files: FileProbe;
+}
+/**
+ * Resolve a command the way a Windows shell would, without the shell.
+ * @param command - the command as configured.
+ * @param lookup - where to look.
+ * @returns the command with a program CreateProcess can start; unchanged when the program is
+ *   not found, so the spawn reports it as missing.
+ * @throws Error when the program is a batch file that only a shell could run.
+ */
+export declare function resolveWindowsCommand(command: CliCommand, lookup: WindowsLookup): CliCommand;
+/**
+ * On Windows, resolve the command against the real file system; elsewhere, leave it alone.
+ * @param command - the command as configured.
+ * @param platform - the current platform.
+ * @param env - the process environment, for PATH and PATHEXT.
+ * @returns the command to spawn.
+ */
+export declare function startOnWindows(command: CliCommand, platform: NodeJS.Platform, env: Readonly<Record<string, string | undefined>>): CliCommand;