@xopcai/xopc 0.0.387 → 0.0.389

package/dist/src/agent/mcp/connection-drafts.js

@@ -0,0 +1,278 @@
+import { McpServerSchema, init_schema } from "../../config/schema.js";
+import { getWorkspacePath } from "../../config/workspace-path-helpers.js";
+import { isManagedConnectorServer } from "../../connectors/materialize.js";
+import { createNativeMcpCredentials } from "./credential-store.js";
+import { loadMergedMcpConfig } from "./config.js";
+import { discoverMcpTools } from "./tool-catalog.js";
+import { cancelMcpAuthorization, getMcpAuthorization, probeMcpConnection, startMcpAuthorization, submitMcpRedirect } from "./connection-setup.js";
+import { createHash, randomUUID } from "node:crypto";
+//#region src/agent/mcp/connection-drafts.ts
+init_schema();
+const TTL_MS = 10 * 6e4;
+function canonical(value) {
+	if (Array.isArray(value)) return value.map(canonical);
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).filter(([, child]) => child !== void 0).sort(([a], [b]) => a.localeCompare(b)).map(([key, child]) => [key, canonical(child)]));
+	return value;
+}
+function mcpConfigRevision(value) {
+	return createHash("sha256").update(JSON.stringify(canonical(value)) ?? "null").digest("hex");
+}
+var McpDraftError = class extends Error {
+	constructor(status, message) {
+		super(message);
+		this.status = status;
+	}
+};
+/** Unsaved configuration and OAuth state belong to one principal and never enter the live registry. */
+var McpConnectionDrafts = class {
+	completed = /* @__PURE__ */ new Map();
+	drafts = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.options = options;
+	}
+	async create(owner, input) {
+		const current = this.options.readConfig();
+		if (!/^[a-zA-Z0-9_-]+$/.test(input.serverId) || input.sourceServerId && input.sourceServerId !== input.serverId) throw new McpDraftError(400, "Invalid or changed MCP server ID.");
+		const source = Object.hasOwn(current.mcp?.servers ?? {}, input.serverId) ? current.mcp?.servers?.[input.serverId] : void 0;
+		if (input.sourceServerId && (!source || isManagedConnectorServer(source))) throw new McpDraftError(409, "The original custom server no longer exists.");
+		if (input.sourceServerId && mcpConfigRevision(source) !== mcpConfigRevision(input.expectedServer)) throw new McpDraftError(409, "The original configuration changed. Reload before testing.");
+		this.assertAvailable(current, input.serverId, input.sourceServerId);
+		const parsed = McpServerSchema.safeParse(input.server);
+		if (!parsed.success) throw new McpDraftError(400, "Invalid MCP configuration.");
+		const revision = mcpConfigRevision(source);
+		const server = structuredClone(parsed.data);
+		for (const internal of [
+			"xopcConnector",
+			"xopcPlugin",
+			"xopcOAuthCredentialId",
+			"xopcConnectionCheck"
+		]) delete server[internal];
+		const workspace = getWorkspacePath(current) || process.cwd();
+		const config = structuredClone(current);
+		config.mcp = { servers: { [input.serverId]: {
+			...server,
+			enabled: true
+		} } };
+		const credentials = await createNativeMcpCredentials(true);
+		if (this.drafts.size >= 100 || [...this.drafts.values()].filter((draft) => draft.owner === owner).length >= 8) throw new McpDraftError(429, "Too many unsaved MCP connection tests.");
+		const id = randomUUID();
+		const timer = setTimeout(() => {
+			const draft = this.drafts.get(id);
+			if (draft && !draft.committing) this.dispose(draft);
+		}, TTL_MS);
+		timer.unref();
+		const draft = {
+			id,
+			owner,
+			serverId: input.serverId,
+			sourceServerId: input.sourceServerId,
+			revision,
+			workspace,
+			server,
+			config,
+			credentials,
+			controller: new AbortController(),
+			timer,
+			expiresAt: Date.now() + TTL_MS,
+			running: false,
+			committing: false
+		};
+		this.drafts.set(id, draft);
+		return {
+			id,
+			serverId: draft.serverId,
+			expiresAt: draft.expiresAt
+		};
+	}
+	async probe(owner, id) {
+		const draft = this.get(owner, id);
+		this.assertIdle(draft);
+		draft.authorizationId = void 0;
+		draft.running = true;
+		draft.probe = void 0;
+		draft.checkedAt = void 0;
+		try {
+			const result = await probeMcpConnection(draft.config, draft.workspace, draft.serverId, {
+				credentials: draft.credentials,
+				signal: draft.controller.signal
+			});
+			this.get(owner, id);
+			draft.probe = result;
+			if (result.state === "connected") draft.checkedAt = (/* @__PURE__ */ new Date()).toISOString();
+			return result;
+		} finally {
+			draft.running = false;
+		}
+	}
+	authorize(owner, id) {
+		const draft = this.get(owner, id);
+		this.assertIdle(draft);
+		if (draft.authorizationId) cancelMcpAuthorization(draft.authorizationId, owner);
+		draft.probe = void 0;
+		const attempt = startMcpAuthorization(draft.config, draft.workspace, draft.serverId, owner, {
+			credentials: draft.credentials,
+			authorizationScope: draft.id
+		});
+		draft.authorizationId = attempt.id;
+		return attempt;
+	}
+	authorization(owner, id) {
+		const draft = this.get(owner, id);
+		const result = draft.authorizationId && getMcpAuthorization(draft.authorizationId, owner, draft.config);
+		if (!result) throw new McpDraftError(404, "Draft authorization not found.");
+		if (result.state === "connected" && draft.probe?.state !== "connected") {
+			draft.probe = {
+				state: "connected",
+				toolCount: result.toolCount
+			};
+			draft.checkedAt = (/* @__PURE__ */ new Date()).toISOString();
+		}
+		return result;
+	}
+	redirect(owner, id, url) {
+		const draft = this.get(owner, id);
+		if (!draft.authorizationId || !submitMcpRedirect(draft.authorizationId, owner, url, draft.config)) throw new McpDraftError(400, "The callback address does not match this draft authorization.");
+	}
+	cancelAuthorization(owner, id) {
+		const draft = this.get(owner, id);
+		if (draft.committing) throw new McpDraftError(409, "This draft is being saved.");
+		if (draft.running) throw new McpDraftError(409, "A connection test is still running.");
+		if (draft.authorizationId) cancelMcpAuthorization(draft.authorizationId, owner);
+		draft.authorizationId = void 0;
+		draft.probe = void 0;
+	}
+	async tools(owner, id) {
+		const draft = this.get(owner, id);
+		this.assertIdle(draft);
+		if (draft.probe?.state !== "connected") throw new McpDraftError(409, "Test the connection first.");
+		draft.running = true;
+		try {
+			const tools = await discoverMcpTools(draft.config, draft.workspace, draft.serverId, {
+				credentials: draft.credentials,
+				signal: draft.controller.signal
+			});
+			this.get(owner, id);
+			return tools;
+		} finally {
+			draft.running = false;
+		}
+	}
+	/** Caller serializes this with other Gateway config writes. Only this entry is merged into the latest config. */
+	async commit(owner, id, enable = false) {
+		const completed = this.completed.get(id);
+		if (completed?.owner === owner) {
+			if (completed.enable !== enable) throw new McpDraftError(409, "This test has already been committed with different settings.");
+			return {
+				serverId: completed.serverId,
+				...completed.reloadRequired ? { reloadRequired: true } : {}
+			};
+		}
+		const draft = this.get(owner, id);
+		this.assertIdle(draft);
+		if (draft.authorizationId) this.authorization(owner, id);
+		if (draft.probe?.state !== "connected") throw new McpDraftError(409, "A successful connection test is required before saving.");
+		const current = this.options.readConfig();
+		if (mcpConfigRevision(current.mcp?.servers?.[draft.serverId]) !== draft.revision || (getWorkspacePath(current) || process.cwd()) !== draft.workspace) throw new McpDraftError(409, "Configuration changed after the test. Reload and test again.");
+		this.assertAvailable(current, draft.serverId, draft.sourceServerId);
+		draft.committing = true;
+		let alias;
+		let durable;
+		let published = false;
+		try {
+			const server = structuredClone(draft.server);
+			if (enable) server.enabled = true;
+			if (server.url) {
+				const state = await draft.credentials.forServer(draft.serverId, server.url).load();
+				const candidateAlias = `mcp_draft_${randomUUID().replaceAll("-", "")}`;
+				durable = await createNativeMcpCredentials();
+				await durable.forServer(candidateAlias, server.url).save(state?.tokens ? {
+					...state,
+					codeVerifier: void 0,
+					oauthState: void 0
+				} : { serverUrl: server.url });
+				alias = candidateAlias;
+				server.xopcOAuthCredentialId = alias;
+			}
+			server.xopcConnectionCheck = {
+				checkedAt: draft.checkedAt,
+				toolCount: draft.probe.toolCount ?? 0,
+				revision: mcpConfigRevision(server)
+			};
+			const latest = this.options.readConfig();
+			if (mcpConfigRevision(latest.mcp?.servers?.[draft.serverId]) !== draft.revision || (getWorkspacePath(latest) || process.cwd()) !== draft.workspace) throw new McpDraftError(409, "Configuration changed while preparing the save. Test again.");
+			this.assertAvailable(latest, draft.serverId, draft.sourceServerId);
+			const next = structuredClone(latest);
+			next.mcp = {
+				...next.mcp,
+				servers: {
+					...next.mcp?.servers,
+					[draft.serverId]: server
+				}
+			};
+			const result = await this.options.saveConfig(next, structuredClone(latest));
+			published = result.persisted === true || alias !== void 0 && this.options.readConfig().mcp?.servers?.[draft.serverId]?.xopcOAuthCredentialId === alias;
+			if (result.conflict) throw new McpDraftError(409, "Configuration changed before writing. Reload and test again.");
+			if (!result.saved && !result.persisted) throw new McpDraftError(500, "Could not save MCP configuration. Retry or reload the current configuration.");
+			const reloadRequired = !result.saved;
+			published = true;
+			const timer = setTimeout(() => this.completed.delete(id), TTL_MS);
+			timer.unref();
+			this.completed.set(id, {
+				owner,
+				enable,
+				serverId: draft.serverId,
+				reloadRequired,
+				timer
+			});
+			this.dispose(draft);
+			return {
+				serverId: draft.serverId,
+				...reloadRequired ? { reloadRequired: true } : {}
+			};
+		} finally {
+			draft.committing = false;
+			if (alias && this.options.readConfig().mcp?.servers?.[draft.serverId]?.xopcOAuthCredentialId === alias) published = true;
+			if (!published && alias && durable && draft.server.url) durable.remove(alias, draft.server.url);
+			if (this.drafts.has(id) && draft.expiresAt <= Date.now()) this.dispose(draft);
+		}
+	}
+	remove(owner, id) {
+		const draft = this.drafts.get(id);
+		if (!draft || draft.owner !== owner) return;
+		if (draft.committing) throw new McpDraftError(409, "This draft is being saved.");
+		this.dispose(draft);
+	}
+	close() {
+		for (const draft of this.drafts.values()) this.dispose(draft);
+		for (const item of this.completed.values()) clearTimeout(item.timer);
+		this.completed.clear();
+	}
+	get(owner, id) {
+		const draft = this.drafts.get(id);
+		if (!draft || draft.owner !== owner) throw new McpDraftError(404, "MCP draft not found or expired.");
+		if (draft.expiresAt <= Date.now() && !draft.committing) {
+			this.dispose(draft);
+			throw new McpDraftError(404, "MCP draft expired.");
+		}
+		return draft;
+	}
+	assertIdle(draft) {
+		const auth = draft.authorizationId && getMcpAuthorization(draft.authorizationId, draft.owner, draft.config);
+		if (draft.running || draft.committing || auth && (auth.state === "starting" || auth.state === "authorizing")) throw new McpDraftError(409, "Another draft operation is still running.");
+	}
+	assertAvailable(config, id, sourceId) {
+		const all = loadMergedMcpConfig({
+			cfg: config,
+			workspaceDir: getWorkspacePath(config) || process.cwd()
+		}).config.mcpServers;
+		if (Object.keys(all).some((other) => other !== sourceId && other.replaceAll("-", "_") === id.replaceAll("-", "_"))) throw new McpDraftError(409, "The MCP server ID is already in use.");
+	}
+	dispose(draft) {
+		this.drafts.delete(draft.id);
+		clearTimeout(draft.timer);
+		draft.controller.abort();
+		if (draft.authorizationId) cancelMcpAuthorization(draft.authorizationId, draft.owner);
+	}
+};
+//#endregion
+export { McpConnectionDrafts, McpDraftError, mcpConfigRevision };

