Skip to content

[codex] Add optimization intelligence reports#129

Merged
ya-nsh merged 2 commits into
mainfrom
feat/optimization-intelligence
May 17, 2026
Merged

[codex] Add optimization intelligence reports#129
ya-nsh merged 2 commits into
mainfrom
feat/optimization-intelligence

Conversation

@ya-nsh
Copy link
Copy Markdown
Owner

@ya-nsh ya-nsh commented May 16, 2026

Summary

Builds Tokenleak's Optimization Intelligence surface across core, CLI, MCP, terminal dashboards, OpenTUI, and live dashboard.

  • Adds Model Routing Simulator, Agent Waste Detector, and Agent Behavior Diff core reports with exported types/builders
  • Adds CLI commands and MCP tools for JSON/terminal optimization workflows
  • Adds OpenTUI and terminal-tab dashboard views plus live dashboard read-only optimization sections
  • Documents examples and adds regression coverage for core, CLI, and MCP paths

Validation

  • PATH="/Users/yansh/.bun/bin:$PATH" /Users/yansh/.bun/bin/bun run check
  • PATH="/Users/yansh/.bun/bin:$PATH" /Users/yansh/.bun/bin/bun run test

Note: Turborepo prints a lockfile parse warning from this external worktree path, but all tasks pass.

Summary by CodeRabbit

  • New Features

    • Added Routing Simulator to analyze model downgrade strategies and compare cost impact
    • Added Agent Waste Detection to identify inefficient patterns in agent behavior with estimated savings
    • Added Agent Behavior Diff to compare metrics across different agent behavior cohorts
    • All features available as CLI commands, interactive dashboard tabs, and MCP tools
  • Documentation

    • Updated README with descriptions of new optimization intelligence commands

Review Change Stack

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 16, 2026

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5c120f9d-449e-4ee6-a968-8d7dfb98b2b9

📥 Commits

Reviewing files that changed from the base of the PR and between d0ea3d6 and 6e0890d.

📒 Files selected for processing (35)
  • README.md
  • packages/cli/src/cli.test.ts
  • packages/cli/src/cli.ts
  • packages/cli/src/data-loader.ts
  • packages/cli/src/tabbed-dashboard.ts
  • packages/core/src/aggregation/agent-behavior-diff.ts
  • packages/core/src/aggregation/agent-waste.ts
  • packages/core/src/aggregation/index.ts
  • packages/core/src/aggregation/optimization-intelligence.test.ts
  • packages/core/src/aggregation/routing-simulator.ts
  • packages/core/src/index.ts
  • packages/core/src/types.ts
  • packages/mcp/src/server.test.ts
  • packages/mcp/src/tools/get-agent-behavior-diff.ts
  • packages/mcp/src/tools/get-agent-waste.ts
  • packages/mcp/src/tools/get-routing-simulation.ts
  • packages/mcp/src/tools/index.ts
  • packages/renderers/src/index.ts
  • packages/renderers/src/live/template.ts
  • packages/renderers/src/terminal/index.ts
  • packages/renderers/src/terminal/tab-views/agent-behavior-diff-view.ts
  • packages/renderers/src/terminal/tab-views/agent-waste-view.ts
  • packages/renderers/src/terminal/tab-views/index.ts
  • packages/renderers/src/terminal/tab-views/routing-simulator-view.ts
  • packages/renderers/src/terminal/tab-views/tab-bar.ts
  • packages/tui/src/index.ts
  • packages/tui/src/lib/data.ts
  • packages/tui/src/lib/state.ts
  • packages/tui/src/panels/behavior.ts
  • packages/tui/src/panels/header.ts
  • packages/tui/src/panels/help.ts
  • packages/tui/src/panels/optimization.test.ts
  • packages/tui/src/panels/simulator.ts
  • packages/tui/src/panels/status-bar.ts
  • packages/tui/src/panels/waste.ts

📝 Walkthrough

Walkthrough

This PR adds optimization intelligence analytics across all interfaces of tokenleak. Three new report builders—routing simulation, agent waste detection, and agent behavior comparison—are integrated into the CLI, TUI, MCP, and renderers with unified data models, caching, and navigation support.

