@xopcai/xopc 0.0.248 → 0.0.249

package/dist/src/agent/context/execution-scope.js

@@ -79,7 +79,7 @@ function formatCurrentWorkForPrompt(scope) {
 }
 function buildExecutionScopeContextForPrompt(sessionKey) {
 	const scope = resolveExecutionScope(sessionKey);
-	return [buildActiveProjectContextForPrompt(sessionKey, { memoryQuery: scope.objective?.objective }), formatCurrentWorkForPrompt(scope)].filter((section) => Boolean(section?.trim())).join("\n\n") || void 0;
+	return [buildActiveProjectContextForPrompt(sessionKey, { knowledgeQuery: scope.objective?.objective }), formatCurrentWorkForPrompt(scope)].filter((section) => Boolean(section?.trim())).join("\n\n") || void 0;
 }
 //#endregion
 export { buildExecutionScopeContextForPrompt, formatCurrentWorkForPrompt, resolveExecutionScope };

package/dist/src/agent/context/prepend.d.ts

@@ -0,0 +1,2 @@
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+export declare function prependAgentContext(message: AgentMessage, block: string): AgentMessage;

package/dist/src/agent/context/prepend.js

@@ -0,0 +1,28 @@
+import { readAgentMessageContent } from "../memory/agent-message-access.js";
+//#region src/agent/context/prepend.ts
+function prependAgentContext(message, block) {
+	if (!block) return message;
+	const prefix = `${block}\n\n`;
+	const content = readAgentMessageContent(message);
+	if (typeof content === "string") return {
+		...message,
+		content: prefix + content
+	};
+	if (!Array.isArray(content)) return message;
+	const copy = [...content];
+	const first = copy[0];
+	if (first?.type === "text" && typeof first.text === "string") copy[0] = {
+		type: "text",
+		text: prefix + first.text
+	};
+	else copy.unshift({
+		type: "text",
+		text: prefix
+	});
+	return {
+		...message,
+		content: copy
+	};
+}
+//#endregion
+export { prependAgentContext };

package/dist/src/agent/context/project-context.d.ts

