@xopcai/xopc 0.0.433 → 0.0.435

package/dist/src/agent/embedded/run-turn.js

@@ -17,7 +17,7 @@ import { resolveAgentAbortReason } from "../orchestration/run-termination.js";
 import { isAgentTurnTimeoutError, isAgentTurnUnsettledError, resolveAgentTurnTimeoutMs, runAgentTurnWithTimeout } from "../orchestration/run-agent-turn-with-timeout.js";
 import { isContextOverflowError } from "../orchestration/context-overflow.js";
 import { ACCEPTANCE_REPAIR_READ_TOOLS, canResumeAfterModelFailure, completedRecoveryToolResult } from "../orchestration/turn-recovery.js";
-import { getAssistantTurnErrorMessage, isAssistantTurnAborted, isAssistantTurnFailed, maybeRetryTurnAfterTransientLlmFailure, stripTrailingErrorAssistantMessages } from "../orchestration/llm-turn-retry.js";
+import { classifyLlmFailure, getAssistantTurnErrorMessage, isAssistantTurnAborted, isAssistantTurnFailed, maybeRetryTurnAfterTransientLlmFailure, stripTrailingErrorAssistantMessages } from "../orchestration/llm-turn-retry.js";
 import { allowsExecutionTool, filterExecutionTools, resolveExecutionToolPolicy } from "./execution-tool-policy.js";
 import { isPhoneAssistanceSuspended, phoneAssistance, phoneResumeForRun } from "../../phone/assistance.js";
 import { runWithEmbeddedExecutionSession } from "./execution-context.js";
