@xopcai/xopc 0.0.308 → 0.0.311

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

@@ -2,6 +2,7 @@ import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { getClarification, getClarificationResumeInput, isClarificationSuspended } from "../../storage/sqlite/clarification-wait-repository.js";
 import { getConnectionResumeInput, init_connection_wait_repository, isConnectionSuspended } from "../../storage/sqlite/connection-wait-repository.js";
+import { runWithEmbeddedExecutionSession } from "./execution-context.js";
 import { isComputerControlActive, isComputerLeaseTool, stopComputerControl } from "../../computer/control-guard.js";
 import { EmbeddedRunConflictError, abortEmbeddedRun, acquireEmbeddedRunLease, queueEmbeddedSteer } from "./runs.js";
 import { lastAssistantPlainText, subscribeEmbeddedSessionEvents } from "./subscribe-session.js";
@@ -22,6 +23,7 @@ import { isPromptCacheExpired, recordPromptCacheTouch } from "../../providers/pr
 import { markTurnToolResult } from "../memory/turn-provenance.js";
 import { RepositoryInstructions } from "../coding/repository-instructions.js";
 import { RunVerification } from "../coding/run-verification.js";
+import { withDelegationScope } from "../orchestration/delegation-scope.js";
 //#region src/agent/embedded/run-turn.ts
 init_connection_wait_repository();
 init_logger();
