gesso-framework 0.4.1 → 0.5.0

package/dist/agent/index.d.ts

@@ -0,0 +1,317 @@
+import { E as WorkerHandle, F as JsonSchema, a as resolveTarget, c as AgentResource, d as AgentSurfaceOptions, f as AgentTool, g as ServedChannel, h as resourceUri, i as outline, l as AgentSurface, m as agentSurface, n as UiRefs, o as uiSurface, p as AgentToolResult, r as UiSurfaceOptions, s as AgentConfirmation, t as UiHost, u as AgentSurfaceLike } from "../ui-U39HjNFA.js";
+//#region src/agent/mcp.d.ts
+/**
+ * An agent surface, served over the Model Context Protocol.
+ *
+ * Two layers. `handleMcpMessage` answers one JSON-RPC message and knows
+ * nothing about how it arrived, which is all a stdio transport or a
+ * relay needs. `mcpHandler` wraps it in MCP's Streamable HTTP
+ * transport as a `fetch`-style function, `(Request) => Response`,
+ * which is what `Bun.serve`, Deno, a service worker and every modern
+ * Node server framework take, so the framework imports no server.
+ *
+ * What it implements is the part a channel needs: `initialize`, `ping`,
+ * `tools/list`, `tools/call`, `resources/list` and `resources/read`.
+ * Responses are plain JSON rather than an event stream, which the
+ * transport allows, and the GET stream for server-initiated messages
+ * is declined with 405, which it also allows: nothing here sends one,
+ * so the capabilities say neither `listChanged` nor `subscribe`.
+ */
+/** The protocol revisions this server speaks, newest first. */
+declare const MCP_PROTOCOL_VERSIONS: readonly ['2025-11-25', '2025-06-18', '2025-03-26'];
+interface McpServerInfo {
+  /** The name a client shows for this server. Defaults to `gesso`. */
+  name?: string;
+  version?: string;
+  /** Told to the agent on connecting: what this application is, in a sentence or two. */
+  instructions?: string;
+}
+type JsonRpcId = string | number;
+type JsonRpcResponse = {
+  jsonrpc: '2.0';
+  id: JsonRpcId | null;
+  result: unknown;
+} | {
+  jsonrpc: '2.0';
+  id: JsonRpcId | null;
+  error: {
+    code: number;
+    message: string;
+  };
+};
+/**
+ * Answers one JSON-RPC message. Returns null for a notification, which
+ * takes no answer, and never throws: a malformed message is answered
+ * with the JSON-RPC error that says what was wrong with it.
+ */
+declare function handleMcpMessage(surface: AgentSurfaceLike, message: unknown, info?: McpServerInfo): Promise<JsonRpcResponse | null>;
+interface McpHandlerOptions extends McpServerInfo {
+  /**
+   * Origins a browser may call from. A request carrying any other
+   * `Origin` is refused, as the transport requires: without it, a web
+   * page the person happens to have open could reach a server bound to
+   * their own machine and send commands to their application. Agents
+   * that are not browsers send no `Origin` and are unaffected.
+   */
+  allowedOrigins?: readonly string[];
+  /**
+   * A secret every request must carry as `Authorization: Bearer
+   * <token>`. Worth setting whenever the port is reachable by anything
+   * other than the person's own agents.
+   */
+  token?: string;
+}
+/**
+ * The Streamable HTTP transport, as a `fetch` handler.
+ *
+ *   Bun.serve({ hostname: '127.0.0.1', port: 7310, fetch: mcpHandler(surface, { name: 'notes' }) });
+ *
+ * It answers every path; mount it where the server routes `/mcp`.
+ */
+declare function mcpHandler(surface: AgentSurfaceLike, options?: McpHandlerOptions): (request: Request) => Promise<Response>;
+//#endregion
+//#region src/agent/validate.d.ts
+/**
+ * Checks a value against the JSON Schema a channel description uses.
+ *
+ * Not a general validator. It understands the keywords
+ * `gesso-vite-plugin` writes (`type`, `enum`, `const`, `anyOf`,
+ * `items`, `prefixItems`, `minItems`, `properties`, `required`,
+ * `additionalProperties`, `not` and `$ref` into `$defs`), and passes
+ * anything else. That is enough to stop the case that matters: an
+ * agent sending `"3"` where a command takes a number, which the
+ * command would accept, store, and fail on much later and somewhere
+ * else.
+ *
+ * Returns the first problem as a sentence naming where it is, written
+ * for the agent that sent the value so it can correct itself, or null.
+ */
+declare function validate(schema: JsonSchema, value: unknown, root?: JsonSchema, at?: string): string | null;
+//#endregion
+//#region src/agent/remote.d.ts
+/**
+ * An agent surface across a thread.
+ *
+ * A web application's channels are served in workers, and an agent
+ * reaches the page, so the surface has to cross from one to the other.
+ * The worker that serves channels answers a `gesso:agent` port with its
+ * own surface (`serveAgentPort`); the page holds the other end as a
+ * surface of its own (`remoteSurface`); and a thread that knows several
+ * such ports, the render worker with its channel workers behind it,
+ * offers them as one (`combineSurfaces`).
+ *
+ * The four operations cross as they are. MCP itself is spoken only at
+ * the end that faces the agent, so nothing in a worker parses JSON-RPC.
+ */
+/** The port key a thread answers with its agent surface. */
+declare const AGENT_PORT = "gesso:agent";
+/** What crosses an agent port, page to worker. */
+type AgentPortRequest = {
+  id: number;
+  op: 'tools';
+} | {
+  id: number;
+  op: 'resources';
+} | {
+  id: number;
+  op: 'call';
+  name: string;
+  args?: Readonly<Record<string, unknown>>;
+} | {
+  id: number;
+  op: 'read';
+  uri: string;
+};
+/** What crosses back. */
+type AgentPortResponse = {
+  id: number;
+  result: unknown;
+} | {
+  id: number;
+  error: string;
+};
+/** How a thread asks the person, wherever the person is. */
+type AgentConfirm = (request: AgentConfirmation) => boolean | Promise<boolean>;
+/** A `MessagePort`, or anything that posts and receives like one. */
+type AgentPort = Pick<MessagePort, 'postMessage' | 'onmessage'>;
+/**
+ * Answers a port with a surface.
+ *
+ * The surface is made on the first request rather than when the port
+ * arrives: a port is opened by a page that may never ask anything, and
+ * a surface subscribes to every view key once it is used. It is given
+ * a `confirm` that asks the far end of this port, so a command marked
+ * `@confirm` reaches the person wherever they are; the far end answers
+ * no when it has no way to ask.
+ */
+declare function serveAgentPort(port: AgentPort, makeSurface: (confirm: AgentConfirm) => AgentSurfaceLike): () => void;
+/**
+ * The surface at the other end of a port.
+ *
+ * A request nobody answers within `timeoutMs` (default 2000) is taken
+ * as a thread with nothing to offer: a worker that serves no channels
+ * never installs the answering side, and an agent asking the whole
+ * application should hear about the threads that do rather than wait
+ * on one that does not.
+ */
+declare function remoteSurface(port: AgentPort, options?: {
+  timeoutMs?: number;
+  confirm?: AgentConfirm;
+}): AgentSurfaceLike;
+/**
+ * Several surfaces as one: tools and resources listed together, a call
+ * or a read sent to whichever surface listed it. When two list the same
+ * name, the first keeps it, as the order of the threads is the order
+ * the application registered them in.
+ */
+declare function combineSurfaces(surfaces: readonly AgentSurfaceLike[]): AgentSurfaceLike;
+//#endregion
+//#region src/agent/dev.d.ts
+/**
+ * The page's half of the development agent bridge.
+ *
+ * `gesso-vite-plugin` serves MCP at `/__gesso/mcp` on the dev server,
+ * but the channels are in the page's workers, and a server cannot
+ * reach a worker. The page can, and it already holds a socket to the
+ * server: Vite's HMR connection. So the server relays each JSON-RPC
+ * message down that socket, this answers it against the render
+ * worker's agent port, and the answer goes back up the same way.
+ *
+ * MCP is spoken here, in the page, rather than on the server, so the
+ * server needs nothing from the framework and the workers need nothing
+ * from MCP. The plugin injects the call in a dev server only; a build
+ * carries no reference to this module.
+ */
+/** The part of `import.meta.hot` this uses. */
+interface DevAgentHot {
+  send(event: string, data?: unknown): void;
+  on(event: string, listener: (data: never) => void): void;
+}
+/** What the bridge needs of an application: a way to reach its render worker. */
+interface DevAgentApp {
+  openRenderPort(key: string): MessagePort | undefined;
+}
+/** Server to page. */
+interface DevAgentRequest {
+  readonly id: number;
+  readonly message: unknown;
+}
+/** Page to server. */
+interface DevAgentResponse {
+  readonly id: number;
+  readonly response: JsonRpcResponse | null;
+}
+/** The HMR events the bridge speaks. The plugin's half uses the same names. */
+declare const DEV_AGENT_EVENTS: {
+  readonly ready: 'gesso:agent:ready';
+  readonly request: 'gesso:agent:request';
+  readonly response: 'gesso:agent:response';
+};
+declare function connectDevAgent(app: DevAgentApp, hot: DevAgentHot, info?: McpServerInfo): void;
+//#endregion
+//#region src/agent/webmcp.d.ts
+/**
+ * An application's channels, offered to an agent in the browser.
+ *
+ * WebMCP (https://webmachinelearning.github.io/webmcp/) is a page
+ * registering tools with the browser, `document.modelContext.registerTool`,
+ * for an agent the browser runs or hosts to call. It is MCP without
+ * the server: no port, no process, and the tools live exactly as long
+ * as the page does. The channel surface is already a list of tools
+ * with JSON Schema inputs and an answer per call, so this registers
+ * each one and routes its calls back through the render worker.
+ *
+ * What the spec gives a tool that a channel does not, and the reverse:
+ *
+ *   - `readOnlyHint` is a channel's view tool; `consequentialHint`, the
+ *     spec's "significant, real-world, or non-reversible", is a command
+ *     marked `@destructive`. `untrustedContentHint` is never set: a
+ *     channel's view is the application's own data.
+ *   - There is no output schema. The result of a call is serialized to
+ *     JSON for the agent, so a call answers with the view it left.
+ *   - There is no way to ask the person. A command marked `@confirm`
+ *     asks through `confirm`, `window.confirm` unless told otherwise.
+ *   - A failed call rejects, which the spec turns into a failed
+ *     `executeTool` the agent reads, with the sentence that says why.
+ *
+ * The API is behind an origin trial in Chrome 149 to 156, and was
+ * `navigator.modelContext` until Chrome 150; the old name is read when
+ * the new one is missing. Where neither exists, nothing is registered
+ * and nothing fails: a page offering tools to a browser that takes
+ * none is an ordinary page.
+ */
+/** The part of `ModelContext` this uses. */
+interface ModelContextLike {
+  registerTool(tool: {
+    name: string;
+    title?: string;
+    description: string;
+    inputSchema?: object;
+    annotations?: {
+      readOnlyHint?: boolean;
+      consequentialHint?: boolean;
+    };
+    execute: (input: Record<string, unknown>, options?: {
+      signal?: AbortSignal;
+    }) => Promise<unknown>;
+  }, options?: {
+    signal?: AbortSignal;
+  }): Promise<void>;
+}
+interface WebMcpOptions {
+  /**
+   * Asks the person whether a `@confirm` command may be sent. Defaults to
+   * the browser's own `window.confirm`, which an application with its
+   * own dialogs will want to replace.
+   */
+  confirm?: AgentConfirm;
+  /** Where to register. Defaults to the page's own `modelContext`. */
+  modelContext?: ModelContextLike;
+}
+/** The page's model context, if the browser has one. */
+declare function pageModelContext(): ModelContextLike | undefined;
+/**
+ * Registers every tool a surface offers, and returns what removes them.
+ *
+ * A tool the browser refuses, a name already taken by something else on
+ * the page, is reported on the console and skipped rather than taking
+ * the rest down with it. Resolves to a no-op when there is no model
+ * context to register with.
+ */
+declare function registerWebMcpTools(surface: AgentSurfaceLike, modelContext?: ModelContextLike | undefined): Promise<() => void>;
+/**
+ * Registers an application's channels once it is mounted.
+ *
+ * Reaches them the way the development bridge does, through an agent
+ * port to the render worker, so every channel the page can reach is
+ * offered, wherever it is served.
+ */
+declare function connectWebMcp(app: {
+  openRenderPort(key: string): MessagePort | undefined;
+}, options?: WebMcpOptions): Promise<() => void>;
+/** The browser's own dialog, worded for a person who did not ask for anything. */
+declare function confirmInWindow(request: AgentConfirmation): boolean;
+//#endregion
+//#region src/agent/app.d.ts
+/** What a thread that draws the application can offer an agent. */
+interface ApplicationAgentParts {
+  /** The channels fed from this thread. */
+  readonly channels: () => readonly ServedChannel[];
+  /** The workers behind it, each asked over an agent port of its own. */
+  readonly workers: () => Iterable<WorkerHandle>;
+  /** The screen, once the application has started. */
+  readonly ui: () => UiHost | undefined;
+}
+/**
+ * Answers an agent port with the whole application: the channels this
+ * thread feeds, whatever each worker behind it serves, and the screen.
+ *
+ * The thread that draws is the one that knows all three, which is the
+ * render worker in the worker configuration and the page in the single
+ * thread one; both answer with this. The screen comes last, so a
+ * channel tool keeps its name.
+ */
+declare function serveApplicationAgent(port: MessagePort, parts: ApplicationAgentParts): () => void;
+//#endregion
+export { AGENT_PORT, type AgentConfirmation, type AgentPortRequest, type AgentPortResponse, type AgentResource, type AgentSurface, type AgentSurfaceLike, type AgentSurfaceOptions, type AgentTool, type AgentToolResult, type ApplicationAgentParts, DEV_AGENT_EVENTS, type DevAgentApp, type DevAgentHot, type DevAgentRequest, type DevAgentResponse, type JsonRpcResponse, MCP_PROTOCOL_VERSIONS, type McpHandlerOptions, type McpServerInfo, type ModelContextLike, type UiHost, UiRefs, type UiSurfaceOptions, type WebMcpOptions, agentSurface, combineSurfaces, confirmInWindow, connectDevAgent, connectWebMcp, handleMcpMessage, mcpHandler, outline, pageModelContext, registerWebMcpTools, remoteSurface, resolveTarget, resourceUri, serveAgentPort, serveApplicationAgent, uiSurface, validate };
+//# sourceMappingURL=index.d.ts.map

