rafcode 2.2.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/CLAUDE.md +19 -4
  2. package/RAF/ahtahs-token-reaper/decisions.md +37 -0
  3. package/RAF/ahtahs-token-reaper/input.md +20 -0
  4. package/RAF/ahtahs-token-reaper/outcomes/01-extend-token-tracker-data-model.md +42 -0
  5. package/RAF/ahtahs-token-reaper/outcomes/02-accumulate-usage-in-retry-loop.md +31 -0
  6. package/RAF/ahtahs-token-reaper/outcomes/03-per-attempt-display-formatting.md +60 -0
  7. package/RAF/ahtahs-token-reaper/outcomes/04-add-model-name-to-claude-call-logs.md +57 -0
  8. package/RAF/ahtahs-token-reaper/outcomes/05-handle-invalid-config-in-raf-config.md +46 -0
  9. package/RAF/ahtahs-token-reaper/outcomes/06-fix-verbose-toggle-timer-display.md +38 -0
  10. package/RAF/ahtahs-token-reaper/plans/01-extend-token-tracker-data-model.md +36 -0
  11. package/RAF/ahtahs-token-reaper/plans/02-accumulate-usage-in-retry-loop.md +36 -0
  12. package/RAF/ahtahs-token-reaper/plans/03-per-attempt-display-formatting.md +43 -0
  13. package/RAF/ahtahs-token-reaper/plans/04-add-model-name-to-claude-call-logs.md +38 -0
  14. package/RAF/ahtahs-token-reaper/plans/05-handle-invalid-config-in-raf-config.md +36 -0
  15. package/RAF/ahtahs-token-reaper/plans/06-fix-verbose-toggle-timer-display.md +40 -0
  16. package/RAF/ahvrih-rate-forge/decisions.md +70 -0
  17. package/RAF/ahvrih-rate-forge/input.md +44 -0
  18. package/RAF/ahvrih-rate-forge/outcomes/01-remove-claude-command-config.md +58 -0
  19. package/RAF/ahvrih-rate-forge/outcomes/02-fix-mixed-attempt-cost.md +46 -0
  20. package/RAF/ahvrih-rate-forge/outcomes/03-rate-limit-estimation.md +82 -0
  21. package/RAF/ahvrih-rate-forge/outcomes/04-show-version-in-do-logs.md +45 -0
  22. package/RAF/ahvrih-rate-forge/outcomes/05-sync-main-before-worktree.md +96 -0
  23. package/RAF/ahvrih-rate-forge/outcomes/06-sync-readme-with-codebase.md +45 -0
  24. package/RAF/ahvrih-rate-forge/outcomes/07-no-session-persistence.md +26 -0
  25. package/RAF/ahvrih-rate-forge/outcomes/08-plan-execution-metadata.md +130 -0
  26. package/RAF/ahvrih-rate-forge/plans/01-remove-claude-command-config.md +36 -0
  27. package/RAF/ahvrih-rate-forge/plans/02-fix-mixed-attempt-cost.md +33 -0
  28. package/RAF/ahvrih-rate-forge/plans/03-rate-limit-estimation.md +82 -0
  29. package/RAF/ahvrih-rate-forge/plans/04-show-version-in-do-logs.md +32 -0
  30. package/RAF/ahvrih-rate-forge/plans/05-sync-main-before-worktree.md +40 -0
  31. package/RAF/ahvrih-rate-forge/plans/06-sync-readme-with-codebase.md +61 -0
  32. package/RAF/ahvrih-rate-forge/plans/07-no-session-persistence.md +28 -0
  33. package/RAF/ahvrih-rate-forge/plans/08-plan-execution-metadata.md +123 -0
  34. package/README.md +27 -7
  35. package/dist/commands/config.d.ts.map +1 -1
  36. package/dist/commands/config.js +24 -7
  37. package/dist/commands/config.js.map +1 -1
  38. package/dist/commands/do.d.ts.map +1 -1
  39. package/dist/commands/do.js +122 -27
  40. package/dist/commands/do.js.map +1 -1
  41. package/dist/commands/plan.d.ts.map +1 -1
  42. package/dist/commands/plan.js +79 -3
  43. package/dist/commands/plan.js.map +1 -1
  44. package/dist/core/claude-runner.d.ts +6 -6
  45. package/dist/core/claude-runner.d.ts.map +1 -1
  46. package/dist/core/claude-runner.js +9 -10
  47. package/dist/core/claude-runner.js.map +1 -1
  48. package/dist/core/failure-analyzer.d.ts.map +1 -1
  49. package/dist/core/failure-analyzer.js +3 -3
  50. package/dist/core/failure-analyzer.js.map +1 -1
  51. package/dist/core/pull-request.d.ts.map +1 -1
  52. package/dist/core/pull-request.js +5 -3
  53. package/dist/core/pull-request.js.map +1 -1
  54. package/dist/core/state-derivation.d.ts +5 -0
  55. package/dist/core/state-derivation.d.ts.map +1 -1
  56. package/dist/core/state-derivation.js +14 -4
  57. package/dist/core/state-derivation.js.map +1 -1
  58. package/dist/core/worktree.d.ts +32 -0
  59. package/dist/core/worktree.d.ts.map +1 -1
  60. package/dist/core/worktree.js +215 -0
  61. package/dist/core/worktree.js.map +1 -1
  62. package/dist/prompts/amend.d.ts.map +1 -1
  63. package/dist/prompts/amend.js +26 -11
  64. package/dist/prompts/amend.js.map +1 -1
  65. package/dist/prompts/planning.d.ts.map +1 -1
  66. package/dist/prompts/planning.js +26 -11
  67. package/dist/prompts/planning.js.map +1 -1
  68. package/dist/types/config.d.ts +30 -13
  69. package/dist/types/config.d.ts.map +1 -1
  70. package/dist/types/config.js +14 -10
  71. package/dist/types/config.js.map +1 -1
  72. package/dist/utils/config.d.ts +53 -4
  73. package/dist/utils/config.d.ts.map +1 -1
  74. package/dist/utils/config.js +197 -30
  75. package/dist/utils/config.js.map +1 -1
  76. package/dist/utils/frontmatter.d.ts +43 -0
  77. package/dist/utils/frontmatter.d.ts.map +1 -0
  78. package/dist/utils/frontmatter.js +85 -0
  79. package/dist/utils/frontmatter.js.map +1 -0
  80. package/dist/utils/name-generator.d.ts.map +1 -1
  81. package/dist/utils/name-generator.js +2 -3
  82. package/dist/utils/name-generator.js.map +1 -1
  83. package/dist/utils/session-parser.d.ts +44 -0
  84. package/dist/utils/session-parser.d.ts.map +1 -0
  85. package/dist/utils/session-parser.js +122 -0
  86. package/dist/utils/session-parser.js.map +1 -0
  87. package/dist/utils/terminal-symbols.d.ts +28 -5
  88. package/dist/utils/terminal-symbols.d.ts.map +1 -1
  89. package/dist/utils/terminal-symbols.js +77 -18
  90. package/dist/utils/terminal-symbols.js.map +1 -1
  91. package/dist/utils/token-tracker.d.ts +31 -1
  92. package/dist/utils/token-tracker.d.ts.map +1 -1
  93. package/dist/utils/token-tracker.js +94 -4
  94. package/dist/utils/token-tracker.js.map +1 -1
  95. package/package.json +1 -1
  96. package/src/commands/config.ts +26 -7
  97. package/src/commands/do.ts +157 -29
  98. package/src/commands/plan.ts +89 -2
  99. package/src/core/claude-runner.ts +16 -17
  100. package/src/core/failure-analyzer.ts +3 -3
  101. package/src/core/pull-request.ts +5 -3
  102. package/src/core/state-derivation.ts +20 -4
  103. package/src/core/worktree.ts +230 -0
  104. package/src/prompts/amend.ts +26 -11
  105. package/src/prompts/config-docs.md +91 -29
  106. package/src/prompts/planning.ts +26 -11
  107. package/src/types/config.ts +46 -21
  108. package/src/utils/config.ts +222 -33
  109. package/src/utils/frontmatter.ts +110 -0
  110. package/src/utils/name-generator.ts +2 -3
  111. package/src/utils/session-parser.ts +161 -0
  112. package/src/utils/terminal-symbols.ts +105 -18
  113. package/src/utils/token-tracker.ts +109 -4
  114. package/tests/unit/claude-runner-interactive.test.ts +8 -6
  115. package/tests/unit/claude-runner.test.ts +5 -66
  116. package/tests/unit/config-command.test.ts +84 -5
  117. package/tests/unit/config.test.ts +292 -45
  118. package/tests/unit/frontmatter.test.ts +182 -0
  119. package/tests/unit/post-execution-picker.test.ts +5 -0
  120. package/tests/unit/session-parser.test.ts +301 -0
  121. package/tests/unit/terminal-symbols.test.ts +263 -33
  122. package/tests/unit/timer-verbose-integration.test.ts +170 -0
  123. package/tests/unit/token-tracker.test.ts +653 -17
  124. package/tests/unit/validation.test.ts +6 -4
  125. package/tests/unit/worktree.test.ts +242 -0
