events.md

outline	deep

Events Reference

Devframe carries change notifications across channels of differing direction and reach: a node event bus, server RPC, and server-pushed broadcasts and shared state.

Two prefixes mark the wire surface: hub: for hub-layer server RPC (client → server), devframe: for the client-facing protocol (server → client). The internal event bus mirrors the subsystem vocabulary (docks, terminals, messages, commands) — docks:activate fans out to devframe:docks:activate.

Each name lives in code: HUB_EVENTS (@devframes/hub/constants) backs the hub tables, DEVFRAME_EVENTS (devframe/constants) the core ones.

Hub events

Internal node event bus

Each subsystem host emits on ctx.<subsystem>.events, consumed inside the same node process by createHubContext, which fans them onto the wire.

Event	Emitted by	Consumed by	Payload
docks:entry:updated	DocksHost.register / update	context → devframe:docks shared state	DevframeDockUserEntry
docks:activate	DocksHost.activate()	context → broadcast + devframe:docks:active	DevframeDockActivation
terminals:session:updated	TerminalsHost register / update / remove / status change	context → devframe:terminals:updated; terminals plugin	DevframeTerminalSession
messages:added / messages:updated / messages:removed / messages:cleared	MessagesHost mutations	context → devframe:messages:updated; messages plugin	entry / entry / id / —
commands:registered / commands:unregistered	CommandsHost register / update / unregister	context → devframe:commands shared state	entry / id

Server RPC methods — client → server

Method	Signature	Purpose
hub:docks:activate	({ dockId, params? }) => void	Ask the viewer to switch its active dock — see Deep Linking.
hub:commands:execute	(id, ...args) => unknown	Invoke a registered server command by id.
hub:messages:add	(input) => DevframeMessageEntry	Add a message to the feed (marked from: 'browser').
hub:messages:update	(id, patch) => DevframeMessageEntry | undefined	Patch a message by id.
hub:messages:remove	(id) => void	Remove a message by id.
hub:messages:clear	() => void	Remove every message.
hub:terminals:write	(id, data) => void	Send input to an interactive PTY session.
hub:terminals:resize	(id, cols, rows) => void	Resize an interactive PTY session.
hub:terminals:terminate	(id) => void	Kill a session's process, keeping it registered.
hub:terminals:restart	(id) => void	Re-run a session's command in place.
hub:terminals:remove	(id) => void	Kill a session's process and drop it from the registry.

Broadcasts & shared state — server → client

A hub-aware client reads or subscribes via rpc.client.register(...); the client host registers the devframe:docks:activate handler for you.

Name	Kind	Carries
devframe:docks:activate	broadcast	Live "switch active dock" request — the client host calls its local switchEntry.
devframe:terminals:updated	broadcast	Terminal sessions changed; re-read terminal state.
devframe:messages:updated	broadcast	Message list changed; re-read message state.
devframe:docks	shared state	Projected dock entry list (DevframeDockEntry[]).
devframe:docks:active	shared state	Most recent DevframeDockActivation, so a dock that mounts in response still converges on it.
devframe:commands	shared state	Serializable command list, handlers stripped (DevframeServerCommandEntry[]).
devframe:user-settings	shared state	Persisted per-workspace hub settings (DevframeDocksUserSettings).
devframe:terminals	streaming channel	Live terminal output stream, keyed by session id.

Core devframe events

This map covers notifications only; request/response RPC endpoints (devframe:rpc:server-state:*, devframe:streaming:subscribe, anonymous:devframe:auth, …) are typed in types/rpc-augments.ts, not events.

Node host bus

Emitted on ctx.agent.events; adapters (e.g. the MCP server) re-publish their manifest.

Event	Emitted by	Payload
agent:manifest:changed	any tool/resource/provider change	—
agent:tool:registered / agent:tool:unregistered	registerTool / unregisterTool	AgentTool / id
agent:resource:registered / agent:resource:unregistered	registerResource / unregisterResource	AgentResource / id

Client connection events

Emitted on the RPC client's rpc.events (RpcClientEvents) to track connection lifecycle and errors.

Event	Carries
rpc:is-trusted:updated	Trust gate flipped (boolean).
rpc:error	An RPC call rejected (error, method).
connection:status	Connection status changed (status, previous).
connection:error	A connection-level error (WebSocket errored, or trust refused).

Broadcasts — server → client

Pushed to subscribed clients, wired by the framework's own hosts.

Name	Carries
devframe:auth:revoked	This connection's bearer token was revoked; the client drops to untrusted.
devframe:rpc:client-state:updated	Full shared-state snapshot for a key.
devframe:rpc:client-state:patch	Incremental shared-state patch for a key.
devframe:streaming:chunk	A streaming chunk for a subscribed channel/id.
devframe:streaming:end	A streaming terminator (optionally an error).
devframe:streaming:upload-cancel	Server-side cancel of an in-flight upload.

Plus one postMessage channel, devframe:remote-assets-error, posted by the remote-assets fallback page to window.parent so an embedding viewer can replace the 502 page.