@agimon-ai/po-mcp 0.0.0-alpha.75 → 0.0.0-alpha.76

package/README.md

@@ -78,13 +78,13 @@ session Cordis root.
 Downstream clients run in-process through `@agimon-ai/po-mcp-proxy`; this adapter does not start its
 Hono server.
 
-## Temporary API-key connections for packages
+## Temporary connections for packages
 
-Trusted session plugins such as po-development can inject `PO_MCP_SESSION_SERVERS_SERVICE`
-from `@agimon-ai/po-mcp/sessionServers`, then call `readPoMcpSessionServers(scoped)` inside
-that injection on their session Cordis root. This is not a model-visible management API and
-not a package-identity boundary. The caller must authorize the destination, bind code-mode
-calls to the owning session, and pass the run's abort signal.
+Trusted session plugins inject `PO_MCP_SERVICE` from `@agimon-ai/po-core/mcp` and call
+`readPoMcp(scoped)` inside that injection on their session Cordis root. `po-mcp` provides
+this portable contract through `PO_MCP_CONTRACT`. This is not a model-visible management
+API or a package-identity boundary. The caller authorizes the destination, binds code-mode
+calls to the owning session, and passes the run's abort signal for establishment.
 
 ```ts
 const connection = await servers.register(
@@ -96,31 +96,39 @@ const connection = await servers.register(
   signal,
 );
 try {
-  // The connected tools join this session's normal MCP surface.
+  // Tools also join this session's normal MCP surface.
+  const tools = connection.snapshot().tools;
+  if (tools.includes('ping')) await connection.invoke('ping', {});
 } finally {
-  await servers.deregister(connection.name);
+  await connection.dispose();
 }
 ```
 
-`register` connects immediately and returns only `{ name, status, tools }`. It accepts HTTP
-or SSE over HTTPS, or HTTP loopback with an explicit port. It rejects URL userinfo,
-fragments, environment interpolation in URLs, reserved names, and all existing names,
-including configured, Help, local-stack, and pending-removal entries. It never replaces
-an existing connection. It is not idempotent.
+`register` connects immediately and returns an identity-owned handle with `name`, live
+`snapshot()`, validated `invoke(tool, args?, signal?)`, and asynchronous idempotent `dispose()`.
+HTTP/SSE no-auth connections require HTTP loopback with an explicit port and never start OAuth.
+API-key connections also accept HTTPS. URL userinfo, fragments, URL environment interpolation,
+reserved names, and all existing or pending-removal names are rejected. Registrations never
+replace a connection. Snapshot and invocation cannot observe a same-name replacement.
 
 API keys use `{ mode: 'bearer', environmentVariable }` or
 `{ mode: 'header', name: 'X-Api-Key', environmentVariable }`. Trusted server code may
-instead supply `value`; raw keys must never enter code-mode arguments, prompts, results,
-or logs. Environment references read only the owning session's admitted environment.
+instead supply `value` programmatically. Do not print keys or add credential-bearing call records.
+Literal keys embedded in `exec` source still persist in saved scripts and transcripts. Environment
+references read only the owning session's admitted environment.
 The key stays in the session overlay, outside proxy configuration, disk caches, and the
 vault. The existing proxy API-key transport pins credentials to the destination origin,
 refuses redirects, and never starts OAuth.
 
-`deregister(name)` removes only this service's exact overlay registration, not a configured,
-Help, local-stack, or same-name replacement. Cleanup remains callable after run cancellation
-or selection changes. Call it in a `finally` when development ends, including failed stop
-paths. Session teardown is a fallback, not dev-finish detection. Failed or cancelled
-registration removes its partial entry and connection; no saved MCP config is changed.
+Establishment cancellation rolls back its partial entry and connection. Once connected, normal
+`exec` completion does not dispose the registration. `dispose()` remains available after run
+cancellation or selection changes. Call it in `finally` when development ends, including failed
+stop paths. Provider shutdown retires handles and closes connections; it does not stop external
+MCP server processes. No saved MCP config is changed.
+
+The existing `@agimon-ai/po-mcp/localServers` and `/sessionServers` APIs remain compatibility
+adapters with their original name-based result and cleanup methods. New consumers use the core
+contract and owned handles.
 
 ## Direct tools and configured identity
 

package/dist/extensions/server.cjs

