@hediet/linkrpc-mcp 0.0.1

package/dist/chunks/server-C4ZM6bfK.js

@@ -0,0 +1,2530 @@
+import { createRequire } from "node:module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ErrorCode, InMemoryManagedIdentity, JsonRpcChannel, RpcError, SigningSender, capabilityFreshAt, generateTsInterface, permissionMatchesTarget, traceMessageTransport } from "@hediet/linkrpc";
+import { z } from "zod";
+import { LINKRPC_ENDPOINT_VAR, LINKRPC_TOKEN_VAR, WebSocketTransport, connectNdjson, createManagedPrincipal, createSelfManagedPrincipal, createSelfManagedPrincipalFromFile, formatEndpointUri, loadOrCreateIdentity, openWebSocket, parseEndpointUri, runInitializeHandshake } from "@hediet/linkrpc/node";
+import { Hub, HubConnectionAcceptor, anonymousHandler, createHubServiceInterfaces } from "@hediet/linkrpc-hub/hub/server/client";
+import { SocketServer } from "@hediet/linkrpc-hub/hub/server/node";
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import { readFileSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { spawnCommand, spawnCommand as spawnCommand$1 } from "@hediet/linkrpc-hub/spawn";
+import { tapTransport } from "@hediet/linkrpc-hub/hub/server/transit";
+import * as net from "node:net";
+import "@hediet/linkrpc-hub/config";
+import { fetchSchema, hubAccessInterface, walkHubDetailed } from "@hediet/linkrpc/hub/common";
+import { Scope, getQuickJS } from "quickjs-emscripten";
+import { fileURLToPath } from "node:url";
+import { createHash } from "crypto";
+import { ContentBlockSchema } from "@modelcontextprotocol/sdk/types.js";
+//#region ../../packages-private/linkrpc-client/src/localHub.ts
+/** Default serviceId namespace the local-hub child may claim (and sees via `hubGrantedServiceId::get`). */
+const DEFAULT_LOCAL_NAMESPACE = "local";
+/** Subfolder (under the linkrpc data dir) holding provisioned identity slots. */
+const PROVISION_SUBDIR = "provisioned-identities";
+/** Provisioned slots untouched for longer than this are swept on next run. */
+const PROVISION_MAX_AGE_MS = 2592e6;
+/**
+* Start an in-process hub on a private socket, spawn `command` as a participant
+* (handing it the socket + token via `LINKRPC_ENDPOINT` / `LINKRPC_TOKEN`), and
+* resolve once the child has registered a service under {@link LOCAL_NAMESPACE}.
+*
+* The hub is single-tenant and local: no claim policy (every well-formed claim
+* is allowed) and no provenance. Identity is either ephemeral (fresh per run)
+* or, when `provisionSlot` is set, a persisted managed identity so the child's
+* HPKE wrap/unwrap keys survive across runs.
+*/
+async function startLocalHub(opts) {
+	const resolveIdentity = _makeIdentityResolver(opts.provisionSlot);
+	const grantedNs = DEFAULT_LOCAL_NAMESPACE;
+	const hub = new Hub();
+	createHubServiceInterfaces(hub);
+	const socketPath = SocketServer.allocSocketPath();
+	const token = randomBytes(16).toString("hex");
+	const socketServer = await SocketServer.start({ endpoint: socketPath });
+	const acceptor = new HubConnectionAcceptor({
+		server: socketServer,
+		hub,
+		handlers: [anonymousHandler({
+			grantedServiceIdNamespace: grantedNs,
+			...resolveIdentity ? { resolveIdentity } : {}
+		})]
+	});
+	const child = spawnCommand(opts.command, {
+		stdio: [
+			"inherit",
+			"inherit",
+			"inherit"
+		],
+		env: {
+			...process.env,
+			...opts.env,
+			LINKRPC_ENDPOINT: socketPath,
+			LINKRPC_TOKEN: token
+		},
+		...opts.cwd !== void 0 ? { cwd: opts.cwd } : {}
+	});
+	let childExited = false;
+	child.once("exit", () => {
+		childExited = true;
+	});
+	const dispose = () => {
+		if (!child.killed) child.kill();
+		acceptor.dispose();
+		socketServer.dispose();
+		if (process.platform !== "win32") try {
+			fs.unlinkSync(socketPath);
+		} catch {}
+	};
+	try {
+		await _waitForClaim(hub, grantedNs, () => childExited, opts.readyTimeoutMs ?? 3e4);
+	} catch (e) {
+		dispose();
+		throw e;
+	}
+	return {
+		socketPath,
+		token,
+		dispose
+	};
+}
+/**
+* Build the hub's `resolveIdentity`, or `undefined` when no identity should be
+* provided. Without `provisionSlot` the hub serves no identity at all — a child
+* that needs `identity::*` will fail. With it, a single persisted managed
+* identity is shared by all connections (stale slots swept first), so the
+* child's HPKE wrap/unwrap keys survive across runs.
+*/
+function _makeIdentityResolver(provisionSlot) {
+	if (provisionSlot === void 0) return;
+	const dir = _provisionDir();
+	_sweepProvisionedIdentities(dir);
+	let shared;
+	return () => {
+		if (!shared) shared = (async () => {
+			const persisted = await loadOrCreateIdentity({
+				id: provisionSlot,
+				storeDir: dir
+			});
+			return new InMemoryManagedIdentity(persisted.keypair, persisted.wrapKeypair);
+		})();
+		return shared;
+	};
+}
+/** Dedicated provisioned-identity folder (sibling of linkrpc's user identities). */
+function _provisionDir() {
+	const home = os.homedir();
+	let base;
+	if (process.platform === "win32") base = process.env.APPDATA ?? path.join(home, "AppData", "Roaming");
+	else if (process.platform === "darwin") base = path.join(home, "Library", "Application Support");
+	else base = process.env.XDG_CONFIG_HOME ?? path.join(home, ".config");
+	return path.join(base, "linkrpc", PROVISION_SUBDIR);
+}
+/** Delete provisioned identity files whose mtime is older than the max age. */
+function _sweepProvisionedIdentities(dir) {
+	let entries;
+	try {
+		entries = fs.readdirSync(dir);
+	} catch {
+		return;
+	}
+	const cutoff = Date.now() - PROVISION_MAX_AGE_MS;
+	for (const name of entries) {
+		if (!name.endsWith(".json")) continue;
+		const file = path.join(dir, name);
+		try {
+			if (fs.statSync(file).mtimeMs < cutoff) fs.unlinkSync(file);
+		} catch {}
+	}
+}
+/** Resolve once the child claims `prefix` (or a sub-prefix), else reject. */
+function _waitForClaim(hub, prefix, childExited, timeoutMs) {
+	const deadline = Date.now() + timeoutMs;
+	return new Promise((resolve, reject) => {
+		const check = () => {
+			if (hub.claimedPrefixes().some((p) => p === prefix || p.startsWith(`${prefix}/`))) {
+				resolve();
+				return;
+			}
+			if (childExited()) {
+				reject(/* @__PURE__ */ new Error("connect: command exited before registering a service"));
+				return;
+			}
+			if (Date.now() >= deadline) {
+				reject(/* @__PURE__ */ new Error(`connect: timed out waiting for command to register a service under '${prefix}'`));
+				return;
+			}
+			setTimeout(check, 50);
+		};
+		check();
+	});
+}
+//#endregion
+//#region ../../packages-private/linkrpc-client/src/connect.ts
+async function connect(endpoint, log) {
+	switch (endpoint.kind) {
+		case "cmd-stdio": return _connectCmdStdio(endpoint.command, endpoint.env, endpoint.cwd, log);
+		case "cmd-env": return _connectCmdEnv(endpoint.command, endpoint.provisionSlot, endpoint.env, endpoint.cwd, log);
+		case "ws": return _connectWs(endpoint, log);
+		case "ws-no-init": return _connectWs(endpoint, log);
+		case "socket": return _connectSocket(endpoint.path, endpoint.token, log);
+	}
+}
+/**
+* Spawn a child from a command spec. `{ command }` is run through the OS shell
+* (so quoting / splitting follows the shell's rules); `{ argv }` is run
+* directly (no shell), except on Windows where `.cmd` shims need one.
+*/
+async function _connectCmdStdio(command, env, cwd, log) {
+	const child = spawnCommand$1(command, {
+		stdio: [
+			"pipe",
+			"pipe",
+			"inherit"
+		],
+		...env !== void 0 ? { env: {
+			...process.env,
+			...env
+		} } : {},
+		...cwd !== void 0 ? { cwd } : {}
+	});
+	if (!child.stdin || !child.stdout) throw new Error("connect: child process exposes no stdio");
+	const { transport } = await connectNdjson({
+		input: child.stdout,
+		output: child.stdin,
+		onClose: () => {
+			if (!child.killed) child.kill();
+		},
+		trace: log?.trace
+	});
+	return _makeCliConnection(transport, () => {
+		if (!child.killed) child.kill();
+	}, log);
+}
+/**
+* Start a private in-process hub, spawn the child as a participant, then
+* connect to the hub's socket. The child registers its services against the
+* hub exactly as it would against a remote one; we tear the hub + child down
+* when the connection closes.
+*/
+async function _connectCmdEnv(command, provisionSlot, env, cwd, log) {
+	return connectViaLocalHub({
+		command,
+		provisionSlot,
+		env,
+		cwd,
+		log
+	});
+}
+/**
+* Spawn a child under an in-process local hub (`startLocalHub`) and connect
+* to that hub over a socket. Backs the standard `cmd-env` endpoint path; the
+* hub + child are torn down when the connection closes.
+*/
+async function connectViaLocalHub(opts) {
+	const hub = await startLocalHub({
+		command: opts.command,
+		provisionSlot: opts.provisionSlot,
+		env: opts.env,
+		...opts.cwd !== void 0 ? { cwd: opts.cwd } : {}
+	});
+	try {
+		const conn = await _connectSocket(hub.socketPath, hub.token, opts.log);
+		return {
+			...conn,
+			close: () => {
+				conn.close();
+				hub.dispose();
+			}
+		};
+	} catch (e) {
+		hub.dispose();
+		throw e;
+	}
+}
+function _connectWs(endpoint, log) {
+	return openWebSocket(endpoint.url).then(async (ws) => {
+		const closeWs = () => {
+			try {
+				ws.close();
+			} catch {}
+		};
+		const baseTransport = new WebSocketTransport(ws, closeWs);
+		const transport = log?.trace === void 0 ? baseTransport : traceMessageTransport(baseTransport, log.trace);
+		if (endpoint.kind === "ws") try {
+			await runInitializeHandshake(transport, {
+				kind: "client",
+				token: endpoint.token ?? ""
+			});
+		} catch (err) {
+			transport.dispose();
+			closeWs();
+			throw err;
+		}
+		return _makeCliConnection(transport, closeWs, log);
+	});
+}
+async function _connectSocket(socketPath, token, log) {
+	const socket = net.createConnection(socketPath);
+	await new Promise((resolve, reject) => {
+		const onConnect = () => {
+			socket.removeListener("error", onError);
+			resolve();
+		};
+		const onError = (error) => {
+			socket.removeListener("connect", onConnect);
+			socket.destroy();
+			reject(error);
+		};
+		socket.once("connect", onConnect);
+		socket.once("error", onError);
+	});
+	socket.on("error", () => socket.destroy());
+	const { transport } = await connectNdjson({
+		input: socket,
+		output: socket,
+		onClose: () => socket.destroy(),
+		initialize: {
+			kind: "client",
+			token: token ?? ""
+		},
+		trace: log?.trace
+	});
+	return _makeCliConnection(transport, () => socket.destroy(), log);
+}
+/**
+* In-memory connection — for tests. The caller hands us a transport already
+* wired to a server-side channel (typically via `TransportPair`).
+*/
+function connectViaTransport(transport) {
+	return _makeCliConnection(transport, () => {});
+}
+function _makeCliConnection(transport, onClose, log) {
+	const tapped = log?.log === void 0 ? transport : tapTransport(transport, {
+		log: log.log,
+		localLabel: "cli",
+		remoteLabel: log.remoteLabel ?? "peer",
+		...log.maxPayload !== void 0 ? { maxPayload: log.maxPayload } : {}
+	});
+	const signing = {};
+	const wrapped = SigningSender.wrapChannel(JsonRpcChannel.create(tapped), signing);
+	const channel = wrapped.sender;
+	return {
+		channel,
+		rpcChannel: wrapped,
+		signing,
+		setRequestHandler: (handler) => wrapped.setRequestHandler(handler),
+		close: () => {
+			channel.close();
+			onClose();
+		}
+	};
+}
+//#endregion
+//#region ../../packages-private/linkrpc-client/src/principal.ts
+/**
+* Identity slot the managed-with-fallback default falls back to when the peer
+* does not offer a managed identity overlay (e.g. a plain stdio server). Maps
+* to the same on-disk slot `logout` clears.
+*/
+const MANAGED_FALLBACK_USER_ID = "hubrpc-cli";
+/**
+* Resolve a {@link PrincipalSpec} into a concrete {@link Principal}, given the
+* (signed) sender used to bootstrap a managed identity. Cheap/idempotent, so
+* it can be re-derived on each reconnect. Also reports the {@link PrincipalSource}
+* that was actually used, including whether `managed` fell back to a local key.
+*/
+async function resolvePrincipal(spec, sender) {
+	switch (spec.kind) {
+		case "managed": try {
+			return {
+				principal: await createManagedPrincipal(sender),
+				source: { kind: "managed" }
+			};
+		} catch {
+			return {
+				principal: await createSelfManagedPrincipal(MANAGED_FALLBACK_USER_ID),
+				source: {
+					kind: "managed-fallback",
+					userId: MANAGED_FALLBACK_USER_ID
+				}
+			};
+		}
+		case "user": return {
+			principal: await createSelfManagedPrincipal(spec.id),
+			source: {
+				kind: "user",
+				id: spec.id
+			}
+		};
+		case "file": return {
+			principal: await createSelfManagedPrincipalFromFile(spec.path),
+			source: {
+				kind: "file",
+				path: spec.path
+			}
+		};
+	}
+}
+//#endregion
+//#region ../../packages-private/linkrpc-client/src/hubSigning.ts
+/** How long before expiry to refresh a capability (2 seconds = transit + skew). */
+const CAP_FRESHNESS_MARGIN_MS = 2e3;
+/**
+* Install signing on `signing` for any endpoint. Resolves the
+* {@link PrincipalSpec} into a concrete {@link Principal} (managed-with-
+* fallback, a user slot, or a file-backed keypair) and points the channel's
+* `SigningSender` at it so every outbound call is signed.
+*
+* When `negotiateHubCaps` is set (hub endpoints), it also ensures a persistent
+* `hubAccess` capability is cached on the principal's {@link CapBag} — requesting
+* one with a single signed round-trip on first run / cache miss. For hub
+* endpoints, it also installs a sign-time capability provider.
+*
+* By default (`autoNegotiatePerCall !== false`) that provider negotiates
+* per-call authority lazily using `callIntent` (method + params + nonce +
+* signedAtMs + optional interfaceHash), so one-shot grants can be pinned to the
+* exact call bytes being signed. Set `autoNegotiatePerCall: false` to disable
+* that: the provider then only presents caps already in the bag, and the caller
+* is expected to request access explicitly via
+* {@link SigningSession.requestAccess}.
+*/
+async function setupSigning(channel, signing, principalSpec, opts) {
+	const { principal, source: principalSource } = await resolvePrincipal(principalSpec, channel);
+	signing.principal = principal;
+	signing.oneShotCaps = void 0;
+	signing.capProvider = void 0;
+	const hubAccessMethod = `${hubAccessInterface.info.id}::requestAccess`;
+	const consumerPrincipalId = principal.id;
+	if (opts.negotiateHubCaps) {
+		let inAccessNegotiation = false;
+		const provider = async ({ method, params, nonce, signedAtMs, interfaceHash }) => {
+			let presentCaps = principal.capBag.capabilities;
+			presentCaps = presentCaps.filter((c) => capabilityFreshAt(c, signedAtMs, CAP_FRESHNESS_MARGIN_MS));
+			const present = presentCaps.length > 0 ? { capabilities: presentCaps } : {};
+			if (inAccessNegotiation) return {};
+			const call = _wireMethodToCall(method);
+			if (!call) return present;
+			if (call.serviceId === "" || call.interfaceId === hubAccessInterface.info.id) return present;
+			if (_capBagCovers(presentCaps, call)) return present;
+			if (opts.autoNegotiatePerCall === false) return present;
+			inAccessNegotiation = true;
+			try {
+				const granted = await _requestAccessForCall(channel, hubAccessMethod, consumerPrincipalId, {
+					call,
+					method,
+					params,
+					nonce,
+					signedAtMs,
+					interfaceHash
+				});
+				if (granted.length === 0) return present;
+				const oneShot = granted.filter(_isOneShotCap);
+				const persistent = granted.filter((c) => !_isOneShotCap(c));
+				if (persistent.length > 0) await principal.capBag.add(...persistent);
+				const durable = principal.capBag.capabilities.filter((c) => capabilityFreshAt(c, signedAtMs, CAP_FRESHNESS_MARGIN_MS));
+				if (oneShot.length > 0) return { capabilities: [...durable, ...oneShot] };
+				return durable.length > 0 ? { capabilities: durable } : {};
+			} catch (err) {
+				process.stderr.write(`linkrpc: capability negotiation skipped (${err.message})\n`);
+				return present;
+			} finally {
+				inAccessNegotiation = false;
+			}
+		};
+		signing.capProvider = provider;
+	}
+	return {
+		principal,
+		principalSource,
+		hubAccessMethod,
+		listGrants: () => principal.capBag.capabilities,
+		requestAccess: (req) => _sessionRequestAccess(channel, hubAccessMethod, principal, req)
+	};
+}
+/** Parse a wire method into a {@link CallTarget}, or `undefined` for form-1/2. */
+function _wireMethodToCall(wireMethod) {
+	const parts = wireMethod.split("::");
+	if (parts.length !== 3) return void 0;
+	const [serviceId, interfaceId, member] = parts;
+	return {
+		serviceId,
+		interfaceId,
+		member
+	};
+}
+/** A cap is one-shot when any permission is pinned to a single call via `callBind`. */
+function _isOneShotCap(sc) {
+	return sc.permissions.some((p) => p.callBind !== void 0);
+}
+/** True when a durable (non-one-shot) cap in the bag authorises `target`. */
+function _capBagCovers(caps, target) {
+	return caps.some((sc) => !_isOneShotCap(sc) && sc.permissions.some((p) => permissionMatchesTarget(target, p)));
+}
+async function _requestAccessForCall(channel, hubAccessMethod, consumerPrincipalId, req) {
+	const result = await _sendRequestAccess(channel, hubAccessMethod, {
+		consumer: {
+			name: "linkrpc-cli",
+			principal: consumerPrincipalId,
+			purpose: `Invoke ${req.method}.`
+		},
+		permissions: [{
+			target: {
+				serviceId: { exact: req.call.serviceId },
+				interfaceId: { exact: req.call.interfaceId },
+				members: [{ exact: req.call.member }]
+			},
+			canInvoke: true,
+			callIntent: {
+				method: req.method,
+				params: req.params,
+				nonce: req.nonce,
+				signedAtMs: req.signedAtMs,
+				...req.interfaceHash !== void 0 ? { interfaceHash: req.interfaceHash } : {},
+				suggestion: "once"
+			}
+		}],
+		duration: "once"
+	});
+	if (result.status !== "granted") return [];
+	return result.capabilities ?? [];
+}
+async function _sendRequestAccess(channel, hubAccessMethod, params) {
+	return await _awaitWithApprovalNotice(channel.sendRequest(hubAccessMethod, params));
+}
+/** Delay before we tell the user an access request is parked awaiting approval. */
+const APPROVAL_NOTICE_DELAY_MS = 750;
+/**
+* Await a `hubAccess::requestAccess` round-trip, printing a one-line hint to
+* stderr if it doesn't resolve quickly. Access requests park at the hub until a
+* human approver (admin) decides them, so without this notice the CLI looks
+* hung — it blocks with no output until approval. Fast requests (auto-approved
+* / open hub) stay silent because the notice only fires after
+* {@link APPROVAL_NOTICE_DELAY_MS}.
+*/
+async function _awaitWithApprovalNotice(pending) {
+	const timer = setTimeout(() => {
+		process.stderr.write("linkrpc: access request sent — waiting for the hub admin to approve it...\n");
+	}, APPROVAL_NOTICE_DELAY_MS);
+	timer.unref?.();
+	try {
+		return await pending;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/**
+* Backs {@link SigningSession.requestAccess}. Sends a batched
+* `hubAccess::requestAccess`, then adds any durable (non-one-shot) caps the hub
+* minted to the principal's cap bag so later calls present them automatically.
+*/
+async function _sessionRequestAccess(channel, hubAccessMethod, principal, req) {
+	const result = await _sendRequestAccess(channel, hubAccessMethod, {
+		consumer: {
+			...req.consumer,
+			principal: principal.id
+		},
+		permissions: req.permissions,
+		...req.duration !== void 0 ? { duration: req.duration } : {}
+	});
+	if (result.status === "granted") {
+		const capabilities = result.capabilities ?? [];
+		const durable = capabilities.filter((c) => !_isOneShotCap(c));
+		if (durable.length > 0) await principal.capBag.add(...durable);
+		return {
+			status: "granted",
+			capabilities,
+			addedDurable: durable.length
+		};
+	}
+	return {
+		status: result.status,
+		reason: result.reason
+	};
+}
+//#endregion
+//#region src/connectionPool.ts
+/**
+* Maintains live hub connections keyed by the canonical endpoint URI (path/url
+* + token). Connections are created lazily on first use and reused for every
+* subsequent call against the same endpoint. Setting up the hub signing session
+* (which may surface a consent modal the first time) happens once per endpoint
+* and the resulting session is cached on the pool entry.
+*/
+var ConnectionPool = class ConnectionPool {
+	_entries = /* @__PURE__ */ new Map();
+	_defaultEndpoint;
+	_defaultTransport;
+	/** Pool key for the in-process default connection (see {@link ConnectionPoolOptions.defaultTransport}). */
+	static _DEFAULT_INPROC_KEY = "<default-inproc>";
+	constructor(options = {}) {
+		this._defaultEndpoint = options.defaultEndpoint;
+		this._defaultTransport = options.defaultTransport;
+	}
+	/**
+	* Resolve a pooled connection for `endpointUri` (a strict endpoint URI such
+	* as `unix:/path?token=…`, `npipe://./pipe/…?token=…`, or
+	* `wss://host?token=…`). When omitted, an in-process default transport (if
+	* configured) is used; otherwise it falls back to the configured default
+	* endpoint, then to the `LINKRPC_ENDPOINT` / `LINKRPC_TOKEN` env vars. A token
+	* absent from the URI is filled in from `LINKRPC_TOKEN` when present.
+	*/
+	async resolve(endpointUri) {
+		if (endpointUri === void 0 && this._defaultTransport) return this._resolveCached(ConnectionPool._DEFAULT_INPROC_KEY, (key) => this._openInProc(this._defaultTransport(), key));
+		const spec = this._resolveSpec(endpointUri);
+		const key = formatEndpointUri(spec, { revealToken: true });
+		return this._resolveCached(key, (k) => this._open(spec, k));
+	}
+	/**
+	* Shared cache-or-open: returns the in-flight/cached entry for `key`, or
+	* starts `open(key)` and caches the promise so concurrent callers share the
+	* same signing setup. On failure the entry is evicted so the next call
+	* retries cleanly.
+	*/
+	_resolveCached(key, open) {
+		const existing = this._entries.get(key);
+		if (existing) return existing;
+		const pending = open(key);
+		this._entries.set(key, pending);
+		pending.catch(() => this._entries.delete(key));
+		return pending;
+	}
+	_resolveSpec(endpointUri) {
+		if (endpointUri !== void 0) return _withEnvToken(parseEndpointUri(endpointUri));
+		return this._defaultEndpoint ?? _resolveFromEnv();
+	}
+	async _open(spec, key) {
+		const display = formatEndpointUri(spec);
+		const cli = await connect(spec);
+		return this._finishOpen(cli, display, key);
+	}
+	async _openInProc(def, key) {
+		const cli = connectViaTransport(def.transport);
+		return this._finishOpen(cli, def.label ?? "inproc", key, def.dispose);
+	}
+	/**
+	* Wrap an already-open {@link CliConnection} in a managed signing session
+	* and build the {@link PooledConnection}. Shared by the dialed-socket and
+	* in-process default paths — both sign as a managed principal and bootstrap
+	* the `hubAccess` cap, the only difference being how the transport was
+	* obtained. `extraDispose` runs on disposal after the connection is closed.
+	*/
+	async _finishOpen(cli, display, key, extraDispose) {
+		const traceListeners = /* @__PURE__ */ new Set();
+		const trace = (line) => {
+			process.stderr.write(`${line}\n`);
+			for (const l of traceListeners) try {
+				l(line);
+			} catch {}
+		};
+		_installTransportTrace(cli.channel, display, trace);
+		try {
+			trace(`linkrpc-mcp[${display}] requesting hub signing session (may prompt for reflection-cap consent on first use)`);
+			const session = await setupSigning(cli.channel, cli.signing, { kind: "managed" }, {
+				negotiateHubCaps: true,
+				autoNegotiatePerCall: false
+			});
+			return {
+				channel: cli.channel,
+				endpoint: display,
+				key,
+				session,
+				lastResultVal: void 0,
+				addTraceListener: (listener) => {
+					traceListeners.add(listener);
+					return () => traceListeners.delete(listener);
+				},
+				trace,
+				dispose: () => {
+					cli.close();
+					extraDispose?.();
+					this._entries.delete(key);
+				}
+			};
+		} catch (e) {
+			cli.close();
+			extraDispose?.();
+			throw e;
+		}
+	}
+	dispose() {
+		for (const pending of this._entries.values()) pending.then((e) => e.dispose(), () => {});
+		this._entries.clear();
+	}
+};
+/**
+* Fill a missing socket/ws token from `LINKRPC_TOKEN` when the URI itself didn't
+* carry one. Command endpoints (`cmd:` / `cmd-stdio:`) carry no token.
+*/
+function _withEnvToken(spec) {
+	if ((spec.kind === "socket" || spec.kind === "ws") && spec.token === void 0) {
+		const token = process.env[LINKRPC_TOKEN_VAR];
+		if (token) return {
+			...spec,
+			token
+		};
+	}
+	return spec;
+}
+function _resolveFromEnv() {
+	const endpoint = process.env[LINKRPC_ENDPOINT_VAR];
+	if (!endpoint) throw new Error(`No connection supplied and ${LINKRPC_ENDPOINT_VAR} is not set. Pass a 'connection' endpoint URI (e.g. unix:/path?token=… or wss://host?token=…) to the tool, or run the MCP server inside a VS Code window with the team-tools hub active.`);
+	return _withEnvToken(parseEndpointUri(endpoint));
+}
+/**
+* Wrap `channel.sendRequest` / `channel.sendNotification` so every
+* outbound JSON-RPC envelope and its outcome is emitted as a trace
+* line. Catches everything the MCP server drives (tool-issued `call` /
+* `notify`, `explore`, and the hub's `hubAccess::requestAccess`
+* permission round-trips).
+*
+* IMPORTANT: the wrappers forward the third `opts` argument verbatim. It
+* carries the per-call {@link SigningCallCtx} (e.g. `signerOverride: null` for
+* the unsigned `identity::*` bootstrap round-trips). Dropping it would make a
+* managed identity's `identity::sign` calls get signed — which recurses
+* (signing a call needs another `identity::sign`), blowing the heap.
+*/
+function _installTransportTrace(channel, endpoint, trace) {
+	const send = channel.sendRequest.bind(channel);
+	const notify = channel.sendNotification.bind(channel);
+	let seq = 0;
+	channel.sendRequest = async (method, params, opts) => {
+		const id = ++seq;
+		trace(`linkrpc-mcp[${endpoint}] → #${id} request ${method} ${_fmt(params)}`);
+		try {
+			const result = await send(method, params, opts);
+			trace(`linkrpc-mcp[${endpoint}] ← #${id} result ${_fmt(result)}`);
+			return result;
+		} catch (e) {
+			trace(`linkrpc-mcp[${endpoint}] ← #${id} error ${e.message}`);
+			throw e;
+		}
+	};
+	channel.sendNotification = async (method, params, opts) => {
+		trace(`linkrpc-mcp[${endpoint}] → #${++seq} notify ${method} ${_fmt(params)}`);
+		await notify(method, params, opts);
+	};
+}
+const _MAX_TRACE_PAYLOAD = 2e3;
+function _fmt(v) {
+	if (v === void 0) return "(no params)";
+	let s;
+	try {
+		s = JSON.stringify(v);
+	} catch {
+		s = String(v);
+	}
+	if (s === void 0) s = "undefined";
+	return s.length > _MAX_TRACE_PAYLOAD ? `${s.slice(0, _MAX_TRACE_PAYLOAD)}…(+${s.length - _MAX_TRACE_PAYLOAD} chars)` : s;
+}
+//#endregion
+//#region src/senderProvider.ts
+/**
+* {@link IConnectionPool} backed by a {@link HubSenderProvider}: caches one
+* {@link HubSigningSender} per distinct `connection` argument and adapts it to
+* the {@link PooledConnection} shape the MCP tools consume. Holds the
+* MCP-layer-only `lastResultVal` and trace fan-out so the sender stays pure.
+*/
+var ProviderPool = class {
+	_provider;
+	_session;
+	_entries = /* @__PURE__ */ new Map();
+	constructor(_provider, _session) {
+		this._provider = _provider;
+		this._session = _session;
+	}
+	resolve(endpointUri) {
+		const key = endpointUri ?? "<default>";
+		const existing = this._entries.get(key);
+		if (existing) return existing;
+		const pending = this._open(endpointUri, key);
+		this._entries.set(key, pending);
+		pending.catch(() => this._entries.delete(key));
+		return pending;
+	}
+	async _open(endpointUri, key) {
+		const sender = await this._provider(this._session, endpointUri);
+		const traceListeners = /* @__PURE__ */ new Set();
+		return {
+			channel: sender,
+			endpoint: sender.identity.principal,
+			key,
+			session: sender,
+			lastResultVal: void 0,
+			addTraceListener: (listener) => {
+				traceListeners.add(listener);
+				return () => traceListeners.delete(listener);
+			},
+			trace: (line) => {
+				for (const l of traceListeners) try {
+					l(line);
+				} catch {}
+			},
+			dispose: () => {
+				sender.close();
+				this._entries.delete(key);
+			}
+		};
+	}
+	dispose() {
+		for (const pending of this._entries.values()) pending.then((e) => e.dispose(), () => {});
+		this._entries.clear();
+	}
+};
+//#endregion
+//#region src/grants.ts
+/** Render a single `serviceId` / `interfaceId` / member matcher as a string. */
+function _fmtPattern(p) {
+	if ("exact" in p) return p.exact;
+	return p.prefix === "" ? "*" : `${p.prefix}*`;
+}
+/**
+* Summarise the durable capabilities a connection currently holds into a
+* compact, JSON-friendly shape the model can read to understand what access it
+* already has (and therefore what it still needs to request).
+*/
+function summarizeGrants(caps) {
+	const grants = caps.map((c) => {
+		const oneShot = c.permissions.some((p) => p.callBind !== void 0);
+		return {
+			issuer: c.issuer,
+			audience: c.audience,
+			...c.expiresAtMs !== void 0 ? { expiresAtMs: c.expiresAtMs } : {},
+			oneShot,
+			permissions: c.permissions.map((p) => ({
+				serviceId: _fmtPattern(p.target.serviceId),
+				interfaceId: _fmtPattern(p.target.interfaceId),
+				members: p.target.members.map(_fmtPattern),
+				canInvoke: p.canInvoke ?? false,
+				canDelegate: p.canDelegate ?? false
+			}))
+		};
+	});
+	return {
+		count: grants.length,
+		grants
+	};
+}
+//#endregion
+//#region src/connectionDts.ts
+/**
+* Documentation that the MCP server exposes as a resource. The text is the
+* single source of truth for what `runLinkRpcScript` sees inside the QuickJS
+* sandbox — it lives as the real declaration file `connection.d.ts` and is
+* embedded here verbatim. Keep `connection.d.ts` in sync with `sandbox.ts`
+* and `explore.ts`.
+*/
+const CONNECTION_DTS = "// ---- runLinkRpcScript sandbox API ----------------------------------------\n//\n// The MCP tool `runLinkRpcScript` takes `code` (a JS function expression) and\n// invokes it inside a QuickJS sandbox with the signature below. Anything the\n// function returns (sync or async) becomes the tool's result, JSON-encoded.\n//\n//     ({ con, lastResultVal, mcp }) => any | Promise<any>\n//\n// Example:\n//\n//     ({ con }) => con.call(\"vscode\", \"vscode.window\",\n//                           \"showInformationMessage\",\n//                           { message: \"hello\" })\n//\n// The sandbox is isolated: no `require`, no `process`, no host globals\n// other than the ones declared here. Memory is capped (~32 MB) and execution\n// is interrupted after ~5 s.\n\ninterface RunSvcContext {\n    /** The live connection wired to the requested hub. */\n    readonly con: SvcConnection;\n    /**\n     * The value returned by the previous `runLinkRpcScript` call on the same hub\n     * connection. JSON round-tripped — non-serialisable members are dropped.\n     * `undefined` on the first call.\n     */\n    readonly lastResultVal: unknown;\n    /**\n     * Optional presentation helpers. Ordinary return values are automatically\n     * converted to native MCP image/audio/resource blocks when possible.\n     */\n    readonly mcp: McpPresentation;\n}\n\ninterface McpAnnotations {\n    readonly audience?: ReadonlyArray<\"user\" | \"assistant\">;\n    readonly priority?: number;\n    readonly lastModified?: string;\n}\n\ntype McpMeta = Record<string, unknown>;\n\ntype McpContentBlock =\n    | {\n        readonly type: \"text\";\n        readonly text: string;\n        readonly annotations?: McpAnnotations;\n        readonly _meta?: McpMeta;\n    }\n    | {\n        readonly type: \"image\";\n        readonly data: string;\n        readonly mimeType: string;\n        readonly annotations?: McpAnnotations;\n        readonly _meta?: McpMeta;\n    }\n    | {\n        readonly type: \"audio\";\n        readonly data: string;\n        readonly mimeType: string;\n        readonly annotations?: McpAnnotations;\n        readonly _meta?: McpMeta;\n    }\n    | {\n        readonly type: \"resource\";\n        readonly resource:\n            | { readonly uri: string; readonly mimeType?: string; readonly text: string; readonly _meta?: McpMeta }\n            | { readonly uri: string; readonly mimeType?: string; readonly blob: string; readonly _meta?: McpMeta };\n        readonly annotations?: McpAnnotations;\n        readonly _meta?: McpMeta;\n    }\n    | {\n        readonly type: \"resource_link\";\n        readonly uri: string;\n        readonly name: string;\n        readonly title?: string;\n        readonly description?: string;\n        readonly mimeType?: string;\n        readonly size?: number;\n        readonly annotations?: McpAnnotations;\n        readonly icons?: ReadonlyArray<{\n            readonly src: string;\n            readonly mimeType?: string;\n            readonly sizes?: ReadonlyArray<string>;\n            readonly theme?: \"light\" | \"dark\";\n        }>;\n        readonly _meta?: McpMeta;\n    };\n\ninterface McpPresentation {\n    /** Suppress automatic presentation for this value and expose its original JSON. */\n    raw<T>(value: T): T;\n    text(text: string, annotations?: McpAnnotations): McpContentBlock;\n    image(data: string, mimeType: string, annotations?: McpAnnotations): McpContentBlock;\n    audio(data: string, mimeType: string, annotations?: McpAnnotations): McpContentBlock;\n    resource(\n        resource:\n            | {\n                readonly uri: string;\n                readonly mimeType?: string;\n                readonly text: string;\n                readonly _meta?: McpMeta;\n            }\n            | {\n                readonly uri: string;\n                readonly mimeType?: string;\n                readonly blob: string;\n                readonly _meta?: McpMeta;\n            },\n        annotations?: McpAnnotations,\n    ): McpContentBlock;\n    resourceLink(\n        resource: Omit<Extract<McpContentBlock, { readonly type: \"resource_link\" }>, \"type\">,\n    ): McpContentBlock;\n    /** Mark any MCP content block for validation when the script result is presented. */\n    content(block: McpContentBlock): McpContentBlock;\n    /**\n     * Return custom MCP content alongside a separate logical value. `value` is\n     * what the next call receives as `lastResultVal`.\n     */\n    result(options: {\n        readonly value?: unknown;\n        readonly structuredContent?: Record<string, unknown>;\n        readonly content?: ReadonlyArray<McpContentBlock>;\n        readonly isError?: boolean;\n        readonly _meta?: McpMeta;\n    }): unknown;\n}\n\ninterface SvcConnection {\n    /**\n     * Cooperative cancellation signal. When the sandbox is ~200 ms away\n     * from its hard timeout (and the configured `timeoutMs` was at least\n     * 500 ms), the host flips `aborted` to `true`, sets `reason`, and\n     * rejects every in-flight host promise with an `AbortError`. This\n     * gives the guest a small grace window to run `finally` blocks,\n     * persist partial state, or return a partial result before the hard\n     * interrupt kicks in. Subsequent `con.call` / `con.notify` /\n     * `con.explore` calls in this window reject immediately so the guest\n     * doesn't spend its grace window waiting for another RPC.\n     *\n     * Idiomatic use:\n     *\n     *     try {\n     *         return await con.call(s, i, m, params);\n     *     } catch (e) {\n     *         if (con.abortSignal.aborted) return { partial: true };\n     *         throw e;\n     *     }\n     */\n    readonly abortSignal: {\n        readonly aborted: boolean;\n        readonly reason: string | undefined;\n        throwIfAborted(): void;\n    };\n\n    /**\n     * Invoke a request on the bus.\n     *   - Form 3 (most common): pass `serviceId` to address a specific\n     *     participant: `con.call(\"vscode\", \"vscode.window\", \"showInformationMessage\", { message })`.\n     *   - Form 2: pass `serviceId: \"\"` to address the hub itself (the\n     *     root): `con.call(\"\", \"hubDirectory\", \"listPrefixes\")`.\n     *\n     * Rejects with an `Error` that carries the RPC error message when the\n     * peer returns a JSON-RPC error.\n     *\n     * Access is NOT automatic: a gated member you hold no capability for\n     * rejects with a permission error. Check `con.grants()` and request\n     * access via `con.requestAccess(...)` first — or pass\n     * `{ requestPermission: true }` to have this call auto-negotiate the\n     * capability it needs (a single `hubAccess` round-trip) and retry once.\n     *\n     * Streaming methods can report server-to-client messages while the request\n     * is pending:\n     *\n     *     const progress = [];\n     *     const result = await con.call(\"svc\", \"jobs\", \"run\", {}, {\n     *         onStreamMessage: message => {\n     *             progress.push(message);\n     *             console.log(\"progress\", message);\n     *         },\n     *     });\n     *\n     * When `onStreamMessage` is omitted, each stream message is written to\n     * `console.log` with the wire method name. This makes a parked streaming\n     * call observable through `awaitLinkRpcTask` without extra callback code.\n     */\n    call(\n        serviceId: string,\n        interfaceId: string,\n        member: string,\n        params?: unknown,\n        options?: CallOptions,\n    ): Promise<unknown>;\n\n    /** Fire-and-forget variant of `call`. Returns once the notification has been sent. */\n    notify(\n        serviceId: string,\n        interfaceId: string,\n        member: string,\n        params?: unknown,\n    ): Promise<void>;\n\n    /**\n     * Escape hatch when you have a fully-formed JSON-RPC method name (e.g.\n     * `\"vscode::vscode.window::showInformationMessage\"`). Prefer `call`.\n     */\n    callRaw(method: string, params?: unknown, options?: CallOptions): Promise<unknown>;\n    notifyRaw(method: string, params?: unknown): Promise<void>;\n\n    /**\n     * Discover and inspect the interfaces on the bus.\n     *\n     *   - `{ kind: \"browse\" }` lists stable virtual-document identities. Use\n     *     exact `serviceId` / `interfaceId` filters to narrow the directory.\n     *   - `{ kind: \"grep\", pattern }` searches the generated, self-contained\n     *     `defineInterface` source for every candidate. `pattern` is a\n     *     case-insensitive regular expression by default; set `syntax:\n     *     \"literal\"` for a case-insensitive substring. Results contain the\n     *     matching line, nearby source context, and enclosing member name.\n     *   - `{ kind: \"inspect\", serviceId, interfaceId }` returns one complete\n     *     generated source document. Set `format: \"schema\"` for its exact raw\n     *     wire schema instead.\n     *   - Reflection plumbing (`linkrpc.*`) is hidden unless `includeInternal`\n     *     is true or an exact internal `interfaceId` is requested.\n     *   - `requestPermission: true` requests one broad reflection grant and\n     *     walks gated directories. Without it, inaccessible branches are\n     *     reported explicitly instead of being silently omitted.\n     *   - Browse and grep use cursor pagination. Pass a returned `nextCursor`\n     *     back with the same query to continue.\n     */\n    explore(args: ExploreArgs): Promise<ExploreResult>;\n\n    /**\n     * List the capabilities this connection currently holds — what\n     * `(serviceId, interfaceId, members)` you may already invoke, each grant's\n     * expiry, and whether it is one-shot. Call this BEFORE invoking a gated\n     * member to check you have access, and to decide what to pass to\n     * `requestAccess`. Reflection (`explore`) works without any grant.\n     */\n    grants(): Promise<GrantsSummary>;\n\n    /**\n     * Request one or more capabilities from the hub. Calls are NOT\n     * auto-granted: if `con.call(...)` fails with a permission error, ask for\n     * access here first, then retry the call.\n     *\n     *   - Pass MANY `permissions` at once to batch related access into a\n     *     SINGLE user prompt (e.g. several members on one service, or read +\n     *     write together) instead of nagging once per call.\n     *   - Choose `duration`: `\"once\"` (single use, 5 min), `\"shortLived\"`\n     *     (5 min), `\"longLived\"` (24 h), or `\"persistent\"` (never expires,\n     *     remembered across runs).\n     *   - Granted durable caps are cached on the connection, so later\n     *     `con.call`s present them automatically — no need to re-request.\n     *\n     * `target.serviceId` / `interfaceId` / `members` are matchers:\n     * `{ exact: \"x\" }` or `{ prefix: \"x\" }` (`{ prefix: \"\" }` = any).\n     * Set `canInvoke: true` to actually call the members.\n     *\n     *     con.requestAccess({\n     *         permissions: [{\n     *             target: {\n     *                 serviceId: { exact: \"github\" },\n     *                 interfaceId: { exact: \"github.issues\" },\n     *                 members: [{ exact: \"list\" }, { exact: \"get\" }],\n     *             },\n     *             canInvoke: true,\n     *         }],\n     *         duration: \"longLived\",\n     *         purpose: \"read the open repo's issues\",\n     *     })\n     */\n    requestAccess(args: RequestAccessArgs): Promise<RequestAccessResult>;\n\n    /**\n     * Return this very text (the TypeScript declarations for the full script context).\n     * Synchronous, no host round-trip — just an embedded string. Useful\n     * when you want to re-read the API contract before composing a more\n     * complicated call.\n     */\n    getDocs(): string;\n}\n\n// ---- access (capabilities) ----------------------------------------------\n\n/** Per-call options for {@link SvcConnection.call} / {@link SvcConnection.callRaw}. */\ninterface CallOptions {\n    /**\n     * When `true` and the call is rejected because no capability is held\n     * (`permissionRequired`), automatically request access for exactly this\n     * `(serviceId, interfaceId, member)` — a single `hubAccess` round-trip —\n     * and retry the call once. The granted capability is durable\n     * (`longLived`), so later calls to the same member present it\n     * automatically. On a gated hub this may prompt the user.\n     *\n     * Defaults to `false`: a missing capability surfaces as an error directing\n     * you to `con.requestAccess(...)`.\n     */\n    readonly requestPermission?: boolean;\n    /**\n     * Called for each server-to-client stream message associated with this\n     * request. Messages are delivered as they arrive, including while a script\n     * is parked as a background task. Throwing from the callback fails the\n     * sandbox and cancels its outstanding requests. When omitted, messages are\n     * logged automatically.\n     */\n    readonly onStreamMessage?: (message: unknown) => void;\n}\n\n/**\n * Sandbox-owned timers. Pending timers continue to run while a script is\n * parked and are cancelled automatically when it completes, fails, is\n * cancelled, or reaches its maximum lifetime.\n */\ndeclare function setTimeout(\n    callback: (...args: unknown[]) => void,\n    timeout?: number,\n    ...args: unknown[]\n): number;\ndeclare function clearTimeout(timerId: number | undefined): void;\ndeclare function setInterval(\n    callback: (...args: unknown[]) => void,\n    timeout?: number,\n    ...args: unknown[]\n): number;\ndeclare function clearInterval(timerId: number | undefined): void;\n\n/** A `serviceId` / `interfaceId` / member matcher. `{ prefix: \"\" }` matches anything. */\ntype AccessPattern = { readonly exact: string } | { readonly prefix: string };\n\ninterface AccessPermission {\n    readonly target: {\n        readonly serviceId: AccessPattern;\n        readonly interfaceId: AccessPattern;\n        readonly interfaceHash?: string;\n        /** `[{ prefix: \"\" }]` covers every member. */\n        readonly members: ReadonlyArray<AccessPattern>;\n    };\n    /** Set true to actually invoke the members (default false). */\n    readonly canInvoke?: boolean;\n    /** Set true to allow re-delegating this authority (default false). */\n    readonly canDelegate?: boolean;\n    readonly params?: Record<string, unknown>;\n}\n\ninterface RequestAccessArgs {\n    /** One or more authorities to request together in a single prompt. */\n    readonly permissions: ReadonlyArray<AccessPermission>;\n    readonly duration?: \"once\" | \"shortLived\" | \"longLived\" | \"persistent\";\n    /** Short human-readable reason shown to the user. */\n    readonly purpose?: string;\n}\n\ntype RequestAccessResult =\n    | { readonly status: \"granted\"; readonly capabilities: ReadonlyArray<unknown>; readonly addedDurable: number }\n    | { readonly status: \"denied\"; readonly reason?: string }\n    | { readonly status: string; readonly reason?: string };\n\ninterface GrantPermissionSummary {\n    readonly serviceId: string;\n    readonly interfaceId: string;\n    readonly members: ReadonlyArray<string>;\n    readonly canInvoke: boolean;\n    readonly canDelegate: boolean;\n}\n\ninterface GrantSummary {\n    readonly issuer: string;\n    readonly audience: string;\n    readonly expiresAtMs?: number;\n    /** True when pinned to a single call (`callBind`); not reusable. */\n    readonly oneShot: boolean;\n    readonly permissions: ReadonlyArray<GrantPermissionSummary>;\n}\n\ninterface GrantsSummary {\n    readonly count: number;\n    readonly grants: ReadonlyArray<GrantSummary>;\n}\n\ninterface ExploreCommonArgs {\n    /** Exact directory-level filters, applied before browsing or searching. */\n    readonly serviceId?: string;\n    readonly interfaceId?: string;\n    /** Include reflection plumbing such as `hubrpc.directory` and `hubrpc.schemas`. */\n    readonly includeInternal?: boolean;\n    /** Request one broad reflection grant when a gated directory is encountered. */\n    readonly requestPermission?: boolean;\n}\n\ninterface ExploreBrowseArgs extends ExploreCommonArgs {\n    readonly kind: \"browse\";\n    /** Number of interfaces to return. Defaults to 20; maximum 100. */\n    readonly limit?: number;\n    /** Continuation cursor returned by a previous browse call. */\n    readonly cursor?: string;\n}\n\ninterface ExploreGrepArgs extends ExploreCommonArgs {\n    readonly kind: \"grep\";\n    /** Pattern searched against generated `defineInterface` source, one line at a time. */\n    readonly pattern: string;\n    /** Defaults to `regex`. Both modes are case-insensitive. */\n    readonly syntax?: \"regex\" | \"literal\";\n    /** Number of matching virtual documents to return. Defaults to 20; maximum 100. */\n    readonly limit?: number;\n    /** Continuation cursor returned by a previous grep call. */\n    readonly cursor?: string;\n    /** Source lines included before and after each match. Defaults to 1; maximum 5. */\n    readonly contextLines?: number;\n}\n\ninterface ExploreInspectArgs extends ExploreCommonArgs {\n    readonly kind: \"inspect\";\n    readonly serviceId: string;\n    readonly interfaceId: string;\n    /** Generated source by default; use `schema` for the raw wire schema. */\n    readonly format?: \"source\" | \"schema\";\n}\n\ntype ExploreArgs = ExploreBrowseArgs | ExploreGrepArgs | ExploreInspectArgs;\n\ntype ExploreResult = ExploreBrowseResult | ExploreGrepResult | ExploreInspectResult;\n\ninterface ExploreListing {\n    readonly serviceId: string;\n    readonly serviceDescription?: string;\n    readonly interfaceId: string;\n    readonly interfaceHash: string;\n    readonly documentId: string;\n}\n\ninterface ExploreBrowseResult {\n    readonly kind: \"browse\";\n    readonly total: number;\n    readonly entries: ReadonlyArray<ExploreListing>;\n    readonly nextCursor?: string;\n    readonly inaccessible?: ReadonlyArray<ExploreInaccessible>;\n}\n\ninterface ExploreGrepMatch {\n    /** Matching source plus the requested surrounding context, joined with newlines. */\n    readonly searchResult: string;\n    /** Inclusive, 1-based line range of `searchResult` in the virtual document. */\n    readonly lineRange: readonly [start: number, end: number];\n    /** LinkRPC member containing every matched line in this chunk, when unambiguous. */\n    readonly member?: string;\n}\n\ninterface ExploreGrepEntry extends ExploreListing {\n    readonly matches: ReadonlyArray<ExploreGrepMatch>;\n    readonly matchesTruncated?: boolean;\n}\n\ninterface ExploreDocumentError {\n    readonly serviceId: string;\n    readonly interfaceId: string;\n    readonly error: string;\n}\n\ninterface ExploreGrepResult {\n    readonly kind: \"grep\";\n    readonly pattern: string;\n    readonly syntax: \"regex\" | \"literal\";\n    readonly total: number;\n    readonly entries: ReadonlyArray<ExploreGrepEntry>;\n    readonly nextCursor?: string;\n    readonly documentErrors?: ReadonlyArray<ExploreDocumentError>;\n    readonly inaccessible?: ReadonlyArray<ExploreInaccessible>;\n}\n\ninterface ExploreInspectResult extends ExploreListing {\n    readonly kind: \"inspect\";\n    readonly format: \"source\" | \"schema\";\n    readonly source?: string;\n    readonly schema?: unknown;\n    readonly inaccessible?: ReadonlyArray<ExploreInaccessible>;\n}\n\ninterface ExploreInaccessible {\n    /** The directory target (serviceId) that could not be enumerated. */\n    readonly serviceId: string;\n    /** The error message from the denied directory lookup. */\n    readonly reason: string;\n    /** Actionable next step to gain visibility into this directory. */\n    readonly hint: string;\n}\n\n// ---- console -------------------------------------------------------------\n// `console.log`, `console.warn`, `console.error` are captured and\n// returned alongside the tool result. There is no `console.debug` /\n// `console.trace` etc.\ndeclare const console: {\n    log(...args: unknown[]): void;\n    warn(...args: unknown[]): void;\n    error(...args: unknown[]): void;\n};\n\n// ---- Notes ---------------------------------------------------------------\n// - Everything is JSON-serialisable. Functions, dates, etc. become `null`\n//   when crossing the sandbox boundary.\n// - The user code MUST evaluate to a function. Top-level statements are\n//   wrapped, so write an arrow or function expression, not a bare\n//   `await con.call(...)`.\n// - `throw` inside user code surfaces as a failed tool call.\n";
+//#endregion
+//#region src/sandbox.ts
+/**
+* The guest runtime (`src/guest/guestMain.ts`) bundled to plain JS, evaluated
+* inside QuickJS before any user code. Authoring it as real TypeScript that is
+* type-checked against `connection.d.ts` is what keeps `con` from drifting out
+* of sync with its declarations.
+*
+* `@vscode/rollup-plugin-esm-url` rewrites the `?esm` URL at build time to the
+* emitted (already-transpiled) chunk next to this module, so the production
+* read returns JS. In dev/test (vite serve, no rewrite) the URL still points
+* at the `.ts` source, so we transpile it on the fly with the `typescript`
+* devDependency — that branch never runs in the shipped `dist`.
+*/
+function _loadGuestRuntime() {
+	const filePath = fileURLToPath(new URL("../src-guest-guestMain.js?esm", import.meta.url));
+	const code = readFileSync(filePath, "utf8");
+	if (!filePath.endsWith(".ts")) return _asGuestScript(code);
+	const ts = createRequire(import.meta.url)("typescript");
+	const transpiled = ts.transpileModule(code, { compilerOptions: {
+		target: ts.ScriptTarget.ES2022,
+		module: ts.ModuleKind.ESNext
+	} }).outputText;
+	return _asGuestScript(transpiled);
+}
+function _asGuestScript(code) {
+	return code.replace(/^\s*export\s*\{\s*\};?\s*$/m, "");
+}
+const GUEST_RUNTIME_JS = _loadGuestRuntime();
+const DEFAULT_FOREGROUND_MS = 5e3;
+const DEFAULT_MAX_LIFETIME_MS = 12e4;
+const DEFAULT_MEMORY_LIMIT_BYTES = 33554432;
+/**
+* Grace window granted to the guest after a soft abort (cancel / max
+* lifetime) so it can run `catch`/`finally` and return a partial result
+* before the task is force-settled.
+*/
+const SOFT_CANCEL_GRACE_MS = 200;
+let _quickjsPromise;
+function _qjs() {
+	if (!_quickjsPromise) _quickjsPromise = getQuickJS();
+	return _quickjsPromise;
+}
+const _delay = () => new Promise((r) => setImmediate(r));
+/**
+* Run-to-completion entry point preserved for callers that just want a result
+* and treat the timeout as a hard wall (the original behaviour). Throws on
+* guest error or deadline; never parks.
+*/
+async function runSandboxed(userCode, host, lastResultVal, options = {}) {
+	const budget = options.timeoutMs ?? DEFAULT_FOREGROUND_MS;
+	const outcome = await (await SandboxExecution.create(userCode, host, lastResultVal, {
+		foregroundMs: budget,
+		maxLifetimeMs: budget,
+		memoryLimitBytes: options.memoryLimitBytes
+	})).runForeground();
+	if (outcome.status === "completed") return {
+		resultJson: outcome.result === void 0 ? "" : JSON.stringify(outcome.result),
+		logs: outcome.logs
+	};
+	if (outcome.status === "error") throw new Error(outcome.error);
+	const final = await outcome.task.cancel();
+	throw new Error(final.status === "error" ? final.error : "sandbox deadline exceeded");
+}
+/**
+* Parking-capable entry point. Runs `userCode` for up to `foregroundMs`; if it
+* settles in that window the result is returned inline, otherwise the live VM
+* is detached into a {@link ParkedTask} that keeps pumping in the background.
+*/
+async function startSandbox(userCode, host, lastResultVal, options = {}) {
+	return (await SandboxExecution.create(userCode, host, lastResultVal, {
+		foregroundMs: options.foregroundMs ?? DEFAULT_FOREGROUND_MS,
+		maxLifetimeMs: options.maxLifetimeMs ?? DEFAULT_MAX_LIFETIME_MS,
+		memoryLimitBytes: options.memoryLimitBytes,
+		label: options.label
+	})).runForeground();
+}
+/**
+* Encapsulates one QuickJS context and drives it through a foreground phase
+* and (optionally) a background phase. Only one driver loop runs at a time:
+* `runForeground` runs first and, if it parks, hands off to `_runBackground`.
+* `cancel` cooperates with the background loop rather than starting its own.
+*/
+var SandboxExecution = class SandboxExecution {
+	_userCode;
+	_host;
+	_lastResultVal;
+	_options;
+	static async create(userCode, host, lastResultVal, options) {
+		const QuickJS = await _qjs();
+		const exec = new SandboxExecution(userCode, host, lastResultVal, options);
+		try {
+			exec._init(QuickJS);
+		} catch (e) {
+			exec._dispose();
+			throw e;
+		}
+		return exec;
+	}
+	_scope = new Scope();
+	_logs = [];
+	/** In-flight host->guest deferreds keyed by a human-readable call label. */
+	_pendingDeferreds = /* @__PURE__ */ new Map();
+	_pendingTimers = /* @__PURE__ */ new Map();
+	_vmState = {
+		alive: true,
+		softAborted: false,
+		softAbortReason: void 0
+	};
+	_abortController = new AbortController();
+	_cpuBurstMs;
+	_startedAt = Date.now();
+	_runtime;
+	_vm;
+	_promiseH;
+	/** Deadline for the current synchronous burst; read by the interrupt handler. */
+	_cpuDeadline = 0;
+	_disposed = false;
+	_settled;
+	_backgroundDone;
+	_cancelGraceDeadline;
+	constructor(_userCode, _host, _lastResultVal, _options) {
+		this._userCode = _userCode;
+		this._host = _host;
+		this._lastResultVal = _lastResultVal;
+		this._options = _options;
+		this._cpuBurstMs = Math.max(_options.foregroundMs, 50);
+	}
+	get _allowPark() {
+		return this._options.maxLifetimeMs > this._options.foregroundMs;
+	}
+	_init(QuickJS) {
+		const runtime = this._scope.manage(QuickJS.newRuntime());
+		runtime.setMemoryLimit(this._options.memoryLimitBytes ?? DEFAULT_MEMORY_LIMIT_BYTES);
+		runtime.setInterruptHandler(() => Date.now() > this._cpuDeadline);
+		this._runtime = runtime;
+		this._vm = this._scope.manage(runtime.newContext());
+		this._cpuDeadline = Date.now() + this._cpuBurstMs;
+		this._installHostApi();
+		_evalPrelude(this._vm, this._lastResultVal);
+	}
+	async runForeground() {
+		this._cpuDeadline = Date.now() + this._cpuBurstMs;
+		const evalRes = this._vm.evalCode(_wrapUserCode(this._userCode));
+		if (evalRes.error) {
+			const dumped = this._vm.dump(evalRes.error);
+			evalRes.error.dispose();
+			this._forceSettle({
+				status: "error",
+				error: _formatGuestError(dumped),
+				logs: this._logs.slice()
+			});
+			return this._terminalOutcome();
+		}
+		this._promiseH = evalRes.value;
+		this._pump();
+		if (await this._loopUntil(Date.now() + this._options.foregroundMs) === "settled") return this._terminalOutcome();
+		if (!this._allowPark) {
+			this._triggerSoftAbort("sandbox deadline exceeded");
+			await this._loopUntil(Date.now() + SOFT_CANCEL_GRACE_MS);
+			if (!this._settled) this._forceSettle({
+				status: "error",
+				error: "sandbox deadline exceeded",
+				logs: this._logs.slice()
+			});
+			return this._terminalOutcome();
+		}
+		const debugName = this._computeDebugName();
+		this._backgroundDone = this._runBackground();
+		return {
+			status: "parked",
+			debugName,
+			task: this._asParkedTask()
+		};
+	}
+	async _runBackground() {
+		const hardDeadline = this._startedAt + this._options.maxLifetimeMs;
+		while (true) {
+			if (this._settled || this._checkPromise()) break;
+			const now = Date.now();
+			if (this._cancelGraceDeadline !== void 0 && now > this._cancelGraceDeadline) {
+				this._forceSettle({
+					status: "cancelled",
+					logs: this._logs.slice()
+				});
+				break;
+			}
+			if (now > hardDeadline) {
+				this._triggerSoftAbort("max lifetime exceeded");
+				this._forceSettle({
+					status: "error",
+					error: "sandbox max lifetime exceeded",
+					logs: this._logs.slice()
+				});
+				break;
+			}
+			await _delay();
+			this._pump();
+		}
+		return this._settled;
+	}
+	/** Pump + poll the user promise until it settles or `deadline` passes. */
+	async _loopUntil(deadline) {
+		while (true) {
+			if (this._settled || this._checkPromise()) return "settled";
+			if (Date.now() > deadline) return "pending";
+			await _delay();
+			this._pump();
+		}
+	}
+	/** Returns true once the user promise has settled (and disposes the VM). */
+	_checkPromise() {
+		if (this._settled) return true;
+		if (!this._vmState.alive || !this._promiseH) return true;
+		const state = this._vm.getPromiseState(this._promiseH);
+		if (state.type === "fulfilled") {
+			let json;
+			try {
+				json = this._vm.getString(state.value);
+			} finally {
+				state.value.dispose();
+			}
+			const result = json === "" ? void 0 : JSON.parse(json);
+			this._forceSettle({
+				status: "completed",
+				result,
+				logs: this._logs.slice()
+			});
+			return true;
+		}
+		if (state.type === "rejected") {
+			const dumped = this._vm.dump(state.error);
+			state.error.dispose();
+			const e = _toError(dumped);
+			this._settleError(e.message, _formatGuestError(dumped));
+			return true;
+		}
+		return false;
+	}
+	_settleError(message, detail) {
+		if (this._vmState.softAborted && /abort/i.test(message)) {
+			this._forceSettle({
+				status: "cancelled",
+				logs: this._logs.slice()
+			});
+			return;
+		}
+		const normalized = /interrupt/i.test(message) ? "sandbox deadline exceeded" : detail ?? message;
+		this._forceSettle({
+			status: "error",
+			error: normalized,
+			logs: this._logs.slice()
+		});
+	}
+	_forceSettle(outcome) {
+		if (this._settled) return;
+		this._dispose();
+		this._settled = outcome;
+	}
+	_pump() {
+		if (!this._vmState.alive || this._disposed) return;
+		this._cpuDeadline = Date.now() + this._cpuBurstMs;
+		const r = this._runtime.executePendingJobs();
+		if (r.error) {
+			const dumped = this._vm.dump(r.error);
+			r.error.dispose();
+			const e = _toError(dumped);
+			this._settleError(e.message, _formatGuestError(dumped));
+		}
+	}
+	_computeDebugName() {
+		if (this._options.label) return this._options.label;
+		const inflight = this._inFlight();
+		if (inflight.length > 0) return inflight.join(", ");
+		return _firstLine(this._userCode);
+	}
+	_inFlight() {
+		return [...this._pendingDeferreds.values(), ...[...this._pendingTimers.values()].map((timer) => `${timer.repeat ? "setInterval" : "setTimeout"}(${timer.delayMs}ms)`)];
+	}
+	_asParkedTask() {
+		return {
+			inFlight: () => this._inFlight(),
+			logs: this._logs,
+			done: this._backgroundDone,
+			cancel: () => this.cancel()
+		};
+	}
+	async cancel() {
+		if (this._settled) return this._settled;
+		this._triggerSoftAbort("cancelled");
+		this._cancelGraceDeadline = Date.now() + SOFT_CANCEL_GRACE_MS;
+		if (this._backgroundDone) return this._backgroundDone;
+		this._forceSettle({
+			status: "cancelled",
+			logs: this._logs.slice()
+		});
+		return this._settled;
+	}
+	/**
+	* Flip the guest-visible `con.abortSignal.aborted` flag and reject every
+	* in-flight host promise with an `AbortError` naming the call.
+	*/
+	_triggerSoftAbort(reason) {
+		if (this._vmState.softAborted || !this._vmState.alive) return;
+		this._vmState.softAborted = true;
+		this._vmState.softAbortReason = reason;
+		this._abortController.abort(reason);
+		this._clearAllTimers();
+		this._cpuDeadline = Date.now() + this._cpuBurstMs;
+		const setFlag = this._vm.evalCode(`(() => {
+                if (globalThis.con && globalThis.con.abortSignal) {
+                    globalThis.con.abortSignal.aborted = true;
+                    globalThis.con.abortSignal.reason = ${JSON.stringify(reason)};
+                }
+            })()`);
+		if (setFlag.error) setFlag.error.dispose();
+		else setFlag.value.dispose();
+		const entries = [...this._pendingDeferreds];
+		this._pendingDeferreds.clear();
+		for (const [d, label] of entries) {
+			if (!d.alive) continue;
+			this._vm.newError(`AbortError: ${reason} (cancelled in-flight: ${label})`).consume((errH) => d.reject(errH));
+		}
+		this._pump();
+	}
+	_dispose() {
+		if (this._disposed) return;
+		this._disposed = true;
+		this._vmState.alive = false;
+		if (!this._abortController.signal.aborted) this._abortController.abort("sandbox disposed");
+		this._clearAllTimers();
+		for (const d of this._pendingDeferreds.keys()) if (d.alive) d.dispose();
+		this._pendingDeferreds.clear();
+		if (this._promiseH && this._promiseH.alive) this._promiseH.dispose();
+		this._scope.dispose();
+	}
+	_terminalOutcome() {
+		const o = this._settled;
+		if (!o) throw new Error("sandbox: terminal outcome requested before settling");
+		if (o.status === "completed") return {
+			status: "completed",
+			result: o.result,
+			logs: o.logs
+		};
+		if (o.status === "cancelled") return {
+			status: "error",
+			error: "sandbox cancelled",
+			logs: o.logs
+		};
+		return {
+			status: "error",
+			error: o.error,
+			logs: o.logs
+		};
+	}
+	_installHostApi() {
+		this._registerAsyncHostFn("__hostCall", (method, paramsJson, optsJson, emit) => this._host.call(method, paramsJson, optsJson, emit, this._abortController.signal), (method) => `con.call(${JSON.stringify(method)})`, "__dispatchHostStream");
+		this._registerAsyncHostFn("__hostNotify", (m, p) => this._host.notify(m, p), (method) => `con.notify(${JSON.stringify(method)})`);
+		this._registerAsyncHostFn("__hostExplore", (a) => this._host.explore(a), () => `con.explore(...)`);
+		this._registerAsyncHostFn("__hostRequestAccess", (a) => this._host.requestAccess(a), () => `con.requestAccess(...)`);
+		this._registerAsyncHostFn("__hostGrants", (a) => this._host.grants(a), () => `con.grants()`);
+		this._vm.newFunction("__hostLog", (levelH, textH) => {
+			const level = this._vm.getString(levelH);
+			const text = textH ? this._vm.getString(textH) : "";
+			this._logs.push({
+				level,
+				text
+			});
+		}).consume((fn) => this._vm.setProp(this._vm.global, "__hostLog", fn));
+		this._vm.newFunction("__hostSetTimer", (idH, delayH, repeatH) => {
+			this._setTimer(this._vm.getNumber(idH), this._vm.getNumber(delayH), this._vm.getNumber(repeatH) === 1);
+		}).consume((fn) => this._vm.setProp(this._vm.global, "__hostSetTimer", fn));
+		this._vm.newFunction("__hostClearTimer", (idH) => {
+			this._clearTimer(this._vm.getNumber(idH));
+		}).consume((fn) => this._vm.setProp(this._vm.global, "__hostClearTimer", fn));
+	}
+	_setTimer(timerId, delayMs, repeat) {
+		this._clearTimer(timerId);
+		if (!this._vmState.alive || this._vmState.softAborted) return;
+		const normalizedDelay = Math.min(Math.max(0, Math.floor(delayMs)), 2147483647);
+		const callback = () => {
+			if (!this._vmState.alive || this._disposed) return;
+			if (!repeat) this._pendingTimers.delete(timerId);
+			this._dispatchGuestFunction("__dispatchHostTimer", timerId);
+		};
+		const handle = repeat ? setInterval(callback, normalizedDelay) : setTimeout(callback, normalizedDelay);
+		this._pendingTimers.set(timerId, {
+			handle,
+			repeat,
+			delayMs: normalizedDelay
+		});
+	}
+	_clearTimer(timerId) {
+		const timer = this._pendingTimers.get(timerId);
+		if (!timer) return;
+		if (timer.repeat) clearInterval(timer.handle);
+		else clearTimeout(timer.handle);
+		this._pendingTimers.delete(timerId);
+	}
+	_clearAllTimers() {
+		for (const timerId of [...this._pendingTimers.keys()]) this._clearTimer(timerId);
+	}
+	_dispatchGuestFunction(name, ...args) {
+		if (!this._vmState.alive || this._disposed || this._settled) return;
+		this._cpuDeadline = Date.now() + this._cpuBurstMs;
+		const result = this._vm.evalCode(`globalThis[${JSON.stringify(name)}](...${JSON.stringify(args)})`);
+		if (result.error) {
+			const dumped = this._vm.dump(result.error);
+			result.error.dispose();
+			const error = _toError(dumped);
+			this._settleError(error.message, _formatGuestError(dumped));
+			return;
+		}
+		result.value.dispose();
+		this._pump();
+	}
+	_registerAsyncHostFn(name, impl, label, guestEventHandler) {
+		this._vm.newFunction(name, (aH, bH, cH, eventIdH) => {
+			const a = aH ? this._vm.getString(aH) : "";
+			const b = bH ? this._vm.getString(bH) : "";
+			const c = cH ? this._vm.getString(cH) : "";
+			const eventId = eventIdH ? this._vm.getString(eventIdH) : "";
+			const deferred = this._vm.newPromise();
+			if (this._vmState.softAborted) {
+				const reason = this._vmState.softAbortReason ?? "soft deadline reached";
+				this._vm.newError(`AbortError: ${reason} (refused: ${label(a, b, c)})`).consume((errH) => deferred.reject(errH));
+				deferred.settled.then(() => this._pump());
+				return deferred.handle;
+			}
+			this._pendingDeferreds.set(deferred, label(a, b, c));
+			impl(a, b, c, (payloadJson) => {
+				if (guestEventHandler && eventId !== "") this._dispatchGuestFunction(guestEventHandler, eventId, payloadJson);
+			}).then((value) => {
+				this._pendingDeferreds.delete(deferred);
+				if (!this._vmState.alive || !deferred.alive) return;
+				this._vm.newString(value).consume((sH) => deferred.resolve(sH));
+			}, (err) => {
+				this._pendingDeferreds.delete(deferred);
+				if (!this._vmState.alive || !deferred.alive) return;
+				this._newGuestHostError(err).consume((errH) => deferred.reject(errH));
+			});
+			deferred.settled.then(() => this._pump());
+			return deferred.handle;
+		}).consume((fn) => this._vm.setProp(this._vm.global, name, fn));
+	}
+	_newGuestHostError(thrown) {
+		const snapshot = _snapshotHostRejection(thrown);
+		const source = `(() => {
+            const error = new Error(${JSON.stringify(snapshot.summary)});
+            const properties = JSON.parse(${JSON.stringify(JSON.stringify(snapshot.properties))});
+            for (const [key, value] of Object.entries(properties)) {
+                Object.defineProperty(error, key, {
+                    value,
+                    writable: true,
+                    enumerable: true,
+                    configurable: true,
+                });
+            }
+            return error;
+        })()`;
+		const result = this._vm.evalCode(source);
+		if (result.error) {
+			result.error.dispose();
+			return this._vm.newError(snapshot.summary);
+		}
+		return result.value;
+	}
+};
+const MAX_REJECTION_DEPTH = 8;
+const MAX_REJECTION_PROPERTIES = 100;
+const MAX_REJECTION_ARRAY_ITEMS = 100;
+const MAX_REJECTION_STRING_LENGTH = 2e4;
+const MAX_REJECTION_NODES = 1e3;
+const MAX_REJECTION_TOTAL_STRING_LENGTH = 1e5;
+function _snapshotHostRejection(thrown) {
+	return {
+		summary: _rejectionSummary(thrown),
+		properties: _snapshotOwnDataProperties(thrown)
+	};
+}
+function _rejectionSummary(thrown) {
+	if (thrown === null) return "Host operation rejected with null";
+	if (typeof thrown !== "object" && typeof thrown !== "function") return `Host operation rejected with ${String(thrown)}`;
+	return "Host operation failed";
+}
+function _snapshotOwnDataProperties(value) {
+	if ((typeof value !== "object" || value === null) && typeof value !== "function") return { value: _snapshotBridgeValue(value, /* @__PURE__ */ new WeakSet(), 0, _newSnapshotBudget()) };
+	let descriptors;
+	try {
+		descriptors = Object.getOwnPropertyDescriptors(value);
+	} catch {
+		return {};
+	}
+	const seen = /* @__PURE__ */ new WeakSet();
+	seen.add(value);
+	const budget = _newSnapshotBudget();
+	const result = {};
+	for (const [key, descriptor] of Object.entries(descriptors).slice(0, MAX_REJECTION_PROPERTIES)) {
+		if (!("value" in descriptor)) continue;
+		result[key] = _snapshotBridgeValue(descriptor.value, seen, 0, budget);
+	}
+	return result;
+}
+function _newSnapshotBudget() {
+	return {
+		nodes: MAX_REJECTION_NODES,
+		stringChars: MAX_REJECTION_TOTAL_STRING_LENGTH
+	};
+}
+function _snapshotBridgeValue(value, seen, depth, budget) {
+	if (budget.nodes <= 0) return "[Truncated]";
+	budget.nodes--;
+	if (value === null || typeof value === "boolean" || typeof value === "number") return value;
+	if (typeof value === "string") {
+		const available = Math.min(MAX_REJECTION_STRING_LENGTH, budget.stringChars);
+		budget.stringChars -= Math.min(value.length, available);
+		return value.length <= available ? value : `${value.slice(0, available)}…`;
+	}
+	if (typeof value === "undefined") return "[undefined]";
+	if (typeof value === "bigint") return `${value}n`;
+	if (typeof value === "symbol") return String(value);
+	if (typeof value === "function") return `[Function${value.name ? `: ${value.name}` : ""}]`;
+	if (depth >= MAX_REJECTION_DEPTH) return "[Truncated]";
+	if (seen.has(value)) return "[Circular]";
+	seen.add(value);
+	if (Array.isArray(value)) return value.slice(0, MAX_REJECTION_ARRAY_ITEMS).map((item) => _snapshotBridgeValue(item, seen, depth + 1, budget));
+	let descriptors;
+	try {
+		descriptors = Object.getOwnPropertyDescriptors(value);
+	} catch {
+		return "[Uninspectable]";
+	}
+	const result = {};
+	for (const [key, descriptor] of Object.entries(descriptors).slice(0, MAX_REJECTION_PROPERTIES)) {
+		if (!("value" in descriptor)) continue;
+		result[key] = _snapshotBridgeValue(descriptor.value, seen, depth + 1, budget);
+	}
+	return result;
+}
+function _evalPrelude(vm, lastResultVal) {
+	const header = `globalThis.__lastResultVal = JSON.parse(${JSON.stringify(JSON.stringify(lastResultVal ?? null))});\nglobalThis.__docs = ${JSON.stringify(CONNECTION_DTS)};\n`;
+	const r = vm.evalCode(header + GUEST_RUNTIME_JS);
+	if (r.error) {
+		const err = vm.dump(r.error);
+		r.error.dispose();
+		throw new Error(`sandbox prelude failed: ${JSON.stringify(err)}`);
+	}
+	r.value.dispose();
+}
+function _wrapUserCode(userCode) {
+	return `(async () => {
+    const __userFn = (${userCode});
+    if (typeof __userFn !== "function") {
+        throw new Error("runLinkRpcScript: \`code\` must evaluate to a function, got " + typeof __userFn);
+    }
+    const __r = await __userFn({ con, lastResultVal: __lastResultVal, mcp });
+    return __r === undefined ? "" : JSON.stringify(__r);
+})()`;
+}
+function _firstLine(code) {
+	const line = code.split("\n", 1)[0].trim();
+	return line.length > 80 ? `${line.slice(0, 79)}…` : line;
+}
+function _toError(dumped) {
+	let json;
+	try {
+		json = JSON.stringify(dumped);
+	} catch {
+		json = String(dumped);
+	}
+	if (dumped && typeof dumped === "object") {
+		const d = dumped;
+		const message = typeof d.message === "string" && d.message.length > 0 ? d.message : `guest error (raw): ${json}`;
+		const e = new Error(message);
+		if (typeof d.stack === "string") e.stack = d.stack;
+		return e;
+	}
+	return /* @__PURE__ */ new Error(`guest error: ${json}`);
+}
+/**
+* Format a dumped guest error as `message` plus its guest stack (when QuickJS
+* provided one). The host only forwards the `error` string to the caller, so
+* folding the stack in here is the only way the guest trace ever reaches them.
+*/
+function _formatGuestError(dumped) {
+	const e = _toError(dumped);
+	const stack = e.stack;
+	if (typeof stack === "string" && stack.length > 0) return stack.includes(e.message) ? stack : `${e.message}\n${stack}`;
+	return e.message;
+}
+//#endregion
+//#region src/taskRegistry.ts
+/**
+* Tracks parked sandbox tasks. At most one task is "live" at a time across all
+* connections: starting a new one supersedes (cancels) the previous one via
+* {@link cancelLive}. Settled tasks are retained so their result can still be
+* fetched by id, and pruned opportunistically.
+*/
+var TaskRegistry = class {
+	_maxSettledAgeMs;
+	_byId = /* @__PURE__ */ new Map();
+	_live;
+	_seq = 0;
+	constructor(_maxSettledAgeMs = 3e5) {
+		this._maxSettledAgeMs = _maxSettledAgeMs;
+	}
+	/**
+	* Register a freshly parked task. Assigns a task id and wires up settlement
+	* bookkeeping. `onComplete` fires with the result when the task completes
+	* (used to thread `lastResultVal`).
+	*/
+	register(endpoint, debugName, task, onComplete) {
+		this._prune();
+		const id = `t${++this._seq}`;
+		const entry = {
+			id,
+			debugName,
+			endpoint,
+			startedAt: Date.now(),
+			task,
+			outcome: void 0
+		};
+		this._byId.set(id, entry);
+		this._live = entry;
+		task.done.then((o) => {
+			entry.outcome = o;
+			if (this._live === entry) this._live = void 0;
+			if (o.status === "completed") onComplete?.(o.result);
+		}, () => {});
+		return id;
+	}
+	/**
+	* Cancel the single live task, if any (the supersede path). Resolves once
+	* the cancellation settles.
+	*/
+	async cancelLive() {
+		const entry = this._live;
+		if (!entry) return void 0;
+		this._live = void 0;
+		await entry.task.cancel();
+		return {
+			taskId: entry.id,
+			debugName: entry.debugName,
+			outcome: "cancelled"
+		};
+	}
+	/**
+	* Wait up to `timeoutMs` for `taskId` to settle. Returns `running` (with a
+	* progress snapshot) if it is still going, otherwise its terminal result.
+	*/
+	async awaitTask(taskId, timeoutMs) {
+		const entry = this._byId.get(taskId);
+		if (!entry) return {
+			status: "unknown",
+			taskId
+		};
+		if (!entry.outcome) {
+			const timeout = new Promise((r) => {
+				setTimeout(() => r("timeout"), timeoutMs).unref?.();
+			});
+			if (await Promise.race([entry.task.done, timeout]) === "timeout") return {
+				status: "running",
+				taskId,
+				debugName: entry.debugName,
+				inFlight: entry.task.inFlight(),
+				logs: [...entry.task.logs]
+			};
+		}
+		return this._outcomeResult(entry);
+	}
+	/** Explicitly cancel a task by id. */
+	async cancel(taskId) {
+		const entry = this._byId.get(taskId);
+		if (!entry) return {
+			status: "unknown",
+			taskId
+		};
+		await entry.task.cancel();
+		return this._outcomeResult(entry);
+	}
+	/** List live (unsettled) tasks. At most one under the global invariant. */
+	list() {
+		const out = [];
+		for (const e of this._byId.values()) {
+			if (e.outcome) continue;
+			out.push({
+				taskId: e.id,
+				debugName: e.debugName,
+				endpoint: e.endpoint,
+				ageMs: Date.now() - e.startedAt,
+				inFlight: e.task.inFlight(),
+				logCount: e.task.logs.length
+			});
+		}
+		return out;
+	}
+	/** Cancel every live task. */
+	dispose() {
+		for (const e of this._byId.values()) if (!e.outcome) e.task.cancel();
+		this._byId.clear();
+		this._live = void 0;
+	}
+	_outcomeResult(entry) {
+		const o = entry.outcome;
+		if (!o) return {
+			status: "running",
+			taskId: entry.id,
+			debugName: entry.debugName,
+			inFlight: entry.task.inFlight(),
+			logs: [...entry.task.logs]
+		};
+		if (o.status === "completed") return {
+			status: "completed",
+			taskId: entry.id,
+			debugName: entry.debugName,
+			result: o.result,
+			logs: o.logs
+		};
+		if (o.status === "cancelled") return {
+			status: "cancelled",
+			taskId: entry.id,
+			debugName: entry.debugName,
+			logs: o.logs
+		};
+		return {
+			status: "error",
+			taskId: entry.id,
+			debugName: entry.debugName,
+			error: o.error,
+			logs: o.logs
+		};
+	}
+	_prune() {
+		const cutoff = Date.now() - this._maxSettledAgeMs;
+		for (const [id, e] of this._byId) if (e.outcome && e.startedAt < cutoff) this._byId.delete(id);
+	}
+};
+//#endregion
+//#region src/explore.ts
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+const MAX_MATCHES_PER_DOCUMENT = 20;
+const interfaceCache = /* @__PURE__ */ new WeakMap();
+/**
+* Browse the reflected directory, grep generated interface source, or inspect
+* one exact virtual document. Generated source is cached by the directory
+* route and interface hash; every call still walks the live directory.
+*/
+async function explore(channel, args, deps) {
+	if (args === void 0 || typeof args !== "object" || !("kind" in args)) throw new Error("explore requires `kind: \"browse\" | \"grep\" | \"inspect\"`.");
+	const unlockGatedDirectory = args.requestPermission === true && deps !== void 0 ? (_serviceId) => deps.requestReflectionAccess() : void 0;
+	const walked = await walkHubDetailed(channel, { unlockGatedDirectory });
+	const listings = _filterAndSort(walked.listings, args);
+	const inaccessible = _inaccessible(walked.inaccessible);
+	switch (args.kind) {
+		case "browse": {
+			const page = _page(listings, args.limit, args.cursor);
+			return {
+				kind: "browse",
+				total: listings.length,
+				entries: page.items.map(_toListing),
+				...page.nextCursor !== void 0 ? { nextCursor: page.nextCursor } : {},
+				...inaccessible !== void 0 ? { inaccessible } : {}
+			};
+		}
+		case "grep": {
+			if (typeof args.pattern !== "string" || args.pattern.length === 0) throw new Error("explore grep requires a non-empty `pattern`.");
+			const syntax = args.syntax ?? "regex";
+			const matchesLine = _createLineMatcher(args.pattern, syntax);
+			const contextLines = _boundedInteger(args.contextLines ?? 1, 0, 5, "contextLines");
+			const loaded = await Promise.all(listings.map(async (listing) => {
+				try {
+					return { document: await _loadDocument(channel, listing) };
+				} catch (error) {
+					return { error: {
+						serviceId: listing.serviceId,
+						interfaceId: listing.interfaceId,
+						error: error.message
+					} };
+				}
+			}));
+			const entries = [];
+			const documentErrors = [];
+			for (const item of loaded) {
+				if (item.error !== void 0) {
+					documentErrors.push(item.error);
+					continue;
+				}
+				const document = item.document;
+				const matches = _grepDocument(document, matchesLine, contextLines);
+				if (matches.length === 0) continue;
+				entries.push({
+					..._toListing(document.listing),
+					matches: matches.slice(0, MAX_MATCHES_PER_DOCUMENT),
+					...matches.length > MAX_MATCHES_PER_DOCUMENT ? { matchesTruncated: true } : {}
+				});
+			}
+			const page = _page(entries, args.limit, args.cursor);
+			return {
+				kind: "grep",
+				pattern: args.pattern,
+				syntax,
+				total: entries.length,
+				entries: page.items,
+				...page.nextCursor !== void 0 ? { nextCursor: page.nextCursor } : {},
+				...documentErrors.length > 0 ? { documentErrors } : {},
+				...inaccessible !== void 0 ? { inaccessible } : {}
+			};
+		}
+		case "inspect": {
+			const listing = listings.find((item) => item.serviceId === args.serviceId && item.interfaceId === args.interfaceId);
+			if (listing === void 0) throw new Error(`Interface not found: ${args.serviceId}::${args.interfaceId}. Browse first, or set \`requestPermission: true\` if its directory is gated.`);
+			const document = await _loadDocument(channel, listing);
+			const format = args.format ?? "source";
+			return {
+				kind: "inspect",
+				format,
+				..._toListing(listing),
+				...format === "source" ? { source: document.source } : { schema: document.schema },
+				...inaccessible !== void 0 ? { inaccessible } : {}
+			};
+		}
+		default: throw new Error(`Unknown explore kind: ${String(args.kind)}`);
+	}
+}
+function _filterAndSort(listings, args) {
+	const includeInternal = args.includeInternal === true || args.interfaceId !== void 0 && _isHubrpcInternalInterface(args.interfaceId);
+	return listings.filter((listing) => {
+		if (args.serviceId !== void 0 && listing.serviceId !== args.serviceId) return false;
+		if (args.interfaceId !== void 0 && listing.interfaceId !== args.interfaceId) return false;
+		return includeInternal || !_isHubrpcInternalInterface(listing.interfaceId);
+	}).sort((a, b) => a.serviceId.localeCompare(b.serviceId) || a.interfaceId.localeCompare(b.interfaceId) || a.hash.localeCompare(b.hash));
+}
+function _toListing(listing) {
+	return {
+		serviceId: listing.serviceId,
+		...listing.serviceDescription !== void 0 ? { serviceDescription: listing.serviceDescription } : {},
+		interfaceId: listing.interfaceId,
+		interfaceHash: listing.hash,
+		documentId: _documentId(listing)
+	};
+}
+async function _loadDocument(channel, listing) {
+	let cache = interfaceCache.get(channel);
+	if (cache === void 0) {
+		cache = /* @__PURE__ */ new Map();
+		interfaceCache.set(channel, cache);
+	}
+	const cacheKey = `${listing.discoveredFrom}\u0000${listing.interfaceId}\u0000${listing.hash}`;
+	let pending = cache.get(cacheKey);
+	if (pending === void 0) {
+		pending = (async () => {
+			const target = listing.discoveredFrom || listing.serviceId || void 0;
+			const schema = await fetchSchema(channel, listing.interfaceId, listing.hash, target);
+			return {
+				schema,
+				generatedSource: generateTsInterface(schema)
+			};
+		})();
+		cache.set(cacheKey, pending);
+	}
+	let cached;
+	try {
+		cached = await pending;
+	} catch (error) {
+		if (cache.get(cacheKey) === pending) cache.delete(cacheKey);
+		throw error;
+	}
+	const documentId = _documentId(listing);
+	return {
+		...cached,
+		listing,
+		source: `${_documentHeader(listing, documentId)}\n${cached.generatedSource}`
+	};
+}
+function _documentHeader(listing, documentId) {
+	return [
+		`// virtualDocument: ${JSON.stringify(documentId)}`,
+		`// serviceId: ${JSON.stringify(listing.serviceId)}`,
+		...listing.serviceDescription !== void 0 ? [`// serviceDescription: ${JSON.stringify(listing.serviceDescription)}`] : [],
+		`// interfaceId: ${JSON.stringify(listing.interfaceId)}`,
+		`// interfaceHash: ${JSON.stringify(listing.hash)}`,
+		`// discoveredFrom: ${JSON.stringify(listing.discoveredFrom)}`
+	].join("\n");
+}
+function _documentId(listing) {
+	return `linkrpc://${listing.serviceId === "" ? "$root" : encodeURIComponent(listing.serviceId)}/${encodeURIComponent(listing.interfaceId)}@${listing.hash}.ts`;
+}
+function _grepDocument(document, matchesLine, contextLines) {
+	const lines = document.source.split("\n");
+	const memberAtLine = _memberMap(lines, document.schema);
+	const ranges = [];
+	for (let index = 0; index < lines.length; index++) {
+		if (!matchesLine(lines[index])) continue;
+		const start = Math.max(0, index - contextLines);
+		const end = Math.min(lines.length, index + contextLines + 1);
+		const previous = ranges.at(-1);
+		if (previous !== void 0 && start <= previous.end) {
+			previous.end = Math.max(previous.end, end);
+			previous.matches.push(index);
+		} else ranges.push({
+			start,
+			end,
+			matches: [index]
+		});
+	}
+	return ranges.map((range) => {
+		const members = new Set(range.matches.map((line) => memberAtLine[line]));
+		const member = members.size === 1 ? members.values().next().value : void 0;
+		return {
+			searchResult: lines.slice(range.start, range.end).join("\n"),
+			lineRange: [range.start + 1, range.end],
+			...member !== void 0 ? { member } : {}
+		};
+	});
+}
+function _memberMap(lines, schema) {
+	const starts = [];
+	let searchFrom = 0;
+	for (const methodName of Object.keys(schema.methods)) {
+		const barePrefix = `${methodName}: `;
+		const quotedPrefix = `${JSON.stringify(methodName)}: `;
+		const line = lines.findIndex((value, index) => index >= searchFrom && (value.trimStart().startsWith(barePrefix) || value.trimStart().startsWith(quotedPrefix)) && (value.includes("requestType(") || value.includes("notificationType(")));
+		if (line >= 0) {
+			starts.push({
+				line,
+				member: methodName
+			});
+			searchFrom = line + 1;
+		}
+	}
+	const result = new Array(lines.length);
+	for (let i = 0; i < starts.length; i++) {
+		const end = starts[i + 1]?.line ?? lines.length;
+		for (let line = starts[i].line; line < end; line++) result[line] = starts[i].member;
+	}
+	return result;
+}
+function _createLineMatcher(pattern, syntax) {
+	if (syntax === "literal") {
+		const needle = pattern.toLocaleLowerCase();
+		return (line) => line.toLocaleLowerCase().includes(needle);
+	}
+	if (syntax !== "regex") throw new Error(`Unknown grep syntax: ${String(syntax)}`);
+	let regex;
+	try {
+		regex = new RegExp(pattern, "iu");
+	} catch (error) {
+		throw new Error(`Invalid grep regular expression: ${error.message}`);
+	}
+	return (line) => regex.test(line);
+}
+function _page(items, requestedLimit, cursor) {
+	const limit = _boundedInteger(requestedLimit ?? DEFAULT_LIMIT, 1, MAX_LIMIT, "limit");
+	const offset = _decodeCursor(cursor);
+	const page = items.slice(offset, offset + limit);
+	const nextOffset = offset + page.length;
+	return {
+		items: page,
+		...nextOffset < items.length ? { nextCursor: String(nextOffset) } : {}
+	};
+}
+function _decodeCursor(cursor) {
+	if (cursor === void 0) return 0;
+	if (!/^\d+$/.test(cursor)) throw new Error("Invalid explore cursor.");
+	return Number(cursor);
+}
+function _boundedInteger(value, min, max, name) {
+	if (!Number.isInteger(value) || value < min || value > max) throw new Error(`explore ${name} must be an integer from ${min} to ${max}.`);
+	return value;
+}
+function _inaccessible(directories) {
+	if (directories.length === 0) return void 0;
+	return directories.map((directory) => ({
+		serviceId: directory.serviceId,
+		reason: directory.reason,
+		hint: "Repeat this explore call with `requestPermission: true` to search all gated directories."
+	}));
+}
+function _isHubrpcInternalInterface(interfaceId) {
+	return interfaceId.startsWith("hubrpc.");
+}
+//#endregion
+//#region src/resultPresentation.ts
+const MCP_PRESENTATION_TAG = "__linkrpcMcpPresentationV1";
+/**
+* Convert a JSON tool-result envelope into MCP-native content while preserving a
+* JSON text fallback for clients that only consume text.
+*/
+function presentToolResult(envelope, mode = "auto") {
+	if (mode === "raw") {
+		const rawEnvelope = stripPresentationTags(envelope);
+		const resultOptions = findExplicitResultOptions(envelope);
+		return {
+			content: [{
+				type: "text",
+				text: JSON.stringify(rawEnvelope, null, 2)
+			}],
+			structuredContent: rawEnvelope,
+			...resultOptions
+		};
+	}
+	const state = { content: [] };
+	const structuredContent = presentValue(envelope, "$", state);
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(structuredContent, null, 2)
+		}, ...state.content],
+		structuredContent,
+		...state.isError !== void 0 ? { isError: state.isError } : {},
+		...state.meta ? { _meta: state.meta } : {}
+	};
+}
+/** Remove presentation-only wrappers before persisting a script result. */
+function scriptResultValue(value) {
+	return stripPresentationTags(value);
+}
+function presentValue(value, path, state) {
+	const tag = getPresentationTag(value);
+	if (tag?.kind === "raw") return stripPresentationTags(tag.value);
+	if (tag?.kind === "result") {
+		if (tag.isError !== void 0) {
+			if (typeof tag.isError !== "boolean") throw new Error(`Invalid MCP result isError at ${path}: expected boolean`);
+			state.isError = tag.isError;
+		}
+		if (tag._meta !== void 0) {
+			if (!isRecord(tag._meta)) throw new Error(`Invalid MCP result _meta at ${path}: expected object`);
+			state.meta = tag._meta;
+		}
+		const presented = presentValue(Object.hasOwn(tag, "structuredContent") ? tag.structuredContent : Object.hasOwn(tag, "value") ? tag.value : null, path, state);
+		const content = Array.isArray(tag.content) ? tag.content : [];
+		for (let i = 0; i < content.length; i++) addExplicitContent(content[i], `${path}.content[${i}]`, state);
+		return presented;
+	}
+	if (tag?.kind === "content") {
+		const block = parseExplicitContent(tag.content, path);
+		state.content.push(block);
+		return describeContent(block, path);
+	}
+	const explicitContent = ContentBlockSchema.safeParse(value);
+	if (explicitContent.success) {
+		state.content.push(explicitContent.data);
+		return describeContentWithMetadata(explicitContent.data, contentBlockMetadata(value, explicitContent.data), path, state);
+	}
+	const automaticContent = detectAutomaticContent(value);
+	if (automaticContent) {
+		state.content.push(automaticContent.block);
+		return describeContentWithMetadata(automaticContent.block, automaticContent.metadata, path, state);
+	}
+	if (Array.isArray(value)) return value.map((item, index) => presentValue(item, `${path}[${index}]`, state));
+	if (isRecord(value)) {
+		const result = {};
+		for (const [key, item] of Object.entries(value)) result[key] = presentValue(item, `${path}.${key}`, state);
+		return result;
+	}
+	return value;
+}
+function addExplicitContent(value, path, state) {
+	const tag = getPresentationTag(value);
+	state.content.push(parseExplicitContent(tag?.kind === "content" ? tag.content : value, path));
+}
+function parseExplicitContent(value, path) {
+	const parsed = ContentBlockSchema.safeParse(value);
+	if (parsed.success) return parsed.data;
+	throw new Error(`Invalid MCP content block at ${path}: ${parsed.error.message}`);
+}
+function detectAutomaticContent(value) {
+	if (typeof value === "string") {
+		const dataUrl = parseDataUrl(value);
+		if (dataUrl) return { block: blockForBinary(dataUrl.data, dataUrl.mimeType) };
+		const base64 = normalizeBase64(value);
+		if (!base64) return;
+		const mimeType = sniffMimeType(base64);
+		return mimeType ? { block: blockForBinary(base64, mimeType) } : void 0;
+	}
+	if (!isRecord(value) || typeof value.mimeType !== "string") return;
+	if (typeof value.text === "string") return {
+		block: {
+			type: "resource",
+			resource: {
+				uri: typeof value.uri === "string" ? value.uri : contentUrn(value.mimeType, value.text),
+				mimeType: value.mimeType,
+				text: value.text
+			}
+		},
+		metadata: contentMetadata(value)
+	};
+	const encoded = [
+		value.data,
+		value.base64,
+		value.blob
+	].find((candidate) => typeof candidate === "string");
+	if (!encoded) return;
+	const dataUrl = parseDataUrl(encoded);
+	const data = dataUrl?.data ?? normalizeBase64(encoded);
+	if (!data) return;
+	return {
+		block: blockForBinary(data, dataUrl?.mimeType ?? value.mimeType, typeof value.uri === "string" ? value.uri : void 0),
+		metadata: contentMetadata(value)
+	};
+}
+function blockForBinary(data, mimeType, uri) {
+	if (mimeType.startsWith("image/")) return {
+		type: "image",
+		data,
+		mimeType
+	};
+	if (mimeType.startsWith("audio/")) return {
+		type: "audio",
+		data,
+		mimeType
+	};
+	return {
+		type: "resource",
+		resource: {
+			uri: uri ?? contentUrn(mimeType, data),
+			mimeType,
+			blob: data
+		}
+	};
+}
+function describeContent(content, path) {
+	switch (content.type) {
+		case "text": return content.text;
+		case "image":
+		case "audio": return { $content: {
+			type: content.type,
+			mimeType: content.mimeType,
+			bytes: base64ByteLength(content.data),
+			path
+		} };
+		case "resource_link": return { $content: {
+			type: content.type,
+			uri: content.uri,
+			name: content.name,
+			...content.mimeType ? { mimeType: content.mimeType } : {},
+			...content.size !== void 0 ? { size: content.size } : {},
+			path
+		} };
+		case "resource": {
+			const resource = content.resource;
+			return { $content: {
+				type: content.type,
+				uri: resource.uri,
+				...resource.mimeType ? { mimeType: resource.mimeType } : {},
+				..."blob" in resource ? { bytes: base64ByteLength(resource.blob) } : { characters: resource.text.length },
+				path
+			} };
+		}
+	}
+}
+function describeContentWithMetadata(content, metadata, path, state) {
+	const description = describeContent(content, path);
+	if (!metadata || Object.keys(metadata).length === 0) return description;
+	const presentedMetadata = presentValue(metadata, path, state);
+	if (isRecord(description)) return {
+		...presentedMetadata,
+		...description
+	};
+	return {
+		...presentedMetadata,
+		$content: {
+			type: content.type,
+			characters: typeof description === "string" ? description.length : void 0,
+			path
+		}
+	};
+}
+function stripPresentationTags(value) {
+	const tag = getPresentationTag(value);
+	if (tag?.kind === "raw") return stripPresentationTags(tag.value);
+	if (tag?.kind === "result") {
+		if (Object.hasOwn(tag, "value")) return stripPresentationTags(tag.value);
+		if (Object.hasOwn(tag, "structuredContent")) return stripPresentationTags(tag.structuredContent);
+		return null;
+	}
+	if (tag?.kind === "content") return stripPresentationTags(tag.content);
+	if (Array.isArray(value)) return value.map(stripPresentationTags);
+	if (isRecord(value)) {
+		const result = {};
+		for (const [key, item] of Object.entries(value)) result[key] = stripPresentationTags(item);
+		return result;
+	}
+	return value;
+}
+function findExplicitResultOptions(value) {
+	const tag = getPresentationTag(value);
+	if (tag?.kind === "raw") return {};
+	if (tag?.kind === "result") return {
+		...typeof tag.isError === "boolean" ? { isError: tag.isError } : {},
+		...isRecord(tag._meta) ? { _meta: tag._meta } : {}
+	};
+	if (Array.isArray(value)) for (const item of value) {
+		const options = findExplicitResultOptions(item);
+		if (options.isError !== void 0 || options._meta !== void 0) return options;
+	}
+	else if (isRecord(value)) for (const item of Object.values(value)) {
+		const options = findExplicitResultOptions(item);
+		if (options.isError !== void 0 || options._meta !== void 0) return options;
+	}
+	return {};
+}
+function getPresentationTag(value) {
+	if (!isRecord(value) || Object.keys(value).length !== 1) return;
+	const candidate = value[MCP_PRESENTATION_TAG];
+	if (!isRecord(candidate) || candidate.kind !== "raw" && candidate.kind !== "result" && candidate.kind !== "content") return;
+	return candidate;
+}
+function parseDataUrl(value) {
+	if (!value.startsWith("data:")) return;
+	const comma = value.indexOf(",");
+	if (comma < 5) return;
+	const parts = value.slice(5, comma).split(";");
+	const mimeType = parts[0] || "text/plain";
+	const payload = value.slice(comma + 1);
+	if (parts.includes("base64")) {
+		const data = normalizeBase64(payload);
+		return data ? {
+			data,
+			mimeType
+		} : void 0;
+	}
+	try {
+		return {
+			data: Buffer.from(decodeURIComponent(payload), "utf8").toString("base64"),
+			mimeType
+		};
+	} catch {
+		return;
+	}
+}
+function normalizeBase64(value) {
+	const compact = value.replace(/\s/g, "");
+	if (compact.length < 8 || compact.length % 4 === 1 || !/^[A-Za-z0-9+/]*={0,2}$/.test(compact)) return;
+	const withoutPadding = compact.replace(/=+$/, "");
+	const padding = (4 - withoutPadding.length % 4) % 4;
+	return withoutPadding + "=".repeat(padding);
+}
+function sniffMimeType(base64) {
+	const bytes = Buffer.from(base64.slice(0, 256), "base64");
+	const ascii = bytes.toString("ascii");
+	if (startsWith(bytes, [
+		137,
+		80,
+		78,
+		71,
+		13,
+		10,
+		26,
+		10
+	])) return "image/png";
+	if (startsWith(bytes, [
+		255,
+		216,
+		255
+	])) return "image/jpeg";
+	if (ascii.startsWith("GIF87a") || ascii.startsWith("GIF89a")) return "image/gif";
+	if (ascii.startsWith("RIFF") && ascii.slice(8, 12) === "WEBP") return "image/webp";
+	if (ascii.startsWith("BM")) return "image/bmp";
+	if (startsWith(bytes, [
+		0,
+		0,
+		1,
+		0
+	])) return "image/x-icon";
+	if (startsWith(bytes, [
+		73,
+		73,
+		42,
+		0
+	]) || startsWith(bytes, [
+		77,
+		77,
+		0,
+		42
+	])) return "image/tiff";
+	if (/^\s*(?:<\?xml[^>]*>\s*)?<svg[\s>]/i.test(bytes.toString("utf8"))) return "image/svg+xml";
+	if (ascii.startsWith("RIFF") && ascii.slice(8, 12) === "WAVE") return "audio/wav";
+	if (ascii.startsWith("ID3") || startsWith(bytes, [255, 251]) || startsWith(bytes, [255, 243]) || startsWith(bytes, [255, 242])) return "audio/mpeg";
+	if (ascii.startsWith("OggS")) return "audio/ogg";
+	if (ascii.startsWith("fLaC")) return "audio/flac";
+	if (startsWith(bytes, [255, 241]) || startsWith(bytes, [255, 249])) return "audio/aac";
+	if (ascii.startsWith("MThd")) return "audio/midi";
+	if (ascii.startsWith("%PDF-")) return "application/pdf";
+	if (startsWith(bytes, [
+		80,
+		75,
+		3,
+		4
+	])) return "application/zip";
+	if (startsWith(bytes, [31, 139])) return "application/gzip";
+}
+function startsWith(value, prefix) {
+	return prefix.every((byte, index) => value[index] === byte);
+}
+function base64ByteLength(value) {
+	const normalized = normalizeBase64(value);
+	if (!normalized) return 0;
+	const padding = normalized.endsWith("==") ? 2 : normalized.endsWith("=") ? 1 : 0;
+	return normalized.length / 4 * 3 - padding;
+}
+function contentUrn(mimeType, value) {
+	return `urn:linkrpc-mcp:content:${createHash("sha256").update(mimeType).update("\0").update(value).digest("base64url")}`;
+}
+function contentMetadata(value) {
+	const metadata = {};
+	for (const [key, item] of Object.entries(value)) if (![
+		"data",
+		"base64",
+		"blob",
+		"text",
+		"mimeType",
+		"uri"
+	].includes(key)) metadata[key] = item;
+	return metadata;
+}
+function contentBlockMetadata(value, content) {
+	const standardKeys = content.type === "text" ? [
+		"type",
+		"text",
+		"annotations",
+		"_meta"
+	] : content.type === "image" || content.type === "audio" ? [
+		"type",
+		"data",
+		"mimeType",
+		"annotations",
+		"_meta"
+	] : content.type === "resource" ? [
+		"type",
+		"resource",
+		"annotations",
+		"_meta"
+	] : [
+		"type",
+		"uri",
+		"name",
+		"title",
+		"description",
+		"mimeType",
+		"size",
+		"annotations",
+		"_meta",
+		"icons"
+	];
+	const metadata = {};
+	for (const [key, item] of Object.entries(value)) if (!standardKeys.includes(key)) metadata[key] = item;
+	return metadata;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/server.ts
+const CONNECTION_SCHEMA = z.string().optional().describe("Endpoint URI of the hub to connect to, e.g. `unix:/run/hub.sock?token=…`, `npipe://./pipe/vscode-linkrpc-…?token=…`, or `wss://host:port?token=…`. The token may be embedded as a `token` query param or supplied via the LINKRPC_TOKEN environment variable. When omitted entirely, the server falls back to the LINKRPC_ENDPOINT and LINKRPC_TOKEN environment variables.");
+const PRESENTATION_SCHEMA = z.enum(["auto", "raw"]).optional().describe("How to present the returned value. `auto` (default) recognizes MCP content blocks, data URLs, common base64 media signatures, and `{ data|base64|blob, mimeType }` objects, emitting native image/audio/resource content while keeping the original value available to subsequent scripts through `lastResultVal`. `raw` disables transformation and exposes the original JSON/base64.");
+const SERVER_NAME = "linkrpc-mcp";
+const SERVER_VERSION = "0.0.1";
+/**
+* MCP server exposing the `runLinkRpcScript` tool plus task-management helpers.
+*
+* Documentation for the sandbox API (`con`) is reachable from inside the
+* sandbox via `con.getDocs()` rather than an MCP resource — that way the
+* model can pull it in by issuing a one-line `runLinkRpcScript` call.
+*
+* Can be hosted over stdio (CLI mode, via {@link startStdio}) or over any
+* MCP {@link Transport} (e.g. Streamable HTTP, used by the VS Code Team
+* Tools extension which embeds this server in-process).
+*/
+var LinkRpcMcpServer = class LinkRpcMcpServer {
+	static async startStdio(options) {
+		const server = new LinkRpcMcpServer(options);
+		await server.connect(new StdioServerTransport());
+		return server;
+	}
+	_mcp;
+	_pool;
+	_tasks = new TaskRegistry();
+	_onToolCall;
+	_onExploreCall;
+	constructor(options = {}) {
+		this._mcp = new McpServer({
+			name: SERVER_NAME,
+			version: SERVER_VERSION
+		});
+		this._onToolCall = options.onToolCall;
+		this._onExploreCall = options.onExploreCall;
+		this._pool = options.pool ?? (options.provider ? new ProviderPool(options.provider) : new ConnectionPool({
+			defaultEndpoint: options.defaultEndpoint,
+			...options.defaultConnection ? { defaultTransport: options.defaultConnection } : {}
+		}));
+		this._registerTools();
+	}
+	async connect(transport) {
+		await this._mcp.connect(transport);
+	}
+	dispose() {
+		this._tasks.dispose();
+		this._pool.dispose();
+	}
+	_registerTools() {
+		this._mcp.registerTool("runLinkRpcScript", {
+			title: "Run JS against a linkrpc hub",
+			description: "Evaluate a JS function inside a QuickJS sandbox with `con` (the live hub connection), `lastResultVal` (previous call's original result), and `mcp` (optional result-presentation helpers) in scope.\n\nBefore composing non-trivial calls, fetch the full sandbox API docs by running:\n  `async ({ con }) => con.getDocs()`\nThat returns the TypeScript declarations for the full script context, including `con`, `mcp`, sandbox limits, and available console.\n\n`code` MUST be a function expression, e.g.\n  `({ con }) => con.call(\"vscode\", \"vscode.window\", \"showInformationMessage\", { message: \"hi\" })`\n\nSet `connection` to a hub endpoint URI (e.g. `unix:/path?token=…` or `wss://host?token=…`) to target a specific hub, or leave it out to use the LINKRPC_ENDPOINT / LINKRPC_TOKEN env vars.\n\nACCESS IS NOT AUTOMATIC: a gated `con.call(...)` is NOT silently granted. Reflection (`con.explore`) works out of the box, but calling a service member you have no capability for fails with a permission error. Inspect what you already hold with `con.grants()`, then ask the user for access — ideally for MANY members at once — with `con.requestAccess({ permissions, duration })`. Pick `duration`: `once` for a one-off, `session` for the rest of this connection, `persistent` to remember across runs. Batch related permissions into a single request so the user sees one prompt instead of many.\n\nBACKGROUND TASKS: if the code is still awaiting I/O (an RPC reply, a user dialog, a stream) when `foregroundMs` elapses, the call does NOT fail — it is parked as a background task and the result is `{ status: \"running\", taskId, debugName, inFlight }`. Use `awaitLinkRpcTask` to wait for it or `cancelLinkRpcTask` to abandon it. Set `label` to give the task a clear debug name. Starting a new `runLinkRpcScript` cancels any task still parked (reported as `supersededTask`).\n\nRESULT PRESENTATION: returned image/audio/resource data is automatically emitted as native MCP content when it is a data URL, recognizable base64, an MCP content block, or an object shaped like `{ data|base64|blob, mimeType }`. This happens only after the script finishes: values passed between hub calls and saved in `lastResultVal` remain original and unmodified. Use `presentation: \"raw\"` or `mcp.raw(value)` when the model needs the literal base64. Use `mcp.image`, `mcp.audio`, `mcp.resource`, `mcp.resourceLink`, or `mcp.result` for explicit control. Native content always includes JSON text and structured fallbacks.\n\nThe result contains `{ status, result | taskId, logs, endpoint }`. Pass `trace: true` to also receive a per-call JSON-RPC wire log under `trace` — useful when a call fails or returns unexpected data.",
+			inputSchema: {
+				connection: CONNECTION_SCHEMA,
+				code: z.string().describe("JS function expression. Receives `{ con, lastResultVal, mcp }`. Sync or async. Return value is JSON-stringified."),
+				presentation: PRESENTATION_SCHEMA,
+				label: z.string().optional().describe("Human-readable debug name for the task if it gets parked, e.g. \"ask user to confirm deploy\". When omitted, the name is inferred from the in-flight RPC(s) at park time."),
+				foregroundMs: z.number().int().positive().optional().describe("How long the call runs synchronously before being parked as a background task. Defaults to 5000."),
+				maxLifetimeMs: z.number().int().positive().optional().describe("Absolute lifetime cap for a parked task before it is cancelled. Defaults to 120000."),
+				trace: z.boolean().optional().describe("When true, include a `trace` array in the result with every outbound JSON-RPC request / notification, its outcome, and every permission round-trip. Off by default to keep results small.")
+			},
+			annotations: { readOnlyHint: true }
+		}, async (args) => this._observeToolCall("runLinkRpcScript", args, async () => {
+			let pooled;
+			try {
+				pooled = await this._pool.resolve(args.connection);
+			} catch (e) {
+				return _errorResult(_describeError(e));
+			}
+			const superseded = await this._tasks.cancelLive();
+			const traceEnabled = args.trace === true;
+			const trace = [];
+			const disposeTrace = traceEnabled ? pooled.addTraceListener((line) => trace.push(line)) : () => {};
+			const host = {
+				call: async (method, paramsJson, optsJson, onStreamMessage, signal) => {
+					const params = paramsJson === "" ? {} : JSON.parse(paramsJson);
+					const requestPermission = (optsJson === "" ? {} : JSON.parse(optsJson)).requestPermission === true;
+					const send = async () => {
+						if (signal.aborted) {
+							const error = /* @__PURE__ */ new Error(`AbortError: ${String(signal.reason ?? "cancelled")}`);
+							error.name = "AbortError";
+							throw error;
+						}
+						const call = pooled.channel.sendRequestWithStream(method, params, { onStreamMessage: (payload) => onStreamMessage(JSON.stringify(payload)) });
+						const cancel = () => {
+							const reason = String(signal.reason ?? "cancelled");
+							call.cancel(reason);
+							call.dispose?.(reason);
+						};
+						signal.addEventListener("abort", cancel, { once: true });
+						try {
+							return await call.result;
+						} finally {
+							signal.removeEventListener("abort", cancel);
+						}
+					};
+					try {
+						const result = await send();
+						return JSON.stringify(result ?? null);
+					} catch (e) {
+						if (requestPermission && _isPermissionError(e)) {
+							if (await _autoRequestAccess(pooled.session, method)) {
+								const result = await send();
+								return JSON.stringify(result ?? null);
+							}
+						}
+						throw _enrichPermissionError(e, method);
+					}
+				},
+				notify: async (method, paramsJson) => {
+					const params = paramsJson === "" ? {} : JSON.parse(paramsJson);
+					await pooled.channel.sendNotification(method, params);
+					return "";
+				},
+				explore: async (argsJson) => {
+					const exploreArgs = argsJson === "" ? {} : JSON.parse(argsJson);
+					let reflectionGrant;
+					try {
+						const result = await explore(pooled.channel, exploreArgs, { requestReflectionAccess: () => reflectionGrant ??= _requestReflectionAccess(pooled.session) });
+						this._observeExploreCall({
+							arguments: exploreArgs,
+							result
+						});
+						return JSON.stringify(result);
+					} catch (error) {
+						this._observeExploreCall({
+							arguments: exploreArgs,
+							error: error instanceof Error ? error.message : String(error)
+						});
+						throw error;
+					}
+				},
+				requestAccess: async (argsJson) => {
+					const req = argsJson === "" ? {} : JSON.parse(argsJson);
+					const result = await pooled.session.requestAccess({
+						consumer: {
+							name: "linkrpc-mcp",
+							purpose: req.purpose
+						},
+						permissions: req.permissions ?? [],
+						duration: req.duration
+					});
+					return JSON.stringify(result);
+				},
+				grants: async () => JSON.stringify(summarizeGrants(pooled.session.listGrants()))
+			};
+			try {
+				const outcome = await startSandbox(args.code, host, pooled.lastResultVal, {
+					foregroundMs: args.foregroundMs,
+					maxLifetimeMs: args.maxLifetimeMs,
+					label: args.label
+				});
+				if (outcome.status === "completed") {
+					pooled.lastResultVal = scriptResultValue(outcome.result);
+					return presentToolResult({
+						status: "completed",
+						result: outcome.result,
+						logs: outcome.logs,
+						...traceEnabled ? { trace } : {},
+						endpoint: pooled.endpoint,
+						...superseded ? { supersededTask: superseded } : {}
+					}, args.presentation);
+				}
+				if (outcome.status === "error") return _errorResult(`runLinkRpcScript failed: ${outcome.error}`, traceEnabled ? trace : void 0);
+				return presentToolResult({
+					status: "running",
+					taskId: this._tasks.register(pooled.endpoint, outcome.debugName, outcome.task, (result) => {
+						pooled.lastResultVal = scriptResultValue(result);
+					}),
+					debugName: outcome.debugName,
+					inFlight: outcome.task.inFlight(),
+					logsSoFar: outcome.task.logs,
+					...traceEnabled ? { traceSoFar: trace } : {},
+					endpoint: pooled.endpoint,
+					...superseded ? { supersededTask: superseded } : {}
+				}, "raw");
+			} catch (e) {
+				return _errorResult(`runLinkRpcScript failed: ${_describeError(e)}`, traceEnabled ? trace : void 0);
+			} finally {
+				disposeTrace();
+			}
+		}));
+		this._mcp.registerTool("awaitLinkRpcTask", {
+			title: "Wait for a parked linkrpc task",
+			description: "Wait up to `timeoutMs` for a background task started by `runLinkRpcScript` to settle. Returns `{ status: \"completed\" | \"error\" | \"cancelled\" | \"running\", … }`. A `running` result means it is still going (with a progress snapshot) — call again to keep waiting. Does NOT cancel the task.",
+			inputSchema: {
+				taskId: z.string().describe("Task id returned by `runLinkRpcScript`."),
+				timeoutMs: z.number().int().positive().optional().describe("How long to wait before returning a `running` snapshot. Defaults to 30000."),
+				presentation: PRESENTATION_SCHEMA
+			},
+			annotations: { readOnlyHint: true }
+		}, async (args) => this._observeToolCall("awaitLinkRpcTask", args, async () => {
+			const res = await this._tasks.awaitTask(args.taskId, args.timeoutMs ?? 3e4);
+			if (res.status === "unknown") return _errorResult(`No task with id ${args.taskId}`);
+			return _presentTaskResult(res, args.presentation);
+		}));
+		this._mcp.registerTool("cancelLinkRpcTask", {
+			title: "Cancel a parked linkrpc task",
+			description: "Soft-abort a background task started by `runLinkRpcScript` and return its terminal outcome. The guest gets a short grace window to run cleanup.",
+			inputSchema: {
+				taskId: z.string().describe("Task id returned by `runLinkRpcScript`."),
+				presentation: PRESENTATION_SCHEMA
+			},
+			annotations: { readOnlyHint: true }
+		}, async (args) => this._observeToolCall("cancelLinkRpcTask", args, async () => {
+			const res = await this._tasks.cancel(args.taskId);
+			if (res.status === "unknown") return _errorResult(`No task with id ${args.taskId}`);
+			return _presentTaskResult(res, args.presentation);
+		}));
+	}
+	async _observeToolCall(name, args, invoke) {
+		const result = await invoke();
+		try {
+			this._onToolCall?.({
+				name,
+				arguments: args,
+				result
+			});
+		} catch {}
+		return result;
+	}
+	_observeExploreCall(call) {
+		try {
+			this._onExploreCall?.(call);
+		} catch {}
+	}
+};
+function _presentTaskResult(value, mode) {
+	try {
+		return presentToolResult(value, mode);
+	} catch (e) {
+		return _errorResult(`Failed to present task result: ${_describeError(e)}`);
+	}
+}
+function _errorResult(message, trace) {
+	return {
+		content: [{
+			type: "text",
+			text: trace && trace.length > 0 ? `${message}\n\nTrace:\n${trace.join("\n")}` : message
+		}],
+		isError: true
+	};
+}
+/**
+* Render an unknown thrown value as a debuggable string: the error's stack
+* (which already begins with `Name: message`) plus the full `cause` chain. The
+* MCP host only forwards the result text to the model — never a JS stack — so
+* without this every failure collapses to a single bare message line.
+*/
+function _describeError(e) {
+	if (!(e instanceof Error)) return String(e);
+	let out = typeof e.stack === "string" && e.stack.length > 0 ? e.stack : e.message;
+	let cause = e.cause;
+	while (cause != null) if (cause instanceof Error) {
+		out += `\n\nCaused by: ${typeof cause.stack === "string" && cause.stack.length > 0 ? cause.stack : cause.message}`;
+		cause = cause.cause;
+	} else {
+		out += `\n\nCaused by: ${String(cause)}`;
+		break;
+	}
+	return out;
+}
+/**
+* Map a hub `permissionRequired` (-32401) error to an actionable message that
+* points the model at the explicit access flow. Other errors pass through
+* unchanged (re-wrapped as an `Error` when they are not already one).
+*/
+function _enrichPermissionError(e, method) {
+	if (_isPermissionError(e)) {
+		const { serviceId, interfaceId, member } = _parseMethod(method);
+		const original = e instanceof Error ? e.message : String(e);
+		return /* @__PURE__ */ new Error(`Permission required for ${method} — no capability is held for this call.\nInspect current access with con.grants(), then request it with con.requestAccess({ permissions: [{ target: { serviceId: { exact: ${JSON.stringify(serviceId)} }, interfaceId: { exact: ${JSON.stringify(interfaceId)} }, members: [{ exact: ${JSON.stringify(member)} }] }, canInvoke: true }], duration: "longLived" }).\nOriginal error: ${original}`);
+	}
+	return e instanceof Error ? e : new Error(String(e));
+}
+/** True when `e` is a hub `permissionRequired` (-32401) error. */
+function _isPermissionError(e) {
+	return e instanceof RpcError ? e.code === ErrorCode.permissionRequired : typeof e === "object" && e !== null && e.code === ErrorCode.permissionRequired;
+}
+/**
+* Split a JSON-RPC method name into its `(serviceId, interfaceId, member)`
+* parts. Form-3 (`serviceId::interfaceId::member`) keeps the serviceId; form-2
+* (`interfaceId::member`, a root/hub call) reports an empty serviceId.
+*/
+function _parseMethod(method) {
+	const parts = method.split("::");
+	if (parts.length >= 3) return {
+		serviceId: parts[0],
+		interfaceId: parts[1],
+		member: parts.slice(2).join("::")
+	};
+	return {
+		serviceId: "",
+		interfaceId: parts[0] ?? "",
+		member: parts[1] ?? ""
+	};
+}
+/**
+* Negotiate durable capabilities for the reflection methods the bus walk uses
+* — `hubrpc.directory::list` (enumeration) and `hubrpc.schemas::get` (schema
+* fetch) — across *all* service ids, through the hub's `hubAccess` consent
+* door. One grant unlocks enumeration of every gated directory the walk
+* reaches, so `explore({ requestPermission: true })` only needs a single
+* consent round-trip. Returns `true` when the grant was issued.
+*/
+async function _requestReflectionAccess(session) {
+	return (await session.requestAccess({
+		consumer: {
+			name: "linkrpc-mcp",
+			purpose: "explore the hub (reflection)"
+		},
+		permissions: [{
+			target: {
+				serviceId: { prefix: "" },
+				interfaceId: { exact: "hubrpc.directory" },
+				members: [{ exact: "list" }]
+			},
+			canInvoke: true
+		}, {
+			target: {
+				serviceId: { prefix: "" },
+				interfaceId: { exact: "hubrpc.schemas" },
+				members: [{ exact: "get" }]
+			},
+			canInvoke: true
+		}],
+		duration: "longLived"
+	})).status === "granted";
+}
+/**
+* Negotiate a durable capability for exactly `method` through the hub's
+* `hubAccess` consent door (the `requestPermission: true` path of `con.call`).
+* Returns `true` when the grant was issued — its durable cap joins the
+* connection's bag, so the caller can retry the call.
+*/
+async function _autoRequestAccess(session, method) {
+	const { serviceId, interfaceId, member } = _parseMethod(method);
+	return (await session.requestAccess({
+		consumer: {
+			name: "linkrpc-mcp",
+			purpose: `invoke ${method}`
+		},
+		permissions: [{
+			target: {
+				serviceId: { exact: serviceId },
+				interfaceId: { exact: interfaceId },
+				members: [{ exact: member }]
+			},
+			canInvoke: true
+		}],
+		duration: "longLived"
+	})).status === "granted";
+}
+//#endregion
+export { CONNECTION_DTS as a, startSandbox as i, explore as n, ProviderPool as o, runSandboxed as r, ConnectionPool as s, LinkRpcMcpServer as t };
+
+//# sourceMappingURL=server-C4ZM6bfK.js.map