chatccc 0.2.187 → 0.2.188

package/src/config.ts

@@ -88,9 +88,9 @@ export interface CursorConfig {
   onDemandMonthlyBudget: number;
 }
 
-export interface CodexConfig {
-  /** 是否启用 Codex Agent；缺省时按"有任意字段非空"自动判定（向后兼容） */
-  enabled: boolean;
+export interface CodexConfig {
+  /** 是否启用 Codex Agent；缺省时按"有任意字段非空"自动判定（向后兼容） */
+  enabled: boolean;
   /** 是否作为 /new 未指定工具时使用的默认 Agent */
   defaultAgent: boolean;
   /** Codex CLI 可执行文件绝对路径；留空时退回到 PATH 中的 `codex` */
@@ -98,13 +98,22 @@ export interface CodexConfig {
   model: string;
   /** /model 可切换的单个备选模型；留空则不加入候选列表 */
   alternativeModel: string;
-  effort: string;
-}
-
-export interface FeishuConfig {
-  appId: string;
-  appSecret: string;
-}
+  effort: string;
+}
+
+export interface CccConfig {
+  /** DeepSeek API Key for the ChatCCC self-developed agent. */
+  DEEPSEEK_API_KEY: string;
+  /** DeepSeek-compatible API Base URL for the ChatCCC self-developed agent. */
+  DEEPSEEK_BASE_URL: string;
+  /** Model used by the ChatCCC self-developed agent. */
+  model: string;
+}
+
+export interface FeishuConfig {
+  appId: string;
+  appSecret: string;
+}
 
 export interface PlatformConfig {
   enabled: boolean;
@@ -149,21 +158,22 @@ export interface AppConfig {
   /** 若为 false，AI 生成过程中用户发送消息不会打断，须先点「停止」再发送新消息 */
   allowInterrupt: boolean;
   rawStreamLogs: RawStreamLogsConfig;
-  claude: ClaudeConfig;
-  cursor: CursorConfig;
-  codex: CodexConfig;
-}
+  claude: ClaudeConfig;
+  cursor: CursorConfig;
+  codex: CodexConfig;
+  ccc: CccConfig;
+}
 
 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[] {
-  const seen = new Set<string>();
-  const collect = (v: unknown) => {
-    if (typeof v === "string" && v.trim()) seen.add(v.trim());
-  };
+export function getAllModelsForTool(tool: AgentTool, cfg: AppConfig = config): string[] {
+  const seen = new Set<string>();
+  const collect = (v: unknown) => {
+    if (typeof v === "string" && v.trim()) seen.add(v.trim());
+  };
 
   if (tool === "claude") {
     collect(cfg.claude.model);
@@ -175,12 +185,29 @@ export function getAllModelsForTool(tool: AgentTool, cfg: AppConfig = config): s
     collect(cfg.codex.model);
     collect(cfg.codex.alternativeModel);
   }
-
-  return Array.from(seen).slice(0, 100);
-}
-
-const CONFIG_FILE = join(USER_DATA_DIR, "config.json");
-const CONFIG_SAMPLE_FILE = join(PROJECT_ROOT, "config.sample.json");
+
+  return Array.from(seen).slice(0, 100);
+}
+
+export const CLAUDE_EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"] as const;
+export const CODEX_EFFORT_LEVELS = ["minimal", "low", "medium", "high", "xhigh"] as const;
+
+export function getAllEffortsForTool(tool: AgentTool): string[] {
+  if (tool === "claude") return [...CLAUDE_EFFORT_LEVELS];
+  if (tool === "codex") return [...CODEX_EFFORT_LEVELS];
+  return [];
+}
+
+export function getDefaultEffortForTool(tool: AgentTool, cfg: AppConfig = config): string {
+  if (tool === "claude") return cfg.claude.effort;
+  if (tool === "codex") return cfg.codex.effort;
+  return "";
+}
+
+const CONFIG_FILE = join(USER_DATA_DIR, "config.json");
+const CONFIG_SAMPLE_FILE = join(PROJECT_ROOT, "config.sample.json");
+export const DEFAULT_CCC_DEEPSEEK_BASE_URL = "https://api.deepseek.com/v1";
+export const DEFAULT_CCC_MODEL = "deepseek-v4-pro[1m]";
 
 /**
  * 将旧位置（PROJECT_ROOT）的持久化数据一次性迁移到 USER_DATA_DIR。
@@ -398,8 +425,8 @@ function loadConfig(): AppConfig {
       claude: { enabled: false, maxBytesPerTurn: 50 * 1024 * 1024, retentionDays: 7, keepCompleted: false },
       cursor: { enabled: false, maxBytesPerTurn: 50 * 1024 * 1024, retentionDays: 7, keepCompleted: false },
       codex: { enabled: false, maxBytesPerTurn: 50 * 1024 * 1024, retentionDays: 7, keepCompleted: false },
-    },
-    claude: { enabled: false, defaultAgent: true, model: "", subagentModel: "", effort: "", apiKey: "", baseUrl: "", maxTurn: 0 },
+    },
+    claude: { enabled: false, defaultAgent: true, model: "", subagentModel: "", effort: "", apiKey: "", baseUrl: "", maxTurn: 0 },
     cursor: {
       enabled: false,
       defaultAgent: false,
@@ -408,9 +435,10 @@ function loadConfig(): AppConfig {
       alternativeModel: "",
       avatarBatteryMode: "apiPercent",
       onDemandMonthlyBudget: 1000,
-    },
-    codex: { enabled: false, defaultAgent: false, path: "", model: "", alternativeModel: "", effort: "" },
-  };
+    },
+    codex: { enabled: false, defaultAgent: false, path: "", model: "", alternativeModel: "", effort: "" },
+    ccc: { DEEPSEEK_API_KEY: "", DEEPSEEK_BASE_URL: DEFAULT_CCC_DEEPSEEK_BASE_URL, model: DEFAULT_CCC_MODEL },
+  };
 
   if (!IS_TEST_ENV) {
     migrateLegacyData();
@@ -460,11 +488,12 @@ function loadConfig(): AppConfig {
       alternativeModel?: unknown;
       avatarBatteryMode?: unknown;
       onDemandMonthlyBudget?: unknown;
-    };
-    codex?: { enabled?: unknown; defaultAgent?: unknown; path?: unknown; command?: unknown; model?: unknown; alternativeModel?: unknown; effort?: unknown };
-    chromeDevtools?: { enabled?: unknown; port?: unknown; chromePath?: unknown };
-    rawStreamLogs?: unknown;
-  };
+    };
+    codex?: { enabled?: unknown; defaultAgent?: unknown; path?: unknown; command?: unknown; model?: unknown; alternativeModel?: unknown; effort?: unknown };
+    ccc?: { DEEPSEEK_API_KEY?: unknown; DEEPSEEK_BASE_URL?: unknown; model?: unknown };
+    chromeDevtools?: { enabled?: unknown; port?: unknown; chromePath?: unknown };
+    rawStreamLogs?: unknown;
+  };
   try {
     parsed = JSON.parse(raw);
   } catch (err) {
@@ -474,9 +503,10 @@ function loadConfig(): AppConfig {
 
   const feishu = parsed.feishu ?? { appId: "", appSecret: "" };
   const claude = parsed.claude ?? {} as Partial<ClaudeConfig>;
-  const cursorRaw = (parsed.cursor ?? {}) as NonNullable<typeof parsed.cursor>;
-  const codexRaw = (parsed.codex ?? {}) as NonNullable<typeof parsed.codex>;
-  const chromeDevtoolsRaw = (parsed.chromeDevtools ?? {}) as NonNullable<typeof parsed.chromeDevtools>;
+  const cursorRaw = (parsed.cursor ?? {}) as NonNullable<typeof parsed.cursor>;
+  const codexRaw = (parsed.codex ?? {}) as NonNullable<typeof parsed.codex>;
+  const cccRaw = (parsed.ccc ?? {}) as NonNullable<typeof parsed.ccc>;
+  const chromeDevtoolsRaw = (parsed.chromeDevtools ?? {}) as NonNullable<typeof parsed.chromeDevtools>;
   const rawStreamLogsRaw = typeof parsed.rawStreamLogs === "object" && parsed.rawStreamLogs !== null
     ? parsed.rawStreamLogs as unknown as Record<string, unknown>
     : {};
@@ -599,16 +629,24 @@ function loadConfig(): AppConfig {
       avatarBatteryMode: normalizeCursorAvatarBatteryMode(cursorRaw.avatarBatteryMode),
       onDemandMonthlyBudget: normalizeCursorOnDemandMonthlyBudget(cursorRaw.onDemandMonthlyBudget),
     },
-    codex: {
-      enabled: codexEnabled,
-      defaultAgent: defaultTool === "codex",
-      path: readToolCliPath(codexRaw, { label: "codex", onLegacyField }),
-      model: normalizeOptionalConfigField(codexRaw.model, { label: "codex.model" }),
-      alternativeModel: normalizeOptionalConfigField(codexRaw.alternativeModel, { label: "codex.alternativeModel" }),
-      effort: normalizeOptionalConfigField(codexRaw.effort, { label: "codex.effort" }),
-    },
-  };
-}
+    codex: {
+      enabled: codexEnabled,
+      defaultAgent: defaultTool === "codex",
+      path: readToolCliPath(codexRaw, { label: "codex", onLegacyField }),
+      model: normalizeOptionalConfigField(codexRaw.model, { label: "codex.model" }),
+      alternativeModel: normalizeOptionalConfigField(codexRaw.alternativeModel, { label: "codex.alternativeModel" }),
+      effort: normalizeOptionalConfigField(codexRaw.effort, { label: "codex.effort" }),
+    },
+    ccc: {
+      DEEPSEEK_API_KEY: normalizeOptionalConfigField(cccRaw.DEEPSEEK_API_KEY, { label: "ccc.DEEPSEEK_API_KEY" }),
+      DEEPSEEK_BASE_URL: normalizeOptionalConfigField(cccRaw.DEEPSEEK_BASE_URL, {
+        label: "ccc.DEEPSEEK_BASE_URL",
+        fallback: DEFAULT_CCC_DEEPSEEK_BASE_URL,
+      }),
+      model: normalizeOptionalConfigField(cccRaw.model, { label: "ccc.model", fallback: DEFAULT_CCC_MODEL }),
+    },
+  };
+}
 
 /**
  * 全局可变 config 对象。

package/src/feishu-api.ts

@@ -20,6 +20,7 @@ import {
   config,
 } from "./config.ts";
 import { getCursorUsageSummary, type CursorUsageSummary } from "./cursor-usage.ts";
+import type { ChatAvatarUsageHints } from "./platform-adapter.ts";
 import { applyPrivacy } from "./privacy.ts";
 
 // ---------------------------------------------------------------------------
@@ -302,10 +303,10 @@ const AVATAR_DIR = resolvePath(PROJECT_ROOT, "images", "avatars");
 const AVATAR_BADGE_DIR = resolvePath(AVATAR_DIR, "badges");
 const AVATAR_COMBINATIONS_DIR = resolvePath(AVATAR_DIR, "combinations");
 const AVATAR_KEY_CACHE_FILE = resolvePath(USER_DATA_DIR, "state", "avatar-image-keys.json");
-const CODEX_AUTH_FILE = resolvePath(homedir(), ".codex", "auth.json");
-const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
-const CODEX_RESET_CREDITS_URL = "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits";
-const CODEX_RESET_CONSUME_URL = "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits/consume";
+const CODEX_AUTH_FILE = resolvePath(homedir(), ".codex", "auth.json");
+const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+const CODEX_RESET_CREDITS_URL = "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits";
+const CODEX_RESET_CONSUME_URL = "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits/consume";
 const AVATAR_SOURCES: Record<string, string> = {
   new: resolvePath(AVATAR_DIR, "status_new.png"),
   busy: resolvePath(AVATAR_DIR, "status_busy.png"),
@@ -322,31 +323,31 @@ 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;
-  remainingPercent: number;
-  resetAtEpochSeconds: number | null;
-  resetAfterSeconds: number | null;
-}
-
-export interface CodexRateLimitResetCredit {
-  grantedAt: string | null;
-  expiresAt: string;
-}
-
-export interface CodexUsageSummary {
-  fiveHour: CodexUsageBalance;
-  weekly: CodexUsageBalance | null;
-  rateLimitResetCreditsAvailable: number | null;
-  rateLimitResetCredits: CodexRateLimitResetCredit[] | null;
-}
-
-export type CodexResetConsumeCode = "reset" | "nothing_to_reset" | "no_credit" | "already_redeemed";
-
-export interface CodexResetConsumeResult {
-  code: CodexResetConsumeCode;
-  windowsReset: number;
-}
+export interface CodexUsageBalance {
+  usedPercent: number;
+  remainingPercent: number;
+  resetAtEpochSeconds: number | null;
+  resetAfterSeconds: number | null;
+}
+
+export interface CodexRateLimitResetCredit {
+  grantedAt: string | null;
+  expiresAt: string;
+}
+
+export interface CodexUsageSummary {
+  fiveHour: CodexUsageBalance;
+  weekly: CodexUsageBalance | null;
+  rateLimitResetCreditsAvailable: number | null;
+  rateLimitResetCredits: CodexRateLimitResetCredit[] | null;
+}
+
+export type CodexResetConsumeCode = "reset" | "nothing_to_reset" | "no_credit" | "already_redeemed";
+
+export interface CodexResetConsumeResult {
+  code: CodexResetConsumeCode;
+  windowsReset: number;
+}
 
 const avatarKeyCache = new Map<string, string>();
 let avatarKeyCacheLoaded = false;
@@ -427,167 +428,172 @@ function usageBalanceFromWindow(raw: Record<string, unknown>, fieldName: string)
   };
 }
 
-function parseOptionalUsageWindow(rateLimit: Record<string, unknown>, keys: string[]): CodexUsageBalance | null {
+function parseOptionalUsageWindow(rateLimit: Record<string, unknown>, keys: string[]): CodexUsageBalance | null {
   for (const key of keys) {
     const raw = rateLimit[key];
     if (!raw || typeof raw !== "object") continue;
     if ((raw as { used_percent?: unknown }).used_percent === undefined) continue;
     return usageBalanceFromWindow(raw as Record<string, unknown>, `rate_limit.${key}`);
   }
-  return null;
-}
-
-function parseRateLimitResetCredits(data: Record<string, unknown>): number | null {
-  const raw = data.rate_limit_reset_credits;
-  if (!raw || typeof raw !== "object") return null;
-  const availableCount = Number((raw as { available_count?: unknown }).available_count);
-  if (!Number.isFinite(availableCount)) return null;
-  return Math.max(0, Math.trunc(availableCount));
-}
-
-interface CodexAuth {
-  accessToken: string;
-  accountId?: string;
-}
-
-async function getCodexAuth(): Promise<CodexAuth | null> {
-  try {
-    const raw = await readFile(CODEX_AUTH_FILE, "utf-8");
-    const parsed = JSON.parse(raw) as { tokens?: { access_token?: unknown; account_id?: unknown } };
-    const token = parsed.tokens?.access_token;
-    if (typeof token !== "string" || !token.trim()) return null;
-    const accountId = parsed.tokens?.account_id;
-    return {
-      accessToken: token,
-      accountId: typeof accountId === "string" && accountId.trim() ? accountId : undefined,
-    };
-  } catch {
-    return null;
-  }
-}
-
-async function getCodexAccessToken(): Promise<string | null> {
-  return (await getCodexAuth())?.accessToken ?? null;
-}
-
-function codexAuthHeaders(auth: CodexAuth): Record<string, string> {
-  const headers: Record<string, string> = {
-    Authorization: `Bearer ${auth.accessToken}`,
-    "OpenAI-Beta": "codex-1",
-    originator: "Codex Desktop",
-  };
-  if (auth.accountId) headers["ChatGPT-Account-ID"] = auth.accountId;
-  return headers;
-}
-
-function parseCodexResetCreditDetails(data: Record<string, unknown>): {
-  availableCount: number | null;
-  availableCredits: CodexRateLimitResetCredit[];
-} {
-  const availableCount = Number(data.available_count);
-  const credits = Array.isArray(data.credits) ? data.credits : [];
-  return {
-    availableCount: Number.isFinite(availableCount) ? Math.max(0, Math.trunc(availableCount)) : null,
-    availableCredits: credits.flatMap((raw) => {
-      if (!raw || typeof raw !== "object") return [];
-      const credit = raw as { status?: unknown; granted_at?: unknown; expires_at?: unknown };
-      if (credit.status !== "available") return [];
-      if (typeof credit.expires_at !== "string" || !credit.expires_at.trim()) return [];
-      return [{
-        grantedAt: typeof credit.granted_at === "string" && credit.granted_at.trim() ? credit.granted_at : null,
-        expiresAt: credit.expires_at,
-      }];
-    }),
-  };
-}
-
-async function fetchCodexRateLimitResetCredits(auth: CodexAuth): Promise<{
-  availableCount: number | null;
-  availableCredits: CodexRateLimitResetCredit[];
-} | null> {
-  try {
-    const resp = await fetch(CODEX_RESET_CREDITS_URL, {
-      headers: codexAuthHeaders(auth),
-    });
-    const text = await resp.text();
-    if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${text.slice(0, 160)}`);
-    return parseCodexResetCreditDetails(JSON.parse(text) as Record<string, unknown>);
-  } catch (err) {
-    console.warn(`[Codex] reset credits lookup failed: ${(err as Error).message}`);
-    return null;
-  }
-}
-
-export async function getCodexUsageSummary(): Promise<CodexUsageSummary> {
-  const auth = await getCodexAuth();
-  if (!auth) throw new Error("missing ~/.codex/auth.json access token");
-
-  const resetCreditsPromise = fetchCodexRateLimitResetCredits(auth);
-
-  const resp = await fetch(CODEX_USAGE_URL, {
-    headers: { Authorization: `Bearer ${auth.accessToken}` },
-  });
-  const text = await resp.text();
-  if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${text.slice(0, 160)}`);
-
-  const data = JSON.parse(text) as {
-    rate_limit?: Record<string, unknown>;
-    rate_limit_reset_credits?: unknown;
-  };
-  const rateLimit = data.rate_limit;
-  if (!rateLimit || typeof rateLimit !== "object") throw new Error("missing rate_limit");
-
-  const fiveHour = parseOptionalUsageWindow(rateLimit, ["primary_window"]);
-  if (!fiveHour) throw new Error("missing rate_limit.primary_window.used_percent");
-  const resetCredits = await resetCreditsPromise;
-
-  return {
-    fiveHour,
-    weekly: parseOptionalUsageWindow(rateLimit, [
-      "secondary_window",
-      "weekly_window",
-      "week_window",
-      "long_window",
-    ]),
-    rateLimitResetCreditsAvailable: resetCredits?.availableCount ?? parseRateLimitResetCredits(data),
-    rateLimitResetCredits: resetCredits?.availableCredits ?? null,
-  };
-}
-
-export async function consumeCodexRateLimitResetCredit(redeemRequestId: string): Promise<CodexResetConsumeResult> {
-  if (!redeemRequestId.trim()) throw new Error("missing redeem_request_id");
-  const token = await getCodexAccessToken();
-  if (!token) throw new Error("missing ~/.codex/auth.json access token");
-
-  const resp = await fetch(CODEX_RESET_CONSUME_URL, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${token}`,
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify({ redeem_request_id: redeemRequestId }),
-  });
-  const text = await resp.text();
-  if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${text.slice(0, 160)}`);
-
-  const data = JSON.parse(text) as { code?: unknown; windows_reset?: unknown };
-  const code = data.code;
-  if (
-    code !== "reset"
-    && code !== "nothing_to_reset"
-    && code !== "no_credit"
-    && code !== "already_redeemed"
-  ) {
-    throw new Error("missing or unknown reset result code");
-  }
-  const windowsReset = Number(data.windows_reset);
-  return {
-    code,
-    windowsReset: Number.isFinite(windowsReset) ? Math.max(0, Math.trunc(windowsReset)) : 0,
-  };
-}
-
-async function fetchCodexAvatarUsage(): Promise<CodexUsageSummary | null> {
+  return null;
+}
+
+function parseRateLimitResetCredits(data: Record<string, unknown>): number | null {
+  const raw = data.rate_limit_reset_credits;
+  if (!raw || typeof raw !== "object") return null;
+  const availableCount = Number((raw as { available_count?: unknown }).available_count);
+  if (!Number.isFinite(availableCount)) return null;
+  return Math.max(0, Math.trunc(availableCount));
+}
+
+interface CodexAuth {
+  accessToken: string;
+  accountId?: string;
+}
+
+async function getCodexAuth(): Promise<CodexAuth | null> {
+  try {
+    const raw = await readFile(CODEX_AUTH_FILE, "utf-8");
+    const parsed = JSON.parse(raw) as { tokens?: { access_token?: unknown; account_id?: unknown } };
+    const token = parsed.tokens?.access_token;
+    if (typeof token !== "string" || !token.trim()) return null;
+    const accountId = parsed.tokens?.account_id;
+    return {
+      accessToken: token,
+      accountId: typeof accountId === "string" && accountId.trim() ? accountId : undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function getCodexAccessToken(): Promise<string | null> {
+  return (await getCodexAuth())?.accessToken ?? null;
+}
+
+function codexAuthHeaders(auth: CodexAuth): Record<string, string> {
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${auth.accessToken}`,
+    "OpenAI-Beta": "codex-1",
+    originator: "Codex Desktop",
+  };
+  if (auth.accountId) headers["ChatGPT-Account-ID"] = auth.accountId;
+  return headers;
+}
+
+function parseCodexResetCreditDetails(data: Record<string, unknown>): {
+  availableCount: number | null;
+  availableCredits: CodexRateLimitResetCredit[];
+} {
+  const availableCount = Number(data.available_count);
+  const credits = Array.isArray(data.credits) ? data.credits : [];
+  return {
+    availableCount: Number.isFinite(availableCount) ? Math.max(0, Math.trunc(availableCount)) : null,
+    availableCredits: credits.flatMap((raw) => {
+      if (!raw || typeof raw !== "object") return [];
+      const credit = raw as { status?: unknown; granted_at?: unknown; expires_at?: unknown };
+      if (credit.status !== "available") return [];
+      if (typeof credit.expires_at !== "string" || !credit.expires_at.trim()) return [];
+      return [{
+        grantedAt: typeof credit.granted_at === "string" && credit.granted_at.trim() ? credit.granted_at : null,
+        expiresAt: credit.expires_at,
+      }];
+    }),
+  };
+}
+
+async function fetchCodexRateLimitResetCredits(auth: CodexAuth): Promise<{
+  availableCount: number | null;
+  availableCredits: CodexRateLimitResetCredit[];
+} | null> {
+  try {
+    const resp = await fetch(CODEX_RESET_CREDITS_URL, {
+      headers: codexAuthHeaders(auth),
+    });
+    const text = await resp.text();
+    if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${text.slice(0, 160)}`);
+    return parseCodexResetCreditDetails(JSON.parse(text) as Record<string, unknown>);
+  } catch (err) {
+    console.warn(`[Codex] reset credits lookup failed: ${(err as Error).message}`);
+    return null;
+  }
+}
+
+export async function getCodexUsageSummary(): Promise<CodexUsageSummary> {
+  const auth = await getCodexAuth();
+  if (!auth) throw new Error("missing ~/.codex/auth.json access token");
+
+  const resetCreditsPromise = fetchCodexRateLimitResetCredits(auth);
+
+  const resp = await fetch(CODEX_USAGE_URL, {
+    headers: { Authorization: `Bearer ${auth.accessToken}` },
+  });
+  const text = await resp.text();
+  if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${text.slice(0, 160)}`);
+
+  const data = JSON.parse(text) as {
+    rate_limit?: Record<string, unknown>;
+    rate_limit_reset_credits?: unknown;
+  };
+  const rateLimit = data.rate_limit;
+  if (!rateLimit || typeof rateLimit !== "object") throw new Error("missing rate_limit");
+
+  const fiveHour = parseOptionalUsageWindow(rateLimit, ["primary_window"]);
+  if (!fiveHour) throw new Error("missing rate_limit.primary_window.used_percent");
+  const resetCredits = await resetCreditsPromise;
+
+  return {
+    fiveHour,
+    weekly: parseOptionalUsageWindow(rateLimit, [
+      "secondary_window",
+      "weekly_window",
+      "week_window",
+      "long_window",
+    ]),
+    rateLimitResetCreditsAvailable: resetCredits?.availableCount ?? parseRateLimitResetCredits(data),
+    rateLimitResetCredits: resetCredits?.availableCredits ?? null,
+  };
+}
+
+export async function consumeCodexRateLimitResetCredit(redeemRequestId: string): Promise<CodexResetConsumeResult> {
+  if (!redeemRequestId.trim()) throw new Error("missing redeem_request_id");
+  const token = await getCodexAccessToken();
+  if (!token) throw new Error("missing ~/.codex/auth.json access token");
+
+  const resp = await fetch(CODEX_RESET_CONSUME_URL, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ redeem_request_id: redeemRequestId }),
+  });
+  const text = await resp.text();
+  if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${text.slice(0, 160)}`);
+
+  const data = JSON.parse(text) as { code?: unknown; windows_reset?: unknown };
+  const code = data.code;
+  if (
+    code !== "reset"
+    && code !== "nothing_to_reset"
+    && code !== "no_credit"
+    && code !== "already_redeemed"
+  ) {
+    throw new Error("missing or unknown reset result code");
+  }
+  const windowsReset = Number(data.windows_reset);
+  return {
+    code,
+    windowsReset: Number.isFinite(windowsReset) ? Math.max(0, Math.trunc(windowsReset)) : 0,
+  };
+}
+
+async function resolveCodexAvatarUsage(usageHint?: CodexUsageSummary | null): Promise<CodexUsageSummary | null> {
+  if (usageHint !== undefined) {
+    if (!usageHint?.weekly) return null;
+    return usageHint;
+  }
+
   try {
     const summary = await getCodexUsageSummary();
     if (!summary.weekly) throw new Error("missing weekly usage window");
@@ -611,7 +617,17 @@ function cursorAvatarBatteryPercentFromUsage(summary: CursorUsageSummary): numbe
   return clampPercent(100 - apiPercentUsed);
 }
 
-async function fetchCursorAvatarBatteryPercent(): Promise<number | null> {
+async function resolveCursorAvatarBatteryPercent(usageHint?: CursorUsageSummary | null): Promise<number | null> {
+  if (usageHint !== undefined) {
+    if (!usageHint) return null;
+    try {
+      return cursorAvatarBatteryPercentFromUsage(usageHint);
+    } catch (err) {
+      console.warn(`[${ts()}] [AVATAR] Cursor usage unavailable, using plain avatar: ${(err as Error).message}`);
+      return null;
+    }
+  }
+
   try {
     return cursorAvatarBatteryPercentFromUsage(await getCursorUsageSummary());
   } catch (err) {
@@ -814,12 +830,19 @@ async function uploadImage(
   return data.data!.image_key!;
 }
 
-async function getOrUploadAvatarKey(token: string, tool: string, status: string): Promise<string> {
+async function getOrUploadAvatarKey(
+  token: string,
+  tool: string,
+  status: string,
+  usageHints: ChatAvatarUsageHints = {},
+): Promise<string> {
   await loadAvatarKeyCache();
   const normalizedTool = normalizeAvatarTool(tool);
   const normalizedStatus = normalizeAvatarStatus(status);
-  const codexUsage = normalizedTool === "codex" ? await fetchCodexAvatarUsage() : null;
-  const cursorBatteryPercent = normalizedTool === "cursor" ? await fetchCursorAvatarBatteryPercent() : null;
+  const codexUsage = normalizedTool === "codex" ? await resolveCodexAvatarUsage(usageHints.codexUsage) : null;
+  const cursorBatteryPercent = normalizedTool === "cursor"
+    ? await resolveCursorAvatarBatteryPercent(usageHints.cursorUsage)
+    : null;
   const keyName = avatarCacheKey(normalizedTool, normalizedStatus, codexUsage, cursorBatteryPercent);
   const cached = avatarKeyCache.get(keyName);
   if (cached) return cached;
@@ -832,9 +855,15 @@ async function getOrUploadAvatarKey(token: string, tool: string, status: string)
   return key;
 }
 
-export async function setChatAvatar(token: string, chatId: string, tool: string, status: string): Promise<void> {
+export async function setChatAvatar(
+  token: string,
+  chatId: string,
+  tool: string,
+  status: string,
+  usageHints: ChatAvatarUsageHints = {},
+): Promise<void> {
   try {
-    const avatarKey = await getOrUploadAvatarKey(token, tool, status);
+    const avatarKey = await getOrUploadAvatarKey(token, tool, status, usageHints);
     const resp = await fetch(`${BASE_URL}/im/v1/chats/${chatId}`, {
       method: "PUT",
       headers: {