Add cost-proxy token guidance

import (
    "context"
    "encoding/json"
    "errors"
    "fmt"
    "io"
    "strconv"
)

func newCheckpointTokensCmd() *cobra.Command {
    var jsonFlag bool
    var compareFlag string
    var agentBriefFlag bool

cmd := &cobra.Command{
        Use:   "tokens <checkpoint-id>",
        ...
    }

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 {
    report, lookup, err := loadCheckpointTokensReport(ctx, cmd, checkpointIDPrefix)
    if lookup != nil {
        defer lookup.Close()
    }
    ...
}

func writeCheckpointTokensAgentBrief(w io.Writer, report checkpointTokensReport) {
    fmt.Fprintln(w, "Checkpoint token brief")
    fmt.Fprintf(w, "Checkpoint: %s\n", report.CheckpointID)
    ...
}

func checkpointAgentBriefNextAction(report checkpointTokensReport) string {
    ...
}

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,
        Current:   current,
        ...
    }
    return delta
}

Changes

• cmd/entire/cli
  • Mcheckpoint_tokens.go+90/-2
  • Msession_tokens.go+62/-9
  • Msessions_test.go+352/-16

func TestRecommendationRules_CacheWritePressure(t *testing.T) {
    t.Parallel()

recs := recommendationRules(tokenRecommendationSignals{
        Tokens: &sessionTokensUsage{
            Total:      50_000,
            CacheWrite: 6_000,
        },
    })

if !recommendationsIncludeID(recs, "cache-write-pressure") {
        t.Fatalf("expected cache-write-pressure recommendation, got %+v", recs)
    }
}

func recommendationsIncludeID(recs []sessionTokensRecommendation, id string) bool {
    for _, rec := range recs {
        if rec.ID == id {
            return true
        }
    }
    return false
}