Add cost-proxy token guidance · Entire
Add cost-proxy token guidance
f942458·
peyton-alt·3w ago·3 files·+504 added/-27 removed
Sessions
e46d5e136530View transcript
Changes
3
cmd/entire/cli
Mcheckpoint_tokens.go+90/-2
Msession_tokens.go+62/-9
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
17 unmodified lines
65
66
67
68
69
70
71
10 unmodified lines
82
83
84
80
85
86
87
88
89
90
91
92
93
94
95
96
97
89
98
99
100
101
16 unmodified lines
118
119
120
121
122
123
124
125
126
127
259 unmodified lines
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
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
92 unmodified lines
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
4 unmodified lines
574
575
576
577
578
579
580
581
582
583
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"`
Qualification string `json:"qualification"`
Limitations []string `json:"limitations,omitempty"`
17 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
}
259 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.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 {
delta := &checkpointTokensMetricDelta{
Baseline: baseline,
92 unmodified lines
QwriteTokenLimitations(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
4 unmodified lines
fmt.Fprintf(w, "Baseline: %s\n", comparison.BaselineCheckpointID)
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)