gesso-vite-plugin 0.4.2 → 0.5.0

package/dist/index.js

@@ -1,3 +1,154 @@
+import { defaultClientConditions } from "vite";
+//#region src/agent.ts
+/**
+* The dev server's half of the agent bridge: MCP at `/__gesso/mcp`.
+*
+* An agent such as Claude Code connects to an MCP server by URL, and
+* the dev server already has one. But the channels it should offer live
+* in the page's workers, and a server cannot reach a worker. The page
+* can, and it holds a socket to the server already, Vite's HMR
+* connection. So this relays: each JSON-RPC message an agent posts goes
+* down that socket to the page, `connectDevAgent` in `gesso-framework/agent`
+* answers it against the render worker, and the answer comes back up
+* and out as the HTTP response.
+*
+* MCP is spoken in the page rather than here, so this file imports
+* nothing from the framework and parses nothing but enough JSON to
+* know a request from a notification.
+*
+* Several tabs may be open. The newest to announce itself answers,
+* which is the one a person most likely means, and a tab that closes
+* hands back to the one before it.
+*/
+/** The path an agent is pointed at. */
+const AGENT_PATH = "/__gesso/mcp";
+/** The HMR events, as `connectDevAgent` names them. */
+const EVENTS = {
+	ready: "gesso:agent:ready",
+	request: "gesso:agent:request",
+	response: "gesso:agent:response"
+};
+function createAgentBridge(socket, options = {}) {
+	const timeoutMs = options.timeoutMs ?? 13e4;
+	/** Pages that announced themselves, newest last. */
+	const pages = [];
+	const pending = /* @__PURE__ */ new Map();
+	let next = 1;
+	socket.on(EVENTS.ready, (_data, client) => {
+		const at = pages.indexOf(client);
+		if (at >= 0) pages.splice(at, 1);
+		pages.push(client);
+	});
+	socket.on("vite:ws:disconnect", (_data, client) => {
+		const at = pages.indexOf(client);
+		if (at >= 0) pages.splice(at, 1);
+	});
+	socket.on(EVENTS.response, (data) => {
+		const resolve = pending.get(data.id);
+		if (resolve !== void 0) {
+			pending.delete(data.id);
+			resolve(data.response);
+		}
+	});
+	const relay = (message) => {
+		const page = pages[pages.length - 1];
+		const id = next++;
+		return new Promise((resolve) => {
+			const timer = setTimeout(() => {
+				pending.delete(id);
+				resolve(rpcError(message, -32001, `The page did not answer within ${Math.round(timeoutMs / 1e3)} seconds.`));
+			}, timeoutMs);
+			pending.set(id, (response) => {
+				clearTimeout(timer);
+				resolve(response);
+			});
+			page.send(EVENTS.request, {
+				id,
+				message
+			});
+		});
+	};
+	return {
+		get connected() {
+			return pages.length > 0;
+		},
+		middleware(request, response, next) {
+			if (request.url?.split("?")[0] !== "/__gesso/mcp") {
+				next();
+				return;
+			}
+			if (request.headers.origin !== void 0) {
+				send(response, 403, "text/plain", "The agent endpoint does not take requests from browser pages.");
+				return;
+			}
+			if (request.method !== "POST") {
+				response.setHeader("allow", "POST");
+				send(response, 405, "text/plain", "POST JSON-RPC messages here.");
+				return;
+			}
+			let body = "";
+			request.on("data", (chunk) => {
+				body += chunk.toString();
+			});
+			request.on("end", () => {
+				let message;
+				try {
+					message = JSON.parse(body);
+				} catch {
+					send(response, 400, "application/json", JSON.stringify(rpcError(null, -32700, "The body is not JSON.")));
+					return;
+				}
+				const notification = typeof message === "object" && message !== null && !("id" in message);
+				if (pages.length === 0) {
+					if (notification) {
+						send(response, 202);
+						return;
+					}
+					send(response, 200, "application/json", JSON.stringify(rpcError(message, -32e3, "No page is running the application. Open it in a browser from this dev server; the agent bridge runs in the page, because that is where the channels are.")));
+					return;
+				}
+				relay(message).then((answer) => {
+					if (answer === null || answer === void 0) send(response, 202);
+					else send(response, 200, "application/json", JSON.stringify(answer));
+				});
+			});
+		}
+	};
+}
+function send(response, status, type, body) {
+	response.statusCode = status;
+	if (type !== void 0) response.setHeader("content-type", type);
+	response.end(body);
+}
+function rpcError(message, code, text) {
+	const id = message?.id;
+	return {
+		jsonrpc: "2.0",
+		id: typeof id === "string" || typeof id === "number" ? id : null,
+		error: {
+			code,
+			message: text
+		}
+	};
+}
+/**
+* What the shell module gets in a dev server: the app, handed to the
+* page's half of the bridge once `gesso-framework/agent` has loaded.
+* Loaded on demand, so the page pays for it only in development.
+*/
+const SHELL_BRIDGE = `function __gessoAgent(app) {
+  if (typeof app.useWebMcp === 'function') {
+    // A single-thread builder: on by default here, as \`webmcp: true\`
+    // is for createApp, and a later useWebMcp(false) still decides.
+    app.useWebMcp(true);
+  }
+  if (import.meta.hot) {
+    void import('gesso-framework/agent').then(({ connectDevAgent }) => connectDevAgent(app, import.meta.hot));
+  }
+  return app;
+}
+`;
+//#endregion
 //#region src/source.ts
 const IDENTIFIER = /[A-Za-z0-9_$]/;
 /**
@@ -233,6 +384,470 @@ function importedNames(clause) {
 	return names;
 }
 //#endregion
+//#region src/contracts.ts
+/** The functions that declare a channel. */
+const DECLARATIONS = ["channel", "defineChannel"];
+/**
+* Whether a module declares a channel, without asking the checker.
+*
+* The checker is a process round trip per question, and every module
+* the application has passes through `transform`, so this is the gate:
+* a call to `channel` or `defineChannel` imported from
+* `gesso-framework`. A module that re-exports a token someone else
+* declared is not a contract, and the module that declared it is the
+* one described.
+*/
+function declaresChannel(code) {
+	if (!code.includes("gesso-framework")) return false;
+	const blank = blankLiterals(code);
+	const imports = importSources(code, blank);
+	return DECLARATIONS.some((name) => imports.get(name) === "gesso-framework" && (findCalls(code, name, blank).length > 0 || new RegExp(`(?<![\\w$.])${name}\\s*<`).test(blank)));
+}
+/**
+* The code appended to a contract module.
+*
+* An import at the bottom is still hoisted, and appending rather than
+* rewriting leaves every line the author wrote where they wrote it, so
+* the module's source map needs nothing.
+*/
+function describeCalls(channels) {
+	const lines = ["import { describeChannel as __gessoDescribeChannel } from 'gesso-framework';"];
+	for (const [name, schema] of channels) lines.push(`__gessoDescribeChannel(${name}, ${JSON.stringify(schema)});`);
+	return `\n${lines.join("\n")}\n`;
+}
+/**
+* A module that describes channels when it is imported, for a bundle
+* this plugin never sees.
+*
+* The plugin describes a contract by appending to it as Vite bundles
+* it. An Electrobun main process is bundled by Electrobun's own build,
+* which takes no plugins, so there the description is written ahead of
+* time instead: `gesso-channels` reads the contracts with the same
+* checker and writes this module, and the main process imports it once.
+* A token is imported from its contract, so the schema lands on the
+* same object the application serves.
+*
+* `outFile` and every `file` are absolute POSIX paths.
+*/
+function describedModule(contracts, outFile) {
+	const lines = [
+		"// Written by gesso-channels from the channel contracts it names below.",
+		"// Run it again after changing a contract rather than editing this file.",
+		"import { describeChannel } from 'gesso-framework';"
+	];
+	const from = outFile.slice(0, outFile.lastIndexOf("/"));
+	for (const contract of contracts) if (contract.channels.size > 0) {
+		const names = [...contract.channels.keys()].join(", ");
+		lines.push(`import { ${names} } from '${importPath(from, contract.file)}';`);
+	}
+	for (const contract of contracts) for (const [name, schema] of contract.channels) lines.push("", `describeChannel(${name}, ${JSON.stringify(schema, null, 2)});`);
+	return `${lines.join("\n")}\n`;
+}
+/** `./Counter` from `/app/src/shared` to `/app/src/shared/Counter.ts`, without the extension. */
+function importPath(fromDir, file) {
+	const from = fromDir.split("/").filter(Boolean);
+	const to = file.replace(/\.[cm]?[jt]sx?$/, "").split("/").filter(Boolean);
+	let shared = 0;
+	while (shared < from.length && shared < to.length - 1 && from[shared] === to[shared]) shared++;
+	const up = from.length - shared;
+	const rest = to.slice(shared).join("/");
+	return up === 0 ? `./${rest}` : `${"../".repeat(up)}${rest}`;
+}
+/**
+* The checker, held open across reads.
+*
+* Spawning it and loading a project costs about a hundred
+* milliseconds; a question after that costs well under one. So one
+* reader lives as long as the dev server or the build, is told which
+* files changed between reads, and is closed at the end, because the
+* process it holds would otherwise keep the build from exiting.
+*/
+var ContractReader = class {
+	api = null;
+	changed = /* @__PURE__ */ new Set();
+	/** Each contract's tsconfig, found once. */
+	configs = /* @__PURE__ */ new Map();
+	/**
+	* @param fs Callbacks the checker reads through before the disk, for
+	*   a spec that keeps its project in memory.
+	*/
+	ts;
+	cwd;
+	fs;
+	constructor(ts, cwd, fs) {
+		this.ts = ts;
+		this.cwd = cwd;
+		this.fs = fs;
+	}
+	/** A file changed on disk since the last read. */
+	invalidate(file) {
+		this.changed.add(file);
+	}
+	/** Every channel `file` exports, described. */
+	read(file) {
+		const api = this.api ??= new this.ts.API({
+			cwd: this.cwd,
+			...this.fs === void 0 ? {} : { fs: this.fs }
+		});
+		this.changed.add(file);
+		let snapshot = api.updateSnapshot({ fileChanges: { changed: [...this.changed] } });
+		this.changed.clear();
+		let config = this.configs.get(file);
+		if (config === void 0) {
+			config = api.updateSnapshot({ openFiles: [file] }).getDefaultProjectForFile(file)?.configFileName;
+			snapshot = api.updateSnapshot({
+				...config === void 0 ? {} : { openProjects: [config] },
+				closeFiles: [file]
+			});
+			if (config !== void 0) this.configs.set(file, config);
+		}
+		const project = config === void 0 ? void 0 : snapshot.getProject(config);
+		const source = project?.program.getSourceFile(file);
+		if (project === void 0 || source === void 0) return {
+			channels: /* @__PURE__ */ new Map(),
+			warnings: [`TypeScript has no project that includes ${file}.`]
+		};
+		const checker = project.checker;
+		const module = checker.getSymbolAtLocation(source);
+		const describer = new Describer(this.ts, checker);
+		const channels = /* @__PURE__ */ new Map();
+		for (const exported of module === void 0 ? [] : checker.getExportsOfModule(module)) {
+			const type = checker.getTypeOfSymbol(exported);
+			if (type === void 0 || type.getSymbol()?.name !== "ChannelToken") continue;
+			const [view, commands] = checker.getTypeArguments(type);
+			channels.set(exported.name, describer.channel(exported, view, commands));
+		}
+		return {
+			channels,
+			warnings: describer.warnings
+		};
+	}
+	close() {
+		this.api?.close();
+		this.api = null;
+	}
+};
+/**
+* Library types that are objects to the checker and not plain data to
+* a channel. They compare by reference, so `provide` rejects them on
+* their first value; describing their methods as properties would be
+* describing something that never arrives.
+*/
+const NOT_PLAIN = /* @__PURE__ */ new Set([
+	"Date",
+	"Map",
+	"ReadonlyMap",
+	"Set",
+	"ReadonlySet",
+	"WeakMap",
+	"WeakSet",
+	"Promise",
+	"RegExp",
+	"Error",
+	"ArrayBuffer",
+	"SharedArrayBuffer",
+	"DataView",
+	"Blob",
+	"File",
+	"URL",
+	"Int8Array",
+	"Uint8Array",
+	"Uint8ClampedArray",
+	"Int16Array",
+	"Uint16Array",
+	"Int32Array",
+	"Uint32Array",
+	"Float32Array",
+	"Float64Array",
+	"BigInt64Array",
+	"BigUint64Array"
+]);
+/**
+* Bytes, which a command may carry and a view key may not.
+*
+* A command's argument is structured-cloned onto the owning thread, and
+* a typed array or an `ArrayBuffer` clones as itself: a file a person
+* dropped crosses as its bytes, with no encoding pass on the render
+* thread. A view key is diffed, and a differ that compares bytes by
+* reference reports a change on every emission, so there they stay
+* unplain. In a command's schema they are a base64 string, which is
+* what an agent can write, tagged with the type the command expects so
+* the agent surface can turn the string back into it.
+*/
+const BINARY = /* @__PURE__ */ new Set([
+	"ArrayBuffer",
+	"Int8Array",
+	"Uint8Array",
+	"Uint8ClampedArray",
+	"Int16Array",
+	"Uint16Array",
+	"Int32Array",
+	"Uint32Array",
+	"Float32Array",
+	"Float64Array",
+	"BigInt64Array",
+	"BigUint64Array"
+]);
+/** Turns checker types into JSON Schema for one module's channels. */
+var Describer = class {
+	warnings = [];
+	flags;
+	/** Describing a command's parameters, where bytes are allowed; see `BINARY`. */
+	inCommand = false;
+	/** Types being described right now, to notice a type that contains itself. */
+	inProgress = /* @__PURE__ */ new Set();
+	/** Types found to contain themselves, which are described once in `$defs`. */
+	recursive = /* @__PURE__ */ new Set();
+	/** `$defs` for the schema being built. Reset per root, so each schema stands alone. */
+	defs = /* @__PURE__ */ new Map();
+	defNames = /* @__PURE__ */ new Map();
+	ts;
+	checker;
+	constructor(ts, checker) {
+		this.ts = ts;
+		this.checker = checker;
+		this.flags = ts.TypeFlags;
+	}
+	channel(token, view, commands) {
+		const out = {
+			view: this.root(view, `${token.name}.view`),
+			commands: {}
+		};
+		const description = this.checker.getDocumentationCommentOfSymbol(token);
+		if (description !== "") out.description = description;
+		if (commands !== void 0) for (const command of this.checker.getPropertiesOfType(commands)) {
+			const described = this.command(command, `${token.name}.commands.${command.name}`);
+			if (described !== null) out.commands[command.name] = described;
+		}
+		return out;
+	}
+	/** A schema that stands alone: its own `$defs`, if anything in it recurs. */
+	root(type, path) {
+		this.defs = /* @__PURE__ */ new Map();
+		const schema = this.describe(type, path);
+		if (this.defs.size > 0) return {
+			...schema,
+			$defs: Object.fromEntries(this.defs)
+		};
+		return schema;
+	}
+	command(symbol, path) {
+		const type = this.checker.getTypeOfSymbol(symbol);
+		const signatures = type === void 0 ? [] : this.checker.getSignaturesOfType(type, this.ts.SignatureKind.Call);
+		if (signatures.length === 0) {
+			this.warnings.push(`${path} is not a function, so it is not a command an agent can send.`);
+			return null;
+		}
+		if (signatures.length > 1) this.warnings.push(`${path} is overloaded; only its first signature is described.`);
+		const signature = signatures[0];
+		const tags = this.checker.getJsDocTagsOfSymbol(symbol);
+		const parameters = signature.getParameters();
+		this.defs = /* @__PURE__ */ new Map();
+		const properties = {};
+		const required = [];
+		this.inCommand = true;
+		parameters.forEach((parameter, index) => {
+			const parameterType = this.checker.getTypeOfSymbol(parameter);
+			const optional = parameterType !== void 0 && this.includesUndefined(parameterType);
+			const schema = parameterType === void 0 ? {} : this.describe(parameterType, `${path}(${parameter.name})`);
+			const description = this.parameterDescription(parameter, tags);
+			properties[parameter.name] = description === "" ? schema : {
+				...schema,
+				description
+			};
+			const rest = signature.hasRestParameter && index === parameters.length - 1;
+			if (!optional && !rest) required.push(parameter.name);
+		});
+		this.inCommand = false;
+		const input = {
+			type: "object",
+			properties,
+			additionalProperties: false
+		};
+		if (required.length > 0) input.required = required;
+		if (this.defs.size > 0) input.$defs = Object.fromEntries(this.defs);
+		const out = {
+			parameters: parameters.map((parameter) => parameter.name),
+			input
+		};
+		const description = this.checker.getDocumentationCommentOfSymbol(symbol);
+		if (description !== "") out.description = description;
+		if (signature.hasRestParameter) out.rest = true;
+		for (const annotation of [
+			"destructive",
+			"idempotent",
+			"confirm",
+			"hidden"
+		]) if (tags.some((tag) => tag.name === annotation)) out[annotation] = true;
+		return out;
+	}
+	/**
+	* A parameter's own comment, or failing that its `@param` line.
+	*
+	* The checker attaches `@param` text to the parameter of a method
+	* signature. A command written as a property, `move: (from: number)
+	* => void`, keeps its comment on the property, so the tag is read
+	* from there instead.
+	*/
+	parameterDescription(parameter, tags) {
+		const own = this.checker.getDocumentationCommentOfSymbol(parameter);
+		if (own !== "") return own;
+		for (const tag of tags) {
+			const match = tag.name === "param" ? /^\s*(\S+)\s*(?:-\s*)?([\s\S]*)$/.exec(tag.text ?? "") : null;
+			if (match !== null && match[1] === parameter.name) return match[2].trim();
+		}
+		return "";
+	}
+	includesUndefined(type) {
+		const { Undefined, Void } = this.flags;
+		if (type.isUnionType()) return (type.getTypes() ?? []).some((member) => (member.flags & (Undefined | Void)) !== 0);
+		return (type.flags & (Undefined | Void)) !== 0;
+	}
+	describe(type, path) {
+		const f = this.flags;
+		const flags = type.flags;
+		if (flags & (f.Any | f.Unknown)) return {};
+		if (flags & f.Never) {
+			this.warnings.push(`${path} is never, which describes no value. An empty array literal is never[] unless it says what it holds: write \`[] as Row[]\`.`);
+			return { not: {} };
+		}
+		if (flags & (f.String | f.TemplateLiteral | f.StringMapping)) return { type: "string" };
+		if (flags & f.Number) return { type: "number" };
+		if (flags & f.Boolean) return { type: "boolean" };
+		if (flags & f.Null) return { type: "null" };
+		if (flags & (f.Undefined | f.Void)) return {};
+		if (flags & f.BooleanLiteral) return { const: type.intrinsicName === "true" };
+		if (flags & (f.StringLiteral | f.NumberLiteral)) return { const: type.value };
+		if (flags & (f.BigInt | f.BigIntLiteral | f.ESSymbol | f.UniqueESSymbol)) return this.unplain(path, flags & f.BigIntLike ? "a bigint" : "a symbol");
+		if (type.isUnionType()) return this.union(type, path);
+		if (flags & f.TypeParameter) return {};
+		if (flags & (f.Object | f.Intersection)) {
+			if (this.checker.isArrayType(type)) {
+				const [element] = this.checker.getTypeArguments(type);
+				return {
+					type: "array",
+					items: element === void 0 ? {} : this.describe(element, `${path}[]`)
+				};
+			}
+			if (this.checker.isTupleType(type)) return this.tuple(type, path);
+			return this.named(type, path);
+		}
+		this.warnings.push(`${path} has a type this reader does not describe, so it is left open.`);
+		return {};
+	}
+	/**
+	* A union, with `undefined` taken out (optionality is said by
+	* `required`), `true | false` folded back into `boolean`, and a union
+	* of nothing but literals written as an `enum`.
+	*/
+	union(type, path) {
+		const f = this.flags;
+		let members = (type.getTypes() ?? []).filter((member) => (member.flags & (f.Undefined | f.Void)) === 0);
+		const booleans = members.filter((member) => member.flags & f.BooleanLiteral);
+		const schemas = [];
+		if (booleans.length === 2) {
+			members = members.filter((member) => !(member.flags & f.BooleanLiteral));
+			schemas.push({ type: "boolean" });
+		}
+		if (members.length > 0 && schemas.length === 0 && members.every((member) => member.flags & (f.StringLiteral | f.NumberLiteral))) return { enum: members.map((member) => member.value) };
+		members.sort((a, b) => Number((a.flags & f.Null) !== 0) - Number((b.flags & f.Null) !== 0));
+		schemas.push(...members.map((member) => this.describe(member, path)));
+		return schemas.length === 1 ? schemas[0] : { anyOf: schemas };
+	}
+	/**
+	* An object type, described once however often it appears, and by
+	* reference when it contains itself.
+	*/
+	named(type, path) {
+		const id = type.id;
+		if (this.inProgress.has(id)) {
+			this.recursive.add(id);
+			return { $ref: `#/$defs/${this.defName(type)}` };
+		}
+		this.inProgress.add(id);
+		const schema = this.object(type, path);
+		this.inProgress.delete(id);
+		if (this.recursive.has(id)) {
+			const name = this.defName(type);
+			this.defs.set(name, schema);
+			return { $ref: `#/$defs/${name}` };
+		}
+		return schema;
+	}
+	defName(type) {
+		let name = this.defNames.get(type.id);
+		if (name === void 0) {
+			const base = (type.getAliasSymbol() ?? type.getSymbol())?.name ?? "Type";
+			name = new Set(this.defNames.values()).has(base) ? `${base}${type.id}` : base;
+			this.defNames.set(type.id, name);
+		}
+		return name;
+	}
+	object(type, path) {
+		const checker = this.checker;
+		const symbolName = type.getSymbol()?.name;
+		if (symbolName !== void 0 && this.inCommand && BINARY.has(symbolName)) return {
+			type: "string",
+			contentEncoding: "base64",
+			"x-gesso-binary": symbolName
+		};
+		if (symbolName !== void 0 && NOT_PLAIN.has(symbolName)) return this.unplain(path, `a ${symbolName}`);
+		if (type.objectFlags & this.ts.ObjectFlags.Class) return this.unplain(path, `an instance of ${symbolName ?? "a class"}`);
+		if (checker.getSignaturesOfType(type, this.ts.SignatureKind.Call).length > 0) return this.unplain(path, "a function");
+		const properties = {};
+		const required = [];
+		for (const property of checker.getPropertiesOfType(type)) {
+			const propertyType = checker.getTypeOfSymbol(property);
+			const at = `${path}.${property.name}`;
+			if (propertyType === void 0) {
+				properties[property.name] = {};
+				continue;
+			}
+			const schema = this.describe(propertyType, at);
+			const description = checker.getDocumentationCommentOfSymbol(property);
+			properties[property.name] = description === "" ? schema : {
+				...schema,
+				description
+			};
+			if (!((property.flags & this.ts.SymbolFlags.Optional) !== 0 || this.includesUndefined(propertyType))) required.push(property.name);
+		}
+		const schema = {
+			type: "object",
+			properties
+		};
+		if (required.length > 0) schema.required = required;
+		const index = checker.getIndexInfosOfType(type).find((info) => info.keyType.flags & this.flags.String);
+		if (index !== void 0) schema.additionalProperties = this.describe(index.valueType, `${path}[key]`);
+		return schema;
+	}
+	tuple(type, path) {
+		const elements = this.checker.getTypeArguments(type);
+		const elementFlags = type.getTarget().elementFlags ?? [];
+		const { Required, Rest } = this.ts.ElementFlags;
+		const prefixItems = [];
+		let items = false;
+		let minItems = 0;
+		elements.forEach((element, index) => {
+			const schema = this.describe(element, `${path}[${index}]`);
+			if (elementFlags[index] & Rest) items = schema;
+			else {
+				prefixItems.push(schema);
+				if (elementFlags[index] & Required) minItems = index + 1;
+			}
+		});
+		return {
+			type: "array",
+			prefixItems,
+			items,
+			minItems
+		};
+	}
+	unplain(path, what) {
+		this.warnings.push(`${path} is ${what}, which is not plain data and cannot cross a channel.`);
+		return {};
+	}
+};
+//#endregion
 //#region src/render.ts
 const MARKER$1 = "/* gesso-vite-plugin: hot replacement */";
 /**
@@ -368,10 +983,12 @@ function findShellCall(code, blank = blankLiterals(code)) {
 function transformShell(code, options) {
 	const shell = findShellCall(code, blankLiterals(code));
 	if (shell === null) return null;
-	if (options.entries === null && !options.overlay) return null;
+	if (options.entries === null && !options.overlay && options.agent !== true) return null;
 	const { call } = shell;
 	const args = code.slice(call.argsStart, call.argsEnd).trim();
-	return `${`${code.slice(0, call.argsStart)}__gessoOptions(${args === "" ? "{}" : args})${code.slice(call.argsEnd)}`}\n${prelude(options)}`;
+	const created = `${code.slice(call.start, call.argsStart)}__gessoOptions(${args === "" ? "{}" : args})${code.slice(call.argsEnd, call.end)}`;
+	const wrapped = options.agent === true ? `__gessoAgent(${created})` : created;
+	return `${`${code.slice(0, call.start)}${wrapped}${code.slice(call.end)}`}\n${prelude(options)}${options.agent === true ? SHELL_BRIDGE : ""}`;
 }
 /**
 * The appended half: the worker construction, and in development the
@@ -394,6 +1011,7 @@ function prelude(options) {
 		...entries === null ? [] : [`    renderWorker: () => new Worker(new URL(${JSON.stringify(entries.renderWorker)}, import.meta.url), { type: 'module', name: options.workerName }),`],
 		...entries?.appLogicWorker == null ? [] : [`    appLogicWorker: () => new Worker(new URL(${JSON.stringify(entries.appLogicWorker)}, import.meta.url), { type: 'module', name: options.workerName }),`],
 		...options.overlay ? ["    onError: __gessoReportError,"] : [],
+		...options.agent === true ? ["    webmcp: true,"] : [],
 		"    ...options",
 		"  };",
 		"}"
@@ -452,9 +1070,42 @@ addEventListener('unhandledrejection', event => {
   __gessoReportError(reason?.message ?? String(reason), reason?.stack, 'window');
 });
 `;
+/**
+* The single-thread shell in a dev server: `createSyncApp(Root)`
+* wrapped so the agent bridge gets the builder, which answers an agent
+* port from the page itself. There are no workers to write and no
+* overlay to wire here, so this is all the plugin does to such a shell.
+*/
+function transformSyncShell(code) {
+	if (code.includes(MARKER)) return null;
+	const blank = blankLiterals(code);
+	if (importSources(code, blank).get("createSyncApp") !== "gesso-framework") return null;
+	const call = findCall(code, "createSyncApp", blank);
+	if (call === null) return null;
+	const wrapped = `__gessoAgent(${code.slice(call.start, call.end)})`;
+	return `${code.slice(0, call.start)}${wrapped}${code.slice(call.end)}\n${MARKER}\n${SHELL_BRIDGE}`;
+}
 //#endregion
 //#region src/index.ts
 /**
+* The export conditions a Gesso application resolves its dependencies
+* with: `worker` ahead of Vite's defaults.
+*
+* A Gesso application's code runs in workers, and Vite resolves every
+* dependency with the `browser` condition, which is the right call for
+* a page and the wrong one for a worker: a package's browser build may
+* reach for `document`. `decode-named-character-reference`, which every
+* markdown parser built on micromark imports, does exactly that, and a
+* render worker that imported one died on start with "document is not
+* defined". The same package publishes a `worker` build, as packages
+* with a DOM-only browser build tend to. A package's own export order
+* decides between the two, and those list `worker` first.
+*
+* The main thread resolves the same way. A worker build runs in a page
+* as well, and the shell imports little beyond Gesso itself.
+*/
+const workerConditions = ["worker", ...defaultClientConditions];
+/**
 * Where a render worker entry is looked for, beside the shell.
 *
 * Ordered so that a name that says what the file is beats the generic
@@ -486,14 +1137,99 @@ function gesso(options = {}) {
 	let renderWorkerId = null;
 	/** Files already reported as reloading, so a save is not a stream of warnings. */
 	const reported = /* @__PURE__ */ new Set();
