Frontend: AgentTerminal component — XTerm.js interactive terminal for session workspace

[frankbria]

Parent Issue

Part of #500

Context

Interactive sessions need a terminal view so users can inspect the workspace, run tests, or verify changes made by the agent. This component provides an XTerm.js-based terminal wired to a backend WebSocket endpoint that shells into the session's workspace directory.

Backend Prerequisite

A simple terminal WebSocket endpoint is needed:

WS /ws/sessions/{id}/terminal?token=<JWT>

This shells a bash process in the session's workspace_path. The backend work is small (~30 lines using asyncio.create_subprocess_exec + WebSocket relay). It can be done in this same issue or as a quick addition to the API built in #502.

What to Build

1. Backend terminal endpoint (small — add to codeframe/ui/routers/session_chat_ws.py)

@router.websocket("/ws/sessions/{session_id}/terminal")
async def session_terminal(websocket: WebSocket, session_id: str, ...):
    # Authenticate JWT
    # Load session, get workspace_path
    # Spawn bash in workspace_path via asyncio.create_subprocess_exec
    # Relay stdin↔stdout between WebSocket and subprocess
    # Handle resize events: {"type": "resize", "cols": 120, "rows": 40}
    # Clean up subprocess on disconnect

2. Frontend component: web-ui/src/components/sessions/AgentTerminal.tsx

Props:

interface AgentTerminalProps {
  sessionId: string;
  className?: string;
}

Implementation:

1. Install xterm and xterm-addon-fit (check if already in package.json; add if not)
2. Mount XTerm.js instance on a <div ref> on component mount
3. Connect WebSocket to /ws/sessions/{sessionId}/terminal?token=<JWT>
4. Relay terminal input (user keystrokes) → WS → subprocess stdin
5. Relay subprocess stdout → WS → terminal.write(data)
6. On window/container resize: fit addon → send { type: "resize", cols, rows } over WS
7. On WS disconnect: show reconnecting overlay, auto-retry (max 3 attempts)
8. On unmount: close WS and dispose XTerm instance

Styling:

