gesso-framework 0.4.1 → 0.5.0

package/dist/remote-xxij8zXe.js

@@ -0,0 +1,600 @@
+//#region src/channel/ChannelSchema.ts
+/**
+* The schemas, beside the tokens rather than on them.
+*
+* A token is a plain object both threads import and nothing should
+* grow on, and its interface is a public type that a schema field would
+* widen for every application, described or not. Keyed weakly, so a
+* token the application drops takes its schema with it.
+*/
+const schemas = /* @__PURE__ */ new WeakMap();
+/**
+* Attaches a schema to a token.
+*
+* `gesso-vite-plugin` calls this at the bottom of each contract module
+* it reads, so it runs once, when the module is first imported. Call it
+* yourself to describe a channel the plugin does not see. A second call
+* for the same token replaces the first, which is what a hot-replaced
+* contract module does.
+*/
+function describeChannel(token, schema) {
+	schemas.set(token, schema);
+}
+/** The schema attached to a token, or undefined when nothing described it. */
+function channelSchema(token) {
+	return schemas.get(token);
+}
+//#endregion
+//#region src/agent/binary.ts
+/**
+* Turns the base64 an agent wrote back into the bytes a command takes.
+*
+* A command may carry an `ArrayBuffer` or a typed array, which an agent
+* cannot write: it speaks JSON. `gesso-vite-plugin` describes such a
+* field as a base64 string tagged `x-gesso-binary` with the type the
+* command expects, the agent sends the string, and this walks the
+* arguments beside their schema and puts the bytes back before the
+* command is sent, so the application receives what its own components
+* would have sent it.
+*
+* Only what the schema tags is touched, and a value that is not a
+* string where bytes are expected is left for the command to see: the
+* validator has already said whether it was the right shape.
+*/
+function decodeBinary(schema, value, root) {
+	if (schema === void 0) return value;
+	const ref = schema.$ref;
+	if (typeof ref === "string") {
+		const target = root.$defs?.[ref.replace(/^#\/\$defs\//, "")];
+		return decodeBinary(target, value, root);
+	}
+	const kind = schema["x-gesso-binary"];
+	if (typeof kind === "string") return typeof value === "string" ? bytesOf(value, kind) : value;
+	if (Array.isArray(schema.anyOf)) {
+		const binary = schema.anyOf.find((option) => typeof option["x-gesso-binary"] === "string");
+		return binary !== void 0 && typeof value === "string" ? decodeBinary(binary, value, root) : value;
+	}
+	if (Array.isArray(value)) {
+		const prefix = schema.prefixItems ?? [];
+		const items = schema.items;
+		return value.map((item, index) => decodeBinary(index < prefix.length ? prefix[index] : typeof items === "object" ? items : void 0, item, root));
+	}
+	if (value !== null && typeof value === "object") {
+		const properties = schema.properties ?? {};
+		const out = {};
+		for (const [key, field] of Object.entries(value)) out[key] = decodeBinary(properties[key], field, root);
+		return out;
+	}
+	return value;
+}
+const TYPED = {
+	Int8Array,
+	Uint8Array,
+	Uint8ClampedArray,
+	Int16Array,
+	Uint16Array,
+	Int32Array,
+	Uint32Array,
+	Float32Array,
+	Float64Array,
+	BigInt64Array,
+	BigUint64Array
+};
+function bytesOf(base64, kind) {
+	const text = atob(base64);
+	const bytes = new Uint8Array(text.length);
+	for (let index = 0; index < text.length; index++) bytes[index] = text.charCodeAt(index);
+	if (kind === "ArrayBuffer") return bytes.buffer;
+	const Typed = TYPED[kind];
+	return Typed === void 0 || Typed === Uint8Array ? bytes : new Typed(bytes.buffer);
+}
+//#endregion
+//#region src/agent/validate.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.
+*/
+function validate(schema, value, root = schema, at = "input") {
+	const ref = schema.$ref;
+	if (typeof ref === "string") {
+		const name = ref.replace(/^#\/\$defs\//, "");
+		const target = root.$defs?.[name];
+		return target === void 0 ? null : validate(target, value, root, at);
+	}
+	if (schema.not !== void 0 && validate(schema.not, value, root, at) === null) return `${at} must not be given.`;
+	if ("const" in schema && value !== schema.const) return `${at} must be ${JSON.stringify(schema.const)}.`;
+	if (Array.isArray(schema.enum) && !schema.enum.includes(value)) return `${at} must be one of ${schema.enum.map((option) => JSON.stringify(option)).join(", ")}.`;
+	if (Array.isArray(schema.anyOf)) {
+		const options = schema.anyOf;
+		if (options.every((option) => validate(option, value, root, at) !== null)) return `${at} does not match any of the ${options.length} shapes it may take.`;
+		return null;
+	}
+	const type = schema.type;
+	if (typeof type === "string" && !hasType(value, type)) return `${at} must be ${article(type)}, not ${describe(value)}.`;
+	if (Array.isArray(value)) return validateArray(schema, value, root, at);
+	if (type === "object" && value !== null && typeof value === "object") return validateObject(schema, value, root, at);
+	return null;
+}
+function validateArray(schema, value, root, at) {
+	const prefix = schema.prefixItems ?? [];
+	if (typeof schema.minItems === "number" && value.length < schema.minItems) return `${at} must have at least ${schema.minItems} items.`;
+	for (let index = 0; index < value.length; index++) {
+		const item = index < prefix.length ? prefix[index] : schema.items;
+		if (item === false) return `${at} must have at most ${prefix.length} items.`;
+		if (item !== void 0 && item !== true) {
+			const problem = validate(item, value[index], root, `${at}[${index}]`);
+			if (problem !== null) return problem;
+		}
+	}
+	return null;
+}
+function validateObject(schema, value, root, at) {
+	const properties = schema.properties ?? {};
+	for (const key of schema.required ?? []) if (value[key] === void 0) return `${at}.${key} is required.`;
+	for (const [key, property] of Object.entries(value)) {
+		const declared = properties[key];
+		if (declared !== void 0) {
+			const problem = property === void 0 ? null : validate(declared, property, root, `${at}.${key}`);
+			if (problem !== null) return problem;
+			continue;
+		}
+		const extra = schema.additionalProperties;
+		if (extra === false) {
+			const known = Object.keys(properties);
+			return `${at}.${key} is not expected${known.length > 0 ? `; the fields are ${known.join(", ")}` : ""}.`;
+		}
+		if (extra !== void 0 && extra !== true) {
+			const problem = validate(extra, property, root, `${at}.${key}`);
+			if (problem !== null) return problem;
+		}
+	}
+	return null;
+}
+function hasType(value, type) {
+	switch (type) {
+		case "string": return typeof value === "string";
+		case "number": return typeof value === "number" && Number.isFinite(value);
+		case "integer": return Number.isInteger(value);
+		case "boolean": return typeof value === "boolean";
+		case "null": return value === null;
+		case "array": return Array.isArray(value);
+		case "object": return value !== null && typeof value === "object" && !Array.isArray(value);
+		default: return true;
+	}
+}
+function article(type) {
+	return /^[aeiou]/.test(type) ? `an ${type}` : `a ${type}`;
+}
+function describe(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "an array";
+	return typeof value === "object" ? "an object" : `${typeof value} ${JSON.stringify(value)}`;
+}
+//#endregion
+//#region src/agent/AgentSurface.ts
+/** The longest tool name MCP clients accept. */
+const MAX_NAME = 64;
+function agentSurface(channels, options = {}) {
+	const quietMs = options.quietMs ?? 50;
+	const settleMs = options.settleMs ?? 1e3;
+	const subscriptions = [];
+	const entries = [];
+	const tools = [];
+	const handlers = /* @__PURE__ */ new Map();
+	let lastChange = 0;
+	let following = false;
+	/**
+	* Subscribed on first use rather than at construction, so a surface
+	* built at startup and never called costs the application nothing:
+	* a view key may be a cold observable doing real work per subscriber.
+	*/
+	const follow = () => {
+		if (following) return;
+		following = true;
+		for (const entry of entries) for (const [key, observable] of Object.entries(entry.served.source.view)) subscriptions.push(observable.subscribe((value) => {
+			entry.view[key] = value;
+			lastChange = Date.now();
+		}));
+	};
+	const settle = async () => {
+		const start = Date.now();
+		for (;;) {
+			await new Promise((resolve) => setTimeout(resolve, quietMs));
+			const now = Date.now();
+			if (now - lastChange >= quietMs || now - start >= settleMs) return;
+		}
+	};
+	const add = (tool, handler) => {
+		if (handlers.has(tool.name)) throw new Error(`Two tools would be called '${tool.name}'. A channel and command name pair has to be unique once joined with an underscore, and a command cannot be called \`view\`.`);
+		tools.push(tool);
+		handlers.set(tool.name, handler);
+	};
+	for (const served of channels) {
+		const schema = channelSchema(served.token);
+		const name = toolName(served.token.name);
+		const commands = /* @__PURE__ */ new Map();
+		for (const command of Object.keys(served.source.commands ?? {})) {
+			const described = schema?.commands[command];
+			if (described?.hidden !== true) commands.set(command, described ?? null);
+		}
+		const entry = {
+			served,
+			name,
+			description: schema?.description,
+			viewSchema: schema?.view,
+			view: { ...served.token.initial },
+			commands
+		};
+		entries.push(entry);
+		const about = entry.description === void 0 ? "" : `\n\n${entry.description}`;
+		add({
+			name: toolName(`${served.token.name}_view`),
+			title: `Read ${served.token.name}`,
+			description: `What the ${served.token.name} channel currently holds.${about}`,
+			inputSchema: {
+				type: "object",
+				properties: {},
+				additionalProperties: false
+			},
+			...entry.viewSchema === void 0 ? {} : { outputSchema: entry.viewSchema },
+			annotations: {
+				readOnlyHint: true,
+				openWorldHint: false
+			}
+		}, async () => {
+			follow();
+			return viewResult(entry, `The ${served.token.name} view.`);
+		});
+		for (const [command, described] of commands) add(commandTool(entry, command, described), (args) => send(entry, command, described, args));
+	}
+	const send = async (entry, command, described, args) => {
+		follow();
+		const channel = entry.served.token.name;
+		const input = args ?? {};
+		let positional;
+		if (described === null) {
+			const list = input.arguments ?? [];
+			if (!Array.isArray(list)) return failure("arguments must be an array of the values the command takes, in order.");
+			positional = list;
+		} else {
+			const problem = validate(described.input, input);
+			if (problem !== null) return failure(problem);
+			const properties = described.input.properties ?? {};
+			positional = described.parameters.map((parameter) => decodeBinary(properties[parameter], input[parameter], described.input));
+			if (described.rest === true) {
+				const spread = positional.pop();
+				positional.push(...Array.isArray(spread) ? spread : []);
+			}
+			while (positional.length > 0 && positional[positional.length - 1] === void 0) positional.pop();
+			if (described.confirm === true) {
+				if (options.confirm === void 0) return failure(`${channel}.${command} asks for a person to approve it, and this application has given agents no way to ask. Ask the person to do it themselves.`);
+				if (!await options.confirm({
+					channel,
+					command,
+					description: described.description,
+					arguments: input,
+					destructive: described.destructive === true
+				})) return failure(`The person declined ${channel}.${command}. Do not send it again unless they ask.`);
+			}
+		}
+		const handler = entry.served.source.commands?.[command];
+		if (handler === void 0) return failure(`${channel} has no command ${command}.`);
+		try {
+			handler(...positional);
+		} catch (error) {
+			return failure(`${channel}.${command} failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		await settle();
+		return viewResult(entry, `Sent ${command} to ${channel}. The view afterwards:`);
+	};
+	return {
+		tools: () => tools,
+		call: async (name, args) => {
+			const handler = handlers.get(name);
+			if (handler === void 0) return failure(`There is no tool called ${name}. The tools are ${[...handlers.keys()].join(", ")}.`);
+			return handler(args);
+		},
+		resources: () => entries.map((entry) => ({
+			uri: resourceUri(entry.served.token.name),
+			name: entry.served.token.name,
+			...entry.description === void 0 ? {} : { description: entry.description },
+			mimeType: "application/json"
+		})),
+		read: (uri) => {
+			const entry = entries.find((candidate) => resourceUri(candidate.served.token.name) === uri);
+			if (entry === void 0) return;
+			follow();
+			return { ...entry.view };
+		},
+		dispose: () => {
+			for (const subscription of subscriptions) subscription.unsubscribe();
+			subscriptions.length = 0;
+			following = false;
+		}
+	};
+}
+/** The URI of a channel's view. */
+function resourceUri(channel) {
+	return `gesso://${encodeURIComponent(channel)}/view`;
+}
+function commandTool(entry, command, described) {
+	const channel = entry.served.token.name;
+	const destructive = described?.destructive === true;
+	const lines = [described?.description ?? `Sends ${command} to the ${channel} channel.`];
+	if (described === null) lines.push(`This command was not described, so its arguments are a positional list. Read ${toolName(`${channel}_view`)} first to see what the channel holds.`);
+	if (described?.confirm === true) lines.push("The person is asked to approve this before it is sent.");
+	lines.push("Returns the view after the command has taken effect.");
+	return {
+		name: toolName(`${channel}_${command}`),
+		title: `${channel}: ${command}`,
+		description: lines.join("\n\n"),
+		inputSchema: described?.input ?? {
+			type: "object",
+			properties: { arguments: {
+				type: "array",
+				description: "The arguments, in order."
+			} },
+			additionalProperties: false
+		},
+		...entry.viewSchema === void 0 ? {} : { outputSchema: entry.viewSchema },
+		annotations: {
+			readOnlyHint: false,
+			...destructive ? { destructiveHint: true } : { destructiveHint: false },
+			...described?.idempotent === true ? { idempotentHint: true } : {},
+			openWorldHint: false
+		}
+	};
+}
+/**
+* A tool name MCP clients accept: letters, digits, underscores and
+* dashes, at most 64 characters. A channel name is the application's
+* own string, so anything else in it becomes an underscore, and one
+* too long is an error at startup rather than a tool a client drops.
+*/
+function toolName(raw) {
+	const name = raw.replace(/[^A-Za-z0-9_-]/g, "_");
+	if (name.length > MAX_NAME) throw new Error(`The tool name '${name}' is longer than ${MAX_NAME} characters. Shorten the channel's name.`);
+	return name;
+}
+function viewResult(entry, lead) {
+	const view = { ...entry.view };
+	return {
+		content: [{
+			type: "text",
+			text: `${lead}\n${JSON.stringify(view, null, 2)}`
+		}],
+		structuredContent: view,
+		isError: false
+	};
+}
+function failure(text) {
+	return {
+		content: [{
+			type: "text",
+			text
+		}],
+		isError: true
+	};
+}
+//#endregion
+//#region src/agent/remote.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. */
+const AGENT_PORT = "gesso:agent";
+/**
+* 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.
+*/
+function serveAgentPort(port, makeSurface) {
+	let surface;
+	let nextConfirm = 1;
+	const asking = /* @__PURE__ */ new Map();
+	const confirm = (request) => new Promise((resolve) => {
+		const id = nextConfirm++;
+		asking.set(id, resolve);
+		port.postMessage({
+			confirm: id,
+			request
+		});
+	});
+	port.onmessage = async (event) => {
+		const data = event.data;
+		if ("confirm" in data && "approved" in data) {
+			asking.get(data.confirm)?.(data.approved);
+			asking.delete(data.confirm);
+			return;
+		}
+		const request = data;
+		if (typeof request?.id !== "number") return;
+		surface ??= makeSurface(confirm);
+		try {
+			port.postMessage({
+				id: request.id,
+				result: await answer(surface, request)
+			});
+		} catch (error) {
+			port.postMessage({
+				id: request.id,
+				error: error instanceof Error ? error.message : String(error)
+			});
+		}
+	};
+	return () => {
+		port.onmessage = null;
+		surface?.dispose?.();
+		for (const resolve of asking.values()) resolve(false);
+		asking.clear();
+	};
+}
+function answer(surface, request) {
+	switch (request.op) {
+		case "tools": return surface.tools();
+		case "resources": return surface.resources();
+		case "call": return surface.call(request.name, request.args);
+		case "read": return surface.read(request.uri) ?? null;
+	}
+}
+/**
+* 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.
+*/
+function remoteSurface(port, options = {}) {
+	const timeoutMs = options.timeoutMs ?? 2e3;
+	let next = 1;
+	const pending = /* @__PURE__ */ new Map();
+	port.onmessage = (event) => {
+		const question = event.data;
+		if (question !== null && typeof question === "object" && "request" in question) {
+			Promise.resolve(options.confirm?.(question.request) ?? false).then((approved) => port.postMessage({
+				confirm: question.confirm,
+				approved
+			}), () => port.postMessage({
+				confirm: question.confirm,
+				approved: false
+			}));
+			return;
+		}
+		const response = event.data;
+		const waiting = pending.get(response?.id);
+		if (waiting === void 0) return;
+		pending.delete(response.id);
+		if ("error" in response) waiting.reject(new Error(response.error));
+		else waiting.resolve(response.result);
+	};
+	const ask = (request, fallback, timeout = timeoutMs) => new Promise((resolve, reject) => {
+		const id = next++;
+		const timer = setTimeout(() => {
+			pending.delete(id);
+			resolve(fallback);
+		}, timeout);
+		pending.set(id, {
+			resolve: (value) => {
+				clearTimeout(timer);
+				resolve(value);
+			},
+			reject: (error) => {
+				clearTimeout(timer);
+				reject(error);
+			}
+		});
+		port.postMessage({
+			...request,
+			id
+		});
+	});
+	return {
+		tools: () => ask({ op: "tools" }, []),
+		resources: () => ask({ op: "resources" }, []),
+		call: (name, args) => ask({
+			op: "call",
+			name,
+			args
+		}, {
+			content: [{
+				type: "text",
+				text: `${name} did not answer in time.`
+			}],
+			isError: true
+		}, Math.max(timeoutMs, 12e4)),
+		read: async (uri) => await ask({
+			op: "read",
+			uri
+		}, null) ?? void 0
+	};
+}
+/**
+* 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.
+*/
+function combineSurfaces(surfaces) {
+	const toolOwners = /* @__PURE__ */ new Map();
+	const resourceOwners = /* @__PURE__ */ new Map();
+	const tools = async () => {
+		const lists = await Promise.all(surfaces.map((surface) => surface.tools()));
+		toolOwners.clear();
+		const out = [];
+		lists.forEach((list, index) => {
+			for (const tool of list) if (!toolOwners.has(tool.name)) {
+				toolOwners.set(tool.name, surfaces[index]);
+				out.push(tool);
+			}
+		});
+		return out;
+	};
+	const resources = async () => {
+		const lists = await Promise.all(surfaces.map((surface) => surface.resources()));
+		resourceOwners.clear();
+		const out = [];
+		lists.forEach((list, index) => {
+			for (const resource of list) if (!resourceOwners.has(resource.uri)) {
+				resourceOwners.set(resource.uri, surfaces[index]);
+				out.push(resource);
+			}
+		});
+		return out;
+	};
+	return {
+		tools,
+		resources,
+		call: async (name, args) => {
+			if (!toolOwners.has(name)) await tools();
+			const owner = toolOwners.get(name);
+			if (owner === void 0) return {
+				content: [{
+					type: "text",
+					text: `There is no tool called ${name}. The tools are ${[...toolOwners.keys()].join(", ")}.`
+				}],
+				isError: true
+			};
+			return owner.call(name, args);
+		},
+		read: async (uri) => {
+			if (!resourceOwners.has(uri)) await resources();
+			return resourceOwners.get(uri)?.read(uri);
+		},
+		dispose: () => {
+			for (const surface of surfaces) surface.dispose?.();
+		}
+	};
+}
+//#endregion
+export { agentSurface as a, channelSchema as c, serveAgentPort as i, describeChannel as l, combineSurfaces as n, resourceUri as o, remoteSurface as r, validate as s, AGENT_PORT as t };
+
+//# sourceMappingURL=remote-xxij8zXe.js.map