Events Reference

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 `BroadcastChannel`s

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).

When Clauses

When clauses gate visibility and executability of docks, commands, and custom UI via VS Code's when-clause contexts. The evaluator whenexpr re-exports at devframe/utils/when.

Node-Side API

Lookup tables for the node side: DevframeDefinition fields, CLI options, storage scopes, RPC function types, broadcast options, streaming lifecycle, remote assets, the cross-devframe services surface, diagnostics prefixes, and the auth surface.