slopus--happy/docs/plans/session-protocol-impl.md

Session Protocol Implementation

Overview

Implement docs/session-protocol.md as the new message format for Codex sessions in the CLI, and add client-side support in happy-app to parse, normalize, and render these messages alongside existing legacy formats (output, codex, acp).

Key decisions from planning:

• CLI (Codex only): Emit session-protocol events instead of current codex/acp format to the server
• App: Support both legacy and session-protocol formats (detect and handle both)
• Conversion happens on CLI level; client normalizes the flat event stream back into grouped structures (subagent nesting, turn grouping)

Context

Message flow today (Codex → App)

1. runCodex.ts receives MCP messages from Codex CLI
2. Calls session.sendCodexMessage() which wraps in { role: 'agent', content: { type: 'codex', data: body } }
3. Encrypted and sent via WebSocket
4. App decrypts → normalizeRawMessage() in typesRaw.ts → NormalizedMessage
5. reducer.ts processes NormalizedMessage[] → Message[] for UI

What changes

• CLI: Instead of sendCodexMessage(), use a new sendSessionProtocolMessage() that emits the 7 event types from session-protocol.md
• App: typesRaw.ts gets a new discriminated union branch type: 'session' in rawAgentRecordSchema, with normalizeRawMessage() converting session-protocol events to NormalizedMessage
• Reducer: Minimal changes — already handles NormalizedMessage correctly; just needs turn tracking awareness

Files involved

CLI (happy-cli):

• src/api/apiSession.ts — new sendSessionProtocolMessage() method
• src/codex/runCodex.ts — convert from sendCodexMessage() to session-protocol events
• src/codex/utils/reasoningProcessor.ts — emit thinking events

App (happy-app):

• sources/sync/typesRaw.ts — new Zod schema for session-protocol envelope + events, new normalizer branch
• sources/sync/reducer/reducer.ts — turn tracking (optional, for grouping)
• sources/sync/reducer/messageToEvent.ts — handle session-protocol turn-start/turn-end

Development Approach

• Testing approach: Regular (code first, then tests)
• Complete each task fully before moving to the next
• Make small, focused changes
• CRITICAL: every task MUST include new/updated tests for code changes in that task
• CRITICAL: all tests must pass before starting next task
• CRITICAL: update this plan file when scope changes during implementation
• Run tests after each change
• Maintain backward compatibility (legacy formats keep working)

Testing Strategy

• Unit tests: required for every task
• Tests live colocated with source files (.test.ts suffix)
• Framework: Vitest

Progress Tracking

• Mark completed items with [x] immediately when done
• Add newly discovered tasks with ➕ prefix
• Document issues/blockers with ⚠️ prefix
• ⚠️ packages/happy-cli and packages/happy-app do not define a lint script; verification used full test suites plus yarn typecheck in both packages.
• ⚠️ In app normalization for content.type === 'session', uuid uses envelope id (not turn) to keep message identity unique while invoke handles sidechain linkage.
• ⚠️ ReasoningProcessor and DiffProcessor still emit legacy internal shapes; Codex now maps those outputs to session-protocol envelopes in sessionProtocolMapper.ts before sending.

Implementation Steps

Task 1: Define session-protocol types and Zod schemas (shared)

Create the TypeScript types and Zod schemas for all 7 session-protocol event types plus the envelope. These will be used by both CLI (for emitting) and app (for parsing).

• Create packages/happy-cli/src/sessionProtocol/types.ts with:
  • Envelope type: { id, time, role, turn?, invoke?, ev }
  • Event union type discriminated by ev.t: text, tool-call-start, tool-call-end, file, photo, turn-start, turn-end
  • Each event type as a separate interface
  • Zod schemas for validation
• Export a helper createEnvelope(role, ev, opts?) that generates cuid2 id and timestamp
• Write tests for Zod schema validation (valid events pass, invalid rejected)
• Write tests for createEnvelope helper
• Run tests — must pass before next task

Task 2: Add sendSessionProtocolMessage() to apiSession.ts

Add a new send method that wraps session-protocol envelopes in the wire format.

• Add sendSessionProtocolMessage(envelope) to ApiSessionClient in packages/happy-cli/src/api/apiSession.ts
  • Wraps as { role: 'session', content: envelope }
  • Encrypts and sends via socket (same pattern as sendCodexMessage)
• Write tests for the new method (verify envelope wrapping, encryption call)
• Run tests — must pass before next task

Task 3: Convert Codex message handler to emit session-protocol events

Replace sendCodexMessage() calls in runCodex.ts with session-protocol event emission.

• Add turn tracking state to runCodex.ts:
  • currentTurnId: string | null — set on task_started, cleared on task_complete/turn_aborted
  • Emit turn-start event on task_started
  • Emit turn-end event on task_complete / turn_aborted
• Convert agent_message → text event with turn field
• Convert agent_reasoning / agent_reasoning_delta → text event with thinking: true
• Convert exec_command_begin / exec_approval_request → tool-call-start event
  • call: use call_id from MCP message
  • name: CodexBash
  • title: short summary from command
  • description: full command description
  • args: input params
