Feature: Bidirectional Agent Chat — Live Interactive Sessions

[frankbria]

Overview

CodeFRAME currently supports one-way execution monitoring via SSE: the user watches the agent run, but cannot steer it mid-flight except through the blocker Q&A (which pauses the whole run). This issue tracks the full work needed to close the bidirectional agent chat gap — persistent, interactive sessions where users can send messages to a running agent and receive streaming token-by-token responses.

Problem

• The existing POST /api/projects/{id}/chat endpoint returns complete responses and is wired to the Lead Agent only, not to a running coding agent
• The existing /ws WebSocket handles project status updates (subscribe/broadcast), not interactive message exchange
• The web-ui has no sessions page, no chat panel component, no XTerm terminal, and no split-pane layout
• There is no concept of a persistent interactive session that can be paused and resumed

What "Done" Looks Like

• User can open a /sessions page and start a new interactive agent session against any workspace
• Session opens a split-pane layout: agent chat on the left, terminal on the right
• Agent chat streams tokens in real-time (not wait-for-complete-response)
• Tool calls are displayed inline with collapsible input/output JSON
• Thinking blocks are rendered with distinct styling
• User can type a follow-up message and send it while the agent is idle
• User can interrupt the agent mid-thinking
• Sessions are persisted in the DB and listed on /sessions; past sessions can be resumed
• Cost and token counts update in real-time

Sub-issues (Atomic, Single-session Work)

Backend

• Backend: DB schema + CRUD API for interactive agent sessions #501 — DB schema + CRUD API for interactive agent sessions
• Backend: WebSocket endpoint for streaming agent chat (/ws/sessions/{id}/chat) #502 — WebSocket endpoint for streaming agent chat (/ws/sessions/{id}/chat)
• Backend: Streaming chat adapter for Anthropic SDK (token-by-token relay) #503 — Streaming chat adapter for Anthropic SDK (token-by-token relay)

Frontend

• Frontend: useAgentChat hook — WebSocket connection and message streaming #504 — useAgentChat hook (WebSocket connection, message accumulation, streaming)
• Frontend: AgentChatPanel component — messages, tool calls, thinking blocks, input bar #505 — AgentChatPanel component (messages, tool calls, thinking blocks, input bar)
• Frontend: AgentTerminal component — XTerm.js interactive terminal for session workspace #506 — AgentTerminal component (XTerm.js interactive terminal)
• Frontend: SplitPane layout component — draggable, collapsible, persistent #507 — SplitPane layout component (draggable, collapsible, localStorage persistence)
• Frontend: /sessions list page + sidebar navigation entry #508 — /sessions list page + sidebar nav entry
• Frontend: /sessions/[id] detail page — wires SplitPane, AgentChatPanel, and AgentTerminal #509 — /sessions/[id] detail page (wires everything together)

Dependency Graph

#501 (DB/API)
  └─→ #502 (WS endpoint)
        └─→ #503 (streaming adapter)   ← backend complete

#504 (hook) ← requires #502 running
  └─→ #505 (chat panel)
#506 (terminal)
#507 (split pane)
#508 (list page) ← requires #501 running
  └─→ #509 (detail page) ← requires #504, #505, #506, #507

Existing Infrastructure

• WebSocket auth pattern: codeframe/ui/routers/websocket.py
• Lead Agent chat (non-streaming): codeframe/ui/routers/chat.py
• Session state endpoint: codeframe/ui/routers/session.py
• SSE streaming pattern: codeframe/core/streaming.py + useEventSource.ts
• DiscoveryPanel (closest existing chat UI): web-ui/src/components/prd/DiscoveryPanel.tsx

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

