devframe 0.9.5 → 0.9.6

package/dist/adapters/mcp.mjs

@@ -1,2 +1,560 @@
-import { i as createMcpServer, n as mountMcpHttp, r as createMcpFetchHandler } from "../http-D7wWuy7-.mjs";
+import { t as Diagnostic } from "../nostics-CzECRXpE.mjs";
+import { t as DEVFRAME_EVENTS } from "../events-4daw0uK9.mjs";
+import { i as isAllowedOrigin } from "../ws-server-BdSLrhxE.mjs";
+import { t as diagnostics } from "../diagnostics-BXWW3VK-.mjs";
+import { t as createHostContext } from "../context-omlma_1n.mjs";
+import { t as toAgentToolName } from "../agent-tool-name-EgfoFO8C.mjs";
+import process from "node:process";
+import { join } from "pathe";
+import { homedir } from "node:os";
+import { defineHandler } from "h3";
+import { Server, createMcpHandler } from "@modelcontextprotocol/server";
+//#region src/adapters/mcp/stringify.ts
+/**
+* JSON-coercing serializer for MCP text payloads.
+*
+* MCP carries tool results and resource reads as plain text over a
+* JSON-RPC transport, so we cannot use the `s:`-prefixed structured-clone
+* format the WS RPC transport falls back to for non-JSON values. Instead,
+* we coerce common non-JSON types into JSON-friendly forms so the LLM
+* client sees something useful instead of `[object Object]`.
+*
+* Coercions:
+*   - `BigInt` → `"123n"`
+*   - `Date` → ISO string (via the native `toJSON`)
+*   - `Map` → `{ __type: 'Map', entries: [[k, v], …] }`
+*   - `Set` → `{ __type: 'Set', entries: [v, …] }`
+*   - `Error` → `{ name, message, stack, cause? }` (cause recurses)
+*   - `Function` → `"[Function: name]"`
+*   - `Symbol` → `value.toString()`
+*   - cycles → `"[Circular]"`
+*/
+function stringifyForMcp(value) {
+	if (value === void 0) return "undefined";
+	if (typeof value === "string") return value;
+	const seen = /* @__PURE__ */ new WeakSet();
+	return JSON.stringify(value, (_key, val) => {
+		if (typeof val === "bigint") return `${val}n`;
+		if (val instanceof Error) {
+			const out = {
+				name: val.name,
+				message: val.message,
+				stack: val.stack
+			};
+			if (val.cause !== void 0) out.cause = val.cause;
+			return out;
+		}
+		if (val instanceof Map) return {
+			__type: "Map",
+			entries: [...val.entries()]
+		};
+		if (val instanceof Set) return {
+			__type: "Set",
+			entries: [...val]
+		};
+		if (typeof val === "function") return `[Function: ${val.name || "anonymous"}]`;
+		if (typeof val === "symbol") return val.toString();
+		if (val !== null && typeof val === "object") {
+			if (seen.has(val)) return "[Circular]";
+			seen.add(val);
+		}
+		return val;
+	}, 2);
+}
+/**
+* Format a thrown value for an MCP `isError` text payload.
+*
+* A nostics `Diagnostic` (every coded devframe error) becomes structured
+* JSON — `{ error: { code, message, fix?, docs? } }` — so an agent receives
+* the actionable next step (`fix`) and the docs URL instead of a bare
+* message string. Other errors surface `Error.name`/`message`, plus one
+* level of `cause.message` so context isn't dropped silently.
+*/
+function formatMcpError(error) {
+	if (error instanceof Diagnostic) return JSON.stringify({ error: {
+		code: error.code,
+		message: error.message,
+		...error.fix ? { fix: error.fix } : {},
+		...error.docs ? { docs: error.docs } : {}
+	} }, null, 2);
+	if (!(error instanceof Error)) return String(error);
+	const cause = error.cause;
+	const causeText = cause instanceof Error ? ` (cause: ${cause.message})` : cause !== void 0 ? ` (cause: ${String(cause)})` : "";
+	return `${error.name}: ${error.message}${causeText}`;
+}
+//#endregion
+//#region src/adapters/mcp/to-json-schema.ts
+const FALLBACK_OBJECT_SCHEMA = Object.freeze({
+	type: "object",
+	additionalProperties: true
+});
+/**
+* Convert a Standard Schema to JSON Schema for the agent/MCP surface.
+*
+* Devframe stays validator-neutral, so conversion uses the schema's own
+* [Standard JSON Schema](https://standardschema.dev/) converter
+* (`~standard.jsonSchema`) when the validator provides one — zod 4 does,
+* for example. Validators without a native converter (e.g. valibot) degrade
+* to a permissive object schema rather than pulling in a converter library.
+*/
+function safeToJsonSchema(schema) {
+	const standard = schema["~standard"];
+	if (standard.jsonSchema) try {
+		return standard.jsonSchema.input({ target: "draft-2020-12" });
+	} catch {
+		return FALLBACK_OBJECT_SCHEMA;
+	}
+	return FALLBACK_OBJECT_SCHEMA;
+}
+/**
+* JSON Schema for an RPC return value on the agent/MCP surface.
+* @internal
+*/
+function returnToJsonSchema(schema) {
+	if (!schema) return void 0;
+	return safeToJsonSchema(schema);
+}
+/**
+* JSON Schema for an RPC function's positional args on the agent/MCP
+* surface. Each positional arg is advertised under `arg0` / `arg1` / … —
+* matching how the agent bridge coerces the incoming object payload back
+* into positional arguments.
+*
+* Returns `{ type: 'object', properties: {} }` when there are no args.
+* @internal
+*/
+function argsToJsonSchema(args) {
+	if (!args || args.length === 0) return {
+		schema: {
+			type: "object",
+			properties: {}
+		},
+		unwrapped: false
+	};
+	const properties = {};
+	const required = [];
+	for (let i = 0; i < args.length; i++) {
+		const key = `arg${i}`;
+		properties[key] = safeToJsonSchema(args[i]);
+		required.push(key);
+	}
+	return {
+		schema: {
+			type: "object",
+			properties,
+			required,
+			additionalProperties: false
+		},
+		unwrapped: false
+	};
+}
+//#endregion
+//#region src/adapters/mcp/build-server.ts
+/**
+* Build a fresh MCP {@link Server} over a devframe context, registering its
+* tool and resource handlers. This is a pure factory — it sets up no
+* long-lived subscriptions and holds no per-connection state, so it is safe
+* to call once per request under `createMcpHandler` or once per connection
+* under `serveStdio`. Change notifications are published separately: over
+* HTTP through the handler's `notify` bus (see `createMcpFetchHandler`), and
+* on stdio through the connection's own `send*ListChanged` calls (see
+* {@link bridgeListChanged}, wired by `serveStdio`).
+*
+* @internal
+*/
+function buildMcpServerFromContext(ctx, options) {
+	const server = new Server({
+		name: options.serverName,
+		version: options.serverVersion
+	}, { capabilities: {
+		tools: { listChanged: true },
+		resources: { listChanged: true }
+	} });
+	registerToolHandlers(server, ctx, options.exposeSharedState);
+	registerResourceHandlers(server, ctx, options.exposeSharedState);
+	return server;
+}
+/**
+* Publish devframe's `list_changed` events through a set of typed sinks:
+* `tools()` for tool-list changes and `resources()` for resource-list
+* changes (shared-state keys are surfaced as resources). Returns an
+* unsubscribe function.
+*
+* The HTTP path passes the handler's `notify` bus sugar; the stdio path
+* passes the pinned server's `send*ListChanged` methods, which `serveStdio`
+* routes onto the connection's active `subscriptions/listen` streams.
+*
+* @internal
+*/
+function bridgeListChanged(ctx, sinks) {
+	const offManifest = ctx.agent.events.on(DEVFRAME_EVENTS.bus.agentManifestChanged, () => {
+		sinks.tools();
+		sinks.resources();
+	});
+	const offKeyAdded = ctx.rpc.sharedState.onKeyAdded(() => {
+		sinks.resources();
+	});
+	return () => {
+		offManifest();
+		offKeyAdded();
+	};
+}
+/**
+* Build an MCP server over the agent surface of a devframe definition.
+* Currently supports `stdio` transport only.
+*/
+async function createMcpServer(definition, options = {}) {
+	const transport = options.transport ?? "stdio";
+	if (transport !== "stdio") throw diagnostics.DF0017({
+		transport,
+		reason: "Only stdio transport is supported in this release."
+	});
+	const ctx = await createHostContext({
+		cwd: process.cwd(),
+		mode: "dev",
+		host: {
+			mountStatic: () => {},
+			resolveOrigin: () => "mcp://devframe",
+			getStorageDir: (scope) => {
+				if (scope === "workspace") return join(process.cwd(), ".devframe");
+				if (scope === "project") return join(process.cwd(), `node_modules/.${definition.id}/devframe`);
+				return join(homedir(), `.${definition.id}/devframe`);
+			}
+		},
+		importMetaUrl: definition.importMetaUrl
+	});
+	for (const input of definition.services ?? []) ctx.services.install(input, { resolveFrom: definition.importMetaUrl });
+	await ctx.services.ready();
+	await definition.setup(ctx);
+	const buildOptions = {
+		serverName: options.serverName ?? `${definition.id} (devframe)`,
+		serverVersion: options.serverVersion ?? definition.version ?? "0.0.0",
+		exposeSharedState: options.exposeSharedState ?? true
+	};
+	let handle;
+	try {
+		const { serveStdio } = await import("@modelcontextprotocol/server/stdio");
+		handle = serveStdio(() => {
+			const server = buildMcpServerFromContext(ctx, buildOptions);
+			const unbridge = bridgeListChanged(ctx, {
+				tools: () => {
+					server.sendToolListChanged().catch(() => {});
+				},
+				resources: () => {
+					server.sendResourceListChanged().catch(() => {});
+				}
+			});
+			const priorOnClose = server.onclose;
+			server.onclose = () => {
+				unbridge();
+				priorOnClose?.();
+			};
+			return server;
+		});
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		throw diagnostics.DF0017({
+			transport,
+			reason,
+			cause: error
+		});
+	}
+	options.onReady?.({ transport: "stdio" });
+	return { async stop() {
+		await handle.close();
+	} };
+}
+/**
+* Id of the built-in shared-state read tool — namespaced like every other
+* built-in (`devframe:<area>:<fn>`). Tool-shaped access matters because many
+* MCP clients only consume tools — the parallel `devframe://state/<key>`
+* resource projection stays for the clients that do read resources.
+*/
+const READ_STATE_TOOL = "devframe:state:read";
+/** Wire name of the built-in shared-state read tool: `devframe_state_read`. */
+const READ_STATE_NAME = toAgentToolName(READ_STATE_TOOL);
+function sharedStateFilter(exposeSharedState) {
+	if (exposeSharedState === false) return void 0;
+	return typeof exposeSharedState === "function" ? exposeSharedState : () => true;
+}
+function readStateToolProjection() {
+	return {
+		name: READ_STATE_NAME,
+		title: "Read shared state",
+		description: "Read this devtool's live shared state. Call without arguments to list the available keys, then with a key to get that value as JSON. Safe to call freely.",
+		inputSchema: {
+			type: "object",
+			properties: { key: {
+				type: "string",
+				description: "A shared-state key from the key list. Omit to list all keys."
+			} }
+		},
+		annotations: {
+			title: "Read shared state",
+			readOnlyHint: true,
+			destructiveHint: false
+		}
+	};
+}
+async function readStateResult(ctx, filter, key) {
+	const keys = ctx.rpc.sharedState.keys().filter(filter);
+	if (key === void 0) return { keys };
+	if (!keys.includes(key)) throw diagnostics.DF0048({ key });
+	return {
+		key,
+		value: (await ctx.rpc.sharedState.get(key)).value()
+	};
+}
+function registerToolHandlers(server, ctx, exposeSharedState) {
+	const stateFilter = sharedStateFilter(exposeSharedState);
+	const warnedCollisions = /* @__PURE__ */ new Set();
+	/**
+	* Resolve a wire tool name back to the registered {@link AgentTool}.
+	* Wire-name matching runs first, in manifest order — the same tool the
+	* list projection advertises under that name — with a raw-id fallback so
+	* a colon-namespaced id keeps working as a call name.
+	*/
+	const resolveTool = (name) => {
+		return ctx.agent.list().tools.find((tool) => toAgentToolName(tool.id) === name) ?? ctx.agent.getTool(name);
+	};
+	server.setRequestHandler("tools/list", async () => {
+		const byName = /* @__PURE__ */ new Map();
+		for (const tool of ctx.agent.list().tools) {
+			const name = toAgentToolName(tool.id);
+			const existing = byName.get(name);
+			if (existing) {
+				if (!warnedCollisions.has(`${name}|${tool.id}`)) {
+					warnedCollisions.add(`${name}|${tool.id}`);
+					diagnostics.DF0047({
+						name,
+						id: tool.id,
+						existing: existing.id
+					});
+				}
+				continue;
+			}
+			byName.set(name, tool);
+		}
+		const tools = [...byName.entries()].map(([name, tool]) => projectTool(name, tool, ctx));
+		if (stateFilter && !byName.has(READ_STATE_NAME)) tools.push(readStateToolProjection());
+		return { tools };
+	});
+	server.setRequestHandler("tools/call", async (request) => {
+		const { name, arguments: args } = request.params;
+		try {
+			const tool = resolveTool(name);
+			if (stateFilter && !tool && (name === READ_STATE_NAME || name === READ_STATE_TOOL)) {
+				const key = args?.key;
+				const result = await readStateResult(ctx, stateFilter, key);
+				return {
+					content: [{
+						type: "text",
+						text: stringifyForMcp(result)
+					}],
+					structuredContent: result
+				};
+			}
+			const outputSchema = tool ? usableOutputSchema(tool.outputSchema ?? computeOutputSchema(tool, ctx)) : void 0;
+			const result = await ctx.agent.invoke(tool?.id ?? name, args ?? {});
+			return {
+				content: [{
+					type: "text",
+					text: stringifyForMcp(result)
+				}],
+				...outputSchema ? { structuredContent: result } : {}
+			};
+		} catch (error) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `Error invoking "${name}": ${formatMcpError(error)}`
+				}]
+			};
+		}
+	});
+}
+function registerResourceHandlers(server, ctx, exposeSharedState) {
+	server.setRequestHandler("resources/list", async () => {
+		const resources = ctx.agent.list().resources.map((resource) => ({
+			uri: resource.uri,
+			name: resource.name,
+			description: resource.description,
+			mimeType: resource.mimeType
+		}));
+		if (exposeSharedState !== false) {
+			const filter = typeof exposeSharedState === "function" ? exposeSharedState : () => true;
+			for (const key of ctx.rpc.sharedState.keys()) {
+				if (!filter(key)) continue;
+				resources.push({
+					uri: `devframe://state/${encodeURIComponent(key)}`,
+					name: key,
+					description: `Shared state: ${key}`,
+					mimeType: "application/json"
+				});
+			}
+		}
+		return { resources };
+	});
+	server.setRequestHandler("resources/read", async (request) => {
+		const { uri } = request.params;
+		const parsed = parseResourceUri(uri);
+		if (parsed.kind === "resource") {
+			const content = await ctx.agent.read(parsed.id);
+			return { contents: [{
+				uri,
+				mimeType: content.mimeType ?? "application/json",
+				text: content.text ?? stringifyForMcp(content.json)
+			}] };
+		}
+		if (parsed.kind === "state") return { contents: [{
+			uri,
+			mimeType: "application/json",
+			text: stringifyForMcp((await ctx.rpc.sharedState.get(parsed.key)).value())
+		}] };
+		throw new Error(`[devframe/mcp] unknown resource URI "${uri}"`);
+	});
+}
+/**
+* MCP constrains a tool's `outputSchema` to a JSON Schema of `type:
+* "object"` — clients (the SDK included) reject anything else. Non-object
+* return schemas (e.g. a schema for `void` / a bare string) simply project
+* no output schema; the text content still carries the result.
+*/
+function usableOutputSchema(schema) {
+	return schema && typeof schema === "object" && schema.type === "object" ? schema : void 0;
+}
+function projectTool(name, tool, ctx) {
+	const inputSchema = tool.inputSchema ?? computeInputSchema(tool, ctx);
+	const outputSchema = usableOutputSchema(tool.outputSchema ?? computeOutputSchema(tool, ctx));
+	return {
+		name,
+		title: tool.title,
+		description: tool.description,
+		inputSchema,
+		...outputSchema ? { outputSchema } : {},
+		annotations: {
+			title: tool.title,
+			readOnlyHint: tool.safety === "read",
+			destructiveHint: tool.safety === "destructive"
+		}
+	};
+}
+function computeInputSchema(tool, ctx) {
+	if (tool.kind === "tool") return argsToJsonSchema(tool.args).schema;
+	if (tool.kind !== "rpc" || !tool.rpcName) return {
+		type: "object",
+		properties: {}
+	};
+	const def = ctx.rpc.definitions.get(tool.rpcName);
+	if (!def) return {
+		type: "object",
+		properties: {}
+	};
+	const args = def.args;
+	return argsToJsonSchema(args).schema;
+}
+function computeOutputSchema(tool, ctx) {
+	if (tool.kind !== "rpc" || !tool.rpcName) return void 0;
+	const def = ctx.rpc.definitions.get(tool.rpcName);
+	if (!def) return void 0;
+	return returnToJsonSchema(def.returns);
+}
+function parseResourceUri(uri) {
+	const match = uri.match(/^devframe:\/\/(resource|state)\/(.+)$/);
+	if (!match) return { kind: "unknown" };
+	const [, kind, rest] = match;
+	const decoded = decodeURIComponent(rest);
+	if (kind === "resource") return {
+		kind: "resource",
+		id: decoded
+	};
+	return {
+		kind: "state",
+		key: decoded
+	};
+}
+//#endregion
+//#region src/adapters/mcp/fetch.ts
+/**
+* Build a framework-agnostic MCP endpoint over a devframe context: a
+* web-standard `Request → Response` handler any host can mount — h3 (see
+* `mountMcpHttp`), a Next.js App Router route, or any other fetch-shaped
+* server.
+*
+* The endpoint is **stateless**: it serves the 2026-07-28 revision per request
+* through the SDK's {@link createMcpHandler}, which builds a fresh MCP server
+* (from the shared, live `ctx` via `buildMcpServerFromContext`) for each
+* request — no `Mcp-Session-Id` registry, no session-local routing, no
+* GET/DELETE teardown protocol. 2025-era clients are still served through the
+* SDK's default stateless legacy path. `list_changed` events reach modern
+* `subscriptions/listen` streams through the handler's `notify` bus.
+*
+* The origin gate guards every request: loopback-default DNS-rebinding
+* protection that — unlike the WS upgrade's `isAllowedOrigin` — also rejects
+* `Origin`-less requests, so a route-based endpoint isn't reachable by an
+* arbitrary local process.
+*/
+function createMcpFetchHandler(ctx, options) {
+	const allowedOrigins = options.allowedOrigins;
+	const handler = createMcpHandler(() => buildMcpServerFromContext(ctx, {
+		serverName: options.serverName,
+		serverVersion: options.serverVersion,
+		exposeSharedState: options.exposeSharedState
+	}));
+	const unbridge = bridgeListChanged(ctx, {
+		tools: () => {
+			handler.notify.toolsChanged();
+		},
+		resources: () => {
+			handler.notify.resourcesChanged();
+		}
+	});
+	async function handle(req) {
+		const origin = req.headers.get("origin") ?? void 0;
+		if (allowedOrigins !== false && (origin === void 0 || !isAllowedOrigin(origin, allowedOrigins ?? []))) return new Response("Forbidden: origin required", { status: 403 });
+		return handler.fetch(req);
+	}
+	return {
+		fetch: handle,
+		dispose: async () => {
+			unbridge();
+			await handler.close();
+		}
+	};
+}
+//#endregion
+//#region src/adapters/mcp/http.ts
+/**
+* Mount a stateless MCP endpoint on an h3 app at `path` — the h3 binding over
+* {@link createMcpFetchHandler}, which owns the per-request serving, the
+* origin gate, and the transport plumbing.
+*
+* The handler is web-standard — it takes the h3 event's web `Request` and
+* returns a web `Response` (an SSE `ReadableStream` body for a
+* `subscriptions/listen` stream). We copy that response onto `event.res` and
+* return its body rather than returning the `Response` object directly, so an
+* MCP error response (e.g. a 4xx) isn't swallowed by h3's "Response-with-404
+* falls through to the next handler" rule (which would otherwise hand the
+* request to the SPA static catch-all).
+*/
+function mountMcpHttp(app, ctx, path, options) {
+	const handler = createMcpFetchHandler(ctx, options);
+	app.use(path, defineHandler(async (event) => respond(event, await handler.fetch(event.req))));
+	return { dispose: handler.dispose };
+}
+/**
+* Copy a web `Response` from the MCP transport onto the h3 event's response
+* and return its body. Returning the body (a `ReadableStream` or `null`)
+* rather than the `Response` object avoids h3's 404-fall-through behavior.
+*/
+function respond(event, response) {
+	event.res.status = response.status;
+	event.res.statusText = response.statusText;
+	response.headers.forEach((value, key) => {
+		event.res.headers.set(key, value);
+	});
+	return response.body ?? "";
+}
+//#endregion
 export { createMcpFetchHandler, createMcpServer, mountMcpHttp };

