im-agent 0.0.0-stage → 0.1.0

package/src/agents/claude/permissions.ts

@@ -0,0 +1,227 @@
+// Claude 的授权细节：「总是允许」名单、工具调用的人话描述、AskUserQuestion 的解析。
+//
+// Codex 把「总是允许」做进了协议（acceptForSession / execpolicy 补丁），Claude 没有，
+// 只能自己记一份名单。特征刻意保守：Bash 只认命令的第一个词，文件类只认所在目录。
+// 宁可多问几次，也不要因为特征太宽而放行了本不该放行的东西。
+import path from "node:path";
+import { dataDir, readJson, writeJsonAtomic } from "../../home.js";
+import type { QuestionSpec } from "../../core/types.js";
+
+const allowlistPath = path.join(dataDir, "claude-allowlist.json");
+let allowlist: string[] | null = null;
+
+/** 「总是允许一次提问」没有意义：只会让提问卡再也不出现。 */
+const NEVER_REMEMBER = new Set(["AskUserQuestion", "ExitPlanMode"]);
+
+export function isRememberable(toolName: string): boolean {
+  return !NEVER_REMEMBER.has(toolName);
+}
+
+/** 按目录记的签名，目录必须是绝对路径；老版本因读错参数名记下的「NotebookEdit:.」之类一律作废 */
+function validSignature(sig: string): boolean {
+  const m = /^(Edit|Write|NotebookEdit):(.*)$/.exec(sig);
+  return !m || path.isAbsolute(m[2]!);
+}
+
+export function isRememberableSignature(toolName: string, signature: string): boolean {
+  return isRememberable(toolName) && validSignature(signature);
+}
+
+function load(): string[] {
+  allowlist ??= readJson<string[]>(allowlistPath, []).filter(validSignature);
+  return allowlist;
+}
+
+/**
+ * 「总是允许」按多宽记。
+ *
+ * 默认只记**完整命令**。只有白名单里的命令才按「首词」记：它们不论带什么参数都
+ * 只是读读看看，放宽了也出不了大事。黑名单的思路试过，不可靠 —— 包装程序数不完
+ * （npm exec、python3.12 -c、各种解释器……），漏一个就是任意命令执行。
+ *
+ * git 单独处理：按「git + 子命令」记（批准过 git status 不等于批准 git push），
+ * 并且带 -c / --config / --exec-path 之类能改行为的全局参数时只记完整命令。
+ *
+ * 无论哪种，命令里只要有 shell 组合语法（; && | $() 重定向……）就只记完整命令：
+ * 否则 `ls; rm -rf ~` 的首词也是 ls。
+ */
+/**
+ * 出现这些字符就不按首词记：shell 组合语法、变量 / 命令替换，以及引号和通配符 ——
+ * 引号能把危险参数藏起来（'--output=/x' 在 shell 去掉引号后才生效），
+ * 通配符和 ~ 会在执行时展开成我们看不到的东西。
+ */
+const SHELL_SYNTAX = /[;&|`<>\n\r\\'"*?[\]{}~#!]|\$/;
+
+/**
+ * 可按首词放行的命令，以及它们「哪些参数不行」。
+ *
+ * 入选标准：无论带什么参数，都既不能执行别的程序，也不能写文件。为此去掉了
+ * 看似只读、其实带「后门参数」的：rg（--pre 能把文件当脚本跑）、sort / uniq / tree
+ * （-o 或位置参数能写文件）。剩下的少数命令里，个别参数仍有副作用（date -s 改系统时间），
+ * 单独拦掉。
+ */
+const PREFIX_SAFE: Record<string, (args: string[]) => boolean> = {
+  ls: () => true,
+  cat: () => true,
+  head: () => true,
+  tail: () => true,
+  wc: () => true,
+  grep: () => true,
+  pwd: (a) => a.length === 0,
+  echo: () => true,
+  stat: () => true,
+  du: () => true,
+  df: () => true,
+  which: () => true,
+  // GNU 长选项可以缩写（--se 就是 --set），所以只认明确列出的参数
+  date: (a) => a.every((x) => /^\+/.test(x) || ["-u", "--utc", "-R", "-I", "--iso-8601"].includes(x)),
+  basename: () => true,
+  dirname: () => true,
+  realpath: () => true,
+  readlink: () => true,
+  uname: () => true,
+  whoami: (a) => a.length === 0,
+  id: () => true,
+  hostname: (a) => a.length === 0, // 带参数就是改主机名
+  uptime: () => true,
+  ps: () => true,
+  mkdir: () => true,
+  touch: () => true,
+};
+
+/**
+ * git 只放行纯查看的子命令，参数也只认白名单 —— git 的长选项同样能缩写
+ * （--outp 就是 --output），用黑名单拦不住。不是选项的参数（路径、提交号）照常放行。
+ */
+const GIT_READONLY = new Set(["status", "log", "show", "diff"]);
+const GIT_SAFE_FLAGS = new Set([
+  "-s", "--short", "-b", "--branch", "--porcelain", "-v", "--verbose", "-u", "--untracked-files",
+  "--oneline", "--graph", "--decorate", "--all", "--stat", "--shortstat", "--name-only", "--name-status",
+  "-p", "--patch", "--cached", "--staged", "--no-color", "--color", "-w", "--ignore-all-space",
+  "--reverse", "--first-parent", "--no-merges", "--merges", "--", "-q", "--quiet",
+]);
+
+function gitArgOk(arg: string): boolean {
+  if (!arg.startsWith("-")) return true;
+  if (/^-\d+$/.test(arg)) return true; // -5：最近 5 条
+  if (/^(-n|--max-count)=?\d*$/.test(arg)) return true;
+  if (/^--(since|until|author|grep)=[^=]+$/.test(arg)) return true;
+  return GIT_SAFE_FLAGS.has(arg);
+}
+
+function prefixSignature(command: string): string | null {
+  const trimmed = command.trim();
+  if (!trimmed || SHELL_SYNTAX.test(trimmed)) return null;
+  const words = trimmed.split(/\s+/);
+  const head = words[0] ?? "";
+  const args = words.slice(1);
+  const check = Object.hasOwn(PREFIX_SAFE, head) ? PREFIX_SAFE[head] : undefined;
+  if (check) return check(args) ? `Bash:${head}` : null;
+  if (head === "git") {
+    const sub = args[0] ?? "";
+    if (!GIT_READONLY.has(sub) || !args.slice(1).every(gitArgOk)) return null;
+    return `Bash:git ${sub}`;
+  }
+  return null;
+}
+
+export function signatureOf(toolName: string, input: Record<string, unknown>): string {
+  if (toolName === "Bash") {
+    const command = typeof input.command === "string" ? input.command : "";
+    return prefixSignature(command) ?? `BashExact:${command.trim()}`;
+  }
+  if (toolName === "Edit" || toolName === "Write" || toolName === "NotebookEdit") {
+    // NotebookEdit 的路径参数叫 notebook_path，不是 file_path
+    const raw = toolName === "NotebookEdit" ? input.notebook_path : input.file_path;
+    const file = typeof raw === "string" ? raw : "";
+    // 拿不到绝对路径就没法按目录记：给一个不可记忆的签名（见 isRememberableSignature）
+    if (!file || !path.isAbsolute(file)) return `${toolName}:`;
+    return `${toolName}:${path.dirname(file)}`;
+  }
+  return toolName;
+}
+
+export function isPreApproved(toolName: string, signature: string): boolean {
+  // 防绕过靠的是 signatureOf：复合命令拿到的是 BashExact 签名，命中不了 Bash:<首词>
+  return isRememberableSignature(toolName, signature) && load().includes(signature);
+}
+
+export function rememberAlways(signature: string): void {
+  if (!validSignature(signature)) return;
+  const list = load();
+  if (list.includes(signature)) return;
+  list.push(signature);
+  writeJsonAtomic(allowlistPath, list);
+}
+
+export function listAllowlist(): string[] {
+  return [...load()];
+}
+
+export function setAllowlist(next: string[]): void {
+  allowlist = [...new Set(next.map((s) => s.trim()).filter(Boolean))];
+  writeJsonAtomic(allowlistPath, allowlist);
+}
+
+/** 「总是允许」按钮上写清楚到底放行多宽。 */
+export function alwaysLabelOf(toolName: string, signature: string): string {
+  if (toolName === "Bash") {
+    return signature.startsWith("BashExact:") ? "总是允许这条完全相同的命令" : `总是允许 ${signature.slice(5)} 开头的单条命令`;
+  }
+  if (signature.includes(":")) return `总是允许在该目录下${toolName === "Write" ? "新建" : "修改"}`;
+  return `总是允许 ${toolName}`;
+}
+
+export function describeToolCall(toolName: string, input: Record<string, unknown>): string {
+  if (toolName === "Bash") {
+    const desc = typeof input.description === "string" ? `${input.description}\n\n` : "";
+    return `${desc}\`\`\`bash\n${String(input.command ?? "")}\n\`\`\``;
+  }
+  if (toolName === "Edit" || toolName === "Write") {
+    return `**文件**：\`${String(input.file_path ?? "")}\``;
+  }
+  // 计划本身就是写给人看的 markdown，套一层 JSON 只会让它没法读
+  if (toolName === "ExitPlanMode" && typeof input.plan === "string") return input.plan;
+  return `\`\`\`json\n${JSON.stringify(input, null, 2)}\n\`\`\``;
+}
+
+/**
+ * 从 AskUserQuestion 的入参里解出问题清单。解不出来返回 null，调用方退回普通授权卡
+ * —— 宁可显示得笨一点，也不要因为 SDK 改了 schema 就把一整轮卡死。
+ *
+ * 问题的 id 用问题原文：SDK 约定答案按「问题原文 → 答案」回填。
+ */
+export function parseQuestions(input: Record<string, unknown>): QuestionSpec[] | null {
+  const raw = input.questions;
+  if (!Array.isArray(raw) || raw.length === 0) return null;
+  const specs: QuestionSpec[] = [];
+  for (const item of raw) {
+    if (typeof item !== "object" || item === null) return null;
+    const rec = item as Record<string, unknown>;
+    const question = typeof rec.question === "string" ? rec.question.trim() : "";
+    const rawOptions = Array.isArray(rec.options) ? rec.options : [];
+    if (!question || rawOptions.length === 0) return null;
+    const options: QuestionSpec["options"] = [];
+    for (const opt of rawOptions) {
+      if (typeof opt !== "object" || opt === null) return null;
+      const o = opt as Record<string, unknown>;
+      const label = typeof o.label === "string" ? o.label.trim() : "";
+      if (!label) return null;
+      options.push({
+        label,
+        ...(typeof o.description === "string" && o.description.trim()
+          ? { description: o.description.trim() }
+          : {}),
+      });
+    }
+    specs.push({
+      id: typeof rec.question === "string" ? rec.question : question,
+      header: typeof rec.header === "string" && rec.header.trim() ? rec.header.trim() : "选择",
+      question,
+      options,
+      multiSelect: rec.multiSelect === true,
+      allowOther: true,
+    });
+  }
+  return specs;
+}

