@xopcai/xopc 0.0.369 → 0.0.370

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

@@ -1,8 +1,13 @@
-import { COMPUTER_CONTROL_TOOL, init_src } from "../../../packages/computer-control-contract/src/index.js";
-import { BROWSER_CONTROL_ENDPOINT_TOOL_NAME } from "../../../packages/browser-control-contract/src/index.js";
-import { executeExternalOperation } from "../../capabilities/runtime/external-operations.js";
+import { init_src } from "../../../packages/computer-control-contract/src/index.js";
+import "../../../packages/browser-control-contract/src/index.js";
+import { ExternalEffectNotAppliedError, executeExternalOperation } from "../../capabilities/runtime/external-operations.js";
 import { canonicalCapabilityJson } from "../../capabilities/runtime/dispatcher.js";
 import { externalToolRef, parseExternalToolRef } from "./refs.js";
+import { processLocationTask } from "../../endpoint-tools/location-task.js";
+import { projectDeviceReading } from "../../endpoint-tools/result-projector.js";
+import { getEndpointDeviceSettings } from "../../storage/sqlite/endpoint-device-settings-repository.js";
+import { DeviceTargetResolver } from "../../endpoint-tools/target-resolver.js";
+import { EndpointToolExecutionError } from "../../endpoint-tools/invocation-service.js";
 import { createHash } from "node:crypto";
 //#region src/agent/external-tools/endpoint-provider.ts
 init_src();
