devframe 0.9.0 → 0.9.1

package/dist/{_shared-CbZ_yhbz.mjs → _shared-BM3PdYli.mjs}

@@ -1,5 +1,5 @@
 import "./constants.mjs";
-import { n as getPort } from "./dist-eNI9qM_I.mjs";
+import { n as getPort } from "./dist-CZXfGEkd.mjs";
 import { cleanDoubleSlashes, withLeadingSlash, withTrailingSlash, withoutLeadingSlash } from "ufo";
 //#region src/adapters/_shared.ts
 const DEFAULT_PORT = 9999;

package/dist/{_shared-BPmX9fqK.d.mts → _shared-DqbKCAew.d.mts}

@@ -1,4 +1,4 @@
-import { d as ConnectionMeta, l as McpRouteOptions, n as DevframeDefinition, r as DevframeDeploymentKind } from "./devframe-DJMg0WLe.mjs";
+import { d as ConnectionMeta, l as McpRouteOptions, n as DevframeDefinition, r as DevframeDeploymentKind } from "./devframe-BlLEZR-x.mjs";
 //#region src/adapters/_shared.d.ts
 /**
  * Resolve the mount base path for a devframe's SPA. Hosted adapters

package/dist/adapters/build.d.mts

@@ -1,4 +1,4 @@
-import { n as DevframeDefinition } from "../devframe-DJMg0WLe.mjs";
+import { n as DevframeDefinition } from "../devframe-BlLEZR-x.mjs";
 import { o as StaticAssetsSource } from "../remote-assets-Bg4gCUZ_.mjs";
 //#region src/adapters/build.d.ts
 interface CreateBuildOptions {

package/dist/adapters/build.mjs

@@ -3,14 +3,14 @@ import { n as strictJsonStringify } from "../serialization-BGzEwAdr.mjs";
 import { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME } from "../constants.mjs";
 import { t as collectStaticRpcDump } from "../static-BPZ1_OPA.mjs";
 import { n as structuredCloneStringify } from "../structured-clone-CbAV5rFI.mjs";
-import { t as diagnostics } from "../diagnostics-DOQPnQmX.mjs";
-import { t as createHostContext } from "../context-CEe4PBz1.mjs";
-import { t as resolveStaticAssetsSource } from "../remote-assets-nTTxY2MU.mjs";
-import { t as createH3DevframeHost } from "../host-h3-Crkzm42q.mjs";
+import { t as diagnostics } from "../diagnostics-Di8ytitn.mjs";
+import { t as createHostContext } from "../context-Bdkakk8S.mjs";
+import { t as resolveStaticAssetsSource } from "../remote-assets-DRfY2RjX.mjs";
+import { t as createH3DevframeHost } from "../host-h3-fRbF9yor.mjs";
+import process from "node:process";
+import { dirname, resolve } from "pathe";
 import { existsSync } from "node:fs";
 import fs$1 from "node:fs/promises";
-import { dirname, resolve } from "pathe";
-import process from "node:process";
 //#region src/adapters/build.ts
 /**
 * Produce a self-contained static deploy of a devframe:
@@ -47,7 +47,9 @@ async function createBuild(d, options = {}) {
 		mode: "build",
 		host
 	});
+	for (const input of d.services ?? []) ctx.services.install(input, { resolveFrom: d.packageName });
 	await d.setup(ctx);
+	await ctx.services.ready();
 	await fs$1.mkdir(resolve(outDir, DEVFRAME_RPC_DUMP_DIRNAME), { recursive: true });
 	const jsonSerializableMethods = [];
 	for (const def of ctx.rpc.definitions.values()) if (def.jsonSerializable === true) jsonSerializableMethods.push(def.name);

package/dist/adapters/cac.d.mts

@@ -1,4 +1,4 @@
-import { At as defineCliFlags, Ot as CliFlagsSchema, jt as parseCliFlags, kt as InferCliFlags, n as DevframeDefinition } from "../devframe-DJMg0WLe.mjs";
+import { Ft as CliFlagsSchema, It as InferCliFlags, Lt as defineCliFlags, Rt as parseCliFlags, n as DevframeDefinition } from "../devframe-BlLEZR-x.mjs";
 import { CAC } from "cac";
 import { H3 } from "h3";
 //#region src/adapters/cac.d.ts

package/dist/adapters/cac.mjs

@@ -1,7 +1,7 @@
 import { s as colors } from "../nostics-CzECRXpE.mjs";
-import { r as resolveDevServerPort } from "../_shared-CbZ_yhbz.mjs";
+import { r as resolveDevServerPort } from "../_shared-BM3PdYli.mjs";
 import { createBuild } from "./build.mjs";
-import { t as createDevServer } from "../dev--rAPzbvO.mjs";
+import { t as createDevServer } from "../dev-C8VHtuPP.mjs";
 import process from "node:process";
 import cac$1 from "cac";
 //#region src/adapters/flags.ts
@@ -93,7 +93,8 @@ function flagKeyToOption(camel) {
 function createCac(d, options = {}) {
 	const defaultPort = options.defaultPort ?? d.cli?.port ?? 9999;
 	const defaultHost = d.cli?.host ?? "localhost";
-	const cli = cac$1(d.cli?.command ?? d.id);
+	const command = d.cli?.command ?? d.id;
+	const cli = cac$1(command);
 	const devCommand = cli.command("[...args]", "Start a local dev server").option("--port <port>", "Port to listen on").option("--host <host>", "Host to bind to", { default: defaultHost }).option("--open", "Open the browser on start").option("--no-open", "Do not open the browser").option("--no-auth", "Disable the interactive authentication gate").option("--mcp", "Expose an MCP server over HTTP at /__mcp (use --no-mcp to disable)");
 	if (d.cli?.flags) for (const [key, schema] of Object.entries(d.cli.flags)) {
 		const optionName = flagKeyToOption(key);

package/dist/adapters/dev.d.mts

@@ -1,8 +1,8 @@
-import { R as DevframeNodeRpcSession, c as DevframeWsOptions, l as McpRouteOptions, n as DevframeDefinition, s as DevframeSseOptions, u as DevframeAuthHandler } from "../devframe-DJMg0WLe.mjs";
+import { _ as DevframeNodeRpcSession, c as DevframeWsOptions, l as McpRouteOptions, n as DevframeDefinition, s as DevframeSseOptions, u as DevframeAuthHandler } from "../devframe-BlLEZR-x.mjs";
 import { d as DevframeRpcConnection, n as WsOriginRegistry, u as DevframeNodeRpcSessionMeta } from "../ws-server-D1d3QM9f.mjs";
 import { o as StaticAssetsSource } from "../remote-assets-Bg4gCUZ_.mjs";
-import { c as StartedServer } from "../instance-shell-CljiKq1c.mjs";
-import { a as resolveMcpConnectionMeta, i as resolveDevServerPort, t as ResolveDevServerPortOptions } from "../_shared-BPmX9fqK.mjs";
+import { c as StartedServer } from "../instance-shell-0iw-cQ5V.mjs";
+import { a as resolveMcpConnectionMeta, i as resolveDevServerPort, t as ResolveDevServerPortOptions } from "../_shared-DqbKCAew.mjs";
 import { H3 } from "h3";
 //#region src/adapters/dev.d.ts
 interface CreateDevServerOptions {

package/dist/adapters/dev.mjs

@@ -1,3 +1,3 @@
-import { i as resolveMcpConnectionMeta, r as resolveDevServerPort } from "../_shared-CbZ_yhbz.mjs";
-import { t as createDevServer } from "../dev--rAPzbvO.mjs";
+import { i as resolveMcpConnectionMeta, r as resolveDevServerPort } from "../_shared-BM3PdYli.mjs";
+import { t as createDevServer } from "../dev-C8VHtuPP.mjs";
 export { createDevServer, resolveDevServerPort, resolveMcpConnectionMeta };

package/dist/adapters/embedded.d.mts

@@ -1,4 +1,4 @@
-import { g as DevframeNodeContext, n as DevframeDefinition } from "../devframe-DJMg0WLe.mjs";
+import { g as DevframeNodeContext, n as DevframeDefinition } from "../devframe-BlLEZR-x.mjs";
 //#region src/adapters/embedded.d.ts
 interface CreateEmbeddedOptions {
   /** Target context the devframe is registered into. Required. */

