Add cost-proxy token guidance · Entire
Add cost-proxy token guidance
d837fa0·
peyton-alt·3w ago·4 files·+541 added/-40 removed
Sessions
e46d5e136530View transcript
Changes
4
cmd/entire/cli
Mcheckpoint_tokens.go+90/-2
Msession_tokens.go+68/-11
Msessions_test.go+352/-16
strategy
Msession_state.go+31/-11
2 unmodified lines
3
4
5
6
7
8
9
28 unmodified lines
38
39
40
41
42
43
44
45
46
47
22 unmodified lines
70
71
72
73
74
75
76
10 unmodified lines
87
88
89
85
90
91
92
93
94
95
96
97
98
99
100
101
102
94
103
104
105
106
16 unmodified lines
123
124
125
126
127
128
129
130
131
132
271 unmodified lines
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
126 unmodified lines
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
7 unmodified lines
629
630
631
632
633
634
635
636
637
638
2 unmodified lines
import (
"context"
"encoding/json"
"errors"
"fmt"
"io"
"strconv"
28 unmodified lines
TargetCheckpointID string `json:"target_checkpoint_id"`
Status string `json:"status"`
Total *checkpointTokensMetricDelta `json:"total,omitempty"`
Input *checkpointTokensMetricDelta `json:"input,omitempty"`
CacheRead *checkpointTokensMetricDelta `json:"cache_read,omitempty"`
CacheWrite *checkpointTokensMetricDelta `json:"cache_write,omitempty"`
Output *checkpointTokensMetricDelta `json:"output,omitempty"`
APICalls *checkpointTokensMetricDelta `json:"api_calls,omitempty"`
CacheReadCaveat string `json:"cache_read_caveat,omitempty"`
Qualification string `json:"qualification"`
22 unmodified lines
func newCheckpointTokensCmd() *cobra.Command {
var jsonFlag bool
var compareFlag string
var agentBriefFlag bool
cmd := &cobra.Command{
Use: "tokens <checkpoint-id>",
10 unmodified lines
checkpoint and qualify observed token reduction or increase.`,
Args: cobra.ExactArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
return runCheckpointTokens(cmd.Context(), cmd, args[0], jsonFlag, compareFlag)
if jsonFlag && agentBriefFlag {
return errors.New("--json and --agent-brief are mutually exclusive")
}
return runCheckpointTokens(cmd.Context(), cmd, args[0], jsonFlag, compareFlag, agentBriefFlag)
},
}
cmd.Flags().BoolVar(&jsonFlag, "json", false, "Output as JSON")
cmd.Flags().StringVar(&compareFlag, "compare", "", "Compare against a baseline checkpoint ID")
cmd.Flags().BoolVar(&agentBriefFlag, "agent-brief", false, "Output compact next-step guidance for agents")
return cmd
}
func runCheckpointTokens(ctx context.Context, cmd *cobra.Command, checkpointIDPrefix string, jsonOutput bool, comparePrefix string) error {
func runCheckpointTokens(ctx context.Context, cmd *cobra.Command, checkpointIDPrefix string, jsonOutput bool, comparePrefix string, agentBrief bool) error {
report, lookup, err := loadCheckpointTokensReport(ctx, cmd, checkpointIDPrefix)
if lookup != nil {
defer lookup.Close()
16 unmodified lines
if jsonOutput {
return writeCheckpointTokensJSON(cmd.OutOrStdout(), report)
}
if agentBrief {
writeCheckpointTokensAgentBrief(cmd.OutOrStdout(), report)
return nil
}
writeCheckpointTokensText(cmd.OutOrStdout(), report)
return nil
}
271 unmodified lines
}
comparison.Total = buildCheckpointMetricDelta(baseline.Tokens.Total, target.Tokens.Total)
comparison.Input = buildCheckpointMetricDelta(baseline.Tokens.Input, target.Tokens.Input)
comparison.CacheRead = buildCheckpointMetricDelta(baseline.Tokens.CacheRead, target.Tokens.CacheRead)
comparison.CacheWrite = buildCheckpointMetricDelta(baseline.Tokens.CacheWrite, target.Tokens.CacheWrite)
comparison.Output = buildCheckpointMetricDelta(baseline.Tokens.Output, target.Tokens.Output)
comparison.APICalls = buildCheckpointMetricDelta(baseline.Tokens.APICalls, target.Tokens.APICalls)
comparison.CacheReadCaveat = checkpointComparisonCacheReadCaveat(comparison.CacheRead)
comparison.Status = checkpointComparisonStatus(comparison.Total)
comparison.Qualification = checkpointComparisonQualification(comparison.Status)
if classes := checkpointCostProxyPressureIncreased(comparison); len(classes) > 0 {
comparison.Qualification += fmt.Sprintf(" Cost-proxy pressure increased for %s even though total tokens decreased.", formatTokenClassList(classes))
}
return comparison
}
func checkpointCostProxyPressureIncreased(comparison *checkpointTokensComparison) []string {
if comparison == nil || comparison.Total == nil || comparison.Total.Change >= 0 {
return nil
}
var classes []string
if comparison.CacheWrite != nil && comparison.CacheWrite.Change > 0 {
classes = append(classes, "cache write")
}
if comparison.Output != nil && comparison.Output.Change > 0 {
classes = append(classes, "output")
}
return classes
}
func formatTokenClassList(classes []string) string {
switch len(classes) {
case 0:
return ""
case 1:
return classes[0]
case 2:
return classes[0] + " and " + classes[1]
default:
return strings.Join(classes[:len(classes)-1], ", ") + ", and " + classes[len(classes)-1]
}
}
func buildCheckpointMetricDelta(baseline, current int) *checkpointTokensMetricDelta {
change := saturatingIntSub(current, baseline)
delta := &checkpointTokensMetricDelta{
126 unmodified lines
writeTokenLimitations(w, report.Limitations)
}
func writeCheckpointTokensAgentBrief(w io.Writer, report checkpointTokensReport) {
fmt.Fprintln(w, "Checkpoint token brief")
fmt.Fprintf(w, "Checkpoint: %s\n", report.CheckpointID)
fmt.Fprintln(w)
fmt.Fprintln(w, agentBriefUsageLine(report.Tokens))
fmt.Fprintln(w)
fmt.Fprintln(w, "Next best action:")
fmt.Fprintln(w, checkpointAgentBriefNextAction(report))
signals := agentBriefSignals(checkpointAgentBriefSessionReport(report))
if len(signals) > 0 {
fmt.Fprintln(w)
fmt.Fprintln(w, "Signals:")
for _, signal := range signals {
fmt.Fprintf(w, "- %s\n", signal)
}
}
}
func checkpointAgentBriefNextAction(report checkpointTokensReport) string {
sessionReport := checkpointAgentBriefSessionReport(report)
if hasTokenRecommendation(sessionReport, "no-token-data") {
return "Do not spend extra commands on token optimization for this checkpoint. Continue with the task and capture a newer checkpoint before rechecking tokens."
}
if action, ok := agentBriefOptimizationAction(sessionReport); ok {
return action
}
return "Continue normally; no high-signal token optimization is available from this checkpoint."
}
func checkpointAgentBriefSessionReport(report checkpointTokensReport) sessionTokensReport {
return sessionTokensReport{
Tokens: report.Tokens,
Context: report.Context,
Recommendations: report.Recommendations,
Limitations: report.Limitations,
}
}
func writeCheckpointTokenComparison(w io.Writer, comparison *checkpointTokensComparison) {
if comparison == nil {
return
}
if comparison.Status != checkpointComparisonStatusUnavailable {
fmt.Fprintf(w, "Total tokens: %s\n", formatCheckpointMetricDelta(comparison.Total, formatTokenCount))
fmt.Fprintf(w, "Input: %s\n", formatCheckpointMetricDelta(comparison.Input, formatTokenCount))
fmt.Fprintf(w, "Cache/context replay: %s\n", formatCheckpointMetricDelta(comparison.CacheRead, formatTokenCount))
fmt.Fprintf(w, "Cache write: %s\n", formatCheckpointMetricDelta(comparison.CacheWrite, formatTokenCount))
fmt.Fprintf(w, "Output: %s\n", formatCheckpointMetricDelta(comparison.Output, formatTokenCount))
fmt.Fprintf(w, "API calls: %s\n", formatCheckpointMetricDelta(comparison.APICalls, formatPlainCount))
}
fmt.Fprintln(w)
Mcmd/entire/cli/checkpoint_tokens.go+90/-2
75 unmodified lines
76
77
78
79
80
81
82
83
36 unmodified lines
120
121
122
121
122
123
124
125
126
127
128
129
130
131
202 unmodified lines
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
29 unmodified lines
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
100 unmodified lines
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
474
527
528
476
529
530
478
479
480
531
532
482
533
534
484
535
536
486
537
538
488
539
540
541
542
5 unmodified lines
548
549
550
551
552
553
554
555
556
557
558
559
75 unmodified lines
recommendationLongSessionCheckpoints = 5
)
const agentBriefCostProxyBatchAction = "Use at most 3 batched reads before answering. Continue only if a named file or test can change the verdict; otherwise answer now. Avoid broad grep, broad diffs, broad tests, and repeated token diagnostics; keep the answer tight."
func newTokensCmd() *cobra.Command {
var jsonFlag bool
var currentFlag bool
36 unmodified lines
}
func runSessionTokens(ctx context.Context, cmd *cobra.Command, sessionID string, current, jsonOutput, agentBrief bool) error {
if sessionID == "" || current {
sessionID = strategy.FindMostRecentSession(ctx)
if sessionID == "" {
if current {
sessionID = strategy.FindMostRecentSessionInCurrentWorktree(ctx)
} else {
sessionID = strategy.FindMostRecentSession(ctx)
}
if sessionID == "" {
fmt.Fprintln(cmd.OutOrStdout(), "No active session found in this worktree.")
return nil
202 unmodified lines
Signals: []string{"subagent_tokens"},
})
}
if signals.Tokens != nil && signals.Tokens.Total > 0 &&
tokenClassPressure(signals.Tokens.CacheWrite, signals.Tokens.Total, 5000, 10, 50_000) {
recs = append(recs, sessionTokensRecommendation{
ID: "cache-write-pressure",
Severity: "medium",
Message: "Cache write is elevated; avoid broad new context and narrow the next read before continuing.",
Signals: []string{"cache_write_tokens"},
})
}
if signals.Tokens != nil && signals.Tokens.Total > 0 &&
tokenClassPressure(signals.Tokens.Output, signals.Tokens.Total, 3000, 2, 10_000) {
recs = append(recs, sessionTokensRecommendation{
ID: "output-pressure",
Severity: "medium",
Message: "Output tokens are elevated; keep the next answer tight and avoid restating evidence.",
Signals: []string{"output_tokens"},
})
}
if signals.Context != nil && signals.Context.Percent >= recommendationHighContextPercent {
recs = append(recs, sessionTokensRecommendation{
ID: "high-context-pressure",
29 unmodified lines
return part >= (total-1)/recommendationSubagentShareDenominator+1
}
func tokenClassPressure(value, total, minTokens int, minPercent float64, highTokens int) bool {
if value <= 0 || total <= 0 {
return false
}
if value >= highTokens {
return true
}
return value >= minTokens && tokenPercent(value, total) >= minPercent
}
func tokenPercent(value, total int) float64 {
if total <= 0 {
return 0
100 unmodified lines
}
func agentBriefNextAction(report sessionTokensReport) string {
if hasTokenRecommendation(report, "no-token-data") {
return "Token usage is not available yet. Use this as a context check, not a spend diagnosis; continue after the next checkpoint captures usage."
}
if action, ok := agentBriefOptimizationAction(report); ok {
return action
}
return "Continue normally; no high-signal token optimization is available from this session yet."
}
func agentBriefOptimizationAction(report sessionTokensReport) (string, bool) {
switch {
case (hasTokenRecommendation(report, "cache-write-pressure") || hasTokenRecommendation(report, "output-pressure")) &&
(hasTokenRecommendation(report, "context-replay-hotspot") || hasTokenRecommendation(report, "api-call-amplification") ):
return agentBriefCostProxyBatchAction, true
case hasTokenRecommendation(report, "cache-write-pressure") && hasTokenRecommendation(report, "output-pressure"):
return agentBriefCostProxyBatchAction, true
case hasTokenRecommendation(report, "cache-write-pressure"):
return "Use at most 3 batched reads and avoid broad new context until you have one narrowed hypothesis.", true
case hasTokenRecommendation(report, "output-pressure"):
return "Keep the next answer tight; cite only necessary evidence and avoid restating prior context.", true
case hasTokenRecommendation(report, "context-replay-hotspot") && hasTokenRecommendation(report, "api-call-amplification"):
return "Summarize the useful findings, then batch the next diagnostic step. Avoid more exploratory reads until you have a narrowed hypothesis."
return agentBriefCostProxyBatchAction, true
case hasTokenRecommendation(report, "api-call-amplification"):
return "Batch the next diagnostic step around one narrowed hypothesis before making more tool calls."
return agentBriefCostProxyBatchAction, true
case hasTokenRecommendation(report, "context-replay-hotspot"):
return "Summarize the current useful findings before continuing, and keep the next prompt narrow."
case hasTokenRecommendation(report, "no-token-data"):
return "Token usage is not available yet. Use this as a context check, not a spend diagnosis; continue after the next checkpoint captures usage."
return "Use at most 2 focused reads after summarizing known findings, then answer. Avoid broad grep, broad diffs, and broad tests.", true
case hasTokenRecommendation(report, "subagent-heavy"):
return "Keep the next agent or subagent task narrow with a concrete expected output; avoid broad parallel exploration."
return "Do not launch broad subagents. Use one narrowly scoped check with a concrete expected output.", true
case hasTokenRecommendation(report, "high-context-pressure"):
return "Preserve the useful findings and compact or restart before adding more broad context."
return "Preserve useful findings, then answer with at most 2 focused reads if more evidence is required.", true
case hasTokenRecommendation(report, "long-session"):
return "Compact or restart after summarizing useful findings if older context is no longer needed."
return "Summarize useful findings and stop unless one focused read can change the answer.", true
default:
return "Continue normally; no high-signal token optimization is available from this session yet."
return "", false
}
}
5 unmodified lines
if hasTokenRecommendation(report, "api-call-amplification") {
signals = append(signals, "API call count is high for one session.")
}
if hasTokenRecommendation(report, "cache-write-pressure") {
signals = append(signals, "Cache write/new context pressure is elevated.")
}
if hasTokenRecommendation(report, "output-pressure") {
signals = append(signals, "Output pressure is elevated.")
}
if hasTokenRecommendation(report, "subagent-heavy") {
signals = append(signals, "Subagent usage is a meaningful part of total tokens.")
}
Mcmd/entire/cli/session_tokens.go+68/-11
1238 unmodified lines
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
27 unmodified lines
1327
1328
1329
1275
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
37 unmodified lines
1377
1378
1379
1322
1380
1381
1382
1383
1384
34 unmodified lines
1419
1420
1421
1363
1422
1423
1424
1425
1426
46 unmodified lines
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
199 unmodified lines
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
1238 unmodified lines
Mcmd/entire/cli/strategy/session_state.go+31/-11