• Dark background (#0a0a0c matching the app theme)
• Purple cursor (brand primary color)
• Monospace font (use existing JetBrains Mono CSS variable if available, or fallback to monospace)
• Fit to container with FitAddon — no fixed height
• Connection status overlay on disconnect: semi-transparent dark overlay with "Reconnecting..." message

Acceptance Criteria

• Terminal renders in the component container with correct dark theme
• Keystrokes are relayed to the backend subprocess in real-time
• Subprocess output appears in the terminal
• Terminal resizes correctly when container size changes
• Disconnect shows overlay; reconnects automatically
• XTerm instance is properly disposed on unmount (no memory leaks)
• Working ls, cat, git status in the session workspace

Notes

• If xterm is already installed, skip that step; check web-ui/package.json
• The terminal is the right pane of the SplitPane layout (see Frontend: AgentTerminal component — XTerm.js interactive terminal for session workspace #506)
• Keep initial scope simple: bash only, no custom shell or agent-piped input

[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

• xterm and xterm-addon-fit are not in file:web-ui/package.json — they must be added.
• The frontend uses Next.js 16 + React 19, Tailwind CSS, and axios for HTTP. No existing WebSocket hook exists; the SSE pattern in useEventSource.ts is the closest analogue.
• Auth uses JWT Bearer tokens validated in file:codeframe/auth/dependencies.py. The frontend currently stores workspace paths in localStorage (via file:web-ui/src/lib/workspace-storage.ts) but has no visible token-retrieval utility — the token must be read from wherever the auth system stores it (cookies via withCredentials: true on the axios client, or a localStorage key set at login).
• The backend router pattern is clear from file:codeframe/ui/routers/session.py and file:codeframe/ui/server.py. New routers are registered in file:codeframe/ui/server.py.
• No sessions/ component directory exists yet in web-ui/src/components/.
• The theme uses CSS variables (no JetBrains Mono variable; font is Nunito Sans). The dark background is hsl(220 9% 6%) (--background in .dark). No brand purple is defined — a sensible inline value (#a855f7) should be used for the cursor.

Approach

Build the two pieces in dependency order: backend WebSocket endpoint first (so the frontend has something to connect to), then the useTerminalSocket hook, and finally the AgentTerminal component. The backend follows the exact same JWT-auth pattern as get_current_user in file:codeframe/auth/dependencies.py. The frontend hook mirrors the structure of useEventSource.ts.

---

Implementation Steps

1. Add xterm packages to file:web-ui/package.json

Add xterm and xterm-addon-fit to the dependencies section. Run npm install (or the project's package manager) to update package-lock.json.

---

2. Backend — create file:codeframe/ui/routers/terminal_ws.py

Create a new router file with a single WebSocket endpoint:

WS /ws/sessions/{session_id}/terminal?token=<JWT>

Key implementation details:

• Router: APIRouter(prefix="", tags=["websocket"]).
• Auth: Accept the JWT via a token query parameter (WebSocket clients cannot send Authorization headers). Decode it using the same SECRET, JWT_ALGORITHM, and JWT_AUDIENCE constants imported from codeframe.auth.manager, and look up the user exactly as get_current_user does in file:codeframe/auth/dependencies.py. Close with code 4001 on auth failure.
• Session lookup: Query the database (via get_async_session_maker()) to retrieve the session record by session_id and verify the user owns it. Close with 4004 if not found or 4003 if unauthorized.
• Subprocess: Spawn bash in session.workspace_path using asyncio.create_subprocess_exec with stdin=PIPE, stdout=PIPE, stderr=STDOUT, and env inheriting the current environment plus TERM=xterm-256color.
• Relay loop: Run two concurrent asyncio.Tasks:
  • WS → stdin: await websocket.receive_text() → if the parsed JSON has type == "resize", call os.set_terminal_size (or send a SIGWINCH-equivalent via fcntl.ioctl on the pty fd); otherwise write raw bytes to process.stdin.
  • stdout → WS: await process.stdout.read(4096) → await websocket.send_bytes(data).
• Cleanup: On WebSocketDisconnect or any exception, cancel both tasks and call process.terminate() / process.wait().

Note on PTY: For full terminal emulation (arrow keys, colours, vim, etc.) a pseudo-terminal (pty) is needed. Use asyncio's loop.subprocess_exec with a custom asyncio.SubprocessProtocol backed by os.openpty(), or the ptyprocess library if already available in pyproject.toml. If neither is available, start with asyncio.create_subprocess_exec (pipes only) and note the limitation.

---

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

Import terminal_ws from codeframe.ui.routers and add:

app.include_router(terminal_ws.router)   # /ws/sessions/{id}/terminal

Also add terminal_ws to the exports in file:codeframe/ui/routers/__init__.py.

---

4. Frontend — create file:web-ui/src/hooks/useTerminalSocket.ts

A custom hook that manages the WebSocket lifecycle for the terminal. Model it after useEventSource.ts.

Interface:

Prop	Type	Purpose
url	string | null	Full WS URL; null disables
onData	(data: Uint8Array) => void	Called with raw bytes from server
maxRetries	number	Default 3
retryDelay	number	Default 1000 ms

Internals:

• Hold a useRef<WebSocket | null> for the socket instance.
• Track status: 'idle' | 'connecting' | 'open' | 'closed' | 'error' in state.
• On onmessage, call onData with new Uint8Array(event.data) (binary frames) or new TextEncoder().encode(event.data) (text frames).
• Expose a sendInput(data: string) callback that calls ws.send(data).
• Expose a sendResize(cols: number, rows: number) callback that sends JSON.stringify({ type: "resize", cols, rows }).
• Implement exponential-backoff reconnect (same logic as useEventSource.ts).
• On unmount, close the socket and cancel any pending retry timer.

Export from file:web-ui/src/hooks/index.ts.

---

5. Frontend — create file:web-ui/src/components/sessions/AgentTerminal.tsx

A 'use client' component.

Props:

interface AgentTerminalProps {
  sessionId: string;
  className?: string;
}

Structure:

<div className={cn("relative w-full h-full", className)}>
  <div ref={terminalRef} className="w-full h-full" />          {/* XTerm mounts here */}
  {status !== 'open' && <ReconnectingOverlay status={status} />}
</div>

Mount / teardown (useEffect):

1. Instantiate new Terminal({ ... }) with the theme options below and attach FitAddon.
2. Call terminal.open(terminalRef.current) and fitAddon.fit().
3. Build the WS URL: `${wsBase}/ws/sessions/${sessionId}/terminal?token=${getToken()}` where wsBase is derived from process.env.NEXT_PUBLIC_API_URL with http(s) replaced by ws(s).
4. Call useTerminalSocket with the URL and wire onData → terminal.write(data).
5. Wire terminal.onData → sendInput(data).
6. Set up a ResizeObserver on the container div; on resize call fitAddon.fit() then sendResize(terminal.cols, terminal.rows).
7. On unmount: disconnect the ResizeObserver, close the WS (via the hook's cleanup), and call terminal.dispose().

XTerm theme options:

Option	Value
background	#0a0a0c
cursor	#a855f7 (purple)
fontFamily	'monospace'
fontSize	14
convertEol	true

Token retrieval (getToken):

Since the axios client uses withCredentials: true (cookie-based auth), the JWT may be in an httpOnly cookie and not accessible from JS. Check how the auth login endpoint sets the token:

• If it's stored in localStorage (e.g. key "access_token"), read it directly.
• If it's a cookie, the backend WebSocket endpoint should accept the cookie instead of a query param — adjust the backend auth accordingly.

Create a small helper file:web-ui/src/lib/auth.ts with a getToken(): string | null function that encapsulates this retrieval.

ReconnectingOverlay (inline or separate):

A semi-transparent absolute inset-0 div with bg-black/60 and a centered "Reconnecting…" text + spinner. Show when status is 'connecting' or 'error'.

---

6. Export the component

Create file:web-ui/src/components/sessions/index.ts (or add to an existing barrel) exporting AgentTerminal.

---

Data Flow

sequenceDiagram
    participant User
    participant AgentTerminal
    participant useTerminalSocket
    participant Backend WS
    participant bash

    User->>AgentTerminal: keystroke
    AgentTerminal->>useTerminalSocket: sendInput(data)
    useTerminalSocket->>Backend WS: ws.send(data)
    Backend WS->>bash: stdin.write(data)
    bash->>Backend WS: stdout bytes
    Backend WS->>useTerminalSocket: ws.send_bytes(data)
    useTerminalSocket->>AgentTerminal: onData(bytes)
    AgentTerminal->>User: terminal.write(bytes)

    User->>AgentTerminal: resize container
    AgentTerminal->>AgentTerminal: fitAddon.fit()
    AgentTerminal->>useTerminalSocket: sendResize(cols, rows)
    useTerminalSocket->>Backend WS: {"type":"resize","cols":…,"rows":…}
    Backend WS->>bash: ioctl TIOCSWINSZ

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

- `xterm` and `xterm-addon-fit` are **not** in `file:web-ui/package.json` — they must be added.
- The frontend uses Next.js 16 + React 19, Tailwind CSS, and `axios` for HTTP. No existing WebSocket hook exists; the SSE pattern in `useEventSource.ts` is the closest analogue.
- Auth uses JWT Bearer tokens validated in `file:codeframe/auth/dependencies.py`. The frontend currently stores workspace paths in `localStorage` (via `file:web-ui/src/lib/workspace-storage.ts`) but has no visible token-retrieval utility — the token must be read from wherever the auth system stores it (cookies via `withCredentials: true` on the axios client, or a `localStorage` key set at login).
- The backend router pattern is clear from `file:codeframe/ui/routers/session.py` and `file:codeframe/ui/server.py`. New routers are registered in `file:codeframe/ui/server.py`.
- No `sessions/` component directory exists yet in `web-ui/src/components/`.
- The theme uses CSS variables (no JetBrains Mono variable; font is Nunito Sans). The dark background is `hsl(220 9% 6%)` (`--background` in `.dark`). No brand purple is defined — a sensible inline value (`#a855f7`) should be used for the cursor.

## Approach

Build the two pieces in dependency order: backend WebSocket endpoint first (so the frontend has something to connect to), then the `useTerminalSocket` hook, and finally the `AgentTerminal` component. The backend follows the exact same JWT-auth pattern as `get_current_user` in `file:codeframe/auth/dependencies.py`. The frontend hook mirrors the structure of `useEventSource.ts`.

---

## Implementation Steps

### 1. Add `xterm` packages to `file:web-ui/package.json`

Add `xterm` and `xterm-addon-fit` to the `dependencies` section. Run `npm install` (or the project's package manager) to update `package-lock.json`.

---

### 2. Backend — create `file:codeframe/ui/routers/terminal_ws.py`

Create a new router file with a single WebSocket endpoint:

```
WS /ws/sessions/{session_id}/terminal?token=<JWT>
```

Key implementation details:

- **Router**: `APIRouter(prefix="", tags=["websocket"])`.
- **Auth**: Accept the JWT via a `token` query parameter (WebSocket clients cannot send `Authorization` headers). Decode it using the same `SECRET`, `JWT_ALGORITHM`, and `JWT_AUDIENCE` constants imported from `codeframe.auth.manager`, and look up the user exactly as `get_current_user` does in `file:codeframe/auth/dependencies.py`. Close with code `4001` on auth failure.
- **Session lookup**: Query the database (via `get_async_session_maker()`) to retrieve the session record by `session_id` and verify the user owns it. Close with `4004` if not found or `4003` if unauthorized.
- **Subprocess**: Spawn `bash` in `session.workspace_path` using `asyncio.create_subprocess_exec` with `stdin=PIPE`, `stdout=PIPE`, `stderr=STDOUT`, and `env` inheriting the current environment plus `TERM=xterm-256color`.
- **Relay loop**: Run two concurrent `asyncio.Task`s:
  - *WS → stdin*: `await websocket.receive_text()` → if the parsed JSON has `type == "resize"`, call `os.set_terminal_size` (or send a `SIGWINCH`-equivalent via `fcntl.ioctl` on the pty fd); otherwise write raw bytes to `process.stdin`.
  - *stdout → WS*: `await process.stdout.read(4096)` → `await websocket.send_bytes(data)`.
- **Cleanup**: On `WebSocketDisconnect` or any exception, cancel both tasks and call `process.terminate()` / `process.wait()`.

> **Note on PTY**: For full terminal emulation (arrow keys, colours, `vim`, etc.) a pseudo-terminal (`pty`) is needed. Use `asyncio`'s `loop.subprocess_exec` with a custom `asyncio.SubprocessProtocol` backed by `os.openpty()`, or the `ptyprocess` library if already available in `pyproject.toml`. If neither is available, start with `asyncio.create_subprocess_exec` (pipes only) and note the limitation.

---

### 3. Register the new router in `file:codeframe/ui/server.py`

Import `terminal_ws` from `codeframe.ui.routers` and add:

```python
app.include_router(terminal_ws.router)   # /ws/sessions/{id}/terminal
```

Also add `terminal_ws` to the exports in `file:codeframe/ui/routers/__init__.py`.

---

### 4. Frontend — create `file:web-ui/src/hooks/useTerminalSocket.ts`

A custom hook that manages the WebSocket lifecycle for the terminal. Model it after `useEventSource.ts`.

**Interface:**

| Prop | Type | Purpose |
|---|---|---|
| `url` | `string \| null` | Full WS URL; `null` disables |
| `onData` | `(data: Uint8Array) => void` | Called with raw bytes from server |
| `maxRetries` | `number` | Default 3 |
| `retryDelay` | `number` | Default 1000 ms |

**Internals:**

- Hold a `useRef<WebSocket | null>` for the socket instance.
- Track `status: 'idle' | 'connecting' | 'open' | 'closed' | 'error'` in state.
- On `onmessage`, call `onData` with `new Uint8Array(event.data)` (binary frames) or `new TextEncoder().encode(event.data)` (text frames).
- Expose a `sendInput(data: string)` callback that calls `ws.send(data)`.
- Expose a `sendResize(cols: number, rows: number)` callback that sends `JSON.stringify({ type: "resize", cols, rows })`.
- Implement exponential-backoff reconnect (same logic as `useEventSource.ts`).
- On unmount, close the socket and cancel any pending retry timer.

Export from `file:web-ui/src/hooks/index.ts`.

---

### 5. Frontend — create `file:web-ui/src/components/sessions/AgentTerminal.tsx`

A `'use client'` component.

**Props:**

```ts
interface AgentTerminalProps {
  sessionId: string;
  className?: string;
}
```

**Structure:**

```
<div className={cn("relative w-full h-full", className)}>
  <div ref={terminalRef} className="w-full h-full" />          {/* XTerm mounts here */}
  {status !== 'open' && <ReconnectingOverlay status={status} />}
</div>
```

**Mount / teardown (`useEffect`):**

1. Instantiate `new Terminal({ ... })` with the theme options below and attach `FitAddon`.
2. Call `terminal.open(terminalRef.current)` and `fitAddon.fit()`.
3. Build the WS URL: `` `${wsBase}/ws/sessions/${sessionId}/terminal?token=${getToken()}` `` where `wsBase` is derived from `process.env.NEXT_PUBLIC_API_URL` with `http(s)` replaced by `ws(s)`.
4. Call `useTerminalSocket` with the URL and wire `onData` → `terminal.write(data)`.
5. Wire `terminal.onData` → `sendInput(data)`.
6. Set up a `ResizeObserver` on the container div; on resize call `fitAddon.fit()` then `sendResize(terminal.cols, terminal.rows)`.
7. On unmount: disconnect the `ResizeObserver`, close the WS (via the hook's cleanup), and call `terminal.dispose()`.

**XTerm theme options:**

| Option | Value |
|---|---|
| `background` | `#0a0a0c` |
| `cursor` | `#a855f7` (purple) |
| `fontFamily` | `'monospace'` |
| `fontSize` | `14` |
| `convertEol` | `true` |

**Token retrieval (`getToken`):**

Since the axios client uses `withCredentials: true` (cookie-based auth), the JWT may be in an `httpOnly` cookie and not accessible from JS. Check how the auth login endpoint sets the token:
- If it's stored in `localStorage` (e.g. key `"access_token"`), read it directly.
- If it's a cookie, the backend WebSocket endpoint should accept the cookie instead of a query param — adjust the backend auth accordingly.

Create a small helper `file:web-ui/src/lib/auth.ts` with a `getToken(): string | null` function that encapsulates this retrieval.

**`ReconnectingOverlay` (inline or separate):**

A semi-transparent `absolute inset-0` div with `bg-black/60` and a centered "Reconnecting…" text + spinner. Show when `status` is `'connecting'` or `'error'`.

---

### 6. Export the component

Create `file:web-ui/src/components/sessions/index.ts` (or add to an existing barrel) exporting `AgentTerminal`.

---

## Data Flow

```mermaid
sequenceDiagram
    participant User
    participant AgentTerminal
    participant useTerminalSocket
    participant Backend WS
    participant bash

    User->>AgentTerminal: keystroke
    AgentTerminal->>useTerminalSocket: sendInput(data)
    useTerminalSocket->>Backend WS: ws.send(data)
    Backend WS->>bash: stdin.write(data)
    bash->>Backend WS: stdout bytes
    Backend WS->>useTerminalSocket: ws.send_bytes(data)
    useTerminalSocket->>AgentTerminal: onData(bytes)
    AgentTerminal->>User: terminal.write(bytes)

    User->>AgentTerminal: resize container
    AgentTerminal->>AgentTerminal: fitAddon.fit()
    AgentTerminal->>useTerminalSocket: sendResize(cols, rows)
    useTerminalSocket->>Backend WS: {"type":"resize","cols":…,"rows":…}
    Backend WS->>bash: ioctl TIOCSWINSZ
```

---

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.