@xopcai/xopc 0.0.247 → 0.0.249

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

@@ -1,14 +1,15 @@
+import { connectionBinding, connectionBindings, publishConnectionWait, requireSessionConnection } from "../../storage/sqlite/connection-wait-repository.js";
 import { consumeConnectorApproval, createConnectorApproval, getConnectorApproval, getConnectorInstallation, listConnectorActionMetadata, listConnectorConnections, listConnectorInstallations, upsertConnectorActionMetadata, upsertConnectorInstallation } from "../../storage/sqlite/connector-repository.js";
 import "../../storage/sqlite/index.js";
-import { init_session_key, parseSessionKey } from "../../routing/session-key.js";
 import { connectorArgumentsHash, connectorArgumentsPreview } from "../../connectors/approval.js";
 import { ComposioSessionsAdapter } from "../../connectors/composio-sessions.js";
 import { getComposioToolkitScope, getConfiguredComposioAuthConfigs, isComposioActionAllowedByCatalog, scopeForComposioAction } from "../../connectors/composio.js";
 import { getConnectorDefinition } from "../../connectors/catalog.js";
+import { isToolInputSchema } from "../../connectors/connection-capabilities.js";
+import { connectorPrincipalForSession } from "../../connectors/principal.js";
+import { ExternalToolSearchError } from "./search-error.js";
 import { externalToolRef, parseExternalToolRef } from "./refs.js";
 //#region src/agent/external-tools/composio-provider.ts
