@xopcai/xopc 0.0.309 → 0.0.311

package/dist/packages/gateway-contract/src/proactive.js

@@ -1,7 +1,7 @@
 import { __esmMin } from "../../../_virtual/_rolldown/runtime.js";
 import { z } from "zod";
 //#region packages/gateway-contract/src/proactive.ts
-var ProactiveLevelSchema, ProactiveTimezoneSchema, ProactivePreferencesSchema, ProactivePreferencesUpdateSchema, ProactiveSubscriptionSettingsSchema, ProactiveSubscriptionCreateSchema, ProactiveSubscriptionUpdateSchema, ProactiveArtifactSchema, ProactiveTaskDraftSchema, ProactiveCardActionSchema;
+var ProactiveLevelSchema, ProactiveTimezoneSchema, ProactivePreferencesSchema, ProactiveSubscriptionSettingsSchema, ProactiveArtifactSchema, ProactiveTaskDraftSchema;
 var init_proactive = __esmMin((() => {
 	ProactiveLevelSchema = z.enum([
 		"quiet",
@@ -46,7 +46,7 @@ var init_proactive = __esmMin((() => {
 		notificationsMuted: z.boolean().default(false),
 		revision: z.number().int().nonnegative().default(0)
 	});
-	ProactivePreferencesUpdateSchema = z.object({
+	z.object({
 		level: ProactivePreferencesSchema.shape.level.removeDefault().optional(),
 		timezone: ProactivePreferencesSchema.shape.timezone.removeDefault().optional(),
 		quietStartHour: ProactivePreferencesSchema.shape.quietStartHour.removeDefault().optional(),
@@ -74,13 +74,13 @@ var init_proactive = __esmMin((() => {
 		scanIntervalMinutes: z.number().int().min(15).max(10080).nullable().default(null),
 		userInstructions: z.string().max(12e3).default("")
 	});
-	ProactiveSubscriptionCreateSchema = ProactiveSubscriptionSettingsSchema.extend({
+	ProactiveSubscriptionSettingsSchema.extend({
 		scenarioKey: z.string().min(1).max(100),
 		scopeKind: z.enum(["workspace", "project"]),
 		scopeId: z.string().min(1).max(200),
 		enabled: z.boolean().default(true)
 	}).strict();
-	ProactiveSubscriptionUpdateSchema = z.object({
+	z.object({
 		level: ProactiveSubscriptionSettingsSchema.shape.level.removeDefault().optional(),
 		delivery: ProactiveSubscriptionSettingsSchema.shape.delivery.removeDefault().optional(),
 		completedAt: ProactiveSubscriptionSettingsSchema.shape.completedAt.removeDefault().optional(),
@@ -102,7 +102,7 @@ var init_proactive = __esmMin((() => {
 		title: z.string().trim().min(1).max(160),
 		objective: z.string().trim().min(1).max(1200)
 	}).strict();
-	ProactiveCardActionSchema = z.object({
+	z.object({
 		actionId: z.enum([
 			"read",
 			"resolve",
@@ -133,4 +133,4 @@ var init_proactive = __esmMin((() => {
 }));
 //#endregion
 init_proactive();
-export { ProactiveArtifactSchema, ProactiveCardActionSchema, ProactiveLevelSchema, ProactivePreferencesSchema, ProactivePreferencesUpdateSchema, ProactiveSubscriptionCreateSchema, ProactiveSubscriptionSettingsSchema, ProactiveSubscriptionUpdateSchema, ProactiveTaskDraftSchema, ProactiveTimezoneSchema, init_proactive };
+export { ProactiveArtifactSchema, ProactiveLevelSchema, ProactivePreferencesSchema, ProactiveSubscriptionSettingsSchema, ProactiveTaskDraftSchema, ProactiveTimezoneSchema, init_proactive };

package/dist/packages/gateway-contract/src/project-monitoring.js

@@ -1,7 +1,7 @@
 import { __esmMin } from "../../../_virtual/_rolldown/runtime.js";
 import { z } from "zod";
 //#region packages/gateway-contract/src/project-monitoring.ts
-var MonitoringModeSchema, QuietHoursSchema, ProjectMonitoringPolicySchema, ProjectMonitoringUpdateSchema;
+var MonitoringModeSchema, QuietHoursSchema;
 var init_project_monitoring = __esmMin((() => {
 	MonitoringModeSchema = z.enum([
 		"observe",
@@ -13,7 +13,7 @@ var init_project_monitoring = __esmMin((() => {
 		endHour: z.number().int().min(0).max(23),
 		timezone: z.string().min(1)
 	});
-	ProjectMonitoringPolicySchema = z.object({
+	z.object({
 		projectId: z.string(),
 		mode: MonitoringModeSchema,
 		quietHours: QuietHoursSchema.optional(),
@@ -23,7 +23,7 @@ var init_project_monitoring = __esmMin((() => {
 		configured: z.boolean(),
 		updatedAt: z.number().optional()
 	});
-	ProjectMonitoringUpdateSchema = z.object({
+	z.object({
 		mode: MonitoringModeSchema.optional(),
 		quietHours: QuietHoursSchema.nullable().optional(),
 		allowedActions: z.array(z.string()).optional(),
@@ -33,4 +33,4 @@ var init_project_monitoring = __esmMin((() => {
 }));
 //#endregion
 init_project_monitoring();
-export { MonitoringModeSchema, ProjectMonitoringPolicySchema, ProjectMonitoringUpdateSchema, QuietHoursSchema, init_project_monitoring };
+export { MonitoringModeSchema, QuietHoursSchema, init_project_monitoring };

package/dist/packages/gateway-contract/src/project-operating.js

@@ -1,13 +1,11 @@
 import { __esmMin } from "../../../_virtual/_rolldown/runtime.js";
 import { TaskAttentionItemSchema, TaskOperationalStateSchema, TaskPhaseSchema, TaskResolutionSchema } from "./task-lifecycle.js";
 import { TaskDependencySummarySchema, TaskPrioritySchema, TaskRunReceiptSchema, init_tasks } from "./tasks.js";
-import { ProjectMonitoringPolicySchema, init_project_monitoring } from "./project-monitoring.js";
 import { z } from "zod";
 //#region packages/gateway-contract/src/project-operating.ts
 var ProjectSummarySchema, ProjectTaskDependencyEdgeSchema, ProjectTaskCardSchema;
 var init_project_operating = __esmMin((() => {
 	init_tasks();
-	init_project_monitoring();
 	ProjectSummarySchema = z.object({
 		id: z.string(),
 		name: z.string(),
@@ -91,8 +89,7 @@ var init_project_operating = __esmMin((() => {
 			]),
 			summary: z.string(),
 			recommendedAction: z.string().optional()
-		}),
-		monitoring: ProjectMonitoringPolicySchema
+		})
 	});
 }));
 //#endregion

package/dist/src/agent/agent-manager.d.ts

@@ -1,9 +1,4 @@
-/**
- * Agent Manager - Manages Agent instances per session
- *
- * Each session gets its own Agent instance for true isolation
- * and concurrent processing across sessions.
- */
+import type { SceneAccess } from '../scenes/httpServices.js';
 import { Agent, type AgentMessage, type AgentEvent, type ThinkingLevel } from '@earendil-works/pi-agent-core';
 import type { AgentInstanceGateway } from './agent-instance-gateway.js';
 import { type Config } from '../config/schema.js';
@@ -95,6 +90,7 @@ export interface AgentManagerConfig {
     };
     /** Gateway: exposes AutomationService for the `automation` tool. */
     getAutomationService?: () => AutomationService | undefined;
+    getSceneAccess?: () => SceneAccess | undefined;
     getBrowserAutomationService?: () => import('../browser/automations/index.js').BrowserAutomationService | undefined;
     emitBrowserEvent?: (type: string, payload: unknown) => void;
     /** Gateway: exposes first-class xopc product objects for the `xopc_use` tool. */

package/dist/src/agent/agent-manager.js

@@ -4,7 +4,7 @@ import { init_logger } from "../utils/logger.js";
 import { isXopcDatabaseOpen } from "../storage/sqlite/connection.js";
 import { consumeClarificationApproval } from "../storage/sqlite/clarification-wait-repository.js";
 import { getInteractionState } from "../storage/sqlite/interaction-state-repository.js";
-import { getSessionMetadata } from "../storage/sqlite/session-repository.js";
+import { getSessionMetadata } from "../storage/sqlite/session-read-repository.js";
 import "../storage/sqlite/index.js";
 import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
 import { applyConfigOverrides } from "../config/runtime-overrides.js";
@@ -262,6 +262,7 @@ var AgentManager = class {
 			getSessionStore: this.config.getSessionStore,
 			gatewayClarify: this.config.gatewayClarify,
 			getAutomationService: this.config.getAutomationService,
+			getSceneAccess: this.config.getSceneAccess,
 			getBrowserAutomationService: this.config.getBrowserAutomationService,
 			emitBrowserEvent: this.config.emitBrowserEvent,
 			getNotesService: this.config.getNotesService,

package/dist/src/agent/background-review/run-background-review.js

@@ -1,7 +1,7 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { finishContextExtractionRun } from "../../storage/sqlite/context-extraction-repository.js";
-import { getSessionMetadata } from "../../storage/sqlite/session-repository.js";
+import { getSessionMetadata } from "../../storage/sqlite/session-read-repository.js";
 import { loadCompactionSourceSnapshot } from "../../storage/sqlite/transcript-repository.js";
 import "../../storage/sqlite/index.js";
 import { extractProfileAgentId } from "../../config/agent-profile.js";

package/dist/src/agent/commands/command-registry.js

@@ -1,8 +1,8 @@
 import { resolveStateDir } from "../../config/paths-state.js";
 import { init_global_singleton, resolveGlobalSingleton } from "../../utils/global-singleton.js";
 import { init_paths } from "../../config/paths.js";
-import { DurableState } from "../../storage/sqlite/durable-state.js";
 import { spawnProcess } from "../../process/run-process.js";
+import { DurableState } from "../../storage/sqlite/durable-state.js";
 import { isolatedCommand, removeCommandContainer } from "./command-isolation.js";
 import { readWorkspaceRevision } from "../coding/workspace-revision.js";
 import { join } from "node:path";

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

@@ -1,5 +1,5 @@
 import { isXopcDatabaseOpen } from "../../storage/sqlite/connection.js";
-import { getSessionMetadata } from "../../storage/sqlite/session-repository.js";
+import { getSessionMetadata } from "../../storage/sqlite/session-read-repository.js";
 import "../../storage/sqlite/index.js";
 import { sanitizeForPromptLiteral } from "../prompt/sanitize-for-prompt.js";
 import { TaskRepository } from "../../tasks/task-repository.js";

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,16 +6,16 @@ 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();

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,
@@ -52,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,4 +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";
@@ -10,6 +11,11 @@ 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,

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

@@ -120,7 +120,7 @@ var ExternalToolService = class {
 		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 ?? {};
-		if (params.readOnly && provider.source === "composio" && (typeof args.xopcAccountId !== "string" || !args.xopcAccountId)) throw new Error("Batch connector reads require an explicit xopcAccountId");
+		if (params.readOnly && (provider.source === "composio" || provider.source === "cli") && (typeof args.xopcAccountId !== "string" || !args.xopcAccountId)) throw new Error("Batch connector reads require an explicit xopcAccountId");
 		let validate;
 		try {
 			validate = this.ajv.compile(current.inputSchema);

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

@@ -1,6 +1,6 @@
 import type { AgentToolResult, AgentToolUpdateCallback } from '@earendil-works/pi-agent-core';
 import type { TurnOrigin } from '@xopcai/endpoint-tools-protocol';
-export declare const EXTERNAL_TOOL_SOURCES: readonly ["mcp", "composio", "extension", "memory", "endpoint"];
+export declare const EXTERNAL_TOOL_SOURCES: readonly ["cli", "mcp", "composio", "extension", "memory", "endpoint"];
 export type ExternalToolSource = (typeof EXTERNAL_TOOL_SOURCES)[number];
 export interface ExternalToolSearchHit {
     toolRef: string;

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

@@ -1,5 +1,6 @@
 //#region src/agent/external-tools/types.ts
 const EXTERNAL_TOOL_SOURCES = [
+	"cli",
 	"mcp",
 	"composio",
 	"extension",

package/dist/src/agent/mcp/bundle-mcp-runtime.js

@@ -1,6 +1,6 @@
-import { init_global_singleton, resolveGlobalSingleton } from "../../utils/global-singleton.js";
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
+import { init_global_singleton, resolveGlobalSingleton } from "../../utils/global-singleton.js";
 import { init_string_coerce, normalizeOptionalString } from "../../utils/string-coerce.js";
 import { resolveConnectorSecretReferences } from "../../connectors/secret-store.js";
 import { redactSensitiveUrlLikeString } from "../../utils/redact-sensitive-url.js";

package/dist/src/agent/mcp/oauth/mcp-oauth-manager.js

@@ -1,6 +1,6 @@
-import { init_global_singleton, resolveGlobalSingleton } from "../../../utils/global-singleton.js";
 import { createLogger } from "../../../utils/logger/index.js";
 import { init_logger } from "../../../utils/logger.js";
+import { init_global_singleton, resolveGlobalSingleton } from "../../../utils/global-singleton.js";
 import { resolveConnectorSecretReferences } from "../../../connectors/secret-store.js";
 import { redactSensitiveUrlLikeString } from "../../../utils/redact-sensitive-url.js";
 import { resolveMcpTransportConfig } from "../mcp-transport-config.js";