@xopcai/xopc 0.0.432 → 0.0.434

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/embedded/xopc-tools-bridge.js

@@ -1,6 +1,6 @@
-import { recordPersonalPerformance } from "../../personal-agent/performance.js";
 import { getXopcToolMetadata } from "./tool-metadata.js";
 import { withDataToolPermissions } from "../tools/dataBatch.js";
+import { recordPersonalPerformance } from "../../personal-agent/performance.js";
 //#region src/agent/embedded/xopc-tools-bridge.ts
 const APPLY_PATCH_BEGIN_MARKER = "*** Begin Patch";
 const APPLY_PATCH_END_MARKER = "*** End Patch";

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

@@ -8,14 +8,14 @@ import "../../storage/sqlite/index.js";
 import { CapabilityError } from "../../capabilities/runtime/errors.js";
 import { ExternalEffectNotAppliedError, executeExternalOperation } from "../../capabilities/runtime/external-operations.js";
 import "../../capabilities/runtime/dispatcher.js";
+import { connectorArgumentsHash, connectorArgumentsPreview } from "../../connectors/approval.js";
 import { connectorPrincipalForSession } from "../../connectors/principal.js";
+import { selectConnectorAccount } from "../../connectors/account-selection.js";
+import { cliContextPath } from "../../connectors/cli/process.js";
 import { getCliAdapter } from "../../connectors/cli/adapterRegistry.js";
 import { evaluateConnectorExecutionPolicy } from "../../connectors/policy.js";
 import { listConnectorInstances } from "../../connectors/instances.js";
-import { cliContextPath } from "../../connectors/cli/process.js";
 import { cliOwnerId, recoverCliExecutions } from "../../connectors/cli/store.js";
-import { selectConnectorAccount } from "../../connectors/account-selection.js";
-import { connectorArgumentsHash, connectorArgumentsPreview } from "../../connectors/approval.js";
 import { validateActionInput } from "../../connectors/cli/protocol.js";
 import { describeCliAction, executeCliAction } from "../../connectors/cli/runtime.js";
 import { externalToolRef, parseExternalToolRef } from "./refs.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