package/src/agents/claude/session.ts

@@ -0,0 +1,430 @@
+// 一条会话 ↔ 一个常驻的 Claude query。
+//
+// 必须用「流式输入」模式：setModel / interrupt / supportedModels / applyFlagSettings
+// 这些控制方法在 SDK 里全都只在 streaming input mode 下可用，也就是 prompt 必须是
+// async iterable。这是架构前提，别改。
+import fs from "node:fs";
+import {
+  query,
+  type PermissionResult,
+  type Query,
+  type SDKMessage,
+  type SDKUserMessage,
+} from "@anthropic-ai/claude-agent-sdk";
+import { agentEnvironment } from "../../core/agent-env.js";
+import { describeAttachments } from "../../core/uploads.js";
+import type {
+  AgentEvents,
+  AgentSession,
+  InteractionHost,
+  ModelInfo,
+  RuntimeInfo,
+  SavedAttachment,
+  SessionOptions,
+  UserInput,
+} from "../../core/types.js";
+import {
+  alwaysLabelOf,
+  describeToolCall,
+  isPreApproved,
+  isRememberableSignature,
+  parseQuestions,
+  rememberAlways,
+  signatureOf,
+} from "./permissions.js";
+
+class AsyncQueue<T> {
+  private items: T[] = [];
+  private waiting: ((result: IteratorResult<T>) => void)[] = [];
+  private closed = false;
+
+  push(item: T): void {
+    if (this.closed) return;
+    const waiter = this.waiting.shift();
+    if (waiter) waiter({ value: item, done: false });
+    else this.items.push(item);
+  }
+
+  /** 丢掉还没被消费的项（停止时：排着队的消息不该在中断后接着跑） */
+  clear(): number {
+    const n = this.items.length;
+    this.items = [];
+    return n;
+  }
+
+  close(): void {
+    this.closed = true;
+    for (const waiter of this.waiting.splice(0)) waiter({ value: undefined as never, done: true });
+  }
+
+  async *stream(): AsyncGenerator<T> {
+    while (true) {
+      const item = this.items.shift();
+      if (item !== undefined) {
+        yield item;
+        continue;
+      }
+      if (this.closed) return;
+      const next = await new Promise<IteratorResult<T>>((resolve) => this.waiting.push(resolve));
+      if (next.done) return;
+      yield next.value;
+    }
+  }
+}
+
+/** Claude 原生能看的内容块 —— 和 Anthropic API 的 content block 同形。 */
+type ContentBlock =
+  | { type: "text"; text: string }
+  | { type: "image"; source: { type: "base64"; media_type: string; data: string } }
+  | { type: "document"; source: { type: "base64"; media_type: "application/pdf"; data: string } };
+
+/** API 对单张图片的限制是 5MB（按 base64 后计），PDF 是整个请求 32MB。超了只给路径。 */
+const INLINE_IMAGE_MAX = 3.75 * 1024 * 1024;
+const INLINE_PDF_MAX = 20 * 1024 * 1024;
+
+function canInline(a: SavedAttachment): boolean {
+  if (a.mediaType === "application/pdf") return a.size <= INLINE_PDF_MAX;
+  if (a.mediaType && /^image\/(png|jpeg|gif|webp)$/.test(a.mediaType)) return a.size <= INLINE_IMAGE_MAX;
+  return false;
+}
+
+/** 文字 + 附件清单，后面跟着能直接看的图片和 PDF。没有附件时就是原样的文字。 */
+function buildContent(input: UserInput): string | ContentBlock[] {
+  if (input.attachments.length === 0) return input.text;
+  const note = describeAttachments(input.attachments, canInline);
+  const blocks: ContentBlock[] = [{ type: "text", text: input.text ? `${input.text}\n\n${note}` : note }];
+  for (const a of input.attachments) {
+    if (!canInline(a)) continue;
+    const data = fs.readFileSync(a.path).toString("base64");
+    blocks.push(
+      a.mediaType === "application/pdf"
+        ? { type: "document", source: { type: "base64", media_type: "application/pdf", data } }
+        : { type: "image", source: { type: "base64", media_type: a.mediaType!, data } },
+    );
+  }
+  return blocks;
+}
+
+export class ClaudeSession implements AgentSession {
+  private queue = new AsyncQueue<SDKUserMessage>();
+  private q: Query | null = null;
+  private pump: Promise<void> | null = null;
+  private currentId: string | undefined;
+  /**
+   * 分叉已经真正生效（CLI 报出了一个不同于原会话的新 session id）。
+   * 在那之前 CLI 起不来、半路退出，重试都还要带 forkSession，绝不能续写原会话。
+   */
+  private forked = false;
+  private runtime: RuntimeInfo = {};
+  private disposed = false;
+  /**
+   * 消息先留在本地，上一轮出结果了才交给 CLI。
+   *
+   * 一股脑塞给 CLI 的话，它会自己排队；而 interrupt() 只停当前这一轮，排在 CLI 里的
+   * 下一条照样会跑 —— 用户点了停止，agent 却还在干活。留在本地就能在停止时一并丢掉。
+   */
+  private turnBusy = false;
+  private pending: UserInput[] = [];
+
+  constructor(
+    private readonly opts: SessionOptions,
+    private readonly events: AgentEvents,
+    private readonly host: InteractionHost,
+  ) {}
+
+  get sessionId(): string | undefined {
+    return this.currentId;
+  }
+
+  private start(): void {
+    if (this.q || this.disposed) return;
+    // 重启时要接着最新的会话，而不是构造时那个 —— 否则中途崩一次，之后都被倒回去
+    const resume = this.opts.fork && !this.forked ? this.opts.resumeId : (this.currentId ?? this.opts.resumeId);
+    // fork 只在第一次生效：重启再 fork 一次就又分叉一条
+    const fork = this.opts.fork && !this.forked;
+
+    // 每个 query 一条自己的输入队列：CLI 崩溃后重新拉起时，旧 query 的输入循环可能还挂在
+    // 旧队列上等着；继续共用的话，下一条消息会被那个已经没人处理的旧循环吞掉。
+    const input = new AsyncQueue<SDKUserMessage>();
+    this.queue = input;
+    this.q = query({
+      prompt: input.stream(),
+      options: {
+        cwd: this.opts.cwd,
+        env: agentEnvironment(),
+        // 必须是 default：bypassPermissions 会让 canUseTool 变成死代码
+        permissionMode: "default",
+        // 逐字输出给 Web 用；飞书渠道直接忽略这些片段
+        includePartialMessages: true,
+        ...(this.opts.model ? { model: this.opts.model } : {}),
+        ...(this.opts.effort ? { effort: this.opts.effort as never } : {}),
+        additionalDirectories: [this.opts.uploadsDir],
+        ...(resume ? { resume } : {}),
+        ...(fork ? { forkSession: true } : {}),
+        canUseTool: async (toolName, input) => this.canUseTool(toolName, input as Record<string, unknown>),
+      },
+    });
+
+    this.pump = this.consume()
+      .catch((err) => {
+        if (!this.disposed) this.events.onError(err);
+      })
+      .finally(() => {
+        // query 真的结束了（CLI 退出或输入被关）。清掉之后下一条消息会带着最新的
+        // sessionId 重新拉起来，上下文不丢；不清的话消息会进一个没人消费的队列。
+        input.close();
+        this.q = null;
+        this.pump = null;
+        // CLI 半路退出：这一轮不会再有结果了，排队的下一条会重新拉起 CLI 接着跑
+        if (this.turnBusy) this.onTurnEnd();
+      });
+  }
+
+  private async consume(): Promise<void> {
+    if (!this.q) return;
+    for await (const message of this.q as AsyncIterable<SDKMessage>) this.handle(message);
+  }
+
+  private handle(message: SDKMessage): void {
+    if ("session_id" in message && typeof message.session_id === "string" && message.session_id) {
+      if (message.session_id !== this.currentId) {
+        // 分叉时 CLI 报出的新 id 和原会话不同，这才算分叉成功
+        if (this.opts.fork && message.session_id !== this.opts.resumeId) this.forked = true;
+        this.currentId = message.session_id;
+        this.events.onSessionId(message.session_id);
+      }
+    }
+
+    if (message.type === "system" && message.subtype === "init") {
+      this.runtime = { model: message.model, ...(message.effort ? { effort: message.effort } : {}) };
+      this.events.onTurnStart?.();
+      return;
+    }
+
+    // 逐字片段。子 agent 的输出（parent_tool_use_id 非空）不算回复正文
+    if (message.type === "stream_event") {
+      if (message.parent_tool_use_id) return;
+      const event = message.event as { type?: string; delta?: { type?: string; text?: string } };
+      if (event.type === "content_block_delta" && event.delta?.type === "text_delta" && event.delta.text) {
+        this.events.onTextDelta(event.delta.text);
+      }
+      return;
+    }
+
+    if (message.type === "assistant") {
+      const blocks = message.message.content;
+      if (!Array.isArray(blocks)) return;
+      const sub = !!message.parent_tool_use_id;
+      for (const block of blocks) {
+        if (block.type === "thinking") {
+          const thought = summarize(block.thinking);
+          if (thought) this.events.onStep("thinking", `💭 ${thought}`);
+        } else if (block.type === "tool_use") {
+          this.events.onStep("tool", `${sub ? "  ↳ " : ""}🔧 ${describeToolUse(block.name, block.input)}`);
+        } else if (block.type === "text" && block.text.trim() && !sub) {
+          this.events.onText(block.text);
+        }
+      }
+      return;
+    }
+
+    if (message.type === "result") {
+      if (message.subtype === "success") {
+        this.events.onResult({
+          text: message.result,
+          costUsd: message.total_cost_usd,
+          durationMs: message.duration_ms,
+        });
+      } else {
+        this.events.onError(new Error(`运行结束但报错：${message.subtype}`));
+      }
+      this.onTurnEnd();
+    }
+  }
+
+  // ---------- 授权 ----------
+
+  /**
+   * canUseTool：预批过的直接放行，否则交给用户。
+   * 对同一 request_id 必须幂等 —— reinitialize 之后 SDK 会重投同一个请求。
+   */
+  private async canUseTool(toolName: string, input: Record<string, unknown>): Promise<PermissionResult> {
+    // 提问不是授权：它问的是「你选哪个」
+    if (toolName === "AskUserQuestion") {
+      const answered = await this.askQuestion(input);
+      if (answered) return answered;
+    }
+
+    const signature = signatureOf(toolName, input);
+    if (isPreApproved(toolName, signature)) return { behavior: "allow", updatedInput: input };
+
+    const outcome = await this.host({
+      kind: "approval",
+      title: `需要授权：${toolName}`,
+      detail: describeToolCall(toolName, input),
+      ...(isRememberableSignature(toolName, signature) ? { alwaysLabel: alwaysLabelOf(toolName, signature) } : {}),
+    });
+    if (outcome.settlement === "allow-always" && isRememberableSignature(toolName, signature)) rememberAlways(signature);
+    if (outcome.settlement === "allow-once" || outcome.settlement === "allow-always") {
+      return { behavior: "allow", updatedInput: input };
+    }
+    const why =
+      outcome.settlement === "timeout"
+        ? "用户长时间没有响应授权请求（已超时），按拒绝处理"
+        : outcome.settlement === "cancelled"
+          ? "授权请求已被取消（用户中断了这一轮或切换了会话）"
+          : "用户拒绝了此操作";
+    return { behavior: "deny", message: why };
+  }
+
+  /**
+   * AskUserQuestion：选了什么要顺着 updatedInput.answers 回填（问题原文 → 答案），
+   * 少了这一步工具会以「The user did not answer the questions.」收场。
+   */
+  private async askQuestion(input: Record<string, unknown>): Promise<PermissionResult | null> {
+    const questions = parseQuestions(input);
+    if (!questions) return null;
+    const outcome = await this.host({ kind: "question", title: "Claude 想确认一下", questions });
+    const answers: Record<string, string> = {};
+    for (const [id, picked] of Object.entries(outcome.answers)) answers[id] = picked.join(", ");
+    if (Object.keys(answers).length > 0) {
+      return { behavior: "allow", updatedInput: { ...input, answers } };
+    }
+    // 说清楚是「没作答」而不是「拒绝这件事」，并且明说别再问一遍
+    return {
+      behavior: "deny",
+      message:
+        "用户没有作答（超时或主动跳过）。不要重复提同样的问题：按你认为合理的默认继续，并在回复里说明你替他选了什么。",
+    };
+  }
+
+  // ---------- 对外 ----------
+
+  send(input: UserInput): void {
+    if (this.disposed) return;
+    if (this.turnBusy) {
+      this.pending.push(input);
+      return;
+    }
+    this.deliver(input);
+  }
+
+  /** 一轮结束（出结果、出错或 CLI 退出）：交出下一条排队的消息 */
+  private onTurnEnd(): void {
+    this.turnBusy = false;
+    const next = this.pending.shift();
+    if (next && !this.disposed) this.deliver(next);
+  }
+
+  private deliver(input: UserInput): void {
+    // 先把内容组装出来再标记「忙」：附件读不出来（比如已被别处的 /new 清掉）时，
+    // 这条要明确报错并让会话恢复可用，而不是挂在一个永远等不到结果的「忙」上
+    let content: string | ContentBlock[];
+    try {
+      content = buildContent(input);
+    } catch (err) {
+      const why = (err as NodeJS.ErrnoException).code === "ENOENT" ? "附件文件已不存在，请重新上传" : String(err);
+      this.events.onError(new Error(`这条消息没能发出：${why}`));
+      const next = this.pending.shift();
+      if (next && !this.disposed) this.deliver(next);
+      return;
+    }
+    this.turnBusy = true;
+    this.start();
+    this.queue.push({
+      type: "user",
+      message: { role: "user", content },
+      parent_tool_use_id: null,
+      // 人敲的字必须显式标记来源；缺省会在严格的信任门上 fail closed
+      origin: { kind: "human" },
+    } as SDKUserMessage);
+  }
+
+  async listModels(): Promise<ModelInfo[]> {
+    this.start();
+    const models = await this.q!.supportedModels();
+    return models.map((m) => ({
+      id: m.value,
+      label: m.displayName || m.value,
+      ...(m.description ? { description: m.description } : {}),
+      ...(m.supportedEffortLevels?.length ? { efforts: [...m.supportedEffortLevels] } : {}),
+    }));
+  }
+
+  async setModel(model?: string, effort?: string): Promise<void> {
+    this.start();
+    if (model !== undefined) {
+      await this.q!.setModel(model);
+      this.opts.model = model;
+      this.runtime = { ...this.runtime, model };
+    }
+    if (effort !== undefined) {
+      await this.q!.applyFlagSettings({ effortLevel: effort as never });
+      this.opts.effort = effort;
+      this.runtime = { ...this.runtime, effort };
+    }
+  }
+
+  /**
+   * 当前实际生效的模型与思考程度。会拉起 CLI 进程，但不消耗对话轮次。
+   * getSettings 没写进 SDK 的 Query 类型，先探测再调用。
+   */
+  async describeRuntime(): Promise<RuntimeInfo> {
+    this.start();
+    const q = this.q as unknown as {
+      getSettings?: () => Promise<{ applied?: { model?: string; effort?: string | null } }>;
+    };
+    if (typeof q?.getSettings === "function") {
+      try {
+        const applied = (await q.getSettings()).applied;
+        if (applied?.model) {
+          this.runtime = { model: applied.model, ...(applied.effort ? { effort: applied.effort } : {}) };
+        }
+      } catch (err) {
+        console.error("[claude] 读取模型设置失败:", err);
+      }
+    }
+    return this.runtime;
+  }
+
+  async interrupt(): Promise<void> {
+    // 停止 = 这一轮和排着队的都不要了
+    const dropped = this.pending.length + this.queue.clear();
+    this.pending = [];
+    if (dropped > 0) this.events.onDropped?.(dropped);
+    if (!this.q) return;
+    try {
+      await this.q.interrupt();
+    } catch (err) {
+      console.warn("[claude] 中断失败:", err instanceof Error ? err.message : err);
+    }
+  }
+
+  async dispose(): Promise<void> {
+    this.disposed = true;
+    this.pending = [];
+    this.queue.close();
+    try {
+      await this.q?.interrupt();
+    } catch {
+      // 已经停了就无所谓
+    }
+    await this.pump?.catch(() => {});
+    this.q = null;
+    this.pump = null;
+  }
+}
+
+export function summarize(text: string, max = 80): string {
+  const line = text.replace(/\s+/g, " ").trim();
+  return line.length > max ? `${line.slice(0, max)}…` : line;
+}
+
+export function describeToolUse(name: string, input: unknown): string {
+  const record = (input ?? {}) as Record<string, unknown>;
+  if (name === "Bash" && typeof record.command === "string") return `Bash: ${summarize(record.command, 60)}`;
+  if (typeof record.file_path === "string") return `${name}: ${record.file_path}`;
+  if (typeof record.pattern === "string") return `${name}: ${summarize(record.pattern, 40)}`;
+  if (typeof record.description === "string") return `${name}: ${summarize(record.description, 50)}`;
+  return name;
+}