@@ -17,15 +22,16 @@ var EndpointToolProvider = class {
 		this.deps = deps;
 	}
 	async search(_query) {
-		const endpoint = this.currentEndpoint();
-		if (!endpoint) return [];
-		return endpoint.tools.filter(({ descriptor }) => ![BROWSER_CONTROL_ENDPOINT_TOOL_NAME, COMPUTER_CONTROL_TOOL].includes(descriptor.name)).map(({ descriptor }) => ({
+		const context = this.deps.getCurrentContext();
+		if (!context) return [];
+		const resolver = this.targetResolver();
+		return resolver.candidates(context.conversationId, context.origin).flatMap((endpoint) => endpoint.tools.filter(({ descriptor }) => !["browser.control", "desktop.computer.control"].includes(descriptor.name) && resolver.resolve(context.conversationId, context.origin, endpoint.endpointId, descriptor.name)).map(({ descriptor }) => ({
 			toolRef: externalToolRef(this.source, endpoint.endpointId, descriptor.name),
 			source: this.source,
 			namespace: endpoint.endpointId,
 			title: descriptor.title,
-			summary: `${descriptor.description} (${endpoint.displayName})`
-		}));
+			summary: `${descriptor.description} (${getEndpointDeviceSettings(endpoint.principalId)?.nickname ?? endpoint.displayName})`
+		})));
 	}
 	async describe(toolRef) {
 		const resolved = this.resolve(toolRef);
@@ -36,77 +42,163 @@ var EndpointToolProvider = class {
 			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
+			description: `${resolved.tool.descriptor.description} Device: ${JSON.stringify(resolved.displayName)}; endpoint: ${JSON.stringify(resolved.endpointId)}. Do not substitute another device.${resolved.approvedArguments ? ` Single-call cross-device consent requires exactly these arguments: ${JSON.stringify(resolved.approvedArguments)}.` : ""}`,
+			inputSchema: resolved.tool.descriptor.inputSchema,
+			outputSchema: {
+				type: "object",
+				properties: { content: resolved.tool.descriptor.name.endsWith(".device.get_location") ? {
+					type: "array",
+					minItems: 1,
+					maxItems: 1,
+					items: {
+						type: "object",
+						required: ["type", "value"],
+						properties: {
+							type: { const: "json" },
+							value: {
+								type: "object",
+								required: [
+									"source",
+									"purpose",
+									"data"
+								]
+							}
+						}
+					}
+				} : resolved.tool.descriptor.outputSchema },
+				required: ["content"],
+				additionalProperties: false
+			},
+			contractRevision: resolved.contractRevision,
+			annotations: {
+				readOnlyHint: resolved.tool.descriptor.effect === "read",
+				destructiveHint: resolved.tool.descriptor.effect === "destructive",
+				idempotentHint: resolved.tool.descriptor.idempotent
+			},
+			batchRead: resolved.tool.descriptor.effect === "read" && resolved.tool.descriptor.sensitivity === "public" && !resolved.tool.descriptor.requiresForeground && resolved.tool.descriptor.confirmation === "never" && resolved.tool.descriptor.requiredPermissions.length === 0
 		};
 	}
 	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 invoke = () => 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?.({
+		const revision = context.contractRevision ?? resolved.contractRevision;
+		let grantLease;
+		const invoke = () => {
+			context.signal?.throwIfAborted();
+			if (this.resolve(toolRef)?.contractRevision !== revision) throw new ExternalEffectNotAppliedError("Endpoint connection, binding or tool contract changed");
+			const turn = this.deps.getCurrentContext();
+			const grant = this.deps.runtime.grants?.find(turn.conversationId, turn.origin, resolved.endpointId, resolved.tool.descriptor.name);
+			if (grant) grantLease = this.deps.runtime.grants.reserve(grant.id, args);
+			const signal = grantLease ? AbortSignal.any([grantLease.signal, context.signal ?? new AbortController().signal]) : context.signal;
+			return this.deps.runtime.invocations.invoke({
+				endpointId: resolved.endpointId,
+				toolCallId: context.toolCallId,
+				toolName: resolved.tool.descriptor.name,
+				arguments: args,
+				descriptorRevision: resolved.tool.revision,
+				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 }
+						}
+					});
+				}
+			}).catch((error) => {
+				if (resolved.tool.descriptor.confirmation === "always" && error instanceof EndpointToolExecutionError && error.code === "USER_DENIED") throw new ExternalEffectNotAppliedError(error.message, { cause: error });
+				throw error;
+			});
+		};
+		try {
+			const result = resolved.tool.descriptor.effect === "read" ? await invoke() : await executeExternalOperation({
+				principalId: resolved.principalId,
+				capabilityId: toolRef,
+				idempotencyKey: createHash("sha256").update(`${this.deps.getCurrentContext()?.conversationId}:${context.toolCallId}`).digest("hex"),
+				requestDigest: createHash("sha256").update(canonicalCapabilityJson(args)).digest("hex"),
+				descriptorDigest: resolved.tool.revision,
+				surface: "agent",
+				recovery: "manual"
+			}, invoke);
+			if (resolved.tool.descriptor.name.endsWith(".device.get_location")) {
+				const signal = grantLease ? AbortSignal.any([grantLease.signal, context.signal ?? new AbortController().signal]) : context.signal;
+				const summary = await processLocationTask(args, result.content, {
+					endpointId: resolved.endpointId,
+					principalId: resolved.principalId
+				}, signal);
+				signal?.throwIfAborted();
+				const current = this.deps.runtime.registry.get(resolved.endpointId);
+				if (!current || current.connectionId !== resolved.connectionId || current.availability !== "foreground" || this.deps.runtime.registry.getTool(resolved.endpointId, resolved.tool.descriptor.name)?.revision !== resolved.tool.revision) throw new ExternalEffectNotAppliedError("Location device connection or capability changed");
+				return {
 					content: [{
 						type: "text",
-						text: progress.message ?? "Endpoint tool is running"
+						text: JSON.stringify(summary)
 					}],
+					structuredContent: JSON.parse(JSON.stringify({ content: [{
+						type: "json",
+						value: summary
+					}] })),
 					details: {
 						endpointId: resolved.endpointId,
-						...progress.percent === void 0 ? {} : { percent: progress.percent }
+						endpointToolName: resolved.tool.descriptor.name,
+						deviceObservation: summary
 					}
-				});
-			}
-		});
-		const result = resolved.tool.descriptor.effect === "read" ? await invoke() : await executeExternalOperation({
-			principalId: resolved.principalId,
-			capabilityId: toolRef,
-			idempotencyKey: createHash("sha256").update(`${this.deps.getCurrentContext()?.conversationId}:${context.toolCallId}`).digest("hex"),
-			requestDigest: createHash("sha256").update(canonicalCapabilityJson(args)).digest("hex"),
-			descriptorDigest: resolved.tool.revision,
-			surface: "agent",
-			recovery: "manual"
-		}, invoke);
-		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,
-				endpointSensitivity: resolved.tool.descriptor.sensitivity,
-				...result.details ?? {},
-				...files.length === 0 ? {} : { endpointFiles: files }
+				};
 			}