package/dist/adapters/embedded.mjs

@@ -9,6 +9,7 @@
 * effective default follows the hosted rule of `def.basePath ?? '/__<id>/'`.
 */
 async function createEmbedded(d, options) {
+	for (const input of d.services ?? []) options.ctx.services.install(input, { resolveFrom: d.packageName });
 	await d.setup(options.ctx);
 }
 //#endregion

package/dist/adapters/initiate.d.mts

@@ -1,7 +1,7 @@
-import { F as DevframeStorageScope, R as DevframeNodeRpcSession, c as DevframeWsOptions, d as ConnectionMeta, g as DevframeNodeContext, l as McpRouteOptions, n as DevframeDefinition, s as DevframeSseOptions, u as DevframeAuthHandler } from "../devframe-DJMg0WLe.mjs";
+import { $ as DevframeStorageScope, _ as DevframeNodeRpcSession, c as DevframeWsOptions, d as ConnectionMeta, g as DevframeNodeContext, l as McpRouteOptions, n as DevframeDefinition, s as DevframeSseOptions, u as DevframeAuthHandler } from "../devframe-BlLEZR-x.mjs";
 import { d as DevframeRpcConnection, n as WsOriginRegistry, u as DevframeNodeRpcSessionMeta } from "../ws-server-D1d3QM9f.mjs";
 import { o as StaticAssetsSource } from "../remote-assets-Bg4gCUZ_.mjs";
