Files
kandev/docs/plans/quick-terminal/plan.md
T
2026-08-24 11:09:03 +00:00

298 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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.