agent-loft 0.0.0-stage → 0.2.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qijieinnet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# agent-loft
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+用飞书（以后还有 Telegram 等）和 Web 页面，驱动本机的 **Claude Code** 和 **Codex**。
+
+由 `feishu-claude-bridge` 和 `feishu-codex-bridge` 合并而来：一个进程、一份配置，飞书和网页共用同一套会话、审批和模型切换。
+
+## 能做什么
+
+- **多个 agent**：Claude Code（官方 Claude Agent SDK）、Codex（官方 `codex app-server`）。在同一条会话里 `/agent` 切换，各 agent 的上下文各自保留。
+- **多个飞书机器人**：一个机器人对应一个 agent，或者一个机器人能切换多个 agent，都在设置页里勾选。机器人能在 Web 上扫码创建，改完配置立即生效，不用重启。
+- **Web 聊天页**：电脑和手机都能用，界面参照 ChatGPT。
+  - 回复逐字显示，markdown 和代码高亮，思考过程和工具调用可以折叠。
+  - 授权卡、提问卡直接在页面上点。
+  - 支持上传附件（粘贴、拖拽，手机上可以拍照）。
+  - 可以「添加到主屏幕」当 App 用。手机切到后台再回来会自动重连，并补上错过的内容。
+  - 系统通知：回复完成、出错、需要授权或提问时推送到手机 / 电脑（设置 → 通知 里按设备开启）。标准 Web Push，不用注册任何开发者账号；需要 HTTPS 访问，iPhone 需 iOS 16.4+ 且从主屏幕图标打开。
+  - 收到推送时，主屏 / 桌面 PWA 图标上显示未读角标（iOS 16.4+、桌面 Chrome / Edge），打开页面自动清零。
+  - 切换工作目录可以在目录树里一层层点选；新对话发第一条消息前也能先选好目录。
+  - 语音输入：输入框旁的麦克风按钮，用浏览器自带的语音识别（Chrome / Edge / Safari，需要 HTTPS）。
+  - 新对话页：大标题里点目录名切换工作目录；输入框上方的条里选目录和 agent，右下角直接选模型和思考程度（弹出菜单，不用开弹窗）。会话中 agent 不切换（命令 `/agent` 仍可切），模型和思考程度随时可换。
+  - 输入框里显示上下文窗口占用（小圆环，悬停看已用 / 剩余 token）。
+  - 输入框的模型按钮直接显示实际的模型和思考程度（如「Opus 5.5 high」），和选项里的名字一致；列表里显示哪些模型在 设置 → Agent 里勾选。
+  - 每条回复下方显示用时、费用和完成时间，最后一条常驻，前面的悬停才出现；可以复制，也可以「从这里分叉」成一条新对话（只保留到这条回复，原对话不动）。
+  - 侧栏分「最近」和「项目」两组：Web 会话按工作目录归类，飞书机器人各占一行并带飞书图标；分叉出来的对话挂在主对话下面，用虚线连起来；分组可折叠，宽度可拖动，双击会话重命名，名字太长时悬停滚动显示。
+  - 侧栏底部显示 Claude / Codex 的订阅额度（5 小时 / 7 天窗口，悬停看重置时间）；空闲时按设置的间隔自动刷新（默认 10 分钟），跑完一轮后也会刷新。
+- **跨渠道同步**：飞书里的会话在 Web 上也能打开，接着聊。同一个授权请求同时出现在飞书卡片和网页上，哪边先点算哪边，另一边自动变成「已处理」。
+- **设置都在网页上**：工作目录、各 agent 的默认模型和思考程度、Codex 沙箱、飞书机器人、配对批准、Claude 的「总是允许」名单、登录设备管理。
+
+## 安装
+
+```bash
+npm install -g agent-loft         # 或者在仓库里 npm install 后用 node bin/cli.js
+agent-loft start                  # 前台运行，日志里会打印首次登录用的设置码
+agent-loft service install        # 注册为开机自启服务（systemd / launchd）
+```
+
+打开 `http://<机器 IP>:8800`：第一次需要输入日志里的设置码，然后设一个登录密码。
+
+### 从旧桥接器迁移
+
+```bash
+agent-loft import --dry-run       # 先看会导入什么
+systemctl --user disable --now feishu-claude-bridge feishu-codex-bridge   # 同一个机器人不能被两个程序同时连
+agent-loft import                 # 导入机器人凭据、白名单、配对、会话绑定、总是允许名单
+agent-loft service install
+```
+
+导入后，飞书群里原来的会话会接着聊。
+
+## 命令
+
+| 命令 | 作用 |
+|---|---|
+| `agent-loft start` | 启动 |
+| `agent-loft import [--only claude\|codex] [--disabled] [--dry-run]` | 从旧桥接器导入 |
+| `agent-loft pair list \| approve <码> \| revoke <机器人id> <open_id>` | 配对管理（Web 设置页里也能做） |
+| `agent-loft passwd [新密码]` | 重置 Web 登录密码，所有设备下线 |
+| `agent-loft service install \| uninstall \| restart \| status` | 开机自启 |
+| `agent-loft doctor` | 体检 |
+
+聊天里的命令（飞书和 Web 通用；Web 输入框打 `/` 会弹出命令补全，飞书里打 `/` 会弹出机器人的指令面板（agent-loft 自动注册，约 5～8 分钟生效；只发一个 `/` 也会回一张可点击的命令卡片），顺序和显示项在 设置 → 命令 里调整）：`/new` `/fork` `/sessions [all]` `/resume <id>` `/model [名称]` `/effort <程度>` `/agent [名称]`（或者直接发 `/claude`、`/codex`）`/stop` `/cd <目录>` `/pwd` `/status` `/approve <id> allow-once|allow-always|allow-session|deny` `/help`
+
+## 安全
+
+这个服务能让 agent 在你的机器上执行命令，等于一个远程 shell。
+
+- Web 登录密码用 scrypt 哈希保存。首次设置必须用启动日志里的一次性设置码，防止「谁先打开页面谁就成了主人」。
+- 登录态通过 HttpOnly cookie 保存，服务端只存它的哈希。同一 IP 连续输错 5 次锁 15 分钟。所有写请求和 WebSocket 都校验 Origin。页面开启了严格的 CSP。
+- 暴露到公网时，只通过 HTTPS 反向代理（比如 Lucky）访问，并把反代的 IP 加进 `web.trustedProxies`（只有从这些地址来的连接才采信 `X-Forwarded-*`）。不要直接把 8800 端口映射出去。
+- 审批超时一律按拒绝处理。Codex 默认沙箱为 `workspace-write`，不会因为 `~/.codex/config.toml` 里配了 `never` 或 `danger-full-access` 就绕过审批。
+- agent 子进程拿不到本服务自己的凭据（`FEISHU_*`、`AGENT_LOFT_*` 等环境变量会被剔除）。
+
+## 结构
+
+```
+src/
+  core/            与渠道、agent 都无关的中枢
+    hub.ts         会话调度：事件广播、命令、切 agent / 模型 / 目录
+    interactions.ts 审批与提问：一个请求，多个渠道都能处理
+    store.ts       会话持久化（每个 agent 的会话 id 各自保存）
+    config.ts      配置（Web 可改，改完热加载）
+    pairing.ts uploads.ts commands.ts …
+  agents/
+    claude/        Claude Agent SDK 驱动
+    codex/         codex app-server 驱动
+  channels/
+    feishu/        飞书：一个 FeishuBot 对应一个机器人，支持多个
+    web/           HTTP + WebSocket + 鉴权
+web/               前端（原生 JS，不需要构建）
+```
+
+### 接入新的消息渠道（比如 Telegram）
+
+参照 `channels/feishu/bot.ts`，做三件事：
+
+1. 收到消息 → `hub.ensure()` 建会话 → `parseCommand()`。是命令就调 `hub.command()`，再把 `CommandReply` 画出来；是聊天就调 `hub.send()`。
+2. 订阅 `hub.on("event")`，挑出自己的会话（键前缀如 `telegram:<botId>:`），把 step / text / result / error 画出来。
+3. 订阅 `interactions` 的 `created / updated / settled`，把授权卡和提问卡画成按钮。用户点击后调 `interactions.decide / select / submit / skip`。
+
+### 接入新的 agent
+
+实现 `core/types.ts` 里的 `AgentDriver`，然后在 `main.ts` 里 `hub.registerDriver()`。`AgentDriver` 包括开会话、发消息、中断、切模型、列历史、读历史，审批通过传入的 `InteractionHost` 发起。以后要接 ACP 协议的 agent（Gemini CLI、OpenCode 等），写一个通用的 ACP 驱动就行。
+
+## 开发
+
+```bash
+npm install
+npm run dev          # AGENT_LOFT_HOME=./.dev，改代码自动重启
+npm test
+npm run typecheck
+```

