@xopcai/xopc 0.0.432 → 0.0.434

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 { getStoreConnectorInstallPlan, parseStoreConnectorCandidateRef, searchStoreConnectorInstallCandidates } from "../../capabilities/store-connector.js";
-import { connectionCandidates, resolveConnectionCandidate } from "../../connectors/connection-candidates.js";
 import { parseExternalToolRef } from "./refs.js";
-import { setXopcToolMetadata } from "../embedded/tool-metadata.js";
-import { assertPersonalRequestAccountAccess } from "../../personal-agent/request-access.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/memory-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/memory-provider.ts
 function toolSummary(tool) {
 	return tool.description || tool.label || tool.name;

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/image/generation/openai-images-provider.js

@@ -5,10 +5,10 @@ import { privateNetworkPolicyToSsrfGuardOptions } from "../../../media-shared/ht
 import { resolveProviderHttpRequestConfig } from "../../../media-shared/http/resolve-provider-http-request-config.js";
 import { postJsonRequest, postMultipartRequest, readJsonResponseLimited } from "../../../media-shared/http/provider-http.js";
 import "../../../media-shared/http/index.js";
+import { imageFileExtensionForMimeType } from "./image-assets.js";
 import { ImageProviderError, validateImageRequest } from "../../../../packages/image-providers/src/validation.js";
 import { decodeBase64, imageFromBytes } from "../../../../packages/image-providers/src/http.js";
 import "../../../../packages/image-providers/src/index.js";
-import { imageFileExtensionForMimeType } from "./image-assets.js";
 //#region src/agent/image/generation/openai-images-provider.ts
 /** Strict implementation of the OpenAI Images REST protocol. */
 init_logger();

package/dist/src/agent/image/generation/runtime.js

@@ -4,12 +4,12 @@ import { assertProviderUsage, init_model_usage } from "../../../providers/model-
 import { PROVIDER_ENV_MAP, init_env_keys } from "../../../providers/env-keys.js";
 import { ImageProviderError, normalizeImageGeometry } from "../../../../packages/image-providers/src/validation.js";
 import "../../../../packages/image-providers/src/index.js";
-import { getImageGenerationProvider, listImageGenerationProviders, listImageGenerationProvidersSummary as listImageGenerationProvidersSummary$1 } from "./provider-registry.js";
 import { describeFailoverError, isFailoverError } from "../../failover-error.js";
 import { buildNoCapabilityModelConfiguredMessage, recordCapabilityCandidateFailure, resolveCapabilityModelCandidates, throwCapabilityGenerationFailure } from "../../media-generation/runtime-shared.js";
 import "../../media-generation/index.js";
 import { parseImageGenerationModelRef } from "./model-ref.js";
 import { validateImageGenerationRequest } from "./validation.js";
+import { getImageGenerationProvider, listImageGenerationProviders, listImageGenerationProvidersSummary as listImageGenerationProvidersSummary$1 } from "./provider-registry.js";
 //#region src/agent/image/generation/runtime.ts
 init_model_usage();
 init_env_keys();

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

@@ -1,9 +1,9 @@
-import { getImageGenerationProvider, listImageGenerationProviders } from "./generation/provider-registry.js";
 import { getImageUnderstandingProvider, listImageUnderstandingProviders, registerImageUnderstandingProvider } from "./understanding/provider-registry.js";
 import { resolveImageModelConfigForTool } from "./tool-model-config.js";
 import { describeImages, describeImagesWithFallback } from "./understanding/runtime.js";
 import { modelSupportsVision, resolveImageHandlingStrategy } from "./vision-detection.js";
 import { runWithImageModelFallback } from "./image-model-fallback.js";
 import { loadImageForToolInput } from "./load-image-media.js";
+import { getImageGenerationProvider, listImageGenerationProviders } from "./generation/provider-registry.js";
 import { generateImage, listImageGenerationProvidersSummary } from "./generation/runtime.js";
 export { describeImages, describeImagesWithFallback, generateImage, getImageGenerationProvider, getImageUnderstandingProvider, listImageGenerationProviders, listImageGenerationProvidersSummary, listImageUnderstandingProviders, loadImageForToolInput, modelSupportsVision, registerImageUnderstandingProvider, resolveImageHandlingStrategy, resolveImageModelConfigForTool, runWithImageModelFallback };

package/dist/src/agent/inbound/attachment-pipeline.js

@@ -1,10 +1,10 @@
 import { stripRuntimeUserMessageEnvelope } from "../../../packages/gateway-contract/src/user-message-display.js";
 import { init_src } from "../../../packages/gateway-contract/src/index.js";
 import { readAgentMessageContent } from "../memory/agent-message-access.js";
+import { extractProfileAgentId } from "../../config/agent-profile.js";
+import { isPersonalConversation } from "../../personal-agent/repository.js";
 import { mimeTypeFromMediaPath } from "../../media/store.js";
 import { readMediaReference } from "../../media/media-reference.js";
-import { isPersonalConversation } from "../../personal-agent/repository.js";
-import { extractProfileAgentId } from "../../config/agent-profile.js";
 import { MODEL_IMAGE_MAX_BYTES, MODEL_IMAGE_SOURCE_MAX_BYTES, prepareImageForModel } from "../image/prepare-image-for-model.js";
 import { isImageInboundAttachment } from "../../channels/attachments/attachment-classifiers.js";
 import "../../channels/attachments/inbound-persist.js";

package/dist/src/agent/inbound/inbound-loop.js

@@ -1,10 +1,10 @@
 import { runWithLogContext, updateAsyncLogContext } from "../../utils/logger/context.js";
 import { init_logger } from "../../utils/logger.js";
 import { init_model_usage, withModelUsageOrigin } from "../../providers/model-usage.js";
-import { MessageBusShutdownError } from "../../infra/bus/queue.js";
-import "../../infra/bus/index.js";
 import { shouldSkipResetOverlapCommand } from "../../session/reset-triggers.js";
 import { initSessionTurn } from "../../session/init-session-turn.js";
+import { MessageBusShutdownError } from "../../infra/bus/queue.js";
+import "../../infra/bus/index.js";
 import { runEmbeddedTurnForSession } from "../embedded/run-for-session.js";
 import { inboundMessageLogRequestId } from "../service-inbound-utils.js";
 //#region src/agent/inbound/inbound-loop.ts

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/independent-execution.js

@@ -1,8 +1,8 @@
 import { withoutCloudCreditBudget } from "../providers/xopc-cloud-credit-budget.js";
 import { withoutEmbeddedExecutionSession } from "./embedded/execution-context.js";
-import { withoutSearchCache } from "./tools/search/cache.js";
-import { withoutDataToolPermissions } from "./tools/dataBatch.js";
 import { withoutDelegationScope } from "./orchestration/delegation-scope.js";
+import { withoutDataToolPermissions } from "./tools/dataBatch.js";
+import { withoutSearchCache } from "./tools/search/cache.js";
 //#region src/agent/independent-execution.ts
 /** Discard caller-owned execution scopes before resolving the target Agent. */
 function runInIndependentAgentExecution(run) {

package/dist/src/agent/index.js

@@ -1,14 +1,14 @@
-import { extractToolCallsFromAssistant, extractToolResultId, sanitizeToolCallId, sanitizeToolCallIdsForCloudCodeAssist } from "./transcript/tool-call-id.js";
-import { makeMissingToolResult, repairToolUseResultPairing, sanitizeToolCallInputs, sanitizeToolUseResultPairing, stripToolResultDetails } from "./transcript/session-transcript-repair.js";
 import { resolveTranscriptPolicy } from "./transcript/transcript-policy.js";
 import { dropThinkingBlocks } from "./transcript/thinking.js";
+import { extractToolCallsFromAssistant, extractToolResultId, sanitizeToolCallId, sanitizeToolCallIdsForCloudCodeAssist } from "./transcript/tool-call-id.js";
+import { makeMissingToolResult, repairToolUseResultPairing, sanitizeToolCallInputs, sanitizeToolUseResultPairing, stripToolResultDetails } from "./transcript/session-transcript-repair.js";
 import { applySessionTranscriptHygiene, applySessionTranscriptHygieneForPersistence, applySessionTranscriptHygieneWithPolicy, resolvePolicyForModel, tryApplySessionTranscriptHygiene, tryApplySessionTranscriptHygieneForPersistence } from "./transcript/transcript-hygiene.js";
-import { AgentService } from "./service.js";
 import { createResponseMessage, createSignalMessage, createTaskMessage, isValidIPCMessage } from "./ipc/types.js";
 import { AgentInbox } from "./ipc/inbox.js";
 import { AgentBus } from "./ipc/bus.js";
 import { AgentSocketClient, AgentSocketServer, isSocketAvailable } from "./ipc/socket.js";
 import "./ipc/index.js";
+import { AgentService } from "./service.js";
 import { stripToolMessages } from "./transcript/strip-tool-messages.js";
 import "./transcript/index.js";
 export { AgentBus, AgentInbox, AgentService, AgentSocketClient, AgentSocketServer, applySessionTranscriptHygiene, applySessionTranscriptHygieneForPersistence, applySessionTranscriptHygieneWithPolicy, createResponseMessage, createSignalMessage, createTaskMessage, dropThinkingBlocks, extractToolCallsFromAssistant, extractToolResultId, isSocketAvailable, isValidIPCMessage, makeMissingToolResult, repairToolUseResultPairing, resolvePolicyForModel, resolveTranscriptPolicy, sanitizeToolCallId, sanitizeToolCallIdsForCloudCodeAssist, sanitizeToolCallInputs, sanitizeToolUseResultPairing, stripToolMessages, stripToolResultDetails, tryApplySessionTranscriptHygiene, tryApplySessionTranscriptHygieneForPersistence };

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

@@ -1,9 +1,9 @@
 import { McpServerSchema, init_schema } from "../../config/schema.js";
+import { getWorkspacePath } from "../../config/workspace-path-helpers.js";
 import { isManagedConnectorServer } from "../../connectors/materialize.js";
 import { createNativeMcpCredentials } from "./credential-store.js";
 import { loadMergedMcpConfig } from "./config.js";
 import { discoverMcpTools } from "./tool-catalog.js";
-import { getWorkspacePath } from "../../config/workspace-path-helpers.js";
 import { cancelMcpAuthorization, getMcpAuthorization, probeMcpConnection, startMcpAuthorization, submitMcpRedirect } from "./connection-setup.js";
 import { createHash, randomUUID } from "node:crypto";
 //#region src/agent/mcp/connection-drafts.ts

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

@@ -8,8 +8,8 @@ import { retryAfter } from "./transport.js";
 import { McpAuthenticationRequiredError, discoverMcpTools, signInNativeMcp } from "./tool-catalog.js";
 import { classifyMcpConnectionError } from "./connection-errors.js";
 import { createHash, randomUUID } from "node:crypto";
-import { Agent } from "undici";
 import { lookup } from "node:dns";
+import { Agent } from "undici";
 //#region src/agent/mcp/connection-setup.ts
 init_logger();
 const log = createLogger("McpConnectionSetup");

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

@@ -3,9 +3,9 @@ import { init_logger } from "../../utils/logger.js";
 import { getActiveConnectionWait, init_connection_wait_repository } 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 { CredentialResolver, init_credentials } from "../../auth/credentials.js";
 import { connectorPrincipalForSession } from "../../connectors/principal.js";
 import { DurableState } from "../../storage/sqlite/durable-state.js";
-import { CredentialResolver, init_credentials } from "../../auth/credentials.js";
 import { connectorSecretProviderId } from "../../connectors/secret-store.js";
 import { isManagedConnectorServer } from "../../connectors/materialize.js";
 import { classifyMcpConnectionError } from "./connection-errors.js";

package/dist/src/agent/mcp/discovery.js

@@ -1,10 +1,10 @@
 import { getSessionMetadata, init_session_read_repository } from "../../storage/sqlite/session-read-repository.js";
 import { loadTranscriptRowsForSession } from "../../storage/sqlite/transcript-repository.js";
-import { DurableState } from "../../storage/sqlite/durable-state.js";
 import { checkUrlSafety } from "../tools/url-safety.js";
-import { fetchPublicText } from "../tools/fetch-text.js";
+import { DurableState } from "../../storage/sqlite/durable-state.js";
 import { SearchProviderRegistry } from "../tools/search/registry.js";
 import { resolveWebSearchConfig } from "../tools/search/resolve-config.js";
+import { fetchPublicText } from "../tools/fetch-text.js";
 import { extractReadableText } from "../tools/web.js";
 import { connectionPlanSchema } from "./setup-plan.js";
 import { createHash, randomUUID } from "node:crypto";

package/dist/src/agent/mcp/transport.js

@@ -1,8 +1,8 @@
 import { checkUrlSafety } from "../tools/url-safety.js";
 import { mcpStdioSupervisor } from "../../process/mcp-stdio-supervisor.js";
 import { resolve } from "node:path";
-import { Agent, fetch } from "undici";
 import { lookup } from "node:dns";
+import { Agent, fetch } from "undici";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StdioTransport, StreamableHttpTransport } from "@earendil-works/pi-mcp";
 //#region src/agent/mcp/transport.ts

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

@@ -1,6 +1,6 @@
-import { buildUserContextBlock, sanitizeUserContextFenceEscapes } from "./context-fence.js";
 import { isMemorySubsystemEnabled } from "./memory-config.js";
 import { extractAgentUserPlainText } from "./user-message-text.js";
+import { buildUserContextBlock, sanitizeUserContextFenceEscapes } from "./context-fence.js";
 import { MemoryManager } from "./manager.js";
 import { discoverMemoryPlugins } from "./plugin-discovery.js";
 import { createMemoryManagerFromConfig } from "./create-memory-manager.js";