refactor: centralize event names in DEVFRAME_EVENTS / HUB_EVENTS maps

Introduce one source-of-truth event map per package and reference it from
every call site, so event/broadcast/shared-state/channel names stop living
as scattered string literals:

- packages/devframe/src/events.ts (DEVFRAME_EVENTS) — agent host bus events,
  client connection events, and server->client broadcasts; re-exported from
  devframe/constants.
- packages/hub/src/events.ts (HUB_EVENTS) — the docks/terminals/messages/
  commands bus events, hub: RPC methods, devframe: broadcasts, shared-state
  keys, and channels; re-exported from @devframes/hub/constants.

Call sites across both packages (plus hub-ui and the messages dev harness)
now reference the maps instead of literals. The unavoidable type-position
keys (EventEmitter<...> maps, RPC augmentation interfaces) mirror the maps.

Document the core devframe channels in the Events Reference and note that
the two maps back the page; add an AGENTS.md rule requiring the maps and
events.md to move together and forbidding magic event names.

Public constant types are preserved (DOCK_RENDERERS_STATE_KEY,
FRAME_NAV_CHANNEL, DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE stay `string`);
the snapshot change is purely the additive HUB_EVENTS / DEVFRAME_EVENTS.

Author: antfubot

AGENTS.md

@@ -41,6 +41,7 @@ Ahead-of-time build artifacts that live under `src/` - the shadow-root styleshee
 ## Conventions
 
 - RPC functions must use `defineRpcFunction`; always namespace IDs `devframes:plugin:<slug>:<fn-name>` (matching the plugin's `@devframes/plugin-<slug>` package name).
+- **No magic event names — use the centralized event maps.** Every event, broadcast, shared-state key, and channel name lives in one of two source-of-truth maps: `DEVFRAME_EVENTS` (`packages/devframe/src/events.ts`, re-exported from `devframe/constants`) for the core runtime, and `HUB_EVENTS` (`packages/hub/src/events.ts`, re-exported from `@devframes/hub/constants`) for the hub. Reference `DEVFRAME_EVENTS.*` / `HUB_EVENTS.*` at call sites (`.events.emit`/`.on`, `rpc.broadcast({ method })`, `sharedState.get(key)`, `defineHubRpcFunction({ name })`, `rpc.call`) instead of re-typing a string literal. The two maps and the [`docs/guide/events.md`](docs/guide/events.md) Events Reference are kept in lockstep: adding, renaming, or removing a name means editing the map **and** that page in the same change — every name in the maps appears in the tables, and vice versa. The only literals left are unavoidable type-position keys (the `EventEmitter<…>` maps in `types/*` and the `DevframeRpcClientFunctions`/`DevframeRpcServerFunctions` augmentations), which mirror the maps; a package that deliberately avoids a hub dependency (e.g. `@devframes/plugin-terminals`, which models the hub bridge structurally) keeps a local literal rather than importing `HUB_EVENTS`.
 - **Stay validator-neutral.** `devframe` and every `@devframes/*` package must not introduce a preferred schema validator dependency - no `valibot`, `zod`, `arktype`, etc. in their runtime `dependencies`. `args`/`returns`/flag schemas are typed against [Standard Schema](https://standardschema.dev/) (`@standard-schema/spec`, types-only); first-party code that needs to author a schema uses the built-in zero-dep `devframe/utils/simple-schema` builder (deliberately minimal - not a general validator). JSON-schema conversion uses each schema's own Standard JSON Schema converter (`~standard.jsonSchema`, implemented by e.g. zod 4) when present and degrades to a permissive object otherwise - no converter library and no vendor dependency is required. Docs, by contrast, should point *users* at a real validator for their own integrations - recommend **valibot** (lightest) or **zod** (worth reusing if they already pull it via the JSON-render or MCP integrations).
 - Shared state via `devframe/utils/shared-state`; keep values serializable.
 - Utility imports use the package-path form `devframe/utils/*`, never relative `../utils/*`.

docs/guide/events.md

@@ -2,13 +2,17 @@
 outline: deep
 ---
 
-# Hub Events Reference
+# Events Reference
 
-The hub carries change notifications across three distinct channels. What separates them is **direction and reach**: an in-process event bus that never leaves the node process, server RPC methods a client calls, and server-pushed broadcasts and shared state a client reads.
+Devframe carries change notifications across a few distinct channels. What separates them is **direction and reach**: an in-process event bus that never leaves the node process, server RPC methods a client calls, and server-pushed broadcasts and shared state a client reads.
 
 Two naming prefixes mark the wire surface: `hub:` for hub-layer server RPC (client → server actions), and `devframe:` for the client-facing devframe protocol (broadcasts, shared state, and streams pushed server → client). The internal event bus mirrors the same plural subsystem vocabulary (`docks`, `terminals`, `messages`, `commands`), so each internal event lines up with its wire counterpart — `docks:activate` fans out to `devframe:docks:activate`.
 
-## Internal node event bus
+Every name on this page has one home in code: the [`HUB_EVENTS`](https://github.com/devframes/devframe/blob/main/packages/hub/src/events.ts) map (`@devframes/hub/constants`) backs the hub tables, and the [`DEVFRAME_EVENTS`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/events.ts) map (`devframe/constants`) backs the core tables. Call sites reference `HUB_EVENTS.*` / `DEVFRAME_EVENTS.*` rather than re-typing a literal, and this page and those maps move together — changing one without the other is a bug.
+
+## Hub events
+
+### Internal node event bus
 
 Each subsystem host emits on `ctx.<subsystem>.events`. These fire and are consumed **inside the same node process** — chiefly by `createHubContext`, which fans them out onto the wire. They never cross to the browser.
 
@@ -22,7 +26,7 @@ Each subsystem host emits on `ctx.<subsystem>.events`. These fire and are consum
 
 The `docks:entry:updated` and `terminals:session:updated` middle nouns (`entry`, `session`) name the specific record type; the messages and commands subsystems imply their record in the subsystem name, so they carry the verb directly.
 
-## Server RPC methods — client → server
+### Server RPC methods — client → server
 
 A connected client (any mounted iframe or panel, on its own RPC client) calls these; the hub node handles them. Carry the `hub:` prefix.
 
@@ -40,7 +44,7 @@ A connected client (any mounted iframe or panel, on its own RPC client) calls th
 | `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
+### Broadcasts & shared state — server → client
 
 The server pushes these; a hub-aware client reads or subscribes. Carry the `devframe:` prefix. A UI subscribes to broadcasts via `rpc.client.register(...)`; the [client host](./client-context) registers the `devframe:docks:activate` handler for you.
 
@@ -56,3 +60,45 @@ The server pushes these; a hub-aware client reads or subscribes. Carry the `devf
 | `devframe:terminals` | streaming channel | Live terminal output stream, keyed by session id. |
 
 The [`devframe:docks:active`](./shared-state) mirror pairs with the `devframe:docks:activate` broadcast: the broadcast reaches docks already on screen, while the mirror lets a dock that mounts *because* of the switch converge on the same request instead of missing it.
+
+## Core devframe events
+
+The core `devframe` runtime (below the hub) carries its own notification channels — the agent host's change events, the client connection lifecycle, and the server-pushed broadcasts that power shared state and streaming. These are backed by `DEVFRAME_EVENTS` (`devframe/constants`).
+
+This map covers notifications only. The request/response RPC endpoints of the shared-state, streaming, and auth-handshake protocols (`devframe:rpc:server-state:*`, `devframe:streaming:subscribe`, `anonymous:devframe:auth`, …) are defined at their handlers and typed in `types/rpc-augments.ts` — they aren't events.
+
+### Node host bus
+
+Emitted on `ctx.agent.events` as the agent-exposed tool/resource surface changes; protocol adapters (e.g. the MCP server) subscribe to 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` emitter (`RpcClientEvents`) for a UI to track connection lifecycle and surface 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 from the server to subscribed clients over the `devframe:` protocol. Wired by the framework's own hosts; not registered manually.
+
+| 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`, that the remote-assets fallback page posts to `window.parent` so an embedding viewer can replace the bare 502 page with its own UI.

packages/devframe/src/adapters/mcp/build-server.ts

@@ -8,6 +8,7 @@ import { Server } from '@modelcontextprotocol/server'
 import { createHostContext } from 'devframe/node'
 import { toAgentToolName } from 'devframe/utils/agent-tool-name'
 import { join } from 'pathe'
+import { DEVFRAME_EVENTS } from '../../events'
 import { diagnostics } from '../../node/diagnostics'
 import { formatMcpError, stringifyForMcp } from './stringify'
 import { argsToJsonSchema, returnToJsonSchema } from './to-json-schema'
@@ -70,7 +71,7 @@ export function buildMcpServerFromContext(
   const notify = (method: string): void => {
     server.notification({ method }).catch(() => { /* ignore transport errors */ })
   }
-  const offManifest = ctx.agent.events.on('agent:manifest:changed', () => {
+  const offManifest = ctx.agent.events.on(DEVFRAME_EVENTS.bus.agentManifestChanged, () => {
     notify('notifications/tools/list_changed')
     notify('notifications/resources/list_changed')
   })

packages/devframe/src/client/rpc-live.ts

@@ -3,6 +3,7 @@ import type { ConnectionMeta, DevframeRpcClientFunctions, DevframeRpcServerFunct
 import type { DevframeConnectionStatus } from './connection'
 import type { DevframeClientRpcHost, DevframeRpcClientMode, DevframeRpcClientOptions, RpcClientEvents } from './rpc'
 import { createRpcClient } from 'devframe/rpc/client'
+import { DEVFRAME_EVENTS } from '../events'
 import { promiseWithResolver } from '../utils/promise'
 import { DevframeConnectionError } from './connection'
 
@@ -65,7 +66,7 @@ export function createLiveRpcClientMode(
       return
     const previous = status
     status = next
-    events.emit('connection:status', next, previous)
+    events.emit(DEVFRAME_EVENTS.client.connectionStatus, next, previous)
   }
 
   // Pending calls we can settle proactively — a connection that drops (or a
@@ -99,7 +100,7 @@ export function createLiveRpcClientMode(
           if (settled)
             return
           finish()
-          events.emit('rpc:error', error, method)
+          events.emit(DEVFRAME_EVENTS.client.error, error, method)
           reject(error)
         },
       }
@@ -127,7 +128,7 @@ export function createLiveRpcClientMode(
             return
           finish()
           const err = error instanceof Error ? error : new Error(String(error))
-          events.emit('rpc:error', err, method)
+          events.emit(DEVFRAME_EVENTS.client.error, err, method)
           reject(err)
         },
       )
@@ -148,7 +149,7 @@ export function createLiveRpcClientMode(
     definitions,
     onError(error) {
       setStatus('error', error)
-      events.emit('connection:error', error)
+      events.emit(DEVFRAME_EVENTS.client.connectionError, error)
       rejectAllPending(new DevframeConnectionError('connection', '[devframe] Connection to the devframe server failed', { cause: error }))
     },
     onDisconnected() {
@@ -169,15 +170,15 @@ export function createLiveRpcClientMode(
 
   // Handle server-initiated auth revocation
   clientRpc.register({
-    name: 'devframe:auth:revoked',
+    name: DEVFRAME_EVENTS.broadcast.authRevoked,
     type: 'event',
     handler: () => {
       isTrusted = false
       const authError = new DevframeConnectionError('auth', '[devframe] The devframe server revoked this client\'s trust')
       setStatus('unauthorized', authError)
-      events.emit('connection:error', authError)
+      events.emit(DEVFRAME_EVENTS.client.connectionError, authError)
       rejectAllPending(authError)
-      events.emit('rpc:is-trusted:updated', false)
+      events.emit(DEVFRAME_EVENTS.client.isTrustedUpdated, false)
     },
   })
 
@@ -209,9 +210,9 @@ export function createLiveRpcClientMode(
       // so it never lands here.
       const authError = new DevframeConnectionError('auth', '[devframe] The devframe server refused this client\'s credentials')
       setStatus('unauthorized', authError)
-      events.emit('connection:error', authError)
+      events.emit(DEVFRAME_EVENTS.client.connectionError, authError)
     }
-    events.emit('rpc:is-trusted:updated', isTrusted)
+    events.emit(DEVFRAME_EVENTS.client.isTrustedUpdated, isTrusted)
     return result.isTrusted
   }
 
@@ -228,7 +229,7 @@ export function createLiveRpcClientMode(
       isTrusted = true
       trustedPromise.resolve(true)
       setStatus('connected')
-      events.emit('rpc:is-trusted:updated', true)
+      events.emit(DEVFRAME_EVENTS.client.isTrustedUpdated, true)
     }
     return token
   }
@@ -284,7 +285,7 @@ export function createLiveRpcClientMode(
       const method = String(args[0])
       const failFast = terminalError()
       if (failFast) {
-        events.emit('rpc:error', failFast, method)
+        events.emit(DEVFRAME_EVENTS.client.error, failFast, method)
         return Promise.reject(failFast)
       }
       return guardCall(
@@ -300,7 +301,7 @@ export function createLiveRpcClientMode(
       // to send, so surface the failure and drop it instead of queuing forever.
       const failFast = terminalError()
       if (failFast) {
-        events.emit('rpc:error', failFast, String(args[0]))
+        events.emit(DEVFRAME_EVENTS.client.error, failFast, String(args[0]))
         return
       }
       return serverRpc.$callEvent(
@@ -312,7 +313,7 @@ export function createLiveRpcClientMode(
       const method = String(args[0])
       const failFast = terminalError()
       if (failFast) {
-        events.emit('rpc:error', failFast, method)
+        events.emit(DEVFRAME_EVENTS.client.error, failFast, method)
         return Promise.reject(failFast)
       }
       return guardCall(

packages/devframe/src/client/rpc-shared-state.ts

@@ -2,6 +2,7 @@ import type { RpcSharedStateGetOptions, RpcSharedStateHost } from 'devframe/type
 import type { SharedState, SharedStatePatch } from 'devframe/utils/shared-state'
 import type { DevframeRpcClient } from './rpc'
 import { createSharedState } from 'devframe/utils/shared-state'
+import { DEVFRAME_EVENTS } from '../events'
 
 export function createRpcSharedStateClientHost(rpc: DevframeRpcClient): RpcSharedStateHost {
   const sharedState = new Map<string, SharedState<any>>()
@@ -20,7 +21,7 @@ export function createRpcSharedStateClientHost(rpc: DevframeRpcClient): RpcShare
   }
 
   rpc.client.register({
-    name: 'devframe:rpc:client-state:updated',
+    name: DEVFRAME_EVENTS.broadcast.clientStateUpdated,
     type: 'event',
     handler: (key: string, fullState: any, syncId: string) => {
       const state = sharedState.get(key)
@@ -31,7 +32,7 @@ export function createRpcSharedStateClientHost(rpc: DevframeRpcClient): RpcShare
   })
 
   rpc.client.register({
-    name: 'devframe:rpc:client-state:patch',
+    name: DEVFRAME_EVENTS.broadcast.clientStatePatch,
     type: 'event',
     handler: (key: string, patches: SharedStatePatch[], syncId: string) => {
       const state = sharedState.get(key)
@@ -124,7 +125,7 @@ export function createRpcSharedStateClientHost(rpc: DevframeRpcClient): RpcShare
         if (!rpc.isTrusted) {
           resolve(state)
           let initialized = false
-          rpc.events.on('rpc:is-trusted:updated', (isTrusted) => {
+          rpc.events.on(DEVFRAME_EVENTS.client.isTrustedUpdated, (isTrusted) => {
             if (isTrusted && !initialized) {
               initialized = true
               initSharedState()

packages/devframe/src/client/rpc-streaming.ts

@@ -1,6 +1,7 @@
 import type { StreamErrorPayload, StreamReader, StreamSink } from 'devframe/utils/streaming-channel'
 import type { DevframeRpcClient } from './rpc'
 import { createStreamReader, createStreamSink } from 'devframe/utils/streaming-channel'
+import { DEVFRAME_EVENTS } from '../events'
 
 const STREAM_KEY_SEPARATOR = '\x1F'
 
@@ -46,7 +47,7 @@ export function createRpcStreamingClientHost(rpc: DevframeRpcClient): RpcStreami
   const uploads = new Map<string, StreamSink<any>>()
 
   rpc.client.register({
-    name: 'devframe:streaming:chunk',
+    name: DEVFRAME_EVENTS.broadcast.streamingChunk,
     type: 'event',
     handler(channel: string, id: string, seq: number, chunk: any) {
       const reader = readers.get(streamKey(channel, id))
@@ -55,7 +56,7 @@ export function createRpcStreamingClientHost(rpc: DevframeRpcClient): RpcStreami
   })
 
   rpc.client.register({
-    name: 'devframe:streaming:end',
+    name: DEVFRAME_EVENTS.broadcast.streamingEnd,
     type: 'event',
     handler(channel: string, id: string, error?: StreamErrorPayload) {
       const key = streamKey(channel, id)
@@ -68,7 +69,7 @@ export function createRpcStreamingClientHost(rpc: DevframeRpcClient): RpcStreami
   })
 
   rpc.client.register({
-    name: 'devframe:streaming:upload-cancel',
+    name: DEVFRAME_EVENTS.broadcast.streamingUploadCancel,
     type: 'event',
     handler(channel: string, id: string) {
       const key = streamKey(channel, id)
@@ -87,7 +88,7 @@ export function createRpcStreamingClientHost(rpc: DevframeRpcClient): RpcStreami
   // OR the WS dropped briefly (state intact). Either way, sending `subscribe`
   // with `afterSeq: lastSeenSeq` is the right thing: the server replays
   // missed chunks if it has them, otherwise starts fresh.
-  rpc.events.on('rpc:is-trusted:updated', (isTrusted) => {
+  rpc.events.on(DEVFRAME_EVENTS.client.isTrustedUpdated, (isTrusted) => {
     if (!isTrusted)
       return
     for (const [key, reader] of readers) {
@@ -142,7 +143,7 @@ export function createRpcStreamingClientHost(rpc: DevframeRpcClient): RpcStreami
       })
     }
     else {
-      const off = rpc.events.on('rpc:is-trusted:updated', (trusted) => {
+      const off = rpc.events.on(DEVFRAME_EVENTS.client.isTrustedUpdated, (trusted) => {
         if (trusted) {
           off()
           if (readers.has(key) && !reader.cancelled && !reader.done) {

packages/devframe/src/constants.ts

@@ -1,3 +1,7 @@
+import { DEVFRAME_EVENTS } from './events'
+
+export { DEVFRAME_EVENTS } from './events'
+
 // Devframe runtime routes and static output conventions.
 export const DEVFRAME_CONNECTION_META_FILENAME = '__connection.json'
 
@@ -88,7 +92,7 @@ export const DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM = 'devframe_viewer_origin_
  * (`@devframes/hub-ui` does, in its iframe view). Payload shape:
  * `RemoteAssetsErrorMessage` (`devframe/types`).
  */
-export const DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE = 'devframe:remote-assets-error'
+export const DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE: string = DEVFRAME_EVENTS.postMessage.remoteAssetsError
 
 /**
  * Prefix that marks an RPC method as callable before a connection is