Changes

Optimization Intelligence Feature

Layer / File(s) Summary
Type system for optimization intelligence
packages/core/src/types.ts
Defines OptimizationConfidence/Impact/Evidence, RoutingRule/Candidate/Report, WasteSignal/Report, BehaviorCohortSelector/Metrics/DiffReport types; extends TokenleakOutput with optional optimization field.
Routing simulation report builder
packages/core/src/aggregation/routing-simulator.ts
Implements buildRoutingSimulationReport with model downgrade rules, cost re-pricing, confidence calculation, and warnings; supports manual rule matching or built-in heuristics.
Agent waste signal detection
packages/core/src/aggregation/agent-waste.ts
Implements buildAgentWasteReport detecting context drag, prompt repeats, model churn, premium-for-small-task, cache-miss-heavy, cache-write-waste, and long-session-low-yield patterns with evidence and recipes.
Agent behavior comparison report
packages/core/src/aggregation/agent-behavior-diff.ts
Implements buildAgentBehaviorDiffReport comparing baseline vs comparison cohorts with per-metric deltas, percentage takeaways, and validation warnings.
Core aggregation index and public exports
packages/core/src/aggregation/index.ts, packages/core/src/index.ts
Re-exports routing/waste/behavior-diff builders and new optimization types from core public API.
Optimization intelligence unit tests
packages/core/src/aggregation/optimization-intelligence.test.ts
Tests routing simulation, agent waste detection, and behavior diff computations with edge cases and warning generation.
Data loader optimization integration
packages/cli/src/data-loader.ts
Extends loadTokenleakData and loadCompareTokenleakData with optional includeOptimization flag; buildDefaultOptimization selects baseline/comparison cohorts from provider/model token totals.
CLI command implementations
packages/cli/src/cli.ts
Adds simulate-routing, waste, and behavior-diff standalone commands with help builders, argument parsing, shared helpers (loadOptimizationInput, writeReportOutput), runners, and terminal renderers with severity filtering and JSON format support.
CLI integration tests
packages/cli/src/cli.test.ts
Tests help output, JSON format validation (asserting strategy, summary, takeaways fields), and invocation behavior for the three new commands.
Tabbed dashboard compare-mode integration
packages/cli/src/tabbed-dashboard.ts
Enables optimization payload in compare-mode via includeOptimization option; wires tab views (sim, waste, diff); adds 0 key for tab navigation.
Terminal view renderers
packages/renderers/src/terminal/tab-views/routing-simulator-view.ts, agent-waste-view.ts, agent-behavior-diff-view.ts
Implements terminal renderers formatting routing savings/candidates, waste signals with severity/evidence, and behavior metrics/takeaways with truncation and color support.
Metric tab definitions and labels
packages/renderers/src/terminal/tab-views/tab-bar.ts
Extends MetricTab union and METRIC_TABS with sim/waste/diff; adds TAB_LABELS mappings; updates keyboard hint to 1-9/0.
Live dashboard HTML optimization section
packages/renderers/src/live/template.ts
Adds optional "OPTIMIZATION INTELLIGENCE" HTML block rendering routing savings, waste summary, baseline-vs-compare label, and cost delta.
TUI state management and report caching
packages/tui/src/lib/state.ts, packages/tui/src/lib/data.ts
Extends ViewMode with simulator/waste/behavior; adds per-view scroll offsets and cached report fields; exports ensure* functions for window-scoped report loading with cohort selection.
TUI view panels
packages/tui/src/panels/simulator.ts, waste.ts, behavior.ts
Implements TUI panels for routing simulator (spend/savings with paginated candidates), waste signals (summary with scrollable signals and severity colors), and behavior diff (metric table with formatted values).
TUI view navigation and scrolling
packages/tui/src/index.ts
Integrates simulator/waste/behavior views into main content switch with deferred loading; extends keybindings (X/Y/Z), view cycling, scrollable views set; implements view-specific item/row counts and scroll offset management.
TUI header and help
packages/tui/src/panels/header.ts, help.ts
Extends VIEWS config with Sim/Waste/Diff mapped to X/Y/Z keys; updates help panel descriptions.
TUI optimization panel tests
packages/tui/src/panels/optimization.test.ts
Tests waste/simulator panel rendering for stable labels, width constraints, and scroll-offset-dependent output differences.
MCP tool implementations
packages/mcp/src/tools/get-routing-simulation.ts, get-agent-waste.ts, get-agent-behavior-diff.ts
Implements MCP handlers resolving date ranges, loading provider data, building optimization reports, and returning JSON responses with provider warnings.
MCP tool registration
packages/mcp/src/tools/index.ts
Registers get_routing_simulation, get_agent_waste, and get_agent_behavior_diff tools with Zod schemas and handler wiring.
MCP tool integration tests
packages/mcp/src/server.test.ts
Tests MCP server availability of new tools and validates JSON response structure (strategy, summary, takeaways fields).
Documentation and help text
README.md
Updates command reference with new "Optimization intelligence" example block and expands "Analysis commands" section to document routing simulation, waste detection, and behavior comparison.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

  • ya-nsh/tokenleak#2: Introduces the shared @tokenleak/core data model and base exports that this PR extends with optimization intelligence types and builders.
  • ya-nsh/tokenleak#121: The main PR replaces the prior "waste not supported as standalone command" behavior with actual runWaste CLI implementation and execution path.
  • ya-nsh/tokenleak#46: Enables optimization generation by adding ProviderData.events and UsageEvent plumbing that loadTokenleakData extracts to build the output.optimization payload.

