@ai-agent-forge/agent-forge 0.85.0

package/dist/core/agent-session-services.js

@@ -0,0 +1,680 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONFIG_DIR_NAME, getAgentDir, VERSION } from "../config.js";
+import { createSuiteAssembly, resolveSuiteId, SUITE_ENV_VAR } from "../profiles/suite-loader.js";
+import { resolvePath } from "../utils/paths.js";
+import { EXPERIMENTAL_PUBLIC_API_VERSION } from "./extensions/index.js";
+import { ModelRuntime } from "./model-runtime.js";
+import { DefaultResourceLoader, } from "./resource-loader.js";
+import { createAgentSession, } from "./sdk.js";
+import { SettingsManager } from "./settings-manager.js";
+// ---------------------------------------------------------------------------
+// Suite MCP registration pool (方案系统 M4: MCP 配置面, 设计 §4/§5)
+// ---------------------------------------------------------------------------
+/** User-level MCP config file directly inside the agent dir. */
+const MCP_CONFIG_FILENAME = "mcp.json";
+/** Generated per-server capability-plugin manifests live below this agentDir dir. */
+const MCP_POOL_DIR = "mcp/pool";
+/** Shared stdio bridge module inside the pool dir (leading "_" keeps server names distinct). */
+const MCP_POOL_BRIDGE_DIR = "_bridge";
+/** Server names are associations keys and pool directory names; "_" is reserved for the bridge. */
+const MCP_SERVER_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * Implementation backing url-configured pool entries (createMcpHttpServerPlugin).
+ * Sources resolve first so development always runs the current implementation;
+ * published installs ship only dist, so dist is the fallback.
+ */
+const MCP_HTTP_PLUGIN_SOURCE_PATH = fileURLToPath(new URL("../plugins/mcp-http.ts", import.meta.url));
+const MCP_HTTP_PLUGIN_DIST_PATH = fileURLToPath(new URL("../../dist/plugins/mcp-http.js", import.meta.url));
+/**
+ * Remote MCP URLs accept only http/https; any other protocol or unparseable
+ * value is a configuration error, not a fallback path.
+ */
+function isHttpUrl(value) {
+    try {
+        const protocol = new URL(value).protocol;
+        return protocol === "http:" || protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Reads one mcp.json (`{ "mcpServers": { "<name>": { "command", "args" } } }`
+ * for stdio servers, or `{ "url" }` for remote HTTP servers). Each entry must
+ * carry exactly one of "command" and "url". Corruption tolerance: a missing
+ * file is an empty config; an unreadable or malformed file, and invalid
+ * per-server entries, contribute a diagnostic and are skipped — never thrown.
+ */
+function parseMcpConfig(path) {
+    const servers = new Map();
+    const diagnostics = [];
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { servers, diagnostics };
+        diagnostics.push(`MCP config at ${path} is unreadable; ignoring it. Errors: ${error instanceof Error ? error.message : String(error)}`);
+        return { servers, diagnostics };
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        diagnostics.push(`MCP config at ${path} must be an object with an "mcpServers" map; ignoring it.`);
+        return { servers, diagnostics };
+    }
+    const mcpServers = value.mcpServers;
+    if (mcpServers === undefined)
+        return { servers, diagnostics };
+    if (typeof mcpServers !== "object" || mcpServers === null || Array.isArray(mcpServers)) {
+        diagnostics.push(`MCP config at ${path} must carry an "mcpServers" object; ignoring it.`);
+        return { servers, diagnostics };
+    }
+    for (const [name, entry] of Object.entries(mcpServers)) {
+        if (!MCP_SERVER_NAME_PATTERN.test(name)) {
+            diagnostics.push(`MCP server name "${name}" in ${path} is invalid (must match ${MCP_SERVER_NAME_PATTERN.source}); ignoring it.`);
+            continue;
+        }
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            diagnostics.push(`MCP server "${name}" in ${path} must be an object with a "command" or "url"; ignoring it.`);
+            continue;
+        }
+        const config = entry;
+        if (config.url !== undefined && (typeof config.url !== "string" || config.url.trim().length === 0)) {
+            diagnostics.push(`MCP server "${name}" in ${path} requires "url" to be a non-empty string; ignoring it.`);
+            continue;
+        }
+        const hasCommand = typeof config.command === "string" && config.command.trim().length > 0;
+        const hasUrl = typeof config.url === "string" && config.url.trim().length > 0;
+        if (hasCommand && hasUrl) {
+            diagnostics.push(`MCP server "${name}" in ${path} accepts either "command" (stdio server) or "url" (remote HTTP server), not both; ignoring it.`);
+            continue;
+        }
+        if (!hasCommand && !hasUrl) {
+            diagnostics.push(`MCP server "${name}" in ${path} requires a non-empty string "command" (stdio server) or "url" (remote HTTP server); ignoring it.`);
+            continue;
+        }
+        if (hasUrl && !isHttpUrl(config.url)) {
+            diagnostics.push(`MCP server "${name}" in ${path} requires "url" to be a valid http:// or https:// URL; ignoring it.`);
+            continue;
+        }
+        if (config.args !== undefined &&
+            (!Array.isArray(config.args) || !config.args.every((arg) => typeof arg === "string"))) {
+            diagnostics.push(`MCP server "${name}" in ${path} requires "args" to be a string array; ignoring it.`);
+            continue;
+        }
+        if (config.deferredTools !== undefined && typeof config.deferredTools !== "boolean") {
+            diagnostics.push(`MCP server "${name}" in ${path} requires "deferredTools" to be a boolean; ignoring it.`);
+            continue;
+        }
+        if (config.headers !== undefined) {
+            if (hasCommand) {
+                // Same acceptance style as a url entry carrying args: the entry
+                // loads, but the field belongs to the other transport shape.
+                diagnostics.push(`MCP server "${name}" in ${path} carries "headers" but headers only apply to remote "url" (HTTP) servers; ignoring them.`);
+            }
+            else {
+                const headersValid = typeof config.headers === "object" &&
+                    config.headers !== null &&
+                    !Array.isArray(config.headers) &&
+                    Object.values(config.headers).every((headerValue) => typeof headerValue === "string" && headerValue.length > 0);
+                if (!headersValid) {
+                    diagnostics.push(`MCP server "${name}" in ${path} requires "headers" to be an object with non-empty string values; ignoring it.`);
+                    continue;
+                }
+            }
+        }
+        servers.set(name, {
+            args: config.args ?? [],
+            deferredTools: config.deferredTools === true ? true : undefined,
+            ...(hasCommand
+                ? { command: config.command }
+                : {
+                    url: config.url,
+                    // Kept verbatim (no case normalization): managed remote MCP
+                    // endpoints compare header names and values exactly.
+                    ...(config.headers === undefined
+                        ? {}
+                        : { headers: config.headers }),
+                }),
+        });
+    }
+    return { servers, diagnostics };
+}
+/**
+ * Generated stdio bridge shared by every injected server: JSON-RPC 2.0 over a
+ * spawned child process (argv, never a shell — except on win32, where a
+ * resolved `.cmd`/`.bat` shim is launched through `cmd.exe /d /s /c`, so its
+ * arguments cross cmd's command-line interpreter exactly as with
+ * `shell: true`), MCP initialize/tools/list
+ * handshake, and one registerTool per remote tool through the public
+ * capability API. Tool call policy stays host-owned; the bridge only forwards
+ * requests and maps results. On win32 the transport additionally resolves
+ * `.cmd`/`.bat` shims (bare names via PATH, explicit suffixes verbatim) and
+ * launches them through `cmd.exe /d /s /c` with MSVCRT argv quoting, because
+ * Node >= 18.20 refuses to spawn extension shims directly (EINVAL) and
+ * extension-less shim names ENOENT.
+ */
+const MCP_POOL_BRIDGE_SOURCE = `// Generated by the suite MCP registration pool (agent-session-services). Do not edit.
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const REQUEST_TIMEOUT_MS = 30000;
+
+// Windows .cmd/.bat shims cannot be spawned directly: Node >= 18.20 raises
+// EINVAL for commands carrying a shim extension and ENOENT for bare names
+// (npx, pnpm, ...), so bare command names (no path separator) are probed
+// along PATH for a .cmd/.bat shim, and explicit .cmd/.bat commands pass
+// through for cmd.exe wrapping. Everything else - .exe/.com, path-bearing
+// executables, non-win32 platforms, and PATH misses - resolves to undefined
+// and keeps the direct spawn behavior (a miss keeps the original ENOENT).
+function resolveWin32ShimCommand(command) {
+	if (process.platform !== 'win32') return undefined;
+	const lowered = command.toLowerCase();
+	if (lowered.endsWith('.cmd') || lowered.endsWith('.bat')) return command;
+	if (command.includes('/') || command.includes('\\\\')) return undefined;
+	for (const dir of (process.env.PATH || '').split(';')) {
+		if (!dir) continue;
+		const cmdShim = join(dir, command + '.cmd');
+		if (existsSync(cmdShim)) return cmdShim;
+		const batShim = join(dir, command + '.bat');
+		if (existsSync(batShim)) return batShim;
+	}
+	return undefined;
+}
+
+// MSVCRT argv quoting for the cmd.exe /c command string: an argument that is
+// empty or contains space/tab/quote is wrapped in double quotes, embedded
+// quotes are escaped as \\", and backslashes directly before a quote (or a
+// quoted argument's trailing backslashes) double up (2n rule) so they cannot
+// escape the closing quote. Plain arguments pass through untouched.
+function quoteCommandString(parts) {
+	const quoted = [];
+	for (const part of parts) {
+		if (part !== '' && !/[ \\t"]/.test(part)) {
+			quoted.push(part);
+			continue;
+		}
+		let inner = '';
+		let backslashes = 0;
+		for (const ch of part) {
+			if (ch === '\\\\') {
+				backslashes += 1;
+			} else if (ch === '"') {
+				inner += '\\\\'.repeat(backslashes * 2 + 1) + '"';
+				backslashes = 0;
+			} else {
+				if (backslashes > 0) {
+					inner += '\\\\'.repeat(backslashes);
+					backslashes = 0;
+				}
+				inner += ch;
+			}
+		}
+		if (backslashes > 0) {
+			inner += '\\\\'.repeat(backslashes * 2);
+		}
+		quoted.push('"' + inner + '"');
+	}
+	return quoted.join(' ');
+}
+
+function startTransport(command, args) {
+	// win32 only: wrap .cmd/.bat shims through cmd.exe (resolveWin32ShimCommand).
+	// The MSVCRT-quoted command string gets ONE more plain outer pair of
+	// quotes (cmd.exe dialect, not MSVCRT): /S strips that outer pair and
+	// re-parses the inner string. windowsVerbatimArguments is required so the
+	// pre-built string reaches cmd.exe untouched; Node's default quoting would
+	// wrap it again and cmd.exe would see literal \\" sequences instead.
+	const shim = resolveWin32ShimCommand(command);
+	const child =
+		shim === undefined
+			? spawn(command, args, { shell: false, stdio: ['pipe', 'pipe', 'pipe'] })
+			: spawn('cmd.exe', ['/d', '/s', '/c', '"' + quoteCommandString([shim].concat(args)) + '"'], {
+					windowsVerbatimArguments: true,
+					stdio: ['pipe', 'pipe', 'pipe'],
+				});
+	let nextId = 1;
+	let closed = false;
+	let failure = null;
+	let buffered = '';
+	const pending = new Map();
+	const rejectAll = (error) => {
+		if (failure) return;
+		failure = error;
+		closed = true;
+		for (const request of pending.values()) request.reject(error);
+		pending.clear();
+	};
+	child.stdout.setEncoding('utf8');
+	child.stdout.on('data', (chunk) => {
+		buffered += chunk;
+		const lines = buffered.split(/\\r?\\n/);
+		buffered = lines.pop() || '';
+		for (const line of lines) {
+			if (!line.trim()) continue;
+			let response;
+			try {
+				response = JSON.parse(line);
+			} catch {
+				rejectAll(new Error('MCP server produced a malformed JSON-RPC response'));
+				return;
+			}
+			if (response.id === undefined || response.id === null) continue;
+			const request = pending.get(response.id);
+			if (!request) continue;
+			pending.delete(response.id);
+			if (response.error) {
+				request.reject(new Error('MCP request failed: ' + String(response.error.message || 'unknown error')));
+			} else {
+				request.resolve(response.result);
+			}
+		}
+	});
+	child.stderr.setEncoding('utf8');
+	child.stderr.on('data', () => undefined);
+	child.once('error', (error) => rejectAll(new Error('Failed to spawn MCP server: ' + error.message)));
+	child.once('close', (exitCode) => rejectAll(new Error('MCP server exited with code ' + String(exitCode))));
+	const send = (message) => {
+		child.stdin.write(JSON.stringify(message) + '\\n');
+	};
+	const request = (method, params, signal) => {
+		if (failure || closed) return Promise.reject(failure || new Error('MCP transport is closed'));
+		if (signal && signal.aborted) return Promise.reject(new Error('MCP request aborted'));
+		const id = nextId++;
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				pending.delete(id);
+				reject(new Error('MCP request timed out: ' + method));
+			}, REQUEST_TIMEOUT_MS);
+			pending.set(id, {
+				resolve: (result) => {
+					clearTimeout(timer);
+					resolve(result);
+				},
+				reject: (error) => {
+					clearTimeout(timer);
+					reject(error);
+				},
+			});
+			if (signal) {
+				signal.addEventListener(
+					'abort',
+					() => {
+						if (pending.delete(id)) reject(new Error('MCP request aborted'));
+					},
+					{ once: true },
+				);
+			}
+			send(Object.assign({ jsonrpc: '2.0', id, method }, params === undefined ? {} : { params }));
+		});
+	};
+	return {
+		request,
+		notify(method, params) {
+			if (closed) return;
+			send(Object.assign({ jsonrpc: '2.0', method }, params === undefined ? {} : { params }));
+		},
+		close() {
+			if (closed) return;
+			closed = true;
+			child.stdin.end();
+			if (!child.killed) child.kill();
+		},
+	};
+}
+
+function normalizeToolResult(result) {
+	if (result && typeof result === 'object' && Array.isArray(result.content)) {
+		return { content: result.content, details: result.details };
+	}
+	if (result === undefined) return { content: [{ type: 'text', text: '' }], details: undefined };
+	return { content: [{ type: 'text', text: JSON.stringify(result) }], details: undefined };
+}
+
+export default function createMcpStdioServerPlugin(config) {
+	return async (api) => {
+		const transport = startTransport(config.command, config.args || []);
+		try {
+			await transport.request('initialize', {
+				protocolVersion: '2024-11-05',
+				capabilities: {},
+				clientInfo: { name: 'agent-forge-mcp-pool', version: '0.1.0' },
+			});
+			transport.notify('notifications/initialized');
+			const listing = await transport.request('tools/list');
+			if (!listing || !Array.isArray(listing.tools)) {
+				throw new Error('MCP tools/list result must contain tools[]');
+			}
+			for (const tool of listing.tools) {
+				if (!tool || typeof tool.name !== 'string' || !tool.name) {
+					throw new Error('MCP tool requires a non-empty name');
+				}
+				api.registerTool({
+					name: tool.name,
+					label: tool.name,
+					description: typeof tool.description === 'string' ? tool.description : 'MCP tool: ' + tool.name,
+					parameters:
+						tool.inputSchema && typeof tool.inputSchema === 'object'
+							? tool.inputSchema
+							: { type: 'object', properties: {} },
+					execute: async (toolCallId, params, signal) => {
+						// Dual call convention: the session passes (toolCallId, params,
+						// signal); the runtime's invokeTool passes the input as the
+						// single first argument.
+						const singleArgCall = params === undefined && typeof toolCallId !== 'string';
+						const input = singleArgCall ? toolCallId : params;
+						const result = await transport.request(
+							'tools/call',
+							{ name: tool.name, arguments: input || {} },
+							singleArgCall ? undefined : signal,
+						);
+						return normalizeToolResult(result);
+					},
+				});
+			}
+			return {
+				dispose() {
+					transport.close();
+				},
+			};
+		} catch (error) {
+			transport.close();
+			throw error;
+		}
+	};
+}
+`;
+function writeMcpPoolBridge(poolDir) {
+    const bridgeDir = join(poolDir, MCP_POOL_BRIDGE_DIR);
+    mkdirSync(bridgeDir, { recursive: true });
+    writeFileSync(join(bridgeDir, "index.mjs"), MCP_POOL_BRIDGE_SOURCE, "utf8");
+}
+/**
+ * Import specifier for the HTTP server plugin implementation, as written into
+ * a generated pool entry below `fromDir`. Relative same-drive form matches the
+ * stdio entry's style; a cross-drive relative() result stays an absolute POSIX
+ * path, which the capability loader (jiti) resolves.
+ */
+function mcpHttpPluginImportSpec(fromDir) {
+    const implPath = existsSync(MCP_HTTP_PLUGIN_SOURCE_PATH) ? MCP_HTTP_PLUGIN_SOURCE_PATH : MCP_HTTP_PLUGIN_DIST_PATH;
+    const relNative = relative(fromDir, implPath);
+    const relPosix = relNative.split(sep).join("/");
+    return isAbsolute(relNative) ? relPosix : `./${relPosix}`;
+}
+/** Materializes one server as a capability-plugin manifest; returns the manifest path. */
+function writeMcpPoolServer(poolDir, name, server) {
+    const serverDir = join(poolDir, name);
+    mkdirSync(serverDir, { recursive: true });
+    const manifest = {
+        id: `agent-forge.mcp.${name}`,
+        version: "0.1.0",
+        // The pool is re-materialized every session, so the declared range always
+        // includes the running host (D-073): an upgraded host never rejects its
+        // own generated pool manifests through the hostVersion gate.
+        hostVersion: `>=${VERSION}`,
+        apiVersion: EXPERIMENTAL_PUBLIC_API_VERSION,
+        entry: "./index.mjs",
+        requiredCapabilities: ["tools"],
+    };
+    writeFileSync(join(serverDir, "plugin.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    const entry = server.url === undefined
+        ? [
+            "// Generated by the suite MCP registration pool (agent-session-services). Do not edit.",
+            `import createMcpStdioServerPlugin from "../${MCP_POOL_BRIDGE_DIR}/index.mjs";`,
+            `export default createMcpStdioServerPlugin(${JSON.stringify({ command: server.command, args: server.args })});`,
+            "",
+        ].join("\n")
+        : [
+            "// Generated by the suite MCP registration pool (agent-session-services). Do not edit.",
+            `import { createMcpHttpServerPlugin } from "${mcpHttpPluginImportSpec(serverDir)}";`,
+            `export default createMcpHttpServerPlugin(${JSON.stringify({
+                url: server.url,
+                ...(server.headers === undefined ? {} : { headers: server.headers }),
+            })});`,
+            "",
+        ].join("\n");
+    writeFileSync(join(serverDir, "index.mjs"), entry, "utf8");
+    return join(serverDir, "plugin.json");
+}
+/**
+ * Resolves the suite's MCP registration pool (方案系统 M4: MCP 配置面, 设计
+ * §4/§5) and materializes each injected server as a capability-plugin
+ * manifest below `<agentDir>/mcp/pool/`, ready for the session's
+ * `capabilityPluginPaths` channel — the same way plugins directory discovery
+ * injects manifests. Filtering: the project level
+ * (`<cwd>/.agent-forge/mcp.json`) is the third layer (设计 §4) and always
+ * passes; the user level (`<agentDir>/mcp.json`) injects only servers named
+ * in `suite.associations.mcp` — an empty association list means zero
+ * user-level injection, the same semantics as skills/extensions.
+ */
+export function resolveSuiteMcpPool(options) {
+    const { cwd, agentDir, suite } = options;
+    const userConfigPath = join(agentDir, MCP_CONFIG_FILENAME);
+    const projectConfigPath = join(cwd, CONFIG_DIR_NAME, MCP_CONFIG_FILENAME);
+    const user = parseMcpConfig(userConfigPath);
+    const project = parseMcpConfig(projectConfigPath);
+    const diagnostics = [...project.diagnostics, ...user.diagnostics];
+    const selected = new Map();
+    // Third layer (设计 §4): project-level servers always pass; they win name
+    // collisions over user definitions.
+    for (const [name, server] of project.servers)
+        selected.set(name, { ...server, scope: "project" });
+    for (const [name, server] of user.servers) {
+        if (selected.has(name)) {
+            diagnostics.push(`MCP server "${name}" from ${userConfigPath} is overridden by the project-level definition at ${projectConfigPath}; keeping the project one.`);
+            continue;
+        }
+        if (!suite.associations.mcp.includes(name)) {
+            diagnostics.push(`Suite "${suite.id}" MCP server "${name}" is not associated (associations.mcp); not injected.`);
+            continue;
+        }
+        selected.set(name, { ...server, scope: "user" });
+    }
+    for (const name of suite.associations.mcp) {
+        if (!selected.has(name)) {
+            diagnostics.push(`Suite "${suite.id}" dangling association "${name}" (mcp): not found in the discovered registry; ignored.`);
+        }
+    }
+    const servers = [];
+    const manifestPaths = [];
+    const deferredPluginIds = [];
+    if (selected.size > 0) {
+        const poolDir = join(agentDir, MCP_POOL_DIR);
+        writeMcpPoolBridge(poolDir);
+        for (const [name, server] of selected) {
+            const manifestPath = writeMcpPoolServer(poolDir, name, server);
+            manifestPaths.push(manifestPath);
+            servers.push({
+                name,
+                args: server.args,
+                scope: server.scope,
+                manifestPath,
+                deferred: server.deferredTools === true,
+                ...(server.url === undefined
+                    ? { command: server.command }
+                    : {
+                        url: server.url,
+                        ...(server.headers === undefined ? {} : { headers: server.headers }),
+                    }),
+            });
+            if (server.deferredTools === true) {
+                deferredPluginIds.push(`agent-forge.mcp.${name}`);
+            }
+        }
+    }
+    return { servers, manifestPaths, deferredPluginIds, diagnostics };
+}
+/**
+ * Create cwd-bound runtime services.
+ *
+ * Returns services plus diagnostics. It does not create an AgentSession.
+ */
+export async function createAgentSessionServices(options) {
+    const cwd = resolvePath(options.cwd);
+    const agentDir = options.agentDir ? resolvePath(options.agentDir) : getAgentDir();
+    const modelRuntime = options.modelRuntime ??
+        (await ModelRuntime.create({
+            authPath: join(agentDir, "auth.json"),
+            modelsPath: join(agentDir, "models.json"),
+            credentials: options.credentials,
+            signal: options.modelRuntimeSignal,
+        }));
+    const settingsManager = options.settingsManager ?? SettingsManager.create(cwd, agentDir);
+    // Suite assembly (设计 §3/§4/§8, M2): resolve once and wire the shared
+    // assembly into this loader. Off by default so evals/testkit services keep
+    // their fixture resources unfiltered.
+    let suiteId;
+    let suiteLoaderOverrides;
+    let suiteLocalSkillsDir;
+    let pluginProfile;
+    /** MCP registration pool for the assembled suite (M4); undefined when assembly is off. */
+    let mcpPool;
+    if (options.suiteAssembly) {
+        suiteId = resolveSuiteId({
+            explicit: options.suite,
+            envSuite: process.env[SUITE_ENV_VAR],
+            settings: settingsManager,
+            agentDir,
+        });
+        const suiteAssembly = createSuiteAssembly({
+            cwd,
+            agentDir,
+            suiteId,
+            pluginProfileId: options.pluginProfileId,
+            selectedPluginIds: options.selectedPluginIds,
+            disabledPluginIds: options.disabledPluginIds,
+            pluginHost: options.pluginHost,
+            verifiedPlugins: options.verifiedPlugins,
+            manifestOverrides: options.manifestOverrides,
+        });
+        pluginProfile = suiteAssembly.pluginProfile;
+        suiteLoaderOverrides = suiteAssembly.loaderOverrides;
+        // Suite-local skill layer (统一修复轮 B): <suiteDir>/skills rides this
+        // loader's skill paths when the suite is active, mirroring the sdk's
+        // self-built loader path so the two first-party entries cannot drift.
+        suiteLocalSkillsDir = suiteAssembly.localSkillsDir;
+        // MCP registration pool (M4): read the mcp.json config surface, filter
+        // by associations.mcp, and materialize the injected servers as
+        // capability-plugin manifests for the session's explicit paths channel.
+        mcpPool = resolveSuiteMcpPool({ cwd, agentDir, suite: suiteAssembly.workspace.suite });
+    }
+    const additionalSkillPaths = [
+        ...(options.resourceLoaderOptions?.additionalSkillPaths ?? []),
+        ...(suiteLocalSkillsDir === undefined ? [] : [suiteLocalSkillsDir]),
+    ];
+    const resourceLoader = new DefaultResourceLoader({
+        ...(options.resourceLoaderOptions ?? {}),
+        ...suiteLoaderOverrides,
+        ...(additionalSkillPaths.length > 0 ? { additionalSkillPaths } : {}),
+        cwd,
+        agentDir,
+        settingsManager,
+    });
+    await resourceLoader.reload(options.resourceLoaderReloadOptions);
+    const diagnostics = [];
+    await modelRuntime.refresh({ allowNetwork: false });
+    for (const message of mcpPool?.diagnostics ?? []) {
+        diagnostics.push({ type: "info", message });
+    }
+    diagnostics.push(...(options.pluginBindingDiagnostics ?? []));
+    return {
+        cwd,
+        agentDir,
+        modelRuntime,
+        settingsManager,
+        resourceLoader,
+        diagnostics,
+        ...(suiteId === undefined ? {} : { suiteId }),
+        ...(pluginProfile === undefined ? {} : { pluginProfile }),
+        ...(options.pluginProfileId === undefined ? {} : { pluginProfileId: options.pluginProfileId }),
+        ...(options.installedCapabilityPlugins === undefined
+            ? {}
+            : { installedCapabilityPlugins: Object.freeze([...options.installedCapabilityPlugins]) }),
+        ...(mcpPool !== undefined && mcpPool.manifestPaths.length > 0
+            ? { mcpCapabilityPluginPaths: mcpPool.manifestPaths }
+            : {}),
+        ...(mcpPool !== undefined && mcpPool.deferredPluginIds.length > 0
+            ? { mcpDeferredToolPluginIds: mcpPool.deferredPluginIds }
+            : {}),
+    };
+}
+/**
+ * Create an AgentSession from previously created services.
+ *
+ * This keeps session creation separate from service creation so callers can
+ * resolve model, thinking, tools, and other session inputs against the target
+ * cwd before constructing the session.
+ */
+export async function createAgentSessionFromServices(options) {
+    return createAgentSession({
+        cwd: options.services.cwd,
+        agentDir: options.services.agentDir,
+        modelRuntime: options.services.modelRuntime,
+        settingsManager: options.services.settingsManager,
+        resourceLoader: options.resourceLoader ?? options.services.resourceLoader,
+        sessionManager: options.sessionManager,
+        model: options.model,
+        streamFn: options.streamFn,
+        thinkingLevel: options.thinkingLevel,
+        scopedModels: options.scopedModels,
+        tools: options.tools,
+        excludeTools: options.excludeTools,
+        noTools: options.noTools,
+        customTools: options.customTools,
+        // Suite binding: an explicit option wins; otherwise the services' single
+        // resolution result is forwarded so the sdk does not resolve again and
+        // the two sides cannot drift (设计 §9).
+        ...(options.suite !== undefined || options.services.suiteId !== undefined
+            ? { suite: options.suite ?? options.services.suiteId }
+            : {}),
+        // Capability wiring (方案系统 M3): the sdk's caller-supplied-loader
+        // boundary would leave it off for the services' own loader, so first-party
+        // assembly turns it on here; an explicit option wins.
+        ...((options.suiteCapabilityWiring ?? options.services.suiteId !== undefined)
+            ? { suiteCapabilityWiring: true }
+            : {}),
+        ...(options.services.pluginProfile === undefined ? {} : { pluginProfile: options.services.pluginProfile }),
+        ...(options.services.installedCapabilityPlugins === undefined
+            ? {}
+            : { installedCapabilityPlugins: options.services.installedCapabilityPlugins }),
+        sessionStartEvent: options.sessionStartEvent,
+        capabilityMode: options.capabilityMode,
+        discoverCapabilityPlugins: options.discoverCapabilityPlugins,
+        // Trace/log control face (设计 §4.4/§5/§6): undefined passes through, so
+        // the sdk defaults (trace on, no host logging) stay in effect.
+        traceEnabled: options.traceEnabled,
+        hostLogger: options.hostLogger,
+        // MCP registration pool (M4): the services' generated manifest paths ride
+        // the explicit caller-intent channel, so they bypass associations.plugins
+        // filtering (they are governed by associations.mcp, not associations.plugins);
+        // caller-provided paths keep discovery-order precedence on id conflicts.
+        ...(options.services.mcpCapabilityPluginPaths === undefined
+            ? { capabilityPluginPaths: options.capabilityPluginPaths }
+            : {
+                capabilityPluginPaths: [
+                    ...(options.capabilityPluginPaths ?? []),
+                    ...options.services.mcpCapabilityPluginPaths,
+                ],
+            }),
+        ...(options.services.mcpDeferredToolPluginIds === undefined
+            ? {}
+            : { deferredToolPluginIds: options.services.mcpDeferredToolPluginIds }),
+        contextStrategyName: options.contextStrategyName,
+        retryPolicyName: options.retryPolicyName,
+        compactionPolicyName: options.compactionPolicyName,
+        overflowPolicyName: options.overflowPolicyName,
+        branchSummaryPolicyName: options.branchSummaryPolicyName,
+        ...(options.interactionHost === undefined ? {} : { interactionHost: options.interactionHost }),
+        ...(options.enableAgentTasks === undefined ? {} : { enableAgentTasks: options.enableAgentTasks }),
+        ...(options.subagentCommunicationWiring === undefined
+            ? {}
+            : { subagentCommunicationWiring: options.subagentCommunicationWiring }),
+        ...(options.subagentPoolFromSelfInvocation === undefined
+            ? {}
+            : { subagentPoolFromSelfInvocation: options.subagentPoolFromSelfInvocation }),
+    });
+}
+//# sourceMappingURL=agent-session-services.js.map