-		};
+			const observation = projectDeviceReading(resolved.tool.descriptor.name, resolved.endpointId, resolved.principalId, result.content, Date.now(), args);
+			const files = result.content.filter((item) => item.type === "file");
+			return {
+				content: observation ? [{
+					type: "text",
+					text: JSON.stringify(observation)
+				}] : result.content.map((item) => ({
+					type: "text",
+					text: contentText(item)
+				})),
+				structuredContent: JSON.parse(JSON.stringify({ content: result.content })),
+				details: {
+					...observation ? { deviceObservation: observation } : {},
+					endpointId: resolved.endpointId,
+					endpointToolName: resolved.tool.descriptor.name,
+					endpointSensitivity: resolved.tool.descriptor.sensitivity,
+					...result.details ?? {},
+					...files.length === 0 ? {} : { endpointFiles: files }
+				}
+			};
+		} finally {
+			grantLease?.complete();
+		}
 	}
-	currentEndpoint() {
-		const context = this.deps.getCurrentContext();
-		if (!context) return void 0;
-		if (this.deps.runtime.bindings.get(context.conversationId)) return this.deps.runtime.bindings.resolve(context.conversationId);
-		const origin = context.origin;
-		if (origin?.type !== "endpoint") return void 0;
-		return this.deps.runtime.registry.get(origin.endpointId);
+	targetResolver() {
+		return new DeviceTargetResolver(this.deps.runtime.registry, this.deps.runtime.bindings, this.deps.runtime.grants);
 	}
 	resolve(toolRef) {
 		const parsed = parseExternalToolRef(toolRef, this.source);
 		if (!parsed) return void 0;
-		const endpoint = this.currentEndpoint();
+		const context = this.deps.getCurrentContext();
+		if (!context) return void 0;
+		const endpoint = this.targetResolver().resolve(context.conversationId, context.origin, parsed.namespace, parsed.toolName);
 		if (!endpoint || endpoint.endpointId !== parsed.namespace) return void 0;
 		const tool = this.deps.runtime.registry.getTool(endpoint.endpointId, parsed.toolName);
 		if (tool && ["browser.control", "desktop.computer.control"].includes(tool.descriptor.name)) return void 0;
 		return tool ? {
+			approvedArguments: this.deps.runtime.grants.find(context.conversationId, context.origin, endpoint.endpointId, parsed.toolName)?.arguments,
+			connectionId: endpoint.connectionId,
 			endpointId: endpoint.endpointId,
 			principalId: endpoint.principalId,
-			displayName: endpoint.displayName,
-			tool
+			displayName: getEndpointDeviceSettings(endpoint.principalId)?.nickname ?? endpoint.displayName,
+			tool,
+			contractRevision: createHash("sha256").update(JSON.stringify([
+				endpoint.principalId,
+				endpoint.connectionId,
+				tool.revision,
+				this.deps.runtime.bindings.get(this.deps.getCurrentContext().conversationId)?.boundAt ?? null,
+				this.deps.runtime.grants?.find(context.conversationId, context.origin, endpoint.endpointId, parsed.toolName)?.id ?? null
+			])).digest("hex")
 		} : void 0;
 	}
 };

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

@@ -1,5 +1,6 @@
 import { externalToolRef, parseExternalToolRef } from "./refs.js";
 import { executeToolWithProtection } from "../tools/executor.js";
