Files
kandev/docs/specs/cli/system-design/mobile-passthrough-composer.md
T
2026-09-05 10:26:55 +00:00

142 lines
6.9 KiB
Markdown

---
status: current
system: cli
requirements:
- REQ-CLI-MOBILE-PASSTHROUGH-COMPOSER-001
---
# Mobile Passthrough Composer System Design
## Purpose and boundaries
The CLI system owns the user-visible prompt path for sessions backed by a raw
agent PTY. The web application implements that path with an inline composer,
but it must keep passthrough submission distinct from raw terminal input. This
design uses the UI system's shared composer overlay contract and the Tasks
system's attachment contract without redefining either one.
The composer remains inline above the passthrough status row. A drawer would
introduce another focus, draft, and viewport owner without solving the measured
touch-target defect. The existing mobile task layout already constrains the
surface with `100dvh`, safe-area padding, and one flexible terminal region.
## Requirement mapping
| Requirement | Design sections |
| --- | --- |
| `REQ-CLI-MOBILE-PASSTHROUGH-COMPOSER-001` | [Components and responsibilities](#components-and-responsibilities), [Control flow](#control-flow), [Responsive behavior](#responsive-behavior), [Persistence](#persistence) |
## Components and responsibilities
- `PassthroughToolbar` owns the vertical terminal, optional composer, comments,
and passthrough status-row composition. It applies touch geometry to the
owned mobile and coarse-pointer tablet status controls, Chat, Comments,
Proceed, and Send to Agent, while preserving compact desktop controls.
- `PassthroughComposerPanel` configures the shared `ChatInputContainer` for a
passthrough session. It disables unadvertised agent commands and external
entity references while retaining context mentions, attachments, plan
context, and session-scoped draft behavior.
- `MobileChatInputToolbar` owns the mobile and coarse-pointer tablet
presentation of shared composer controls. Its context, attachment, plan,
cancel, send, and split Implement controls use a touch presentation with a
minimum 44-by-44 CSS-pixel target. Desktop toolbar geometry does not change.
- `PassthroughTerminal` remains the raw PTY surface and the only flexible child
in the toolbar. On mobile, it retains touch scrolling.
- The shared suggestion popup remains responsible for visual-viewport
containment, internal result scrolling, and touch selection.
The current defect comes from fixed `h-6` and `h-7` classes in the passthrough
status row and shared composer primitives. The mobile and tablet layouts reused
those desktop-sized controls without a touch presentation, which produced
measured 24-to-28 CSS-pixel targets.
## Data and contracts
No backend, WebSocket, or persisted data contract changes.
- Composer submission continues to use `message.add` with `task_id`,
`session_id`, a unique `client_message_id`, resolved content, optional
attachments, and optional context-file metadata.
- The backend remains responsible for converting that message into the active
passthrough agent's configured submit sequence. The browser must not send a
raw Enter key as a substitute for this request.
- `hasAgentCommands={false}` remains the passthrough capability declaration.
Literal `/` input is therefore intentional, not a missing mobile menu.
- The existing task attachment contract owns file materialization, retry,
removal, and error behavior.
## Control flow
1. The phone user opens Chat from the passthrough status row.
2. `PassthroughToolbar` renders the inline `PassthroughComposerPanel` and moves
focus into its TipTap editor.
3. The user enters text, selects contextual `@` results, or chooses attachments.
These actions update the session-scoped draft and do not submit it.
4. Explicit send resolves selected comments, context files, plans, task
mentions, and attachments into one `message.add` request.
5. After the request succeeds, the composer clears its sent state and closes.
On failure, it stays available with the draft and error feedback intact.
Escape closes the Kandev composer while it has focus. Raw Ctrl+C, Escape, Enter,
and other terminal keys remain xterm interactions and are not added to the
composer toolbar by this capability.
## Responsive behavior
Touch presentation is selected by the existing responsive breakpoint. The
mobile and coarse-pointer tablet branches use touch-sized controls; fine-pointer
desktop branches retain compact controls. The terminal stays `min-h-0` and
flexible; the composer and status row keep their intrinsic height. This
prevents the document from becoming a second scroll container when the composer
opens.
The shared composer actions and passthrough status-row actions owned by this
change use at least 44-by-44 CSS-pixel hit areas. This includes the composer
plan, attachment, context, cancel, send, and split Implement actions, plus the
passthrough Chat, Comments, Proceed, and Send to Agent actions. Visual glyphs
can remain smaller. Integration-owned status chips, including dependency and
PR/provider chips, keep their own component contracts. A horizontal action
strip can scroll internally when its controls exceed the available width, but
it must not cause document-level horizontal overflow.
The existing visual-viewport-aware suggestion popup remains attached above the
composer. The implementation does not replace it with a drawer.
## Failure and recovery
- If `message.add` fails, the composer keeps the unsent draft and exposes the
existing translated error. It must not clear or close as though the send
succeeded.
- If attachment upload fails, the existing attachment item remains retryable or
removable before send.
- If the Visual Viewport API is unavailable, the shared overlay falls back to
layout-viewport bounds.
- A passthrough session that has no advertised ACP commands continues to accept
literal slash text without showing an empty or misleading command menu.
## Persistence
TipTap JSON, selected context, and attachment state continue to use the
session-keyed chat draft store. Switching tasks selects another session key;
returning restores the original session's draft. This change adds no storage,
migration, or retention policy.
## Verification boundary
Focused component tests prove the mobile and desktop class contracts. The
mobile passthrough Playwright specification proves touch geometry, explicit
send, literal slash behavior, contextual suggestions, operating-system file
selection, session-scoped draft restoration, and lack of document overflow.
Automated mobile Chromium coverage is necessary but not sufficient to close the
issue. The final verification records a smoke test on iPhone Safari and Android
Chrome for focus, software-keyboard reachability, suggestion selection, file
selection, and send.
## Related specifications
- [CLI-mode task parity](../requirements/cli-mode-parity.md)
- [Composer suggestion overlays](../../ui/requirements/composer-suggestion-overlays.md)
- [Slash command composer selection](../../ui/requirements/slash-command-composer.md)
- [Task prompt attachments](../../tasks/requirements/prompt-attachments.md)