glad-web 1.0.39 → 1.0.41

package/README.md

@@ -34,6 +34,7 @@ Glad was created to enable **vibe coding** on mobile devices. By bringing variou
 
 Our design philosophy is **Easy to use, Stable, and Restrained**. Glad focuses strictly on the essentials:
 - **Session management:** Run multiple sessions from a single dashboard with per-session working directories.
+- **Local usage dashboard:** Select a week or month, compare per-model and daily token totals, and inspect model-stacked token and cost charts through the bundled read-only `ccusage` engine. Costs use `ccusage` estimates and are shown only for GPT models used by Codex.
 - **High-fidelity terminal interaction:** A mobile-friendly terminal experience with touch shortcuts.
 - **Extreme performance history viewing:** Fast and responsive text history.
 - **Simple but effective change checking:** Integrated Git changes preview.

package/README.zh-CN.md

@@ -34,6 +34,7 @@ Glad 的初衷是开发一款完全运行在本地的、足够简单的，且登
 
 我们的设计哲学是：**易用、稳定、克制**。只提供最核心且体验优秀的功能：
 - **Session 管理**：在一个面板中管理多个会话，每个会话可单独指定工作目录。
+- **本地用量看板**：通过内置的只读 `ccusage` 引擎选择某周或某月，查看按模型汇总及每日 token，并用按模型堆叠的柱状图比较 token 和费用；费用完全采用 `ccusage` 估算，且只对 Codex 使用的 GPT 模型显示。
 - **高还原度的 terminal 交互**：专为手机优化的终端体验与快捷按键。
 - **极致性能的历史查看**：快速流畅的终端历史记录浏览。
 - **简单但足够好用的改动检查**：内置 Git 改动预览功能。

package/lib/codex/structured-session.js

@@ -7,6 +7,12 @@ const PTYManager = require('../session/pty-manager');
 const PERMISSION_MODES = new Set(['untrusted', 'on-request', 'never']);
 const SANDBOX_MODES = new Set(['read-only', 'workspace-write', 'danger-full-access']);
 const FALLBACK_EFFORTS = ['minimal', 'low', 'medium', 'high', 'xhigh', 'ultra'];
