@codeam/shared 2.54.0

package/dist/index.d.ts

@@ -0,0 +1,1117 @@
+/**
+ * Protocol-level types for TUI chrome steps and interactive selectors.
+ *
+ * Agent-AGNOSTIC: the *shapes* below are part of the chunk-protocol contract
+ * between the CLI/IDE clients and the mobile app. The *parsers* that recognize
+ * chrome lines and selectors live next to each agent's runtime strategy
+ * (e.g. apps/cli/src/agents/claude/parsing.ts) because the glyphs and
+ * conventions vary per agent.
+ */
+type ChromeToolType = 'read' | 'edit' | 'bash' | 'search' | 'thinking' | 'other';
+interface ChromeStep {
+    tool: ChromeToolType;
+    label: string;
+    detail?: string;
+    status: 'running' | 'done';
+}
+interface SelectPrompt {
+    question: string;
+    options: string[];
+    optionDescriptions: string[];
+    /** 0-based index of the highlighted item (always 0 for numbered selectors). */
+    currentIndex: number;
+}
+
+/**
+ * Shared wire / lifecycle constants. The values here are bundled
+ * into the CLI + VS Code extension at build time via tsup / esbuild
+ * and mirrored in `apps/jetbrains-plugin/.../protocol/Constants.kt`
+ * since Kotlin can't import an npm package.
+ *
+ * If you change one of these values, also update the Kotlin mirror.
+ */
+/**
+ * Discriminated chunk-protocol version sent as the
+ * `X-Codeam-Protocol-Version` header on every authed request. The
+ * backend uses this to opt into legacy translations or to reject
+ * with 426 when the client is too far behind. Bumped in lockstep
+ * with chunk-shape changes (e.g. when the `chrome_steps` chunk
+ * type is added).
+ */
+declare const PROTOCOL_VERSION: "2.0.0";
+/**
+ * The VS Code AgentOutputMonitor's loopback HTTP server bound to
+ * 127.0.0.1 on this port — the observer JS in the IDE renderer
+ * uses it to round-trip captured chat content back into the
+ * extension host. The port is intentionally fixed (rather than
+ * `listen(0)`) so the observer script can be a static constant
+ * rather than dynamically rewriting itself per session.
+ *
+ * Multi-window collision is solved by listen(0) per-window in the
+ * monitor (see #103); this default is still the documented
+ * starting port for tooling that needs to probe whether a CodeAgent
+ * Mobile session is active locally.
+ */
+declare const OBSERVER_BRIDGE_PORT = 47832;
+/**
+ * Default plugin → backend heartbeat interval. User-configurable
+ * via `codeagent-mobile.heartbeatIntervalMs` on VS Code and
+ * `heartbeatIntervalMs` in SettingsService.kt's @State on JetBrains.
+ * Mirrors the value the apps/api side uses to flip the paired
+ * session to offline.
+ */
+declare const HEARTBEAT_INTERVAL_MS_DEFAULT = 30000;
+/**
+ * SSE + polling reconnect cap. Vercel's serverless functions close
+ * SSE connections after ~25 s by default; the client uses 35 s as
+ * its overall socket timeout to leave a beat for graceful close.
+ */
+declare const SSE_SOCKET_TIMEOUT_MS = 35000;
+
+/**
+ * Render raw PTY bytes into an array of screen lines using a simplified
+ * virtual terminal. Handles cursor movements (A/B/C/D/G/H), erase (J/K),
+ * alternate-screen (?1049h), carriage return, and LF.
+ *
+ * This is the authoritative implementation used by both codeam-cli (PTY
+ * output) and the VS Code extension (shell-integration output) so that
+ * the mobile/web client sees identical chunks regardless of surface.
+ */
+declare function renderToLines(raw: string): string[];
+
+/**
+ * The command envelope clients receive from the backend relay — both from
+ * the `commands` SSE frames on `/api/commands/pending/stream` and from the
+ * `GET /api/commands/pending` polling fallback. One schema, shared, so the
+ * VS Code extension (and eventually the CLI) stop blind-casting
+ * `Record<string, unknown>` into this shape.
+ */
+interface RemoteCommand {
+    id: string;
+    sessionId: string;
+    pluginId: string;
+    type: string;
+    payload: Record<string, unknown>;
+    status: string;
+    createdAt: number;
+}
+/**
+ * Validate a raw (already JSON-parsed) value into a `RemoteCommand`.
+ * Returns `null` — never throws — on a malformed envelope so callers can
+ * log-and-skip the single bad command without dropping the whole batch.
+ */
+declare function toRemoteCommand(raw: unknown): RemoteCommand | null;
+
+interface ModelPricing {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+declare const MODEL_PRICING: Record<string, ModelPricing>;
+declare const MODEL_CONTEXT_WINDOW: Record<string, number>;
+/** True when the model id resolves to a real MODEL_PRICING row (i.e. getPricing
+ *  will NOT be guessing via the unknown-model fallback). */
+declare function isKnownModel(model: string): boolean;
+/**
+ * Resolve pricing by longest matching prefix. Unknown models fall back to
+ * claude-sonnet-4 rates — a guess, kept because existing callers do
+ * unconditional arithmetic on the result. Callers that need to distinguish
+ * real pricing from the fallback must check `isKnownModel(model)` first.
+ */
+declare function getPricing(model: string): ModelPricing;
+declare function getContextWindow(model: string | null): number;
+
+type AgentId = 'claude' | 'codex' | 'copilot' | 'coderabbit' | 'cursor' | 'aider' | 'gemini';
+type AgentAuthKind = 'oauth_token' | 'api_key' | 'setup_token';
+/**
+ * The agent kinds Headroom (the token-compression proxy) can actually
+ * wrap/route — the exact subcommands `headroom init --global <kind>`
+ * accepts. NOT an alias of {@link AgentId}: cursor / gemini / aider run
+ * native (Headroom disabled) because `headroom init` has no recipe that
+ * routes them.
+ */
+type HeadroomKind = 'claude' | 'codex' | 'copilot';
+interface AgentAuth {
+    kind: AgentAuthKind;
+    /** API key plain, or JSON serialized for oauth_token. Interpretation depends on the agent. */
+    value: string;
+}
+interface AgentModel {
+    id: string;
+    label: string;
+    contextWindow: number;
+    pricing?: {
+        inputPerM: number;
+        outputPerM: number;
+        cacheReadPerM?: number;
+        cacheCreationPerM?: number;
+    };
+}
+interface NormalizedMessage {
+    id: string;
+    role: 'user' | 'agent' | 'system';
+    text: string;
+    timestamp: string;
+    modelId?: string;
+    usage?: {
+        input: number;
+        output: number;
+        cacheRead?: number;
+        cacheCreation?: number;
+    };
+}
+interface AgentMetadata {
+    id: AgentId;
+    displayName: string;
+    binaryName: string;
+    enabled: boolean;
+    supportedAuthKinds: AgentAuthKind[];
+    preferredAuthKind: AgentAuthKind;
+    /**
+     * Whether Headroom can wrap/route this agent (claude / codex / copilot
+     * only). Canonical truth previously scattered across two prefix-matching
+     * predicates: `isHeadroomSupportedAgent` (CLI `host-agent.ts`) and
+     * `isHeadroomWrappableAgent` (api-v2 `codespaces/headroom.ts`). When
+     * false the agent MUST run native — wrapping an unsupported agent
+     * mislaunches it as Claude (the 2026-06 Cursor incident).
+     */
+    headroomWrappable: boolean;
+    /**
+     * The `headroom init --global <kind>` subcommand for this agent.
+     * Present iff {@link headroomWrappable} is true.
+     */
+    headroomKind?: HeadroomKind;
+    /**
+     * Whether the agent runs over ACP (Agent Client Protocol) in the CLI —
+     * mirrors which agents have an entry in the CLI's ACP adapter registry
+     * (`apps/cli/src/agents/acp/adapters.ts`). `false` ⇒ legacy PTY runtime.
+     */
+    acp: boolean;
+    /**
+     * `true` for agents that authorize via the OAuth DEVICE-code flow
+     * (Codex, Cursor) rather than the redirect/paste flow (Claude, Gemini).
+     * Mirrors the mobile agent catalog (`apps/mobile/src/lib/agentCatalog.ts`).
+     */
+    deviceFlow?: boolean;
+    /**
+     * Whether the device-code flow surfaces `userCode` to the user as an
+     * "enter this code" string. `true` for Codex (a real human-typed
+     * user_code shown on the OpenAI page). `false` for Cursor — there
+     * `userCode` is the secret PKCE verifier used only for the poll
+     * echo-back; rendering it would leak the secret. Only meaningful when
+     * {@link deviceFlow} is `true`.
+     */
+    showsUserCode?: boolean;
+}
+
+declare const AGENT_REGISTRY: Record<AgentId, AgentMetadata>;
+declare function getEnabledAgents(): AgentMetadata[];
+declare function getAgent(id: AgentId): AgentMetadata;
+declare function isKnownAgentId(id: string): id is AgentId;
+
+/**
+ * Agent identity — the ONE place the public (`LinkedAgentId`) and internal
+ * (`AgentId`) id spaces are declared and bridged, plus the ONE alias
+ * normalizer every surface funnels through.
+ *
+ * Canonical values consolidated from (Phase 2, PR-1):
+ *   - backend `apps/api-v2/src/linked-agents/agent-map.ts`
+ *     (`PUBLIC_TO_INTERNAL` / `INTERNAL_TO_PUBLIC` / `LinkedAgentId`),
+ *   - CLI `apps/cli/src/commands/host/agent-provisioning.ts`
+ *     (`PUBLIC_TO_INTERNAL_AGENT`),
+ *   - VS Code plugin `apps/vsc-plugin/src/utils/cli-agent-id.ts`
+ *     (marketplace aliases + `__terminal__:` strip),
+ *   - CLI `apps/cli/src/commands/start/handlers.ts`
+ *     (the `claude_code` → `claude` normalization),
+ *   - mobile `apps/mobile/src/lib/agent-id-map.ts`.
+ */
+
+/** Sentinel id for the synthetic "CodeAgent Cloud (incluido)" house agent. */
+declare const HOUSE_AGENT_ID = "house-codeagent-cloud";
+/** Internal provider discriminator for the house agent. */
+declare const HOUSE_AGENT_PROVIDER = "codeagent_cloud";
+/** White-label display strings — never mention the backend model. */
+declare const HOUSE_AGENT_NAME = "CodeAgent Cloud";
+declare const HOUSE_AGENT_VENDOR = "CodeAgent";
+declare const HOUSE_AGENT_SUBTITLE = "Included \u2014 no setup";
+/**
+ * Public-facing linked-agent ids — the id space the `/api/agents/...`
+ * endpoints and the mobile/web surfaces speak. The internal `AgentId`
+ * (`'claude' | 'codex' | …`) is what the runtimes / provisioning key on.
+ */
+type LinkedAgentId = 'claude_code' | 'codex' | 'cursor' | 'aider' | 'coderabbit' | 'gemini' | typeof HOUSE_AGENT_ID;
+declare const LINKED_AGENT_IDS: readonly LinkedAgentId[];
+declare function isLinkedAgentId(value: string): value is LinkedAgentId;
+/**
+ * Every public id → internal `AgentId`.
+ *
+ * ⚠️ RECONCILED ASYMMETRY — this map is the UNION of what the two sides
+ * historically accepted:
+ *   - The backend's `agent-map.ts` accepts only the `LinkedAgentId` union
+ *     (incl. the house agent, whose runtime is Claude Code) — no bare
+ *     `claude`, no `copilot` (there is no public copilot LinkedAgentId).
+ *   - The CLI's self-hosted `agent-provisioning.ts` additionally accepts
+ *     bare `'claude'` and `'copilot'` (deploy payloads have carried
+ *     already-internal ids), but not the house agent.
+ * Consumers that must REJECT ids outside their own historical set keep
+ * their own guard on top (e.g. `isLinkedAgentId`).
+ */
+declare const PUBLIC_TO_INTERNAL: Readonly<Record<LinkedAgentId | 'claude' | 'copilot', AgentId>>;
+/**
+ * Internal → public. Partial: `copilot` has no public LinkedAgentId, and
+ * `claude` maps back to `claude_code` (never the house agent — that
+ * direction is intentionally lossy).
+ */
+declare const INTERNAL_TO_PUBLIC: Readonly<Partial<Record<AgentId, LinkedAgentId>>>;
+/** Resolve a public/linked id to the internal `AgentId`, or null. */
+declare function publicToInternal(publicId: string): AgentId | null;
+/** Resolve an internal `AgentId` to its public `LinkedAgentId`, or null. */
+declare function internalToPublic(internal: AgentId): LinkedAgentId | null;
+/** Prefix IDE plugins use for terminal-hosted agent ids. */
+declare const TERMINAL_AGENT_PREFIX = "__terminal__:";
+/**
+ * THE agent-id normalizer. Collapses every known spelling of an agent id
+ * (registry id, public `claude_code` form, marketplace extension id,
+ * `__terminal__:`-prefixed plugin id — case/whitespace tolerant) onto the
+ * internal `AgentId`, or `null` when unknown.
+ *
+ * Deliberately does NOT:
+ *   - gate on `enabled` (callers that need availability check the
+ *     registry — see the VS Code wrapper `normalizeCliAgentId`);
+ *   - map the house agent (that's a runtime substitution, not an alias —
+ *     use {@link publicToInternal});
+ *   - fall back to anything. Unknown in → `null` out.
+ */
+declare function normalizeAgentId(raw: string): AgentId | null;
+/**
+ * The `headroom init --global <kind>` subcommand for an agent id, derived
+ * from the registry's `headroomKind` flags — or `null` for unknown or
+ * non-wrappable agents (cursor / gemini / aider / anything else).
+ *
+ * ⚠️ NEVER falls back to `'claude'`. The historical CLI fallback is how
+ * the 2026-06 Cursor incident happened: an unsupported agent slipped
+ * through, defaulted to `claude`, and `headroom wrap claude` launched
+ * Claude Code instead of the user's agent. Callers that genuinely need a
+ * default (e.g. picking an init subcommand AFTER the wrappable gate has
+ * already passed) apply it themselves — see the CLI's
+ * `agentIdToHeadroomKind` wrapper.
+ *
+ * Matching mirrors the historical predicates on BOTH sides (CLI
+ * `isHeadroomSupportedAgent`, api-v2 `isHeadroomWrappableAgent`):
+ * case-insensitive, `_`/`-` tolerant, prefix match — so `claude_code`,
+ * `Claude-Code`, `codex_cli`, `copilot-cli` all resolve.
+ */
+declare function headroomKindFor(agentId: string): HeadroomKind | null;
+/**
+ * Registry-derived replacement for the two scattered predicates
+ * (`isHeadroomSupportedAgent` in the CLI, `isHeadroomWrappableAgent` in
+ * api-v2). Accepts both id spaces (`claude_code` and `claude`).
+ */
+declare function isHeadroomWrappable(agentId: string): boolean;
+
+/**
+ * Wire-shape types for the CLI / IDE-plugin → backend producer endpoints
+ * that feed the mobile Files screen and the Pending Review Queue:
+ *
+ *   - `POST /api/files/changed`  — register a file change (upsert keyed by
+ *     `sessionId + filePath` server-side, so re-emitting on every save is
+ *     safe).
+ *   - `POST /api/review/hunks`   — register an individual hunk for the
+ *     Pending Review Queue. The "Aggressive" policy this codebase ships
+ *     with sends one of these per hunk in the diff so the mobile user
+ *     approves/rejects each one independently.
+ *
+ * These mirror the backend NestJS DTOs at:
+ *   apps/api-v2/src/files/dto/report-file-changed.dto.ts
+ *   apps/api-v2/src/review/dto/create-hunk.dto.ts
+ *
+ * They are wire-only — no class-validator decorators, no runtime
+ * coercion. The producer constructs them in TypeScript and serialises
+ * directly to JSON. The backend re-validates on its side.
+ */
+type FileChangeStatus = 'modified' | 'added' | 'deleted' | 'renamed';
+type FileReviewStatus = 'modified' | 'awaiting_review' | 'approved' | 'rejected' | 'reviewed';
+/**
+ * Body for `POST /api/files/changed`. The producer emits one of these
+ * per modified file per session-tick (debounced). The server upserts
+ * on `(sessionId, filePath)` so re-emitting on every save is safe.
+ *
+ * `pluginId` is required by the backend's `PluginAuthGuard` — it's
+ * read off the body so the guard can derive the expected HMAC of the
+ * `X-Plugin-Auth-Token` header against this exact `(session, plugin)`
+ * pair before the controller runs.
+ */
+interface FileChangedEvent {
+    sessionId: string;
+    pluginId: string;
+    filePath: string;
+    fileStatus: FileChangeStatus;
+    linesAdded: number;
+    linesRemoved: number;
+    hunkCount: number;
+    /**
+     * Optional. When the producer also emits hunks to `/api/review/hunks`
+     * for this file, set this to `'awaiting_review'` so the Files screen
+     * renders the pending-review badge. Defaults to `'modified'`
+     * server-side when omitted.
+     */
+    reviewStatus?: FileReviewStatus;
+    /**
+     * Optional path of the enclosing git repo, relative to the
+     * producer's workingDir / workspace folder. Empty string when the
+     * producer was launched from inside the repo (single-repo
+     * workspace). Lets the UI attribute each row to its sub-repo when
+     * the user paired from a multi-repo parent directory (e.g.
+     * `~/Documents/codeagent/` containing several sibling repos).
+     * Optional for back-compat with older producers — backend
+     * defaults to null.
+     */
+    repoPath?: string;
+    /**
+     * Optional basename of the enclosing git repo. Provides a short
+     * label the UI can render in a chip without parsing `repoPath`.
+     * Optional for back-compat.
+     */
+    repoName?: string;
+}
+type HunkLineType = 'add' | 'remove' | 'context';
+/**
+ * One line of a unified diff hunk. `lineNumber` carries the
+ * post-change ('+'-side) line numbers from `git diff` so the mobile
+ * UI can render the gutter without re-deriving them.
+ */
+interface PendingReviewHunkLine {
+    type: HunkLineType;
+    lineNumber: number;
+    text: string;
+}
+/**
+ * Body for `POST /api/review/hunks`. One per hunk in the diff.
+ *
+ * `reasoning` and `sessionLogPreview` are nullable — the v1 chokidar
+ * producer doesn't have either (it can't tell agent edits from human
+ * edits, and it doesn't read the agent's rationale), so it skips
+ * these fields entirely. A future PTY-output-parsing producer can
+ * populate them.
+ */
+interface PendingReviewHunkEvent {
+    sessionId: string;
+    pluginId: string;
+    filePath: string;
+    fileStatus: FileChangeStatus;
+    hunkHeader: string;
+    lines: PendingReviewHunkLine[];
+    linesAdded: number;
+    linesRemoved: number;
+    reasoning?: string;
+    sessionLogPreview?: string[];
+}
+/**
+ * One commit in the file's git log (newest first). `sha` is the full
+ * 40-char hash; consumers truncate for display. `committedAt` is ISO
+ * 8601 in UTC. Mirrors `apps/api-v2/src/review/dto/create-history.dto.ts`
+ * `CommitEntryDto`.
+ */
+interface CommitEntryWire {
+    sha: string;
+    authorName: string;
+    authorEmail: string;
+    committedAt: string;
+    subject: string;
+}
+/**
+ * Body for `POST /api/review/history`. The producer captures `git log
+ * --max-count=N -- <path>` for each touched file at the same point it
+ * pushes hunks, then upserts on `(sessionId, repoPath, filePath)`
+ * server-side. Re-emitting per save is safe.
+ */
+interface FileHistoryEvent {
+    sessionId: string;
+    pluginId: string;
+    filePath: string;
+    repoPath?: string;
+    repoName?: string;
+    commits: CommitEntryWire[];
+}
+/**
+ * One line of `git blame`. `lineNumber` is 1-based and matches the
+ * post-image (current) file gutter.
+ */
+interface BlameLineWire {
+    lineNumber: number;
+    sha: string;
+    authorName: string;
+    committedAt: string;
+    text: string;
+}
+/**
+ * Body for `POST /api/review/blame`. Capped server-side by what the
+ * producer chose to emit — large files get truncated by the CLI so a
+ * single payload stays under the JSON size limit.
+ */
+interface FileBlameEvent {
+    sessionId: string;
+    pluginId: string;
+    filePath: string;
+    repoPath?: string;
+    repoName?: string;
+    lines: BlameLineWire[];
+}
+
+/**
+ * Wire-shape types for the CLI / IDE-plugin → backend Epic C streaming
+ * endpoints. The CLI parses Claude's (or Codex's) PTY output into a
+ * stream of discriminated chunks and pushes each one to the backend, so
+ * the mobile client can render an in-progress agent turn token-by-token
+ * instead of waiting for the entire turn to finalise.
+ *
+ *   - `POST /api/sessions/:id/streaming-chunk` — body is
+ *     {@link StreamingChunkEvent}. Fires an SSE delta downstream.
+ *   - `POST /api/sessions/:id/awaiting-answer` — body is
+ *     {@link AwaitingAnswerEvent}. Pauses the turn on the mobile side
+ *     and prompts the user for a reply. Stored in Redis with a 5 min TTL.
+ *   - Answer channel: backend publishes user replies on the Redis
+ *     channel `session:${sessionId}:answers` with the payload shape
+ *     {@link AnswerResolvedEvent}. The CLI polls
+ *     `GET /api/sessions/:id/pending-answer` to drain it (the polling
+ *     interval is 1.5 s — short enough to feel instant, long enough to
+ *     stay well under any sane rate limit).
+ *
+ * These mirror the backend NestJS DTOs at:
+ *   apps/api-v2/src/sessions/dto/streaming-chunk.dto.ts
+ *   apps/api-v2/src/sessions/dto/awaiting-answer.dto.ts
+ *   apps/api-v2/src/sessions/dto/answer-resolved.dto.ts
+ *
+ * They are wire-only — no class-validator decorators, no runtime
+ * coercion. The producer constructs them in TypeScript and serialises
+ * directly to JSON. The backend re-validates on its side.
+ */
+/**
+ * Logical kind of an Epic C streaming chunk.
+ *
+ * - `text`        — agent prose (the conversational reply the user sees).
+ * - `thinking`    — Claude's "(thinking)" / "+ Puttering…" frame between
+ *                   the prompt and the answer.
+ * - `tool_use`    — a tool call (Read / Edit / Bash / Search / …) the
+ *                   agent invoked.
+ * - `tool_result` — the result body of the prior tool call (typically
+ *                   the `└ …` continuation line in Claude's TUI).
+ */
+type StreamingChunkKind = 'text' | 'thinking' | 'tool_use' | 'tool_result';
+/**
+ * Body for `POST /api/sessions/:id/streaming-chunk`.
+ *
+ * `chunkId` is stable across continuation pushes for the same logical
+ * chunk (so the backend can splice deltas), and changes when the
+ * producer flips `kind` or finalises the chunk. `isFinal: true` marks
+ * the last push for this `chunkId`; the next emission opens a fresh
+ * chunkId.
+ */
+interface StreamingChunkEvent {
+    chunkId: string;
+    kind: StreamingChunkKind;
+    content: string;
+    isFinal: boolean;
+}
+/**
+ * Body for `POST /api/sessions/:id/awaiting-answer`.
+ *
+ * `prompt` is the question text the agent rendered (free-form). When
+ * the agent presented a multiple-choice selector, `options` is the
+ * ordered list of choices the user can pick. `questionId` is the
+ * producer-generated UUID the backend echoes back through the answer
+ * channel so the CLI can correlate the user's reply with the prompt.
+ */
+interface AwaitingAnswerEvent {
+    questionId: string;
+    prompt: string;
+    options?: string[];
+}
+/**
+ * Wire shape for the `input_suggestion` output chunk emitted by CLI agents
+ * after a turn ends.
+ *
+ * PTY agents (claude, codex, copilot, aider) emit `content: string` —
+ * the detected ghost-text from the agent's input area (backward-compat,
+ * one chip on mobile).
+ *
+ * ACP agents emit `content: string[]` — a static set of chip labels such
+ * as `['Continue', 'Yes, go ahead', 'Explain']` (multiple chips on mobile).
+ *
+ * Consumers MUST normalise:
+ *   `Array.isArray(content) ? content : [content]`
+ */
+interface InputSuggestionChunk {
+    type: 'input_suggestion';
+    /** Single string (PTY, backward-compat) or array of chip labels (ACP). */
+    content: string | string[];
+    done: true;
+}
+/**
+ * Payload published on the Redis `session:${sessionId}:answers`
+ * channel — and also the shape returned by the polling fallback
+ * `GET /api/sessions/:id/pending-answer` (wrapped in `{ data: … }` by
+ * the backend's standard envelope).
+ *
+ * For free-form prompts `answer` is the user's typed text. For a
+ * selector prompt, the backend forwards the chosen option label as
+ * `answer` and additionally sets `optionIndex` (0-based) so the
+ * producer can drive arrow-key navigation in a React Ink selector
+ * without re-resolving the label.
+ */
+interface AnswerResolvedEvent {
+    questionId: string;
+    answer: string;
+    optionIndex?: number;
+}
+
+/**
+ * Production API base URL for all CodeAgent Mobile clients.
+ *
+ * History note: prod migrated from Vercel (`https://api.codeagent-mobile.com`)
+ * to Cloud Run / api-v2 (`https://api.codeagent-mobile.com`) in 2026-05. The
+ * Vercel deployment is now gated by Vercel deployment protection and returns
+ * 403 for unauthed traffic — DO NOT fall back to it.
+ *
+ * Override at runtime with `CODEAM_API_URL` (full URL override) OR set
+ * `CODEAM_TEST_MODE=1` to point every client request at the dev
+ * preview without having to know its host.
+ */
+declare const DEFAULT_API_BASE_URL: "https://api.codeagent-mobile.com";
+/**
+ * Dev-preview API base URL. Same Cloud Run service as prod but routed
+ * to the `dev` revision (auto-deploys from the `dev` branch in the
+ * backend repo). Manual smoke tests + load runs land here.
+ */
+declare const DEV_API_BASE_URL: "https://dev-api.codeagent-mobile.com";
+/**
+ * Resolve the active API base URL, honoring in priority order:
+ *
+ *   1. Explicit `CODEAM_API_URL` env var — full URL, takes precedence.
+ *   2. `CODEAM_TEST_MODE=1` shortcut — flips to [DEV_API_BASE_URL]
+ *      without the user having to know the dev host.
+ *   3. The `DEFAULT_API_BASE_URL` constant (prod).
+ *
+ * Used by every CLI service that talks to the backend so one env var
+ * flips heartbeats, command relay, chunk uploads, and the pairing
+ * flow in lockstep — eliminates the cross-environment misroute where
+ * pairing succeeds in dev (shared Redis) but the CLI keeps
+ * heartbeating to prod.
+ */
+declare function resolveApiBaseUrl(): string;
+
+/**
+ * Preview wire types (PreviewDetection / PreviewStatus / EnvVar).
+ *
+ * CANONICAL WIRE OWNER: this file (`@codeam/shared`) owns the wire
+ * protocol, per the cross-repo rule. The backend repo keeps hand-synced
+ * MIRRORS (`codeagent-mobile/packages/shared/src/types/preview.ts` for
+ * mobile/landing, `codeagent-mobile/apps/api-v2/src/common/types/preview.ts`
+ * for the backend); a drift-check script at
+ * `codeagent-mobile/scripts/check-shared-drift` compares them.
+ */
+interface PreviewDetection {
+    framework: string;
+    command: string;
+    args: string[];
+    port: number;
+    ready_pattern: string;
+    env?: Record<string, string>;
+    setup_commands?: Array<{
+        cmd: string;
+        args: string[];
+    }>;
+    notes?: string;
+}
+type PreviewState = 'idle' | 'detection_pending' | 'detection_ready' | 'starting' | 'running' | 'error';
+type PreviewErrorStage = 'detection' | 'spawn' | 'tunnel' | 'ready_timeout' | 'unsupported';
+interface PreviewStatus {
+    state: PreviewState;
+    url?: string;
+    framework?: string;
+    detection?: PreviewDetection;
+    error?: {
+        stage: PreviewErrorStage;
+        message: string;
+    };
+}
+/**
+ * One environment variable as edited from the app and written to the
+ * project `.env`. The wire shape for `env_read` (returns EnvVar[]) and
+ * `env_write` (accepts EnvVar[]).
+ */
+interface EnvVar {
+    key: string;
+    value: string;
+}
+
+/**
+ * Beads wire protocol — the bytes the codeam-cli pushes to the backend's
+ * `POST /api/beads/ingest` and that the backend mirrors + fans out over the
+ * per-user SSE bus.
+ *
+ * CANONICAL WIRE OWNER: this file (`@codeam/shared`) owns the wire
+ * protocol, per the cross-repo rule. The backend repo keeps hand-synced
+ * MIRRORS of these shapes (`codeagent-mobile/packages/shared/src/types/beads.ts`
+ * for mobile/landing, `codeagent-mobile/apps/api-v2/src/beads/beads.types.ts`
+ * for the backend service); a drift-check script at
+ * `codeagent-mobile/scripts/check-shared-drift` compares them. Both the CLI
+ * (tsup) and the VS Code extension (esbuild) inline this file at build time.
+ *
+ * Shape rationale: `BeadsIssueDto` mirrors `bd ready --json` / `bd list --json`
+ * output (verified against `@beads/bd@1.0.5`) plus the backend-required
+ * `projectKey` scoping field (design decision D7). We do NOT reshape bd's
+ * field names — the mirror stores them as-is so a bd schema bump is a
+ * one-file change here, not a sprawling rename across the codebase.
+ */
+/** bd lifecycle status. bd emits these literals in `--json`. */
+type BeadsIssueStatus = 'open' | 'in_progress' | 'blocked' | 'closed';
+/**
+ * Single issue as emitted by `bd ready --json` / `bd list --json`, plus the
+ * backend scoping field. The counts are REQUIRED on the wire — the backend's
+ * ingest DTO validates them as required ints, so the producer (`bd-adapter`'s
+ * `parseIssues`) defaults any count bd omits to 0 rather than dropping the
+ * field.
+ */
+interface BeadsIssueDto {
+    id: string;
+    title: string;
+    status: BeadsIssueStatus;
+    /** 0 = P0 (highest). bd emits an integer; null when unset. */
+    priority: number | null;
+    /** bug | task | feature | message | … (free-form in bd). */
+    issue_type: string;
+    /** agent / session id that claimed the issue, when claimed. */
+    owner: string | null;
+    created_at: string;
+    updated_at: string;
+    dependency_count: number;
+    dependent_count: number;
+    comment_count: number;
+    /** D7 scoping — normalized git origin (or path-hash fallback). */
+    projectKey: string;
+}
+/** bd dependency kind. */
+type BeadsDependencyKind = 'blocks' | 'related' | 'parent-child' | 'discovered-from';
+/**
+ * One dependency edge. Rows carry NO per-row `projectKey` — the ingest
+ * payload is per-project, so edges are scoped by the payload-level
+ * `projectKey` on the backend.
+ */
+interface BeadsDependencyDto {
+    /** stable id — `${fromId}:${kind}:${toId}` when bd doesn't supply one. */
+    id: string;
+    fromId: string;
+    toId: string;
+    kind: BeadsDependencyKind;
+}
+interface BeadsMemoryDto {
+    id: string;
+    body: string;
+    createdAt: string;
+    /** null = cross-cutting / personal (not scoped to one project). */
+    projectKey: string | null;
+}
+/** `bd status --json` → `summary` block. */
+interface BeadsStatusSummary {
+    open_issues: number;
+    ready_issues: number;
+    blocked_issues: number;
+    in_progress_issues: number;
+    closed_issues: number;
+    total_issues: number;
+}
+/**
+ * The delta (or full snapshot) the CLI POSTs to `/api/beads/ingest` whenever
+ * `.beads/issues.jsonl` changes. `fullSnapshot: true` tells the backend to
+ * prune issues absent from `issues` (station-wins reconciliation).
+ */
+interface BeadsIngestPayload {
+    sessionId: string;
+    pluginId: string;
+    /** D7 project key the issues/memories belong to. */
+    projectKey: string;
+    /** Human-readable label (repo name) for the UI. */
+    projectLabel: string;
+    /** When true, the backend prunes mirror rows not present in `issues`. */
+    fullSnapshot?: boolean;
+    issues: BeadsIssueDto[];
+    /** Dependency edges between issues. The current watcher ALWAYS sends this
+     *  (an empty array today — edges aren't computed in the P0 snapshot); the
+     *  backend DTO nevertheless marks it optional to tolerate older producers.
+     *  Field name matches the backend (`dependencies`, not `deps`). */
+    dependencies: BeadsDependencyDto[];
+    memories: BeadsMemoryDto[];
+    summary?: BeadsStatusSummary;
+}
+/**
+ * A mobile-originated action relayed to the CLI as a pending command
+ * (`type: 'beads_action'`). The CLI replays it as a native `bd` command
+ * (Task 9) then pushes the resulting state back through ingest.
+ *
+ * NOTE — this is the backend→CLI COMMAND hop, NOT the mobile→backend
+ * request hop. The mobile client POSTs a `BeadsActionRequest`
+ * (discriminator `action`, create-title in `title`) to
+ * `POST /api/beads/actions`; the backend translates it in
+ * `codeagent-mobile/apps/api-v2/src/beads/beads.controller.ts` (+
+ * `bd-action.util.ts`) and pushes a `beads_action` command whose payload
+ * the CLI decodes in `apps/cli/src/beads/wiring.ts`
+ * (`beadsActionFromPayload`) into THIS shape (discriminator `kind`,
+ * title/body in `text`, plus `owner`).
+ */
+type BeadsActionKind = 'claim' | 'close' | 'create' | 'remember';
+interface BeadsActionCommand {
+    kind: BeadsActionKind;
+    /** Target issue id — required for `claim` / `close`. */
+    issueId?: string;
+    /** Free text — `create` title or `remember` body. */
+    text?: string;
+    /** `close` reason. */
+    reason?: string;
+    /** Owner to claim as — defaults to the session/agent id when omitted. */
+    owner?: string;
+    /** Project the action targets (so the right `bd` working context applies). */
+    projectKey?: string;
+}
+/** @deprecated Renamed to `BeadsActionCommand` — the old name collided with
+ *  the backend repo's mobile→backend request type (now `BeadsActionRequest`). */
+type BeadsActionPayload = BeadsActionCommand;
+/** Action verb for `configureBeads` (enable / disable / status). */
+type BeadsConfigureAction = 'enable' | 'disable' | 'status';
+/** Lifecycle state emitted by `configureBeads` on the per-session SSE bus. */
+type BeadsStatusState = 'enabled' | 'disabled' | 'error' | 'provisioning';
+/**
+ * Lifecycle of the CLI's Beads provisioning step (spec D10/D13).
+ *
+ * The CLI's composition-root provisions Beads (`bd init` → start the
+ * shared dolt server → enable auto-export → start the watcher) as a
+ * parallel, non-fatal concern, decoupled from the agent run. It signals
+ * each phase to the backend, which fans it out as a `beads_provisioning`
+ * UserEvent so the read-only mobile/web surface can show a lightweight
+ * status line ("Provisioning Beads…", "Beads ready", "Beads
+ * provisioning failed") — distinct from the data feed (`beads_state_changed`).
+ *
+ * - `provisioning` — bootstrap started / in flight.
+ * - `ready`        — Beads is up; the mirror will begin receiving deltas.
+ * - `failed`       — bootstrap aborted (e.g. bd install failed); the
+ *                    surface explains the agent is running without Beads.
+ */
+type BeadsProvisioningStatus = 'provisioning' | 'ready' | 'failed';
+/**
+ * Body of `POST /api/beads/provisioning` — the CLI is the producer.
+ *
+ * `sessionId` + `pluginId` carry the plugin-auth envelope (the CLI has
+ * NO user JWT, same as `/ingest`). The backend resolves the userId from
+ * the session and publishes `{ type: 'beads_provisioning', status,
+ * projectKey }` on the per-user SSE bus.
+ *
+ * `projectKey` is optional: the home-level `bd init` runs before any
+ * repo is resolved, so the first `provisioning` frame may not carry one
+ * yet. `detail` is an optional human-readable note (e.g. the failure
+ * reason) the surface can render verbatim.
+ */
+interface BeadsProvisioningPayload {
+    /** Paired session the CLI is pushing from (plugin-auth). */
+    sessionId: string;
+    /** Plugin id the auth token was minted for (plugin-auth). */
+    pluginId: string;
+    status: BeadsProvisioningStatus;
+    /** Affected project, when the bootstrap has resolved a repo. */
+    projectKey?: string;
+    /** Optional human-readable note (e.g. failure reason). */
+    detail?: string;
+}
+/** Snapshot of the station's Beads add-on state (mirrored to mobile). */
+interface BeadsStatus {
+    state: BeadsStatusState;
+    running?: boolean;
+    bdAvailable?: boolean;
+    doltAvailable?: boolean;
+    serverUp?: boolean;
+    prefix?: string | null;
+    error?: string;
+}
+/** One project the mirror has seen — drives the project-list view. */
+interface BeadsProjectDto {
+    projectKey: string;
+    /** Human repo name for the UI. */
+    label: string;
+    /** ISO8601 — last time the CLI pushed state for this project. */
+    lastSyncedAt: string;
+}
+/**
+ * One-shot snapshot returned by `GET /api/beads/me` and embedded in the
+ * per-user SSE `snapshot` so reconnects rehydrate. `issuesByProject` is
+ * keyed by `projectKey`.
+ */
+interface BeadsSnapshotDto {
+    projects: BeadsProjectDto[];
+    issuesByProject: Record<string, BeadsIssueDto[]>;
+    memories: BeadsMemoryDto[];
+    /** Aggregate summary across all the user's projects. */
+    summary: BeadsStatusSummary;
+}
+/**
+ * The user-initiated Beads actions a mobile/web client can request.
+ *
+ * - `claim`    — take ownership of a ready issue (`bd update --status in_progress`).
+ * - `close`    — close an issue (`bd close`).
+ * - `create`   — create a new issue (`bd create`).
+ * - `remember` — record a persistent memory note (`bd remember`).
+ *
+ * The backend does NOT mutate the mirror directly — it relays the
+ * action as a `bd` command to the user's active paired session, where
+ * the CLI runs it natively against the station's `bd` graph. The
+ * resulting state change flows back via `POST /api/beads/ingest` and
+ * fans out over the per-user SSE bus. The mirror is read-optimised;
+ * the station stays the source of truth (station-wins).
+ */
+type BeadsActionType = 'claim' | 'close' | 'create' | 'remember';
+/**
+ * Body of `POST /api/beads/actions` (JWT-authed mobile/web user).
+ *
+ * NOTE — this is the mobile→backend REQUEST hop, NOT the backend→CLI
+ * command hop (`BeadsActionCommand` above).
+ *
+ * Field relevance by action:
+ * - `claim`    — `issueId` required.
+ * - `close`    — `issueId` required; `reason` optional.
+ * - `create`   — `title` required; `projectKey` optional (targets a project).
+ * - `remember` — `text` required; `projectKey` optional (scopes the memory).
+ */
+interface BeadsActionRequest {
+    action: BeadsActionType;
+    /** Target issue for `claim` / `close`. */
+    issueId?: string;
+    /** Title for a `create`d issue. */
+    title?: string;
+    /** Optional human-readable reason for `close`. */
+    reason?: string;
+    /** Memory body for `remember`. */
+    text?: string;
+    /** Project scope for `create` / `remember`; defaults to the station's current repo. */
+    projectKey?: string;
+}
+
+/**
+ * Headroom budget configuration and command types.
+ * Used by the CLI to enable/disable cost-saving Headroom token compression
+ * and track spending against configured budgets.
+ *
+ * CANONICAL WIRE OWNER: this file (`@codeam/shared`) owns the wire
+ * protocol, per the cross-repo rule. The backend repo keeps hand-synced
+ * MIRRORS (`codeagent-mobile/packages/shared/src/types/headroom.ts` for
+ * mobile/landing, `codeagent-mobile/apps/api-v2/src/common/types/headroom.ts`
+ * for the backend); a drift-check script at
+ * `codeagent-mobile/scripts/check-shared-drift` compares them.
+ */
+type HeadroomBudgetPeriod = 'hourly' | 'daily' | 'monthly';
+/**
+ * Command sent via relay to enable/disable/configure Headroom budget settings.
+ * The `agentId` field is included because PairedSession has no agentId server-side,
+ * so the relay command carries it for the CLI handler to guard on.
+ */
+interface HeadroomBudgetCommand {
+    budgetEnabled: boolean;
+    budgetUsd?: number;
+    budgetPeriod?: HeadroomBudgetPeriod;
+    agentId?: string;
+}
+/**
+ * Budget usage fields appended to the savings payload that the Headroom reporter
+ * sends to the backend. Tracks spending in the current budget period.
+ */
+interface HeadroomBudgetUsage {
+    periodSpendUsd?: number;
+    budgetUsd?: number;
+    budgetPeriod?: HeadroomBudgetPeriod;
+    /** True iff this turn pushed periodSpendUsd to or past budgetUsd. */
+    budgetReached?: boolean;
+}
+/**
+ * Headroom cost-saving state for a session — carried on the `headroom_status`
+ * SSE event and snapshotted by the backend into Redis `headroom:<sessionId>`.
+ * Mirrored byte-for-byte in `apps/api-v2/src/common/types/headroom.ts`.
+ */
+interface HeadroomStatus {
+    state: 'enabled' | 'disabled' | 'error' | 'provisioning';
+    running?: boolean;
+    agent?: string;
+    savings?: number;
+    error?: string;
+}
+
+/**
+ * Headroom provisioning manifest — the SINGLE source of truth for what a
+ * Headroom install consists of, rendered by every provisioning surface:
+ *
+ *   - codespace bootstrap (bash composer in the backend repo,
+ *     `apps/api-v2/src/codespaces/github-ssh.service.ts` — adopts in PR-2),
+ *   - self-hosted deploy (TS installer, CLI `commands/host-agent.ts`
+ *     `setupHeadroomForSelfHosted`),
+ *   - on-demand local sessions ("Session add-ons → Cost-saving", CLI
+ *     `services/headroom/configure.ts`).
+ *
+ * Values are DATA-first (arrays/records, plus tiny pure renderers) so both
+ * the TS installer and a bash composer can interpolate from them. Renderers
+ * are byte-exact with the literals they replaced — guarded by
+ * `packages/shared/__tests__/headroom-manifest.test.ts`.
+ *
+ * ⚠️ The extras matter: `[proxy,code]` pulls the ONNX compression engines
+ * (Kompress + tree-sitter CodeCompressor). NEVER add `[ml]` — that's
+ * multi-GB PyTorch, and a broken/cold torch wedges every prompt at
+ * "Thinking…". The models are pre-downloaded at provision time because the
+ * proxy eager-loads with `allow_download=False` and a cold cache defers the
+ * ~840 MB download to the first prompt (blowing the agent's ~90 s idle
+ * timeout).
+ */
+/** Local proxy port the agent's config is routed to. */
+declare const HEADROOM_PROXY_PORT = 8787;
+/**
+ * Env that pins the ONNX backend on the proxy process — never imports
+ * torch. Spread into the proxy launch env on every surface.
+ */
+declare const HEADROOM_BACKEND_ENV: {
+    readonly HEADROOM_KOMPRESS_BACKEND: "onnx_cpu";
+};
+/**
+ * The proxy's HTTP/server companion packages, installed alongside the
+ * `headroom-ai[...]` package. The COMPRESSION ENGINES come from the
+ * headroom-ai extras — NOT this list.
+ */
+declare const HEADROOM_PIP_COMPANIONS: readonly string[];
+/** The three provisioning surfaces (see module doc). */
+type HeadroomSurface = 'codespace' | 'selfHosted' | 'onDemand';
+/**
+ * pip extras per surface. `onDemand` additionally ships `image`
+ * (image-compression support, added with the Session add-ons path in
+ * codeam-cli@2.49.0); the older codespace/self-hosted install strings
+ * remain `[proxy,code]` byte-for-byte.
+ */
+declare const HEADROOM_EXTRAS_BY_SURFACE: Readonly<Record<HeadroomSurface, readonly string[]>>;
+/** `headroom-ai[<extras>]` — the pip requirement string. */
+declare function headroomPipPackage(extras: readonly string[]): string;
+/** One HuggingFace repo to pre-warm into the HF cache at provision time. */
+interface HeadroomModelSpec {
+    repo: string;
+    /** `snapshot_download(..., allow_patterns=[…])` filter. */
+    allowPatterns: readonly string[];
+}
+/**
+ * The two HF repos Kompress needs. kompress-v2-base is the ONNX model
+ * (skip its .pt/.safetensors torch artifacts); ModernBERT-base is the
+ * TOKENIZER ONLY (skip its model weights).
+ */
+declare const HEADROOM_MODELS: readonly HeadroomModelSpec[];
+/** Formatting knob so each surface can stay byte-identical to its
+ *  historical literal (the CLI joins patterns with `,`, the codespace
+ *  bash composer with `, `). */
+interface HeadroomPythonRenderOpts {
+    /** Put a space after the commas between allow_patterns entries. */
+    spaceAfterComma?: boolean;
+}
+/** Render one `snapshot_download(...)` python line for a model. */
+declare function headroomSnapshotDownloadLine(model: HeadroomModelSpec, opts?: HeadroomPythonRenderOpts): string;
+/**
+ * The full model pre-download python snippet (import + one
+ * `snapshot_download` per model), newline-joined — what the surfaces pass
+ * to `python -c` / a heredoc.
+ */
+declare function headroomModelPredownloadScript(opts?: HeadroomPythonRenderOpts): string;
+
+/**
+ * Canonical names of the per-user SSE bus events (`/api/users/me/stream`).
+ *
+ * The authoritative list is the `UserEvent` discriminated union in the
+ * backend repo: codeagent-mobile/apps/api-v2/src/user-events/user-events.types.ts.
+ * Every `type:` literal of that union appears here exactly once — when a new
+ * variant lands on the union, add its name here (and in the backend mirror of
+ * this file at codeagent-mobile/packages/shared/src/types/events.ts).
+ *
+ * Producers (CLI event posts, backend `userEvents.publish` calls) and
+ * consumers (the `useUserEventsSSE` hooks' switch cases) should reference
+ * `USER_EVENTS.*` instead of re-typing the string, so a typo becomes a
+ * compile error instead of a silently dropped event.
+ */
+declare const USER_EVENTS: {
+    readonly PAIRED_SESSION_STATUS: "paired_session_status";
+    readonly PAIRED_SESSION_ADDED: "paired_session_added";
+    readonly PAIRED_SESSION_REMOVED: "paired_session_removed";
+    readonly PAIRED_SESSION_BRANCH_CHANGED: "paired_session_branch_changed";
+    readonly SHARED_WITH_ME_ADDED: "shared_with_me_added";
+    readonly SHARED_WITH_ME_REVOKED: "shared_with_me_revoked";
+    readonly USAGE_CHANGED: "usage_changed";
+    readonly TASK_DONE: "task_done";
+    readonly HUNK_PENDING_REVIEW_ADDED: "hunk_pending_review_added";
+    readonly HUNK_REVIEW_RESOLVED: "hunk_review_resolved";
+    readonly FILE_CHANGED: "file_changed";
+    readonly FILES_BATCH_CHANGED: "files_batch_changed";
+    readonly AGENT_STREAMING_CHUNK: "agent_streaming_chunk";
+    readonly AGENT_AWAITING_ANSWER: "agent_awaiting_answer";
+    readonly AWAITING_INPUT_ADDED: "awaiting_input_added";
+    readonly AGENT_ANSWER_RESOLVED: "agent_answer_resolved";
+    readonly TEMPLATE_ADDED: "template_added";
+    readonly TEMPLATE_REMOVED: "template_removed";
+    readonly TEMPLATE_UPDATED: "template_updated";
+    readonly AGENT_TASK_DISPATCHED: "agent_task_dispatched";
+    readonly AGENT_TASK_COMPLETED: "agent_task_completed";
+    readonly LINKED_AGENT_ADDED: "linked_agent_added";
+    readonly QUOTA_REACHED: "quota_reached";
+    readonly LINKED_AGENT_LINK_FAILED: "linked_agent_link_failed";
+    readonly CODESPACE_AGENT_INSTALLED: "codespace_agent_installed";
+    readonly AGENT_CREDENTIALS_REFRESHED: "agent_credentials_refreshed";
+    readonly CREDENTIAL_INVALID: "credential_invalid";
+    readonly CODESPACE_WAKING: "codespace_waking";
+    readonly CODESPACE_BILLING_BLOCKED: "codespace_billing_blocked";
+    readonly COST_SAVING_UPDATED: "cost_saving_updated";
+    readonly COMMAND_COMPLETED: "command_completed";
+    readonly AI_SUMMARY_PENDING: "ai_summary_pending";
+    readonly AI_SUMMARY_READY: "ai_summary_ready";
+    readonly AI_INSIGHT_PENDING: "ai_insight_pending";
+    readonly AI_INSIGHT_READY: "ai_insight_ready";
+    readonly PUSH_TOKEN_INVALIDATED: "push_token_invalidated";
+    readonly PREVIEW_DETECTION_PENDING: "preview_detection_pending";
+    readonly PREVIEW_DETECTION_READY: "preview_detection_ready";
+    readonly PREVIEW_STARTING: "preview_starting";
+    readonly PREVIEW_READY: "preview_ready";
+    readonly PREVIEW_STOPPED: "preview_stopped";
+    readonly PREVIEW_ERROR: "preview_error";
+    readonly PREVIEW_PROGRESS: "preview_progress";
+    readonly BEADS_STATE_CHANGED: "beads_state_changed";
+    readonly BEADS_PROVISIONING: "beads_provisioning";
+    readonly BEADS_TEAM_MEMORY_CHANGED: "beads_team_memory_changed";
+    readonly AUDIT_EVENT_ADDED: "audit_event_added";
+    readonly SELF_HOSTED_HOST_ADDED: "self_hosted_host_added";
+    readonly SELF_HOSTED_HOST_STATUS: "self_hosted_host_status";
+    readonly SELF_HOSTED_HOST_REMOVED: "self_hosted_host_removed";
+    readonly SELF_HOSTED_HOST_TELEMETRY: "self_hosted_host_telemetry";
+    readonly SELF_HOSTED_HOST_METRICS: "self_hosted_host_metrics";
+    readonly SELF_HOSTED_HOST_SESSIONS: "self_hosted_host_sessions";
+    readonly SELF_HOSTED_DEPLOY_PROGRESS: "self_hosted_deploy_progress";
+    readonly REFERRAL_REWARD_EARNED: "referral_reward_earned";
+    readonly HEADROOM_PROGRESS: "headroom_progress";
+    readonly HEADROOM_STATUS: "headroom_status";
+    readonly BEADS_STATUS: "beads_status";
+    readonly LINKED_AGENT_HEADROOM_BUDGET_UPDATED: "linked_agent_headroom_budget_updated";
+    readonly CLI_UPDATE_AVAILABLE: "cli_update_available";
+    readonly AGENT_INSTALL_PROGRESS: "agent_install_progress";
+    readonly AGENT_INSTALL_FAILED: "agent_install_failed";
+    readonly CLI_UPDATE_PROGRESS: "cli_update_progress";
+    readonly CLI_UPDATE_FAILED: "cli_update_failed";
+};
+type UserEventName = (typeof USER_EVENTS)[keyof typeof USER_EVENTS];
+
+/**
+ * Prompt the CLI sends to the user's linked agent (Claude, Codex, …)
+ * in a headless one-shot to detect how to start the project's dev
+ * server. Same pattern as the AI Insights "summary" prompt — the
+ * agent runs locally with the user's auth, has read access to the
+ * project, and returns a tiny JSON blob the CLI parses.
+ *
+ * Kept here (in `@codeam/shared`) so the CLI build inlines the
+ * exact string at compile time without runtime fetch from the backend.
+ */
+declare const PREVIEW_DETECT_PROMPT: string;
+
+export { AGENT_REGISTRY, type AgentAuth, type AgentAuthKind, type AgentId, type AgentMetadata, type AgentModel, type AnswerResolvedEvent, type AwaitingAnswerEvent, type BeadsActionCommand, type BeadsActionKind, type BeadsActionPayload, type BeadsActionRequest, type BeadsActionType, type BeadsConfigureAction, type BeadsDependencyDto, type BeadsDependencyKind, type BeadsIngestPayload, type BeadsIssueDto, type BeadsIssueStatus, type BeadsMemoryDto, type BeadsProjectDto, type BeadsProvisioningPayload, type BeadsProvisioningStatus, type BeadsSnapshotDto, type BeadsStatus, type BeadsStatusState, type BeadsStatusSummary, type BlameLineWire, type ChromeStep, type ChromeToolType, type CommitEntryWire, DEFAULT_API_BASE_URL, DEV_API_BASE_URL, type EnvVar, type FileBlameEvent, type FileChangeStatus, type FileChangedEvent, type FileHistoryEvent, type FileReviewStatus, HEADROOM_BACKEND_ENV, HEADROOM_EXTRAS_BY_SURFACE, HEADROOM_MODELS, HEADROOM_PIP_COMPANIONS, HEADROOM_PROXY_PORT, HEARTBEAT_INTERVAL_MS_DEFAULT, HOUSE_AGENT_ID, HOUSE_AGENT_NAME, HOUSE_AGENT_PROVIDER, HOUSE_AGENT_SUBTITLE, HOUSE_AGENT_VENDOR, type HeadroomBudgetCommand, type HeadroomBudgetPeriod, type HeadroomBudgetUsage, type HeadroomKind, type HeadroomModelSpec, type HeadroomPythonRenderOpts, type HeadroomStatus, type HeadroomSurface, type HunkLineType, INTERNAL_TO_PUBLIC, type InputSuggestionChunk, LINKED_AGENT_IDS, type LinkedAgentId, MODEL_CONTEXT_WINDOW, MODEL_PRICING, type ModelPricing, type NormalizedMessage, OBSERVER_BRIDGE_PORT, PREVIEW_DETECT_PROMPT, PROTOCOL_VERSION, PUBLIC_TO_INTERNAL, type PendingReviewHunkEvent, type PendingReviewHunkLine, type PreviewDetection, type PreviewErrorStage, type PreviewState, type PreviewStatus, type RemoteCommand, SSE_SOCKET_TIMEOUT_MS, type SelectPrompt, type StreamingChunkEvent, type StreamingChunkKind, TERMINAL_AGENT_PREFIX, USER_EVENTS, type UserEventName, getAgent, getContextWindow, getEnabledAgents, getPricing, headroomKindFor, headroomModelPredownloadScript, headroomPipPackage, headroomSnapshotDownloadLine, internalToPublic, isHeadroomWrappable, isKnownAgentId, isKnownModel, isLinkedAgentId, normalizeAgentId, publicToInternal, renderToLines, resolveApiBaseUrl, toRemoteCommand };