• Convert exec_command_end → tool-call-end event
• Convert patch_apply_begin → tool-call-start with name CodexPatch
• Convert patch_apply_end → tool-call-end
• Convert token_count → skip (no session-protocol equivalent, or emit as-is using sendCodexMessage for backwards compat)
• Keep task_started/task_complete/turn_aborted sending via session events (sendSessionEvent) — these are lifecycle, not messages
• Write tests for the conversion logic (mock session, verify correct event types emitted)
• Run tests — must pass before next task

Task 4: Update ReasoningProcessor to emit session-protocol events

The ReasoningProcessor currently calls session.sendCodexMessage() directly via callback. Update it.

• Update the callback type in ReasoningProcessor constructor to accept session-protocol envelopes
• Convert reasoning tool-call emissions to tool-call-start / tool-call-end session-protocol events
• Convert reasoning message emissions to text events with thinking: true
• Write tests for the updated processor output format
• Run tests — must pass before next task

Task 5: Add session-protocol parsing to typesRaw.ts (app)

Add a new type: 'session' branch to the raw record schema and update normalizeRawMessage().

• Add Zod schema for the session-protocol envelope in typesRaw.ts:
  • z.object({ type: z.literal('session'), data: sessionEnvelopeSchema })
  • The envelope schema validates id, time, role, turn?, invoke?, ev with discriminated union on ev.t
• Add 'session' to rawAgentRecordSchema discriminated union
• Add normalization logic in normalizeRawMessage() for raw.content.type === 'session':
  • ev.t === 'text' → NormalizedMessage with role: 'agent', content: [{ type: 'text', text, uuid, parentUUID }] (or type: 'thinking' if ev.thinking)
  • ev.t === 'tool-call-start' → NormalizedMessage with content: [{ type: 'tool-call', id: ev.call, name: ev.name, input: ev.args, description: ev.description }]
  • ev.t === 'tool-call-end' → NormalizedMessage with content: [{ type: 'tool-result', tool_use_id: ev.call, content: null, is_error: false }]
  • ev.t === 'turn-start' → NormalizedMessage with role: 'event', content: { type: 'message', message: 'Turn started' } (or skip)
  • ev.t === 'turn-end' → NormalizedMessage with role: 'event', content: { type: 'ready' } (triggers ready handling)
  • ev.t === 'file' → map to tool-call for display
  • ev.t === 'file' with image metadata → map to tool-call for display (or new message type later)
• Handle invoke field: set parentUUID to the invoke value so sidechains work through existing tracer
• Handle turn field: set uuid to turn value so grouping works
• Write tests for each event type normalization (valid input → correct NormalizedMessage)
• Write tests for invalid/malformed session events (graceful null return)
• Run tests — must pass before next task

Task 6: Update reducer for turn-start/turn-end awareness

The reducer already handles NormalizedMessage well. Minor updates for the new event semantics.

• Ensure turn-end events with { type: 'ready' } trigger hasReadyEvent = true (already works via existing code path)
• Ensure turn-start events don't create visible messages (filter them out or make them no-op)
• Ensure subagent messages (with invoke → parentUUID) flow through existing sidechain/tracer logic
• Write tests verifying turn lifecycle events flow correctly through reducer
• Write tests verifying subagent messages nest correctly under parent tool calls
• Run tests — must pass before next task

Task 7: Verify acceptance criteria

• Verify Codex CLI emits session-protocol events for all message types
• Verify app can parse and display session-protocol messages
• Verify app still handles legacy formats (output, codex, acp) correctly
• Verify subagent nesting works via invoke field
• Verify turn lifecycle (turn-start/turn-end) works correctly
• Run full test suite — yarn test in happy-cli, happy-app
• Run linter — all issues must be fixed

Task 8: [Final] Update documentation

• Update docs/session-protocol.md if any deviations from spec were necessary
• Add inline code comments for the session-protocol conversion path

Technical Details

Envelope structure (wire format)

// What gets encrypted and sent over WebSocket
{
  role: 'agent',
  content: {
    type: 'session',  // NEW discriminator
    data: {           // session-protocol envelope
      id: 'cuid2...',
      time: 1739347200000,
      role: 'agent',
      turn: 'turn-id',
      invoke: 'parent-call-id',  // only for subagents
      ev: { t: 'text', text: 'Hello' }
    }
  },
  meta: { sentFrom: 'cli' }
}

Event → NormalizedMessage mapping

Session Protocol Event	NormalizedMessage role	NormalizedMessage content type
text	agent	text (or thinking if ev.thinking)
tool-call-start	agent	tool-call
tool-call-end	agent	tool-result
turn-start	event	{ type: 'message', message: 'Turn started' }
turn-end	event	{ type: 'ready' }
file	agent	tool-call (synthetic, for UI display)
photo	agent	tool-call (synthetic, for UI display)

Turn tracking in CLI

task_started → emit turn-start, set currentTurnId
  agent_message → emit text with turn: currentTurnId
  exec_command_begin → emit tool-call-start with turn: currentTurnId
  exec_command_end → emit tool-call-end with turn: currentTurnId
task_complete → emit turn-end, clear currentTurnId

Post-Completion

Manual verification:

• Test with real Codex session to verify messages display correctly in app
• Verify existing Claude Code sessions still display correctly (legacy format)
• Test abort/resume flow with session-protocol format
• Test permission flow with session-protocol format