@aiti-ai/aiti-claude-code-agent 0.0.0-stage → 0.1.8

package/AGENTS.md

@@ -0,0 +1,32 @@
+# aiti-claude-code-agent 扩展（部署目录直改指南）
+
+## 结构
+- 运行时文件平铺在本目录根（index.ts / core.cjs …，宿主 loader 按相对路径加载——**禁手改运行时平铺文件**，改 src/ 再 build）
+- `src/` 源码（client/src + 服务端 ts/cjs）· `dist/` 构建产物（禁手改）· `tools/` 构建/部署脚本
+- npm 包形态的扩展：本目录 package.json 含 version 与 aitiConfigs 声明
+
+## 小改现场流程（改文案/样式/小逻辑）
+1. 改 `src/` 下对应源码
+2. `node tools/build.mjs`（client 有构建产物的扩展；纯服务端改动跳过）
+3. `curl -X POST http://127.0.0.1:3001/api/extensions/reload`（dev；prod 3002；外部经 nginx 带 basePath：/dev、/mac、/mdev、/win、/wdev → `/xxx/api/extensions/reload`）
+4. 浏览器刷新页面验证
+
+## 大改回源码仓
+- 源码仓：`extensions/aiti-claude-code-agent/`（git 管理，deploy 同步回本目录）
+- 改完在源码仓跑 `node tools/deploy.mjs`（或仓库根 `node scripts/deploy-all.mjs --only aiti-claude-code-agent`）
+
+## 数据目录（数据分层：config / cache）
+- `ctx.configDir` 根级 = 配置与关键小状态（aiti-configs 备份范围；小、珍贵、人可读）
+- `ctx.cacheDir`（= `<configDir>/cache/`）= 可删缓存：db/venv/日志/大文件；rm -rf 后扩展下次访问自动重建
+- `ctx.dataDir` 已移除（访问即抛）——新代码禁用
+- 本扩展白名单（永不为 cache 的配置文件）见 package.json `aitiConfigs.configFiles`
+
+## 红线
+- 禁轮询（setInterval 拉取）；需要等待用事件/回调/SSE（桥的 SSE、aiti-event-bus topics）
+- 禁重启生产服务（pi-web 3002 等 restart 须用户明确同意）
+- 禁手改 dist/ 与运行时平铺文件；跨扩展通信走 ctx.services（禁 globalThis.__ext 直穿）
+- 服务端：SQLite 一律 WAL + 分批小事务（批间 setImmediate 让步）；禁 execFileSync 调 >1s 外部程序；>8MB 文件禁同步读
+
+## 账号档 / 额度对接
+- 本扩展已 provide `<extId>.agent` 描述符（账号档槽位）与 `accountQuota` 额度出口 `GET /login/quota`。
+  接入契约 / 现状待办 / 平台坑（.mjs reload 缓存）→ `docs/pi-web-ext-agent-account-contract.md`。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aiti-ai contributors
+
+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,39 @@
-# Temporary Holding Version
+# @aiti-ai/aiti-claude-code-agent
 
