- Fill empty apply-pr2.md with backend API + frontend client apply report
- Mark all 12 tasks as completed in tasks.md
- Update .openspec.yaml status from exploring to completed
The implementation was already merged to dev across PR 1, PR 2, and PR 3.
This commit only synchronizes the OpenSpec change metadata.
2026-06-12 14:41:12 +00:00
3 changed files with 91 additions and 13 deletions
# Apply Report: PR 2 – Backend API + Frontend Client for Multi-Session Terminal UX
## Summary
Implemented the session-scoped WebSocket route, REST endpoints for terminal session CRUD, and the frontend API client/hook. All changes are backward-compatible with the legacy single-session `/terminal` WebSocket endpoint and `POST .../terminal/reset` alias.
### Key Changes
1.**WebSocket Routing**– Added `/ws/tool-instances/{instance_id}/terminal/{session_id}` route and preserved `/ws/tool-instances/{instance_id}/terminal` as the default-session alias. Extracted a shared `_handle_terminal_websocket()` handler containing auth, validation, and the I/O loop.
2.**REST Endpoints**– Added the following endpoints under `/instances/{instance_id}/terminal`:
-`GET /sessions`– list sessions with live `has_websockets` flag
-`POST /sessions`– create a new session (409 when max 5 reached)
-`DELETE /sessions/{session_id}`– close a session
-`POST /sessions/{session_id}/reset`– reset a specific session
-`POST /sessions/{session_id}/rename`– rename a session
-`POST /reset`– legacy alias for resetting the default session
3.**Frontend API Client**– Created `apps/web/src/api/terminal.ts` with typed REST wrappers.
4.**Frontend Hook**– Created `apps/web/src/hooks/use-terminal-sessions.ts` for loading, creating, closing, resetting, and renaming sessions with optimistic UI updates.
5.**Tests**– Added `apps/api/tests/api/test_terminal_ws_multi.py` with auth-requirement coverage for every new endpoint and WebSocket route.
1.**Path simplification**– REST endpoints were mounted under `/instances/{instance_id}/terminal/...` rather than the originally proposed `/projects/{pid}/repositories/{rid}/instances/{iid}/terminal/...`. This keeps the API consistent with the existing terminal WebSocket path which only requires `instance_id`, and matches the frontend's routing model where the terminal page is reached directly by instance ID.
2.**Endpoint path prefix**– The terminal router is included at the application root; endpoints live at `/instances/{instance_id}/terminal/sessions` (no `/projects/...` nesting).
3.**Test scope**– The integration tests for PR 2 focus on auth/404 routing because fully exercising WebSocket multi-session I/O requires a running Docker container and authenticated cookie flow. Those deeper integration scenarios are covered in PR 1 unit tests (manager behavior) and can be added to PR 2 later if an async test client with cookie auth becomes practical.
## Blockers / Risks
- **Auth-only REST tests** – The new REST endpoints are only tested for auth gating in this PR. End-to-end CRUD behavior with real instances is exercised indirectly through the frontend and the manager unit tests from PR 1.
- **WebSocket restore path** – When a client connects to `/ws/.../terminal/{session_id}` for a session that is in the DB but not in memory (e.g. after API restart), the handler recreates the PTY from the DB row. This path is not yet covered by automated tests.
## Next Recommended Action
1.**Task 9–12 (Frontend UI + tests)**– Implement `TerminalSessionTabs`, update `TerminalPage` for multi-session orchestration, fullscreen, and keyboard shortcuts, and add frontend tests.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Developer