@@ -3,8 +3,8 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_rolldown_runtime = require("../rolldown-runtime-C0BPl7ul.cjs");
-const require_mcpCatalog = require("../mcpCatalog-BE6bOIBG.cjs");
-const require_sessionServers = require("../sessionServers-BajEiwhs.cjs");
+const require_mcpCatalog = require("../mcpCatalog-Domudw3m.cjs");
+const require_sessionServers = require("../sessionServers-CJNAexGl.cjs");
 const require_projection = require("../projection-DBpXsw0W.cjs");
 let node_crypto = require("node:crypto");
 let node_fs_promises = require("node:fs/promises");
@@ -14,6 +14,7 @@ node_path = require_rolldown_runtime.__toESM(node_path, 1);
 let _agimon_ai_po_config_agentPluginMcp = require("@agimon-ai/po-config/agentPluginMcp");
 let node_os = require("node:os");
 node_os = require_rolldown_runtime.__toESM(node_os, 1);
+let _agimon_ai_po_core_mcpSession = require("@agimon-ai/po-core/mcpSession");
 let _agimon_ai_po_core_help = require("@agimon-ai/po-core/help");
 let _agimon_ai_po_mcp_proxy = require("@agimon-ai/po-mcp-proxy");
 let typebox_value = require("typebox/value");
@@ -27,8 +28,10 @@ let _agimon_ai_po_core_piSettings = require("@agimon-ai/po-core/piSettings");
 let _agimon_ai_po_core_childSession = require("@agimon-ai/po-core/childSession");
 let _agimon_ai_po_core_codemode = require("@agimon-ai/po-core/codemode");
 let _agimon_ai_po_core_headless = require("@agimon-ai/po-core/headless");
+let _agimon_ai_po_core_mcp = require("@agimon-ai/po-core/mcp");
 let _agimon_ai_po_core_mcpStatus = require("@agimon-ai/po-core/mcpStatus");
 let _agimon_ai_po_core_mcpToolResolver = require("@agimon-ai/po-core/mcpToolResolver");
+let _agimon_ai_po_core_platform = require("@agimon-ai/po-core/platform");
 let node_dns_promises = require("node:dns/promises");
 node_dns_promises = require_rolldown_runtime.__toESM(node_dns_promises, 1);
 let node_https = require("node:https");
