@xopcai/xopc 0.0.433 → 0.0.434

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

@@ -1,7 +1,7 @@
-import { init_src } from "../../../packages/computer-control-contract/src/index.js";
-import "../../../packages/browser-control-contract/src/index.js";
 import { ExternalEffectNotAppliedError, executeExternalOperation } from "../../capabilities/runtime/external-operations.js";
 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 { prepareImageForModel } from "../image/prepare-image-for-model.js";

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

@@ -2,18 +2,20 @@ import { init_connection, isXopcDatabaseOpen } from "../../storage/sqlite/connec
 import { init_request_repository, personalRequestForExecution } from "../../personal-agent/request-repository.js";
 import { getConnectorAccount, init_connector_account_repository } from "../../storage/sqlite/connector-account-repository.js";
 import { getConnectorConnection, getConnectorInstallation, init_connector_repository, listConnectorActionMetadata, listConnectorConnections } from "../../storage/sqlite/connector-repository.js";
-import { connectionBindings, getActiveConnectionWait, init_connection_wait_repository, publishConnectionWait, requireSessionConnection, reviseCurrentConnectionObjective } from "../../storage/sqlite/connection-wait-repository.js";
+import { connectionBindings, init_connection_wait_repository, publishConnectionWait, requireSessionConnection, reviseCurrentConnectionObjective } from "../../storage/sqlite/connection-wait-repository.js";
 import { getSessionMetadata } from "../../storage/sqlite/session-read-repository.js";
 import { init_session_repository } from "../../storage/sqlite/session-repository.js";
 import { connectorPrincipalForSession } from "../../connectors/principal.js";
 import { setXopcToolMetadata } from "../embedded/tool-metadata.js";
 import { listConnectorInstances } from "../../connectors/instances.js";
 import { parseExternalToolRef } from "./refs.js";
-import { getStoreConnectorInstallPlan, parseStoreConnectorCandidateRef, searchStoreConnectorInstallCandidates } from "../../capabilities/store-connector.js";
-import { assertPersonalRequestAccountAccess } from "../../personal-agent/request-access.js";
-import { connectionCandidates, resolveConnectionCandidate } from "../../connectors/connection-candidates.js";
+import { getStoreConnectorInstallPlan, parseStoreConnectorCandidateRef } from "../../capabilities/store-connector.js";
+import { createPersonalRequestExecutionAuthorizer } from "../../personal-agent/request-access.js";
+import { resolveConnectionCandidate } from "../../connectors/connection-candidates.js";
 import { ExternalToolService } from "./service.js";
 import { EXTERNAL_TOOL_SOURCES } from "./types.js";
+import { discoverExternalTools } from "./discovery.js";
+import { personalRequestToolScope, scopePersonalRequestProvider } from "./personal-request-scope.js";
 import { bindExternalToolRegistry } from "./tool-registry.js";
 import { Type } from "@sinclair/typebox";
 //#region src/agent/external-tools/gateway-tools.ts