+const DEFAULT_ABORT_GRACE_MS = 5000;
+const PROCESS_SHUTDOWN_TIMEOUT_MS = 2000;
+
+function turnKey(threadId, turnId) {
+  return `${String(threadId || '')}\n${String(turnId || '')}`;
+}
 
 function normalizePermissionMode(value) {
   const mode = String(value || 'default');
@@ -57,11 +63,37 @@ function appServerSpawnOptions({ cwd, env, platform = process.platform }) {
   if (platform === 'win32') {
     options.shell = true;
     options.windowsHide = true;
+  } else {
+    // Keep the npm wrapper, native Codex binary, and MCP children in one group
+    // so a forced abort can stop the complete app-server process tree.
+    options.detached = true;
   }
 
   return options;
 }
 
+function forceKillProcessTree(child, options = {}) {
+  const platform = options.platform || process.platform;
+  const killGroup = options.killGroup || process.kill;
+  const spawnProcess = options.spawnProcess || spawn;
+  if (!child?.pid) return false;
+  if (platform !== 'win32') {
+    try {
+      killGroup(-child.pid, 'SIGKILL');
+      return true;
+    } catch (_error) {
+      try { return child.kill('SIGKILL'); } catch (_) { return false; }
+    }
+  }
+  const killer = spawnProcess('taskkill', ['/pid', String(child.pid), '/t', '/f'], {
+    stdio: 'ignore', windowsHide: true
+  });
+  killer.once('error', () => {
+    try { child.kill('SIGKILL'); } catch (_) { /* process already exited */ }
+  });
+  return true;
+}
+
 function textFromInputItems(content) {
   return (Array.isArray(content) ? content : [])
     .filter(item => item && item.type === 'text')
@@ -233,6 +265,14 @@ class CodexStructuredSession extends EventEmitter {
     this.pendingRequests = new Map();
     this.process = null;
     this.processReady = null;
+    this.processShutdown = null;
+    this.needsThreadResume = false;
+    this.aborting = false;
+    this.abortTargets = new Map();
+    this.abortTimer = null;
+    this.abortGraceMs = Number(options.abortGraceMs) > 0
+      ? Number(options.abortGraceMs) : DEFAULT_ABORT_GRACE_MS;
+    this.forceKillProcessTree = options.forceKillProcessTree || forceKillProcessTree;
     this.terminalSession = null;
     this.terminalOutput = '';
     this.hasUnreadCompletion = false;
@@ -312,10 +352,13 @@ class CodexStructuredSession extends EventEmitter {
       effectivePermissionMode: this.effectivePermissionMode, effectiveSandboxMode: this.effectiveSandboxMode,
       model: this.model, effort: this.effort,
       status: this.status, threadId: this.threadId, presentation: this.presentation,
-      canAbort: this.presentation === 'structured' && this.status !== 'idle',
-      canCompact: this.presentation === 'structured' && this.status === 'idle' && !this.compacting && Boolean(this.threadId),
+      aborting: this.aborting,
+      canAbort: this.presentation === 'structured' && this.status !== 'idle' && !this.aborting,
+      canCompact: this.presentation === 'structured' && this.status === 'idle' && !this.compacting
+        && !this.aborting && Boolean(this.threadId),
       compacting: this.compacting,
-      canSwitchToTerminal: this.presentation === 'structured' && this.status === 'idle' && Boolean(this.threadId),
+      canSwitchToTerminal: this.presentation === 'structured' && this.status === 'idle'
+        && !this.aborting && Boolean(this.threadId),
       canSwitchToStructured: this.presentation === 'terminal',
       pendingPermissionCount: this.pendingPermissions.size, activeSubagentCount, models: this.models };
   }
@@ -362,7 +405,27 @@ class CodexStructuredSession extends EventEmitter {
     return completed;
   }
 
+  clearAbortState(emit = true) {
+    const changed = this.aborting;
+    if (this.abortTimer) clearTimeout(this.abortTimer);
+    this.abortTimer = null;
+    this.abortTargets.clear();
+    this.aborting = false;
+    if (emit && changed) this.emitControlState();
+  }
+
+  finishAbortIfComplete() {
+    if (!this.aborting || this.abortTargets.size) return false;
+    this.clearAbortState(false);
+    const hasActiveTurn = this.currentTurnId
+      || Array.from(this.threadTurns.values()).some(turn => turn?.status === 'running');
+    if (!hasActiveTurn && this.status !== 'idle') this.setStatus('idle');
+    else this.emitControlState();
+    return true;
+  }
+
   async ensureProcess() {
+    if (this.processShutdown) await this.processShutdown;
     if (this.processReady) return this.processReady;
     this.processReady = new Promise((resolve, reject) => {
       const child = spawn(this.tool.command, ['app-server', '--listen', 'stdio://'], appServerSpawnOptions({
@@ -384,6 +447,8 @@ class CodexStructuredSession extends EventEmitter {
           this.pendingRequests.clear();
           if (this.running && this.presentation === 'structured') {
             const activeTurn = Boolean(this.currentTurnId || this.status === 'running' || this.status === 'waiting_approval');
+            this.needsThreadResume = Boolean(this.threadId);
+            this.clearAbortState(false);
             this.compacting = false;
             this.append({ kind: 'event', level: 'error', text: 'Codex app-server exited.' });
             this.emitEvent({
@@ -514,8 +579,16 @@ class CodexStructuredSession extends EventEmitter {
       const durationMs = Number(params.turn?.durationMs || 0)
         || (startedAtMs ? Math.max(0, completedAtMs - startedAtMs) : null);
       const context = this.turnContexts.get(String(completedTurnId || ''));
-      this.append({ kind: 'turn-end', threadId, turnId: completedTurnId, status: turnStatus,
-        durationMs, createdAt: completedAtMs, ...(context ? { context } : {}) });
+      const existingTurnEnd = this.messages.find(item => item.kind === 'turn-end'
+        && item.threadId === threadId && item.turnId === completedTurnId);
+      if (existingTurnEnd) {
+        this.patch(existingTurnEnd.id, { status: turnStatus, durationMs,
+          createdAt: completedAtMs, ...(context ? { context } : {}) });
+      } else {
+        this.append({ kind: 'turn-end', threadId, turnId: completedTurnId, status: turnStatus,
+          durationMs, createdAt: completedAtMs, ...(context ? { context } : {}) });
+      }
+      this.abortTargets.delete(turnKey(threadId, completedTurnId));
       const observedNow = Date.now();
       const observedCompletedAtMs = Math.abs(observedNow - completedAtMs) < 5000
         ? Math.max(completedAtMs, observedNow) : completedAtMs;
@@ -543,11 +616,12 @@ class CodexStructuredSession extends EventEmitter {
         if (params.turn?.status === 'failed' || params.turn?.error) {
           this.append({ kind: 'event', level: 'error', text: params.turn?.error?.message || 'Codex turn failed.' });
         }
-        this.setStatus('idle');
+        this.setStatus(this.aborting && this.abortTargets.size ? 'running' : 'idle');
         this.hasUnreadCompletion = true;
       } else {
         this.emitControlState();
       }
+      this.finishAbortIfComplete();
       return;
     }
     if (method === 'thread/compacted') {
@@ -568,7 +642,7 @@ class CodexStructuredSession extends EventEmitter {
       const status = params.status?.type || params.status;
       if (!threadId || threadId === this.threadId) {
         if (status === 'idle' && !this.currentTurnId) { this.compacting = false; this.setStatus('idle'); }
-        if (status === 'active') this.setStatus('running');
+        if (status === 'active' && !this.aborting) this.setStatus('running');
       }
       return;
     }
@@ -952,11 +1026,32 @@ class CodexStructuredSession extends EventEmitter {
     return this.getControlState();
   }
 
+  async resumeThreadAfterProcessRestart() {
+    if (!this.threadId || !this.needsThreadResume) return false;
+    const result = await this.request('thread/resume', this.threadResumeParams(this.threadId));
+    this.needsThreadResume = false;
+    this.model = result.model || result.thread?.model || this.model;
+    this.effort = result.reasoningEffort || result.thread?.reasoningEffort || this.effort;
+    this.effectivePermissionMode = result.approvalPolicy || this.effectivePermissionMode;
+    this.effectiveSandboxMode = sandboxModeFromPolicy(result.sandbox) || this.effectiveSandboxMode;
+    return true;
+  }
+
+  threadResumeParams(threadId) {
+    const params = { threadId, cwd: this.workingDir };
+    if (this.permissionMode) params.approvalPolicy = this.permissionMode;
+    if (this.sandboxMode) params.sandbox = this.sandboxMode;
+    if (this.hasModelOverride && this.model) params.model = this.model;
+    if (this.hasEffortOverride && this.effort) params.config = { model_reasoning_effort: this.effort };
+    return params;
+  }
+
   async sendUserMessage(text, attachments = [], skills = []) {
     const prompt = String(text || '').trim();
     const images = (Array.isArray(attachments) ? attachments : [])
       .filter(item => item && typeof item.path === 'string' && item.path);
-    if ((!prompt && images.length === 0) || this.presentation !== 'structured' || this.status !== 'idle') return false;
+    if ((!prompt && images.length === 0) || this.presentation !== 'structured'
+      || this.status !== 'idle' || this.aborting) return false;
     this.hasUnreadCompletion = false;
     this.promptHistoryCache = null;
     this.append({
@@ -967,8 +1062,10 @@ class CodexStructuredSession extends EventEmitter {
         name: String(item?.name || ''), path: String(item?.path || '')
       })).filter(item => item.name && item.path)
     });
+    this.setStatus('running');
     try {
       await this.ensureProcess();
+      await this.resumeThreadAfterProcessRestart();
       if (!this.threadId) {
         const params = { cwd: this.workingDir };
         if (this.hasModelOverride) params.model = this.model;
@@ -976,13 +1073,13 @@ class CodexStructuredSession extends EventEmitter {
         if (this.sandboxMode) params.sandbox = this.sandboxMode;
         const started = await this.request('thread/start', params);
         this.threadId = started.thread?.id;
+        this.needsThreadResume = false;
         this.model = started.model || this.model;
         this.effort = started.reasoningEffort || this.effort;
         this.effectivePermissionMode = started.approvalPolicy || this.effectivePermissionMode;
         this.effectiveSandboxMode = sandboxModeFromPolicy(started.sandbox) || this.effectiveSandboxMode;
         this.emitEvent({ type: 'state', state: this.getControlState() });
       }
-      this.setStatus('running');
       const input = [];
       input.push(...await this.resolveSkillInputs(skills));
       if (prompt) input.push({ type: 'text', text: prompt });
@@ -1008,7 +1105,7 @@ class CodexStructuredSession extends EventEmitter {
   }
 
   async compactContext() {
-    if (!this.threadId || this.presentation !== 'structured' || this.status !== 'idle') return false;
+    if (!this.threadId || this.presentation !== 'structured' || this.status !== 'idle' || this.aborting) return false;
     await this.ensureProcess();
     this.compacting = true;
     this.setStatus('running');
@@ -1060,6 +1157,7 @@ class CodexStructuredSession extends EventEmitter {
 
   abort(reason = 'Aborted by user') {
     if (this.presentation !== 'structured' || this.status === 'idle') return false;
+    if (this.aborting) return true;
     for (const pending of this.pendingPermissions.values()) {
       const response = pending.method === 'item/permissions/requestApproval'
         ? { permissions: {}, scope: 'turn' }
@@ -1077,32 +1175,77 @@ class CodexStructuredSession extends EventEmitter {
       && !targets.some(target => target.threadId === this.threadId && target.turnId === this.currentTurnId)) {
       targets.push({ threadId: this.threadId, turnId: this.currentTurnId });
     }
+    this.aborting = true;
+    this.abortTargets = new Map(targets.map(target => [turnKey(target.threadId, target.turnId), target]));
+    this.emitControlState();
     for (const target of targets) {
       this.request('turn/interrupt', target).catch(error => {
         this.logger.debugInfo?.(`[codex-app-server] turn/interrupt failed for ${target.threadId}/${target.turnId}: ${error.message}`);
       });
     }
     this.append({ kind: 'event', level: 'info', text: reason });
+    this.abortTimer = setTimeout(() => this.forceAbortAfterTimeout(), this.abortGraceMs);
+    this.abortTimer.unref?.();
+    return true;
+  }
+
+  forceAbortAfterTimeout() {
+    if (!this.aborting) return false;
+    const targets = Array.from(this.abortTargets.values());
+    const completedAtMs = Date.now();
+    const timeoutSeconds = Math.max(1, Math.round(this.abortGraceMs / 1000));
+    this.append({ kind: 'event', level: 'warning',
+      text: `Codex did not stop within ${timeoutSeconds} seconds. Stopping its app-server.` });
+
+    for (const target of targets) {
+      const tracked = this.threadTurns.get(target.threadId);
+      const startedAtMs = Number(tracked?.startedAt || 0)
+        || (target.threadId === this.threadId ? Number(this.currentTurnStartedAt || 0) : 0);
+      const existingTurnEnd = this.messages.find(item => item.kind === 'turn-end'
+        && item.threadId === target.threadId && item.turnId === target.turnId);
+      if (!existingTurnEnd) {
+        this.append({ kind: 'turn-end', threadId: target.threadId, turnId: target.turnId,
+          status: 'cancelled', durationMs: startedAtMs ? Math.max(0, completedAtMs - startedAtMs) : null,
+          createdAt: completedAtMs });
+      }
+    }
+    for (const item of this.messages.filter(message => message.kind === 'tool'
+      && ['running', 'inProgress'].includes(message.toolStatus))) {
+      const startedAtMs = Number(item.startedAtMs || item.createdAt || 0);
+      this.patch(item.id, { toolStatus: 'cancelled', completedAtMs,
+        ...(startedAtMs ? { durationMs: Math.max(1, completedAtMs - startedAtMs) } : {}) });
+    }
+
+    this.needsThreadResume = Boolean(this.threadId);
+    this.currentTurnId = null;
+    this.currentTurnStartedAt = null;
+    this.threadTurns.clear();
+    this.pendingPermissions.clear();
+    this.compacting = false;
+    this.hasUnreadCompletion = true;
+    this.clearAbortState(false);
+    void this.disconnectProcess(true);
+    if (this.status !== 'idle') this.setStatus('idle');
+    else this.emitControlState();
+    this.append({ kind: 'event', level: 'info',
+      text: 'Codex app-server stopped. It will restart before the next message.' });
     return true;
   }
 
   async resume(threadId = null) {
     const target = String(threadId || this.threadId || '').trim();
-    if (!target || this.presentation !== 'structured' || this.status !== 'idle') return false;
+    if (!target || this.presentation !== 'structured' || this.status !== 'idle' || this.aborting) return false;
     await this.ensureProcess();
     const selectedModel = this.model;
     const selectedEffort = this.effort;
     const resumeWithModelOverride = Boolean(this.hasModelOverride && selectedModel);
     const resumeWithEffortOverride = Boolean(this.hasEffortOverride && selectedEffort);
-    const params = { threadId: target, cwd: this.workingDir };
-    if (this.permissionMode) params.approvalPolicy = this.permissionMode;
-    if (this.sandboxMode) params.sandbox = this.sandboxMode;
-    if (resumeWithModelOverride) params.model = selectedModel;
-    if (resumeWithEffortOverride) params.config = { model_reasoning_effort: selectedEffort };
+    const params = this.threadResumeParams(target);
     this.deferredWarnings = [];
     try {
       const result = await this.request('thread/resume', params);
       this.threadId = result.thread?.id || target;
+      this.needsThreadResume = false;
       this.hasModelOverride = resumeWithModelOverride;
       this.hasEffortOverride = resumeWithEffortOverride;
       this.model = result.model || result.thread?.model || selectedModel;
@@ -1167,7 +1310,7 @@ class CodexStructuredSession extends EventEmitter {
 
   async forkFrom(threadId) {
     const sourceThreadId = String(threadId || '').trim();
-    if (!sourceThreadId || this.presentation !== 'structured' || this.status !== 'idle') return false;
+    if (!sourceThreadId || this.presentation !== 'structured' || this.status !== 'idle' || this.aborting) return false;
     await this.ensureProcess();
     const params = { threadId: sourceThreadId, cwd: this.workingDir, ephemeral: false, threadSource: null };
     if (this.hasModelOverride) params.model = this.model;
@@ -1177,6 +1320,7 @@ class CodexStructuredSession extends EventEmitter {
     const forkedThread = result?.thread;
     if (!forkedThread?.id) throw new Error('Codex did not return a forked thread');
     this.threadId = forkedThread.id;
+    this.needsThreadResume = false;
     this.model = result.model || forkedThread.model || this.model;
     this.effort = result.reasoningEffort || forkedThread.reasoningEffort || forkedThread.reasoning_effort || this.effort;
     this.effectivePermissionMode = result.approvalPolicy || this.effectivePermissionMode;
@@ -1187,7 +1331,7 @@ class CodexStructuredSession extends EventEmitter {
   }
 
   async switchToTerminal() {
-    if (this.presentation !== 'structured' || this.status !== 'idle' || !this.threadId) throw new Error('Codex must be idle before switching to Terminal.');
+    if (this.presentation !== 'structured' || this.status !== 'idle' || this.aborting || !this.threadId) throw new Error('Codex must be idle before switching to Terminal.');
     await this.disconnectProcess();
     this.terminalOutput = '';
     const terminal = new PTYManager(this.tool, this.workingDir, { append() {} }, { silent: true });
@@ -1218,19 +1362,45 @@ class CodexStructuredSession extends EventEmitter {
     return this.resume();
   }
 
-  async disconnectProcess() {
-    if (!this.process) return;
+  async disconnectProcess(force = false) {
+    if (!this.process) return this.processShutdown || undefined;
     const child = this.process;
     this.process = null;
     this.processReady = null;
     for (const request of this.pendingRequests.values()) { clearTimeout(request.timer); request.reject(new Error('Codex app-server disconnected')); }
     this.pendingRequests.clear();
-    child.kill();
+    const shutdown = typeof child.once === 'function'
+      ? new Promise(resolve => {
+        let timer;
+        const finish = () => { clearTimeout(timer); resolve(); };
+        child.once('exit', finish);
+        timer = setTimeout(() => {
+          this.logger.debugInfo?.('[codex-app-server] process did not exit within 2 seconds');
+          finish();
+        }, PROCESS_SHUTDOWN_TIMEOUT_MS);
+      })
+      : Promise.resolve();
+    this.processShutdown = shutdown;
+    if (force) this.forceKillProcessTree(child);
+    else child.kill();
+    try {
+      await shutdown;
+    } finally {
+      if (this.processShutdown === shutdown) this.processShutdown = null;
+    }
   }
 
   markCompletionRead() { this.hasUnreadCompletion = false; this.completionReadInputSeq = this.inputSeq; }
-  kill() { this.running = false; this.terminalSession?.kill(); this.terminalSession = null; void this.disconnectProcess(); this.emit('exit'); }
+  async kill() {
+    this.running = false;
+    this.clearAbortState(false);
+    this.terminalSession?.kill();
+    this.terminalSession = null;
+    await this.disconnectProcess(true);
+    this.emit('exit');
+  }
 }
 
 module.exports = CodexStructuredSession;
 module.exports.appServerSpawnOptions = appServerSpawnOptions;
+module.exports.forceKillProcessTree = forceKillProcessTree;

package/lib/commands/web.js

@@ -47,6 +47,8 @@ const registerScheduleRoutes = require('../server/routes/schedules');
 const registerWorkspaceRoutes = require('../server/routes/workspace');
 const registerProviderRoutes = require('../server/routes/providers');
 const registerNotificationRoutes = require('../server/routes/notifications');
+const registerUsageRoutes = require('../server/routes/usage');
+const { UsageService } = require('../usage/usage-service');
 const { ServerChanSettingsStore } = require('../notifications/serverchan-settings-store');
 const ServerChanClient = require('../notifications/serverchan-client');
 const NotificationService = require('../notifications/notification-service');
@@ -101,6 +103,7 @@ async function webCommand(options) {
     channel: new ServerChanClient(),
     logger
   });
+  const usageService = new UsageService({ logger });
   sessionManager.on('output', ({ sessionId, data }) => {
     broadcastToSession(sessionId, { type: 'output', data });
   });
@@ -143,6 +146,7 @@ async function webCommand(options) {
     settingsStore: serverChanSettings,
     notificationService
   });
+  registerUsageRoutes(app, { usageService, sendJson: sendCompressedJson });
 
   // API: List all active sessions
   app.get('/api/sessions', (req, res) => {
@@ -272,8 +276,8 @@ async function webCommand(options) {
   });
 
   // API: Delete/Kill session
-  app.delete('/api/sessions/:id', (req, res) => {
-    sessionManager.kill(req.params.id);
+  app.delete('/api/sessions/:id', async (req, res) => {
+    await sessionManager.kill(req.params.id);
     res.json({ success: true });
   });
 
@@ -481,7 +485,8 @@ async function webCommand(options) {
     'composer.js',
     'timed-inputs.js',
     'terminal-scroll.js',
-    'git.js'
+    'git.js',
+    'usage.js'
   ];
   for (const assetName of webAssets) {
     const escapedName = assetName.replace('.', '\\.');

package/lib/server/routes/usage.js

@@ -0,0 +1,23 @@
+module.exports = function registerUsageRoutes(app, { usageService, sendJson = (_req, res, payload) => res.json(payload) }) {
+  app.get('/api/usage/sources', async (req, res) => {
+    try {
+      res.json(await usageService.listSources(req.query.refresh === '1'));
+    } catch (error) {
+      res.status(error.statusCode || 500).json({ error: error.message || 'Failed to load usage sources' });
+    }
+  });
+
+  app.get('/api/usage/report', async (req, res) => {
+    try {
+      const report = await usageService.getDashboard(
+        req.query.source,
+        req.query.scope || 'weekly',
+        req.query.period,
+        req.query.refresh === '1'
+      );
+      sendJson(req, res, report);
+    } catch (error) {
+      res.status(error.statusCode || 500).json({ error: error.message || 'Failed to load usage report' });
+    }
+  });
+};

package/lib/session/session-manager.js

@@ -610,7 +610,7 @@ class SessionManager extends EventEmitter {
     return true;
   }
 
-  kill(id) {
+  async kill(id) {
     const session = this.get(id);
     if (!session) return false;
     clearTimeout(session.completionTimer);
@@ -620,7 +620,7 @@ class SessionManager extends EventEmitter {
     this.logSessionDiagnostics('session-deleted', session, {}, { compact: true });
     this.disposeSessionHistory(session);
     if (['claude-structured', 'codex-structured'].includes(session.kind)) {
-      session.ptyManager.kill();
+      await session.ptyManager.kill();
       return true;
     }
     session.ptyManager.kill();

package/lib/usage/ccusage-runner.js

@@ -0,0 +1,128 @@
+const { spawn } = require('child_process');
+const { chmodSync, statSync } = require('fs');
+
+const MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 45000;
+
+const NATIVE_PACKAGES = {
+  'darwin-arm64': '@ccusage/ccusage-darwin-arm64',
+  'darwin-x64': '@ccusage/ccusage-darwin-x64',
+  'linux-arm64': '@ccusage/ccusage-linux-arm64',
+  'linux-x64': '@ccusage/ccusage-linux-x64',
+  'win32-arm64': '@ccusage/ccusage-win32-arm64',
+  'win32-x64': '@ccusage/ccusage-win32-x64'
+};
+
+function resolveCcusageBinary(platform = process.platform, arch = process.arch) {
+  const packageName = NATIVE_PACKAGES[`${platform}-${arch}`];
+  if (!packageName) {
+    throw new Error(`ccusage is not available for ${platform}-${arch}`);
+  }
+  const binaryName = platform === 'win32' ? 'ccusage.exe' : 'ccusage';
+  try {
+    return require.resolve(`${packageName}/bin/${binaryName}`);
+  } catch (_error) {
+    throw new Error(`ccusage native package is missing for ${platform}-${arch}`);
+  }
+}
+
+function ensureCcusageBinaryExecutable(binaryPath, options = {}) {
+  const platform = options.platform || process.platform;
+  if (platform === 'win32') return binaryPath;
+
+  const statPath = options.statPath || statSync;
+  const chmodPath = options.chmodPath || chmodSync;
+  try {
+    // ccusage's platform packages can be installed without execute bits. Its JS
+    // wrapper repairs them too, but this runner intentionally spawns the native binary.
+    if ((statPath(binaryPath).mode & 0o111) === 0) chmodPath(binaryPath, 0o755);
+    return binaryPath;
+  } catch (error) {
+    throw new Error(`ccusage native binary is not executable: ${error.message}`);
+  }
+}
+
+function reportArgs(timezone) {
+  return [
+    'daily',
+    '--sections', 'daily,weekly,monthly',
+    '--by-agent',
+    '--json',
+    '--offline',
+    '--timezone', timezone
+  ];
+}
+
+class CcusageRunner {
+  constructor(options = {}) {
+    this.binaryPath = options.binaryPath
+      || ensureCcusageBinaryExecutable(resolveCcusageBinary());
+    this.timeoutMs = options.timeoutMs || DEFAULT_TIMEOUT_MS;
+    this.spawnProcess = options.spawnProcess || spawn;
+  }
+
+  loadAllPeriods(timezone) {
+    return this.runJson(reportArgs(timezone));
+  }
+
+  runJson(args) {
+    return new Promise((resolve, reject) => {
+      const child = this.spawnProcess(this.binaryPath, args, {
+        env: { ...process.env, NO_COLOR: '1' },
+        shell: false,
+        windowsHide: true
+      });
+      const stdout = [];
+      const stderr = [];
+      let outputBytes = 0;
+      let stderrBytes = 0;
+      let settled = false;
+
+      const finish = callback => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        callback();
+      };
+      const timer = setTimeout(() => {
+        child.kill();
+        finish(() => reject(new Error('ccusage timed out while reading local usage data')));
+      }, this.timeoutMs);
+
+      child.stdout.on('data', chunk => {
+        outputBytes += chunk.length;
+        if (outputBytes > MAX_OUTPUT_BYTES) {
+          child.kill();
+          finish(() => reject(new Error('ccusage report exceeded the safe output limit')));
+          return;
+        }
+        stdout.push(chunk);
+      });
+      child.stderr.on('data', chunk => {
+        if (stderrBytes >= 64 * 1024) return;
+        stderr.push(chunk);
+        stderrBytes += chunk.length;
+      });
+      child.on('error', error => finish(() => reject(new Error(`Unable to start ccusage: ${error.message}`))));
+      child.on('close', code => finish(() => {
+        const errorText = Buffer.concat(stderr).toString('utf8').trim();
+        if (code !== 0) {
+          reject(new Error(errorText || `ccusage exited with code ${code}`));
+          return;
+        }
+        try {
+          resolve(JSON.parse(Buffer.concat(stdout).toString('utf8')));
+        } catch (_error) {
+          reject(new Error('ccusage returned invalid JSON'));
+        }
+      }));
+    });
+  }
+}
+
+module.exports = {
+  CcusageRunner,
+  ensureCcusageBinaryExecutable,
+  reportArgs,
+  resolveCcusageBinary
+};

package/lib/usage/source-catalog.js

@@ -0,0 +1,26 @@
+const SOURCES = [
+  { id: 'codex', label: 'Codex', badge: 'CX' },
+  { id: 'claude', label: 'Claude', badge: 'CL' },
+  { id: 'gemini', label: 'Gemini', badge: 'GE' },
+  { id: 'opencode', label: 'OpenCode', badge: 'OC' },
+  { id: 'copilot', label: 'Copilot', badge: 'CP' },
+  { id: 'amp', label: 'Amp', badge: 'AM' },
+  { id: 'droid', label: 'Droid', badge: 'DR' },
+  { id: 'codebuff', label: 'Codebuff', badge: 'CB' },
+  { id: 'hermes', label: 'Hermes', badge: 'HE' },
+  { id: 'pi', label: 'Pi', badge: 'PI' },
+  { id: 'goose', label: 'Goose', badge: 'GO' },
+  { id: 'kilo', label: 'Kilo', badge: 'KI' },
+  { id: 'kimi', label: 'Kimi', badge: 'KM' },
+  { id: 'qwen', label: 'Qwen', badge: 'QW' },
+  { id: 'openclaw', label: 'OpenClaw', badge: 'OA' },
+  { id: 'grok', label: 'Grok', badge: 'GR' }
+];
+
+const SOURCE_BY_ID = new Map(SOURCES.map(source => [source.id, source]));
+
+function getUsageSource(id) {
+  return SOURCE_BY_ID.get(String(id || '').toLowerCase()) || null;
+}
+
+module.exports = { SOURCES, getUsageSource };