AGENTS.md@crates/common/vtcode-desktop-protocol git:20261028.fc84ebeA

Immutable. This exact content never changes and is served at /api/v1/blob/0782a8361bd3b078.

# vtcode-desktop-protocol

[Root AGENTS.md](../../../AGENTS.md) | Internal wire contract for the desktop app and local service.

## Conventions

- Keep messages typed and framing bounded; Git review echoes request/workspace identities to reject stale snapshots.
- Preserve opaque interaction option identities across the wire. `sharedUi` carries only non-secret CLI preferences.
- For `interaction/respond`, validate without consuming, enqueue to the active runtime, then resolve; failed delivery
  must leave it retryable.
- `sessionOptions` are typed idle-session selections;
  `availableModes` contains CLI-discovered primary-agent metadata. Resource names are bounded CLI-safe tokens.
- Primary-agent display notifications are ephemeral and session-scoped; keep configured `sessionOptions.mode` separate.
- `config/theme` accepts a built-in CLI theme ID. Settings DTOs carry bounded dotted keys and JSON values, never
  config file paths, full TOML, or credentials.
- Use `vtcode-exec-events` history types; review/activity snapshots never replay live lifecycle events.
- Hidden model-only history rows retain archive indices; only system rows may be omitted from the visible transcript.
- The live event channel (`live_event_channel`) coalesces under saturation: snapshots replace per item,
  plan deltas merge, ordered events are only dropped when nothing coalescable remains. A slow consumer
  must never fail the producing turn; only a dropped consumer half is fatal.

## Dependencies

- `serde` and `serde_json` (wire encoding)
- `tokio` (bounded asynchronous stdio framing)
- `vtcode-exec-events` (canonical runtime event payloads)