@@ -44,10 +46,10 @@ const ToolSearchSchema = Type.Object({
 const ToolDescribeSchema = Type.Object({ toolRefs: Type.Array(Type.String(), {
 	minItems: 1,
 	maxItems: 3,
-	description: "Exact tool references returned by xopc_tool_search."
+	description: "Exact tool references returned by tool_search."
 }) });
 const ToolExecuteSchema = Type.Object({
-	toolRef: Type.String({ description: "Exact tool reference returned by xopc_tool_search." }),
+	toolRef: Type.String({ description: "Exact tool reference returned by tool_search." }),
 	revision: Type.String({ description: "Exact contract revision returned by xopc_tool_describe." }),
 	arguments: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
 	approvalId: Type.Optional(Type.String({ description: "One-time approval id when execution requested confirmation." })),
@@ -63,7 +65,15 @@ function textResult(value, details = {}) {
 	};
 }
 function createExternalToolGatewayTools(providers, getContext, getConfig, getExecutionConversationId, nativeSources = [], executorConfig) {
-	const service = new ExternalToolService(providers);
+	const getRequest = () => personalRequestToolScope(getExecutionConversationId?.() ?? getContext?.()?.conversationId);
+	const service = new ExternalToolService(providers.map((provider) => scopePersonalRequestProvider(provider, getRequest, getConfig)));
+	const discoveryDeps = {
+		service,
+		nativeSources,
+		getContext,
+		getConfig,
+		getRequest
+	};
 	const gatewaySources = EXTERNAL_TOOL_SOURCES.filter((source) => !nativeSources.includes(source));
 	const assertGatewayRef = (ref) => {
 		if (nativeSources.some((source) => ref.startsWith(`${source}:`))) throw new Error("Use tool_search to load this native tool, then call it directly.");
@@ -74,45 +84,13 @@ function createExternalToolGatewayTools(providers, getContext, getConfig, getExe
 		description: `Search external tools from these sources: ${gatewaySources.join(", ")}.${nativeSources.length ? ` Use tool_search for native ${nativeSources.join(", ")} tools.` : ""} CLI connectors include Feishu/Lark, WeCom and WPS 365. Omit sources unless intentionally restricting the search; do not guess a source list. Use concise English capability keywords, e.g. "wecom doc.search". Returns executable tools, connection candidates, or reviewed Store install candidates. Call xopc_tool_describe before executing a tool. When no executable tool exists but a connection or install candidate is returned, use xopc_require_connection instead of falling back to browser automation. If a source-filtered search finds no relevant tools, retry without sources before concluding a capability is unavailable.`,
 		parameters: ToolSearchSchema,
 		async execute(_toolCallId, params) {
-			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 textResult({
-				tools: [],
-				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 candidates = [...result.connectionCandidates, ...connectionCandidates(params.query)].filter((candidate, index, all) => all.findIndex((item) => item.candidateRef === candidate.candidateRef) === index);
-			let installCandidates = [];
-			let installCatalogError;
-			const config = getConfig?.();
-			if (!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 textResult({
-				...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: getContext?.()?.conversationId ? connectionBindings(getContext().conversationId) : [],
-				waitingObjective: getContext?.()?.conversationId ? getActiveConnectionWait(getContext().conversationId)?.summary : void 0
-			});
+			return textResult(await discoverExternalTools(discoveryDeps, params));
 		}
 	};
 	const describeTool = {
 		name: EXTERNAL_TOOL_NAMES.describe,
 		label: "📋 External Tool Contract",
-		description: "Load exact contracts for up to three external tools returned by xopc_tool_search.",
+		description: "Load exact contracts for up to three external tools returned by tool_search.",
 		parameters: ToolDescribeSchema,
 		async execute(_toolCallId, params) {
 			params.toolRefs.forEach(assertGatewayRef);
@@ -131,6 +109,7 @@ function createExternalToolGatewayTools(providers, getContext, getConfig, getExe
 		async execute(toolCallId, params, signal, onUpdate) {
 			const conversationId = getExecutionConversationId?.() ?? getContext?.()?.conversationId;
 			const request = conversationId ? personalRequestForExecution(conversationId) : void 0;
+			let authorize;
 			if (!request && conversationId && isXopcDatabaseOpen() && getSessionMetadata(conversationId)?.customData?.personalReadRequestId) throw new Error("Personal request is no longer active");
 			if (request) {
 				if ([
@@ -145,7 +124,7 @@ function createExternalToolGatewayTools(providers, getContext, getConfig, getExe
 				const connectorId = composio ? getConnectorInstallation(composio.namespace)?.connectorId : cli && config ? listConnectorInstances(config).find((instance) => instance.instanceId === cli.namespace)?.connectorId : void 0;
 				if (connectorId !== request.connectorId) throw new Error("Use only the selected Personal request connector");
 				if (composio && !listConnectorActionMetadata(connectorId).some((action) => action.actionId === composio.toolName && action.scope === "read" && action.curated)) throw new Error("Personal requests permit only curated read operations");
-				assertPersonalRequestAccountAccess(request);
+				authorize = createPersonalRequestExecutionAuthorizer(conversationId, request);
 				const account = getConnectorAccount(request.accountId);
 				const connection = account?.currentConnectionId ? getConnectorConnection(account.currentConnectionId) : void 0;
 				if (!connection || connection.status !== "active" || connection.expiresAt && Date.parse(connection.expiresAt) <= Date.now()) {
@@ -168,7 +147,7 @@ function createExternalToolGatewayTools(providers, getContext, getConfig, getExe
 					toolCallId,
 					signal,
 					onUpdate,
-					...request ? { authorize: () => assertPersonalRequestAccountAccess(request) } : {}
+					...authorize ? { authorize } : {}
 				}
 			});
 			return {
@@ -190,7 +169,8 @@ function createExternalToolGatewayTools(providers, getContext, getConfig, getExe
 		service,
 		nativeSources,
 		execute: nativeExecute,
-		executorConfig
+		executorConfig,
+		search: (params) => discoverExternalTools(discoveryDeps, params)
 	});
 	const requireSchema = Type.Object({
 		requirements: Type.Array(Type.Object({
@@ -223,7 +203,7 @@ function createExternalToolGatewayTools(providers, getContext, getConfig, getExe
 		name: EXTERNAL_TOOL_NAMES.requireConnection,
 		label: "Connect app",
 		parameters: requireSchema,
-		description: "Use only when a requested read cannot proceed because authorization, installation or account selection is required. Available authorized tools should be executed directly without asking the user to confirm the read. Request an exact connectionCandidates or installCandidates entry returned by xopc_tool_search. Explain the verified need once before calling. This saves and pauses the objective, displays one action area above the input, and lets the host resume automatically after the required user action. Stop this turn after connection_required; never ask the user to reply continue after authorization. Never invent a candidate reference, return OAuth URLs, or repeat a skipped request. If another objective is waiting, do not create a duplicate objective.",
+		description: "Use only when a requested read cannot proceed because authorization, installation or account selection is required. Available authorized tools should be executed directly without asking the user to confirm the read. Request an exact connectionCandidates or installCandidates entry returned by tool_search. Explain the verified need once before calling. This saves and pauses the objective, displays one action area above the input, and lets the host resume automatically after the required user action. Stop this turn after connection_required; never ask the user to reply continue after authorization. Never invent a candidate reference, return OAuth URLs, or repeat a skipped request. If another objective is waiting, do not create a duplicate objective.",
 		async execute(_id, params) {
 			const context = getContext?.();
 			if (!context) throw new Error("No active conversation.");
@@ -313,7 +293,7 @@ function createExternalToolGatewayTools(providers, getContext, getConfig, getExe
 		}
 	};
 	return [
-		searchTool,
+		setXopcToolMetadata(searchTool, { exposure: "hidden" }),
 		describeTool,
 		executeTool,
 		setXopcToolMetadata(requireTool, { exposure: "model-only" }),

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

@@ -13,6 +13,7 @@ export interface DefaultExternalToolGatewayDeps {
     agentId?: string;
     extensionRegistry?: ExtensionRegistry;
     disabledTools?: Set<string>;
+    toolAllowlist?: readonly string[];
     hookRunner?: ExtensionHookRunner;
     toolExecutorConfig?: Partial<ToolExecutorConfig>;
     getMemoryManager?: () => MemoryManager;

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

@@ -68,6 +68,13 @@ function createDefaultExternalToolGatewayTools(deps) {
 		"memory"
 	], deps.toolExecutorConfig);
 	const registry = getExternalToolRegistry(tools);
+	if (registry) {
+		const native = !deps.disabledTools?.has("tool_search");
+		registry.discovery = {
+			native,
+			connectors: native && !deps.disabledTools?.has("xopc_tool_search") && (!deps.toolAllowlist || deps.toolAllowlist.includes("tool_search") || deps.toolAllowlist.includes("xopc_tool_search"))
+		};
+	}
 	if (registry && deps.endpointTools) {
 		const endpoints = deps.endpointTools;
 		registry.subscribeInvalidation = (conversationId, ref, listener) => {

package/dist/src/agent/external-tools/personal-request-scope.d.ts

@@ -0,0 +1,7 @@
+import type { Config } from '../../config/schema.js';
+import { type PersonalRequest } from '../../personal-agent/request-repository.js';
+import type { ExternalToolProvider } from './types.js';
+/** Read scope follows persisted request identity, including cancelled or detached workers. */
+export declare function personalRequestToolScope(conversationId?: string): PersonalRequest | undefined;
+/** Apply the same connector, account and curated-read boundary before search ranking and describe. */
+export declare function scopePersonalRequestProvider(provider: ExternalToolProvider, getRequest: () => PersonalRequest | undefined, getConfig?: () => Config | undefined): ExternalToolProvider;

package/dist/src/agent/external-tools/personal-request-scope.js

@@ -0,0 +1,83 @@
+import { init_connection, isXopcDatabaseOpen } from "../../storage/sqlite/connection.js";
+import { init_request_repository, personalRequestForExecution } from "../../personal-agent/request-repository.js";
+import { getConnectorInstallation, init_connector_repository, listConnectorActionMetadata } from "../../storage/sqlite/connector-repository.js";
+import { getSessionMetadata } from "../../storage/sqlite/session-read-repository.js";
+import { init_session_repository } from "../../storage/sqlite/session-repository.js";
+import { listConnectorInstances } from "../../connectors/instances.js";
+import { parseExternalToolRef } from "./refs.js";
+import { assertPersonalRequestAccountAccess } from "../../personal-agent/request-access.js";
+//#region src/agent/external-tools/personal-request-scope.ts
+init_request_repository();
+init_connection();
+init_connector_repository();
+init_session_repository();
+/** Read scope follows persisted request identity, including cancelled or detached workers. */
+function personalRequestToolScope(conversationId) {
+	const request = conversationId ? personalRequestForExecution(conversationId) : void 0;
+	if (!request && conversationId && isXopcDatabaseOpen() && getSessionMetadata(conversationId)?.customData?.personalReadRequestId) throw new Error("Personal request is no longer active");
+	if (request) assertPersonalRequestAccountAccess(request);
+	return request;
+}
+/** Apply the same connector, account and curated-read boundary before search ranking and describe. */
+function scopePersonalRequestProvider(provider, getRequest, getConfig) {
+	const describe = async (ref) => {
+		const request = getRequest();
+		if (!request) return provider.describe(ref);
+		if (!request.accountId) throw new Error("Personal request requires a selected account");
+		const parsed = parseExternalToolRef(ref, provider.source);
+		if (!parsed || !["cli", "composio"].includes(provider.source)) return void 0;
+		const config = getConfig?.();
+		const connectorId = provider.source === "composio" ? getConnectorInstallation(parsed.namespace)?.connectorId : config ? listConnectorInstances(config).find((instance) => instance.instanceId === parsed.namespace)?.connectorId : void 0;
+		if (connectorId !== request.connectorId) return void 0;
+		if (provider.source === "composio" && !listConnectorActionMetadata(connectorId).some((action) => action.actionId === parsed.toolName && action.scope === "read" && action.curated)) return void 0;
+		const descriptor = await provider.describe(ref, {
+			connectorId: request.connectorId,
+			accountId: request.accountId
+		});
+		const current = getRequest();
+		if (!current || current.accountId !== request.accountId || current.connectorId !== request.connectorId || current.requestId !== request.requestId) throw new Error("Personal request execution identity changed");
+		if (!descriptor || descriptor.readOnly !== true) return void 0;
+		return {
+			...descriptor,
+			description: `${descriptor.summary}\nUse only selected account ${request.accountId}.`,
+			inputSchema: {
+				...descriptor.inputSchema,
+				properties: {
+					...descriptor.inputSchema.properties,
+					xopcAccountId: {
+						type: "string",
+						const: request.accountId
+					}
+				},
+				required: [...new Set([...descriptor.inputSchema.required ?? [], "xopcAccountId"])]
+			}
+		};
+	};
+	return {
+		source: provider.source,
+		async search(query) {
+			const request = getRequest();
+			if (!request) return provider.search(query);
+			if (!request.accountId) throw new Error("Personal request requires a selected account");
+			if (!["cli", "composio"].includes(provider.source)) return [];
+			const hits = await provider.search(query, {
+				connectorId: request.connectorId,
+				accountId: request.accountId
+			});
+			return (await Promise.all(hits.map(async (hit) => {
+				const descriptor = await describe(hit.toolRef);
+				return descriptor ? {
+					...hit,
+					summary: descriptor.summary
+				} : void 0;
+			}))).filter((hit) => hit !== void 0);
+		},
+		async connectionCandidates(query) {
+			return getRequest() ? [] : await provider.connectionCandidates?.(query) ?? [];
+		},
+		describe,
+		execute: (ref, args, approvalId, context) => provider.execute(ref, args, approvalId, context)
+	};
+}
+//#endregion
+export { personalRequestToolScope, scopePersonalRequestProvider };

package/dist/src/agent/external-tools/read-policy.js

@@ -3,16 +3,17 @@
 function withExternalReadPolicy(provider, getPolicy) {
 	return {
 		source: provider.source,
-		search: (query) => provider.search(query),
+		search: (query, context) => context ? provider.search(query, context) : provider.search(query),
 		...provider.connectionCandidates ? { connectionCandidates: provider.connectionCandidates.bind(provider) } : {},
-		describe: async (ref) => {
-			const descriptor = await provider.describe(ref);
+		describe: async (ref, context) => {
+			const descriptor = await (context ? provider.describe(ref, context) : provider.describe(ref));
 			if (!descriptor) return void 0;
 			const policy = getPolicy(ref);
 			if (policy?.mode === "deny") return void 0;
+			const batchRead = descriptor.readOnly === false ? false : provider.source === "endpoint" ? descriptor.batchRead === true && policy?.readOnly !== false : policy?.readOnly ?? descriptor.batchRead;
 			return {
 				...descriptor,
-				batchRead: provider.source === "endpoint" ? descriptor.batchRead === true && policy?.readOnly !== false : policy?.readOnly ?? descriptor.batchRead
+				batchRead
 			};
 		},
 		execute: (ref, args, approval, context) => provider.execute(ref, args, approval, context)

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

@@ -10,6 +10,8 @@ export declare class ExternalToolService {
         query: string;
         sources?: ExternalToolSource[];
         limit?: number;
+        signal?: AbortSignal;
+        timeoutMs?: number;
     }): Promise<{
         tools: ExternalToolSearchHit[];
         connectionCandidates: ExternalConnectionCandidate[];

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

@@ -31,6 +31,7 @@ function descriptorRevision(descriptor) {
 		outputSchema: descriptor.outputSchema,
 		annotations: descriptor.annotations,
 		batchRead: descriptor.batchRead === true,
+		readOnly: descriptor.readOnly,
 		contractRevision: descriptor.contractRevision,
 		exposure: descriptor.exposure
 	})).digest("hex").slice(0, 16);
@@ -65,11 +66,12 @@ var ExternalToolService = class {
 	}
 	async search(params) {
 		const selected = params.sources?.length ? params.sources.map((source) => this.providerBySource.get(source)).filter((provider) => provider !== void 0) : [...this.providerBySource.values()];
-		const settled = await Promise.allSettled(selected.map(async (provider) => ({
+		const settled = await Promise.allSettled(selected.map((provider) => searchWithDeadline(async () => ({
 			provider,
 			hits: await provider.search(params.query),
 			candidates: await provider.connectionCandidates?.(params.query) ?? []
-		})));
+		}), params.timeoutMs, params.signal)));
+		params.signal?.throwIfAborted();
 		const unavailableSources = [];
 		const sourceErrors = [];
 		const hits = [];
@@ -137,7 +139,7 @@ var ExternalToolService = class {
 		const descriptor = await provider.describe(params.toolRef);
 		if (!descriptor) throw new Error(`External tool is unavailable: ${params.toolRef}`);
 		const current = versionDescriptor(descriptor);
-		if (params.personalReadOnly && current.readOnly !== true && current.batchRead !== true) throw new Error("This external operation has no host-curated read-only contract");
+		if (params.personalReadOnly && current.readOnly !== true) throw new Error("This external operation has no host-curated read-only contract");
 		if (params.readOnly && current.batchRead !== true) throw new Error("This external operation is not approved for batch reads");
 		if (current.revision !== params.revision) throw new Error(`Tool contract changed. Describe ${params.toolRef} again before executing it.`);
 		const args = params.arguments ?? {};
@@ -165,5 +167,22 @@ var ExternalToolService = class {
 		return this.providerBySource.get(toolRef.slice(0, separator));
 	}
 };
+/** A stalled directory must not hide successful results from another provider. */
+async function searchWithDeadline(search, timeoutMs, signal) {
+	signal?.throwIfAborted();
+	if (!timeoutMs && !signal) return search();
+	let timer;
+	let onAbort;
+	try {
+		return await Promise.race([search(), new Promise((_resolve, reject) => {
+			if (timeoutMs) timer = setTimeout(() => reject(Object.assign(/* @__PURE__ */ new Error("Tool source discovery timed out"), { code: "discovery_timeout" })), timeoutMs);
+			onAbort = () => reject(signal?.reason ?? /* @__PURE__ */ new Error("Tool search aborted"));
+			signal?.addEventListener("abort", onAbort, { once: true });
+		})]);
+	} finally {
+		clearTimeout(timer);
+		if (onAbort) signal?.removeEventListener("abort", onAbort);
+	}
+}
 //#endregion
 export { ExternalToolService };

package/dist/src/agent/external-tools/tool-registry.d.ts

@@ -1,11 +1,17 @@
 import type { AgentTool } from '@earendil-works/pi-agent-core';
+import type { ExternalDiscoveryParams, ExternalDiscoveryResult } from './discovery.js';
 import type { ExternalToolService } from './service.js';
 import type { ExternalToolSource } from './types.js';
 import type { ToolInvalidationReason } from '../embedded/tool-metadata.js';
 import type { ToolExecutorConfig } from '../tools/executor.js';
 export interface ExternalToolRegistry {
     service: ExternalToolService;
+    search: (params: ExternalDiscoveryParams) => Promise<ExternalDiscoveryResult>;
     nativeSources: readonly ExternalToolSource[];
+    discovery?: {
+        native: boolean;
+        connectors: boolean;
+    };
     execute: AgentTool['execute'];
     executorConfig?: Partial<ToolExecutorConfig>;
     subscribeInvalidation?: (conversationId: string, toolRef: string, listener: (reason?: ToolInvalidationReason) => void) => () => void;

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

@@ -48,10 +48,15 @@ export interface ExternalToolTurnContext {
     conversationId: string;
     origin: TurnOrigin;
 }
+/** Host-selected discovery scope; never supplied by the model. */
+export interface ExternalToolDiscoveryContext {
+    connectorId: string;
+    accountId: string;
+}
 export interface ExternalToolProvider {
     readonly source: ExternalToolSource;
-    search(query: string): Promise<ExternalToolSearchHit[]>;
+    search(query: string, context?: ExternalToolDiscoveryContext): Promise<ExternalToolSearchHit[]>;
     connectionCandidates?(query: string): Promise<ExternalConnectionCandidate[]>;
-    describe(toolRef: string): Promise<ExternalToolDescriptor | undefined>;
+    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>>>;
 }

package/dist/src/agent/inbound/turn-dispatcher.d.ts

@@ -91,7 +91,7 @@ export declare class TurnDispatcher {
      * after current tool work, before the next LLM call). See `Agent.steer`
      * in `@earendil-works/pi-agent-core`.
      */
-    steerWebchatSession(conversationId: string, text: string): Promise<boolean>;
+    steerWebchatSession(conversationId: string, text: string, expectedRunId?: string): Promise<boolean>;
     private buildStreamingDeps;
     private buildOneShotDeps;
 }

package/dist/src/agent/inbound/turn-dispatcher.js

@@ -76,16 +76,17 @@ var TurnDispatcher = class {
 	* after current tool work, before the next LLM call). See `Agent.steer`
 	* in `@earendil-works/pi-agent-core`.
 	*/
-	async steerWebchatSession(conversationId, text) {
+	async steerWebchatSession(conversationId, text, expectedRunId) {
 		const trimmed = text.trim();
 		if (!trimmed) return false;
 		try {
-			return await queueEmbeddedSteer(conversationId, trimmed);
+			return await queueEmbeddedSteer(conversationId, trimmed, expectedRunId);
 		} catch (err) {
 			this.log.warn({
 				err,
 				conversationId
 			}, "steerWebchatSession failed");
+			if (expectedRunId !== void 0) throw err;
 			return false;
 		}
 	}

package/dist/src/agent/orchestration/llm-turn-retry.d.ts

@@ -13,7 +13,7 @@ export declare function getLastAssistantMessage(messages: AgentMessage[]): Agent
 export declare function getAssistantTurnErrorMessage(agent: Agent): string | undefined;
 /** After waitForIdle + transient retries, true if the last assistant turn ended in error. */
 export declare function isAssistantTurnFailed(agent: Agent): boolean;
-/** User or client aborted the assistant turn — do not try another model. */
+/** Provider reported an aborted stream; the host signal determines whether the run was cancelled. */
 export declare function isAssistantTurnAborted(agent: Agent): boolean;
 /**
  * Remove trailing assistant messages that ended in error/aborted (typically one).

package/dist/src/agent/orchestration/llm-turn-retry.js

@@ -7,7 +7,7 @@ function isTransientLlmErrorMessage(message) {
 }
 function classifyLlmFailure(message) {
 	const normalized = message.trim().toLowerCase();
-	if (normalized === "aborted" || normalized.includes("aborterror")) return "aborted";
+	if (normalized === "aborted" || normalized.includes("aborterror") || normalized === "request was aborted" || normalized === "the operation was aborted") return "aborted";
 	if (isContextOverflowError(message)) return "context_overflow";
 	if (isTransientLlmErrorMessage(message)) return "transient_network";
 	return "permanent";
@@ -19,7 +19,8 @@ function getLastAssistantMessage(messages) {
 function getAssistantTurnErrorMessage(agent) {
 	const last = getLastAssistantMessage(agent.state.messages);
 	if (!last) return void 0;
-	if (last.stopReason !== "error") return void 0;
+	const stopReason = last.stopReason;
+	if (stopReason !== "error" && stopReason !== "aborted") return void 0;
 	const errMsg = last.errorMessage;
 	if (typeof errMsg === "string" && errMsg.trim()) return errMsg.trim();
 }
@@ -29,7 +30,7 @@ function isAssistantTurnFailed(agent) {
 	if (!last) return true;
 	return last.stopReason === "error";
 }
-/** User or client aborted the assistant turn — do not try another model. */
+/** Provider reported an aborted stream; the host signal determines whether the run was cancelled. */
 function isAssistantTurnAborted(agent) {
 	const last = getLastAssistantMessage(agent.state.messages);
 	if (!last) return false;
@@ -78,10 +79,12 @@ async function maybeRetryTurnAfterTransientLlmFailure(agent, options) {
 	while (budget.continues < maxContinues && options.shouldRetry?.() !== false) {
 		const last = getLastAssistantMessage(agent.state.messages);
 		if (!last) return;
-		if (last.stopReason !== "error") return;
+		const sr = last.stopReason;
+		if (sr !== "error" && sr !== "aborted") return;
 		const errMsg = String(last.errorMessage || "");
-		const failureKind = classifyLlmFailure(errMsg);
-		if (failureKind !== "transient_network") {
+		const failureKind = sr === "aborted" ? "aborted" : classifyLlmFailure(errMsg);
+		const providerAborted = failureKind === "aborted" && options.signal !== void 0 && !options.signal.aborted;
+		if (failureKind !== "transient_network" && !providerAborted) {
 			options.log.warn({
 				conversationId: options.conversationId,
 				errorMessage: errMsg,
@@ -89,7 +92,8 @@ async function maybeRetryTurnAfterTransientLlmFailure(agent, options) {
 			}, "Assistant turn ended with error (not retrying as transient)");
 			return;
 		}
-		if (!canResumeAfterModelFailure(agent.state.messages)) {
+		const trimmed = stripTrailingErrorAssistantMessages(agent.state.messages);
+		if (agent.state.messages.slice(trimmed.length).some((message) => message.role === "assistant" && Array.isArray(message.content) && message.content.some((block) => block.type === "toolCall")) || !canResumeAfterModelFailure(trimmed)) {
 			options.log.warn({ conversationId: options.conversationId }, "Model recovery stopped because a tool outcome is unconfirmed");
 			return;
 		}
@@ -102,6 +106,8 @@ async function maybeRetryTurnAfterTransientLlmFailure(agent, options) {
 			conversationId: options.conversationId,
 			errorMessage: errMsg,
 			failureKind,
+			phase: "model_request_recovery",
+			hostSignalAborted: options.signal?.aborted ?? false,
 			continueAttempt: continues,
 			maxContinues,
 			retryDelayMs
@@ -109,7 +115,6 @@ async function maybeRetryTurnAfterTransientLlmFailure(agent, options) {
 		await waitForRetryDelay(retryDelayMs, options.signal);
 		options.signal?.throwIfAborted();
 		options.onRetry?.();
-		const trimmed = stripTrailingErrorAssistantMessages(agent.state.messages);
 		agent.state.messages = trimmed;
 		await agent.continue();
 		await agent.waitForIdle();

package/dist/src/agent/orchestration/run-agent-turn-with-timeout.d.ts

@@ -23,4 +23,5 @@ export declare function isAgentTurnTimeoutError(err: unknown): boolean;
 export declare function runAgentTurnWithTimeout(agent: Agent, runTurn: () => Promise<void>, timeoutMs: number, options?: {
     abortGraceMs?: number;
     timeoutExtensionMs?: () => number;
+    onTimeout?: (reason: AgentRunDeadlineError) => void;
 }): Promise<void>;

package/dist/src/agent/orchestration/run-agent-turn-with-timeout.js

@@ -41,7 +41,9 @@ async function runAgentTurnWithTimeout(agent, runTurn, timeoutMs, options = {})
 				timeoutId = setTimeout(expire, extensionMs);
 				return;
 			}
-			reject(new AgentRunDeadlineError(`Agent turn timed out after ${effectiveTimeoutMs / 1e3}s`));
+			const reason = new AgentRunDeadlineError(`Agent turn timed out after ${effectiveTimeoutMs / 1e3}s`);
+			options.onTimeout?.(reason);
+			reject(reason);
 		};
 		timeoutId = setTimeout(expire, timeoutMs);
 	});

package/dist/src/agent/prompt/sections/tooling.js

@@ -132,7 +132,7 @@ function buildToolingSection(params) {
 		"## Tooling",
 		"Tool availability (filtered by policy):",
 		"Use only case-sensitive names in current function schemas; prose/history examples grant no tool. Never probe invented names. Missing prerequisites: give a final blocker, without unrelated calls.",
-		availableTools.has("tool_search") ? "Registered tools may be deferred. Use tool_search for the exact name before reporting it missing; call only after its schema loads." : "",
+		availableTools.has("tool_search") || availableTools.has("xopc_tool_execute") ? "Use tool_search as the single tool discovery entry. loadedTools can be called after their schemas load; externalTools require xopc_tool_describe then xopc_tool_execute. Connection candidates are recovery options, not proof of missing authorization. Respect the current execution scope." : "",
 		hasPublishArtifacts && !hasRead && !hasWrite && !hasPatch && !hasExec ? "Only publication is available for workspace files. For a request to edit then publish, editing is blocked: make no publication call and explain the limitation. Publish an existing file only when the user requests that existing content without an outstanding edit." : "",
 		"When a tool returns an xopc product link, reuse its exact URL in a Markdown link with a short descriptive label in the user's language (for example, [打开会话](url)). Do not invent link parameters, escape the link brackets/parentheses, or wrap a navigation link in a code span. Avoid repeating raw URLs or internal object metadata unless requested.",
 		toolLines.length > 0 ? toolLines.join("\n") : "- No tools are registered for this session.",

package/dist/src/agent/service.js

@@ -2,13 +2,13 @@ import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { parseNoteAttachmentTarget } from "../notes/attachment-ref.js";
 import { init_agent_scope, resolveAgentHomeDir, resolveDefaultAgentId } from "./agent-scope.js";
+import { extractTextContent } from "./context/workspace.js";
 import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
 import { init_agent_session_key, resolveAgentIdFromConversationId } from "../routing/agent-session-key.js";
 import { extractProfileAgentId, resolveEffectiveAgentConfigForSession } from "../config/agent-profile.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";