The codebase is a FastAPI + Next.js stack with two UI layers: a legacy legacy/web-ui (v1) and a new web-ui (v2). The backend uses both project_id-based routing (legacy) and workspace_path-based routing (v2). WebSocket auth uses JWT via query param. The existing /ws endpoint handles project status updates (subscribe/broadcast), not interactive message exchange. The existing POST /api/projects/{id}/chat endpoint is wired to the Lead Agent only and returns complete responses (not streaming). The DiscoveryPanel component in web-ui/src/components/prd/DiscoveryPanel.tsx provides a reference for session-based chat UI patterns. The ticket defines 9 atomic sub-issues with a dependency graph: backend (#501–#503) must complete before frontend (#504–#509).

Approach

The work is split into two parallel tracks — backend and frontend — following the 9 atomic sub-issues in the ticket. The backend (#501–#503) adds a new InteractiveSession entity with CRUD API, a dedicated WebSocket endpoint at /ws/sessions/{id}/chat for streaming agent chat, and a streaming Anthropic adapter that relays tokens in real-time. The frontend (#504–#509) adds the useAgentChat hook for WebSocket connection and message accumulation, three new components (AgentChatPanel, AgentTerminal, SplitPane), and two new pages (/sessions, /sessions/[id]). The implementation reuses existing patterns: WebSocket auth from codeframe/ui/routers/websocket.py, chat API structure from codeframe/ui/routers/chat.py, SSE streaming from streaming_v2.py, and UI patterns from DiscoveryPanel.tsx.

---

Implementation Plan

Phase 1 — Backend: DB Schema + CRUD API for Interactive Sessions (#501)

New file: file:codeframe/ui/routers/sessions_v2.py

1. Define the InteractiveSession data model in file:codeframe/ui/routers/sessions_v2.py. Fields:

   • id (UUID string, primary key)
   • workspace_path (string, from query param or request body)
   • title (string, optional)
   • status (idle | running | interrupted | completed)
   • created_at, updated_at (ISO timestamps)
   • message_history (JSON list of {role, content, tool_calls?, thinking?, timestamp})
   • token_count, cost_usd (floats, updated incrementally)

2. Create a SessionStore class in file:codeframe/core/session_store.py that persists sessions as JSON files under <workspace_state_dir>/sessions/. Implement methods: create(), get(), list(), update(), delete().

3. Create REST endpoints in file:codeframe/ui/routers/sessions_v2.py:

   • POST /api/v2/sessions — create a new session (body: workspace_path, optional title)
   • GET /api/v2/sessions — list sessions for a workspace (query: workspace_path)
   • GET /api/v2/sessions/{session_id} — get session detail including full message history
   • DELETE /api/v2/sessions/{session_id} — delete a session

4. Add Pydantic response models in file:codeframe/ui/response_models.py: InteractiveSessionResponse, SessionListResponse.

5. Register the router in file:codeframe/ui/server.py alongside the other v2 routers.

Phase 2 — Backend: WebSocket Endpoint for Streaming Agent Chat (#502)

New file: file:codeframe/ui/routers/session_chat_ws.py

The new WebSocket endpoint lives at /ws/sessions/{session_id}/chat and is separate from the existing /ws (project status) endpoint.

1. Create the router with @router.websocket("/ws/sessions/{session_id}/chat"). Reuse JWT-from-query-param auth from file:codeframe/ui/routers/websocket.py (extract token, decode with pyjwt, verify user).

2. Message protocol (JSON over WebSocket):

   Direction	Type	Payload
   Client → Server	user_message	{content: string}
   Client → Server	interrupt	{}
   Client → Server	ping	{}
   Server → Client	token	{delta: string}
   Server → Client	tool_call	{id, name, input}
   Server → Client	tool_result	{tool_call_id, output}
   Server → Client	thinking	{delta: string}
   Server → Client	message_complete	{role, content, token_count, cost_usd}
   Server → Client	error	{message: string}
   Server → Client	pong	{}

3. Session state management: On connect, load the session from SessionStore. Maintain an asyncio.Event for interrupt signaling. Keep a reference to the running streaming task so it can be cancelled on interrupt.

4. Register the router in file:codeframe/ui/server.py.

Phase 3 — Backend: Streaming Chat Adapter for Anthropic SDK (#503)

New file: file:codeframe/core/agent_chat_stream.py

1. Create AgentChatStream class that wraps the anthropic SDK's streaming API (anthropic.AsyncAnthropic().messages.stream()). The anthropic>=0.18.0 SDK already supports async streaming.

2. stream_response async generator method: accepts the session's message_history list and an asyncio.Event interrupt_event. Iterates over the SDK's streaming events and yields typed dicts matching the WebSocket protocol:

   • RawContentBlockDeltaEvent with TextDelta → yield token
   • RawContentBlockDeltaEvent with InputJsonDelta → yield tool_call input accumulation
   • RawContentBlockStartEvent with ToolUseBlock → yield tool_call start
   • Thinking blocks (extended thinking) → yield thinking
   • After stream completes → yield message_complete with usage stats

3. Interrupt handling: Check interrupt_event.is_set() at each yield point; if set, break the loop and close the stream context manager.

4. Tool execution: After a tool_call is yielded, the WebSocket handler executes the tool (via existing codeframe/core/ tool infrastructure) and sends tool_result back to the client, then appends both to message_history before continuing.

5. Persist after each complete turn: call SessionStore.update_session() to save the updated message_history, token_count, and cost_usd.

Phase 4 — Backend: Interrupt and Steering (part of #502)

This is handled within the WebSocket handler in file:codeframe/ui/routers/session_chat_ws.py:

1. Concurrent receive loop: Use asyncio.create_task to run a background task that reads incoming WebSocket messages while the streaming task runs. When an interrupt message arrives, set the interrupt_event and cancel the streaming task.

2. Mid-session user messages: When the agent is idle (no streaming task running), a user_message triggers a new streaming turn. When the agent is running, a user_message is queued and processed after the current turn completes (or after interrupt).

3. Status broadcast: After each state change (idle → running → idle), update the session's status field in SessionStore.

---

Phase 5 — Frontend: Install Required Packages

Before writing any frontend code, add the missing dependencies to file:web-ui/package.json:

• xterm and @xterm/addon-fit (for the terminal component)
• @xterm/addon-web-links (optional, for clickable links in terminal)

No split-pane library is needed — implement it with CSS flex + a draggable divider (avoids adding a dependency).

---

Phase 6 — Frontend: useAgentChat Hook (#504)

New file: file:web-ui/src/hooks/useAgentChat.ts

Model this after the existing WebSocketClient in file:legacy/web-ui/src/lib/websocket.ts but scoped to a single session.

1. State managed by the hook:

   • messages: AgentMessage[] — accumulated message list
   • streamingContent: string — current in-progress token stream
   • status: 'idle' | 'connecting' | 'running' | 'error'
   • tokenCount: number, costUsd: number

2. AgentMessage type (add to file:web-ui/src/types/index.ts):

   { id, role, content, toolCalls?, thinking?, tokenCount?, costUsd?, timestamp }
   

3. WebSocket lifecycle: Connect to ws://localhost:8000/ws/sessions/{sessionId}/chat?token=... on mount (read token from localStorage as in the legacy client). Reconnect with exponential backoff on disconnect.

4. Incoming message handling: Switch on type field — accumulate token deltas into streamingContent, flush to messages on message_complete, append tool_call/tool_result/thinking as structured entries.

5. Exposed actions: sendMessage(content: string), interrupt(), both send JSON over the WebSocket.

6. Cleanup: Close WebSocket on unmount.

---

Phase 7 — Frontend: AgentChatPanel Component (#505)

New file: file:web-ui/src/components/sessions/AgentChatPanel.tsx

1. Props: { messages: AgentMessage[], streamingContent: string, status, tokenCount, costUsd, onSendMessage, onInterrupt }

2. Message rendering (reference: file:web-ui/src/components/prd/DiscoveryPanel.tsx and DiscoveryTranscript.tsx):

   • role === 'user' → right-aligned bubble (reuse Tailwind classes from existing components)
   • role === 'assistant' with plain text → left-aligned bubble, render with react-markdown (already in web-ui/package.json)
   • tool_call entries → collapsible card showing tool name + input JSON (use <details> element)
   • tool_result entries → collapsible card showing output JSON
   • thinking entries → distinct styling (e.g., italic, muted color, collapsible)
   • Streaming in-progress → show streamingContent with a blinking cursor

3. Input bar (reference: DiscoveryInput.tsx): <textarea> + Send button. Disable when status === 'running'. Show an Interrupt button when status === 'running'.

4. Cost/token display: Small footer showing tokenCount tokens · $costUsd.

5. Auto-scroll: useEffect to scroll to bottom on new messages.

---

Phase 8 — Frontend: AgentTerminal Component (#506)

New file: file:web-ui/src/components/sessions/AgentTerminal.tsx

1. Use xterm.js: Import Terminal from xterm and FitAddon from @xterm/addon-fit. Initialize in a useEffect with a useRef for the container div.

2. Connect to workspace: The terminal connects to the workspace's shell via a separate WebSocket or PTY endpoint. Since no PTY backend exists yet, implement a read-only log view initially: subscribe to the existing SSE stream (/api/v2/tasks/{task_id}/stream) and write OutputEvent lines to the terminal. This avoids needing a new PTY backend for the first iteration.

3. Fit on resize: Use FitAddon and a ResizeObserver on the container div to call fitAddon.fit() when the pane is resized.

4. Cleanup: Dispose the terminal instance on unmount.

---

Phase 9 — Frontend: SplitPane Layout Component (#507)

New file: file:web-ui/src/components/sessions/SplitPane.tsx

1. Props: { left: ReactNode, right: ReactNode, defaultSplit?: number } where defaultSplit is a percentage (default 50).

2. Implementation: Two flex children with a draggable divider <div>. On mousedown on the divider, attach mousemove and mouseup listeners to document. Calculate new split percentage from mouse position relative to container width.

3. Persistence: Save the split percentage to localStorage under a key like codeframe:session-split and restore on mount.

4. Collapse: Double-click the divider to collapse/restore the right pane (toggle between saved split and 100%).

---

Phase 10 — Frontend: /sessions List Page (#508)

New file: file:web-ui/src/app/sessions/page.tsx

1. Data fetching: Use swr to call GET /api/v2/sessions?workspace_path=... (read workspacePath from localStorage via getSelectedWorkspacePath()).

2. Session list: Render a table/card list of sessions showing title, status badge, created date, token count, cost. Each row links to /sessions/[id].

3. New session button: POST /api/v2/sessions with the current workspace_path, then router.push('/sessions/{newId}').

4. Delete: Confirm dialog (use existing @radix-ui/react-alert-dialog) then DELETE /api/v2/sessions/{id}.

5. Add sessionsApi to file:web-ui/src/lib/api.ts with create, list, get, delete methods.

6. Add types InteractiveSession, SessionListResponse to file:web-ui/src/types/index.ts.

---

Phase 11 — Frontend: /sessions/[id] Detail Page (#509)

New file: file:web-ui/src/app/sessions/[id]/page.tsx

1. Data fetching: Fetch session detail via sessionsApi.get(sessionId) to load initial message_history and metadata.

2. Wire hooks and components:

   • Call useAgentChat(sessionId) to get live state and actions
   • Seed messages from the fetched session's message_history on first load
   • Render <SplitPane left={<AgentChatPanel .../>} right={<AgentTerminal .../>} />

3. Page header: Session title (editable inline), status badge, back link to /sessions.

---

Phase 12 — Frontend: Sidebar Navigation Entry

Modify: file:web-ui/src/components/layout/AppSidebar.tsx

Add a new entry to the NAV_ITEMS array:

{ href: '/sessions', label: 'Sessions', icon: <suitable HugeIcons icon>, enabled: true }

Choose an appropriate icon from @hugeicons/react (e.g., MessageMultiple01Icon or BubbleChatIcon).

---

Data Flow Diagram

sequenceDiagram
    participant UI as AgentChatPanel
    participant Hook as useAgentChat
    participant WS as /ws/sessions/{id}/chat
    participant Adapter as AgentChatStream
    participant SDK as Anthropic SDK
    participant Store as SessionStore

    UI->>Hook: sendMessage("fix the bug")
    Hook->>WS: {type:"user_message", content:"..."}
    WS->>Store: append user turn to history
    WS->>Adapter: stream_response(history, interrupt_event)
    Adapter->>SDK: messages.stream(...)
    loop token streaming
        SDK-->>Adapter: TextDelta / ToolUse / Thinking
        Adapter-->>WS: typed event dict
        WS-->>Hook: {type:"token", delta:"..."}
        Hook-->>UI: update streamingContent
    end
    SDK-->>Adapter: message_stop
    Adapter-->>WS: {type:"message_complete", ...}
    WS->>Store: persist updated history + usage
    WS-->>Hook: {type:"message_complete"}
    Hook-->>UI: flush to messages[], reset streamingContent

    UI->>Hook: interrupt()
    Hook->>WS: {type:"interrupt"}
    WS->>Adapter: interrupt_event.set()
    Adapter-->>WS: StopIteration
    WS-->>Hook: {type:"message_complete", partial:true}

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase is a **FastAPI + Next.js** stack with two UI layers: a legacy `legacy/web-ui` (v1) and a new `web-ui` (v2). The backend uses both `project_id`-based routing (legacy) and `workspace_path`-based routing (v2). WebSocket auth uses JWT via query param. The existing `/ws` endpoint handles project status updates (subscribe/broadcast), not interactive message exchange. The existing `POST /api/projects/{id}/chat` endpoint is wired to the Lead Agent only and returns complete responses (not streaming). The `DiscoveryPanel` component in `web-ui/src/components/prd/DiscoveryPanel.tsx` provides a reference for session-based chat UI patterns. The ticket defines 9 atomic sub-issues with a dependency graph: backend (#501–#503) must complete before frontend (#504–#509).

## Approach

The work is split into two parallel tracks — backend and frontend — following the 9 atomic sub-issues in the ticket. The backend (#501–#503) adds a new `InteractiveSession` entity with CRUD API, a dedicated WebSocket endpoint at `/ws/sessions/{id}/chat` for streaming agent chat, and a streaming Anthropic adapter that relays tokens in real-time. The frontend (#504–#509) adds the `useAgentChat` hook for WebSocket connection and message accumulation, three new components (`AgentChatPanel`, `AgentTerminal`, `SplitPane`), and two new pages (`/sessions`, `/sessions/[id]`). The implementation reuses existing patterns: WebSocket auth from `codeframe/ui/routers/websocket.py`, chat API structure from `codeframe/ui/routers/chat.py`, SSE streaming from `streaming_v2.py`, and UI patterns from `DiscoveryPanel.tsx`.

---

## Implementation Plan

### Phase 1 — Backend: DB Schema + CRUD API for Interactive Sessions (#501)

**New file:** `file:codeframe/ui/routers/sessions_v2.py`

1. **Define the `InteractiveSession` data model** in `file:codeframe/ui/routers/sessions_v2.py`. Fields:
   - `id` (UUID string, primary key)
   - `workspace_path` (string, from query param or request body)
   - `title` (string, optional)
   - `status` (`idle` | `running` | `interrupted` | `completed`)
   - `created_at`, `updated_at` (ISO timestamps)
   - `message_history` (JSON list of `{role, content, tool_calls?, thinking?, timestamp}`)
   - `token_count`, `cost_usd` (floats, updated incrementally)

2. **Create a `SessionStore` class** in `file:codeframe/core/session_store.py` that persists sessions as JSON files under `<workspace_state_dir>/sessions/`. Implement methods: `create()`, `get()`, `list()`, `update()`, `delete()`.

3. **Create REST endpoints** in `file:codeframe/ui/routers/sessions_v2.py`:
   - `POST /api/v2/sessions` — create a new session (body: `workspace_path`, optional `title`)
   - `GET /api/v2/sessions` — list sessions for a workspace (query: `workspace_path`)
   - `GET /api/v2/sessions/{session_id}` — get session detail including full message history
   - `DELETE /api/v2/sessions/{session_id}` — delete a session

4. **Add Pydantic response models** in `file:codeframe/ui/response_models.py`: `InteractiveSessionResponse`, `SessionListResponse`.

5. **Register the router** in `file:codeframe/ui/server.py` alongside the other v2 routers.

### Phase 2 — Backend: WebSocket Endpoint for Streaming Agent Chat (#502)

**New file:** `file:codeframe/ui/routers/session_chat_ws.py`

The new WebSocket endpoint lives at `/ws/sessions/{session_id}/chat` and is separate from the existing `/ws` (project status) endpoint.

1. **Create the router** with `@router.websocket("/ws/sessions/{session_id}/chat")`. Reuse JWT-from-query-param auth from `file:codeframe/ui/routers/websocket.py` (extract `token`, decode with `pyjwt`, verify user).

2. **Message protocol** (JSON over WebSocket):

   | Direction | Type | Payload |
   |---|---|---|
   | Client → Server | `user_message` | `{content: string}` |
   | Client → Server | `interrupt` | `{}` |
   | Client → Server | `ping` | `{}` |
   | Server → Client | `token` | `{delta: string}` |
   | Server → Client | `tool_call` | `{id, name, input}` |
   | Server → Client | `tool_result` | `{tool_call_id, output}` |
   | Server → Client | `thinking` | `{delta: string}` |
   | Server → Client | `message_complete` | `{role, content, token_count, cost_usd}` |
   | Server → Client | `error` | `{message: string}` |
   | Server → Client | `pong` | `{}` |

3. **Session state management**: On connect, load the session from `SessionStore`. Maintain an `asyncio.Event` for interrupt signaling. Keep a reference to the running streaming task so it can be cancelled on `interrupt`.

4. **Register the router** in `file:codeframe/ui/server.py`.

### Phase 3 — Backend: Streaming Chat Adapter for Anthropic SDK (#503)

**New file:** `file:codeframe/core/agent_chat_stream.py`

1. **Create `AgentChatStream` class** that wraps the `anthropic` SDK's streaming API (`anthropic.AsyncAnthropic().messages.stream()`). The `anthropic>=0.18.0` SDK already supports async streaming.

2. **`stream_response` async generator method**: accepts the session's `message_history` list and an `asyncio.Event interrupt_event`. Iterates over the SDK's streaming events and yields typed dicts matching the WebSocket protocol:
   - `RawContentBlockDeltaEvent` with `TextDelta` → yield `token`
   - `RawContentBlockDeltaEvent` with `InputJsonDelta` → yield `tool_call` input accumulation
   - `RawContentBlockStartEvent` with `ToolUseBlock` → yield `tool_call` start
   - Thinking blocks (extended thinking) → yield `thinking`
   - After stream completes → yield `message_complete` with usage stats

3. **Interrupt handling**: Check `interrupt_event.is_set()` at each yield point; if set, break the loop and close the stream context manager.

4. **Tool execution**: After a `tool_call` is yielded, the WebSocket handler executes the tool (via existing `codeframe/core/` tool infrastructure) and sends `tool_result` back to the client, then appends both to `message_history` before continuing.

5. **Persist after each complete turn**: call `SessionStore.update_session()` to save the updated `message_history`, `token_count`, and `cost_usd`.

### Phase 4 — Backend: Interrupt and Steering (part of #502)

This is handled within the WebSocket handler in `file:codeframe/ui/routers/session_chat_ws.py`:

1. **Concurrent receive loop**: Use `asyncio.create_task` to run a background task that reads incoming WebSocket messages while the streaming task runs. When an `interrupt` message arrives, set the `interrupt_event` and cancel the streaming task.

2. **Mid-session user messages**: When the agent is `idle` (no streaming task running), a `user_message` triggers a new streaming turn. When the agent is `running`, a `user_message` is queued and processed after the current turn completes (or after interrupt).

3. **Status broadcast**: After each state change (`idle` → `running` → `idle`), update the session's `status` field in `SessionStore`.

---

### Phase 5 — Frontend: Install Required Packages

Before writing any frontend code, add the missing dependencies to `file:web-ui/package.json`:
- `xterm` and `@xterm/addon-fit` (for the terminal component)
- `@xterm/addon-web-links` (optional, for clickable links in terminal)

No split-pane library is needed — implement it with CSS `flex` + a draggable divider (avoids adding a dependency).

---

### Phase 6 — Frontend: `useAgentChat` Hook (#504)

**New file:** `file:web-ui/src/hooks/useAgentChat.ts`

Model this after the existing `WebSocketClient` in `file:legacy/web-ui/src/lib/websocket.ts` but scoped to a single session.

1. **State managed by the hook**:
   - `messages: AgentMessage[]` — accumulated message list
   - `streamingContent: string` — current in-progress token stream
   - `status: 'idle' | 'connecting' | 'running' | 'error'`
   - `tokenCount: number`, `costUsd: number`

2. **`AgentMessage` type** (add to `file:web-ui/src/types/index.ts`):
   ```
   { id, role, content, toolCalls?, thinking?, tokenCount?, costUsd?, timestamp }
   ```

3. **WebSocket lifecycle**: Connect to `ws://localhost:8000/ws/sessions/{sessionId}/chat?token=...` on mount (read token from `localStorage` as in the legacy client). Reconnect with exponential backoff on disconnect.

4. **Incoming message handling**: Switch on `type` field — accumulate `token` deltas into `streamingContent`, flush to `messages` on `message_complete`, append `tool_call`/`tool_result`/`thinking` as structured entries.

5. **Exposed actions**: `sendMessage(content: string)`, `interrupt()`, both send JSON over the WebSocket.

6. **Cleanup**: Close WebSocket on unmount.

---

### Phase 7 — Frontend: `AgentChatPanel` Component (#505)

**New file:** `file:web-ui/src/components/sessions/AgentChatPanel.tsx`

1. **Props**: `{ messages: AgentMessage[], streamingContent: string, status, tokenCount, costUsd, onSendMessage, onInterrupt }`

2. **Message rendering** (reference: `file:web-ui/src/components/prd/DiscoveryPanel.tsx` and `DiscoveryTranscript.tsx`):
   - `role === 'user'` → right-aligned bubble (reuse Tailwind classes from existing components)
   - `role === 'assistant'` with plain text → left-aligned bubble, render with `react-markdown` (already in `web-ui/package.json`)
   - `tool_call` entries → collapsible card showing tool name + input JSON (use `<details>` element)
   - `tool_result` entries → collapsible card showing output JSON
   - `thinking` entries → distinct styling (e.g., italic, muted color, collapsible)
   - Streaming in-progress → show `streamingContent` with a blinking cursor

3. **Input bar** (reference: `DiscoveryInput.tsx`): `<textarea>` + Send button. Disable when `status === 'running'`. Show an **Interrupt** button when `status === 'running'`.

4. **Cost/token display**: Small footer showing `tokenCount` tokens · `$costUsd`.

5. **Auto-scroll**: `useEffect` to scroll to bottom on new messages.

---

### Phase 8 — Frontend: `AgentTerminal` Component (#506)

**New file:** `file:web-ui/src/components/sessions/AgentTerminal.tsx`

1. **Use xterm.js**: Import `Terminal` from `xterm` and `FitAddon` from `@xterm/addon-fit`. Initialize in a `useEffect` with a `useRef` for the container div.

2. **Connect to workspace**: The terminal connects to the workspace's shell via a separate WebSocket or PTY endpoint. Since no PTY backend exists yet, implement a **read-only log view** initially: subscribe to the existing SSE stream (`/api/v2/tasks/{task_id}/stream`) and write `OutputEvent` lines to the terminal. This avoids needing a new PTY backend for the first iteration.

3. **Fit on resize**: Use `FitAddon` and a `ResizeObserver` on the container div to call `fitAddon.fit()` when the pane is resized.

4. **Cleanup**: Dispose the terminal instance on unmount.

---

### Phase 9 — Frontend: `SplitPane` Layout Component (#507)

**New file:** `file:web-ui/src/components/sessions/SplitPane.tsx`

1. **Props**: `{ left: ReactNode, right: ReactNode, defaultSplit?: number }` where `defaultSplit` is a percentage (default `50`).

2. **Implementation**: Two `flex` children with a draggable divider `<div>`. On `mousedown` on the divider, attach `mousemove` and `mouseup` listeners to `document`. Calculate new split percentage from mouse position relative to container width.

3. **Persistence**: Save the split percentage to `localStorage` under a key like `codeframe:session-split` and restore on mount.

4. **Collapse**: Double-click the divider to collapse/restore the right pane (toggle between saved split and `100%`).

---

### Phase 10 — Frontend: `/sessions` List Page (#508)

**New file:** `file:web-ui/src/app/sessions/page.tsx`

1. **Data fetching**: Use `swr` to call `GET /api/v2/sessions?workspace_path=...` (read `workspacePath` from `localStorage` via `getSelectedWorkspacePath()`).

2. **Session list**: Render a table/card list of sessions showing title, status badge, created date, token count, cost. Each row links to `/sessions/[id]`.

3. **New session button**: `POST /api/v2/sessions` with the current `workspace_path`, then `router.push('/sessions/{newId}')`.

4. **Delete**: Confirm dialog (use existing `@radix-ui/react-alert-dialog`) then `DELETE /api/v2/sessions/{id}`.

5. **Add `sessionsApi`** to `file:web-ui/src/lib/api.ts` with `create`, `list`, `get`, `delete` methods.

6. **Add types** `InteractiveSession`, `SessionListResponse` to `file:web-ui/src/types/index.ts`.

---

### Phase 11 — Frontend: `/sessions/[id]` Detail Page (#509)

**New file:** `file:web-ui/src/app/sessions/[id]/page.tsx`

1. **Data fetching**: Fetch session detail via `sessionsApi.get(sessionId)` to load initial `message_history` and metadata.

2. **Wire hooks and components**:
   - Call `useAgentChat(sessionId)` to get live state and actions
   - Seed `messages` from the fetched session's `message_history` on first load
   - Render `<SplitPane left={<AgentChatPanel .../>} right={<AgentTerminal .../>} />`

3. **Page header**: Session title (editable inline), status badge, back link to `/sessions`.

---

### Phase 12 — Frontend: Sidebar Navigation Entry

**Modify:** `file:web-ui/src/components/layout/AppSidebar.tsx`

Add a new entry to the `NAV_ITEMS` array:
```
{ href: '/sessions', label: 'Sessions', icon: <suitable HugeIcons icon>, enabled: true }
```

Choose an appropriate icon from `@hugeicons/react` (e.g., `MessageMultiple01Icon` or `BubbleChatIcon`).

---

### Data Flow Diagram

```mermaid
sequenceDiagram
    participant UI as AgentChatPanel
    participant Hook as useAgentChat
    participant WS as /ws/sessions/{id}/chat
    participant Adapter as AgentChatStream
    participant SDK as Anthropic SDK
    participant Store as SessionStore

    UI->>Hook: sendMessage("fix the bug")
    Hook->>WS: {type:"user_message", content:"..."}
    WS->>Store: append user turn to history
    WS->>Adapter: stream_response(history, interrupt_event)
    Adapter->>SDK: messages.stream(...)
    loop token streaming
        SDK-->>Adapter: TextDelta / ToolUse / Thinking
        Adapter-->>WS: typed event dict
        WS-->>Hook: {type:"token", delta:"..."}
        Hook-->>UI: update streamingContent
    end
    SDK-->>Adapter: message_stop
    Adapter-->>WS: {type:"message_complete", ...}
    WS->>Store: persist updated history + usage
    WS-->>Hook: {type:"message_complete"}
    Hook-->>UI: flush to messages[], reset streamingContent

    UI->>Hook: interrupt()
    Hook->>WS: {type:"interrupt"}
    WS->>Adapter: interrupt_event.set()
    Adapter-->>WS: StopIteration
    WS-->>Hook: {type:"message_complete", partial:true}
```

---

Execution Information

Branch: main
Commit: cb074e3

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

🔗 Related PRs

#10 - feat(frontend): Multi-Agent State Management with React Context [merged]
#188 - feat(e2e): Add comprehensive error monitoring and strict verification [merged]
#221 - feat(api): add manual task generation endpoint [merged]
#224 - feat(websocket): implement proactive messaging system [merged]
#228 - fix: prevent duplicate task generation button for late-joining users [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

I have updated the Implementation Plan to reflect the recent changes in the ticket.

Previous Plan

Observations

The codebase is a v2 FastAPI + Next.js 16 / React 19 stack. The backend uses workspace_path-based routing (not project_id), JWT auth via query param for WebSocket, and an existing EventPublisher/SSE pattern in streaming_v2.py. The frontend uses axios + swr, Tailwind + Radix UI, and a sidebar-driven layout in AppSidebar. There is no xterm.js, no split-pane library, and no WebSocket client in web-ui/package.json — these must be added. The anthropic>=0.18.0 SDK is already a backend dependency.

Approach

The work is split into two parallel tracks — backend and frontend — following the sub-issue breakdown in the ticket. The backend adds a new SQLite-backed InteractiveSession entity, a dedicated WebSocket endpoint at /ws/sessions/{id}/chat, a streaming Anthropic adapter, and interrupt support. The frontend adds the useAgentChat hook, three new components (AgentChatPanel, AgentTerminal, SplitPane), and two new pages (/sessions, /sessions/[id]), wiring everything together.

---

Implementation Plan

Phase 1 — Backend: DB Schema + CRUD API for Interactive Sessions

New file: codeframe/ui/routers/sessions_v2.py

1. Define the InteractiveSession SQLAlchemy model (or a plain dataclass stored in the workspace SQLite DB, consistent with how other v2 entities are stored). Fields:

   • id (UUID string, primary key)
   • workspace_path (string)
   • title (string, optional)
   • status (idle | running | interrupted | completed)
   • created_at, updated_at (ISO timestamps)
   • message_history (JSON blob — list of {role, content, tool_calls?, thinking?})
   • token_count, cost_usd (floats, updated incrementally)

2. Add CRUD methods to the workspace's state layer (consistent with how codeframe/core/ modules manage state files). Create a SessionStore class in codeframe/core/session_store.py that reads/writes sessions as JSON files under <workspace_state_dir>/sessions/.

3. Create REST endpoints in codeframe/ui/routers/sessions_v2.py:

   • POST /api/v2/sessions — create a new session (body: workspace_path, optional title)
   • GET /api/v2/sessions — list sessions for a workspace (query: workspace_path)
   • GET /api/v2/sessions/{session_id} — get session detail including full message history
   • DELETE /api/v2/sessions/{session_id} — delete a session

4. Register the router in codeframe/ui/server.py alongside the other v2 routers.

5. Add Pydantic response models (InteractiveSessionResponse, SessionListResponse) in codeframe/ui/models.py or a new codeframe/ui/routers/sessions_v2.py local models block.

---

Phase 2 — Backend: WebSocket Endpoint for Streaming Agent Chat

New file: codeframe/ui/routers/session_chat_ws.py

The new WebSocket endpoint lives at /ws/sessions/{session_id}/chat and is separate from the existing /ws (project status) endpoint.

1. Create the router with @router.websocket("/ws/sessions/{session_id}/chat"). Reuse the same JWT-from-query-param auth pattern from codeframe/ui/routers/websocket.py (extract token, decode with pyjwt, verify user).

2. Message protocol (JSON over WebSocket):

   Direction	Type	Payload
   Client → Server	user_message	{content: string}
   Client → Server	interrupt	{}
   Client → Server	ping	{}
   Server → Client	token	{delta: string}
   Server → Client	tool_call	{id, name, input}
   Server → Client	tool_result	{tool_call_id, output}
   Server → Client	thinking	{delta: string}
   Server → Client	message_complete	{role, content, token_count, cost_usd}
   Server → Client	error	{message: string}
   Server → Client	pong	{}

3. Session state management: On connect, load the session from SessionStore. Maintain an asyncio.Event for interrupt signaling. Keep a reference to the running streaming task so it can be cancelled on interrupt.

4. Register the router in codeframe/ui/server.py.

---

Phase 3 — Backend: Streaming Chat Adapter for Anthropic SDK

New file: codeframe/core/agent_chat_stream.py

1. Create AgentChatStream class that wraps the anthropic SDK's streaming API (anthropic.AsyncAnthropic().messages.stream()). The anthropic>=0.18.0 SDK already supports async streaming.

2. stream_response async generator method: accepts the session's message_history list and an asyncio.Event interrupt_event. Iterates over the SDK's streaming events and yields typed dicts matching the WebSocket protocol above:

   • RawContentBlockDeltaEvent with TextDelta → yield token
   • RawContentBlockDeltaEvent with InputJsonDelta → yield tool_call input accumulation
   • RawContentBlockStartEvent with ToolUseBlock → yield tool_call start
   • Thinking blocks (extended thinking) → yield thinking
   • After stream completes → yield message_complete with usage stats

3. Interrupt handling: Check interrupt_event.is_set() at each yield point; if set, break the loop and close the stream context manager.

4. Tool execution: After a tool_call is yielded, the WebSocket handler executes the tool (via existing codeframe/core/ tool infrastructure) and sends tool_result back to the client, then appends both to message_history before continuing.

5. Persist after each complete turn: call SessionStore.update_session() to save the updated message_history, token_count, and cost_usd.

---

Phase 4 — Backend: Interrupt and Steering

This is handled within the WebSocket handler in session_chat_ws.py:

1. Concurrent receive loop: Use asyncio.create_task to run a background task that reads incoming WebSocket messages while the streaming task runs. When an interrupt message arrives, set the interrupt_event and cancel the streaming task.

2. Mid-session user messages: When the agent is idle (no streaming task running), a user_message triggers a new streaming turn. When the agent is running, a user_message is queued and processed after the current turn completes (or after interrupt).

3. Status broadcast: After each state change (idle → running → idle), update the session's status field in SessionStore.

---

Phase 5 — Frontend: Install Required Packages

Before writing any frontend code, add the missing dependencies to file:web-ui/package.json:

• xterm and @xterm/addon-fit (for the terminal component)
• @xterm/addon-web-links (optional, for clickable links in terminal)

No split-pane library is needed — implement it with CSS flex + a draggable divider (avoids adding a dependency).

---

Phase 6 — Frontend: useAgentChat Hook

New file: web-ui/src/hooks/useAgentChat.ts

Model this after the existing WebSocketClient in file:legacy/web-ui/src/lib/websocket.ts but scoped to a single session.

1. State managed by the hook:

   • messages: AgentMessage[] — accumulated message list
   • streamingContent: string — current in-progress token stream
   • status: 'idle' | 'connecting' | 'running' | 'error'
   • tokenCount: number, costUsd: number

2. AgentMessage type (add to file:web-ui/src/types/index.ts):

   { id, role, content, toolCalls?, thinking?, tokenCount?, costUsd?, timestamp }
   

3. WebSocket lifecycle: Connect to ws://localhost:8000/ws/sessions/{sessionId}/chat?token=... on mount (read token from localStorage as in the legacy client). Reconnect with exponential backoff on disconnect.

4. Incoming message handling: Switch on type field — accumulate token deltas into streamingContent, flush to messages on message_complete, append tool_call/tool_result/thinking as structured entries.

5. Exposed actions: sendMessage(content: string), interrupt(), both send JSON over the WebSocket.

6. Cleanup: Close WebSocket on unmount.

---

Phase 7 — Frontend: AgentChatPanel Component

New file: web-ui/src/components/sessions/AgentChatPanel.tsx

1. Props: { messages: AgentMessage[], streamingContent: string, status, tokenCount, costUsd, onSendMessage, onInterrupt }

2. Message rendering:

   • role === 'user' → right-aligned bubble (reuse Tailwind classes from existing components)
   • role === 'assistant' with plain text → left-aligned bubble, render with react-markdown (already in web-ui/package.json)
   • tool_call entries → collapsible card showing tool name + input JSON (use @radix-ui/react-dialog or a simple <details> element)
   • tool_result entries → collapsible card showing output JSON
   • thinking entries → distinct styling (e.g., italic, muted color, collapsible)
   • Streaming in-progress → show streamingContent with a blinking cursor

3. Input bar: <textarea> + Send button. Disable when status === 'running'. Show an Interrupt button when status === 'running'.

4. Cost/token display: Small footer showing tokenCount tokens · $costUsd.

5. Auto-scroll: useEffect to scroll to bottom on new messages.

---

Phase 8 — Frontend: AgentTerminal Component

New file: web-ui/src/components/sessions/AgentTerminal.tsx

1. Use xterm.js: Import Terminal from xterm and FitAddon from @xterm/addon-fit. Initialize in a useEffect with a useRef for the container div.

2. Connect to workspace: The terminal connects to the workspace's shell via a separate WebSocket or PTY endpoint. Since no PTY backend exists yet, implement a read-only log view initially: subscribe to the existing SSE stream (/api/v2/tasks/{task_id}/stream) and write OutputEvent lines to the terminal. This avoids needing a new PTY backend for the first iteration.

3. Fit on resize: Use FitAddon and a ResizeObserver on the container div to call fitAddon.fit() when the pane is resized.

4. Cleanup: Dispose the terminal instance on unmount.

---

Phase 9 — Frontend: SplitPane Layout Component

New file: web-ui/src/components/sessions/SplitPane.tsx

1. Props: { left: ReactNode, right: ReactNode, defaultSplit?: number } where defaultSplit is a percentage (default 50).

2. Implementation: Two flex children with a draggable divider <div>. On mousedown on the divider, attach mousemove and mouseup listeners to document. Calculate new split percentage from mouse position relative to container width.

3. Persistence: Save the split percentage to localStorage under a key like codeframe:session-split and restore on mount.

4. Collapse: Double-click the divider to collapse/restore the right pane (toggle between saved split and 100%).

---

Phase 10 — Frontend: /sessions List Page

New file: web-ui/src/app/sessions/page.tsx

1. Data fetching: Use swr to call GET /api/v2/sessions?workspace_path=... (read workspacePath from localStorage via getSelectedWorkspacePath()).

2. Session list: Render a table/card list of sessions showing title, status badge, created date, token count, cost. Each row links to /sessions/[id].

3. New session button: POST /api/v2/sessions with the current workspace_path, then router.push('/sessions/{newId}').

4. Delete: Confirm dialog (use existing @radix-ui/react-alert-dialog) then DELETE /api/v2/sessions/{id}.

5. Add sessionsApi to file:web-ui/src/lib/api.ts with create, list, get, delete methods.

6. Add types InteractiveSession, SessionListResponse to file:web-ui/src/types/index.ts.

---

Phase 11 — Frontend: /sessions/[id] Detail Page

New file: web-ui/src/app/sessions/[id]/page.tsx

1. Data fetching: Fetch session detail via sessionsApi.get(sessionId) to load initial message_history and metadata.

2. Wire hooks and components:

   • Call useAgentChat(sessionId) to get live state and actions
   • Seed messages from the fetched session's message_history on first load
   • Render <SplitPane left={<AgentChatPanel .../>} right={<AgentTerminal .../>} />

3. Page header: Session title (editable inline), status badge, back link to /sessions.

---

Phase 12 — Frontend: Sidebar Navigation Entry

Modify: file:web-ui/src/components/layout/AppSidebar.tsx

Add a new entry to the NAV_ITEMS array:

{ href: '/sessions', label: 'Sessions', icon: <suitable HugeIcons icon>, enabled: true }

Choose an appropriate icon from @hugeicons/react (e.g., MessageMultiple01Icon or BubbleChatIcon).

---

Data Flow Diagram

sequenceDiagram
    participant UI as AgentChatPanel
    participant Hook as useAgentChat
    participant WS as /ws/sessions/{id}/chat
    participant Adapter as AgentChatStream
    participant SDK as Anthropic SDK
    participant Store as SessionStore

    UI->>Hook: sendMessage("fix the bug")
    Hook->>WS: {type:"user_message", content:"..."}
    WS->>Store: append user turn to history
    WS->>Adapter: stream_response(history, interrupt_event)
    Adapter->>SDK: messages.stream(...)
    loop token streaming
        SDK-->>Adapter: TextDelta / ToolUse / Thinking
        Adapter-->>WS: typed event dict
        WS-->>Hook: {type:"token", delta:"..."}
        Hook-->>UI: update streamingContent
    end
    SDK-->>Adapter: message_stop
    Adapter-->>WS: {type:"message_complete", ...}
    WS->>Store: persist updated history + usage
    WS-->>Hook: {type:"message_complete"}
    Hook-->>UI: flush to messages[], reset streamingContent

    UI->>Hook: interrupt()
    Hook->>WS: {type:"interrupt"}
    WS->>Adapter: interrupt_event.set()
    Adapter-->>WS: StopIteration
    WS-->>Hook: {type:"message_complete", partial:true}

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase is a **v2 FastAPI + Next.js 16 / React 19** stack. The backend uses `workspace_path`-based routing (not `project_id`), JWT auth via query param for WebSocket, and an existing `EventPublisher`/SSE pattern in `streaming_v2.py`. The frontend uses `axios` + `swr`, Tailwind + Radix UI, and a sidebar-driven layout in `AppSidebar`. There is **no xterm.js, no split-pane library, and no WebSocket client** in `web-ui/package.json` — these must be added. The `anthropic>=0.18.0` SDK is already a backend dependency.

## Approach

The work is split into two parallel tracks — backend and frontend — following the sub-issue breakdown in the ticket. The backend adds a new SQLite-backed `InteractiveSession` entity, a dedicated WebSocket endpoint at `/ws/sessions/{id}/chat`, a streaming Anthropic adapter, and interrupt support. The frontend adds the `useAgentChat` hook, three new components (`AgentChatPanel`, `AgentTerminal`, `SplitPane`), and two new pages (`/sessions`, `/sessions/[id]`), wiring everything together.

---

## Implementation Plan

### Phase 1 — Backend: DB Schema + CRUD API for Interactive Sessions

**New file:** `codeframe/ui/routers/sessions_v2.py`

1. **Define the `InteractiveSession` SQLAlchemy model** (or a plain dataclass stored in the workspace SQLite DB, consistent with how other v2 entities are stored). Fields:
   - `id` (UUID string, primary key)
   - `workspace_path` (string)
   - `title` (string, optional)
   - `status` (`idle` | `running` | `interrupted` | `completed`)
   - `created_at`, `updated_at` (ISO timestamps)
   - `message_history` (JSON blob — list of `{role, content, tool_calls?, thinking?}`)
   - `token_count`, `cost_usd` (floats, updated incrementally)

2. **Add CRUD methods** to the workspace's state layer (consistent with how `codeframe/core/` modules manage state files). Create a `SessionStore` class in `codeframe/core/session_store.py` that reads/writes sessions as JSON files under `<workspace_state_dir>/sessions/`.

3. **Create REST endpoints** in `codeframe/ui/routers/sessions_v2.py`:
   - `POST /api/v2/sessions` — create a new session (body: `workspace_path`, optional `title`)
   - `GET /api/v2/sessions` — list sessions for a workspace (query: `workspace_path`)
   - `GET /api/v2/sessions/{session_id}` — get session detail including full message history
   - `DELETE /api/v2/sessions/{session_id}` — delete a session

4. **Register the router** in `codeframe/ui/server.py` alongside the other v2 routers.

5. **Add Pydantic response models** (`InteractiveSessionResponse`, `SessionListResponse`) in `codeframe/ui/models.py` or a new `codeframe/ui/routers/sessions_v2.py` local models block.

---

### Phase 2 — Backend: WebSocket Endpoint for Streaming Agent Chat

**New file:** `codeframe/ui/routers/session_chat_ws.py`

The new WebSocket endpoint lives at `/ws/sessions/{session_id}/chat` and is separate from the existing `/ws` (project status) endpoint.

1. **Create the router** with `@router.websocket("/ws/sessions/{session_id}/chat")`. Reuse the same JWT-from-query-param auth pattern from `codeframe/ui/routers/websocket.py` (extract `token`, decode with `pyjwt`, verify user).

2. **Message protocol** (JSON over WebSocket):

   | Direction | Type | Payload |
   |---|---|---|
   | Client → Server | `user_message` | `{content: string}` |
   | Client → Server | `interrupt` | `{}` |
   | Client → Server | `ping` | `{}` |
   | Server → Client | `token` | `{delta: string}` |
   | Server → Client | `tool_call` | `{id, name, input}` |
   | Server → Client | `tool_result` | `{tool_call_id, output}` |
   | Server → Client | `thinking` | `{delta: string}` |
   | Server → Client | `message_complete` | `{role, content, token_count, cost_usd}` |
   | Server → Client | `error` | `{message: string}` |
   | Server → Client | `pong` | `{}` |

3. **Session state management**: On connect, load the session from `SessionStore`. Maintain an `asyncio.Event` for interrupt signaling. Keep a reference to the running streaming task so it can be cancelled on `interrupt`.

4. **Register the router** in `codeframe/ui/server.py`.

---

### Phase 3 — Backend: Streaming Chat Adapter for Anthropic SDK

**New file:** `codeframe/core/agent_chat_stream.py`

1. **Create `AgentChatStream` class** that wraps the `anthropic` SDK's streaming API (`anthropic.AsyncAnthropic().messages.stream()`). The `anthropic>=0.18.0` SDK already supports async streaming.

2. **`stream_response` async generator method**: accepts the session's `message_history` list and an `asyncio.Event interrupt_event`. Iterates over the SDK's streaming events and yields typed dicts matching the WebSocket protocol above:
   - `RawContentBlockDeltaEvent` with `TextDelta` → yield `token`
   - `RawContentBlockDeltaEvent` with `InputJsonDelta` → yield `tool_call` input accumulation
   - `RawContentBlockStartEvent` with `ToolUseBlock` → yield `tool_call` start
   - Thinking blocks (extended thinking) → yield `thinking`
   - After stream completes → yield `message_complete` with usage stats

3. **Interrupt handling**: Check `interrupt_event.is_set()` at each yield point; if set, break the loop and close the stream context manager.

4. **Tool execution**: After a `tool_call` is yielded, the WebSocket handler executes the tool (via existing `codeframe/core/` tool infrastructure) and sends `tool_result` back to the client, then appends both to `message_history` before continuing.

5. **Persist after each complete turn**: call `SessionStore.update_session()` to save the updated `message_history`, `token_count`, and `cost_usd`.

---

### Phase 4 — Backend: Interrupt and Steering

This is handled within the WebSocket handler in `session_chat_ws.py`:

1. **Concurrent receive loop**: Use `asyncio.create_task` to run a background task that reads incoming WebSocket messages while the streaming task runs. When an `interrupt` message arrives, set the `interrupt_event` and cancel the streaming task.

2. **Mid-session user messages**: When the agent is `idle` (no streaming task running), a `user_message` triggers a new streaming turn. When the agent is `running`, a `user_message` is queued and processed after the current turn completes (or after interrupt).

3. **Status broadcast**: After each state change (`idle` → `running` → `idle`), update the session's `status` field in `SessionStore`.

---

### Phase 5 — Frontend: Install Required Packages

Before writing any frontend code, add the missing dependencies to `file:web-ui/package.json`:
- `xterm` and `@xterm/addon-fit` (for the terminal component)
- `@xterm/addon-web-links` (optional, for clickable links in terminal)

No split-pane library is needed — implement it with CSS `flex` + a draggable divider (avoids adding a dependency).

---

### Phase 6 — Frontend: `useAgentChat` Hook

**New file:** `web-ui/src/hooks/useAgentChat.ts`

Model this after the existing `WebSocketClient` in `file:legacy/web-ui/src/lib/websocket.ts` but scoped to a single session.

1. **State managed by the hook**:
   - `messages: AgentMessage[]` — accumulated message list
   - `streamingContent: string` — current in-progress token stream
   - `status: 'idle' | 'connecting' | 'running' | 'error'`
   - `tokenCount: number`, `costUsd: number`

2. **`AgentMessage` type** (add to `file:web-ui/src/types/index.ts`):
   ```
   { id, role, content, toolCalls?, thinking?, tokenCount?, costUsd?, timestamp }
   ```

3. **WebSocket lifecycle**: Connect to `ws://localhost:8000/ws/sessions/{sessionId}/chat?token=...` on mount (read token from `localStorage` as in the legacy client). Reconnect with exponential backoff on disconnect.

4. **Incoming message handling**: Switch on `type` field — accumulate `token` deltas into `streamingContent`, flush to `messages` on `message_complete`, append `tool_call`/`tool_result`/`thinking` as structured entries.

5. **Exposed actions**: `sendMessage(content: string)`, `interrupt()`, both send JSON over the WebSocket.

6. **Cleanup**: Close WebSocket on unmount.

---

### Phase 7 — Frontend: `AgentChatPanel` Component

**New file:** `web-ui/src/components/sessions/AgentChatPanel.tsx`

1. **Props**: `{ messages: AgentMessage[], streamingContent: string, status, tokenCount, costUsd, onSendMessage, onInterrupt }`

2. **Message rendering**:
   - `role === 'user'` → right-aligned bubble (reuse Tailwind classes from existing components)
   - `role === 'assistant'` with plain text → left-aligned bubble, render with `react-markdown` (already in `web-ui/package.json`)
   - `tool_call` entries → collapsible card showing tool name + input JSON (use `@radix-ui/react-dialog` or a simple `<details>` element)
   - `tool_result` entries → collapsible card showing output JSON
   - `thinking` entries → distinct styling (e.g., italic, muted color, collapsible)
   - Streaming in-progress → show `streamingContent` with a blinking cursor

3. **Input bar**: `<textarea>` + Send button. Disable when `status === 'running'`. Show an **Interrupt** button when `status === 'running'`.

4. **Cost/token display**: Small footer showing `tokenCount` tokens · `$costUsd`.

5. **Auto-scroll**: `useEffect` to scroll to bottom on new messages.

---

### Phase 8 — Frontend: `AgentTerminal` Component

**New file:** `web-ui/src/components/sessions/AgentTerminal.tsx`

1. **Use xterm.js**: Import `Terminal` from `xterm` and `FitAddon` from `@xterm/addon-fit`. Initialize in a `useEffect` with a `useRef` for the container div.

2. **Connect to workspace**: The terminal connects to the workspace's shell via a separate WebSocket or PTY endpoint. Since no PTY backend exists yet, implement a **read-only log view** initially: subscribe to the existing SSE stream (`/api/v2/tasks/{task_id}/stream`) and write `OutputEvent` lines to the terminal. This avoids needing a new PTY backend for the first iteration.

3. **Fit on resize**: Use `FitAddon` and a `ResizeObserver` on the container div to call `fitAddon.fit()` when the pane is resized.

4. **Cleanup**: Dispose the terminal instance on unmount.

---

### Phase 9 — Frontend: `SplitPane` Layout Component

**New file:** `web-ui/src/components/sessions/SplitPane.tsx`

1. **Props**: `{ left: ReactNode, right: ReactNode, defaultSplit?: number }` where `defaultSplit` is a percentage (default `50`).

2. **Implementation**: Two `flex` children with a draggable divider `<div>`. On `mousedown` on the divider, attach `mousemove` and `mouseup` listeners to `document`. Calculate new split percentage from mouse position relative to container width.

3. **Persistence**: Save the split percentage to `localStorage` under a key like `codeframe:session-split` and restore on mount.

4. **Collapse**: Double-click the divider to collapse/restore the right pane (toggle between saved split and `100%`).

---

### Phase 10 — Frontend: `/sessions` List Page

**New file:** `web-ui/src/app/sessions/page.tsx`

1. **Data fetching**: Use `swr` to call `GET /api/v2/sessions?workspace_path=...` (read `workspacePath` from `localStorage` via `getSelectedWorkspacePath()`).

2. **Session list**: Render a table/card list of sessions showing title, status badge, created date, token count, cost. Each row links to `/sessions/[id]`.

3. **New session button**: `POST /api/v2/sessions` with the current `workspace_path`, then `router.push('/sessions/{newId}')`.

4. **Delete**: Confirm dialog (use existing `@radix-ui/react-alert-dialog`) then `DELETE /api/v2/sessions/{id}`.

5. **Add `sessionsApi`** to `file:web-ui/src/lib/api.ts` with `create`, `list`, `get`, `delete` methods.

6. **Add types** `InteractiveSession`, `SessionListResponse` to `file:web-ui/src/types/index.ts`.

---

### Phase 11 — Frontend: `/sessions/[id]` Detail Page

**New file:** `web-ui/src/app/sessions/[id]/page.tsx`

1. **Data fetching**: Fetch session detail via `sessionsApi.get(sessionId)` to load initial `message_history` and metadata.

2. **Wire hooks and components**:
   - Call `useAgentChat(sessionId)` to get live state and actions
   - Seed `messages` from the fetched session's `message_history` on first load
   - Render `<SplitPane left={<AgentChatPanel .../>} right={<AgentTerminal .../>} />`

3. **Page header**: Session title (editable inline), status badge, back link to `/sessions`.

---

### Phase 12 — Frontend: Sidebar Navigation Entry

**Modify:** `file:web-ui/src/components/layout/AppSidebar.tsx`

Add a new entry to the `NAV_ITEMS` array:
```
{ href: '/sessions', label: 'Sessions', icon: <suitable HugeIcons icon>, enabled: true }
```

Choose an appropriate icon from `@hugeicons/react` (e.g., `MessageMultiple01Icon` or `BubbleChatIcon`).

---

### Data Flow Diagram

```mermaid
sequenceDiagram
    participant UI as AgentChatPanel
    participant Hook as useAgentChat
    participant WS as /ws/sessions/{id}/chat
    participant Adapter as AgentChatStream
    participant SDK as Anthropic SDK
    participant Store as SessionStore

    UI->>Hook: sendMessage("fix the bug")
    Hook->>WS: {type:"user_message", content:"..."}
    WS->>Store: append user turn to history
    WS->>Adapter: stream_response(history, interrupt_event)
    Adapter->>SDK: messages.stream(...)
    loop token streaming
        SDK-->>Adapter: TextDelta / ToolUse / Thinking
        Adapter-->>WS: typed event dict
        WS-->>Hook: {type:"token", delta:"..."}
        Hook-->>UI: update streamingContent
    end
    SDK-->>Adapter: message_stop
    Adapter-->>WS: {type:"message_complete", ...}
    WS->>Store: persist updated history + usage
    WS-->>Hook: {type:"message_complete"}
    Hook-->>UI: flush to messages[], reset streamingContent

    UI->>Hook: interrupt()
    Hook->>WS: {type:"interrupt"}
    WS->>Adapter: interrupt_event.set()
    Adapter-->>WS: StopIteration
    WS-->>Hook: {type:"message_complete", partial:true}
```

---

Execution Information

Branch: main
Commit: cb074e3

New Plan

Observations

The codebase is a FastAPI + Next.js stack with two UI layers: a legacy legacy/web-ui (v1) and a new web-ui (v2). The backend uses both project_id-based routing (legacy) and workspace_path-based routing (v2). WebSocket auth uses JWT via query param. The existing /ws endpoint handles project status updates (subscribe/broadcast), not interactive message exchange. The existing POST /api/projects/{id}/chat endpoint is wired to the Lead Agent only and returns complete responses (not streaming). The DiscoveryPanel component in web-ui/src/components/prd/DiscoveryPanel.tsx provides a reference for session-based chat UI patterns. The ticket defines 9 atomic sub-issues with a dependency graph: backend (#501–#503) must complete before frontend (#504–#509).

Approach

The work is split into two parallel tracks — backend and frontend — following the 9 atomic sub-issues in the ticket. The backend (#501–#503) adds a new InteractiveSession entity with CRUD API, a dedicated WebSocket endpoint at /ws/sessions/{id}/chat for streaming agent chat, and a streaming Anthropic adapter that relays tokens in real-time. The frontend (#504–#509) adds the useAgentChat hook for WebSocket connection and message accumulation, three new components (AgentChatPanel, AgentTerminal, SplitPane), and two new pages (/sessions, /sessions/[id]). The implementation reuses existing patterns: WebSocket auth from codeframe/ui/routers/websocket.py, chat API structure from codeframe/ui/routers/chat.py, SSE streaming from streaming_v2.py, and UI patterns from DiscoveryPanel.tsx.

---

Implementation Plan

Phase 1 — Backend: DB Schema + CRUD API for Interactive Sessions (#501)

New file: file:codeframe/ui/routers/sessions_v2.py

1. Define the InteractiveSession data model in file:codeframe/ui/routers/sessions_v2.py. Fields:

   • id (UUID string, primary key)
   • workspace_path (string, from query param or request body)
   • title (string, optional)
   • status (idle | running | interrupted | completed)
   • created_at, updated_at (ISO timestamps)
   • message_history (JSON list of {role, content, tool_calls?, thinking?, timestamp})
   • token_count, cost_usd (floats, updated incrementally)

2. Create a SessionStore class in file:codeframe/core/session_store.py that persists sessions as JSON files under <workspace_state_dir>/sessions/. Implement methods: create(), get(), list(), update(), delete().

3. Create REST endpoints in file:codeframe/ui/routers/sessions_v2.py:

   • POST /api/v2/sessions — create a new session (body: workspace_path, optional title)
   • GET /api/v2/sessions — list sessions for a workspace (query: workspace_path)
   • GET /api/v2/sessions/{session_id} — get session detail including full message history
   • DELETE /api/v2/sessions/{session_id} — delete a session

4. Add Pydantic response models in file:codeframe/ui/response_models.py: InteractiveSessionResponse, SessionListResponse.

5. Register the router in file:codeframe/ui/server.py alongside the other v2 routers.

Phase 2 — Backend: WebSocket Endpoint for Streaming Agent Chat (#502)

New file: file:codeframe/ui/routers/session_chat_ws.py

The new WebSocket endpoint lives at /ws/sessions/{session_id}/chat and is separate from the existing /ws (project status) endpoint.

1. Create the router with @router.websocket("/ws/sessions/{session_id}/chat"). Reuse JWT-from-query-param auth from file:codeframe/ui/routers/websocket.py (extract token, decode with pyjwt, verify user).

2. Message protocol (JSON over WebSocket):

   Direction	Type	Payload
   Client → Server	user_message	{content: string}
   Client → Server	interrupt	{}
   Client → Server	ping	{}
   Server → Client	token	{delta: string}
   Server → Client	tool_call	{id, name, input}
   Server → Client	tool_result	{tool_call_id, output}
   Server → Client	thinking	{delta: string}
   Server → Client	message_complete	{role, content, token_count, cost_usd}
   Server → Client	error	{message: string}
   Server → Client	pong	{}

3. Session state management: On connect, load the session from SessionStore. Maintain an asyncio.Event for interrupt signaling. Keep a reference to the running streaming task so it can be cancelled on interrupt.

4. Register the router in file:codeframe/ui/server.py.

Phase 3 — Backend: Streaming Chat Adapter for Anthropic SDK (#503)

New file: file:codeframe/core/agent_chat_stream.py

1. Create AgentChatStream class that wraps the anthropic SDK's streaming API (anthropic.AsyncAnthropic().messages.stream()). The anthropic>=0.18.0 SDK already supports async streaming.

2. stream_response async generator method: accepts the session's message_history list and an asyncio.Event interrupt_event. Iterates over the SDK's streaming events and yields typed dicts matching the WebSocket protocol:

   • RawContentBlockDeltaEvent with TextDelta → yield token
   • RawContentBlockDeltaEvent with InputJsonDelta → yield tool_call input accumulation
   • RawContentBlockStartEvent with ToolUseBlock → yield tool_call start
   • Thinking blocks (extended thinking) → yield thinking
   • After stream completes → yield message_complete with usage stats

3. Interrupt handling: Check interrupt_event.is_set() at each yield point; if set, break the loop and close the stream context manager.

4. Tool execution: After a tool_call is yielded, the WebSocket handler executes the tool (via existing codeframe/core/ tool infrastructure) and sends tool_result back to the client, then appends both to message_history before continuing.

5. Persist after each complete turn: call SessionStore.update_session() to save the updated message_history, token_count, and cost_usd.

Phase 4 — Backend: Interrupt and Steering (part of #502)

This is handled within the WebSocket handler in file:codeframe/ui/routers/session_chat_ws.py:

1. Concurrent receive loop: Use asyncio.create_task to run a background task that reads incoming WebSocket messages while the streaming task runs. When an interrupt message arrives, set the interrupt_event and cancel the streaming task.

2. Mid-session user messages: When the agent is idle (no streaming task running), a user_message triggers a new streaming turn. When the agent is running, a user_message is queued and processed after the current turn completes (or after interrupt).

3. Status broadcast: After each state change (idle → running → idle), update the session's status field in SessionStore.

---

Phase 5 — Frontend: Install Required Packages

Before writing any frontend code, add the missing dependencies to file:web-ui/package.json:

• xterm and @xterm/addon-fit (for the terminal component)
• @xterm/addon-web-links (optional, for clickable links in terminal)

No split-pane library is needed — implement it with CSS flex + a draggable divider (avoids adding a dependency).

---

Phase 6 — Frontend: useAgentChat Hook (#504)

New file: file:web-ui/src/hooks/useAgentChat.ts

Model this after the existing WebSocketClient in file:legacy/web-ui/src/lib/websocket.ts but scoped to a single session.

1. State managed by the hook:

   • messages: AgentMessage[] — accumulated message list
   • streamingContent: string — current in-progress token stream
   • status: 'idle' | 'connecting' | 'running' | 'error'
   • tokenCount: number, costUsd: number

2. AgentMessage type (add to file:web-ui/src/types/index.ts):

   { id, role, content, toolCalls?, thinking?, tokenCount?, costUsd?, timestamp }
   

3. WebSocket lifecycle: Connect to ws://localhost:8000/ws/sessions/{sessionId}/chat?token=... on mount (read token from localStorage as in the legacy client). Reconnect with exponential backoff on disconnect.

4. Incoming message handling: Switch on type field — accumulate token deltas into streamingContent, flush to messages on message_complete, append tool_call/tool_result/thinking as structured entries.

5. Exposed actions: sendMessage(content: string), interrupt(), both send JSON over the WebSocket.

6. Cleanup: Close WebSocket on unmount.

---

Phase 7 — Frontend: AgentChatPanel Component (#505)

New file: file:web-ui/src/components/sessions/AgentChatPanel.tsx

1. Props: { messages: AgentMessage[], streamingContent: string, status, tokenCount, costUsd, onSendMessage, onInterrupt }

2. Message rendering (reference: file:web-ui/src/components/prd/DiscoveryPanel.tsx and DiscoveryTranscript.tsx):

   • role === 'user' → right-aligned bubble (reuse Tailwind classes from existing components)
   • role === 'assistant' with plain text → left-aligned bubble, render with react-markdown (already in web-ui/package.json)
   • tool_call entries → collapsible card showing tool name + input JSON (use <details> element)
   • tool_result entries → collapsible card showing output JSON
   • thinking entries → distinct styling (e.g., italic, muted color, collapsible)
   • Streaming in-progress → show streamingContent with a blinking cursor

3. Input bar (reference: DiscoveryInput.tsx): <textarea> + Send button. Disable when status === 'running'. Show an Interrupt button when status === 'running'.

4. Cost/token display: Small footer showing tokenCount tokens · $costUsd.

5. Auto-scroll: useEffect to scroll to bottom on new messages.

---

Phase 8 — Frontend: AgentTerminal Component (#506)

New file: file:web-ui/src/components/sessions/AgentTerminal.tsx

1. Use xterm.js: Import Terminal from xterm and FitAddon from @xterm/addon-fit. Initialize in a useEffect with a useRef for the container div.

2. Connect to workspace: The terminal connects to the workspace's shell via a separate WebSocket or PTY endpoint. Since no PTY backend exists yet, implement a read-only log view initially: subscribe to the existing SSE stream (/api/v2/tasks/{task_id}/stream) and write OutputEvent lines to the terminal. This avoids needing a new PTY backend for the first iteration.

3. Fit on resize: Use FitAddon and a ResizeObserver on the container div to call fitAddon.fit() when the pane is resized.

4. Cleanup: Dispose the terminal instance on unmount.

---

Phase 9 — Frontend: SplitPane Layout Component (#507)

New file: file:web-ui/src/components/sessions/SplitPane.tsx

1. Props: { left: ReactNode, right: ReactNode, defaultSplit?: number } where defaultSplit is a percentage (default 50).

2. Implementation: Two flex children with a draggable divider <div>. On mousedown on the divider, attach mousemove and mouseup listeners to document. Calculate new split percentage from mouse position relative to container width.

3. Persistence: Save the split percentage to localStorage under a key like codeframe:session-split and restore on mount.

4. Collapse: Double-click the divider to collapse/restore the right pane (toggle between saved split and 100%).

---

Phase 10 — Frontend: /sessions List Page (#508)

New file: file:web-ui/src/app/sessions/page.tsx

1. Data fetching: Use swr to call GET /api/v2/sessions?workspace_path=... (read workspacePath from localStorage via getSelectedWorkspacePath()).

2. Session list: Render a table/card list of sessions showing title, status badge, created date, token count, cost. Each row links to /sessions/[id].

3. New session button: POST /api/v2/sessions with the current workspace_path, then router.push('/sessions/{newId}').

4. Delete: Confirm dialog (use existing @radix-ui/react-alert-dialog) then DELETE /api/v2/sessions/{id}.

5. Add sessionsApi to file:web-ui/src/lib/api.ts with create, list, get, delete methods.

6. Add types InteractiveSession, SessionListResponse to file:web-ui/src/types/index.ts.

---

Phase 11 — Frontend: /sessions/[id] Detail Page (#509)

New file: file:web-ui/src/app/sessions/[id]/page.tsx

1. Data fetching: Fetch session detail via sessionsApi.get(sessionId) to load initial message_history and metadata.

2. Wire hooks and components:

   • Call useAgentChat(sessionId) to get live state and actions
   • Seed messages from the fetched session's message_history on first load
   • Render <SplitPane left={<AgentChatPanel .../>} right={<AgentTerminal .../>} />

3. Page header: Session title (editable inline), status badge, back link to /sessions.

---

Phase 12 — Frontend: Sidebar Navigation Entry

Modify: file:web-ui/src/components/layout/AppSidebar.tsx

Add a new entry to the NAV_ITEMS array:

{ href: '/sessions', label: 'Sessions', icon: <suitable HugeIcons icon>, enabled: true }

Choose an appropriate icon from @hugeicons/react (e.g., MessageMultiple01Icon or BubbleChatIcon).

---

Data Flow Diagram

sequenceDiagram
    participant UI as AgentChatPanel
    participant Hook as useAgentChat
    participant WS as /ws/sessions/{id}/chat
    participant Adapter as AgentChatStream
    participant SDK as Anthropic SDK
    participant Store as SessionStore

    UI->>Hook: sendMessage("fix the bug")
    Hook->>WS: {type:"user_message", content:"..."}
    WS->>Store: append user turn to history
    WS->>Adapter: stream_response(history, interrupt_event)
    Adapter->>SDK: messages.stream(...)
    loop token streaming
        SDK-->>Adapter: TextDelta / ToolUse / Thinking
        Adapter-->>WS: typed event dict
        WS-->>Hook: {type:"token", delta:"..."}
        Hook-->>UI: update streamingContent
    end
    SDK-->>Adapter: message_stop
    Adapter-->>WS: {type:"message_complete", ...}
    WS->>Store: persist updated history + usage
    WS-->>Hook: {type:"message_complete"}
    Hook-->>UI: flush to messages[], reset streamingContent

    UI->>Hook: interrupt()
    Hook->>WS: {type:"interrupt"}
    WS->>Adapter: interrupt_event.set()
    Adapter-->>WS: StopIteration
    WS-->>Hook: {type:"message_complete", partial:true}

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase is a **FastAPI + Next.js** stack with two UI layers: a legacy `legacy/web-ui` (v1) and a new `web-ui` (v2). The backend uses both `project_id`-based routing (legacy) and `workspace_path`-based routing (v2). WebSocket auth uses JWT via query param. The existing `/ws` endpoint handles project status updates (subscribe/broadcast), not interactive message exchange. The existing `POST /api/projects/{id}/chat` endpoint is wired to the Lead Agent only and returns complete responses (not streaming). The `DiscoveryPanel` component in `web-ui/src/components/prd/DiscoveryPanel.tsx` provides a reference for session-based chat UI patterns. The ticket defines 9 atomic sub-issues with a dependency graph: backend (#501–#503) must complete before frontend (#504–#509).

## Approach

The work is split into two parallel tracks — backend and frontend — following the 9 atomic sub-issues in the ticket. The backend (#501–#503) adds a new `InteractiveSession` entity with CRUD API, a dedicated WebSocket endpoint at `/ws/sessions/{id}/chat` for streaming agent chat, and a streaming Anthropic adapter that relays tokens in real-time. The frontend (#504–#509) adds the `useAgentChat` hook for WebSocket connection and message accumulation, three new components (`AgentChatPanel`, `AgentTerminal`, `SplitPane`), and two new pages (`/sessions`, `/sessions/[id]`). The implementation reuses existing patterns: WebSocket auth from `codeframe/ui/routers/websocket.py`, chat API structure from `codeframe/ui/routers/chat.py`, SSE streaming from `streaming_v2.py`, and UI patterns from `DiscoveryPanel.tsx`.

---

## Implementation Plan

### Phase 1 — Backend: DB Schema + CRUD API for Interactive Sessions (#501)

**New file:** `file:codeframe/ui/routers/sessions_v2.py`

1. **Define the `InteractiveSession` data model** in `file:codeframe/ui/routers/sessions_v2.py`. Fields:
   - `id` (UUID string, primary key)
   - `workspace_path` (string, from query param or request body)
   - `title` (string, optional)
   - `status` (`idle` | `running` | `interrupted` | `completed`)
   - `created_at`, `updated_at` (ISO timestamps)
   - `message_history` (JSON list of `{role, content, tool_calls?, thinking?, timestamp}`)
   - `token_count`, `cost_usd` (floats, updated incrementally)

2. **Create a `SessionStore` class** in `file:codeframe/core/session_store.py` that persists sessions as JSON files under `<workspace_state_dir>/sessions/`. Implement methods: `create()`, `get()`, `list()`, `update()`, `delete()`.

3. **Create REST endpoints** in `file:codeframe/ui/routers/sessions_v2.py`:
   - `POST /api/v2/sessions` — create a new session (body: `workspace_path`, optional `title`)
   - `GET /api/v2/sessions` — list sessions for a workspace (query: `workspace_path`)
   - `GET /api/v2/sessions/{session_id}` — get session detail including full message history
   - `DELETE /api/v2/sessions/{session_id}` — delete a session

4. **Add Pydantic response models** in `file:codeframe/ui/response_models.py`: `InteractiveSessionResponse`, `SessionListResponse`.

5. **Register the router** in `file:codeframe/ui/server.py` alongside the other v2 routers.

### Phase 2 — Backend: WebSocket Endpoint for Streaming Agent Chat (#502)

**New file:** `file:codeframe/ui/routers/session_chat_ws.py`

The new WebSocket endpoint lives at `/ws/sessions/{session_id}/chat` and is separate from the existing `/ws` (project status) endpoint.

1. **Create the router** with `@router.websocket("/ws/sessions/{session_id}/chat")`. Reuse JWT-from-query-param auth from `file:codeframe/ui/routers/websocket.py` (extract `token`, decode with `pyjwt`, verify user).

2. **Message protocol** (JSON over WebSocket):

   | Direction | Type | Payload |
   |---|---|---|
   | Client → Server | `user_message` | `{content: string}` |
   | Client → Server | `interrupt` | `{}` |
   | Client → Server | `ping` | `{}` |
   | Server → Client | `token` | `{delta: string}` |
   | Server → Client | `tool_call` | `{id, name, input}` |
   | Server → Client | `tool_result` | `{tool_call_id, output}` |
   | Server → Client | `thinking` | `{delta: string}` |
   | Server → Client | `message_complete` | `{role, content, token_count, cost_usd}` |
   | Server → Client | `error` | `{message: string}` |
   | Server → Client | `pong` | `{}` |

3. **Session state management**: On connect, load the session from `SessionStore`. Maintain an `asyncio.Event` for interrupt signaling. Keep a reference to the running streaming task so it can be cancelled on `interrupt`.

4. **Register the router** in `file:codeframe/ui/server.py`.

### Phase 3 — Backend: Streaming Chat Adapter for Anthropic SDK (#503)

**New file:** `file:codeframe/core/agent_chat_stream.py`

1. **Create `AgentChatStream` class** that wraps the `anthropic` SDK's streaming API (`anthropic.AsyncAnthropic().messages.stream()`). The `anthropic>=0.18.0` SDK already supports async streaming.

2. **`stream_response` async generator method**: accepts the session's `message_history` list and an `asyncio.Event interrupt_event`. Iterates over the SDK's streaming events and yields typed dicts matching the WebSocket protocol:
   - `RawContentBlockDeltaEvent` with `TextDelta` → yield `token`
   - `RawContentBlockDeltaEvent` with `InputJsonDelta` → yield `tool_call` input accumulation
   - `RawContentBlockStartEvent` with `ToolUseBlock` → yield `tool_call` start
   - Thinking blocks (extended thinking) → yield `thinking`
   - After stream completes → yield `message_complete` with usage stats

3. **Interrupt handling**: Check `interrupt_event.is_set()` at each yield point; if set, break the loop and close the stream context manager.

4. **Tool execution**: After a `tool_call` is yielded, the WebSocket handler executes the tool (via existing `codeframe/core/` tool infrastructure) and sends `tool_result` back to the client, then appends both to `message_history` before continuing.

5. **Persist after each complete turn**: call `SessionStore.update_session()` to save the updated `message_history`, `token_count`, and `cost_usd`.

### Phase 4 — Backend: Interrupt and Steering (part of #502)

This is handled within the WebSocket handler in `file:codeframe/ui/routers/session_chat_ws.py`:

1. **Concurrent receive loop**: Use `asyncio.create_task` to run a background task that reads incoming WebSocket messages while the streaming task runs. When an `interrupt` message arrives, set the `interrupt_event` and cancel the streaming task.

2. **Mid-session user messages**: When the agent is `idle` (no streaming task running), a `user_message` triggers a new streaming turn. When the agent is `running`, a `user_message` is queued and processed after the current turn completes (or after interrupt).

3. **Status broadcast**: After each state change (`idle` → `running` → `idle`), update the session's `status` field in `SessionStore`.

---

### Phase 5 — Frontend: Install Required Packages

Before writing any frontend code, add the missing dependencies to `file:web-ui/package.json`:
- `xterm` and `@xterm/addon-fit` (for the terminal component)
- `@xterm/addon-web-links` (optional, for clickable links in terminal)

No split-pane library is needed — implement it with CSS `flex` + a draggable divider (avoids adding a dependency).

---

### Phase 6 — Frontend: `useAgentChat` Hook (#504)

**New file:** `file:web-ui/src/hooks/useAgentChat.ts`

Model this after the existing `WebSocketClient` in `file:legacy/web-ui/src/lib/websocket.ts` but scoped to a single session.

1. **State managed by the hook**:
   - `messages: AgentMessage[]` — accumulated message list
   - `streamingContent: string` — current in-progress token stream
   - `status: 'idle' | 'connecting' | 'running' | 'error'`
   - `tokenCount: number`, `costUsd: number`

2. **`AgentMessage` type** (add to `file:web-ui/src/types/index.ts`):
   ```
   { id, role, content, toolCalls?, thinking?, tokenCount?, costUsd?, timestamp }
   ```

3. **WebSocket lifecycle**: Connect to `ws://localhost:8000/ws/sessions/{sessionId}/chat?token=...` on mount (read token from `localStorage` as in the legacy client). Reconnect with exponential backoff on disconnect.

4. **Incoming message handling**: Switch on `type` field — accumulate `token` deltas into `streamingContent`, flush to `messages` on `message_complete`, append `tool_call`/`tool_result`/`thinking` as structured entries.

5. **Exposed actions**: `sendMessage(content: string)`, `interrupt()`, both send JSON over the WebSocket.

6. **Cleanup**: Close WebSocket on unmount.

---

### Phase 7 — Frontend: `AgentChatPanel` Component (#505)

**New file:** `file:web-ui/src/components/sessions/AgentChatPanel.tsx`

1. **Props**: `{ messages: AgentMessage[], streamingContent: string, status, tokenCount, costUsd, onSendMessage, onInterrupt }`

2. **Message rendering** (reference: `file:web-ui/src/components/prd/DiscoveryPanel.tsx` and `DiscoveryTranscript.tsx`):
   - `role === 'user'` → right-aligned bubble (reuse Tailwind classes from existing components)
   - `role === 'assistant'` with plain text → left-aligned bubble, render with `react-markdown` (already in `web-ui/package.json`)
   - `tool_call` entries → collapsible card showing tool name + input JSON (use `<details>` element)
   - `tool_result` entries → collapsible card showing output JSON
   - `thinking` entries → distinct styling (e.g., italic, muted color, collapsible)
   - Streaming in-progress → show `streamingContent` with a blinking cursor

3. **Input bar** (reference: `DiscoveryInput.tsx`): `<textarea>` + Send button. Disable when `status === 'running'`. Show an **Interrupt** button when `status === 'running'`.

4. **Cost/token display**: Small footer showing `tokenCount` tokens · `$costUsd`.

5. **Auto-scroll**: `useEffect` to scroll to bottom on new messages.

---

### Phase 8 — Frontend: `AgentTerminal` Component (#506)

**New file:** `file:web-ui/src/components/sessions/AgentTerminal.tsx`

1. **Use xterm.js**: Import `Terminal` from `xterm` and `FitAddon` from `@xterm/addon-fit`. Initialize in a `useEffect` with a `useRef` for the container div.

2. **Connect to workspace**: The terminal connects to the workspace's shell via a separate WebSocket or PTY endpoint. Since no PTY backend exists yet, implement a **read-only log view** initially: subscribe to the existing SSE stream (`/api/v2/tasks/{task_id}/stream`) and write `OutputEvent` lines to the terminal. This avoids needing a new PTY backend for the first iteration.

3. **Fit on resize**: Use `FitAddon` and a `ResizeObserver` on the container div to call `fitAddon.fit()` when the pane is resized.

4. **Cleanup**: Dispose the terminal instance on unmount.

---

### Phase 9 — Frontend: `SplitPane` Layout Component (#507)

**New file:** `file:web-ui/src/components/sessions/SplitPane.tsx`

1. **Props**: `{ left: ReactNode, right: ReactNode, defaultSplit?: number }` where `defaultSplit` is a percentage (default `50`).

2. **Implementation**: Two `flex` children with a draggable divider `<div>`. On `mousedown` on the divider, attach `mousemove` and `mouseup` listeners to `document`. Calculate new split percentage from mouse position relative to container width.

3. **Persistence**: Save the split percentage to `localStorage` under a key like `codeframe:session-split` and restore on mount.

4. **Collapse**: Double-click the divider to collapse/restore the right pane (toggle between saved split and `100%`).

---

### Phase 10 — Frontend: `/sessions` List Page (#508)

**New file:** `file:web-ui/src/app/sessions/page.tsx`

1. **Data fetching**: Use `swr` to call `GET /api/v2/sessions?workspace_path=...` (read `workspacePath` from `localStorage` via `getSelectedWorkspacePath()`).

2. **Session list**: Render a table/card list of sessions showing title, status badge, created date, token count, cost. Each row links to `/sessions/[id]`.

3. **New session button**: `POST /api/v2/sessions` with the current `workspace_path`, then `router.push('/sessions/{newId}')`.

4. **Delete**: Confirm dialog (use existing `@radix-ui/react-alert-dialog`) then `DELETE /api/v2/sessions/{id}`.

5. **Add `sessionsApi`** to `file:web-ui/src/lib/api.ts` with `create`, `list`, `get`, `delete` methods.

6. **Add types** `InteractiveSession`, `SessionListResponse` to `file:web-ui/src/types/index.ts`.

---

### Phase 11 — Frontend: `/sessions/[id]` Detail Page (#509)

**New file:** `file:web-ui/src/app/sessions/[id]/page.tsx`

1. **Data fetching**: Fetch session detail via `sessionsApi.get(sessionId)` to load initial `message_history` and metadata.

2. **Wire hooks and components**:
   - Call `useAgentChat(sessionId)` to get live state and actions
   - Seed `messages` from the fetched session's `message_history` on first load
   - Render `<SplitPane left={<AgentChatPanel .../>} right={<AgentTerminal .../>} />`

3. **Page header**: Session title (editable inline), status badge, back link to `/sessions`.

---

### Phase 12 — Frontend: Sidebar Navigation Entry

**Modify:** `file:web-ui/src/components/layout/AppSidebar.tsx`

Add a new entry to the `NAV_ITEMS` array:
```
{ href: '/sessions', label: 'Sessions', icon: <suitable HugeIcons icon>, enabled: true }
```

Choose an appropriate icon from `@hugeicons/react` (e.g., `MessageMultiple01Icon` or `BubbleChatIcon`).

---

### Data Flow Diagram

```mermaid
sequenceDiagram
    participant UI as AgentChatPanel
    participant Hook as useAgentChat
    participant WS as /ws/sessions/{id}/chat
    participant Adapter as AgentChatStream
    participant SDK as Anthropic SDK
    participant Store as SessionStore

    UI->>Hook: sendMessage("fix the bug")
    Hook->>WS: {type:"user_message", content:"..."}
    WS->>Store: append user turn to history
    WS->>Adapter: stream_response(history, interrupt_event)
    Adapter->>SDK: messages.stream(...)
    loop token streaming
        SDK-->>Adapter: TextDelta / ToolUse / Thinking
        Adapter-->>WS: typed event dict
        WS-->>Hook: {type:"token", delta:"..."}
        Hook-->>UI: update streamingContent
    end
    SDK-->>Adapter: message_stop
    Adapter-->>WS: {type:"message_complete", ...}
    WS->>Store: persist updated history + usage
    WS-->>Hook: {type:"message_complete"}
    Hook-->>UI: flush to messages[], reset streamingContent

    UI->>Hook: interrupt()
    Hook->>WS: {type:"interrupt"}
    WS->>Adapter: interrupt_event.set()
    Adapter-->>WS: StopIteration
    WS-->>Hook: {type:"message_complete", partial:true}
```

---

Execution Information

Branch: main
Commit: cb074e3