@@ -5,7 +5,7 @@ export interface ProjectTaskContext {
     priority: string;
 }
 export declare function buildActiveProjectContextForPrompt(sessionKey: string, options?: {
-    memoryQuery?: string;
+    knowledgeQuery?: string;
 }): string | undefined;
 export declare function formatActiveProjectContextForPrompt(input: {
     project: Project;
@@ -17,10 +17,10 @@ export declare function formatActiveProjectContextForPrompt(input: {
         updatedAt: string;
         agentId: string;
     }>;
-    memoryRecords?: Array<{
+    knowledgeItems?: Array<{
         kind: string;
         content: string;
-        updatedAt: string;
+        updatedAt: number;
     }>;
     localApp?: {
         extensionId: string;

package/dist/src/agent/context/project-context.js

@@ -1,18 +1,18 @@
-import { listMemoryRecords, searchMemoryRecords } from "../../storage/sqlite/memory-records-repository.js";
-import "../../storage/sqlite/index.js";
 import { sanitizeForPromptLiteral } from "../prompt/sanitize-for-prompt.js";
 import { TaskRepository } from "../../tasks/task-repository.js";
 import { TaskReadModelProjector } from "../../tasks/task-read-model-projector.js";
 import { LocalAppStore } from "../../local-apps/store.js";
 import { ProjectStore } from "../../projects/project-store.js";
 import { getProjectForSession, getProjectWorkspacePathForSession } from "../../projects/workspace.js";
+import { listKnowledgeItems, searchKnowledgeItems } from "../../knowledge-memory/repository.js";
+import "../../knowledge-memory/index.js";
 //#region src/agent/context/project-context.ts
 const MAX_TEXT = 1200;
 const MAX_TASKS = 5;
 const MAX_SESSIONS = 5;
-const MAX_RECENT_MEMORY = 5;
-const MAX_RELEVANT_MEMORY = 5;
-const MAX_MEMORY = 8;
+const MAX_RECENT_KNOWLEDGE = 5;
+const MAX_RELEVANT_KNOWLEDGE = 5;
+const MAX_KNOWLEDGE = 8;
 function truncateText(value, max = MAX_TEXT) {
 	const trimmed = value?.trim();
 	if (!trimmed) return void 0;
@@ -26,11 +26,11 @@ function formatTask(task) {
 		`priority=${task.priority}`
 	].join(" | ");
 }
-function selectProjectMemoryRecords(input) {
+function selectProjectKnowledge(input) {
 	const selected = /* @__PURE__ */ new Map();
 	for (const record of [...input.relevant, ...input.recent]) {
 		if (!selected.has(record.id)) selected.set(record.id, record);
-		if (selected.size >= MAX_MEMORY) break;
+		if (selected.size >= MAX_KNOWLEDGE) break;
 	}
 	return [...selected.values()];
 }
@@ -49,18 +49,21 @@ function buildActiveProjectContextForPrompt(sessionKey, options = {}) {
 			state: `${task.phase}/${new TaskReadModelProjector().project(task).operationalState}`
 		})),
 		recentSessions: new ProjectStore().getRecentSessions(project.id, MAX_SESSIONS),
-		memoryRecords: selectProjectMemoryRecords({
-			relevant: options.memoryQuery?.trim() ? searchMemoryRecords({
-				query: options.memoryQuery,
-				projectId: project.id,
+		knowledgeItems: selectProjectKnowledge({
+			relevant: options.knowledgeQuery?.trim() ? searchKnowledgeItems({
+				query: options.knowledgeQuery,
+				context: {
+					agentId: project.defaultAgentId ?? "main",
+					workspaceId: project.workspaceRoot ?? "",
+					projectId: project.id,
+					sessionId: sessionKey
+				},
+				limit: MAX_RELEVANT_KNOWLEDGE
+			}) : [],
+			recent: listKnowledgeItems({
 				statuses: ["active"],
-				maxResults: MAX_RELEVANT_MEMORY
-			}).map((result) => result.record) : [],
-			recent: listMemoryRecords({
-				projectId: project.id,
-				status: "active",
-				limit: MAX_RECENT_MEMORY
-			})
+				limit: 500
+			}).filter((item) => item.scope.type === "project" && item.scope.id === project.id).slice(0, MAX_RECENT_KNOWLEDGE)
 		}),
 		localApp: localApp ? {
 			extensionId: localApp.extensionId,
@@ -107,12 +110,12 @@ function formatActiveProjectContextForPrompt(input) {
 		const label = sanitizeForPromptLiteral(session.name?.trim() || session.key);
 		lines.push(`- ${label} | agent=${sanitizeForPromptLiteral(session.agentId)} | updated=${sanitizeForPromptLiteral(session.updatedAt)}`);
 	}
-	lines.push("", "## Project Memory");
-	const memoryRecords = input.memoryRecords ?? [];
-	if (memoryRecords.length === 0) lines.push("- None recorded.");
-	else for (const record of memoryRecords) {
+	lines.push("", "## Project Knowledge");
+	const knowledgeItems = input.knowledgeItems ?? [];
+	if (knowledgeItems.length === 0) lines.push("- None recorded.");
+	else for (const record of knowledgeItems) {
 		const content = sanitizeForPromptLiteral(truncateText(record.content, 240) ?? "");
-		lines.push(`- ${sanitizeForPromptLiteral(record.kind)} | updated=${sanitizeForPromptLiteral(record.updatedAt)} | ${content}`);
+		lines.push(`- ${sanitizeForPromptLiteral(record.kind)} | updated=${new Date(record.updatedAt).toISOString()} | ${content}`);
 	}
 	return lines.join("\n");
 }

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

@@ -1,3 +1,4 @@
+import { getEmbeddedExecutionSession, runWithEmbeddedExecutionSession } from "./execution-context.js";
 import { abortEmbeddedRun, getEmbeddedRunBySessionKey, queueEmbeddedSteer } from "./runs.js";
 import { DEFAULT_MAX_LIVE_TOOL_RESULT_CHARS, resolveLiveToolResultMaxChars, truncateToolResultMessage } from "./tool-result-truncation.js";
 import { getRawSessionAppendMessage, guardSessionManager, installSessionToolResultGuard } from "./session-tool-result-guard.js";
@@ -6,7 +7,6 @@ import { repairAssistantUsageInSessionManager } from "./session-manager-init.js"
 import { openSqliteHydratingSessionManager } from "./sqlite-hydrating-session-manager.js";
 import { InMemoryTranscriptRuntime, createSqliteTranscriptRuntime } from "./transcript-runtime.js";
 import { runXopcEmbeddedTurn } from "./run-turn.js";
-import { getEmbeddedExecutionSession, runWithEmbeddedExecutionSession } from "./execution-context.js";
 import { runEmbeddedTurnForSession } from "./run-for-session.js";
 import { CURRENT_SESSION_VERSION, PiTranscriptManager } from "./pi-transcript.js";
 export { CURRENT_SESSION_VERSION, DEFAULT_MAX_LIVE_TOOL_RESULT_CHARS, InMemoryTranscriptRuntime, PiTranscriptManager, abortEmbeddedRun, acquireEmbeddedSessionRunner, buildEmbeddedRunnerFingerprint, createSqliteTranscriptRuntime, evictAllEmbeddedSessionRunners, evictEmbeddedSessionRunner, getEmbeddedExecutionSession, getEmbeddedRunBySessionKey, getEmbeddedSessionRunnerIdleTtlMs, getEmbeddedSessionRunnerStats, getRawSessionAppendMessage, guardSessionManager, installSessionToolResultGuard, isEmbeddedSessionRunnerEnabled, openSqliteHydratingSessionManager, queueEmbeddedSteer, repairAssistantUsageInSessionManager, resetEmbeddedSessionRunnerForTest, resolveLiveToolResultMaxChars, runEmbeddedTurnForSession, runWithEmbeddedExecutionSession, runXopcEmbeddedTurn, truncateToolResultMessage };

package/dist/src/agent/embedded/run-for-session.js

@@ -27,6 +27,7 @@ async function runEmbeddedTurnForSession(params) {
 		parentSignal: params.abortSignal
 	});
 	const finish = async (result) => {
+		if (result.stopReason === "connection_required") return result;
 		try {
 			const rows = await sessionStore.loadTranscriptRows(sessionKey);
 			const hasTurn = rows.some((source) => {

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

@@ -1,5 +1,6 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
+import { getConnectionResumeInput, isConnectionSuspended } from "../../storage/sqlite/connection-wait-repository.js";
 import { EmbeddedRunConflictError, abortEmbeddedRun, acquireEmbeddedRunLease, queueEmbeddedSteer } from "./runs.js";
 import { lastAssistantPlainText, subscribeEmbeddedSessionEvents } from "./subscribe-session.js";
 import { isContextOverflowError } from "../orchestration/context-overflow.js";
@@ -233,8 +234,14 @@ async function runXopcEmbeddedTurn(params) {
 			...await verification.summary()
 		});
 		let policyStopped = false;
+		let connectionStopped = false;
 		params.turnPolicy?.reset();
 		session.agent.beforeToolCall = async (context, signal) => {
+			if (connectionStopped) return {
+				block: true,
+				reason: "Waiting for the user to connect an app.",
+				terminate: true
+			};
 			const decision = await params.turnPolicy?.beforeToolCall(context, signal);
 			if (decision?.block) {
 				policyStopped ||= decision.terminate === true;
@@ -251,6 +258,7 @@ async function runXopcEmbeddedTurn(params) {
 			return decision;
 		};
 		session.agent.afterToolCall = async (context) => {
+			connectionStopped ||= isConnectionSuspended(sessionKey, runId);
 			const scoped = context.toolCall.name === "read_file" ? await instructions.forTool(context.toolCall.name, context.args) : "";
 			const checked = await verification.afterTool(context);
 			if (scoped) checked.result.content.unshift({
@@ -265,7 +273,7 @@ async function runXopcEmbeddedTurn(params) {
 		};
 		session.agent.shouldStopAfterTurn = (context) => {
 			policyStopped ||= params.turnPolicy?.shouldStopAfterTurn(context) ?? false;
-			return policyStopped;
+			return policyStopped || connectionStopped;
 		};
 		unsubscribe = subscribeEmbeddedSessionEvents(session, (event) => {
 			if (event.type === "message_end" && event.message.role === "assistant") recordPromptCacheTouch(sessionKey, resolvedModel, event.message.usage);
@@ -281,13 +289,20 @@ async function runXopcEmbeddedTurn(params) {
 		runAbortSignal.addEventListener("abort", abortListener, { once: true });
 		try {
 			await runAgentTurnWithTimeout(session.agent, async () => {
-				if (params.resumeLastUserMessage) await session.agent.continue();
+				const connectionResume = getConnectionResumeInput(sessionKey, runId);
+				if (connectionResume) await session.sendCustomMessage({
+					customType: "connection_resume",
+					content: connectionResume.content,
+					display: false
+				}, { triggerTurn: true });
+				else if (params.resumeLastUserMessage) await session.agent.continue();
 				else {
 					const text = userMessageToPromptText(userMessage);
 					const images = params.images ?? [];
 					await session.prompt(text, images.length > 0 ? { images } : void 0);
 				}
 				await session.agent.waitForIdle();
+				if (connectionStopped) return;
 				await maybeRetryTurnAfterTransientLlmFailure(session.agent, {
 					sessionKey,
 					log,
@@ -311,6 +326,10 @@ async function runXopcEmbeddedTurn(params) {
 					await session.agent.waitForIdle();
 				}
 			}, timeoutMs);
+			if (connectionStopped) runner.piSm.appendCustomEntry("connection_required", {
+				runId,
+				sessionKey
+			});
 			runner.piSm.appendCustomEntry("coding_verification", {
 				runId,
 				workspace: workspaceDir,
@@ -337,6 +356,7 @@ async function runXopcEmbeddedTurn(params) {
 			});
 			return {
 				ok: true,
+				...connectionStopped ? { stopReason: "connection_required" } : {},
 				lastAssistantText: lastAssistantPlainText(session)
 			};
 		} finally {

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

@@ -48,31 +48,6 @@ export type EmbeddedStreamEvent = {
     runId?: string;
     stage: string;
     message: string;
-} | {
-    type: 'memory_consent_required';
-    runId?: string;
-    requests: Array<{
-        id: string;
-        recordId: string;
-        statement: string;
-        purpose: string;
-    }>;
-} | {
-    type: 'memory_captured';
-    runId?: string;
-    records: Array<{
-        id: string;
-        content: string;
-        kind: string;
-    }>;
-} | {
-    type: 'memory_candidate';
-    runId?: string;
-    records: Array<{
-        id: string;
-        content: string;
-        kind: string;
-    }>;
 } | {
     type: 'error';
     runId?: string;
@@ -114,6 +89,7 @@ export type RunXopcEmbeddedTurnParams = {
 };
 export type RunXopcEmbeddedTurnResult = {
     ok: boolean;
+    stopReason?: 'connection_required';
     /** False for harness failures that must not trigger another model attempt. */
     retryable?: boolean;
     errorMessage?: string;

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[];