@@ -7,6 +7,7 @@ import { bindObjectiveAccount, connectionBinding, connectionBindings, connectorO
 import "../../storage/sqlite/index.js";
 import { CapabilityError } from "../../capabilities/runtime/errors.js";
 import { ExternalEffectNotAppliedError, executeExternalOperation } from "../../capabilities/runtime/external-operations.js";
+import { connectorArgumentsHash, connectorArgumentsPreview } from "../../connectors/approval.js";
 import { canAccessConnectorAccount, currentAccountConnections } from "../../connectors/account-access.js";
 import { connectorPrincipalForSession } from "../../connectors/principal.js";
 import { connectorIdentitySummary } from "../../connectors/connector-identity.js";
@@ -15,9 +16,8 @@ import { ComposioSessionsAdapter } from "../../connectors/composio-sessions.js";
 import { getComposioToolkitScope, getConfiguredComposioAuthConfigs, isComposioActionAllowedByCatalog, scopeForComposioAction } from "../../connectors/composio.js";
 import { getConnectorDefinition } from "../../connectors/catalog.js";
 import { listConnectorInstances } from "../../connectors/instances.js";
-import { connectorArgumentsHash, connectorArgumentsPreview } from "../../connectors/approval.js";
-import { isToolInputSchema } from "../../connectors/connection-capabilities.js";
 import { externalToolRef, parseExternalToolRef } from "./refs.js";
+import { isToolInputSchema } from "../../connectors/connection-capabilities.js";
 import { ExternalToolSearchError } from "./search-error.js";
 //#region src/agent/external-tools/composio-provider.ts
 init_session_input_repository();
@@ -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>>;

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

@@ -0,0 +1,56 @@
+import { connectionBindings, getActiveConnectionWait, init_connection_wait_repository } from "../../storage/sqlite/connection-wait-repository.js";
+import { searchStoreConnectorInstallCandidates } from "../../capabilities/store-connector.js";
+import { connectionCandidates } from "../../connectors/connection-candidates.js";
+import { EXTERNAL_TOOL_SOURCES } from "./types.js";
+//#region src/agent/external-tools/discovery.ts
+init_connection_wait_repository();
+/** Discover capabilities without activating tools or granting execution permissions. */
+async function discoverExternalTools(deps, params) {
+	const { service, nativeSources, getContext, getConfig } = deps;
+	const gatewaySources = EXTERNAL_TOOL_SOURCES.filter((source) => !nativeSources.includes(source));
+	const request = deps.getRequest();
+	const selectedSources = new Set(params.sources ?? []);
+	const excludedSources = selectedSources.size ? EXTERNAL_TOOL_SOURCES.filter((source) => !selectedSources.has(source)) : [];
+	if (params.sources?.length && params.sources.every((source) => nativeSources.includes(source))) return {
+		tools: [],
+		connectionCandidates: [],
+		installCandidates: [],
+		unavailableSources: [],
+		instruction: "Use tool_search for native tools."
+	};
+	const result = await service.search({
+		...params,
+		sources: (params.sources?.length ? params.sources : gatewaySources).filter((source) => !nativeSources.includes(source))
+	});
+	const currentRequest = deps.getRequest();
+	if (request && (currentRequest?.requestId !== request.requestId || currentRequest.accountId !== request.accountId || currentRequest.connectorId !== request.connectorId)) throw new Error("Personal request execution identity changed");
+	const candidates = [...request ? [] : result.connectionCandidates, ...request ? [] : connectionCandidates(params.query)].filter((candidate, index, all) => all.findIndex((item) => item.candidateRef === candidate.candidateRef) === index).slice(0, params.limit ?? 8);
+	let installCandidates = [];
+	let installCatalogError;
+	const config = getConfig?.();
+	if (!request && !params.sources?.length && result.tools.length === 0 && candidates.length === 0 && config) try {
+		installCandidates = await searchStoreConnectorInstallCandidates(config, params.query, params.limit ?? 5);
+	} catch (error) {
+		installCatalogError = error instanceof Error ? error.message : String(error);
+	}
+	return {
+		...result,
+		connectionCandidates: candidates,
+		installCandidates,
+		...result.tools.length === 0 && (candidates.length > 0 || installCandidates.length > 0) ? { instruction: "No executable tool matched this search. This alone does not prove the account is disconnected. Retry without restrictive sources and inspect the returned account state. If authorization or account selection is actually required, call xopc_require_connection with an exact candidateRef from this result; the host owns selection, authorization and automatic continuation. Do not ask the user whether to perform an already requested read, or to reply continue after authorization. Do not fall back to browser automation unless the user explicitly asked for browser use or skips the connection." } : {},
+		...result.tools.length > 0 ? { instruction: "Describe the relevant tool contracts and execute the requested read using the available authorized account. The user request already authorizes these reads; do not ask for another confirmation. Respect the exact contracts and host permission checks. Hand off to the user only when a required authorization, ambiguous account choice or essential missing decision cannot be resolved from existing context." } : {},
+		...installCatalogError ? { installCatalogError } : {},
+		...excludedSources.length ? { searchScope: {
+			excludedSources,
+			instruction: "This search excluded these sources. Results from other apps do not establish that the requested app is unavailable. Retry without sources before declaring a capability unavailable or requesting authorization. Feishu/Lark, WeCom and WPS 365 connectors use cli."
+		} } : {},
+		selectedConnections: !request && getContext?.()?.conversationId ? connectionBindings(getContext().conversationId) : [],
+		waitingObjective: !request && getContext?.()?.conversationId ? getActiveConnectionWait(getContext().conversationId)?.summary : void 0,
+		...request ? {
+			selectedAccountId: request.accountId,
+			instruction: "Use only this request connector and selected account. Describe matching contracts before execution. If the selected account needs authorization, use personal_request_connection; the main chat owns reconnection and automatic continuation."
+		} : {}
+	};
+}
+//#endregion
+export { discoverExternalTools };

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

@@ -2,14 +2,14 @@ import { ExternalEffectNotAppliedError, executeExternalOperation } from "../../c
 import { canonicalCapabilityJson } from "../../capabilities/runtime/dispatcher.js";
 import { init_src } from "../../../packages/computer-control-contract/src/index.js";
 import "../../../packages/browser-control-contract/src/index.js";
+import { externalToolRef, parseExternalToolRef } from "./refs.js";
 import { extractDocumentText } from "../../document-understanding/extract.js";
-import { EndpointToolExecutionError } from "../../endpoint-tools/invocation-service.js";
+import { prepareImageForModel } from "../image/prepare-image-for-model.js";
 import { processLocationTask } from "../../endpoint-tools/location-task.js";
 import { projectDeviceReading } from "../../endpoint-tools/result-projector.js";
-import { DeviceTargetResolver } from "../../endpoint-tools/target-resolver.js";
 import { getEndpointDeviceSettings } from "../../storage/sqlite/endpoint-device-settings-repository.js";
-import { externalToolRef, parseExternalToolRef } from "./refs.js";
-import { prepareImageForModel } from "../image/prepare-image-for-model.js";
+import { DeviceTargetResolver } from "../../endpoint-tools/target-resolver.js";
+import { EndpointToolExecutionError } from "../../endpoint-tools/invocation-service.js";
 import { createHash } from "node:crypto";
 //#region src/agent/external-tools/endpoint-provider.ts
 init_src();

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

@@ -1,6 +1,6 @@
+import { getXopcToolMetadata } from "../embedded/tool-metadata.js";
 import { externalToolRef, parseExternalToolRef } from "./refs.js";
 import { executeToolWithProtection } from "../tools/executor.js";
-import { getXopcToolMetadata } from "../embedded/tool-metadata.js";
 //#region src/agent/external-tools/extension-provider.ts
 function toolSummary(tool) {
 	return tool.description || tool.label || tool.name;