dsh-ccgui 0.0.0-stage → 1.0.0

package/lib/model-probe.js

@@ -0,0 +1,91 @@
+/**
+ * Asks a CLI which models it offers. ACP only reports them on a session, so this
+ * opens one and removes it again. It sends no prompt, so no model is called.
+ * @module dsh-ccgui/model-probe
+ */
+import { setTimeout as delay } from 'node:timers/promises';
+import { abortable } from "./abortable.js";
+import { readModelList } from "./model-options.js";
+const IGNORING_HANDLERS = {
+    onUpdate: () => {
+        /* a probe only reads the model list */
+    },
+    onPermission: () => Promise.resolve({ outcome: { outcome: 'cancelled' } }),
+    onClosed: () => {
+        /* the caller's dispose handles the close */
+    },
+};
+const CLEANUP_LIMIT_MS = 3_000;
+/**
+ * Otherwise every probe would leave an empty session in the CLI's history. Failing to
+ * clean up does not make the answer any less true, so it gets its own short limit and
+ * can never cost the list already in hand.
+ */
+async function discardSession(transport, sessionId, capabilities, limitMs) {
+    const discarding = capabilities?.delete != null
+        ? transport.deleteSession(sessionId)
+        : capabilities?.close != null
+            ? transport.closeSession(sessionId)
+            : undefined;
+    if (discarding === undefined)
+        return;
+    await Promise.race([
+        discarding.catch(() => {
+            /* a failed cleanup does not change the answer in hand */
+        }),
+        delay(limitMs, undefined, { ref: false }),
+    ]);
+}
+/**
+ * Runs behind the answer, because removing the session takes Pi seconds and exiting takes
+ * Codex as long, with the user watching a menu that could already be filled.
+ */
+async function cleanUp(transport, discard, limitMs, signal) {
+    await abortable(discard(limitMs), signal).catch(() => {
+        /* a failed cleanup does not change the answer in hand */
+    });
+    await transport.dispose(signal?.aborted === true).catch(() => {
+        /* likewise */
+    });
+}
+async function askModels(transport, cwd) {
+    const { agentCapabilities } = await transport.initialize();
+    const { sessionId, configOptions } = await transport.newSession(cwd);
+    return {
+        list: readModelList(configOptions),
+        discard: (limitMs) => discardSession(transport, sessionId, agentCapabilities?.sessionCapabilities, limitMs),
+    };
+}
+/**
+ * Start a CLI just long enough to read its model list.
+ * @param open - starts the CLI.
+ * @param cwd - working directory for the temporary session.
+ * @param timeoutMs - how long to wait, which must allow for a cold `npx` download.
+ * @param signal - stops the CLI at once when the bridge is shutting down.
+ * @returns the model list, or undefined when the CLI offers none.
+ */
+export async function probeModels(open, cwd, timeoutMs, signal) {
+    signal?.throwIfAborted();
+    const transport = open(IGNORING_HANDLERS);
+    const { promise: timedOut, reject } = Promise.withResolvers();
+    const timer = setTimeout(() => {
+        reject(new Error('超时，CLI 没有响应'));
+    }, timeoutMs);
+    const cleanupLimitMs = Math.min(CLEANUP_LIMIT_MS, timeoutMs / 2);
+    try {
+        const { list, discard } = await abortable(Promise.race([askModels(transport, cwd), timedOut]), signal);
+        void cleanUp(transport, discard, cleanupLimitMs, signal).catch(() => {
+            /* background cleanup; nobody to report to */
+        });
+        return list;
+    }
+    catch (error) {
+        await transport.dispose(true).catch(() => {
+            /* the original error is rethrown; a failed dispose must not replace it */
+        });
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/lib/npx-cache.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Starts a version-pinned `npx` package straight from the copy npx already cached. On every
+ * start `npx` first asks the registry about the package, even with that copy at hand, which
+ * measured 4 to 26 seconds here and holds up both the model menu and the first message.
+ *
+ * Its `--prefer-offline` flag skips the question but is not a fix: it fails on a version newer
+ * than the cached metadata, and it reaches the CLI as `npm_config_prefer_offline`, so npm
+ * commands the agent runs in the user's project would quietly see stale metadata.
+ *
+ * Everything here rests on npm's cache layout, so whatever is not plainly there goes to `npx`
+ * as configured. A change on npm's side can only make a start slower, never wrong.
+ * @module dsh-ccgui/npx-cache
+ */
+/** How to start one CLI. */
+export interface CliCommand {
+    readonly argv: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+}
+/** Where to look, and what to build the child's path on. */
+export interface NpxCacheOptions {
+    /** npm's `_npx` directory, or undefined where this cannot work. */
+    readonly npxCache: string | undefined;
+    readonly path: string | undefined;
+}
+/**
+ * Point a command at npx's cached copy of its package, when that is safe.
+ * @param command - the command as configured.
+ * @param options - where to look.
+ * @returns the command to run: the same one unless a cached copy can stand in for it.
+ */
+export declare function startFromNpxCache(command: CliCommand, { npxCache, path }: NpxCacheOptions): CliCommand;
+/**
+ * Locate npx's cache. A cache moved by `.npmrc` is not found, which only means going by `npx`.
+ * @param env - the process environment.
+ * @param home - the user's home directory.
+ * @param platform - the current platform.
+ * @returns the `_npx` directory, or undefined on Windows, whose links need a shell to start.
+ */
+export declare function npxCacheDir(env: Readonly<Record<string, string | undefined>>, home: string, platform: NodeJS.Platform): string | undefined;

package/lib/npx-cache.js

@@ -0,0 +1,97 @@
+/**
+ * Starts a version-pinned `npx` package straight from the copy npx already cached. On every
+ * start `npx` first asks the registry about the package, even with that copy at hand, which
+ * measured 4 to 26 seconds here and holds up both the model menu and the first message.
+ *
+ * Its `--prefer-offline` flag skips the question but is not a fix: it fails on a version newer
+ * than the cached metadata, and it reaches the CLI as `npm_config_prefer_offline`, so npm
+ * commands the agent runs in the user's project would quietly see stale metadata.
+ *
+ * Everything here rests on npm's cache layout, so whatever is not plainly there goes to `npx`
+ * as configured. A change on npm's side can only make a start slower, never wrong.
+ * @module dsh-ccgui/npx-cache
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, delimiter, join } from 'node:path';
+const NPX = 'npx';
+const YES_FLAGS = new Set(['-y', '--yes']);
+const KEY_LENGTH = 16;
+/** Exact versions only: a tag or range means asking the registry, and the name stays inside the cache. */
+const PINNED_SPEC = /^((?:@[a-z0-9~-][a-z0-9._~-]*\/)?[a-z0-9~-][a-z0-9._~-]*)@(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]+)?)$/;
+const isObject = (value) => typeof value === 'object' && value !== null;
+function readPinned([command, ...args]) {
+    if (command !== NPX)
+        return undefined;
+    const [spec, ...rest] = YES_FLAGS.has(args[0] ?? '') ? args.slice(1) : args;
+    const match = PINNED_SPEC.exec(spec ?? '');
+    if (spec === undefined || match === null)
+        return undefined;
+    const [, name, version] = match;
+    return name === undefined || version === undefined ? undefined : { spec, name, version, args: rest };
+}
+function readManifest(path) {
+    try {
+        const manifest = JSON.parse(readFileSync(path, 'utf8'));
+        return isObject(manifest) ? manifest : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Follows npm's own choice in `libnpmexec`, so this runs what `npx` would have run. */
+function binOf(bin, name) {
+    const unscoped = name.replace(/^@[^/]+\//, '');
+    const bins = typeof bin === 'string' ? { [unscoped]: bin } : isObject(bin) ? bin : {};
+    const [first] = Object.keys(bins);
+    if (new Set(Object.values(bins)).size === 1)
+        return first;
+    return unscoped in bins ? unscoped : undefined;
+}
+/** A finished install leaves this lockfile, and only the same version will do. */
+function findCachedBin(npxCache, { spec, name, version }) {
+    const key = createHash('sha512').update(spec).digest('hex').slice(0, KEY_LENGTH);
+    const modules = join(npxCache, key, 'node_modules');
+    if (!existsSync(join(modules, '.package-lock.json')))
+        return undefined;
+    const manifest = readManifest(join(modules, name, 'package.json'));
+    if (manifest?.version !== version)
+        return undefined;
+    const bin = binOf(manifest.bin, name);
+    if (bin === undefined || basename(bin) !== bin)
+        return undefined;
+    const dir = join(modules, '.bin');
+    return existsSync(join(dir, bin)) ? { dir, file: join(dir, bin) } : undefined;
+}
+/**
+ * Point a command at npx's cached copy of its package, when that is safe.
+ * @param command - the command as configured.
+ * @param options - where to look.
+ * @returns the command to run: the same one unless a cached copy can stand in for it.
+ */
+export function startFromNpxCache(command, { npxCache, path }) {
+    if (npxCache === undefined)
+        return command;
+    const pinned = readPinned(command.argv);
+    const found = pinned === undefined ? undefined : findCachedBin(npxCache, pinned);
+    if (pinned === undefined || found === undefined)
+        return command;
+    const inherited = command.env.PATH ?? path;
+    return {
+        argv: [found.file, ...pinned.args],
+        // `npx` puts these on the path too, for a CLI that starts a dependency's command by name.
+        env: { ...command.env, PATH: inherited === undefined ? found.dir : `${found.dir}${delimiter}${inherited}` },
+    };
+}
+/**
+ * Locate npx's cache. A cache moved by `.npmrc` is not found, which only means going by `npx`.
+ * @param env - the process environment.
+ * @param home - the user's home directory.
+ * @param platform - the current platform.
+ * @returns the `_npx` directory, or undefined on Windows, whose links need a shell to start.
+ */
+export function npxCacheDir(env, home, platform) {
+    if (platform === 'win32')
+        return undefined;
+    return join(env.npm_config_cache ?? join(home, '.npm'), '_npx');
+}

package/lib/permission.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Maps a harness approval decision onto the options a CLI offered.
+ * @module dsh-ccgui/permission
+ */
+import type { PermissionOption, RequestPermissionResponse } from '@agentclientprotocol/sdk';
+import type { ApprovalOutcome } from '@deepseek-ai/dsh-user-approval';
+/** The answer for a request nobody will decide on. */
+export declare const CANCELLED: RequestPermissionResponse;
+/**
+ * Answer a CLI permission request. A harness approval covers one operation, so it
+ * never selects `allow_always`: with no one-time option on offer, the safe answer is
+ * no. `unavailable` means nobody could answer and is also a no, which fails closed.
+ * @param outcome - the harness approval decision.
+ * @param options - the options the CLI offered.
+ * @returns the ACP response.
+ */
+export declare function permissionResponse(outcome: ApprovalOutcome, options: readonly PermissionOption[]): RequestPermissionResponse;

package/lib/permission.js

@@ -0,0 +1,34 @@
+/**
+ * Maps a harness approval decision onto the options a CLI offered.
+ * @module dsh-ccgui/permission
+ */
+/** The answer for a request nobody will decide on. */
+export const CANCELLED = { outcome: { outcome: 'cancelled' } };
+function selectFirst(options, kinds) {
+    for (const kind of kinds) {
+        const match = options.find((option) => option.kind === kind);
+        if (match !== undefined)
+            return { outcome: { outcome: 'selected', optionId: match.optionId } };
+    }
+    return undefined;
+}
+/**
+ * Answer a CLI permission request. A harness approval covers one operation, so it
+ * never selects `allow_always`: with no one-time option on offer, the safe answer is
+ * no. `unavailable` means nobody could answer and is also a no, which fails closed.
+ * @param outcome - the harness approval decision.
+ * @param options - the options the CLI offered.
+ * @returns the ACP response.
+ */
+export function permissionResponse(outcome, options) {
+    const reject = selectFirst(options, ['reject_once', 'reject_always']) ?? CANCELLED;
+    switch (outcome) {
+        case 'allowed-once':
+            return selectFirst(options, ['allow_once']) ?? reject;
+        case 'rejected':
+        case 'unavailable':
+            return reject;
+        case 'cancelled':
+            return CANCELLED;
+    }
+}

package/lib/prompt-images.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Turns the images in a user message into what the CLI can take. The harness keeps
+ * images as references to its attachment store; a CLI only understands inline bytes,
+ * so each one is read here, just before the prompt goes out.
+ * @module dsh-ccgui/prompt-images
+ */
+import type { ContentBlock as AcpContentBlock } from '@agentclientprotocol/sdk';
+/**
+ * The fields of the harness's image reference this bridge relies on. The full type
+ * lives in `@deepseek-ai/dsh-attachment`, which the host provides but this package does
+ * not depend on; the reference is passed back to the host untouched.
+ */
+export interface ImageRef {
+    readonly attachmentId: string;
+    readonly mediaType: string;
+    readonly name?: string;
+}
+/** One piece of user input before its images are resolved. */
+export type InputBlock = {
+    readonly type: 'text';
+    readonly text: string;
+} | {
+    readonly type: 'image';
+    readonly ref: ImageRef;
+    readonly offloaded: boolean;
+};
+/** Reads one image's stored bytes. */
+export type ReadImage = (ref: ImageRef, signal?: AbortSignal) => Promise<Uint8Array>;
+/** What resolving images needs to know. */
+export interface ImageResolution {
+    /** The CLI declared `promptCapabilities.image`; ACP forbids sending images otherwise. */
+    readonly acceptsImages: boolean;
+    /** Absent when the harness runs without an attachment service. */
+    readonly readImage?: ReadImage | undefined;
+}
+/**
+ * Resolve user input into ACP prompt blocks, in order.
+ * @param blocks - text and image references from the user's messages.
+ * @param resolution - whether the CLI takes images and how to read them.
+ * @param signal - cancellation for the reads.
+ * @returns the prompt to send.
+ * @throws LlmError when an image cannot be read; sending without it would hide it from the CLI.
+ */
+export declare function toPromptBlocks(blocks: readonly InputBlock[], resolution: ImageResolution, signal?: AbortSignal): Promise<AcpContentBlock[]>;

package/lib/prompt-images.js

@@ -0,0 +1,46 @@
+/**
+ * Turns the images in a user message into what the CLI can take. The harness keeps
+ * images as references to its attachment store; a CLI only understands inline bytes,
+ * so each one is read here, just before the prompt goes out.
+ * @module dsh-ccgui/prompt-images
+ */
+import { LlmError, offloadedImageText, textOnlyImageText } from '@deepseek-ai/dsh-llm';
+function imageLabel(ref) {
+    return ref.name ?? ref.attachmentId;
+}
+async function imageBlock(ref, readImage, signal) {
+    if (readImage === undefined) {
+        throw new LlmError('当前环境没有附件服务，无法把图片发送给 CLI。', 'UNSUPPORTED_CONTENT');
+    }
+    try {
+        const data = await readImage(ref, signal);
+        return { type: 'image', mimeType: ref.mediaType, data: Buffer.from(data).toString('base64') };
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        throw new LlmError(`无法读取图片「${imageLabel(ref)}」，这条消息没有发送。`, 'CLI_PROMPT_FAILED', {
+            cause: error,
+        });
+    }
+}
+function toBlock(block, resolution, signal) {
+    if (block.type === 'text')
+        return Promise.resolve(block);
+    // `ref` is the host's own reference object, so its placeholder texts accept it as is.
+    if (block.offloaded)
+        return Promise.resolve({ type: 'text', text: offloadedImageText(block.ref) });
+    if (!resolution.acceptsImages)
+        return Promise.resolve({ type: 'text', text: textOnlyImageText(block.ref) });
+    return imageBlock(block.ref, resolution.readImage, signal);
+}
+/**
+ * Resolve user input into ACP prompt blocks, in order.
+ * @param blocks - text and image references from the user's messages.
+ * @param resolution - whether the CLI takes images and how to read them.
+ * @param signal - cancellation for the reads.
+ * @returns the prompt to send.
+ * @throws LlmError when an image cannot be read; sending without it would hide it from the CLI.
+ */
+export function toPromptBlocks(blocks, resolution, signal) {
+    return Promise.all(blocks.map((block) => toBlock(block, resolution, signal)));
+}

package/lib/request-input.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Reads what the CLI still needs from a harness model request. The CLI holds its
+ * own conversation, so only new user input and the native session id matter.
+ * @module dsh-ccgui/request-input
+ */
+import type { ReplayEnvelope, RequestMessage } from '@deepseek-ai/dsh-llm';
+import type { InputBlock } from './prompt-images.ts';
+/** User input the CLI has not received yet. */
+export interface UserInput {
+    readonly ids: readonly string[];
+    /** Text and image references; images are read only when the prompt is sent. */
+    readonly blocks: readonly InputBlock[];
+}
+/**
+ * Collect the user input still owed to the CLI: messages after the last assistant or
+ * tool message, from the current turn, not sent yet. A tail ending in a tool result
+ * yields nothing, which is how a continuation step is told apart from a new prompt.
+ * @param messages - the derived request history.
+ * @param seen - ids of messages already sent to the CLI.
+ * @param currentTurn - ids of the user messages in the open turn; omitted, all qualify.
+ * @returns new message ids and their text and image blocks, in conversation order.
+ */
+export declare function unseenUserInput(messages: readonly RequestMessage[], seen: ReadonlySet<string>, currentTurn?: ReadonlySet<string>): UserInput;
+/**
+ * Build the replay state that ties a harness session to its CLI session.
+ * @param acpSessionId - the CLI's session id.
+ * @param dshSessionId - the harness session that owns it.
+ * @returns the envelope carried by `finish` and stored on the assistant message.
+ */
+export declare function nativeReplayState(acpSessionId: string, dshSessionId: string): ReplayEnvelope;
+/**
+ * Find the CLI session to reattach to, from the latest assistant message.
+ * The owner check keeps a fork, which inherits its parent's messages under a new
+ * id, from writing into the parent's CLI session. The provider check is needed because
+ * all CLIs share one adapter, so the harness does not strip another route's replay state,
+ * and a session id means nothing to any other CLI.
+ * @param messages - the derived request history.
+ * @param dshSessionId - the harness session asking.
+ * @param provider - the CLI route asking.
+ * @returns the CLI session id, or undefined when there is none to reuse.
+ */
+export declare function readNativeSession(messages: readonly RequestMessage[], dshSessionId: string, provider: string): string | undefined;

package/lib/request-input.js

@@ -0,0 +1,113 @@
+/**
+ * Reads what the CLI still needs from a harness model request. The CLI holds its
+ * own conversation, so only new user input and the native session id matter.
+ * @module dsh-ccgui/request-input
+ */
+/**
+ * Message sources written by a person. The harness also uses the user role for its
+ * own reminders and instructions; those are meant for its own model, and forwarded
+ * they would start CLI turns nobody asked for.
+ */
+const FORWARDED_KINDS = new Set(['user', 'schedule']);
+/**
+ * Starts the harness's note about a schedule edit. It has the same source kind as a
+ * real reminder and says it needs no action, and this text is the only difference.
+ */
+const SCHEDULE_NOTICE_PREFIX = '[SCHEDULE CHANGE]';
+function messagesAfterLastReply(messages) {
+    const lastReply = messages.findLastIndex((message) => message.role === 'assistant' || message.role === 'tool');
+    return messages.slice(lastReply + 1);
+}
+/**
+ * The reference's type comes from a package this one does not depend on, so its shape
+ * is checked here instead of trusted.
+ */
+function imageRefOf(block) {
+    const { attachment } = block;
+    if (typeof attachment !== 'object' || attachment === null)
+        return undefined;
+    const { attachmentId, mediaType } = attachment;
+    return typeof attachmentId === 'string' && typeof mediaType === 'string' ? attachment : undefined;
+}
+/**
+ * Text and images are what a person writes. Files arrive already turned into text by
+ * the host, and the remaining block kinds belong to model or tool output.
+ */
+function inputBlocks(message) {
+    return message.content.flatMap((block) => {
+        if (block.type === 'text')
+            return [{ type: 'text', text: block.text }];
+        if (block.type === 'image') {
+            const ref = imageRefOf(block);
+            return ref === undefined ? [] : [{ type: 'image', ref, offloaded: block.offloaded === true }];
+        }
+        return [];
+    });
+}
+function isScheduleNotice(message) {
+    const [first] = message.content;
+    return first?.type === 'text' && first.text.startsWith(SCHEDULE_NOTICE_PREFIX);
+}
+function isForwarded(message) {
+    // The agent loop and other producers extend this union; compare it as a plain string.
+    const kind = message.source?.kind;
+    if (message.role !== 'user')
+        return false;
+    if (kind === 'schedule' && isScheduleNotice(message))
+        return false;
+    return kind === undefined || FORWARDED_KINDS.has(kind);
+}
+/**
+ * Collect the user input still owed to the CLI: messages after the last assistant or
+ * tool message, from the current turn, not sent yet. A tail ending in a tool result
+ * yields nothing, which is how a continuation step is told apart from a new prompt.
+ * @param messages - the derived request history.
+ * @param seen - ids of messages already sent to the CLI.
+ * @param currentTurn - ids of the user messages in the open turn; omitted, all qualify.
+ * @returns new message ids and their text and image blocks, in conversation order.
+ */
+export function unseenUserInput(messages, seen, currentTurn) {
+    const fresh = messagesAfterLastReply(messages).filter((message) => isForwarded(message) &&
+        (message.id === undefined || (!seen.has(message.id) && (currentTurn?.has(message.id) ?? true))));
+    return {
+        ids: fresh.flatMap((message) => (message.id === undefined ? [] : [message.id])),
+        blocks: fresh.flatMap(inputBlocks),
+    };
+}
+/**
+ * Build the replay state that ties a harness session to its CLI session.
+ * @param acpSessionId - the CLI's session id.
+ * @param dshSessionId - the harness session that owns it.
+ * @returns the envelope carried by `finish` and stored on the assistant message.
+ */
+export function nativeReplayState(acpSessionId, dshSessionId) {
+    return { response: { acpSessionId, dshSessionId } };
+}
+function parseReplayResponse(replayState) {
+    const response = replayState?.response;
+    if (typeof response !== 'object' || response === null)
+        return undefined;
+    const { acpSessionId, dshSessionId } = response;
+    return typeof acpSessionId === 'string' && typeof dshSessionId === 'string'
+        ? { acpSessionId, dshSessionId }
+        : undefined;
+}
+/**
+ * Find the CLI session to reattach to, from the latest assistant message.
+ * The owner check keeps a fork, which inherits its parent's messages under a new
+ * id, from writing into the parent's CLI session. The provider check is needed because
+ * all CLIs share one adapter, so the harness does not strip another route's replay state,
+ * and a session id means nothing to any other CLI.
+ * @param messages - the derived request history.
+ * @param dshSessionId - the harness session asking.
+ * @param provider - the CLI route asking.
+ * @returns the CLI session id, or undefined when there is none to reuse.
+ */
+export function readNativeSession(messages, dshSessionId, provider) {
+    const latest = messages.findLast((message) => message.role === 'assistant');
+    const source = latest?.source;
+    if (source?.provider !== provider)
+        return undefined;
+    const replay = parseReplayResponse(source.replayState);
+    return replay?.dshSessionId === dshSessionId ? replay.acpSessionId : undefined;
+}

package/lib/session/connect.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Opening the ACP connection to a CLI and getting a session on it: a new one, or the
+ * native session an earlier process left behind.
+ * @module dsh-ccgui/session/connect
+ */
+import type { AcpTransport, TransportHandlers } from '../transport.ts';
+import type { ModelState } from './model-state.ts';
+/** What opening a session needs. */
+export interface OpenSessionRequest {
+    readonly openTransport: (handlers: TransportHandlers) => AcpTransport;
+    readonly handlers: TransportHandlers;
+    readonly cwd: string;
+    /** The CLI's own session for this conversation, when an earlier process left one. */
+    readonly nativeSessionId: string | undefined;
+    readonly model: ModelState;
+    /** Told as soon as the transport exists, so a stop during startup can still close it. */
+    readonly onTransport: (transport: AcpTransport) => void;
+    /** Receives a failed reattach, which falls back to a new session rather than failing. */
+    readonly onError?: ((error: unknown) => void) | undefined;
+}
+/** The session the CLI is working in. */
+export interface OpenedSession {
+    readonly acpSessionId: string;
+    /** The native session could not be continued, so the CLI starts without the conversation. */
+    readonly reattachFailed: boolean;
+    /** The CLI takes image blocks in a prompt. */
+    readonly acceptsImages: boolean;
+}
+/**
+ * Connect to the CLI and open or continue its session.
+ * @param request - transport factory, handlers and what to continue.
+ * @returns the session and whether continuing it failed.
+ */
+export declare function openSession(request: OpenSessionRequest): Promise<OpenedSession>;
+/**
+ * A stalled `npx` or a CLI waiting for a login would otherwise hang every later message too.
+ * @param work - the startup to bound.
+ * @param timeoutMs - how long it may take.
+ * @returns the startup, rejected with a readable reason once the time is up.
+ */
+export declare function withinStartTimeout(work: () => Promise<void>, timeoutMs: number): Promise<void>;

package/lib/session/connect.js

@@ -0,0 +1,68 @@
+/**
+ * Opening the ACP connection to a CLI and getting a session on it: a new one, or the
+ * native session an earlier process left behind.
+ * @module dsh-ccgui/session/connect
+ */
+const MS_PER_SECOND = 1000;
+/**
+ * Connect to the CLI and open or continue its session.
+ * @param request - transport factory, handlers and what to continue.
+ * @returns the session and whether continuing it failed.
+ */
+export async function openSession(request) {
+    const { openTransport, handlers, cwd, nativeSessionId, model, onTransport } = request;
+    const transport = openTransport(handlers);
+    onTransport(transport);
+    const { agentCapabilities } = await transport.initialize();
+    const acceptsImages = agentCapabilities?.promptCapabilities?.image === true;
+    if (nativeSessionId === undefined) {
+        const { sessionId, configOptions } = await transport.newSession(cwd);
+        model.adopt(configOptions, true);
+        return { acpSessionId: sessionId, reattachFailed: false, acceptsImages };
+    }
+    const attached = await reattach(request, transport, nativeSessionId, {
+        resume: agentCapabilities?.sessionCapabilities?.resume != null,
+        load: agentCapabilities?.loadSession === true,
+    });
+    return { ...attached, acceptsImages };
+}
+async function reattach({ cwd, model, onError }, transport, sessionId, can) {
+    try {
+        if (can.resume) {
+            model.adopt(await transport.resumeSession(sessionId, cwd), false);
+            return { acpSessionId: sessionId, reattachFailed: false };
+        }
+        if (can.load) {
+            // session/load replays the conversation as updates. No turn is active yet,
+            // so the update handler drops them; the harness already has that history.
+            model.adopt(await transport.loadSession(sessionId, cwd), false);
+            return { acpSessionId: sessionId, reattachFailed: false };
+        }
+    }
+    catch (error) {
+        onError?.(error);
+    }
+    const { sessionId: fresh, configOptions } = await transport.newSession(cwd);
+    model.adopt(configOptions, true);
+    return { acpSessionId: fresh, reattachFailed: true };
+}
+/**
+ * A stalled `npx` or a CLI waiting for a login would otherwise hang every later message too.
+ * @param work - the startup to bound.
+ * @param timeoutMs - how long it may take.
+ * @returns the startup, rejected with a readable reason once the time is up.
+ */
+export async function withinStartTimeout(work, timeoutMs) {
+    const { promise: timedOut, reject } = Promise.withResolvers();
+    const seconds = Math.ceil(timeoutMs / MS_PER_SECOND);
+    const timer = setTimeout(() => {
+        reject(new Error(`等了 ${seconds} 秒没有响应`));
+    }, timeoutMs);
+    timer.unref();
+    try {
+        await Promise.race([work(), timedOut]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}