@@ -2718,6 +2721,11 @@ var McpSession = class {
 	toolRestriction;
 	enabled = true;
 	startup;
+	initialConfiguration() {
+		const configuration = (0, _agimon_ai_po_core_mcpSession.readPoMcpSessionConfig)(this.options.environment ?? {});
+		if (!configuration) throw new Error("MCP session configuration must be supplied by the host.");
+		return configuration;
+	}
 	/** Resolved per tool call, so a registration outlives the container it was made under. */
 	getClientManager = () => this.runtime?.getServices()?.clientManager;
 	constructor(options) {
@@ -2754,7 +2762,7 @@ var McpSession = class {
 	* Returns the servers it seeded, so a caller can report what the session started
 	* with before anything connected.
 	*/
-	async install(configuration = require_mcpCatalog.readSessionConfig(this.options.environment)) {
+	async install(configuration = this.initialConfiguration()) {
 		const generation = ++this.lifecycleGeneration;
 		await this.bindConfiguration(configuration);
 		if (generation !== this.lifecycleGeneration) return this.catalog.toSnapshot();
@@ -2929,7 +2937,7 @@ var McpSession = class {
 		if (!this.enabled || this.configuredServerNames().length === 0) return;
 		const [{ MemoryTokenStore }, { McpRuntimeOwner }, { VaultTokenStore }] = await Promise.all([
 			import("@agimon-ai/po-mcp-proxy"),
-			Promise.resolve().then(() => require("../mcpCatalog-BE6bOIBG.cjs")).then((n) => n.mcpRuntime_exports),
+			Promise.resolve().then(() => require("../mcpCatalog-Domudw3m.cjs")).then((n) => n.mcpRuntime_exports),
 			Promise.resolve().then(() => vaultTokenStore_exports)
 		]);
 		if (generation !== this.lifecycleGeneration) return;
@@ -3340,6 +3348,7 @@ var McpSession = class {
 		if (change.state !== "connecting" && change.state !== "needs-auth") this.authorizationUrls.delete(change.serverName);
 		const runtime = this.runtime;
 		const services = runtime?.getServices();
+		const entry = this.options.sessionServers?.().get(change.serverName);
 		(change.state === "connected" && services ? services.clientManager.ensureConnected(change.serverName).then((connection) => connection.listTools()) : Promise.resolve([])).then((tools) => ({
 			tools,
 			error: void 0
@@ -3347,7 +3356,7 @@ var McpSession = class {
 			tools: [],
 			error: `Could not discover tools for MCP server "${change.serverName}".`
 		})).then(({ tools, error }) => {
-			if (generation !== this.lifecycleGeneration || !runtime?.isCurrent(services) || this.disconnectedServers.has(change.serverName)) return;
+			if (generation !== this.lifecycleGeneration || !runtime?.isCurrent(services) || this.disconnectedServers.has(change.serverName) || this.options.sessionServers?.().get(change.serverName) !== entry) return;
 			if (error) this.catalog.addDiagnostic(error);
 			this.catalog.applyStateChange(error ? {
 				...change,
@@ -3448,11 +3457,10 @@ function createMcpSessionApi(source, countTokens) {
 }
 //#endregion
 //#region src/services/serverRuntime/index.ts
-async function sessionConfiguration(execution, workspaceRoot) {
+async function sessionConfiguration(execution, workspaceRoot, loaded) {
 	if (workspaceRoot !== void 0) {
-		const loaded = (0, _agimon_ai_po_config_harnessStore.loadHarnessState)({ ...execution.environment });
-		const projection = loaded.state.mcpProjection;
-		if (loaded.filePath && loaded.state.root === workspaceRoot && execution.repoRoot === workspaceRoot && loaded.state.mcp && loaded.state.majorMode === execution.selection.majorMode && JSON.stringify(loaded.state.domains) === JSON.stringify(execution.selection.domains) && JSON.stringify(loaded.state.layers) === JSON.stringify(execution.selection.activeLayers) && (0, _agimon_ai_po_core_mcpProjection.isPoMcpProjection)(projection) && projection.repoRoot === workspaceRoot) return require_projection.mcpSessionConfigFromProjection(projection, execution.cwd);
+		const projection = loaded?.state.mcpProjection;
+		if (loaded?.filePath && loaded.state.root === workspaceRoot && execution.repoRoot === workspaceRoot && loaded.state.mcp && loaded.state.majorMode === execution.selection.majorMode && JSON.stringify(loaded.state.domains) === JSON.stringify(execution.selection.domains) && JSON.stringify(loaded.state.layers) === JSON.stringify(execution.selection.activeLayers) && (0, _agimon_ai_po_core_mcpProjection.isPoMcpProjection)(projection) && projection.repoRoot === workspaceRoot) return require_projection.mcpSessionConfigFromProjection(projection, execution.cwd);
 		return {
 			enabled: false,
 			repoRoot: execution.cwd,
@@ -3462,8 +3470,11 @@ async function sessionConfiguration(execution, workspaceRoot) {
 	}
 	return require_mcpCatalog.readSessionConfig(execution.environment, execution.cwd);
 }
-function createMcpServerRuntime(environment = {}, workspaceRoot, getResolver, publishFile, assertPackageActive, getVault) {
+function createMcpServerRuntime(environment = {}, workspaceRoot, getResolver, publishFile, assertPackageActive, getVault, getFs) {
 	let active;
+	let stopActive;
+	let disposed = false;
+	let disposal;
 	let currentSelection;
 	let staleSelection = false;
 	let cleanup;
@@ -3486,6 +3497,7 @@ function createMcpServerRuntime(environment = {}, workspaceRoot, getResolver, pu
 		sessionServers: () => sessionServers
 	});
 	const assertAvailable = () => {
+		if (disposed) throw new Error("The MCP runtime has been disposed.");
 		if (!active) throw new Error("The MCP runtime has not started yet.");
 		if (staleSelection) throw new Error("The MCP projection is stale for the current selection.");
 	};
@@ -3494,6 +3506,11 @@ function createMcpServerRuntime(environment = {}, workspaceRoot, getResolver, pu
 		session,
 		entries: sessionServers,
 		environment,
+		invoke: (server, tool, args, signal) => invoke({
+			server,
+			tool,
+			arguments: args
+		}, signal),
 		assertAdmitted(sessionId, signal) {
 			assertPackageActive?.();
 			assertAvailable();
@@ -3533,11 +3550,13 @@ function createMcpServerRuntime(environment = {}, workspaceRoot, getResolver, pu
 			}
 			if (active !== execution) return;
 			const resolver = getResolver?.();
-			const loaded = workspaceRoot ? (0, _agimon_ai_po_config_harnessStore.loadHarnessState)({ ...execution.environment }) : void 0;
+			const fs = getFs?.();
+			if (workspaceRoot && !fs) throw new Error("MCP session configuration requires the host filesystem.");
+			const loaded = workspaceRoot && fs ? await (0, _agimon_ai_po_config_harnessStore.loadHarnessStateAsync)(fs, { ...execution.environment }, (0, _agimon_ai_po_core_platform.withAbortSignal)(lifetime.signal, _agimon_ai_po_core_platform.BACKGROUND_CONTEXT)) : void 0;
 			const authorized = workspaceRoot && loaded?.filePath && loaded.state.root === workspaceRoot && execution.repoRoot === workspaceRoot && loaded.state.mcp && (0, _agimon_ai_po_core_mcpProjection.isPoMcpProjection)(loaded.state.mcpProjection) && loaded.state.mcpProjection.repoRoot === workspaceRoot && loaded.state.mcpProjection.enabled;
 			if (!resolver || !authorized) {
 				if (active === execution && selection === currentSelection) {
-					if (workspaceRoot === void 0 || JSON.stringify(execution.selection.domains) === JSON.stringify(selection.domains)) await session.reconfigure(await sessionConfiguration(execution, workspaceRoot), execution.cwd, execution.repoRoot);
+					if (workspaceRoot === void 0 || JSON.stringify(execution.selection.domains) === JSON.stringify(selection.domains)) await session.reconfigure(await sessionConfiguration(execution, workspaceRoot, loaded), execution.cwd, execution.repoRoot);
 					staleSelection = workspaceRoot !== void 0 && JSON.stringify(execution.selection.domains) !== JSON.stringify(selection.domains);
 				}
 				return;
@@ -3556,8 +3575,13 @@ function createMcpServerRuntime(environment = {}, workspaceRoot, getResolver, pu
 				await candidate.cleanup();
 				throw error;
 			}
-		}).then(() => {
-			for (const name of sessionServers.keys()) if (session.hasConfiguredServer(name)) sessionServers.delete(name);
+		}).then(async () => {
+			for (const [name, entry] of sessionServers) {
+				if (!session.hasConfiguredServer(name)) continue;
+				sessionServers.delete(name);
+				delete entry.apiKey;
+				await entry.tokenStore.clear(name);
+			}
 			sessionTools.refresh();
 		}).catch(async (error) => {
 			if (active !== execution || selection !== currentSelection) return;
@@ -3589,6 +3613,7 @@ function createMcpServerRuntime(environment = {}, workspaceRoot, getResolver, pu
 	const activity = {
 		name: "po-mcp-runtime",
 		async start(execution) {
+			if (disposed) throw new Error("The MCP runtime has been disposed.");
 			active = execution;
 			lifetime = new AbortController();
 			currentSelection = execution.selection;
@@ -3628,45 +3653,53 @@ function createMcpServerRuntime(environment = {}, workspaceRoot, getResolver, pu
 			loadTokenizer().then(() => {
 				if (active === execution) publish();
 			});
+			let stopping;
+			const stop = () => {
+				stopping ??= (async () => {
+					stopPublishing();
+					if (active !== execution) return;
+					lifetime.abort();
+					setHelp();
+					testServers.clear();
+					active = void 0;
+					currentSelection = void 0;
+					staleSelection = true;
+					sessionTools.refresh();
+					authorizing.clear();
+					await transition;
+					const retiredCleanup = cleanup;
+					cleanup = void 0;
+					try {
+						await session.dispose();
+					} finally {
+						await session.install({
+							enabled: false,
+							repoRoot: execution.cwd,
+							stagingDirectory: execution.cwd
+						});
+						await retiredCleanup?.();
+						execution.client.setStatus(MCP_STATUS_KEY, void 0);
+						execution.client.setStatus(MCP_SESSION_AUTH_STATUS_KEY, void 0);
+						execution.client.setStatus(_agimon_ai_po_core_contextApi.CONTEXT_TOOL_WARNINGS_STATUS_KEY, void 0);
+					}
+				})().finally(async () => {
+					if (stopActive === stop) stopActive = void 0;
+					await testServers.settleRemovals();
+				});
+				return stopping;
+			};
+			stopActive = stop;
 			try {
 				await refresh(execution, execution.selection);
-				publish();
+				if (active === execution) publish();
 			} catch (error) {
-				await execution.client.notify({
+				if (active === execution) await execution.client.notify({
 					title: "Po MCP unavailable",
 					body: error instanceof Error ? error.message : String(error),
 					level: "warning"
 				});
 			}
-			return async () => {
-				stopPublishing();
-				if (active !== execution) return;
-				lifetime.abort();
-				setHelp();
-				sessionServers.clear();
-				testServers.clear();
-				active = void 0;
-				currentSelection = void 0;
-				staleSelection = true;
-				sessionTools.refresh();
-				authorizing.clear();
-				await transition;
-				const retiredCleanup = cleanup;
-				cleanup = void 0;
-				try {
-					await session.dispose();
-				} finally {
-					await session.install({
-						enabled: false,
-						repoRoot: execution.cwd,
-						stagingDirectory: execution.cwd
-					});
-					await retiredCleanup?.();
-					execution.client.setStatus(MCP_STATUS_KEY, void 0);
-					execution.client.setStatus(MCP_SESSION_AUTH_STATUS_KEY, void 0);
-					execution.client.setStatus(_agimon_ai_po_core_contextApi.CONTEXT_TOOL_WARNINGS_STATUS_KEY, void 0);
-				}
-			};
+			return stop;
 		}
 	};
 	const invoke = async (parameters, signal) => {
@@ -3769,6 +3802,27 @@ function createMcpServerRuntime(environment = {}, workspaceRoot, getResolver, pu
 		testServerNamespace: testServers.namespace,
 		localServers: testServers.localServers,
 		sessionServers: testServers.sessionServers,
+		mcp: testServers.mcp,
+		dispose() {
+			if (disposal) return disposal;
+			disposed = true;
+			lifetime.abort();
+			testServers.retire();
+			const stop = stopActive;
+			disposal = (async () => {
+				try {
+					if (stop) await stop();
+					else {
+						await transition;
+						await session.dispose();
+					}
+				} finally {
+					sessionTools.dispose();
+					await testServers.settleRemovals();
+				}
+			})();
+			return disposal;
+		},
 		isHelpActive: () => helpActive,
 		onHelpChange(listener) {
 			helpListeners.add(listener);
@@ -3797,17 +3851,24 @@ const createMcpServerRoot = (context) => {
 		host: () => appHost,
 		signal: context?.signal
 	});
-	const runtime = createMcpServerRuntime(context?.agent?.context?.environment, context?.host.context.workspaceRoot, () => resolver, publishFile, () => appHost?.assertActive("@agimon-ai/po-mcp"), () => serverScope?.resolve(_agimon_ai_po_vault.PO_VAULT_CONTRACT));
+	const runtime = createMcpServerRuntime(context?.agent?.context?.environment, context?.host.context.workspaceRoot, () => resolver, publishFile, () => appHost?.assertActive("@agimon-ai/po-mcp"), () => serverScope?.resolve(_agimon_ai_po_vault.PO_VAULT_CONTRACT), () => context && (0, _agimon_ai_po_core_platform.readPoFs)(context.context));
 	const generation = `${context?.agent?.context?.sessionId ?? crypto.randomUUID()}:mcp-server`;
 	const { session } = runtime;
 	const tools = [...runtime.tools, ...createFileTransferTools(context)];
 	const apps = createMcpAppsService(runtime.sessionTools, () => appHost, context?.signal);
 	const namespace = createMcpNamespace(runtime.sessionTools, hostContext?.sessionId);
 	const mountSession = (cordis) => {
-		cordis.inject([_agimon_ai_po_core_serverPlugin.PO_SERVER_SCOPE_SERVICE], (scoped) => {
+		cordis.inject([_agimon_ai_po_core_serverPlugin.PO_SERVER_SCOPE_SERVICE], async (scoped) => {
 			serverScope = (0, _agimon_ai_po_core_serverPlugin.requirePoServerScope)(scoped);
-			return () => {
+			const withdraw = await serverScope.provide(_agimon_ai_po_core_mcp.PO_MCP_CONTRACT, runtime.mcp);
+			return async () => {
 				serverScope = void 0;
+				const closing = runtime.dispose();
+				try {
+					await withdraw();
+				} finally {
+					await closing;
+				}
 			};
 		});
 		cordis.inject([_agimon_ai_po_core_codemode.PO_CODEMODE_SERVICE], (scoped) => {
@@ -3899,7 +3960,7 @@ const createMcpServerRoot = (context) => {
 			provider.provide(_agimon_ai_po_core_childSession.PO_CHILD_SESSION_MCP_TOOL_SERVICE, runtime.childTool);
 			provider.provide(require_sessionServers.PO_MCP_LOCAL_SERVERS_SERVICE, runtime.localServers);
 			provider.provide(require_sessionServers.PO_MCP_SESSION_SERVERS_SERVICE, runtime.sessionServers);
-			return () => runtime.sessionTools.dispose();
+			return () => runtime.dispose();
 		});
 	};
 	return {
@@ -3909,7 +3970,13 @@ const createMcpServerRoot = (context) => {
 		},
 		activities: runtime.activities,
 		services: [mountMcpHeadlessTools(tools), mountSession],
-		onDispose: apps.dispose
+		onDispose: async () => {
+			try {
+				await runtime.dispose();
+			} finally {
+				apps.dispose();
+			}
+		}
 	};
 };
 //#endregion