@the-bearded-bear/claude-craft 5.6.0 → 5.7.0-next.bf058ea

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.
@@ -0,0 +1,528 @@
1
+ #!/usr/bin/env bash
2
+ # =============================================================================
3
+ # Agent Teams - Token Cost Estimator
4
+ # Estimates token cost of Agent Teams operation vs sequential execution
5
+ #
6
+ # Based on empirical data from:
7
+ # - reports/audit-pipeline.md (Section 6: Token Cost Estimation)
8
+ # - reports/devils-advocate.md (Section 4.1: Realistic Cost Multiplier)
9
+ # =============================================================================
10
+ set -euo pipefail
11
+
12
+ # =============================================================================
13
+ # Constants: Model Pricing (per million tokens, USD)
14
+ # =============================================================================
15
+
16
+ # Input pricing ($/M tokens)
17
+ declare -A MODEL_INPUT_PRICE=(
18
+ [opus]=15.00
19
+ [sonnet]=3.00
20
+ [haiku]=0.25
21
+ )
22
+
23
+ # Output pricing ($/M tokens)
24
+ declare -A MODEL_OUTPUT_PRICE=(
25
+ [opus]=75.00
26
+ [sonnet]=15.00
27
+ [haiku]=1.25
28
+ )
29
+
30
+ # =============================================================================
31
+ # Constants: Token Usage Baselines (from audit-pipeline.md Section 6.1)
32
+ # =============================================================================
33
+
34
+ # Average tokens per audit check (sequential, single agent)
35
+ TOKENS_PER_CHECK=12500
36
+
37
+ # Technology detection phase (fixed cost)
38
+ TOKENS_DETECTION=2000
39
+
40
+ # Score calculation + report generation (fixed cost)
41
+ TOKENS_REPORT=8000
42
+
43
+ # =============================================================================
44
+ # Constants: Overhead Factors (from devils-advocate.md Section 4.1)
45
+ # =============================================================================
46
+
47
+ # Per-agent fixed overhead: system prompt, context loading, warmup
48
+ # (audit-pipeline.md Section 6.2: ~2K startup + ~3K coordination per agent)
49
+ TOKENS_AGENT_STARTUP=2000
50
+
51
+ # Per-agent coordination: task management, messaging
52
+ TOKENS_AGENT_COORDINATION=3000
53
+
54
+ # Context duplication factor by worker model
55
+ # Applied to per-agent context reload (not total work tokens)
56
+ # Each agent reloads ~5-8K of shared context (CLAUDE.md, project files)
57
+ # Haiku: smaller context but more retries -> higher duplication
58
+ # Sonnet: better reasoning, fewer retries -> moderate duplication
59
+ # Opus: best reasoning, no retries -> lowest duplication
60
+ declare -A CONTEXT_DUPLICATION_FACTOR=(
61
+ [haiku]=0.60
62
+ [sonnet]=0.30
63
+ [opus]=0.15
64
+ )
65
+
66
+ # Base context tokens each agent reloads (shared project context)
67
+ TOKENS_CONTEXT_PER_AGENT=6000
68
+
69
+ # Coordination overhead (task creation, messaging, status checks)
70
+ COORDINATION_OVERHEAD_PERCENT=15
71
+
72
+ # Input/output token ratio (approx 70% input, 30% output)
73
+ INPUT_RATIO=0.70
74
+ OUTPUT_RATIO=0.30
75
+
76
+ # =============================================================================
77
+ # Constants: Time Estimates
78
+ # =============================================================================
79
+
80
+ # Average minutes per check (sequential)
81
+ MINUTES_PER_CHECK=1.5
82
+
83
+ # Agent startup time (minutes)
84
+ AGENT_STARTUP_MINUTES=0.15
85
+
86
+ # Aggregation phase (minutes)
87
+ AGGREGATION_MINUTES=1.0
88
+
89
+ # =============================================================================
90
+ # Defaults
91
+ # =============================================================================
92
+
93
+ DEFAULT_TECHS=2
94
+ DEFAULT_CHECKS=5
95
+ DEFAULT_WORKER_MODEL="sonnet"
96
+ DEFAULT_LEADER_MODEL="opus"
97
+ DRY_RUN=false
98
+
99
+ # =============================================================================
100
+ # Usage
101
+ # =============================================================================
102
+
103
+ show_help() {
104
+ cat <<'HELP'
105
+ Agent Teams - Token Cost Estimator
106
+
107
+ Estimates token cost and time for Agent Teams parallel execution
108
+ versus sequential execution of audit/check commands.
109
+
110
+ USAGE:
111
+ cost-estimator.sh [OPTIONS]
112
+
113
+ OPTIONS:
114
+ --techs N Number of technology stacks (default: 2)
115
+ --checks N Number of checks per technology (default: 5)
116
+ --worker-model M Worker agent model: haiku|sonnet|opus (default: sonnet)
117
+ --leader-model M Leader agent model: haiku|sonnet|opus (default: opus)
118
+ --tokens-per-check N Override tokens per check estimate (default: 12500)
119
+ --dry-run Show configuration without calculating
120
+ --help Show this help
121
+
122
+ EXAMPLES:
123
+ # 2-tech project with Sonnet workers
124
+ cost-estimator.sh --techs 2 --checks 5 --worker-model sonnet
125
+
126
+ # 3-tech project with Haiku workers (cost-optimized)
127
+ cost-estimator.sh --techs 3 --checks 5 --worker-model haiku
128
+
129
+ # Quick check with dry-run
130
+ cost-estimator.sh --techs 4 --dry-run
131
+
132
+ COST FORMULA:
133
+ sequential_tokens = detection + (N_techs * N_checks * tokens_per_check) + report
134
+ parallel_tokens = sequential_tokens * (1 + overhead_factor)
135
+
136
+ overhead_factor = 0.14 * N_agents + context_duplication_factor + coordination_overhead
137
+
138
+ Context duplication factors:
139
+ haiku = 0.60 (smaller context, more retries)
140
+ sonnet = 0.30 (balanced)
141
+ opus = 0.15 (best reasoning, fewest retries)
142
+
143
+ DATA SOURCES:
144
+ - reports/audit-pipeline.md Section 6
145
+ - reports/devils-advocate.md Section 4.1
146
+ HELP
147
+ }
148
+
149
+ # =============================================================================
150
+ # Argument Parsing
151
+ # =============================================================================
152
+
153
+ parse_args() {
154
+ local n_techs=$DEFAULT_TECHS
155
+ local n_checks=$DEFAULT_CHECKS
156
+ local worker_model=$DEFAULT_WORKER_MODEL
157
+ local leader_model=$DEFAULT_LEADER_MODEL
158
+ local tokens_check=$TOKENS_PER_CHECK
159
+
160
+ while [[ $# -gt 0 ]]; do
161
+ case "$1" in
162
+ --techs)
163
+ n_techs="$2"
164
+ shift 2
165
+ ;;
166
+ --checks)
167
+ n_checks="$2"
168
+ shift 2
169
+ ;;
170
+ --worker-model)
171
+ worker_model="$2"
172
+ shift 2
173
+ ;;
174
+ --leader-model)
175
+ leader_model="$2"
176
+ shift 2
177
+ ;;
178
+ --tokens-per-check)
179
+ tokens_check="$2"
180
+ shift 2
181
+ ;;
182
+ --dry-run)
183
+ DRY_RUN=true
184
+ shift
185
+ ;;
186
+ --help|-h)
187
+ show_help
188
+ exit 0
189
+ ;;
190
+ *)
191
+ echo "ERROR: Unknown option: $1" >&2
192
+ echo "Use --help for usage information." >&2
193
+ exit 1
194
+ ;;
195
+ esac
196
+ done
197
+
198
+ # Validate inputs
199
+ if [[ ! "$n_techs" =~ ^[1-9][0-9]*$ ]]; then
200
+ echo "ERROR: --techs must be a positive integer, got: $n_techs" >&2
201
+ exit 1
202
+ fi
203
+ if [[ ! "$n_checks" =~ ^[1-9][0-9]*$ ]]; then
204
+ echo "ERROR: --checks must be a positive integer, got: $n_checks" >&2
205
+ exit 1
206
+ fi
207
+ if [[ -z "${MODEL_INPUT_PRICE[$worker_model]+x}" ]]; then
208
+ echo "ERROR: --worker-model must be haiku|sonnet|opus, got: $worker_model" >&2
209
+ exit 1
210
+ fi
211
+ if [[ -z "${MODEL_INPUT_PRICE[$leader_model]+x}" ]]; then
212
+ echo "ERROR: --leader-model must be haiku|sonnet|opus, got: $leader_model" >&2
213
+ exit 1
214
+ fi
215
+
216
+ # Export to globals
217
+ N_TECHS=$n_techs
218
+ N_CHECKS=$n_checks
219
+ WORKER_MODEL=$worker_model
220
+ LEADER_MODEL=$leader_model
221
+ TOKENS_PER_CHECK=$tokens_check
222
+ }
223
+
224
+ # =============================================================================
225
+ # Core Estimation Functions
226
+ # =============================================================================
227
+
228
+ # Calculate sequential token usage
229
+ # Returns: total tokens for sequential execution
230
+ estimate_sequential_tokens() {
231
+ local n_techs=$1
232
+ local n_checks=$2
233
+ local tokens_per_check=$3
234
+
235
+ local work_tokens=$((n_techs * n_checks * tokens_per_check))
236
+ local total=$((TOKENS_DETECTION + work_tokens + TOKENS_REPORT))
237
+
238
+ echo "$total"
239
+ }
240
+
241
+ # Calculate parallel token usage with Agent Teams
242
+ # Returns: total tokens for parallel execution
243
+ #
244
+ # Formula breakdown (from audit-pipeline.md Section 6.2 + devils-advocate.md Section 4.1):
245
+ # parallel_tokens = work_tokens
246
+ # + agent_startup_overhead (N_agents * startup_cost)
247
+ # + context_duplication (N_workers * context_per_agent * duplication_factor)
248
+ # + coordination_overhead (leader coordination with workers)
249
+ # + leader_overhead (detection + aggregation + report)
250
+ estimate_parallel_tokens() {
251
+ local n_techs=$1
252
+ local n_checks=$2
253
+ local tokens_per_check=$3
254
+ local worker_model=$4
255
+
256
+ local n_workers=$n_techs
257
+ local n_agents=$((n_techs + 1)) # 1 leader + N tech auditors
258
+
259
+ # Base work tokens (same work, distributed across agents)
260
+ local work_tokens=$((n_techs * n_checks * tokens_per_check))
261
+
262
+ # Agent startup overhead (each agent pays startup cost)
263
+ local startup_overhead=$((n_agents * TOKENS_AGENT_STARTUP))
264
+
265
+ # Context duplication: each worker reloads shared context
266
+ # Factor scales how much extra context is needed (retries, re-reads)
267
+ local ctx_factor=${CONTEXT_DUPLICATION_FACTOR[$worker_model]}
268
+ local ctx_overhead
269
+ ctx_overhead=$(awk "BEGIN { printf \"%d\", $n_workers * $TOKENS_CONTEXT_PER_AGENT * (1 + $ctx_factor) }")
270
+
271
+ # Leader overhead (detection + aggregation + per-worker coordination)
272
+ local leader_overhead=$((TOKENS_DETECTION + TOKENS_REPORT + TOKENS_AGENT_COORDINATION * n_workers))
273
+
274
+ # Coordination overhead: percentage of work tokens for messaging/task management
275
+ local coord_pct_overhead
276
+ coord_pct_overhead=$(awk "BEGIN { printf \"%d\", $work_tokens * $COORDINATION_OVERHEAD_PERCENT / 100 }")
277
+
278
+ # Total parallel tokens
279
+ local total=$((work_tokens + startup_overhead + ctx_overhead + leader_overhead + coord_pct_overhead))
280
+
281
+ echo "$total"
282
+ }
283
+
284
+ # Calculate sequential time estimate (minutes)
285
+ estimate_sequential_time() {
286
+ local n_techs=$1
287
+ local n_checks=$2
288
+
289
+ local total_checks=$((n_techs * n_checks))
290
+ # Sequential: each check runs one after another
291
+ local time
292
+ time=$(awk "BEGIN { printf \"%.1f\", $total_checks * $MINUTES_PER_CHECK + 1.0 }")
293
+ echo "$time"
294
+ }
295
+
296
+ # Calculate parallel time estimate (minutes)
297
+ estimate_parallel_time() {
298
+ local n_techs=$1
299
+ local n_checks=$2
300
+
301
+ # Parallel: all techs run simultaneously, checks within each tech are sequential
302
+ # Time = agent startup + max(checks per tech) + aggregation
303
+ local time
304
+ time=$(awk "BEGIN { printf \"%.1f\", $AGENT_STARTUP_MINUTES + ($n_checks * $MINUTES_PER_CHECK) + $AGGREGATION_MINUTES }")
305
+ echo "$time"
306
+ }
307
+
308
+ # Calculate cost in USD for a given model and token count
309
+ # Usage: calculate_cost <model> <total_tokens>
310
+ calculate_cost() {
311
+ local model=$1
312
+ local total_tokens=$2
313
+
314
+ local input_price=${MODEL_INPUT_PRICE[$model]}
315
+ local output_price=${MODEL_OUTPUT_PRICE[$model]}
316
+
317
+ # Split tokens into input/output using ratio
318
+ local cost
319
+ cost=$(awk "BEGIN {
320
+ input_tokens = $total_tokens * $INPUT_RATIO
321
+ output_tokens = $total_tokens * $OUTPUT_RATIO
322
+ input_cost = input_tokens * $input_price / 1000000
323
+ output_cost = output_tokens * $output_price / 1000000
324
+ printf \"%.4f\", input_cost + output_cost
325
+ }")
326
+
327
+ echo "$cost"
328
+ }
329
+
330
+ # Calculate blended cost for parallel execution (leader + workers)
331
+ calculate_parallel_cost() {
332
+ local leader_model=$1
333
+ local worker_model=$2
334
+ local total_tokens=$3
335
+ local n_techs=$4
336
+
337
+ local n_agents=$((n_techs + 1))
338
+
339
+ # Leader tokens (roughly 15-20% of total)
340
+ local leader_tokens
341
+ leader_tokens=$(awk "BEGIN { printf \"%d\", $total_tokens * 0.18 }")
342
+
343
+ # Worker tokens (remaining)
344
+ local worker_tokens=$((total_tokens - leader_tokens))
345
+
346
+ local leader_cost
347
+ leader_cost=$(calculate_cost "$leader_model" "$leader_tokens")
348
+
349
+ local worker_cost
350
+ worker_cost=$(calculate_cost "$worker_model" "$worker_tokens")
351
+
352
+ awk "BEGIN { printf \"%.4f\", $leader_cost + $worker_cost }"
353
+ }
354
+
355
+ # Calculate break-even point (min checks where parallel is faster)
356
+ calculate_break_even() {
357
+ local n_techs=$1
358
+
359
+ # Break-even: sequential time > parallel time
360
+ # seq_time = n_techs * n_checks * min_per_check + 1
361
+ # par_time = startup + n_checks * min_per_check + aggregation
362
+ # seq_time > par_time when:
363
+ # n_techs * n_checks * min_per_check > startup + n_checks * min_per_check + aggregation
364
+ # n_checks * min_per_check * (n_techs - 1) > startup + aggregation
365
+ # n_checks > (startup + aggregation) / (min_per_check * (n_techs - 1))
366
+
367
+ if [[ $n_techs -le 1 ]]; then
368
+ echo "N/A (single tech, no benefit)"
369
+ return
370
+ fi
371
+
372
+ local break_even
373
+ break_even=$(awk "BEGIN {
374
+ divisor = $MINUTES_PER_CHECK * ($n_techs - 1)
375
+ if (divisor <= 0) {
376
+ print \"N/A\"
377
+ } else {
378
+ be = ($AGENT_STARTUP_MINUTES + $AGGREGATION_MINUTES) / divisor
379
+ printf \"%d\", (be == int(be)) ? be : int(be) + 1
380
+ }
381
+ }")
382
+
383
+ echo "$break_even checks/tech"
384
+ }
385
+
386
+ # =============================================================================
387
+ # Output Functions
388
+ # =============================================================================
389
+
390
+ # Format token count with K suffix
391
+ format_tokens() {
392
+ local tokens=$1
393
+ awk "BEGIN { printf \"%.1fK\", $tokens / 1000 }"
394
+ }
395
+
396
+ # Format cost with $ prefix
397
+ format_cost() {
398
+ local cost=$1
399
+ awk "BEGIN { printf \"\$%.4f\", $cost }"
400
+ }
401
+
402
+ # Determine recommendation based on time/cost analysis
403
+ get_recommendation() {
404
+ local seq_time=$1
405
+ local par_time=$2
406
+ local seq_tokens=$3
407
+ local par_tokens=$4
408
+
409
+ local time_saved_pct
410
+ time_saved_pct=$(awk "BEGIN {
411
+ if ($seq_time <= 0) print 0
412
+ else printf \"%d\", (($seq_time - $par_time) / $seq_time) * 100
413
+ }")
414
+
415
+ local extra_cost_pct
416
+ extra_cost_pct=$(awk "BEGIN {
417
+ if ($seq_tokens <= 0) print 0
418
+ else printf \"%d\", (($par_tokens - $seq_tokens) / $seq_tokens) * 100
419
+ }")
420
+
421
+ # Recommendation logic: parallel if time_saved > 30% AND extra_cost < 50%
422
+ if [[ $time_saved_pct -gt 30 ]] && [[ $extra_cost_pct -lt 50 ]]; then
423
+ echo "USE PARALLEL"
424
+ else
425
+ echo "STAY SEQUENTIAL"
426
+ fi
427
+ }
428
+
429
+ # =============================================================================
430
+ # Dry Run Output
431
+ # =============================================================================
432
+
433
+ show_dry_run() {
434
+ cat <<EOF
435
+ === Cost Estimator Configuration (Dry Run) ===
436
+
437
+ Technologies: $N_TECHS
438
+ Checks per tech: $N_CHECKS
439
+ Total checks: $((N_TECHS * N_CHECKS))
440
+ Worker model: $WORKER_MODEL
441
+ Leader model: $LEADER_MODEL
442
+ Tokens per check: $TOKENS_PER_CHECK
443
+ Agent count: $((N_TECHS + 1)) (1 leader + $N_TECHS workers)
444
+
445
+ Context duplication factor ($WORKER_MODEL): ${CONTEXT_DUPLICATION_FACTOR[$WORKER_MODEL]}
446
+ Coordination overhead: ${COORDINATION_OVERHEAD_PERCENT}%
447
+
448
+ Model pricing (input/output per M tokens):
449
+ opus: \$${MODEL_INPUT_PRICE[opus]} / \$${MODEL_OUTPUT_PRICE[opus]}
450
+ sonnet: \$${MODEL_INPUT_PRICE[sonnet]} / \$${MODEL_OUTPUT_PRICE[sonnet]}
451
+ haiku: \$${MODEL_INPUT_PRICE[haiku]} / \$${MODEL_OUTPUT_PRICE[haiku]}
452
+
453
+ No calculation performed (--dry-run).
454
+ EOF
455
+ }
456
+
457
+ # =============================================================================
458
+ # Full Estimate Output (machine-readable key=value)
459
+ # =============================================================================
460
+
461
+ output_estimate() {
462
+ local seq_tokens
463
+ local par_tokens
464
+ local seq_time
465
+ local par_time
466
+ local seq_cost
467
+ local par_cost
468
+ local recommendation
469
+ local break_even
470
+
471
+ seq_tokens=$(estimate_sequential_tokens "$N_TECHS" "$N_CHECKS" "$TOKENS_PER_CHECK")
472
+ par_tokens=$(estimate_parallel_tokens "$N_TECHS" "$N_CHECKS" "$TOKENS_PER_CHECK" "$WORKER_MODEL")
473
+ seq_time=$(estimate_sequential_time "$N_TECHS" "$N_CHECKS")
474
+ par_time=$(estimate_parallel_time "$N_TECHS" "$N_CHECKS")
475
+ seq_cost=$(calculate_cost "$LEADER_MODEL" "$seq_tokens")
476
+ par_cost=$(calculate_parallel_cost "$LEADER_MODEL" "$WORKER_MODEL" "$par_tokens" "$N_TECHS")
477
+ recommendation=$(get_recommendation "$seq_time" "$par_time" "$seq_tokens" "$par_tokens")
478
+ break_even=$(calculate_break_even "$N_TECHS")
479
+
480
+ local token_overhead_pct
481
+ token_overhead_pct=$(awk "BEGIN {
482
+ if ($seq_tokens <= 0) print 0
483
+ else printf \"%d\", (($par_tokens - $seq_tokens) / $seq_tokens) * 100
484
+ }")
485
+
486
+ local time_saved_pct
487
+ time_saved_pct=$(awk "BEGIN {
488
+ if ($seq_time <= 0) print 0
489
+ else printf \"%d\", (($seq_time - $par_time) / $seq_time) * 100
490
+ }")
491
+
492
+ local time_saved_min
493
+ time_saved_min=$(awk "BEGIN { printf \"%.1f\", $seq_time - $par_time }")
494
+
495
+ # Output key=value pairs (consumable by cost-dashboard.sh)
496
+ cat <<EOF
497
+ TECHS=$N_TECHS
498
+ CHECKS=$N_CHECKS
499
+ WORKER_MODEL=$WORKER_MODEL
500
+ LEADER_MODEL=$LEADER_MODEL
501
+ SEQ_TOKENS=$seq_tokens
502
+ PAR_TOKENS=$par_tokens
503
+ SEQ_TIME=$seq_time
504
+ PAR_TIME=$par_time
505
+ SEQ_COST=$seq_cost
506
+ PAR_COST=$par_cost
507
+ TOKEN_OVERHEAD_PCT=$token_overhead_pct
508
+ TIME_SAVED_PCT=$time_saved_pct
509
+ TIME_SAVED_MIN=$time_saved_min
510
+ BREAK_EVEN=$break_even
511
+ RECOMMENDATION=$recommendation
512
+ EOF
513
+ }
514
+
515
+ # =============================================================================
516
+ # Library Mode: Source-able functions
517
+ # =============================================================================
518
+
519
+ # When sourced by another script, only define functions without executing
520
+ if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
521
+ parse_args "$@"
522
+
523
+ if [[ "$DRY_RUN" == "true" ]]; then
524
+ show_dry_run
525
+ else
526
+ output_estimate
527
+ fi
528
+ fi