3.9 KiB
3.9 KiB
id, title, status, wave, depends_on, plan, spec
| id | title | status | wave | depends_on | plan | spec | |
|---|---|---|---|---|---|---|---|
| 04-per-tab-host-shell-sessions | Add per-tab host-shell sessions | done | 4 |
|
plan.md | ../../specs/ui/requirements/quick-terminal.md |
Task 04: Add per-tab host-shell sessions
Acceptance
POST /api/v1/host-shell/startaccepts an optional UUIDclient_id: the same value is idempotent, different values create independent running PTYs, an omitted value retains the legacy singleton behavior, and malformed values return400 Bad Request.- The manager separates its internal uniqueness key from the public
AgentID, preserving one login PTY per agent,agent_id: "_host_shell"responses, exit callbacks, and independent stop/cleanup for each host terminal. - Focused manager and handler tests cover same/different/missing/invalid client IDs, concurrent command sessions, and stopping one session without affecting its sibling.
Verification
From the repository worktree:
cd apps/backend && go test ./internal/agent/loginpty
Files likely touched
apps/backend/internal/agent/loginpty/handlers.goapps/backend/internal/agent/loginpty/handlers_test.goapps/backend/internal/agent/loginpty/manager.goapps/backend/internal/agent/loginpty/manager_test.godocs/plans/quick-terminal/plan.md(status/results only)docs/plans/quick-terminal/task-04-per-tab-host-shell-sessions.md(status/results only)
Dependencies
- Task 03 is the shipped PTY lifecycle baseline. Preserve its output-drain, StrictMode-facing idempotency, timeout, and cleanup behavior.
Parallelism
Sequential. Task 05 consumes the exact request and ownership contract established here.
Inputs
- Spec:
API surface,State machine,Failure modes, andPersistence guarantees. - Plan:
Per-tab host-shell idempotency,Manager lifecycle, backend tests, and backend risks. - Existing patterns:
apps/backend/internal/agent/loginpty/handlers.go:httpStartHostShell,Manager.Start,Manager.supervise, and the existing manager tests.
Implementation notes
- Follow TDD: first add failing tests for two client IDs and the unchanged omitted-ID path.
- Keep client IDs as bounded opaque map keys. They must never alter the shell command, environment, filesystem path, public agent identity, or discovery-cache callback identity.
- Avoid weakening the one-session-per-agent invariant used by login/auth terminals.
- Ensure every test stops its PTYs and leaves no goroutine or process behind.
Risks
- Deleting manager state by public
AgentIDwould remove the wrong host terminal once several sessions share_host_shell; cleanup must use the internal key. - A handler-only idempotency map can drift from manager cleanup. Keep uniqueness ownership in the manager so timeout, natural exit, and explicit stop follow one removal path.
Output contract
Report the contract implemented, files changed, exact test count/result, process cleanup evidence,
blockers, residual risks, and synchronized task/plan status. Set this task to in_progress before
production or test changes and replace ## Results before marking it done.
Results
- Implemented manager uniqueness keys separate from the stable public
AgentID, including per-key cleanup and preservedManager.Start/agent-login semantics. - Added UUID validation and per-client host-shell keys while retaining the omitted-client singleton.
- Added manager and
httptesthandler coverage for idempotency, sibling isolation, public identity, invalid IDs, and legacy behavior. cd apps/backend && go test ./internal/agent/loginpty -count=1— 8 passed.cd apps/backend && go test -race ./internal/agent/loginpty -count=1— 8 passed.- Every PTY started by the tests is stopped through cleanup; the manager cleanup assertions wait for the first session to leave the manager while confirming its sibling remains running.