package/dist/agent/index.js

@@ -0,0 +1,184 @@
+import { a as agentSurface, i as serveAgentPort, n as combineSurfaces, o as resourceUri, r as remoteSurface, s as validate, t as AGENT_PORT } from "../remote-xxij8zXe.js";
+import { a as resolveTarget, i as outline, n as serveApplicationAgent, o as uiSurface, r as UiRefs } from "../app-BvlIO1G9.js";
+import { i as registerWebMcpTools, n as connectWebMcp, r as pageModelContext, t as confirmInWindow } from "../webmcp-CJVFvAHe.js";
+//#region src/agent/mcp.ts
+/**
+* An agent surface, served over the Model Context Protocol.
+*
+* Two layers. `handleMcpMessage` answers one JSON-RPC message and knows
+* nothing about how it arrived, which is all a stdio transport or a
+* relay needs. `mcpHandler` wraps it in MCP's Streamable HTTP
+* transport as a `fetch`-style function, `(Request) => Response`,
+* which is what `Bun.serve`, Deno, a service worker and every modern
+* Node server framework take, so the framework imports no server.
+*
+* What it implements is the part a channel needs: `initialize`, `ping`,
+* `tools/list`, `tools/call`, `resources/list` and `resources/read`.
+* Responses are plain JSON rather than an event stream, which the
+* transport allows, and the GET stream for server-initiated messages
+* is declined with 405, which it also allows: nothing here sends one,
+* so the capabilities say neither `listChanged` nor `subscribe`.
+*/
+/** The protocol revisions this server speaks, newest first. */
+const MCP_PROTOCOL_VERSIONS = [
+	"2025-11-25",
+	"2025-06-18",
+	"2025-03-26"
+];
+const PARSE_ERROR = -32700;
+const INVALID_REQUEST = -32600;
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+/** MCP's code for a resource that does not exist. */
+const RESOURCE_NOT_FOUND = -32002;
+/**
+* Answers one JSON-RPC message. Returns null for a notification, which
+* takes no answer, and never throws: a malformed message is answered
+* with the JSON-RPC error that says what was wrong with it.
+*/
+async function handleMcpMessage(surface, message, info = {}) {
+	if (!isRequest(message)) return error(null, INVALID_REQUEST, "Expected a JSON-RPC 2.0 request with a method.");
+	if (message.id === void 0) return null;
+	const { id } = message;
+	const params = message.params ?? {};
+	switch (message.method) {
+		case "initialize": {
+			const asked = params.protocolVersion;
+			return ok(id, {
+				protocolVersion: MCP_PROTOCOL_VERSIONS.find((supported) => supported === asked) ?? MCP_PROTOCOL_VERSIONS[0],
+				capabilities: {
+					tools: {},
+					resources: {}
+				},
+				serverInfo: {
+					name: info.name ?? "gesso",
+					version: info.version ?? "0.0.0"
+				},
+				...info.instructions === void 0 ? {} : { instructions: info.instructions }
+			});
+		}
+		case "ping": return ok(id, {});
+		case "tools/list": return ok(id, { tools: await surface.tools() });
+		case "tools/call": {
+			if (typeof params.name !== "string") return error(id, INVALID_PARAMS, "tools/call needs the name of a tool.");
+			const args = params.arguments;
+			if (args !== void 0 && (args === null || typeof args !== "object" || Array.isArray(args))) return error(id, INVALID_PARAMS, "tools/call arguments must be an object.");
+			return ok(id, await surface.call(params.name, args));
+		}
+		case "resources/list": return ok(id, { resources: await surface.resources() });
+		case "resources/templates/list": return ok(id, { resourceTemplates: [] });
+		case "resources/read": {
+			const uri = params.uri;
+			const view = typeof uri === "string" ? await surface.read(uri) : void 0;
+			if (typeof uri !== "string" || view === void 0) return error(id, RESOURCE_NOT_FOUND, `No resource at ${String(uri)}.`);
+			return ok(id, { contents: [{
+				uri,
+				mimeType: "application/json",
+				text: JSON.stringify(view)
+			}] });
+		}
+		default: return error(id, METHOD_NOT_FOUND, `This server does not implement ${message.method}.`);
+	}
+}
+/**
+* The Streamable HTTP transport, as a `fetch` handler.
+*
+*   Bun.serve({ hostname: '127.0.0.1', port: 7310, fetch: mcpHandler(surface, { name: 'notes' }) });
+*
+* It answers every path; mount it where the server routes `/mcp`.
+*/
+function mcpHandler(surface, options = {}) {
+	return async (request) => {
+		const origin = request.headers.get("origin");
+		if (origin !== null && !(options.allowedOrigins ?? []).includes(origin)) return text(403, `Requests from ${origin} are not allowed.`);
+		if (options.token !== void 0 && request.headers.get("authorization") !== `Bearer ${options.token}`) return text(401, "This server needs a bearer token.");
+		const version = request.headers.get("mcp-protocol-version");
+		if (version !== null && !MCP_PROTOCOL_VERSIONS.includes(version)) return text(400, `Unsupported MCP protocol version ${version}.`);
+		if (request.method !== "POST") return new Response(null, {
+			status: 405,
+			headers: { allow: "POST" }
+		});
+		let message;
+		try {
+			message = await request.json();
+		} catch {
+			return json(400, error(null, PARSE_ERROR, "The body is not JSON."));
+		}
+		const response = await handleMcpMessage(surface, message, options);
+		return response === null ? new Response(null, { status: 202 }) : json(200, response);
+	};
+}
+function isRequest(message) {
+	const candidate = message;
+	return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate) && candidate.jsonrpc === "2.0" && typeof candidate.method === "string";
+}
+function ok(id, result) {
+	return {
+		jsonrpc: "2.0",
+		id,
+		result
+	};
+}
+function error(id, code, message) {
+	return {
+		jsonrpc: "2.0",
+		id,
+		error: {
+			code,
+			message
+		}
+	};
+}
+function json(status, body) {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "content-type": "application/json" }
+	});
+}
+function text(status, body) {
+	return new Response(body, {
+		status,
+		headers: { "content-type": "text/plain; charset=utf-8" }
+	});
+}
+//#endregion
+//#region src/agent/dev.ts
+/** The HMR events the bridge speaks. The plugin's half uses the same names. */
+const DEV_AGENT_EVENTS = {
+	ready: "gesso:agent:ready",
+	request: "gesso:agent:request",
+	response: "gesso:agent:response"
+};
+function connectDevAgent(app, hot, info = {}) {
+	let surface;
+	/**
+	* Opened on the first request, because the render worker does not
+	* exist until the app mounts, and an agent may well ask first.
+	*/
+	const reach = () => {
+		if (surface !== void 0) return surface;
+		const port = app.openRenderPort(AGENT_PORT);
+		if (port === void 0) return combineSurfaces([]);
+		surface = remoteSurface(port, { confirm: confirmInWindow });
+		return surface;
+	};
+	hot.on(DEV_AGENT_EVENTS.request, (request) => {
+		handleMcpMessage(reach(), request.message, {
+			name: info.name ?? (document.title || "gesso"),
+			...info
+		}).then((response) => hot.send(DEV_AGENT_EVENTS.response, {
+			id: request.id,
+			response
+		}));
+	});
+	const announce = () => hot.send(DEV_AGENT_EVENTS.ready, {
+		title: document.title,
+		url: location.href
+	});
+	announce();
+	hot.on("vite:ws:connect", announce);
+}
+//#endregion
+export { AGENT_PORT, DEV_AGENT_EVENTS, MCP_PROTOCOL_VERSIONS, UiRefs, agentSurface, combineSurfaces, confirmInWindow, connectDevAgent, connectWebMcp, handleMcpMessage, mcpHandler, outline, pageModelContext, registerWebMcpTools, remoteSurface, resolveTarget, resourceUri, serveAgentPort, serveApplicationAgent, uiSurface, validate };
+
+//# sourceMappingURL=index.js.map

