@xopcai/xopc 0.0.187 → 0.0.189

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

@@ -0,0 +1,307 @@
+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, isComposioActionAllowedByCatalog, scopeForComposioAction } from "../../connectors/composio.js";
+import { getConnectorDefinition } from "../../connectors/catalog.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 {
+		content: [{
+			type: "text",
+			text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
+		}],
+		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 [];
+		const row = record;
+		const marker = row.xopcConnector;
+		const markerRecord = marker && typeof marker === "object" && !Array.isArray(marker) ? marker : void 0;
+		if (markerRecord?.enabled === false) return [];
+		const runtime = row.runtime;
+		if (typeof markerRecord?.connectorId !== "string" || !runtime || typeof runtime !== "object" || Array.isArray(runtime) || runtime.type !== "composio" || runtime.role !== "toolkit" || typeof runtime.toolkit !== "string") return [];
+		return [{
+			connectorId: markerRecord.connectorId,
+			toolkit: runtime.toolkit
+		}];
+	});
+}
+function composioToolkitFromConnectorId(connectorId) {
+	const definition = getConnectorDefinition(connectorId);
+	return definition?.runtime.type === "composio" && definition.runtime.role === "toolkit" ? definition.runtime.toolkit : void 0;
+}
+function toolkitFromInstallation(installation) {
+	const toolkit = composioToolkitFromConnectorId(installation.connectorId);
+	if (!toolkit) throw new Error(`Connector installation is not a Composio toolkit: ${installation.connectorId}`);
+	return toolkit;
+}
+function syncLocalOwnerInstallations(config) {
+	for (const { connectorId, toolkit } of installedConfigToolkits(config)) {
+		const id = `${connectorId}-local-owner`;
+		const existing = getConnectorInstallation(id);
+		upsertConnectorInstallation({
+			id,
+			connectorId,
+			principalId: "local-owner",
+			enabled: true,
+			allowedAgentIds: existing?.allowedAgentIds ?? [],
+			maxScope: getComposioToolkitScope(config, toolkit),
+			confirmationPolicy: existing?.confirmationPolicy ?? "writes",
+			selectedConnectionIds: existing?.selectedConnectionIds ?? [],
+			createdAt: existing?.createdAt
+		});
+	}
+}
+function toolkitForAction(actionId, candidates) {
+	const normalizedAction = actionId.trim().toUpperCase();
+	return [...candidates].sort((left, right) => right.length - left.length).find((toolkit) => normalizedAction === toolkit.toUpperCase() || normalizedAction.startsWith(`${toolkit.toUpperCase()}_`));
+}
+function contractFromSearch(connectorId, toolkit, actionId, value) {
+	const row = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+	const risk = scopeForComposioAction(actionId);
+	return {
+		connectorId,
+		actionId,
+		toolkit,
+		scope: risk.scope,
+		curated: risk.curated,
+		inputSchema: row.inputSchema,
+		cachedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+function schemaSummary(value, fallback) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return fallback;
+	const row = value;
+	for (const candidate of [
+		row.description,
+		row.title,
+		row.name
+	]) if (typeof candidate === "string" && candidate.trim()) return candidate.trim();
+	return fallback;
+}
+function actionInputSchema(action) {
+	const schema = action.inputSchema && typeof action.inputSchema === "object" && !Array.isArray(action.inputSchema) ? action.inputSchema : { type: "object" };
+	const properties = schema.properties && typeof schema.properties === "object" && !Array.isArray(schema.properties) ? schema.properties : {};
+	return {
+		...schema,
+		type: "object",
+		properties: {
+			...properties,
+			[CONNECTION_ARGUMENT]: {
+				type: "string",
+				description: "Optional local connection id when more than one account is connected."
+			}
+		}
+	};
+}
+var ComposioToolProvider = class {
+	source = "composio";
+	adapter;
+	constructor(deps) {
+		this.deps = deps;
+		this.adapter = deps.adapter ?? new ComposioSessionsAdapter();
+	}
+	async search(query) {
+		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
+		})).search({
+			query,
+			toolkits
+		});
+		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.`
+			};
+		});
+		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;
+			upsertConnectorActionMetadata(contractFromSearch(installation.connectorId, toolkit, actionId, schema));
+			hits.push({
+				toolRef: externalToolRef(this.source, installation.id, actionId),
+				source: this.source,
+				namespace: toolkit,
+				title: actionId,
+				summary: schemaSummary(schema, `Run ${actionId} in ${toolkit}.`)
+			});
+		}
+		return hits;
+	}
+	async describe(toolRef) {
+		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;
+		const summary = `Run ${action.actionId} in ${toolkit}.`;
+		return {
+			toolRef,
+			source: this.source,
+			namespace: toolkit,
+			title: action.actionId,
+			summary,
+			description: summary,
+			inputSchema: actionInputSchema(action)
+		};
+	}
+	async execute(toolRef, args, approvalId, _context) {
+		const available = this.availableInstallations();
+		const resolved = this.resolve(toolRef, available.installations);
+		if (!resolved) return textResult("This connected app tool is not allowed for this user and agent.");
+		let executionArgs = args;
+		if (this.deps.hookRunner) {
+			const hook = await this.deps.hookRunner.runBeforeToolCall(toolRef, args, { sessionKey: available.context?.sessionKey });
+			if (!hook.allowed) throw new Error(hook.reason ?? "Connected app tool call blocked by policy hook.");
+			executionArgs = hook.params ?? args;
+		}
+		const toolkit = toolkitFromInstallation(resolved.installation);
+		if (resolved.actionId === CONNECT_ACTION) {
+			const authorization = await this.adapter.authorize({
+				principalId: available.principalId,
+				toolkit,
+				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(() => []);
+		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];
+		const actionArgs = { ...executionArgs };
+		delete actionArgs[CONNECTION_ARGUMENT];
+		const argsHash = connectorArgumentsHash(actionArgs);
+		let confirmed = false;
+		if (approvalId) {
+			const pending = getConnectorApproval(approvalId);
+			if (!pending || pending.principalId !== available.principalId || pending.connectorId !== resolved.installation.connectorId || pending.actionId !== action.actionId || pending.sessionKey !== available.context?.sessionKey) return textResult("The connector approval is invalid for this session or action.");
+			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]
+			},
+			installation: resolved.installation,
+			connection,
+			action,
+			args: actionArgs,
+			agentId: available.agentId,
+			sessionKey: available.context?.sessionKey,
+			confirmed
+		});
+		if (result.decision === "confirmation_required") {
+			const approval = createConnectorApproval({
+				principalId: available.principalId,
+				connectorId: resolved.installation.connectorId,
+				connectionId: connection?.id,
+				agentId: available.agentId,
+				sessionKey: available.context?.sessionKey,
+				actionId: action.actionId,
+				scope: action.scope,
+				argumentsHash: argsHash,
+				argumentsPreview: connectorArgumentsPreview(actionArgs),
+				expiresAt: new Date(Date.now() + 10 * 6e4).toISOString()
+			});
+			return textResult({
+				status: "confirmation_required",
+				approvalId: approval.id,
+				actionId: approval.actionId,
+				scope: approval.scope,
+				argumentsPreview: approval.argumentsPreview,
+				expiresAt: approval.expiresAt,
+				instruction: "Ask the user to approve this exact action in xopc, then retry with the approvalId and unchanged arguments."
+			});
+		}
+		return textResult(result.decision === "allowed" ? result.result : result.reason);
+	}
+	availableInstallations() {
+		const context = this.deps.getCurrentContext();
+		const principal = connectorPrincipalForSession(context?.sessionKey);
+		if (principal.isLocalOwner) syncLocalOwnerInstallations(this.deps.getConfig());
+		const agentId = this.deps.agentId ?? principal.agentId;
+		const installations = listConnectorInstallations(principal.principalId).filter((installation) => installation.enabled && composioToolkitFromConnectorId(installation.connectorId) !== void 0 && (installation.allowedAgentIds.length === 0 || Boolean(agentId && installation.allowedAgentIds.includes(agentId))));
+		return {
+			principalId: principal.principalId,
+			agentId,
+			context,
+			installations
+		};
+	}
+	resolve(toolRef, installations = this.availableInstallations().installations) {
+		const parsed = parseExternalToolRef(toolRef, this.source);
+		if (!parsed) return void 0;
+		const installation = installations.find((candidate) => candidate.id === parsed.namespace);
+		return installation ? {
+			installation,
+			actionId: parsed.toolName
+		} : void 0;
+	}
+};
+//#endregion
+export { ComposioToolProvider };

package/dist/src/agent/external-tools/endpoint-provider.d.ts

@@ -0,0 +1,17 @@
+import type { AgentToolResult } from '@earendil-works/pi-agent-core';
+import type { EndpointToolRuntime } from '../../endpoint-tools/index.js';
+import type { ExternalToolDescriptor, ExternalToolExecutionContext, ExternalToolProvider, ExternalToolSearchHit, ExternalToolTurnContext } from './types.js';
+export interface EndpointToolProviderDeps {
+    runtime: EndpointToolRuntime;
+    getCurrentContext: () => ExternalToolTurnContext | null;
+}
+export declare class EndpointToolProvider implements ExternalToolProvider {
+    private readonly deps;
+    readonly source: "endpoint";
+    constructor(deps: EndpointToolProviderDeps);
+    search(_query: string): Promise<ExternalToolSearchHit[]>;
+    describe(toolRef: string): Promise<ExternalToolDescriptor | undefined>;
+    execute(toolRef: string, args: Record<string, unknown>, _approvalId: string | undefined, context: ExternalToolExecutionContext): Promise<AgentToolResult<Record<string, unknown>>>;
+    private currentEndpoint;
+    private resolve;
+}

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

@@ -0,0 +1,93 @@
+import { externalToolRef, parseExternalToolRef } from "./refs.js";
+//#region src/agent/external-tools/endpoint-provider.ts
+function contentText(content) {
+	if (content.type === "text") return content.text;
+	if (content.type === "json") return JSON.stringify(content.value, null, 2);
+	return `[File: ${content.name}, ${content.mimeType}, ${content.size} bytes, id=${content.fileId}]`;
+}
+var EndpointToolProvider = class {
+	source = "endpoint";
+	constructor(deps) {
+		this.deps = deps;
+	}
+	async search(_query) {
+		const endpoint = this.currentEndpoint();
+		if (!endpoint) return [];
+		return endpoint.tools.map(({ descriptor }) => ({
+			toolRef: externalToolRef(this.source, endpoint.endpointId, descriptor.name),
+			source: this.source,
+			namespace: endpoint.endpointId,
+			title: descriptor.title,
+			summary: `${descriptor.description} (${endpoint.displayName})`
+		}));
+	}
+	async describe(toolRef) {
+		const resolved = this.resolve(toolRef);
+		if (!resolved) return void 0;
+		return {
+			toolRef,
+			source: this.source,
+			namespace: resolved.endpointId,
+			title: resolved.tool.descriptor.title,
+			summary: `${resolved.tool.descriptor.description} (${resolved.displayName})`,
+			description: resolved.tool.descriptor.description,
+			inputSchema: resolved.tool.descriptor.inputSchema
+		};
+	}
+	async execute(toolRef, args, _approvalId, context) {
+		const resolved = this.resolve(toolRef);
+		if (!resolved) throw new Error(`Endpoint tool is unavailable for this turn: ${toolRef}`);
+		const result = await this.deps.runtime.invocations.invoke({
+			endpointId: resolved.endpointId,
+			toolCallId: context.toolCallId,
+			toolName: resolved.tool.descriptor.name,
+			arguments: args,
+			descriptorRevision: resolved.tool.revision,
+			signal: context.signal,
+			onProgress: (progress) => {
+				context.onUpdate?.({
+					content: [{
+						type: "text",
+						text: progress.message ?? "Endpoint tool is running"
+					}],
+					details: {
+						endpointId: resolved.endpointId,
+						...progress.percent === void 0 ? {} : { percent: progress.percent }
+					}
+				});
+			}
+		});
+		const files = result.content.filter((item) => item.type === "file");
+		return {
+			content: result.content.map((item) => ({
+				type: "text",
+				text: contentText(item)
+			})),
+			details: {
+				endpointId: resolved.endpointId,
+				endpointToolName: resolved.tool.descriptor.name,
+				...result.details ?? {},
+				...files.length === 0 ? {} : { endpointFiles: files }
+			}
+		};
+	}
+	currentEndpoint() {
+		const origin = this.deps.getCurrentContext()?.origin;
+		if (origin?.type !== "endpoint") return void 0;
+		return this.deps.runtime.registry.get(origin.endpointId);
+	}
+	resolve(toolRef) {
+		const parsed = parseExternalToolRef(toolRef, this.source);
+		if (!parsed) return void 0;
+		const endpoint = this.currentEndpoint();
+		if (!endpoint || endpoint.endpointId !== parsed.namespace) return void 0;
+		const tool = this.deps.runtime.registry.getTool(endpoint.endpointId, parsed.toolName);
+		return tool ? {
+			endpointId: endpoint.endpointId,
+			displayName: endpoint.displayName,
+			tool
+		} : void 0;
+	}
+};
+//#endregion
+export { EndpointToolProvider };

package/dist/src/agent/external-tools/extension-provider.d.ts

@@ -0,0 +1,20 @@
+import type { ExtensionHookRunner } from '../../extensions/index.js';
+import type { ExtensionRegistry } from '../../extensions/types/index.js';
+import { type ToolExecutorConfig } from '../tools/executor.js';
+import type { ExternalToolDescriptor, ExternalToolExecutionContext, ExternalToolProvider, ExternalToolSearchHit } from './types.js';
+export interface ExtensionToolProviderDeps {
+    registry?: ExtensionRegistry;
+    disabledTools?: Set<string>;
+    getSessionKey: () => string | undefined;
+    hookRunner?: ExtensionHookRunner;
+    toolExecutorConfig?: Partial<ToolExecutorConfig>;
+}
+export declare class ExtensionToolProvider implements ExternalToolProvider {
+    private readonly deps;
+    readonly source: "extension";
+    constructor(deps: ExtensionToolProviderDeps);
+    search(_query: string): Promise<ExternalToolSearchHit[]>;
+    describe(toolRef: string): Promise<ExternalToolDescriptor | undefined>;
+    execute(toolRef: string, args: Record<string, unknown>, _approvalId: string | undefined, context: ExternalToolExecutionContext): Promise<import("@earendil-works/pi-agent-core").AgentToolResult<any>>;
+    private resolve;
+}

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

@@ -0,0 +1,68 @@
+import { externalToolRef, parseExternalToolRef } from "./refs.js";
+import { executeToolWithProtection } from "../tools/executor.js";
+//#region src/agent/external-tools/extension-provider.ts
+function toolSummary(tool) {
+	return tool.description || tool.label || tool.name;
+}
+var ExtensionToolProvider = class {
+	source = "extension";
+	constructor(deps) {
+		this.deps = deps;
+	}
+	async search(_query) {
+		if (!this.deps.registry) return [];
+		return this.deps.registry.getAllTools().filter((tool) => !this.deps.disabledTools?.has(tool.name)).flatMap((tool) => {
+			const extensionId = this.deps.registry.getToolExtensionId(tool.name);
+			if (!extensionId) return [];
+			return [{
+				toolRef: externalToolRef(this.source, extensionId, tool.name),
+				source: this.source,
+				namespace: extensionId,
+				title: tool.label || tool.name,
+				summary: toolSummary(tool)
+			}];
+		});
+	}
+	async describe(toolRef) {
+		const resolved = this.resolve(toolRef);
+		if (!resolved) return void 0;
+		const { extensionId, tool } = resolved;
+		const summary = toolSummary(tool);
+		return {
+			toolRef,
+			source: this.source,
+			namespace: extensionId,
+			title: tool.label || tool.name,
+			summary,
+			description: summary,
+			inputSchema: tool.parameters
+		};
+	}
+	async execute(toolRef, args, _approvalId, context) {
+		const resolved = this.resolve(toolRef);
+		if (!resolved) throw new Error(`Extension tool is unavailable: ${toolRef}`);
+		let executionArgs = args;
+		if (this.deps.hookRunner) {
+			const hook = await this.deps.hookRunner.runBeforeToolCall(resolved.tool.name, args, {
+				extensionId: resolved.extensionId,
+				sessionKey: this.deps.getSessionKey()
+			});
+			if (!hook.allowed) throw new Error(hook.reason ?? "Extension tool call blocked by policy hook.");
+			executionArgs = hook.params ?? args;
+		}
+		return executeToolWithProtection(resolved.tool, context.toolCallId, executionArgs, context.signal, context.onUpdate, this.deps.toolExecutorConfig);
+	}
+	resolve(toolRef) {
+		if (!this.deps.registry) return void 0;
+		const parsed = parseExternalToolRef(toolRef, this.source);
+		if (!parsed || this.deps.disabledTools?.has(parsed.toolName)) return void 0;
+		const tool = this.deps.registry.getTool(parsed.toolName);
+		if (!tool || this.deps.registry.getToolExtensionId(parsed.toolName) !== parsed.namespace) return;
+		return {
+			extensionId: parsed.namespace,
+			tool
+		};
+	}
+};
+//#endregion
+export { ExtensionToolProvider };

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

@@ -0,0 +1,8 @@
+import type { AgentTool } from '@earendil-works/pi-agent-core';
+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";
+};
+export declare function createExternalToolGatewayTools(providers: ExternalToolProvider[]): AgentTool[];

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

@@ -0,0 +1,89 @@
+import { ExternalToolService } from "./service.js";
+import { EXTERNAL_TOOL_SOURCES } from "./types.js";
+import { Type } from "@sinclair/typebox";
+//#region src/agent/external-tools/gateway-tools.ts
+const EXTERNAL_TOOL_NAMES = {
+	search: "xopc_tool_search",
+	describe: "xopc_tool_describe",
+	execute: "xopc_tool_execute"
+};
+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."
+	})),
+	limit: Type.Optional(Type.Integer({
+		minimum: 1,
+		maximum: 20
+	}))
+});
+const ToolDescribeSchema = Type.Object({ toolRefs: Type.Array(Type.String(), {
+	minItems: 1,
+	maxItems: 3,
+	description: "Exact tool references returned by xopc_tool_search."
+}) });
+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." }))
+});
+function textResult(value, details = {}) {
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(value, null, 2)
+		}],
+		details
+	};
+}
+function createExternalToolGatewayTools(providers) {
+	const service = new ExternalToolService(providers);
+	return [
+		{
+			name: EXTERNAL_TOOL_NAMES.search,
+			label: "🔎 External Tool Search",
+			description: "Search MCP, connected-app, extension, remote-memory, and current-endpoint tools. Use concise English capability keywords. Returns compact references only; call xopc_tool_describe before execution.",
+			parameters: ToolSearchSchema,
+			async execute(_toolCallId, params) {
+				return textResult(await service.search(params));
+			}
+		},
+		{
+			name: EXTERNAL_TOOL_NAMES.describe,
+			label: "📋 External Tool Contract",
+			description: "Load exact contracts for up to three external tools returned by xopc_tool_search.",
+			parameters: ToolDescribeSchema,
+			async execute(_toolCallId, params) {
+				return textResult(await service.describe(params.toolRefs));
+			}
+		},
+		{
+			name: EXTERNAL_TOOL_NAMES.execute,
+			label: "▶️ External Tool Execute",
+			description: "Execute one external tool using its exact reference, contract revision, and validated arguments.",
+			parameters: ToolExecuteSchema,
+			async execute(toolCallId, params, signal, onUpdate) {
+				const result = await service.execute({
+					...params,
+					context: {
+						toolCallId,
+						signal,
+						onUpdate
+					}
+				});
+				return {
+					...result,
+					details: {
+						...result.details ?? {},
+						delegatedToolRef: params.toolRef,
+						delegatedToolRevision: params.revision
+					}
+				};
+			}
+		}
+	];
+}
+//#endregion
+export { EXTERNAL_TOOL_NAMES, createExternalToolGatewayTools };

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

@@ -0,0 +1,23 @@
+import type { Config } from '../../config/schema.js';
+import type { ExtensionHookRunner } from '../../extensions/index.js';
+import type { ExtensionRegistry } from '../../extensions/types/index.js';
+import type { MemoryManager } from '../memory/manager.js';
+import type { EndpointToolRuntime } from '../../endpoint-tools/index.js';
+import type { ToolExecutorConfig } from '../tools/executor.js';
+import type { ExternalToolTurnContext } from './types.js';
+export interface DefaultExternalToolGatewayDeps {
+    workspace: string;
+    getConfig: () => Config | undefined;
+    getCurrentContext: () => ExternalToolTurnContext | null;
+    endpointTools?: EndpointToolRuntime;
+    agentId?: string;
+    extensionRegistry?: ExtensionRegistry;
+    disabledTools?: Set<string>;
+    hookRunner?: ExtensionHookRunner;
+    toolExecutorConfig?: Partial<ToolExecutorConfig>;
+    getMemoryManager?: () => MemoryManager;
+}
+export declare function createDefaultExternalToolGatewayTools(deps: DefaultExternalToolGatewayDeps): import("@earendil-works/pi-agent-core").AgentTool<import("typebox").TSchema, any>[];
+export { ExternalToolService } from './service.js';
+export { EXTERNAL_TOOL_NAMES } from './gateway-tools.js';
+export type * from './types.js';

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

@@ -0,0 +1,46 @@
+import { ComposioToolProvider } from "./composio-provider.js";
+import { ExtensionToolProvider } from "./extension-provider.js";
+import { ExternalToolService } from "./service.js";
+import { EXTERNAL_TOOL_NAMES, createExternalToolGatewayTools } from "./gateway-tools.js";
+import { McpToolProvider } from "./mcp-provider.js";
+import { MemoryToolProvider } from "./memory-provider.js";
+import { EndpointToolProvider } from "./endpoint-provider.js";
+//#region src/agent/external-tools/index.ts
+function createDefaultExternalToolGatewayTools(deps) {
+	const providers = [
+		new McpToolProvider({
+			workspace: deps.workspace,
+			getConfig: deps.getConfig,
+			getSessionKey: () => deps.getCurrentContext()?.sessionKey,
+			agentId: deps.agentId,
+			hookRunner: deps.hookRunner
+		}),
+		new ComposioToolProvider({
+			getConfig: deps.getConfig,
+			getCurrentContext: deps.getCurrentContext,
+			agentId: deps.agentId,
+			hookRunner: deps.hookRunner
+		}),
+		new ExtensionToolProvider({
+			registry: deps.extensionRegistry,
+			disabledTools: deps.disabledTools,
+			getSessionKey: () => deps.getCurrentContext()?.sessionKey,
+			hookRunner: deps.hookRunner,
+			toolExecutorConfig: deps.toolExecutorConfig
+		}),
+		new MemoryToolProvider({
+			getMemoryManager: deps.getMemoryManager,
+			disabledTools: deps.disabledTools,
+			getSessionKey: () => deps.getCurrentContext()?.sessionKey,
+			hookRunner: deps.hookRunner,
+			toolExecutorConfig: deps.toolExecutorConfig
+		})
+	];
+	if (deps.endpointTools) providers.push(new EndpointToolProvider({
+		runtime: deps.endpointTools,
+		getCurrentContext: deps.getCurrentContext
+	}));
+	return createExternalToolGatewayTools(providers);
+}
+//#endregion
+export { EXTERNAL_TOOL_NAMES, ExternalToolService, createDefaultExternalToolGatewayTools };