@@ -377,7 +377,12 @@ async function runXopcEmbeddedTurnInner(params) {
 		const { session, reused } = runner;
 		const configurationTurnStart = session.agent.state.messages.length;
 		await runLease.attach(session, async () => session.abort());
-		const runAbortSignal = params.abortSignal ? AbortSignal.any([runLease.signal, params.abortSignal]) : runLease.signal;
+		const turnDeadline = new AbortController();
+		const runAbortSignal = AbortSignal.any([
+			runLease.signal,
+			turnDeadline.signal,
+			...params.abortSignal ? [params.abortSignal] : []
+		]);
 		if (runAbortSignal.aborted) {
 			await session.abort();
 			return {
@@ -917,7 +922,20 @@ async function runXopcEmbeddedTurnInner(params) {
 					modelRequestNumber
 				}, "Embedded first response text ready");
 			}
-			if (event.type === "message_end" && event.message.role === "assistant") recordPromptCacheTouch(conversationId, resolvedModel, event.message.usage);
+			if (event.type === "message_end" && event.message.role === "assistant") {
+				recordPromptCacheTouch(conversationId, resolvedModel, event.message.usage);
+				if (event.message.stopReason === "error" || event.message.stopReason === "aborted") log.warn({
+					conversationId,
+					runId,
+					modelRef: latencyModelRef,
+					modelRequestNumber,
+					phase: "model_request_end",
+					stopReason: event.message.stopReason,
+					errorMessage: event.message.errorMessage,
+					hostSignalAborted: runAbortSignal.aborted,
+					...runAbortSignal.aborted ? { terminationReason: resolveAgentAbortReason(runAbortSignal.reason) } : {}
+				}, "Model request ended without completing the response");
+			}
 			if (event.type === "tool_execution_end") {
 				markTurnToolResult(conversationId, runId, event.toolName);
 				if (event.toolName === "send_message" && !event.isError) sentVisibleMessage = true;
@@ -1055,7 +1073,10 @@ async function runXopcEmbeddedTurnInner(params) {
 					await session.agent.waitForIdle();
 					await recoverSettledTurn();
 				}
-			}), timeoutMs, { timeoutExtensionMs: params.timeoutExtensionMs });
+			}), timeoutMs, {
+				timeoutExtensionMs: params.timeoutExtensionMs,
+				onTimeout: (reason) => turnDeadline.abort(reason)
+			});
 			if (phoneStopped) {
 				const wait = phoneAssistance(conversationId);
 				const notice = {
@@ -1125,7 +1146,7 @@ async function runXopcEmbeddedTurnInner(params) {
 				ok: false,
 				retryable: false,
 				terminationReason: "provider_error",
-				errorMessage: "aborted",
+				errorMessage: `Model request was interrupted while the agent run was still active; automatic recovery could not complete. ${getAssistantTurnErrorMessage(session.agent) ?? "Provider returned an aborted stream."}`,
 				lastAssistantText: lastAssistantPlainText(session)
 			};
 			if (policyStopped && !policyCompleted || lengthRecoveryExhausted || lastAssistantMessage(session.agent.state.messages)?.stopReason === "length") return {
@@ -1139,7 +1160,7 @@ async function runXopcEmbeddedTurnInner(params) {
 				ok: false,
 				retryable: canResumeAfterModelFailure(session.agent.state.messages, { allowFailedReadTools: ACCEPTANCE_REPAIR_READ_TOOLS }),
 				terminationReason: "provider_error",
-				errorMessage: getAssistantTurnErrorMessage(session.agent) ?? "Assistant turn failed",
+				errorMessage: classifyLlmFailure(getAssistantTurnErrorMessage(session.agent) ?? "") === "aborted" ? `Model request was interrupted while the agent run was still active; automatic recovery could not complete. ${getAssistantTurnErrorMessage(session.agent)}` : getAssistantTurnErrorMessage(session.agent) ?? "Assistant turn failed",
 				lastAssistantText: lastAssistantPlainText(session)
 			};
 			if (params.requireVisibleReply && !sentVisibleMessage && lastAssistantPlainText(session).trim() === "NO_REPLY") return {
@@ -1191,7 +1212,9 @@ async function runXopcEmbeddedTurnInner(params) {
 		log.error({
 			err,
 			conversationId,
-			runId
+			runId,
+			phase: "embedded_run_end",
+			terminationReason: isAgentTurnTimeoutError(err) ? "deadline_exceeded" : params.abortSignal?.aborted ? resolveAgentAbortReason(params.abortSignal.reason) : "runtime_error"
 		}, `Embedded run failed: ${em}`);
 		onEvent?.({
 			type: "error",

package/dist/src/agent/embedded/runs.d.ts

@@ -30,11 +30,11 @@ export declare class EmbeddedRunRegistry {
     acquire(identity: EmbeddedRunIdentity): EmbeddedRunLease;
     getByConversationId(conversationId: string): EmbeddedRunHandle | undefined;
     abortByConversationId(conversationId: string, reason?: 'user_cancelled' | 'parent_cancelled', expectedRunId?: string): Promise<boolean>;
-    steerByConversationId(conversationId: string, text: string): Promise<boolean>;
+    steerByConversationId(conversationId: string, text: string, expectedRunId?: string): Promise<boolean>;
     size(): number;
 }
 export declare function acquireEmbeddedRunLease(identity: EmbeddedRunIdentity): EmbeddedRunLease;
 export declare function reserveEmbeddedRunCancellation(identity: Pick<EmbeddedRunIdentity, 'conversationId' | 'runId'>): EmbeddedRunCancellation;
 export declare function getEmbeddedRunByConversationId(conversationId: string): EmbeddedRunHandle | undefined;
 export declare function abortEmbeddedRun(conversationId: string, reason?: 'user_cancelled' | 'parent_cancelled', expectedRunId?: string): Promise<boolean>;
-export declare function queueEmbeddedSteer(conversationId: string, text: string): Promise<boolean>;
+export declare function queueEmbeddedSteer(conversationId: string, text: string, expectedRunId?: string): Promise<boolean>;

package/dist/src/agent/embedded/runs.js

@@ -63,9 +63,9 @@ var EmbeddedRunRegistry = class {
 		if (entry.handle) await entry.handle.abort();
 		return true;
 	}
-	async steerByConversationId(conversationId, text) {
+	async steerByConversationId(conversationId, text, expectedRunId) {
 		const handle = this.getByConversationId(conversationId);
-		if (!handle) return false;
+		if (!handle || expectedRunId !== void 0 && handle.runId !== expectedRunId || this.byConversationId.get(conversationId)?.abortController.signal.aborted) return false;
 		await handle.session.steer(text);
 		return true;
 	}
@@ -86,8 +86,8 @@ function getEmbeddedRunByConversationId(conversationId) {
 function abortEmbeddedRun(conversationId, reason = "parent_cancelled", expectedRunId) {
 	return embeddedRunRegistry.abortByConversationId(conversationId, reason, expectedRunId);
 }
-function queueEmbeddedSteer(conversationId, text) {
-	return embeddedRunRegistry.steerByConversationId(conversationId, text);
+function queueEmbeddedSteer(conversationId, text, expectedRunId) {
+	return embeddedRunRegistry.steerByConversationId(conversationId, text, expectedRunId);
 }
 //#endregion
 export { EmbeddedRunConflictError, EmbeddedRunRegistry, abortEmbeddedRun, acquireEmbeddedRunLease, getEmbeddedRunByConversationId, queueEmbeddedSteer, reserveEmbeddedRunCancellation };

package/dist/src/agent/embedded/session-runner.js

@@ -3,6 +3,7 @@ import { init_logger } from "../../utils/logger.js";
 import { filterExecutionTools, resolveExecutionToolPolicy } from "./execution-tool-policy.js";
 import { deferredToolContract, getXopcToolMetadata } from "./tool-metadata.js";
 import { isCodemodeCoreRead } from "../tools/codemode-permissions.js";
+import { getExternalToolRegistry } from "../external-tools/tool-registry.js";
 import { createEmbeddedModelRuntime, resolveEmbeddedProviderApiKeySync } from "./model-runtime.js";
 import { getNativePiAgentDir } from "../mcp/native-mcp.js";
 import { createXopcMcpTransport } from "../mcp/transport.js";
@@ -21,13 +22,20 @@ import { createHash } from "node:crypto";
 import { DefaultResourceLoader, SettingsManager, createAgentSession, createMcpExtension } from "@earendil-works/pi-coding-agent";
 //#region src/agent/embedded/session-runner.ts
 init_logger();
-const toolContract = (tool) => JSON.stringify([
-	tool.name,
-	tool.parameters,
-	tool.description,
-	isCodemodeCoreRead(tool),
-	getXopcToolMetadata(tool)
-]);
+const toolContract = (tool) => {
+	const registry = getExternalToolRegistry([tool]);
+	return JSON.stringify([
+		tool.name,
+		tool.parameters,
+		tool.description,
+		isCodemodeCoreRead(tool),
+		getXopcToolMetadata(tool),
+		registry ? {
+			discovery: registry.discovery,
+			nativeSources: registry.nativeSources
+		} : void 0
+	]);
+};
 const log = createLogger("EmbeddedSessionRunner");
 const DEFAULT_IDLE_TTL_MS = 5 * 6e4;
 function providerCredentialRevision(providerId) {
@@ -259,8 +267,8 @@ var EmbeddedSessionRunnerPool = class {
 			contextWindowTokens: model.contextWindow ?? 128e3,
 			transformMessageForPersistence: params.transcriptRuntime.persistent ? (message) => transformUserMessageForPersistence(runtimeId, message) : void 0
 		});
-		const toolDefs = xopcToolsToDefinitions(tools);
-		const toolNames = tools.filter((tool) => getXopcToolMetadata(tool)?.exposure !== "deferred").map((tool) => tool.name);
+		const toolDefs = xopcToolsToDefinitions(tools.filter((tool) => tool.name !== "tool_search"));
+		const toolNames = tools.filter((tool) => !["deferred", "hidden"].includes(getXopcToolMetadata(tool)?.exposure ?? "") && tool.name !== "tool_search").map((tool) => tool.name);
 		const discoveryState = piSm.getBranch().findLast((entry) => entry.type === "custom" && entry.customType === "xopc-tool-discovery");
 		const saved = discoveryState?.type === "custom" ? discoveryState.data : void 0;
 		const restored = new Map((saved?.loaded ?? []).map((tool) => [tool.name, tool.contract]));
@@ -277,7 +285,10 @@ var EmbeddedSessionRunnerPool = class {
 			maxOutputTokens: 4e3
 		} : void 0;
 		if (codemode) toolNames.push("codemode");
-		const discovery = params.executionToolPolicy?.discovery !== false && (hasMcp || tools.some((tool) => getXopcToolMetadata(tool)?.exposure === "deferred"));
+		const registry = getExternalToolRegistry(tools);
+		const nativeDiscovery = params.executionToolPolicy?.discovery !== false && registry?.discovery?.native !== false;
+		const externalDiscovery = registry?.discovery?.connectors !== false;
+		const discovery = nativeDiscovery && (hasMcp || externalDiscovery && Boolean(registry) || tools.some((tool) => getXopcToolMetadata(tool)?.exposure === "deferred")) || externalDiscovery && params.executionToolPolicy?.surface === "personal_request_worker";
 		if (discovery) toolNames.push("tool_search");
 		const modelRuntime = await createEmbeddedModelRuntime(model.provider);
 		const resourceLoader = new DefaultResourceLoader({
@@ -291,7 +302,11 @@ var EmbeddedSessionRunnerPool = class {
 				createMcpSetupContinuationGuard(runtimeId, tools.some((tool) => tool.name === "mcp_setup")),
 				...mcp?.automationSourceRunId ? [createAutomationMcpSourceGuard(mcp.automationSourceRunId)] : [],
 				...codemode ? [createXopcCodemodeExtension(codemode, tools, () => boundSession)] : [],
-				...discovery ? [createXopcToolSearchExtension(tools)] : [],
+				...discovery ? [createXopcToolSearchExtension(tools, {
+					nativeDiscovery,
+					externalDiscovery,
+					registry
+				})] : [],
 				...mcp ? [createMcpExtension({
 					createTransport: createXopcMcpTransport(),
 					loadConfig: () => mcp,

package/dist/src/agent/embedded/tool-search-extension.d.ts

@@ -1,5 +1,11 @@
 import type { AgentTool } from '@earendil-works/pi-agent-core';
 import { type ExtensionFactory } from '@earendil-works/pi-coding-agent';
+import { type ExternalToolRegistry } from '../external-tools/tool-registry.js';
 export declare const TOOL_DISCOVERY_STATE = "xopc-tool-discovery";
-/** xopc deliberately excludes pi system declarations from SQLite; retain only discovery state. */
-export declare function createXopcToolSearchExtension(tools: readonly AgentTool[]): ExtensionFactory;
+/** One model-facing discovery entry; execution and connection permissions remain host-owned. */
+export declare function createXopcToolSearchExtension(tools: readonly AgentTool[], options?: {
+    nativeDiscovery?: boolean;
+    externalDiscovery?: boolean;
+    registry?: ExternalToolRegistry;
+    externalTimeoutMs?: number;
+}): ExtensionFactory;

package/dist/src/agent/embedded/tool-search-extension.js

@@ -1,44 +1,136 @@
 import { deferredToolContract, getXopcToolMetadata } from "./tool-metadata.js";
+import { getExternalToolRegistry } from "../external-tools/tool-registry.js";
 import { createToolSearchExtension } from "@earendil-works/pi-coding-agent";
 //#region src/agent/embedded/tool-search-extension.ts
 const TOOL_DISCOVERY_STATE = "xopc-tool-discovery";
-/** xopc deliberately excludes pi system declarations from SQLite; retain only discovery state. */
-function createXopcToolSearchExtension(tools) {
+/** One model-facing discovery entry; execution and connection permissions remain host-owned. */
+function createXopcToolSearchExtension(tools, options = {}) {
 	const deferred = tools.filter((tool) => getXopcToolMetadata(tool)?.exposure === "deferred");
-	return (pi) => createToolSearchExtension()({
-		...pi,
-		registerTool(definition) {
-			pi.registerTool({
-				...definition,
-				async execute(id, params, signal, update, context) {
-					const input = params;
-					if ((input.limit ?? 8) > 20 || (input.query?.length ?? 0) > 2e3) throw new Error("Tool search permits at most 20 matches and 2000 query characters");
-					const result = await definition.execute(id, params, signal, update, context);
-					if ((result.details?.loaded)?.length === 0) {
-						const queryNames = new Set((input.query ?? "").match(/[\w.:-]+/g));
-						const active = new Set(pi.getActiveTools());
-						const alreadyLoaded = deferred.filter((tool) => active.has(tool.name) && queryNames.has(tool.name)).map((tool) => tool.name);
-						if (alreadyLoaded.length) return {
-							...result,
-							content: [{
-								type: "text",
-								text: `Already loaded: ${alreadyLoaded.join(", ")}. These tools are declared and available now; call them directly. No new tools were loaded.`
-							}]
-						};
-					}
-					return result;
-				}
-			});
-		},
-		setActiveTools(names) {
+	const registry = options.externalDiscovery === false ? void 0 : options.registry ?? getExternalToolRegistry(tools);
+	const nativeDiscovery = options.nativeDiscovery !== false;
+	return (pi) => {
+		const setActiveTools = (names) => {
 			pi.setActiveTools(names);
+			if (!nativeDiscovery) return;
 			const active = new Set(pi.getActiveTools());
 			pi.appendEntry(TOOL_DISCOVERY_STATE, { loaded: deferred.filter((tool) => active.has(tool.name)).map((tool) => ({
 				name: tool.name,
 				contract: deferredToolContract(tool)
 			})) });
-		}
-	});
+		};
+		return createToolSearchExtension()({
+			...pi,
+			registerTool(definition) {
+				pi.registerTool({
+					...definition,
+					description: "Search for tools and connector capabilities using concise capability keywords. loadedTools are available by name from the next model call. externalTools require xopc_tool_describe, then xopc_tool_execute with the exact revision. Connection and install candidates are recovery options, not executable tools or proof of missing authorization. Use xopc_require_connection only when authorization, installation or account selection is actually required; Personal request workers use personal_request_connection. Source errors do not mean a capability is unavailable. Searches never grant permissions.",
+					executionMode: "sequential",
+					async execute(id, params, signal, update, context) {
+						const input = params;
+						const limit = input.limit ?? 8;
+						if (!Number.isInteger(limit) || limit < 1 || limit > 20 || !input.query?.trim() || input.query.length > 2e3) throw new Error("Tool search requires a nonempty query of at most 2000 characters and a limit from 1 to 20");
+						signal?.throwIfAborted();
+						const nativeLimit = nativeDiscovery ? registry ? Math.max(1, Math.floor(limit / 2)) : limit : 0;
+						const externalLimit = nativeDiscovery ? Math.max(1, limit - nativeLimit) : limit;
+						const externalSearch = registry ? boundedSearch(() => registry.search({
+							query: input.query,
+							limit: externalLimit,
+							signal,
+							timeoutMs: 4e3
+						}), options.externalTimeoutMs ?? 8e3, signal) : Promise.resolve(void 0);
+						const result = nativeDiscovery ? await definition.execute(id, {
+							...params,
+							limit: nativeLimit
+						}, signal, update, context) : {
+							content: [],
+							details: { loaded: [] }
+						};
+						const external = await externalSearch;
+						signal?.throwIfAborted();
+						const loaded = result.details?.loaded ?? [];
+						const queryNames = new Set(input.query.match(/[\w.:-]+/g));
+						const active = new Set(pi.getActiveTools());
+						const alreadyLoaded = nativeDiscovery ? deferred.filter((tool) => active.has(tool.name) && !loaded.includes(tool.name) && queryNames.has(tool.name)).map((tool) => tool.name) : [];
+						const externalTools = (external?.result?.tools ?? []).slice(0, Math.max(0, limit - loaded.length));
+						if (externalTools.length) setActiveTools([
+							...active,
+							"xopc_tool_describe",
+							"xopc_tool_execute"
+						]);
+						const all = new Map(pi.getAllTools().map((tool) => [tool.name, tool]));
+						const payload = {
+							loadedTools: loaded.map((name) => ({
+								name,
+								description: all.get(name)?.description,
+								nextAction: "call"
+							})),
+							alreadyLoaded,
+							externalTools: externalTools.map((tool) => ({
+								...tool,
+								nextAction: "describe"
+							})),
+							connectionCandidates: external?.result?.connectionCandidates ?? [],
+							installCandidates: external?.result?.installCandidates ?? [],
+							selectedConnections: external?.result?.selectedConnections ?? [],
+							selectedAccountId: external?.result?.selectedAccountId,
+							waitingObjective: external?.result?.waitingObjective,
+							sourceErrors: [
+								...external?.result?.sourceErrors ?? [],
+								...external?.error ? [{
+									source: "connectors",
+									message: external.error
+								}] : [],
+								...external?.result?.installCatalogError ? [{
+									source: "store",
+									message: external.result.installCatalogError
+								}] : []
+							],
+							unavailableSources: external?.result?.unavailableSources ?? [],
+							scope: {
+								native: nativeDiscovery,
+								connectors: Boolean(registry),
+								...nativeDiscovery ? {} : { restriction: "Only the selected Personal request connector, account and curated reads are discoverable." }
+							},
+							instruction: [
+								nativeDiscovery ? result.content.filter((block) => block.type === "text").map((block) => block.text).join("\n") : "",
+								alreadyLoaded.length ? `Already loaded: ${alreadyLoaded.join(", ")}. Call these tools directly.` : "",
+								external?.result?.instruction ?? "",
+								"loadedTools are declared from the next model call; externalTools are references and must be described before execution. No matches alone do not prove missing authorization."
+							].filter(Boolean).join("\n")
+						};
+						return {
+							content: [{
+								type: "text",
+								text: JSON.stringify(payload)
+							}],
+							details: {
+								...payload,
+								loaded
+							}
+						};
+					}
+				});
+			},
+			setActiveTools
+		});
+	};
+}
+/** Bound directory latency without cancelling another source or executing any operation. */
+async function boundedSearch(search, timeoutMs, signal) {
+	let timer;
+	let onAbort;
+	try {
+		return await Promise.race([Promise.resolve().then(search).then((result) => ({ result })), new Promise((_resolve, reject) => {
+			timer = setTimeout(() => reject(/* @__PURE__ */ new Error("Connector discovery timed out; retry before declaring the capability unavailable")), timeoutMs);
+			onAbort = () => reject(signal?.reason ?? /* @__PURE__ */ new Error("Tool search aborted"));
+			signal?.addEventListener("abort", onAbort, { once: true });
+		})]);
+	} catch (error) {
+		return { error: error instanceof Error ? error.message : String(error) };
+	} finally {
+		clearTimeout(timer);
+		if (onAbort) signal?.removeEventListener("abort", onAbort);
+	}
 }
 //#endregion
 export { TOOL_DISCOVERY_STATE, createXopcToolSearchExtension };

package/dist/src/agent/external-tools/cliProvider.d.ts

@@ -1,5 +1,5 @@
 import type { Config } from '../../config/schema.js';
-import type { ExternalToolProvider, ExternalToolExecutionContext, ExternalToolTurnContext } from './types.js';
+import type { ExternalToolProvider, ExternalToolDiscoveryContext, ExternalToolExecutionContext, ExternalToolTurnContext } from './types.js';
 export declare class CliToolProvider implements ExternalToolProvider {
     private readonly deps;
     readonly source: "cli";
@@ -9,20 +9,14 @@ export declare class CliToolProvider implements ExternalToolProvider {
         agentId?: string;
     });
     private available;
-    search(query: string): Promise<{
+    search(query: string, context?: ExternalToolDiscoveryContext): Promise<{
         toolRef: string;
         source: "cli";
         namespace: string;
         title: string;
         summary: string;
     }[]>;
-    describe(toolRef: string): Promise<{
-        toolRef: string;
-        source: "cli";
-        namespace: string;
-        title: string;
-        summary: string;
-        description: string;
+    describe(toolRef: string, context?: ExternalToolDiscoveryContext): Promise<{
         readOnly: boolean;
         batchRead: boolean;
         inputSchema: {
@@ -37,6 +31,13 @@ export declare class CliToolProvider implements ExternalToolProvider {
                 };
             };
         };
+        contractRevision?: string;
+        toolRef: string;
+        source: "cli";
+        namespace: string;
+        title: string;
+        summary: string;
+        description: string;
     }>;
     execute(toolRef: string, args: Record<string, unknown>, approvalId: string | undefined, context: ExternalToolExecutionContext): Promise<{
         content: {

package/dist/src/agent/external-tools/cliProvider.js

@@ -35,6 +35,16 @@ const result = (value) => ({
 	}],
 	details: {}
 });
+function cliContractRevision(connection, action, adapter) {
+	return connectorArgumentsHash({
+		accountId: connection.accountId,
+		connectionId: connection.id,
+		connectionUpdatedAt: connection.updatedAt,
+		action,
+		adapterVersion: adapter.version,
+		binaryVersion: adapter.binaryVersion
+	});
+}
 var CliToolProvider = class {
 	source = "cli";
 	constructor(deps) {
@@ -60,13 +70,14 @@ var CliToolProvider = class {
 			}];
 		});
 	}
-	async search(query) {
+	async search(query, context) {
 		const words = query.toLowerCase().split(/\s+/).filter(Boolean);
 		return this.available().flatMap((item) => {
+			if (context && item.instance.connectorId !== context.connectorId) return [];
 			const accounts = selectConnectorAccount({
 				installation: item.policy,
 				agentId: item.agentId,
-				accept: (c) => c.provider === "cli" && c.metadata.runtimeInstanceId === item.instance.instanceId
+				accept: (c) => c.provider === "cli" && c.metadata.runtimeInstanceId === item.instance.instanceId && (!context || c.accountId === context.accountId)
 			}).candidates;
 			if (!accounts.length) return [];
 			return Object.entries(item.adapter.curatedActions).filter(([id, scope]) => {
@@ -90,16 +101,18 @@ var CliToolProvider = class {
 			}));
 		});
 	}
-	async describe(toolRef) {
+	async describe(toolRef, context) {
 		const parsed = parseExternalToolRef(toolRef, this.source);
 		const item = this.available().find((value) => value.instance.instanceId === parsed?.namespace);
 		if (!item || !parsed) return void 0;
+		if (context && item.instance.connectorId !== context.connectorId) return void 0;
 		const selected = selectConnectorAccount({
 			installation: item.policy,
 			agentId: item.agentId,
+			requestedAccountId: context?.accountId,
 			accept: (c) => c.provider === "cli" && c.metadata.runtimeInstanceId === item.instance.instanceId
 		});
-		const connection = selected.connection ?? selected.candidates[0];
+		const connection = selected.connection ?? (context ? void 0 : selected.candidates[0]);
 		if (!connection) return void 0;
 		const action = await describeCliAction(item.config, item.instance.instanceId, connection, parsed.toolName);
 		if (evaluateConnectorExecutionPolicy({
@@ -119,6 +132,7 @@ var CliToolProvider = class {
 			title: action.id,
 			summary: action.description,
 			description: action.description,
+			...context ? { contractRevision: cliContractRevision(connection, action, item.adapter) } : {},
 			readOnly: action.scope === "read",
 			batchRead: action.scope === "read",
 			inputSchema: {
@@ -159,6 +173,9 @@ var CliToolProvider = class {
 			instruction: "Select a connected account using xopcAccountId. Never substitute another account."
 		});
 		const action = await describeCliAction(item.config, item.instance.instanceId, connection, parsed.toolName);
+		context.authorize?.();
+		context.signal?.throwIfAborted();
+		if (context.contractRevision && context.contractRevision !== cliContractRevision(connection, action, item.adapter)) throw new CapabilityError("REVISION_CONFLICT", "Selected account or CLI action contract changed. Describe the tool again.");
 		if (args.xopcExportResult !== void 0 && typeof args.xopcExportResult !== "boolean") throw new Error("Invalid export option.");
 		const exportResult = args.xopcExportResult === true;
 		const input = { ...args };
@@ -252,6 +269,8 @@ var CliToolProvider = class {
 		}
 		const acceptedArgumentsHash = argumentsHash();
 		const authorizeCurrent = () => {
+			context.authorize?.();
+			context.signal?.throwIfAborted();
 			const freshPolicy = getConnectorInstallation(item.policy.id);
 			const freshConnection = getConnectorConnection(connection.id);
 			const currentConfig = this.deps.getConfig();
@@ -273,6 +292,7 @@ var CliToolProvider = class {
 				confirmed: Boolean(approvalId)
 			}).decision !== "allowed") throw new CapabilityError("FORBIDDEN", "Connector permission changed.");
 			if (argumentsHash() !== acceptedArgumentsHash) throw new CapabilityError("REVISION_CONFLICT", "Connector objective changed.");
+			if (context.contractRevision && context.contractRevision !== cliContractRevision(freshConnection, action, item.adapter)) throw new CapabilityError("REVISION_CONFLICT", "Selected account or CLI action contract changed.");
 		};
 		const execute = async (executionId) => {
 			let authorized = false;

package/dist/src/agent/external-tools/composio-provider.d.ts

@@ -2,7 +2,7 @@ import type { AgentToolResult } from '@earendil-works/pi-agent-core';
 import type { Config } from '../../config/schema.js';
 import type { ExtensionHookRunner } from '../../extensions/index.js';
 import { ComposioSessionsAdapter } from '../../connectors/composio-sessions.js';
-import type { ExternalToolDescriptor, ExternalToolExecutionContext, ExternalToolProvider, ExternalToolSearchHit } from './types.js';
+import type { ExternalToolDescriptor, ExternalToolDiscoveryContext, ExternalToolExecutionContext, ExternalToolProvider, ExternalToolSearchHit } from './types.js';
 type CurrentContext = {
     channel: string;
     chatId: string;
@@ -21,8 +21,8 @@ export declare class ComposioToolProvider implements ExternalToolProvider {
     private readonly adapter;
     private readonly unavailableToolkits;
     constructor(deps: ComposioToolProviderDeps);
-    search(query: string): Promise<ExternalToolSearchHit[]>;
-    describe(toolRef: string): Promise<ExternalToolDescriptor | undefined>;
+    search(query: string, context?: ExternalToolDiscoveryContext): Promise<ExternalToolSearchHit[]>;
+    describe(toolRef: string, context?: ExternalToolDiscoveryContext): Promise<ExternalToolDescriptor | undefined>;
     execute(toolRef: string, args: Record<string, unknown>, approvalId: string | undefined, context: ExternalToolExecutionContext): Promise<AgentToolResult<Record<string, unknown>>>;
     private availableInstallations;
     private resolve;

package/dist/src/agent/external-tools/composio-provider.js

@@ -142,8 +142,9 @@ var ComposioToolProvider = class {
 		this.deps = deps;
 		this.adapter = deps.adapter ?? new ComposioSessionsAdapter();
 	}
-	async search(query) {
+	async search(query, context) {
 		const available = this.availableInstallations();
+		if (context) available.installations = available.installations.filter((installation) => installation.connectorId === context.connectorId);
 		if (available.installations.length === 0) return [];
 		const settled = await Promise.allSettled(available.installations.map(async (installation) => {
 			const toolkit = toolkitFromInstallation(installation);
@@ -207,9 +208,10 @@ var ComposioToolProvider = class {
 		}
 		return hits;
 	}
-	async describe(toolRef) {
+	async describe(toolRef, context) {
 		const resolved = this.resolve(toolRef);
 		if (!resolved) return void 0;
+		if (context && resolved.installation.connectorId !== context.connectorId) return void 0;
 		const toolkit = toolkitFromInstallation(resolved.installation);
 		const action = listConnectorActionMetadata(resolved.installation.connectorId).find((candidate) => candidate.actionId === resolved.actionId);
 		if (!action || !isToolInputSchema(action.inputSchema) || !isComposioActionAllowedByCatalog(action.actionId)) return void 0;
@@ -218,11 +220,12 @@ var ComposioToolProvider = class {
 		const accounts = currentAccountConnections(listConnectorConnections({
 			principalId: available.principalId,
 			connectorId: resolved.installation.connectorId
-		}).filter((connection) => canAccessConnectorAccount(connection, resolved.installation, available.agentId))).map((connection) => ({
+		}).filter((connection) => canAccessConnectorAccount(connection, resolved.installation, available.agentId) && (!context || connection.accountId === context.accountId))).map((connection) => ({
 			accountId: connection.accountId,
 			label: getConnectorAccount(connection.accountId)?.label,
 			identity: connectorIdentitySummary(connection.identity)
 		}));
+		if (context && !accounts.length) return void 0;
 		return {
 			toolRef,
 			source: this.source,

package/dist/src/agent/external-tools/discovery.d.ts

@@ -0,0 +1,47 @@
+import type { Config } from '../../config/schema.js';
+import type { ExternalToolService } from './service.js';
+import { type ExternalToolSource, type ExternalToolTurnContext } from './types.js';
+import type { PersonalRequest } from '../../personal-agent/request-repository.js';
+export type ExternalDiscoveryParams = {
+    query: string;
+    limit?: number;
+    sources?: ExternalToolSource[];
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+/** Discover capabilities without activating tools or granting execution permissions. */
+export declare function discoverExternalTools(deps: {
+    service: ExternalToolService;
+    nativeSources: readonly ExternalToolSource[];
+    getContext?: () => ExternalToolTurnContext | null;
+    getConfig?: () => Config | undefined;
+    getRequest: () => PersonalRequest | undefined;
+}, params: ExternalDiscoveryParams): Promise<{
+    tools: any[];
+    connectionCandidates: any[];
+    installCandidates: any[];
+    unavailableSources: any[];
+    instruction: string;
+} | {
+    selectedAccountId?: string;
+    instruction?: string;
+    selectedConnections: import("@xopcai/gateway-contract/src/connection-waits.js").ConnectionNeed[];
+    waitingObjective: string;
+    searchScope?: {
+        excludedSources: ("cli" | "extension" | "memory" | "endpoint" | "composio")[];
+        instruction: string;
+    };
+    installCatalogError?: string;
+    connectionCandidates: {
+        candidateRef: string;
+        label: string;
+        capabilities: string[];
+    }[];
+    installCandidates: import("../../capabilities/store-connector.js").StoreConnectorInstallCandidate[];
+    tools: import("./types.js").ExternalToolSearchHit[];
+    unavailableSources: ExternalToolSource[];
+    sourceErrors?: Array<ReturnType<typeof import("./search-error.js").searchFailureDetails> & {
+        source: ExternalToolSource;
+    }>;
+}>;
+export type ExternalDiscoveryResult = Awaited<ReturnType<typeof discoverExternalTools>>;