@@ -0,0 +1,161 @@
1
+ /**
2
+ * Utilities for parsing Claude CLI session files to extract token usage data.
3
+ * Claude CLI saves session data to ~/.claude/projects/<escaped-path>/<session-id>.jsonl
4
+ */
5
+
6
+ import * as fs from 'node:fs';
7
+ import * as path from 'node:path';
8
+ import * as os from 'node:os';
9
+ import type { UsageData } from '../types/config.js';
10
+
11
+ /** Raw usage structure from Claude session JSONL assistant message entries. */
12
+ interface SessionMessageUsage {
13
+ input_tokens?: number;
14
+ output_tokens?: number;
15
+ cache_read_input_tokens?: number;
16
+ cache_creation_input_tokens?: number;
17
+ }
18
+
19
+ /** Structure of an assistant message entry in the session JSONL. */
20
+ interface SessionMessageEntry {
21
+ type: 'assistant';
22
+ message?: {
23
+ usage?: SessionMessageUsage;
24
+ model?: string;
25
+ };
26
+ costUSD?: number;
27
+ }
28
+
29
+ /** Result of parsing a session file. */
30
+ export interface SessionParseResult {
31
+ /** Accumulated usage data from all assistant messages. */
32
+ usage: UsageData;
33
+ /** Whether parsing was successful. */
34
+ success: boolean;
35
+ /** Error message if parsing failed. */
36
+ error?: string;
37
+ }
38
+
39
+ /**
40
+ * Escape a path for use in Claude's project directory naming scheme.
41
+ * Claude escapes `/` to `-` in project paths.
42
+ */
43
+ export function escapeProjectPath(projectPath: string): string {
44
+ // Remove leading slash and replace remaining slashes with dashes
45
+ return projectPath.replace(/^\//, '').replace(/\//g, '-');
46
+ }
47
+
48
+ /**
49
+ * Compute the expected session file path for a given session ID and working directory.
50
+ *
51
+ * @param sessionId - The UUID session ID passed to --session-id
52
+ * @param cwd - The working directory where Claude was run (project path)
53
+ * @returns The expected path to the session JSONL file
54
+ */
55
+ export function getSessionFilePath(sessionId: string, cwd: string): string {
56
+ const claudeDir = path.join(os.homedir(), '.claude', 'projects');
57
+ const escapedPath = escapeProjectPath(cwd);
58
+ return path.join(claudeDir, escapedPath, `${sessionId}.jsonl`);
59
+ }
60
+
61
+ /**
62
+ * Parse a Claude session JSONL file and extract accumulated token usage data.
63
+ *
64
+ * @param sessionFilePath - Path to the session JSONL file
65
+ * @returns Parsed usage data or error information
66
+ */
67
+ export function parseSessionFile(sessionFilePath: string): SessionParseResult {
68
+ const emptyUsage: UsageData = {
69
+ inputTokens: 0,
70
+ outputTokens: 0,
71
+ cacheReadInputTokens: 0,
72
+ cacheCreationInputTokens: 0,
73
+ modelUsage: {},
74
+ };
75
+
76
+ if (!fs.existsSync(sessionFilePath)) {
77
+ return {
78
+ usage: emptyUsage,
79
+ success: false,
80
+ error: `Session file not found: ${sessionFilePath}`,
81
+ };
82
+ }
83
+
84
+ try {
85
+ const content = fs.readFileSync(sessionFilePath, 'utf-8');
86
+ const lines = content.trim().split('\n').filter(line => line.trim());
87
+
88
+ const accumulated: UsageData = { ...emptyUsage, modelUsage: {} };
89
+
90
+ for (const line of lines) {
91
+ try {
92
+ const entry = JSON.parse(line) as Record<string, unknown>;
93
+
94
+ // Only process assistant message entries
95
+ if (entry.type !== 'assistant') continue;
96
+
97
+ const assistantEntry = entry as unknown as SessionMessageEntry;
98
+ const usage = assistantEntry.message?.usage;
99
+ const model = assistantEntry.message?.model;
100
+
101
+ if (!usage) continue;
102
+
103
+ const inputTokens = usage.input_tokens ?? 0;
104
+ const outputTokens = usage.output_tokens ?? 0;
105
+ const cacheReadTokens = usage.cache_read_input_tokens ?? 0;
106
+ const cacheCreateTokens = usage.cache_creation_input_tokens ?? 0;
107
+
108
+ // Accumulate aggregate totals
109
+ accumulated.inputTokens += inputTokens;
110
+ accumulated.outputTokens += outputTokens;
111
+ accumulated.cacheReadInputTokens += cacheReadTokens;
112
+ accumulated.cacheCreationInputTokens += cacheCreateTokens;
113
+
114
+ // Accumulate per-model usage
115
+ if (model) {
116
+ const existing = accumulated.modelUsage[model];
117
+ if (existing) {
118
+ existing.inputTokens += inputTokens;
119
+ existing.outputTokens += outputTokens;
120
+ existing.cacheReadInputTokens += cacheReadTokens;
121
+ existing.cacheCreationInputTokens += cacheCreateTokens;
122
+ } else {
123
+ accumulated.modelUsage[model] = {
124
+ inputTokens,
125
+ outputTokens,
126
+ cacheReadInputTokens: cacheReadTokens,
127
+ cacheCreationInputTokens: cacheCreateTokens,
128
+ };
129
+ }
130
+ }
131
+ } catch {
132
+ // Skip malformed lines
133
+ continue;
134
+ }
135
+ }
136
+
137
+ return {
138
+ usage: accumulated,
139
+ success: true,
140
+ };
141
+ } catch (error) {
142
+ return {
143
+ usage: emptyUsage,
144
+ success: false,
145
+ error: `Failed to parse session file: ${error}`,
146
+ };
147
+ }
148
+ }
149
+
150
+ /**
151
+ * Parse a Claude session by session ID and working directory.
152
+ * Convenience wrapper around getSessionFilePath + parseSessionFile.
153
+ *
154
+ * @param sessionId - The UUID session ID passed to --session-id
155
+ * @param cwd - The working directory where Claude was run
156
+ * @returns Parsed usage data or error information
157
+ */
158
+ export function parseSessionById(sessionId: string, cwd: string): SessionParseResult {
159
+ const filePath = getSessionFilePath(sessionId, cwd);
160
+ return parseSessionFile(filePath);
161
+ }
@@ -5,7 +5,17 @@
5
5
 
6
6
  import { formatElapsedTime } from './timer.js';
7
7
  import type { UsageData } from '../types/config.js';
8
- import type { CostBreakdown } from './token-tracker.js';
8
+ import type { CostBreakdown, TaskUsageEntry } from './token-tracker.js';
9
+
10
+ /** Options for token summary formatting. */
11
+ export interface TokenSummaryOptions {
12
+ /** Whether to show cache token counts. Default: true */
13
+ showCacheTokens?: boolean;
14
+ /** Whether to show rate limit percentage. Default: true */
15
+ showRateLimitEstimate?: boolean;
16
+ /** Rate limit percentage to display (requires showRateLimitEstimate: true) */
17
+ rateLimitPercentage?: number;
18
+ }
9
19
 
10
20
  /**
11
21
  * Visual symbols for terminal output using dots/symbols style.
@@ -146,39 +156,112 @@ export function formatCost(cost: number): string {
146
156
  }
147
157
 
148
158
  /**
149
- * Formats a per-task token usage summary line.
150
- * Example: " Tokens: 5,234 in / 1,023 out | Cache: 18,500 read | Est. cost: $0.42"
159
+ * Formats a rate limit percentage for display.
160
+ * Uses tilde (~) prefix to indicate estimate.
161
+ */
162
+ export function formatRateLimitPercentage(percentage: number): string {
163
+ if (percentage === 0) return '~0% of 5h window';
164
+ if (percentage < 0.1) return `~${percentage.toFixed(2)}% of 5h window`;
165
+ if (percentage < 1) return `~${percentage.toFixed(1)}% of 5h window`;
166
+ return `~${Math.round(percentage)}% of 5h window`;
167
+ }
168
+
169
+ /**
170
+ * Formats a single line of token usage (for a single attempt or total).
171
+ * Used internally by formatTaskTokenSummary.
151
172
  */
152
- export function formatTaskTokenSummary(usage: UsageData, cost: CostBreakdown): string {
173
+ function formatTokenLine(
174
+ usage: UsageData,
175
+ costValue: number,
176
+ prefix: string = '',
177
+ indent: string = ' ',
178
+ options: TokenSummaryOptions = {}
179
+ ): string {
180
+ const { showCacheTokens = true, showRateLimitEstimate = false, rateLimitPercentage } = options;
153
181
  const parts: string[] = [];
154
- parts.push(`Tokens: ${formatNumber(usage.inputTokens)} in / ${formatNumber(usage.outputTokens)} out`);
155
-
156
- const cacheTotal = usage.cacheReadInputTokens + usage.cacheCreationInputTokens;
157
- if (cacheTotal > 0) {
158
- if (usage.cacheReadInputTokens > 0 && usage.cacheCreationInputTokens > 0) {
159
- parts.push(`Cache: ${formatNumber(usage.cacheReadInputTokens)} read / ${formatNumber(usage.cacheCreationInputTokens)} created`);
160
- } else if (usage.cacheReadInputTokens > 0) {
161
- parts.push(`Cache: ${formatNumber(usage.cacheReadInputTokens)} read`);
162
- } else {
163
- parts.push(`Cache: ${formatNumber(usage.cacheCreationInputTokens)} created`);
182
+ const tokenPart = `${formatNumber(usage.inputTokens)} in / ${formatNumber(usage.outputTokens)} out`;
183
+ parts.push(prefix ? `${prefix}: ${tokenPart}` : `Tokens: ${tokenPart}`);
184
+
185
+ if (showCacheTokens) {
186
+ const cacheTotal = usage.cacheReadInputTokens + usage.cacheCreationInputTokens;
187
+ if (cacheTotal > 0) {
188
+ if (usage.cacheReadInputTokens > 0 && usage.cacheCreationInputTokens > 0) {
189
+ parts.push(`Cache: ${formatNumber(usage.cacheReadInputTokens)} read / ${formatNumber(usage.cacheCreationInputTokens)} created`);
190
+ } else if (usage.cacheReadInputTokens > 0) {
191
+ parts.push(`Cache: ${formatNumber(usage.cacheReadInputTokens)} read`);
192
+ } else {
193
+ parts.push(`Cache: ${formatNumber(usage.cacheCreationInputTokens)} created`);
194
+ }
164
195
  }
165
196
  }
166
197
 
167
- parts.push(`Est. cost: ${formatCost(cost.totalCost)}`);
168
- return ` ${parts.join(' | ')}`;
198
+ parts.push(`Est. cost: ${formatCost(costValue)}`);
199
+
200
+ if (showRateLimitEstimate && rateLimitPercentage !== undefined) {
201
+ parts.push(formatRateLimitPercentage(rateLimitPercentage));
202
+ }
203
+
204
+ return `${indent}${parts.join(' | ')}`;
205
+ }
206
+
207
+ /**
208
+ * Formats a per-task token usage summary.
209
+ * For single-attempt tasks: " Tokens: 5,234 in / 1,023 out | Cache: 18,500 read | Est. cost: $0.42 | ~2% of 5h window"
210
+ * For multi-attempt tasks: shows per-attempt breakdown plus total.
211
+ *
212
+ * @param entry - The TaskUsageEntry containing accumulated usage, cost, and attempts array
213
+ * @param calculateAttemptCost - Optional function to calculate cost for a single attempt's UsageData
214
+ * @param options - Display options for showing cache tokens and rate limit percentage
215
+ */
216
+ export function formatTaskTokenSummary(
217
+ entry: TaskUsageEntry,
218
+ calculateAttemptCost?: (usage: UsageData) => CostBreakdown,
219
+ options: TokenSummaryOptions = {}
220
+ ): string {
221
+ // Single-attempt: render exactly as before (no per-attempt breakdown)
222
+ if (entry.attempts.length <= 1) {
223
+ return formatTokenLine(entry.usage, entry.cost.totalCost, '', ' ', options);
224
+ }
225
+
226
+ // Multi-attempt: show per-attempt lines plus total
227
+ // Per-attempt lines don't show rate limit (only show on total)
228
+ const perAttemptOptions: TokenSummaryOptions = {
229
+ ...options,
230
+ showRateLimitEstimate: false,
231
+ rateLimitPercentage: undefined,
232
+ };
233
+
234
+ const lines: string[] = [];
235
+ entry.attempts.forEach((attemptUsage, i) => {
236
+ const attemptCost = calculateAttemptCost
237
+ ? calculateAttemptCost(attemptUsage).totalCost
238
+ : 0;
239
+ lines.push(formatTokenLine(attemptUsage, attemptCost, `Attempt ${i + 1}`, ' ', perAttemptOptions));
240
+ });
241
+ lines.push(formatTokenLine(entry.usage, entry.cost.totalCost, 'Total', ' ', options));
242
+ return lines.join('\n');
169
243
  }
170
244
 
171
245
  /**
172
246
  * Formats the grand total token usage summary block.
173
247
  * Displayed after all tasks complete.
248
+ *
249
+ * @param usage - Total usage data
250
+ * @param cost - Total cost breakdown
251
+ * @param options - Display options for cache tokens and rate limit
174
252
  */
175
- export function formatTokenTotalSummary(usage: UsageData, cost: CostBreakdown): string {
253
+ export function formatTokenTotalSummary(
254
+ usage: UsageData,
255
+ cost: CostBreakdown,
256
+ options: TokenSummaryOptions = {}
257
+ ): string {
258
+ const { showCacheTokens = true, showRateLimitEstimate = false, rateLimitPercentage } = options;
176
259
  const lines: string[] = [];
177
260
  const divider = '── Token Usage Summary ──────────────────';
178
261
  lines.push(divider);
179
262
  lines.push(`Total tokens: ${formatNumber(usage.inputTokens)} in / ${formatNumber(usage.outputTokens)} out`);
180
263
 
181
- if (usage.cacheReadInputTokens > 0 || usage.cacheCreationInputTokens > 0) {
264
+ if (showCacheTokens && (usage.cacheReadInputTokens > 0 || usage.cacheCreationInputTokens > 0)) {
182
265
  const cacheParts: string[] = [];
183
266
  if (usage.cacheReadInputTokens > 0) {
184
267
  cacheParts.push(`${formatNumber(usage.cacheReadInputTokens)} read`);
@@ -190,6 +273,10 @@ export function formatTokenTotalSummary(usage: UsageData, cost: CostBreakdown):
190
273
  }
191
274
 
192
275
  lines.push(`Estimated cost: ${formatCost(cost.totalCost)}`);
276
+
277
+ if (showRateLimitEstimate && rateLimitPercentage !== undefined) {
278
+ lines.push(formatRateLimitPercentage(rateLimitPercentage));
279
+ }
193
280
  lines.push('─────────────────────────────────────────');
194
281
  return lines.join('\n');
195
282
  }
@@ -1,5 +1,5 @@
1
1
  import { UsageData, PricingConfig } from '../types/config.js';
2
- import { resolveModelPricingCategory, getPricingConfig } from './config.js';
2
+ import { resolveModelPricingCategory, getPricingConfig, getRateLimitWindowConfig } from './config.js';
3
3
 
4
4
  /** Cost breakdown for a single task or accumulated total. */
5
5
  export interface CostBreakdown {
@@ -13,8 +13,71 @@ export interface CostBreakdown {
13
13
  /** Per-task usage snapshot stored by the tracker. */
14
14
  export interface TaskUsageEntry {
15
15
  taskId: string;
16
+ /** Accumulated usage across all attempts. */
16
17
  usage: UsageData;
18
+ /** Cost breakdown for accumulated usage. */
17
19
  cost: CostBreakdown;
20
+ /** Raw per-attempt usage data (for display breakdowns). */
21
+ attempts: UsageData[];
22
+ }
23
+
24
+ /**
25
+ * Sum multiple CostBreakdown objects into a single total.
26
+ */
27
+ export function sumCostBreakdowns(costs: CostBreakdown[]): CostBreakdown {
28
+ const result: CostBreakdown = {
29
+ inputCost: 0,
30
+ outputCost: 0,
31
+ cacheReadCost: 0,
32
+ cacheCreateCost: 0,
33
+ totalCost: 0,
34
+ };
35
+
36
+ for (const cost of costs) {
37
+ result.inputCost += cost.inputCost;
38
+ result.outputCost += cost.outputCost;
39
+ result.cacheReadCost += cost.cacheReadCost;
40
+ result.cacheCreateCost += cost.cacheCreateCost;
41
+ result.totalCost += cost.totalCost;
42
+ }
43
+
44
+ return result;
45
+ }
46
+
47
+ /**
48
+ * Merge multiple UsageData objects into a single accumulated UsageData.
49
+ * Sums all token fields and merges modelUsage maps.
50
+ */
51
+ export function accumulateUsage(attempts: UsageData[]): UsageData {
52
+ const result: UsageData = {
53
+ inputTokens: 0,
54
+ outputTokens: 0,
55
+ cacheReadInputTokens: 0,
56
+ cacheCreationInputTokens: 0,
57
+ modelUsage: {},
58
+ };
59
+
60
+ for (const attempt of attempts) {
61
+ result.inputTokens += attempt.inputTokens;
62
+ result.outputTokens += attempt.outputTokens;
63
+ result.cacheReadInputTokens += attempt.cacheReadInputTokens;
64
+ result.cacheCreationInputTokens += attempt.cacheCreationInputTokens;
65
+
66
+ // Merge per-model usage
67
+ for (const [modelId, modelUsage] of Object.entries(attempt.modelUsage)) {
68
+ const existing = result.modelUsage[modelId];
69
+ if (existing) {
70
+ existing.inputTokens += modelUsage.inputTokens;
71
+ existing.outputTokens += modelUsage.outputTokens;
72
+ existing.cacheReadInputTokens += modelUsage.cacheReadInputTokens;
73
+ existing.cacheCreationInputTokens += modelUsage.cacheCreationInputTokens;
74
+ } else {
75
+ result.modelUsage[modelId] = { ...modelUsage };
76
+ }
77
+ }
78
+ }
79
+
80
+ return result;
18
81
  }
19
82
 
20
83
  /**
@@ -31,10 +94,17 @@ export class TokenTracker {
31
94
 
32
95
  /**
33
96
  * Record usage data from a completed task.
97
+ * Accepts an array of UsageData (one per attempt) and accumulates them.
98
+ * Cost is calculated per-attempt to avoid underreporting when some attempts
99
+ * have modelUsage and others only have aggregate fields.
34
100
  */
35
- addTask(taskId: string, usage: UsageData): TaskUsageEntry {
36
- const cost = this.calculateCost(usage);
37
- const entry: TaskUsageEntry = { taskId, usage, cost };
101
+ addTask(taskId: string, attempts: UsageData[]): TaskUsageEntry {
102
+ const usage = accumulateUsage(attempts);
103
+ // Calculate cost per-attempt, then sum. This ensures attempts with only
104
+ // aggregate fields use sonnet fallback pricing independently.
105
+ const perAttemptCosts = attempts.map((attempt) => this.calculateCost(attempt));
106
+ const cost = sumCostBreakdowns(perAttemptCosts);
107
+ const entry: TaskUsageEntry = { taskId, usage, cost, attempts };
38
108
  this.entries.push(entry);
39
109
  return entry;
40
110
  }
@@ -132,4 +202,39 @@ export class TokenTracker {
132
202
  result.totalCost = result.inputCost + result.outputCost + result.cacheReadCost + result.cacheCreateCost;
133
203
  return result;
134
204
  }
205
+
206
+ /**
207
+ * Calculate the 5h rate limit window percentage for a given cost.
208
+ * Converts cost to Sonnet-equivalent tokens using the configured Sonnet pricing,
209
+ * then divides by the configured cap.
210
+ *
211
+ * @param totalCost - The total cost in dollars
212
+ * @param sonnetTokenCap - Optional override for the Sonnet-equivalent token cap (defaults to config value)
213
+ * @returns The percentage of the 5h window consumed (0-100+)
214
+ */
215
+ calculateRateLimitPercentage(totalCost: number, sonnetTokenCap?: number): number {
216
+ if (totalCost === 0) return 0;
217
+
218
+ // Get the configured cap or use the provided override
219
+ const cap = sonnetTokenCap ?? getRateLimitWindowConfig().sonnetTokenCap;
220
+
221
+ // Calculate the average Sonnet cost per token
222
+ // Using the average of input and output pricing (simplified approach)
223
+ const sonnetPricing = this.pricingConfig.sonnet;
224
+ const avgSonnetCostPerToken = (sonnetPricing.inputPerMTok + sonnetPricing.outputPerMTok) / 2 / 1_000_000;
225
+
226
+ // Convert cost to Sonnet-equivalent tokens
227
+ const sonnetEquivalentTokens = totalCost / avgSonnetCostPerToken;
228
+
229
+ // Calculate percentage
230
+ return (sonnetEquivalentTokens / cap) * 100;
231
+ }
232
+
233
+ /**
234
+ * Get the cumulative 5h window percentage across all recorded tasks.
235
+ */
236
+ getCumulativeRateLimitPercentage(sonnetTokenCap?: number): number {
237
+ const totals = this.getTotals();
238
+ return this.calculateRateLimitPercentage(totals.cost.totalCost, sonnetTokenCap);
239
+ }
135
240
  }
@@ -144,7 +144,9 @@ describe('ClaudeRunner - runInteractive', () => {
144
144
 
145
145
  const spawnArgs = mockPtySpawn.mock.calls[0][1] as string[];
146
146
  expect(spawnArgs).toContain('--model');
147
- expect(spawnArgs).toContain('opus');
147
+ // Default model comes from config, could be short alias or full model ID
148
+ const modelArgIndex = spawnArgs.indexOf('--model');
149
+ expect(spawnArgs[modelArgIndex + 1]).toMatch(/^(opus|sonnet|haiku|claude-(opus|sonnet|haiku)-.+)$/);
148
150
 
149
151
  mockProc._exitCallback({ exitCode: 0 });
150
152
  await runPromise;
@@ -244,8 +246,8 @@ describe('ClaudeRunner - runInteractive', () => {
244
246
  });
245
247
  });
246
248
 
247
- describe('effort level (not applied in interactive mode)', () => {
248
- it('should NOT set CLAUDE_CODE_EFFORT_LEVEL in runInteractive env', async () => {
249
+ describe('environment passing', () => {
250
+ it('should pass process.env to pty spawn in runInteractive', async () => {
249
251
  const mockProc = createMockPtyProcess();
250
252
  const mockStdin = createMockStdin();
251
253
  const mockStdout = createMockStdout();
@@ -256,12 +258,12 @@ describe('ClaudeRunner - runInteractive', () => {
256
258
  mockPtySpawn.mockReturnValue(mockProc);
257
259
 
258
260
  const runner = new ClaudeRunner();
259
- // Even if effortLevel were somehow passed, interactive mode should use process.env as-is
260
261
  const runPromise = runner.runInteractive('system', 'user');
261
262
 
262
263
  const spawnOptions = mockPtySpawn.mock.calls[0][2];
263
- // Interactive mode passes process.env directly, no effort level override
264
- expect(spawnOptions.env).not.toHaveProperty('CLAUDE_CODE_EFFORT_LEVEL');
264
+ // Interactive mode passes process.env directly
265
+ // Note: effortLevel option was removed from ClaudeRunner in favor of per-task model resolution
266
+ expect(spawnOptions.env).toBeDefined();
265
267
 
266
268
  mockProc._exitCallback({ exitCode: 0 });
267
269
  await runPromise;
@@ -473,7 +473,9 @@ describe('ClaudeRunner', () => {
473
473
  });
474
474
  });
475
475
 
476
- describe('effort level', () => {
476
+ // Note: effortLevel option was removed from ClaudeRunner in favor of per-task model resolution
477
+ // via plan frontmatter. See effortMapping config and frontmatter.ts for the new approach.
478
+ describe('environment handling', () => {
477
479
  function createMockProcess() {
478
480
  const stdout = new EventEmitter();
479
481
  const stderr = new EventEmitter();
@@ -484,35 +486,7 @@ describe('ClaudeRunner', () => {
484
486
  return proc;
485
487
  }
486
488
 
487
- it('should set CLAUDE_CODE_EFFORT_LEVEL env var in run() when effortLevel is provided', async () => {
488
- const mockProc = createMockProcess();
489
- mockSpawn.mockReturnValue(mockProc);
490
-
491
- const runner = new ClaudeRunner();
492
- const runPromise = runner.run('test prompt', { timeout: 60, effortLevel: 'medium' });
493
-
494
- mockProc.emit('close', 0);
495
- await runPromise;
496
-
497
- const spawnOptions = mockSpawn.mock.calls[0][2];
498
- expect(spawnOptions.env.CLAUDE_CODE_EFFORT_LEVEL).toBe('medium');
499
- });
500
-
501
- it('should set CLAUDE_CODE_EFFORT_LEVEL env var in runVerbose() when effortLevel is provided', async () => {
502
- const mockProc = createMockProcess();
503
- mockSpawn.mockReturnValue(mockProc);
504
-
505
- const runner = new ClaudeRunner();
506
- const runPromise = runner.runVerbose('test prompt', { timeout: 60, effortLevel: 'medium' });
507
-
508
- mockProc.emit('close', 0);
509
- await runPromise;
510
-
511
- const spawnOptions = mockSpawn.mock.calls[0][2];
512
- expect(spawnOptions.env.CLAUDE_CODE_EFFORT_LEVEL).toBe('medium');
513
- });
514
-
515
- it('should NOT set CLAUDE_CODE_EFFORT_LEVEL when effortLevel is not provided in run()', async () => {
489
+ it('should pass process.env to child process in run()', async () => {
516
490
  const mockProc = createMockProcess();
517
491
  mockSpawn.mockReturnValue(mockProc);
518
492
 
@@ -523,11 +497,10 @@ describe('ClaudeRunner', () => {
523
497
  await runPromise;
524
498
 
525
499
  const spawnOptions = mockSpawn.mock.calls[0][2];
526
- // env should be process.env directly (no CLAUDE_CODE_EFFORT_LEVEL override)
527
500
  expect(spawnOptions.env).toBe(process.env);
528
501
  });
529
502
 
530
- it('should NOT set CLAUDE_CODE_EFFORT_LEVEL when effortLevel is not provided in runVerbose()', async () => {
503
+ it('should pass process.env to child process in runVerbose()', async () => {
531
504
  const mockProc = createMockProcess();
532
505
  mockSpawn.mockReturnValue(mockProc);
533
506
 
@@ -538,42 +511,8 @@ describe('ClaudeRunner', () => {
538
511
  await runPromise;
539
512
 
540
513
  const spawnOptions = mockSpawn.mock.calls[0][2];
541
- // env should be process.env directly (no CLAUDE_CODE_EFFORT_LEVEL override)
542
514
  expect(spawnOptions.env).toBe(process.env);
543
515
  });
544
-
545
- it('should support different effort levels', async () => {
546
- for (const level of ['low', 'medium', 'high'] as const) {
547
- const mockProc = createMockProcess();
548
- mockSpawn.mockReturnValue(mockProc);
549
-
550
- const runner = new ClaudeRunner();
551
- const runPromise = runner.run('test prompt', { timeout: 60, effortLevel: level });
552
-
553
- mockProc.emit('close', 0);
554
- await runPromise;
555
-
556
- const spawnOptions = mockSpawn.mock.calls[mockSpawn.mock.calls.length - 1][2];
557
- expect(spawnOptions.env.CLAUDE_CODE_EFFORT_LEVEL).toBe(level);
558
- }
559
- });
560
-
561
- it('should preserve other env vars when effortLevel is set', async () => {
562
- const mockProc = createMockProcess();
563
- mockSpawn.mockReturnValue(mockProc);
564
-
565
- const runner = new ClaudeRunner();
566
- const runPromise = runner.run('test prompt', { timeout: 60, effortLevel: 'medium' });
567
-
568
- mockProc.emit('close', 0);
569
- await runPromise;
570
-
571
- const spawnOptions = mockSpawn.mock.calls[0][2];
572
- // Should have PATH from process.env
573
- expect(spawnOptions.env.PATH).toBe(process.env.PATH);
574
- // And the injected effort level
575
- expect(spawnOptions.env.CLAUDE_CODE_EFFORT_LEVEL).toBe('medium');
576
- });
577
516
  });
578
517
 
579
518
  describe('system prompt append flag', () => {