Module mps 

AgentMux Pub/Sub system: event brokering with scoped subscriptions. Port of Go’s pkg/wps/wps.go + wpstypes.go (Wave Terminal’s original names).

The Broker supports:

• All-scope subscriptions (receive all events of a type)
• Exact-scope subscriptions (e.g., “block:uuid”)
• Star-scope subscriptions (e.g., “block:*”)
• Event persistence (history/replay)

Structs

Broker

The central pub/sub broker for MuxEvents.

BrokerInner 🔒

BrokerSubscription 🔒

MuxEvent

One event on the broker. The envelope is typed; data is each event’s own payload, still untyped (any) on the frontend: srv builds most payloads with json!, so there is no Rust type per event to generate yet.

PersistEventWrap 🔒

PersistKey 🔒

StreamPos

One transcript stream’s position for an append: the records it wrote are lines line .. lines of generation gen of stream.

SubscriptionRequest

WSFileEventData

Constants

EVENT_AGENT_CONTEXT_USAGE

Where an agent process will auto-compact, as its CLI reports it. See agent_context_usage.rs.

EVENT_AGENT_FAILURE

Fired when an agent subprocess exits non-zero (or reports an error on its terminal result frame). Carries the classified AgentFailure so the pane shows the real cause instead of a bare exit code.

EVENT_AGENT_MESSAGE_ACCEPTED

Fired by SubprocessController::spawn_turn when a user message is picked up (either direct-spawn or queue drain). Frontend uses this to promote pending PendingMessage entries into the conversation document. Payload: { block_id, message_id }.

EVENT_AGENT_RESUME_RETRY

Fired by the persistent controller’s stale---resume recovery path (retry_after_resume_failure / publish_resume_retry_status, docs/status/STATUS_STALE_RESUME_LIVE_REPRO_AND_FIX_PLAN_2026_08_23.md §6.2) so the pane can show a “Reconnecting…” readout instead of going silent for the ~seconds-to-tens-of-seconds it can take the controller to detect a stale registry session_id and respawn against a recovered one. Payload: { "status": "retrying", "startedAt": "<rfc3339>" } or { "status": "resolved" }. persist: 2 (unlike compaction_started’s persist: 0) is deliberate: both ends of this signal travel over this same MPS channel (there’s no separate out-of-band completion marker the way compact_boundary is for compaction), so replaying the latest retrying→resolved pair to a freshly (re)subscribed pane is always the correct current state, not a stale echo — see publish_resume_retry_status’s own doc comment for why 2, not 1.

EVENT_AGENT_RUNTIME

What an agent process was actually spawned with. See agent_runtime.rs.

EVENT_AGENT_TURN

The agent’s turn as the user sees it, over however many CLI passes. See blockcontroller::health::TurnLedger.

EVENT_ATTACHMENT_BATCH_DONE

EVENT_ATTACHMENT_FAILED

EVENT_ATTACHMENT_PROGRESS

Image attachment processing (SPEC_AGENT_PANE_IMAGE_ATTACHMENTS_2026_09_26.md §6.5). Scoped block:<id> of the pane that started the batch. Payloads are AttachmentProgressEvent / AttachmentReadyEvent / AttachmentFailedEvent / AttachmentBatchDoneEvent in rpc_types::attachments.

EVENT_ATTACHMENT_READY

EVENT_BLOCK_ACTIVITY

Fired by the agent-pane PTY read loop when an OSC 0/2 window-title sequence from Claude Code is extracted. Carries the normalised conversation-topic string so the frontend can surface it as a term:osc_title tab label. Payload: { "blockId": "...", "activity": "auth refactor" }.

EVENT_BLOCK_CLOSE

EVENT_BLOCK_FILE

EVENT_BLOCK_STATS

EVENT_BTW_ANSWER_CHUNK

Fired by the /btw slash command’s one-shot side-question turn (server/agent_handlers/side_question.rs, AskSideQuestionCommand) — one event per AgentEvent translated from the throwaway turn’s stream-json output (same ClaudeTranslator the drone Agent block runner uses, agents/translator/claude.rs), plus a final event with "done": true when the turn completes (successfully, with an error, or via a timeout/no-response fallback).

EVENT_CONFIG

EVENT_CONN_CHANGE

EVENT_CONTROLLER_STATUS

EVENT_CRON_CHANGED

Fired whenever a cron job is created, fires, is paused/resumed, or deleted (SPEC_SWARM_LONG_RUNNING_PROCESS_ROWS_2026_07_20 Phase 2). Payload-free, unscoped — the Swarm pane just reloads the full list via cron.ListActive on receipt, the same “any event of this type ⇒ refetch” pattern shell_node_create/shell_chunk(op:"exit") already use.