-import { c as StartedServer, f as DevframeInstanceRecord } from "../instance-shell-CljiKq1c.mjs";
+import { c as StartedServer, f as DevframeInstanceRecord } from "../instance-shell-0iw-cQ5V.mjs";
 import { Buffer } from "node:buffer";
 import { IncomingMessage, Server, ServerResponse } from "node:http";
 import { Duplex } from "node:stream";

package/dist/adapters/initiate.mjs

@@ -1,2 +1,2 @@
-import { n as getInstanceInternals, r as initDevframe } from "../dev--rAPzbvO.mjs";
+import { n as getInstanceInternals, r as initDevframe } from "../dev-C8VHtuPP.mjs";
 export { getInstanceInternals, initDevframe };

package/dist/adapters/mcp.d.mts

@@ -1,4 +1,4 @@
-import { g as DevframeNodeContext, n as DevframeDefinition } from "../devframe-DJMg0WLe.mjs";
+import { g as DevframeNodeContext, n as DevframeDefinition } from "../devframe-BlLEZR-x.mjs";
 import { H3 } from "h3";
 import "@modelcontextprotocol/server";
 //#region src/adapters/mcp/build-server.d.ts

package/dist/adapters/mcp.mjs

@@ -1,2 +1,2 @@
-import { i as createMcpServer, n as mountMcpHttp, r as createMcpFetchHandler } from "../http-DYpK0cUi.mjs";
+import { i as createMcpServer, n as mountMcpHttp, r as createMcpFetchHandler } from "../http-BbHCU5Zs.mjs";
 export { createMcpFetchHandler, createMcpServer, mountMcpHttp };

package/dist/cli/main.mjs

@@ -1,6 +1,6 @@
 import { t as Diagnostic } from "../nostics-CzECRXpE.mjs";
-import { t as diagnostics } from "../diagnostics-DOQPnQmX.mjs";
-import { n as listLiveDevframeInstances, r as probeDevframeOrigin } from "../instance-registry-WvQkt42E.mjs";
+import { t as diagnostics } from "../diagnostics-Di8ytitn.mjs";
+import { n as listLiveDevframeInstances, r as probeDevframeOrigin } from "../instance-registry-CHunhMi5.mjs";
 import { t as toAgentToolName } from "../agent-tool-name-EgfoFO8C.mjs";
 import process from "node:process";
 import { joinURL } from "ufo";

package/dist/client/index.d.mts

@@ -1,4 +1,4 @@
-import { $ as StreamReader, A as ScopedServerFunctions, H as RpcSharedStateHost, K as DevframeRpcClientFunctions, M as SettingsForNamespace, Tt as EventEmitter, V as RpcSharedStateGetOptions, d as ConnectionMeta, et as StreamSink, j as ScopedSharedStates, k as ScopedRpcFn, lt as SharedState, q as DevframeRpcServerFunctions, w as DevframeSettings } from "../devframe-DJMg0WLe.mjs";
+import { E as DevframeRpcServerFunctions, H as DevframeSettings, J as ScopedServerFunctions, M as DevframeServiceMeta, Mt as EventEmitter, P as DevframeServiceScopeOf, R as DevframeServicesState, T as DevframeRpcClientFunctions, X as SettingsForNamespace, Y as ScopedSharedStates, b as RpcSharedStateGetOptions, d as ConnectionMeta, gt as SharedState, ot as StreamReader, q as ScopedRpcFn, st as StreamSink, x as RpcSharedStateHost } from "../devframe-BlLEZR-x.mjs";
 import { f as RpcCacheManager, p as RpcCacheOptions } from "../index-tdrk1bzV.mjs";
 import { _ as RpcFunctionDefinition, w as RpcFunctionsCollector } from "../types-Djq7CBXh.mjs";
 import { t as SseRpcChannelOptions } from "../sse-client-CFBOIaUi.mjs";