package/dist/agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/agent/mcp.ts","../../src/agent/dev.ts"],"sourcesContent":["import type { AgentSurfaceLike } from './AgentSurface';\n\n/**\n * An agent surface, served over the Model Context Protocol.\n *\n * Two layers. `handleMcpMessage` answers one JSON-RPC message and knows\n * nothing about how it arrived, which is all a stdio transport or a\n * relay needs. `mcpHandler` wraps it in MCP's Streamable HTTP\n * transport as a `fetch`-style function, `(Request) => Response`,\n * which is what `Bun.serve`, Deno, a service worker and every modern\n * Node server framework take, so the framework imports no server.\n *\n * What it implements is the part a channel needs: `initialize`, `ping`,\n * `tools/list`, `tools/call`, `resources/list` and `resources/read`.\n * Responses are plain JSON rather than an event stream, which the\n * transport allows, and the GET stream for server-initiated messages\n * is declined with 405, which it also allows: nothing here sends one,\n * so the capabilities say neither `listChanged` nor `subscribe`.\n */\n\n/** The protocol revisions this server speaks, newest first. */\nexport const MCP_PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26'] as const;\n\nexport interface McpServerInfo {\n  /** The name a client shows for this server. Defaults to `gesso`. */\n  name?: string;\n  version?: string;\n  /** Told to the agent on connecting: what this application is, in a sentence or two. */\n  instructions?: string;\n}\n\ntype JsonRpcId = string | number;\n\ninterface JsonRpcRequest {\n  readonly jsonrpc: '2.0';\n  readonly id?: JsonRpcId;\n  readonly method: string;\n  readonly params?: Record<string, unknown>;\n}\n\nexport type JsonRpcResponse =\n  | { jsonrpc: '2.0'; id: JsonRpcId | null; result: unknown }\n  | { jsonrpc: '2.0'; id: JsonRpcId | null; error: { code: number; message: string } };\n\nconst PARSE_ERROR = -32700;\nconst INVALID_REQUEST = -32600;\nconst METHOD_NOT_FOUND = -32601;\nconst INVALID_PARAMS = -32602;\n/** MCP's code for a resource that does not exist. */\nconst RESOURCE_NOT_FOUND = -32002;\n\n/**\n * Answers one JSON-RPC message. Returns null for a notification, which\n * takes no answer, and never throws: a malformed message is answered\n * with the JSON-RPC error that says what was wrong with it.\n */\nexport async function handleMcpMessage(\n  surface: AgentSurfaceLike,\n  message: unknown,\n  info: McpServerInfo = {}\n): Promise<JsonRpcResponse | null> {\n  if (!isRequest(message)) {\n    return error(null, INVALID_REQUEST, 'Expected a JSON-RPC 2.0 request with a method.');\n  }\n  if (message.id === undefined) {\n    // `notifications/initialized` and `notifications/cancelled` are the\n    // ones a client sends. Neither needs anything from a server whose\n    // every call answers before the next is read.\n    return null;\n  }\n  const { id } = message;\n  const params = message.params ?? {};\n  switch (message.method) {\n    case 'initialize': {\n      const asked = params.protocolVersion;\n      const version = MCP_PROTOCOL_VERSIONS.find(supported => supported === asked) ?? MCP_PROTOCOL_VERSIONS[0];\n      return ok(id, {\n        protocolVersion: version,\n        capabilities: { tools: {}, resources: {} },\n        serverInfo: { name: info.name ?? 'gesso', version: info.version ?? '0.0.0' },\n        ...(info.instructions === undefined ? {} : { instructions: info.instructions })\n      });\n    }\n    case 'ping':\n      return ok(id, {});\n    case 'tools/list':\n      return ok(id, { tools: await surface.tools() });\n    case 'tools/call': {\n      if (typeof params.name !== 'string') {\n        return error(id, INVALID_PARAMS, 'tools/call needs the name of a tool.');\n      }\n      const args = params.arguments;\n      if (args !== undefined && (args === null || typeof args !== 'object' || Array.isArray(args))) {\n        return error(id, INVALID_PARAMS, 'tools/call arguments must be an object.');\n      }\n      return ok(id, await surface.call(params.name, args as Record<string, unknown> | undefined));\n    }\n    case 'resources/list':\n      return ok(id, { resources: await surface.resources() });\n    case 'resources/templates/list':\n      return ok(id, { resourceTemplates: [] });\n    case 'resources/read': {\n      const uri = params.uri;\n      const view = typeof uri === 'string' ? await surface.read(uri) : undefined;\n      if (typeof uri !== 'string' || view === undefined) {\n        return error(id, RESOURCE_NOT_FOUND, `No resource at ${String(uri)}.`);\n      }\n      return ok(id, { contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(view) }] });\n    }\n    default:\n      return error(id, METHOD_NOT_FOUND, `This server does not implement ${message.method}.`);\n  }\n}\n\nexport interface McpHandlerOptions extends McpServerInfo {\n  /**\n   * Origins a browser may call from. A request carrying any other\n   * `Origin` is refused, as the transport requires: without it, a web\n   * page the person happens to have open could reach a server bound to\n   * their own machine and send commands to their application. Agents\n   * that are not browsers send no `Origin` and are unaffected.\n   */\n  allowedOrigins?: readonly string[];\n  /**\n   * A secret every request must carry as `Authorization: Bearer\n   * <token>`. Worth setting whenever the port is reachable by anything\n   * other than the person's own agents.\n   */\n  token?: string;\n}\n\n/**\n * The Streamable HTTP transport, as a `fetch` handler.\n *\n *   Bun.serve({ hostname: '127.0.0.1', port: 7310, fetch: mcpHandler(surface, { name: 'notes' }) });\n *\n * It answers every path; mount it where the server routes `/mcp`.\n */\nexport function mcpHandler(\n  surface: AgentSurfaceLike,\n  options: McpHandlerOptions = {}\n): (request: Request) => Promise<Response> {\n  return async request => {\n    const origin = request.headers.get('origin');\n    if (origin !== null && !(options.allowedOrigins ?? []).includes(origin)) {\n      return text(403, `Requests from ${origin} are not allowed.`);\n    }\n    if (options.token !== undefined && request.headers.get('authorization') !== `Bearer ${options.token}`) {\n      return text(401, 'This server needs a bearer token.');\n    }\n    const version = request.headers.get('mcp-protocol-version');\n    if (version !== null && !(MCP_PROTOCOL_VERSIONS as readonly string[]).includes(version)) {\n      return text(400, `Unsupported MCP protocol version ${version}.`);\n    }\n    if (request.method !== 'POST') {\n      // GET is the optional stream for messages the server starts, and\n      // DELETE ends a session. There are no such messages and no\n      // sessions, and 405 is how the transport says so.\n      return new Response(null, { status: 405, headers: { allow: 'POST' } });\n    }\n    let message: unknown;\n    try {\n      message = await request.json();\n    } catch {\n      return json(400, error(null, PARSE_ERROR, 'The body is not JSON.'));\n    }\n    const response = await handleMcpMessage(surface, message, options);\n    return response === null ? new Response(null, { status: 202 }) : json(200, response);\n  };\n}\n\nfunction isRequest(message: unknown): message is JsonRpcRequest {\n  const candidate = message as Partial<JsonRpcRequest> | null;\n  return (\n    typeof candidate === 'object' &&\n    candidate !== null &&\n    !Array.isArray(candidate) &&\n    candidate.jsonrpc === '2.0' &&\n    typeof candidate.method === 'string'\n  );\n}\n\nfunction ok(id: JsonRpcId, result: unknown): JsonRpcResponse {\n  return { jsonrpc: '2.0', id, result };\n}\n\nfunction error(id: JsonRpcId | null, code: number, message: string): JsonRpcResponse {\n  return { jsonrpc: '2.0', id, error: { code, message } };\n}\n\nfunction json(status: number, body: unknown): Response {\n  return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });\n}\n\nfunction text(status: number, body: string): Response {\n  return new Response(body, { status, headers: { 'content-type': 'text/plain; charset=utf-8' } });\n}\n","import { handleMcpMessage, type JsonRpcResponse, type McpServerInfo } from './mcp';\nimport { AGENT_PORT, combineSurfaces, remoteSurface } from './remote';\nimport { confirmInWindow } from './webmcp';\nimport type { AgentSurfaceLike } from './AgentSurface';\n\n/**\n * The page's half of the development agent bridge.\n *\n * `gesso-vite-plugin` serves MCP at `/__gesso/mcp` on the dev server,\n * but the channels are in the page's workers, and a server cannot\n * reach a worker. The page can, and it already holds a socket to the\n * server: Vite's HMR connection. So the server relays each JSON-RPC\n * message down that socket, this answers it against the render\n * worker's agent port, and the answer goes back up the same way.\n *\n * MCP is spoken here, in the page, rather than on the server, so the\n * server needs nothing from the framework and the workers need nothing\n * from MCP. The plugin injects the call in a dev server only; a build\n * carries no reference to this module.\n */\n\n/** The part of `import.meta.hot` this uses. */\nexport interface DevAgentHot {\n  send(event: string, data?: unknown): void;\n  on(event: string, listener: (data: never) => void): void;\n}\n\n/** What the bridge needs of an application: a way to reach its render worker. */\nexport interface DevAgentApp {\n  openRenderPort(key: string): MessagePort | undefined;\n}\n\n/** Server to page. */\nexport interface DevAgentRequest {\n  readonly id: number;\n  readonly message: unknown;\n}\n\n/** Page to server. */\nexport interface DevAgentResponse {\n  readonly id: number;\n  readonly response: JsonRpcResponse | null;\n}\n\n/** The HMR events the bridge speaks. The plugin's half uses the same names. */\nexport const DEV_AGENT_EVENTS = {\n  ready: 'gesso:agent:ready',\n  request: 'gesso:agent:request',\n  response: 'gesso:agent:response'\n} as const;\n\nexport function connectDevAgent(app: DevAgentApp, hot: DevAgentHot, info: McpServerInfo = {}): void {\n  let surface: AgentSurfaceLike | undefined;\n  /**\n   * Opened on the first request, because the render worker does not\n   * exist until the app mounts, and an agent may well ask first.\n   */\n  const reach = (): AgentSurfaceLike => {\n    if (surface !== undefined) {\n      return surface;\n    }\n    const port = app.openRenderPort(AGENT_PORT);\n    if (port === undefined) {\n      return combineSurfaces([]);\n    }\n    // A command marked `@confirm` is put to the person here, in the\n    // page they are looking at. A browser's own dialog: in development\n    // that is enough, and it cannot be mistaken for the application's.\n    surface = remoteSurface(port, { confirm: confirmInWindow });\n    return surface;\n  };\n  hot.on(DEV_AGENT_EVENTS.request, (request: DevAgentRequest) => {\n    void handleMcpMessage(reach(), request.message, {\n      name: info.name ?? (document.title || 'gesso'),\n      ...info\n    }).then(response => hot.send(DEV_AGENT_EVENTS.response, { id: request.id, response } satisfies DevAgentResponse));\n  });\n  const announce = () => hot.send(DEV_AGENT_EVENTS.ready, { title: document.title, url: location.href });\n  announce();\n  // A restarted dev server is a new one that has never heard of this\n  // page, and the page reconnects to it without reloading. Saying so\n  // again on every connection is what keeps an agent from being told\n  // no page is open while one plainly is.\n  hot.on('vite:ws:connect', announce);\n}\n"],"mappings":"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"}