298 lines
18 KiB
Markdown
298 lines
18 KiB
Markdown
---
|
||
spec: docs/specs/ui/requirements/quick-terminal.md
|
||
created: 2026-08-03
|
||
updated: 2026-08-04
|
||
status: completed
|
||
---
|
||
|
||
# Implementation Plan: Quick Chat and Terminal Tabs
|
||
|
||
## Overview
|
||
|
||
The shipped Quick Terminal baseline already exposes the host PTY from desktop, tablet, and phone,
|
||
but it owns a separate provider/dialog and the backend permits only one host shell. This revision
|
||
keeps those launchers while moving terminal content into the existing workspace-scoped Quick Chat
|
||
tab surface. The backend first gains per-tab idempotent host-shell sessions, then the frontend
|
||
separates reusable PTY rendering from stop-on-dialog-close ownership, adds browser-local terminal
|
||
tab state, and replaces the Quick Chat plus action with a grouped creation menu.
|
||
|
||
Tasks 01–03 remain the completed record of the shipped baseline. Tasks 04–07 complete this
|
||
revision's backend, lifecycle, shared-tab, and viewport verification work.
|
||
|
||
## Backend
|
||
|
||
### Per-tab host-shell idempotency
|
||
|
||
- Extend the optional JSON body handled by
|
||
`apps/backend/internal/agent/loginpty/handlers.go:httpStartHostShell` with
|
||
`client_id: string`.
|
||
- Preserve the legacy singleton key when `client_id` is omitted so
|
||
**Settings → Agents** and older clients remain idempotent exactly as they are today.
|
||
- When `client_id` is present, derive a bounded internal session key from
|
||
`_host_shell` plus that client ID. Repeated starts for one client ID return the same running PTY;
|
||
distinct client IDs create independent PTYs.
|
||
- Keep the public `agent_id` in the returned `Status` equal to `_host_shell`. Add an internal
|
||
manager key/owner distinction rather than exposing the client id as an agent identity or passing
|
||
it to the discovery-cache exit callback.
|
||
- Require a present client ID to parse as a UUID and reject malformed values with
|
||
`400 Bad Request`; do not use a
|
||
client-provided value as a command, path, environment variable, or log field without bounding it.
|
||
- Leave the session-ID status, stream, resize, and stop routes unchanged. Stopping one per-tab
|
||
session must not remove another tab's session or an agent-login session.
|
||
|
||
### Manager lifecycle
|
||
|
||
- Extend `apps/backend/internal/agent/loginpty/manager.go` so uniqueness is keyed separately from
|
||
the stable logical `AgentID`. Existing `Manager.Start(agentID, ...)` callers retain one active
|
||
login PTY per agent.
|
||
- Store the internal key on `Session` for manager-map cleanup; continue indexing the public
|
||
session route by the generated session ID.
|
||
- Preserve the existing idle timeout, hard timeout, 16 KB rolling output buffer, subscriber
|
||
detach/reconnect behavior, and exit callback semantics.
|
||
|
||
## Frontend
|
||
|
||
### Host-shell client and reusable PTY view
|
||
|
||
- Extend `apps/web/lib/api/domains/settings-api.ts:startHostShell` with an optional
|
||
`clientId`/request field serialized as `client_id`. Agent-login start requests remain unchanged.
|
||
- Extract the xterm/resize/WebSocket portion of
|
||
`apps/web/components/settings/pty-terminal-dialog.tsx` into a reusable terminal view, likely
|
||
`apps/web/components/settings/pty-terminal-view.tsx`.
|
||
- Give the extracted view an explicit lifecycle contract:
|
||
- the default dialog mode starts a session and stops it on unmount, preserving every Agents/login
|
||
caller;
|
||
- the Quick Chat tab mode can start with a stable client ID or attach to a stored session ID,
|
||
reports start/exit/error changes to the tab store, and only closes its WebSocket/xterm on
|
||
unmount;
|
||
- explicit terminal-tab close remains the owner of the stop request.
|
||
- Preserve the StrictMode mount-generation guard. A pending start that resolves after its tab was
|
||
explicitly removed must be stopped; a view that merely detached because of a tab switch or dialog
|
||
dismissal must not stop it.
|
||
- Reattachment uses the existing status/stream routes and buffered output. A missing session is
|
||
reported as exited/unavailable and does not trigger an implicit replacement.
|
||
- Keep `PtyTerminalDialog` and `HostShellDialog` as wrappers for the Agents-page and login/auth
|
||
surfaces; remove only their use as the standalone Quick Terminal presentation.
|
||
|
||
### Shared workspace tab state
|
||
|
||
- Extend `apps/web/lib/state/slices/ui/types.ts` with a discriminated
|
||
`QuickTerminalTab` descriptor matching the spec: `tabId`, `workspaceId`, `sessionId`,
|
||
`sequence`, `status`, optional `exitCode`, and optional `error`.
|
||
- Keep backend-restored conversation sessions in `quickChat.sessions`. Add browser-local terminal
|
||
tabs and explicit active-kind/last-terminal state instead of widening
|
||
`QuickChatSessionKind = "chat" | "config"`; terminal tabs have no task/session-message contract.
|
||
- Add focused UI-slice actions for:
|
||
- reuse-or-create terminal launch for a workspace;
|
||
- always-new terminal creation from the add menu;
|
||
- terminal session/status updates;
|
||
- terminal activation;
|
||
- explicit terminal removal and adjacent same-workspace fallback, closing the modal only when no
|
||
conversation, setup, or terminal tab remains.
|
||
- Conversation activation preserves the existing `chat` versus `config` launcher filtering
|
||
without discarding the last active terminal. Terminal activation does not overwrite conversation
|
||
selection. This lets each launcher restore its own matching content.
|
||
- Generate the stable tab/client ID in the browser with `crypto.randomUUID()`. Assign terminal
|
||
sequence labels within a workspace without colliding with another open terminal.
|
||
- Update `apps/web/lib/state/slices/ui/quick-chat-sync.ts`,
|
||
`apps/web/lib/state/default-state.ts`, and
|
||
`apps/web/lib/state/hydration/hydrator.ts` only as needed to ensure boot/resync replacement of
|
||
server conversation sessions preserves local terminal descriptors and active-terminal state.
|
||
Terminal descriptors must never be sent to Quick Chat rename/delete/sync APIs.
|
||
|
||
### One Quick Chat dialog
|
||
|
||
- Update `apps/web/components/quick-chat/quick-chat-modal.tsx` to derive a shared active tab from
|
||
the conversation and terminal state. Render:
|
||
- `QuickChatSessionView`, `QuickChatSetup`, or `ConfigChatSetup` for conversation tabs;
|
||
- a new `apps/web/components/quick-chat/quick-terminal-tab-view.tsx` for terminal tabs.
|
||
- Generalize `QuickChatTabItem` or introduce a sibling tab item so terminal tabs show an accessible
|
||
terminal icon and fixed `Terminal N` label without entering chat rename/delete code.
|
||
- Terminal tab close calls the shared stop endpoint. Treat `404 session not found` as already
|
||
stopped; retain the tab and surface an error for other failures. Closing a chat tab continues to
|
||
use its confirmation dialog and backing-task deletion.
|
||
- Dismissing the modal removes abandoned chat setup placeholders as today but retains terminal
|
||
descriptors and sessions. Switching tabs only detaches the selected terminal view.
|
||
- Keep the current horizontal overflow owner for the tab strip and the current resizable
|
||
tablet/desktop and full-height phone dialog geometry. The terminal fills the content region below
|
||
the strip and does not render a nested `Dialog`, title, description, or Done footer.
|
||
|
||
### Grouped plus menu
|
||
|
||
- Replace the direct plus-button `onNewChat` handler with a Radix
|
||
`DropdownMenu` implemented in a focused component such as
|
||
`apps/web/components/quick-chat/quick-tab-add-menu.tsx`.
|
||
- Mirror the task-detail add-menu information hierarchy without importing task/Dockview state:
|
||
- **Agents** label and **New Agent**;
|
||
- separator;
|
||
- **Terminals** label and **New Terminal**.
|
||
- Keep existing conversation and terminal tabs selectable from the horizontal tab strip; the
|
||
creation menu does not duplicate those rows.
|
||
- Keep the plus trigger at least 44×44 px on phone. Reuse the existing global Radix menu mobile
|
||
treatment so the menu becomes a contained, safe-area-aware bottom sheet with 44 px rows on
|
||
coarse/narrow viewports.
|
||
|
||
### Launcher and provider ownership
|
||
|
||
- Change `apps/web/hooks/use-quick-terminal-launcher.ts` to accept the active workspace ID and
|
||
dispatch the reuse-or-create action into the shared tab store.
|
||
- Update the sidebar, tablet header, and phone header callers to pass their workspace ID. Keep their
|
||
current visibility, order, test IDs, accessible labels, and hitboxes.
|
||
- Extend `apps/web/components/quick-chat/quick-chat-provider.tsx` so workspace resolution considers
|
||
the active terminal as well as the active conversation and so one provider renders the only
|
||
shared dialog.
|
||
- Move launcher focus capture/restoration into the shared provider/launcher contract. Preserve the
|
||
pointer-only sidebar tooltip behavior after focus returns.
|
||
- Remove `QuickTerminalProvider` from `apps/web/src/app-shell.tsx` and
|
||
`apps/web/app/layout.tsx`; delete the provider component/test after its focus and lazy-loading
|
||
responsibilities are covered by the shared provider. Keep terminal code lazy enough that xterm
|
||
does not enter the initial application bundle before a terminal tab is rendered.
|
||
|
||
### Internationalization
|
||
|
||
- Add render-time translations for **Agents**, **Terminals**, **New Agent**, **New Terminal**,
|
||
`Terminal {{count}}`, terminal-tab accessible labels, and terminal lifecycle errors in the
|
||
appropriate English namespace.
|
||
- Do not translate tab IDs, backend session IDs, or enum discriminants. Use `count` for numbered or
|
||
plural copy and include the changed paths in the i18n ratchet check.
|
||
|
||
### Mobile design contract
|
||
|
||
- **Desktop outcome:** the sidebar terminal launcher opens the shared large Quick Chat dialog on the
|
||
last terminal or a first new terminal; the plus menu creates either content kind while the tab
|
||
strip switches between existing content.
|
||
- **Mobile entry point:** the existing 44 px Home/Tasks terminal and Quick Chat actions remain. The
|
||
terminal action selects terminal content inside the same full-height dialog as Quick Chat.
|
||
- **Nearest shipped exemplars:** `quick-chat-modal.tsx` owns the full-height phone/floating wider
|
||
surface and horizontal tab strip; `dockview-add-panel-items.tsx`,
|
||
`session-reopen-menu.tsx`, and `terminal-reopen-menu.tsx` supply the grouped menu hierarchy;
|
||
the global Radix menu treatment supplies the phone bottom sheet.
|
||
- **Hierarchy and primary action:** the fixed strip identifies the active tab; the selected chat or
|
||
terminal is the sole content focus. The plus control is the visible creation overflow and the
|
||
phone close control remains fixed.
|
||
- **Presentation rationale:** conversations and terminals are frequently revisited dense content,
|
||
so they share a full-height phone workspace rather than nesting another dialog or temporary
|
||
drawer. Only the short creation choice rises in the menu bottom sheet.
|
||
- **Geometry:** `100dvh` on phone, current bounded `85vh` floating geometry on wider viewports,
|
||
one selected-content scroll owner, safe-area clearance, a horizontally scrollable tab strip, and
|
||
no document horizontal overflow.
|
||
- **Shared logic:** terminal identity, lifecycle, workspace filtering, active selection, and API
|
||
behavior are shared across viewports; only launcher placement and existing responsive dialog/menu
|
||
presentation differ.
|
||
- **Mobile proof:** Pixel 5 coverage taps both launchers, opens the grouped menu, creates and switches
|
||
terminal tabs, verifies 44 px controls/menu rows, terminal containment, internal scrolling,
|
||
dismissal, focus return, and zero document horizontal overflow.
|
||
|
||
## Tests
|
||
|
||
- **What:** a host-shell client ID is idempotent for one tab while distinct IDs create independent
|
||
sessions and legacy starts remain singleton.
|
||
**Files:** `apps/backend/internal/agent/loginpty/manager_test.go` and a focused
|
||
`apps/backend/internal/agent/loginpty/handlers_test.go`.
|
||
**How:** table-driven manager and `httptest` handler tests cover same/different/missing/invalid
|
||
keys, independent stop, stable public agent ID, and unchanged agent-login uniqueness.
|
||
- **What:** standard PTY dialogs stop on unmount while Quick Chat terminal views detach, reattach,
|
||
and stop only after explicit tab close.
|
||
**Files:** new focused tests beside
|
||
`apps/web/components/settings/pty-terminal-view.tsx` and
|
||
`apps/web/components/quick-chat/quick-terminal-tab-view.tsx`.
|
||
**How:** mock xterm, WebSocket, ResizeObserver, and API calls; exercise StrictMode replay, pending
|
||
start removal, detached reattachment, exit, 404 stop, and sibling isolation.
|
||
- **What:** store actions implement reuse-or-create versus always-new behavior, per-workspace last
|
||
selection, deterministic close fallback, and server reconciliation that preserves terminal tabs.
|
||
**Files:** `apps/web/lib/state/slices/ui/quick-chat-actions.test.ts`,
|
||
`apps/web/lib/state/slices/ui/quick-chat-sync.test.ts`, and
|
||
`apps/web/lib/state/hydration/hydrator.test.ts`.
|
||
**How:** pure Zustand/helper tests with two workspaces, several chat kinds, several terminal IDs,
|
||
and empty server resync.
|
||
- **What:** the shared modal renders mixed tabs and a grouped creation menu, while both launcher
|
||
kinds select the intended last tab and restore focus; conversation tabs also expose context-menu
|
||
rename.
|
||
**Files:** `apps/web/components/quick-chat/quick-chat-modal.test.ts`, a new menu component test,
|
||
`apps/web/hooks/use-quick-chat-launcher.test.ts`, the replacement terminal-launcher/provider
|
||
tests, and existing sidebar/mobile-header component tests.
|
||
**How:** mocked store/API/component tests assert menu grouping, creation callbacks, context-menu
|
||
rename, accessible labels, workspace gating, focus restoration, and tooltip behavior.
|
||
|
||
## E2E Tests
|
||
|
||
- **Scenario:** first terminal launch creates one tab; dismissing and reopening via the sidebar
|
||
selects the same session and replays its marker output.
|
||
**File:** `apps/web/e2e/tests/terminal/quick-terminal.spec.ts`.
|
||
**What to verify:** shared Quick Chat dialog identity, one tab after reopen, same terminal marker,
|
||
no standalone Quick Terminal dialog/footer, focus return, and no stale tooltip.
|
||
- **Scenario:** the plus menu creates a second independent terminal and switches existing chats and
|
||
terminals without duplication.
|
||
**File:** `apps/web/e2e/tests/terminal/quick-terminal.spec.ts`.
|
||
**What to verify:** grouped labels/rows, distinct terminal labels and command output, terminal
|
||
shortcut reuse, Quick Chat shortcut selection, tab close stopping only one session, and fallback.
|
||
- **Scenario:** the low-level host-shell API supports same-key idempotency, different-key
|
||
concurrency, independent command streams, independent stop, and omitted-key compatibility.
|
||
**File:** `apps/web/e2e/tests/settings/host-shell-pty.spec.ts`.
|
||
**What to verify:** response/session identities and live WebSocket command markers for two PTYs.
|
||
- **Scenario:** phone users can open the shared surface, invoke the add menu as a touch-safe bottom
|
||
sheet, create/switch terminals, dismiss, and return to the launcher.
|
||
**File:** `apps/web/e2e/tests/terminal/mobile-quick-terminal.spec.ts`.
|
||
**What to verify:** 44 px controls/menu rows, dynamic-viewport containment, terminal height,
|
||
safe-area/internal scrolling, same-session reopen, and zero document horizontal overflow.
|
||
- Re-run the existing Quick Chat desktop/mobile happy paths affected by the shared dialog:
|
||
`apps/web/e2e/tests/chat/quick-chat.spec.ts` and the relevant
|
||
`apps/web/e2e/tests/chat/mobile-quick-chat-entry.spec.ts` scenarios.
|
||
|
||
## Verification Results
|
||
|
||
Completed. Tasks 04–06 record the backend, lifecycle, state, UI, typecheck, lint, and i18n
|
||
results. Task 07 records the final managed desktop run (20 passed) and Pixel 5 run (5 passed),
|
||
including backend/Vite rebuilds and worker teardown evidence.
|
||
|
||
## Implementation Waves And Parallel Candidates
|
||
|
||
Historical shipped baseline:
|
||
|
||
- [x] [Task 01: Build the shared Quick Terminal UI](task-01-quick-terminal-ui.md) (`done`)
|
||
- [x] [Task 02: Prove Quick Terminal across viewports](task-02-quick-terminal-e2e.md) (`done`)
|
||
- [x] [Task 03: Fix Quick Terminal startup race](task-03-fix-quick-terminal-startup-race.md) (`done`)
|
||
|
||
Revision wave 4:
|
||
|
||
- [x] [Task 04: Add per-tab host-shell sessions](task-04-per-tab-host-shell-sessions.md)
|
||
(`done`)
|
||
|
||
Revision wave 5:
|
||
|
||
- [x] [Task 05: Extract detachable PTY lifecycle](task-05-detachable-pty-lifecycle.md)
|
||
(`done`)
|
||
|
||
Revision wave 6:
|
||
|
||
- [x] [Task 06: Unify Quick Chat and terminal tabs](task-06-unified-quick-tabs.md)
|
||
(`done`)
|
||
|
||
Revision wave 7:
|
||
|
||
- [x] [Task 07: Prove shared tabs across viewports](task-07-shared-tabs-e2e.md)
|
||
(`done`)
|
||
|
||
Tasks 04–07 are sequential because each consumes the contract established by the preceding task and
|
||
the frontend tasks share PTY/dialog files. The task files are suitable handoff packets, but this
|
||
plan does not itself authorize subagent execution.
|
||
|
||
## Risks
|
||
|
||
- The login PTY manager enforces one login process per agent for credential safety. Per-tab host
|
||
shells must add a separate idempotency key without relaxing that invariant or changing the public
|
||
agent identity delivered to exit callbacks.
|
||
- A hidden terminal is intentionally alive without a subscriber. Its output is recoverable only
|
||
from the existing 16 KB rolling buffer, and it can expire under the existing 10-minute idle or
|
||
30-minute hard timeout.
|
||
- Start, detach, explicit close, StrictMode replay, and late async completion can race. Stable
|
||
client IDs plus explicit ownership tests are required to avoid leaked or accidentally stopped
|
||
sibling sessions.
|
||
- Backend Quick Chat hydration/resync is authoritative only for conversation sessions. A naive array
|
||
replacement can erase local terminal tabs or activate a tab from another workspace.
|
||
- xterm measures its mounted container. Reattachment and the selected-tab layout must fit only after
|
||
the content region has non-zero dimensions and must tolerate phone browser chrome and the
|
||
on-screen keyboard.
|
||
- Quick terminals execute with the backend host user's permissions. The shared dialog must not imply
|
||
task-worktree isolation or route terminal descriptors through conversation persistence APIs.
|