+	/** The checker, started by the first contract, or null once it is known to be unavailable. */
+	let contracts;
+	let root = "";
+	const readerFor = (warn) => contracts ??= import("typescript/unstable/sync").then((ts) => new ContractReader(ts, root), () => {
+		warn("Channels are not described, because TypeScript 7 is not installed. Add `typescript` (7 or later) to devDependencies, or pass `channelSchemas: false` to stop this message.");
+		return null;
+	});
+	const closeContracts = async () => {
+		(await contracts)?.close();
+		contracts = void 0;
+	};
+	/** The module with its channels described, or null when it declares none. */
+	const describeContract = async (code, id, warn) => {
+		if (options.channelSchemas === false || !SOURCE.test(id) || id.includes("/node_modules/") || !declaresChannel(code)) return null;
+		const reader = await readerFor(warn);
+		if (reader === null) return null;
+		const reading = reader.read(id.replace(/\?.*$/, ""));
+		reading.warnings.forEach(warn);
+		return reading.channels.size > 0 ? code + describeCalls(reading.channels) : null;
+	};
+	/**
+	* The same description, for a worker's bundle.
+	*
+	* A build bundles each worker with `worker.plugins` rather than with
+	* the plugins of the page, and a contract is imported by workers far
+	* more often than by the page, so without this a build would describe
+	* almost nothing. A dev server runs every module through the main
+	* plugins and does not need it. Each worker bundle closes the checker
+	* when it is done, because nothing guarantees another bundle follows
+	* to close it; the next contract starts it again.
+	*/
+	const workerContracts = {
+		name: "gesso:channel-schemas",
+		enforce: "pre",
+		async transform(code, id) {
+			const described = await describeContract(code, id, (message) => this.warn(message));
+			return described === null ? null : {
+				code: described,
+				map: null
+			};
+		},
+		async closeBundle() {
+			await closeContracts();
+		}
+	};
 	return {
 		name: "gesso",
 		enforce: "pre",
+		config(config) {
+			return {
+				...options.workerConditions === false ? {} : { resolve: { conditions: [...workerConditions] } },
+				worker: {
+					...config.worker?.format === void 0 ? { format: "es" } : {},
+					...options.channelSchemas === false ? {} : { plugins: () => [workerContracts] }
+				}
+			};
+		},
 		configResolved(config) {
 			serving = config.command === "serve";
+			root = config.root;
 		},
-		async transform(code, id) {
+		/**
+		* The agent endpoint, and a line saying where it is once the server
+		* is listening, because an endpoint nobody knows the address of is
+		* one nobody connects to.
+		*/
+		configureServer(server) {
+			if (options.agent === false) return;
+			const bridge = createAgentBridge(server.ws);
+			server.middlewares.use((request, response, next) => bridge.middleware(request, response, next));
+			server.httpServer?.once("listening", () => {
+				const base = server.resolvedUrls?.local[0];
+				if (base !== void 0) {
+					const url = new URL(AGENT_PATH, base).href;
+					server.config.logger.info(`  ➜  Agents:  ${url}\n             claude mcp add --transport http ${agentName(server.config.root)} ${url}`);
+				}
+			});
+		},
+		watchChange(id) {
+			contracts?.then((reader) => reader?.invalidate(id));
+		},
+		/**
+		* The checker is a child process, and a build that left it running
+		* would never exit. A dev server calls this when it closes, so the
+		* one hook covers both.
+		*/
+		async closeBundle() {
+			await closeContracts();
+		},
+		async transform(source, id) {
 			if (!SOURCE.test(id) || id.includes("/node_modules/")) return null;
+			const described = await describeContract(source, id, (message) => this.warn(message));
+			const code = described ?? source;
 			if (serving && options.hmr !== false) {
 				const wiring = transformRenderWorker(code);
 				if (wiring.skipped !== null) this.warn(`${wiring.skipped} Saving it will reload the page rather than replace the tree.`);
@@ -506,13 +1242,27 @@ function gesso(options = {}) {
 				}
 			}
 			const call = findShellCall(code);
-			if (call === null) return null;
+			if (call === null) {
+				const sync = serving && options.agent !== false ? transformSyncShell(code) : null;
+				if (sync !== null) return {
+					code: sync,
+					map: null
+				};
+				return described === null ? null : {
+					code,
+					map: null
+				};
+			}
 			shellId = id;
 			const shell = transformShell(code, {
 				entries: call.needsWorkers ? await resolveEntries(this, id, options) : null,
-				overlay: serving && options.overlay !== false
+				overlay: serving && options.overlay !== false,
+				agent: serving && options.agent !== false
 			});
-			return shell === null ? null : {
+			return shell === null ? described === null ? null : {
+				code,
+				map: null
+			} : {
 				code: shell,
 				map: null
 			};
@@ -539,6 +1289,10 @@ function gesso(options = {}) {
 		}
 	};
 }
+/** A name for the MCP server: the project's directory, which is what a person calls the app. */
+function agentName(root) {
+	return (root.split("/").filter(Boolean).pop() ?? "gesso").replace(/[^A-Za-z0-9_-]/g, "-");
+}
 /** Every module that transitively imports this one, plus this one. */
 function importerClosure(module) {
 	const seen = /* @__PURE__ */ new Set();
@@ -579,6 +1333,6 @@ async function firstResolved(context, importer, names) {
 	return null;
 }
 //#endregion
-export { blankLiterals, gesso as default, gesso, findCall, findCalls, findShellCall, firstArgumentName, importSources, transformRenderWorker, transformShell };
+export { ContractReader, blankLiterals, gesso as default, gesso, describedModule, findCall, findCalls, findShellCall, firstArgumentName, importSources, transformRenderWorker, transformShell, transformSyncShell, workerConditions };
 
 //# sourceMappingURL=index.js.map