package/bin/cli.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// 统一入口：agent-loft <start|import|pair|passwd|service|doctor>
+//
+// 源码是 TypeScript，用 tsx 的 ESM loader 直接加载，装完即可运行，不需要先 build。
+import { register } from "tsx/esm/api";
+
+const COMMANDS = {
+  start: "../src/main.ts",
+  import: "../src/cli/import.ts",
+  pair: "../src/cli/pair.ts",
+  passwd: "../src/cli/passwd.ts",
+  service: "../src/cli/service.ts",
+  doctor: "../src/cli/doctor.ts",
+};
+
+const USAGE = `agent-loft —— 用飞书 / Web 驱动本机的 Claude Code 和 Codex
+
+用法：
+  agent-loft start            启动（默认命令）
+  agent-loft import           从旧的 feishu-claude-bridge / feishu-codex-bridge 导入配置和会话
+  agent-loft pair ...         配对管理：list | approve <配对码> | revoke <机器人id> <open_id>
+  agent-loft passwd           重置 Web 登录密码
+  agent-loft service ...      开机自启：install | uninstall | restart | status
+  agent-loft doctor           体检：配置 / agent / 飞书连通性
+
+配置目录：~/.agent-loft（可用 AGENT_LOFT_HOME 覆盖；已有旧的 ~/.im-agent 会继续沿用）
+`;
+
+const [, , rawCommand, ...rest] = process.argv;
+const command = rawCommand ?? "start";
+
+if (command === "-h" || command === "--help" || command === "help") {
+  process.stdout.write(USAGE);
+  process.exit(0);
+}
+
+const target = COMMANDS[command];
+if (!target) {
+  process.stderr.write(`未知命令：${command}\n\n${USAGE}`);
+  process.exit(1);
+}
+
+process.argv = [process.argv[0], process.argv[1], ...rest];
+
+register();
+try {
+  await import(new URL(target, import.meta.url).href);
+} catch (err) {
+  if (process.env.AGENT_LOFT_DEBUG || process.env.IM_AGENT_DEBUG) throw err;
+  process.stderr.write(`${err instanceof Error ? err.message : err}\n`);
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "agent-loft",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.7",
+  "type": "module",
+  "description": "把飞书（以及以后的 Telegram 等）和 Web 页面桥接到本机 Claude Code / Codex：聊天驱动、卡片审批、会话与模型切换",
+  "keywords": [
+    "feishu",
+    "lark",
+    "claude-code",
+    "codex",
+    "bridge",
+    "agent",
+    "飞书"
+  ],
+  "license": "MIT",
+  "author": "qijieinnet",
+  "homepage": "https://github.com/qijieinnet/agent-loft#readme",
+  "bugs": {
+    "url": "https://github.com/qijieinnet/agent-loft/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qijieinnet/agent-loft.git"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "agent-loft": "bin/cli.js",
+    "aloft": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "web",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/cli.js start",
+    "dev": "AGENT_LOFT_HOME=./.dev tsx watch src/main.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts",
+    "prepublishOnly": "npm run typecheck"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.302",
+    "@highlightjs/cdn-assets": "^11.12.0",
+    "@larksuiteoapi/node-sdk": "^1.73.0",
+    "dompurify": "^3.2.0",
+    "marked": "^16.0.0",
+    "qrcode": "^1.5.4",
+    "tsx": "^4.20.6",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@types/qrcode": "^1.5.6",
+    "@types/ws": "^8.5.12",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/agents/claude/account.ts

@@ -0,0 +1,122 @@
+// 账号额度：Claude 订阅的 5 小时 / 7 天用量窗口，和 Codex 那边的 account.ts 对齐。
+//
+// 数据来自 SDK 的 usage 控制请求 —— 也就是 Claude Code 里 `/usage` 背后的那份结构化数据，
+// 通过探针 query 读取（见 probe.ts）。
+//
+// 注意：SDK 把它标成了 EXPERIMENTAL，方法名以后会改。改了的话这里只会读失败，
+// /status 少几行而已，不影响别的。
+import type { QuotaInfo } from "../../core/types.js";
+import { cachedProbe, withProbe } from "./probe.js";
+
+type Window = { utilization: number | null; resets_at: string | null } | null | undefined;
+
+type LimitRow = {
+  kind: string;
+  group: string;
+  percent: number;
+  resets_at: string | null;
+  severity?: string;
+  scope?: { model?: { display_name: string } | null; surface?: { display_name: string } | null } | null;
+};
+
+export type ClaudeUsage = {
+  subscriptionType: string | null;
+  rows: { label: string; short: string; percent: number; resetsAt: string | null; severity?: string }[];
+};
+
+function labelOf(row: LimitRow): string {
+  const scope = row.scope?.model?.display_name || row.scope?.surface?.display_name;
+  const base = row.kind === "session" ? "5 小时" : row.group === "weekly" ? "7 天" : row.kind;
+  return scope ? `${base}（${scope}）` : base;
+}
+
+/** 侧栏紧凑显示用：5h / 7d，带范围的加上范围名 */
+function shortOf(row: LimitRow): string {
+  const scope = row.scope?.model?.display_name || row.scope?.surface?.display_name;
+  const base = row.kind === "session" ? "5h" : row.group === "weekly" ? "7d" : row.kind;
+  return scope ? `${base} ${scope}` : base;
+}
+
+function normalize(res: {
+  subscription_type: string | null;
+  rate_limits_available: boolean;
+  rate_limits: Record<string, unknown> | null;
+}): ClaudeUsage | null {
+  if (!res.rate_limits_available || !res.rate_limits) return null;
+  const rl = res.rate_limits;
+  const limits = rl.limits as LimitRow[] | null | undefined;
+  let rows: ClaudeUsage["rows"];
+  if (Array.isArray(limits)) {
+    // 新版服务端直接给出要显示哪些行、什么顺序，照单全收
+    rows = limits.map((r) => ({
+      label: labelOf(r),
+      short: shortOf(r),
+      percent: r.percent,
+      resetsAt: r.resets_at,
+      ...(r.severity ? { severity: r.severity } : {}),
+    }));
+  } else {
+    // 老格式兜底：只认两个主窗口
+    rows = [];
+    for (const [key, label, short] of [
+      ["five_hour", "5 小时", "5h"],
+      ["seven_day", "7 天", "7d"],
+    ] as const) {
+      const w = rl[key] as Window;
+      if (w && w.utilization != null) rows.push({ label, short, percent: w.utilization, resetsAt: w.resets_at });
+    }
+  }
+  return { subscriptionType: res.subscription_type, rows };
+}
+
+async function fetchUsage(): Promise<ClaudeUsage | null> {
+  const res = await withProbe((q) =>
+    q.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET({ skipBehaviors: true }),
+  );
+  return normalize(res as Parameters<typeof normalize>[0]);
+}
+
+/**
+ * 同 Codex：缓存 60 秒，挡住连敲几次 /status，又不至于数字明显过期。
+ * 读不到额度不该让整条 /status 失败 —— 它只是其中几行，所以失败时给 null。
+ */
+export const readUsage = cachedProbe(60_000, "额度", fetchUsage, null);
+
+/** 距离重置还有多久，和 Codex 那边同一个说法 */
+function untilReset(resetsAt: string | null, now = Date.now()): string {
+  if (!resetsAt) return "";
+  const ms = Date.parse(resetsAt);
+  if (Number.isNaN(ms)) return "";
+  const seconds = Math.floor((ms - now) / 1000);
+  if (seconds <= 0) return "即将重置";
+  const days = Math.floor(seconds / 86400);
+  const hours = Math.floor((seconds % 86400) / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+  if (days > 0) return `${days} 天 ${hours} 小时后重置`;
+  if (hours > 0) return `${hours} 小时 ${minutes} 分后重置`;
+  return `${minutes} 分钟后重置`;
+}
+
+/** 侧栏用的结构化额度 */
+export function toQuota(usage: ClaudeUsage | null): QuotaInfo | null {
+  if (!usage || usage.rows.length === 0) return null;
+  return {
+    ...(usage.subscriptionType ? { plan: usage.subscriptionType } : {}),
+    windows: usage.rows.map((r) => {
+      const at = r.resetsAt ? Date.parse(r.resetsAt) : NaN;
+      return { label: r.label, short: r.short, percent: r.percent, ...(Number.isNaN(at) ? {} : { resetsAt: at }) };
+    }),
+    ...(usage.rows.some((r) => r.percent >= 100) ? { reached: true } : {}),
+  };
+}
+
+/** 渲染成 /status 里的几行；没有可显示的就返回空数组（API key / Bedrock 之类没有订阅额度） */
+export function describeUsage(usage: ClaudeUsage | null, now = Date.now()): string[] {
+  if (!usage || usage.rows.length === 0) return [];
+  const rows = usage.rows.map((r) => {
+    const reset = untilReset(r.resetsAt, now);
+    return `  ${r.label}　已用 ${Math.round(r.percent)}%${reset ? `　${reset}` : ""}`;
+  });
+  if (usage.rows.some((r) => r.percent >= 100)) rows.push("  ⚠️ 已达上限，等窗口重置后才能继续");
+  return [`额度${usage.subscriptionType ? `（${usage.subscriptionType}）` : ""}`, ...rows];
+}

package/src/agents/claude/driver.ts

@@ -0,0 +1,216 @@
+// Claude Code 驱动：官方 Claude Agent SDK。
+//
+// 会话列表 / 历史全部走 SDK 自带的 listSessions / getSessionInfo / getSessionMessages，
+// 不再自己去扒 ~/.claude/projects 下的 jsonl —— 那是 CLI 的内部约定，SDK 才是公开接口。
+import {
+  forkSession,
+  getSessionInfo,
+  getSessionMessages,
+  listSessions,
+} from "@anthropic-ai/claude-agent-sdk";
+import os from "node:os";
+import type { AgentCommand } from "../../core/command-catalog.js";
+import { config } from "../../core/config.js";
+import type {
+  AgentDriver,
+  AgentEvents,
+  AgentSession,
+  HistoryMessage,
+  InteractionHost,
+  ModelInfo,
+  QuotaInfo,
+  RuntimeInfo,
+  SessionOptions,
+  SessionSummary,
+} from "../../core/types.js";
+import { describeUsage, readUsage, toQuota } from "./account.js";
+import { cachedProbe, withProbe } from "./probe.js";
+import { diagnose } from "./errors.js";
+import { ClaudeSession, describeToolUse, summarize, toModelInfo } from "./session.js";
+
+/** 模型列表几乎不变，缓存 10 分钟；读失败抛给设置页，让它退回手填 */
+const readCatalog = cachedProbe(10 * 60_000, "模型列表", () => withProbe(async (q) => toModelInfo(await q.supportedModels())));
+
+/**
+ * 斜杠命令（skills、/compact 这些）。项目目录里可能有自己的命令，所以按 cwd 分开缓存；
+ * 装了新 skill 最多 5 分钟后出现。读不到就只显示 agent-loft 自己的命令。
+ */
+const commandReaders = new Map<string, () => Promise<AgentCommand[]>>();
+function readCommands(cwd: string): Promise<AgentCommand[]> {
+  let reader = commandReaders.get(cwd);
+  if (!reader) {
+    // 目录数量一般很少；万一很多，丢掉最早的，别无限涨
+    if (commandReaders.size >= 50) commandReaders.delete(commandReaders.keys().next().value!);
+    reader = cachedProbe(
+      5 * 60_000,
+      "Claude 命令列表",
+      () =>
+        withProbe(
+          async (q) =>
+            (await q.supportedCommands()).map((c) => ({
+              name: c.name,
+              description: c.description,
+              ...(c.argumentHint ? { args: c.argumentHint } : {}),
+            })),
+          cwd,
+        ),
+      [] as AgentCommand[],
+    );
+    commandReaders.set(cwd, reader);
+  }
+  return reader();
+}
+
+/** sessionId 会被拼进路径，先验形，防 /resume ../../x 越界 */
+const SESSION_ID = /^[A-Za-z0-9_-]{8,64}$/;
+
+function titleOf(info: { customTitle?: string; summary?: string; firstPrompt?: string }): string {
+  const raw = (info.customTitle || info.summary || info.firstPrompt || "").replace(/\s+/g, " ").trim();
+  if (!raw) return "(无标题)";
+  return raw.length > 60 ? `${raw.slice(0, 60)}…` : raw;
+}
+
+type Block = { type?: string; text?: string; name?: string; input?: unknown; thinking?: string };
+
+function blocksOf(message: unknown): Block[] {
+  const content = (message as { content?: unknown } | null)?.content;
+  if (typeof content === "string") return [{ type: "text", text: content }];
+  return Array.isArray(content) ? (content as Block[]) : [];
+}
+
+/** 用户消息里我们自己拼进去的附件说明，历史里只留一行简述 */
+function cleanUserText(text: string): string {
+  const cut = [text.indexOf("[用户通过飞书发来了以下附件"), text.indexOf("[用户发来了以下附件")]
+    .filter((i) => i >= 0)
+    .sort((a, b) => a - b)[0];
+  if (cut === undefined) return text;
+  const files = (text.slice(cut).match(/^- /gm) ?? []).length;
+  return `${text.slice(0, cut).trim()}${files ? `\n\n📎 ${files} 个附件` : ""}`.trim();
+}
+
+export class ClaudeDriver implements AgentDriver {
+  readonly id = "claude";
+  readonly label = "Claude Code";
+  readonly capabilities = { effort: true, fork: true, cost: true, streaming: true };
+
+  async start(): Promise<void> {}
+  async stop(): Promise<void> {}
+
+  createSession(opts: SessionOptions, events: AgentEvents, host: InteractionHost): AgentSession {
+    return new ClaudeSession(opts, events, host);
+  }
+
+  async listSessions(cwd: string | undefined, limit = 10): Promise<SessionSummary[]> {
+    try {
+      const sessions = await listSessions({ ...(cwd ? { dir: cwd } : {}), limit });
+      return sessions.map((s) => ({
+        id: s.sessionId,
+        title: titleOf(s),
+        ...(s.cwd ? { cwd: s.cwd } : {}),
+        updatedAt: s.lastModified,
+      }));
+    } catch (err) {
+      console.error("[claude] 读取会话列表失败:", err);
+      return [];
+    }
+  }
+
+  async sessionExists(id: string, cwd: string): Promise<boolean> {
+    if (!SESSION_ID.test(id)) return false;
+    try {
+      return !!(await getSessionInfo(id, { dir: cwd }));
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * 把会话记录整理成「一问一答」：用户一条，助手把这一轮所有文本拼成一条，
+   * 中间的工具调用作为过程摘要挂在助手那条上。工具结果（type=user 的 tool_result）
+   * 和子 agent 的消息不算对话。
+   */
+  async readHistory(id: string, cwd: string): Promise<HistoryMessage[]> {
+    if (!SESSION_ID.test(id)) return [];
+    const raw = await getSessionMessages(id, { dir: cwd });
+    const out: HistoryMessage[] = [];
+    let assistant: HistoryMessage | null = null;
+    const flush = () => {
+      if (assistant && (assistant.text.trim() || assistant.steps?.length)) out.push(assistant);
+      assistant = null;
+    };
+    for (const msg of raw) {
+      if (msg.parent_tool_use_id) continue;
+      const blocks = blocksOf(msg.message);
+      // 运行时带着 timestamp（ISO 字符串），类型声明里没有
+      const ts = Date.parse((msg as { timestamp?: string }).timestamp ?? "");
+      if (msg.type === "user") {
+        const texts = blocks.filter((b) => b.type === "text" && b.text).map((b) => b.text!);
+        if (texts.length === 0) continue; // 纯 tool_result
+        const text = cleanUserText(texts.join("\n"));
+        if (!text || text.startsWith("<command-") || text.startsWith("<local-command")) continue;
+        flush();
+        out.push({ role: "user", text, ...(Number.isFinite(ts) ? { ts } : {}) });
+      } else if (msg.type === "assistant") {
+        assistant ??= { role: "assistant", text: "", steps: [] };
+        // 这一轮最后一条助手消息：分叉到这里为止，时间也取它的
+        assistant.anchor = msg.uuid;
+        if (Number.isFinite(ts)) assistant.ts = ts;
+        for (const b of blocks) {
+          if (b.type === "text" && b.text?.trim()) {
+            assistant.text += (assistant.text ? "\n\n" : "") + b.text;
+          } else if (b.type === "tool_use" && b.name) {
+            assistant.steps!.push(`🔧 ${describeToolUse(b.name, b.input)}`);
+          } else if (b.type === "thinking" && b.thinking) {
+            const t = summarize(b.thinking);
+            if (t) assistant.steps!.push(`💭 ${t}`);
+          }
+        }
+      }
+    }
+    flush();
+    return out;
+  }
+
+  async forkAt(id: string, cwd: string, anchor?: string): Promise<string> {
+    if (!SESSION_ID.test(id)) throw new Error("会话 id 不对");
+    if (anchor) {
+      // 先确认这条回复在记录里：SDK 遇到不认识的 id 不一定报错，可能整条复制
+      const raw = await getSessionMessages(id, { dir: cwd });
+      if (!raw.some((m) => m.uuid === anchor)) throw new Error("在会话记录里找不到这条回复");
+    }
+    const res = await forkSession(id, { dir: cwd, ...(anchor ? { upToMessageId: anchor } : {}) });
+    return res.sessionId;
+  }
+
+  async listModels(session: AgentSession): Promise<ModelInfo[]> {
+    return (session as ClaudeSession).listModels();
+  }
+
+  catalog(): Promise<ModelInfo[]> {
+    return readCatalog();
+  }
+
+  commands(cwd?: string): Promise<AgentCommand[]> {
+    return readCommands(cwd ?? os.homedir());
+  }
+
+  async defaults(): Promise<RuntimeInfo> {
+    const c = config().agents.claude;
+    return {
+      ...(c.defaultModel ? { model: c.defaultModel } : {}),
+      ...(c.defaultEffort ? { effort: c.defaultEffort } : {}),
+    };
+  }
+
+  async statusLines(): Promise<string[]> {
+    return describeUsage(await readUsage());
+  }
+
+  async quota(): Promise<QuotaInfo | null> {
+    return toQuota(await readUsage());
+  }
+
+  diagnose(err: unknown) {
+    return diagnose(err);
+  }
+}