@@ -197,6 +197,45 @@ interface DevframeScopedClientContext<NS extends string = string, Settings exten
  */
 declare function createScopedClientContext<NS extends string = string>(rpc: DevframeRpcClient, namespace: NS): DevframeScopedClientContext<NS>;
 //#endregion
+//#region src/client/rpc-services.d.ts
+/**
+ * A typed handle on one advertised wire service — the service's
+ * advertisement meta plus an RPC surface scoped to its namespace, so
+ * `handle.rpc.call('fn-name', …)` targets `<scope>:fn-name`. Service
+ * packages type the calls by augmenting `DevframeRpcServerFunctions` with
+ * their fully-qualified ids and `DevframeServicesScopeRegistry` with their
+ * package → scope mapping.
+ */
+interface DevframeServiceClientHandle<NS extends string = string> extends DevframeServiceMeta {
+  readonly scope: NS;
+  /** RPC surface scoped to the service's namespace. */
+  readonly rpc: DevframeScopedClientRpc<NS>;
+}
+/**
+ * Client-side view of the server's wire-service registry, mirrored through
+ * the reactive `devframe:services` shared state. The accessors are
+ * synchronous snapshots — before the first sync lands (or on a server with
+ * no services) they read as empty. For reactive UI (e.g. hiding an
+ * "open in editor" button until the service appears), subscribe to the
+ * shared state itself via {@link DevframeServicesClient.state}.
+ */
+interface DevframeServicesClient {
+  /** Whether the service package is advertised as installed. */
+  has: (pkg: string) => boolean;
+  /**
+   * A typed handle on an advertised service — its meta plus a scoped RPC
+   * surface — or `undefined` while it isn't available (never throws).
+   */
+  get: <PKG extends string>(pkg: PKG) => DevframeServiceClientHandle<DevframeServiceScopeOf<PKG>> | undefined;
+  /** Package names of every advertised service. */
+  keys: () => string[];
+  /**
+   * The mirrored `devframe:services` shared state — subscribe to its
+   * `updated` event for reactivity.
+   */
+  state: () => Promise<SharedState<DevframeServicesState>>;
+}
+//#endregion
 //#region src/client/rpc.d.ts
 interface DevframeRpcContext {
   /**
@@ -363,6 +402,13 @@ interface DevframeRpcClient {
    * The shared state host
    */
   sharedState: RpcSharedStateHost;
+  /**
+   * The server's advertised wire services (mirrored `devframe:services`
+   * shared state) — feature-detect a capability with
+   * `rpc.services.has('@devframes/service-x')` and get a scoped, typed RPC
+   * handle with `rpc.services.get(...)`. See {@link DevframeServicesClient}.
+   */
+  services: DevframeServicesClient;
   /**
    * The streaming channel host. Subscribe to a server-side stream by
    * channel + id; the returned reader is both `AsyncIterable<T>` and
@@ -505,4 +551,4 @@ declare function createClientSettings<T extends Record<string, any> = Record<str
 //#region src/client/index.d.ts
 declare const connectDevframe: typeof getDevframeRpcClient;
 //#endregion
-export { DevframeClientRpcHost, DevframeConnection, DevframeConnectionError, DevframeConnectionErrorKind, DevframeConnectionStatus, DevframeRpcClient, DevframeRpcClientCall, DevframeRpcClientCallEvent, DevframeRpcClientCallOptional, DevframeRpcClientMode, DevframeRpcClientOptions, DevframeRpcContext, DevframeScopedClientContext, DevframeScopedClientRpc, DevframeScopedClientStreamingHost, RpcClientEvents, RpcStreamingClientHost, SetupDevframeConnectionOptions, StreamingSubscribeOptions, type WsUrlLocation, authenticateWithUrlOtp, connectDevframe, consumeOtpFromUrl, createClientSettings, createRpcStreamingClientHost, createScopedClientContext, getDevframeConnection, getDevframeRpcClient, isCallableStatus, readOtpFromUrl, registerDevframeViewerOrigin, resolveClientTransport, resolveSseUrl, resolveWsUrl, setupDevframeConnection };
+export { DevframeClientRpcHost, DevframeConnection, DevframeConnectionError, DevframeConnectionErrorKind, DevframeConnectionStatus, DevframeRpcClient, DevframeRpcClientCall, DevframeRpcClientCallEvent, DevframeRpcClientCallOptional, DevframeRpcClientMode, DevframeRpcClientOptions, DevframeRpcContext, DevframeScopedClientContext, DevframeScopedClientRpc, DevframeScopedClientStreamingHost, type DevframeServiceClientHandle, type DevframeServicesClient, RpcClientEvents, RpcStreamingClientHost, SetupDevframeConnectionOptions, StreamingSubscribeOptions, type WsUrlLocation, authenticateWithUrlOtp, connectDevframe, consumeOtpFromUrl, createClientSettings, createRpcStreamingClientHost, createScopedClientContext, getDevframeConnection, getDevframeRpcClient, isCallableStatus, readOtpFromUrl, registerDevframeViewerOrigin, resolveClientTransport, resolveSseUrl, resolveWsUrl, setupDevframeConnection };

package/dist/client/index.mjs

@@ -8,6 +8,70 @@ import { defineDiagnostics } from "nostics";
 import { ansiFormatter } from "nostics/formatters/ansi";
 import { withBase, withProtocol } from "ufo";
 import { createBirpc } from "birpc";
+//#region src/events.ts
+/**
+* Centralized registry of the core devframe event names — the node-side host
+* bus events, the client RPC connection events, and the server→client
+* broadcast notifications — so these names live in one place instead of
+* scattered string literals.
+*
+* **Keep this in sync with [`docs/guide/events.md`](../../../docs/guide/events.md)**
+* (the "Core devframe events" section): every name here appears in that page's
+* tables, and every name there resolves to an entry here. Add, rename, or
+* remove a name in both places in the same change, and reference
+* `DEVFRAME_EVENTS.*` from call sites instead of re-typing a literal.
+*
+* This map covers **notifications** (events, broadcasts). 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 and stay out of this map.
+*
+* The `EventEmitter` maps (`RpcClientEvents`, `DevframeAgentHostEvents`) and the
+* `DevframeRpcClientFunctions` augmentation declare these names as type-level
+* keys (a literal is unavoidable in a type position); those declarations mirror
+* this map and move with it.
+*/
+const DEVFRAME_EVENTS = {
+	/**
+	* Node-side host `EventEmitter` events. The agent host (`ctx.agent.events`)
+	* emits these as its tool/resource surface changes; protocol adapters (e.g.
+	* MCP) subscribe to re-publish their manifest.
+	*/
+	bus: {
+		agentManifestChanged: "agent:manifest:changed",
+		agentToolRegistered: "agent:tool:registered",
+		agentToolUnregistered: "agent:tool:unregistered",
+		agentResourceRegistered: "agent:resource:registered",
+		agentResourceUnregistered: "agent:resource:unregistered"
+	},
+	/**
+	* Client-side RPC connection `EventEmitter` events (`rpc.events`) a UI
+	* subscribes to for connection lifecycle and error surfacing.
+	*/
+	client: {
+		isTrustedUpdated: "rpc:is-trusted:updated",
+		error: "rpc:error",
+		connectionStatus: "connection:status",
+		connectionError: "connection:error"
+	},
+	/**
+	* Broadcast notifications the server pushes to clients (server → client),
+	* `devframe:` prefix. The paired request methods (subscribe/get/set/…) are
+	* RPC endpoints, not events, and are omitted deliberately.
+	*/
+	broadcast: {
+		authRevoked: "devframe:auth:revoked",
+		clientStateUpdated: "devframe:rpc:client-state:updated",
+		clientStatePatch: "devframe:rpc:client-state:patch",
+		streamingChunk: "devframe:streaming:chunk",
+		streamingEnd: "devframe:streaming:end",
+		streamingUploadCancel: "devframe:streaming:upload-cancel"
+	},
+	/** `postMessage` channels the runtime posts across window boundaries. */
+	postMessage: { remoteAssetsError: "devframe:remote-assets-error" }
+};
+//#endregion
 //#region src/constants.ts
 const DEVFRAME_CONNECTION_META_FILENAME = "__connection.json";
 /**
@@ -25,6 +89,12 @@ const DEVFRAME_CONNECTION_KEY = "__DEVFRAME_CONNECTION__";
 const DEVFRAME_SSE_SESSION_HEADER = "x-birpc-session";
 const DEVFRAME_RPC_DUMP_MANIFEST_FILENAME = "__rpc-dump/index.json";
 /**
+* Shared-state key carrying the wire-service advertisements (package name →
+* `DevframeServiceMeta`). Written by the node services host; mirrored to
+* clients for feature-detection via `client.services`.
+*/
+const DEVFRAME_SERVICES_STATE_KEY = "devframe:services";
+/**
 * Page-URL **fragment** parameter carrying a one-time authentication code (OTP)
 * for "magic link" auth. A host can print a link like
 * `<origin>/#devframe_otp=<code>`; the client reads the code, exchanges it for a
@@ -47,6 +117,7 @@ const DEVFRAME_AUTH_TOKEN_QUERY_PARAM = "devframe_auth_token";
 const DEVFRAME_VIEWER_ORIGIN_QUERY_PARAM = "devframe_viewer_origin";
 /** Token that authorizes an external viewer origin registration. */
 const DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM = "devframe_viewer_origin_token";
+DEVFRAME_EVENTS.postMessage.remoteAssetsError;
 //#endregion
 //#region src/rpc/cache.ts
 /**
@@ -606,6 +677,43 @@ async function authenticateWithUrlOtp(rpc, options = {}) {
 	return rpc.requestTrustWithCode(code);
 }
 //#endregion
+//#region src/client/rpc-services.ts
+/** @internal */
+function createDevframeServicesClient(rpc) {
+	let current = {};
+	const handles = /* @__PURE__ */ new WeakMap();
+	let statePromise;
+	const state = () => {
+		statePromise ??= rpc.sharedState.get(DEVFRAME_SERVICES_STATE_KEY, { initialValue: {} }).then((shared) => {
+			current = shared.value();
+			shared.on("updated", (value) => {
+				current = value;
+			});
+			return shared;
+		});
+		return statePromise;
+	};
+	state();
+	return {
+		state,
+		has: (pkg) => pkg in current,
+		keys: () => Object.keys(current),
+		get: (pkg) => {
+			const entry = current[pkg];
+			if (!entry) return void 0;
+			let handle = handles.get(entry);
+			if (!handle) {
+				handle = {
+					...entry,
+					rpc: rpc.scope(entry.scope).rpc
+				};
+				handles.set(entry, handle);
+			}
+			return handle;
+		}
+	};
+}
+//#endregion
 //#region src/client/rpc-shared-state.ts
 function createRpcSharedStateClientHost(rpc) {
 	const sharedState = /* @__PURE__ */ new Map();
@@ -622,7 +730,7 @@ function createRpcSharedStateClientHost(rpc) {
 		return serverState;
 	}
 	rpc.client.register({
-		name: "devframe:rpc:client-state:updated",
+		name: DEVFRAME_EVENTS.broadcast.clientStateUpdated,
 		type: "event",
 		handler: (key, fullState, syncId) => {
 			const state = sharedState.get(key);
@@ -631,7 +739,7 @@ function createRpcSharedStateClientHost(rpc) {
 		}
 	});
 	rpc.client.register({
-		name: "devframe:rpc:client-state:patch",
+		name: DEVFRAME_EVENTS.broadcast.clientStatePatch,
 		type: "event",
 		handler: (key, patches, syncId) => {
 			const state = sharedState.get(key);
@@ -698,7 +806,7 @@ function createRpcSharedStateClientHost(rpc) {
 				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();
@@ -926,7 +1034,7 @@ function createLiveRpcClientMode(options) {
 		if (next === status) return;
 		const previous = status;
 		status = next;
-		events.emit("connection:status", next, previous);
+		events.emit(DEVFRAME_EVENTS.client.connectionStatus, next, previous);
 	}
 	const pending = /* @__PURE__ */ new Set();
 	function rejectAllPending(error) {
@@ -948,7 +1056,7 @@ function createLiveRpcClientMode(options) {
 			const entry = { reject(error) {
 				if (settled) return;
 				finish();
-				events.emit("rpc:error", error, method);
+				events.emit(DEVFRAME_EVENTS.client.error, error, method);
 				reject(error);
 			} };
 			function finish() {
@@ -968,7 +1076,7 @@ function createLiveRpcClientMode(options) {
 				if (settled) 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);
 			});
 		});
@@ -979,7 +1087,7 @@ function createLiveRpcClientMode(options) {
 		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() {
@@ -992,15 +1100,15 @@ function createLiveRpcClientMode(options) {
 		rpcOptions
 	});
 	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);
 		}
 	});
 	let currentAuthToken = authToken;
@@ -1018,9 +1126,9 @@ function createLiveRpcClientMode(options) {
 		} else {
 			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;
 	}
 	async function requestTrustWithCode(code) {
@@ -1034,7 +1142,7 @@ function createLiveRpcClientMode(options) {
 			isTrusted = true;
 			trustedPromise.resolve(true);
 			setStatus("connected");
-			events.emit("rpc:is-trusted:updated", true);
+			events.emit(DEVFRAME_EVENTS.client.isTrustedUpdated, true);
 		}
 		return token;
 	}
@@ -1073,7 +1181,7 @@ function createLiveRpcClientMode(options) {
 			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(serverRpc.$call(...args), method);
@@ -1081,7 +1189,7 @@ function createLiveRpcClientMode(options) {
 		callEvent: (...args) => {
 			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(...args);
@@ -1090,7 +1198,7 @@ function createLiveRpcClientMode(options) {
 			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(serverRpc.$callOptional(...args), method);
@@ -1287,14 +1395,14 @@ function createRpcStreamingClientHost(rpc) {
 	const readers = /* @__PURE__ */ new Map();
 	const uploads = /* @__PURE__ */ new Map();
 	rpc.client.register({
-		name: "devframe:streaming:chunk",
+		name: DEVFRAME_EVENTS.broadcast.streamingChunk,
 		type: "event",
 		handler(channel, id, seq, chunk) {
 			readers.get(streamKey(channel, id))?._push(seq, chunk);
 		}
 	});
 	rpc.client.register({
-		name: "devframe:streaming:end",
+		name: DEVFRAME_EVENTS.broadcast.streamingEnd,
 		type: "event",
 		handler(channel, id, error) {
 			const key = streamKey(channel, id);
@@ -1305,7 +1413,7 @@ function createRpcStreamingClientHost(rpc) {
 		}
 	});
 	rpc.client.register({
-		name: "devframe:streaming:upload-cancel",
+		name: DEVFRAME_EVENTS.broadcast.streamingUploadCancel,
 		type: "event",
 		handler(channel, id) {
 			const key = streamKey(channel, id);
@@ -1315,7 +1423,7 @@ function createRpcStreamingClientHost(rpc) {
 			uploads.delete(key);
 		}
 	});
-	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) {
 			if (reader.cancelled || reader.done) continue;
@@ -1344,7 +1452,7 @@ function createRpcStreamingClientHost(rpc) {
 		readers.set(key, reader);
 		if (rpc.isTrusted) rpc.callEvent("devframe:streaming:subscribe", channel, id, { afterSeq: 0 });
 		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) rpc.callEvent("devframe:streaming:subscribe", channel, id, { afterSeq: reader.lastSeenSeq });
@@ -1737,6 +1845,7 @@ async function getDevframeRpcClient(options = {}) {
 		callOptional: gateOnBootstrapAuth(mode.callOptional),
 		client: clientRpc,
 		sharedState: void 0,
+		services: void 0,
 		streaming: void 0,
 		cacheManager,
 		scope: void 0,
@@ -1744,6 +1853,7 @@ async function getDevframeRpcClient(options = {}) {
 	};
 	rpc.sharedState = createRpcSharedStateClientHost(rpc);
 	rpc.streaming = createRpcStreamingClientHost(rpc);
+	rpc.services = createDevframeServicesClient(rpc);
 	const scopedCache = /* @__PURE__ */ new Map();
 	rpc.scope = ((namespace) => {
 		if (!namespace) return rpc;

package/dist/constants.d.mts

@@ -1,3 +1,69 @@
+//#region src/events.d.ts
+/**
+ * Centralized registry of the core devframe event names — the node-side host
+ * bus events, the client RPC connection events, and the server→client
+ * broadcast notifications — so these names live in one place instead of
+ * scattered string literals.
+ *
+ * **Keep this in sync with [`docs/guide/events.md`](../../../docs/guide/events.md)**
+ * (the "Core devframe events" section): every name here appears in that page's
+ * tables, and every name there resolves to an entry here. Add, rename, or
+ * remove a name in both places in the same change, and reference
+ * `DEVFRAME_EVENTS.*` from call sites instead of re-typing a literal.
+ *
+ * This map covers **notifications** (events, broadcasts). 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 and stay out of this map.
+ *
+ * The `EventEmitter` maps (`RpcClientEvents`, `DevframeAgentHostEvents`) and the
+ * `DevframeRpcClientFunctions` augmentation declare these names as type-level
+ * keys (a literal is unavoidable in a type position); those declarations mirror
+ * this map and move with it.
+ */
+declare const DEVFRAME_EVENTS: {
+  /**
+   * Node-side host `EventEmitter` events. The agent host (`ctx.agent.events`)
+   * emits these as its tool/resource surface changes; protocol adapters (e.g.
+   * MCP) subscribe to re-publish their manifest.
+   */
+  readonly bus: {
+    readonly agentManifestChanged: "agent:manifest:changed";
+    readonly agentToolRegistered: "agent:tool:registered";
+    readonly agentToolUnregistered: "agent:tool:unregistered";
+    readonly agentResourceRegistered: "agent:resource:registered";
+    readonly agentResourceUnregistered: "agent:resource:unregistered";
+  };
+  /**
+   * Client-side RPC connection `EventEmitter` events (`rpc.events`) a UI
+   * subscribes to for connection lifecycle and error surfacing.
+   */
+  readonly client: {
+    readonly isTrustedUpdated: "rpc:is-trusted:updated";
+    readonly error: "rpc:error";
+    readonly connectionStatus: "connection:status";
+    readonly connectionError: "connection:error";
+  };
+  /**
+   * Broadcast notifications the server pushes to clients (server → client),
+   * `devframe:` prefix. The paired request methods (subscribe/get/set/…) are
+   * RPC endpoints, not events, and are omitted deliberately.
+   */
+  readonly broadcast: {
+    readonly authRevoked: "devframe:auth:revoked";
+    readonly clientStateUpdated: "devframe:rpc:client-state:updated";
+    readonly clientStatePatch: "devframe:rpc:client-state:patch";
+    readonly streamingChunk: "devframe:streaming:chunk";
+    readonly streamingEnd: "devframe:streaming:end";
+    readonly streamingUploadCancel: "devframe:streaming:upload-cancel";
+  };
+  /** `postMessage` channels the runtime posts across window boundaries. */
+  readonly postMessage: {
+    readonly remoteAssetsError: "devframe:remote-assets-error";
+  };
+};
+//#endregion
 //#region src/constants.d.ts
 declare const DEVFRAME_CONNECTION_META_FILENAME = "__connection.json";
 /**
@@ -40,6 +106,12 @@ declare const DEVFRAME_MCP_ROUTE = "__mcp";
 declare const DEVFRAME_RPC_DUMP_MANIFEST_FILENAME = "__rpc-dump/index.json";
 declare const DEVFRAME_DOCK_IMPORTS_FILENAME = "__client-imports.js";
 declare const DEVFRAME_RPC_DUMP_DIRNAME = "__rpc-dump";
+/**
+ * Shared-state key carrying the wire-service advertisements (package name →
+ * `DevframeServiceMeta`). Written by the node services host; mirrored to
+ * clients for feature-detection via `client.services`.
+ */
+declare const DEVFRAME_SERVICES_STATE_KEY = "devframe:services";
 /**
  * URL fragment / query parameter name carrying the remote dock
  * connection descriptor (defined as `RemoteConnectionInfo` in
@@ -77,7 +149,7 @@ declare const DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM = "devframe_viewer_origin
  * (`@devframes/hub-ui` does, in its iframe view). Payload shape:
  * `RemoteAssetsErrorMessage` (`devframe/types`).
  */
-declare const DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE = "devframe:remote-assets-error";
+declare const DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE: string;
 /**
  * Prefix that marks an RPC method as callable before a connection is
  * trusted. This is the *only* rule the pre-trust gate applies — there is no
@@ -94,4 +166,4 @@ declare const ANONYMOUS_RPC_PREFIX = "anonymous:";
  */
 declare function isAnonymousRpcMethod(name: string): boolean;
 //#endregion
-export { ANONYMOUS_RPC_PREFIX, DEVFRAME_AUTH_TOKEN_QUERY_PARAM, DEVFRAME_CONNECTION_KEY, DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_MCP_ROUTE, DEVFRAME_OTP_URL_PARAM, DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME, DEVFRAME_SSE_ROUTE, DEVFRAME_SSE_SESSION_HEADER, DEVFRAME_VIEWER_ORIGIN_QUERY_PARAM, DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM, DEVFRAME_WS_ROUTE, REMOTE_CONNECTION_KEY, isAnonymousRpcMethod };
+export { ANONYMOUS_RPC_PREFIX, DEVFRAME_AUTH_TOKEN_QUERY_PARAM, DEVFRAME_CONNECTION_KEY, DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_EVENTS, DEVFRAME_MCP_ROUTE, DEVFRAME_OTP_URL_PARAM, DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME, DEVFRAME_SERVICES_STATE_KEY, DEVFRAME_SSE_ROUTE, DEVFRAME_SSE_SESSION_HEADER, DEVFRAME_VIEWER_ORIGIN_QUERY_PARAM, DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM, DEVFRAME_WS_ROUTE, REMOTE_CONNECTION_KEY, isAnonymousRpcMethod };