@workerdeck/core 0.12.0 → 0.15.0

package/build/index.mjs

@@ -410,6 +410,8 @@ var SessionRunner = class {
 	id;
 	createdAt;
 	#config;
+	/** {@link SessionRunnerConfig.cwd}, checked once in the constructor. */
+	#cwd;
 	#events = [];
 	#listeners = /* @__PURE__ */ new Set();
 	#seq = 0;
@@ -434,6 +436,8 @@ var SessionRunner = class {
 	#closed = false;
 	#runPromise;
 	constructor(config, id = randomUUID()) {
+		if (!config.cwd) throw new Error("the claude engine requires a cwd");
+		this.#cwd = config.cwd;
 		this.#config = config;
 		this.#permissionMode = config.permissionMode;
 		this.id = id;
@@ -460,7 +464,7 @@ var SessionRunner = class {
 			id: this.id,
 			sdkSessionId: this.#sdkSessionId,
 			status: this.#status,
-			cwd: this.#config.cwd,
+			cwd: this.#cwd,
 			profile: this.#config.profile,
 			engine: "claude",
 			capabilities: ENGINE_CAPABILITIES.claude,
@@ -473,6 +477,7 @@ var SessionRunner = class {
 			activityCount: this.#activityCount,
 			pendingPermissionCount: this.#pending.size,
 			meta: this.#config.meta,
+			scope: this.#config.scope,
 			title: this.#title(),
 			totalCostUsd: this.#totalCostUsd,
 			numTurns: this.#numTurns,
@@ -665,7 +670,7 @@ var SessionRunner = class {
 		const historyFn = c.historyFn ?? ((sessionId, options) => getSessionMessages(sessionId, options));
 		let messages;
 		try {
-			messages = await historyFn(c.resume, { dir: c.cwd });
+			messages = await historyFn(c.resume, { dir: this.#cwd });
 		} catch {
 			return;
 		}
@@ -690,7 +695,7 @@ var SessionRunner = class {
 	#buildOptions() {
 		const c = this.#config;
 		return {
-			cwd: c.cwd,
+			cwd: this.#cwd,
 			permissionMode: c.permissionMode,
 			allowedTools: c.allowedTools,
 			disallowedTools: c.disallowedTools,
@@ -1099,7 +1104,7 @@ var AiSdkRunner = class {
 		return {
 			id: this.id,
 			status: this.#status,
-			cwd: this.#config.cwd ?? process.cwd(),
+			cwd: this.#config.cwd ?? "",
 			profile: this.#config.profile,
 			engine: "provider",
 			capabilities: ENGINE_CAPABILITIES.provider,
@@ -1110,6 +1115,7 @@ var AiSdkRunner = class {
 			activityCount: this.#activityCount,
 			pendingPermissionCount: 0,
 			meta: this.#config.meta,
+			scope: this.#config.scope,
 			title: this.#title(),
 			numTurns: this.#numTurns || void 0,
 			lastActivityAt: this.#lastActivityAt
@@ -1694,6 +1700,17 @@ var AiSdkRunner = class {
 		if (!prompt) return void 0;
 		return prompt.length > 80 ? prompt.slice(0, 77) + "…" : prompt;
 	}
+	/**
+	* This session's MCP servers, as the host assembled them.
+	*
+	* Always answers — an empty list when no MCP was wired — because the
+	* alternative (undefined, which the server turns into a 501) says "this
+	* engine cannot tell you", and this engine can: the host that built the
+	* session is the only party who knows, and it has been asked.
+	*/
+	async mcpServers() {
+		return await this.#config.reportMcpServers?.() ?? [];
+	}
 	/** Host-facing rename: writes `meta.title`, which `#title()` prefers. Clearing
 	* it (undefined) restores the derived title. The engine is never told. */
 	setTitle(title) {
@@ -2327,21 +2344,50 @@ function createToolContext(options) {
 /** Add host-side MCP tools to a context. They are ALWAYS authoritative: they run
 * server-side with server credentials, and must never be handed to a browser. */
 function withMcpTools(context, mcpTools) {
+	return withHostTools(context, Object.fromEntries(Object.entries(mcpTools).map(([name, mcpTool]) => [name, {
+		tool: mcpTool,
+		trust: "authoritative"
+	}])), "MCP tool");
+}
+/**
+* Add host-supplied tools to a context at an explicit trust level.
+*
+* The trust level is the whole point of the seam: {@link withMcpTools} can only
+* produce authoritative tools, so a host tool that *should* be sandboxed — and
+* therefore executable in the browser tab that asked for it — had no way to be
+* expressed at all. Here the host says which it is, and the contradictions are
+* refused rather than silently resolved:
+*
+* - a `sandboxed` tool carrying `execute` would run inline in this process with
+*   the gateway's ambient authority, which is exactly what sandboxing it was
+*   meant to prevent;
+* - an `authoritative` tool *without* `execute` would park the turn on a call no
+*   executor claims, and the session would simply stop.
+*/
+function withHostTools(context, hostTools, kind = "host tool") {
+	const entries = Object.entries(hostTools);
+	if (entries.length === 0) return context;
 	const definitions = [...context.definitions];
 	const tools = { ...context.tools };
-	for (const [name, mcpTool] of Object.entries(mcpTools)) {
-		if (context.sandboxedToolNames.includes(name)) throw new Error(`MCP tool '${name}' collides with a sandboxed tool of the same name`);
+	const sandboxedToolNames = [...context.sandboxedToolNames];
+	for (const [name, { tool: hostTool, trust }] of entries) {
+		if (name in tools) throw new Error(`${kind} '${name}' collides with an existing tool of the same name`);
+		const executes = typeof hostTool.execute === "function";
+		if (trust === "sandboxed" && executes) throw new Error(`${kind} '${name}' is declared sandboxed but has an \`execute\` — it would run in this process with full authority. Drop \`execute\` so it rides the ToolExecutor seam.`);
+		if (trust === "authoritative" && !executes) throw new Error(`${kind} '${name}' is declared authoritative but has no \`execute\` — nothing would ever answer its calls and the turn would stall.`);
 		definitions.push({
 			name,
-			trust: "authoritative",
-			tool: mcpTool
+			trust,
+			tool: hostTool
 		});
-		tools[name] = mcpTool;
+		tools[name] = hostTool;
+		if (trust === "sandboxed") sandboxedToolNames.push(name);
 	}
 	return {
 		...context,
 		tools,
-		definitions
+		definitions,
+		sandboxedToolNames
 	};
 }
 function truncate(text) {
@@ -2581,7 +2627,7 @@ const CAPABILITY_TOOLS = {
 * the host wired, which is what a host that ignores profiles gets.
 */
 function createEngineSession(options) {
-	const vfs = options.config.vfs ?? createVfs(options.config.restore?.vfs);
+	const vfs = options.config.vfs ?? createVfs(options.config.restore ? options.config.restore.vfs : options.seedVfs);
 	const executor = options.selectExecutor();
 	const granted = options.config.capabilities ?? options.profile?.session?.capabilities;
 	const isGranted = (key) => granted === void 0 || granted.includes(CAPABILITY_TOOLS[key]);
@@ -2602,8 +2648,12 @@ function createEngineSession(options) {
 		webFetch,
 		onFileDelivered: options.capabilities?.deliverFiles === false || !isGranted("deliverFiles") ? void 0 : (file) => runner?.emitFileDelivered(file)
 	});
-	const mcpTools = selectMcpTools(options.mcpTools, options.profile?.session?.mcpServers);
-	const context = mcpTools ? withMcpTools(base, mcpTools) : base;
+	const declaredServers = options.profile?.session?.mcpServers;
+	const connected = options.mcp?.tools ?? options.mcpTools;
+	requireDeclaredServers(options.profile?.name ?? "(unnamed)", declaredServers, options.mcp, connected);
+	const mcpTools = selectMcpTools(connected, declaredServers);
+	const withMcp = mcpTools ? withMcpTools(base, mcpTools) : base;
+	const context = options.tools ? withHostTools(withMcp, options.tools) : withMcp;
 	runner = new AiSdkRunner({
 		...options.config,
 		languageModel: options.resolveModel(options.profile, options.config),
@@ -2613,11 +2663,42 @@ function createEngineSession(options) {
 		executor,
 		executableTools: context.sandboxedToolNames,
 		executionBackend: options.backend ?? "server",
-		executionLimits: options.executionLimits
-	});
+		executionLimits: options.executionLimits,
+		reportMcpServers: options.mcp ? () => Promise.resolve(declaredServers === void 0 ? options.mcp.servers : options.mcp.servers.filter((s) => declaredServers.includes(s.name))) : void 0
+	}, options.id);
 	return runner;
 }
 /**
+* Refuse to build a session whose profile names an MCP server that isn't there.
+*
+* A profile's `mcpServers` list is a **declaration**, not a filter: an embedder
+* who wrote it meant the agent to have those tools. Honouring it partially is
+* the worst failure mode this engine has — the session starts, reports healthy,
+* and the agent apologises its way through every request that needed the server,
+* with one warning line in a log nobody is reading.
+*
+* With a {@link McpConnection} the check is exact (did this server connect?).
+* With a bare tool set all we can see is whether any tool carries the server's
+* namespace, so a genuinely tool-less server would trip it — the fix there is to
+* pass `mcp` rather than to weaken this.
+*/
+function requireDeclaredServers(profileName, declared, mcp, tools) {
+	if (!declared || declared.length === 0) return;
+	const missing = declared.filter((name) => {
+		if (mcp) {
+			const server = mcp.servers.find((s) => s.name === name);
+			return !server || server.status !== "connected";
+		}
+		return !Object.keys(tools ?? {}).some((tool) => tool.split("__")[0] === name);
+	});
+	if (missing.length === 0) return;
+	const reasons = missing.map((name) => {
+		const error = mcp?.servers.find((s) => s.name === name)?.error;
+		return error ? `${name} (${error})` : name;
+	}).join(", ");
+	throw new Error(`profile '${profileName}' declares MCP server(s) that are not connected: ${reasons}. A session missing a declared server is a session whose agent silently cannot do its job.`);
+}
+/**
 * Restrict a connected tool set to the MCP servers a profile grants, by the
 * `<server>__<tool>` namespace {@link connectMcpTools} assigns. Undefined `servers`
 * = no declaration, so every connected server passes through.
@@ -2637,31 +2718,88 @@ function selectMcpTools(tools, servers) {
 * Server-side only, with server credentials: these tools are authoritative and
 * must never be bridged to a browser. `@ai-sdk/mcp` is imported lazily and is an
 * optional dependency — an operator who wires no MCP servers never needs it.
+*
+* **A stateless MCP server must answer `GET` with 405.** The client opens the
+* SSE stream with a `GET` before it sends anything, and a POST-only server
+* mounted under a framework's default 404 makes the whole connect fail with an
+* error that names neither the method nor the route. This is the single most
+* common way an otherwise-correct MCP mount fails.
 */
 async function connectMcpTools(servers, options = {}) {
 	const entries = Object.entries(servers);
 	if (entries.length === 0) return {
 		tools: {},
+		servers: [],
 		close: async () => {}
 	};
 	const { createMCPClient } = await import("@ai-sdk/mcp");
 	const clients = [];
 	const tools = {};
-	for (const [name, server] of entries) try {
-		const client = await createMCPClient({
-			transport: toTransport(server),
-			onUncaughtError: (error) => options.onError?.(name, error)
-		});
-		clients.push(client);
-		for (const [toolName, mcpTool] of Object.entries(await client.tools())) tools[`${name}__${toolName}`] = mcpTool;
-	} catch (error) {
-		options.onError?.(name, error);
+	const statuses = [];
+	const closeAll = async () => {
+		await Promise.allSettled(clients.map((c) => c.close()));
+	};
+	for (const [name, server] of entries) {
+		const identity = describeServer(server);
+		try {
+			const client = await createMCPClient({
+				transport: toTransport(server),
+				onUncaughtError: (error) => options.onError?.(name, error)
+			});
+			clients.push(client);
+			const connected = await client.tools();
+			for (const [toolName, mcpTool] of Object.entries(connected)) tools[`${name}__${toolName}`] = mcpTool;
+			statuses.push({
+				name,
+				status: "connected",
+				...identity,
+				tools: Object.entries(connected).map(([toolName, mcpTool]) => toToolInfo(toolName, mcpTool))
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			statuses.push({
+				name,
+				status: "failed",
+				error: message,
+				...identity
+			});
+			options.onError?.(name, error);
+			if (options.required) {
+				await closeAll();
+				throw new Error(`MCP server '${name}' failed to connect: ${message}`);
+			}
+		}
 	}
 	return {
 		tools,
-		close: async () => {
-			await Promise.allSettled(clients.map((c) => c.close()));
-		}
+		servers: statuses,
+		close: closeAll
+	};
+}
+/** The connection's identity, minus its secrets — `headers` never travel. */
+function describeServer(server) {
+	if ("url" in server) return {
+		transport: server.type === "sse" ? "sse" : "http",
+		url: server.url
+	};
+	return {
+		transport: "stdio",
+		command: server.command,
+		args: server.args
+	};
+}
+/**
+* The AI SDK hands back its own `Tool`, whose `inputSchema` may be a zod schema
+* or a `jsonSchema()` wrapper. Only the latter carries a JSON Schema document,
+* so that is the only case where parameters are reported — `McpServerToolInfo`
+* models the absence deliberately, and inventing one here would be worse.
+*/
+function toToolInfo(name, mcpTool) {
+	const { description, inputSchema } = mcpTool ?? {};
+	return {
+		name,
+		description: typeof description === "string" ? description : void 0,
+		inputSchema: inputSchema?.jsonSchema
 	};
 }
 /**
@@ -2797,9 +2935,9 @@ const claudeAdapter = {
 		};
 		return { available: "unknown" };
 	},
-	createRunner({ config, restore }) {
+	createRunner({ config, restore, id }) {
 		if (restore) throw new Error("the Claude engine cannot rebuild a parked session");
-		return new SessionRunner(config);
+		return new SessionRunner(config, id);
 	},
 	/**
 	* The Agent SDK's on-disk session store, mapped browser-safe. The SDK reads
@@ -3345,6 +3483,8 @@ var CodexRunner = class {
 	id;
 	createdAt;
 	#config;
+	/** {@link CodexRunnerConfig.cwd}, checked once in the constructor. */
+	#cwd;
 	#events = [];
 	#listeners = /* @__PURE__ */ new Set();
 	#seq = 0;
@@ -3407,6 +3547,8 @@ var CodexRunner = class {
 		const mode = config.permissionMode ?? "default";
 		if (!ENGINE_CAPABILITIES.codex.permissionModes.includes(mode)) throw new Error(`permission mode '${mode}' is not supported by the codex engine`);
 		if (config.forkSession) throw new Error("the codex engine cannot fork a resumed thread");
+		if (!config.cwd) throw new Error("the codex engine requires a cwd");
+		this.#cwd = config.cwd;
 		this.#config = config;
 		this.#permissionMode = mode;
 		this.#model = config.model;
@@ -3442,7 +3584,7 @@ var CodexRunner = class {
 			id: this.id,
 			sdkSessionId: this.#sdkSessionId,
 			status: this.#status,
-			cwd: this.#config.cwd,
+			cwd: this.#cwd,
 			profile: this.#config.profile,
 			engine: "codex",
 			capabilities: ENGINE_CAPABILITIES.codex,
@@ -3454,6 +3596,7 @@ var CodexRunner = class {
 			activityCount: this.#activityCount,
 			pendingPermissionCount: this.#approvals.size,
 			meta: this.#config.meta,
+			scope: this.#config.scope,
 			title: this.#title(),
 			totalCostUsd: this.#totalCostUsd,
 			numTurns: this.#numTurns || void 0,
@@ -3738,7 +3881,7 @@ var CodexRunner = class {
 		}
 		if (!this.#threadLoaded) {
 			const options = {
-				cwd: this.#config.cwd,
+				cwd: this.#cwd,
 				approvalPolicy: APPROVAL_POLICY_BY_MODE[this.#permissionMode],
 				sandbox: THREAD_SANDBOX_BY_MODE[this.#permissionMode]
 			};
@@ -3779,7 +3922,7 @@ var CodexRunner = class {
 		if (this.#skillsRefresh) return this.#skillsRefresh;
 		const run = (async () => {
 			try {
-				const result = await connection.request("skills/list", { cwds: [this.#config.cwd] });
+				const result = await connection.request("skills/list", { cwds: [this.#cwd] });
 				if (this.#closed) return;
 				const entries = Array.isArray(result?.data) ? result.data : [];
 				const seen = /* @__PURE__ */ new Set();
@@ -3981,7 +4124,7 @@ var CodexRunner = class {
 			const params = {
 				threadId: this.#sdkSessionId,
 				input: turn.input,
-				cwd: this.#config.cwd,
+				cwd: this.#cwd,
 				approvalPolicy: APPROVAL_POLICY_BY_MODE[this.#permissionMode],
 				sandboxPolicy: TURN_SANDBOX_BY_MODE[this.#permissionMode]
 			};
@@ -4905,7 +5048,7 @@ const codexAdapter = {
 	capabilities: ENGINE_CAPABILITIES.codex,
 	catalog: CODEX_CATALOG,
 	checkAvailability: (profile, env) => checkCodexAvailability(profile, env),
-	createRunner({ config, profile, restore }) {
+	createRunner({ config, profile, restore, id }) {
 		if (restore) throw new Error("the codex engine cannot rebuild a parked session");
 		const executable = config.codexPathOverride ?? resolveBundledCodexExecutable();
 		if (!executable) throw new Error(NOT_INSTALLED);
@@ -4916,7 +5059,7 @@ const codexAdapter = {
 				executable,
 				...options
 			})
-		});
+		}, id);
 	},
 	async listSessions(options) {
 		const executable = resolveBundledCodexExecutable();
@@ -4976,6 +5119,6 @@ function getEngineAdapter(engine) {
 	return ADAPTERS[engine ?? "claude"];
 }
 //#endregion
-export { AiSdkRunner, BrowserBridgeExecutor, CLAUDE_CATALOG, CODEX_CATALOG, CodexRunner, DeferredExecutor, InputQueue, JsonRpcError, JsonRpcStdioConnection, PendingRequestRegistry, QuickJsExecutor, SUPPORTED_ATTACHMENT_TYPES, SessionRunner, attachmentContentBlocks, attachmentKind, attachmentRef, checkClaudeAuth, claudeAdapter, codexAdapter, connectAppServer, connectMcpTools, createEngineSession, createToolContext, createWebFetch, getEngineAdapter, htmlToMarkdown, isHostAllowed, isPrivateAddress, listCodexSessions, mcpStatusInfo, modelOptionsFromSdk, normalizeMediaType, normalizeSdkMessage, providerAdapter, resolveBundledClaudeExecutable, resolveBundledCodexExecutable, toApiMessage, toExecutionResult, withMcpTools };
+export { AiSdkRunner, BrowserBridgeExecutor, CLAUDE_CATALOG, CODEX_CATALOG, CodexRunner, DeferredExecutor, InputQueue, JsonRpcError, JsonRpcStdioConnection, PendingRequestRegistry, QuickJsExecutor, SUPPORTED_ATTACHMENT_TYPES, SessionRunner, attachmentContentBlocks, attachmentKind, attachmentRef, checkClaudeAuth, claudeAdapter, codexAdapter, connectAppServer, connectMcpTools, createEngineSession, createToolContext, createWebFetch, getEngineAdapter, htmlToMarkdown, isHostAllowed, isPrivateAddress, listCodexSessions, mcpStatusInfo, modelOptionsFromSdk, normalizeMediaType, normalizeSdkMessage, providerAdapter, resolveBundledClaudeExecutable, resolveBundledCodexExecutable, toApiMessage, toExecutionResult, withHostTools, withMcpTools };
 
 //# sourceMappingURL=index.mjs.map