paseo/plan.md

Plan

Context

Voice-controlled terminal assistant using OpenAI's Realtime API. Monorepo with Express backend and Expo cross-platform app.

Focus: Agent model info tracking. Two distinct concepts:

1. Configured model: What the user requested (default or specific model)
2. Runtime model: What the agent is actually using (from the agent process itself)

Hard requirement: We must get the actual runtime model, not just echo back the requested config.

Environment

• Expo app: Running in tmux session moboudra:mobile - check logs with tmux capture-pane -t moboudra:mobile -p
• Server: Running in tmux session moboudra:server - check logs with tmux capture-pane -t moboudra:server -p
• Web testing: Use Playwright MCP at http://localhost:8081

Guiding Principles

• Keep changes minimal and focused
• Run typecheck after every change
• Don't break existing functionality
• Test in the running app when possible

Testing Requirements (CRITICAL)

• Nothing is done until tested. Every implementation task must be followed by a testing task using Playwright MCP.
• Test tasks verify specific behaviors. Not "test the feature" but "verify X does Y when Z".
• Test failures spawn fix tasks. If a test finds issues, add fix tasks immediately after.
• Fix tasks get their own test tasks. After a fix task, add a re-test task to verify the fix.
• Loop until it works. The cycle is: implement → test → fix → re-test → ... until verified working.
• Testers own the plan. Test tasks can and should add new tasks (fixes, re-tests) to keep the loop going.
• Never claim done without verification. If you can't test it with Playwright MCP, you can't mark it complete.

Tasks

• Plan: Audit current model info implementation and expand this plan.

  • Find where model config is set when creating agents.
  • Find where runtime model info is fetched/displayed.
  • Document how each provider (Claude SDK, Codex SDK) exposes actual model info.
  • Check if we're currently showing requested model vs actual runtime model.
  • Add implementation tasks based on findings.
  • Add test tasks as needed.
  • Add another Plan task at an appropriate position to re-audit after some progress.
  • Done (2025-12-21 12:45): Completed full audit. See findings below.

Audit Findings: Model Info Implementation

Current Architecture (Working Well):

• Model config is set via AgentSessionConfig.model in agent-sdk-types.ts:148-164
• Runtime info uses AgentRuntimeInfo type with model field in agent-sdk-types.ts:126-132
• UI correctly uses extractAgentModel() which reads runtimeInfo.model (not config)
• Displayed in agent screen header at line 555 of [agentId].tsx

Claude SDK:

• claude-agent.ts:423-435 - getRuntimeInfo() returns this.lastOptionsModel
• Model comes from Claude SDK options passed during agent creation
• Currently echoes back the configured model (not truly "runtime detected")

Codex SDK:

• codex-agent.ts:407-426 - getRuntimeInfo() reads actual runtime model
• codex-agent.ts:1229-1261 - Parses rollout file for turn_context.payload.model
• This IS the actual runtime model (correctly implemented)
• Falls back to config model if rollout not available yet

Gap Identified:

• Claude agents: Model info is the configured model, not detected from Claude SDK
• Codex agents: Model info IS detected from runtime (via rollout file) ✓
• Claude SDK may expose actual model in response metadata - needs investigation

Data Flow:

1. Config: config.model → agent creation
2. Runtime: agent.session.getRuntimeInfo() called after stream/turn completion
3. Storage: runtimeInfo persisted in agent registry
4. Client: Receives via WebSocket, displayed via extractAgentModel()

---

• Investigate: Check if Claude SDK exposes actual model in response/stream metadata.

  • Look at @anthropic-ai/claude-agent-sdk types for model info in responses
  • Check if query() returns model information
  • Document findings for implementation task
  • Done (2025-12-21 13:15): YES, the Claude SDK exposes actual model info in TWO places:
    1. SDKSystemMessage (subtype: "init") has model: string field (sdk.d.ts:334)
    2. SDKResultMessage has modelUsage: { [modelName: string]: ModelUsage } (sdk.d.ts:299-300)
    • Current implementation ignores both - only uses config.model (claude-agent.ts:712)
    • Fix: Update handleSystemMessage() to capture message.model as lastOptionsModel
    • Alternatively: Extract model name from modelUsage keys in SDKResultMessage

• Implement: Capture actual model from Claude SDK init message.

  • In handleSystemMessage(), set this.lastOptionsModel = message.model
  • This gives us the actual model the SDK selected (not just our config)
  • Simpler than parsing modelUsage, same result
  • Done (2025-12-21 13:25): Updated handleSystemMessage() in claude-agent.ts:868-882 to capture message.model from the SDK init message and invalidate cached runtime info. Typecheck passes.

• Test: Verify current Codex runtime model detection works.

  • Create a Codex agent with default model
  • Wait for first turn to complete
  • Verify the model displayed matches actual runtime model (e.g., gpt-4.1)
  • Check that it's not just echoing configured model

• Test: Verify Claude agent model display behavior.

  • Create a Claude agent with default model
  • Wait for first turn to complete
  • Check what model is displayed
  • Document whether it's configured or runtime model

• Plan: Re-audit after investigation and initial tests complete.

  • Review test results
  • Determine if Claude SDK exposes runtime model info
  • Add implementation tasks if improvements needed
  • Add fix tasks if tests reveal issues

• Plan: Design and implement agent parent/child hierarchy.

  • Add parentId field to agents.
  • Agents created via MCP should auto-set parentId to the calling agent.
  • Homepage should only show top-level agents (no parentId).
  • Agent screen three-dot menu should show sub-agents of that agent.
  • Sub-agents should be navigable from the menu.
  • Ensure back button works properly when navigating agent hierarchy.
  • Add implementation tasks based on findings.
  • Add another Plan task at an appropriate position to re-audit after some progress.

• agent=codex Review: Code quality and types review.

  • Review all changed files for code quality issues.
  • Check TypeScript types are correct and complete.
  • Look for any type errors or unsafe casts.
  • Check for proper error handling.
  • Add fix tasks for any issues found.
  • Add another agent=codex **Review** task after fix tasks to verify fixes.