Poem

🐰 Three new insights hop into view—
Route the models, catch waste in the crew,
Compare the cohorts, see what's changed true,
Optimization intelligence shines bright anew! ✨

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/optimization-intelligence

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

since: z.string().optional().describe('Start date in YYYY-MM-DD format'),
until: z.string().optional().describe('End date in YYYY-MM-DD format (default: today)'),
provider: z.string().optional().describe('Filter to a specific provider by name'),
strategy: z.string().optional().describe('Routing strategy name, default conservative'),
Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The MCP routing tool exposes strategy, including manual by description, but it has no rules input and handleGetRoutingSimulation always calls buildRoutingSimulationReport without rules. strategy: "manual" therefore returns an empty/no-op simulation for every request. Please add a routing-rule schema and pass it through, or reject/manual-hide that strategy so callers do not get a misleading successful report.

import { handleGetAgentBehaviorDiff } from './get-agent-behavior-diff.js';

const behaviorSelectorSchema = z.object({
label: z.string(),
Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

label is required here, but the planned MCP shape for get_agent_behavior_diff passes selectors like { dimension: "provider", provider: "claude-code" } without labels. That makes the documented/expected agent call fail schema validation before it reaches the handler. Either make label optional and derive a fallback from the selector, or update all public examples/contracts to require it.

Comment thread packages/tui/src/index.ts Outdated
ensureRoutingSimulationReport(state);
});
}
return createSimulatorPanel(state.cachedRoutingSimulationReport);
Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new optimization views update simulatorScrollOffset / wasteScrollOffset / behaviorScrollOffset, but the offsets are not passed into these panels and the panels themselves hard-slice to the first 8 rows. As a result j/k changes state but cannot reveal candidates/signals beyond the first page, despite the status bar advertising scrolling. Please pass the offset into the panels and slice from it, or remove the scroll handling for these views until row navigation is implemented.

Comment thread packages/cli/src/cli.ts
case '--repo':
cliArgs['repo'] = next();
break;
case '--strategy':
Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

simulate-routing does not accept the --rule flag from the implementation plan (tokenleak simulate-routing --rule premium-short-output:claude-opus->claude-sonnet). I reproduced this locally and it fails at parse time with Unknown optimization flag "--rule", so users cannot exercise manual routing from the CLI even though the core builder supports rules. Please add parsing/validation for rule strings and pass them into buildRoutingSimulationReport, or remove the manual/rule surface from the advertised command until it is wired.

@ya-nsh ya-nsh marked this pull request as ready for review May 17, 2026 10:04
@ya-nsh ya-nsh merged commit 7a52932 into main May 17, 2026
2 checks passed
@ya-nsh ya-nsh deleted the feat/optimization-intelligence branch May 17, 2026 10:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant