magpie-agent-console 0.1.0 → 1.0.0

package/README.md

@@ -1,115 +1,158 @@
 # Agent Console
 
-Magpie 窗口里的 Agent 控制台：驱动本机真实的 Agent CLI（Claude Code、Codex、Cursor、Copilot、OpenCode、Pi、Devin、dsh）。每个对话是一条**常驻 Agent 会话**，挂在独立的 Node daemon 上——关掉页面、刷新、重启 magpie，Agent 还在跑；重新打开就接回现场。
+A Magpie page plugin that drives real local Agent CLIs (Claude Code, Codex, Cursor, Copilot, OpenCode, Pi, Devin, dsh). Each conversation is a **persistent Agent session** on a standalone Node daemon. Close or refresh the page — the Agent keeps running while Magpie is open. Reopen the page and you pick up where you left off. When Magpie quits, the daemon and its Agents stop; threads are persisted and can be resumed next time.
 
-## 安装
+## Install
 
-需要 [Magpie](https://usemagpie.ai) ≥ 0.1.1340，以及本机 Node.js ≥ 20。
+Requires [Magpie](https://usemagpie.ai) ≥ 0.1.1340 and Node.js ≥ 20.
 
 ```bash
 magpie plugin add magpie-agent-console
 ```
 
-或在 Magpie：**设置 → 插件 → 添加插件**，填 `magpie-agent-console`。装好后侧栏插件分组会出现「Agent 控制台」。
+Or in Magpie: **Settings → Plugins → Add plugin**, enter `magpie-agent-console`. After install, **Agent Console** appears in the sidebar plugin group.
 
-本机要已安装你想用的 Agent CLI（如 `claude`、`codex`）。未安装的会在设置里显示安装提示。
+Install the Agent CLIs you want to use (for example `claude` or `codex`). Missing CLIs show an install hint in Settings.
 
 ---
 
-不是打网关的聊天框：daemon 通过 `@anthropic-ai/claude-agent-sdk` / `codex app-server` / ACP 持久连接真实 CLI，规范化结构化事件流（工具调用、思考、授权请求、用量），经 WebSocket 实时推给 React 页面。
+This is not a gateway chat box. The daemon talks to the real CLIs through `@anthropic-ai/claude-agent-sdk`, `codex app-server`, and ACP, normalizes a structured event stream (tool calls, thinking, permission requests, usage), and pushes it to the React page over WebSocket.
 
-不是打网关的聊天框：daemon 通过 `@anthropic-ai/claude-agent-sdk` / `codex app-server` 持久连接真实 CLI，规范化结构化事件流（工具调用、思考、授权请求、用量），经 WebSocket 实时推给 React 页面。
+UI principle: **obvious at a glance, nothing extra**. Three columns — sidebar (projects × threads), conversation timeline, and a right panel (changes / files / terminal).
 
-界面原则：**一眼就懂，没有多余的东西**。三列工作台——侧栏（项目×对话）、对话时间线、右侧面板（改动/文件/终端）。
+## Features
 
-## 功能
+- **Persistent sessions**: each thread binds to a long-lived Agent process; after a daemon restart, running threads are marked closed and can be resumed (`--resume` / `thread/resume`)
+- **Multiple Agents**: Claude Code, Codex, Cursor, Copilot, OpenCode, Pi, Devin, dsh; missing CLIs show an install hint
+- **Model / permission / thinking**: per-thread; four permission modes and five thinking levels (what each Agent actually supports)
+- **Structured timeline**: user message → thinking (expandable) → tool calls (read / edit / command, with line-level diffs) → todos → usage and duration; answer permission requests (tools / plan / questions) on the card
+- **Steer and queue**: steer while running, queue the next message, interrupt
+- **Changes panel**: git status refresh every 3s, unified per-file diffs; discarded untracked files go to trash instead of a hard delete
+- **Files panel**: lazy directory tree (respects `.gitignore`), syntax-highlighted preview
+- **Terminal panel**: real PTY via node-pty (pwsh / powershell); reconnects after reopening the page; degrades if PTY is unavailable
+- **Import history**: import matching sessions from `~/.claude/projects` and `~/.codex/sessions` as new threads (resumable)
+- **Thread management**: search (Ctrl+K), pin, rename, archive, delete (trash), export Markdown, thread info (usage / cost / session ID)
+- **Mock Agent**: `AGENT_CONSOLE_MOCK=1` registers a demo Agent with 8 scripts (`default` / `perm` / `plan` / `ask` / `slow` / `error` / `long` / `exit`) so UI work does not burn tokens
 
-- **常驻会话**：每个对话绑定一个持久 Agent 进程；daemon 重启后 running 对话标为已关闭并可一键续接（`--resume` / `thread/resume`）
-- **多 Agent**：Claude Code、Codex、Cursor、Copilot、OpenCode、Pi、Devin、dsh；未安装的显示安装提示
-- **模型/权限/思考强度**：每对话可改；权限四档（计划/默认/接受编辑/放开全部），思考强度五档
-- **结构化时间线**：用户消息 → 思考（可展开）→ 工具调用（读/改/跑命令，带行级 diff）→ 待办 → 用量与耗时；授权请求（工具/计划/提问）卡片内应答
-- **插话与排队**：运行中可 steer 插话、排队下一条、打断（interrupt）
-- **改动面板**：git status 实时刷新（3s），逐文件统一 diff，放弃改动（未跟踪文件移入回收区不硬删）
-- **文件面板**：目录树懒加载（遵守 .gitignore），文件预览带语法高亮
-- **终端面板**：node-pty 真终端（pwsh/powershell），重开页面可接回；无 PTY 时降级为简化模式
-- **导入历史**：把 `~/.claude/projects`、`~/.codex/sessions` 里与项目匹配的既有会话导入为新对话（可续接）
-- **会话管理**：搜索（Ctrl+K）、置顶、重命名、归档、删除（移回收目录）、导出 Markdown、对话信息（用量/费用/会话 ID）
-- **Mock Agent**：`AGENT_CONSOLE_MOCK=1` 注册演示 Agent，8 个剧本（默认/perm/plan/ask/slow/error/long/exit）联调 UI 不烧 token
-
-## 架构
+## Architecture
 
 ```
-magpie 插件页（sandbox iframe，opaque origin）
-      │ location.replace → http://127.0.0.1:3488
-      ▼
-index.mjs           插件入口：ensureDaemon——读 daemon.json、pid 存活检查、
-                    ping 校验、复用或 spawn 新 daemon；端口迁移时优雅重启
-      │
-daemon/             独立 Node 进程（默认端口 3488，数据目录 ~/.config/magpie/agent-console）
-  http.ts           静态文件 + /api/ping + /api/upload；Host/Origin/页面令牌校验
-  ws/gateway.ts     /ws：hello 鉴权、req/res 方法分派、订阅频道推送、二进制终端帧
-  ws/methods.ts     zod 校验的全部方法（projects/threads/settings/git/files/history/terminal…）
-  agents/manager.ts 会话运行时：send/steer/queue/interrupt、授权 pending、coalescer（60ms 合并 delta）、
-                    崩溃补 turn_ended、空闲回收、重启恢复
-  providers/        claude（SDK）+ codex（app-server）+ mock；detect/listModels/createSession
-  store/            projects/threads/settings/attachments：json + jsonl，串行写队列，原子落盘
-  terminal/         node-pty 终端池（≤8/项目），环形缓冲 + 16ms 合并推送
-  git/ files/       改动状态/diff/放弃；目录树/文件读取
-  history/          Claude/Codex 历史会话扫描与导入
-      │ WebSocket（文本帧 req/res/evt + 二进制终端帧）
-      ▼
-web/src → app/      React 19 + zustand 前端：三列布局、虚拟化时间线、
-                    xterm 终端、diff 渲染、marked+dompurify Markdown
+Magpie window
+ └─ page/index.html  (sandbox="allow-scripts" iframe, served by Magpie from /_magpie/plugin/<per-run id>/)
+     │ reads page/session.js  {port, key}  (gate key only, written by the plugin host)
+     │ navigates itself to  http://127.0.0.1:<port>/open?k=<key>&theme=…
+     ▼
+Magpie plugin host (Bun) ── index.mjs + lib/gate.mjs  "gate" on 127.0.0.1:<port> (default 3488)
+     │ first /open: spawns the daemon as a child process (node, --port 0, stdin lifeline, --parent-pid)
+     │ 302 → http://127.0.0.1:<daemonPort>/?theme=…#t=<token>
+     ▼
+daemon (Node, daemon/dist/main.js) ── HTTP + WebSocket on an ephemeral 127.0.0.1 port
+     └─ React app (app/) reads the token from location.hash, sends it as the x-agent-console header
+        and in the WebSocket hello
+```
+
+## Security model
+
+The daemon can run Agents with full access to your machine, so the token that unlocks it must never be readable by another web page.
+
+- **Two secrets per plugin-host run.** Each run generates two independent random 256-bit values: a **gate key** and the **daemon token**. Only the gate key is ever written to a file.
+- **Why `session.js` holds only the gate key.** Magpie serves the page folder at `/_magpie/plugin/<per-run id>/`, where the id is an HMAC that changes every time Magpie starts and is handed out only to Magpie's own window. Magpie does not check `Origin`, `Host`, `Sec-Fetch-*` or a cookie on these files, and sends no `Cross-Origin-Resource-Policy`, so the unguessable path is their only protection. A classic `<script src>` include is not subject to CORS, so any page that learned the path (a different localhost port, a `file:` page, any website) could run `session.js` and read `globalThis.AgentConsoleSession`. That is why the file never contains the daemon token.
+- **Token handoff.** After the gate binds its port, the host writes `{port, key}` to `page/session.js` (atomic write, mode 0600; git-ignored and excluded from the npm package). The page navigates to the gate's `/open?k=<key>`; the gate compares the key in constant time, starts or reuses the daemon and redirects to it with the daemon token **only in the URL fragment** (`#t=…`). The fragment is never sent to a server, written to a log, or leaked through `Referer`, and the window that ends up holding it belongs to the daemon's origin (an opaque origin inside Magpie's sandboxed frame), so the page that started the navigation cannot read it. A leaked gate key therefore lets another page at most open the console UI in a frame or tab it cannot read; it does not unlock the daemon's API or WebSocket. No HTML served by the daemon contains the token; an unauthenticated `GET /` returns a page with no secret in it.
+- **`Origin: null` is not trusted.** Any site can produce `Origin: null` (sandboxed iframes, `data:` and `file:` pages). The token is the only authority:
+  - static routes (`/`, `app.js`, …) refuse `Origin: null` and foreign origins with 403 and never send CORS headers;
+  - token routes (`/api/*`, `/attachments/*`, WebSocket hello) accept `Origin: null` only as a way to *present* the token (the Magpie iframe has an opaque origin); `access-control-allow-origin: null` is emitted only on responses to requests that carried a valid token, plus the preflight for `/api/upload`; credentials are never allowed;
+  - any other origin gets 403 even with a valid token.
+- **Host is checked on every request and WebSocket upgrade** (gate and daemon): it must be `127.0.0.1:<port>` or `localhost:<port>` with the actually bound port, otherwise 421. This blocks DNS rebinding, where the attacker's requests carry no `Origin` at all.
+- The gate answers only `GET /open?k=<gate key>` (the daemon token is not accepted there), refuses any request that carries an `Origin` header, and sends `Cache-Control: no-store`, `X-Content-Type-Options: nosniff`, `Referrer-Policy: no-referrer`.
+- WebSocket connections must send `hello` with the token within 5 seconds, otherwise they are closed with code 4401.
+
+## Lifecycle
+
+- Importing `index.mjs` has no side effects (no port, no process, no files).
+- `server()` (called by Magpie's plugin host at host start-up — this includes short-lived hosts started by CLI commands such as `magpie plugin add` or `magpie plugin list`) binds the gate and writes `page/session.js`. If the port is busy it retries every 2 s in the background without blocking the host; a detached 0.1.0 daemon still holding the port is shut down once, only after it proves its identity by answering `/api/ping` with the token from `daemon.json`.
+- The daemon starts when the page is opened for the first time and is reused for later opens. It is a normal (non-detached) child of the plugin host.
+- The daemon exits when its stdin pipe closes or its parent pid disappears (checked every 2 s) — i.e. when Magpie quits or the plugin host restarts — and after 60 minutes idle.
+- Magpie's plugin host treats the value returned by `server()` as OpenCode hooks and never calls `stop()`; it exits the Bun process when Magpie closes its stdin. A synchronous `exit` handler therefore closes the daemon's lifeline, signals it, and removes the `session.js` this host wrote. `stop()` (used by tests and other hosts) closes the gate, ends the daemon (graceful, then forced) and removes `session.js`.
+- Agents stop with the daemon. Threads are persisted and can be resumed after reopening the page. On macOS/Linux every Agent CLI, the Codex app-server and the no-PTY shell run in their own process group, so stopping one ends everything it started; on Windows the same is done with `taskkill /T`. A process `exit` hook reaps any tree still alive when the daemon exits.
+
+## Platforms
+
+The plugin runs wherever Magpie runs (Windows, macOS, Linux). It needs **Node.js 20+** on `PATH`: Magpie's plugin host is Bun, but the daemon and `node-pty` need Node. If Node is missing, opening the page shows "Node.js was not found" (the gate's 503 page) instead of silently running under Bun; a too-old Node gives a similar message.
+
+- **Finding Agent CLIs.** `PATH` is scanned in JavaScript (no `where.exe`/`which`; `where.exe` prints in the console code page, which garbled Chinese user names). The first hit in `PATH` order wins. Common install dirs are also searched because a GUI app may start with a minimal `PATH` (Magpie adds the login-shell `PATH` itself; this is a fallback): Homebrew (`/opt/homebrew/bin`, `/usr/local/bin`), `~/.local/bin`, npm global, Volta, Bun, `~/.claude/local`, `%APPDATA%\npm`.
+- **Windows shims.** `.exe` runs directly; npm `.cmd` shims run their `cli.js` with Node; `.ps1`-only shims run with `powershell -NoProfile -ExecutionPolicy Bypass -File`; any other `.cmd`/`.bat` runs through `cmd.exe` with cross-spawn-style escaping (spaces, `&`, `%`, quotes and Chinese in paths and arguments are safe).
+- **Terminal.** `node-pty` prebuilds cover win32/darwin/linux × x64/arm64 (Linux prebuilds are glibc only). Default shell: Windows `pwsh` → `powershell` → `cmd`; macOS/Linux `$SHELL` if it exists, else `zsh` (macOS) / `bash` / `sh`. If `node-pty` cannot load, a simple non-PTY terminal is used. On macOS the exec bit of `node-pty`'s `spawn-helper` is restored if the package extraction dropped it.
+- **Folder picker.** Windows: PowerShell `FolderBrowserDialog`; macOS: `osascript` "choose folder"; Linux: `zenity` or `kdialog` when a graphical session exists; otherwise type the path.
+- **Paths.** Project paths are compared case-insensitively on Windows and macOS (and NFC-normalized on macOS); `realpath.native` resolves 8.3 short names and `subst` drives; UNC paths work. Discarding an untracked file moves it to the trash with a copy fallback when the project and data dir are on different drives.
+- **Encoding.** Agent output is decoded as UTF-8; the folder picker falls back to GBK (CP936); the file preview tries UTF-8, then GBK. Git runs with `core.quotepath=false` so Chinese file names show as-is.
+- **Magpie desktop window → `http://127.0.0.1`.** Magpie's window origin is `wails://` on macOS/Linux and `http://wails.localhost` on Windows. The plugin frame navigates itself to the gate on `http://127.0.0.1`, as Magpie's plugin-runtime docs describe for page plugins. On macOS, Magpie's `Info.plist` has no ATS keys and ATS exempts IP-address hosts by default, and the main window has no CSP that could block the frame, so the navigation is allowed. This is the one item that still needs a run on a real Mac.
+- **Clickjacking / `frame-ancestors`.** Not set on purpose. The UI must load inside Magpie's frame on every mode: `wails://` (a non-special scheme whose origin WebKit may treat as opaque), `http://wails.localhost`, and `magpie web` on any address, LAN IP or reverse proxy. No `frame-ancestors` list covers all of them without breaking one. Framing the console also requires the gate key, which only Magpie's per-run page path hands out.
+
+## Reproducible build
+
+`app/app.js`, `app/app.css`, `app/index.html`, `daemon/dist/main.js` and `daemon/dist/main.js.map` are committed build outputs of `web/src` and `daemon/src` (esbuild, options in `scripts/build-v1.mjs`). The build is deterministic: no timestamps, no absolute paths, LF line endings enforced by `.gitattributes`.
+
+```bash
+npm ci
+npm run build
+git diff --exit-code app daemon/dist   # no output = identical bytes
+npm run verify:build                   # rebuilds into a temp dir, byte-compares, prints SHA-256
 ```
 
-## 安全模型
+`verify:build` prints `OK <sha256>  <file>` for each bundle and exits non-zero on any mismatch.
 
-magpie 的插件页是 `sandbox="allow-scripts"` iframe，跳走后是 opaque origin（`Origin: null`）——靠 Origin 区分不了"真 UI"和恶意 iframe：
+## Dependencies
 
-- daemon 启动时生成随机页面令牌，写进 `daemon.json`；返回 index.html 时注入 `<meta>`，前端所有请求带 `x-agent-console: <token>`，不符 403/4401
-- Host 必须是 `127.0.0.1:<port>`/`localhost:<port>`，否则 421（防 DNS rebinding）；静态响应不带 `access-control-allow-origin`
-- WS hello 5 秒内必须鉴权；终端输入帧只在订阅 `terminal:<index>` 后才接受
+All dependencies and devDependencies are pinned to exact versions, and `package-lock.json` matches them (`npm ci` succeeds). Runtime dependencies: `@agentclientprotocol/sdk`, `@anthropic-ai/claude-agent-sdk`, `@tanstack/react-virtual`, `@xterm/addon-fit`, `@xterm/xterm`, `clsx`, `dompurify`, `highlight.js`, `ignore`, `lucide-react`, `marked`, `node-pty`, `react`, `react-dom`, `ws`, `zod`, `zustand` (most of the UI packages are bundled into `app/app.js`; the daemon loads its packages from `node_modules`).
 
-## 数据目录
+- `node-pty` is a native module and ships prebuilt binaries. Magpie installs plugins with install scripts disabled; if the binary cannot load, the terminal panel degrades to a simple non-PTY terminal.
+- `@anthropic-ai/claude-agent-sdk` is distributed under Anthropic's commercial terms.
+
+## Data directory
 
 ```
-$XDG_CONFIG_HOME/magpie/agent-console/   （默认 ~/.config/magpie/agent-console）
-  daemon.json          pid/port/token/version（插件入口据此复用）
-  settings.json        设置（默认 Agent/权限/发送键/面板宽度…）
-  projects.json        项目列表
-  threads/<id>/        meta.json + timeline.jsonl（事件持久化，重连补推）
-  attachments/         上传的附件
-  trash/               删除的对话与放弃的新文件（不硬删）
-  logs/                按天滚动日志（留 7 天）
+$XDG_CONFIG_HOME/magpie/agent-console/   (default ~/.config/magpie/agent-console on every OS;
+                                           on Windows ~ is %USERPROFILE%, the same root Magpie uses)
+  daemon.json          pid/port/token/version of the running daemon (mode 0600)
+  settings.json        settings (default Agent / permission / send key / panel widths…)
+  projects.json        project list
+  threads/<id>/        meta.json + timeline.jsonl (event persistence, replay on reconnect)
+  attachments/         uploaded files
+  trash/               deleted threads and discarded new files (not hard-deleted)
+  logs/                daily rotating logs (kept 7 days); logs/daemon-spawn.log has the plugin host's view
 ```
 
-## 开发
+Magpie in portable mode keeps its own config next to the executable, but this plugin still uses the directory above (it follows `XDG_CONFIG_HOME`).
+
+## Development
 
 ```bash
-npm run build      # daemon esm + web iife（app/ 四件套；daemon/dist 也提交）
-npm run dev        # 起 daemon：端口 3499、数据目录 _tmp/xdg-dev（不碰真实数据）
-npm run check      # 双 tsconfig 类型检查
-npm test           # vitest 单测（test/v1 + web/src）
-npm run e2e:v1     # 端到端：spawn daemon(3497)+Edge CDP 全场景（Mock Agent）
-npm run shot:v1    # 截图集（亮/暗 × 各场景 → _tmp/shots-v1/）
-
-# Mock 联调（不烧真 token）
+npm run build      # daemon esm + web iife (app/ and daemon/dist are committed)
+npm run verify:build  # check committed bundles match a clean build
+npm run dev        # daemon on port 3499, data dir _tmp/xdg-dev (does not touch real data)
+npm run check      # typecheck both tsconfigs
+npm test           # vitest (test/v1 + web/src)
+npm run e2e:v1     # e2e: spawn daemon(3497) + Edge/Chrome/Chromium, Mock Agent (MSEDGE_PATH / CHROME_PATH to override)
+node scripts/verify-windows.mjs [--quick]   # one-command platform self-check, see docs/VERIFY-windows.md
+npm run shot:v1    # screenshot set (light/dark × scenes → _tmp/shots-v1/)
+
+# Mock (no real tokens)
 AGENT_CONSOLE_MOCK=1 npm run dev
-# 剧本：默认 /perm /plan /ask /slow /error /long(5000 事件压测) /exit
+# scripts: default /perm /plan /ask /slow /error /long (5000-event stress) /exit
 ```
 
-| 环境变量 | 作用 |
+| Env | Purpose |
 |---|---|
-| `AGENT_CONSOLE_PORT` | daemon 默认端口（默认 3488；插件 options.port 优先） |
-| `AGENT_CONSOLE_MOCK=1` | 注册 mock provider |
-| `AGENT_CONSOLE_TOKEN` | 固定页面令牌（测试/截图用，生产不要设） |
-| `AGENT_CONSOLE_IDLE_EXIT_MIN` | 空闲自动退出分钟数（默认 60） |
-| `XDG_CONFIG_HOME` | 数据根目录（开发用 `_tmp/xdg-dev`） |
+| `AGENT_CONSOLE_PORT` | gate port in the plugin / daemon port in standalone mode (3488; plugin `options.port` wins) |
+| `AGENT_CONSOLE_MOCK=1` | register the mock provider |
+| `AGENT_CONSOLE_TOKEN` | fixed page token (tests/screenshots only; do not set in production) |
+| `AGENT_CONSOLE_IDLE_EXIT_MIN` | idle auto-exit minutes (default 60) |
+| `XDG_CONFIG_HOME` | data root (`_tmp/xdg-dev` in development) |
 
-daemon CLI：`node daemon/dist/main.js [--port N] [--data DIR] [--token T]`。
+Daemon CLI: `node daemon/dist/main.js [--port N|0] [--data DIR] [--token T] [--parent-pid PID]`. In standalone mode (no `--parent-pid`) it prints the URL to open, `http://127.0.0.1:<port>/#t=<token>`, to the console.
 
-## 依赖与许可证
+## License
 
-本插件 MIT（见 LICENSE）。第三方依赖许可证见 THIRD-PARTY-NOTICES.md：运行时 16 个包（多为 MIT；dompurify MPL-2.0/Apache-2.0、highlight.js BSD-3-Clause、lucide-react ISC；`@anthropic-ai/claude-agent-sdk` 为 Anthropic 商用条款），构建/测试依赖 esbuild/vitest/typescript/playwright-core。
+MIT (see LICENSE). Third-party licenses are in THIRD-PARTY-NOTICES.md: 16 runtime packages (mostly MIT; DOMPurify MPL-2.0/Apache-2.0, highlight.js BSD-3-Clause, lucide-react ISC; `@anthropic-ai/claude-agent-sdk` is Anthropic's commercial terms). Build/test: esbuild, vitest, TypeScript, playwright-core.
 
-架构设计参考了 Paseo（常驻 daemon + provider 抽象）与 T3 Code（时间线形态与三列布局）——仅参考思路，未复制代码。
+Architecture takes cues from Paseo (persistent daemon + provider abstraction) and T3 Code (timeline shape and three-column layout) — ideas only, no copied code.

package/THIRD-PARTY-NOTICES.md

@@ -1,22 +1,24 @@
-# 第三方声明
+# Third-Party Notices
 
-## 设计参考
+## Design references
 
-本插件 v1.0 的常驻会话架构、事件协议与界面布局在设计时参考了以下开源项目
-（仅参考设计思路与协议形态，未复制源代码）：
+The persistent-session architecture, event protocol and UI layout of this plugin were designed
+with reference to the following open-source projects (only design ideas and protocol shapes were
+referenced; no source code was copied):
 
-- **Paseo**（https://github.com/anthropics/paseo 类项目，Apache-2.0）
-  —— 常驻 daemon + WebSocket 事件推送、provider 会话抽象的思路。
-- **T3 Code**（https://github.com/pingdotgg/t3code 类项目，MIT）
-  —— 时间线条目形态（工具组、授权卡片、计划卡片）与三列工作台布局。
+- **Paseo** (https://github.com/getpaseo/paseo)
+  — persistent daemon + WebSocket event push, and the provider session abstraction.
+- **T3 Code** (https://github.com/pingdotgg/t3code, MIT)
+  — timeline item shapes (tool groups, permission cards, plan cards) and the three-column workbench layout.
 
-## npm 依赖及其许可证
+## npm dependencies and their licenses
 
-运行时依赖（`dependencies`）：
+Runtime dependencies (`dependencies`):
 
-| 包 | 版本 | 许可证 |
+| Package | Version | License |
 |---|---|---|
-| @anthropic-ai/claude-agent-sdk | 0.3.312 | SEE LICENSE IN README.md（Anthropic 商用条款） |
+| @agentclientprotocol/sdk | 2.1.0 | Apache-2.0 |
+| @anthropic-ai/claude-agent-sdk | 0.3.312 | SEE LICENSE IN README.md (Anthropic commercial terms) |
 | @tanstack/react-virtual | 3.14.24 | MIT |
 | @xterm/addon-fit | 0.11.0 | MIT |
 | @xterm/xterm | 6.0.0 | MIT |
@@ -33,10 +35,10 @@
 | zod | 4.6.7 | MIT |
 | zustand | 5.0.16 | MIT |
 
-开发依赖（`devDependencies`，不随发布包分发构建产物以外的内容）：
-typescript（Apache-2.0）、esbuild（MIT）、vitest（MIT）、playwright-core（Apache-2.0）、
-@types/*（MIT）。
+Development dependencies (`devDependencies`; nothing from them ships except the built output):
+typescript (Apache-2.0), esbuild (MIT), vitest (MIT), playwright-core (Apache-2.0),
+@types/* (MIT).
 
-Codex app-server 的 JSON-RPC schema 文件（`daemon/src/providers/codex/schema/`）由
-`codex app-server generate-json-schema` 在本机生成，属于 OpenAI Codex CLI 的接口描述，
-按 Codex 的许可证使用；插件仅将其用于协议对接。
+The Codex app-server JSON-RPC schema files (`daemon/src/providers/codex/schema/`) are generated
+locally by `codex app-server generate-json-schema`. They describe the OpenAI Codex CLI interface
+and are used under the Codex license; the plugin uses them only for protocol integration.