package/dist/cli/main.mjs

@@ -203,7 +203,7 @@ async function withInstanceClient(sdk, url, fn) {
 	const client = new sdk.Client({
 		name: "devframe-connect",
 		version: "0.0.0"
-	});
+	}, { versionNegotiation: { mode: "auto" } });
 	await client.connect(transport);
 	try {
 		return await fn(client);

package/dist/client/index.d.mts

@@ -1,8 +1,8 @@
-import { f as RpcCacheManager, p as RpcCacheOptions } from "../index-DOg4S5wk.mjs";
-import { _ as RpcFunctionDefinition, w as RpcFunctionsCollector } from "../types-BBLeGfpt.mjs";
-import { Q as DevframeServiceScopeOf, X as DevframeServiceMeta, _t as DevframeRpcServerFunctions, b as StreamSink, d as RpcSharedStateHost, dt as ScopedRpcFn, ft as ScopedServerFunctions, gt as DevframeRpcClientFunctions, k as SharedState, mt as SettingsForNamespace, nt as DevframeServicesState, ot as DevframeSettings, pt as ScopedSharedStates, t as ConnectionMeta, u as RpcSharedStateGetOptions, y as StreamReader, zt as EventEmitter } from "../context-c0OlSc12.mjs";
-import { t as SseRpcChannelOptions } from "../sse-client-CdGD_B8_.mjs";
-import { t as WsRpcChannelOptions } from "../ws-client-Bo2t6hES.mjs";
+import { f as RpcCacheManager, p as RpcCacheOptions } from "../index-BzyopqxV.mjs";
+import { _ as RpcFunctionDefinition, w as RpcFunctionsCollector } from "../types-CMdPYhOx.mjs";
+import { Q as DevframeServiceScopeOf, X as DevframeServiceMeta, _t as DevframeRpcServerFunctions, b as StreamSink, d as RpcSharedStateHost, dt as ScopedRpcFn, ft as ScopedServerFunctions, gt as DevframeRpcClientFunctions, k as SharedState, mt as SettingsForNamespace, nt as DevframeServicesState, ot as DevframeSettings, pt as ScopedSharedStates, t as ConnectionMeta, u as RpcSharedStateGetOptions, y as StreamReader, zt as EventEmitter } from "../context-BhBzOXVa.mjs";
+import { t as SseRpcChannelOptions } from "../sse-client-DwX021ST.mjs";
+import { t as WsRpcChannelOptions } from "../ws-client-7_lZi-B9.mjs";
 import { BirpcOptions, BirpcReturn } from "birpc";
 //#region src/client/connection.d.ts
 interface DevframeConnection {

package/dist/client/index.mjs

@@ -1,3 +1,4 @@
+import { t as DEVFRAME_EVENTS } from "../events-4daw0uK9.mjs";
 import { t as hash } from "../hash-DdPnc4k3.mjs";
 import { colors } from "../utils/colors.mjs";
 import { createEventEmitter } from "../utils/events.mjs";
@@ -8,70 +9,6 @@ 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/content/1.guide/20.events.md`](../../../docs/content/1.guide/20.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";
 /**

package/dist/constants.d.mts

@@ -5,7 +5,7 @@
  * broadcast notifications — so these names live in one place instead of
  * scattered string literals.
  *
- * **Keep this in sync with [`docs/content/1.guide/20.events.md`](../../../docs/content/1.guide/20.events.md)**
+ * **Keep this in sync with [`docs/content/8.references/3.events.md`](../../../docs/content/8.references/3.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
@@ -58,9 +58,21 @@ declare const DEVFRAME_EVENTS: {
     readonly streamingEnd: "devframe:streaming:end";
     readonly streamingUploadCancel: "devframe:streaming:upload-cancel";
   };
+  /**
+   * In-page channel notifications the page script pushes to its panels
+   * (page script → panel), `devframe:` prefix. The paired request methods
+   * (`devframe:in-page:page-state:subscribe`/`set`/`patch`) are call
+   * endpoints, not events, and are defined at their handlers
+   * (`in-page-channel/state.ts`).
+   */
+  readonly inPageChannel: {
+    readonly panelStateUpdated: "devframe:in-page:panel-state:updated";
+    readonly panelStatePatch: "devframe:in-page:panel-state:patch";
+  };
   /** `postMessage` channels the runtime posts across window boundaries. */
   readonly postMessage: {
     readonly remoteAssetsError: "devframe:remote-assets-error";
+    readonly inPageChannel: "devframe:in-page-channel";
   };
 };
 //#endregion