3.events.md

title	Events Reference
navigation	icon i-lucide-radio-tower
description	Devframe carries change notifications through client contexts, node event buses, RPC, broadcasts, and shared state.

Devframe carries change notifications through client contexts, node event buses, RPC, broadcasts, and shared state.

Two prefixes mark the wire protocol: 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

Client-context events

Client scripts subscribe to these events on the client context inside the host page.

Event	Emitter	Payload
panel:state:changed	ctx.panel.events	DevframeDockPanelState

ctx.panel.state supplies the current snapshot when a client script loads. Later open, close, dock selection, and hub UI provider visibility changes emit panel:state:changed. The snapshot contains state: 'open' | 'closed' | 'hidden' and an optional selectedDockId.

Internal node event bus

Each subsystem 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; the terminals devframe	DevframeTerminalSession
messages:added / messages:updated / messages:removed / messages:cleared	MessagesHost mutations	context → devframe:messages:updated; the messages devframe	entry / entry / id / none
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 hub UI provider 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 RPC client reads or subscribes via rpc.client.register(...); the client runtime registers the devframe:docks:activate handler for you.

Name	Kind	Carries
devframe:docks:activate	broadcast	Live "switch active dock" request; the client runtime 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 project-scope hub settings (DevframeDocksUserSettings).
devframe:terminals	streaming channel	Live terminal output stream, keyed by session id.

Same-origin BroadcastChannels

Used on a static backend, where no live server can relay a client's request to its sibling browsing contexts.

Name	Posted by	Carries
devframe:docks:activate	a panel iframe (e.g. the messages panel's activate actions)	The { dockId, params? } activation; the client runtime in the host page switches the dock locally.

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 event 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	none
agent:tool:registered / agent:tool:unregistered	registerTool / unregisterTool	AgentTool / id
agent:resource:registered / agent:resource:unregistered	registerResource / unregisterResource	AgentResource / id

RPC 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 RPC clients, wired by the core node side.

Name	Carries
devframe:auth:revoked	This connection's bearer token was revoked; the RPC 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.

In-page channel notifications (page script → panel)

Pushed over each panel's in-page channel port; the paired request methods (devframe:in-page:page-state:subscribe/set/patch) are call endpoints defined at their handlers, not events.

Name	Carries
devframe:in-page:panel-state:updated	Full channel shared-state snapshot for a key.
devframe:in-page:panel-state:patch	Incremental channel shared-state patch for a key.

postMessage channels

Name	Posted by	Carries
devframe:remote-assets-error	the remote-assets fallback page, to window.parent	The failed package/version/reason, so an embedding hub UI provider can replace the 502 page.
devframe:in-page-channel	both in-page channel endpoints, across window boundaries	The versioned handshake envelope (panel hello, page-script port grant).