The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import { |
| 2 | resolveIdleCompaction, |
| 3 | type ModelSelection, |
| 4 | type OrchestrationV2ProviderTurn, |
| 5 | type OrchestrationV2ProviderTurnTokenUsage, |
| 6 | type OrchestrationV2ProviderThread, |
| 7 | type ServerProvider, |
| 8 | type ServerSettings, |
| 9 | type ThreadTokenUsageSnapshot, |
| 10 | } from "@t3tools/contracts"; |
| 11 | import { |
| 12 | CLAUDE_RESUME_COMPACTION_NEVER_ANSWER, |
| 13 | COMPACTION_SUGGESTION_MIN_TOKENS, |
| 14 | isClaudeResumeCompactionQuestion, |
| 15 | } from "@t3tools/shared/claudeCompaction"; |
| 16 | import * as DateTime from "effect/DateTime"; |
| 17 | |
| 18 | import { resolvePendingHandoff } from "../handoff.ts"; |
| 19 | import type { ThreadStructure, ThreadStructureTurnItem } from "./models.ts"; |
| 20 | |
| 21 | // Fallback TTL: Claude's 1h cache plus slack. |
| 22 | const CLAUDE_RESUME_COMPACTION_FALLBACK_MS = 70 * 60_000; |
| 23 | |
| 24 | // A typed `/compact`, with or without instructions, is already the compaction. Queueing a |
| 25 | // bare one ahead of it would run an uninstructed compaction first and charge for two. |
| 26 | export const COMPACT_COMMAND_PATTERN = /^\/compact(?:\s|$)/i; |
| 27 | |
| 28 | function asFiniteNumber(value: unknown): number | null { |
| 29 | return typeof value === "number" && Number.isFinite(value) ? value : null; |
| 30 | } |
| 31 | |
| 32 | type NullableContextWindowUsage = { |
| 33 | readonly [Key in keyof ThreadTokenUsageSnapshot]: undefined extends ThreadTokenUsageSnapshot[Key] |
| 34 | ? Exclude<ThreadTokenUsageSnapshot[Key], undefined> | null |
| 35 | : ThreadTokenUsageSnapshot[Key]; |
| 36 | }; |
| 37 | |
| 38 | export type ContextWindowSnapshot = NullableContextWindowUsage & { |
| 39 | readonly remainingTokens: number | null; |
| 40 | readonly usedPercentage: number | null; |
| 41 | readonly remainingPercentage: number | null; |
| 42 | readonly updatedAt: string; |
| 43 | }; |
| 44 | |
| 45 | /** |
| 46 | * Newest report by timestamp among the active provider thread's turns, since a provider switch leaves |
| 47 | * the previous provider's report behind. Without an active provider thread, every turn is a candidate. |
| 48 | */ |
| 49 | export function latestProviderTurnTokenUsage( |
| 50 | turns: ReadonlyArray<Pick<OrchestrationV2ProviderTurn, "providerThreadId" | "tokenUsage">>, |
| 51 | projection?: Pick<ThreadStructure, "thread" | "contextTransfers"> | null, |
| 52 | providerThread?: Pick<OrchestrationV2ProviderThread, "id" | "contextUsage"> | null, |
| 53 | ): OrchestrationV2ProviderTurnTokenUsage | null { |
| 54 | let latest: OrchestrationV2ProviderTurnTokenUsage | null = null; |
| 55 | for (const { providerThreadId, tokenUsage } of turns) { |
| 56 | if (tokenUsage === undefined) continue; |
| 57 | if (providerThread != null && providerThreadId !== providerThread.id) continue; |
| 58 | // Ties go to the later entry, since live upserts append. |
| 59 | if (latest === null || Date.parse(tokenUsage.updatedAt) >= Date.parse(latest.updatedAt)) { |
| 60 | latest = tokenUsage; |
| 61 | } |
| 62 | } |
| 63 | if (latest !== null || projection == null || providerThread?.contextUsage != null) return latest; |
| 64 | const forkedFrom = projection.thread.forkedFrom; |
| 65 | if (forkedFrom?.type !== "run") return null; |
| 66 | return ( |
| 67 | projection.contextTransfers.find( |
| 68 | (transfer) => |
| 69 | transfer.type === "fork" && |
| 70 | transfer.targetThreadId === projection.thread.id && |
| 71 | transfer.sourceThreadId === forkedFrom.threadId && |
| 72 | transfer.sourcePoint.runId === forkedFrom.runId && |
| 73 | transfer.sourceProviderInstanceId === projection.thread.modelSelection.instanceId && |
| 74 | (transfer.status === "pending" || transfer.resolution?.strategy === "native_fork"), |
| 75 | )?.sourceTokenUsage ?? null |
| 76 | ); |
| 77 | } |
| 78 | |
| 79 | type CompactionItem = Extract<ThreadStructureTurnItem, { readonly type: "compaction" }>; |
| 80 | |
| 81 | // A retired provider thread's items say nothing about the active conversation. |
| 82 | function isRetiredProviderThreadItem( |
| 83 | item: CompactionItem, |
| 84 | providerThread: Pick<OrchestrationV2ProviderThread, "id"> | null | undefined, |
| 85 | ): boolean { |
| 86 | return ( |
| 87 | providerThread != null && |
| 88 | item.providerThreadId != null && |
| 89 | item.providerThreadId !== providerThread.id |
| 90 | ); |
| 91 | } |
| 92 | |
| 93 | function compactionSnapshot( |
| 94 | item: CompactionItem, |
| 95 | maxTokens: number | null, |
| 96 | updatedAt: string, |
| 97 | ): ContextWindowSnapshot | null { |
| 98 | const usedTokens = asFiniteNumber(item.afterTokenCount); |
| 99 | if (usedTokens === null || usedTokens < 0) return null; |
| 100 | const usedPercentage = |
| 101 | maxTokens !== null && maxTokens > 0 ? Math.min(100, (usedTokens / maxTokens) * 100) : null; |
| 102 | return { |
| 103 | usedTokens, |
| 104 | totalProcessedTokens: asFiniteNumber(item.beforeTokenCount), |
| 105 | maxTokens, |
| 106 | remainingTokens: maxTokens !== null ? Math.max(0, Math.round(maxTokens - usedTokens)) : null, |
| 107 | usedPercentage, |
| 108 | remainingPercentage: usedPercentage !== null ? Math.max(0, 100 - usedPercentage) : null, |
| 109 | inputTokens: null, |
| 110 | cachedInputTokens: null, |
| 111 | outputTokens: null, |
| 112 | reasoningOutputTokens: null, |
| 113 | lastUsedTokens: null, |
| 114 | lastInputTokens: null, |
| 115 | lastCachedInputTokens: null, |
| 116 | lastOutputTokens: null, |
| 117 | lastReasoningOutputTokens: null, |
| 118 | toolUses: null, |
| 119 | durationMs: null, |
| 120 | compactsAutomatically: true, |
| 121 | autoCompactThreshold: null, |
| 122 | cost: null, |
| 123 | updatedAt, |
| 124 | }; |
| 125 | } |
| 126 | |
| 127 | export function deriveLatestContextWindowSnapshot( |
| 128 | entries: ReadonlyArray<{ |
| 129 | readonly item: ThreadStructureTurnItem; |
| 130 | }>, |
| 131 | liveUsage?: OrchestrationV2ProviderTurnTokenUsage | null, |
| 132 | providerThread?: Pick<OrchestrationV2ProviderThread, "id" | "contextUsage" | "updatedAt"> | null, |
| 133 | ): ContextWindowSnapshot | null { |
| 134 | const latestCompletedCompaction = entries.findLast( |
| 135 | (entry): entry is { readonly item: CompactionItem } => |
| 136 | entry.item.type === "compaction" && |
| 137 | entry.item.status === "completed" && |
| 138 | !isRetiredProviderThreadItem(entry.item, providerThread), |
| 139 | )?.item; |
| 140 | const usageUpdatedAt = |
| 141 | liveUsage?.updatedAt ?? |
| 142 | (providerThread?.contextUsage != null ? DateTime.formatIso(providerThread.updatedAt) : null); |
| 143 | if (latestCompletedCompaction !== undefined) { |
| 144 | const compactedAt = DateTime.formatIso( |
| 145 | latestCompletedCompaction.completedAt ?? latestCompletedCompaction.updatedAt, |
| 146 | ); |
| 147 | // Usage reported before the compaction describes the context it just discarded; usage at |
| 148 | // the same instant is the provider's own post-compaction report. |
| 149 | if (usageUpdatedAt === null || Date.parse(compactedAt) > Date.parse(usageUpdatedAt)) { |
| 150 | return compactionSnapshot( |
| 151 | latestCompletedCompaction, |
| 152 | liveUsage?.maxTokens ?? asFiniteNumber(providerThread?.contextUsage?.maxTokens), |
| 153 | compactedAt, |
| 154 | ); |
| 155 | } |
| 156 | } |
| 157 | |
| 158 | if (liveUsage != null) { |
| 159 | const usedTokens = Math.max(0, liveUsage.usedTokens); |
| 160 | const maxTokens = liveUsage.maxTokens ?? null; |
| 161 | const usedPercentage = |
| 162 | maxTokens !== null && maxTokens > 0 ? Math.min(100, (usedTokens / maxTokens) * 100) : null; |
| 163 | const remainingTokens = |
| 164 | maxTokens !== null ? Math.max(0, Math.round(maxTokens - usedTokens)) : null; |
| 165 | const remainingPercentage = usedPercentage !== null ? Math.max(0, 100 - usedPercentage) : null; |
| 166 | return { |
| 167 | usedTokens, |
| 168 | totalProcessedTokens: null, |
| 169 | maxTokens, |
| 170 | remainingTokens, |
| 171 | usedPercentage, |
| 172 | remainingPercentage, |
| 173 | inputTokens: liveUsage.inputTokens ?? null, |
| 174 | cachedInputTokens: liveUsage.cachedInputTokens ?? null, |
| 175 | outputTokens: liveUsage.outputTokens ?? null, |
| 176 | reasoningOutputTokens: liveUsage.reasoningOutputTokens ?? null, |
| 177 | lastUsedTokens: null, |
| 178 | lastInputTokens: null, |
| 179 | lastCachedInputTokens: null, |
| 180 | lastOutputTokens: null, |
| 181 | lastReasoningOutputTokens: null, |
| 182 | toolUses: null, |
| 183 | durationMs: null, |
| 184 | compactsAutomatically: true, |
| 185 | autoCompactThreshold: liveUsage.autoCompactThreshold ?? null, |
| 186 | cost: null, |
| 187 | updatedAt: liveUsage.updatedAt, |
| 188 | }; |
| 189 | } |
| 190 | const providerUsage = providerThread?.contextUsage; |
| 191 | const providerUsageUpdatedAt = providerThread?.updatedAt; |
| 192 | if ( |
| 193 | providerUsage !== null && |
| 194 | providerUsage !== undefined && |
| 195 | providerUsageUpdatedAt !== undefined |
| 196 | ) { |
| 197 | const maxTokens = asFiniteNumber(providerUsage.maxTokens); |
| 198 | const usedTokens = providerUsage.usedTokens; |
| 199 | const usedPercentage = |
| 200 | maxTokens !== null && maxTokens > 0 ? Math.min(100, (usedTokens / maxTokens) * 100) : null; |
| 201 | return { |
| 202 | usedTokens, |
| 203 | totalProcessedTokens: asFiniteNumber(providerUsage.totalProcessedTokens), |
| 204 | maxTokens, |
| 205 | remainingTokens: maxTokens === null ? null : Math.max(0, Math.round(maxTokens - usedTokens)), |
| 206 | usedPercentage, |
| 207 | remainingPercentage: usedPercentage === null ? null : Math.max(0, 100 - usedPercentage), |
| 208 | inputTokens: asFiniteNumber(providerUsage.inputTokens), |
| 209 | cachedInputTokens: asFiniteNumber(providerUsage.cachedInputTokens), |
| 210 | outputTokens: asFiniteNumber(providerUsage.outputTokens), |
| 211 | reasoningOutputTokens: asFiniteNumber(providerUsage.reasoningOutputTokens), |
| 212 | lastUsedTokens: asFiniteNumber(providerUsage.lastUsedTokens), |
| 213 | lastInputTokens: asFiniteNumber(providerUsage.lastInputTokens), |
| 214 | lastCachedInputTokens: asFiniteNumber(providerUsage.lastCachedInputTokens), |
| 215 | lastOutputTokens: asFiniteNumber(providerUsage.lastOutputTokens), |
| 216 | lastReasoningOutputTokens: asFiniteNumber(providerUsage.lastReasoningOutputTokens), |
| 217 | toolUses: asFiniteNumber(providerUsage.toolUses), |
| 218 | durationMs: asFiniteNumber(providerUsage.durationMs), |
| 219 | compactsAutomatically: providerUsage.compactsAutomatically ?? null, |
| 220 | cost: providerUsage.cost ?? null, |
| 221 | autoCompactThreshold: providerUsage.autoCompactThreshold ?? null, |
| 222 | updatedAt: DateTime.formatIso(providerUsageUpdatedAt), |
| 223 | }; |
| 224 | } |
| 225 | for (let index = entries.length - 1; index >= 0; index -= 1) { |
| 226 | const item = entries[index]?.item; |
| 227 | if (item?.type !== "compaction" || isRetiredProviderThreadItem(item, providerThread)) { |
| 228 | continue; |
| 229 | } |
| 230 | const snapshot = compactionSnapshot( |
| 231 | item, |
| 232 | null, |
| 233 | DateTime.formatIso(item.startedAt ?? item.updatedAt), |
| 234 | ); |
| 235 | if (snapshot !== null) return snapshot; |
| 236 | } |
| 237 | |
| 238 | return null; |
| 239 | } |
| 240 | |
| 241 | export function hasDismissedResumeCompaction( |
| 242 | activities: ReadonlyArray<{ readonly kind: string; readonly payload: unknown }>, |
| 243 | ): boolean { |
| 244 | return activities.some((activity) => { |
| 245 | if (activity.kind !== "user-input.resolved") return false; |
| 246 | const payload = activity.payload; |
| 247 | if (!payload || typeof payload !== "object") return false; |
| 248 | const answers = (payload as { readonly answers?: unknown }).answers; |
| 249 | if (!answers || typeof answers !== "object" || Array.isArray(answers)) return false; |
| 250 | |
| 251 | return Object.entries(answers).some( |
| 252 | ([question, answer]) => |
| 253 | isClaudeResumeCompactionQuestion(question) && |
| 254 | answer === CLAUDE_RESUME_COMPACTION_NEVER_ANSWER, |
| 255 | ); |
| 256 | }); |
| 257 | } |
| 258 | |
| 259 | export function shouldOfferResumeCompaction(input: { |
| 260 | readonly provider: string | null | undefined; |
| 261 | readonly usedTokens: number | null | undefined; |
| 262 | readonly updatedAt: string | null | undefined; |
| 263 | readonly promptCacheTtlMs?: number | undefined; |
| 264 | readonly now: string; |
| 265 | }): boolean { |
| 266 | if ( |
| 267 | input.provider !== "claudeAgent" || |
| 268 | (input.usedTokens ?? 0) < COMPACTION_SUGGESTION_MIN_TOKENS |
| 269 | ) { |
| 270 | return false; |
| 271 | } |
| 272 | |
| 273 | const updatedAt = Date.parse(input.updatedAt ?? ""); |
| 274 | const now = Date.parse(input.now); |
| 275 | return ( |
| 276 | Number.isFinite(updatedAt) && |
| 277 | Number.isFinite(now) && |
| 278 | now - updatedAt >= (input.promptCacheTtlMs ?? CLAUDE_RESUME_COMPACTION_FALLBACK_MS) |
| 279 | ); |
| 280 | } |
| 281 | |
| 282 | /** |
| 283 | * The tokens a plain send into an idle thread compacts first, as web's composer does under |
| 284 | * "When you return", or null when it sends as is. Web reads the same state for its "Compact and |
| 285 | * send" button. A send that hands off to another conversation starts that one fresh, so only the |
| 286 | * resumed one counts. |
| 287 | */ |
| 288 | export function compactBeforeSendTokens(input: { |
| 289 | readonly projection: Pick< |
| 290 | ThreadStructure, |
| 291 | | "thread" |
| 292 | | "contextTransfers" |
| 293 | | "providerThreads" |
| 294 | | "providerTurns" |
| 295 | | "runtimeRequests" |
| 296 | | "runs" |
| 297 | | "visibleTurnItems" |
| 298 | >; |
| 299 | readonly visibleTurnItems: ReadonlyArray<{ readonly item: ThreadStructureTurnItem }>; |
| 300 | readonly selection: ModelSelection; |
| 301 | readonly providers: ReadonlyArray<ServerProvider>; |
| 302 | readonly settings: Pick< |
| 303 | ServerSettings, |
| 304 | "providerInstances" | "compactIdleThreads" | "idleCompaction" |
| 305 | >; |
| 306 | readonly text: string; |
| 307 | readonly threadIdle: boolean; |
| 308 | readonly now: string; |
| 309 | }): number | null { |
| 310 | const { projection } = input; |
| 311 | const provider = input.providers.find((entry) => entry.instanceId === input.selection.instanceId); |
| 312 | if ( |
| 313 | provider === undefined || |
| 314 | !input.threadIdle || |
| 315 | COMPACT_COMMAND_PATTERN.test(input.text) || |
| 316 | resolveIdleCompaction(input.settings, provider.instanceId) === "off" || |
| 317 | !provider.slashCommands.some((command) => command.name === "compact") || |
| 318 | resolvePendingHandoff(projection, input.selection, input.providers) !== null || |
| 319 | projection.runtimeRequests.some((request) => request.status === "pending") || |
| 320 | projection.runs.some((run) => run.status === "queued" && run.queueHeld === true) || |
| 321 | (!input.visibleTurnItems.some( |
| 322 | ({ item }) => |
| 323 | item.type === "user_message" && |
| 324 | (item.text.trim().toLowerCase() !== "/compact" || item.attachments.length > 0), |
| 325 | ) && |
| 326 | !projection.runs.some( |
| 327 | (run) => |
| 328 | run.status !== "rolled_back" && |
| 329 | run.startedAt !== null && |
| 330 | !input.visibleTurnItems.some( |
| 331 | ({ item }) => item.type === "user_message" && item.runId === run.id, |
| 332 | ), |
| 333 | )) || |
| 334 | hasDismissedResumeCompaction( |
| 335 | projection.runtimeRequests |
| 336 | .filter((request) => request.kind === "user_input" && request.status === "resolved") |
| 337 | .map((request) => ({ kind: "user-input.resolved", payload: { answers: request.answers } })), |
| 338 | ) |
| 339 | ) { |
| 340 | return null; |
| 341 | } |
| 342 | const activeProviderThreadId = projection.thread.activeProviderThreadId; |
| 343 | const providerThread = projection.providerThreads.find( |
| 344 | (thread) => thread.id === activeProviderThreadId, |
| 345 | ); |
| 346 | const liveUsage = latestProviderTurnTokenUsage( |
| 347 | projection.providerTurns.filter((turn) => turn.providerThreadId === activeProviderThreadId), |
| 348 | input.selection.instanceId === projection.thread.modelSelection.instanceId ? projection : null, |
| 349 | providerThread, |
| 350 | ); |
| 351 | const contextWindow = deriveLatestContextWindowSnapshot( |
| 352 | input.visibleTurnItems, |
| 353 | liveUsage, |
| 354 | providerThread, |
| 355 | ); |
| 356 | return contextWindow !== null && |
| 357 | shouldOfferResumeCompaction({ |
| 358 | provider: provider.driver, |
| 359 | usedTokens: contextWindow.usedTokens, |
| 360 | updatedAt: contextWindow.updatedAt, |
| 361 | promptCacheTtlMs: liveUsage?.promptCacheTtlMs, |
| 362 | now: input.now, |
| 363 | }) |
| 364 | ? contextWindow.usedTokens |
| 365 | : null; |
| 366 | } |