-init_session_key();
-const CONNECT_ACTION = "$connect";
 const CONNECTION_ARGUMENT = "xopcConnectionId";
 function textResult(value) {
 	return {
@@ -19,19 +20,6 @@ function textResult(value) {
 		details: {}
 	};
 }
-function connectorPrincipalForSession(sessionKey) {
-	const parsed = parseSessionKey(sessionKey);
-	if (!parsed || parsed.source === "cli" || parsed.source === "webchat") return {
-		principalId: "local-owner",
-		agentId: parsed?.agentId,
-		isLocalOwner: true
-	};
-	return {
-		principalId: `channel:${parsed.source}:${parsed.accountId}:${parsed.peerKind}:${parsed.peerId}`,
-		agentId: parsed.agentId,
-		isLocalOwner: false
-	};
-}
 function installedConfigToolkits(config) {
 	return Object.values(config?.connectors?.instances ?? {}).flatMap((record) => {
 		if (!record || typeof record !== "object" || Array.isArray(record)) return [];
@@ -65,9 +53,9 @@ function syncLocalOwnerInstallations(config) {
 			id,
 			connectorId,
 			principalId: "local-owner",
-			enabled: true,
+			enabled: existing?.enabled ?? true,
 			allowedAgentIds: existing?.allowedAgentIds ?? [],
-			maxScope: getComposioToolkitScope(config, toolkit),
+			maxScope: existing?.maxScope ?? getComposioToolkitScope(config, toolkit),
 			confirmationPolicy: existing?.confirmationPolicy ?? "writes",
 			selectedConnectionIds: existing?.selectedConnectionIds ?? [],
 			createdAt: existing?.createdAt
@@ -102,7 +90,8 @@ function schemaSummary(value, fallback) {
 	return fallback;
 }
 function actionInputSchema(action) {
-	const schema = action.inputSchema && typeof action.inputSchema === "object" && !Array.isArray(action.inputSchema) ? action.inputSchema : { type: "object" };
+	if (!isToolInputSchema(action.inputSchema)) throw new Error(`Exact input contract is unavailable for ${action.actionId}`);
+	const schema = action.inputSchema;
 	const properties = schema.properties && typeof schema.properties === "object" && !Array.isArray(schema.properties) ? schema.properties : {};
 	return {
 		...schema,
@@ -127,31 +116,31 @@ var ComposioToolProvider = class {
 		const available = this.availableInstallations();
 		const toolkits = available.installations.map(toolkitFromInstallation);
 		if (toolkits.length === 0) return [];
-		const result = await (await this.adapter.createSession({
-			principalId: available.principalId,
-			toolkits,
-			authConfigs: getConfiguredComposioAuthConfigs(this.deps.getConfig(), toolkits)
-		})).search({
-			query,
-			toolkits
-		});
+		let phase = "create_session";
+		let result;
+		try {
+			const session = await this.adapter.createSession({
+				principalId: available.principalId,
+				toolkits,
+				authConfigs: getConfiguredComposioAuthConfigs(this.deps.getConfig(), toolkits)
+			});
+			phase = "search";
+			result = await session.search({
+				query,
+				toolkits
+			});
+		} catch (cause) {
+			throw new ExternalToolSearchError(phase, toolkits, cause);
+		}
 		const schemas = result && typeof result === "object" && !Array.isArray(result) ? result.toolSchemas : void 0;
-		const hits = available.installations.map((installation) => {
-			const toolkit = toolkitFromInstallation(installation);
-			return {
-				toolRef: externalToolRef(this.source, installation.id, CONNECT_ACTION),
-				source: this.source,
-				namespace: toolkit,
-				title: `Connect ${toolkit}`,
-				summary: `Authorize an account for the installed ${toolkit} app.`
-			};
-		});
+		const hits = [];
 		if (!schemas || typeof schemas !== "object" || Array.isArray(schemas)) return hits;
 		for (const [actionId, schema] of Object.entries(schemas)) {
 			const toolkit = toolkitForAction(actionId, toolkits);
 			if (!toolkit || !isComposioActionAllowedByCatalog(actionId)) continue;
 			const installation = available.installations.find((candidate) => toolkitFromInstallation(candidate) === toolkit);
 			if (!installation) continue;
+			if (!isToolInputSchema(schema && typeof schema === "object" ? schema.inputSchema : void 0)) continue;
 			upsertConnectorActionMetadata(contractFromSearch(installation.connectorId, toolkit, actionId, schema));
 			hits.push({
 				toolRef: externalToolRef(this.source, installation.id, actionId),
@@ -167,27 +156,8 @@ var ComposioToolProvider = class {
 		const resolved = this.resolve(toolRef);
 		if (!resolved) return void 0;
 		const toolkit = toolkitFromInstallation(resolved.installation);
-		if (resolved.actionId === CONNECT_ACTION) {
-			const summary = `Authorize an account for the installed ${toolkit} app.`;
-			return {
-				toolRef,
-				source: this.source,
-				namespace: toolkit,
-				title: `Connect ${toolkit}`,
-				summary,
-				description: `${summary} Never claim the connection succeeded until it is checked again.`,
-				inputSchema: {
-					type: "object",
-					properties: { alias: {
-						type: "string",
-						description: "Optional account label."
-					} },
-					additionalProperties: false
-				}
-			};
-		}
 		const action = listConnectorActionMetadata(resolved.installation.connectorId).find((candidate) => candidate.actionId === resolved.actionId);
-		if (!action?.inputSchema || !isComposioActionAllowedByCatalog(action.actionId)) return void 0;
+		if (!action || !isToolInputSchema(action.inputSchema) || !isComposioActionAllowedByCatalog(action.actionId)) return void 0;
 		const summary = `Run ${action.actionId} in ${toolkit}.`;
 		return {
 			toolRef,
@@ -210,31 +180,47 @@ var ComposioToolProvider = class {
 			executionArgs = hook.params ?? args;
 		}
 		const toolkit = toolkitFromInstallation(resolved.installation);
-		if (resolved.actionId === CONNECT_ACTION) {
-			const authorization = await this.adapter.authorize({
-				principalId: available.principalId,
-				toolkit,
-				authConfigId: installedConfigToolkits(this.deps.getConfig()).find((item) => item.connectorId === resolved.installation.connectorId)?.authConfigId,
-				installationId: resolved.installation.id,
-				alias: typeof executionArgs.alias === "string" ? executionArgs.alias : void 0
-			});
-			return textResult({
-				status: authorization.status,
-				toolkit,
-				authorizationUrl: authorization.connectUrl,
-				connectionId: authorization.connectionId,
-				instruction: "Ask the user to open the authorization URL. Check the connection again after they finish."
-			});
-		}
 		const action = listConnectorActionMetadata(resolved.installation.connectorId).find((candidate) => candidate.actionId === resolved.actionId);
-		if (!action?.inputSchema || !isComposioActionAllowedByCatalog(resolved.actionId)) return textResult("The exact action contract is unavailable. Search and describe the tool again.");
-		await this.adapter.syncConnections({ principalId: available.principalId }).catch(() => []);
+		if (!action || !isToolInputSchema(action.inputSchema) || !isComposioActionAllowedByCatalog(resolved.actionId)) return textResult("The exact action contract is unavailable. Search and describe the tool again.");
+		let fresh = await this.adapter.syncConnections({ principalId: available.principalId });
+		const binding = available.context ? connectionBinding(available.context.sessionKey, resolved.installation.connectorId) : void 0;
+		const expired = fresh.find((item) => item.connectorId === resolved.installation.connectorId && item.status === "expired" && item.id === binding);
+		if (expired) {
+			const refreshed = await this.adapter.refreshConnection(expired);
+			fresh = fresh.map((item) => item.id === refreshed.id ? refreshed : item);
+		}
 		const connections = listConnectorConnections({
 			principalId: available.principalId,
 			connectorId: resolved.installation.connectorId
-		}).filter((connection) => connection.status === "active");
-		const requestedConnection = typeof executionArgs[CONNECTION_ARGUMENT] === "string" ? executionArgs[CONNECTION_ARGUMENT] : void 0;
-		const connection = requestedConnection ? connections.find((candidate) => candidate.id === requestedConnection) : connections.find((candidate) => candidate.isDefault) ?? connections[0];
+		}).filter((connection) => connection.status === "active" && fresh.some((item) => item.id === connection.id) && (!resolved.installation.selectedConnectionIds.length || resolved.installation.selectedConnectionIds.includes(connection.id)));
+		const requestedConnection = typeof executionArgs[CONNECTION_ARGUMENT] === "string" ? executionArgs[CONNECTION_ARGUMENT] : available.context ? connectionBinding(available.context.sessionKey, resolved.installation.connectorId) : void 0;
+		const bindings = available.context ? connectionBindings(available.context.sessionKey).filter((need) => need.connectorId === resolved.installation.connectorId) : [];
+		if (bindings.length > 1 && !requestedConnection) return textResult({
+			status: "account_selection_required",
+			accounts: bindings,
+			instruction: "Choose the account for this operation using xopcConnectionId."
+		});
+		if (bindings.length && requestedConnection && !bindings.some((need) => need.connectionId === requestedConnection)) return textResult("This account was not selected for the current objective.");
+		const connection = requestedConnection ? connections.find((candidate) => candidate.id === requestedConnection) : connections.length === 1 ? connections[0] : void 0;
+		const requestConnection = () => {
+			if (!available.context) return textResult({ status: "connection_required" });
+			const result = requireSessionConnection({
+				sessionKey: available.context.sessionKey,
+				principalId: available.principalId,
+				agentId: available.agentId ?? "main",
+				summary: `Continue ${action.actionId} using ${toolkit}`,
+				needs: [{
+					key: `${resolved.installation.connectorId}:default`,
+					connectorId: resolved.installation.connectorId,
+					connectionId: requestedConnection,
+					label: getConnectorDefinition(resolved.installation.connectorId)?.displayName ?? toolkit,
+					capabilities: [action.actionId]
+				}]
+			});
+			publishConnectionWait(available.context.sessionKey);
+			return textResult(result);
+		};
+		if (!connection) return requestConnection();
 		const actionArgs = { ...executionArgs };
 		delete actionArgs[CONNECTION_ARGUMENT];
 		const argsHash = connectorArgumentsHash(actionArgs);
@@ -245,20 +231,29 @@ var ComposioToolProvider = class {
 			confirmed = Boolean(consumeConnectorApproval(approvalId, argsHash));
 			if (!confirmed) return textResult("The connector approval is not approved, has expired, or was already used.");
 		}
-		const result = await this.adapter.executeWithPolicy({
-			context: {
-				principalId: available.principalId,
-				toolkits: [toolkit],
-				authConfigs: getConfiguredComposioAuthConfigs(this.deps.getConfig(), [toolkit])
-			},
-			installation: resolved.installation,
-			connection,
-			action,
-			args: actionArgs,
-			agentId: available.agentId,
-			sessionKey: available.context?.sessionKey,
-			confirmed
-		});
+		let result;
+		try {
+			result = await this.adapter.executeWithPolicy({
+				context: {
+					principalId: available.principalId,
+					toolkits: [toolkit],
+					authConfigs: getConfiguredComposioAuthConfigs(this.deps.getConfig(), [toolkit])
+				},
+				installation: resolved.installation,
+				connection,
+				action,
+				args: actionArgs,
+				agentId: available.agentId,
+				sessionKey: available.context?.sessionKey,
+				confirmed
+			});
+		} catch (error) {
+			if (action.scope === "read") {
+				const checked = await this.adapter.syncConnections({ principalId: available.principalId }).catch(() => void 0);
+				if (checked && !checked.some((item) => item.id === connection.id && item.status === "active")) return requestConnection();
+			}
+			throw error;
+		}
 		if (result.decision === "confirmation_required") {
 			const approval = createConnectorApproval({
 				principalId: available.principalId,

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

@@ -1,8 +1,11 @@
 import type { AgentTool } from '@earendil-works/pi-agent-core';
+import type { ExternalToolTurnContext } from './types.js';
 import { type ExternalToolProvider } from './types.js';
 export declare const EXTERNAL_TOOL_NAMES: {
     readonly search: "xopc_tool_search";
     readonly describe: "xopc_tool_describe";
     readonly execute: "xopc_tool_execute";
+    readonly requireConnection: "xopc_require_connection";
+    readonly updateConnectionObjective: "xopc_update_connection_objective";
 };
-export declare function createExternalToolGatewayTools(providers: ExternalToolProvider[]): AgentTool[];
+export declare function createExternalToolGatewayTools(providers: ExternalToolProvider[], getContext?: () => ExternalToolTurnContext | null): AgentTool[];

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

@@ -1,3 +1,7 @@
+import { connectionBindings, getActiveConnectionWait, publishConnectionWait, requireSessionConnection, reviseCurrentConnectionObjective } from "../../storage/sqlite/connection-wait-repository.js";
+import { listConnectorConnections } from "../../storage/sqlite/connector-repository.js";
+import { connectorPrincipalForSession } from "../../connectors/principal.js";
+import { connectionCandidates, resolveConnectionCandidate } from "../../connectors/connection-candidates.js";
 import { ExternalToolService } from "./service.js";
 import { EXTERNAL_TOOL_SOURCES } from "./types.js";
 import { Type } from "@sinclair/typebox";
@@ -5,7 +9,9 @@ import { Type } from "@sinclair/typebox";
 const EXTERNAL_TOOL_NAMES = {
 	search: "xopc_tool_search",
 	describe: "xopc_tool_describe",
-	execute: "xopc_tool_execute"
+	execute: "xopc_tool_execute",
+	requireConnection: "xopc_require_connection",
+	updateConnectionObjective: "xopc_update_connection_objective"
 };
 const ToolSearchSchema = Type.Object({
 	query: Type.String({ description: "Describe the capability or task you need." }),
@@ -38,49 +44,155 @@ function textResult(value, details = {}) {
 		details
 	};
 }
-function createExternalToolGatewayTools(providers) {
+function createExternalToolGatewayTools(providers, getContext) {
 	const service = new ExternalToolService(providers);
+	const searchTool = {
+		name: EXTERNAL_TOOL_NAMES.search,
+		label: "🔎 External Tool Search",
+		description: "Search MCP, connected-app, extension, remote-memory, and current-endpoint tools. Use concise English capability keywords. Returns compact references only; call xopc_tool_describe before execution.",
+		parameters: ToolSearchSchema,
+		async execute(_toolCallId, params) {
+			return textResult({
+				...await service.search(params),
+				connectionCandidates: connectionCandidates(params.query),
+				selectedConnections: getContext?.()?.sessionKey ? connectionBindings(getContext().sessionKey) : [],
+				waitingObjective: getContext?.()?.sessionKey ? getActiveConnectionWait(getContext().sessionKey)?.summary : void 0
+			});
+		}
+	};
+	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.",
+		parameters: ToolDescribeSchema,
+		async execute(_toolCallId, params) {
+			const result = await service.describe(params.toolRefs);
+			return textResult({
+				...result,
+				...result.notFound.length ? { instruction: "These exact tool contracts are unavailable. Do not execute them, invent revisions, or reconnect the account. Use a different available tool or explain the capability failure." } : {}
+			});
+		}
+	};
+	const executeTool = {
+		name: EXTERNAL_TOOL_NAMES.execute,
+		label: "▶️ External Tool Execute",
+		description: "Execute one external tool using its exact reference, contract revision, and validated arguments.",
+		parameters: ToolExecuteSchema,
+		async execute(toolCallId, params, signal, onUpdate) {
+			const result = await service.execute({
+				...params,
+				context: {
+					toolCallId,
+					signal,
+					onUpdate
+				}
+			});
+			return {
+				...result,
+				details: {
+					...result.details ?? {},
+					delegatedToolRef: params.toolRef,
+					delegatedToolRevision: params.revision
+				}
+			};
+		}
+	};
+	const requireSchema = Type.Object({
+		requirements: Type.Array(Type.Object({
+			candidateRef: Type.String(),
+			accountId: Type.Optional(Type.String()),
+			accountSelector: Type.Optional(Type.String({ maxLength: 100 }))
+		}), {
+			minItems: 1,
+			maxItems: 5
+		}),
+		purpose: Type.String({
+			minLength: 1,
+			maxLength: 1e3
+		}),
+		checkpoint: Type.Object({
+			completedSteps: Type.Array(Type.String({ maxLength: 500 }), { maxItems: 20 }),
+			pendingSteps: Type.Array(Type.String({ maxLength: 500 }), {
+				minItems: 1,
+				maxItems: 20
+			}),
+			timeRange: Type.Optional(Type.Object({
+				from: Type.String(),
+				to: Type.String(),
+				timezone: Type.String(),
+				expression: Type.String()
+			}))
+		}, { description: "Preserve completed work, remaining work, and absolute dates resolved from the original request. Never include credentials." })
+	});
+	const requireTool = {
+		name: EXTERNAL_TOOL_NAMES.requireConnection,
+		label: "Connect app",
+		parameters: requireSchema,
+		description: "Request the connections returned as connectionCandidates by xopc_tool_search. Explain the need once before calling. This pauses the current objective and displays one action area above the input. Never return OAuth URLs or repeat a skipped request. If another objective is waiting, ask the user to continue or cancel it first.",
+		async execute(_id, params) {
+			const context = getContext?.();
+			if (!context) throw new Error("No active conversation.");
+			const range = params.checkpoint.timeRange;
+			if (range && (!Number.isFinite(Date.parse(range.from)) || !Number.isFinite(Date.parse(range.to)) || Date.parse(range.from) >= Date.parse(range.to))) throw new Error("Provide a valid absolute time range.");
+			if (range) new Intl.DateTimeFormat("en", { timeZone: range.timezone }).format();
+			const principal = connectorPrincipalForSession(context.sessionKey);
+			if (!principal.isLocalOwner) throw new Error("Connection recovery is available in the owner chat.");
+			const selected = connectionBindings(context.sessionKey);
+			if (params.requirements.every((item) => selected.some((need) => need.connectorId === item.candidateRef && need.connectionId && (!item.accountId || item.accountId === need.accountId) && (!item.accountSelector || item.accountSelector === need.accountSelector) && listConnectorConnections({
+				principalId: principal.principalId,
+				connectorId: need.connectorId
+			}).some((connection) => connection.id === need.connectionId && connection.status === "active")))) return textResult({
+				status: "already_connected",
+				selectedConnections: selected,
+				instruction: "These accounts were already checked for this objective. Missing tool contracts are a tool availability problem. Do not request authorization again or invent a revision. Explain the unavailable capability and stop retrying the same tools."
+			});
+			const result = requireSessionConnection({
+				sessionKey: context.sessionKey,
+				principalId: principal.principalId,
+				agentId: principal.agentId ?? "main",
+				summary: params.purpose,
+				checkpoint: params.checkpoint,
+				needs: params.requirements.map((item) => {
+					const need = resolveConnectionCandidate(item.candidateRef);
+					if (item.accountId && !listConnectorConnections({
+						principalId: principal.principalId,
+						connectorId: need.connectorId
+					}).some((connection) => connection.accountId === item.accountId)) throw new Error("Unknown account for this app.");
+					return {
+						...need,
+						accountId: item.accountId,
+						accountSelector: item.accountSelector,
+						key: `${need.connectorId}:${item.accountId ?? item.accountSelector ?? "default"}`
+					};
+				})
+			});
+			publishConnectionWait(context.sessionKey);
+			return textResult(result);
+		}
+	};
+	const reviseSchema = Type.Object({
+		action: Type.Union([Type.Literal("update"), Type.Literal("cancel")]),
+		objective: Type.Optional(Type.String({
+			minLength: 1,
+			maxLength: 4e3
+		}))
+	});
 	return [
+		searchTool,
+		describeTool,
+		executeTool,
+		requireTool,
 		{
-			name: EXTERNAL_TOOL_NAMES.search,
-			label: "🔎 External Tool Search",
-			description: "Search MCP, connected-app, extension, remote-memory, and current-endpoint tools. Use concise English capability keywords. Returns compact references only; call xopc_tool_describe before execution.",
-			parameters: ToolSearchSchema,
-			async execute(_toolCallId, params) {
-				return textResult(await service.search(params));
-			}
-		},
-		{
-			name: EXTERNAL_TOOL_NAMES.describe,
-			label: "📋 External Tool Contract",
-			description: "Load exact contracts for up to three external tools returned by xopc_tool_search.",
-			parameters: ToolDescribeSchema,
-			async execute(_toolCallId, params) {
-				return textResult(await service.describe(params.toolRefs));
-			}
-		},
-		{
-			name: EXTERNAL_TOOL_NAMES.execute,
-			label: "▶️ External Tool Execute",
-			description: "Execute one external tool using its exact reference, contract revision, and validated arguments.",
-			parameters: ToolExecuteSchema,
-			async execute(toolCallId, params, signal, onUpdate) {
-				const result = await service.execute({
-					...params,
-					context: {
-						toolCallId,
-						signal,
-						onUpdate
-					}
-				});
-				return {
-					...result,
-					details: {
-						...result.details ?? {},
-						delegatedToolRef: params.toolRef,
-						delegatedToolRevision: params.revision
-					}
-				};
+			name: EXTERNAL_TOOL_NAMES.updateConnectionObjective,
+			label: "Update waiting objective",
+			parameters: reviseSchema,
+			description: "Use when the user supplements or explicitly cancels the objective waiting for a connection. Update with the complete revised objective including the requested time range. For unrelated work leave the waiting objective unchanged. Cancellation does not disconnect the account.",
+			async execute(_id, params) {
+				const context = getContext?.();
+				if (!context) throw new Error("No active conversation.");
+				if (params.action === "update" && !params.objective) throw new Error("The revised objective is required.");
+				reviseCurrentConnectionObjective(context.sessionKey, params.action === "update" ? params.objective : void 0);
+				return textResult({ status: params.action === "update" ? "updated" : "cancelled" });
 			}
 		}
 	];

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

@@ -40,7 +40,7 @@ function createDefaultExternalToolGatewayTools(deps) {
 		runtime: deps.endpointTools,
 		getCurrentContext: deps.getCurrentContext
 	}));
-	return createExternalToolGatewayTools(providers);
+	return createExternalToolGatewayTools(providers, deps.getCurrentContext);
 }
 //#endregion
 export { EXTERNAL_TOOL_NAMES, ExternalToolService, createDefaultExternalToolGatewayTools };

package/dist/src/agent/external-tools/search-error.d.ts

@@ -0,0 +1,12 @@
+export declare class ExternalToolSearchError extends Error {
+    readonly phase: 'create_session' | 'search';
+    readonly toolkits: string[];
+    constructor(phase: 'create_session' | 'search', toolkits: string[], cause: unknown);
+}
+/** Expose diagnostic metadata without returning provider payloads or credentials to the model. */
+export declare function searchFailureDetails(error: unknown): {
+    phase: string;
+    toolkits?: string[];
+    code?: string | number;
+    status?: number;
+};

package/dist/src/agent/external-tools/search-error.js

@@ -0,0 +1,29 @@
+//#region src/agent/external-tools/search-error.ts
+var ExternalToolSearchError = class extends Error {
+	constructor(phase, toolkits, cause) {
+		super(`Composio tool discovery failed during ${phase}`, { cause });
+		this.phase = phase;
+		this.toolkits = toolkits;
+		this.name = "ExternalToolSearchError";
+	}
+};
+/** Expose diagnostic metadata without returning provider payloads or credentials to the model. */
+function searchFailureDetails(error) {
+	const details = error instanceof ExternalToolSearchError ? {
+		phase: error.phase,
+		toolkits: error.toolkits
+	} : { phase: "search" };
+	const visited = /* @__PURE__ */ new Set();
+	let current = error;
+	while (current && typeof current === "object" && !visited.has(current)) {
+		visited.add(current);
+		const row = current;
+		if (details.code === void 0 && (typeof row.code === "number" || typeof row.code === "string" && /^[a-zA-Z0-9_.-]{1,100}$/.test(row.code))) details.code = row.code;
+		const status = row.status ?? row.statusCode;
+		if (details.status === void 0 && typeof status === "number") details.status = status;
+		current = row.cause;
+	}
+	return details;
+}
+//#endregion
+export { ExternalToolSearchError, searchFailureDetails };

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

@@ -1,3 +1,4 @@
+import { searchFailureDetails } from './search-error.js';
 import type { ExternalToolExecutionContext, ExternalToolProvider, ExternalToolSearchHit, ExternalToolSource, VersionedExternalToolDescriptor } from './types.js';
 export declare class ExternalToolService {
     private readonly providerBySource;
@@ -10,6 +11,9 @@ export declare class ExternalToolService {
     }): Promise<{
         tools: ExternalToolSearchHit[];
         unavailableSources: ExternalToolSource[];
+        sourceErrors?: Array<ReturnType<typeof searchFailureDetails> & {
+            source: ExternalToolSource;
+        }>;
     }>;
     describe(toolRefs: string[]): Promise<{
         tools: VersionedExternalToolDescriptor[];

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

@@ -1,6 +1,11 @@
+import { createLogger } from "../../utils/logger/index.js";
+import { init_logger } from "../../utils/logger.js";
+import { searchFailureDetails } from "./search-error.js";
 import crypto from "node:crypto";
 import Ajv2020 from "ajv/dist/2020.js";
 //#region src/agent/external-tools/service.ts
+init_logger();
+const log = createLogger("ExternalToolService");
 const DEFAULT_SEARCH_LIMIT = 8;
 const MAX_SEARCH_LIMIT = 20;
 const MAX_DESCRIBE_COUNT = 3;
@@ -49,11 +54,25 @@ var ExternalToolService = class {
 			hits: await provider.search(params.query)
 		})));
 		const unavailableSources = [];
+		const sourceErrors = [];
 		const hits = [];
 		for (const [index, result] of settled.entries()) if (result.status === "fulfilled") hits.push(...result.value.hits);
 		else {
 			const provider = selected[index];
-			if (provider) unavailableSources.push(provider.source);
+			if (provider) {
+				unavailableSources.push(provider.source);
+				const details = {
+					source: provider.source,
+					...searchFailureDetails(result.reason)
+				};
+				sourceErrors.push(details);
+				const errorMessage = result.reason instanceof Error ? result.reason.message : String(result.reason);
+				log.warn({
+					...details,
+					err: result.reason instanceof Error ? result.reason : void 0,
+					errorMessage
+				}, `External tool search failed for ${provider.source}: ${errorMessage}`);
+			}
 		}
 		const limit = Math.min(MAX_SEARCH_LIMIT, Math.max(1, params.limit ?? DEFAULT_SEARCH_LIMIT));
 		return {
@@ -67,7 +86,8 @@ var ExternalToolService = class {
 				title: hit.title,
 				summary: hit.summary.slice(0, 300)
 			})),
-			unavailableSources
+			unavailableSources,
+			...sourceErrors.length ? { sourceErrors } : {}
 		};
 	}
 	async describe(toolRefs) {

package/dist/src/agent/ipc/inbox.d.ts

@@ -1,41 +1,18 @@
 import type { Config } from '../../config/schema.js';
 import type { AgentIPCMessage } from './types.js';
+/** SQLite queue with acknowledgement after processing and renewable claims. */
 export declare class AgentInbox {
-    private readonly pendingDir;
-    private readonly processedDir;
-    private watcher?;
-    constructor(agentDir: string);
-    /**
-     * Static factory using agent ID (paths from config).
-     */
-    static forAgent(config: Config, agentId: string): AgentInbox;
-    /**
-     * Enqueue a message
-     */
+    private readonly queue;
+    private timer?;
+    private processing;
+    private stopped;
+    constructor(agentId: string);
+    static forAgent(_config: Config, agentId: string): AgentInbox;
     enqueue(message: AgentIPCMessage): Promise<void>;
-    /**
-     * Dequeue the oldest pending message
-     */
-    dequeue(): Promise<AgentIPCMessage | null>;
-    /**
-     * Peek at pending messages without removing them
-     */
     peek(limit?: number): Promise<AgentIPCMessage[]>;
-    /**
-     * Count pending messages
-     */
     count(): Promise<number>;
-    /**
-     * Watch for new messages
-     */
+    clearProcessed(olderThanMs?: number): Promise<number>;
     watch(handler: (msg: AgentIPCMessage) => Promise<void>): Promise<() => void>;
-    /**
-     * Stop watching
-     */
     stopWatching(): void;
-    /**
-     * Clear all processed messages
-     */
-    clearProcessed(olderThanMs?: number): Promise<number>;
     private processPending;
 }