Skip to content

CodexBar 是一个 macOS 菜单栏应用,用于查看本机 Codex 账号状态、额度、Token 用量、详细统计信息

feat: 支持任务 Token 用量统计与历史同步重建

Bobec0148e330aa
diff --git a/CodexBar/Controllers/FallbackPanelController.swift b/CodexBar/Controllers/FallbackPanelController.swift
index bcac4ab..a3a00ad 100644
--- a/CodexBar/Controllers/FallbackPanelController.swift
+++ b/CodexBar/Controllers/FallbackPanelController.swift
@@ -41,6 +41,20 @@ final class FallbackPanelController {
panel?.orderOut(nil)
}
+ func resizeIfVisible(animated: Bool) {
+ guard let panel, panel.isVisible else { return }
+ let size = contentSize(for: panel)
+ guard panel.frame.size != size else { return }
+ var frame = panel.frame
+ frame.origin.y = frame.maxY - size.height
+ frame.size = size
+ NSAnimationContext.runAnimationGroup { context in
+ context.duration = animated ? 0.20 : 0
+ context.timingFunction = CAMediaTimingFunction(name: .easeInEaseOut)
+ panel.animator().setFrame(frame, display: true)
+ }
+ }
+
private func makePanelIfNeeded() -> KeyableBorderlessPanel {
if let panel {
return panel
diff --git a/CodexBar/Controllers/StatusItemController.swift b/CodexBar/Controllers/StatusItemController.swift
index 779516d..1958c48 100644
--- a/CodexBar/Controllers/StatusItemController.swift
+++ b/CodexBar/Controllers/StatusItemController.swift
@@ -111,6 +111,7 @@ final class StatusItemController: NSObject, NSMenuDelegate {
private var statusIconHostingView: StatusItemIconHostingView?
private var statusIconExpirationTask: Task<Void, Never>?
private var statusToolTipTask: Task<Void, Never>?
+ private var popoverResizeAnimationTask: Task<Void, Never>?
private var registeredHotKeyShortcut: GlobalHotKeyShortcut?
private var auxiliaryWindowFocusRestoreTask: Task<Void, Never>?
private var activeStatusItemMenu: NSMenu?
@@ -392,6 +393,8 @@ final class StatusItemController: NSObject, NSMenuDelegate {
.map(\.hasTaskCenterContent)
.removeDuplicates()
+ observeActivityCardSize()
+
let isTaskCenterVisible = Publishers.CombineLatest(
codexHookSettings.$isEnabled,
mainPanelSettings.$layout
@@ -472,6 +475,37 @@ final class StatusItemController: NSObject, NSMenuDelegate {
.store(in: &cancellables)
}
+ private func observeActivityCardSize() {
+ Publishers.CombineLatest(viewModel.$snapshot.map { $0 != nil }, activityMonitor.$snapshot)
+ .map { hasQuota, activity in hasQuota && activity.primaryActivity.tokenUsage != nil }
+ .removeDuplicates()
+ .handleEvents(receiveOutput: { [weak self] _ in
+ self?.animatePopoverContentResize()
+ })
+ // 用量补齐会改变卡片高度, 等 @Published 完成赋值后再测量备用面板
+ .receive(on: DispatchQueue.main)
+ .sink { [weak self] _ in
+ guard let self else { return }
+ fallbackPanelController.resizeIfVisible(
+ animated: fallbackPanelAnimationState.allowsAnimations
+ )
+ }
+ .store(in: &cancellables)
+ }
+
+ private func animatePopoverContentResize() {
+ guard menuSurfaceState == .shown, popover.isShown, popoverAnimationState.allowsAnimations else { return }
+ popoverResizeAnimationTask?.cancel()
+ // preferredContentSize 更新前启用 AppKit 尺寸动画, 显隐仍由统一淡入淡出管理
+ popover.animates = true
+ popoverResizeAnimationTask = Task { @MainActor [weak self] in
+ try? await Task.sleep(for: .milliseconds(250))
+ guard !Task.isCancelled else { return }
+ self?.popover.animates = false
+ self?.popoverResizeAnimationTask = nil
+ }
+ }
+
private func observeWorkflowSyncState() {
codexHookSettings.$isEnabled
.removeDuplicates()
@@ -896,6 +930,9 @@ final class StatusItemController: NSObject, NSMenuDelegate {
return
}
+ popoverResizeAnimationTask?.cancel()
+ popoverResizeAnimationTask = nil
+ popover.animates = false
menuSurfaceFadeCoordinator.cancel()
hideSideDetailPanels()
menuSurfaceDismissMonitor.remove()
@@ -1115,6 +1152,7 @@ final class StatusItemController: NSObject, NSMenuDelegate {
private func closeActiveMenuSurface() {
// 主动关闭先清除宿主身份, 避免同步的关闭回调重入清理流程
activeMenuSurface = .none
+ popover.animates = false
if popover.isShown {
popover.performClose(nil)
}
diff --git a/CodexBar/Models/CodexActivityModels.swift b/CodexBar/Models/CodexActivityModels.swift
index 02273a3..0b1c86a 100644
--- a/CodexBar/Models/CodexActivityModels.swift
+++ b/CodexBar/Models/CodexActivityModels.swift
@@ -39,6 +39,7 @@ nonisolated struct CodexActivityTaskSnapshot: Equatable, Identifiable {
let showsPreciseDuration: Bool
/// nil 表示 Hook 字段不足, 无法可靠统计; 0 表示已确认当前没有活跃子 Agent
let activeSubagentCount: Int?
+ var tokenUsage: CodexTokenUsage?
}
/// 最近确认结束的任务; 完成只表示一轮任务结束, 不代表执行成功
@@ -50,6 +51,7 @@ nonisolated struct CodexActivityCompletion: Equatable, Identifiable {
let effort: String?
let completedAt: Date
let duration: TimeInterval?
+ var tokenUsage: CodexTokenUsage?
}
/// 本轮确认的终态和快照一起发布, 历史恢复只发布快照
@@ -86,6 +88,7 @@ nonisolated struct CodexActivityTermination: Equatable, Identifiable {
let effort: String?
let terminatedAt: Date
let duration: TimeInterval?
+ var tokenUsage: CodexTokenUsage?
}
/// 实时越过静默阈值时交给通知服务的最小信息, 不包含原始 session 或 turn ID
@@ -199,6 +202,15 @@ nonisolated enum CodexPrimaryActivity: Equatable {
case completed(CodexActivityCompletion)
case terminated(CodexActivityTermination)
case idle
+
+ var tokenUsage: CodexTokenUsage? {
+ switch self {
+ case let .completed(completion): completion.tokenUsage
+ case let .terminated(termination): termination.tokenUsage
+ case let .waiting(task), let .running(task): task.tokenUsage
+ case .idle: nil
+ }
+ }
}
/// 只有 live Hook 或 session 生命周期会发布 transition, bootstrap 永远不会触发历史通知
diff --git a/CodexBar/Models/CodexTokenHistory.swift b/CodexBar/Models/CodexTokenHistory.swift
new file mode 100644
index 0000000..1a168d8
--- /dev/null
+++ b/CodexBar/Models/CodexTokenHistory.swift
@@ -0,0 +1,116 @@
+import CryptoKit
+import Foundation
+
+/// 一条线程轮次的累计快照, 身份只保存哈希, 不保存对话正文或原始 ID
+nonisolated struct CodexTokenTurn: Codable, Equatable, Identifiable {
+ let id: String
+ var rootID: String
+ var startedAt: Date?
+ var updatedAt: Date
+ var usage: CodexTokenUsage?
+ var rebuiltAt: Date?
+
+ static func identifier(thread: String, turn: String) -> String {
+ // 哈希身份域是固定输入, 不随存储 schema 变化, 避免同一轮次生成多个身份
+ let data = (try? JSONEncoder().encode(["token-turn-v1", thread, turn])) ?? Data()
+ return SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined()
+ }
+
+ func merging(_ other: Self) -> Self {
+ precondition(id == other.id)
+ // 显式重建允许修正为更小的用量, 旧缓存不能再以累计值较大为由恢复错误结果
+ if rebuiltAt != other.rebuiltAt {
+ return (rebuiltAt ?? .distantPast) > (other.rebuiltAt ?? .distantPast) ? self : other
+ }
+ var result = self
+ if rootID == id {
+ result.rootID = other.rootID
+ }
+ if let date = other.startedAt {
+ result.startedAt = min(startedAt ?? date, date)
+ }
+ result.updatedAt = max(updatedAt, other.updatedAt)
+ if let candidate = other.usage, candidate.isValid {
+ if let current = usage {
+ // 同一累计快照的副本和较短扫描都不能重复累加或覆盖更完整的数据
+ if Self.usageOrder(candidate).lexicographicallyPrecedes(Self.usageOrder(current)) == false {
+ result.usage = candidate
+ }
+ } else {
+ result.usage = candidate
+ }
+ }
+ return result
+ }
+
+ static func merged(_ records: [Self]) -> [String: Self] {
+ records.reduce(into: [:]) { result, record in
+ result[record.id] = result[record.id]?.merging(record) ?? record
+ }
+ }
+
+ static func dailyUsage(_ records: [Self], now: Date = Date()) -> [String: CodexTokenUsage] {
+ let byID = merged(records)
+ let cutoff = WorkflowStorage.retentionCutoffDate(today: now)
+ var result: [String: CodexTokenUsage] = [:]
+ var invalidDates: Set<String> = []
+ for record in byID.values {
+ guard let usage = record.usage, usage.isValid,
+ let start = byID[record.rootID]?.startedAt, start >= cutoff, start <= now else { continue }
+ let date = CodexDateFormat.dayString(from: start)
+ if let current = result[date] {
+ if let sum = current.adding(usage) {
+ result[date] = sum
+ } else {
+ invalidDates.insert(date)
+ }
+ } else {
+ result[date] = usage
+ }
+ }
+ for date in invalidDates {
+ result.removeValue(forKey: date)
+ }
+ return result
+ }
+
+ func pseudonymized(salt: Data) -> Self {
+ func hash(_ value: String) -> String {
+ HMAC<SHA256>.authenticationCode(for: Data(value.utf8), using: SymmetricKey(data: salt))
+ .map { String(format: "%02x", $0) }.joined()
+ }
+ return Self(id: hash(id), rootID: hash(rootID), startedAt: startedAt, updatedAt: updatedAt, usage: usage, rebuiltAt: rebuiltAt)
+ }
+
+ static func syncable(_ records: [Self]) -> [Self] {
+ let rootIDs = Set(records.filter { $0.usage != nil }.map(\.rootID))
+ return records.filter { $0.usage != nil || $0.rebuiltAt != nil || rootIDs.contains($0.id) }
+ }
+
+ private static func usageOrder(_ usage: CodexTokenUsage) -> [Int64] {
+ [
+ usage.totalTokens,
+ usage.inputTokens,
+ usage.outputTokens,
+ usage.cachedInputTokens,
+ usage.cacheWriteInputTokens,
+ usage.reasoningOutputTokens
+ ]
+ }
+}
+
+/// 云端身份只通过账户 salt 与本地已发现的轮次匹配, 不导入其他设备的轮次
+nonisolated struct CodexTokenHistoryBaseline {
+ let salt: Data
+ let turns: [String: CodexTokenTurn]
+
+ func replacement(for local: CodexTokenTurn) -> CodexTokenTurn? {
+ let exported = local.pseudonymized(salt: salt)
+ guard let remote = turns[exported.id], let rebuiltAt = remote.rebuiltAt,
+ rebuiltAt > (local.rebuiltAt ?? .distantPast), remote.rootID == exported.rootID else { return nil }
+ return CodexTokenTurn(
+ id: local.id, rootID: local.rootID, startedAt: remote.startedAt ?? local.startedAt,
+ updatedAt: remote.updatedAt, usage: remote.usage, rebuiltAt: rebuiltAt
+ )
+ }
+}
diff --git a/CodexBar/Models/CodexTokenUsage.swift b/CodexBar/Models/CodexTokenUsage.swift
new file mode 100644
index 0000000..ab058e6
--- /dev/null
+++ b/CodexBar/Models/CodexTokenUsage.swift
@@ -0,0 +1,70 @@
+import Foundation
+
+nonisolated struct CodexTokenUsage: Codable, Equatable {
+ let inputTokens: Int64
+ let cachedInputTokens: Int64
+ let cacheWriteInputTokens: Int64
+ let outputTokens: Int64
+ let reasoningOutputTokens: Int64
+ let totalTokens: Int64
+
+ var cacheHitRate: Double? {
+ inputTokens > 0 ? Double(cachedInputTokens) / Double(inputTokens) : nil
+ }
+
+ var isValid: Bool {
+ let inputAndOutput = inputTokens.addingReportingOverflow(outputTokens)
+ let cachedAndWritten = cachedInputTokens.addingReportingOverflow(cacheWriteInputTokens)
+ return inputTokens >= 0 && cachedInputTokens >= 0 && cacheWriteInputTokens >= 0
+ && outputTokens >= 0 && reasoningOutputTokens >= 0 && totalTokens >= 0
+ && !inputAndOutput.overflow && inputAndOutput.partialValue == totalTokens
+ && !cachedAndWritten.overflow && cachedAndWritten.partialValue <= inputTokens
+ && reasoningOutputTokens <= outputTokens
+ }
+
+ func adding(_ other: Self) -> Self? {
+ let sums = zip(values, other.values).map { $0.addingReportingOverflow($1) }
+ guard !sums.contains(where: \.overflow) else { return nil }
+ return Self(
+ inputTokens: sums[0].partialValue, cachedInputTokens: sums[1].partialValue,
+ cacheWriteInputTokens: sums[2].partialValue, outputTokens: sums[3].partialValue,
+ reasoningOutputTokens: sums[4].partialValue, totalTokens: sums[5].partialValue
+ )
+ }
+
+ private var values: [Int64] {
+ [inputTokens, cachedInputTokens, cacheWriteInputTokens, outputTokens, reasoningOutputTokens, totalTokens]
+ }
+
+ private enum CodingKeys: String, CodingKey {
+ case inputTokens = "input_tokens"
+ case cachedInputTokens = "cached_input_tokens"
+ case cacheWriteInputTokens = "cache_write_input_tokens"
+ case outputTokens = "output_tokens"
+ case reasoningOutputTokens = "reasoning_output_tokens"
+ case totalTokens = "total_tokens"
+ }
+}
+
+/// 终态读取可能从文件尾部开始, 使用明确归属的轮次累计值避免漏算前面的响应
+nonisolated struct CodexRolloutTokenUsageRecord: Decodable {
+ let payload: CodexRolloutTokenUsagePayload
+}
+
+nonisolated struct CodexRolloutTokenUsagePayload: Decodable {
+ let threadId: String
+ let sessionId: String
+ let turnId: String
+ let rootTurnId: String
+ let responseId: String
+ let turnTokenUsage: CodexTokenUsage
+
+ private enum CodingKeys: String, CodingKey {
+ case threadId = "thread_id"
+ case sessionId = "session_id"
+ case turnId = "turn_id"
+ case rootTurnId = "root_turn_id"
+ case responseId = "response_id"
+ case turnTokenUsage = "turn_token_usage"
+ }
+}
diff --git a/CodexBar/Models/CodexWorkflowModels.swift b/CodexBar/Models/CodexWorkflowModels.swift
index cccb5d5..ebe32fc 100644
--- a/CodexBar/Models/CodexWorkflowModels.swift
+++ b/CodexBar/Models/CodexWorkflowModels.swift
@@ -348,6 +348,7 @@ nonisolated struct WorkflowDailyMetrics: Equatable {
/// WorkflowService 发布给 UI 的近端快照
nonisolated struct WorkflowSnapshot: Equatable {
let dailyMetrics: [WorkflowDailyMetrics]
+ var tokenUsageByDate: [String: CodexTokenUsage] = [:]
static let empty = WorkflowSnapshot(dailyMetrics: [])
diff --git a/CodexBar/Models/UsageHeatmapDay.swift b/CodexBar/Models/UsageHeatmapDay.swift
index 2b0d70b..0c3bf41 100644
--- a/CodexBar/Models/UsageHeatmapDay.swift
+++ b/CodexBar/Models/UsageHeatmapDay.swift
@@ -19,6 +19,7 @@ nonisolated struct UsageHeatmapDay: Equatable, Identifiable {
let startDate: String
let tokenState: UsageHeatmapTokenState
let workflow: WorkflowDailyMetrics
+ var tokenUsage: CodexTokenUsage?
var id: String {
startDate
@@ -72,7 +73,8 @@ nonisolated struct UsageHeatmapDay: Equatable, Identifiable {
return UsageHeatmapDay(
startDate: startDate,
tokenState: tokenState,
- workflow: workflowByDate[startDate] ?? .empty(startDate: startDate)
+ workflow: workflowByDate[startDate] ?? .empty(startDate: startDate),
+ tokenUsage: workflow.tokenUsageByDate[startDate]
)
}
}
diff --git a/CodexBar/Resources/Localizable.xcstrings b/CodexBar/Resources/Localizable.xcstrings
index ff4b03a..29dd75b 100644
--- a/CodexBar/Resources/Localizable.xcstrings
+++ b/CodexBar/Resources/Localizable.xcstrings
@@ -705,6 +705,118 @@
}
}
},
+ "activity.tokens.cache-hit-rate" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Cache-H"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "缓存命中率"
+ }
+ }
+ }
+ },
+ "activity.tokens.cache-write" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Cache-W"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "缓存写入"
+ }
+ }
+ }
+ },
+ "activity.tokens.cached-read" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Cached"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "缓存命中"
+ }
+ }
+ }
+ },
+ "activity.tokens.reasoning" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Reasoning"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "推理输出"
+ }
+ }
+ }
+ },
+ "activity.tokens.input" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Input"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "输入总计"
+ }
+ }
+ }
+ },
+ "activity.tokens.output" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Output"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "输出总计"
+ }
+ }
+ }
+ },
+ "activity.tokens.total" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Total"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "总计"
+ }
+ }
+ }
+ },
"app.action.quit" : {
"localizations" : {
"en" : {
@@ -5233,18 +5345,34 @@
}
}
},
- "usage.heatmap.intensity" : {
+ "usage.heatmap.activity-metrics" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "Intensity"
+ "value" : "Activity data"
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "用量强度"
+ "value" : "活动数据"
+ }
+ }
+ }
+ },
+ "usage.heatmap.token-metrics" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Session token data"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "会话 Token 数据"
}
}
}
@@ -5510,13 +5638,13 @@
"en" : {
"stringUnit" : {
"state" : "translated",
- "value" : "Recalculate %@ from local Hook events.\nReplace this device's cloud data for those dates during the next sync."
+ "value" : "Recalculate activity data and session token data for %@ from local Hook events and rollouts.\nAfter syncing, local data will be replaced and cloud data updated."
}
},
"zh-Hans" : {
"stringUnit" : {
"state" : "translated",
- "value" : "将从本机原始 Hook 事件重新统计 %@\n并在下次同步时替换当前设备对应日期的云端数据"
+ "value" : "将从本机 Hook 事件和 rollout 重新统计 %@ 的活动数据和会话 Token 数据\n同步后将替换本机数据并更新云端数据"
}
}
}
@@ -5745,6 +5873,70 @@
}
}
},
+ "workflow.rebuild.status.running" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Rebuilding activity data and session token data in the background"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "正在后台重建活动数据和会话 Token 数据"
+ }
+ }
+ }
+ },
+ "workflow.rebuild.summary.tokens" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "; %lld session token records"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "; 会话 Token 数据 %lld 条"
+ }
+ }
+ }
+ },
+ "workflow.rebuild.summary.tokens-failed" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "; session token data rebuild incomplete, please retry"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "; 会话 Token 数据重建未完成, 请重试"
+ }
+ }
+ }
+ },
+ "workflow.rebuild.error.already-running" : {
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Session token data is already being rebuilt"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "会话 Token 数据正在重建中"
+ }
+ }
+ }
+ },
"workflow.rebuild.title" : {
"localizations" : {
"en" : {
diff --git a/CodexBar/Services/Workflow/CodexActivityMonitor.swift b/CodexBar/Services/Workflow/CodexActivityMonitor.swift
index a94bf7f..38559e8 100644
--- a/CodexBar/Services/Workflow/CodexActivityMonitor.swift
+++ b/CodexBar/Services/Workflow/CodexActivityMonitor.swift
@@ -35,6 +35,7 @@ final class CodexActivityMonitor: ObservableObject {
var terminations: [CodexActivityTermination] = []
var recentlyEndedTaskAt: [CodexActivityTaskKey: Date] = [:]
var terminalTaskKeyByID: [UUID: CodexActivityTaskKey] = [:]
+ var terminalTokenUsageRequests: [UUID: CodexTaskTokenUsageRequest] = [:]
var activityTaskOrigins: [CodexActivityTaskKey: (origin: WorkflowEventOrigin, observedAt: Date)] = [:]
var tailReader: HookEventTailReader?
private var tailReaderControlTask: Task<Void, Never>?
@@ -443,8 +444,9 @@ final class CodexActivityMonitor: ObservableObject {
}
private func lifecycleReferences(now: Date, includeAll: Bool) -> [CodexActivityTurnReference] {
- var references = tasks.values.compactMap(\.turnReference)
+ var references = activeTokenUsageReferences()
references.append(contentsOf: subagentLifecycleReferences())
+ references.append(contentsOf: terminalTokenUsageReferences(now: now))
let due = pendingTerminalTasks.filter { includeAll || $0.value.nextPollAt <= now }
.sorted { $0.value.nextPollAt < $1.value.nextPollAt }
for (key, var pending) in due.prefix(16) {
@@ -487,6 +489,10 @@ final class CodexActivityMonitor: ObservableObject {
if !terminalOnly {
didChange = replayAssociatedSubagentEvents(into: &transitions) || didChange
}
+ if !terminalOnly {
+ didChange = applyActiveTokenUsage(states) || didChange
+ }
+ didChange = applyTerminalTokenUsage(states) || didChange
if didChange {
refreshSnapshot(now: Date())
}
@@ -1261,6 +1267,7 @@ final class CodexActivityMonitor: ObservableObject {
terminalTaskKeyByID = terminalTaskKeyByID.filter {
retainedTerminalIDs.contains($0.key)
}
+ terminalTokenUsageRequests = terminalTokenUsageRequests.filter { retainedTerminalIDs.contains($0.key) }
let endedTaskCutoff = now.addingTimeInterval(-Self.endedTaskRetention)
recentlyEndedTaskAt = recentlyEndedTaskAt.filter {
diff --git a/CodexBar/Services/Workflow/CodexActivityTask.swift b/CodexBar/Services/Workflow/CodexActivityTask.swift
index 5792273..02f2c0e 100644
--- a/CodexBar/Services/Workflow/CodexActivityTask.swift
+++ b/CodexBar/Services/Workflow/CodexActivityTask.swift
@@ -137,6 +137,7 @@ struct CodexActivityTask {
var executions: [CodexActivityExecutionKey: CodexActivityExecution] = [:]
var subagentsByID: [String: CodexSubagentObservation]
var isSubagentCountReliable: Bool
+ var tokenUsage: CodexTokenUsage?
init(
displayID: UUID,
@@ -190,7 +191,8 @@ struct CodexActivityTask {
startedAt: startedAt,
stateChangedAt: stateChangedAt,
showsPreciseDuration: showsPreciseDuration,
- activeSubagentCount: activeSubagentCount
+ activeSubagentCount: activeSubagentCount,
+ tokenUsage: tokenUsage
)
}
diff --git a/CodexBar/Services/Workflow/CodexActivityTerminalResolution.swift b/CodexBar/Services/Workflow/CodexActivityTerminalResolution.swift
index 1d7cb1c..2f0db88 100644
--- a/CodexBar/Services/Workflow/CodexActivityTerminalResolution.swift
+++ b/CodexBar/Services/Workflow/CodexActivityTerminalResolution.swift
@@ -45,7 +45,8 @@ extension CodexActivityMonitor {
modelName: event.modelName ?? task?.modelName,
effort: event.effort ?? task?.effort,
terminatedAt: event.timestamp,
- duration: task?.preciseDuration(until: event.timestamp)
+ duration: task?.preciseDuration(until: event.timestamp),
+ task: task
)
recordEndedTask(key, at: event.timestamp)
if let resolved = task?.resolvedTurnKey {
@@ -162,6 +163,7 @@ extension CodexActivityMonitor {
)
completions.append(completion)
terminalTaskKeyByID[completion.id] = key
+ registerTerminalTokenUsage(id: completion.id, key: key, task: task, endedAt: recordedCompletedAt)
recordTerminalPresentationEvent(.completed(completion))
recordEndedTask(key, at: recordedCompletedAt)
if let resolved = task.resolvedTurnKey {
@@ -181,7 +183,8 @@ extension CodexActivityMonitor {
modelName: task.modelName,
effort: task.effort,
terminatedAt: terminatedAt,
- duration: includesDuration ? task.preciseDuration(until: terminatedAt) : nil
+ duration: includesDuration ? task.preciseDuration(until: terminatedAt) : nil,
+ task: task
)
}
@@ -191,7 +194,8 @@ extension CodexActivityMonitor {
modelName: String?,
effort: String?,
terminatedAt: Date,
- duration: TimeInterval?
+ duration: TimeInterval?,
+ task: CodexActivityTask? = nil
) {
let termination = CodexActivityTermination(
id: UUID(),
@@ -204,6 +208,7 @@ extension CodexActivityMonitor {
)
terminations.append(termination)
terminalTaskKeyByID[termination.id] = key
+ registerTerminalTokenUsage(id: termination.id, key: key, task: task, endedAt: terminatedAt)
recordTerminalPresentationEvent(.terminated(termination))
}
@@ -260,6 +265,7 @@ extension CodexActivityMonitor {
terminations.removeAll()
recentlyEndedTaskAt.removeAll()
terminalTaskKeyByID.removeAll()
+ terminalTokenUsageRequests.removeAll()
activityTaskOrigins.removeAll()
pendingSubagentEvents.removeAll()
subagentTurnLinks.removeAll()
diff --git a/CodexBar/Services/Workflow/CodexActivityTokenUsage.swift b/CodexBar/Services/Workflow/CodexActivityTokenUsage.swift
new file mode 100644
index 0000000..081e824
--- /dev/null
+++ b/CodexBar/Services/Workflow/CodexActivityTokenUsage.swift
@@ -0,0 +1,128 @@
+import Foundation
+
+struct CodexTaskTokenUsageRequest {
+ let root: CodexActivityTurnReference
+ let expectedAgentIDs: Set<String>
+ var references: Set<CodexActivityTurnReference>
+ let deadline: Date
+ var nextReadAt = Date.distantPast
+
+ func usage(from states: [CodexSessionTaskLifecycleState], requiresFinalUsage: Bool = true) -> CodexTokenUsage? {
+ let agentIDs = Set(references.filter { $0 != root }.map(\.sessionId))
+ guard !requiresFinalUsage || expectedAgentIDs.isSubset(of: agentIDs) else { return nil }
+ var total: CodexTokenUsage?
+ for reference in references {
+ guard let state = states.first(where: { $0.sessionId == reference.sessionId && $0.turnId == reference.turnId }),
+ state.readStatus == .complete, state.threadId == reference.sessionId,
+ state.rootTurnId == root.turnId,
+ (state.rootSessionId ?? state.threadId) == root.sessionId,
+ !requiresFinalUsage || reference == root || state.terminal != nil,
+ let usage = state.tokenUsage else {
+ if requiresFinalUsage {
+ return nil
+ }
+ continue
+ }
+ if let previous = total {
+ guard let sum = previous.adding(usage) else { return nil }
+ total = sum
+ } else {
+ total = usage
+ }
+ }
+ return total
+ }
+}
+
+extension CodexActivityMonitor {
+ func registerTerminalTokenUsage(
+ id: UUID, key: CodexActivityTaskKey, task: CodexActivityTask?, endedAt: Date, now: Date = Date()
+ ) {
+ guard let session = key.sessionId, let turn = task?.associatedTurnId ?? key.turnId else { return }
+ // 缺少子 Agent 身份时不能把主线程小计展示为整项任务总量
+ guard task?.executions.keys.contains(where: \.isUnattributed) != true else { return }
+ let root = CodexActivityTurnReference(sessionId: session, turnId: turn, startedAt: task?.startedAt ?? endedAt)
+ terminalTokenUsageRequests[id] = tokenUsageRequest(root: root, task: task, deadline: now.addingTimeInterval(30))
+ }
+
+ private func tokenUsageRequest(
+ root: CodexActivityTurnReference, task: CodexActivityTask?, deadline: Date
+ ) -> CodexTaskTokenUsageRequest {
+ var references: Set = [root]
+ let rootKey = CodexActivityTaskKey.turn(session: root.sessionId, turn: root.turnId)
+ references.formUnion(subagentTurnLinks.filter { $0.value == rootKey }.map(\.key))
+ if let task {
+ for owner in task.executions.keys {
+ guard let agent = owner.agentId, let turn = owner.turnId else { continue }
+ references.insert(CodexActivityTurnReference(sessionId: agent, turnId: turn, startedAt: root.startedAt))
+ }
+ }
+ return CodexTaskTokenUsageRequest(
+ root: root, expectedAgentIDs: Set(task?.subagentsByID.keys.map(\.self) ?? []),
+ references: references, deadline: deadline
+ )
+ }
+
+ func activeTokenUsageReferences() -> [CodexActivityTurnReference] {
+ var references: Set<CodexActivityTurnReference> = []
+ for task in tasks.values {
+ guard let root = task.turnReference else { continue }
+ references.formUnion(tokenUsageRequest(root: root, task: task, deadline: .distantFuture).references)
+ }
+ return Array(references)
+ }
+
+ @discardableResult
+ func applyActiveTokenUsage(_ states: [CodexSessionTaskLifecycleState]) -> Bool {
+ var changed = false
+ for (key, var task) in tasks {
+ guard let root = task.turnReference else { continue }
+ let request = tokenUsageRequest(root: root, task: task, deadline: .distantFuture)
+ // 运行中汇总已明确归属的累计用量, 尚未产生记录的线程不伪造零值
+ let usage = request.usage(from: states, requiresFinalUsage: false)
+ guard task.tokenUsage != usage else { continue }
+ task.tokenUsage = usage
+ tasks[key] = task
+ changed = true
+ }
+ return changed
+ }
+
+ /// 结束后有界重读, Interrupt Hook 可能先于最后一条用量落盘
+ func terminalTokenUsageReferences(now: Date) -> [CodexActivityTurnReference] {
+ terminalTokenUsageRequests = terminalTokenUsageRequests.filter { $0.value.deadline > now }
+ let due = terminalTokenUsageRequests.filter { $0.value.nextReadAt <= now }
+ .sorted { $0.value.nextReadAt < $1.value.nextReadAt }.prefix(16)
+ var references: Set<CodexActivityTurnReference> = []
+ for (id, var request) in due {
+ let rootKey = CodexActivityTaskKey.turn(session: request.root.sessionId, turn: request.root.turnId)
+ request.references.formUnion(subagentTurnLinks.filter { $0.value == rootKey }.map(\.key))
+ request.nextReadAt = now.addingTimeInterval(2)
+ terminalTokenUsageRequests[id] = request
+ references.formUnion(request.references)
+ }
+ return Array(references)
+ }
+
+ @discardableResult
+ func applyTerminalTokenUsage(_ states: [CodexSessionTaskLifecycleState]) -> Bool {
+ var changed = false
+ for (id, var request) in terminalTokenUsageRequests {
+ guard states.contains(where: { $0.sessionId == request.root.sessionId && $0.turnId == request.root.turnId }) else { continue }
+ let rootKey = CodexActivityTaskKey.turn(session: request.root.sessionId, turn: request.root.turnId)
+ request.references.formUnion(subagentTurnLinks.filter { $0.value == rootKey }.map(\.key))
+ terminalTokenUsageRequests[id] = request
+ // 仅汇总已确认属于本轮的线程, 临时读取不完整时保留上次结果
+ guard let usage = request.usage(from: states) else { continue }
+ if let index = completions.firstIndex(where: { $0.id == id }), completions[index].tokenUsage != usage {
+ completions[index].tokenUsage = usage
+ changed = true
+ }
+ if let index = terminations.firstIndex(where: { $0.id == id }), terminations[index].tokenUsage != usage {
+ terminations[index].tokenUsage = usage
+ changed = true
+ }
+ }
+ return changed
+ }
+}
diff --git a/CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift b/CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift
index 67fa8a9..49eb6b2 100644
--- a/CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift
+++ b/CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift
@@ -89,7 +89,8 @@ actor CodexSessionLifecycleReader {
parentThreadId: cursor?.metadata?.parentThreadId,
lastExecutionProgressAt: known?.lastExecutionProgressAt,
incompleteTailUnchangedSince: status == .incomplete && !hasReadGap && known?.hasContext == true && known?.terminal == nil
- ? cursor?.incompleteTailUnchangedSince : nil
+ ? cursor?.incompleteTailUnchangedSince : nil,
+ tokenUsage: turnStatus == .complete ? known?.tokenUsage : nil
))
}
}
@@ -295,6 +296,20 @@ private nonisolated struct SessionFileCursor {
}
for envelope in decoded.values {
apply(envelope)
+ if envelope.type == "token_usage_record", let turnId = envelope.payload?.turnId {
+ // 用量字段损坏不能影响生命周期解码, 也不能沿用上一条累计值
+ var state = lifecycleByTurnId[turnId] ?? SessionTurnLifecycle()
+ state.tokenUsage = nil
+ if let record = try? JSONDecoder().decode(CodexRolloutTokenUsageRecord.self, from: partialLineData).payload,
+ record.threadId == metadata?.id,
+ record.sessionId == (metadata?.sessionId ?? metadata?.id),
+ !record.responseId.isEmpty, !record.rootTurnId.isEmpty,
+ !turnId.isEmpty, record.turnTokenUsage.isValid {
+ state.tokenUsage = record.turnTokenUsage
+ state.rootTurnId = record.rootTurnId
+ }
+ lifecycleByTurnId[turnId] = state
+ }
}
}
@@ -304,8 +319,11 @@ private nonisolated struct SessionFileCursor {
mutating func markReadGap() {
hasDecodeFailures = true
currentTurnId = nil
- for turnId in lifecycleByTurnId.keys where lifecycleByTurnId[turnId]?.terminal == nil {
- lifecycleByTurnId[turnId]?.hasReadGap = true
+ for turnId in lifecycleByTurnId.keys {
+ lifecycleByTurnId[turnId]?.tokenUsage = nil
+ if lifecycleByTurnId[turnId]?.terminal == nil {
+ lifecycleByTurnId[turnId]?.hasReadGap = true
+ }
}
}
@@ -501,6 +519,7 @@ private nonisolated enum SessionLifecycleChange {
}
private nonisolated struct SessionTurnLifecycle {
+ var tokenUsage: CodexTokenUsage?
var rootTurnId: String?
var hasReadGap = false
var contextObservedAt: Date?
@@ -555,6 +574,7 @@ nonisolated struct CodexSessionTaskLifecycleState {
var parentThreadId: String?
var lastExecutionProgressAt: Date?
var incompleteTailUnchangedSince: Date?
+ var tokenUsage: CodexTokenUsage?
}
nonisolated enum CodexSessionReadStatus {
diff --git a/CodexBar/Services/Workflow/CodexTokenHistoryStore.swift b/CodexBar/Services/Workflow/CodexTokenHistoryStore.swift
new file mode 100644
index 0000000..e4234b0
--- /dev/null
+++ b/CodexBar/Services/Workflow/CodexTokenHistoryStore.swift
@@ -0,0 +1,555 @@
+import CryptoKit
+import Darwin
+import Foundation
+import os
+
+/// 历史采集独立于实时任务, 全量补读后按文件游标增量消费
+actor CodexTokenHistoryStore {
+ private let codexHomeURL: URL
+ private let directoryURL: URL
+ private let byteBudget: Int
+ private let reportProgress: @Sendable (CodexTokenReplayProgress) -> Void
+ private var lastReportedProgress: CodexTokenReplayProgress?
+
+ init(
+ codexHomeURL: URL = CodexCLIResolver.codexHomeDirectory(),
+ directoryURL: URL = WorkflowStorage.directoryURL().appendingPathComponent("Tokens"),
+ byteBudget: Int = 64 * 1024 * 1024,
+ reportProgress: @escaping @Sendable (CodexTokenReplayProgress) -> Void = { $0.writeLog() }
+ ) {
+ self.codexHomeURL = codexHomeURL
+ self.directoryURL = directoryURL
+ self.byteBudget = byteBudget
+ self.reportProgress = reportProgress
+ }
+
+ func refresh(now: Date = Date(), baseline: CodexTokenHistoryBaseline? = nil) throws -> [CodexTokenTurn] {
+ let duration = LogDuration()
+ return try CodexTokenFileStorage.withLock(in: directoryURL) {
+ let url = directoryURL.appendingPathComponent("ledger.json")
+ var ledger = try CodexTokenFileStorage.load(TokenHistoryLedger.self, from: url) ?? TokenHistoryLedger()
+ guard ledger.schema == TokenHistoryLedger.currentSchema else { throw CocoaError(.fileReadCorruptFile) }
+ var restored = false
+ for turn in ledger.turns.values {
+ guard let replacement = baseline?.replacement(for: turn) else { continue }
+ ledger.restore(replacement)
+ restored = true
+ }
+ // 已扫描的累计值可能混有重建前的旧记录, 重新按记录时间消费而不是给旧值换上新标记
+ if restored {
+ ledger.files.removeAll()
+ }
+ let cutoff = WorkflowStorage.retentionCutoffDate(today: now)
+ let files = rolloutFiles(since: cutoff)
+ var remaining = byteBudget
+ // 每轮先处理上次尚未扫描的文件, 防止大型活跃文件让历史补读饥饿
+ let ordered = files.map { file in
+ (
+ url: file,
+ lastReadAt: ledger.files[fileKey(file)]?.lastReadAt ?? .distantPast,
+ modifiedAt: (try? file.resourceValues(forKeys: [.contentModificationDateKey]))?.contentModificationDate ?? .distantPast
+ )
+ }.sorted { lhs, rhs in
+ if lhs.lastReadAt != rhs.lastReadAt {
+ return lhs.lastReadAt < rhs.lastReadAt
+ }
+ // 同批未读文件优先补近期数据, 不依赖文件系统枚举顺序
+ if lhs.modifiedAt != rhs.modifiedAt {
+ return lhs.modifiedAt > rhs.modifiedAt
+ }
+ return lhs.url.path < rhs.url.path
+ }.map(\.url)
+ var results: [String: TokenHistoryScanResult] = [:]
+ for file in ordered where remaining > 0 {
+ try Task.checkCancellation()
+ results[fileKey(file)] = try scan(file, ledger: &ledger, remaining: &remaining, now: now, baseline: baseline)
+ }
+ let roots = Set(ledger.turns.values.filter { $0.updatedAt >= cutoff }.map(\.rootID))
+ ledger.turns = ledger.turns.filter { $0.value.updatedAt >= cutoff || roots.contains($0.key) }
+ ledger.recoveryCutoffs = ledger.recoveryCutoffs?.filter { ledger.turns[$0.key] != nil }
+ let fileKeys = Set(files.map(fileKey))
+ ledger.files = ledger.files.filter { fileKeys.contains($0.key) }
+ try CodexTokenFileStorage.save(ledger, to: url)
+ let progress = replayProgress(files: files, ledger: ledger, results: results, batchBytes: byteBudget - remaining, duration: duration)
+ publishProgress(progress, restored: restored)
+ return Array(ledger.turns.values)
+ }
+ }
+
+ private func replayProgress(
+ files: [URL], ledger: TokenHistoryLedger, results: [String: TokenHistoryScanResult], batchBytes: Int, duration: LogDuration
+ ) -> CodexTokenReplayProgress {
+ var progress = CodexTokenReplayProgress(totalFiles: files.count, batchBytes: batchBytes, elapsed: duration.elapsed)
+ for file in files {
+ let key = fileKey(file)
+ guard let stat = WorkflowStorage.fileStat(at: file) else {
+ progress.unavailableFiles += 1
+ continue
+ }
+ progress.totalBytes += stat.size
+ let cursor = ledger.files[key]
+ let hasValidCursor = cursor?.inode == stat.identifier && (cursor?.offset ?? 0) <= stat.size
+ let offset = hasValidCursor ? cursor?.offset ?? 0 : 0
+ progress.processedBytes += offset
+ if results[key] == .unavailable {
+ progress.unavailableFiles += 1
+ } else if results[key] == .waitingForLine || cursor?.droppingLongLine == true && offset == stat.size {
+ progress.waitingFiles += 1
+ } else if hasValidCursor, offset == stat.size {
+ progress.completedFiles += 1
+ }
+ }
+ return progress
+ }
+
+ private func publishProgress(_ progress: CodexTokenReplayProgress, restored: Bool) {
+ guard progress.totalFiles > 0 || lastReportedProgress != nil else { return }
+ if let previous = lastReportedProgress, !restored {
+ // 追平后的普通追加不重复记录完成, 停在同一个半行或不可读文件时也不刷屏
+ guard !(previous.isComplete && progress.isComplete), !progress.hasSamePosition(as: previous) else { return }
+ }
+ lastReportedProgress = progress
+ reportProgress(progress)
+ }
+
+ private func rolloutFiles(since cutoff: Date) -> [URL] {
+ var result: [URL] = []
+ for name in ["sessions", "archived_sessions"] {
+ let root = codexHomeURL.appendingPathComponent(name)
+ guard let enumerator = FileManager.default.enumerator(
+ at: root, includingPropertiesForKeys: [.isRegularFileKey, .contentModificationDateKey], options: [.skipsHiddenFiles]
+ ) else { continue }
+ for case let url as URL in enumerator where url.pathExtension == "jsonl" && url.lastPathComponent.hasPrefix("rollout-") {
+ guard let values = try? url.resourceValues(forKeys: [.isRegularFileKey, .contentModificationDateKey]),
+ values.isRegularFile == true, (values.contentModificationDate ?? .distantPast) >= cutoff else { continue }
+ result.append(url)
+ }
+ }
+ return result
+ }
+
+ @discardableResult
+ private func scan(
+ _ url: URL, ledger: inout TokenHistoryLedger, remaining: inout Int, now: Date,
+ snapshot: WorkflowFileStat? = nil, baseline: CodexTokenHistoryBaseline? = nil
+ ) throws -> TokenHistoryScanResult {
+ guard let source = try openSource(url, snapshot: snapshot) else { return .unavailable }
+ let handle = source.handle
+ defer { try? handle.close() }
+ let size = snapshot?.size ?? source.stat.size
+ let inode = source.stat.identifier
+ let key = fileKey(url)
+ var cursor = ledger.files[key] ?? TokenHistoryCursor(inode: inode)
+ if cursor.inode != inode || cursor.offset > size {
+ cursor = TokenHistoryCursor(inode: inode)
+ }
+ if let hash = cursor.boundaryHash, try boundaryHash(handle, at: cursor.offset) != hash {
+ if snapshot != nil {
+ throw CodexTokenRebuildError.sourceChanged
+ }
+ cursor = TokenHistoryCursor(inode: inode)
+ }
+ cursor.lastReadAt = now
+ guard cursor.offset < size else {
+ ledger.files[key] = cursor
+ return TokenHistoryScanResult(reachedEnd: true, hasPartialLine: cursor.droppingLongLine)
+ }
+ try handle.seek(toOffset: cursor.offset)
+ var line = Data()
+ var dropping = cursor.droppingLongLine
+ reading: while cursor.offset < size, remaining > 0 || !line.isEmpty {
+ try Task.checkCancellation()
+ let count = remaining > 0 ? min(64 * 1024, remaining) : 64 * 1024
+ let data = try handle.read(upToCount: min(count, Int(clamping: size - cursor.offset))) ?? Data()
+ if data.isEmpty {
+ if snapshot != nil {
+ throw CodexTokenRebuildError.sourceChanged
+ }
+ break
+ }
+ remaining -= data.count
+ var offset = data.startIndex
+ while offset < data.endIndex {
+ let newline = data[offset...].firstIndex(of: JSONLines.newlineByte)
+ let end = newline ?? data.endIndex
+ let fragment = data[offset ..< end]
+ cursor.offset += UInt64(fragment.count + (newline == nil ? 0 : 1))
+ if !dropping {
+ if line.count + fragment.count > 1024 * 1024 {
+ line.removeAll(keepingCapacity: false)
+ dropping = true
+ } else {
+ line.append(contentsOf: fragment)
+ }
+ }
+ if newline != nil {
+ if !dropping {
+ consume(line, thread: source.thread, session: source.session, ledger: &ledger, baseline: baseline)
+ }
+ line.removeAll(keepingCapacity: true)
+ dropping = false
+ cursor.committedOffset = cursor.offset
+ if remaining <= 0 {
+ break reading
+ }
+ offset = end + 1
+ } else {
+ break
+ }
+ }
+ }
+ // 半行不提交, 超长正文则跨轮继续跳过, 不将正文写入缓存
+ let reachedEnd = cursor.offset >= size
+ cursor.droppingLongLine = dropping
+ if !dropping {
+ cursor.offset = cursor.committedOffset
+ }
+ cursor.boundaryHash = try boundaryHash(handle, at: cursor.offset)
+ ledger.files[key] = cursor
+ return TokenHistoryScanResult(reachedEnd: reachedEnd, hasPartialLine: dropping || cursor.offset < size)
+ }
+
+ private func openSource(
+ _ url: URL, snapshot: WorkflowFileStat?
+ ) throws -> TokenHistoryReadSource? {
+ guard let stat = WorkflowStorage.fileStat(at: url) else {
+ if snapshot != nil {
+ throw CocoaError(.fileReadNoSuchFile)
+ }
+ return nil
+ }
+ if let snapshot, snapshot.identifier != stat.identifier || stat.size < snapshot.size {
+ throw CodexTokenRebuildError.sourceChanged
+ }
+ guard let metadata = WorkflowRolloutMetadataReader.metadata(transcriptPath: url.path), let thread = metadata.id,
+ let handle = try? FileHandle(forReadingFrom: url) else {
+ if snapshot != nil {
+ throw CocoaError(.fileReadCorruptFile)
+ }
+ return nil
+ }
+ return TokenHistoryReadSource(stat: stat, thread: thread, session: metadata.sessionId ?? thread, handle: handle)
+ }
+
+ private func boundaryHash(_ handle: FileHandle, at offset: UInt64) throws -> String {
+ let count = min(offset, 512)
+ try handle.seek(toOffset: offset - count)
+ let data = try handle.read(upToCount: Int(count)) ?? Data()
+ return SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined()
+ }
+
+ private func consume(
+ _ line: Data, thread: String, session: String, ledger: inout TokenHistoryLedger,
+ baseline: CodexTokenHistoryBaseline?
+ ) {
+ guard let envelope = try? JSONDecoder().decode(TokenHistoryLine.self, from: line) else { return }
+ if envelope.type == "token_usage_record" {
+ guard let payload = try? JSONDecoder().decode(CodexRolloutTokenUsageRecord.self, from: line).payload,
+ payload.threadId == thread, payload.sessionId == session,
+ !payload.turnId.isEmpty, !payload.rootTurnId.isEmpty, !payload.responseId.isEmpty,
+ payload.turnTokenUsage.isValid, let timestamp = envelope.date else { return }
+ let id = CodexTokenTurn.identifier(thread: thread, turn: payload.turnId)
+ var value = CodexTokenTurn(
+ id: id, rootID: CodexTokenTurn.identifier(thread: session, turn: payload.rootTurnId),
+ startedAt: ledger.turns[id]?.startedAt, updatedAt: timestamp,
+ usage: payload.turnTokenUsage, rebuiltAt: ledger.turns[id]?.rebuiltAt
+ )
+ if let replacement = baseline?.replacement(for: value) {
+ ledger.restore(replacement)
+ value.rebuiltAt = replacement.rebuiltAt
+ }
+ // 恢复后重放旧文件和归档副本时, 不能恢复云端已经修正的旧累计值
+ guard timestamp > (ledger.recoveryCutoffs?[id] ?? .distantPast) else { return }
+ ledger.turns[id] = ledger.turns[id]?.merging(value) ?? value
+ } else if envelope.type == "event_msg", ["task_started", "turn_started"].contains(envelope.payload?.type ?? ""),
+ let turn = envelope.payload?.turnId, !turn.isEmpty,
+ let timestamp = envelope.payload?.startedAt.flatMap(TokenHistoryLine.eventDate) ?? envelope.date {
+ let id = CodexTokenTurn.identifier(thread: thread, turn: turn)
+ let value = CodexTokenTurn(
+ id: id, rootID: id, startedAt: timestamp, updatedAt: timestamp, usage: nil, rebuiltAt: ledger.turns[id]?.rebuiltAt
+ )
+ if let replacement = baseline?.replacement(for: value) {
+ ledger.restore(replacement)
+ } else {
+ ledger.turns[id] = ledger.turns[id]?.merging(value) ?? value
+ }
+ }
+ }
+
+ private func fileKey(_ url: URL) -> String {
+ SHA256.hash(data: Data(url.path.utf8)).map { String(format: "%02x", $0) }.joined()
+ }
+}
+
+extension CodexTokenHistoryStore {
+ func currentTurns() throws -> [CodexTokenTurn] {
+ try CodexTokenFileStorage.withLock(in: directoryURL) {
+ try Array(loadLedger().turns.values)
+ }
+ }
+
+ func rebuildableDateKeys(now: Date = Date()) throws -> [String] {
+ try CodexTokenFileStorage.withLock(in: directoryURL) {
+ let ledger = try loadLedger()
+ let cutoff = WorkflowStorage.retentionCutoffDate(today: now)
+ return Set(ledger.turns.values.compactMap { turn -> String? in
+ guard let start = ledger.turns[turn.rootID]?.startedAt, start >= cutoff, start <= now else { return nil }
+ return CodexDateFormat.dayString(from: start)
+ }).sorted()
+ }
+ }
+
+ /// 只在完整扫描成功后提交, 扫描期间不持有共享账本锁, 旧统计仍可读取
+ func rebuild(for dateKeys: [String], now: Date = Date()) async throws -> CodexTokenRebuildResult {
+ guard let lock = try CodexTokenFileStorage.acquireLock(in: directoryURL, name: "rebuild.lock", nonblocking: true) else {
+ throw CodexTokenRebuildError.alreadyRunning
+ }
+ defer { CodexTokenFileStorage.releaseLock(lock) }
+ let dates = Set(dateKeys.filter {
+ WorkflowStorage.isValidDateKey($0) && $0 >= WorkflowStorage.dateKey(for: WorkflowStorage.retentionCutoffDate(today: now))
+ && $0 <= WorkflowStorage.dateKey(for: now)
+ })
+ guard !dates.isEmpty else { return .empty }
+ let files = try rolloutFiles(since: WorkflowStorage.retentionCutoffDate(today: now)).map { url in
+ guard let stat = WorkflowStorage.fileStat(at: url) else { throw CocoaError(.fileReadNoSuchFile) }
+ return (url, stat)
+ }
+ var rebuilt = TokenHistoryLedger()
+ for (url, stat) in files {
+ var finished = false
+ while !finished {
+ try Task.checkCancellation()
+ var remaining = max(1, byteBudget)
+ finished = try scan(url, ledger: &rebuilt, remaining: &remaining, now: now, snapshot: stat) != .pending
+ await Task.yield()
+ }
+ }
+ return try commitRebuild(rebuilt, dates: dates, startedAt: now)
+ }
+
+ private func loadLedger() throws -> TokenHistoryLedger {
+ let ledger = try CodexTokenFileStorage.load(TokenHistoryLedger.self, from: directoryURL.appendingPathComponent("ledger.json"))
+ ?? TokenHistoryLedger()
+ guard ledger.schema == TokenHistoryLedger.currentSchema else { throw CocoaError(.fileReadCorruptFile) }
+ return ledger
+ }
+
+ private func commitRebuild(_ rebuilt: TokenHistoryLedger, dates: Set<String>, startedAt: Date) throws -> CodexTokenRebuildResult {
+ try CodexTokenFileStorage.withLock(in: directoryURL) {
+ try Task.checkCancellation()
+ var ledger = try loadLedger()
+ let requiredRoots = Set(rebuilt.turns.values.filter { $0.usage != nil }.map(\.rootID))
+ var rebuiltDates: Set<String> = []
+ var turnCount = 0
+ for var turn in rebuilt.turns.values {
+ let previous = ledger.turns[turn.id]
+ if turn.usage == nil, let previous {
+ turn.rootID = previous.rootID
+ }
+ guard let start = rebuilt.turns[turn.rootID]?.startedAt ?? ledger.turns[turn.rootID]?.startedAt,
+ dates.contains(CodexDateFormat.dayString(from: start)) else { continue }
+ turn.startedAt = turn.startedAt ?? previous?.startedAt
+ // 读取开始之后新产生的累计用量保留, 不用重建的文件快照覆盖活跃任务的新进展
+ if var previous, previous.updatedAt > startedAt {
+ previous.rebuiltAt = nil
+ turn = turn.merging(previous)
+ }
+ if turn.usage != nil || previous?.usage != nil || requiredRoots.contains(turn.id) {
+ turn.rebuiltAt = max(startedAt, previous?.rebuiltAt?.addingTimeInterval(0.001) ?? startedAt)
+ }
+ ledger.turns[turn.id] = turn
+ ledger.recoveryCutoffs?.removeValue(forKey: turn.id)
+ rebuiltDates.insert(CodexDateFormat.dayString(from: start))
+ if turn.usage != nil {
+ turnCount += 1
+ }
+ }
+ try CodexTokenFileStorage.save(ledger, to: directoryURL.appendingPathComponent("ledger.json"))
+ return CodexTokenRebuildResult(dateKeys: rebuiltDates, turnCount: turnCount)
+ }
+ }
+}
+
+nonisolated struct CodexTokenRebuildResult {
+ let dateKeys: Set<String>
+ let turnCount: Int
+ static let empty = Self(dateKeys: [], turnCount: 0)
+}
+
+private nonisolated enum CodexTokenRebuildError: LocalizedError {
+ case sourceChanged
+ case alreadyRunning
+
+ var errorDescription: String? {
+ switch self {
+ case .sourceChanged: String(localized: "workflow.rebuild.error.source-changed")
+ case .alreadyRunning: String(localized: "workflow.rebuild.error.already-running")
+ }
+ }
+}
+
+private nonisolated enum TokenHistoryScanResult {
+ case pending
+ case waitingForLine
+ case complete
+ case unavailable
+
+ init(reachedEnd: Bool, hasPartialLine: Bool) {
+ if !reachedEnd {
+ self = .pending
+ } else {
+ self = hasPartialLine ? .waitingForLine : .complete
+ }
+ }
+}
+
+/// 只记录扫描工作量, 不携带路径 轮次身份或 token 用量
+nonisolated struct CodexTokenReplayProgress {
+ let totalFiles: Int
+ let batchBytes: Int
+ let elapsed: String
+ var completedFiles = 0
+ var unavailableFiles = 0
+ var waitingFiles = 0
+ var totalBytes: UInt64 = 0
+ var processedBytes: UInt64 = 0
+
+ var isComplete: Bool {
+ completedFiles == totalFiles
+ }
+
+ var remainingBytes: UInt64 {
+ totalBytes - min(processedBytes, totalBytes)
+ }
+
+ func hasSamePosition(as other: Self) -> Bool {
+ totalFiles == other.totalFiles && completedFiles == other.completedFiles
+ && unavailableFiles == other.unavailableFiles && waitingFiles == other.waitingFiles
+ && totalBytes == other.totalBytes && processedBytes == other.processedBytes
+ }
+
+ func writeLog() {
+ let fraction = totalBytes == 0 ? 0 : Double(processedBytes) / Double(totalBytes)
+ let percent = isComplete ? 100 : min(99.9, fraction * 100)
+ let details = LogFields.joined(
+ "files=\(completedFiles)/\(totalFiles)",
+ "progress=\(String(format: "%.1f%%", percent))",
+ "processed=\(Self.formattedBytes(processedBytes))/\(Self.formattedBytes(totalBytes))",
+ "remaining=\(Self.formattedBytes(remainingBytes))",
+ "read=\(Self.formattedBytes(UInt64(max(0, batchBytes))))",
+ "waiting=\(waitingFiles)",
+ "unavailable=\(unavailableFiles)",
+ "elapsed=\(elapsed)"
+ )
+ if isComplete {
+ AppLog.workflow.notice("Rollout 回放完成: \(details, privacy: .public)")
+ } else {
+ AppLog.workflow.notice("Rollout 回放进度: \(details, privacy: .public)")
+ }
+ }
+
+ private static func formattedBytes(_ bytes: UInt64) -> String {
+ if bytes < 1024 {
+ return "\(bytes)B"
+ }
+ if bytes < 1024 * 1024 {
+ return String(format: "%.2fKiB", Double(bytes) / 1024)
+ }
+ return String(format: "%.2fMiB", Double(bytes) / (1024 * 1024))
+ }
+}
+
+private nonisolated struct TokenHistoryReadSource {
+ let stat: WorkflowFileStat
+ let thread: String
+ let session: String
+ let handle: FileHandle
+}
+
+private nonisolated struct TokenHistoryLedger: Codable {
+ static let currentSchema = 1
+ var schema = currentSchema
+ var turns: [String: CodexTokenTurn] = [:]
+ var files: [String: TokenHistoryCursor] = [:]
+ var recoveryCutoffs: [String: Date]?
+
+ mutating func restore(_ turn: CodexTokenTurn) {
+ turns[turn.id] = turn
+ if recoveryCutoffs == nil {
+ recoveryCutoffs = [:]
+ }
+ recoveryCutoffs?[turn.id] = turn.rebuiltAt
+ }
+}
+
+private nonisolated struct TokenHistoryCursor: Codable {
+ let inode: UInt64
+ var offset: UInt64 = 0
+ var committedOffset: UInt64 = 0
+ var droppingLongLine = false
+ var lastReadAt = Date.distantPast
+ var boundaryHash: String?
+}
+
+private nonisolated struct TokenHistoryLine: Decodable {
+ let type: String
+ let timestamp: String?
+ let payload: TokenHistoryEvent?
+ var date: Date? {
+ timestamp.flatMap(CodexDateFormat.iso8601Date)
+ }
+
+ static func eventDate(_ value: Double) -> Date? {
+ guard value.isFinite, value > 0 else { return nil }
+ return Date(timeIntervalSince1970: value > 100000000000 ? value / 1000 : value)
+ }
+}
+
+private nonisolated struct TokenHistoryEvent: Decodable {
+ let type: String?
+ let turnId: String?
+ let startedAt: Double?
+ enum CodingKeys: String, CodingKey {
+ case type
+ case turnId = "turn_id"
+ case startedAt = "started_at"
+ }
+}
+
+/// 独立文件锁避免 Debug 与 Release 互相覆盖, 不占用 Hook recorder 的锁
+nonisolated enum CodexTokenFileStorage {
+ static func withLock<T>(in directory: URL, _ operation: () throws -> T) throws -> T {
+ guard let descriptor = try acquireLock(in: directory) else { throw POSIXError(.EIO) }
+ defer { releaseLock(descriptor) }
+ return try operation()
+ }
+
+ static func acquireLock(in directory: URL, name: String = "store.lock", nonblocking: Bool = false) throws -> Int32? {
+ try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+ let descriptor = open(directory.appendingPathComponent(name).path, O_RDWR | O_CREAT, 0o600)
+ guard descriptor >= 0 else { throw POSIXError(.EIO) }
+ guard flock(descriptor, LOCK_EX | (nonblocking ? LOCK_NB : 0)) == 0 else {
+ let code = errno
+ close(descriptor)
+ if nonblocking, code == EWOULDBLOCK {
+ return nil
+ }
+ throw POSIXError(POSIXErrorCode(rawValue: code) ?? .EIO)
+ }
+ return descriptor
+ }
+
+ static func releaseLock(_ descriptor: Int32) {
+ flock(descriptor, LOCK_UN)
+ close(descriptor)
+ }
+
+ static func load<T: Decodable>(_: T.Type, from url: URL) throws -> T? {
+ guard FileManager.default.fileExists(atPath: url.path) else { return nil }
+ return try JSONDecoder().decode(T.self, from: Data(contentsOf: url))
+ }
+
+ static func save(_ value: some Encodable, to url: URL) throws {
+ try JSONLines.stableEncoder.encode(value).write(to: url, options: .atomic)
+ }
+}
diff --git a/CodexBar/Services/Workflow/CodexTokenHistorySync.swift b/CodexBar/Services/Workflow/CodexTokenHistorySync.swift
new file mode 100644
index 0000000..e97caf3
--- /dev/null
+++ b/CodexBar/Services/Workflow/CodexTokenHistorySync.swift
@@ -0,0 +1,221 @@
+import CloudKit
+import Foundation
+
+/// 每个线程轮次一个云端累计记录, 多设备通过条件写入收敛到同一份用量
+actor CodexTokenHistorySync {
+ private let database: CKDatabase
+ private let directoryURL: URL
+ static let recordType = "CodexBarTokenTurn"
+ private static let currentSchema = 1
+
+ init(database: CKDatabase, directoryURL: URL) {
+ self.database = database
+ self.directoryURL = directoryURL
+ }
+
+ func recoveryBaseline(accountID: String?) -> CodexTokenHistoryBaseline? {
+ guard let accountID, let cache = try? load(), cache.accountID == accountID else { return nil }
+ return CodexTokenHistoryBaseline(salt: cache.salt, turns: cache.turns)
+ }
+
+ func snapshot(local: [CodexTokenTurn], accountID: String?) -> [String: CodexTokenUsage] {
+ guard let cache = try? load(), cache.accountID == accountID else {
+ return CodexTokenTurn.dailyUsage(local)
+ }
+ return CodexTokenTurn.dailyUsage(local.map { $0.pseudonymized(salt: cache.salt) } + Array(cache.turns.values))
+ }
+
+ func hasPendingUpdates(local: [CodexTokenTurn], accountID: String?) -> Bool {
+ let records = CodexTokenTurn.syncable(local)
+ guard let cache = try? load(), cache.accountID == accountID else { return !records.isEmpty }
+ return records.contains { turn in
+ let candidate = turn.pseudonymized(salt: cache.salt)
+ guard let remote = cache.turns[candidate.id] else { return true }
+ return remote.merging(candidate) != remote
+ }
+ }
+
+ func synchronize(local: [CodexTokenTurn], accountID: String, salt: Data, zoneID: CKRecordZone.ID) async throws {
+ // 整轮同步共用非阻塞锁, 防止另一个进程用较早的快照覆盖游标, 界面读取不等待网络
+ guard let lock = try CodexTokenFileStorage.acquireLock(in: directoryURL, name: "sync.lock", nonblocking: true) else { return }
+ defer { CodexTokenFileStorage.releaseLock(lock) }
+ var cache = try load() ?? TokenSyncCache(accountID: accountID, salt: salt)
+ if cache.accountID != accountID || cache.salt != salt {
+ cache = TokenSyncCache(accountID: accountID, salt: salt)
+ }
+ do {
+ try await fetch(into: &cache, zoneID: zoneID)
+ } catch let error as CKError where error.code == .changeTokenExpired {
+ cache.cursor = nil
+ cache.turns = [:]
+ try await fetch(into: &cache, zoneID: zoneID)
+ }
+ // 先落盘拉取结果, 上传失败时也能展示已经读取的其他设备贡献
+ try save(cache)
+ try await upload(local: local, cache: &cache, zoneID: zoneID)
+ try await prune(cache: &cache, zoneID: zoneID)
+ try save(cache)
+ }
+
+ private func fetch(into cache: inout TokenSyncCache, zoneID: CKRecordZone.ID) async throws {
+ var token = try cache.cursor.flatMap {
+ try NSKeyedUnarchiver.unarchivedObject(ofClass: CKServerChangeToken.self, from: $0)
+ }
+ var more = true
+ while more {
+ try Task.checkCancellation()
+ let result = try await database.recordZoneChanges(inZoneWith: zoneID, since: token, desiredKeys: nil, resultsLimit: 200)
+ for modification in result.modificationResultsByID.values {
+ if let turn = try Self.turn(from: modification.get().record) {
+ cache.turns[turn.id] = turn
+ }
+ }
+ for deletion in result.deletions where deletion.recordType == Self.recordType {
+ cache.turns.removeValue(forKey: deletion.recordID.recordName)
+ }
+ token = result.changeToken
+ more = result.moreComing
+ }
+ cache.cursor = try token.map { try NSKeyedArchiver.archivedData(withRootObject: $0, requiringSecureCoding: true) }
+ }
+
+ private func upload(local: [CodexTokenTurn], cache: inout TokenSyncCache, zoneID: CKRecordZone.ID) async throws {
+ let pending = CodexTokenTurn.syncable(local).map { $0.pseudonymized(salt: cache.salt) }
+ .filter { candidate in
+ guard let remote = cache.turns[candidate.id] else { return true }
+ return remote.merging(candidate) != remote
+ }
+ .sorted { $0.updatedAt > $1.updatedAt }
+ let deadline = Date().addingTimeInterval(20)
+ for offset in stride(from: 0, to: pending.count, by: 25) {
+ try Task.checkCancellation()
+ guard Date() < deadline else { break }
+ let batch = Array(pending[offset ..< min(offset + 25, pending.count)])
+ let ids = batch.map { Self.recordID($0.id, zoneID: zoneID) }
+ let existing = try await database.records(for: ids)
+ var saving: [CKRecord] = []
+ for candidate in batch {
+ let id = Self.recordID(candidate.id, zoneID: zoneID)
+ let record = try fetchedRecord(existing[id])
+ ?? CKRecord(recordType: Self.recordType, recordID: id)
+ let remote = Self.turn(from: record)
+ let merged = remote?.merging(candidate) ?? candidate
+ if remote == merged {
+ cache.turns[merged.id] = merged
+ continue
+ }
+ Self.apply(merged, to: record)
+ saving.append(record)
+ }
+ if saving.isEmpty {
+ continue
+ }
+ let result = try await database.modifyRecords(saving: saving, deleting: [], savePolicy: .ifServerRecordUnchanged, atomically: false)
+ var failure: (any Error)?
+ for record in saving {
+ switch result.saveResults[record.recordID] {
+ case let .success(saved):
+ if let turn = Self.turn(from: saved) {
+ cache.turns[turn.id] = turn
+ }
+ case let .failure(error): failure = error
+ case nil: failure = TokenHistorySyncError.missingRecordResult
+ }
+ }
+ try save(cache)
+ // 冲突不会使用覆盖写入, 下一轮重新获取服务端累计值后合并
+ if let failure {
+ throw failure
+ }
+ }
+ }
+
+ private func fetchedRecord(_ result: Result<CKRecord, any Error>?) throws -> CKRecord? {
+ switch result {
+ case let .success(record): record
+ case let .failure(error as CKError) where error.code == .unknownItem: nil
+ case let .failure(error): throw error
+ case nil: throw TokenHistorySyncError.missingRecordResult
+ }
+ }
+
+ private func prune(cache: inout TokenSyncCache, zoneID: CKRecordZone.ID) async throws {
+ let cutoff = WorkflowStorage.retentionCutoffDate()
+ let requiredRoots = Set(cache.turns.values.filter { $0.updatedAt >= cutoff }.map(\.rootID))
+ let expired = cache.turns.values.filter {
+ $0.updatedAt < cutoff && !requiredRoots.contains($0.id)
+ }.prefix(200)
+ let ids = expired.map { Self.recordID($0.id, zoneID: zoneID) }
+ guard !ids.isEmpty else { return }
+ let result = try await database.modifyRecords(saving: [], deleting: ids, atomically: false)
+ for id in ids {
+ guard let deletion = result.deleteResults[id] else { throw TokenHistorySyncError.missingRecordResult }
+ do { try deletion.get() } catch let error as CKError where error.code == .unknownItem {}
+ cache.turns.removeValue(forKey: id.recordName)
+ }
+ }
+
+ private func load() throws -> TokenSyncCache? {
+ try CodexTokenFileStorage.withLock(in: directoryURL) {
+ let cache = try CodexTokenFileStorage.load(TokenSyncCache.self, from: directoryURL.appendingPathComponent("cache.json"))
+ guard cache == nil || cache?.schema == TokenSyncCache.currentSchema else { throw CocoaError(.fileReadCorruptFile) }
+ return cache
+ }
+ }
+
+ private func save(_ cache: TokenSyncCache) throws {
+ try CodexTokenFileStorage.withLock(in: directoryURL) {
+ try CodexTokenFileStorage.save(cache, to: directoryURL.appendingPathComponent("cache.json"))
+ }
+ }
+
+ static func recordID(_ id: String, zoneID: CKRecordZone.ID) -> CKRecord.ID {
+ CKRecord.ID(recordName: id, zoneID: zoneID)
+ }
+
+ static func apply(_ turn: CodexTokenTurn, to record: CKRecord) {
+ record["schemaVersion"] = currentSchema as CKRecordValue
+ record["rootID"] = turn.rootID as CKRecordValue
+ record["startedAt"] = turn.startedAt as CKRecordValue?
+ record["observedAt"] = turn.updatedAt as CKRecordValue
+ record["rebuiltAt"] = turn.rebuiltAt as CKRecordValue?
+ record["usage"] = turn.usage.flatMap { try? JSONLines.stableEncoder.encode($0) } as CKRecordValue?
+ }
+
+ static func turn(from record: CKRecord) -> CodexTokenTurn? {
+ guard record.recordType == recordType, (record["schemaVersion"] as? NSNumber)?.intValue == currentSchema,
+ let rootID = record["rootID"] as? String,
+ let updatedAt = record["observedAt"] as? Date else { return nil }
+ let id = record.recordID.recordName
+ guard isHash(id), isHash(rootID) else { return nil }
+ var usage: CodexTokenUsage?
+ if let value = record["usage"] {
+ guard let data = value as? Data, let decoded = try? JSONDecoder().decode(CodexTokenUsage.self, from: data), decoded.isValid else { return nil }
+ usage = decoded
+ }
+ if let rebuiltAt = record["rebuiltAt"], !(rebuiltAt is Date) {
+ return nil
+ }
+ return CodexTokenTurn(
+ id: id, rootID: rootID, startedAt: record["startedAt"] as? Date, updatedAt: updatedAt,
+ usage: usage, rebuiltAt: record["rebuiltAt"] as? Date
+ )
+ }
+
+ private static func isHash(_ text: String) -> Bool {
+ text.count == 64 && text.utf8.allSatisfy { (48 ... 57).contains($0) || (97 ... 102).contains($0) }
+ }
+}
+
+private nonisolated struct TokenSyncCache: Codable {
+ static let currentSchema = 1
+ var schema = currentSchema
+ let accountID: String
+ let salt: Data
+ var turns: [String: CodexTokenTurn] = [:]
+ var cursor: Data?
+}
+
+private nonisolated enum TokenHistorySyncError: Error {
+ case missingRecordResult
+}
diff --git a/CodexBar/Services/Workflow/WorkflowService.swift b/CodexBar/Services/Workflow/WorkflowService.swift
index 1ca4d9c..7cc7cd3 100644
--- a/CodexBar/Services/Workflow/WorkflowService.swift
+++ b/CodexBar/Services/Workflow/WorkflowService.swift
@@ -38,6 +38,7 @@ actor WorkflowService {
private let eventsDirectoryURL: URL
private let dailyLogURL: URL
private let syncService: WorkflowSyncService
+ private let tokenHistory: CodexTokenHistoryStore
/// 上次归一化时 daily.jsonl 的 stat 与当天日期键
private var lastNormalizedDailyLog: WorkflowDailyLogStamp?
/// 上一条维护日志之后连续空转的轮数, 记出去就清零
@@ -47,11 +48,13 @@ actor WorkflowService {
init(
eventsDirectoryURL: URL = WorkflowStorage.eventsDirectoryURL(),
dailyLogURL: URL = WorkflowStorage.dailyURL(),
- syncService: WorkflowSyncService = WorkflowSyncService()
+ syncService: WorkflowSyncService = WorkflowSyncService(),
+ tokenHistory: CodexTokenHistoryStore = CodexTokenHistoryStore()
) {
self.eventsDirectoryURL = eventsDirectoryURL
self.dailyLogURL = dailyLogURL
self.syncService = syncService
+ self.tokenHistory = tokenHistory
}
// MARK: - 快照读取
@@ -81,23 +84,34 @@ actor WorkflowService {
private func makeSnapshot(
localAggregates: [WorkflowDailyAggregate],
synchronize: Bool,
- trigger: LogTrigger
+ trigger: LogTrigger,
+ localTokenTurns: [CodexTokenTurn]? = nil
) async -> WorkflowSnapshot {
- let syncSnapshot: WorkflowSyncSnapshot = if synchronize {
- await syncService.synchronizeIfEnabled(localAggregates: localAggregates, trigger: trigger)
+ let tokenTurns: [CodexTokenTurn]
+ if let localTokenTurns {
+ tokenTurns = localTokenTurns
} else {
- await syncService.snapshotFromCacheIfEnabled()
+ do {
+ let baseline = await syncService.tokenRecoveryBaselineIfEnabled()
+ tokenTurns = try await tokenHistory.refresh(baseline: baseline)
+ } catch {
+ let error = error as NSError
+ AppLog.workflow.error("Token 历史读取失败: domain=\(error.domain, privacy: .public) code=\(error.code)")
+ tokenTurns = []
+ }
}
-
- guard !localAggregates.isEmpty || !syncSnapshot.records.isEmpty else {
- return .empty
+ let syncSnapshot: WorkflowSyncSnapshot = if synchronize {
+ await syncService.synchronizeIfEnabled(localAggregates: localAggregates, localTokenTurns: tokenTurns, trigger: trigger)
+ } else {
+ await syncService.snapshotFromCacheIfEnabled(localTokenTurns: tokenTurns)
}
-
- return WorkflowSnapshot(
+ var snapshot = WorkflowSnapshot(
localAggregates: localAggregates,
syncedRecords: syncSnapshot.records,
currentDeviceId: syncSnapshot.currentDeviceId
)
+ snapshot.tokenUsageByDate = syncSnapshot.tokenUsageByDate ?? CodexTokenTurn.dailyUsage(tokenTurns)
+ return snapshot
}
/// 以指定日期范围内的本机原始事件为权威来源重建, 并安排替换当前设备的同日云端贡献
@@ -116,7 +130,8 @@ actor WorkflowService {
var rebuildResults = [WorkflowMaintenanceResult]()
var failedDateKeys = [String]()
var firstFailure: Error?
- for dateKey in normalizedDateKeys {
+ let hookDateKeys = normalizedDateKeys.filter { WorkflowStorage.fileSize(at: eventLogURL(for: $0)) > 0 }
+ for dateKey in hookDateKeys {
do {
try rebuildResults.append(rebuildLocalData(for: dateKey))
} catch {
@@ -134,12 +149,23 @@ actor WorkflowService {
}
}
+ var tokenResult = CodexTokenRebuildResult.empty
+ var didFailTokenRebuild = false
+ do {
+ tokenResult = try await tokenHistory.rebuild(for: normalizedDateKeys)
+ } catch {
+ didFailTokenRebuild = true
+ firstFailure = firstFailure ?? error
+ let error = error as NSError
+ AppLog.workflow.error("Token 重建失败: domain=\(error.domain, privacy: .public) code=\(error.code)")
+ }
+
// 成功与失败的日期都要登记: 失败的日期稍后会被自动重建并推进 sourceGeneration,
// 届时会上传到新的 record ID, 不清理旧记录会在云端留下同日重复的贡献
// 全部失败时同样要登记, 它们一样已被标脏
var didFailReplacementMarking = false
do {
- try await syncService.markReplacementNeeded(for: normalizedDateKeys)
+ try await syncService.markReplacementNeeded(for: hookDateKeys)
} catch {
let details = LogFields.joined(
"stage=replacementMarking",
@@ -151,28 +177,34 @@ actor WorkflowService {
}
// 一天都没成功才算整体失败, 并保留首个真实原因而非笼统报「数据发生变化」
- guard !rebuildResults.isEmpty else {
+ guard !rebuildResults.isEmpty || !tokenResult.dateKeys.isEmpty else {
throw firstFailure ?? WorkflowDataRebuildError.sourceUnavailable
}
// 重建只由设置页的用户操作发起
+ let localTurns = await (try? tokenHistory.currentTurns()) ?? []
let snapshot = await makeSnapshot(
localAggregates: loadDailyAggregates() ?? [],
synchronize: synchronize,
- trigger: .manual
+ trigger: .manual,
+ localTokenTurns: localTurns
)
+ let tokenSyncPending = await syncService.hasPendingTokenUpdates(local: localTurns)
let summary = await WorkflowDataRebuildSummary(
- rebuiltDateCount: rebuildResults.count,
+ rebuiltDateCount: Set(rebuildResults.map(\.dateKey)).union(tokenResult.dateKeys).count,
eventCount: rebuildResults.reduce(0) { $0 + ($1.aggregate.eventCount ?? 0) },
corruptLineCount: rebuildResults.reduce(0) { $0 + $1.corrupt },
- isSyncReplacementPending: syncService.hasPendingReplacement(for: normalizedDateKeys),
+ isSyncReplacementPending: syncService.hasPendingReplacement(for: hookDateKeys) || tokenSyncPending,
failedDateKeys: failedDateKeys,
- didFailSyncReplacementMarking: didFailReplacementMarking
+ didFailSyncReplacementMarking: didFailReplacementMarking,
+ tokenTurnCount: tokenResult.turnCount,
+ didFailTokenRebuild: didFailTokenRebuild
)
let elapsed = duration.elapsed
let details = LogFields.joined(
"dates=\(summary.rebuiltDateCount)",
"events=\(summary.eventCount)",
+ "tokenTurns=\(summary.tokenTurnCount)",
"corruptLines=\(summary.corruptLineCount)",
"failedDates=\(failedDateKeys.count)",
"elapsed=\(elapsed)"
@@ -1445,6 +1477,8 @@ nonisolated struct WorkflowDataRebuildSummary: Equatable, Sendable {
/// 未完成的日期, 已标脏并会由常规维护自动重建
let failedDateKeys: [String]
let didFailSyncReplacementMarking: Bool
+ let tokenTurnCount: Int
+ let didFailTokenRebuild: Bool
}
private nonisolated struct WorkflowDataRebuildOutcome {
diff --git a/CodexBar/Services/Workflow/WorkflowSyncScheduler.swift b/CodexBar/Services/Workflow/WorkflowSyncScheduler.swift
index 244546f..c5abb50 100644
--- a/CodexBar/Services/Workflow/WorkflowSyncScheduler.swift
+++ b/CodexBar/Services/Workflow/WorkflowSyncScheduler.swift
@@ -182,7 +182,7 @@ final class WorkflowSyncScheduler {
pendingRebuild = nil
let synchronize = syncActivation().isActive
- Task { @MainActor [weak self] in
+ Task(priority: .utility) { @MainActor [weak self] in
guard let self else {
return
}
diff --git a/CodexBar/Services/Workflow/WorkflowSyncService.swift b/CodexBar/Services/Workflow/WorkflowSyncService.swift
index e186953..9f672d5 100644
--- a/CodexBar/Services/Workflow/WorkflowSyncService.swift
+++ b/CodexBar/Services/Workflow/WorkflowSyncService.swift
@@ -19,6 +19,7 @@ private nonisolated enum WorkflowSyncStage: String {
case device
case fetch
case upload
+ case tokens
case prune
}
@@ -27,6 +28,7 @@ actor WorkflowSyncService {
private let database: CKDatabase
private let fileManager: FileManager
private let directoryURL: URL
+ private let tokenHistorySync: CodexTokenHistorySync
// zone 存在性和 account salt 首次确认后跨轮缓存, 省掉每轮同步的两次固定往返
// 任一轮同步失败时作废: iCloud 账号切换必然伴随请求报错, 下一轮会重新确认
@@ -41,17 +43,21 @@ actor WorkflowSyncService {
database = container.privateCloudDatabase
self.fileManager = fileManager
self.directoryURL = directoryURL
+ tokenHistorySync = CodexTokenHistorySync(
+ database: container.privateCloudDatabase,
+ directoryURL: directoryURL.appendingPathComponent("Tokens")
+ )
}
// MARK: - 同步入口
- func snapshotFromCacheIfEnabled() -> WorkflowSyncSnapshot {
+ func snapshotFromCacheIfEnabled(localTokenTurns: [CodexTokenTurn] = []) async -> WorkflowSyncSnapshot {
guard WorkflowSyncSettings.isEnabled() else {
return .disabled
}
let state = loadState()
- return snapshot(from: state)
+ return await snapshot(from: state, localTokenTurns: localTokenTurns)
}
/// 显式重建后, 将所选日期标记为当前设备云端贡献的权威替换来源
@@ -75,8 +81,18 @@ actor WorkflowSyncService {
!Set(loadState().replacementDates).isDisjoint(with: dates)
}
+ func tokenRecoveryBaselineIfEnabled() async -> CodexTokenHistoryBaseline? {
+ guard WorkflowSyncSettings.isEnabled() else { return nil }
+ return await tokenHistorySync.recoveryBaseline(accountID: loadState().deviceId)
+ }
+
+ func hasPendingTokenUpdates(local: [CodexTokenTurn]) async -> Bool {
+ await tokenHistorySync.hasPendingUpdates(local: local, accountID: loadState().deviceId)
+ }
+
func synchronizeIfEnabled(
localAggregates: [WorkflowDailyAggregate],
+ localTokenTurns: [CodexTokenTurn] = [],
trigger: LogTrigger
) async -> WorkflowSyncSnapshot {
guard WorkflowSyncSettings.isEnabled() else {
@@ -127,6 +143,10 @@ actor WorkflowSyncService {
)
try await refreshCacheFromRemote()
+ stage = .tokens
+ try await tokenHistorySync.synchronize(
+ local: localTokenTurns, accountID: deviceId, salt: accountSalt(), zoneID: syncZoneID
+ )
stage = .prune
let deletedCount = try await pruneCurrentDeviceRecordsIfNeeded(
deviceId: deviceId,
@@ -160,7 +180,7 @@ actor WorkflowSyncService {
}
let latestState = loadState()
- return snapshot(from: latestState)
+ return await snapshot(from: latestState, localTokenTurns: localTokenTurns)
}
private func logSyncSkipped(trigger: LogTrigger) {
@@ -265,7 +285,7 @@ actor WorkflowSyncService {
}
}
- private func snapshot(from state: WorkflowSyncState) -> WorkflowSyncSnapshot {
+ private func snapshot(from state: WorkflowSyncState, localTokenTurns: [CodexTokenTurn]) async -> WorkflowSyncSnapshot {
guard let deviceId = state.deviceId else {
return .disabled
}
@@ -275,9 +295,10 @@ actor WorkflowSyncService {
record.deviceId != deviceId || !replacementDates.contains(record.date)
}
- return WorkflowSyncSnapshot(
+ return await WorkflowSyncSnapshot(
records: records,
- currentDeviceId: deviceId
+ currentDeviceId: deviceId,
+ tokenUsageByDate: tokenHistorySync.snapshot(local: localTokenTurns, accountID: deviceId)
)
}
}
@@ -1357,6 +1378,7 @@ private extension WorkflowSyncService {
nonisolated struct WorkflowSyncSnapshot: Equatable {
let records: [WorkflowSyncedDailyRecord]
let currentDeviceId: String?
+ var tokenUsageByDate: [String: CodexTokenUsage]?
static let disabled = WorkflowSyncSnapshot(records: [], currentDeviceId: nil)
}
diff --git a/CodexBar/Views/Menu/CodexActivityCard.swift b/CodexBar/Views/Menu/CodexActivityCard.swift
index 5a38ea4..57965c5 100644
--- a/CodexBar/Views/Menu/CodexActivityCard.swift
+++ b/CodexBar/Views/Menu/CodexActivityCard.swift
@@ -1,6 +1,6 @@
import SwiftUI
-/// Hook 开启时常驻的固定高度活动摘要, 使用菜单面板共享的逐秒时间
+/// Hook 开启时常驻的活动摘要, 使用菜单面板共享的逐秒时间
/// 在卡片内部观察 activityMonitor 与逐秒时间, 让 1Hz 失效范围只覆盖本卡片而不是整个菜单树
/// keepAliveController 同理, 它的 helperStatus 等字段与菜单树无关却会无条件发信号
struct CodexActivityCard: View {
@@ -62,7 +62,42 @@ struct CodexActivityCard: View {
private func card(now: Date) -> some View {
let content = content(at: now)
- return HStack(spacing: 10) {
+ return VStack(alignment: .leading, spacing: 8) {
+ statusRow(content)
+ if let usage = content.tokenUsage {
+ VStack(spacing: 8) {
+ LiquidGlassDivider()
+ tokenUsageMetrics(usage)
+ }
+ .transition(.opacity.combined(with: .offset(y: 6)))
+ }
+ }
+ .animation(.codexStatus, value: showsKeepAliveBadge)
+ .animation(.codexStatus, value: content.isAnonymous)
+ // 任务数变化会让 +N 增删, 防睡眠徽标跟着横移; 两者一起纳入动画上下文才不会跳
+ .animation(.codexStatus, value: content.otherTaskCount)
+ .padding(.horizontal, MenuMetrics.panelPadding)
+ .frame(maxWidth: .infinity)
+ .frame(height: content.tokenUsage == nil ? Metrics.height : Metrics.usageHeight)
+ .clipped()
+ .activityStatusParticles(cornerRadius: MenuMetrics.panelCornerRadius)
+ .liquidGlassSurface(cornerRadius: MenuMetrics.panelCornerRadius)
+ .overlay {
+ RoundedRectangle(cornerRadius: MenuMetrics.panelCornerRadius, style: .continuous)
+ .strokeBorder(
+ isTaskCenterPresented
+ ? Color.accentColor.opacity(0.55)
+ : Color.primary.opacity(isHovered && snapshot.hasTaskCenterContent ? 0.14 : 0),
+ lineWidth: 1
+ )
+ .animation(.codexStatus, value: isHovered)
+ .animation(.codexStatus, value: isTaskCenterPresented)
+ }
+ .animation(.codexStatus, value: content.tokenUsage != nil)
+ }
+
+ private func statusRow(_ content: ActivityCardContent) -> some View {
+ HStack(spacing: 10) {
Image(systemName: content.symbolName)
.font(.system(size: 14, weight: .semibold))
.foregroundStyle(content.tint)
@@ -120,25 +155,40 @@ struct CodexActivityCard: View {
.help(String(localized: "activity.summary.other-task-count", defaultValue: "\(content.otherTaskCount, specifier: "%lld")"))
}
}
- .animation(.codexStatus, value: showsKeepAliveBadge)
- .animation(.codexStatus, value: content.isAnonymous)
- // 任务数变化会让 +N 增删, 防睡眠徽标跟着横移; 两者一起纳入动画上下文才不会跳
- .animation(.codexStatus, value: content.otherTaskCount)
- .padding(.horizontal, MenuMetrics.panelPadding)
- .frame(maxWidth: .infinity, minHeight: Metrics.height, maxHeight: Metrics.height)
- .activityStatusParticles(cornerRadius: MenuMetrics.panelCornerRadius)
- .liquidGlassSurface(cornerRadius: MenuMetrics.panelCornerRadius)
- .overlay {
- RoundedRectangle(cornerRadius: MenuMetrics.panelCornerRadius, style: .continuous)
- .strokeBorder(
- isTaskCenterPresented
- ? Color.accentColor.opacity(0.55)
- : Color.primary.opacity(isHovered && snapshot.hasTaskCenterContent ? 0.14 : 0),
- lineWidth: 1
- )
- .animation(.codexStatus, value: isHovered)
- .animation(.codexStatus, value: isTaskCenterPresented)
+ }
+
+ private func tokenUsageMetrics(_ usage: CodexTokenUsage) -> some View {
+ HStack(alignment: .top, spacing: 0) {
+ tokenMetric("activity.tokens.total", tokens: usage.totalTokens)
+ tokenMetric("activity.tokens.input", tokens: usage.inputTokens)
+ tokenMetric("activity.tokens.output", tokens: usage.outputTokens)
+ tokenMetric("activity.tokens.cached-read", tokens: usage.cachedInputTokens)
+ tokenMetric("activity.tokens.cache-write", tokens: usage.cacheWriteInputTokens)
+ VStack(spacing: 3) {
+ Text("activity.tokens.cache-hit-rate")
+ .font(.caption2)
+ .foregroundStyle(Color.codexSecondaryLabel)
+ .minimumScaleFactor(0.65)
+ Text(usage.cacheHitRate.map { $0.formatted(.percent.precision(.fractionLength(0 ... 1))) } ?? "—")
+ .font(.caption2.monospacedDigit().weight(.semibold))
+ .foregroundStyle(Color.codexLabel)
+ }
+ .frame(minWidth: 0, maxWidth: .infinity)
+ tokenMetric("activity.tokens.reasoning", tokens: usage.reasoningOutputTokens)
+ }
+ .lineLimit(1)
+ }
+
+ private func tokenMetric(_ title: LocalizedStringKey, tokens: Int64) -> some View {
+ VStack(spacing: 3) {
+ Text(title)
+ .font(.caption2)
+ .foregroundStyle(Color.codexSecondaryLabel)
+ .minimumScaleFactor(0.65)
+ TokenCountText(tokens: Int(tokens), font: .caption2.monospacedDigit().weight(.semibold))
+ .foregroundStyle(Color.codexLabel)
}
+ .frame(minWidth: 0, maxWidth: .infinity)
}
private func content(at now: Date) -> ActivityCardContent {
@@ -181,7 +231,8 @@ struct CodexActivityCard: View {
),
detail: details.joined(separator: " • "),
otherTaskCount: 0,
- isAnonymous: completion.isAnonymous
+ isAnonymous: completion.isAnonymous,
+ tokenUsage: completion.tokenUsage
)
case let .terminated(termination):
let details = CodexActivityDisplayFormat.historyDetailComponents(
@@ -199,7 +250,8 @@ struct CodexActivityCard: View {
),
detail: details.joined(separator: " • "),
otherTaskCount: 0,
- isAnonymous: termination.isAnonymous
+ isAnonymous: termination.isAnonymous,
+ tokenUsage: termination.tokenUsage
)
case .idle:
return ActivityCardContent(
@@ -234,7 +286,8 @@ struct CodexActivityCard: View {
),
detail: details.joined(separator: " • "),
otherTaskCount: otherTaskCount,
- isAnonymous: task.isAnonymous
+ isAnonymous: task.isAnonymous,
+ tokenUsage: task.tokenUsage
)
}
@@ -282,6 +335,7 @@ struct CodexActivityCard: View {
private enum Metrics {
static let height: CGFloat = 58
+ static let usageHeight: CGFloat = 108
}
}
@@ -310,6 +364,7 @@ private struct ActivityCardContent {
let detail: String?
let otherTaskCount: Int
let isAnonymous: Bool
+ var tokenUsage: CodexTokenUsage?
}
struct CodexActivityAnonymousIcon: View {
diff --git a/CodexBar/Views/Menu/CodexActivityCenterView.swift b/CodexBar/Views/Menu/CodexActivityCenterView.swift
index aab0546..01a0bc4 100644
--- a/CodexBar/Views/Menu/CodexActivityCenterView.swift
+++ b/CodexBar/Views/Menu/CodexActivityCenterView.swift
@@ -278,7 +278,8 @@ struct CodexActivityCenterView: View {
completion.completedAt,
now: now
)
- )
+ ),
+ tokenUsage: completion.tokenUsage
)
}
@@ -296,7 +297,8 @@ struct CodexActivityCenterView: View {
termination.terminatedAt,
now: now
)
- )
+ ),
+ tokenUsage: termination.tokenUsage
)
}
@@ -308,6 +310,7 @@ struct CodexActivityCenterView: View {
effort: String?,
isAnonymous: Bool,
detail: String,
+ tokenUsage: CodexTokenUsage? = nil,
effect: CodexActivityStatusText.Effect = .none
) -> some View {
HStack(alignment: .top, spacing: 9) {
@@ -328,13 +331,19 @@ struct CodexActivityCenterView: View {
effort: effort
)
- CodexActivityStatusText(
- text: detail,
- tint: tint,
- effect: presentationState.isPresented
- && mainPanelSettings.areEntranceAnimationsEnabled
- ? effect : .none
- )
+ HStack(spacing: 6) {
+ CodexActivityStatusText(
+ text: detail,
+ tint: tint,
+ effect: presentationState.isPresented
+ && mainPanelSettings.areEntranceAnimationsEnabled
+ ? effect : .none
+ )
+ if let tokenUsage {
+ Spacer(minLength: 0)
+ CodexTokenUsageText(usage: tokenUsage)
+ }
+ }
}
}
.frame(maxWidth: .infinity, alignment: .leading)
diff --git a/CodexBar/Views/Menu/TokenCountText.swift b/CodexBar/Views/Menu/TokenCountText.swift
index f16a964..2569920 100644
--- a/CodexBar/Views/Menu/TokenCountText.swift
+++ b/CodexBar/Views/Menu/TokenCountText.swift
@@ -35,8 +35,22 @@ struct TokenCountText: View {
}
}
+struct CodexTokenUsageText: View {
+ let usage: CodexTokenUsage
+
+ var body: some View {
+ HStack(spacing: 3) {
+ TokenCountText(tokens: Int(usage.totalTokens), font: .caption2.monospacedDigit())
+ Text(verbatim: "tokens")
+ .font(.caption2)
+ }
+ .foregroundStyle(.secondary)
+ .fixedSize()
+ }
+}
+
/// 1K 以下显示完整整数, 1K 起使用 K/M/B
-private enum TokenCountFormatter {
+enum TokenCountFormatter {
static func parts(from tokens: Int) -> TokenCountParts {
switch tokens {
case 1000000000...:
diff --git a/CodexBar/Views/Menu/UsageHeatmap.swift b/CodexBar/Views/Menu/UsageHeatmap.swift
index 35fad77..b8d84d3 100644
--- a/CodexBar/Views/Menu/UsageHeatmap.swift
+++ b/CodexBar/Views/Menu/UsageHeatmap.swift
@@ -593,7 +593,7 @@ struct UsageHeatmapDayDetailView: View {
static func panelSize(showsWorkflow: Bool) -> CGSize {
CGSize(
- width: Metrics.panelWidth,
+ width: showsWorkflow ? Metrics.workflowPanelWidth : Metrics.panelWidth,
height: showsWorkflow ? Metrics.workflowPanelHeight : Metrics.tokenPanelHeight
)
}
@@ -627,52 +627,93 @@ struct UsageHeatmapDayDetailView: View {
LiquidGlassDivider()
.opacity(0.72)
- VStack(alignment: .leading, spacing: Metrics.metricSpacing) {
- tokenIntensityMetricRow
- mostUsedModelMetricRow
+ tokenIntensityMetricRow
- ForEach(workflowMetricRows) { row in
- metricRow(row)
+ HStack(alignment: .top, spacing: Metrics.columnSpacing) {
+ VStack(alignment: .leading, spacing: Metrics.sectionSpacing) {
+ columnTitle("usage.heatmap.activity-metrics")
+ Grid(alignment: .leading, horizontalSpacing: Metrics.metricRowSpacing, verticalSpacing: Metrics.metricSpacing) {
+ mostUsedModelMetricRow
+ ForEach(workflowMetricRows) { row in
+ metricRow(row)
+ }
+ }
+ }
+ .frame(minWidth: 0, maxWidth: .infinity)
+
+ Rectangle()
+ .fill(Color.primary.opacity(0.08))
+ .frame(width: 1)
+
+ VStack(alignment: .leading, spacing: Metrics.sectionSpacing) {
+ columnTitle("usage.heatmap.token-metrics")
+ dailyTokenMetrics
}
+ .frame(minWidth: 0, maxWidth: .infinity)
}
+ .frame(height: Metrics.columnHeight)
}
}
- private var tokenOnlyContent: some View {
- VStack(alignment: .leading, spacing: Metrics.sectionSpacing) {
- header
-
- LiquidGlassDivider()
- .opacity(0.62)
+ private func columnTitle(_ title: LocalizedStringKey) -> some View {
+ Text(title)
+ .font(.caption2.weight(.semibold))
+ .foregroundStyle(Color.codexSecondaryLabel)
+ .frame(height: Metrics.metricRowHeight)
+ }
- tokenOnlyFooter
+ private var dailyTokenMetrics: some View {
+ let usage = context.day.tokenUsage
+ let cacheHitRate = usage?.cacheHitRate ?? 0
+ return Grid(alignment: .leading, horizontalSpacing: Metrics.metricRowSpacing, verticalSpacing: Metrics.metricSpacing) {
+ dailyTokenRow("activity.tokens.total", tokens: usage?.totalTokens, tint: .blue)
+ dailyTokenRow("activity.tokens.input", tokens: usage?.inputTokens, tint: .indigo)
+ dailyTokenRow("activity.tokens.output", tokens: usage?.outputTokens, tint: .orange)
+ dailyTokenRow("activity.tokens.cached-read", tokens: usage?.cachedInputTokens, tint: .green)
+ dailyTokenRow("activity.tokens.cache-write", tokens: usage?.cacheWriteInputTokens, tint: .purple)
+ metricRowLayout {
+ metricDot(tint: .teal)
+ Text("activity.tokens.cache-hit-rate")
+ .foregroundStyle(.secondary)
+ .fixedSize(horizontal: true, vertical: false)
+ .frame(height: Metrics.metricRowHeight)
+ fittingMetricValue(
+ cacheHitRate.formatted(.percent.precision(.fractionLength(0 ... 1))),
+ comparison: cacheHitRate
+ )
+ }
+ dailyTokenRow("activity.tokens.reasoning", tokens: usage?.reasoningOutputTokens, tint: .cyan)
}
}
- private var tokenOnlyFooter: some View {
- metricRowLayout {
- tokenIntensityDot
- Text("usage.heatmap.intensity")
+ private func dailyTokenRow(_ title: LocalizedStringKey, tokens: Int64?, tint: Color) -> some View {
+ let count = tokens ?? 0
+ return metricRowLayout {
+ metricDot(tint: tint)
+ Text(title)
.foregroundStyle(.secondary)
+ .lineLimit(1)
+ .fixedSize(horizontal: true, vertical: false)
+ .frame(height: Metrics.metricRowHeight)
+ fittingMetricValue(TokenCountFormatter.parts(from: Int(count)).text, comparison: Double(count))
+ }
+ }
- Spacer(minLength: 8)
+ private var tokenOnlyContent: some View {
+ VStack(alignment: .leading, spacing: Metrics.sectionSpacing) {
+ header
- tokenIntensityStrip
- .frame(width: Metrics.tokenIntensityStripWidth)
+ LiquidGlassDivider()
+ .opacity(0.62)
+
+ tokenIntensityMetricRow
}
}
private var tokenIntensityMetricRow: some View {
- metricRowLayout {
- tokenIntensityDot
- Text("usage.heatmap.intensity")
- .foregroundStyle(.secondary)
- .frame(width: Metrics.metricLabelWidth, alignment: .leading)
-
- tokenIntensityStrip
- .frame(width: Metrics.tokenIntensityStripWidth)
- .frame(maxWidth: .infinity, alignment: .trailing)
- }
+ tokenIntensityStrip
+ .frame(maxWidth: .infinity)
+ .frame(height: Metrics.metricRowHeight)
}
private var mostUsedModelMetricRow: some View {
@@ -680,20 +721,16 @@ struct UsageHeatmapDayDetailView: View {
metricDot(tint: .cyan)
Text("usage.heatmap.top-model")
.foregroundStyle(.secondary)
- .frame(width: Metrics.metricLabelWidth, alignment: .leading)
+ .fixedSize(horizontal: true, vertical: false)
+ .frame(height: Metrics.metricRowHeight)
fittingModelValue(context.day.workflow.mostUsedModel ?? "--")
}
}
- private var tokenIntensityDot: some View {
- metricDot(tint: .blue, darkOpacity: 0.88, lightOpacity: 0.76)
- }
-
private func metricRowLayout(@ViewBuilder content: () -> some View) -> some View {
- HStack(spacing: Metrics.metricRowSpacing, content: content)
+ GridRow(content: content)
.font(.system(size: Metrics.workflowFontSize))
- .frame(height: Metrics.metricRowHeight)
}
private func metricDot(tint: Color, darkOpacity: Double = 0.86, lightOpacity: Double = 0.72) -> some View {
@@ -802,7 +839,8 @@ struct UsageHeatmapDayDetailView: View {
return Color.blue.opacity(colorScheme == .dark ? 0.14 : 0.10)
}
- let opacity = colorScheme == .dark ? 0.42 + Double(index) * 0.10 : 0.34 + Double(index) * 0.09
+ let position = Double(index) / Double(Metrics.tokenIntensitySegmentCount - 1)
+ let opacity = colorScheme == .dark ? 0.42 + position * 0.40 : 0.34 + position * 0.36
return Color.blue.opacity(min(opacity, 0.88))
}
@@ -811,7 +849,8 @@ struct UsageHeatmapDayDetailView: View {
metricDot(tint: row.tint)
Text(row.label)
.foregroundStyle(.secondary)
- .frame(width: Metrics.metricLabelWidth, alignment: .leading)
+ .fixedSize(horizontal: true, vertical: false)
+ .frame(height: Metrics.metricRowHeight)
fittingMetricValue("\(row.value)", comparison: Double(row.value))
}
@@ -825,7 +864,10 @@ struct UsageHeatmapDayDetailView: View {
}
private func fittingModelValue(_ value: String) -> some View {
- fittingValueContent(value)
+ metricValueText(value)
+ .minimumScaleFactor(Metrics.metricValueMinimumScale)
+ .allowsTightening(true)
+ .contentTransition(.numericText())
.layoutPriority(1)
.frame(maxWidth: .infinity, alignment: .trailing)
}
@@ -861,7 +903,10 @@ struct UsageHeatmapDayDetailView: View {
private enum Metrics {
static let panelWidth: CGFloat = 212
- static let workflowPanelHeight: CGFloat = 208
+ static let workflowPanelWidth: CGFloat = 360
+ static let workflowPanelHeight: CGFloat = 232
+ static let columnSpacing: CGFloat = 12
+ static let columnHeight: CGFloat = 150
static let tokenPanelHeight: CGFloat = 84
static let sectionSpacing: CGFloat = 8
static let horizontalPadding: CGFloat = 12
@@ -873,12 +918,10 @@ struct UsageHeatmapDayDetailView: View {
static let metricRowSpacing: CGFloat = 6
static let metricDotSize: CGFloat = 5
static let metricRowHeight: CGFloat = 14
- static let metricLabelWidth: CGFloat = 72
static let metricValueMinimumScale: CGFloat = 0.60
static let workflowFontSize: CGFloat = 11
- static let tokenIntensitySegmentCount = 5
+ static let tokenIntensitySegmentCount = 10
static let tokenIntensitySegmentSpacing: CGFloat = 3
- static let tokenIntensityStripWidth: CGFloat = 74
static let tokenIntensityStripHeight: CGFloat = 5
static let statusAnimation = Animation.codexStatus
}
diff --git a/CodexBar/Views/Settings/AppSettingsView.swift b/CodexBar/Views/Settings/AppSettingsView.swift
index 543a81e..18fd581 100644
--- a/CodexBar/Views/Settings/AppSettingsView.swift
+++ b/CodexBar/Views/Settings/AppSettingsView.swift
@@ -755,6 +755,9 @@ private extension AppSettingsView {
}
var rebuildCaption: RebuildStatus {
+ if isRebuildingWorkflowData {
+ return RebuildStatus(message: String(localized: "workflow.rebuild.status.running"), isError: false)
+ }
if let rebuildStatus {
return rebuildStatus
}
@@ -780,11 +783,18 @@ private extension AppSettingsView {
guard let selectedRebuildRange, selectedRebuildRange.isComplete else {
return []
}
- return rebuildableDates.filter(selectedRebuildRange.contains)
+ return selectedRebuildRange.dateKeys
}
func refreshRebuildableDates() {
- rebuildableDates = WorkflowStorage.rebuildableEventDateKeys()
+ Task {
+ let dates = await Task.detached(priority: .utility) {
+ let hookDates = WorkflowStorage.rebuildableEventDateKeys()
+ let tokenDates = await (try? CodexTokenHistoryStore().rebuildableDateKeys()) ?? []
+ return Set(hookDates + tokenDates).sorted()
+ }.value
+ rebuildableDates = dates
+ }
}
/// 防睡眠不在这里刷: 控制器自己订阅了 didBecomeActive, 窗口打开也走 refreshSettingsState
@@ -842,6 +852,10 @@ private extension AppSettingsView {
localized: "workflow.rebuild.summary.completed",
defaultValue: "\(summary.rebuiltDateCount, specifier: "%lld")\(summary.eventCount, specifier: "%lld")"
)
+ message += String(localized: "workflow.rebuild.summary.tokens", defaultValue: "\(summary.tokenTurnCount, specifier: "%lld")")
+ if summary.didFailTokenRebuild {
+ message += String(localized: "workflow.rebuild.summary.tokens-failed")
+ }
if summary.corruptLineCount > 0 {
message += String(localized: "workflow.rebuild.summary.skipped-invalid-events", defaultValue: "\(summary.corruptLineCount, specifier: "%lld")")
}
@@ -1346,66 +1360,6 @@ private struct RebuildDatePicker: View {
}
}
-private struct RebuildDateRange: Equatable {
- let startDateKey: String
- let endDateKey: String?
-
- static func starting(at dateKey: String) -> RebuildDateRange {
- RebuildDateRange(startDateKey: dateKey, endDateKey: nil)
- }
-
- var isComplete: Bool {
- endDateKey != nil
- }
-
- var dayCount: Int {
- guard let endDateKey,
- let startDate = CodexDateFormat.dayDate(from: startDateKey),
- let endDate = CodexDateFormat.dayDate(from: endDateKey) else {
- return 0
- }
-
- guard let dayDifference = CodexDateFormat.localGregorianCalendar.dateComponents(
- [.day],
- from: startDate,
- to: endDate
- ).day else {
- return 0
- }
- return dayDifference + 1
- }
-
- var displayText: String {
- guard let startDate = CodexDateFormat.dayDate(from: startDateKey) else {
- return startDateKey
- }
- let startText = CodexDateFormat.localDayDisplayString(from: startDate)
- guard let endDateKey else {
- return String(localized: "date-range.open-ended", defaultValue: "\(startText)")
- }
- guard startDateKey != endDateKey,
- let endDate = CodexDateFormat.dayDate(from: endDateKey) else {
- return startText
- }
- let endText = CodexDateFormat.localDayDisplayString(from: endDate)
- return String(localized: "date-range.closed", defaultValue: "\(startText)\(endText)")
- }
-
- func completing(with dateKey: String) -> RebuildDateRange {
- RebuildDateRange(
- startDateKey: min(startDateKey, dateKey),
- endDateKey: max(startDateKey, dateKey)
- )
- }
-
- func contains(_ dateKey: String) -> Bool {
- guard let endDateKey else {
- return false
- }
- return dateKey >= startDateKey && dateKey <= endDateKey
- }
-}
-
private struct RebuildStatus {
let message: String
let isError: Bool
diff --git a/CodexBar/Views/Settings/RebuildDateRange.swift b/CodexBar/Views/Settings/RebuildDateRange.swift
new file mode 100644
index 0000000..3d1d8a3
--- /dev/null
+++ b/CodexBar/Views/Settings/RebuildDateRange.swift
@@ -0,0 +1,69 @@
+import Foundation
+
+struct RebuildDateRange: Equatable {
+ let startDateKey: String
+ let endDateKey: String?
+
+ static func starting(at dateKey: String) -> RebuildDateRange {
+ RebuildDateRange(startDateKey: dateKey, endDateKey: nil)
+ }
+
+ var isComplete: Bool {
+ endDateKey != nil
+ }
+
+ var dayCount: Int {
+ guard let endDateKey,
+ let startDate = CodexDateFormat.dayDate(from: startDateKey),
+ let endDate = CodexDateFormat.dayDate(from: endDateKey) else {
+ return 0
+ }
+
+ guard let dayDifference = CodexDateFormat.localGregorianCalendar.dateComponents(
+ [.day],
+ from: startDate,
+ to: endDate
+ ).day else {
+ return 0
+ }
+ return dayDifference + 1
+ }
+
+ var dateKeys: [String] {
+ guard isComplete, dayCount > 0, let start = CodexDateFormat.dayDate(from: startDateKey) else { return [] }
+ return (0 ..< dayCount).compactMap { offset in
+ CodexDateFormat.localGregorianCalendar.date(byAdding: .day, value: offset, to: start)
+ .map(CodexDateFormat.dayString(from:))
+ }
+ }
+
+ var displayText: String {
+ guard let startDate = CodexDateFormat.dayDate(from: startDateKey) else {
+ return startDateKey
+ }
+ let startText = CodexDateFormat.localDayDisplayString(from: startDate)
+ guard let endDateKey else {
+ return String(localized: "date-range.open-ended", defaultValue: "\(startText)")
+ }
+ guard startDateKey != endDateKey,
+ let endDate = CodexDateFormat.dayDate(from: endDateKey) else {
+ return startText
+ }
+ let endText = CodexDateFormat.localDayDisplayString(from: endDate)
+ return String(localized: "date-range.closed", defaultValue: "\(startText)\(endText)")
+ }
+
+ func completing(with dateKey: String) -> RebuildDateRange {
+ RebuildDateRange(
+ startDateKey: min(startDateKey, dateKey),
+ endDateKey: max(startDateKey, dateKey)
+ )
+ }
+
+ func contains(_ dateKey: String) -> Bool {
+ guard let endDateKey else {
+ return false
+ }
+ return dateKey >= startDateKey && dateKey <= endDateKey
+ }
+}
diff --git a/CodexBar/Views/Shared/LiquidGlassStyle.swift b/CodexBar/Views/Shared/LiquidGlassStyle.swift
index 4afd2fc..e5631b2 100644
--- a/CodexBar/Views/Shared/LiquidGlassStyle.swift
+++ b/CodexBar/Views/Shared/LiquidGlassStyle.swift
@@ -1,3 +1,5 @@
+import AppKit
+import Combine
import SwiftUI
/// CodexBar 统一的短状态动画
@@ -103,23 +105,105 @@ private struct SidePanelChrome: ViewModifier {
}
}
-/// 分区之间的细分隔线, 与玻璃背景保持低对比
+/// 分区之间的细分隔线, 以银灰和冷白高光衬托玻璃背景
struct LiquidGlassDivider: View {
+ @Environment(\.colorScheme) private var colorScheme
+ @State private var isVisible = false
+
var body: some View {
+ TimelineView(.animation(minimumInterval: 1.0 / 30, paused: !isVisible)) { timeline in
+ let phase = timeline.date.timeIntervalSinceReferenceDate * .pi / 4
+ line(offset: sin(phase) * 0.28)
+ }
+ .mask {
+ LinearGradient(
+ stops: [
+ .init(color: .clear, location: 0),
+ .init(color: .white, location: 0.12),
+ .init(color: .white, location: 0.88),
+ .init(color: .clear, location: 1)
+ ],
+ startPoint: .leading,
+ endPoint: .trailing
+ )
+ }
+ .frame(height: 1)
+ .background {
+ LiquidGlassDividerVisibility { isVisible = $0 }
+ }
+ }
+
+ private func line(offset: Double) -> some View {
Rectangle()
.fill(
LinearGradient(
colors: [
.clear,
- .white.opacity(0.36),
- .primary.opacity(0.08),
+ Color(hex: 0x8799AE),
+ Color(hex: 0xE3EBF4),
+ Color(hex: 0xA9B9CB),
.clear
],
- startPoint: .leading,
- endPoint: .trailing
+ startPoint: UnitPoint(x: offset, y: 0.5),
+ endPoint: UnitPoint(x: 1 + offset, y: 0.5)
)
)
- .frame(height: 1)
+ .opacity(colorScheme == .dark ? 0.36 : 0.30)
+ }
+}
+
+/// 面板可能保留隐藏的 hosting view, 按窗口可见性暂停时间线, 不依赖动画偏好开关
+private struct LiquidGlassDividerVisibility: NSViewRepresentable {
+ let onChange: (Bool) -> Void
+
+ func makeNSView(context _: Context) -> VisibilityView {
+ let view = VisibilityView()
+ view.onChange = onChange
+ return view
+ }
+
+ func updateNSView(_ view: VisibilityView, context _: Context) {
+ view.onChange = onChange
+ view.updateVisibility()
+ }
+
+ final class VisibilityView: NSView {
+ var onChange: ((Bool) -> Void)?
+ private var reportedVisibility = false
+ private var visibilityObservation: AnyCancellable?
+
+ override func viewDidMoveToWindow() {
+ super.viewDidMoveToWindow()
+ visibilityObservation = nil
+ if let window {
+ visibilityObservation = NotificationCenter.default.publisher(for: NSWindow.didChangeOcclusionStateNotification, object: window)
+ .sink { [weak self] _ in
+ MainActor.assumeIsolated { self?.updateVisibility() }
+ }
+ }
+ updateVisibility()
+ }
+
+ override func viewDidHide() {
+ super.viewDidHide()
+ updateVisibility()
+ }
+
+ override func viewDidUnhide() {
+ super.viewDidUnhide()
+ updateVisibility()
+ }
+
+ override func hitTest(_: NSPoint) -> NSView? {
+ nil
+ }
+
+ func updateVisibility() {
+ let visible = window?.occlusionState.contains(.visible) == true && !isHiddenOrHasHiddenAncestor
+ guard visible != reportedVisibility else { return }
+ reportedVisibility = visible
+ Task { @MainActor [weak self] in self?.onChange?(visible) }
+ }
}
}
diff --git a/CodexBarTests/CodexActivityTokenUsageTests.swift b/CodexBarTests/CodexActivityTokenUsageTests.swift
new file mode 100644
index 0000000..c4a9f38
--- /dev/null
+++ b/CodexBarTests/CodexActivityTokenUsageTests.swift
@@ -0,0 +1,295 @@
+import Foundation
+import Testing
+
+struct CodexActivityTokenUsageTests {
+ @Test func cacheHitRateUsesAllInputAndIsUnavailableWithoutInput() {
+ let usage = CodexTokenUsage(
+ inputTokens: 1000, cachedInputTokens: 800, cacheWriteInputTokens: 100,
+ outputTokens: 200, reasoningOutputTokens: 50, totalTokens: 1200
+ )
+ #expect(usage.cacheHitRate == 0.8)
+ let outputOnly = CodexTokenUsage(
+ inputTokens: 0, cachedInputTokens: 0, cacheWriteInputTokens: 0,
+ outputTokens: 200, reasoningOutputTokens: 50, totalTokens: 200
+ )
+ #expect(outputOnly.cacheHitRate == nil)
+ }
+
+ @Test func rootAndMultipleChildTurnsAreSummedOnce() throws {
+ let root = reference("session-a", "turn-a")
+ let first = reference("child-a", "child-turn-a")
+ let second = reference("child-a", "child-turn-b")
+ let third = reference("child-b", "child-turn-c")
+ let request = request(root: root, children: [first, second, third, first])
+ let states = [state(root, input: 100), state(first, input: 200), state(second, input: 300), state(third, input: 400)]
+ let usage = try #require(request.usage(from: states))
+ #expect(usage.inputTokens == 1000)
+ #expect(usage.outputTokens == 40)
+ #expect(usage.totalTokens == 1040)
+ #expect(usage.cachedInputTokens == 80)
+ }
+
+ @Test(arguments: ["missing", "unavailable", "other-root", "other-session", "running-child", "missing-usage"])
+ func incompleteOrUnrelatedChildPreventsPartialTotal(scenario: String) {
+ let root = reference("session-a", "turn-a")
+ let child = reference("child-a", "child-turn")
+ let request = request(root: root, children: [child])
+ var childState = state(child)
+ switch scenario {
+ case "unavailable": childState.readStatus = .unavailable
+ case "other-root": childState.rootTurnId = "other-root"
+ case "other-session": childState.rootSessionId = "other-session"
+ case "missing-usage": childState.tokenUsage = nil
+ case "running-child": childState = state(child, terminal: nil)
+ default: break
+ }
+ let states = scenario == "missing" ? [state(root)] : [state(root), childState]
+ #expect(request.usage(from: states) == nil)
+ }
+
+ @Test func knownAgentWithoutResolvedTurnPreventsPartialTotal() {
+ let root = reference("session-a", "turn-a")
+ let request = CodexTaskTokenUsageRequest(
+ root: root, expectedAgentIDs: ["unknown-child"], references: [root], deadline: TestFixtures.now
+ )
+ #expect(request.usage(from: [state(root)]) == nil)
+ }
+
+ @Test func inProgressUsageIncludesAvailableRunningAndCompletedChildren() throws {
+ let root = reference("session-a", "turn-a")
+ let running = reference("child-a", "child-turn-a")
+ let completed = reference("child-a", "child-turn-b")
+ let unknown = reference("child-b", "child-turn-c")
+ let request = request(root: root, children: [running, completed, unknown, running])
+ let states = [state(root, terminal: nil), state(running, input: 200, terminal: nil), state(completed, input: 300)]
+ let usage = try #require(request.usage(from: states, requiresFinalUsage: false))
+ #expect(usage.totalTokens == 630)
+ #expect(usage.cachedInputTokens == 60)
+ #expect(request.usage(from: states) == nil)
+ #expect(request.usage(from: [], requiresFinalUsage: false) == nil)
+ }
+
+ @Test(arguments: ["other-root", "other-session", "other-thread", "unavailable", "missing-usage"])
+ func inProgressUsageDoesNotIncludeUnverifiedChildren(scenario: String) {
+ let root = reference("session-a", "turn-a")
+ let child = reference("child-a", "child-turn")
+ let request = request(root: root, children: [child])
+ var childState = state(child, terminal: nil)
+ switch scenario {
+ case "other-root": childState.rootTurnId = "other-root"
+ case "other-session": childState.rootSessionId = "other-session"
+ case "other-thread": childState.threadId = "other-thread"
+ case "unavailable": childState.readStatus = .unavailable
+ default: childState.tokenUsage = nil
+ }
+ let states = [state(root, terminal: nil), childState]
+ #expect(request.usage(from: states, requiresFinalUsage: false)?.totalTokens == 110)
+ }
+
+ @Test func activeSnapshotsUpdateBeforeCompletionAndKeepCompletedChildReferences() throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let preferences = try TestPreferences()
+ defer { preferences.remove() }
+ let monitor = try makeMonitor(directory: directory, preferences: preferences)
+ let event = TestFixtures.event()
+ let key = CodexActivityTaskKey(event: event)
+ monitor.tasks[key] = CodexActivityTask(
+ displayID: UUID(), key: key, event: event, state: .running,
+ latestEvent: .promptSubmitted, startedAt: TestFixtures.now, progressGeneration: 1
+ )
+ let root = reference("session-a", "turn-a")
+ let child = reference("child-a", "child-turn")
+ monitor.subagentTurnLinks[child] = key
+ #expect(Set(monitor.activeTokenUsageReferences()) == [root, child])
+ #expect(monitor.tasks[key]?.snapshot.tokenUsage == nil)
+ let initial = [state(root, terminal: nil)]
+ #expect(monitor.applyActiveTokenUsage(initial))
+ let running = try #require(monitor.tasks[key]?.snapshot)
+ #expect(CodexPrimaryActivity.running(running).tokenUsage?.totalTokens == 110)
+ #expect(!monitor.applyActiveTokenUsage(initial))
+
+ monitor.tasks[key]?.state = .waitingApproval
+ let updated = [state(root, input: 200, terminal: nil), state(child, input: 300)]
+ #expect(monitor.applyActiveTokenUsage(updated))
+ let waiting = try #require(monitor.tasks[key]?.snapshot)
+ #expect(CodexPrimaryActivity.waiting(waiting).tokenUsage?.totalTokens == 520)
+ #expect(monitor.tasks[key]?.state == .waitingApproval)
+ #expect(monitor.pendingTerminalPresentationEvents.isEmpty)
+ #expect(monitor.completions.isEmpty)
+
+ let task = try #require(monitor.tasks[key])
+ var transitions: [CodexActivityTransition] = []
+ monitor.resolveTerminal(
+ .completed(at: TestFixtures.now, duration: 1), task: task, key: key,
+ abortFallback: TestFixtures.now, into: &transitions
+ )
+ #expect(monitor.applyTerminalTokenUsage(updated))
+ #expect(monitor.completions.first?.tokenUsage?.totalTokens == 520)
+ }
+
+ @Test func activeUsageDoesNotCarryAcrossTurnsOrKeepUnavailableData() throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let preferences = try TestPreferences()
+ defer { preferences.remove() }
+ let monitor = try makeMonitor(directory: directory, preferences: preferences)
+ let event = TestFixtures.event(turn: "turn-b")
+ let key = CodexActivityTaskKey(event: event)
+ monitor.tasks[key] = CodexActivityTask(
+ displayID: UUID(), key: key, event: event, state: .running,
+ latestEvent: .promptSubmitted, startedAt: TestFixtures.now, progressGeneration: 1
+ )
+ #expect(!monitor.applyActiveTokenUsage([state(reference("session-a", "turn-a"))]))
+ #expect(monitor.tasks[key]?.tokenUsage == nil)
+ var current = state(reference("session-a", "turn-b"), terminal: nil)
+ current.rootTurnId = "turn-b"
+ #expect(monitor.applyActiveTokenUsage([current]))
+ #expect(monitor.tasks[key]?.tokenUsage?.totalTokens == 110)
+ current.readStatus = .unavailable
+ #expect(monitor.applyActiveTokenUsage([current]))
+ #expect(monitor.tasks[key]?.tokenUsage == nil)
+ }
+
+ @Test func overflowIsRejectedAndConfirmedZeroRemainsAvailable() {
+ let large = CodexTokenUsage(
+ inputTokens: .max, cachedInputTokens: 0, cacheWriteInputTokens: 0,
+ outputTokens: 0, reasoningOutputTokens: 0, totalTokens: .max
+ )
+ #expect(large.isValid)
+ #expect(large.adding(large) == nil)
+ let zero = CodexTokenUsage(
+ inputTokens: 0, cachedInputTokens: 0, cacheWriteInputTokens: 0,
+ outputTokens: 0, reasoningOutputTokens: 0, totalTokens: 0
+ )
+ #expect(zero.isValid)
+ #expect(zero.adding(large) == large)
+ }
+
+ @Test func completedAndInterruptedTasksReceiveLateUsageWithoutNewTerminalEvents() throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let preferences = try TestPreferences()
+ defer { preferences.remove() }
+ let monitor = try makeMonitor(directory: directory, preferences: preferences)
+ let event = TestFixtures.event()
+ let key = CodexActivityTaskKey(event: event)
+ let task = CodexActivityTask(
+ displayID: UUID(), key: key, event: event, state: .running,
+ latestEvent: .promptSubmitted, startedAt: TestFixtures.now, progressGeneration: 1
+ )
+ var transitions: [CodexActivityTransition] = []
+ monitor.resolveTerminal(
+ .completed(at: TestFixtures.now, duration: 1), task: task, key: key,
+ abortFallback: TestFixtures.now, into: &transitions
+ )
+ let completedID = try #require(monitor.completions.first?.id)
+ let otherEvent = TestFixtures.event(turn: "turn-b")
+ let otherKey = CodexActivityTaskKey(event: otherEvent)
+ monitor.tasks[otherKey] = CodexActivityTask(
+ displayID: UUID(), key: otherKey, event: otherEvent, state: .running,
+ latestEvent: .promptSubmitted, startedAt: TestFixtures.now, progressGeneration: 1
+ )
+ monitor.interruptTask(from: otherEvent, source: .bootstrap)
+ #expect(monitor.completions.first?.tokenUsage == nil)
+ #expect(monitor.terminations.first?.tokenUsage == nil)
+
+ var stopped = state(reference("session-a", "turn-b"), input: 200, terminal: nil)
+ stopped.rootTurnId = "turn-b"
+ let states = [state(reference("session-a", "turn-a")), stopped]
+ #expect(monitor.applyTerminalTokenUsage(states))
+ #expect(monitor.completions.first?.tokenUsage?.totalTokens == 110)
+ #expect(monitor.terminations.first?.tokenUsage?.totalTokens == 210)
+ #expect(monitor.completions.first?.id == completedID)
+ #expect(monitor.pendingTerminalPresentationEvents.isEmpty)
+ #expect(!monitor.applyTerminalTokenUsage(states))
+ stopped.readStatus = .unavailable
+ #expect(!monitor.applyTerminalTokenUsage([stopped]))
+ #expect(monitor.terminations.first?.tokenUsage?.totalTokens == 210)
+ _ = monitor.terminalTokenUsageReferences(now: Date().addingTimeInterval(31))
+ #expect(monitor.terminalTokenUsageRequests.isEmpty)
+ #expect(monitor.completions.first?.tokenUsage?.totalTokens == 110)
+ monitor.clearCollectedActivityState()
+ #expect(monitor.completions.isEmpty)
+ }
+
+ @Test func laterTurnPendingAgentMustNotEraseCompletedTurnUsage() throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let preferences = try TestPreferences()
+ defer { preferences.remove() }
+ let monitor = try makeMonitor(directory: directory, preferences: preferences)
+ let first = TestFixtures.event()
+ let firstKey = CodexActivityTaskKey(event: first)
+ let task = CodexActivityTask(
+ displayID: UUID(), key: firstKey, event: first, state: .running,
+ latestEvent: .promptSubmitted, startedAt: TestFixtures.now, progressGeneration: 1
+ )
+ var transitions: [CodexActivityTransition] = []
+ monitor.resolveTerminal(.completed(at: TestFixtures.now, duration: 1), task: task, key: firstKey, abortFallback: TestFixtures.now, into: &transitions)
+ let firstState = state(reference("session-a", "turn-a"))
+ _ = monitor.applyTerminalTokenUsage([firstState])
+ #expect(monitor.completions.first?.tokenUsage?.totalTokens == 110)
+ let second = TestFixtures.event(at: TestFixtures.now.addingTimeInterval(2), turn: "turn-b")
+ let secondKey = CodexActivityTaskKey(event: second)
+ monitor.tasks[secondKey] = CodexActivityTask(
+ displayID: UUID(), key: secondKey, event: second, state: .running,
+ latestEvent: .promptSubmitted, startedAt: second.timestamp, progressGeneration: 2
+ )
+ let child = TestFixtures.event(.subagentStart, at: TestFixtures.now.addingTimeInterval(3), turn: "child-turn-b", agent: "child-b")
+ #expect(monitor.deferUnassociatedSubagentEvent(child, source: .live))
+ _ = monitor.applyTerminalTokenUsage([firstState])
+ #expect(monitor.completions.first?.tokenUsage?.totalTokens == 110)
+ let lateChild = reference("child-a", "child-turn-a")
+ monitor.subagentTurnLinks[lateChild] = firstKey
+ #expect(!monitor.applyTerminalTokenUsage([firstState]))
+ #expect(monitor.completions.first?.tokenUsage?.totalTokens == 110)
+ #expect(monitor.applyTerminalTokenUsage([firstState, state(lateChild, input: 200)]))
+ #expect(monitor.completions.first?.tokenUsage?.totalTokens == 320)
+ var unavailable = firstState
+ unavailable.readStatus = .unavailable
+ #expect(!monitor.applyTerminalTokenUsage([unavailable]))
+ _ = monitor.terminalTokenUsageReferences(now: Date().addingTimeInterval(31))
+ #expect(monitor.completions.first?.tokenUsage?.totalTokens == 320)
+ }
+
+ private func reference(_ thread: String, _ turn: String) -> CodexActivityTurnReference {
+ CodexActivityTurnReference(sessionId: thread, turnId: turn, startedAt: TestFixtures.now)
+ }
+
+ private func request(root: CodexActivityTurnReference, children: [CodexActivityTurnReference]) -> CodexTaskTokenUsageRequest {
+ CodexTaskTokenUsageRequest(
+ root: root, expectedAgentIDs: Set(children.map(\.sessionId)), references: Set([root] + children), deadline: TestFixtures.now
+ )
+ }
+
+ private func state(
+ _ reference: CodexActivityTurnReference, input: Int64 = 100,
+ terminal: CodexSessionTaskTerminalState? = .completed(at: TestFixtures.now, duration: 1)
+ ) -> CodexSessionTaskLifecycleState {
+ CodexSessionTaskLifecycleState(
+ sessionId: reference.sessionId, turnId: reference.turnId, startedAt: TestFixtures.now,
+ approvalReviewer: nil, effort: nil, lastProgressAt: TestFixtures.now, terminal: terminal,
+ rootTurnId: "turn-a", threadId: reference.sessionId, rootSessionId: "session-a",
+ tokenUsage: CodexTokenUsage(
+ inputTokens: input, cachedInputTokens: 20, cacheWriteInputTokens: 0,
+ outputTokens: 10, reasoningOutputTokens: 2, totalTokens: input + 10
+ )
+ )
+ }
+
+ private func makeMonitor(directory: TestDirectory, preferences: TestPreferences) throws -> CodexActivityMonitor {
+ try CodexActivityMonitor(
+ codexHookSettings: CodexHookSettings(
+ hooksURL: directory.url.appendingPathComponent("hooks.json"),
+ codexStatusService: makeStatusService(suiteName: preferences.suite)
+ ),
+ activityProtectionSettings: ActivityProtectionSettings(defaults: preferences.defaults),
+ activityProtectionStateStore: ActivityProtectionStateStore(directoryURL: directory.url)
+ )
+ }
+
+ private nonisolated func makeStatusService(suiteName: String) throws -> CodexStatusService {
+ try CodexStatusService(defaults: #require(UserDefaults(suiteName: suiteName)))
+ }
+}
diff --git a/CodexBarTests/CodexSessionLifecycleReaderTests.swift b/CodexBarTests/CodexSessionLifecycleReaderTests.swift
index 9d48113..3cf6a98 100644
--- a/CodexBarTests/CodexSessionLifecycleReaderTests.swift
+++ b/CodexBarTests/CodexSessionLifecycleReaderTests.swift
@@ -242,6 +242,160 @@ struct CodexSessionLifecycleReaderTests {
CodexActivityTurnReference(sessionId: "session-a", turnId: "turn-a", startedAt: TestFixtures.now)
}
+ @Test func tokenUsageUpdatesIncrementallyBeforeTaskCompletion() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let url = try writeRollout(in: directory, lines: [context, start])
+ let reader = CodexSessionLifecycleReader(codexHomeURL: directory.url)
+ #expect(await reader.lifecycleStates(for: [reference]).first?.tokenUsage == nil)
+ for input in [100, 200, 300] {
+ try append(tokenUsage(input: input) + "\n", to: url)
+ let state = try #require(await reader.lifecycleStates(for: [reference]).first)
+ #expect(state.readStatus == .complete)
+ #expect(state.terminal == nil)
+ #expect(state.tokenUsage?.totalTokens == Int64(input + 10))
+ }
+ try append(completion + "\n", to: url)
+ let completed = try #require(await reader.lifecycleStates(for: [reference]).first)
+ #expect(completed.terminal != nil)
+ #expect(completed.tokenUsage?.totalTokens == 310)
+ }
+
+ @Test func tokenUsageUsesLatestTurnSnapshotWithoutDoubleCounting() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let latest = tokenUsage(input: 200)
+ _ = try writeRollout(in: directory, lines: [context, start, tokenUsage(input: 100), latest, latest, completion])
+ let reader = CodexSessionLifecycleReader(codexHomeURL: directory.url)
+ let state = try #require(await reader.lifecycleStates(for: [reference]).first)
+ #expect(state.tokenUsage?.inputTokens == 200)
+ #expect(state.tokenUsage?.totalTokens == 210)
+ #expect(state.rootTurnId == "turn-a")
+ }
+
+ @Test func lateUsageAfterAbortIsReadWithoutIncludingNextTurn() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let abort = #"{"type":"event_msg","payload":{"type":"turn_aborted","turn_id":"turn-a"}}"#
+ let url = try writeRollout(in: directory, lines: [context, start, tokenUsage(input: 100), abort])
+ let reader = CodexSessionLifecycleReader(codexHomeURL: directory.url)
+ #expect(await reader.lifecycleStates(for: [reference]).first?.tokenUsage?.totalTokens == 110)
+ try append(tokenUsage(input: 200) + "\n" + tokenUsage(input: 999, turn: "turn-b") + "\n", to: url)
+ let state = try #require(await reader.lifecycleStates(for: [reference]).first)
+ #expect(state.tokenUsage?.totalTokens == 210)
+ guard case .aborted = state.terminal else {
+ Issue.record("Expected the aborted turn to retain its terminal state")
+ return
+ }
+ }
+
+ @Test(arguments: ["wrong-thread", "wrong-session", "missing", "negative", "overflow", "wrong-type"])
+ func invalidUsageDoesNotBreakTerminalOrReusePreviousCount(scenario: String) async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let valid = tokenUsage(input: 100)
+ let invalid = switch scenario {
+ case "wrong-thread": valid.replacingOccurrences(of: #""thread_id":"session-a""#, with: #""thread_id":"other""#)
+ case "wrong-session": valid.replacingOccurrences(of: #""session_id":"session-a""#, with: #""session_id":"other""#)
+ case "missing": valid.replacingOccurrences(of: #""input_tokens":100,"#, with: "")
+ case "negative": valid.replacingOccurrences(of: #""cached_input_tokens":20"#, with: #""cached_input_tokens":-1"#)
+ case "overflow": valid.replacingOccurrences(of: #""input_tokens":100"#, with: #""input_tokens":9223372036854775807"#)
+ default: valid.replacingOccurrences(of: #""input_tokens":100"#, with: #""input_tokens":"100""#)
+ }
+ _ = try writeRollout(in: directory, lines: [context, start, valid, invalid, completion])
+ let reader = CodexSessionLifecycleReader(codexHomeURL: directory.url)
+ let state = try #require(await reader.lifecycleStates(for: [reference]).first)
+ #expect(state.readStatus == .complete)
+ #expect(state.terminal != nil)
+ #expect(state.tokenUsage == nil)
+ }
+
+ @Test func oldTokenCountDoesNotBecomeZeroOrAUsageRecord() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ _ = try writeRollout(in: directory, lines: [
+ context,
+ start,
+ #"{"type":"event_msg","payload":{"type":"token_count","info":{"total_token_usage":{"total_tokens":999}}}}"#,
+ completion
+ ])
+ let reader = CodexSessionLifecycleReader(codexHomeURL: directory.url)
+ #expect(await reader.lifecycleStates(for: [reference]).first?.tokenUsage == nil)
+ }
+
+ @Test func corruptGapDropsUsageUntilAFreshCumulativeRecordArrives() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let url = try writeRollout(in: directory, lines: [context, start, tokenUsage(input: 100), completion, "broken"])
+ let reader = CodexSessionLifecycleReader(codexHomeURL: directory.url)
+ let state = try #require(await reader.lifecycleStates(for: [reference]).first)
+ #expect(state.terminal != nil)
+ #expect(state.tokenUsage == nil)
+ try append(tokenUsage(input: 200) + "\n", to: url)
+ #expect(await reader.lifecycleStates(for: [reference]).first?.tokenUsage?.totalTokens == 210)
+ }
+
+ @Test func tailBootstrapUsesCumulativeUsageEvenWhenEarlierResponsesAreOutsideWindow() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ _ = try writeRollout(in: directory, lines: [
+ context,
+ start,
+ tokenUsage(input: 100),
+ oversizedLine(type: "response_item", payloadByteCount: 600 * 1024),
+ tokenUsage(input: 200),
+ completion
+ ])
+ let reader = CodexSessionLifecycleReader(codexHomeURL: directory.url)
+ #expect(await reader.lifecycleStates(for: [reference]).first?.tokenUsage?.totalTokens == 210)
+ }
+
+ @Test func partialUsageAndFileReplacementDoNotExposeStaleCounts() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let url = try writeRollout(in: directory, lines: [context, start, tokenUsage(input: 100), completion])
+ let reader = CodexSessionLifecycleReader(codexHomeURL: directory.url)
+ #expect(await reader.lifecycleStates(for: [reference]).first?.tokenUsage?.totalTokens == 110)
+ try append(tokenUsage(input: 200), to: url)
+ #expect(await reader.lifecycleStates(for: [reference]).first?.tokenUsage == nil)
+ try append("\n", to: url)
+ #expect(await reader.lifecycleStates(for: [reference]).first?.tokenUsage?.totalTokens == 210)
+ try Data((metadata(session: "session-a") + "\n" + context + "\n" + completion + "\n").utf8).write(to: url, options: .atomic)
+ #expect(await reader.lifecycleStates(for: [reference]).first?.tokenUsage == nil)
+ }
+
+ private func tokenUsage(input: Int, turn: String = "turn-a") -> String {
+ """
+ {"type":"token_usage_record","payload":{"thread_id":"session-a","session_id":"session-a","turn_id":"\(turn)",\
+ "root_turn_id":"\(turn)","response_id":"response-\(input)","turn_token_usage":{\
+ "input_tokens":\(input),"cached_input_tokens":20,"cache_write_input_tokens":0,\
+ "output_tokens":10,"reasoning_output_tokens":2,"total_tokens":\(input + 10)}}}
+ """
+ }
+
+ @Test func forkedMetadataDoesNotReplaceChildUsageIdentity() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let childMetadata = #"{"type":"session_meta","payload":{"id":"child-a","session_id":"session-a","parent_thread_id":"session-a","#
+ + #""source":{"subagent":{"thread_spawn":{"parent_thread_id":"session-a"}}}}}"#
+ let usage = tokenUsage(input: 100, turn: "child-turn")
+ .replacingOccurrences(of: #""thread_id":"session-a""#, with: #""thread_id":"child-a""#)
+ .replacingOccurrences(of: #""root_turn_id":"child-turn""#, with: #""root_turn_id":"turn-a""#)
+ let datePath = CodexDateFormat.dayString(from: TestFixtures.now).replacingOccurrences(of: "-", with: "/")
+ _ = try directory.write(
+ [childMetadata, metadata(session: "session-a"), usage, completion.replacingOccurrences(of: "turn-a", with: "child-turn")]
+ .joined(separator: "\n") + "\n",
+ to: "sessions/\(datePath)/rollout-test-child-a.jsonl"
+ )
+ let reader = CodexSessionLifecycleReader(codexHomeURL: directory.url)
+ let child = CodexActivityTurnReference(sessionId: "child-a", turnId: "child-turn", startedAt: TestFixtures.now)
+ let state = try #require(await reader.lifecycleStates(for: [child]).first)
+ #expect(state.threadId == "child-a")
+ #expect(state.rootSessionId == "session-a")
+ #expect(state.rootTurnId == "turn-a")
+ #expect(state.tokenUsage?.totalTokens == 110)
+ }
+
private var context: String {
#"{"timestamp":"2026-09-15T08:00:00Z","type":"turn_context","payload":{"turn_id":"turn-a","approvals_reviewer":"user","effort":" high "}}"#
}
diff --git a/CodexBarTests/CodexTokenHistoryTests.swift b/CodexBarTests/CodexTokenHistoryTests.swift
new file mode 100644
index 0000000..06c6e48
--- /dev/null
+++ b/CodexBarTests/CodexTokenHistoryTests.swift
@@ -0,0 +1,582 @@
+import CloudKit
+import Foundation
+import Synchronization
+import Testing
+
+struct CodexTokenHistoryTests {
+ @Test func replayProgressReportsBackfillAndCompletionWithoutIdleOrIncrementalSpam() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let records = (1 ... 20).map { record(input: $0 * 100) + "\n" }.joined()
+ let file = try directory.write(metadata() + "\n" + start() + "\n" + records, to: "sessions/rollout-main.jsonl")
+ let reports = Mutex<[CodexTokenReplayProgress]>([])
+ let store = CodexTokenHistoryStore(
+ codexHomeURL: directory.url, directoryURL: directory.url.appendingPathComponent("history"), byteBudget: 256,
+ reportProgress: { progress in reports.withLock { $0.append(progress) } }
+ )
+ for _ in 0 ..< 30 {
+ _ = try await store.refresh(now: TestFixtures.now)
+ }
+ let progress = reports.withLock { $0 }
+ #expect(progress.count > 1)
+ #expect(progress.first?.isComplete == false)
+ #expect(progress.first?.remainingBytes ?? 0 > 0)
+ #expect(progress.allSatisfy { $0.totalFiles == 1 && $0.unavailableFiles == 0 })
+ #expect(zip(progress, progress.dropFirst()).allSatisfy { $0.processedBytes < $1.processedBytes })
+ let completed = try #require(progress.last)
+ #expect(completed.isComplete)
+ #expect(completed.remainingBytes == 0)
+ #expect(try completed.processedBytes == UInt64(Data(contentsOf: file).count))
+ let count = progress.count
+ try append(record(input: 3000) + "\n", to: file)
+ _ = try await store.refresh(now: TestFixtures.now)
+ #expect(reports.withLock { $0.count } == count)
+ #expect(try await daily(store)[day]?.totalTokens == 3010)
+ }
+
+ @Test func replayProgressDoesNotCallPartialOrUnreadableFilesComplete() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let file = try directory.write(lines(input: 100) + record(input: 200), to: "sessions/rollout-main.jsonl")
+ let broken = try directory.write("invalid metadata\n", to: "sessions/rollout-broken.jsonl")
+ let reports = Mutex<[CodexTokenReplayProgress]>([])
+ let store = CodexTokenHistoryStore(
+ codexHomeURL: directory.url, directoryURL: directory.url.appendingPathComponent("history"),
+ reportProgress: { progress in reports.withLock { $0.append(progress) } }
+ )
+ _ = try await store.refresh(now: TestFixtures.now)
+ let first = try #require(reports.withLock { $0.last })
+ #expect(!first.isComplete)
+ #expect(first.waitingFiles == 1)
+ #expect(first.unavailableFiles == 1)
+ #expect(first.completedFiles == 0)
+ _ = try await store.refresh(now: TestFixtures.now)
+ #expect(reports.withLock { $0.count } == 1)
+ try append("\n", to: file)
+ _ = try await store.refresh(now: TestFixtures.now)
+ let partial = try #require(reports.withLock { $0.last })
+ #expect(!partial.isComplete)
+ #expect(partial.completedFiles == 1)
+ #expect(partial.waitingFiles == 0)
+ try FileManager.default.removeItem(at: broken)
+ _ = try await store.refresh(now: TestFixtures.now)
+ #expect(reports.withLock { $0.last?.isComplete } == true)
+ }
+
+ @Test func replayProgressResumesPersistedOffsetsAndReportsReplacement() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let file = try directory.write(lines(input: 100), to: "sessions/rollout-main.jsonl")
+ let reports = Mutex<[CodexTokenReplayProgress]>([])
+ let first = CodexTokenHistoryStore(
+ codexHomeURL: directory.url, directoryURL: directory.url.appendingPathComponent("history"), byteBudget: 256,
+ reportProgress: { progress in reports.withLock { $0.append(progress) } }
+ )
+ _ = try await first.refresh(now: TestFixtures.now)
+ let initial = try #require(reports.withLock { $0.last })
+ let restarted = CodexTokenHistoryStore(
+ codexHomeURL: directory.url, directoryURL: directory.url.appendingPathComponent("history"),
+ reportProgress: { progress in reports.withLock { $0.append(progress) } }
+ )
+ _ = try await restarted.refresh(now: TestFixtures.now)
+ let completed = try #require(reports.withLock { $0.last })
+ #expect(completed.isComplete)
+ #expect(completed.processedBytes > initial.processedBytes)
+ #expect(UInt64(completed.batchBytes) < completed.totalBytes)
+ try Data((metadata() + "\n" + start() + "\n" + record(input: 200)).utf8).write(to: file, options: .atomic)
+ _ = try await restarted.refresh(now: TestFixtures.now)
+ #expect(reports.withLock { $0.last?.waitingFiles } == 1)
+ #expect(reports.withLock { $0.last?.isComplete } == false)
+ try append("\n", to: file)
+ _ = try await restarted.refresh(now: TestFixtures.now)
+ #expect(reports.withLock { $0.last?.isComplete } == true)
+ }
+
+ @Test func rebuildReplacesOnlySelectedLocalTurnsAndKeepsIncrementalReading() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let source = try directory.write(lines(input: 500), to: "sessions/rollout-main.jsonl")
+ let otherDay = TestFixtures.now.addingTimeInterval(-86400)
+ let other = lines(input: 200).replacingOccurrences(of: "thread-main", with: "thread-other")
+ .replacingOccurrences(of: String(TestFixtures.now.timeIntervalSince1970), with: String(otherDay.timeIntervalSince1970))
+ let otherFile = try directory.write(other, to: "sessions/rollout-other.jsonl")
+ let store = makeStore(directory)
+ let initial = try await store.refresh(now: TestFixtures.now.addingTimeInterval(60))
+ let otherID = CodexTokenTurn.identifier(thread: "thread-other", turn: "turn-main")
+ let previousOther = try #require(initial.first { $0.id == otherID })
+ try Data(lines(input: 100).utf8).write(to: source, options: .atomic)
+ let changedOther = lines(input: 400).replacingOccurrences(of: "thread-main", with: "thread-other")
+ .replacingOccurrences(of: String(TestFixtures.now.timeIntervalSince1970), with: String(otherDay.timeIntervalSince1970))
+ try Data(changedOther.utf8).write(to: otherFile, options: .atomic)
+ _ = try directory.write(lines(input: 100), to: "archived_sessions/rollout-copy.jsonl")
+ let result = try await store.rebuild(for: [day], now: TestFixtures.now.addingTimeInterval(120))
+ #expect(result.dateKeys == [day])
+ #expect(result.turnCount == 1)
+ let current = try await store.currentTurns()
+ #expect(current.first { $0.id == otherID } == previousOther)
+ #expect(CodexTokenTurn.dailyUsage(current, now: TestFixtures.now.addingTimeInterval(180))[day]?.totalTokens == 110)
+ #expect(CodexTokenTurn.dailyUsage(current + initial, now: TestFixtures.now.addingTimeInterval(180))[day]?.totalTokens == 110)
+ try append(record(input: 300) + "\n", to: source)
+ #expect(try await daily(makeStore(directory))[day]?.totalTokens == 310)
+ }
+
+ @Test func rebuildWithMissingRolloutsPreservesKnownTurns() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let source = try directory.write(lines(input: 500), to: "sessions/rollout-main.jsonl")
+ let store = makeStore(directory)
+ let before = try await store.refresh(now: TestFixtures.now)
+ try FileManager.default.removeItem(at: source)
+ let result = try await store.rebuild(for: [day], now: TestFixtures.now)
+ #expect(result.dateKeys.isEmpty)
+ #expect(try await store.currentTurns() == before)
+ }
+
+ @Test func rebuildCanClearPreviouslyCountedUsageAndExcludesConcurrentRebuilds() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let source = try directory.write(lines(input: 500), to: "sessions/rollout-main.jsonl")
+ let store = makeStore(directory)
+ let before = try await store.refresh(now: TestFixtures.now)
+ let lock = try #require(try CodexTokenFileStorage.acquireLock(in: directory.url.appendingPathComponent("history"), name: "rebuild.lock"))
+ await #expect(throws: (any Error).self) { try await store.rebuild(for: [day], now: TestFixtures.now) }
+ CodexTokenFileStorage.releaseLock(lock)
+ #expect(try await store.currentTurns() == before)
+ try Data((metadata() + "\n" + start() + "\n").utf8).write(to: source, options: .atomic)
+ _ = try await store.rebuild(for: [day], now: TestFixtures.now.addingTimeInterval(60))
+ let current = try await store.currentTurns()
+ #expect(current.count == 1)
+ #expect(current.first?.usage == nil)
+ #expect(current.first?.rebuiltAt != nil)
+ #expect(CodexTokenTurn.dailyUsage(current + before, now: TestFixtures.now.addingTimeInterval(60)).isEmpty)
+ }
+
+ @Test func incompleteOrCancelledRebuildDoesNotPublishPartialResults() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let source = try directory.write(lines(input: 500), to: "sessions/rollout-main.jsonl")
+ let store = makeStore(directory)
+ let before = try await store.refresh(now: TestFixtures.now)
+ try Data(lines(input: 100).utf8).write(to: source, options: .atomic)
+ let cancelled = Task { try await store.rebuild(for: [day], now: TestFixtures.now) }
+ cancelled.cancel()
+ await #expect(throws: CancellationError.self) { try await cancelled.value }
+ #expect(try await store.currentTurns() == before)
+ _ = try directory.write("broken metadata\n", to: "sessions/rollout-broken.jsonl")
+ await #expect(throws: (any Error).self) { try await store.rebuild(for: [day], now: TestFixtures.now) }
+ #expect(try await store.currentTurns() == before)
+ }
+
+ @Test func rebuildReadsAllBatchesButLeavesPartialTailForIncrementalRefresh() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let body = "{\"type\":\"response_item\",\"payload\":\"" + String(repeating: "x", count: 2 * 1024 * 1024) + "\"}\n"
+ let source = try directory.write(lines(input: 100) + body + record(input: 300), to: "sessions/rollout-main.jsonl")
+ let store = CodexTokenHistoryStore(codexHomeURL: directory.url, directoryURL: directory.url.appendingPathComponent("history"), byteBudget: 4096)
+ let result = try await store.rebuild(for: [day], now: TestFixtures.now.addingTimeInterval(60))
+ #expect(result.turnCount == 1)
+ let current = try await store.currentTurns()
+ #expect(CodexTokenTurn.dailyUsage(current, now: TestFixtures.now.addingTimeInterval(60))[day]?.totalTokens == 110)
+ try append("\n", to: source)
+ #expect(try await daily(makeStore(directory))[day]?.totalTokens == 310)
+ }
+
+ @Test func rebuildGroupsCrossMidnightChildUsageUnderRootStartDay() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let rootStart = try #require(CodexDateFormat.dayDate(from: day)).addingTimeInterval(-10)
+ let rootDay = CodexDateFormat.dayString(from: rootStart)
+ let main = lines(input: 100).replacingOccurrences(
+ of: String(TestFixtures.now.timeIntervalSince1970), with: String(rootStart.timeIntervalSince1970)
+ )
+ _ = try directory.write(main, to: "sessions/rollout-main.jsonl")
+ let child = metadata(thread: "thread-child") + "\n" + start(turn: "turn-child") + "\n"
+ + record(input: 300, thread: "thread-child", turn: "turn-child") + "\n"
+ _ = try directory.write(child, to: "sessions/rollout-child.jsonl")
+ let store = makeStore(directory)
+ let result = try await store.rebuild(for: [rootDay], now: TestFixtures.now.addingTimeInterval(60))
+ #expect(result.turnCount == 2)
+ #expect(result.dateKeys == [rootDay])
+ let current = try await store.currentTurns()
+ #expect(CodexTokenTurn.dailyUsage(current, now: TestFixtures.now.addingTimeInterval(60))[rootDay]?.totalTokens == 420)
+ }
+
+ @Test func cloudRebuildMarkerOverridesStaleTotalsAndCanClearUsage() {
+ let stale = turn("main", "a", input: 500)
+ var rebuilt = turn("main", "a", input: 100)
+ rebuilt.rebuiltAt = TestFixtures.now
+ #expect(stale.merging(rebuilt) == rebuilt)
+ #expect(rebuilt.merging(stale) == rebuilt)
+ let exported = rebuilt.pseudonymized(salt: Data("account".utf8))
+ let record = CKRecord(recordType: CodexTokenHistorySync.recordType, recordID: .init(recordName: exported.id))
+ CodexTokenHistorySync.apply(exported, to: record)
+ #expect(CodexTokenHistorySync.turn(from: record) == exported)
+ var cleared = exported
+ cleared.usage = nil
+ cleared.rebuiltAt = TestFixtures.now.addingTimeInterval(1)
+ CodexTokenHistorySync.apply(cleared, to: record)
+ #expect(CodexTokenHistorySync.turn(from: record) == cleared)
+ #expect(exported.merging(cleared).usage == nil)
+ #expect(CodexTokenTurn.syncable([cleared]) == [cleared])
+ }
+
+ @Test(arguments: [false, true])
+ func cloudBaselineRecoveryReplaysNewUsageWithoutRevivingOldTotals(scanBeforeRecovery: Bool) async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let source = try directory.write(lines(input: 100), to: "sessions/rollout-main.jsonl")
+ let store = makeStore(directory)
+ let rebuiltAt = TestFixtures.now.addingTimeInterval(60)
+ _ = try await store.rebuild(for: [day], now: rebuiltAt)
+ let corrected = try #require(try await store.currentTurns().first)
+ let salt = Data("test-account".utf8)
+ let remote = corrected.pseudonymized(salt: salt)
+ let unrelated = turn("other-device", "other-turn", input: 900).pseudonymized(salt: salt)
+ let baseline = CodexTokenHistoryBaseline(salt: salt, turns: [remote.id: remote, unrelated.id: unrelated])
+ try FileManager.default.removeItem(at: directory.url.appendingPathComponent("history"))
+ // 同一文件混有旧的大数值和重建后的新记录, 聚合时间较新不能证明聚合值也较新
+ let newRecord = record(input: 200).replacingOccurrences(
+ of: "2026-09-15T08:00:10Z", with: rebuiltAt.addingTimeInterval(20).ISO8601Format()
+ )
+ try Data((lines(input: 500) + newRecord + "\n").utf8).write(to: source)
+ if scanBeforeRecovery {
+ #expect(try await daily(makeStore(directory))[day]?.totalTokens == 510)
+ }
+ let restored = try await makeStore(directory).refresh(now: rebuiltAt.addingTimeInterval(30), baseline: baseline)
+ let recovered = try #require(restored.first)
+ #expect(restored.count == 1)
+ #expect(recovered.rebuiltAt == corrected.rebuiltAt)
+ #expect(recovered.usage?.totalTokens == 210)
+ #expect(remote.merging(recovered.pseudonymized(salt: salt)).usage?.totalTokens == 210)
+ // 新进程且本轮云端不可用, 仍然记住恢复边界, 归档旧副本不能重新抬高统计
+ _ = try directory.write(lines(input: 700), to: "archived_sessions/rollout-old.jsonl")
+ #expect(try await daily(makeStore(directory))[day]?.totalTokens == 210)
+ let nextRecord = record(input: 300).replacingOccurrences(
+ of: "2026-09-15T08:00:10Z", with: rebuiltAt.addingTimeInterval(40).ISO8601Format()
+ )
+ try append(nextRecord + "\n", to: source)
+ #expect(try await daily(makeStore(directory))[day]?.totalTokens == 310)
+ }
+
+ @Test func recoveredClearUsageAndSmallBudgetSurviveRestarts() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let body = "{\"type\":\"response_item\",\"payload\":\"" + String(repeating: "x", count: 8192) + "\"}\n"
+ let file = try directory.write(lines(input: 500) + body, to: "sessions/rollout-main.jsonl")
+ let original = try #require(try await makeStore(directory).refresh(now: TestFixtures.now).first)
+ var cleared = original
+ cleared.usage = nil
+ cleared.rebuiltAt = TestFixtures.now.addingTimeInterval(60)
+ let salt = Data("account".utf8)
+ let cloud = cleared.pseudonymized(salt: salt)
+ let baseline = CodexTokenHistoryBaseline(salt: salt, turns: [cloud.id: cloud])
+ let record = record(input: 200).replacingOccurrences(
+ of: "2026-09-15T08:00:10Z", with: TestFixtures.now.addingTimeInterval(80).ISO8601Format()
+ )
+ try append(record + "\n", to: file)
+ var turns: [CodexTokenTurn] = []
+ for iteration in 0 ..< 12 {
+ let store = CodexTokenHistoryStore(
+ codexHomeURL: directory.url, directoryURL: directory.url.appendingPathComponent("history"), byteBudget: 1024
+ )
+ turns = try await store.refresh(now: TestFixtures.now.addingTimeInterval(90), baseline: baseline)
+ if iteration == 0 {
+ #expect(turns.first?.usage == nil)
+ }
+ }
+ #expect(turns.first?.usage?.totalTokens == 210)
+ #expect(turns.first?.rebuiltAt == cleared.rebuiltAt)
+ // 较早的云端基线不能覆盖后续手动重建
+ try Data(lines(input: 100).utf8).write(to: file, options: .atomic)
+ _ = try await makeStore(directory).rebuild(for: [day], now: TestFixtures.now.addingTimeInterval(120))
+ let rebuilt = try await makeStore(directory).refresh(now: TestFixtures.now.addingTimeInterval(130), baseline: baseline)
+ #expect(rebuilt.first?.usage?.totalTokens == 110)
+ }
+
+ @Test func recoveryKeepsChildUsageUnderRootDayWithoutImportingRemoteOnlyTurns() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ _ = try directory.write(lines(input: 100), to: "sessions/rollout-main.jsonl")
+ let child = metadata(thread: "thread-child") + "\n" + start(turn: "turn-child") + "\n"
+ + record(input: 200, thread: "thread-child", turn: "turn-child") + "\n"
+ let childFile = try directory.write(child, to: "sessions/rollout-child.jsonl")
+ let store = makeStore(directory)
+ _ = try await store.rebuild(for: [day], now: TestFixtures.now.addingTimeInterval(60))
+ let salt = Data("account".utf8)
+ let remote = try await store.currentTurns().map { $0.pseudonymized(salt: salt) }
+ let baseline = CodexTokenHistoryBaseline(salt: salt, turns: CodexTokenTurn.merged(remote))
+ try FileManager.default.removeItem(at: directory.url.appendingPathComponent("history"))
+ let updated = record(input: 300, thread: "thread-child", turn: "turn-child").replacingOccurrences(
+ of: "2026-09-15T08:00:10Z", with: TestFixtures.now.addingTimeInterval(80).ISO8601Format()
+ )
+ try append(updated + "\n", to: childFile)
+ let turns = try await makeStore(directory).refresh(now: TestFixtures.now.addingTimeInterval(90), baseline: baseline)
+ #expect(turns.count == 2)
+ #expect(CodexTokenTurn.dailyUsage(turns, now: TestFixtures.now.addingTimeInterval(90))[day]?.totalTokens == 420)
+ let childID = CodexTokenTurn.identifier(thread: "thread-child", turn: "turn-child")
+ #expect(turns.first { $0.id == childID }?.startedAt == TestFixtures.now)
+ #expect(turns.first { $0.id == childID }?.rootID == CodexTokenTurn.identifier(thread: "thread-main", turn: "turn-main"))
+ }
+
+ @Test func cloudRecoveryMatchesAccountSaltAndRootIdentity() {
+ let local = turn("child", "b", root: CodexTokenTurn.identifier(thread: "main", turn: "a"), input: 100)
+ var remote = local.pseudonymized(salt: Data("account-a".utf8))
+ remote.rebuiltAt = TestFixtures.now
+ #expect(CodexTokenHistoryBaseline(salt: Data("account-b".utf8), turns: [remote.id: remote]).replacement(for: local) == nil)
+ let baseline = CodexTokenHistoryBaseline(salt: Data("account-a".utf8), turns: [remote.id: remote])
+ #expect(baseline.replacement(for: local)?.rootID == local.rootID)
+ var unknownRoot = local
+ unknownRoot.rootID = local.id
+ #expect(baseline.replacement(for: unknownRoot) == nil)
+ }
+
+ @Test func sharedSyncLockExcludesConcurrentWritersWithoutBlockingCacheReads() throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let first = try #require(try CodexTokenFileStorage.acquireLock(in: directory.url, name: "sync.lock", nonblocking: true))
+ let competing = try CodexTokenFileStorage.acquireLock(in: directory.url, name: "sync.lock", nonblocking: true)
+ #expect(competing == nil)
+ if let competing {
+ CodexTokenFileStorage.releaseLock(competing)
+ }
+ try CodexTokenFileStorage.withLock(in: directory.url) {}
+ CodexTokenFileStorage.releaseLock(first)
+ let next = try #require(try CodexTokenFileStorage.acquireLock(in: directory.url, name: "sync.lock", nonblocking: true))
+ CodexTokenFileStorage.releaseLock(next)
+ }
+
+ @Test func freshHistoryReadsRecentFilesBeforeOlderBackfill() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ for index in 0 ..< 20 {
+ _ = try directory.write(lines(input: 100), to: "sessions/rollout-\(index).jsonl")
+ }
+ let files = try FileManager.default.contentsOfDirectory(at: directory.url.appendingPathComponent("sessions"), includingPropertiesForKeys: nil)
+ let recent = try #require(files.last)
+ for file in files {
+ try FileManager.default.setAttributes([.modificationDate: TestFixtures.now.addingTimeInterval(-86400)], ofItemAtPath: file.path)
+ }
+ try Data(lines(input: 10000).utf8).write(to: recent)
+ try FileManager.default.setAttributes([.modificationDate: TestFixtures.now], ofItemAtPath: recent.path)
+ let store = CodexTokenHistoryStore(codexHomeURL: directory.url, directoryURL: directory.url.appendingPathComponent("history"), byteBudget: 2048)
+ #expect(try await daily(store)[day]?.totalTokens == 10010)
+ }
+
+ @Test func cumulativeSnapshotsAndMultipleDevicesCountEachThreadTurnOnce() {
+ let root = turn("main", "a", input: 100)
+ var updated = turn("main", "a", input: 200)
+ updated.updatedAt = TestFixtures.now.addingTimeInterval(10)
+ let child = turn("child", "b", root: root.id, input: 300)
+ let result = CodexTokenTurn.dailyUsage([root, updated, root, child, child], now: TestFixtures.now.addingTimeInterval(60))
+ #expect(result[day]?.totalTokens == 520)
+ #expect(CodexTokenTurn.merged([updated, root])[root.id] == CodexTokenTurn.merged([root, updated])[root.id])
+ }
+
+ @Test func allChildrenIncludingLaterTurnsBelongToRootStartDate() throws {
+ let start = try #require(CodexDateFormat.dayDate(from: "2026-09-15")?.addingTimeInterval(86390))
+ var root = turn("main", "a", input: 100)
+ root.startedAt = start
+ root.updatedAt = start.addingTimeInterval(30)
+ var child = turn("child", "b", root: root.id, input: 200)
+ child.startedAt = start.addingTimeInterval(20)
+ child.updatedAt = start.addingTimeInterval(80)
+ var followup = turn("child", "c", root: root.id, input: 300)
+ followup.startedAt = start.addingTimeInterval(40)
+ followup.updatedAt = start.addingTimeInterval(90)
+ let days = CodexTokenTurn.dailyUsage([root, child, followup], now: start.addingTimeInterval(100))
+ #expect(days.count == 1)
+ #expect(days["2026-09-15"]?.totalTokens == 630)
+ #expect(CodexTokenTurn.dailyUsage([child], now: start.addingTimeInterval(100)).isEmpty)
+ }
+
+ @Test func cacheRateUsesDailyTotalsAndMissingUsageDoesNotBecomeZero() {
+ var a = turn("main", "a", input: 100)
+ var b = turn("other", "a", input: 300)
+ a.usage = usage(input: 100, cached: 80)
+ b.usage = usage(input: 300, cached: 30)
+ let merged = CodexTokenTurn.dailyUsage([a, b], now: TestFixtures.now)
+ #expect(merged[day]?.cacheHitRate == 0.275)
+ a.usage = nil
+ #expect(CodexTokenTurn.dailyUsage([a], now: TestFixtures.now).isEmpty)
+ a.usage = CodexTokenUsage(inputTokens: 0, cachedInputTokens: 0, cacheWriteInputTokens: 0, outputTokens: 0, reasoningOutputTokens: 0, totalTokens: 0)
+ #expect(CodexTokenTurn.dailyUsage([a], now: TestFixtures.now)[day]?.totalTokens == 0)
+ }
+
+ @Test func cloudCodecUsesAccountScopedHashesAndRetainsAllCounters() throws {
+ let source = turn("private-thread", "private-turn", input: 100)
+ let exported = source.pseudonymized(salt: Data("account-a".utf8))
+ #expect(exported.id == exported.rootID)
+ #expect(exported.id != source.id)
+ #expect(exported.id != source.pseudonymized(salt: Data("account-b".utf8)).id)
+ let zone = CKRecordZone.ID(zoneName: "test", ownerName: CKCurrentUserDefaultName)
+ let id = CodexTokenHistorySync.recordID(exported.id, zoneID: zone)
+ #expect(id.recordName == exported.id)
+ let record = CKRecord(recordType: CodexTokenHistorySync.recordType, recordID: id)
+ CodexTokenHistorySync.apply(exported, to: record)
+ #expect(CodexTokenHistorySync.turn(from: record) == exported)
+ #expect(record.allKeys().sorted() == ["observedAt", "rootID", "schemaVersion", "startedAt", "usage"])
+ let text = try #require(String(data: JSONEncoder().encode(exported), encoding: .utf8))
+ #expect(!text.contains("private-thread"))
+ #expect(!text.contains("private-turn"))
+ record["schemaVersion"] = 99 as CKRecordValue
+ #expect(record.recordID == CodexTokenHistorySync.recordID(exported.id, zoneID: zone))
+ #expect(CodexTokenHistorySync.turn(from: record) == nil)
+ }
+
+ @Test func incrementalReadRestartAndArchivedCopiesDoNotDuplicateUsage() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let file = try directory.write(lines(input: 100), to: "sessions/2026/09/15/rollout-main.jsonl")
+ let store = makeStore(directory)
+ #expect(try await daily(store)[day]?.totalTokens == 110)
+ try append(record(input: 200), to: file)
+ #expect(try await daily(store)[day]?.totalTokens == 110)
+ try append("\n", to: file)
+ #expect(try await daily(store)[day]?.totalTokens == 210)
+ let restarted = makeStore(directory)
+ _ = try directory.write(Data(contentsOf: file), to: "archived_sessions/rollout-copy.jsonl")
+ #expect(try await daily(restarted)[day]?.totalTokens == 210)
+ let ledger = try String(contentsOf: directory.url.appendingPathComponent("history/ledger.json"), encoding: .utf8)
+ #expect(!ledger.contains("thread-main"))
+ #expect(!ledger.contains("turn-main"))
+ #expect(!ledger.contains("PRIVATE_BODY"))
+ }
+
+ @Test func childInheritedHistoryIsIgnoredAndNewUsageIsIncludedOnce() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ _ = try directory.write(lines(input: 100), to: "sessions/rollout-main.jsonl")
+ let child = metadata(thread: "thread-child", session: "thread-main") + "\n" + lines(input: 100)
+ + start(turn: "turn-child") + "\n" + record(input: 300, thread: "thread-child", turn: "turn-child") + "\n"
+ _ = try directory.write(child, to: "sessions/rollout-child.jsonl")
+ #expect(try await daily(makeStore(directory))[day]?.totalTokens == 420)
+ }
+
+ @Test func truncationAndReplacementPreserveKnownConsumptionWithoutDoubleCounting() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let file = try directory.write(lines(input: 100), to: "sessions/rollout-main.jsonl")
+ let store = makeStore(directory)
+ #expect(try await daily(store)[day]?.totalTokens == 110)
+ try Data(lines(input: 300).utf8).write(to: file)
+ #expect(try await daily(store)[day]?.totalTokens == 310)
+ try Data(lines(input: 100).utf8).write(to: file, options: .atomic)
+ #expect(try await daily(store)[day]?.totalTokens == 310)
+ }
+
+ @Test func boundedReadsCrossOversizedBodyAndNeverLoseFollowingUsage() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let body = "{\"type\":\"response_item\",\"payload\":{\"text\":\"" + String(repeating: "x", count: 3 * 1024 * 1024) + "\"}}\n"
+ _ = try directory.write(lines(input: 100) + body + record(input: 300) + "\n", to: "sessions/rollout-main.jsonl")
+ let store = CodexTokenHistoryStore(codexHomeURL: directory.url, directoryURL: directory.url.appendingPathComponent("history"), byteBudget: 256 * 1024)
+ var result: [String: CodexTokenUsage] = [:]
+ for _ in 0 ..< 15 {
+ result = try await daily(store)
+ }
+ #expect(result[day]?.totalTokens == 310)
+ }
+
+ @Test func malformedUsageAndLegacySnapshotsCannotInventCounts() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let invalid = record(input: 100).replacingOccurrences(of: "\"input_tokens\":100", with: "\"input_tokens\":-1")
+ let legacy = "{\"type\":\"event_msg\",\"payload\":{\"type\":\"token_count\"}}\n"
+ _ = try directory.write(metadata() + "\n" + start() + "\n" + invalid + "\n" + legacy, to: "sessions/rollout-main.jsonl")
+ #expect(try await daily(makeStore(directory)).isEmpty)
+ }
+
+ @Test func smallReadBudgetStopsAtOneLineAndEventuallyCatchesUp() async throws {
+ let directory = try TestDirectory()
+ defer { try? directory.remove() }
+ let records = (1 ... 100).map { record(input: $0 * 100) + "\n" }.joined()
+ _ = try directory.write(metadata() + "\n" + start() + "\n" + records, to: "sessions/rollout-main.jsonl")
+ let store = CodexTokenHistoryStore(codexHomeURL: directory.url, directoryURL: directory.url.appendingPathComponent("history"), byteBudget: 256)
+ let initial = try await daily(store)
+ #expect((initial[day]?.totalTokens ?? 0) < 10010)
+ var result = initial
+ for _ in 0 ..< 110 {
+ result = try await daily(store)
+ }
+ #expect(result[day]?.totalTokens == 10010)
+ }
+
+ @Test func childUsageWaitsForRootStartAndNeedsNoRootUsageRecord() {
+ var root = turn("main", "a", input: 100)
+ root.usage = nil
+ let child = turn("child", "b", root: root.id, input: 200)
+ #expect(CodexTokenTurn.dailyUsage([child], now: TestFixtures.now).isEmpty)
+ #expect(CodexTokenTurn.dailyUsage([root, child], now: TestFixtures.now)[day]?.totalTokens == 210)
+ #expect(Set(CodexTokenTurn.syncable([root, child]).map(\.id)) == [root.id, child.id])
+ }
+
+ @Test func dailyOverflowIsUnavailableAndExpiredTurnsAreExcluded() {
+ var root = turn("main", "a", input: 100)
+ root.usage = CodexTokenUsage(
+ inputTokens: .max, cachedInputTokens: 0, cacheWriteInputTokens: 0,
+ outputTokens: 0, reasoningOutputTokens: 0, totalTokens: .max
+ )
+ let child = turn("child", "b", root: root.id, input: 200)
+ #expect(CodexTokenTurn.dailyUsage([root, child], now: TestFixtures.now).isEmpty)
+ root.startedAt = TestFixtures.now.addingTimeInterval(-220 * 86400)
+ #expect(CodexTokenTurn.dailyUsage([root], now: TestFixtures.now).isEmpty)
+ }
+
+ @Test func heatmapSeparatesAccountIntensityFromRolloutDailyMetrics() throws {
+ var workflow = WorkflowSnapshot.empty
+ workflow.tokenUsageByDate = [day: usage(input: 100)]
+ let grid = UsageHeatmapDay.grid(usage: nil, workflow: workflow, showsWorkflow: true, columnCount: 2, today: TestFixtures.now)
+ let today = try #require(grid.compactMap(\.self).first { $0.startDate == day })
+ #expect(today.tokenState == .unavailable)
+ #expect(today.tokenUsage?.totalTokens == 110)
+ #expect(today.workflow.turnCount == 0)
+ }
+
+ private var day: String {
+ CodexDateFormat.dayString(from: TestFixtures.now)
+ }
+
+ private func usage(input: Int64, cached: Int64 = 20) -> CodexTokenUsage {
+ CodexTokenUsage(inputTokens: input, cachedInputTokens: cached, cacheWriteInputTokens: 5, outputTokens: 10, reasoningOutputTokens: 2, totalTokens: input + 10)
+ }
+
+ private func turn(_ thread: String, _ turn: String, root: String? = nil, input: Int64) -> CodexTokenTurn {
+ let id = CodexTokenTurn.identifier(thread: thread, turn: turn)
+ return CodexTokenTurn(id: id, rootID: root ?? id, startedAt: TestFixtures.now, updatedAt: TestFixtures.now, usage: usage(input: input))
+ }
+
+ private func makeStore(_ directory: TestDirectory) -> CodexTokenHistoryStore {
+ CodexTokenHistoryStore(codexHomeURL: directory.url, directoryURL: directory.url.appendingPathComponent("history"))
+ }
+
+ private func daily(_ store: CodexTokenHistoryStore) async throws -> [String: CodexTokenUsage] {
+ try await CodexTokenTurn.dailyUsage(store.refresh(now: TestFixtures.now.addingTimeInterval(60)), now: TestFixtures.now.addingTimeInterval(60))
+ }
+
+ private func metadata(thread: String = "thread-main", session: String = "thread-main") -> String {
+ "{\"type\":\"session_meta\",\"payload\":{\"id\":\"\(thread)\",\"session_id\":\"\(session)\",\"source\":\"cli\"}}"
+ }
+
+ private func start(turn: String = "turn-main") -> String {
+ "{\"type\":\"event_msg\",\"payload\":{\"type\":\"task_started\",\"turn_id\":\"\(turn)\",\"started_at\":\(TestFixtures.now.timeIntervalSince1970)}}"
+ }
+
+ private func record(input: Int, thread: String = "thread-main", turn: String = "turn-main") -> String {
+ """
+ {"timestamp":"2026-09-15T08:00:10Z","type":"token_usage_record","payload":{"thread_id":"\(thread)","session_id":"thread-main",\
+ "turn_id":"\(turn)","root_turn_id":"turn-main","response_id":"response-\(input)","turn_token_usage":{\
+ "input_tokens":\(input),"cached_input_tokens":20,"cache_write_input_tokens":5,"output_tokens":10,"reasoning_output_tokens":2,"total_tokens":\(input + 10)}}}
+ """
+ }
+
+ private func lines(input: Int) -> String {
+ metadata() + "\n" + start() + "\n{\"type\":\"response_item\",\"payload\":{\"text\":\"PRIVATE_BODY\"}}\n" + record(input: input) + "\n"
+ }
+
+ private func append(_ text: String, to url: URL) throws {
+ let handle = try FileHandle(forWritingTo: url)
+ defer { try? handle.close() }
+ try handle.seekToEnd()
+ try handle.write(contentsOf: Data(text.utf8))
+ }
+}
diff --git a/CodexBarTests/SettingsAndMaintenanceTests.swift b/CodexBarTests/SettingsAndMaintenanceTests.swift
index 23e2309..e332b35 100644
--- a/CodexBarTests/SettingsAndMaintenanceTests.swift
+++ b/CodexBarTests/SettingsAndMaintenanceTests.swift
@@ -2,6 +2,13 @@ import Foundation
import Testing
struct SettingsAndMaintenanceTests {
+ @Test func rebuildRangeIncludesDatesWithoutHookEvents() {
+ let range = RebuildDateRange.starting(at: "2026-09-15").completing(with: "2026-09-17")
+ #expect(range.dateKeys == ["2026-09-15", "2026-09-16", "2026-09-17"])
+ #expect(RebuildDateRange.starting(at: "2026-09-15").dateKeys.isEmpty)
+ #expect(RebuildDateRange.starting(at: "2026-09-15").completing(with: "2026-09-15").dateKeys == ["2026-09-15"])
+ }
+
@Test func autoResetDefaultsOffAndRepairsInvalidLeadTime() throws {
let preferences = try TestPreferences()
defer { preferences.remove() }
diff --git a/Config/Version.xcconfig b/Config/Version.xcconfig
index 12b4d1d..047dc5d 100644
--- a/Config/Version.xcconfig
+++ b/Config/Version.xcconfig
@@ -1,2 +1,2 @@
-MARKETING_VERSION = 4.0.8
-CURRENT_PROJECT_VERSION = 108
+MARKETING_VERSION = 4.0.9
+CURRENT_PROJECT_VERSION = 109
diff --git a/Docs/DeveloperGuide/activity-monitor.md b/Docs/DeveloperGuide/activity-monitor.md
index 37c63d3..bb3c07b 100644
--- a/Docs/DeveloperGuide/activity-monitor.md
+++ b/Docs/DeveloperGuide/activity-monitor.md
@@ -4,14 +4,15 @@
## 目标
-实时任务链路需要回答 4 个问题:
+实时任务链路需要回答以下问题:
- 当前是否有任务正在运行
- 当前是否在等待用户批准
- 最近任务是完成还是终止
- 哪些运行任务已经长时间没有进展
+- 当前轮次及其子 Agent 已产生多少 Token 用量
-Hook 事件提供实时进展和中断信号,rollout 文件补充生命周期信息。[`CodexActivityMonitor.swift`](../../CodexBar/Services/Workflow/CodexActivityMonitor.swift) 合并两者并发布唯一任务快照:
+Hook 事件提供实时进展和中断信号,rollout 文件补充生命周期和轮次 Token 用量。[`CodexActivityMonitor.swift`](../../CodexBar/Services/Workflow/CodexActivityMonitor.swift) 合并两者并发布唯一任务快照:
```text
Codex Hook -> WorkflowHookEventRecorder -> Hook JSONL
@@ -207,6 +208,28 @@ rollout 坏行将当时尚未结束的 turn 标记为有覆盖缺口,后续重
终态要求 `payload.turn_id` 非空,并且本轮读取状态为 `complete`。外层 `type = "event_msg"` 时,`payload.type` 为 `task_complete` 或 `turn_complete` 确认完成,完成时间优先使用有效的 `payload.completed_at`(Unix 秒),缺失或无效时使用外层 `timestamp`;两者均不可用时不确认完成。`payload.type = "turn_aborted"` 确认中断。非负且有限的 `payload.duration_ms` 换算为秒后用于耗时展示;中断时间缺失时,活动任务使用对账时间,待确认任务使用移出活动列表的时间,结果均不早于任务最后活动时间。
+## 本轮 Token 用量
+
+`CodexSessionLifecycleReader` 从外层 `type == token_usage_record` 的记录读取 `payload.turn_token_usage`。使用线程轮次累计值,不累加每条累计快照;`event_msg/token_count` 只提供进展信号,不作为本轮用量来源。
+
+| 展示指标 | `turn_token_usage` 字段或计算方式 |
+| --- | --- |
+| 总量 | `total_tokens`,等于输入加输出 |
+| 输入 | `input_tokens`,包含缓存命中和写入 |
+| 输出 | `output_tokens`,包含推理输出 |
+| 缓存命中 | `cached_input_tokens` |
+| 缓存写入 | `cache_write_input_tokens` |
+| 缓存命中率 | `cached_input_tokens / input_tokens`,输入为零时不可计算 |
+| 推理输出 | `reasoning_output_tokens` |
+
+六项计数均需存在且非负,总量必须等于输入加输出,缓存命中加写入不能超过输入,推理不能超过输出。解析同时校验 `thread_id`、`session_id`、`turn_id`、`root_turn_id` 和 `response_id` 的归属与有效性;字段缺失或校验失败时不生成用量。有效记录中的缓存写入或推理输出为零时直接展示零值。
+
+`CodexActivityTokenUsage.swift` 按根任务收集主线程及已关联子线程的轮次引用,并按线程、轮次去重。运行中汇总本次读取完整且归属匹配的线程,尚未有用量的线程等待后续刷新;显示值因此可以是已知线程的小计。实时卡片使用内存任务快照,不读取历史日汇总或 iCloud 缓存。
+
+完成和终止记录创建时用量为空,由结束后补读填入。补读最多持续 30 秒,每 2 秒安排一次,每批最多处理 16 个待补读任务。最终汇总要求已知子 Agent 身份齐全、各线程用量可用,且子线程已结束。补读取得用量后,后续读取不完整时保留该值,迟到的子线程关联只加入所属根轮次,不影响后续轮次。结束状态、通知和防睡眠释放不等待 Token 补读。
+
+历史回放使用独立的账本与读取游标,见 [Rollout Token 历史](sync.md#rollout-token-历史)
+
## 任务身份
任务 key 按可用信息选择最精确身份:
@@ -566,6 +589,7 @@ Monitor 为 reader 和异步恢复任务维护 generation:
## 关键源码
+- [`CodexActivityTokenUsage.swift`](../../CodexBar/Services/Workflow/CodexActivityTokenUsage.swift)
- [`CodexActivityMonitor.swift`](../../CodexBar/Services/Workflow/CodexActivityMonitor.swift)
- [`CodexActivityTask.swift`](../../CodexBar/Services/Workflow/CodexActivityTask.swift)
- [`CodexActivitySubagentTracking.swift`](../../CodexBar/Services/Workflow/CodexActivitySubagentTracking.swift)
diff --git a/Docs/DeveloperGuide/architecture.md b/Docs/DeveloperGuide/architecture.md
index 15b2f3b..852cd0c 100644
--- a/Docs/DeveloperGuide/architecture.md
+++ b/Docs/DeveloperGuide/architecture.md
@@ -124,8 +124,8 @@ Hook handler 在 Codex 的关键路径上,它需要的是接近命令行工具
| 链路 | 输入 | 输出 | 主要消费者 |
| --- | --- | --- | --- |
| app-server | `codex app-server` JSON-RPC | 账户、额度、token 用量、Reset Credit 使用、Hook 配置能力 | 主面板、菜单栏额度、设置、自动重置状态机 |
-| Hook 历史 | Hook JSONL | 日级事件、session, turn, tool, model 聚合 | 活跃度热力图、历史统计、CloudKit |
-| 实时任务 | Hook 增量事件加 rollout 生命周期 | 运行、等待批准、完成、终止 | 菜单栏状态、任务中心、任务流光、通知、防睡眠 |
+| 历史统计 | Hook JSONL 与 rollout JSONL,分别读取和聚合 | 日级活动统计、线程轮次 Token 累计值及日汇总 | 热力图日期详情、历史统计、CloudKit |
+| 实时任务 | Hook 增量事件加 rollout 生命周期与轮次用量 | 运行、等待批准、完成、终止、本轮 Token | 菜单栏状态、任务中心、任务流光、通知、防睡眠 |
### 依赖方向
@@ -176,7 +176,9 @@ Hook + rollout --------> CodexActivityMonitor --------> UI
### Actor 服务
- `CodexStatusService` 管理 app-server 连接和刷新
-- `WorkflowService` 管理历史聚合
+- `WorkflowService` 协调 Hook 日聚合与 Token 历史快照
+- `CodexTokenHistoryStore` 管理 rollout 历史账本、读取游标和显式重建
+- `CodexTokenHistorySync` 管理轮次用量的 CloudKit 记录和缓存
- `HookEventTailReader` 管理 Hook 文件游标
- `CodexSessionLifecycleReader` 管理 rollout 文件游标
- `WorkflowSyncService` 管理 CloudKit 状态
@@ -223,6 +225,7 @@ Hook + rollout --------> CodexActivityMonitor --------> UI
| 任务中心 terminal 历史 | 10 分钟 | 提供近期上下文但不长期占用 UI |
| terminal 去重记忆 | 24 小时 | 防止迟到 Hook 或 rollout 复活旧任务 |
| Hook 原始和日聚合 | 210 天 | 支持长期统计和重建 |
+| Token 轮次账本 | 按最近记录时间保留 210 天,保留仍被子轮次引用的根记录 | 支持日汇总、增量续读和重建 |
| 日聚合身份明细 | 3 天 | 近期精确去重与隐私、文件体积折中 |
| Activity Protection 记录 | 最后进展后 24 小时 | 跨重启保持抑制,同时限制身份留存 |
diff --git a/Docs/DeveloperGuide/data-and-privacy.md b/Docs/DeveloperGuide/data-and-privacy.md
index 4acc3d5..75a818e 100644
--- a/Docs/DeveloperGuide/data-and-privacy.md
+++ b/Docs/DeveloperGuide/data-and-privacy.md
@@ -51,6 +51,7 @@ CodexBar 的最小化顺序是:
| app-server 账户、额度和 Reset Credits | 主面板、通知判断和用户启用的自动重置 | 仅短期状态 | 否 |
| Hook 结构化事件 | 历史聚合和实时任务 | 是,最长 210 天 | 只上传日聚合 |
| rollout 生命周期 | terminal 和进展对账 | 不单独持久化 | 否 |
+| rollout token 累计值 | 轮次去重和日汇总 | 哈希身份、时间和计数,210 天 | 用户启用同步后上传脱敏轮次累计值 |
| App 设置 | 功能开关和阈值 | UserDefaults | 否 |
| Activity Protection | 异常会话恢复 | 哈希身份,最长 24 小时 | 否 |
| CodexBarHelper ownership | 系统睡眠恢复 | root 状态文件 | 否 |
@@ -86,9 +87,11 @@ Hook 子进程从 rollout 首条 `session_meta` 的完整记录或已完成字
Hook recorder 通过 `transcript_path` 读取当前 rollout,`SubagentStop` 的来源使用子线程自身的 `agent_transcript_path`。实时活动 reader 访问 `$CODEX_HOME/sessions` 和 `$CODEX_HOME/archived_sessions` 中相关主线程及子线程的文件。
-这些读取只解析来源分类、线程及轮次归属、生命周期、时间、turn context、progress、effort 和 reviewer 等结构字段。线程关联只在内存中使用,对话正文不进入 CodexBar 存储或 UI。
+这些读取只解析来源分类、线程及轮次归属、生命周期、时间、turn context、progress、effort、reviewer 和 token 计数等结构字段。实时线程关联只在内存中使用;历史 token 账本仅保存哈希身份、必要时间和六项累计计数。对话正文不进入 CodexBar 存储或 UI。
-rollout reader 从文件尾部按预算扫描,一方面减少 I/O,另一方面降低无关历史内容进入进程内存的范围。解析 DTO 只声明所需字段,JSONDecoder 自动忽略其余内容。
+Token 历史扫描从文件起点建立轮次账本,再按游标增量读取。云端身份使用账户 salt 做 HMAC-SHA256,不上传原始线程或轮次 ID。字段和保留规则见 [Rollout Token 历史](sync.md#rollout-token-历史)
+
+实时 rollout reader 从文件尾部按预算扫描,一方面减少 I/O,另一方面降低无关历史内容进入进程内存的范围。解析 DTO 只声明所需字段,JSONDecoder 自动忽略其余内容。
### Reset Credits 明细
@@ -116,7 +119,18 @@ rollout reader 从文件尾部按预算扫描,一方面减少 I/O,另一方
daily.jsonl
maintenance.json
stats.lock
+ Tokens/
+ ledger.json
+ store.lock
+ rebuild.lock
Sync/
+ state.json
+ cache.jsonl
+ cursor.data
+ Tokens/
+ cache.json
+ store.lock
+ sync.lock
ActivityProtection/
state.json
```
@@ -126,13 +140,17 @@ rollout reader 从文件尾部按预算扫描,一方面减少 I/O,另一方
| `HookEvents/events` | 原始结构化 Hook 事件 | 210 天 |
| `HookEvents/daily.jsonl` | 日级聚合 | 210 天 |
| `HookEvents/maintenance.json` | 文件游标、generation 和维护状态 | 持续更新 |
-| `HookEvents/Sync` | CloudKit 缓存和游标 | 同步状态有效期间 |
+| `HookEvents/Tokens/ledger.json` | 哈希轮次身份、累计值、重建与恢复边界、文件读取游标 | 用量按最近记录时间保留 210 天;仍被保留子轮次引用的根记录一同保留 |
+| `HookEvents/Sync` | Hook 日聚合的云端缓存、游标和替换状态 | 同步状态有效期间 |
+| `HookEvents/Sync/Tokens/cache.json` | 账户域轮次记录、salt 和 CloudKit 游标 | 同步时清理过期轮次,保留仍被引用的根记录 |
| `ActivityProtection/state.json` | 哈希任务身份和时间戳 | 最后进展后最长 24 小时 |
最近 3 天的日聚合可以保留 session 和 turn ID 明细用于准确去重。更早数据只保留计数。
匿名任务不生成异常会话保护标识,因此不会写入 `ActivityProtection/state.json`
+Token 账本和同步缓存由 Debug 与 Release 共用。`store.lock` 保护对应目录中的文件读写;`rebuild.lock` 排斥并发 Token 重建,`sync.lock` 排斥并发 Token 同步。`stats.lock` 用于 Hook 聚合事务。锁文件本身不保存统计或进度。
+
### UserDefaults
UserDefaults 保存:
@@ -182,6 +200,8 @@ App 内 [`RequestLog.swift`](../../CodexBar/Services/CodexStatus/RequestLog.swif
- 不敏感计数
- 可定位模块的错误信息
+自动 rollout 回放在 `workflow` 分类记录文件数、读取字节数、剩余量、等待或不可读文件数及耗时,不记录文件路径、身份和用量。进度含义见 [Rollout Token 历史](sync.md#rollout-token-历史)
+
系统日志不应记录:
- OAuth token
@@ -196,7 +216,7 @@ App 内 [`RequestLog.swift`](../../CodexBar/Services/CodexStatus/RequestLog.swif
| 目标 | 用途 | 触发条件 |
| --- | --- | --- |
-| CloudKit private database | 同步日级 Hook 聚合 | 用户主动开启同步 |
+| CloudKit private database | 同步日级 Hook 聚合和脱敏轮次 token 累计值 | 用户主动开启同步 |
| Codex 服务(app-server 子进程) | 认证、额度、用量和 Reset Credit 消费 | 正式刷新、代理测试或自动重置 |
| Sparkle appcast 和更新资源 | 检查或安装更新 | 自动检查或用户手动检查 |
@@ -208,7 +228,7 @@ CodexBarHelper 不进行任何网络访问。
## CloudKit 边界
-CloudKit 只上传日级聚合字段:
+CloudKit 上传以下 Hook 日聚合字段:
- 设备 pseudonym
- 日期和 source generation
@@ -218,13 +238,15 @@ CloudKit 只上传日级聚合字段:
- model 计数
- 更新时间
+此外,token 历史上传账户内稳定的哈希轮次标识、根轮次关联、必要时间和六项累计计数,用于跨设备去重和按日汇总。
+
CloudKit 不上传:
- 原始 Hook JSONL
-- session, turn 或 agent ID
+- 原始 session, turn 或 agent ID
- 完整工作目录
- prompt, response, tool 参数或输出
-- Codex 账户、额度和 token 用量
+- app-server 的 Codex 账户、额度和账户 token 用量
- Reset Credits 明细、自动重置设置和消费状态
- access token
- App 请求日志
@@ -275,12 +297,14 @@ helper 的 ownership 文件不是用户偏好,而是 crash recovery 事务记
- 用包含明显标记字符串的 prompt 和 tool 参数运行任务,确认 Hook JSONL、App 日志和 CloudKit cache 均没有该字符串
- 让项目目录名包含敏感测试词,确认它只出现在允许的本地展示和 opt-in 聚合字段
- 模拟 Reset Credits 请求失败,确认 access token 不出现在内存日志和 unified log
-- 检查 CloudKit record 不包含 session, turn, agent ID 或完整路径
+- 检查 CloudKit record 不包含原始 session, turn, agent ID 或完整路径
- 以非 root 用户验证 helper 状态目录不可写
- 损坏各类缓存文件,确认系统降级或重建,而不是扩大到备用数据采集
## 关键源码
+- [`CodexTokenHistoryStore.swift`](../../CodexBar/Services/Workflow/CodexTokenHistoryStore.swift)
+- [`CodexTokenHistorySync.swift`](../../CodexBar/Services/Workflow/CodexTokenHistorySync.swift)
- [`WorkflowHookEventRecorder.swift`](../../CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift)
- [`WorkflowService.swift`](../../CodexBar/Services/Workflow/WorkflowService.swift)
- [`CodexSessionLifecycleReader.swift`](../../CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift)
diff --git a/Docs/DeveloperGuide/design-decisions.md b/Docs/DeveloperGuide/design-decisions.md
index 8c59d86..bd299ce 100644
--- a/Docs/DeveloperGuide/design-decisions.md
+++ b/Docs/DeveloperGuide/design-decisions.md
@@ -9,8 +9,8 @@
| 链路 | 状态来源 | 输出用途 |
| --- | --- | --- |
| app-server | 账户、额度和用量响应 | 周期性展示,同账户内可使用 stale 缓存 |
-| Hook 历史 | 原始 JSONL | 可重建的日级统计与跨设备同步 |
-| 实时任务 | Hook 增量事件与 rollout 生命周期 | 活动快照、任务通知和防睡眠 |
+| 历史统计 | Hook 事件与 rollout 用量分别维护 | 可重建的日级活动统计、线程轮次 Token 账本与跨设备同步 |
+| 实时任务 | Hook 增量事件与 rollout 生命周期、轮次用量 | 含本轮 Token 的活动快照、任务通知和防睡眠 |
快照可以反复读取;通知使用 live transition,bootstrap 只建立基线,不补发历史通知。历史聚合与额度刷新共享部分触发时机,但读取和失败处理独立。组件关系见 [整体架构](architecture.md)
@@ -50,10 +50,12 @@ Combine 的 `@Published` 在 `willSet` 发布。组合设置状态时使用订
Hook 原始 JSONL 是历史重建来源,日聚合是派生结果。聚合语义变化通过 schema 递增触发保留期内完整重建。文件替换由 `sourceGeneration` 区分,同日同源数据按替换合并,独立来源才累加。
+Token 账本以线程和轮次组成稳定身份,累计快照去重后按根轮次开始日汇总。显式重建先完成本机扫描,再提交所选日期的已读轮次;`rebuiltAt` 使更小的修正值优先于旧副本。缺失原始文件的轮次保留已有统计,其他设备的独有轮次保留在同步缓存中。字段和合并规则见 [Rollout Token 历史](sync.md#rollout-token-历史)
+
异常会话保护记录和 helper ownership 则用于恢复已经发生的状态变化。前者异步保存,隐藏不等待落盘;后者必须先持久化恢复责任,再修改系统睡眠值。具体顺序见 [实时任务监控](activity-monitor.md) 和 [防睡眠系统](sleep-prevention.md)
## 特权与上传范围
任务识别、自动重置策略和网络访问在主 App 中执行。root helper 只接受固定的睡眠租约与唤醒操作,通过签名校验客户端,并回读系统结果。
-CloudKit 只同步日级聚合。原始事件、会话标识、账户和代理密码留在本机;项目显示名属于上传内容,必须由用户开启同步。字段和存储范围见 [数据与隐私边界](data-and-privacy.md)
+CloudKit 同步日级活动聚合与脱敏的线程轮次 Token 记录。原始事件、原始会话标识、账户和代理密码留在本机;项目显示名属于上传内容,必须由用户开启同步。字段和存储范围见 [数据与隐私边界](data-and-privacy.md)
diff --git a/Docs/DeveloperGuide/development.md b/Docs/DeveloperGuide/development.md
index 4bb05af..b71aa46 100644
--- a/Docs/DeveloperGuide/development.md
+++ b/Docs/DeveloperGuide/development.md
@@ -30,6 +30,8 @@ swiftlint
| Hook 与 JSONL | 名称归一化、坏行隔离、元数据读取预算、半行补齐、bootstrap 与 live 分流、文件替换 |
| 实时任务 | 匿名身份、时长、乱序进展、子 Agent 计数、各执行归属独立的审批状态 |
| rollout 生命周期 | 完成与进展、读取覆盖、损坏行、文件丢失或替换、归档定位 |
+| 本轮 Token | 计数校验、主子线程归属与去重、运行中更新、结束后补读、轮次隔离、溢出和零值 |
+| Token 历史 | 跨午夜归属、增量续读、回放日志、重建降低或清除计数、缺失文件保留、云端修正恢复、取消与跨实例锁 |
| 聚合与同步模型 | ID 去重、事件对计数、缺失计数、增量与重放一致性、同设备 generation 去重 |
| 持久化与设置 | 保护记录过期、跨实例合并、条件删除、旧记录默认值、配置损坏与回填 |
| 额度、代理与展示 | 凭证筛选、稳定 UUID、实际运行版本、代理输入和环境变量、日期与热力图状态 |
@@ -48,7 +50,8 @@ swiftlint
| 实时任务与异常保护 | `CodexActivityMonitor` 和 readers | [实时任务监控](activity-monitor.md) |
| 防睡眠与系统唤醒 | `KeepAliveController`、`AutoResetWakeScheduler`、helper | [防睡眠系统](sleep-prevention.md) |
| 通知与音效 | `CodexNotificationService`、通知 Settings | [通知系统](notifications.md) |
-| 同步 | `WorkflowSyncService` 与 scheduler | [CloudKit 同步](sync.md) |
+| Token 历史与同步 | `CodexTokenHistoryStore`、`CodexTokenHistorySync` 与 `CodexTokenTurn` | [Rollout Token 历史](sync.md#rollout-token-历史) |
+| Hook 同步 | `WorkflowSyncService` 与 scheduler | [CloudKit 同步](sync.md) |
| 菜单、窗口、快捷键 | `Controllers` 与对应 View | [UI 与应用生命周期](ui-and-lifecycle.md) |
长期对象由 `CodexBarAppDelegate` 装配。新增状态优先放入现有所有者,View 消费快照并发出操作意图。源码阅读入口见 [整体架构](architecture.md)
@@ -83,6 +86,7 @@ swiftlint
| 通知 | 授权拒绝与恢复、阈值跨越、同周期去重、任务恢复撤回、声音缺失 |
| 代理 | 首次配置、启停、无效配置停用、损坏记录删除、测试取消、快速操作与失败回滚 |
| 同步 | 首次上传、多设备合并、断网续传、部分上传失败、重建替换、iCloud 账户切换 |
+| Token 回放与重建 | 大量历史断点续读、后台重建时使用主面板、关闭设置窗口、退出后自动回放与手动重建的区别、修正值跨设备收敛 |
| 系统电源与 helper | 首次授权、任务运行/等待切换、低电量、时长上限、外部睡眠来源、异常退出与重启 |
| 自动重置唤醒 | 计划替换、关闭与退出清理、连接中断、helper 重启、注销前清零、到点重新读取 |
diff --git a/Docs/DeveloperGuide/sync.md b/Docs/DeveloperGuide/sync.md
index 83d9bb2..254553a 100644
--- a/Docs/DeveloperGuide/sync.md
+++ b/Docs/DeveloperGuide/sync.md
@@ -4,9 +4,9 @@
## 同步范围
-CloudKit 同步用于在同一 iCloud 账户的 Mac 之间合并 Hook 日级统计。
+CloudKit 同步用于在同一 iCloud 账户的 Mac 之间合并 Hook 日级统计和 rollout Token 用量。
-同步对象是聚合结果,不是原始 Hook 事件:
+Hook 同步以日聚合为单位:
```text
本机原始 Hook JSONL
@@ -16,11 +16,11 @@ CloudKit 同步用于在同一 iCloud 账户的 Mac 之间合并 Hook 日级统
-> 按日期合并展示
```
-账户、额度、token 总量、Reset Credits、自动重置设置与状态、实时任务和防睡眠状态不参与同步。
+app-server 账户、额度、账户 token 总量、Reset Credits、自动重置设置与状态、实时任务和防睡眠状态不参与同步。
## 数据来源
-同步展示同时使用 3 类值:
+Hook 日聚合展示同时使用 3 类值。Token 轮次账本及其云端缓存见 [Rollout Token 历史](#rollout-token-历史)
| 数据 | 权威来源 | 断网时行为 |
| --- | --- | --- |
@@ -42,6 +42,7 @@ CloudKit 同步用于在同一 iCloud 账户的 Mac 之间合并 Hook 日级统
| Custom zone | `CodexBarZone` |
| 元数据 record type | `CodexBarSyncMetadata` |
| 日聚合 record type | `CodexBarDailyAggregate` |
+| Token 轮次 record type | `CodexBarTokenTurn` |
private database 中的数据只属于当前 iCloud 账户,不写入 public database。
@@ -96,12 +97,43 @@ salt 存在同一个 private custom zone 中。多台设备先后创建时通过
- 完整工作目录
- prompt 或 response 内容
- Codex 账户和额度
-- token 或 `auth.json` 等
+- 认证 token 或 `auth.json` 等凭证
- App 请求日志
- 异常会话保护状态
更完整的数据边界见 [数据与隐私边界](data-and-privacy.md)
+## Rollout Token 历史
+
+Token 历史使用同一 private zone 中独立的 `CodexBarTokenTurn` 记录,schema 为 `1`。一条记录对应一个线程轮次,同一轮的累计快照更新原记录,不按设备相加。主线程和子线程分别计数,子线程归入根轮次开始日。日期按查看设备的本地时区计算。
+
+本地轮次标识先对线程和轮次 ID 做 SHA-256,再使用账户 salt 做 HMAC-SHA256,生成云端标识。不同设备读取同一份 rollout 时生成相同记录名,缓存和本地数据也按该标识去重。记录不包含原始 session、turn 或 agent ID。
+
+云端字段如下,发布环境需要在 CloudKit Console 部署该记录类型及字段:
+
+| 字段 | 类型 | 内容 |
+| --- | --- | --- |
+| `schemaVersion` | Int64 | `1` |
+| `rootID` | String | 根轮次的账户域哈希 |
+| `startedAt` | Date | 轮次开始时间,可缺失 |
+| `observedAt` | Date | 最近累计记录的时间 |
+| `rebuiltAt` | Date | 可选的显式重建时间,用于拒绝旧统计回流 |
+| `usage` | Bytes | 六项 token 整数的 JSON,可缺失 |
+
+记录名直接使用轮次哈希,保持稳定;数据格式版本由 `schemaVersion` 字段管理。缺少 `usage` 的记录不贡献用量:根记录可用于确定子轮次日期,带 `rebuiltAt` 的记录可用于清除该轮旧计数。上传前读取服务端记录,保留更完整的累计快照,使用 `ifServerRecordUnchanged` 条件写入;并发冲突留待下一轮重新获取、合并和重试。不会把多个累计快照相加,也不会对输入、缓存和输出字段分别拼接最大值。
+
+显式重建扫描本机保留期内的 rollout,按根轮次开始日筛选结果,只更新所选日期重新读到的轮次。本地 `rebuild.lock` 防止多个进程同时重建;扫描时不持有账本锁,每批读取后让出执行机会,完整成功后加锁提交。读取开始后的活跃轮次进展保留,原始文件缺失的旧轮次不删除。失败或取消保留提交前账本,App 退出后不自动续跑这次手动重建。
+
+需要同步的重建记录携带 `rebuiltAt`。合并优先选择较新的重建结果,再在同一次重建内保留完整累计值,允许显式修正为更小的计数。正常增量读取继承本地轮次的重建时间。本地账本恢复或云端存在更新的重建结果时,只对账户与根轮次身份匹配的本地轮次恢复云端基线。已读取的文件按每轮读取预算重新扫描,恢复边界之前的用量保留云端修正值,之后的累计记录继续更新。恢复边界与读取游标保存在本地账本,重启后继续补读,不导入其他机器独有的轮次。重建后没有用量的旧轮次仍可同步,以清除云端旧计数;其他轮次和其他机器独有的记录不受影响。
+
+日汇总累加去重后的线程轮次,缓存命中率使用日缓存命中总量除以日输入总量。热力图颜色和账户用量来自 app-server,与 rollout 用量独立。热力图日期详情将缺失用量显示为 `0`,缓存命中率显示为 `0%`;存储与同步仍保留缺失状态。
+
+本地账本位于 `HookEvents/Tokens/ledger.json`,保存哈希身份、累计值、开始时间和文件读取游标。独立文件锁协调 Debug 和 Release。同步缓存与游标位于 `HookEvents/Sync/Tokens/cache.json`,记录按账户校验,Debug 和 Release 共用。整轮同步由非阻塞 `sync.lock` 协调,独立文件锁保护缓存读写,界面读取不等待网络。Hook 日聚合使用独立的存储与同步记录。
+
+历史扫描覆盖 `$CODEX_HOME/sessions` 和 `$CODEX_HOME/archived_sessions` 中最近 210 天内修改的 `rollout-*.jsonl` 文件,单轮读取预算为 64 MiB,最多额外读完一条 1 MiB 内的记录。超出预算的历史在后续维护中继续补读。同批尚未读取的文件优先处理最近修改的会话,再逐步补齐更早历史。正文大行有界跳过,半行等待下一轮补齐;文件替换、截断或读取边界改变时重新扫描,已知累计用量不会再次叠加。轮次按 `updatedAt` 保留 210 天,仍被保留子轮次引用的根记录一同保留;日汇总只展示根轮次开始日位于保留期内的数据。原始 rollout 缺失或没有 `token_usage_record` 时无法补出用量。
+
+自动回放每批提交后在 `workflow` 系统日志输出进度,包括已追平文件数、字节进度、本轮读取量、剩余量、等待完整行的文件数、不可读文件数和耗时。全部文件追平后输出一次“Rollout 回放完成”;正常增量追加和位置不变的等待不重复输出。完成状态只表示本轮检查范围内的本地文件已读完,不表示 iCloud 已同步。日志不包含文件路径、会话身份、正文或 token 用量。
+
## 一次同步的阶段
```text
@@ -111,8 +143,9 @@ salt 存在同一个 private custom zone 中。多台设备先后创建时通过
-> 按设备身份和 schema 更新本地状态
-> 拉取远端变更到缓存,处理待替换日期
-> 上传当前设备变化日期
- -> 再次拉取远端变更到缓存
- -> 清理超过保留期的记录
+ -> 再次拉取 Hook 远端变更到缓存
+ -> 拉取、上传并清理 Token 轮次记录
+ -> 清理当前设备超过保留期的 Hook 记录
-> 保存状态并发布合并结果
```
@@ -123,7 +156,7 @@ salt 存在同一个 private custom zone 中。多台设备先后创建时通过
- 上传后再次拉取,才能把本轮写入和其他设备并发写入统一进本地缓存
- 最后清理过期记录,避免清理失败阻断本轮有效数据上传
-每个阶段都写入日志中的 `stage`,失败信息因此能回答问题发生在 zone, device, fetch, upload 还是 prune,而不只得到一个笼统的 CloudKit error:
+每个阶段都写入日志中的 `stage`,失败信息会标明 `zone`、`device`、`fetch`、`upload`、`tokens` 或 `prune` 阶段:
- 上传每批最多 25 条记录
- 每轮上传按 20 秒预算决定是否启动下一批
@@ -136,7 +169,7 @@ salt 存在同一个 private custom zone 中。多台设备先后创建时通过
上传使用 `atomically: false`,远端允许单批部分成功。但只要该批出现错误,调用方就移除整批日期的本地确认 hash,下轮重新检查这一批。此前已完成批次的确认保留,远端已成功写入的记录不回滚。
-## 合并语义
+## Hook 日聚合的合并语义
同一天可能有多个设备记录,也可能有当前设备尚未上传的最新本地结果。
@@ -180,7 +213,7 @@ CloudKit 解码及持久化模型保留可选计数字段。本地与远端聚
CloudKit 使用可选整数字段 `interruptCount` 保存中断次数。同日合并的任一贡献缺少该字段时,中断次数合计保持不可用。
-## 来源替换与重建
+## Hook 来源替换与重建
用户执行重新扫描时:
@@ -221,7 +254,7 @@ replacement 删除前全量拉取当前设备同日记录,覆盖本地增量
| `cache.jsonl` | 远端设备日聚合缓存 |
| `cursor.data` | CloudKit zone change token |
-当前 CloudKit record schema 为 `6`。本地同步状态 schema 为 `4`,能读取上一版 schema `3`
+Hook 日聚合的 CloudKit record schema 为 `6`。本地同步状态 schema 为 `4`,能读取上一版 schema `3`
3 个文件有不同的可恢复等级:
@@ -299,12 +332,17 @@ CloudKit 记录保留期与本地 Hook 历史一致,最长 210 天:
- 关闭同步后只显示本地统计
- iCloud 未登录时显示明确状态,本地统计继续工作
- 网络断开后使用最后缓存,恢复后完成增量同步
-- 本机重建后只替换当前设备记录
+- 本机重建后只替换当前设备的 Hook 记录与本机重新读到的 Token 轮次
+- Token 重建可降低或清除计数;其他设备刷新后收敛,旧缓存不会恢复旧计数
+- 缺失 rollout 时保留已知轮次;本地账本恢复后,旧文件回放不覆盖云端修正值
+- 同一轮次的文件副本及跨设备副本只计一次,主线程与子线程按根轮次开始日归属
- 超过 210 天的本地和远端缓存被清理
- iCloud 账户切换后不显示前一账户缓存
## 关键源码
+- [`CodexTokenHistoryStore.swift`](../../CodexBar/Services/Workflow/CodexTokenHistoryStore.swift)
+- [`CodexTokenHistorySync.swift`](../../CodexBar/Services/Workflow/CodexTokenHistorySync.swift)
- [`WorkflowSyncService.swift`](../../CodexBar/Services/Workflow/WorkflowSyncService.swift)
- [`WorkflowSyncScheduler.swift`](../../CodexBar/Services/Workflow/WorkflowSyncScheduler.swift)
- [`WorkflowSyncSettings.swift`](../../CodexBar/Services/Settings/WorkflowSyncSettings.swift)
diff --git a/Docs/DeveloperGuide/ui-and-lifecycle.md b/Docs/DeveloperGuide/ui-and-lifecycle.md
index 3620bc1..7d939af 100644
--- a/Docs/DeveloperGuide/ui-and-lifecycle.md
+++ b/Docs/DeveloperGuide/ui-and-lifecycle.md
@@ -200,6 +200,12 @@ fallback panel 在展示前根据 SwiftUI fitting size 和目标屏幕可见区
主面板可见时,数字随数据变化滚动,Token 数字与待查询或不可用占位之间淡入淡出。“动画效果”控制入场动画、太阳徽标旋转和任务状态文字动画,数字更新不受此开关控制。
+活动卡片的 Token 区域仅在 `primaryActivity.tokenUsage` 可用时出现,七项等宽居中,分割线随区域一起显示。可用性变化触发卡片高度和主面板尺寸动画,独立于“动画效果”设置。Popover 在内容尺寸更新前临时启用 `animates`;fallback 等待 `@Published` 完成赋值后测量,并保持顶边位置。
+
+Hook 开启时,热力图详情采用两栏:顶部 10 格强度条通栏,左侧活动统计,右侧会话 Token。每栏用 `Grid` 按最长标签确定统一名称宽度,数值使用剩余空间。日期切换时,Token 与活动数值使用相同的 `numericText` 过渡,最常用模型使用同一文本视图过渡并按可用宽度缩小字号。
+
+共享 `LiquidGlassDivider` 使用银灰和冷白渐变,按 8 秒周期缓慢移动。它通过所在 `NSView` 的窗口可见状态暂停或恢复时间线,不受“动画效果”设置控制。
+
相关控制器包括:
- [`HeatmapDetailPanelController.swift`](../../CodexBar/Controllers/HeatmapDetailPanelController.swift)
@@ -339,6 +345,10 @@ app-server 状态默认每 60 秒检查刷新。主面板的 0.24 秒淡入完
- 面板打开刷新不会造成动画卡顿或重复请求
- 数字首次递减、连续增减、Token 单位切换和日期跨月时方向正确,主面板关闭后停止数字动画
+- 中英文下快速切换热力图日期,名称列宽稳定,Token 数字和模型名原位过渡
+- Token 区域从无到有、由有到无时,popover 和 fallback 尺寸平滑变化;关闭动画设置后仍保留此效果
+- 所有共享分割线缓慢流动,关闭或隐藏所属窗口后停止持续绘制
+
## 关键源码
- [`CodexBarAppDelegate.swift`](../../CodexBar/Controllers/CodexBarAppDelegate.swift)
diff --git a/Docs/UserGuide/activity-and-hook.md b/Docs/UserGuide/activity-and-hook.md
index 9a726ee..973de65 100644
--- a/Docs/UserGuide/activity-and-hook.md
+++ b/Docs/UserGuide/activity-and-hook.md
@@ -2,7 +2,7 @@
简体中文 | [English](../en/UserGuide/activity-and-hook.md)
-CodexBar Hook 用于显示实时任务,并支持任务通知、触觉反馈、按任务防睡眠,以及每日会话、轮次和工具调用统计。开启后也可以同步或重建这些每日统计。
+CodexBar Hook 用于显示实时任务,并支持任务通知、触觉反馈、按任务防睡眠,以及每日会话、轮次和工具调用统计。开启后也可以同步每日活动统计和 rollout Token 历史;重建数据可重新计算本机保留的两类历史。
## 开启方法
@@ -37,13 +37,13 @@ CodexBar 自动检查和修复已开启的 Hook 配置,保留用户和其他 A
## 每日统计
-在主面板热力图上悬停日期,可查看当天的会话数、对话轮次、工具调用、权限请求、上下文压缩、子 Agent 和最常用模型。
+在主面板热力图上悬停日期,左栏显示当天的会话数、对话轮次、工具调用、权限请求、上下文压缩、子 Agent 和最常用模型,右栏显示会话 Token 汇总。Token 按根轮次开始日累计,与活动计数的按日归属方式不同。详见 [Token 用量与热力图](main-panel.md#token-用量与热力图)
会话和轮次按天去重,跨天继续活动会计入新的一天。当天只有会话结束事件的会话,以及只有完成候选或中断事件的轮次,不计入当天活跃数。工具调用按开始和结束事件数的较大值统计。
## 关闭 Hook
-关闭后,实时任务、任务通知、触觉反馈、防睡眠、Hook 统计及其跨设备同步停止更新。账户、额度和 Token 热力图仍可使用。
+关闭后,实时任务、任务通知、触觉反馈、防睡眠和 Hook 统计停止更新,活动与 Token 历史的跨设备同步停止。热力图隐藏两栏历史详情,账户、额度和 app-server Token 热力图仍可使用。
Hook 记录任务的时间、模型、工具名和项目等信息,不保存提问、回复或工具输入输出正文。保存期限与同步内容见 [数据、同步与隐私](sync-data-privacy.md)
diff --git a/Docs/UserGuide/main-panel.md b/Docs/UserGuide/main-panel.md
index 2e990e8..fce9884 100644
--- a/Docs/UserGuide/main-panel.md
+++ b/Docs/UserGuide/main-panel.md
@@ -53,6 +53,8 @@ CodexBar 会展示 Codex 返回的全部额度分组和窗口。
开启 `动画效果` 时,分段进度条会在每次打开主面板时从零填充到当前剩余比例。
+玻璃分割线的渐变会缓慢流动,独立于 `动画效果` 开关;所在窗口隐藏后暂停。
+
主额度分组还可能展示以下信息:
- 可用积分或无限积分状态
@@ -63,7 +65,7 @@ CodexBar 会展示 Codex 返回的全部额度分组和窗口。
## Token 用量与热力图
-汇总区域会展示以下指标:
+账户用量来自 app-server,汇总区域会展示以下指标:
- 全时累计 Token
- 单日 Token 峰值
@@ -77,7 +79,7 @@ CodexBar 会展示 Codex 返回的全部额度分组和窗口。
悬停日期方块时会显示日期、Token 数量和用量强度。
-CodexBar Hook 开启且当天有数据时,日期详情还会显示以下统计:
+CodexBar Hook 开启时,日期详情还会显示以下统计:
- 最常用模型
- 会话数
@@ -87,6 +89,12 @@ CodexBar Hook 开启且当天有数据时,日期详情还会显示以下统计
- 权限请求次数
- 上下文压缩次数
+日期详情采用两栏布局:用量强度以 10 格强度条横跨顶部,左栏显示上述活动统计,右栏显示 rollout 的日 Token 汇总,依次为总量、输入、输出、缓存命中、缓存写入、缓存命中率和推理输出。两栏各项指标前显示彩色圆点。每栏名称区域按该栏最长名称统一宽度,其余空间用于右对齐的模型名和数值。Token 数量使用 K/M/B 缩写,缺失计数和零值均显示 `0`,缺失或为零的缓存命中率显示 `0%`。切换日期时,活动统计、Token 数字和最常用模型使用滚动切换动画。
+
+每个线程轮次只计一次,主 Agent 和子 Agent 的用量归到根任务开始日期,跨午夜也不拆分。缓存命中率用当日缓存命中总量除以输入总量计算。启用 iCloud 同步后,各 Mac 的同一轮记录先去重再汇总。
+
+热力图颜色、日期标题旁的 Token 数量和用量强度来自 app-server,右栏会话 Token 来自本地 rollout 及 iCloud 历史,两者的来源和统计范围不同。历史回放、续读和重建方式见 [数据、同步与隐私](sync-data-privacy.md#历史-token-回放)
+
## 活动卡片
活动卡片优先显示等待批准,其次是运行中任务。没有活跃任务时,显示结束时间最新的完成或终止记录;时间相同优先显示终止。
@@ -109,6 +117,14 @@ CodexBar Hook 开启且当天有数据时,日期详情还会显示以下统计
点击有内容的活动卡片可以打开任务中心。活动卡片和任务中心的状态文字颜色随任务状态变化。开启“动画效果”时,运行状态文字播放扫光,等待批准文字周围显示橙色粒子;关闭后保留静态彩色文字。
+### 本轮 Token 用量
+
+活动卡片取得本轮 rollout 用量后,在状态下方显示一排七项指标:总量、输入、输出、缓存命中、缓存写入、缓存命中率、推理输出。各项等宽居中,数量使用 K/M/B 缩写。用量区域和上方分割线一起展开或收起,动画不受 `动画效果` 开关控制。没有用量时隐藏整个区域。
+
+运行中和等待批准时,已能确认归属的主线程与子 Agent 用量会持续更新;后续线程记录到达后继续补齐。完成或终止后会短暂补读本轮用量,取得完整汇总后显示。之后读取暂时失败时,保留已经取得的结束用量。这里统计的是当前对话轮次及其子 Agent,而非整个会话。
+
+总量等于输入加输出;缓存命中和缓存写入包含在输入中,推理输出包含在输出中,不能再次加到总量上。缓存命中率为缓存命中除以输入;输入为零时,卡片显示 `—`。英文标签 `Cached`、`Cache-W` 和 `Cache-H` 分别表示缓存命中、缓存写入和缓存命中率。
+
## 任务中心
任务中心按状态分组展示以下内容:
@@ -120,6 +136,8 @@ CodexBar Hook 开启且当天有数据时,日期详情还会显示以下统计
最近完成和最近终止记录保留 10 分钟。完成表示一轮任务结束,不代表执行成功;终止记录包括中断及其他终止情况,不触发完成通知。
+最近完成和最近终止条目在有用量数据时显示本轮总 Token,使用 K/M/B 缩写。运行中和等待批准条目只显示任务状态;主面板活动卡片显示当前摘要任务的用量。
+
## 底部状态
主面板底部包含以下信息:
diff --git a/Docs/UserGuide/settings.md b/Docs/UserGuide/settings.md
index 287c752..267fdb5 100644
--- a/Docs/UserGuide/settings.md
+++ b/Docs/UserGuide/settings.md
@@ -60,8 +60,8 @@ Hook 不可用时隐藏光带并保留开关选择。系统睡眠、屏幕休眠
| [系统通知](notifications.md) | 配置通知类型、阈值、音效和触觉反馈 | 总开关关闭 |
| 自动重置 | 提前使用即将过期的留存重置 | 关闭,提前 30 分钟 |
| [防止系统睡眠](sleep-prevention.md) | 在符合条件的任务运行时保持 Mac 唤醒 | 关闭 |
-| [跨设备同步](sync-data-privacy.md) | 通过 iCloud 合并每日 Hook 统计 | 关闭 |
-| [重建数据](sync-data-privacy.md#重建数据) | 重新计算所选日期的 Hook 统计 | 手动操作 |
+| [跨设备同步](sync-data-privacy.md) | 通过 iCloud 合并每日活动统计和会话 Token 用量 | 关闭 |
+| [重建数据](sync-data-privacy.md#重建数据) | 在后台重新计算所选日期的活动统计和会话 Token 用量 | 手动操作 |
### 代理
diff --git a/Docs/UserGuide/sync-data-privacy.md b/Docs/UserGuide/sync-data-privacy.md
index b4d03c6..3bc5ca4 100644
--- a/Docs/UserGuide/sync-data-privacy.md
+++ b/Docs/UserGuide/sync-data-privacy.md
@@ -4,7 +4,7 @@
## 跨设备同步
-在 `设置 > 高级` 开启 `跨设备同步`,可以合并同一 iCloud 账户下多台 Mac 的每日 Hook 统计。需要先开启 CodexBar Hook,并登录可用的 iCloud 账户。
+在 `设置 > 高级` 开启 `跨设备同步`,可以合并同一 iCloud 账户下多台 Mac 的每日 Hook 统计和 rollout Token 用量。需要先开启 CodexBar Hook,并登录可用的 iCloud 账户。
首次开启会上传本机保留期内的统计,之后自动同步变化。关闭同步会保留本机数据。
@@ -19,13 +19,13 @@
## 哪些数据会上传
-同步数据保存在你的 iCloud 私有数据库中,包括日期、每日事件和会话统计、项目显示名、模型名,以及用于区分设备和避免重复计数的标识。
+同步数据保存在你的 iCloud 私有数据库中,包括日期、每日事件和会话统计、项目显示名、模型名,以及用于区分设备和避免重复计数的标识。Token 历史另行同步脱敏轮次标识、必要时间和六项累计计数,用于跨设备去重后计算日汇总。
以下内容不参与同步:
- 原始 Hook 事件、会话和任务标识、完整工作目录
- 提问、Codex 回复、工具参数和输出
-- Codex 账户、额度、Token 用量和留存重置
+- Codex 账户、额度、app-server 账户用量和留存重置
- App 设置、代理配置和密码
- 日志、实时任务状态和异常会话保护记录
@@ -36,6 +36,7 @@
| 数据 | 内容与保留方式 |
| --- | --- |
| Hook 记录与每日统计 | 时间、事件、模型、工具、项目和任务标识等,保留 210 天;每日统计中的会话和轮次明细仅保留最近 3 天 |
+| rollout Token 历史 | 哈希轮次标识、开始时间、累计计数和读取游标,保留 210 天;仍被子轮次引用的根时间一同保留 |
| 异常会话保护 | 无法直接还原的任务标识和时间,最长保留到最后进展后的 24 小时 |
| App 设置 | 保存在当前 Mac,包括代理配置;代理密码以明文保存 |
| 交互日志 | 最近 500 条 Codex 请求和响应,只在本次运行期间保留 |
@@ -45,11 +46,23 @@ CodexBar 读取本机 Codex 的任务状态和活动记录,但不保存提问
关闭代理会保留配置和密码;保存关闭身份验证的配置或选择 `删除配置` 时会删除密码。
+## 历史 Token 回放
+
+App 在历史统计刷新时自动读取本机 Codex 的 rollout,逐步补全保留期内的轮次用量,无需手动重建。每批保存用量和读取位置;退出后再次打开,会从保存的位置继续。追平历史后,后续刷新按读取位置处理追加内容。文件被替换或截断时会重新读取,同一线程轮次仍只计一次。
+
+历史很多时可能需要多轮刷新才能补全。回放进度写入系统日志的 `workflow` 分类,读完当前检查范围内的文件后记录 `Rollout 回放完成`。这个状态表示本地回放进度,云端传输状态在同步区域查看。
+
+日用量按根轮次开始时间和查看设备的本地时区归属。原始 rollout 已缺失或没有记录用量时,无法补出对应计数。
+
## 重建数据
-统计异常时,可在 `设置 > 高级 > 重建数据` 选择日期范围并确认。可选范围为最近 210 天,有本机记录的日期会显示标记。
+统计异常时,可在 `设置 > 高级 > 重建数据` 选择日期范围并确认。可选范围为最近 210 天,有本机 Hook 记录或已发现 Token 轮次的日期会显示标记;未标记的日期也可以选择。
+
+重建使用保留的本机 Hook 事件和 rollout,重新计算所选日期的活动统计与 Token 用量。Token 按根轮次开始日期归属,同一轮及其子线程不会重复累计。日期没有 Hook 事件时,也可以重建本机 rollout 中的 Token 数据。
+
+重建在后台运行,可以继续使用主面板或关闭设置窗口。Token 按批读取,扫描完整成功后一次更新;取消或读取失败不会发布部分结果。退出 App 会停止本次重建,未完成的 Token 重建需要重新发起。完成后显示处理日期、活动记录和 Token 轮次数量。
-重建使用保留的本机记录重新计算 Hook 统计,完成后显示处理结果。开启同步时,重建结果会替换当前设备对应日期的云端统计,其他设备的贡献保留。账户、额度和 Token 用量不受影响。
+开启同步时,重建结果会替换当前设备对应日期的活动统计,以及本机重新读到的 Token 轮次记录;其他轮次保留。重建可以降低 Token 计数;重新读到轮次但没有用量记录时,会清除该轮旧计数并同步到云端。本机已经缺失 rollout 的轮次保留已有统计,不会因此删除云端记录。账户信息、额度和 app-server 的账户用量不受影响。
## 网络与日志
@@ -57,7 +70,7 @@ CodexBar 读取本机 Codex 的任务状态和活动记录,但不保存提问
| --- | --- |
| Codex 服务 | 获取账户、额度和用量,执行自动重置 |
| 更新服务 | 检查并下载 CodexBar 更新 |
-| iCloud | 开启同步后传输每日 Hook 统计 |
+| iCloud | 开启同步后传输每日 Hook 统计和会话 Token 数据 |
代理只用于 CodexBar 的 Codex 服务连接,不影响更新、iCloud 或其他 App。
diff --git a/Docs/en/DeveloperGuide/activity-monitor.md b/Docs/en/DeveloperGuide/activity-monitor.md
index 626ec8b..4fd4f88 100644
--- a/Docs/en/DeveloperGuide/activity-monitor.md
+++ b/Docs/en/DeveloperGuide/activity-monitor.md
@@ -4,14 +4,15 @@
## Goals
-The live-task flow answers four questions:
+The live-task flow answers these questions:
- Is a task currently running?
- Is a task waiting for user approval?
- Did a recent task complete or terminate?
- Which running tasks have made no progress for too long?
+- How many tokens have the current turn and its subagents used?
-Hook events provide live progress and interruption signals, while rollout files supply lifecycle context. [`CodexActivityMonitor.swift`](../../../CodexBar/Services/Workflow/CodexActivityMonitor.swift) merges both into the sole task snapshot:
+Hook events provide live progress and interruption signals, while rollout files supply lifecycle context and turn token usage. [`CodexActivityMonitor.swift`](../../../CodexBar/Services/Workflow/CodexActivityMonitor.swift) merges both into the sole task snapshot:
```text
Codex Hook -> WorkflowHookEventRecorder -> Hook JSONL
@@ -207,6 +208,28 @@ The shared `CodexRolloutLineEnvelope` extracts only fields needed for turn conte
Terminal resolution requires a nonempty `payload.turn_id` and a `complete` current read. With outer `type = "event_msg"`, `payload.type` equal to `task_complete` or `turn_complete` confirms completion. Completion time prefers a valid `payload.completed_at` in Unix seconds, falling back to outer `timestamp` when absent or invalid; neither being usable leaves completion unconfirmed. `payload.type = "turn_aborted"` confirms interruption. A finite, nonnegative `payload.duration_ms` is converted to seconds for duration display. A missing interruption timestamp uses reconciliation time for an active task or removal time for a pending task, never earlier than its last activity.
+## Token Usage for the Current Turn
+
+`CodexSessionLifecycleReader` reads `payload.turn_token_usage` from records whose outer `type` is `token_usage_record`. These are cumulative thread-turn snapshots, so successive snapshots are not added together. `event_msg/token_count` supplies progress signals, not turn usage.
+
+| Display metric | `turn_token_usage` field or calculation |
+| --- | --- |
+| Total | `total_tokens`, equal to input plus output |
+| Input | `input_tokens`, including cache hits and writes |
+| Output | `output_tokens`, including reasoning |
+| Cached | `cached_input_tokens` |
+| Cache write | `cache_write_input_tokens` |
+| Cache hit rate | `cached_input_tokens / input_tokens`; undefined when input is zero |
+| Reasoning | `reasoning_output_tokens` |
+
+All six counters must be present and nonnegative. Total must equal input plus output, cache hits plus writes must not exceed input, and reasoning must not exceed output. Parsing also validates the identities and ownership in `thread_id`, `session_id`, `turn_id`, `root_turn_id`, and `response_id`. Missing fields or failed validation produce no usage. Zero cache-write or reasoning counts in valid records are displayed as zero.
+
+`CodexActivityTokenUsage.swift` collects main and associated child-thread references for the root task, deduplicating by thread and turn. While running, it sums matching threads with complete current reads; threads without usage wait for later refreshes. The displayed value may therefore be a subtotal of known threads. The live card reads the in-memory task snapshot, not historical daily totals or iCloud caches.
+
+Completed and terminated records start without usage and receive it through terminal rereads. Rereading lasts up to 30 seconds, scheduled every 2 seconds for at most 16 pending tasks per batch. Final aggregation requires all expected child identities and thread usage, with child threads ended. Once terminal usage has been obtained, later incomplete reads preserve that value. Late child associations join only their root turn, without affecting subsequent turns. Terminal state, notifications, and sleep-prevention release do not wait for token rereads.
+
+Historical replay uses its own ledger and read cursors. See [Rollout Token History](sync.md#rollout-token-history).
+
## Task Identity
The task key chooses the most precise available identity:
@@ -566,6 +589,7 @@ Task progress invalidates its protection attempt. Reader, bootstrap, and recover
## Key Source Files
+- [`CodexActivityTokenUsage.swift`](../../../CodexBar/Services/Workflow/CodexActivityTokenUsage.swift)
- [`CodexActivityMonitor.swift`](../../../CodexBar/Services/Workflow/CodexActivityMonitor.swift)
- [`CodexActivityTask.swift`](../../../CodexBar/Services/Workflow/CodexActivityTask.swift)
- [`CodexActivitySubagentTracking.swift`](../../../CodexBar/Services/Workflow/CodexActivitySubagentTracking.swift)
diff --git a/Docs/en/DeveloperGuide/architecture.md b/Docs/en/DeveloperGuide/architecture.md
index 50cbb2c..6f38c9c 100644
--- a/Docs/en/DeveloperGuide/architecture.md
+++ b/Docs/en/DeveloperGuide/architecture.md
@@ -124,8 +124,8 @@ Three data flows manage distinct inputs, freshness requirements, and failure sta
| Flow | Input | Output | Main consumers |
| --- | --- | --- | --- |
| app-server | `codex app-server` JSON-RPC | Account, rate limits, token usage, Reset Credit use, Hook configuration capabilities | Main panel, menu bar rate limit, Settings, Automatic Reset state machine |
-| Hook history | Hook JSONL | Daily event, session, turn, tool, and model aggregations | Activity heatmap, historical metrics, CloudKit |
-| Live tasks | Incremental Hook events plus rollout lifecycle | Running, waiting for approval, completed, terminated | Menu bar status, Task Center, task glow, notifications, sleep prevention |
+| Historical statistics | Hook JSONL and rollout JSONL, read and aggregated separately | Daily activity metrics, cumulative thread-turn tokens, and daily token totals | Heatmap date details, historical metrics, CloudKit |
+| Live tasks | Incremental Hook events plus rollout lifecycle and turn usage | Running, waiting for approval, completed, terminated, current-turn tokens | Menu bar status, Task Center, task glow, notifications, sleep prevention |
### Dependency Direction
@@ -176,7 +176,9 @@ These objects own observable state and UI coordination. They must not perform bl
### Actor Services
- `CodexStatusService` manages app-server connections and refreshes
-- `WorkflowService` manages historical aggregation
+- `WorkflowService` coordinates Hook daily aggregates and token-history snapshots
+- `CodexTokenHistoryStore` manages the rollout ledger, read cursors, and explicit rebuilds
+- `CodexTokenHistorySync` manages CloudKit turn-usage records and their cache
- `HookEventTailReader` manages Hook-file cursors
- `CodexSessionLifecycleReader` manages rollout-file cursors
- `WorkflowSyncService` manages CloudKit state
@@ -223,6 +225,7 @@ State lifetimes are:
| Task Center terminal history | 10 minutes | Provides recent context without occupying the UI indefinitely |
| Terminal deduplication memory | 24 hours | Prevents late Hook or rollout data from reviving old tasks |
| Raw Hook data and daily aggregations | 210 days | Supports long-term metrics and rebuilding |
+| Token-turn ledger | 210 days from the latest record, retaining roots referenced by child turns | Supports daily totals, incremental reads, and rebuilding |
| Daily-aggregation identity details | 3 days | Balances recent exact deduplication with privacy and file size |
| Activity Protection records | 24 hours after the last progress | Preserves suppression across restarts while limiting identity retention |
diff --git a/Docs/en/DeveloperGuide/data-and-privacy.md b/Docs/en/DeveloperGuide/data-and-privacy.md
index ca37d29..f10ed33 100644
--- a/Docs/en/DeveloperGuide/data-and-privacy.md
+++ b/Docs/en/DeveloperGuide/data-and-privacy.md
@@ -51,6 +51,7 @@ CodexBar narrows data in this order:
| app-server account, rate limits, and Reset Credits | Main panel, notification decisions, and user-enabled Automatic Reset | Short-lived state only | No |
| Structured Hook events | Historical aggregation and live tasks | Yes, up to 210 days | Daily aggregations only |
| Rollout lifecycle | Terminal and progress reconciliation | Not persisted separately | No |
+| Rollout token counters | Deduplicated turns and daily totals | Hashed identities, timestamps, and counts for 210 days | Pseudonymous cumulative turns when sync is enabled |
| App settings | Feature switches and thresholds | UserDefaults | No |
| Activity Protection | Stalled-task recovery | Hashed identity, up to 24 hours | No |
| CodexBarHelper ownership | System-sleep recovery | Root-owned state file | No |
@@ -86,9 +87,11 @@ The working directory is used only to derive a project display name and live-tas
The Hook recorder reads the current rollout through `transcript_path`; origin for `SubagentStop` uses the child thread's own `agent_transcript_path`. The live-activity reader accesses relevant main-thread and child-thread files under `$CODEX_HOME/sessions` and `$CODEX_HOME/archived_sessions`.
-These reads parse only structural fields such as origin classification, thread and turn relationships, lifecycle, time, turn context, progress, effort, and reviewer. Thread associations remain in memory, and conversation text does not enter CodexBar storage or UI.
+These reads parse structural fields including origin classification, thread and turn relationships, lifecycle, time, turn context, progress, effort, reviewer, and token counters. Live thread associations remain in memory; historical token records store hashed identities, necessary timestamps, and six cumulative counters. Conversation text does not enter CodexBar storage or UI.
-The rollout reader scans backward from file tails under a budget. This reduces I/O and limits how much unrelated historical content enters process memory. Parsing DTOs declare only required fields, and `JSONDecoder` ignores everything else.
+Historical token scanning starts at the beginning of each source and then follows persisted cursors. Cloud identities use account-salted HMAC-SHA256; raw thread and turn IDs are not uploaded. See [Rollout Token History](sync.md#rollout-token-history) for fields and retention.
+
+The live rollout reader scans backward from file tails under a budget. This reduces I/O and limits how much unrelated historical content enters process memory. Parsing DTOs declare only required fields, and `JSONDecoder` ignores everything else.
### Reset Credits Details
@@ -116,7 +119,18 @@ A rate-limit response from stale cache may remain visible but cannot trigger a n
daily.jsonl
maintenance.json
stats.lock
+ Tokens/
+ ledger.json
+ store.lock
+ rebuild.lock
Sync/
+ state.json
+ cache.jsonl
+ cursor.data
+ Tokens/
+ cache.json
+ store.lock
+ sync.lock
ActivityProtection/
state.json
```
@@ -126,13 +140,17 @@ A rate-limit response from stale cache may remain visible but cannot trigger a n
| `HookEvents/events` | Raw structured Hook events | 210 days |
| `HookEvents/daily.jsonl` | Daily aggregations | 210 days |
| `HookEvents/maintenance.json` | File cursors, generation, and maintenance state | Continuously updated |
-| `HookEvents/Sync` | CloudKit cache and cursor | While sync state remains valid |
+| `HookEvents/Tokens/ledger.json` | Hashed turn identities, cumulative usage, rebuild and recovery boundaries, file cursors | Usage retained for 210 days from its latest record; roots referenced by retained child turns are also kept |
+| `HookEvents/Sync` | Cloud cache, cursor, and replacement state for Hook daily aggregates | While sync state remains valid |
+| `HookEvents/Sync/Tokens/cache.json` | Account-scoped turns, salt, and CloudKit cursor | Sync prunes expired turns while retaining referenced roots |
| `ActivityProtection/state.json` | Hashed task identities and timestamps | Up to 24 hours after the last progress |
Daily aggregations for the latest 3 days may retain session and turn ID details for exact deduplication. Older data retains counts only.
Anonymous tasks do not create Stalled Task Protection identifiers and therefore never write to `ActivityProtection/state.json`.
+Debug and Release share the token ledger and sync cache. Each `store.lock` protects reads and writes in its directory; `rebuild.lock` excludes concurrent token rebuilds, and `sync.lock` excludes concurrent token sync passes. `stats.lock` protects Hook aggregation transactions. Lock files do not contain statistics or progress.
+
### UserDefaults
UserDefaults stores:
@@ -182,11 +200,13 @@ System logs may contain only:
- Nonsensitive counts
- Errors that identify a module
+Automatic rollout replay logs file counts, bytes read, remaining bytes, waiting or unreadable files, and elapsed time in the `workflow` category, without paths, identities, or usage counts. See [Rollout Token History](sync.md#rollout-token-history) for progress semantics.
+
System logs must not contain:
- OAuth tokens
- Prompts, responses, or tool content
-- Session, turn, or agent IDs
+- Raw session, turn, or agent IDs
- Full project paths or sensitive project names
- Account rate-limit or token-usage details
@@ -196,7 +216,7 @@ Fixed `CodexProxyError` messages go to the `settings` system-log category withou
| Destination | Purpose | Trigger |
| --- | --- | --- |
-| CloudKit private database | Sync daily Hook aggregations | User explicitly enables sync |
+| CloudKit private database | Sync daily Hook aggregations and pseudonymous rollout token turns | User explicitly enables sync |
| Codex service, through the app-server subprocess | Authentication, rate limits, usage, and Reset Credit consumption | Regular refreshes, proxy tests, or Automatic Reset |
| Sparkle appcast and update resources | Check for or install updates | Automatic check or manual user request |
@@ -208,7 +228,7 @@ When a proxy is enabled, its address and optional credentials are passed through
## CloudKit Boundary
-CloudKit uploads only daily aggregate fields:
+CloudKit uploads these daily Hook aggregate fields:
- Device pseudonym
- Date and source generation
@@ -218,13 +238,15 @@ CloudKit uploads only daily aggregate fields:
- Model counts
- Update time
+Token history also uploads account-scoped hashed turn identities, root-turn links, necessary timestamps, and six cumulative counters for cross-device deduplication and daily totals.
+
CloudKit does not upload:
- Raw Hook JSONL
-- Session, turn, or agent IDs
+- Raw session, turn, or agent IDs
- Full working directories
- Prompts, responses, tool arguments, or output
-- Codex account, rate-limit, or token usage data
+- Codex account, rate-limit, or account token usage data from app-server
- Reset Credits details, Automatic Reset settings, or redemption state
- Access tokens
- App request logs
@@ -275,12 +297,14 @@ The helper ownership file is a crash-recovery transaction record, not a user pre
- Run a task with a conspicuous marker in the prompt and tool arguments; confirm the marker is absent from Hook JSONL, app logs, and CloudKit cache
- Put a sensitive test term in a project directory name; confirm it appears only in allowed local presentation and opt-in aggregate fields
- Simulate a failed Reset Credits request and confirm that access tokens do not enter the in-memory or unified logs
-- Confirm CloudKit records contain no session, turn, or agent IDs or full paths
+- Confirm CloudKit records contain no raw session, turn, or agent IDs or full paths
- As a non-root user, verify that the helper-state directory is not writable
- Corrupt each cache type and confirm the system degrades or rebuilds rather than broadening fallback data collection
## Key Source Files
+- [`CodexTokenHistoryStore.swift`](../../../CodexBar/Services/Workflow/CodexTokenHistoryStore.swift)
+- [`CodexTokenHistorySync.swift`](../../../CodexBar/Services/Workflow/CodexTokenHistorySync.swift)
- [`WorkflowHookEventRecorder.swift`](../../../CodexBar/Services/Workflow/WorkflowHookEventRecorder.swift)
- [`WorkflowService.swift`](../../../CodexBar/Services/Workflow/WorkflowService.swift)
- [`CodexSessionLifecycleReader.swift`](../../../CodexBar/Services/Workflow/CodexSessionLifecycleReader.swift)
diff --git a/Docs/en/DeveloperGuide/design-decisions.md b/Docs/en/DeveloperGuide/design-decisions.md
index 15b8670..f905360 100644
--- a/Docs/en/DeveloperGuide/design-decisions.md
+++ b/Docs/en/DeveloperGuide/design-decisions.md
@@ -9,8 +9,8 @@ Each data flow has one service owning its facts; consumers read snapshots or tra
| Flow | Source of state | Output use |
| --- | --- | --- |
| app-server | Account, quota, and usage responses | Periodic display with same-account stale-cache fallback |
-| Hook history | Raw JSONL | Rebuildable daily statistics and cross-device sync |
-| Live tasks | Incremental Hook events and rollout lifecycle | Activity snapshots, task alerts, and sleep prevention |
+| Historical statistics | Independently maintained Hook events and rollout usage | Rebuildable daily activity metrics, thread-turn token ledger, and cross-device sync |
+| Live tasks | Incremental Hook events, rollout lifecycle, and turn usage | Activity snapshots with current-turn tokens, task alerts, and sleep prevention |
Snapshots can be read repeatedly. Notifications use live transitions; bootstrap establishes a baseline without replaying historical alerts. Historical aggregation shares some refresh triggers with quota, but reads and failure handling remain independent. See [Architecture](architecture.md) for component relationships.
@@ -50,10 +50,12 @@ Combine’s `@Published` emits during `willSet`. Combined-setting decisions use
Raw Hook JSONL is the source for rebuilding history; daily aggregates are derived output. Aggregation-semantic changes increment the schema and rebuild retained history. `sourceGeneration` distinguishes file replacements: same-day, same-source data replaces a contribution, while independent sources add together.
+Token history uses stable thread-and-turn identities, deduplicates cumulative snapshots, and aggregates by the root turn’s start date. Explicit rebuilds finish the local scan before committing reread turns for selected dates. `rebuiltAt` gives corrected lower counts precedence over stale copies. Turns with missing source files retain known statistics, while remote-only turns remain in the sync cache. See [Rollout Token History](sync.md#rollout-token-history) for fields and merge rules.
+
Activity Protection and helper ownership records recover state changes that have already occurred. Protection saves asynchronously and does not wait for disk before hiding a task. The helper persists recovery responsibility before changing system sleep state. See [Live Task Monitoring](activity-monitor.md) and [Sleep Prevention](sleep-prevention.md) for ordering.
## Privileged Operations and Upload Scope
Task identification, Automatic Reset policy, and networking run in the main app. The root helper accepts only fixed sleep-lease and wake operations, validates client signatures, and reads back system results.
-CloudKit syncs only daily aggregates. Raw events, session identifiers, account data, and proxy passwords remain local. Project display names are uploaded only after the user enables sync. See [Data and Privacy Boundaries](data-and-privacy.md) for fields and storage scope.
+CloudKit syncs daily activity aggregates and pseudonymous thread-turn token records. Raw events, raw session identifiers, account data, and proxy passwords remain local. Project display names are uploaded only after the user enables sync. See [Data and Privacy Boundaries](data-and-privacy.md) for fields and storage scope.
diff --git a/Docs/en/DeveloperGuide/development.md b/Docs/en/DeveloperGuide/development.md
index 3140cc1..30670e2 100644
--- a/Docs/en/DeveloperGuide/development.md
+++ b/Docs/en/DeveloperGuide/development.md
@@ -30,6 +30,8 @@ The test target has no app host. It compiles the production sources in `CodexBar
| Hook and JSONL | Name normalization, corrupt-line isolation, metadata read budget, partial lines, bootstrap/live separation, file replacement |
| Live tasks | Anonymous identity, duration, out-of-order progress, subagent counts, approvals scoped to each execution |
| Rollout lifecycle | Completion and progress, read coverage, corrupt lines, missing/replaced files, archived sessions |
+| Current-turn tokens | Counter validation, main/child ownership and deduplication, live updates, terminal rereads, turn isolation, overflow and zero values |
+| Token history | Cross-midnight attribution, persisted cursors, replay logs, rebuilds lowering or clearing counts, missing-file preservation, cloud-baseline recovery, cancellation and cross-instance locks |
| Aggregation and sync models | Identifier deduplication, paired events, missing counts, incremental/replay equivalence, same-device generation deduplication |
| Persistence and settings | Protection expiry, merging across store instances, conditional removal, legacy defaults, corrupt configuration and draft restoration |
| Quota, proxy, and presentation | Credit filtering, stable UUIDs, actual running versions, proxy validation and environment, dates and heatmap states |
@@ -48,7 +50,8 @@ Unit tests do not cover live CloudKit, app-server, system notifications, window
| Live tasks and protection | `CodexActivityMonitor` and readers | [Live Task Monitoring](activity-monitor.md) |
| Sleep prevention and system wakes | `KeepAliveController`, `AutoResetWakeScheduler`, helper | [Sleep Prevention](sleep-prevention.md) |
| Notifications and sound | `CodexNotificationService`, notification Settings | [Notifications](notifications.md) |
-| Sync | `WorkflowSyncService` and scheduler | [CloudKit Sync](sync.md) |
+| Token history and sync | `CodexTokenHistoryStore`, `CodexTokenHistorySync`, and `CodexTokenTurn` | [Rollout Token History](sync.md#rollout-token-history) |
+| Hook sync | `WorkflowSyncService` and scheduler | [CloudKit Sync](sync.md) |
| Menus, windows, hot keys | `Controllers` and corresponding views | [UI and Lifecycle](ui-and-lifecycle.md) |
`CodexBarAppDelegate` assembles long-lived objects. Add state to its existing owner where possible; views consume snapshots and emit action intents. See [Architecture](architecture.md) for source entry points.
@@ -83,6 +86,7 @@ Documentation-only changes run format checks, lint, and build, plus relative-lin
| Notifications | Authorization denial/recovery, threshold crossing, cycle deduplication, withdrawal after progress, missing sounds |
| Proxy | First configuration, enable/disable, disable invalid data, delete corrupt records, cancel tests, rapid actions and failure rollback |
| Sync | First upload, multiple devices, offline recovery, partial upload failure, rebuild replacement, iCloud account changes |
+| Token replay and rebuild | Large-history resume, main-panel use during rebuild, closing Settings, automatic replay versus manual rebuild after restart, cross-device convergence of corrected counts |
| Power and helper | First approval, running/waiting transitions, low battery, duration limit, external sleep sources, abnormal exit and restart |
| Automatic Reset wakes | Replace schedules, disable/exit cleanup, connection loss, helper restart, clear before unregistering, fresh reads when due |
diff --git a/Docs/en/DeveloperGuide/sync.md b/Docs/en/DeveloperGuide/sync.md
index eb4cd80..3f6e7b6 100644
--- a/Docs/en/DeveloperGuide/sync.md
+++ b/Docs/en/DeveloperGuide/sync.md
@@ -4,9 +4,9 @@
## Sync Scope
-CloudKit sync merges daily Hook metrics across Macs signed in to the same iCloud account.
+CloudKit sync merges daily Hook metrics and rollout token usage across Macs signed in to the same iCloud account.
-It syncs aggregated results, not raw Hook events:
+Hook sync transfers daily aggregates:
```text
Local raw Hook JSONL
@@ -16,11 +16,11 @@ Local raw Hook JSONL
-> Merge by date for display
```
-Account data, rate limits, total tokens, Reset Credits, Automatic Reset settings and state, live tasks, and sleep-prevention state do not sync.
+App-server account data, rate limits, account token totals, Reset Credits, Automatic Reset settings and state, live tasks, and sleep-prevention state do not sync.
## Data Sources
-Synced presentation combines three kinds of values:
+Hook daily aggregates combine three kinds of data. See [Rollout Token History](#rollout-token-history) for the turn ledger and its cloud cache.
| Data | Authoritative source | Offline behavior |
| --- | --- | --- |
@@ -42,6 +42,7 @@ The remote cache is a rebuildable projection, and the cursor is only an optimiza
| Custom zone | `CodexBarZone` |
| Metadata record type | `CodexBarSyncMetadata` |
| Daily aggregate record type | `CodexBarDailyAggregate` |
+| Token-turn record type | `CodexBarTokenTurn` |
Private-database content belongs only to the current iCloud account and is never written to the public database.
@@ -96,12 +97,43 @@ It does not upload:
- Full working directories
- Prompt or response content
- Codex account or rate-limit data
-- Tokens or files such as `auth.json`
+- Authentication tokens or credential files such as `auth.json`
- App request logs
- Stalled Task Protection state
For complete boundaries, see [Data and Privacy Boundaries](data-and-privacy.md).
+## Rollout Token History
+
+Token history uses a separate `CodexBarTokenTurn` record type with schema `1` in the same private zone. Each record represents one thread and turn. Cumulative snapshots replace the previous contribution; they are never summed by device. Main and child threads contribute once each, attributed to the root turn's start date in the viewing device's local time zone.
+
+Local identities are SHA-256 hashes of thread and turn IDs. Cloud identities apply account-salted HMAC-SHA256 to those hashes, so copied rollouts on different Macs resolve to the same record. No raw session, turn, or agent ID is uploaded.
+
+Deploy the following record type and fields to the CloudKit production schema before distribution:
+
+| Field | CloudKit type | Meaning |
+| --- | --- | --- |
+| `schemaVersion` | Int64 | `1` |
+| `rootID` | String | Account-scoped root-turn hash |
+| `startedAt` | Date | Optional turn start time |
+| `observedAt` | Date | Latest cumulative observation time |
+| `rebuiltAt` | Date | Optional explicit rebuild time that supersedes stale statistics |
+| `usage` | Bytes | Optional JSON with six token counters |
+
+Record names use the stable turn hash without a prefix; `schemaVersion` describes the data format. A record without `usage` contributes no tokens: root records can anchor child dates, and records carrying `rebuiltAt` can clear a turn’s previous counts. Uploads fetch the existing record, retain the more complete cumulative snapshot, and use `ifServerRecordUnchanged`. Conflicts are fetched and merged again on the next sync. Counters from separate snapshots are not combined field by field.
+
+Explicit rebuilds scan retained local rollouts, select records by the root turn's start date, and replace only reread turns in the requested dates. A local `rebuild.lock` excludes concurrent rebuilds across processes. Scanning yields between batches without holding the ledger lock; a complete successful scan is committed atomically. Live progress observed after the scan began is preserved. Missing source files do not remove known turns. Read failures and cancellation preserve the previous ledger; restarting the app does not resume an unfinished manual rebuild.
+
+Rebuilt turns that need syncing carry `rebuiltAt`. Merging first selects the newer rebuild, then retains the more complete cumulative snapshot within that rebuild. This allows corrections to lower counts. Incremental reads inherit the local turn's rebuild time. When recovering the local ledger or observing a newer cloud rebuild, restore the cloud baseline only for locally discovered turns with matching account and root identities. Previously read files replay within the usual byte budget. Usage records at or before the restored rebuild boundary cannot replace the corrected baseline; later cumulative records continue updating it. Recovery boundaries and file cursors persist locally so replay resumes after restart without importing remote-only turns. A previously counted turn rebuilt without usage remains syncable to clear its old cloud usage. Other turns and sessions from other Macs remain untouched.
+
+Daily cache hit rate is total cached input divided by total input. Account usage and heatmap intensity come from app-server. Heatmap date details present missing usage as `0` and a missing cache hit rate as `0%`; storage and sync preserve missing values.
+
+The local ledger is `HookEvents/Tokens/ledger.json`; its separate process lock coordinates Debug and Release. Account-scoped sync state lives in `HookEvents/Sync/Tokens/cache.json`. Debug and Release share this cache. A nonblocking `sync.lock` serializes complete sync passes while the separate file lock allows reads between writes. Hook daily aggregates use separate storage and sync records.
+
+Scanning includes `rollout-*.jsonl` files modified within the last 210 days under `$CODEX_HOME/sessions` and `$CODEX_HOME/archived_sessions`, with a 64 MiB pass budget plus at most one additional bounded line. Later maintenance passes continue historical backfill. Equally unread files are ordered by most recent modification first, so recent sessions are processed before older history. Partial lines are retried; large body lines are skipped without storing their contents. Replacement, truncation, and changed read boundaries trigger replay without counting known cumulative usage again. Turns are retained for 210 days by `updatedAt`, along with root records referenced by retained child turns. Daily totals include only root start dates within retention. Missing rollouts or missing `token_usage_record` entries cannot be reconstructed.
+
+Automatic replay reports progress in the `workflow` system log after each committed batch: caught-up file count, byte progress, bytes read this pass, remaining bytes, files waiting for a complete line, unreadable files, and elapsed time. Once all files are caught up, it logs “Rollout 回放完成” once. Routine incremental appends and unchanged waits do not repeat the message. Completion refers to local files checked in that pass, not iCloud synchronization. Logs contain no paths, session identities, conversation content, or token usage.
+
## One Sync Cycle
```text
@@ -111,8 +143,9 @@ Read local sync state
-> Update local state for the device identity and schema
-> Fetch remote changes into the cache and process replacement dates
-> Upload changed dates for this device
- -> Fetch remote changes into the cache again
- -> Prune records outside retention
+ -> Fetch remote Hook changes into the cache again
+ -> Fetch, upload, and prune token-turn records
+ -> Prune this device’s expired Hook records
-> Save state and publish merged results
```
@@ -123,7 +156,7 @@ The fetches before and after upload serve different purposes:
- It fetches again after upload to merge this cycle's writes and concurrent writes from other devices into the local cache
- It prunes expired records last so a pruning failure cannot block valid uploads in the same cycle
-Every stage writes a `stage` field to logs, so an error identifies zone, device, fetch, upload, or prune instead of reporting only a generic CloudKit error:
+Every stage writes a `stage` field to logs, identifying failures in `zone`, `device`, `fetch`, `upload`, `tokens`, or `prune`:
- Upload batches contain at most 25 records
- Each upload cycle uses a 20-second budget to decide whether to start another batch
@@ -136,7 +169,7 @@ Each date’s stable JSON is encoded and hashed once, reusing the result for pen
Uploads use `atomically: false`, allowing partial success remotely. If any error occurs in a batch, the caller removes local confirmation hashes for every date in that batch and rechecks it next cycle. Confirmations from earlier completed batches remain, and successful remote writes are not rolled back.
-## Merge Semantics
+## Hook Daily Aggregate Merge Semantics
One day may have records from several devices plus a newer local result that the current device has not uploaded yet.
@@ -180,7 +213,7 @@ CloudKit decoding and persisted models preserve optional counts. Local and remot
CloudKit stores interruption counts in the optional integer field `interruptCount`. If any contribution for a combined date lacks this field, the total interruption count remains unavailable.
-## Source Replacement and Rebuild
+## Hook Source Replacement and Rebuilding
When the user requests a rescan:
@@ -299,12 +332,17 @@ Transient errors preserve the last usable remote cache. After account switching
- Disabling sync shows local metrics only
- When iCloud is signed out, the app shows a clear state and local metrics keep working
- After network loss, the app uses the last cache and completes incremental sync on recovery
-- A local rebuild replaces only current-device records
+- Local rebuilds replace this device’s Hook records and token turns reread locally
+- Token rebuilds can lower or clear counts; other devices converge without restoring stale counts
+- Missing rollouts preserve known turns; replay after ledger recovery respects cloud corrections
+- File copies and cross-device copies of a turn count once; main and child threads use the root turn’s start date
- Local and remote cache older than 210 days is pruned
- Switching iCloud accounts does not show cache from the previous account
## Key Source Files
+- [`CodexTokenHistoryStore.swift`](../../../CodexBar/Services/Workflow/CodexTokenHistoryStore.swift)
+- [`CodexTokenHistorySync.swift`](../../../CodexBar/Services/Workflow/CodexTokenHistorySync.swift)
- [`WorkflowSyncService.swift`](../../../CodexBar/Services/Workflow/WorkflowSyncService.swift)
- [`WorkflowSyncScheduler.swift`](../../../CodexBar/Services/Workflow/WorkflowSyncScheduler.swift)
- [`WorkflowSyncSettings.swift`](../../../CodexBar/Services/Settings/WorkflowSyncSettings.swift)
diff --git a/Docs/en/DeveloperGuide/ui-and-lifecycle.md b/Docs/en/DeveloperGuide/ui-and-lifecycle.md
index f8d04f4..49b00b2 100644
--- a/Docs/en/DeveloperGuide/ui-and-lifecycle.md
+++ b/Docs/en/DeveloperGuide/ui-and-lifecycle.md
@@ -200,6 +200,12 @@ The heatmap detail panel uses the complete heatmap area, including its heading,
While the main panel is visible, digits roll as values change and Token values fade when switching to or from pending or unavailable placeholders. Animation Effects controls entrance animations, sun-badge rotation, and task status-text animations; it does not control numeric updates.
+The activity card shows its token area only when `primaryActivity.tokenUsage` is available, with seven equally sized, centered metrics and a divider. Availability changes animate the card height and main-panel size independently of Animation Effects. The popover temporarily enables `animates` before the content-size update; the fallback waits for the `@Published` assignment before measuring and keeps its top edge fixed.
+
+With Hook enabled, heatmap details use two columns beneath a full-width ten-segment intensity row: activity statistics on the left and session tokens on the right. Each column uses a `Grid` to size labels to its longest label, leaving the remaining width for values. Date changes use the same `numericText` transition for token and activity values. The most-used model transitions within one text view and scales its font to fit.
+
+The shared `LiquidGlassDivider` slowly moves a silver-gray and cool-white gradient over an 8-second cycle. It pauses or resumes its timeline using its `NSView` window visibility, independently of Animation Effects.
+
Related controllers include:
- [`HeatmapDetailPanelController.swift`](../../../CodexBar/Controllers/HeatmapDetailPanelController.swift)
@@ -339,6 +345,10 @@ Release scripts require Developer ID, signing, and notarization credentials and
- Panel-open refresh does not stall animation or issue duplicate requests
- Initial numeric decreases, consecutive changes, Token unit changes, and month boundaries roll in the correct direction; numeric animations stop when the main panel closes
+- Switch heatmap dates rapidly in Chinese and English; label widths remain stable while token values and model names transition in place
+- Toggle token availability; popover and fallback sizes animate smoothly even with Animation Effects disabled
+- Shared dividers flow slowly and stop continuous rendering when their window closes or becomes hidden
+
## Key Source Files
- [`CodexBarAppDelegate.swift`](../../../CodexBar/Controllers/CodexBarAppDelegate.swift)
diff --git a/Docs/en/UserGuide/activity-and-hook.md b/Docs/en/UserGuide/activity-and-hook.md
index 9e9d108..62f1ea8 100644
--- a/Docs/en/UserGuide/activity-and-hook.md
+++ b/Docs/en/UserGuide/activity-and-hook.md
@@ -2,7 +2,7 @@
[简体中文](../../UserGuide/activity-and-hook.md) | English
-CodexBar Hook provides live task status, task notifications, haptics, task-based sleep prevention, and daily session, turn, and tool-call statistics. It also enables syncing and rebuilding those daily statistics.
+CodexBar Hook provides live task status, task notifications, haptics, task-based sleep prevention, and daily session, turn, and tool-call statistics. It also enables syncing daily activity statistics and rollout token history. Rebuild Data recalculates both types of retained local history.
## Enable Hook
@@ -37,13 +37,13 @@ Tasks with a known origin whose session cannot be identified show an orange anon
## Daily Statistics
-Hover over a day in the main panel heatmap to view sessions, turns, tool calls, permission requests, context compactions, subagents, and the most-used model.
+Hover over a day in the main-panel heatmap to see sessions, turns, tool calls, permission requests, context compactions, subagents, and the most-used model in the left column, with session token totals on the right. Token usage belongs to the root turn’s start date, unlike daily activity counts. See [Token Usage and Heatmap](main-panel.md#token-usage-and-heatmap).
Sessions and turns are deduplicated within each day; activity continuing into another day counts toward that day. Sessions with only a session-end event and turns with only completion-candidate or interruption events do not count as active that day. Tool calls use the larger of the start and end event counts.
## Disable Hook
-Disabling Hook stops updates to live tasks, task notifications, haptics, sleep prevention, Hook statistics, and their cross-device sync. Account, quota, and token heatmap features remain available.
+Disabling Hook stops updates to live tasks, task notifications, haptics, sleep prevention, and Hook statistics, and stops cross-device sync for activity and token history. The heatmap hides its two-column history details. Account, quota, and the app-server token heatmap remain available.
Hook records task information such as time, model, tool name, and project, without saving prompt, reply, or tool input/output content. See [Data, Sync, and Privacy](sync-data-privacy.md) for retention and sync details.
diff --git a/Docs/en/UserGuide/main-panel.md b/Docs/en/UserGuide/main-panel.md
index 6398717..885c14a 100644
--- a/Docs/en/UserGuide/main-panel.md
+++ b/Docs/en/UserGuide/main-panel.md
@@ -53,6 +53,8 @@ Each rate-limit window includes:
When `Animation Effects` is enabled, each segmented progress bar fills from zero to its current remaining percentage whenever the main panel opens.
+Glass dividers use a slowly flowing gradient independently of `Animation Effects`; the animation pauses while their window is hidden.
+
The primary rate-limit group may also show:
- Available credits or unlimited-credit status
@@ -63,7 +65,7 @@ Click `Banked Resets` to view expiration times by batch. The entry appears when
## Token Usage and Heatmap
-The summary area shows:
+Account usage comes from app-server. The summary area shows:
- All-time token usage
- Highest daily token usage
@@ -77,7 +79,7 @@ When `Animation Effects` is enabled, the day squares appear from the top left to
Hover over a day to see its date, token count, and usage intensity.
-When CodexBar Hook is enabled and data exists for that day, the details also include:
+When CodexBar Hook is enabled, the details also include:
- Most-used model
- Sessions
@@ -87,6 +89,12 @@ When CodexBar Hook is enabled and data exists for that day, the details also inc
- Permission requests
- Context compactions
+The date detail panel uses two columns beneath a full-width, ten-segment intensity row. Activity metrics appear on the left; the right column shows daily rollout totals in this order: total, input, output, cached input, cache write, cache hit rate, and reasoning output. Each metric in either column has a colored dot. Labels share the width of the longest label within their own column, leaving the remaining space for right-aligned model names and values. Token counts use K/M/B units. Missing and zero counts display `0`; missing or zero cache hit rate displays `0%`. Activity counts, token values, and the most-used model roll between values when the selected date changes.
+
+Each thread turn contributes once. Main and child-agent usage belongs to the root task's start date, including tasks that cross midnight. Daily cache hit rate divides total cached input by total input. With iCloud sync enabled, duplicate turns across Macs are merged before daily aggregation.
+
+Heatmap colors, the token count beside the date, and intensity come from app-server. Session tokens in the right column come from local rollouts and iCloud history, with a different scope. See [Data, Sync, and Privacy](sync-data-privacy.md#historical-token-replay) for backfill, incremental reads, and rebuilding.
+
## Activity Card
The activity card prioritizes tasks waiting for approval, then running tasks. With no active tasks, it shows the latest completion or termination by end time, with termination taking precedence on ties.
@@ -109,6 +117,14 @@ The activity card’s `+N` shows the total number of other active tasks.
Click a populated activity card to open Task Center. In both views, status-text colors follow task state. With Animation Effects enabled, running status text shimmers and orange particles appear around approval-waiting text. Disabling the setting keeps the colored text static.
+### Token Usage for the Current Turn
+
+Once rollout usage is available, the activity card shows seven equally sized, centered metrics beneath its status: Total, Input, Output, Cached, Cache-W, Cache-H, and Reasoning. Counts use K/M/B units. The usage row and its divider expand or collapse together, independently of `Animation Effects`. Both remain hidden when usage is unavailable.
+
+While a task is running or waiting for approval, usage updates for main and child threads whose ownership is confirmed. Later thread records fill in the subtotal. Completed and terminated tasks briefly reread turn usage and display it once a complete total is available. Later temporary read failures preserve the usage already obtained for the ended task. These values cover the current turn and its subagents, rather than the entire conversation.
+
+Total equals input plus output. Cached input and cache write are included in input; reasoning is included in output. These subsets must not be added to the total again. Cache-H is cached input divided by input; the card shows `—` when input is zero. Cached shows the number of input tokens served from cache; Cache-W shows cache writes.
+
## Task Center
Task Center groups tasks into:
@@ -120,6 +136,8 @@ Task Center groups tasks into:
Recently completed and terminated records remain for 10 minutes. Completion means a turn ended, without implying success. Termination records include interruptions and other task terminations, and do not trigger completion notifications.
+Recently completed and terminated entries show total tokens for the turn when available, using K/M/B units. Running and waiting entries show task status; the main-panel activity card displays usage for the task it summarizes.
+
## Footer Status
The bottom of the main panel shows:
diff --git a/Docs/en/UserGuide/settings.md b/Docs/en/UserGuide/settings.md
index a90df76..5d23719 100644
--- a/Docs/en/UserGuide/settings.md
+++ b/Docs/en/UserGuide/settings.md
@@ -60,8 +60,8 @@ A shortcut needs at least two modifier keys and cannot use `Command-Space` or `C
| [System Notifications](notifications.md) | Configure notification types, thresholds, sounds, and haptics | Main switch off |
| Automatic Reset | Use banked resets shortly before expiration | Off, 30-minute lead time |
| [Prevent System Sleep](sleep-prevention.md) | Keep your Mac awake while eligible tasks run | Off |
-| [Cross-Device Sync](sync-data-privacy.md) | Combine daily Hook statistics through iCloud | Off |
-| [Rebuild Data](sync-data-privacy.md#rebuild-data) | Recalculate Hook statistics for selected dates | Manual |
+| [Cross-Device Sync](sync-data-privacy.md) | Combine daily activity statistics and session token usage through iCloud | Off |
+| [Rebuild Data](sync-data-privacy.md#rebuild-data) | Recalculate activity statistics and session token usage for selected dates in the background | Manual |
### Proxy
diff --git a/Docs/en/UserGuide/sync-data-privacy.md b/Docs/en/UserGuide/sync-data-privacy.md
index b555533..1134976 100644
--- a/Docs/en/UserGuide/sync-data-privacy.md
+++ b/Docs/en/UserGuide/sync-data-privacy.md
@@ -4,7 +4,7 @@
## Cross-Device Sync
-Enable `Cross-Device Sync` in `Settings > Advanced` to combine daily Hook statistics from Macs using the same iCloud account. CodexBar Hook must be enabled and an available iCloud account signed in.
+Enable `Cross-Device Sync` in `Settings > Advanced` to combine daily Hook statistics and rollout token usage from Macs using the same iCloud account. CodexBar Hook must be enabled and an available iCloud account signed in.
The first sync uploads statistics within local retention; later changes sync automatically. Turning sync off keeps local data.
@@ -19,13 +19,13 @@ The main panel footer and Settings show sync status. Settings also shows the las
## Uploaded Data
-Synced data is stored in your private iCloud database. It includes dates, daily event and session statistics, project display names, model names, and identifiers used to distinguish devices and avoid duplicate counts.
+Synced data is stored in your private iCloud database. It includes dates, daily event and session statistics, project display names, model names, and identifiers used to distinguish devices and avoid duplicate counts. Token history separately syncs pseudonymous turn identities, necessary timestamps, and six cumulative counters for cross-device deduplication and daily totals.
The following are not synced:
- Raw Hook events, session and task identifiers, and full working-directory paths
- Prompts, Codex replies, and tool parameters or output
-- Codex account data, quota, token usage, and banked resets
+- Codex account data, quota, app-server account usage, and banked resets
- App settings, proxy configuration, and passwords
- Logs, live task state, and Stalled Task Protection records
@@ -36,6 +36,7 @@ Project display names are uploaded. Disable cross-device sync if you do not want
| Data | Contents and retention |
| --- | --- |
| Hook records and daily statistics | Times, events, models, tools, projects, and task identifiers, retained for 210 days; session and turn details in daily statistics are retained for only the latest 3 days |
+| Rollout token history | Hashed turn identities, timestamps, cumulative counts, and read cursors, retained for 210 days; root timestamps referenced by retained child turns are also kept |
| Stalled Task Protection | Irreversible task identifiers and times, retained for up to 24 hours after the last progress |
| App settings | Stored on the current Mac, including proxy configuration; proxy passwords are stored in plain text |
| Interaction logs | The latest 500 Codex requests and responses, retained only during the current run |
@@ -45,11 +46,23 @@ CodexBar reads local Codex task state and activity records without saving prompt
Turning the proxy off retains its configuration and password. Saving with authentication disabled or choosing `Delete Configuration` removes the password.
+## Historical Token Replay
+
+During historical-statistics refreshes, the app automatically reads local Codex rollouts to backfill retained turn usage. No manual rebuild is required. Each batch saves usage and read positions; reopening the app resumes from those positions. Once caught up, later refreshes read appended content. Replaced or truncated files are reread, with each thread and turn still counted once.
+
+Large histories may take several refreshes to complete. Progress appears in the `workflow` system-log category. `Rollout 回放完成` means the files checked in that pass are caught up locally; the sync area reports cloud transfer status.
+
+Daily usage follows the root turn’s start time in the viewing device’s local time zone. Missing rollouts or records without usage cannot supply the corresponding counts.
+
## Rebuild Data
-If statistics look incorrect, choose a date range in `Settings > Advanced > Rebuild Data` and confirm. You can select from the last 210 days; dates with local records are marked.
+If statistics look incorrect, choose a date range in `Settings > Advanced > Rebuild Data` and confirm. You can select from the last 210 days; dates with local Hook records or discovered token turns are marked; unmarked dates can also be selected.
+
+Rebuilding recalculates activity statistics and token usage for the selected dates from local Hook events and rollouts. Tokens belong to the root turn's start date; each thread and turn contributes once. Dates without Hook events can still rebuild token usage from local rollouts.
+
+The work runs in the background. You can keep using the main panel or close Settings. Token files are read in batches and committed only after the complete scan succeeds; cancellation and read errors do not publish partial results. Quitting the app stops the operation, and an unfinished token rebuild must be started again. The result reports days, activity events, and token turns processed.
-Rebuilding recalculates Hook statistics from retained local records and displays the result. With sync enabled, the result replaces this device’s cloud statistics for those dates while preserving other devices’ contributions. Account, quota, and token usage are unaffected.
+With sync enabled, rebuilding replaces this device's activity statistics and the token turns reread locally, preserving other turns. Rebuilding can lower token counts. If a turn is reread without usage records, its previous counts are cleared and that correction syncs to iCloud. Turns whose local rollouts are missing retain known statistics; missing files do not delete cloud records. Account details, quota, and app-server account usage are unaffected.
## Network and Logs
@@ -57,7 +70,7 @@ Rebuilding recalculates Hook statistics from retained local records and displays
| --- | --- |
| Codex service | Read account, quota, and usage data; perform Automatic Reset |
| Update service | Check for and download CodexBar updates |
-| iCloud | Transfer daily Hook statistics when sync is enabled |
+| iCloud | After enabling synchronization, transmit daily Hook statistics and session token data |
The proxy applies only to CodexBar’s Codex service connection, not updates, iCloud, or other apps.
diff --git a/appcast.xml b/appcast.xml
index 3a981a3..dfc7ff2 100644
--- a/appcast.xml
+++ b/appcast.xml
@@ -7,6 +7,15 @@
<link>https://codexbar.zabrian.app/appcast.xml</link>
<description>CodexBar appcast feed</description>
<language>zh-CN</language>
+ <item>
+ <title>CodexBar.app 4.0.9</title>
+ <sparkle:version>109</sparkle:version>
+ <sparkle:shortVersionString>4.0.9</sparkle:shortVersionString>
+ <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+ <sparkle:releaseNotesLink>https://codexbar.zabrian.app/notes#4.0.9</sparkle:releaseNotesLink>
+ <pubDate>Tue, 29 Sep 2026 10:19:18 +0800</pubDate>
+ <enclosure url="https://codexbar.zabrian.app/download/CodexBar-v4.0.9.dmg" sparkle:edSignature="oODBR1X6049kYbHveUV6YzY6eY6TskDhVpk2Oul/m0k4BNbbct8Ox758Oy47Wk8hpXq2AGVBKgYpOb3vCPzWBQ==" length="8687104" type="application/octet-stream"/>
+ </item>
<item>
<title>CodexBar.app 4.0.8</title>
<sparkle:version>108</sparkle:version>