guanghu/docs/adr/0133-request-scoped-ai-stream-events.md

type, id, title, status, date

type	id	title	status	date
ADR	0133	Request-scoped AI stream event channels	active	2026-05-29

Context

AI agent streams and direct model streams used shared Tauri event names (ai-agent-stream and ai-model-stream). That worked while only one stream of each kind was active, but the side AI workspace and pop-out window can make concurrent or rapidly reused AI sessions more likely. Shared channels risk routing deltas, tool events, or completion events to the wrong renderer listener.

Decision

Each native AI stream uses a request-scoped Tauri event channel generated by the renderer and validated by the backend.

The renderer creates a unique event name with the stream's stable base prefix, listens on that channel, and passes it to the stream_ai_agent or stream_ai_model command as event_name. The Rust command accepts only scoped names that match the expected base prefix and safe character set; invalid or missing names fall back to the legacy shared channel.

Alternatives considered

• Request-scoped renderer channel (chosen): isolates simultaneous streams without changing the stream event payload shape, while preserving backward-compatible command defaults.
• Keep shared static event names: simpler, but concurrent agent/model sessions can cross-deliver stream events between workspaces or chats.
• Backend-generated channel names: centralizes validation, but requires a setup handshake before the renderer can subscribe and complicates the current fire-and-stream command flow.

Consequences

Concurrent AI streams can run without contaminating each other's renderer callbacks. The backend keeps a narrow validation boundary for externally supplied event names. Any future AI streaming command should follow the same base-prefix plus scoped-suffix convention instead of adding another process-wide static channel.