@aiti-ai/aiti-cursor-agent 0.1.9

package/AGENTS.md

@@ -0,0 +1,32 @@
+# aiti-cursor-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-cursor-agent/`（git 管理，deploy 同步回本目录）
+- 改完在源码仓跑 `node tools/deploy.mjs`（或仓库根 `node scripts/deploy-all.mjs --only aiti-cursor-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

@@ -0,0 +1,39 @@
+# @aiti-ai/aiti-cursor-agent
+
+> 驱动 Cursor Agent CLI 会话（agentKey: cursor）——stream-json print 模式 + --resume 多轮；Cursor IDE 会话只读解析
+
+## 来源 · 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>
+
+## 功能定位（中文）
+
+驱动 Cursor Agent CLI 会话（agentKey: cursor）——stream-json print 模式 + --resume 多轮；Cursor IDE 会话只读解析
+
+会话管理 · tags: `cursor` · `agent` · `sessions` · `cli`
+
+## Positioning (English)
+
+Drives Cursor Agent CLI sessions (agentKey: cursor) — stream-json print mode + --resume multi-turn; Cursor IDE sessions parsed read-only
+
+## 安装 / 部署
+
+随 aiti-agent 扩展体系部署（extman 安装 / deploy 脚本拷贝到 `~/.pi/web/extensions/`），一般不单独 npm 安装；作为依赖被引用时经 extman reconcile 自动装入共享 node_modules。
+
+Deployed as part of the aiti-agent extension system (extman install / deploy scripts copy it to `~/.pi/web/extensions/`); usually not installed standalone.
+
+## 文档 · Documentation
+
+- 中文完整文档（aiti-docs）: <https://aiti.pw/extensions/aiti-cursor-agent.html>
+- English docs: <https://aiti.pw/en/extensions/aiti-cursor-agent.html>
+- 扩展注册表 / registry: <https://aiti.pw/extensions.html> · machine-readable <https://aiti.pw/extensions.json>
+
+## License
+
+MIT

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

@@ -0,0 +1,22 @@
+/**
+ * aiti-cursor-agent · 受控登录 client（薄壳）。
+ *
+ * 全部 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-cursor-agent",
+    toolbarLabel: "登录 Cursor",
+    title: "登录 Cursor",
+    urlHint:
+      "后端发起官方 cursor login（无浏览器通道），把授权链接交给你——在任意设备的浏览器打开并登录 Cursor 账号授权即可；" +
+      "凭据由官方 CLI 自动落盘，本页约 2s 内自动感知。" +
+      "若本机无密钥环（headless 常见）导致登录失败，可给 pi-web 服务设置 AGENT_CREDENTIAL_STORE=file 后重试。",
+    pasteHint: null,
+    successHint: null,
+  });
+}

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

@@ -0,0 +1,270 @@
+/**
+ * controlled-login — 外部 Agent 受控登录标准 · 前端统一弹窗（原生 h() 渲染，零构建步骤）。
+ *
+ * ⚠ 副本同步（字节级拷贝，改动须同步到全部副本；测试 `_shared/controlled-login.test.mjs` 钉住一致性）。
+ * 权威源：pi-web-ext/_shared/controlled-login-dialog.mjs
+ * 部署副本（client 侧走部署树内相对导入 —— 零构建 client 无法像 vite 客户端那样在构建期
+ * 内联 ../../_shared（资产路由拒绝越目录穿越），与 draft-keeper 的 ./core.mjs 同一惯例）：
+ *   pi-web-ext/aiti-{zcode,cursor,qoder,claude-code,codex}-agent/client/controlled-login-dialog.mjs
+ *
+ * 契约（docs/ext-controlled-login-standard.md §3.5）：
+ *   🔗「打开授权页」按钮（target=_blank）+ URL 文本可复制 + 模式说明行
+ *   + 状态区（waiting 转圈 / success ✅ 用户名 / failed / timeout / cancelled，均带重试）
+ *   + B 模式（paste）专属 code 输入框+提交。
+ * 状态刷新：弹窗打开期间每 2s 轮询 GET /login/status，关闭即停
+ * （方案 §3.6 已论证并拍板的轮询例外：登录是分钟级一次性交互）。
+ *
+ * 浮动契约：面板根节点 data-ext-float="1" + data-ext-float-w/-h + data-ext-float-full="1"
+ * （aiti-float 接管拖拽/缩放/持久化/小屏全屏；未装时自身 style 居中兜底）。
+ *
+ * 接入（各扩展 client/controlled-login-client.mjs，两行）：
+ *   import { registerControlledLoginClient } from "./controlled-login-dialog.mjs";
+ *   export default function register(ctx) { registerControlledLoginClient(ctx, { … }); }
+ */
+
+// ---------- 模块内 open 状态（toolbar 入口与 dialogs 条目同模块共享，不落 window 全局） ----------
+let moduleSetOpen = null;
+// 懒加载（clientImmediately:false）下 toolbar 静态条目点击时弹窗组件可能尚未挂载：
+// 记 pending，挂载 effect 消费——避免首点失效。
+let pendingOpen = false;
+
+/** 打开本扩展的受控登录弹窗（toolbar 🔑 按钮 / 静态条目 meta.onClick 用）。 */
+export function openControlledLogin() {
+  if (moduleSetOpen) moduleSetOpen(true);
+  else pendingOpen = true;
+}
+
+// ---------- 自持样式层（幂等注入；clg- 前缀 + var(--x, 兜底)，零宿主耦合） ----------
+const STYLE_ID = "aiti-controlled-login-styles";
+const STYLES = `
+.clg-mask { position: fixed; inset: 0; z-index: 2147483000; background: rgba(0,0,0,.32); display: flex; align-items: center; justify-content: center; }
+.clg-panel { width: 520px; max-width: calc(100vw - 16px); display: flex; flex-direction: column; overflow: hidden;
+  background: var(--bg,#fff); color: var(--text,#1a1a1a); border: 1px solid var(--border,#e0e0e0); border-radius: 12px;
+  box-shadow: 0 16px 64px rgba(0,0,0,.25); font-size: 13px; line-height: 1.55; }
+.clg-head { display: flex; align-items: center; gap: 10px; padding: 11px 16px; border-bottom: 1px solid var(--border,#e0e0e0); flex-shrink: 0; background: var(--bg-subtle,#f7f7f7); }
+.clg-title { font-size: 14px; font-weight: 700; display: flex; align-items: center; gap: 6px; }
+.clg-x { margin-left: auto; border: none; background: none; cursor: pointer; color: var(--text-muted,#888); font-size: 16px; line-height: 1; padding: 4px 6px; border-radius: 6px; }
+.clg-x:hover { background: var(--bg-hover,#eee); color: var(--text,#1a1a1a); }
+.clg-body { padding: 14px 16px 16px; display: flex; flex-direction: column; gap: 10px; }
+.clg-intro { color: var(--text-muted,#777); font-size: 12.5px; }
+.clg-urlrow { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+.clg-open { display: inline-flex; align-items: center; gap: 6px; padding: 7px 16px; border: 1px solid var(--accent,#2563eb); border-radius: 8px;
+  cursor: pointer; background: var(--accent,#2563eb); color: #fff; font-size: 13px; font-weight: 600; text-decoration: none; white-space: nowrap; }
+.clg-open:hover { background: var(--accent-hover,#1d4ed8); }
+.clg-url { flex: 1; min-width: 200px; font: 11.5px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace; color: var(--text-muted,#777);
+  word-break: break-all; cursor: pointer; padding: 5px 8px; border: 1px dashed var(--border,#d8d8d8); border-radius: 6px; }
+.clg-url:hover { border-color: var(--accent,#2563eb); color: var(--text,#1a1a1a); }
+.clg-copied { color: #16a34a; font-size: 11.5px; }
+.clg-status { display: flex; align-items: center; gap: 8px; padding: 9px 12px; border-radius: 8px; font-size: 12.5px; flex-wrap: wrap; }
+.clg-status.waiting { background: rgba(37,99,235,.08); color: var(--accent,#2563eb); }
+.clg-status.success { background: color-mix(in srgb, var(--ok, #22c55e) 12%, transparent); color: #16a34a; }
+.clg-status.failed, .clg-status.timeout, .clg-status.cancelled { background: color-mix(in srgb, var(--danger, #ef4444) 8%, transparent); color: #dc2626; }
+.clg-spin { width: 14px; height: 14px; flex-shrink: 0; border: 2px solid color-mix(in srgb, currentColor 25%, transparent); border-top-color: currentColor;
+  border-radius: 50%; animation: clg-rotate .9s linear infinite; }
+@keyframes clg-rotate { to { transform: rotate(360deg); } }
+.clg-errline { font-size: 12px; color: #dc2626; word-break: break-all; }
+.clg-tail { font: 11px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace; color: var(--text-muted,#888); background: var(--bg-subtle,#f5f5f5);
+  border: 1px solid var(--border,#e0e0e0); border-radius: 8px; padding: 8px 10px; max-height: 140px; overflow: auto; white-space: pre-wrap; word-break: break-all; }
+.clg-coderow { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; }
+.clg-input { flex: 1; min-width: 180px; padding: 7px 10px; border: 1px solid var(--border,#d8d8d8); border-radius: 8px;
+  background: var(--bg,#fff); color: var(--text,#1a1a1a); font-size: 12.5px; outline: none; }
+.clg-input:focus { border-color: var(--accent,#2563eb); box-shadow: 0 0 0 2px color-mix(in srgb, var(--accent,#2563eb) 18%, transparent); }
+.clg-btn { display: inline-flex; align-items: center; gap: 5px; padding: 6px 14px; border: 1px solid var(--border,#d8d8d8); border-radius: 7px;
+  cursor: pointer; background: var(--bg,#fff); color: var(--text,#1a1a1a); font-size: 12.5px; font-weight: 500; white-space: nowrap; }
+.clg-btn:hover { background: var(--bg-hover,#f0f0f0); }
+.clg-btn:disabled { opacity: .5; cursor: not-allowed; }
+.clg-btn.primary { background: var(--accent,#2563eb); border-color: var(--accent,#2563eb); color: #fff; }
+.clg-btn.primary:hover { background: var(--accent-hover,#1d4ed8); }
+.clg-foot { display: flex; align-items: center; gap: 8px; margin-top: 2px; }
+.clg-hint { color: var(--text-dim,#999); font-size: 11.5px; }
+`;
+
+let stylesInjected = false;
+function ensureStyles() {
+  if (stylesInjected) return;
+  if (typeof document === "undefined") return;
+  if (!document.getElementById(STYLE_ID)) {
+    const el = document.createElement("style");
+    el.id = STYLE_ID;
+    el.textContent = STYLES;
+    document.head.appendChild(el);
+  }
+  stylesInjected = true;
+}
+
+/**
+ * 统一弹窗注册（每扩展 client 的薄壳调用一次）。
+ *
+ * @param {*} ctx 宿主 client 上下文（h/useState/useEffect/apiUrl/registerItems）
+ * @param {object} config
+ * @param {string} config.extId        扩展 id（API 前缀 / toolbar item id 用）
+ * @param {string} config.toolbarLabel 工具条按钮 title/label（如 "登录 ZCode"）
+ * @param {string} config.title        弹窗标题
+ * @param {string} [config.urlHint]    A url-only 模式说明行
+ * @param {string} [config.pasteHint]  B paste-relay 模式说明行
+ * @param {string} [config.successHint] 成功后的补充说明（如凭据换 key 提示）
+ */
+export function registerControlledLoginClient(ctx, config) {
+  ensureStyles();
+  const h = (...a) => ctx.h(...a);
+  const useState = (v) => ctx.useState(v);
+  const useEffect = (fn, deps) => ctx.useEffect(fn, deps);
+  const api = (p, init) => fetch(ctx.apiUrl("/api/extensions/" + config.extId + p), { cache: "no-store", ...init });
+  const jsonInit = (body) => ({ method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+
+  // ---- 工具条入口：声明式图标按钮（meta.icon + meta.onClick、无 render —— 宿主统一渲染 36×36 线图按钮，禁 emoji） ----
+  ctx.registerItems("toolbar", [{
+    id: `${config.extId}-controlled-login`,
+    meta: {
+      label: config.toolbarLabel,
+      title: config.toolbarLabel,
+      icon: "icons/key-round.svg",
+      onClick: () => openControlledLogin(),
+    },
+  }]);
+  // ---- 弹窗条目（dialogs slot；宿主包 display:contents 壳，float 持久化键认它） ----
+  ctx.registerItems("dialogs", [{
+    id: `${config.extId}-controlled-login-dialog`,
+    render: () => h(ControlledLoginDialog),
+  }]);
+
+  function ControlledLoginDialog() {
+    const [open, setOpen] = useState(false);
+    const [status, setStatus] = useState(null);   // /login/status 响应（{state,...}）
+    const [busy, setBusy] = useState(false);
+    const [reqError, setReqError] = useState(null); // 请求层错误（网络/400）
+    const [code, setCode] = useState("");
+    const [copied, setCopied] = useState(false);
+
+    useEffect(() => {
+      moduleSetOpen = setOpen;
+      if (pendingOpen) { pendingOpen = false; setOpen(true); }
+      return () => { if (moduleSetOpen === setOpen) moduleSetOpen = null; };
+    }, []);
+
+    // 打开期间 2s 轮询 /login/status（§3.6 拍板例外）；关闭即停
+    useEffect(() => {
+      if (!open) return;
+      let stopped = false;
+      let timer = null;
+      const tick = async () => {
+        try {
+          const r = await api("/login/status");
+          const d = await r.json();
+          if (!stopped) { setStatus(d); setReqError(null); }
+        } catch { /* 网络抖动忽略，下轮再试 */ }
+        if (!stopped) timer = setTimeout(tick, 2000);
+      };
+      tick();
+      return () => { stopped = true; if (timer) clearTimeout(timer); };
+    }, [open]);
+
+    if (!open) return null;
+
+    const st = status?.state ?? "idle";
+    const mode = status?.mode ?? "url";
+    const pasteMode = mode === "paste";
+
+    async function call(p, init) {
+      setBusy(true); setReqError(null);
+      try {
+        const r = await api(p, init);
+        const d = await r.json();
+        if (d && d.error) setReqError(d.error);
+        if (d) setStatus(d);
+      } catch (e) {
+        setReqError(e?.message || String(e));
+      }
+      setBusy(false);
+    }
+    const startLogin = () => call("/login/start", jsonInit({}));
+    const cancelLogin = () => call("/login/cancel", jsonInit({}));
+    const submitCode = () => { if (code.trim()) call("/login/submit", jsonInit({ code })); };
+
+    async function copyUrl() {
+      const url = status?.url || "";
+      if (!url) return;
+      try { await navigator.clipboard.writeText(url); setCopied(true); setTimeout(() => setCopied(false), 1500); } catch { /* 剪贴板不可用：URL 文本本身可选中复制 */ }
+    }
+
+    // ---- 状态区 ----
+    let statusLine = null;
+    if (st === "idle") {
+      statusLine = h("div", { className: "clg-status waiting" }, "尚未发起登录");
+    } else if (st === "waiting") {
+      statusLine = h("div", { className: "clg-status waiting" },
+        h("span", { className: "clg-spin" }),
+        status?.url ? "等待你在浏览器完成授权…（本页自动感知，约 2s 内）" : "正在启动官方登录进程，等待授权链接…",
+        h("button", { className: "clg-btn", disabled: busy, style: { marginLeft: "auto" }, onClick: cancelLogin }, "取消"),
+      );
+    } else if (st === "success") {
+      statusLine = h("div", { className: "clg-status success" },
+        "登录成功", status?.user ? h("span", { style: { fontWeight: 700 } }, status.user) : null,
+        config.successHint ? h("span", { className: "clg-hint", style: { color: "inherit" } }, config.successHint) : null,
+      );
+    } else if (st === "failed" || st === "timeout" || st === "cancelled") {
+      const label = st === "failed" ? "登录失败" : st === "timeout" ? "登录超时" : "已取消";
+      statusLine = h("div", { className: "clg-status " + st },
+        h("span", null, (st === "timeout" ? "⏱ " : st === "cancelled" ? "⚪ " : "❌ ") + label),
+        status?.error ? h("span", { className: "clg-errline" }, status.error) : null,
+      );
+    }
+
+    return h("div", { className: "clg-mask", onClick: () => setOpen(false) },
+      h("div", {
+        className: "clg-panel",
+        "data-ext-float": "1", "data-ext-float-w": 520, "data-ext-float-h": 380, "data-ext-float-full": "1",
+        onClick: (e) => e.stopPropagation(),
+      },
+        // ── 标题栏（首个子元素 = float 拖拽把手）──
+        h("div", { className: "clg-head" },
+          h("span", { className: "clg-title" }, "🔑 " + config.title),
+          h("button", { className: "clg-x", title: "关闭", onClick: () => setOpen(false) }, "✕"),
+        ),
+        h("div", { className: "clg-body" },
+          config.urlHint && !pasteMode ? h("div", { className: "clg-intro" }, config.urlHint) : null,
+          pasteMode && config.pasteHint ? h("div", { className: "clg-intro" }, config.pasteHint) : null,
+
+          // ── URL 区（waiting 且已抓到链接）──
+          st === "waiting" && status?.url
+            ? h("div", { className: "clg-urlrow" },
+                h("a", { className: "clg-open", href: status.url, target: "_blank", rel: "noopener noreferrer" }, "打开授权页"),
+                h("span", { className: "clg-url", title: "点击复制链接", onClick: copyUrl }, status.url),
+                copied ? h("span", { className: "clg-copied" }, "已复制") : null,
+              )
+            : null,
+
+          // ── B 模式 code 输入（paste 且 waiting）──
+          pasteMode && st === "waiting"
+            ? h("div", { className: "clg-coderow" },
+                h("input", {
+                  className: "clg-input",
+                  placeholder: "粘贴授权完成页显示的 code（或完整回调链接）",
+                  value: code,
+                  onChange: (e) => setCode(e.target.value),
+                  onKeyDown: (e) => { if (e.key === "Enter") submitCode(); },
+                }),
+                h("button", { className: "clg-btn primary", disabled: busy || !code.trim(), onClick: submitCode }, busy ? "…" : "提交 code"),
+              )
+            : null,
+
+          statusLine,
+          reqError ? h("div", { className: "clg-errline" }, reqError) : null,
+
+          // CLI 升级改输出格式导致 URL 抓取失败时：原文透出（人工可读可复制，方案 §7）
+          (st === "failed" || st === "timeout") && status?.outputTail
+            ? h("div", { className: "clg-tail" }, status.outputTail)
+            : null,
+
+          // ── 底部动作：idle/终态带（重）试 ──
+          h("div", { className: "clg-foot" },
+            st === "idle" || st === "failed" || st === "timeout" || st === "cancelled" || st === "success"
+              ? h("button", { className: "clg-btn primary", disabled: busy, onClick: startLogin }, busy ? "…" : st === "idle" ? "发起登录" : "重试")
+              : null,
+            h("span", { className: "clg-hint" }, "授权在浏览器完成，凭据由官方 CLI 落盘；本页关闭不影响进行中的登录。"),
+          ),
+        ),
+      ),
+    );
+  }
+}

package/cursor-agent.test.mjs

@@ -0,0 +1,154 @@
+/**
+ * aiti-cursor-agent — 单测（D6）：帧状态机 + 登录 driver 契约。
+ *
+ * cursor 协议核心（cursor-cli-store wire 解码）由 _shared/cursor-cli-store.test.mjs
+ * 钉死；本文件补扩展自身两块：
+ *   1. handle 帧状态机（经 mock startup → createSession 拿真 handle，私有 onLine 直驱）：
+ *      assistant 文本累积、result 收口（settled + running 复位）、thinking 忽略、
+ *      is_error → settled error、turnEnded 后晚到帧忽略（防重复 settled）；
+ *   2. 受控登录 driver（extractUrl/interpret/bin 名）。
+ *
+ * Run: node --experimental-strip-types --test pi-web-ext/aiti-cursor-agent/cursor-agent.test.mjs
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+
+const mod = await import("./index.ts");
+const { extractCursorLoginUrl, interpretCursorLogin, cursorLoginDriver } = mod;
+
+/** mock startup → 捕获 createSession → 造 handle（不 spawn：spawn 在 prompt 里）。 */
+async function makeHandle() {
+  let created = null;
+  const providers = { register(p) { created = p; return "aiti-cursor-agent/cursor"; } };
+  const ctx = { sessionProviders: providers, configDir: "/tmp" };
+  await mod.default.server.startup(ctx);
+  assert.ok(created, "startup 应注册 provider");
+  const h = await created.createSession({ cwd: "/tmp" });
+  const events = [];
+  h.subscribe((e) => events.push(e));
+  const write = (frame) => h.consumeLine(JSON.stringify(frame));
+  return { h, events, write };
+}
+
+test("帧状态机：assistant 累积 → result 收口（settled + running 复位 + 历史入库）", async () => {
+  const { h, events, write } = await makeHandle();
+  h.running = true; // 模拟 prompt 后在途
+  write({ type: "assistant", message: { model: "composer-1", content: [{ type: "text", text: "你好" }] } });
+  write({ type: "assistant", message: { content: [{ type: "text", text: "！" }] } });
+  write({ type: "result", result: "你好！", is_error: false });
+  const settled = events.find((e) => e.type === "agent_settled");
+  assert.ok(settled, "result 应发 settled");
+  assert.equal(settled.result, "你好！");
+  assert.equal(h.isRunning(), false, "result 即收口（不等进程 exit）");
+  const last = h.history.at(-1);
+  assert.equal(last?.role, "assistant");
+  assert.equal(last?.content?.[0]?.text, "你好！");
+});
+
+test("帧状态机：thinking 忽略；is_error → settled error", async () => {
+  const { h, events, write } = await makeHandle();
+  h.running = true;
+  write({ type: "thinking", text: "内部推理" });
+  assert.ok(!events.some((e) => e.type === "message_update"), "thinking 不进正文流");
+  write({ type: "result", result: "", is_error: true });
+  const settled = events.find((e) => e.type === "agent_settled");
+  assert.ok(settled?.error, "is_error 应带 error");
+});
+
+test("帧状态机：turnEnded 后晚到帧忽略（防重复 settled）", async () => {
+  const { h, events, write } = await makeHandle();
+  h.running = true;
+  write({ type: "result", result: "一" });
+  const settledCount = () => events.filter((e) => e.type === "agent_settled").length;
+  assert.equal(settledCount(), 1);
+  write({ type: "assistant", message: { content: [{ type: "text", text: "晚到" }] } });
+  write({ type: "result", result: "晚到的二" });
+  assert.equal(settledCount(), 1, "重复 result/晚到帧不得二次收口");
+  assert.equal(h.history.at(-1)?.content?.[0]?.text, "一");
+});
+
+test("登录 driver：URL 提取 / 结果判定 / bin 名", () => {
+  assert.equal(
+    extractCursorLoginUrl("navigate to this link: https://cursor.com/login-device?code=XYZ to finish"),
+    "https://cursor.com/login-device?code=XYZ",
+  );
+  assert.equal(extractCursorLoginUrl("no url here"), null);
+  assert.deepEqual(interpretCursorLogin(0, "", ""), { state: "success" });
+  const failed = interpretCursorLogin(1, "out", "err line");
+  assert.equal(failed.state, "failed");
+  assert.equal(failed.error, "err line");
+  assert.equal(cursorLoginDriver.agentId, "cursor");
+});
+
+// ---- 队列接线（共享层 backend-queue，docs/aiti-agent-queue-clear-recall-audit-plan.md §2）----
+// 不真 spawn：settle 时队列已清空 → scheduleDrain no-op，dispatch 不会被触发。
+
+test("队列接线：运行中 followUp 入队 + queue_update；list/move/remove 转发共享层", async () => {
+  const { h, events } = await makeHandle();
+  h.running = true;
+  await h.followUp("a");
+  await h.followUp("b");
+  const updates = events.filter((e) => e.type === "queue_update");
+  assert.ok(updates.length >= 2, "每次入队应广播 queue_update");
+  assert.deepEqual(updates.at(-1).followUp, ["a", "b"]);
+  const list = await h.queueManage({ action: "list" });
+  assert.deepEqual(list.followUp, ["a", "b"]);
+  assert.deepEqual(list.steering, []);
+  await h.queueManage({ action: "move", from: 0, to: 1 });
+  assert.deepEqual((await h.queueManage({ action: "list" })).followUp, ["b", "a"]);
+  const rm = await h.queueManage({ action: "remove", index: 0 });
+  assert.equal(rm.entry.text, "b");
+  assert.equal(rm.removed.text, "b");
+});
+
+test("队列接线：clear 返回清空前文本（pi clearQueue 契约——前端「全部编辑」回填输入框）", async () => {
+  const { h, events, write } = await makeHandle();
+  h.running = true;
+  await h.followUp("msg-1");
+  await h.followUp("msg-2");
+  const cleared = await h.queueManage({ action: "clear" });
+  assert.deepEqual(cleared.followUp, ["msg-1", "msg-2"], "clear 须带回清空前的文本");
+  assert.deepEqual((await h.queueManage({ action: "list" })).followUp, []);
+  assert.ok(events.some((e) => e.type === "queue_update" && e.followUp.length === 0), "清空应广播空 queue_update");
+  // settle（队列已空 → scheduleDrain no-op，不会真 spawn）
+  write({ type: "result", result: "ok" });
+  assert.ok(events.some((e) => e.type === "agent_settled"));
+  assert.deepEqual((await h.queueManage({ action: "list" })).followUp, [], "settle 后队列不得复活");
+});
+
+test("队列接线：recall 单条取回；steer 组操作给人话错误", async () => {
+  const { h } = await makeHandle();
+  h.running = true;
+  await h.followUp("x");
+  const rec = await h.queueManage({ action: "recall", index: 0 });
+  assert.equal(rec.entry.text, "x");
+  await assert.rejects(() => h.queueManage({ action: "clear", kind: "steer" }), /不支持/);
+});
+
+// ---- 上下文用量（机会式；docs/pi-web-external-agent-context-usage-plan.md）----
+
+test("contextUsage 机会式：result.usage（claude 形态）→ getContextUsage；composer 模型窗口未知 → undefined", async () => {
+  const { h, write } = await makeHandle();
+  h.running = true;
+  write({ type: "assistant", message: { model: "claude-sonnet-4-5", content: [{ type: "text", text: "hi" }] } });
+  write({ type: "result", result: "hi", is_error: false,
+    usage: { input_tokens: 100, output_tokens: 20, cache_read_input_tokens: 500, cache_creation_input_tokens: 10 } });
+  const cu = h.getContextUsage();
+  assert.ok(cu, "usage 齐全 + 模型可判 → 有数据");
+  assert.equal(cu.tokens, 610);
+  assert.equal(cu.contextWindow, 200_000);
+  const totals = h.getUsageTotals();
+  assert.equal(totals.inputTokens, 100);
+  assert.equal(totals.turns, 1);
+});
+
+test("contextUsage 机会式：无 usage 帧 → getContextUsage undefined（不编数据），totals 全 0", async () => {
+  const { h, write } = await makeHandle();
+  h.running = true;
+  write({ type: "assistant", message: { model: "composer-1", content: [{ type: "text", text: "hi" }] } });
+  write({ type: "result", result: "hi", is_error: false });
+  assert.equal(h.getContextUsage(), undefined, "composer 窗口未知 + 无 usage → 空轨");
+  const totals = h.getUsageTotals();
+  assert.equal(totals.turns, 0);
+  assert.equal(totals.inputTokens, 0);
+});

package/cursor-quota.test.mjs

@@ -0,0 +1,85 @@
+/**
+ * cursor-quota 单测（归一化 + 凭据读取 + fetch 注入；响应样本来自 2026-09-13 真机实测）。
+ *
+ * Run: node --test pi-web-ext/aiti-cursor-agent/cursor-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 { normalizeCursorUsage, fetchCursorQuota, readCursorToken, cursorAuthPath } = await import("./cursor-quota.ts");
+
+/** 真机实测样本（GetCurrentPeriodUsage）。 */
+const SAMPLE = {
+  billingCycleStart: "1787582660974",
+  billingCycleEnd: "1790261060974",
+  planUsage: { totalSpend: 46, bonusSpend: 46, remainingBonus: false, autoPercentUsed: 46, apiPercentUsed: 0, totalPercentUsed: 23 },
+  spendLimitUsage: { pooledLimit: 0, pooledRemaining: 0, individualLimit: 0, limitType: "user", overallLimit: 0, overallRemaining: 0 },
+  displayThreshold: 200,
+  displayMessage: "You've used 0% of your included usage",
+  autoModelSelectedDisplayMessage: "You've used 23% of your included total usage",
+};
+
+test("normalizeCursorUsage：实测样本 → 剩余 77% + auto/api 分包", () => {
+  const v = normalizeCursorUsage(SAMPLE, 1_700_000_000_000);
+  assert.equal(v.available, true);
+  assert.equal(v.unit, "%");
+  assert.equal(v.usedPercent, 23);
+  assert.equal(v.remaining, 77);
+  assert.equal(v.total, 100);
+  assert.equal(v.display, "额度 剩余 77%");
+  assert.deepEqual(v.packages.map((p) => [p.name, p.usedPercent]), [["自动模型（auto）", 46], ["API 模型", 0], ["总用量", 23]]);
+  assert.equal(v.expiresAt, 1790261060974);
+  assert.equal(v.note, "You've used 0% of your included usage");
+  assert.equal(v.fetchedAt, 1_700_000_000_000);
+});
+
+test("normalizeCursorUsage：消费上限非 0 → 追加一行；缺 totalPercentUsed → unparsed", () => {
+  const v = normalizeCursorUsage({ planUsage: { totalPercentUsed: 10, autoPercentUsed: 20, apiPercentUsed: 1 }, spendLimitUsage: { overallLimit: 500, overallRemaining: 120 } });
+  assert.equal(v.available, true);
+  assert.equal(v.packages.at(-1).name, "消费上限");
+  assert.match(v.packages.at(-1).note, /上限 500 \/ 剩余 120/);
+
+  const bad = normalizeCursorUsage({ planUsage: {} });
+  assert.equal(bad.available, false);
+  assert.equal(bad.reason, "unparsed");
+});
+
+test("fetchCursorQuota：成功（fetchImpl 注入）+ 非 200 抛错", async () => {
+  const ok = await fetchCursorQuota({
+    token: "tok",
+    fetchImpl: async (url, init) => {
+      assert.match(String(url), /GetCurrentPeriodUsage$/);
+      assert.equal(init.method, "POST");
+      assert.equal(init.headers.Authorization, "Bearer tok");
+      assert.equal(init.headers["Connect-Protocol-Version"], "1");
+      return { ok: true, status: 200, json: async () => SAMPLE };
+    },
+  });
+  assert.equal(ok.available, true);
+  assert.equal(ok.remaining, 77);
+
+  await assert.rejects(
+    fetchCursorQuota({ token: "t", fetchImpl: async () => ({ ok: false, status: 401, json: async () => ({}) }) }),
+    /HTTP 401/,
+  );
+});
+
+test("readCursorToken：primary/legacy 路径优先 + 坏文件兜底", () => {
+  const home = mkdtempSync(join(tmpdir(), "cursor-quota-"));
+  try {
+    assert.equal(cursorAuthPath(home), null, "无凭据时 null");
+    mkdirSync(join(home, ".cursor"), { recursive: true });
+    writeFileSync(join(home, ".cursor", "auth.json"), JSON.stringify({ accessToken: "legacy-tok" }));
+    assert.equal(readCursorToken(home), "legacy-tok", "旧路径兜底");
+    mkdirSync(join(home, ".config", "cursor"), { recursive: true });
+    writeFileSync(join(home, ".config", "cursor", "auth.json"), JSON.stringify({ accessToken: "primary-tok" }));
+    assert.equal(readCursorToken(home), "primary-tok", "primary 优先");
+    writeFileSync(join(home, ".config", "cursor", "auth.json"), "{broken");
+    assert.equal(readCursorToken(home), null, "坏文件 → null");
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});