-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.
+> 驱动 Claude Code CLI 会话 —— 从 All Sessions 恢复历史行（agentKey: claude）；claude 2.1.318+ keyring 凭据三级裁决登录态
+
+## 来源 · Origin
+
+本包是 **aiti** 生态的组成部分——以 [pi](https://pi.dev) 为引擎的个人 AI 开发工作台与本地调试注入生态：**aiti-agent**（自托管 Web 工作台，基于开源项目 [pi-web](https://github.com/aiti-ai/pi-web) 构建，浏览器为主操作面）+ 各开发工具内的调试注入（aiti-devtools）+ 丰富的扩展体系。
+
+This package is part of the **aiti** ecosystem — a personal AI development workbench powered by [pi](https://pi.dev): **aiti-agent** (a self-hosted web workbench built on the open-source [pi-web](https://github.com/aiti-ai/pi-web)) plus debug injection into mainstream dev tools (aiti-devtools) and a rich extension system.
+
+- 工作台 / workbench: <https://github.com/aiti-ai/pi-web>
+- 生态仓库 / monorepo: <https://github.com/aiti-ai/aiti-ai>
+- 官网 / site: <https://aiti.pw>
+
+## 功能定位（中文）
+
+驱动 Claude Code CLI 会话 —— 从 All Sessions 恢复历史行（agentKey: claude）；claude 2.1.318+ keyring 凭据三级裁决登录态
+
+多 agent 后端 · tags: `claude-code` · `cli` · `session` · `multi-agent`
+
+## Positioning (English)
+
+Drives Claude Code CLI sessions — restores history rows from All Sessions (agentKey: claude); claude 2.1.318+ keyring credentials with a three-tier login-state adjudication
+
+## 安装 / 部署
+
+```bash
+# 部署到 ~/.pi/web/extensions/aiti-claude-code-agent/ 后 reload
+```
+
+## 文档 · Documentation
+
+- 中文完整文档（aiti-docs）: <https://aiti.pw/extensions/aiti-claude-code-agent.html>
+- English docs: <https://aiti.pw/en/extensions/aiti-claude-code-agent.html>
+- 扩展注册表 / registry: <https://aiti.pw/extensions.html> · machine-readable <https://aiti.pw/extensions.json>
+
+## License
+
+MIT

package/claude-handle.test.mjs

@@ -0,0 +1,236 @@
+/**
+ * aiti-claude-code-agent — handle 单测（D4 权限记录 / D5 工具直播卡 / followUp 队列）。
+ *
+ * 用假 child（stdout = PassThrough，stdin.write 捕获）直驱 handle，钉死：
+ *   1. can_use_tool → permission_request 事件 + 🔐 pending 记录进 liveHistory（D4）；
+ *   2. respondPermission → control_response 写回 + 决策记录（D4）；
+ *   3. result 帧收口未决授权 → cancelled 记录 + agent_settled + 队列续轮（D4/D11）；
+ *   4. assistant tool_use → liveHistory 原生 toolCall 块 + 原生直播条目（方案 X）；
+ *   5. user tool_result → 原生 toolResult 条目（liveHistory + 直播，折叠配对，方案 X）；
+ *   6. 运行中 prompt → 本地队列（queue_update），result 后自动续轮（D3/D11 探针定论）。
+ *
+ * Run: node --experimental-strip-types --test pi-web-ext/aiti-claude-code-agent/claude-handle.test.mjs
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+import { PassThrough } from "node:stream";
+
+const { ClaudeCodeHandle } = await import("./index.ts");
+
+/** 假 child + 订阅事件捕获。 */
+function makeHandle(id = "claude:new-test") {
+  const stdout = new PassThrough();
+  const stdinWrites = [];
+  const child = {
+    stdout,
+    stderr: { on() {} },
+    once() {},
+    stdin: { write: (s) => { stdinWrites.push(s); return true; }, writable: true },
+    kill() {},
+    exitCode: null,
+  };
+  const h = new ClaudeCodeHandle(id, child, "/tmp", undefined, "claude");
+  const events = [];
+  h.subscribe((e) => events.push(e));
+  const write = (frame) => stdout.write(JSON.stringify(frame) + "\n");
+  return { h, events, stdinWrites, write };
+}
+
+const flush = () => new Promise((r) => setTimeout(r, 2));
+const customs = (events, type) => events.filter((e) => e.type === "message_end" && e.message?.customType === type);
+const historyCustoms = (h, type) => h.liveHistory.filter((m) => m?.role === "custom" && m.customType === type);
+const messageEnds = (events, role) => events.filter((e) => e.type === "message_end" && e.message?.role === role);
+const historyRoles = (h, role) => h.liveHistory.filter((m) => m?.role === role);
+
+test("D4: can_use_tool → permission_request + 🔐 pending 记录", () => {
+  const { h, events, write } = makeHandle();
+  write({ type: "control_request", request_id: "toolu_1", request: { subtype: "can_use_tool", tool_name: "Bash", input: { command: "ls -la" } } });
+  const req = events.find((e) => e.type === "permission_request");
+  assert.equal(req?.toolName, "Bash");
+  const pending = historyCustoms(h, "🔐 工具授权");
+  assert.equal(pending.length, 1);
+  assert.match(pending[0].content, /Bash/);
+  assert.match(pending[0].content, /ls -la/);
+  assert.match(pending[0].content, /⏳ 等待授权/);
+  assert.equal(pending[0].details.requestId, "toolu_1");
+});
+
+test("D4: respondPermission → control_response 写回 + 决策记录", () => {
+  const { h, events, stdinWrites, write } = makeHandle();
+  write({ type: "control_request", request_id: "toolu_2", request: { subtype: "can_use_tool", tool_name: "Write", input: { path: "a.txt" } } });
+  return h.respondPermission("toolu_2", { behavior: "deny", message: "too risky" }).then((ok) => {
+    assert.equal(ok, true);
+    const resp = stdinWrites.find((s) => s.includes("control_response"));
+    assert.ok(resp, "应写回 control_response");
+    assert.ok(resp.includes('"behavior":"deny"') || resp.includes('"behavior": "deny"'), "deny 应答");
+    const decided = historyCustoms(h, "🔐 工具授权");
+    assert.equal(decided.length, 2, "pending + decision 两条");
+    assert.match(decided[1].content, /⛔ 已拒绝/);
+    assert.match(decided[1].content, /too risky/);
+  });
+});
+
+test("D4: result 帧收口未决授权 → cancelled 记录 + settled + 队列续轮", async () => {
+  const { h, events, stdinWrites, write } = makeHandle();
+  write({ type: "control_request", request_id: "toolu_3", request: { subtype: "can_use_tool", tool_name: "Bash", input: {} } });
+  // 运行中排入一条 followUp（result 后应自动续轮）
+  await h.prompt("first");
+  const p2 = h.prompt("second", { streamingBehavior: "followUp" });
+  await p2;
+  await flush();
+  assert.deepEqual(events.filter((e) => e.type === "queue_update").at(-1)?.followUp, ["second"]);
+
+  write({ type: "result", subtype: "success", is_error: false, result: "done" });
+  await flush();
+  const cancelled = historyCustoms(h, "🔐 工具授权").filter((m) => m.content.includes("已取消"));
+  assert.equal(cancelled.length, 1, "未决授权应记取消");
+  assert.ok(events.some((e) => e.type === "agent_settled"), "result 应发 settled");
+  await flush();
+  const userTurn2 = stdinWrites.filter((s) => s.includes("Reply") || s.includes("second"));
+  assert.ok(userTurn2.some((s) => JSON.parse(s).message.content[0].text === "second"), "result 后应自动续轮发出 second");
+});
+
+test("方案 X: assistant tool_use → liveHistory 原生块 + 原生 toolCall 直播条目（无双卡）", () => {
+  const { h, events, write } = makeHandle();
+  write({ type: "assistant", message: { model: "claude-sonnet-4-5", content: [
+    { type: "tool_use", id: "tc_1", name: "Bash", input: { command: "pwd" } },
+  ] } });
+  const toolCallMsg = h.liveHistory.find((m) => m?.role === "assistant" && Array.isArray(m.content) && m.content.some((b) => b.type === "toolCall"));
+  assert.ok(toolCallMsg, "liveHistory 应有原生 toolCall 块");
+  const live = messageEnds(events, "assistant").filter((e) => (e.message.content ?? []).some((b) => b.type === "toolCall"));
+  assert.equal(live.length, 1, "原生 toolCall 直播条目恰好一条");
+  assert.equal(live[0].message.content[0].toolCallId, "tc_1");
+  assert.equal(live[0].message.content[0].toolName, "Bash");
+  assert.equal(live[0].message.model, "claude-sonnet-4-5");
+  assert.equal(events.some((e) => e.type === "message_end" && e.message?.customType === "🛠 工具调用"), false, "不再发 🛠 custom 卡");
+});
+
+test("方案 X: user tool_result → 原生 toolResult 条目（liveHistory + 直播，错误标记保真）", () => {
+  const { h, events, write } = makeHandle();
+  write({ type: "assistant", message: { content: [{ type: "tool_use", id: "tc_2", name: "Bash", input: { command: "false" } }] } });
+  write({ type: "user", message: { content: [{ type: "tool_result", tool_use_id: "tc_2", is_error: true, content: [{ type: "text", text: "exit 1" }] }] } });
+  const live = messageEnds(events, "toolResult");
+  assert.equal(live.length, 1, "原生 toolResult 直播条目");
+  assert.equal(live[0].message.toolCallId, "tc_2");
+  assert.equal(live[0].message.toolName, "Bash", "toolName 由 toolCallOpen 回填");
+  assert.equal(live[0].message.isError, true);
+  assert.match(live[0].message.content[0].text, /exit 1/);
+  const hist = historyRoles(h, "toolResult");
+  assert.equal(hist.length, 1, "toolResult 进 liveHistory（refetch 可折叠配对）");
+  assert.equal(hist[0].toolCallId, "tc_2");
+  assert.equal(events.some((e) => e.type === "message_end" && e.message?.customType === "❌ 工具失败"), false, "不再发 ❌ custom 卡");
+});
+
+test("followUp 能力方法 + queueManage（D2/D3 契约）", async () => {
+  const { h, events } = makeHandle();
+  await h.prompt("first");
+  await h.followUp("queued-a");
+  await h.followUp("queued-b");
+  await flush();
+  assert.deepEqual(events.filter((e) => e.type === "queue_update").at(-1)?.followUp, ["queued-a", "queued-b"]);
+  const list = await h.queueManage({ action: "list" });
+  assert.deepEqual(list.followUp, ["queued-a", "queued-b"]);
+  const recalled = await h.queueManage({ action: "recall", index: 0 });
+  assert.equal(recalled.entry.text, "queued-a");
+  assert.equal(h.capabilities.followUp, true);
+  assert.equal(h.capabilities.queueManage, true);
+  assert.throws(() => h.steer(), /not supported/);
+});
+
+// ---- 加固回归（docs/pi-web-ext-agent-family-hardening-plan.md 阶段 1/2）-----------
+
+test("加固 A4: stdin.write 返回 false（背压）≠ 失败——大帧 prompt 不再误报 stdin closed", async () => {
+  const stdout = new PassThrough();
+  const child = {
+    stdout,
+    stderr: { on() {} },
+    once() {},
+    stdin: { write: () => false, writable: true }, // 恒背压（>16KB 帧的常态）
+    kill() {},
+    exitCode: null,
+  };
+  const h = new ClaudeCodeHandle("claude:new-bp", child, "/tmp", undefined, "claude");
+  await h.prompt("a".repeat(64 * 1024)); // 旧实现此处 throw "stdin closed" 且 running 卡死
+  assert.equal(h.isRunning(), true, "写成功（入缓冲）后 running 应置位");
+  assert.equal(h.alive(), true);
+});
+
+test("加固 A4: stdin 不可写 → prompt 抛错且 running 不置位（队列不被卡死）", async () => {
+  const child = {
+    stdout: new PassThrough(),
+    stderr: { on() {} },
+    once() {},
+    stdin: { writable: false, write: () => { throw new Error("EPIPE"); } },
+    kill() {},
+    exitCode: null,
+  };
+  const h = new ClaudeCodeHandle("claude:new-closed", child, "/tmp", undefined, "claude");
+  await assert.rejects(h.prompt("hi"), /stdin closed/);
+  assert.equal(h.isRunning(), false, "写失败 running 必须保持 false");
+});
+
+test("加固 A2: stdout 流 error → session_backend_dead（不再崩宿主进程）", async () => {
+  const { h, events } = makeHandle();
+  h.child.stdout.emit("error", Object.assign(new Error("read ECONNRESET"), { code: "ECONNRESET" }));
+  await flush();
+  assert.equal(h.alive(), false);
+  assert.match(events.find((e) => e.type === "session_backend_dead")?.reason ?? "", /stdout error/);
+});
+
+test("加固 A3: 单个订阅者抛错不漏帧、不裸抛（后续订阅者照常收帧）", async () => {
+  const { h, write } = makeHandle();
+  const got = [];
+  h.subscribe(() => { throw new Error("listener boom"); });
+  h.subscribe((e) => got.push(e));
+  write({ type: "assistant", message: { content: [{ type: "text", text: "hi" }] } });
+  await flush();
+  assert.equal(got.length >= 1, true, "第二个订阅者应照常收到帧");
+});
+
+// ---- 上下文用量（docs/pi-web-external-agent-context-usage-plan.md）----
+
+test("contextUsage: result 帧 usage → getContextUsage（input 侧三项相加 / 模型窗口）+ getUsageTotals 累计", async () => {
+  const { h, write } = makeHandle();
+  assert.equal(h.getContextUsage(), undefined, "首轮 result 未到 → undefined（空轨态）");
+
+  write({ type: "result", subtype: "success", is_error: false,
+    usage: { input_tokens: 100, output_tokens: 40, cache_read_input_tokens: 500, cache_creation_input_tokens: 60 },
+    total_cost_usd: 0.05, num_turns: 2 });
+  await flush();
+
+  const cu = h.getContextUsage();
+  assert.ok(cu, "result 后有数据");
+  assert.equal(cu.tokens, 660, "input + cacheRead + cacheWrite");
+  assert.equal(cu.contextWindow, 200_000, "默认 claude 窗口");
+  assert.ok(Math.abs(cu.percent - (660 / 200_000) * 100) < 1e-9);
+
+  const totals = h.getUsageTotals();
+  assert.equal(totals.inputTokens, 100);
+  assert.equal(totals.outputTokens, 40);
+  assert.equal(totals.cacheReadTokens, 500);
+  assert.equal(totals.cacheWriteTokens, 60);
+  assert.equal(totals.costUsd, 0.05);
+  assert.equal(totals.turns, 1);
+
+  // 第二轮：累计叠加
+  write({ type: "result", subtype: "success", is_error: false,
+    usage: { input_tokens: 30, output_tokens: 10 }, total_cost_usd: 0.02, num_turns: 1 });
+  await flush();
+  const t2 = h.getUsageTotals();
+  assert.equal(t2.inputTokens, 130);
+  assert.equal(t2.turns, 2);
+  const cu2 = h.getContextUsage();
+  assert.equal(cu2.tokens, 30, "contextUsage 只看最近一轮（当前上下文占用）");
+});
+
+test("contextUsage: [1m] 模型 → 1M 窗口；全零 usage → undefined（不报 0%）", async () => {
+  const { h, write } = makeHandle();
+  h.model = { id: "claude-sonnet-4-5[1m]", provider: "claude" };
+  write({ type: "result", subtype: "success", is_error: false,
+    usage: { input_tokens: 1_500_000, output_tokens: 100, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 },
+    total_cost_usd: 1 });
+  await flush();
+  const cu = h.getContextUsage();
+  assert.equal(cu.contextWindow, 1_000_000);
+  assert.equal(cu.percent, 100, "封顶 100%");
+});

package/claude-quota.test.mjs

@@ -0,0 +1,88 @@
+/**
+ * claude-quota 单测（归一化 + 凭据读取 + fetch 注入）。
+ * 注意：本机无 claude 登录，接口形状按社区已知实现（待真机校准）；本测试用假响应钉住归一化契约。
+ *
+ * Run: node --test pi-web-ext/aiti-claude-code-agent/claude-quota.test.mjs
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const { normalizeClaudeUsage, fetchClaudeQuota, readClaudeCreds } = await import("./claude-quota.ts");
+
+const SAMPLE = {
+  five_hour: { utilization: 12.5, resets_at: "2026-09-13T15:00:00.000Z" },
+  seven_day: { utilization: 40, resets_at: "2026-09-15T00:00:00.000Z" },
+  seven_day_opus: { utilization: 5, resets_at: "2026-09-15T00:00:00.000Z" },
+};
+
+test("normalizeClaudeUsage：5h/7d 双窗口 → 剩余百分比 + 分包（含 reset 注记）", () => {
+  const v = normalizeClaudeUsage(SAMPLE, 1_700_000_000_000);
+  assert.equal(v.available, true);
+  assert.equal(v.unit, "%");
+  assert.equal(v.usedPercent, 40, "主指标取 7d");
+  assert.equal(v.remaining, 60);
+  assert.equal(v.display, "额度 5h 剩余 87.5% · 7d 剩余 60%");
+  assert.deepEqual(v.packages.map((p) => [p.name, p.usedPercent]), [["5 小时窗口", 12.5], ["7 天窗口", 40], ["7 天 Opus", 5]]);
+  assert.match(v.packages[0].note, /^重置于 /);
+  assert.equal(v.fetchedAt, 1_700_000_000_000);
+});
+
+test("normalizeClaudeUsage：窗口缺失优雅降级（仅 7d / 仅 5h / 全缺 = unparsed）", () => {
+  const only7 = normalizeClaudeUsage({ seven_day: { utilization: 90 } }, 1);
+  assert.equal(only7.available, true);
+  assert.equal(only7.display, "额度 7d 剩余 10%");
+  assert.equal(only7.usedPercent, 90);
+
+  const only5 = normalizeClaudeUsage({ five_hour: { utilization: 25 } }, 1);
+  assert.equal(only5.available, true);
+  assert.equal(only5.display, "额度 5h 剩余 75%");
+  assert.equal(only5.usedPercent, 25, "仅 5h 时主指标回落 5h");
+
+  const none = normalizeClaudeUsage({ five_hour: {} }, 1);
+  assert.equal(none.available, false);
+  assert.equal(none.reason, "unparsed");
+});
+
+test("normalizeClaudeUsage：tokenExpiresAt 透出为 expiresAt", () => {
+  const v = normalizeClaudeUsage(SAMPLE, 1, 1_800_000_000_000);
+  assert.equal(v.expiresAt, 1_800_000_000_000);
+});
+
+test("fetchClaudeQuota：成功（注入 fetch 校验 headers）+ 非 200 抛错", async () => {
+  const ok = await fetchClaudeQuota({
+    token: "tok",
+    expiresAt: 1_800_000_000_000,
+    fetchImpl: async (url, init) => {
+      assert.equal(String(url), "https://api.anthropic.com/api/oauth/usage");
+      assert.equal(init.headers.Authorization, "Bearer tok");
+      assert.equal(init.headers["anthropic-beta"], "oauth-2025-04-20");
+      return { ok: true, status: 200, json: async () => SAMPLE };
+    },
+  });
+  assert.equal(ok.available, true);
+  assert.equal(ok.expiresAt, 1_800_000_000_000);
+
+  await assert.rejects(
+    fetchClaudeQuota({ token: "t", fetchImpl: async () => ({ ok: false, status: 403, json: async () => ({}) }) }),
+    /HTTP 403/,
+  );
+});
+
+test("readClaudeCreds：claudeAiOauth 形态 / 顶层兼容 / 无凭据", () => {
+  const home = mkdtempSync(join(tmpdir(), "claude-quota-"));
+  try {
+    assert.equal(readClaudeCreds(home), null, "无文件 → null");
+    mkdirSync(join(home, ".claude"), { recursive: true });
+    writeFileSync(join(home, ".claude", ".credentials.json"), JSON.stringify({ claudeAiOauth: { accessToken: "oauth-tok", expiresAt: 1_799_000_000_000 } }));
+    assert.deepEqual(readClaudeCreds(home), { token: "oauth-tok", expiresAt: 1_799_000_000_000 });
+    writeFileSync(join(home, ".claude", ".credentials.json"), JSON.stringify({ accessToken: "flat-tok" }));
+    assert.deepEqual(readClaudeCreds(home), { token: "flat-tok" }, "顶层兼容");
+    writeFileSync(join(home, ".claude", ".credentials.json"), '{"claudeAiOauth":{}}');
+    assert.equal(readClaudeCreds(home), null, "无 token → null");
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});

package/claude-quota.ts

@@ -0,0 +1,147 @@
+/**
+ * claude-quota —— Claude Code 账号额度（agent-manager 统一「账号额度」行显示）。
+ *
+ * 凭据：~/.claude/.credentials.json → claudeAiOauth.accessToken（兼容顶层 accessToken）。
+ * 接口：GET https://api.anthropic.com/api/oauth/usage（社区已知端点，
+ *   headers: Authorization: Bearer <token> / anthropic-version: 2023-06-01 / anthropic-beta: oauth-2025-04-20）
+ *   → 窗口字段 five_hour / seven_day / seven_day_opus / seven_day_sonnet，各 { utilization: 0-100, resets_at: ISO }。
+ *
+ * ⚠ 本机当前无 claude 登录，接口形状按社区已知实现，**待真机校准**（正常化逻辑已用假响应单测覆盖；
+ *   解析不到窗口时返回 available:false，不会误报）。token 仅服务端使用，绝不下发客户端。
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface ClaudeQuotaPackage {
+  name?: string;
+  usedPercent?: number;
+  note?: string;
+}
+
+export type ClaudeQuotaView =
+  | {
+    available: true;
+    display?: string;
+    unit?: string;
+    used?: number;
+    usedPercent?: number;
+    remaining?: number;
+    total?: number;
+    packages?: ClaudeQuotaPackage[];
+    note?: string;
+    expiresAt?: number;
+    fetchedAt: number;
+  }
+  | { available: false; reason: string; note?: string; fetchedAt: number };
+
+export interface ClaudeCreds {
+  token: string;
+  expiresAt?: number;
+}
+
+/** 读 Claude OAuth 凭据（无凭据/坏文件 → null）。 */
+export function readClaudeCreds(home = homedir()): ClaudeCreds | null {
+  const p = join(home, ".claude", ".credentials.json");
+  if (!existsSync(p)) return null;
+  try {
+    const j = JSON.parse(readFileSync(p, "utf8")) as {
+      accessToken?: unknown;
+      expiresAt?: unknown;
+      claudeAiOauth?: { accessToken?: unknown; expiresAt?: unknown };
+    };
+    const oauth = j.claudeAiOauth ?? {};
+    const token = (typeof oauth.accessToken === "string" && oauth.accessToken)
+      || (typeof j.accessToken === "string" && j.accessToken)
+      || "";
+    if (!token) return null;
+    const rawExp = typeof oauth.expiresAt === "number" ? oauth.expiresAt : (typeof j.expiresAt === "number" ? j.expiresAt : undefined);
+    return { token, ...(rawExp !== undefined ? { expiresAt: rawExp } : {}) };
+  } catch {
+    return null;
+  }
+}
+
+const num = (v: unknown): number | undefined => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
+const pctLeft = (used: number): number => Math.round(Math.max(0, Math.min(100, 100 - used)) * 10) / 10;
+
+/** 窗口定义（显示名 + 简称）。 */
+const WINDOWS: Array<{ key: string; name: string; short: string }> = [
+  { key: "five_hour", name: "5 小时窗口", short: "5h" },
+  { key: "seven_day", name: "7 天窗口", short: "7d" },
+  { key: "seven_day_opus", name: "7 天 Opus", short: "7d Opus" },
+  { key: "seven_day_sonnet", name: "7 天 Sonnet", short: "7d Sonnet" },
+];
+
+const fmtReset = (iso: unknown): string | undefined => {
+  if (typeof iso !== "string" || !iso) return undefined;
+  const ms = Date.parse(iso);
+  if (!Number.isFinite(ms)) return undefined;
+  try { return new Date(ms).toLocaleString(); } catch { return undefined; }
+};
+
+/** oauth/usage 响应 → 归一化视图（纯函数；窗口缺失优雅降级）。 */
+export function normalizeClaudeUsage(raw: unknown, now = Date.now(), tokenExpiresAt?: number): ClaudeQuotaView {
+  const d = (raw ?? {}) as Record<string, unknown>;
+  const found: Array<{ key: string; name: string; short: string; used: number; reset?: string }> = [];
+  for (const w of WINDOWS) {
+    const win = (d[w.key] ?? null) as Record<string, unknown> | null;
+    if (!win) continue;
+    const used = num(win.utilization);
+    if (used === undefined) continue;
+    found.push({ ...w, used, ...(fmtReset(win.resets_at) ? { reset: fmtReset(win.resets_at)! } : {}) });
+  }
+  if (!found.length) {
+    return { available: false, reason: "unparsed", note: "Claude 用量响应未识别（窗口字段缺失；待真机校准）", fetchedAt: now };
+  }
+  const primary = found.find((w) => w.key === "seven_day") ?? found[0];
+  const display = "额度 " + found
+    .filter((w) => w.key === "five_hour" || w.key === "seven_day")
+    .map((w) => `${w.short} 剩余 ${pctLeft(w.used)}%`)
+    .join(" · ");
+  return {
+    available: true,
+    display: display === "额度 " ? `额度 剩余 ${pctLeft(primary.used)}%` : display,
+    unit: "%",
+    used: primary.used,
+    usedPercent: primary.used,
+    remaining: pctLeft(primary.used),
+    total: 100,
+    packages: found.map((w) => ({
+      name: w.name,
+      usedPercent: w.used,
+      ...(w.reset ? { note: `重置于 ${w.reset}` } : {}),
+    })),
+    ...(tokenExpiresAt !== undefined ? { expiresAt: tokenExpiresAt } : {}),
+    fetchedAt: now,
+  };
+}
+
+/** 拉 Claude OAuth 用量（fetchImpl 可注入；超时/非 200/异常 → throw，调用方回落 available:false）。 */
+export async function fetchClaudeQuota(opts: {
+  token: string;
+  expiresAt?: number;
+  timeoutMs?: number;
+  now?: number;
+  fetchImpl?: typeof fetch;
+}): Promise<ClaudeQuotaView> {
+  const fetchFn = opts.fetchImpl ?? fetch;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs ?? 15_000);
+  try {
+    const res = await fetchFn("https://api.anthropic.com/api/oauth/usage", {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${opts.token}`,
+        "anthropic-version": "2023-06-01",
+        "anthropic-beta": "oauth-2025-04-20",
+      },
+      signal: ctrl.signal,
+    });
+    if (!res.ok) throw new Error(`Claude 用量接口 HTTP ${res.status}`);
+    return normalizeClaudeUsage(await res.json(), opts.now, opts.expiresAt);
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/client/src/controlled-login-client.mjs

@@ -0,0 +1,22 @@
+/**
+ * aiti-claude-code-agent · 受控登录 client（薄壳，paste-relay 模式）。
+ *
+ * 全部 UI/轮询/文案模板在 ./controlled-login-dialog.mjs
+ * （权威源 pi-web-ext/_shared/controlled-login-dialog.mjs 的部署副本，改动须双向同步）——
+ * 本文件只传扩展专属配置。
+ */
+import { registerControlledLoginClient } from "./controlled-login-dialog.mjs";
+
+export default function register(ctx) {
+  registerControlledLoginClient(ctx, {
+    extId: "aiti-claude-code-agent",
+    toolbarLabel: "登录 Claude Code",
+    title: "登录 Claude Code",
+    pasteHint:
+      "后端发起官方 claude auth login（Claude 订阅档），把授权链接交给你——" +
+      "在任意设备的浏览器打开并登录授权后，Claude 的完成页会显示一段一次性 code：" +
+      "把它（或整个回调链接）复制到下方输入框提交，后端原样喂给 login 进程即完成登录。" +
+      "code 一次性且时效短，请拿到后尽快提交。",
+    successHint: null,
+  });
+}