chatccc 0.2.178 → 0.2.179

package/src/__tests__/orchestrator.test.ts

@@ -6,8 +6,9 @@ import { join } from "node:path";
 import type { PlatformAdapter } from "../platform-adapter.ts";
 import type { SessionInfo, ToolAdapter } from "../adapters/adapter-interface.ts";
 
-const mockStreamStates = new Map<string, { status: "running" | "done" | "stopped"; finalReply: string }>();
-const mockGetCodexUsageSummary = vi.hoisted(() => vi.fn());
+const mockStreamStates = new Map<string, { status: "running" | "done" | "stopped"; finalReply: string }>();
+const mockGetCodexUsageSummary = vi.hoisted(() => vi.fn());
+const mockGetCursorUsageSummary = vi.hoisted(() => vi.fn());
 
 vi.mock("../im-skills.ts", () => ({
   buildImSkillsPrompt: async () => "",
@@ -15,7 +16,7 @@ vi.mock("../im-skills.ts", () => ({
   exportSkillSubDocs: async () => {},
 }));
 
-vi.mock("../stream-state.ts", () => ({
+vi.mock("../stream-state.ts", () => ({
   readStreamState: async (sessionId: string) => {
     const state = mockStreamStates.get(sessionId);
     if (!state) return null;
@@ -50,14 +51,18 @@ vi.mock("../stream-state.ts", () => ({
     cwd,
     tool,
   }),
-  fixStaleStreamStates: async () => {},
-}));
-
-vi.mock("../feishu-platform.ts", () => ({
-  getCodexUsageSummary: mockGetCodexUsageSummary,
-  getTenantAccessToken: vi.fn(async () => "tenant-token"),
-  sendPostMessage: vi.fn(async () => true),
-}));
+  fixStaleStreamStates: async () => {},
+}));
+
+vi.mock("../feishu-platform.ts", () => ({
+  getCodexUsageSummary: mockGetCodexUsageSummary,
+  getTenantAccessToken: vi.fn(async () => "tenant-token"),
+  sendPostMessage: vi.fn(async () => true),
+}));
+
+vi.mock("../cursor-usage.ts", () => ({
+  getCursorUsageSummary: mockGetCursorUsageSummary,
+}));
 
 import { handleCommand } from "../orchestrator.ts";
 import {
@@ -120,14 +125,40 @@ describe("handleCommand WeChat processing ack", () => {
     _setSessionToolsFileForTest(join(tempDir, "sessions.json"));
     resetState();
     resetBindingState();
-    mockStreamStates.clear();
-    mockGetCodexUsageSummary.mockReset();
-    mockGetCodexUsageSummary.mockResolvedValue({
-      fiveHour: { usedPercent: 0, remainingPercent: 100, resetAtEpochSeconds: null, resetAfterSeconds: null },
-      weekly: { usedPercent: 0, remainingPercent: 100, resetAtEpochSeconds: null, resetAfterSeconds: null },
-    });
-    _setAdapterForToolForTest("claude", mockAdapter());
-  });
+    mockStreamStates.clear();
+    mockGetCodexUsageSummary.mockReset();
+    mockGetCursorUsageSummary.mockReset();
+    mockGetCodexUsageSummary.mockResolvedValue({
+      fiveHour: { usedPercent: 0, remainingPercent: 100, resetAtEpochSeconds: null, resetAfterSeconds: null },
+      weekly: { usedPercent: 0, remainingPercent: 100, resetAtEpochSeconds: null, resetAfterSeconds: null },
+    });
+    mockGetCursorUsageSummary.mockResolvedValue({
+      billingCycleStart: "1779357999000",
+      billingCycleEnd: "1782036399000",
+      planUsage: {
+        totalSpend: 8159,
+        includedSpend: 2000,
+        bonusSpend: 6159,
+        limit: 2000,
+        remainingBonus: false,
+        autoPercentUsed: 0,
+        apiPercentUsed: 100,
+        totalPercentUsed: 100,
+      },
+      spendLimitUsage: {
+        pooledLimit: 48950000,
+        pooledUsed: 31808224,
+        pooledRemaining: 17141776,
+        individualUsed: 101252,
+        limitType: "team",
+      },
+      displayThreshold: 200,
+      enabled: true,
+      displayMessage: "You've hit your usage limit",
+      autoBucketModels: ["default"],
+    });
+    _setAdapterForToolForTest("claude", mockAdapter());
+  });
 
   afterEach(async () => {
     resetState();
@@ -249,7 +280,7 @@ describe("handleCommand WeChat processing ack", () => {
     expect(registry["feishu-group"]?.sessionId).toBe("sid-feishu-new");
   });
 
-  it("cleans stale Feishu p2p binding but keeps valid commands from auto-creating a group", async () => {
+  it("cleans stale Feishu p2p binding but keeps valid commands from auto-creating a group", async () => {
     const platform = mockPlatform("feishu");
     await recordSessionRegistry({
       chatId: "feishu-p2p",
@@ -264,76 +295,115 @@ describe("handleCommand WeChat processing ack", () => {
     expect(platform.createGroup).not.toHaveBeenCalled();
     expect(platform.sendRawCard).toHaveBeenCalled();
     const registry = await loadSessionRegistryForBinding();
-    expect(registry["feishu-p2p"]).toBeUndefined();
-  });
-
-  it("handles /usage without creating a new Feishu group", async () => {
-    const platform = mockPlatform("feishu");
-    mockGetCodexUsageSummary.mockResolvedValue({
-      fiveHour: { usedPercent: 37, remainingPercent: 63, resetAtEpochSeconds: 1781528212, resetAfterSeconds: 10349 },
-      weekly: { usedPercent: 12, remainingPercent: 88, resetAtEpochSeconds: 1781842926, resetAfterSeconds: 325063 },
-    });
-
-    await handleCommand(platform, "/usage", "feishu-p2p", "ou-user", Date.now(), "p2p");
-
-    expect(platform.createGroup).not.toHaveBeenCalled();
-    expect(platform.sendCard).toHaveBeenCalledWith(
-      "feishu-p2p",
-      "Codex Usage",
-      expect.stringContaining("**5h:** 已用 37%，剩余 63%，重置:"),
-      "blue",
-    );
-    expect(platform.sendCard).toHaveBeenCalledWith(
-      "feishu-p2p",
-      "Codex Usage",
-      expect.stringContaining("约 2小时52分钟后"),
-      "blue",
-    );
-    expect(platform.sendCard).toHaveBeenCalledWith(
-      "feishu-p2p",
-      "Codex Usage",
-      expect.stringContaining("[███████░░░░░░░░░░░░░]"),
-      "blue",
-    );
-    expect(platform.sendCard).toHaveBeenCalledWith(
-      "feishu-p2p",
-      "Codex Usage",
-      expect.stringContaining("**周:** 已用 12%，剩余 88%，重置:"),
-      "blue",
-    );
-    expect(platform.sendCard).toHaveBeenCalledWith(
-      "feishu-p2p",
-      "Codex Usage",
-      expect.stringContaining("约 3天18小时17分钟后"),
-      "blue",
-    );
-    expect(platform.sendCard).toHaveBeenCalledWith(
-      "feishu-p2p",
-      "Codex Usage",
-      expect.stringContaining("[██░░░░░░░░░░░░░░░░░░]"),
-      "blue",
-    );
-  });
-
-  it("only advertises /usage in new Codex session ready messages", async () => {
-    const codexPlatform = mockPlatform("feishu");
-    _setAdapterForToolForTest("codex", mockAdapter("sid-codex"));
-
-    await handleCommand(codexPlatform, "/new codex", "feishu-p2p", "ou-user", Date.now(), "p2p");
-
-    expect(codexPlatform.sendCard).toHaveBeenCalledWith(
-      "feishu-group",
-      "Codex Session Ready",
-      expect.stringContaining("发送 **/usage** 查看 Codex 5h 和周用量。"),
-      "green",
-    );
-
-    const claudePlatform = mockPlatform("feishu");
-    await handleCommand(claudePlatform, "/new claude", "feishu-p2p-2", "ou-user", Date.now(), "p2p");
-
-    const claudeReadyCall = vi.mocked(claudePlatform.sendCard).mock.calls.find(
-      ([chatId, title]) => chatId === "feishu-group" && title === "Claude Code Session Ready",
-    );
-    expect(claudeReadyCall?.[2]).not.toContain("/usage");
-  });
-});
+    expect(registry["feishu-p2p"]).toBeUndefined();
+  });
+
+  it("handles /usage without creating a new Feishu group", async () => {
+    const platform = mockPlatform("feishu");
+    mockGetCodexUsageSummary.mockResolvedValue({
+      fiveHour: { usedPercent: 37, remainingPercent: 63, resetAtEpochSeconds: 1781528212, resetAfterSeconds: 10349 },
+      weekly: { usedPercent: 12, remainingPercent: 88, resetAtEpochSeconds: 1781842926, resetAfterSeconds: 325063 },
+    });
+
+    await handleCommand(platform, "/usage", "feishu-p2p", "ou-user", Date.now(), "p2p");
+
+    expect(platform.createGroup).not.toHaveBeenCalled();
+    expect(platform.sendCard).toHaveBeenCalledWith(
+      "feishu-p2p",
+      "Codex Usage",
+      expect.stringContaining("**5h:** 已用 37%，剩余 63%，重置:"),
+      "blue",
+    );
+    expect(platform.sendCard).toHaveBeenCalledWith(
+      "feishu-p2p",
+      "Codex Usage",
+      expect.stringContaining("约 2小时52分钟后"),
+      "blue",
+    );
+    expect(platform.sendCard).toHaveBeenCalledWith(
+      "feishu-p2p",
+      "Codex Usage",
+      expect.stringContaining("[███████░░░░░░░░░░░░░]"),
+      "blue",
+    );
+    expect(platform.sendCard).toHaveBeenCalledWith(
+      "feishu-p2p",
+      "Codex Usage",
+      expect.stringContaining("**周:** 已用 12%，剩余 88%，重置:"),
+      "blue",
+    );
+    expect(platform.sendCard).toHaveBeenCalledWith(
+      "feishu-p2p",
+      "Codex Usage",
+      expect.stringContaining("约 3天18小时17分钟后"),
+      "blue",
+    );
+    expect(platform.sendCard).toHaveBeenCalledWith(
+      "feishu-p2p",
+      "Codex Usage",
+      expect.stringContaining("[██░░░░░░░░░░░░░░░░░░]"),
+      "blue",
+    );
+  });
+
+  it("handles /usage as Cursor usage in Cursor chats", async () => {
+    const platform = mockPlatform("feishu");
+    await recordSessionRegistry({
+      chatId: "cursor-chat",
+      sessionId: "sid-cursor",
+      tool: "cursor",
+      chatName: "cursor-session",
+      running: false,
+    });
+
+    await handleCommand(platform, "/usage", "cursor-chat", "ou-user", Date.now(), "group");
+
+    expect(platform.createGroup).not.toHaveBeenCalled();
+    expect(mockGetCodexUsageSummary).not.toHaveBeenCalled();
+    expect(mockGetCursorUsageSummary).toHaveBeenCalled();
+    expect(platform.sendCard).toHaveBeenCalledWith(
+      "cursor-chat",
+      "Cursor Usage",
+      expect.stringContaining("Individual used: $1012.52"),
+      "blue",
+    );
+    expect(platform.sendCard).toHaveBeenCalledWith(
+      "cursor-chat",
+      "Cursor Usage",
+      expect.stringContaining("Pool remaining: $171417.76"),
+      "blue",
+    );
+  });
+
+  it("advertises /usage in new Codex and Cursor session ready messages", async () => {
+    const codexPlatform = mockPlatform("feishu");
+    _setAdapterForToolForTest("codex", mockAdapter("sid-codex"));
+
+    await handleCommand(codexPlatform, "/new codex", "feishu-p2p", "ou-user", Date.now(), "p2p");
+
+    expect(codexPlatform.sendCard).toHaveBeenCalledWith(
+      "feishu-group",
+      "Codex Session Ready",
+      expect.stringContaining("发送 **/usage** 查看 Codex 5h 和周用量。"),
+      "green",
+    );
+
+    const cursorPlatform = mockPlatform("feishu");
+    _setAdapterForToolForTest("cursor", mockAdapter("sid-cursor"));
+
+    await handleCommand(cursorPlatform, "/new cursor", "feishu-p2p-cursor", "ou-user", Date.now(), "p2p");
+
+    const cursorReadyCall = vi.mocked(cursorPlatform.sendCard).mock.calls.find(
+      ([chatId, title]) => chatId === "feishu-group" && title === "Cursor Session Ready",
+    );
+    expect(cursorReadyCall?.[2]).toContain("/usage");
+
+    const claudePlatform = mockPlatform("feishu");
+    await handleCommand(claudePlatform, "/new claude", "feishu-p2p-2", "ou-user", Date.now(), "p2p");
+
+    const claudeReadyCall = vi.mocked(claudePlatform.sendCard).mock.calls.find(
+      ([chatId, title]) => chatId === "feishu-group" && title === "Claude Code Session Ready",
+    );
+    expect(claudeReadyCall?.[2]).not.toContain("/usage");
+  });
+});

package/src/cards.ts

@@ -133,11 +133,11 @@ export function buildHelpCard(
     "发送 **/new cursor** 创建新 Cursor 会话",
     "发送 **/new codex** 创建新 Codex 会话",
     "发送 **/newh** 重置当前会话（沿用当前工作目录，不切换）",
-    "发送 **/plan** 以规划模式提问（只读，不执行写操作）",
-    "发送 **/ask** 以问答模式提问（只读，不执行写操作）",
-    "发送 **/usage** 查看 Codex 5h 和周用量",
-    "发送 **/restart** 重启 ChatCCC 进程",
-    "发送 **/updateg** 更新并重启（仅 npm 全局安装可用）",
+    "发送 **/plan** 以规划模式提问（只读，不执行写操作）",
+    "发送 **/ask** 以问答模式提问（只读，不执行写操作）",
+    "发送 **/usage** 查看 Codex 5h 和周用量",
+    "发送 **/restart** 重启 ChatCCC 进程",
+    "发送 **/update** 更新并重启（仅 npm 全局安装可用）",
   ].join("\n");
   return JSON.stringify({
     config: { wide_screen_mode: true },
@@ -151,7 +151,7 @@ export function buildHelpCard(
         { text: "新建 Cursor 会话（/new cursor）", value: JSON.stringify({ cmd: "new cursor" }), type: "primary" },
         { text: "新建 Codex 会话（/new codex）", value: JSON.stringify({ cmd: "new codex" }), type: "primary" },
         { text: "重启 ChatCCC（/restart）", value: JSON.stringify({ cmd: "restart" }), type: "danger" },
-        { text: "更新并重启（/updateg）", value: JSON.stringify({ cmd: "updateg" }), type: "danger" },
+        { text: "更新并重启（/update）", value: JSON.stringify({ cmd: "update" }), type: "danger" },
         { text: "切换工作路径（/cd）", value: JSON.stringify({ cmd: "cd" }), type: "default" },
       ]),
     ],

package/src/config.ts

@@ -81,6 +81,8 @@ export interface CursorConfig {
   /** Cursor Agent CLI 可执行文件绝对路径；留空时由运行时按 LocalAppData / PATH 兜底 */
   path: string;
   model: string;
+  avatarBatteryMode: CursorAvatarBatteryMode;
+  onDemandMonthlyBudget: number;
 }
 
 export interface CodexConfig {
@@ -125,6 +127,7 @@ export interface AppConfig {
 
 export type AgentTool = "claude" | "cursor" | "codex";
 export const AGENT_TOOLS: AgentTool[] = ["claude", "cursor", "codex"];
+export type CursorAvatarBatteryMode = "apiPercent" | "onDemandUse";
 
 /** 获取指定 agent 配置中所有模型相关的值（最多 100 个，去重） */
 export function getAllModelsForTool(tool: AgentTool, cfg: AppConfig = config): string[] {
@@ -326,6 +329,15 @@ function normalizePlatformType(raw: string): "feishu" | "lark" {
   return "feishu";
 }
 
+function normalizeCursorAvatarBatteryMode(raw: unknown): CursorAvatarBatteryMode {
+  return raw === "onDemandUse" ? "onDemandUse" : "apiPercent";
+}
+
+function normalizeCursorOnDemandMonthlyBudget(raw: unknown): number {
+  const value = typeof raw === "string" ? Number(raw.trim()) : Number(raw);
+  return Number.isFinite(value) && value > 0 ? value : 1000;
+}
+
 function loadConfig(): AppConfig {
   const defaults: AppConfig = {
     feishu: { appId: "", appSecret: "" },
@@ -334,7 +346,14 @@ function loadConfig(): AppConfig {
     gitTimeoutSeconds: 180,
     allowInterrupt: false,
     claude: { enabled: false, defaultAgent: true, model: "", subagentModel: "", effort: "", apiKey: "", baseUrl: "", maxTurn: 0 },
-    cursor: { enabled: false, defaultAgent: false, path: "", model: "claude-opus-4-7-max" },
+    cursor: {
+      enabled: false,
+      defaultAgent: false,
+      path: "",
+      model: "claude-opus-4-7-max",
+      avatarBatteryMode: "apiPercent",
+      onDemandMonthlyBudget: 1000,
+    },
     codex: { enabled: false, defaultAgent: false, path: "", model: "", effort: "" },
   };
 
@@ -377,7 +396,15 @@ function loadConfig(): AppConfig {
 
   let parsed: Partial<AppConfig> & {
     claude?: Partial<ClaudeConfig> & { enabled?: unknown };
-    cursor?: { enabled?: unknown; defaultAgent?: unknown; path?: unknown; command?: unknown; model?: unknown };
+    cursor?: {
+      enabled?: unknown;
+      defaultAgent?: unknown;
+      path?: unknown;
+      command?: unknown;
+      model?: unknown;
+      avatarBatteryMode?: unknown;
+      onDemandMonthlyBudget?: unknown;
+    };
     codex?: { enabled?: unknown; defaultAgent?: unknown; path?: unknown; command?: unknown; model?: unknown; effort?: unknown };
   };
   try {
@@ -491,6 +518,8 @@ function loadConfig(): AppConfig {
       defaultAgent: defaultTool === "cursor",
       path: readToolCliPath(cursorRaw, { label: "cursor", onLegacyField }),
       model: normalizeOptionalConfigField(cursorRaw.model, { label: "cursor.model", fallback: "claude-opus-4-7-max" }),
+      avatarBatteryMode: normalizeCursorAvatarBatteryMode(cursorRaw.avatarBatteryMode),
+      onDemandMonthlyBudget: normalizeCursorOnDemandMonthlyBudget(cursorRaw.onDemandMonthlyBudget),
     },
     codex: {
       enabled: codexEnabled,

package/src/cursor-usage.ts

@@ -0,0 +1,128 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const require = createRequire(import.meta.url);
+
+const CURSOR_USAGE_URL = "https://api2.cursor.sh/aiserver.v1.DashboardService/GetCurrentPeriodUsage";
+
+export type CursorUsageSummary = {
+  billingCycleStart?: string;
+  billingCycleEnd?: string;
+  planUsage?: {
+    totalSpend?: number;
+    includedSpend?: number;
+    bonusSpend?: number;
+    limit?: number;
+    remainingBonus?: boolean;
+    bonusTooltip?: string;
+    autoPercentUsed?: number;
+    apiPercentUsed?: number;
+    totalPercentUsed?: number;
+  };
+  spendLimitUsage?: {
+    totalSpend?: number;
+    pooledLimit?: number;
+    pooledUsed?: number;
+    pooledRemaining?: number;
+    individualUsed?: number;
+    limitType?: string;
+  };
+  displayThreshold?: number;
+  enabled?: boolean;
+  displayMessage?: string;
+  autoModelSelectedDisplayMessage?: string;
+  namedModelSelectedDisplayMessage?: string;
+  autoBucketModels?: string[];
+};
+
+type SqliteStatement = {
+  get(value?: unknown): unknown;
+  all(value?: unknown): unknown[];
+};
+
+type SqliteDatabase = {
+  prepare(sql: string): SqliteStatement;
+  close(): void;
+};
+
+function getCursorDbPath(): string {
+  if (process.platform === "win32") {
+    return join(process.env.APPDATA || "", "Cursor", "User", "globalStorage", "state.vscdb");
+  }
+
+  if (process.platform === "darwin") {
+    return join(homedir(), "Library", "Application Support", "Cursor", "User", "globalStorage", "state.vscdb");
+  }
+
+  return join(homedir(), ".config", "Cursor", "User", "globalStorage", "state.vscdb");
+}
+
+function openSqliteDatabase(dbPath: string): SqliteDatabase {
+  try {
+    const { DatabaseSync } = require("node:sqlite") as {
+      DatabaseSync?: new (path: string, opts: { readOnly: boolean }) => SqliteDatabase;
+    };
+    if (DatabaseSync) return new DatabaseSync(dbPath, { readOnly: true });
+  } catch (error) {
+    const code = (error as { code?: string }).code;
+    if (code !== "ERR_UNKNOWN_BUILTIN_MODULE" && code !== "MODULE_NOT_FOUND") {
+      throw error;
+    }
+  }
+
+  try {
+    const Database = require("better-sqlite3") as new (path: string, opts: { readonly: boolean }) => SqliteDatabase;
+    return new Database(dbPath, { readonly: true });
+  } catch {
+    throw new Error("node:sqlite is unavailable and better-sqlite3 is not installed");
+  }
+}
+
+function parseStorageValue(value: unknown): unknown {
+  if (typeof value !== "string") return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+function getCursorAccessToken(dbPath = getCursorDbPath()): string {
+  if (!existsSync(dbPath)) {
+    throw new Error(`Cursor database not found: ${dbPath}`);
+  }
+
+  const db = openSqliteDatabase(dbPath);
+
+  try {
+    const row = db.prepare("SELECT value FROM ItemTable WHERE key = ?").get("cursorAuth/accessToken") as
+      | { value?: unknown }
+      | undefined;
+    const token = parseStorageValue(row?.value);
+    if (typeof token === "string" && token.length > 0) return token;
+    throw new Error("Cursor access token not found");
+  } finally {
+    db.close();
+  }
+}
+
+export async function getCursorUsageSummary(): Promise<CursorUsageSummary> {
+  const token = getCursorAccessToken();
+  const response = await fetch(CURSOR_USAGE_URL, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+      "Connect-Protocol-Version": "1",
+    },
+    body: "{}",
+  });
+
+  if (!response.ok) {
+    throw new Error(`Cursor usage API returned ${response.status} ${response.statusText}`);
+  }
+
+  return (await response.json()) as CursorUsageSummary;
+}

package/src/feishu-api.ts

@@ -17,7 +17,9 @@ import {
   ts,
   resolveDefaultAgentTool,
   toolDisplayName,
+  config,
 } from "./config.ts";
+import { getCursorUsageSummary, type CursorUsageSummary } from "./cursor-usage.ts";
 import { applyPrivacy } from "./privacy.ts";
 
 // ---------------------------------------------------------------------------
@@ -316,6 +318,7 @@ const AVATAR_SIZE = 256;
 const AVATAR_BADGE_SIZE = 92;
 const AVATAR_BADGE_MARGIN = 10;
 const CODEX_AVATAR_USAGE_STYLE_VERSION = "usage-ring-gray-consumed-v13";
+const CURSOR_AVATAR_USAGE_STYLE_VERSION = "usage-battery-v1";
 
 export interface CodexUsageBalance {
   usedPercent: number;
@@ -344,7 +347,12 @@ function avatarCombinationPath(tool: string, status: string): string {
   return resolvePath(AVATAR_COMBINATIONS_DIR, `avatar_${normalizeAvatarTool(tool)}_${normalizeAvatarStatus(status)}.png`);
 }
 
-function avatarCacheKey(tool: string, status: string, codexUsage: CodexUsageSummary | null = null): string {
+function avatarCacheKey(
+  tool: string,
+  status: string,
+  codexUsage: CodexUsageSummary | null = null,
+  cursorBatteryPercent: number | null = null,
+): string {
   const normalizedTool = normalizeAvatarTool(tool);
   const normalizedStatus = normalizeAvatarStatus(status);
   if (normalizedTool === "codex") {
@@ -352,6 +360,11 @@ function avatarCacheKey(tool: string, status: string, codexUsage: CodexUsageSumm
       ? `${normalizedTool}:${normalizedStatus}:${CODEX_AVATAR_USAGE_STYLE_VERSION}:week-battery:${codexUsage.weekly?.remainingPercent}:5h-ring:${codexUsage.fiveHour.remainingPercent}`
       : `${normalizedTool}:${normalizedStatus}:plain`;
   }
+  if (normalizedTool === "cursor") {
+    return cursorBatteryPercent !== null
+      ? `${normalizedTool}:${normalizedStatus}:${CURSOR_AVATAR_USAGE_STYLE_VERSION}:battery:${cursorBatteryPercent}`
+      : `${normalizedTool}:${normalizedStatus}:plain`;
+  }
   return `${normalizedTool}:${normalizedStatus}`;
 }
 
@@ -460,6 +473,28 @@ async function fetchCodexAvatarUsage(): Promise<CodexUsageSummary | null> {
   }
 }
 
+function cursorAvatarBatteryPercentFromUsage(summary: CursorUsageSummary): number {
+  if (config.cursor.avatarBatteryMode === "onDemandUse") {
+    const usedCents = Number(summary.spendLimitUsage?.individualUsed);
+    if (!Number.isFinite(usedCents)) throw new Error("missing spendLimitUsage.individualUsed");
+    const budget = config.cursor.onDemandMonthlyBudget > 0 ? config.cursor.onDemandMonthlyBudget : 1000;
+    return clampPercent(100 - ((usedCents / 100) / budget) * 100);
+  }
+
+  const apiPercentUsed = Number(summary.planUsage?.apiPercentUsed);
+  if (!Number.isFinite(apiPercentUsed)) throw new Error("missing planUsage.apiPercentUsed");
+  return clampPercent(100 - apiPercentUsed);
+}
+
+async function fetchCursorAvatarBatteryPercent(): Promise<number | null> {
+  try {
+    return cursorAvatarBatteryPercentFromUsage(await getCursorUsageSummary());
+  } catch (err) {
+    console.warn(`[${ts()}] [AVATAR] Cursor usage unavailable, using plain avatar: ${(err as Error).message}`);
+    return null;
+  }
+}
+
 function codexUsagePalette(remainingPercent: number): { start: string; end: string; glow: string } {
   if (remainingPercent <= 25) return { start: "#ef4444", end: "#fb923c", glow: "#fed7aa" };
   if (remainingPercent <= 60) return { start: "#eab308", end: "#facc15", glow: "#fef3c7" };
@@ -573,20 +608,32 @@ async function buildAgentBadgeOverlay(tool: string): Promise<sharp.OverlayOption
   };
 }
 
-async function renderAvatar(tool: string, status: string, codexUsage: CodexUsageSummary | null = null): Promise<{ buffer: Buffer; contentType: string; filename: string }> {
+async function renderAvatar(
+  tool: string,
+  status: string,
+  codexUsage: CodexUsageSummary | null = null,
+  cursorBatteryPercent: number | null = null,
+): Promise<{ buffer: Buffer; contentType: string; filename: string }> {
   const normalizedTool = normalizeAvatarTool(tool);
   const normalizedStatus = normalizeAvatarStatus(status);
   const composites: sharp.OverlayOptions[] = [];
 
-  const useDynamicCodexAvatar = normalizedTool === "codex" && codexUsage?.weekly;
-  const basePath = useDynamicCodexAvatar
+  const codexWeeklyUsage = normalizedTool === "codex" ? codexUsage?.weekly : null;
+  const useDynamicCodexAvatar = codexUsage && codexWeeklyUsage;
+  const useDynamicCursorAvatar = normalizedTool === "cursor" && cursorBatteryPercent !== null;
+  const basePath = useDynamicCodexAvatar || useDynamicCursorAvatar
     ? AVATAR_SOURCES[normalizedStatus]
     : avatarCombinationPath(normalizedTool, normalizedStatus);
 
   if (useDynamicCodexAvatar) {
     composites.push(
       { input: buildCodexUsageRingSvg(codexUsage.fiveHour.remainingPercent), left: 0, top: 0 },
-      { input: buildCodexUsageBatterySvg(codexUsage.weekly.remainingPercent), left: 0, top: 0 },
+      { input: buildCodexUsageBatterySvg(codexWeeklyUsage.remainingPercent), left: 0, top: 0 },
+      await buildAgentBadgeOverlay(normalizedTool),
+    );
+  } else if (useDynamicCursorAvatar) {
+    composites.push(
+      { input: buildCodexUsageBatterySvg(cursorBatteryPercent), left: 0, top: 0 },
       await buildAgentBadgeOverlay(normalizedTool),
     );
   }
@@ -608,12 +655,20 @@ async function renderAvatar(tool: string, status: string, codexUsage: CodexUsage
     contentType: "image/jpeg",
     filename: codexUsage?.weekly
       ? `avatar_${normalizedTool}_${normalizedStatus}_week_${codexUsage.weekly.remainingPercent}_5h_${codexUsage.fiveHour.remainingPercent}.jpg`
+      : cursorBatteryPercent !== null
+        ? `avatar_${normalizedTool}_${normalizedStatus}_battery_${cursorBatteryPercent}.jpg`
       : `avatar_${normalizedTool}_${normalizedStatus}.jpg`,
   };
 }
 
-async function uploadImage(token: string, tool: string, status: string, codexUsage: CodexUsageSummary | null = null): Promise<string> {
-  const image = await renderAvatar(tool, status, codexUsage);
+async function uploadImage(
+  token: string,
+  tool: string,
+  status: string,
+  codexUsage: CodexUsageSummary | null = null,
+  cursorBatteryPercent: number | null = null,
+): Promise<string> {
+  const image = await renderAvatar(tool, status, codexUsage, cursorBatteryPercent);
   const blob = new Blob([new Uint8Array(image.buffer)], { type: image.contentType });
   const form = new FormData();
   form.append("image_type", "avatar");
@@ -639,10 +694,11 @@ async function getOrUploadAvatarKey(token: string, tool: string, status: string)
   const normalizedTool = normalizeAvatarTool(tool);
   const normalizedStatus = normalizeAvatarStatus(status);
   const codexUsage = normalizedTool === "codex" ? await fetchCodexAvatarUsage() : null;
-  const keyName = avatarCacheKey(normalizedTool, normalizedStatus, codexUsage);
+  const cursorBatteryPercent = normalizedTool === "cursor" ? await fetchCursorAvatarBatteryPercent() : null;
+  const keyName = avatarCacheKey(normalizedTool, normalizedStatus, codexUsage, cursorBatteryPercent);
   const cached = avatarKeyCache.get(keyName);
   if (cached) return cached;
-  const key = await uploadImage(token, normalizedTool, normalizedStatus, codexUsage);
+  const key = await uploadImage(token, normalizedTool, normalizedStatus, codexUsage, cursorBatteryPercent);
   avatarKeyCache.set(keyName, key);
   await persistAvatarKeyCache().catch((err) => {
     console.error(`[${ts()}] [AVATAR] persist cache FAIL: ${(err as Error).message}`);