add agent brief for token diagnostics

dbd532c·

peyton-alt·3w ago·2 files·+292 added/-3 removed

Sessions

f1dfd807cfdcView transcript

[?
CLI Token Usage Visibility AnalysisCodex·GPT-5.5·3 steps](/content/gh/entireio/cli/session/019e988d-650c-75b3-a222-a00b07184ae0#timeline-f1dfd807cfdc/index.html)

Changes

2

• cmd/entire/cli

• Msession_tokens.go+111/-3

• Msessions_test.go+181

68 unmodified lines

func newTokensCmd() *cobra.Command {
    var jsonFlag bool
    var currentFlag bool
    var agentBriefFlag bool

cmd := &cobra.Command{
        Use:   "tokens [session-id]",

When no session ID is provided, Entire reports on the most recently active
session, preferring the current worktree and falling back to the newest session
if no state matches this worktree. The report uses token and context data Entire
already captured for the session.

func runSessionTokens(ctx context.Context, cmd *cobra.Command, sessionID string, current, jsonOutput bool) error { if sessionID == "" || current { sessionID = strategy.FindMostRecentSession(ctx) if sessionID == "" { return errors.New("Session ID is not specified") } }

if jsonOutput { return writeSessionTokensJSON(cmd.OutOrStdout(), report) }

writeSessionTokensText(cmd.OutOrStdout(), report) return nil }

func writeSessionTokensAgentBrief(w io.Writer, report sessionTokensReport) { fmt.Fprintln(w, "Session token brief") fmt.Fprintf(w, "Session: %s\n", report.SessionID) fmt.Fprintln(w)

fmt.Fprintln(w, "Next best action:")
fmt.Fprintln(w, agentBriefNextAction(report))

signals := agentBriefSignals(report) if len(signals) > 0 { fmt.Fprintln(w) fmt.Fprintln(w, "Signals:") for _, signal := range signals { fmt.Fprintf(w, "- %s\n", signal) } } }

func agentBriefNextAction(report sessionTokensReport) string { switch { case hasTokenRecommendation(report, "context-replay-hotspot") && hasTokenRecommendation(report, "api-call-amplification"): return "Summarize the useful findings, then batch the next diagnostic step." case hasTokenRecommendation(report, "context-replay-hotspot"): return "Summarize the current useful findings before continuing, and keep the next prompt narrow." default: return "Continue normally; no high-signal token optimization is available from this session yet." } }

// ... (remaining code snippets omitted for brevity)

func TestTokensCmd_AgentBriefPrioritizesNextAction(t *testing.T) { setupStopTestRepo(t)

ctx := context.Background() state := makeSessionState("test-tokens-brief", session.PhaseActive) state.AgentType = testAgentClaude state.TokenUsage = &agent.TokenUsage{ InputTokens: 94, CacheCreationTokens: 122171, CacheReadTokens: 6052424, OutputTokens: 38956, APICallCount: 70, }

if err := strategy.SaveSessionState(ctx, state); err != nil { t.Fatalf("SaveSessionState() error = %v", err) }

cmd := newTokensCmd() var stdout bytes.Buffer cmd.SetOut(&stdout) cmd.SetArgs([]string{"test-tokens-brief", "--agent-brief"})

if err := cmd.ExecuteContext(ctx); err != nil {
    t.Fatalf("expected no error, got: %v", err)
}

out := stdout.String() checks := []string{ "Session token brief", "Session: test-tokens-brief", "Token usage: 6213.6k total; 97.4% cache/context replay; 70 API calls.", "Next best action:", "Summarize the useful findings, then batch the next diagnostic step.", "Signals:", "- Cache/context replay dominates token volume.", } for _, check := range checks { if !strings.Contains(out, check) { t.Errorf("expected %q in output, got:\n%s", check, out) } } }