feat: add Dispatch agents with streamed chat and background processes

[niiyeboah]

Summary

Adds an opt-in Dispatch agent that runs Claude Code, Codex, or OpenCode and streams its work into the existing Chat feed. Enable Dispatch agent (beta) in Settings, then choose the provider and model when creating a session. Each provider uses its CLI installation and existing login on the server.

User experience

• Each turn shows the prompt, collapsible tool activity, output and diffs, and the result. Reviews, pins, peer messages, and presence appear in the same feed. Review cards remain fully visible in compact peer rows.
• A task list above the composer shows current work and completion progress. Every Dispatch agent can maintain it through dispatch_update_tasks, including Claude Code sessions without a native todo tool. Native ACP plans also work; no goal workflow is required.
• Queued messages support Send now and Remove. Stop and Ctrl+C interrupt the active turn. The slash menu shows provider commands, and the model picker supports the options the provider exposes.
• New Dispatch sessions show an animated startup card in Chat with plain-language stages and estimated progress through workspace setup, dependency installation, provider connection, and session settings. Progress advances only on observed stage changes, never completes on a timer, and respects reduced motion. The composer stays disabled until startup finishes; failures show the existing error/sign-in guidance. The Terminal segment remains available for provider login and diagnostics.
• /usage separates context usage, subscription limits, and reported API cost. Reports show their observation time. Claude attempts to refresh subscription usage through the CLI's existing credentials and retains the last report on failure. Codex selects reports by event timestamp, not log modification time. Monthly cost budgets are configurable for providers that report cost.
• A service restart marks the active turn interrupted, resumes the provider session when supported, and redelivers queued messages. When a provider cannot resume, Dispatch preserves the chat history and explains that the provider session restarted.

Implementation and limits

• Providers communicate over Agent Client Protocol (ACP). Model prefixes select the adapter: claude/, codex/, gemini/, or opencode/.
• The backend records stream events and serializes prompts and task updates per agent. Schema changes add agent_stream_events and agent_chat_messages.delivery_text; both migrations are additive and guarded.
• Capabilities vary by provider: Claude supports nested subagent activity; Codex reports tokens without cost; Gemini sets its model at launch and reports no ACP usage. Provider-plan data can be unavailable or stale; the UI says when it was last reported instead of presenting a refresh time as a new observation.
• Claude's direct subscription refresh requires the CLI's file-backed OAuth credential. Other credential storage falls back to the local Claude /usage report. Dispatch does not save or expose provider credentials.
• Launch guidance also asks CLI agents to continue into accepted work, and persona reviews default to their parent's agent type and provider.

Background processes

• New session-scoped dispatch_background_process tool starts non-interactive shell commands without blocking a turn; completion automatically queues an agent message. Supports list, inspect, and stop.
• Background processes and tasks share compact headers, typography, padding, and row styles. A single right-aligned chevron expands the process list; running work appears first in a four-row preview, with Show more/fewer for history. Open a row for command, working directory, elapsed time, live output, exit status, and Stop. Touch targets remain accessible on mobile.
• Status and bounded output persist across page reloads. Session stop terminates process groups; server restart marks unfinished records interrupted rather than restarting commands. An additive agent_background_processes table stores the records.
• Limits: four concurrent processes per session, 16 server-wide, one-hour default timeout (up to 24 hours), and the latest 20 records plus running processes. Agent guidance asks for sequential heavy validation.
• This is not an interactive terminal and does not retroactively adopt provider-native shell processes. It tracks commands launched through the Dispatch tool.

Long-chat rendering

• Window chat histories and top-level tool activity rails once they exceed 80 rows, using measured variable heights and a six-row buffer on each side.
• Preserve older-history anchors, agent-switch reading positions, and activity disclosure state. Keep focused rows mounted.
• This reduces mounted React/DOM work; it does not discard loaded query data or individually virtualize one large markdown/code result or nested subagent details. Browser Find and selection cover mounted content.
• Stress tests pass with 5,000 messages (~11 mounted in the checked viewport) and a 1,000-step active turn (~17 mounted). They cover older-page anchors, agent-switch restoration, incoming messages while reading history, jump-to-latest, tool output, and mobile resizing.

Gemini follow-up

Gemini CLI support remains implemented, but Gemini is temporarily hidden from UI provider/model choices and Settings copy. Existing sessions and backend support are retained. Before re-enabling it:

• Define and validate an in-app/in-chat sign-in flow, including actionable access-denied and account-entitlement errors.
• Clearly distinguish API-key billing from signed-in account/subscription access and show the active authentication source.
• Review account eligibility and organizational access with management; management confirmation is still outstanding.

Validation

• Type checking, production web finalization, formatting, and changed-file web lint checks pass.
• Prior full unit baseline: 3,586 server tests, 2,143 web tests, 60 browser-extension tests, and four extension-manifest checks. The compact-list update additionally passes all 81 focused web tests. Startup coverage includes stage reporting, slow-stage estimates, opening-prompt delivery, error handling, and composer readiness.
• The background-process suite covers cancellation during startup, timeout, ownership, bounded output, and shutdown.
• Full non-live E2E run: 207 passed, 21 expected live-runtime skips, no failures or retries needed. Includes compact task/process styling, keyboard disclosure, Show more/fewer, mobile output/Stop controls and focus restoration, the startup flow, and both long-history stress tests.
• A separate live-runtime test with the fake Claude ACP adapter starts two background commands, inspects output, stops one, verifies persistence after reload, and checks the completion notification queue.
• Playwright interactions and shared screenshots cover the background process list/detail on desktop and mobile and Gemini's absence from the provider picker. Browsers were closed.
• Startup Playwright coverage exercises setup, connection, configuration, sign-in failure, retry, and readiness. Production-built desktop/mobile screenshots verify the startup card, reduced motion, and composer handoff; browsers are closed.
• Earlier cleanup validation also covered live task updates, full review cards, task-list expansion, dated usage fallback, and real Claude/Codex provider usage reads.

Setup and operational details: docs/10-operations-runbook.md.