dsh-ccgui 0.0.0-stage → 1.0.0

package/lib/async-queue.js

@@ -0,0 +1,55 @@
+/**
+ * Single-reader async queue. CLI output arrives on notification callbacks while
+ * the harness pulls it from an async generator, and a step can stop reading with
+ * events still buffered for the next step.
+ * @module dsh-ccgui/async-queue
+ */
+/** FIFO buffer with one abortable waiting reader. */
+export class AsyncQueue {
+    items = [];
+    waiter;
+    /** Number of buffered items. */
+    get size() {
+        return this.items.length;
+    }
+    /**
+     * Hand an item to the waiting reader, or buffer it.
+     * @param item - the item to deliver.
+     */
+    push(item) {
+        const waiter = this.waiter;
+        if (waiter === undefined) {
+            this.items = [...this.items, item];
+            return;
+        }
+        this.waiter = undefined;
+        waiter.dispose();
+        waiter.resolve(item);
+    }
+    /**
+     * Read the next item, waiting if necessary. Aborting leaves buffered items in place.
+     * @param signal - optional cancellation for this read.
+     * @returns the next item.
+     */
+    next(signal) {
+        if (signal?.aborted)
+            return Promise.reject(signal.reason);
+        const [first, ...rest] = this.items;
+        if (this.items.length > 0) {
+            this.items = rest;
+            return Promise.resolve(first);
+        }
+        const { promise, resolve, reject } = Promise.withResolvers();
+        const onAbort = () => {
+            this.waiter = undefined;
+            reject(signal?.reason);
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+        this.waiter = { resolve, dispose: () => signal?.removeEventListener('abort', onAbort) };
+        return promise;
+    }
+    /** Drop all buffered items. */
+    clear() {
+        this.items = [];
+    }
+}

package/lib/cli-session.d.ts

@@ -0,0 +1,99 @@
+/**
+ * One harness session's live CLI session. The harness thinks in steps, each one
+ * model request plus its tools; a CLI thinks in turns that run many tools before
+ * `session/prompt` returns. This class holds a CLI turn open across harness steps:
+ * a step ends at every tool call, the mirror tool waits for the CLI's result, and
+ * the next step resumes reading the same turn.
+ * @module dsh-ccgui/cli-session
+ */
+import type { StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { AskPermission } from './session/drive-tool.ts';
+import type { CliSessionOptions, StreamRequest } from './session/types.ts';
+import type { ToolOutcome } from './tool-record.ts';
+export type { AskPermission, PermissionAsk } from './session/drive-tool.ts';
+export type { CliSessionOptions, StreamRequest } from './session/types.ts';
+/** Live bridge between one harness session and one CLI session. */
+export declare class CliSession {
+    private readonly options;
+    private readonly events;
+    private readonly label;
+    private readonly startTimeoutMs;
+    private readonly tools;
+    private readonly permissions;
+    private readonly model;
+    private readonly turns;
+    private seen;
+    private transport;
+    private started;
+    private acpSessionId;
+    /** Whether the CLI declared image support when it connected. */
+    private acceptsImages;
+    /** The CLI cannot see this conversation, and the user has not been told yet. */
+    private owesFreshNotice;
+    private failure;
+    private disposeRequested;
+    /** This dead session holds user input it can no longer deliver. */
+    private owesInput;
+    constructor(options: CliSessionOptions);
+    /** Whether this session can no longer run turns. */
+    get dead(): boolean;
+    /**
+     * Whether a dead session can be replaced. While its failure is unread it stays,
+     * so the next step reports why the CLI died instead of quietly starting another.
+     */
+    get replaceable(): boolean;
+    /** Ids of the user messages this session or its predecessors sent to a CLI. */
+    get sentMessageIds(): ReadonlySet<string>;
+    /**
+     * Run one harness step: send any new user input, then read until the next tool
+     * call or the end of the CLI turn.
+     * @param request - the derived history and cancellation for this step.
+     * @yields the step's stream chunks, ending with `finish`.
+     */
+    stream(request: StreamRequest): AsyncGenerator<StreamChunk>;
+    /**
+     * Wait for the CLI's result of a published call. This is the body of the mirror
+     * tool. It answers every open permission request, not only its own: a parent call
+     * can be waiting on a child whose mirror cannot start until this one returns.
+     * @param callId - the call id from the harness log.
+     * @param ask - asks the harness about a blocked call.
+     * @param signal - cancellation; aborting abandons the CLI turn.
+     * @returns the finished call's outcome.
+     */
+    waitForTool(callId: string, ask: AskPermission, signal?: AbortSignal): Promise<ToolOutcome>;
+    /**
+     * Stop whatever the CLI is doing for a harness turn that is over. The harness can
+     * end a turn between steps, when no stream or mirror is there to notice, so this
+     * is driven by the end of the harness turn. It does nothing on an idle session.
+     */
+    abandonTurn(): void;
+    /**
+     * Stop the CLI process and fail anything still waiting on it.
+     * @param force - skip the wait for the CLI to exit by itself.
+     * @param reason - why it is being stopped, shown to a turn it cuts off.
+     */
+    dispose(force?: boolean, reason?: string): Promise<void>;
+    private prepareStep;
+    private promptBlocks;
+    private applyModel;
+    /** Steering still in the queue is not sent yet, but must not be queued a second time. */
+    private unsentInput;
+    private ensureStarted;
+    private connectInTime;
+    private connect;
+    private pushFreshSessionNotice;
+    private handleUpdate;
+    private handlePermission;
+    private handleClosed;
+    private settleFailure;
+    /**
+     * A mirror can be denied by a policy or skipped by a stop before it runs, leaving
+     * the CLI blocked on an answer nobody would give. By the next step the harness has
+     * finished with the call, so a request still open for it is refused.
+     */
+    private rejectSkippedMirrors;
+    private hasWork;
+    private replayFields;
+    private readStep;
+    private nextEvent;
+}

package/lib/cli-session.js

@@ -0,0 +1,384 @@
+/**
+ * One harness session's live CLI session. The harness thinks in steps, each one
+ * model request plus its tools; a CLI thinks in turns that run many tools before
+ * `session/prompt` returns. This class holds a CLI turn open across harness steps:
+ * a step ends at every tool call, the mirror tool waits for the CLI's result, and
+ * the next step resumes reading the same turn.
+ * @module dsh-ccgui/cli-session
+ */
+import { randomUUID } from 'node:crypto';
+import { LlmError } from '@deepseek-ai/dsh-llm';
+import { abortable } from "./abortable.js";
+import { AsyncQueue } from "./async-queue.js";
+import { nativeReplayState, readNativeSession, unseenUserInput } from "./request-input.js";
+import { toPromptBlocks } from "./prompt-images.js";
+import { openSession, withinStartTimeout } from "./session/connect.js";
+import { driveTool } from "./session/drive-tool.js";
+import { ModelState } from "./session/model-state.js";
+import { errorMessage } from "./session/outcomes.js";
+import { CANCELLED, PermissionQueue } from "./session/permission-queue.js";
+import { readStep } from "./session/read-step.js";
+import { ToolMirror } from "./session/tool-mirror.js";
+import { TurnQueue } from "./session/turn-queue.js";
+const DEFAULT_CANCEL_GRACE_MS = 10_000;
+const DEFAULT_START_TIMEOUT_MS = 120_000;
+const DEFAULT_TOOL_SETTLE_MS = 1_000;
+const NEVER_ABORTED = new AbortController().signal;
+/** Live bridge between one harness session and one CLI session. */
+export class CliSession {
+    options;
+    events = new AsyncQueue();
+    label;
+    startTimeoutMs;
+    tools;
+    permissions = new PermissionQueue();
+    model;
+    turns;
+    seen;
+    transport;
+    started;
+    acpSessionId;
+    /** Whether the CLI declared image support when it connected. */
+    acceptsImages = false;
+    /** The CLI cannot see this conversation, and the user has not been told yet. */
+    owesFreshNotice = false;
+    failure;
+    disposeRequested = false;
+    /** This dead session holds user input it can no longer deliver. */
+    owesInput = false;
+    constructor(options) {
+        this.options = options;
+        this.label = options.label;
+        this.startTimeoutMs = options.startTimeoutMs ?? DEFAULT_START_TIMEOUT_MS;
+        this.seen = options.sentMessageIds ?? new Set();
+        this.model = new ModelState(options.knownModels);
+        this.tools = new ToolMirror({
+            mintCallId: options.mintCallId ?? (() => `cli-${randomUUID()}`),
+            settleMs: options.toolSettleMs ?? DEFAULT_TOOL_SETTLE_MS,
+            onReady: (acpId) => {
+                this.events.push({ type: 'tool-ready', acpId });
+            },
+        });
+        this.turns = new TurnQueue({
+            target: () => {
+                const { transport, acpSessionId } = this;
+                if (this.failure !== undefined || transport === undefined || acpSessionId === undefined)
+                    return undefined;
+                return { transport, acpSessionId };
+            },
+            onSend: (prompt) => {
+                this.seen = new Set([...this.seen, ...prompt.ids]);
+            },
+            onEnd: (event, wasCancelling) => {
+                this.tools.failOpen();
+                this.permissions.cancelAll();
+                if (!wasCancelling)
+                    this.events.push(event);
+            },
+            onCancelTimeout: () => {
+                this.dispose(true).catch((error) => this.options.onError?.(error));
+            },
+            cancelGraceMs: options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS,
+        });
+    }
+    /** Whether this session can no longer run turns. */
+    get dead() {
+        return this.failure !== undefined;
+    }
+    /**
+     * Whether a dead session can be replaced. While its failure is unread it stays,
+     * so the next step reports why the CLI died instead of quietly starting another.
+     */
+    get replaceable() {
+        return this.dead && this.events.size === 0;
+    }
+    /** Ids of the user messages this session or its predecessors sent to a CLI. */
+    get sentMessageIds() {
+        return this.seen;
+    }
+    /**
+     * Run one harness step: send any new user input, then read until the next tool
+     * call or the end of the CLI turn.
+     * @param request - the derived history and cancellation for this step.
+     * @yields the step's stream chunks, ending with `finish`.
+     */
+    async *stream(request) {
+        const { signal } = request;
+        signal?.throwIfAborted();
+        if (this.failure === undefined) {
+            await this.prepareStep(request);
+            yield* this.readStep(signal);
+            return;
+        }
+        if (this.events.size === 0)
+            throw this.failure;
+        // The turn being read may look finished. If this request's input never reached
+        // the CLI, a clean finish would swallow the message with nothing on screen. This
+        // is remembered because a tool call read here moves the message out of the window
+        // `unseenUserInput` looks at, and the next step could no longer tell.
+        this.owesInput ||= this.unsentInput(request).blocks.length > 0;
+        yield* this.readStep(signal);
+    }
+    /**
+     * Wait for the CLI's result of a published call. This is the body of the mirror
+     * tool. It answers every open permission request, not only its own: a parent call
+     * can be waiting on a child whose mirror cannot start until this one returns.
+     * @param callId - the call id from the harness log.
+     * @param ask - asks the harness about a blocked call.
+     * @param signal - cancellation; aborting abandons the CLI turn.
+     * @returns the finished call's outcome.
+     */
+    async waitForTool(callId, ask, signal) {
+        const acpId = this.tools.acpIdFor(callId);
+        if (acpId === undefined)
+            throw new Error(`ccgui: 调用 ${callId} 不是这个 CLI 会话发出的`);
+        this.tools.startMirror(acpId);
+        try {
+            const context = {
+                tools: this.tools,
+                permissions: this.permissions,
+                label: this.label,
+                turnSignal: () => this.turns.signal,
+            };
+            return await driveTool(context, { acpId, callId }, ask, signal ?? NEVER_ABORTED);
+        }
+        catch (error) {
+            this.abandonTurn();
+            throw error;
+        }
+        finally {
+            this.tools.forget(acpId);
+        }
+    }
+    /**
+     * Stop whatever the CLI is doing for a harness turn that is over. The harness can
+     * end a turn between steps, when no stream or mirror is there to notice, so this
+     * is driven by the end of the harness turn. It does nothing on an idle session.
+     */
+    abandonTurn() {
+        this.events.clear();
+        this.turns.clearPending();
+        this.permissions.cancelAll();
+        this.tools.dropUnmirrored();
+        const { acpSessionId } = this;
+        if (this.turns.active && !this.turns.cancelling && acpSessionId !== undefined) {
+            this.turns.beginCancel(() => this.transport?.cancel(acpSessionId));
+        }
+        this.turns.abortLifetime();
+        this.tools.failOpen();
+    }
+    /**
+     * Stop the CLI process and fail anything still waiting on it.
+     * @param force - skip the wait for the CLI to exit by itself.
+     * @param reason - why it is being stopped, shown to a turn it cuts off.
+     */
+    async dispose(force = false, reason) {
+        this.disposeRequested = true;
+        this.failure ??= new LlmError(reason === undefined ? `${this.label} 会话已关闭。` : `${this.label} 已停止：${reason}`, 'CLI_START_FAILED');
+        this.settleFailure(this.failure);
+        await this.transport?.dispose(force);
+    }
+    async prepareStep(request) {
+        const { messages, signal } = request;
+        this.rejectSkippedMirrors();
+        await abortable(this.ensureStarted(messages), signal);
+        if (this.turns.cancelling) {
+            await abortable(this.turns.untilEnded(), signal);
+            if (this.failure !== undefined) {
+                throw new LlmError(`${this.label} 没有响应取消，已被结束。这条消息没有发送，请重新发送。`, 'CLI_PROMPT_FAILED');
+            }
+        }
+        // The CLI can exit during either wait above, and a prompt queued on a dead
+        // session would never go out, leaving this step waiting forever.
+        if (this.failure !== undefined)
+            throw this.failure;
+        const input = this.unsentInput(request);
+        if (input.blocks.length === 0)
+            return;
+        // Read before anything is committed, so a failed read leaves the step as if never run.
+        const blocks = await this.promptBlocks(input, signal);
+        // Steering joins a turn already under way, so only a fresh prompt can switch.
+        if (!this.turns.busy) {
+            await this.applyModel(request.model, signal);
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition, @typescript-eslint/only-throw-error -- a callback may set failure during the await, which narrowing cannot see
+            if (this.failure !== undefined)
+                throw this.failure;
+        }
+        // Told only now because a failed switch ends the harness turn, which clears the queue,
+        // and the user still needs to hear this when they send again.
+        if (this.owesFreshNotice) {
+            this.owesFreshNotice = false;
+            this.pushFreshSessionNotice();
+        }
+        this.turns.enqueue({ ids: input.ids, blocks });
+    }
+    async promptBlocks(input, signal) {
+        const resolution = { acceptsImages: this.acceptsImages, readImage: this.options.readImage };
+        const blocks = await abortable(toPromptBlocks(input.blocks, resolution, signal), signal);
+        // The CLI can exit while the images are read; a prompt queued then would never go out.
+        if (this.failure !== undefined)
+            throw this.failure;
+        return blocks;
+    }
+    async applyModel(model, signal) {
+        const { transport, acpSessionId, label } = this;
+        if (transport === undefined || acpSessionId === undefined)
+            return;
+        await this.model.apply(model, { transport, acpSessionId, label }, signal);
+    }
+    /** Steering still in the queue is not sent yet, but must not be queued a second time. */
+    unsentInput({ messages, currentTurnMessageIds }) {
+        const handled = new Set([...this.seen, ...this.turns.queuedIds]);
+        return unseenUserInput(messages, handled, currentTurnMessageIds);
+    }
+    ensureStarted(messages) {
+        if (this.started !== undefined)
+            return this.started;
+        // A conversation the new CLI session never saw: a replacement process, a fork, or
+        // a session that started on another model. The user should know it starts blank.
+        const startsBlind = this.seen.size > 0 || messages.some((message) => message.role === 'assistant');
+        const nativeSessionId = readNativeSession(messages, this.options.dshSessionId, this.options.provider);
+        this.started = this.connectInTime(nativeSessionId, startsBlind).catch((error) => {
+            // Being stopped during startup is not a startup failure, and needs no install hint.
+            const failure = this.disposeRequested && this.failure !== undefined
+                ? this.failure
+                : new LlmError(`无法启动 ${this.label}：${errorMessage(error)}。请确认它已安装并完成登录。`, 'CLI_START_FAILED', { cause: error });
+            this.failure = failure;
+            this.transport?.dispose(true).catch((disposeError) => this.options.onError?.(disposeError));
+            throw failure;
+        });
+        // An aborted step stops waiting for this; the rejection must not go unobserved.
+        this.started.catch(() => {
+            /* whoever awaits this.started handles the rejection */
+        });
+        return this.started;
+    }
+    connectInTime(nativeSessionId, startsBlind) {
+        return withinStartTimeout(() => this.connect(nativeSessionId, startsBlind), this.startTimeoutMs);
+    }
+    async connect(nativeSessionId, startsBlind) {
+        await this.options.after;
+        // The registry no longer holds a session stopped during that wait, so a CLI
+        // started now would have nobody to stop it.
+        if (this.failure !== undefined)
+            throw this.failure;
+        const { acpSessionId, reattachFailed, acceptsImages } = await openSession({
+            openTransport: this.options.openTransport,
+            handlers: {
+                onUpdate: (update) => this.handleUpdate(update),
+                onPermission: (request) => this.handlePermission(request),
+                onClosed: (error) => this.handleClosed(error),
+            },
+            cwd: this.options.cwd,
+            nativeSessionId,
+            model: this.model,
+            onTransport: (transport) => {
+                this.transport = transport;
+            },
+            onError: this.options.onError,
+        });
+        this.acpSessionId = acpSessionId;
+        this.acceptsImages = acceptsImages;
+        this.owesFreshNotice = reattachFailed || (nativeSessionId === undefined && startsBlind);
+    }
+    pushFreshSessionNotice() {
+        this.events.push({
+            type: 'text',
+            text: `（${this.label} 无法恢复之前的会话，已开始新会话，它不记得之前的内容。）\n\n`,
+        });
+    }
+    handleUpdate(update) {
+        if (update.sessionUpdate === 'config_option_update') {
+            this.model.observe(update.configOptions);
+            return;
+        }
+        // Outside a turn nothing is reading, and stale output would surface in the next
+        // turn. While cancelling, the user has already left this turn behind.
+        if (!this.turns.active || this.turns.cancelling)
+            return;
+        switch (update.sessionUpdate) {
+            case 'agent_message_chunk':
+            case 'agent_thought_chunk':
+                if (update.content.type === 'text') {
+                    const type = update.sessionUpdate === 'agent_message_chunk' ? 'text' : 'reasoning';
+                    this.events.push({ type, text: update.content.text });
+                }
+                return;
+            case 'tool_call':
+                this.tools.reopen(update.toolCallId);
+                this.tools.apply(update, false);
+                return;
+            case 'tool_call_update':
+                if (!this.tools.isClaimed(update.toolCallId))
+                    this.tools.apply(update, false);
+                return;
+            default:
+        }
+    }
+    handlePermission(request) {
+        if (!this.turns.active || this.turns.cancelling)
+            return Promise.resolve(CANCELLED);
+        const { toolCall, options } = request;
+        const { promise, resolve } = Promise.withResolvers();
+        this.permissions.add({ acpId: toolCall.toolCallId, options, resolve });
+        // Its mirror may have been skipped earlier. Asking again reopens the call, and
+        // its later updates must reach the new mirror.
+        this.tools.reopen(toolCall.toolCallId);
+        this.tools.apply(toolCall, true);
+        return promise;
+    }
+    handleClosed(error) {
+        this.failure ??= new LlmError(`${this.label} 已退出：${error.message}`, 'CLI_PROMPT_FAILED', { cause: error });
+        this.settleFailure(this.failure);
+    }
+    settleFailure(failure) {
+        this.turns.clearPending();
+        this.turns.end({ type: 'failure', error: failure });
+        this.tools.failOpen();
+        this.permissions.cancelAll();
+    }
+    /**
+     * A mirror can be denied by a policy or skipped by a stop before it runs, leaving
+     * the CLI blocked on an answer nobody would give. By the next step the harness has
+     * finished with the call, so a request still open for it is refused.
+     */
+    rejectSkippedMirrors() {
+        for (const acpId of this.tools.skippedMirrors()) {
+            this.permissions.rejectFor(acpId);
+            this.tools.forget(acpId);
+        }
+    }
+    hasWork() {
+        return this.turns.busy || this.events.size > 0;
+    }
+    replayFields() {
+        return this.acpSessionId === undefined
+            ? {}
+            : { replayState: nativeReplayState(this.acpSessionId, this.options.dshSessionId) };
+    }
+    readStep(signal) {
+        return readStep({
+            label: this.label,
+            nextEvent: (stepSignal) => this.nextEvent(stepSignal),
+            hasWork: () => this.hasWork(),
+            owesInput: () => this.owesInput,
+            failure: () => this.failure,
+            handOff: (acpId) => {
+                const record = this.tools.get(acpId);
+                if (record !== undefined)
+                    this.tools.handOff(acpId);
+                return record;
+            },
+            replay: () => this.replayFields(),
+        }, signal);
+    }
+    async nextEvent(signal) {
+        try {
+            return await this.events.next(signal);
+        }
+        catch (error) {
+            this.abandonTurn();
+            throw error;
+        }
+    }
+}

package/lib/cli-tool.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The mirror tool. A CLI runs its tools itself, but the harness can only show and
+ * log a call that goes through a registered tool. This tool's body runs nothing:
+ * it waits for the CLI to report what happened.
+ * @module dsh-ccgui/cli-tool
+ */
+import type { ToolDefinition, ToolRunContext } from '@deepseek-ai/dsh-tools';
+import type { ToolOutcome } from './tool-record.ts';
+/** What the tool needs from the bridge. */
+export interface CliToolDeps {
+    waitForTool(exec: ToolRunContext): Promise<ToolOutcome>;
+}
+/**
+ * Build the tool definition.
+ * @param deps - the bridge.
+ * @returns the `cli_tool` definition.
+ */
+export declare function createCliTool(deps: CliToolDeps): ToolDefinition;

package/lib/cli-tool.js

@@ -0,0 +1,101 @@
+/**
+ * The mirror tool. A CLI runs its tools itself, but the harness can only show and
+ * log a call that goes through a registered tool. This tool's body runs nothing:
+ * it waits for the CLI to report what happened.
+ * @module dsh-ccgui/cli-tool
+ */
+import { HarnessError } from '@deepseek-ai/dsh-llm';
+import { defineTool, TOOL_ABORTED } from '@deepseek-ai/dsh-tools';
+import { CLI_TOOL_NAME } from "./constants.js";
+const KNOWN_KINDS = new Set(['read', 'edit', 'delete', 'move', 'search', 'execute', 'fetch']);
+const DIFF_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        path: { type: 'string', required: true },
+        oldText: { oneOf: [{ type: 'string' }, { type: 'null' }], required: true },
+        newText: { type: 'string', required: true },
+    },
+};
+function toLocations(paths) {
+    return (paths ?? []).map((path) => ({ path }));
+}
+function presentCall(args) {
+    const { title, kind, command, input, diffs, locations } = args;
+    if (command !== undefined) {
+        return { card: 'terminal', title: command, ...(title === command ? {} : { description: title }) };
+    }
+    if (diffs !== undefined && diffs.length > 0) {
+        return { card: 'diff', title, diffs: [...diffs], locations: toLocations(locations) };
+    }
+    return {
+        card: 'generic',
+        title,
+        kind: (KNOWN_KINDS.has(kind) ? kind : 'other'),
+        ...(input === undefined ? {} : { rawInput: input }),
+        ...(locations === undefined ? {} : { locations: toLocations(locations) }),
+    };
+}
+function resultText(result) {
+    return result.content.flatMap((block) => (block.type === 'text' ? [block.text] : [])).join('\n');
+}
+function presentResult(args, result) {
+    if (result.isError)
+        return undefined;
+    if (args.command !== undefined)
+        return { card: 'terminal', output: resultText(result) };
+    const diffs = result.meta?.diffs;
+    return diffs !== undefined && diffs.length > 0 ? { card: 'diff', diffs } : undefined;
+}
+/** The harness aborts with a plain object, which would be logged as `[object Object]`. */
+async function waitForOutcome(deps, exec) {
+    try {
+        return await deps.waitForTool(exec);
+    }
+    catch (error) {
+        if (!exec.signal.aborted)
+            throw error;
+        const aborted = new HarnessError('tool call aborted', TOOL_ABORTED, { cause: error });
+        aborted.name = 'AbortError';
+        throw aborted;
+    }
+}
+/**
+ * Build the tool definition.
+ * @param deps - the bridge.
+ * @returns the `cli_tool` definition.
+ */
+export function createCliTool(deps) {
+    return defineTool({
+        name: CLI_TOOL_NAME,
+        description: 'Records a tool call made by an external CLI. It runs nothing itself.',
+        parameters: {
+            title: { type: 'string', required: true, description: 'What the CLI says this call does.' },
+            kind: { type: 'string', required: true, description: 'The ACP tool kind.' },
+            command: { type: 'string', description: 'The shell command, for an execute call.' },
+            input: { type: 'json', description: 'The raw input the CLI reported.' },
+            diffs: { type: 'array', items: DIFF_SCHEMA },
+            locations: { type: 'array', items: { type: 'string' } },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    text: { type: 'string', required: true },
+                    diffs: { type: 'array', items: DIFF_SCHEMA, required: true },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: value.text }],
+            presentationMeta: (_args, value) => ({ diffs: value.diffs }),
+        },
+        async execute(_args, exec) {
+            const outcome = await waitForOutcome(deps, exec);
+            if (outcome.failed)
+                throw new Error(outcome.text);
+            return { text: outcome.text, diffs: outcome.diffs.map((diff) => ({ ...diff })) };
+        },
+        presentCall: (args) => presentCall(args),
+        presentResult: (args, result) => presentResult(args, result),
+    });
+}