@@ -318,9 +320,16 @@ async function runXopcEmbeddedTurn(params) {
 		session.agent.afterToolCall = async (context) => {
 			connectionStopped ||= isConnectionSuspended(conversationId, runId);
 			clarificationStopped ||= isClarificationSuspended(conversationId, runId);
-			const scoped = context.toolCall.name === "read_file" ? await instructions.forTool(context.toolCall.name, context.args) : "";
+			const scoped = context.toolCall.name === "read_file" ? await instructions.forTool(context.toolCall.name, context.args) : context.toolCall.name === "data_batch" ? await instructions.forDataResult(context.result.content) : "";
 			const checked = await verification.afterTool(context);
-			if (scoped) checked.result.content.unshift({
+			if (scoped && context.toolCall.name === "data_batch") checked.result = {
+				content: [{
+					type: "text",
+					text: `${scoped}\n\nNew directory instructions were discovered. Apply them before retrying the affected data queries; this result is not evidence of a complete search.`
+				}],
+				details: { status: "retry_required" }
+			};
+			else if (scoped) checked.result.content.unshift({
 				type: "text",
 				text: scoped
 			});
@@ -347,7 +356,10 @@ async function runXopcEmbeddedTurn(params) {
 		};
 		runAbortSignal.addEventListener("abort", abortListener, { once: true });
 		try {
-			await runAgentTurnWithTimeout(session.agent, async () => {
+			await runAgentTurnWithTimeout(session.agent, () => withDelegationScope({
+				tools,
+				authorizeToolCall: params.turnPolicy ? (context, signal) => runWithEmbeddedExecutionSession(conversationId, () => params.turnPolicy.beforeToolCall(context, signal), runId) : void 0
+			}, async () => {
 				const connectionResume = getConnectionResumeInput(conversationId, runId);
 				const clarificationResume = getClarificationResumeInput(conversationId, runId);
 				if (connectionResume) await session.sendCustomMessage({
@@ -392,7 +404,7 @@ async function runXopcEmbeddedTurn(params) {
 					}, { triggerTurn: true });
 					await session.agent.waitForIdle();
 				}
-			}, timeoutMs);
+			}), timeoutMs);
 			if (connectionStopped) runner.piSm.appendCustomEntry("connection_required", {
 				runId,
 				conversationId

package/dist/src/agent/embedded/session-runner.d.ts

@@ -9,6 +9,7 @@ export type EmbeddedRunnerFingerprintInput = {
     workspaceDir: string;
     modelRef: string;
     toolNames: readonly string[];
+    toolContracts: readonly string[];
     systemPrompt: string;
     thinkingLevel: string;
     credentialRevision: string;

package/dist/src/agent/embedded/session-runner.js

@@ -23,6 +23,7 @@ function buildEmbeddedRunnerFingerprint(input) {
 		input.workspaceDir,
 		input.modelRef,
 		tools,
+		[...input.toolContracts].sort().join("\0"),
 		input.systemPrompt,
 		input.thinkingLevel,
 		input.credentialRevision
@@ -92,6 +93,7 @@ var EmbeddedSessionRunnerPool = class {
 			workspaceDir: params.workspaceDir,
 			modelRef: params.modelRef,
 			toolNames: params.tools.map((t) => t.name),
+			toolContracts: params.tools.map((tool) => JSON.stringify([tool.name, tool.parameters])),
 			systemPrompt: params.systemPrompt,
 			thinkingLevel: params.thinkingLevel ?? "medium",
 			credentialRevision: providerCredentialRevision(params.model.provider)
@@ -196,6 +198,7 @@ var EmbeddedSessionRunnerPool = class {
 				workspaceDir,
 				modelRef: params.modelRef,
 				toolNames,
+				toolContracts: tools.map((tool) => JSON.stringify([tool.name, tool.parameters])),
 				systemPrompt,
 				thinkingLevel: thinkingLevel ?? "medium",
 				credentialRevision: providerCredentialRevision(model.provider)

package/dist/src/agent/embedded/tool-result-truncation.js

@@ -1,4 +1,5 @@
 import { init_string_coerce, normalizeLowercaseStringOrEmpty } from "../../utils/string-coerce.js";
+import { isDataBatchResult, renderDataBatch } from "../data-acquisition/render.js";
 import { formatContextLimitTruncationNotice } from "./tool-result-context-guard.js";
 //#region src/agent/embedded/tool-result-truncation.ts
 init_string_coerce();
@@ -101,6 +102,16 @@ function truncateToolResultMessage(msg, maxChars, options = {}) {
 	if (!Array.isArray(content)) return msg;
 	const totalTextChars = getToolResultTextLength(msg);
 	if (totalTextChars <= maxChars) return msg;
+	if (msg.toolName === "data_batch" && content.length === 1 && content[0]?.type === "text") try {
+		const batch = JSON.parse(content[0].text);
+		if (isDataBatchResult(batch)) return {
+			...msg,
+			content: [{
+				type: "text",
+				text: renderDataBatch(batch, maxChars).text
+			}]
+		};
+	} catch {}
 	const newContent = content.map((block) => {
 		if (!block || typeof block !== "object" || block.type !== "text") return block;
 		const textBlock = block;

package/dist/src/agent/embedded/xopc-tools-bridge.js

@@ -1,3 +1,4 @@
+import { withDataToolPermissions } from "../tools/dataBatch.js";
 //#region src/agent/embedded/xopc-tools-bridge.ts
 const APPLY_PATCH_BEGIN_MARKER = "*** Begin Patch";
 const APPLY_PATCH_END_MARKER = "*** End Patch";
@@ -106,7 +107,7 @@ function xopcToolsToDefinitions(tools) {
 					const envelopeError = validateApplyPatchEnvelope(params);
 					if (envelopeError) return invalidApplyPatchEnvelopeResult(envelopeError);
 				}
-				return tool.execute(toolCallId, params, signal, onUpdate);
+				return withDataToolPermissions(new Set(tools.map((item) => item.name)), () => tool.execute(toolCallId, params, signal, onUpdate));
 			}
 		};
 	});

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

@@ -0,0 +1,47 @@
+import type { Config } from '../../config/schema.js';
+import type { ExternalToolProvider, ExternalToolExecutionContext, ExternalToolTurnContext } from './types.js';
+export declare class CliToolProvider implements ExternalToolProvider {
+    private readonly deps;
+    readonly source: "cli";
+    constructor(deps: {
+        getConfig: () => Config | undefined;
+        getCurrentContext: () => ExternalToolTurnContext | null;
+        agentId?: string;
+    });
+    private available;
+    search(query: string): Promise<{
+        toolRef: string;
+        source: "cli";
+        namespace: string;
+        title: string;
+        summary: string;
+    }[]>;
+    describe(toolRef: string): Promise<{
+        toolRef: string;
+        source: "cli";
+        namespace: string;
+        title: string;
+        summary: string;
+        description: string;
+        batchRead: boolean;
+        inputSchema: {
+            properties: {
+                xopcAccountId: {
+                    type: string;
+                    description: string;
+                };
+                xopcExportResult: {
+                    type: string;
+                    description: string;
+                };
+            };
+        };
+    }>;
+    execute(toolRef: string, args: Record<string, unknown>, approvalId: string | undefined, context: ExternalToolExecutionContext): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: {};
+    }>;
+}

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

@@ -0,0 +1,317 @@
+import { isXopcDatabaseOpen } from "../../storage/sqlite/connection.js";
+import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "../../storage/sqlite/transaction.js";
+import { getSessionInputState, init_session_input_repository } from "../../storage/sqlite/session-input-repository.js";
+import { getConnectorAccount, init_connector_account_repository } from "../../storage/sqlite/connector-account-repository.js";
+import { appendConnectorExecutionAudit, consumeConnectorApproval, createConnectorApproval, getConnectorApproval, getConnectorConnection, getConnectorInstallation, init_connector_repository } from "../../storage/sqlite/connector-repository.js";
+import { connectorObjectiveScope, init_connection_wait_repository, publishConnectionWait, requireSessionConnection } from "../../storage/sqlite/connection-wait-repository.js";
+import "../../storage/sqlite/index.js";
+import { connectorArgumentsHash, connectorArgumentsPreview } from "../../connectors/approval.js";
+import { selectConnectorAccount } from "../../connectors/account-selection.js";
+import { cliContextPath } from "../../connectors/cli/process.js";
+import { validateActionInput } from "../../connectors/cli/protocol.js";
+import { getCliAdapter } from "../../connectors/cli/adapterRegistry.js";
+import { evaluateConnectorExecutionPolicy } from "../../connectors/policy.js";
+import { listConnectorInstances } from "../../connectors/instances.js";
+import { cliOwnerId, recoverCliExecutions } from "../../connectors/cli/store.js";
+import { describeCliAction, executeCliAction } from "../../connectors/cli/runtime.js";
+import { connectorPrincipalForSession } from "../../connectors/principal.js";
+import { externalToolRef, parseExternalToolRef } from "./refs.js";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { writeFile } from "node:fs/promises";
+//#region src/agent/external-tools/cliProvider.ts
+init_connector_account_repository();
+init_connector_repository();
+init_connection_wait_repository();
+init_session_input_repository();
+init_transaction();
+const result = (value) => ({
+	content: [{
+		type: "text",
+		text: JSON.stringify(value)
+	}],
+	details: {}
+});
+var CliToolProvider = class {
+	source = "cli";
+	constructor(deps) {
+		this.deps = deps;
+	}
+	available() {
+		const config = this.deps.getConfig();
+		if (!config || !isXopcDatabaseOpen()) return [];
+		recoverCliExecutions();
+		const principal = connectorPrincipalForSession(this.deps.getCurrentContext()?.conversationId);
+		return listConnectorInstances(config).flatMap((instance) => {
+			if (instance.materialized.type !== "cli" || !instance.enabled) return [];
+			const policy = getConnectorInstallation(`${instance.connectorId}-${principal.principalId}`);
+			const agentId = this.deps.agentId ?? principal.agentId;
+			if (!policy?.enabled || policy.allowedAgentIds.length && (!agentId || !policy.allowedAgentIds.includes(agentId))) return [];
+			return [{
+				config,
+				instance,
+				policy,
+				principal,
+				agentId,
+				adapter: getCliAdapter(instance.materialized.adapterId)
+			}];
+		});
+	}
+	async search(query) {
+		const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+		return this.available().flatMap((item) => {
+			const accounts = selectConnectorAccount({
+				installation: item.policy,
+				agentId: item.agentId,
+				accept: (c) => c.provider === "cli" && c.metadata.runtimeInstanceId === item.instance.instanceId
+			}).candidates;
+			if (!accounts.length) return [];
+			return Object.entries(item.adapter.curatedActions).filter(([id, scope]) => {
+				const text = `${item.instance.displayName} ${item.instance.connectorId} ${item.adapter.id} ${id}`.toLowerCase();
+				return (!words.length || words.some((word) => text.includes(word))) && evaluateConnectorExecutionPolicy({
+					installation: item.policy,
+					action: {
+						scope,
+						curated: true
+					},
+					agentId: item.agentId,
+					accountId: accounts[0].accountId,
+					confirmed: true
+				}).decision === "allowed";
+			}).map(([id]) => ({
+				toolRef: externalToolRef("cli", item.instance.instanceId, id),
+				source: this.source,
+				namespace: item.instance.connectorId,
+				title: id,
+				summary: `${item.instance.displayName}: ${id}`
+			}));
+		});
+	}
+	async describe(toolRef) {
+		const parsed = parseExternalToolRef(toolRef, this.source);
+		const item = this.available().find((value) => value.instance.instanceId === parsed?.namespace);
+		if (!item || !parsed) return void 0;
+		const selected = selectConnectorAccount({
+			installation: item.policy,
+			agentId: item.agentId,
+			accept: (c) => c.provider === "cli" && c.metadata.runtimeInstanceId === item.instance.instanceId
+		});
+		const connection = selected.connection ?? selected.candidates[0];
+		if (!connection) return void 0;
+		const action = await describeCliAction(item.config, item.instance.instanceId, connection, parsed.toolName);
+		if (evaluateConnectorExecutionPolicy({
+			installation: item.policy,
+			action: {
+				scope: action.scope,
+				curated: true
+			},
+			agentId: item.agentId,
+			accountId: connection.accountId,
+			confirmed: true
+		}).decision !== "allowed") return void 0;
+		return {
+			toolRef,
+			source: this.source,
+			namespace: item.instance.connectorId,
+			title: action.id,
+			summary: action.description,
+			description: action.description,
+			batchRead: action.scope === "read",
+			inputSchema: {
+				...action.inputSchema,
+				properties: {
+					...action.inputSchema.properties,
+					xopcAccountId: {
+						type: "string",
+						description: "Stable account ID; required when multiple accounts are available."
+					},
+					xopcExportResult: {
+						type: "boolean",
+						description: "Save the successful result as a JSON artifact in this account context."
+					}
+				}
+			}
+		};
+	}
+	async execute(toolRef, args, approvalId, context) {
+		const parsed = parseExternalToolRef(toolRef, this.source);
+		const item = this.available().find((value) => value.instance.instanceId === parsed?.namespace);
+		if (!item || !parsed) throw new Error("CLI connector is unavailable.");
+		const conversationId = this.deps.getCurrentContext()?.conversationId;
+		const selected = selectConnectorAccount({
+			installation: item.policy,
+			agentId: item.agentId,
+			conversationId,
+			requestedAccountId: typeof args.xopcAccountId === "string" ? args.xopcAccountId : void 0,
+			accept: (c) => c.provider === "cli" && c.metadata.runtimeInstanceId === item.instance.instanceId
+		});
+		const connection = selected.connection;
+		if (!connection) return result({
+			status: "account_selection_required",
+			accounts: selected.candidates.map((c) => ({
+				id: c.accountId,
+				identity: c.identity
+			})),
+			instruction: "Select a connected account using xopcAccountId. Never substitute another account."
+		});
+		const action = await describeCliAction(item.config, item.instance.instanceId, connection, parsed.toolName);
+		if (args.xopcExportResult !== void 0 && typeof args.xopcExportResult !== "boolean") throw new Error("Invalid export option.");
+		const exportResult = args.xopcExportResult === true;
+		const input = { ...args };
+		delete input.xopcAccountId;
+		delete input.xopcExportResult;
+		validateActionInput(action, input);
+		const scopes = Array.isArray(connection.metadata.scopes) ? connection.metadata.scopes : [];
+		if (action.requiredScopes.some((scope) => !scopes.includes(scope))) throw new Error("CLI account is missing required scopes. Reauthorize this account.");
+		const argumentsHash = () => connectorArgumentsHash({
+			args: input,
+			exportResult,
+			instanceId: item.instance.instanceId,
+			accountId: connection.accountId,
+			connectionId: connection.id,
+			actionRevision: action.revision,
+			binaryVersion: item.adapter.binaryVersion,
+			adapterVersion: item.adapter.version,
+			principalId: item.principal.principalId,
+			agentId: item.agentId,
+			conversationId,
+			objective: conversationId ? connectorObjectiveScope(conversationId) : void 0
+		});
+		const decision = evaluateConnectorExecutionPolicy({
+			installation: item.policy,
+			action: {
+				scope: action.scope,
+				curated: true
+			},
+			agentId: item.agentId,
+			accountId: connection.accountId,
+			confirmed: Boolean(approvalId)
+		});
+		if (decision.decision === "denied") throw new Error(decision.reason);
+		if (decision.decision === "confirmation_required") {
+			const wait = conversationId && getSessionInputState(conversationId).activeInputId ? requireSessionConnection({
+				conversationId,
+				principalId: item.principal.principalId,
+				agentId: item.agentId ?? "main",
+				summary: `Confirm ${action.id}`,
+				needs: [{
+					key: `${item.instance.connectorId}:${connection.accountId}`,
+					connectorId: item.instance.connectorId,
+					accountId: connection.accountId,
+					connectionId: connection.id,
+					label: item.instance.displayName,
+					capabilities: [action.id]
+				}]
+			}) : void 0;
+			const approval = createConnectorApproval({
+				principalId: item.principal.principalId,
+				connectorId: item.instance.connectorId,
+				connectionId: connection.id,
+				agentId: item.agentId,
+				conversationId,
+				waitId: wait?.waitId,
+				actionId: action.id,
+				scope: action.scope,
+				argumentsHash: argumentsHash(),
+				argumentsPreview: {
+					account: {
+						id: connection.accountId,
+						identity: connection.identity
+					},
+					arguments: connectorArgumentsPreview(input)
+				},
+				expiresAt: new Date(Date.now() + 6e5).toISOString()
+			});
+			if (wait && conversationId) publishConnectionWait(conversationId);
+			return result({
+				status: "confirmation_required",
+				approvalId: approval.id,
+				argumentsPreview: approval.argumentsPreview,
+				instruction: "Approve this exact action in xopc, then retry with unchanged arguments and approvalId."
+			});
+		}
+		const executionId = randomUUID();
+		let authorized = false;
+		const beforeExecute = () => {
+			runSqliteWriteTransaction((db) => {
+				const hash = argumentsHash();
+				const freshPolicy = getConnectorInstallation(item.policy.id);
+				const freshConnection = getConnectorConnection(connection.id);
+				if (!freshPolicy || freshConnection?.status !== "active" || getConnectorAccount(connection.accountId)?.currentConnectionId !== connection.id || !selectConnectorAccount({
+					installation: freshPolicy,
+					agentId: item.agentId,
+					conversationId,
+					requestedAccountId: connection.accountId
+				}).connection || evaluateConnectorExecutionPolicy({
+					installation: freshPolicy,
+					action: {
+						scope: action.scope,
+						curated: true
+					},
+					accountId: connection.accountId,
+					agentId: item.agentId,
+					confirmed: Boolean(approvalId)
+				}).decision !== "allowed") throw new Error("Connector permission changed.");
+				if (approvalId) {
+					const approval = getConnectorApproval(approvalId);
+					if (!approval || approval.argumentsHash !== hash || !consumeConnectorApproval(approvalId, hash)) throw new Error("Approval is invalid, expired or already consumed.");
+				}
+				db.prepare(`INSERT INTO connector_cli_executions (id,instance_id,account_id,connection_id,action_id,revision,arguments_hash,status,owner_id,started_at)
+          VALUES (?,?,?,?,?,?,?,'running',?,?)`).run(executionId, item.instance.instanceId, connection.accountId, connection.id, action.id, action.revision, hash, cliOwnerId, Date.now());
+			});
+			authorized = true;
+		};
+		const started = Date.now();
+		let output;
+		try {
+			output = await executeCliAction(item.config, item.instance.instanceId, connection, action, input, context.signal, beforeExecute);
+		} catch (error) {
+			output = {
+				outcome: authorized && action.scope !== "read" ? "unknown" : "failed",
+				error: {
+					kind: "runtime",
+					message: error instanceof Error ? error.message : "CLI failed."
+				}
+			};
+		}
+		getSqliteDatabase().prepare("UPDATE connector_cli_executions SET status = ?, error_kind = ?, finished_at = ? WHERE id = ?").run(output.outcome, output.error?.kind ?? null, Date.now(), executionId);
+		appendConnectorExecutionAudit({
+			installationId: item.policy.id,
+			connectionId: connection.id,
+			connectorId: item.instance.connectorId,
+			principalId: item.principal.principalId,
+			agentId: item.agentId,
+			conversationId,
+			actionId: action.id,
+			scope: action.scope,
+			decision: authorized ? "allowed" : "denied",
+			resultStatus: output.outcome === "success" ? "success" : "error",
+			errorCode: output.outcome === "unknown" ? "outcome_unknown" : output.error?.kind,
+			durationMs: Date.now() - started
+		});
+		let artifact;
+		if (exportResult && output.outcome === "success") try {
+			await writeFile(join(cliContextPath(String(connection.metadata.contextId)), "files", `${executionId}.json`), JSON.stringify(output.data ?? null, null, 2), {
+				mode: 384,
+				flag: "wx"
+			});
+			artifact = `/api/connectors/executions/${executionId}/artifact`;
+		} catch {
+			return result({
+				executionId,
+				accountId: connection.accountId,
+				...output,
+				artifactError: "The action succeeded, but its JSON export could not be saved. Do not repeat the action to retry export."
+			});
+		}
+		return result({
+			...authorized ? { executionId } : {},
+			artifact,
+			accountId: connection.accountId,
+			...output,
+			...output.outcome === "unknown" ? { instruction: "The write may have succeeded. Inspect the provider using a read action; do not retry automatically." } : {}
+		});
+	}
+};
+//#endregion
+export { CliToolProvider };

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

@@ -6,22 +6,32 @@ import { consumeConnectorApproval, createConnectorApproval, getConnectorApproval
 import { bindObjectiveAccount, connectionBinding, connectionBindings, connectorObjectiveScope, init_connection_wait_repository, publishConnectionWait, requireSessionConnection } from "../../storage/sqlite/connection-wait-repository.js";
 import "../../storage/sqlite/index.js";
 import { connectorArgumentsHash, connectorArgumentsPreview } from "../../connectors/approval.js";
-import { connectorIdentitySummary } from "../../connectors/connector-identity.js";
 import { canAccessConnectorAccount, currentAccountConnections } from "../../connectors/account-access.js";
+import { connectorIdentitySummary } from "../../connectors/connector-identity.js";
 import { ComposioSessionsAdapter } from "../../connectors/composio-sessions.js";
 import { getComposioToolkitScope, getConfiguredComposioAuthConfigs, isComposioActionAllowedByCatalog, scopeForComposioAction } from "../../connectors/composio.js";
 import { getConnectorDefinition } from "../../connectors/catalog.js";
 import { listConnectorInstances } from "../../connectors/instances.js";
-import { isToolInputSchema } from "../../connectors/connection-capabilities.js";
 import { connectorPrincipalForSession } from "../../connectors/principal.js";
-import { ExternalToolSearchError } from "./search-error.js";
 import { externalToolRef, parseExternalToolRef } from "./refs.js";
+import { isToolInputSchema } from "../../connectors/connection-capabilities.js";
+import { ExternalToolSearchError } from "./search-error.js";
 //#region src/agent/external-tools/composio-provider.ts
 init_session_input_repository();
 init_connection_wait_repository();
 init_logger();
 const CONNECTION_ARGUMENT = "xopcAccountId";
 const log = createLogger("ComposioToolProvider");
+const BATCH_READ_ACTIONS = new Set([
+	"GMAIL_GET_PROFILE",
+	"GMAIL_GET_EMAIL",
+	"GMAIL_LIST_LABELS",
+	"GOOGLEDRIVE_GET_ABOUT",
+	"GOOGLEDRIVE_GET_FILE_METADATA",
+	"GITHUB_GET_THE_AUTHENTICATED_USER",
+	"GITHUB_GET_A_REPOSITORY",
+	"GITHUB_GET_REPOSITORY"
+]);
 function textResult(value) {
 	return {
 		content: [{
@@ -213,7 +223,8 @@ var ComposioToolProvider = class {
 			title: action.actionId,
 			summary,
 			description: `${summary} Available accounts: ${JSON.stringify(accounts)}. Use xopcAccountId to select one; never guess when the user's intent is ambiguous.`,
-			inputSchema: actionInputSchema(action)
+			inputSchema: actionInputSchema(action),
+			batchRead: accounts.length > 0 && action.scope === "read" && action.curated && BATCH_READ_ACTIONS.has(action.actionId)
 		};
 	}
 	async execute(toolRef, args, approvalId, _context) {

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

@@ -19,7 +19,7 @@ const ToolSearchSchema = Type.Object({
 	query: Type.String({ description: "Describe the capability or task you need." }),
 	sources: Type.Optional(Type.Array(Type.Union(EXTERNAL_TOOL_SOURCES.map((source) => Type.Literal(source))), {
 		maxItems: EXTERNAL_TOOL_SOURCES.length,
-		description: "Optional external tool sources to search."
+		description: "Omit to search all sources (recommended). Set only to intentionally restrict providers. Feishu/Lark, WeCom and WPS 365 connectors use cli."
 	})),
 	limit: Type.Optional(Type.Integer({
 		minimum: 1,
@@ -35,7 +35,8 @@ const ToolExecuteSchema = Type.Object({
 	toolRef: Type.String({ description: "Exact tool reference returned by xopc_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." }))
+	approvalId: Type.Optional(Type.String({ description: "One-time approval id when execution requested confirmation." })),
+	readOnly: Type.Optional(Type.Boolean({ description: "Require a host-curated batchRead contract; never permits unapproved operations." }))
 });
 function textResult(value, details = {}) {
 	return {
@@ -51,11 +52,17 @@ function createExternalToolGatewayTools(providers, getContext) {
 	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.",
+		description: `Search external tools from these sources: ${EXTERNAL_TOOL_SOURCES.join(", ")}. 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 compact references only; call xopc_tool_describe before execution. If a source-filtered search finds no relevant tools, retry without sources before concluding a capability is unavailable or requesting a connection.`,
 		parameters: ToolSearchSchema,
 		async execute(_toolCallId, params) {
+			const selectedSources = new Set(params.sources ?? []);
+			const excludedSources = selectedSources.size ? EXTERNAL_TOOL_SOURCES.filter((source) => !selectedSources.has(source)) : [];
 			return textResult({
 				...await service.search(params),
+				...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."
+				} } : {},
 				connectionCandidates: connectionCandidates(params.query),
 				selectedConnections: getContext?.()?.conversationId ? connectionBindings(getContext().conversationId) : [],
 				waitingObjective: getContext?.()?.conversationId ? getActiveConnectionWait(getContext().conversationId)?.summary : void 0

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

@@ -1,3 +1,5 @@
+import { resolveEffectiveAgentConfigForAgent, resolveEffectiveAgentConfigForSession } from "../../config/agent-profile.js";
+import { CliToolProvider } from "./cliProvider.js";
 import { ComposioToolProvider } from "./composio-provider.js";
 import { ExtensionToolProvider } from "./extension-provider.js";
 import { ExternalToolService } from "./service.js";
@@ -5,9 +7,15 @@ import { EXTERNAL_TOOL_NAMES, createExternalToolGatewayTools } from "./gateway-t
 import { McpToolProvider } from "./mcp-provider.js";
 import { MemoryToolProvider } from "./memory-provider.js";
 import { EndpointToolProvider } from "./endpoint-provider.js";
+import { withExternalReadPolicy } from "./read-policy.js";
 //#region src/agent/external-tools/index.ts
 function createDefaultExternalToolGatewayTools(deps) {
 	const providers = [
+		new CliToolProvider({
+			getConfig: deps.getConfig,
+			getCurrentContext: deps.getCurrentContext,
+			agentId: deps.agentId
+		}),
 		new McpToolProvider({
 			workspace: deps.workspace,
 			getConfig: deps.getConfig,
@@ -41,7 +49,12 @@ function createDefaultExternalToolGatewayTools(deps) {
 		runtime: deps.endpointTools,
 		getCurrentContext: deps.getCurrentContext
 	}));
-	return createExternalToolGatewayTools(providers, deps.getCurrentContext);
+	return createExternalToolGatewayTools(providers.map((provider) => withExternalReadPolicy(provider, (toolRef) => {
+		const config = deps.getConfig();
+		if (!config) return void 0;
+		const conversationId = deps.getCurrentContext()?.conversationId;
+		return (conversationId ? resolveEffectiveAgentConfigForSession(config, conversationId) : deps.agentId ? resolveEffectiveAgentConfigForAgent(config, deps.agentId) : resolveEffectiveAgentConfigForSession(config, void 0)).config.tools[toolRef];
+	})), deps.getCurrentContext);
 }
 //#endregion
 export { EXTERNAL_TOOL_NAMES, ExternalToolService, createDefaultExternalToolGatewayTools };

package/dist/src/agent/external-tools/read-policy.d.ts

@@ -0,0 +1,6 @@
+import type { ExternalToolProvider } from './types.js';
+/** Only local configuration and host-curated contracts may authorize delegated reads. */
+export declare function withExternalReadPolicy(provider: ExternalToolProvider, getPolicy: (toolRef: string) => {
+    mode: string;
+    readOnly?: boolean;
+} | undefined): ExternalToolProvider;

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

@@ -0,0 +1,21 @@
+//#region src/agent/external-tools/read-policy.ts
+/** Only local configuration and host-curated contracts may authorize delegated reads. */
+function withExternalReadPolicy(provider, getPolicy) {
+	return {
+		source: provider.source,
+		search: (query) => provider.search(query),
+		describe: async (ref) => {
+			const descriptor = await provider.describe(ref);
+			if (!descriptor) return void 0;
+			const policy = getPolicy(ref);
+			if (policy?.mode === "deny") return void 0;
+			return {
+				...descriptor,
+				batchRead: policy?.readOnly ?? descriptor.batchRead
+			};
+		},
+		execute: (ref, args, approval, context) => provider.execute(ref, args, approval, context)
+	};
+}
+//#endregion
+export { withExternalReadPolicy };

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

@@ -24,6 +24,7 @@ export declare class ExternalToolService {
         revision: string;
         arguments?: Record<string, unknown>;
         approvalId?: string;
+        readOnly?: boolean;
         context: ExternalToolExecutionContext;
     }): Promise<import("@earendil-works/pi-agent-core").AgentToolResult<Record<string, unknown>>>;
     private providerForRef;