+import { getXopcToolMetadata } from "../embedded/tool-metadata.js";
 //#region src/agent/external-tools/extension-provider.ts
 function toolSummary(tool) {
 	return tool.description || tool.label || tool.name;
@@ -28,6 +29,8 @@ var ExtensionToolProvider = class {
 		if (!resolved) return void 0;
 		const { extensionId, tool } = resolved;
 		const summary = toolSummary(tool);
+		const metadata = getXopcToolMetadata(tool);
+		if (metadata?.exposure === "hidden") return void 0;
 		return {
 			toolRef,
 			source: this.source,
@@ -35,7 +38,10 @@ var ExtensionToolProvider = class {
 			title: tool.label || tool.name,
 			summary,
 			description: summary,
-			inputSchema: tool.parameters
+			inputSchema: tool.parameters,
+			outputSchema: metadata?.outputSchema,
+			annotations: metadata?.annotations,
+			exposure: metadata?.exposure
 		};
 	}
 	async execute(toolRef, args, _approvalId, context) {
@@ -50,6 +56,7 @@ var ExtensionToolProvider = class {
 			if (!hook.allowed) throw new Error(hook.reason ?? "Extension tool call blocked by policy hook.");
 			executionArgs = hook.params ?? args;
 		}
+		context.validateArguments?.(executionArgs);
 		return executeToolWithProtection(resolved.tool, context.toolCallId, executionArgs, context.signal, context.onUpdate, this.deps.toolExecutorConfig);
 	}
 	resolve(toolRef) {

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

@@ -9,4 +9,4 @@ export declare const EXTERNAL_TOOL_NAMES: {
     readonly requireConnection: "xopc_require_connection";
     readonly updateConnectionObjective: "xopc_update_connection_objective";
 };
-export declare function createExternalToolGatewayTools(providers: ExternalToolProvider[], getContext?: () => ExternalToolTurnContext | null, getConfig?: () => Config | undefined): AgentTool[];
+export declare function createExternalToolGatewayTools(providers: ExternalToolProvider[], getContext?: () => ExternalToolTurnContext | null, getConfig?: () => Config | undefined, getExecutionConversationId?: () => string | undefined, nativeSources?: readonly import('./types.js').ExternalToolSource[], executorConfig?: Partial<import('../tools/executor.js').ToolExecutorConfig>): AgentTool[];

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

@@ -8,11 +8,12 @@ import { init_session_repository } from "../../storage/sqlite/session-repository
 import { listConnectorInstances } from "../../connectors/instances.js";
 import { connectorPrincipalForSession } from "../../connectors/principal.js";
 import { parseExternalToolRef } from "./refs.js";
+import { setXopcToolMetadata } from "../embedded/tool-metadata.js";
 import { getStoreConnectorInstallPlan, parseStoreConnectorCandidateRef, searchStoreConnectorInstallCandidates } from "../../capabilities/store-connector.js";
 import { connectionCandidates, resolveConnectionCandidate } from "../../connectors/connection-candidates.js";
-import { parsePluginMcpCandidateRef, resolvePluginMcpConnectionCandidate } from "../../extensions/agent-plugins/connection.js";
 import { ExternalToolService } from "./service.js";
 import { EXTERNAL_TOOL_SOURCES } from "./types.js";
+import { bindExternalToolRegistry } from "./tool-registry.js";
 import { Type } from "@sinclair/typebox";
 //#region src/agent/external-tools/gateway-tools.ts
 init_connector_repository();
@@ -60,17 +61,28 @@ function textResult(value, details = {}) {
 		details
 	};
 }
-function createExternalToolGatewayTools(providers, getContext, getConfig) {
+function createExternalToolGatewayTools(providers, getContext, getConfig, getExecutionConversationId, nativeSources = [], executorConfig) {
 	const service = new ExternalToolService(providers);
+	const legacySources = EXTERNAL_TOOL_SOURCES.filter((source) => !nativeSources.includes(source));
+	const assertLegacyRef = (ref) => {
+		if (nativeSources.some((source) => ref.startsWith(`${source}:`))) throw new Error("Use tool_search to load this native tool, then call it directly.");
+	};
 	const searchTool = {
 		name: EXTERNAL_TOOL_NAMES.search,
 		label: "🔎 External Tool Search",
-		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 executable tools, connection candidates, or reviewed Store install candidates. Call xopc_tool_describe before executing a tool. When no executable tool exists but a connection or install candidate is returned, use xopc_require_connection instead of falling back to browser automation. If a source-filtered search finds no relevant tools, retry without sources before concluding a capability is unavailable.`,
+		description: `Search external tools from these sources: ${legacySources.join(", ")}.${nativeSources.length ? ` Use tool_search for native ${nativeSources.join(", ")} tools.` : ""} 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 executable tools, connection candidates, or reviewed Store install candidates. Call xopc_tool_describe before executing a tool. When no executable tool exists but a connection or install candidate is returned, use xopc_require_connection instead of falling back to browser automation. If a source-filtered search finds no relevant tools, retry without sources before concluding a capability is unavailable.`,
 		parameters: ToolSearchSchema,
 		async execute(_toolCallId, params) {
 			const selectedSources = new Set(params.sources ?? []);
 			const excludedSources = selectedSources.size ? EXTERNAL_TOOL_SOURCES.filter((source) => !selectedSources.has(source)) : [];
-			const result = await service.search(params);
+			if (params.sources?.length && params.sources.every((source) => nativeSources.includes(source))) return textResult({
+				tools: [],
+				instruction: "Use tool_search for native tools."
+			});
+			const result = await service.search({
+				...params,
+				sources: (params.sources?.length ? params.sources : legacySources).filter((source) => !nativeSources.includes(source))
+			});
 			const candidates = [...result.connectionCandidates, ...connectionCandidates(params.query)].filter((candidate, index, all) => all.findIndex((item) => item.candidateRef === candidate.candidateRef) === index);
 			let installCandidates = [];
 			let installCatalogError;
@@ -101,6 +113,7 @@ function createExternalToolGatewayTools(providers, getContext, getConfig) {
 		description: "Load exact contracts for up to three external tools returned by xopc_tool_search.",
 		parameters: ToolDescribeSchema,
 		async execute(_toolCallId, params) {
+			params.toolRefs.forEach(assertLegacyRef);
 			const result = await service.describe(params.toolRefs);
 			return textResult({
 				...result,
@@ -114,7 +127,7 @@ function createExternalToolGatewayTools(providers, getContext, getConfig) {
 		description: "Execute one external tool using its exact reference, contract revision, and validated arguments.",
 		parameters: ToolExecuteSchema,
 		async execute(toolCallId, params, signal, onUpdate) {
-			const conversationId = getContext?.()?.conversationId;
+			const conversationId = getExecutionConversationId?.() ?? getContext?.()?.conversationId;
 			const request = conversationId ? personalRequestForExecution(conversationId) : void 0;
 			if (!request && conversationId && isXopcDatabaseOpen() && getSessionMetadata(conversationId)?.customData?.personalReadRequestId) throw new Error("Personal request is no longer active");
 			if (request) {
@@ -161,6 +174,17 @@ function createExternalToolGatewayTools(providers, getContext, getConfig) {
 			};
 		}
 	};
+	const nativeExecute = executeTool.execute.bind(executeTool);
+	executeTool.execute = async (id, params, signal, update) => {
+		assertLegacyRef(params.toolRef);
+		return nativeExecute(id, params, signal, update);
+	};
+	bindExternalToolRegistry(executeTool, {
+		service,
+		nativeSources,
+		execute: nativeExecute,
+		executorConfig
+	});
 	const requireSchema = Type.Object({
 		requirements: Type.Array(Type.Object({
 			candidateRef: Type.String(),
@@ -203,13 +227,11 @@ function createExternalToolGatewayTools(providers, getContext, getConfig) {
 			if (!principal.isLocalOwner) throw new Error("Connection recovery is available in the owner chat.");
 			const selected = connectionBindings(context.conversationId);
 			if (params.requirements.every((item) => {
-				const pluginTarget = parsePluginMcpCandidateRef(item.candidateRef);
 				return selected.some((need) => {
 					if (need.target.type === "connector") return need.target.connectorId === item.candidateRef && Boolean(need.connectionId) && (!item.accountId || item.accountId === need.accountId) && (!item.accountSelector || item.accountSelector === need.accountSelector) && listConnectorConnections({
 						principalId: principal.principalId,
 						connectorId: need.target.connectorId
 					}).some((connection) => connection.id === need.connectionId && connection.status === "active");
-					if (need.target.type === "plugin-mcp") return Boolean(pluginTarget && need.target.pluginId === pluginTarget.pluginId && need.target.serverName === pluginTarget.serverName && need.connectionId === need.target.serverId);
 					const storeTarget = parseStoreConnectorCandidateRef(item.candidateRef);
 					return Boolean(storeTarget && need.target.packageName === storeTarget.packageName && need.target.version === storeTarget.version && need.connectionId);
 				});
@@ -242,7 +264,7 @@ function createExternalToolGatewayTools(providers, getContext, getConfig) {
 						},
 						label: plan.definition.displayName,
 						capabilities: plan.definition.capabilities
-					} : resolvePluginMcpConnectionCandidate(item.candidateRef) ?? resolveConnectionCandidate(item.candidateRef);
+					} : resolveConnectionCandidate(item.candidateRef);
 					if (item.accountId && need.target.type !== "connector") throw new Error("This install candidate does not support account selection.");
 					if (item.accountId && need.target.type === "connector" && !listConnectorConnections({
 						principalId: principal.principalId,
@@ -267,24 +289,25 @@ function createExternalToolGatewayTools(providers, getContext, getConfig) {
 			maxLength: 4e3
 		}))
 	});
+	const reviseTool = {
+		name: EXTERNAL_TOOL_NAMES.updateConnectionObjective,
+		label: "Update waiting objective",
+		parameters: reviseSchema,
+		description: "Use when the user supplements or explicitly cancels the objective waiting for a connection. Update with the complete revised objective including the requested time range. For unrelated work leave the waiting objective unchanged. Cancellation does not disconnect the account.",
+		async execute(_id, params) {
+			const context = getContext?.();
+			if (!context) throw new Error("No active conversation.");
+			if (params.action === "update" && !params.objective) throw new Error("The revised objective is required.");
+			reviseCurrentConnectionObjective(context.conversationId, params.action === "update" ? params.objective : void 0);
+			return textResult({ status: params.action === "update" ? "updated" : "cancelled" });
+		}
+	};
 	return [
 		searchTool,
 		describeTool,
 		executeTool,
-		requireTool,
-		{
-			name: EXTERNAL_TOOL_NAMES.updateConnectionObjective,
-			label: "Update waiting objective",
-			parameters: reviseSchema,
-			description: "Use when the user supplements or explicitly cancels the objective waiting for a connection. Update with the complete revised objective including the requested time range. For unrelated work leave the waiting objective unchanged. Cancellation does not disconnect the account.",
-			async execute(_id, params) {
-				const context = getContext?.();
-				if (!context) throw new Error("No active conversation.");
-				if (params.action === "update" && !params.objective) throw new Error("The revised objective is required.");
-				reviseCurrentConnectionObjective(context.conversationId, params.action === "update" ? params.objective : void 0);
-				return textResult({ status: params.action === "update" ? "updated" : "cancelled" });
-			}
-		}
+		setXopcToolMetadata(requireTool, { exposure: "model-only" }),
+		setXopcToolMetadata(reviseTool, { exposure: "model-only" })
 	];
 }
 //#endregion

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

@@ -1,28 +1,24 @@
 import { resolveEffectiveAgentConfigForAgent, resolveEffectiveAgentConfigForSession } from "../../config/agent-profile.js";
+import { getEmbeddedExecutionSession } from "../embedded/execution-context.js";
+import { parseExternalToolRef } from "./refs.js";
 import { CliToolProvider } from "./cliProvider.js";
 import { ComposioToolProvider } from "./composio-provider.js";
 import { ExtensionToolProvider } from "./extension-provider.js";
 import { ExternalToolService } from "./service.js";
+import { getExternalToolRegistry } from "./tool-registry.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";
 import { withExternalReadPolicy } from "./read-policy.js";
 //#region src/agent/external-tools/index.ts
 function createDefaultExternalToolGatewayTools(deps) {
+	const getConversationId = () => getEmbeddedExecutionSession() ?? deps.getCurrentContext()?.conversationId;
 	const providers = [
 		new CliToolProvider({
 			getConfig: deps.getConfig,
 			getCurrentContext: deps.getCurrentContext,
 			agentId: deps.agentId
 		}),
-		new McpToolProvider({
-			workspace: deps.workspace,
-			getConfig: deps.getConfig,
-			getConversationId: () => deps.getCurrentContext()?.conversationId,
-			agentId: deps.agentId,
-			hookRunner: deps.hookRunner
-		}),
 		new ComposioToolProvider({
 			getConfig: deps.getConfig,
 			getCurrentContext: deps.getCurrentContext,
@@ -32,14 +28,14 @@ function createDefaultExternalToolGatewayTools(deps) {
 		new ExtensionToolProvider({
 			registry: deps.extensionRegistry,
 			disabledTools: deps.disabledTools,
-			getConversationId: () => deps.getCurrentContext()?.conversationId,
+			getConversationId,
 			hookRunner: deps.hookRunner,
 			toolExecutorConfig: deps.toolExecutorConfig
 		}),
 		new MemoryToolProvider({
 			getMemoryManager: deps.getMemoryManager,
 			disabledTools: deps.disabledTools,
-			getConversationId: () => deps.getCurrentContext()?.conversationId,
+			getConversationId,
 			canAccess: deps.canAccessMemory,
 			hookRunner: deps.hookRunner,
 			toolExecutorConfig: deps.toolExecutorConfig
@@ -47,13 +43,49 @@ function createDefaultExternalToolGatewayTools(deps) {
 	];
 	if (deps.endpointTools) providers.push(new EndpointToolProvider({
 		runtime: deps.endpointTools,
-		getCurrentContext: deps.getCurrentContext
+		getCurrentContext: () => {
+			const conversationId = getConversationId();
+			if (!conversationId) return null;
+			const context = deps.getCurrentContext();
+			return context?.conversationId === conversationId ? context : {
+				conversationId,
+				channel: "internal",
+				chatId: conversationId,
+				origin: {
+					type: "system",
+					source: "internal"
+				}
+			};
+		}
 	}));
-	return createExternalToolGatewayTools(providers.map((provider) => withExternalReadPolicy(provider, (toolRef) => {
+	const tools = createExternalToolGatewayTools(providers.map((provider) => withExternalReadPolicy(provider, (toolRef) => {
 		if (!deps.getConfig()) return void 0;
-		const conversationId = deps.getCurrentContext()?.conversationId;
+		const conversationId = getConversationId();
 		return (conversationId ? resolveEffectiveAgentConfigForSession(conversationId) : deps.agentId ? resolveEffectiveAgentConfigForAgent(deps.agentId) : resolveEffectiveAgentConfigForSession(void 0)).config.tools[toolRef];
-	})), deps.getCurrentContext, deps.getConfig);
+	})), deps.getCurrentContext, deps.getConfig, getConversationId, [
+		"endpoint",
+		"extension",
+		"memory"
+	], deps.toolExecutorConfig);
+	const registry = getExternalToolRegistry(tools);
+	if (registry && deps.endpointTools) {
+		const endpoints = deps.endpointTools;
+		registry.subscribeInvalidation = (conversationId, ref, listener) => {
+			const parsed = parseExternalToolRef(ref, "endpoint");
+			if (!parsed) return () => {};
+			const releaseEndpoint = endpoints.registry.onChange((id) => {
+				if (id === parsed?.namespace) listener();
+			});
+			const releaseBinding = endpoints.bindings.onChange((id) => {
+				if (id === conversationId) listener();
+			});
+			return () => {
+				releaseEndpoint();
+				releaseBinding();
+			};
+		};
+	}
+	return tools;
 }
 //#endregion
 export { EXTERNAL_TOOL_NAMES, ExternalToolService, createDefaultExternalToolGatewayTools };

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

@@ -1,5 +1,6 @@
 import { externalToolRef, parseExternalToolRef } from "./refs.js";
 import { executeToolWithProtection } from "../tools/executor.js";
+import { getXopcToolMetadata } from "../embedded/tool-metadata.js";
 //#region src/agent/external-tools/memory-provider.ts
 function toolSummary(tool) {
 	return tool.description || tool.label || tool.name;
@@ -22,6 +23,8 @@ var MemoryToolProvider = class {
 		const resolved = this.resolve(toolRef);
 		if (!resolved) return void 0;
 		const summary = toolSummary(resolved.tool);
+		const metadata = getXopcToolMetadata(resolved.tool);
+		if (metadata?.exposure === "hidden") return void 0;
 		return {
 			toolRef,
 			source: this.source,
@@ -29,7 +32,10 @@ var MemoryToolProvider = class {
 			title: resolved.tool.label || resolved.tool.name,
 			summary,
 			description: summary,
-			inputSchema: resolved.tool.parameters
+			inputSchema: resolved.tool.parameters,
+			outputSchema: metadata?.outputSchema,
+			annotations: metadata?.annotations,
+			exposure: metadata?.exposure
 		};
 	}
 	async execute(toolRef, args, _approvalId, context) {
@@ -41,6 +47,7 @@ var MemoryToolProvider = class {
 			if (!hook.allowed) throw new Error(hook.reason ?? "Memory provider tool call blocked by policy hook.");
 			executionArgs = hook.params ?? args;
 		}
+		context.validateArguments?.(executionArgs);
 		return executeToolWithProtection(resolved.tool, context.toolCallId, executionArgs, context.signal, context.onUpdate, this.deps.toolExecutorConfig);
 	}
 	entries() {

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

@@ -4,6 +4,7 @@ function withExternalReadPolicy(provider, getPolicy) {
 	return {
 		source: provider.source,
 		search: (query) => provider.search(query),
+		...provider.connectionCandidates ? { connectionCandidates: provider.connectionCandidates.bind(provider) } : {},
 		describe: async (ref) => {
 			const descriptor = await provider.describe(ref);
 			if (!descriptor) return void 0;
@@ -11,7 +12,7 @@ function withExternalReadPolicy(provider, getPolicy) {
 			if (policy?.mode === "deny") return void 0;
 			return {
 				...descriptor,
-				batchRead: policy?.readOnly ?? descriptor.batchRead
+				batchRead: provider.source === "endpoint" ? descriptor.batchRead === true && policy?.readOnly !== false : policy?.readOnly ?? descriptor.batchRead
 			};
 		},
 		execute: (ref, args, approval, context) => provider.execute(ref, args, approval, context)

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

@@ -4,6 +4,8 @@ export declare class ExternalToolService {
     private readonly providerBySource;
     private readonly ajv;
     constructor(providers: ExternalToolProvider[]);
+    /** Materialize an authorized local directory without keyword ranking or model round trips. */
+    catalog(sources: readonly ExternalToolSource[]): Promise<VersionedExternalToolDescriptor[]>;
     search(params: {
         query: string;
         sources?: ExternalToolSource[];

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

@@ -28,7 +28,11 @@ function descriptorRevision(descriptor) {
 		toolRef: descriptor.toolRef,
 		description: descriptor.description,
 		inputSchema: descriptor.inputSchema,
-		batchRead: descriptor.batchRead === true
+		outputSchema: descriptor.outputSchema,
+		annotations: descriptor.annotations,
+		batchRead: descriptor.batchRead === true,
+		contractRevision: descriptor.contractRevision,
+		exposure: descriptor.exposure
 	})).digest("hex").slice(0, 16);
 }
 function versionDescriptor(descriptor) {
@@ -48,6 +52,17 @@ var ExternalToolService = class {
 	constructor(providers) {
 		this.providerBySource = new Map(providers.map((provider) => [provider.source, provider]));
 	}
+	/** Materialize an authorized local directory without keyword ranking or model round trips. */
+	async catalog(sources) {
+		const descriptors = [];
+		for (const source of sources) {
+			const provider = this.providerBySource.get(source);
+			if (!provider) continue;
+			const refs = [...new Set((await provider.search("")).map((hit) => hit.toolRef))];
+			for (const ref of refs) descriptors.push(...(await this.describe([ref])).tools);
+		}
+		return descriptors;
+	}
 	async search(params) {
 		const selected = params.sources?.length ? params.sources.map((source) => this.providerBySource.get(source)).filter((provider) => provider !== void 0) : [...this.providerBySource.values()];
 		const settled = await Promise.allSettled(selected.map(async (provider) => ({
@@ -132,8 +147,15 @@ var ExternalToolService = class {
 		} catch (error) {
 			throw new Error(`Tool contract is invalid: ${params.toolRef}`, { cause: error });
 		}
-		if (!validate(args)) throw new Error(`Arguments do not match ${params.toolRef}: ${this.ajv.errorsText(validate.errors)}`);
-		return provider.execute(params.toolRef, args, params.approvalId, params.context);
+		const validateArguments = (input) => {
+			if (!validate(input)) throw new Error(`Arguments do not match ${params.toolRef}: ${this.ajv.errorsText(validate.errors)}`);
+		};
+		validateArguments(args);
+		return provider.execute(params.toolRef, args, params.approvalId, {
+			...params.context,
+			contractRevision: current.contractRevision,
+			validateArguments
+		});
 	}
 	providerForRef(toolRef) {
 		const separator = toolRef.indexOf(":");