Add cost-proxy token guidance · Entire
Add cost-proxy token guidance
d4cd759·
Sessions
e46d5e136530View transcript
Changes
4
cmd/entire/cli
Mcheckpoint_tokens.go+90/-2
Msession_tokens.go+68/-11
Msessions_test.go+352/-16
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
7 unmodified lines
}
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
193 unmodified lines
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
29 unmodified lines
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
100 unmodified lines
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
465
518
519
467
520
521
469
470
471
522
523
473
524
525
475
526
527
477
528
529
479
530
531
532
533
5 unmodified lines
539
540
541
542
543
544
545
546
547
548
549
550
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
}
193 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.")
}