oh-my-agent-web 0.7.0 → 1.0.2

package/dist/server/engine/claude-sessions.js

@@ -0,0 +1,581 @@
+/**
+ * Claude Code 的**会话存储**（只读解析 + 侧栏清单）：`<CLAUDE_CONFIG_DIR|~/.claude>/projects/<encoded-cwd>/<id>.jsonl`。
+ *
+ * 为什么要自己读 JSONL，而不是让 ACP 适配器回放：
+ *   1. `session/load` 是**会重放整段历史**的（每条历史消息都变成一条 `session/update`），
+ *      我们只是要看一看历史、不该为此拿一个活的 query 句柄（续接才需要，见 claude.ts 的 resume）；
+ *   2. ACP 的 `session/list` 只回 `{sessionId, cwd, title, updatedAt}`，**没有模型和用量**，
+ *      而侧栏要显示模型、会话信息面板要显示 token —— 这些都在 JSONL 里；
+ *   3. 用量：`session/prompt` 只回 `stopReason`（**没有 usage**），唯一的账本就是这个 JSONL
+ *      里每条 assistant 的 `message.usage`。
+ *
+ * 文件格式（实测 Claude Code 2.1.301）：每行一个 JSON 条目，我们只认这几种：
+ *   - `{type:"user", message:{role:"user", content}, timestamp, uuid, cwd, sessionId, isSidechain}`
+ *     `content` 是字符串（真人输入）或块数组（`text` / `tool_result`）；
+ *   - `{type:"assistant", message:{role:"assistant", content:[text|thinking|tool_use], model, usage}, ...}`
+ *     **一次模型调用一条**：一个回合里有工具调用时会有多条，所以界面消息要把连续几条合成一条；
+ *   - `{type:"system", subtype:"api_error", error:{message}}`：报错，映射成 error 块；
+ *   - `{type:"cost-state", totalCostUSD}`：整段会话花费（最后一次为准）；
+ *   - 其余（`queue-operation` / `attachment` / `api-request*` / `last-prompt` / `atis-latch` …）
+ *     是内部记账，一律跳过。
+ *
+ * 目录名编码不可逆（`/a-b` 与 `/a/b` 都编成 `-a-b`），所以**只用它做定位预筛**，
+ * 真正的 cwd 一律取条目里的 `cwd` 字段 —— 与适配器 `unstable_listSessions` 的判法一致。
+ */
+import { existsSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { TOOL_EXCERPT_CHARS, } from "../protocol.js";
+import { CLAUDE_PROVIDER, summarizeToolInput } from "./claude-map.js";
+import { isScratchCwd } from "./scratch.js";
+/** 标题上限：与适配器一致（超过就截断加省略号） */
+const MAX_TITLE_LENGTH = 128;
+/** Claude 的数据目录（`CLAUDE_CONFIG_DIR` 与 claude 本体一致） */
+function claudeHome(home) {
+    return home?.trim() || process.env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), ".claude");
+}
+/** 与 claude-code-acp 的 `encodeProjectPath` 完全一致（不可逆，只用于定位目录） */
+function encodeProjectPath(cwd) {
+    return cwd.replace(/[^a-zA-Z0-9]/g, "-");
+}
+/** 逐行容忍解析：坏行（历史版本、被截断的行）跳过，不让整个会话消失 */
+function parseTranscript(text) {
+    const out = [];
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed === "")
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed !== null && typeof parsed === "object")
+                out.push(parsed);
+        }
+        catch {
+            continue;
+        }
+    }
+    return out;
+}
+export function readTranscriptFile(file) {
+    try {
+        return parseTranscript(readFileSync(file, "utf8"));
+    }
+    catch {
+        return [];
+    }
+}
+function timestampOf(entry) {
+    const parsed = typeof entry.timestamp === "string" ? Date.parse(entry.timestamp) : Number.NaN;
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+/** 会话 id → 文件（先按 cwd 猜路径，再扫全部项目目录；与适配器的 `findSessionFile` 同序） */
+export function claudeSessionFile(sessionId, options = {}) {
+    if (sessionId.trim() === "")
+        return null;
+    const root = join(claudeHome(options.home), "projects");
+    const fileName = `${sessionId}.jsonl`;
+    if (options.cwd) {
+        const expected = join(root, encodeProjectPath(options.cwd), fileName);
+        if (existsSync(expected))
+            return expected;
+    }
+    let dirs;
+    try {
+        dirs = readdirSync(root).filter((name) => {
+            try {
+                return statSync(join(root, name)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return null;
+    }
+    for (const dir of dirs) {
+        const candidate = join(root, dir, fileName);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/** 全部会话文件（跳过 `agent-*.jsonl`：那是内部子代理的日志，不是用户会话） */
+function listClaudeSessionFiles(home) {
+    const root = join(claudeHome(home), "projects");
+    let dirs;
+    try {
+        dirs = readdirSync(root, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const dir of dirs) {
+        let files;
+        try {
+            files = readdirSync(join(root, dir));
+        }
+        catch {
+            continue;
+        }
+        for (const file of files) {
+            if (!file.endsWith(".jsonl") || file.startsWith("agent-"))
+                continue;
+            const full = join(root, dir, file);
+            let mtimeMs = 0;
+            try {
+                mtimeMs = statSync(full).mtimeMs;
+            }
+            catch {
+                continue;
+            }
+            out.push({ id: file.slice(0, -".jsonl".length), file: full, mtimeMs });
+        }
+    }
+    return out;
+}
+function sanitizeTitle(text) {
+    const sanitized = text
+        .replace(/[\r\n]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    return sanitized.length <= MAX_TITLE_LENGTH ? sanitized : `${sanitized.slice(0, MAX_TITLE_LENGTH)}…`;
+}
+/** 这块内容算不算「真人说的话」（排除工具结果、system-reminder、命令回显） */
+function userTextOf(content) {
+    const candidates = typeof content === "string"
+        ? [content]
+        : (content ?? [])
+            .filter((block) => block.type === "text" && typeof block.text === "string")
+            .map((block) => block.text);
+    for (const text of candidates) {
+        const trimmed = text.trim();
+        if (trimmed === "")
+            continue;
+        // 注入的上下文（<system-reminder> / <local-command-stdout> / 工具结果回显）不是用户输入
+        if (trimmed.startsWith("<"))
+            continue;
+        return sanitizeTitle(trimmed);
+    }
+    return null;
+}
+/** 一条会话的元数据（cwd / 标题 / 起止时间 / 模型）；判不出 cwd 或落在临时目录的返回 null */
+function sessionMetaOf(id, file, entries, updatedAt) {
+    let cwd = "";
+    let title = null;
+    let startedAt = 0;
+    let model = null;
+    for (const entry of entries) {
+        if (entry.isSidechain === true)
+            continue;
+        if (cwd === "" && typeof entry.cwd === "string")
+            cwd = entry.cwd;
+        if (startedAt === 0)
+            startedAt = timestampOf(entry);
+        if (entry.type === "user" && title === null)
+            title = userTextOf(entry.message?.content);
+        if (entry.type === "assistant") {
+            const found = entry.message?.model;
+            if (typeof found === "string" && found !== "" && found !== "<synthetic>")
+                model = found;
+        }
+    }
+    if (cwd === "" || isScratchCwd(cwd))
+        return null;
+    return {
+        id,
+        file,
+        cwd,
+        title: title ?? id,
+        startedAt: startedAt || updatedAt,
+        updatedAt,
+        model,
+    };
+}
+/** 纯分组：会话 → 项目（按 cwd；项目名取目录名） */
+function groupClaudeSessions(sessions) {
+    const groups = new Map();
+    for (const session of sessions) {
+        const group = groups.get(session.cwd) ??
+            { cwd: session.cwd, name: basename(session.cwd) || session.cwd, sessions: [] };
+        const summary = {
+            id: session.id,
+            engineSessionId: session.id,
+            title: session.title,
+            startedAt: session.startedAt,
+            updatedAt: session.updatedAt,
+            cwd: session.cwd,
+            model: session.model,
+            // 会话的事实源就是这个文件（读历史 / 删除都用它）
+            sessionPath: session.file,
+        };
+        group.sessions.push(summary);
+        groups.set(session.cwd, group);
+    }
+    return [...groups.values()]
+        .map((group) => ({
+        ...group,
+        sessions: [...group.sessions].sort((left, right) => right.updatedAt - left.updatedAt),
+    }))
+        .sort((left, right) => (right.sessions[0]?.updatedAt ?? 0) - (left.sessions[0]?.updatedAt ?? 0));
+}
+/**
+ * 侧栏的会话清单（读文件，不开子进程）。
+ *
+ * 每个文件按 mtime 缓存解析结果：刷新会话列表是高频动作（每次回合结束都会来一次），
+ * 但历史文件几乎不变 —— 没有这层缓存就会把几十条会话每条都重新 parse 一遍。
+ */
+export function createClaudeSessionsProvider(options) {
+    const home = options.home;
+    const cacheMs = options.cacheMs ?? 5000;
+    const now = options.now ?? Date.now;
+    let cached = null;
+    const fileCache = new Map();
+    return async () => {
+        if (cached && now() - cached.at < cacheMs)
+            return cached.value;
+        try {
+            const sessions = [];
+            for (const session of listClaudeSessionFiles(home)) {
+                const known = fileCache.get(session.file);
+                if (known && known.mtimeMs === session.mtimeMs) {
+                    if (known.meta)
+                        sessions.push(known.meta);
+                    continue;
+                }
+                const meta = sessionMetaOf(session.id, session.file, readTranscriptFile(session.file), session.mtimeMs);
+                fileCache.set(session.file, { mtimeMs: session.mtimeMs, meta });
+                if (meta)
+                    sessions.push(meta);
+            }
+            cached = { at: now(), value: groupClaudeSessions(sessions) };
+            return cached.value;
+        }
+        catch (error) {
+            options.log?.(`读取 claude 会话清单失败：${error instanceof Error ? error.message : String(error)}`);
+            return cached?.value ?? [];
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// JSONL → 界面消息 / 转录 / 统计
+// ---------------------------------------------------------------------------
+function toolBlockOf(block, ts) {
+    const name = typeof block.name === "string" && block.name !== "" ? block.name : "tool";
+    const summary = summarizeToolInput(name, block.input);
+    const full = block.input === undefined ? "" : safeJson(block.input);
+    return {
+        kind: "tool",
+        toolCallId: typeof block.id === "string" ? block.id : `tool-${ts}-${name}`,
+        name,
+        argsSummary: summary.length > 300 ? `${summary.slice(0, 300)}…` : summary,
+        ...(full !== "" && full !== summary ? { argsFull: full } : {}),
+        status: "running",
+        outputExcerpt: "",
+        truncated: false,
+        startedAt: ts,
+    };
+}
+/** 工具结果回填（Claude 把 tool_result 放在**下一条 user 条目**里） */
+function applyToolResult(block, result, ts) {
+    if (!block)
+        return;
+    const output = outputTextOf(result.content);
+    block.status = result.is_error === true ? "failed" : "ok";
+    block.outputExcerpt = output.length > TOOL_EXCERPT_CHARS ? `${output.slice(0, TOOL_EXCERPT_CHARS)}…` : output;
+    block.truncated = output.length > TOOL_EXCERPT_CHARS;
+    block.endedAt = ts || block.startedAt;
+}
+function outputTextOf(value) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value)) {
+        return value
+            .map((item) => outputTextOf(item))
+            .filter((text) => text !== "")
+            .join("\n");
+    }
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        if (typeof record.text === "string")
+            return record.text;
+        if (record.content !== undefined)
+            return outputTextOf(record.content);
+        return safeJson(value);
+    }
+    return "";
+}
+function safeJson(value) {
+    try {
+        return JSON.stringify(value) ?? "";
+    }
+    catch {
+        return String(value);
+    }
+}
+/** 条目的内容块（字符串内容 = 纯文本，没有块可数） */
+function contentBlocksOf(entry) {
+    const content = entry.message?.content;
+    return Array.isArray(content) ? content : [];
+}
+/**
+ * 转录 → 界面消息。
+ *
+ * 分组规则：**一个回合 = 一条 assistant 消息**。Claude 每调一次模型就写一条 `assistant` 条目，
+ * 带工具的一轮会有好几条（调工具前后各一次），界面显示成分开的几条会把「一次回复」切碎；
+ * 所以把连续几条合成一条，token 求和，`endedAt` 取最后一条的时间。
+ * 中间的 `tool_result`（在 user 条目里）只回填工具卡片，不产生用户消息。
+ */
+export function transcriptToUiMessages(entries) {
+    const out = [];
+    const tools = new Map();
+    let pending = null;
+    const flush = () => {
+        if (pending && pending.blocks.length > 0)
+            out.push(pending);
+        pending = null;
+    };
+    for (const entry of entries) {
+        if (entry.isSidechain === true)
+            continue;
+        const ts = timestampOf(entry);
+        // 报错条目没有 message 字段（只有 error），要在 message 守卫**之前**处理掉
+        if (entry.type === "system" && entry.subtype === "api_error") {
+            if (!pending)
+                pending = { id: `a-${entry.uuid ?? out.length}`, role: "assistant", ts, blocks: [] };
+            const text = entry.error?.message ?? "Claude Code 报了一个错";
+            pending.blocks.push({ kind: "error", code: "claude.api_error", message: text });
+            pending.endedAt = ts;
+            continue;
+        }
+        const message = entry.message;
+        if (!message)
+            continue;
+        if (entry.type === "user") {
+            const content = message.content;
+            let said = null;
+            if (typeof content === "string") {
+                said = userTextOf(content);
+            }
+            else if (Array.isArray(content)) {
+                for (const block of content) {
+                    if (block.type === "tool_result") {
+                        const id = typeof block.tool_use_id === "string" ? block.tool_use_id : "";
+                        applyToolResult(tools.get(id), block, ts);
+                        continue;
+                    }
+                    if (block.type === "text" && said === null)
+                        said = userTextOf([block]);
+                }
+            }
+            if (said !== null) {
+                flush();
+                out.push({
+                    id: `u-${entry.uuid ?? out.length}`,
+                    role: "user",
+                    ts,
+                    blocks: [{ kind: "text", text: said }],
+                });
+            }
+            continue;
+        }
+        if (entry.type !== "assistant")
+            continue;
+        if (!pending) {
+            pending = { id: `a-${entry.uuid ?? out.length}`, role: "assistant", ts, blocks: [] };
+        }
+        const blocks = pending.blocks;
+        for (const block of Array.isArray(message.content) ? message.content : []) {
+            if (block.type === "text" && typeof block.text === "string" && block.text !== "") {
+                blocks.push({ kind: "text", text: block.text });
+                continue;
+            }
+            if (block.type === "thinking" && typeof block.thinking === "string" && block.thinking !== "") {
+                blocks.push({ kind: "thinking", text: block.thinking });
+                continue;
+            }
+            if ((block.type === "tool_use" || block.type === "server_tool_use") && block.name !== "TodoWrite") {
+                const tool = toolBlockOf(block, ts);
+                tools.set(tool.toolCallId, tool);
+                blocks.push(tool);
+            }
+        }
+        const usage = message.usage;
+        if (usage) {
+            const previous = pending.usage ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+            pending.usage = {
+                input: previous.input + Number(usage.input_tokens ?? 0),
+                output: previous.output + Number(usage.output_tokens ?? 0),
+                cacheRead: previous.cacheRead + Number(usage.cache_read_input_tokens ?? 0),
+                cacheWrite: previous.cacheWrite + Number(usage.cache_creation_input_tokens ?? 0),
+            };
+        }
+        if (typeof message.model === "string" && message.model !== "" && message.model !== "<synthetic>") {
+            pending.model = `${CLAUDE_PROVIDER}/${message.model}`;
+        }
+        pending.endedAt = ts || pending.endedAt;
+    }
+    flush();
+    return out;
+}
+/** 转录 → 引擎转录（只留正文，给「续聊」这种只要文本的场合） */
+export function transcriptToTranscript(entries) {
+    const out = [];
+    for (const entry of entries) {
+        if (entry.isSidechain === true)
+            continue;
+        const message = entry.message;
+        if (!message)
+            continue;
+        if (entry.type === "user") {
+            const text = userTextOf(message.content);
+            if (text !== null)
+                out.push({ role: "user", text, ts: timestampOf(entry) });
+            continue;
+        }
+        if (entry.type !== "assistant")
+            continue;
+        const parts = [];
+        for (const block of Array.isArray(message.content) ? message.content : []) {
+            if (block.type === "text" && typeof block.text === "string" && block.text !== "")
+                parts.push(block.text);
+        }
+        if (parts.length === 0)
+            continue;
+        out.push({ role: "assistant", text: parts.join("\n\n"), ts: timestampOf(entry) });
+    }
+    return out;
+}
+/**
+ * 转录 → 会话统计。
+ *
+ * 四桶用量 = Σ 每条 assistant 的 `message.usage`（Claude 按次记账）；
+ * 上下文占用取**最后一条** assistant 的输入侧（含缓存读写），近似「现在上下文多大」；
+ * 花费只有 `cost-state` 条目给（`totalCostUSD`），没有就不给这个字段（不编 0）。
+ */
+export function transcriptStats(entries) {
+    const stats = {
+        userMessages: 0,
+        assistantMessages: 0,
+        toolCalls: 0,
+        toolResults: 0,
+        totalMessages: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        totalTokens: 0,
+        contextTokens: 0,
+    };
+    for (const entry of entries) {
+        if (entry.isSidechain === true)
+            continue;
+        if (entry.type === "user") {
+            if (userTextOf(entry.message?.content) === null) {
+                // 只有工具结果的 user 条目：计入工具结果，不算一条用户消息
+                for (const block of contentBlocksOf(entry)) {
+                    if (block.type === "tool_result")
+                        stats.toolResults += 1;
+                }
+                continue;
+            }
+            stats.userMessages += 1;
+            stats.totalMessages += 1;
+            continue;
+        }
+        if (entry.type !== "assistant")
+            continue;
+        stats.assistantMessages += 1;
+        stats.totalMessages += 1;
+        for (const block of contentBlocksOf(entry)) {
+            if (block.type === "tool_use" && block.name !== "TodoWrite")
+                stats.toolCalls += 1;
+        }
+        const usage = entry.message?.usage;
+        if (!usage)
+            continue;
+        const input = Number(usage.input_tokens ?? 0);
+        const output = Number(usage.output_tokens ?? 0);
+        const cacheRead = Number(usage.cache_read_input_tokens ?? 0);
+        const cacheWrite = Number(usage.cache_creation_input_tokens ?? 0);
+        stats.inputTokens += input;
+        stats.outputTokens += output;
+        stats.cacheRead += cacheRead;
+        stats.cacheWrite += cacheWrite;
+        stats.totalTokens += input + output + cacheRead + cacheWrite;
+        stats.contextTokens = input + cacheRead + cacheWrite;
+    }
+    for (const entry of entries) {
+        if (entry.type === "cost-state" && typeof entry.totalCostUSD === "number") {
+            stats.cost = entry.totalCostUSD;
+        }
+    }
+    return stats;
+}
+/**
+ * 这一轮的用量（最后一条真人输入之后的全部 assistant 之和）。
+ *
+ * 用在哪里：`session/prompt` 的返回里没有 usage，宿主却要在这轮结束时报一次账 ——
+ * 回合结束时读一遍 JSONL，把这段加起来推一个 `usage` 事件（界面上的 token 才会动）。
+ */
+export function lastTurnUsage(entries) {
+    let start = -1;
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry?.type !== "user" || entry.isSidechain === true)
+            continue;
+        if (userTextOf(entry.message?.content) === null)
+            continue;
+        start = index;
+        break;
+    }
+    if (start < 0)
+        return null;
+    const total = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+    for (const entry of entries.slice(start + 1)) {
+        if (entry.type !== "assistant" || entry.isSidechain === true)
+            continue;
+        const usage = entry.message?.usage;
+        if (!usage)
+            continue;
+        total.input += Number(usage.input_tokens ?? 0);
+        total.output += Number(usage.output_tokens ?? 0);
+        total.cacheRead += Number(usage.cache_read_input_tokens ?? 0);
+        total.cacheWrite += Number(usage.cache_creation_input_tokens ?? 0);
+    }
+    const sum = total.input + total.output + total.cacheRead + total.cacheWrite;
+    return sum === 0 ? null : total;
+}
+/** 会话最后用的模型（历史会话打开时显示它，而不是「当前默认」） */
+export function sessionModelOf(entries) {
+    let model = null;
+    for (const entry of entries) {
+        if (entry.type !== "assistant" || entry.isSidechain === true)
+            continue;
+        const found = entry.message?.model;
+        if (typeof found === "string" && found !== "" && found !== "<synthetic>")
+            model = found;
+    }
+    return model === null ? null : { provider: CLAUDE_PROVIDER, model };
+}
+/**
+ * 删除会话：删掉那个 JSONL。
+ *
+ * Claude 自己的 CLI 没有「删除会话」这个动作（`/clear` 只是开新的），所以这里直接删文件 ——
+ * 与「会话的事实源是引擎自己写的文件」一致：文件没了，侧栏与 `claude --resume` 也就找不到了。
+ */
+export function deleteClaudeSession(sessionId, options = {}) {
+    const file = options.sessionPath || claudeSessionFile(sessionId, options);
+    if (!file || !existsSync(file))
+        return false;
+    try {
+        rmSync(file, { force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/server/engine/claude-transport.js

@@ -0,0 +1,75 @@
+/**
+ * Claude Code 的 ACP 客户端（ADR-0044）= 通用 JSON-RPC stdio + ACP 握手。
+ *
+ * 为什么走 `claude-code-acp`（`@zed-industries/claude-code-acp`）而不是 SDK / `claude -p`：
+ *   - `claude -p --output-format stream-json` 是**一次性回合**：权限问询要靠管道里的 control
+ *     帧自己实现，也没有 `session/list`（历史会话只能自己扫 `~/.claude/projects`），
+ *     换模型要重启进程 —— 只能当兜底，不能当引擎；
+ *   - `@anthropic-ai/claude-agent-sdk` 能力最全，但它把 Claude Code 整个打包进宿主进程，
+ *     版本跟着本工作台的依赖走，用户本机的 `claude` 登录态 / 权限配置反而管不到；
+ *   - 这个适配器是 Zed 维护的官方级 ACP 实现，对外给的就是我们要的那几个动作：
+ *     `session/new|load|resume|list`、`session/set_model`、`session/set_mode`、
+ *     `session/cancel`、`session/request_permission`。与 dsh / opencode 走同一套协议，
+ *     所以复用 `jsonrpc-stdio.ts`（换的只有可执行文件与握手参数）。
+ *
+ * 实测（claude-code-acp 0.16.2 + Claude Code 2.1.301）：
+ *   initialize → `{protocolVersion:1, agentCapabilities:{loadSession:true,
+ *                 sessionCapabilities:{list,resume,fork}, promptCapabilities:{image,embeddedContext}},
+ *                 agentInfo:{name:"@zed-industries/claude-code-acp", title:"Claude Code", version}}`
+ *   session/new → `{sessionId, models:{availableModels:[{modelId,name,description}], currentModelId},
+ *                   modes:{currentModeId, availableModes}}`
+ *
+ * 与 dsh / opencode 的两处差异（决定了 claude.ts 的写法）：
+ *   1. 没有 `configOptions`：模型是 `session/new` 返回的 `models`，切换走 `session/set_model`
+ *      （不是 `session/set_config_option`），思考档位这套协议里压根没有；
+ *   2. `session/resume`（不重放历史）与 `session/load`（重放历史）都在，所以「续接」用前者，
+ *      历史回放交给 JSONL（见 claude-sessions.ts），不必让适配器把整段历史再推一遍。
+ */
+import { findExecutable } from "../util/spawn-cli.js";
+import { createJsonRpcStdioClient } from "./jsonrpc-stdio.js";
+/**
+ * 这个适配器**改过名**，两个包都还在被装着，所以两个 bin 名都认：
+ *   - `@zed-industries/claude-code-acp` → `claude-code-acp`（老包，npm 上已标记 deprecated）；
+ *   - `@agentclientprotocol/claude-agent-acp` → `claude-agent-acp`（改名后的新包）。
+ * 只认一个的话，用户按 deprecation 提示装完新包反而变成「没有找到适配器」。
+ */
+const CLAUDE_ACP_BINS = ["claude-code-acp", "claude-agent-acp"];
+/** 默认可执行文件：PATH 里先命中哪个用哪个；都没装就报第一个名字（错误信息里再教怎么装） */
+export function defaultClaudeBin(env = process.env, find = (bin, e) => findExecutable(bin, e)) {
+    for (const bin of CLAUDE_ACP_BINS) {
+        if (find(bin, env))
+            return bin;
+    }
+    return CLAUDE_ACP_BINS[0];
+}
+/**
+ * 握手时声明的客户端能力。
+ *
+ * 全部 `false`：Claude 自己的工具（Bash / Read / Write …）在适配器进程里跑，
+ * 我们不当它的 fs / terminal 桥（与 dsh / opencode 一致）。
+ * `promptCapabilities.image` 是**它**收图，不需要我们声明。
+ */
+const CLIENT_CAPABILITIES = {
+    fs: { readTextFile: false, writeTextFile: false },
+    terminal: false,
+};
+export function createClaudeClient(options = {}) {
+    return createJsonRpcStdioClient({
+        bin: options.bin ?? defaultClaudeBin(),
+        args: options.args ?? [],
+        env: options.env,
+        cwd: options.cwd,
+        name: "claude",
+        log: options.log ?? (() => { }),
+        timeoutMs: options.timeoutMs,
+        // ACP 是标准 JSON-RPC 2.0：帧里必须带 jsonrpc 字段
+        jsonrpc: true,
+        async handshake(call) {
+            const result = (await call("initialize", {
+                protocolVersion: 1,
+                clientCapabilities: CLIENT_CAPABILITIES,
+            }));
+            return { version: result?.agentInfo?.version ?? null };
+        },
+    });
+}