EVENT_DOCK_CLEAR

Fired by handle_muxspect_dock_clear when a muxspect dock clear request is served. Scoped block:<id>, same convention as shell_node_create — only a renderer currently displaying that block receives it. Payload: { node_id }. The receiving renderer flips that one ToolNode to status: "canceled" via the ForceCancelToolNode document-reducer command; a renderer without that node (already resolved, or a different pane’s block) no-ops. See docs/specs/SPEC_MUXSPECT_DOCK_DIAGNOSIS_AND_REMEDIATION_2026_08_06.md §3.2.

EVENT_INSTALL_PROGRESS

EVENT_MUX_OBJ_UPDATE

EVENT_REMOTES_CHANGE

The Connectors → Remotes list changed in a way connchange doesn’t cover: a remote’s settings, or a recent one forgotten (SPEC_REMOTES_PANE_2026_10_05.md §4.6).

EVENT_ROUTE_GONE

EVENT_SHELL_CHUNK

Fired per stdout/stderr line and on process exit by ShellNodeRunner. op: "chunk" carries { shell_id, kind, content, timestamp }; op: "exit" carries { shell_id, exit_code, timestamp }.

EVENT_SHELL_NODE_CREATE

Fired by handle_shell_create when a persistent shell is launched. Frontend creates the ShellNode row on receipt. Payload: { shell_id, cmd, cwd?, title, timestamp }.

EVENT_SUBAGENT_BACKFILL_STATUS

Fired by SubagentWatcher::scan_session_subagents (the pane-reopen cold-backfill entry point, subagent_watcher/scan.rs) so a pane can show its BrainSpinner overlay (block.tsx’s ready() gate) until its own subagent/dispatch history has actually finished backfilling, instead of exposing the Activity Dock’s genuinely-changing intermediate states — see docs/retro/retro-activity-dock-flicker-survives-debounce-fix-2026-08-24.md §5 option 1/2. Payload: { "status": "started" | "done" }. persist: 2, same rationale as EVENT_AGENT_RESUME_RETRY above — both ends travel over this one channel, so a mount-time EventReadHistoryCommand read (guarding the same “pane subscribed after the backend already finished” race that event’s own hook already handles) always recovers the correct current status rather than a stale one.

EVENT_SYS_INFO

EVENT_USER_ATTENTION

A call to action srv holds open started or ended: { key, block_id, kind, text, window_ids, active } (backend/user_attention.rs).

EVENT_USER_INPUT

EVENT_WIDGET_PACKAGES

The widget packages changed: installed, approved, edited, removed (SPEC_USER_WIDGETS_AND_WIDGET_API_2026_10_09.md §8). Payload { packages }.

EVENT_WIDGET_REQUESTS

Agents’ widget install requests waiting for the user: { requests }.

EVENT_WIDGET_STORAGE

A widget package’s storage changed: { id, keys }, never the values.

FILE_OP_APPEND

FILE_OP_CREATE

FILE_OP_DELETE

FILE_OP_INVALIDATE

FILE_OP_REPLACE

A transcript output replaced by other content (restore): pos names the new generation and its line count (Phase 5a-3).

FILE_OP_TRUNCATE

MAX_PERSIST 🔒

REMAKE_ARR_THRESHOLD 🔒

Traits

WpsClient

Trait for event delivery to connected clients.

Functions

add_to_scope_map 🔒

add_unique 🔒

is_zero 🔒

publish_block_activity

Publish a Claude Code OSC window-title activity string to the frontend for a given agent-pane block. Frontend subscribes to block:activity events scoped to block:{block_id} and writes the payload to term:osc_title block metadata, which the tab label reads.

publish_install_progress

Publish a single install-progress line to the frontend for a given block. The frontend subscribes to install_progress events scoped to block:{block_id} and displays each message as a log line in the agent presentation view.

remove_from_all_scopes 🔒

scope_has_star 🔒

star_match 🔒

Simple star matching: each segment separated by sep is compared. “*” matches any single segment, “**” matches any remaining segments.

Type Aliases

BrokerObserver

See Broker::add_observer.

ReplayKey 🔒

Tracks (route_id, event_name, scope) tuples whose persisted history has already been replayed to a given route. Skipping replay on resubscribe prevents the frontend’s eventsub flushes (sent on every listener add/remove, once per conn_id) from re-emitting completed bash logs on every pane mount or tab switch. Codex P2 on PR #817; route keying updated PR #1418.