Research: Agent Panel Missing t/s (Throughput) Display

Research -- Agent Panel Missing t/s (Throughput) Display

Date: 2026-02-09 Owner: agent Phase: Research

Goal

Map out why the agent panel no longer displays tokens-per-second (t/s) after the unified CSS panel migration (PR #373) and the tinyAgent migration (PR #374). Determine root cause and identify all files in the fix path.

Findings

The Rendering Logic Is Intact

The render_agent_response function correctly computes and formats throughput:

• src/tunacode/ui/renderers/agent_response.py:141-142 -- Guard requires both tokens > 0 and duration_ms > 0:

  if tokens > 0 and duration_ms > 0:
      status_parts.append(f"{tokens * 1000 / duration_ms:.0f} t/s")
  

• The status bar, separator, and layout are all structurally correct.
• CSS classes (agent-panel) are applied properly via PanelMeta.

The Single Call Site Passes Zero Tokens

• src/tunacode/ui/app.py:229-230 -- reads tokens from state:

  session = self.state_manager.session
  tokens = session.usage.last_call_usage.completion_tokens  # Always 0
  

• duration_ms at line 228 IS valid (wall-clock timer set at line 187).
• Since tokens == 0, the guard at agent_response.py:141 never fires.

Root Cause: Usage Write-Side Is Missing

The pipeline from API response to UsageMetrics is completely disconnected:

The Broken Pipeline (Data Flow)

OpenRouter API returns usage on final SSE chunk
  |
  X -- tinyagent openrouter_provider.py:303-326 does NOT extract `usage` from chunks
  |
  X -- AssistantMessage.usage (agent_types.py:128) is always None
  |
  X -- RequestOrchestrator._handle_stream_message_end (main.py:331) ignores usage
  |
  X -- No code writes to session.usage.last_call_usage
  |
  app.py:230 reads completion_tokens => 0
  |
  agent_response.py:141 guard fails => no t/s displayed

Before vs After the Migrations

• Before (pydantic-ai era): pydantic-ai tracked usage natively. The last_call_usage was populated after each call, so t/s displayed correctly.
• After (tinyAgent migration, PR #374): tinyAgent has zero usage tracking. The read-side infrastructure (UsageMetrics, UsageState, the UI consumer) survived the migration. The write-side did not.
• PR #373 (CSS panel migration): Changed render_agent_response to return (content, PanelMeta) instead of a Rich Panel. This did NOT break t/s -- the throughput calculation logic was preserved verbatim. The issue is purely data, not rendering.

Relevant Files & Why They Matter

Secondary Finding: render_agent_streaming Is Dead Code

• Defined at agent_response.py:61-109
• Zero production call sites (only called in test file)
• Was part of the streaming UI before the refactor

Key Patterns / Solutions Found

• Two-point fix: The fix needs changes at two points:

  1. tinyagent provider level -- Extract usage from the final SSE chunk in the OpenRouter provider (or in a local wrapper/middleware)
  2. RequestOrchestrator level -- Read usage from the message_end or agent_end event and write it to session.usage.last_call_usage

• Alternative single-point fix: If modifying tinyagent's provider is undesirable, the _handle_stream_agent_end handler at main.py:416 could inspect the persisted messages for a usage field, or the agent object itself could expose usage after completion.

• Duration is already working: The duration_ms path is functional. Only tokens (completion_tokens) is missing.

Knowledge Gaps

• Whether tinyagent's Agent object exposes usage data post-completion (e.g., agent.last_usage or similar)
• Whether OpenRouter's SSE stream reliably includes usage on the final chunk for all models
• Whether tinyagent has plans to add native usage tracking (upstream fix vs. local patch)
• Whether render_agent_streaming should be deleted or reconnected for live streaming panels

References

• src/tunacode/ui/renderers/agent_response.py -- Throughput rendering logic
• src/tunacode/ui/app.py -- Call site and timer logic
• src/tunacode/core/agents/main.py -- Stream event handlers
• src/tunacode/types/canonical.py -- UsageMetrics definition
• src/tunacode/core/types/state_structures.py -- UsageState definition
• memory-bank/research/2026-01-27_16-11-11_streaming_and_panels.md -- Prior streaming/panel research
• memory-bank/research/2026-01-27_17-45-00_chatcontainer_refactor.md -- Chat container refactor research