package/dist/src/agent/mcp/connection-setup.d.ts

@@ -1,10 +1,11 @@
 import type { Config } from '../../config/schema.js';
+import { type McpSessionOptions } from './tool-catalog.js';
 export type McpConnectionProbe = {
     state: 'connected' | 'oauth_required' | 'token_required' | 'error';
     toolCount?: number;
     error?: string;
 };
-export declare function probeMcpConnection(config: Config, workspace: string, serverId: string): Promise<McpConnectionProbe>;
+export declare function probeMcpConnection(config: Config, workspace: string, serverId: string, options?: McpSessionOptions): Promise<McpConnectionProbe>;
 export type McpAuthorization = {
     id: string;
     serverId: string;
@@ -15,7 +16,9 @@ export type McpAuthorization = {
     error?: string;
 };
 /** A UI bridge to native pi's login command; no host-owned OAuth client or token store. */
-export declare function startMcpAuthorization(config: Config, workspace: string, serverId: string, owner: string): McpAuthorization;
+export declare function startMcpAuthorization(config: Config, workspace: string, serverId: string, owner: string, options?: McpSessionOptions & {
+    authorizationScope?: string;
+}): McpAuthorization;
 export declare function getMcpAuthorization(id: string, owner: string, config: Config): McpAuthorization | undefined;
 export declare function cancelMcpAuthorization(id: string, owner: string): boolean;
 export declare function submitMcpRedirect(id: string, owner: string, redirectUrl: string, config: Config): boolean;

package/dist/src/agent/mcp/connection-setup.js

@@ -71,11 +71,11 @@ async function advertisesOAuth(config, workspace, serverId) {
 	const legacy = await metadata(new URL("/.well-known/oauth-authorization-server", url));
 	return Boolean(legacy && legacy.issuer === url.origin && typeof legacy.authorization_endpoint === "string" && typeof legacy.token_endpoint === "string");
 }
-async function probeMcpConnection(config, workspace, serverId) {
+async function probeMcpConnection(config, workspace, serverId, options) {
 	try {
 		return {
 			state: "connected",
-			toolCount: (await discoverMcpTools(config, workspace, serverId)).length
+			toolCount: (await discoverMcpTools(config, workspace, serverId, options)).length
 		};
 	} catch (error) {
 		if (error instanceof McpAuthenticationRequiredError) try {
@@ -117,15 +117,17 @@ function cancel(attempt) {
 	}
 }
 /** A UI bridge to native pi's login command; no host-owned OAuth client or token store. */
-function startMcpAuthorization(config, workspace, serverId, owner) {
+function startMcpAuthorization(config, workspace, serverId, owner, options) {
 	const server = config.mcp?.servers?.[serverId];
 	if (!server?.url || server.enabled === false || isManagedConnectorServer(server) && server.xopcConnector.enabled === false) throw new Error("An enabled HTTP MCP server is required.");
 	httpUrl(server.url);
 	if (server.auth || Object.keys(server.headers ?? {}).some((name) => name.toLowerCase() === "authorization")) throw new Error("This server uses configured credentials. Remove Authorization before using OAuth.");
-	for (const attempt of attempts.values()) if (attempt.owner === owner && attempt.result.serverId === serverId) cancel(attempt);
+	const scope = options?.authorizationScope ?? serverId;
+	for (const attempt of attempts.values()) if (attempt.owner === owner && attempt.scope === scope) cancel(attempt);
 	if (attempts.size >= 100) throw new Error("Too many pending sign-ins. Try again later.");
 	const attempt = {
 		owner,
+		scope,
 		fingerprint: fingerprint(config, serverId),
 		controller: new AbortController(),
 		result: {
@@ -159,7 +161,7 @@ function startMcpAuthorization(config, workspace, serverId, owner) {
 				attempt.dispose = () => signal?.removeEventListener("abort", stop);
 			});
 		}
-	}).then((tools) => {
+	}, options).then((tools) => {
 		if (!attempt.controller.signal.aborted) {
 			attempt.result.state = "connected";
 			attempt.result.toolCount = tools.length;

package/dist/src/agent/mcp/credential-store.d.ts

@@ -0,0 +1,6 @@
+import type { McpExtensionOptions } from '@earendil-works/pi-coding-agent';
+export type NativeMcpCredentials = NonNullable<McpExtensionOptions['credentials']>;
+/** Use pi's own stores; never change PI_CODING_AGENT_DIR for an individual connection. */
+export declare function createNativeMcpCredentials(memory?: boolean): Promise<NativeMcpCredentials>;
+/** Credential identity may change on commit without changing the public tool namespace. */
+export declare function routeNativeMcpCredentials(store: NativeMcpCredentials, aliases: ReadonlyMap<string, string>): NativeMcpCredentials;

package/dist/src/agent/mcp/credential-store.js

@@ -0,0 +1,24 @@
+//#region src/agent/mcp/credential-store.ts
+/** Use pi's own stores; never change PI_CODING_AGENT_DIR for an individual connection. */
+async function createNativeMcpCredentials(memory = false) {
+	const root = import.meta.resolve("@earendil-works/pi-coding-agent");
+	const { McpOAuthCredentialStore } = await import(new URL("./extensions/mcp/oauth.js", root).href);
+	if (!memory) return new McpOAuthCredentialStore();
+	const { InMemoryAuthStorageBackend } = await import(new URL("./core/auth-storage.js", root).href);
+	return new McpOAuthCredentialStore(new InMemoryAuthStorageBackend());
+}
+/** Credential identity may change on commit without changing the public tool namespace. */
+function routeNativeMcpCredentials(store, aliases) {
+	const forServer = store.forServer.bind(store), tokens = store.tokens.bind(store), remove = store.remove.bind(store);
+	store.forServer = (name, url) => forServer(aliases.get(name) ?? name, url);
+	store.tokens = (name, url) => tokens(aliases.get(name) ?? name, url);
+	store.remove = (name, url) => {
+		const alias = aliases.get(name);
+		if (!alias) return remove(name, url);
+		forServer(alias, url).save({ serverUrl: url });
+		return true;
+	};
+	return store;
+}
+//#endregion
+export { createNativeMcpCredentials, routeNativeMcpCredentials };

package/dist/src/agent/mcp/native-mcp.d.ts

@@ -1,6 +1,11 @@
 import { type LoadedMcpConfig } from '@earendil-works/pi-coding-agent';
 import { type Config } from '../../config/schema.js';
+import { type NativeMcpCredentials } from './credential-store.js';
 /** One process-wide pi directory: sessions share native OAuth credentials, never swap roots per turn. */
 export declare function getNativePiAgentDir(): string;
+export type NativeMcpConfig = LoadedMcpConfig & {
+    credentials?: NativeMcpCredentials;
+    credentialAliases?: Record<string, string>;
+};
 /** Only projects host configuration and secret references; all MCP execution belongs to pi. */
-export declare function prepareNativeMcpConfig(config: Config, workspaceDir: string): Promise<LoadedMcpConfig>;
+export declare function prepareNativeMcpConfig(config: Config, workspaceDir: string): Promise<NativeMcpConfig>;

package/dist/src/agent/mcp/native-mcp.js

@@ -1,6 +1,7 @@
 import { init_paths_state, resolveStateDir } from "../../config/paths-state.js";
 import { McpServerSchema, init_schema } from "../../config/schema.js";
 import { resolveConnectorSecretReferences } from "../../connectors/secret-store.js";
+import { createNativeMcpCredentials, routeNativeMcpCredentials } from "./credential-store.js";
 import { loadMergedMcpConfig } from "./config.js";
 import { join } from "node:path";
 import { mkdirSync } from "node:fs";
@@ -67,6 +68,11 @@ async function prepareNativeMcpConfig(config, workspaceDir) {
 			scope: "extension"
 		});
 	}
+	const aliases = new Map(Object.entries(config.mcp?.servers ?? {}).filter(([, value]) => typeof value.xopcOAuthCredentialId === "string").map(([name, value]) => [name, value.xopcOAuthCredentialId]));
+	if (aliases.size) {
+		result.credentials = routeNativeMcpCredentials(await createNativeMcpCredentials(), aliases);
+		result.credentialAliases = Object.fromEntries(aliases);
+	}
 	return result;
 }
 //#endregion

package/dist/src/agent/mcp/tool-catalog.d.ts

@@ -1,4 +1,5 @@
 import type { Config } from '../../config/schema.js';
+import type { NativeMcpCredentials } from './credential-store.js';
 export type McpCatalogTool = {
     name: string;
     description: string;
@@ -12,7 +13,11 @@ export type McpLoginInteraction = {
     onAuthorizationUrl: (url: string) => void;
     requestRedirectUrl: (signal?: AbortSignal) => Promise<string | undefined>;
 };
+export type McpSessionOptions = {
+    credentials?: NativeMcpCredentials;
+    signal?: AbortSignal;
+};
 /** A short-lived native session discovers tools without making a model request. */
-export declare function discoverMcpTools(config: Config, workspaceDir: string, serverId: string): Promise<McpCatalogTool[]>;
+export declare function discoverMcpTools(config: Config, workspaceDir: string, serverId: string, options?: McpSessionOptions): Promise<McpCatalogTool[]>;
 /** Native pi owns PKCE, registration, callbacks, token storage and refresh. */
-export declare function signInNativeMcp(config: Config, workspaceDir: string, serverId: string, interaction: McpLoginInteraction): Promise<McpCatalogTool[]>;
+export declare function signInNativeMcp(config: Config, workspaceDir: string, serverId: string, interaction: McpLoginInteraction, options?: McpSessionOptions): Promise<McpCatalogTool[]>;

package/dist/src/agent/mcp/tool-catalog.js

@@ -6,15 +6,19 @@ import { DefaultResourceLoader, ModelRuntime, SessionManager, SettingsManager, c
 //#region src/agent/mcp/tool-catalog.ts
 var McpAuthenticationRequiredError = class extends Error {};
 /** A short-lived native session discovers tools without making a model request. */
-async function discoverMcpTools(config, workspaceDir, serverId) {
-	return runNativeMcpSession(config, workspaceDir, serverId);
+async function discoverMcpTools(config, workspaceDir, serverId, options) {
+	return runNativeMcpSession(config, workspaceDir, serverId, void 0, options);
 }
 /** Native pi owns PKCE, registration, callbacks, token storage and refresh. */
-async function signInNativeMcp(config, workspaceDir, serverId, interaction) {
-	return runNativeMcpSession(config, workspaceDir, serverId, interaction);
+async function signInNativeMcp(config, workspaceDir, serverId, interaction, options) {
+	return runNativeMcpSession(config, workspaceDir, serverId, interaction, options);
 }
-async function runNativeMcpSession(config, workspaceDir, serverId, interaction) {
-	const entry = (await prepareNativeMcpConfig(config, workspaceDir)).servers.find((server) => server.name === serverId);
+async function runNativeMcpSession(config, workspaceDir, serverId, interaction, options) {
+	const signal = interaction?.signal ?? options?.signal;
+	signal?.throwIfAborted();
+	const loaded = await prepareNativeMcpConfig(config, workspaceDir);
+	signal?.throwIfAborted();
+	const entry = loaded.servers.find((server) => server.name === serverId);
 	if (!entry) throw new Error(`MCP server "${serverId}" is not configured or has invalid configuration.`);
 	if (entry.config.enabled === false) throw new Error(`MCP server "${serverId}" is disabled.`);
 	const agentDir = getNativePiAgentDir();
@@ -32,6 +36,7 @@ async function runNativeMcpSession(config, workspaceDir, serverId, interaction)
 		noThemes: true,
 		noContextFiles: true,
 		extensionFactories: [createToolSearchExtension(), createMcpExtension({
+			credentials: options?.credentials ?? loaded.credentials,
 			loadConfig: () => ({
 				servers: [entry],
 				errors: [],
@@ -42,18 +47,21 @@ async function runNativeMcpSession(config, workspaceDir, serverId, interaction)
 		})]
 	});
 	await loader.reload();
+	signal?.throwIfAborted();
 	const provider = "url" in entry.config ? entry.config.auth?.provider : void 0;
+	const modelRuntime = provider ? await createEmbeddedModelRuntime(provider) : await ModelRuntime.create({
+		credentials: new InMemoryCredentialStore(),
+		modelsStore: new InMemoryModelsStore(),
+		modelsPath: null,
+		refreshOnCreate: false
+	});
+	signal?.throwIfAborted();
 	const { session } = await createAgentSession({
 		cwd: workspaceDir,
 		agentDir,
 		resourceLoader: loader,
 		settingsManager,
-		modelRuntime: provider ? await createEmbeddedModelRuntime(provider) : await ModelRuntime.create({
-			credentials: new InMemoryCredentialStore(),
-			modelsStore: new InMemoryModelsStore(),
-			modelsPath: null,
-			refreshOnCreate: false
-		}),
+		modelRuntime,
 		sessionManager: SessionManager.inMemory(),
 		noTools: "builtin"
 	});
@@ -70,6 +78,8 @@ async function runNativeMcpSession(config, workspaceDir, serverId, interaction)
 	try {
 		const runner = session.extensionRunner;
 		if (!runner) throw new Error("Native MCP extension is unavailable.");
+		signal?.throwIfAborted();
+		signal?.addEventListener("abort", abort, { once: true });
 		await session.bindExtensions({ uiContext: {
 			...runner.getUIContext(),
 			notify(message) {
@@ -81,8 +91,7 @@ async function runNativeMcpSession(config, workspaceDir, serverId, interaction)
 				return interaction?.requestRedirectUrl(options?.signal) ?? Promise.resolve(void 0);
 			}
 		} });
-		interaction?.signal.addEventListener("abort", abort, { once: true });
-		if (interaction?.signal.aborted) throw new Error("MCP sign-in cancelled.");
+		if (signal?.aborted) throw new Error("MCP sign-in cancelled.");
 		let timer;
 		try {
 			await Promise.race([session.prompt("/mcp"), new Promise((_resolve, reject) => {
@@ -100,6 +109,7 @@ async function runNativeMcpSession(config, workspaceDir, serverId, interaction)
 			if (/needs sign-in|needs-auth/.test(failure)) throw new McpAuthenticationRequiredError(failure);
 			throw new Error(failure);
 		}
+		if (signal?.aborted) throw new Error("MCP connection check cancelled.");
 		const namespace = `mcp__${serverId.replace(/-/g, "_")}`;
 		return session.getAllTools().filter((tool) => tool.namespace?.name === namespace).map((tool) => ({
 			name: tool.name,
@@ -109,7 +119,7 @@ async function runNativeMcpSession(config, workspaceDir, serverId, interaction)
 		})).sort((a, b) => a.name.localeCompare(b.name));
 	} finally {
 		try {
-			interaction?.signal.removeEventListener("abort", abort);
+			signal?.removeEventListener("abort", abort);
 			await close();
 		} finally {
 			session.dispose();

package/dist/src/agent/service/process-direct-streaming.js

@@ -3,8 +3,8 @@ import { init_src } from "../../../packages/gateway-contract/src/index.js";
 import { init_session_input_repository, listTaskUpdateTriggers } from "../../storage/sqlite/session-input-repository.js";
 import { getClarificationResumeInput, init_clarification_wait_repository } from "../../storage/sqlite/clarification-wait-repository.js";
 import { getConnectionResumeInput, init_connection_wait_repository } from "../../storage/sqlite/connection-wait-repository.js";
-import { init_agent_session_key, resolveAgentMainConversationId } from "../../routing/agent-session-key.js";
 import { init_agent_scope, resolveDefaultAgentId } from "../agent-scope.js";
+import { init_agent_session_key, resolveAgentMainConversationId } from "../../routing/agent-session-key.js";
 import { readAgentMessageContent } from "../memory/agent-message-access.js";
 import { abortEmbeddedRun } from "../embedded/runs.js";
 import { clearPendingTranscriptUserMessage, setPendingTranscriptUserMessage } from "../inbound/attachment-pipeline.js";

package/dist/src/agent/service.js

@@ -1,14 +1,14 @@
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { init_attachment_ref, parseNoteAttachmentTarget } from "../notes/attachment-ref.js";
-import { init_agent_session_key, resolveAgentIdFromConversationId } from "../routing/agent-session-key.js";
 import { init_agent_scope, resolveAgentHomeDir, resolveDefaultAgentId } from "./agent-scope.js";
+import { extractTextContent } from "./context/workspace.js";
+import { init_agent_session_key, resolveAgentIdFromConversationId } from "../routing/agent-session-key.js";
 import { extractProfileAgentId, resolveEffectiveAgentConfigForSession } from "../config/agent-profile.js";
 import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
 import { init_providers, resolveModel } from "../providers/index.js";
 import { configureTracing, flushTracing } from "../observability/runtime.js";
 import { getUserTimezone } from "../user-model/repository.js";
-import { extractTextContent } from "./context/workspace.js";
 import { resolveAgentTurnTimeoutMs } from "./orchestration/run-agent-turn-with-timeout.js";
 import { applyConfigOverrides } from "../config/runtime-overrides.js";
 import { effectiveWorkspacePathForSession } from "../session/session-workspace.js";

package/dist/src/agent/skills/index.js

@@ -1,8 +1,8 @@
 import { resolveStateDir } from "../../config/paths-state.js";
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
-import { init_paths } from "../../config/paths.js";
 import { parseFrontmatter } from "../../markdown/frontmatter.js";
+import { init_paths } from "../../config/paths.js";
 import { findInstallSpec, hasBinary, installSkill } from "./installer.js";
 import { applySkillEnvOverrides, createSkillConfigManager, getSkillEnvironment, isSkillEnabled, resolveSkillConfig, validateSkillConfig } from "./config.js";
 import { parseSkillToolConditions } from "./skill-tool-gating.js";

package/dist/src/agent/skills/managed-store.js

@@ -1,5 +1,5 @@
-import { init_paths, resolveSkillsDir } from "../../config/paths.js";
 import { parseFrontmatter } from "../../markdown/frontmatter.js";
+import { init_paths, resolveSkillsDir } from "../../config/paths.js";
 import { loadSkillsLock } from "./hub-lock.js";
 import { dirname, join, resolve, sep } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";

package/dist/src/agent/skills/skill-manage-ops.js

@@ -1,5 +1,5 @@
-import { init_paths, resolveSkillsDir } from "../../config/paths.js";
 import { parseFrontmatter } from "../../markdown/frontmatter.js";
+import { init_paths, resolveSkillsDir } from "../../config/paths.js";
 import { resolveWorkspaceSkillsDir } from "./workspace-skills-dir.js";
 import { formatScanSummary, scanSkillDirectory } from "./scanner.js";
 import { fuzzyFindText, normalizeForFuzzyMatch, normalizeToLF, restoreLineEndings } from "../tools/edit-diff.js";

package/dist/src/agent/tools/clarify-tool.d.ts

@@ -1,9 +1,8 @@
+import type { ClarificationPresentation } from '@xopcai/gateway-contract';
 import type { AgentTool } from '@earendil-works/pi-agent-core';
-export type ClarifyRequestPayload = {
+export type ClarifyRequestPayload = ClarificationPresentation & {
     kind?: 'approval';
     question: string;
-    choices?: string[];
-    suggestedAnswer?: string;
     /** Stable hash of the exact operation guarded by an approval. */
     approvalKey?: string;
 };

package/dist/src/agent/tools/clarify-tool.js

@@ -2,13 +2,18 @@ import { Type } from "@sinclair/typebox";
 //#region src/agent/tools/clarify-tool.ts
 const ClarifySchema = Type.Object({
 	question: Type.String({ description: "The question to ask the user. Be specific and concise." }),
-	choices: Type.Optional(Type.Array(Type.String(), {
-		description: "Optional list of choices for multiple-choice questions. If provided, the user picks one. If omitted, the user types a free-form answer.",
+	interactionMode: Type.Optional(Type.Union([Type.Literal("quick"), Type.Literal("compose")], { description: "quick submits a choice immediately; compose lets the user select and add details before submitting." })),
+	choiceDetails: Type.Optional(Type.Array(Type.Object({
+		id: Type.String(),
+		label: Type.String(),
+		description: Type.Optional(Type.String())
+	}), {
 		minItems: 2,
-		maxItems: 10
+		maxItems: 10,
+		description: "Answer choices with stable unique IDs and optional descriptions."
 	})),
-	suggestedAnswer: Type.Optional(Type.String({ description: "Optional recommendation shown to the user. It is never selected automatically." }))
-});
+	recommendedChoiceId: Type.Optional(Type.String())
+}, { additionalProperties: false });
 function waitForAbort(signal) {
 	return new Promise((_, reject) => {
 		if (!signal) return;
@@ -23,7 +28,7 @@ function createClarifyTool(deps) {
 	return {
 		name: "clarify",
 		label: "❓ Clarify",
-		description: "Ask the user a clarifying question and pause the objective until they respond.\n\nUse this when you need more information to proceed correctly, rather than guessing.\n\nWHEN TO USE:\n- Ambiguous instructions with multiple valid interpretations\n- Missing critical information (which file, which approach, etc.)\n- Confirming destructive or irreversible actions\n\nWHEN NOT TO USE:\n- When you can reasonably infer the answer from context\n- For trivial decisions that do not affect the task\n- When the user explicitly said \"just do it\" or \"your choice\"\n\nTIPS:\n- Provide choices when there are clear options (faster for the user)\n- Keep questions short and specific\n- Include a suggested answer when one option is clearly more likely",
+		description: "Ask the user a clarifying question and pause the objective until they respond.\n\nUse this when you need more information to proceed correctly, rather than guessing.\n\nWHEN TO USE:\n- Ambiguous instructions with multiple valid interpretations\n- Missing critical information (which file, which approach, etc.)\n- Confirming destructive or irreversible actions\n\nWHEN NOT TO USE:\n- When you can reasonably infer the answer from context\n- For trivial decisions that do not affect the task\n- When the user explicitly said \"just do it\" or \"your choice\"\n\nTIPS:\n- Provide choices when there are clear options (faster for the user)\n- Keep questions short and specific\n- Set recommendedChoiceId when one option is clearly more likely",
 		parameters: ClarifySchema,
 		async execute(toolCallId, params, signal) {
 			const p = params;
@@ -36,9 +41,10 @@ function createClarifyTool(deps) {
 				details: { answer: "" }
 			};
 			const payload = {
-				question: p.question,
-				choices: p.choices,
-				suggestedAnswer: p.suggestedAnswer
+				interactionMode: p.interactionMode,
+				choiceDetails: p.choiceDetails,
+				recommendedChoiceId: p.recommendedChoiceId,
+				question: p.question
 			};
 			try {
 				const result = await Promise.race([askUser(payload), waitForAbort(signal)]);