@xopcai/xopc 0.0.188 → 0.0.189

package/dist/src/agent/session/session-state-bag.d.ts

@@ -16,7 +16,7 @@
  * `sessionEventUnsubscribers`) are still cleared via `disposeSession`, but they
  * are NOT subject to TTL — sweeping them would race with their owners.
  */
-export type WebchatSsePublisher = (event: {
+export type WebchatStreamPublisher = (event: {
     type: string;
     [key: string]: unknown;
 }) => void;
@@ -34,7 +34,7 @@ export interface SessionStateBagOptions {
     now?: () => number;
 }
 export declare class SessionStateBag {
-    /** Webchat SSE publisher (register/unregister + TTL fallback). */
+    /** Webchat run publisher (register/unregister + TTL fallback). */
     private readonly webchatPublishers;
     /** Last assistant plain text (TTL + LRU). */
     private readonly lastAssistantText;
@@ -51,9 +51,9 @@ export declare class SessionStateBag {
     private readonly now;
     private readonly sweepTimer;
     constructor(opts?: SessionStateBagOptions);
-    registerWebchatPublisher(sessionKey: string, publisher: WebchatSsePublisher): void;
+    registerWebchatPublisher(sessionKey: string, publisher: WebchatStreamPublisher): void;
     unregisterWebchatPublisher(sessionKey: string): void;
-    getWebchatPublisher(sessionKey: string): WebchatSsePublisher | undefined;
+    getWebchatPublisher(sessionKey: string): WebchatStreamPublisher | undefined;
     setLastAssistantText(sessionKey: string, text: string): void;
     getLastAssistantText(sessionKey: string): string | undefined;
     appendEmbeddedStreamText(sessionKey: string, chunk: string): string;

package/dist/src/agent/session/session-state-bag.js

@@ -7,7 +7,7 @@ const DEFAULT_TTL_MS = 3600 * 1e3;
 const DEFAULT_SWEEP_INTERVAL_MS = 600 * 1e3;
 const DEFAULT_MAX_ENTRIES = 5e3;
 var SessionStateBag = class {
-	/** Webchat SSE publisher (register/unregister + TTL fallback). */
+	/** Webchat run publisher (register/unregister + TTL fallback). */
 	webchatPublishers = /* @__PURE__ */ new Map();
 	/** Last assistant plain text (TTL + LRU). */
 	lastAssistantText = /* @__PURE__ */ new Map();

package/dist/src/agent/streaming/reasoning-visibility.d.ts

@@ -0,0 +1,6 @@
+import type { ReasoningLevel } from '../transcript/thinking-types.js';
+export type AgentStreamEvent = {
+    type: string;
+    [key: string]: unknown;
+};
+export declare function applyReasoningVisibility(event: AgentStreamEvent, reasoningLevel: ReasoningLevel): AgentStreamEvent | null;

package/dist/src/agent/streaming/{reasoning-visibility-sse.js → reasoning-visibility.js}

@@ -1,8 +1,5 @@
-//#region src/agent/streaming/reasoning-visibility-sse.ts
-/**
-* @returns `null` to drop the event; unchanged `event` otherwise.
-*/
-function applyReasoningVisibilityToSseEvent(event, reasoningLevel) {
+//#region src/agent/streaming/reasoning-visibility.ts
+function applyReasoningVisibility(event, reasoningLevel) {
 	if (reasoningLevel !== "off") return event;
 	if (event.type === "thinking") return null;
 	if (event.type === "message_update" && event.assistantMessageEvent?.type === "thinking_delta") return null;
@@ -10,4 +7,4 @@ function applyReasoningVisibilityToSseEvent(event, reasoningLevel) {
 	return event;
 }
 //#endregion
-export { applyReasoningVisibilityToSseEvent };
+export { applyReasoningVisibility };

package/dist/src/agent/tools/factory.d.ts

@@ -9,6 +9,8 @@
 import type { AgentTool } from '@earendil-works/pi-agent-core';
 import type { Model, Api } from '@earendil-works/pi-ai';
 import type { Config } from '../../config/schema.js';
+import type { EndpointToolRuntime } from '../../endpoint-tools/index.js';
+import type { TurnOrigin } from '@xopcai/endpoint-tools-protocol';
 import type { ExtensionRegistry } from '../../extensions/types/index.js';
 import type { MessageBus } from '../../infra/bus/index.js';
 import { type SkillInstallToolOptions, type SkillInstallToolResult, type MarketplaceSkillInstallToolOptions, type MarketplaceSkillInstallToolResult } from './index.js';
@@ -31,7 +33,9 @@ export interface ToolFactoryDeps {
         channel: string;
         chatId: string;
         sessionKey: string;
+        origin: TurnOrigin;
     } | null;
+    endpointTools?: EndpointToolRuntime;
     hookRunner?: import('../../extensions/index.js').ExtensionHookRunner;
     bus: MessageBus;
     toolExecutorConfig?: Partial<ToolExecutorConfig>;

package/dist/src/agent/tools/factory.js

@@ -182,6 +182,7 @@ var AgentToolsFactory = class {
 			workspace,
 			getConfig: () => this.deps.getConfig?.(),
 			getCurrentContext: this.deps.getCurrentContext,
+			endpointTools: this.deps.endpointTools,
 			agentId,
 			extensionRegistry: this.deps.extensionRegistry,
 			disabledTools: disabled,

package/dist/src/automations/domain/types.d.ts

@@ -1,5 +1,6 @@
 import type { WorkflowRunInputEnvelope } from '../../workflows/domain/index.js';
 import type { TaskCommand } from '@xopcai/gateway-contract';
+import type { TurnOrigin } from '@xopcai/endpoint-tools-protocol';
 import type { WorkflowRunServiceLike } from '../../workflows/service/workflow-run-service.types.js';
 export type AutomationSchedule = {
     kind: 'once';
@@ -171,7 +172,7 @@ export interface AutomationDeps {
             applyAutomationModelOverride?: (sessionKey: string, model: string | undefined) => Promise<boolean>;
         };
         turnDispatcher?: {
-            processDirect: (message: string, sessionKey: string, attachments?: unknown[], thinking?: string, options?: {
+            processDirect: (message: string, sessionKey: string, origin: TurnOrigin, attachments?: unknown[], thinking?: string, options?: {
                 signal?: AbortSignal;
                 runId?: string;
                 deadlineAtMs?: number;

package/dist/src/automations/domain/validation.d.ts

@@ -656,6 +656,7 @@ export declare const UpdateAutomationSchema: z.ZodObject<{
             }, z.core.$strip>;
         }, z.core.$strip>], "type">;
     }, z.core.$strict>], "kind">>;
+    description: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     state: z.ZodOptional<z.ZodDefault<z.ZodObject<{
         nextRunAtMs: z.ZodOptional<z.ZodNumber>;
         runningRunId: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
@@ -672,7 +673,6 @@ export declare const UpdateAutomationSchema: z.ZodObject<{
         lastError: z.ZodOptional<z.ZodString>;
         consecutiveFailures: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>>;
-    description: z.ZodOptional<z.ZodOptional<z.ZodString>>;
     trigger: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"manual">;
     }, z.core.$strict>, z.ZodObject<{

package/dist/src/automations/service/action-executor.js

@@ -177,7 +177,10 @@ var AutomationActionExecutor = class {
 				model: action.model
 			}, "Automation model override invalid; using agent default");
 		}
-		const response = await agentService.turnDispatcher.processDirect(buildSafetyInstruction(automation, action.instruction), sessionKey, void 0, void 0, {
+		const response = await agentService.turnDispatcher.processDirect(buildSafetyInstruction(automation, action.instruction), sessionKey, {
+			type: "system",
+			source: "automation"
+		}, void 0, void 0, {
 			signal,
 			runId: run.id,
 			deadlineAtMs

package/dist/src/channels/pairing/pairing-challenge.d.ts

@@ -18,7 +18,7 @@ export type IssuePairingChallengeParams = {
 };
 /**
  * OpenClaw-style pairing: mint or refresh a pending code; notify the user only on new codes.
- * Repeat DMs refresh lastSeenAt and broadcast SSE without re-sending the bot message.
+ * Repeat DMs refresh lastSeenAt and publish realtime status without re-sending the bot message.
  */
 export declare function issuePairingChallenge(params: IssuePairingChallengeParams): Promise<{
     created: boolean;

package/dist/src/channels/pairing/pairing-challenge.js

@@ -4,7 +4,7 @@ import { broadcastPairingEvent } from "./pairing-events.js";
 //#region src/channels/pairing/pairing-challenge.ts
 /**
 * OpenClaw-style pairing: mint or refresh a pending code; notify the user only on new codes.
-* Repeat DMs refresh lastSeenAt and broadcast SSE without re-sending the bot message.
+* Repeat DMs refresh lastSeenAt and publish realtime status without re-sending the bot message.
 */
 async function issuePairingChallenge(params) {
 	const normalizedAccountId = params.accountId.trim().toLowerCase() || "default";

package/dist/src/cli/commands/agent/stream-renderer.js

@@ -28,7 +28,10 @@ function formatToolArgs(args) {
 */
 async function renderStreamToTerminal(agent, message, sessionKey) {
 	const stamped = message.trimStart().startsWith("/") ? message : prependEnvelopeTimestamp(message);
-	const stream = agent.turnDispatcher.processDirectStreaming(stamped, sessionKey);
+	const stream = agent.turnDispatcher.processDirectStreaming(stamped, sessionKey, {
+		type: "system",
+		source: "cli"
+	});
 	let responseText = "";
 	let isFirstToken = true;
 	let isInThinking = false;

package/dist/src/cli/commands/doctor/checks/database-schema.js

@@ -52,7 +52,7 @@ async function checkDatabaseSchema(ctx) {
 		id: "database-schema",
 		label: "Database schema",
 		status: "pass",
-		message: `SQLite schema v${status.dbVersion} (current release v108).`,
+		message: `SQLite schema v${status.dbVersion} (current release v112).`,
 		hints: []
 	};
 }

package/dist/src/cli/commands/extension-marketplace.js

@@ -3,9 +3,9 @@ import { init_loader, loadConfig } from "../../config/loader.js";
 import { downloadExtensionStoreZipBuffer, resolveExtensionZipDownloadUrl, resolveExtensionsStoreBaseUrl, verifyStoreArtifactSha256 } from "../../agent/skills/marketplace/adapters/store/store-api-client.js";
 import { getContextWithOpts } from "../context.js";
 import { getExtensionLockfileManager } from "../../extensions/lockfile.js";
-import { fetchRegistry, findExtension, getExtensionMarketplaceStoreBaseUrl, listExtensions, searchExtensions } from "../../extensions/marketplace.js";
 import { installFromLocal, installFromNpm, peekExtensionManifestFromStoreZip } from "../../extensions/install.js";
 import { commitStagedExtensionInstall, finalizeStagedExtensionInstall, rollbackStagedExtensionInstall, stageExtensionStoreZip } from "../../extensions/install-transaction.js";
+import { fetchRegistry, findExtension, getExtensionMarketplaceStoreBaseUrl, listExtensions, searchExtensions } from "../../extensions/marketplace.js";
 import { colors } from "../utils/colors.js";
 import { validateExtensionPackageDirectory } from "./extension-pack.js";
 import { join, resolve } from "node:path";

package/dist/src/config/rules.js

@@ -93,11 +93,6 @@ const BASE_RELOAD_RULES = [
 		kind: "restart",
 		description: "Host-header origin fallback"
 	},
-	{
-		prefix: "gateway.maxSseConnections",
-		kind: "restart",
-		description: "SSE connection limit"
-	},
 	{
 		prefix: "gateway.channelConnectDeferMode",
 		kind: "restart",

package/dist/src/config/schema.d.ts

@@ -781,8 +781,8 @@ export declare const WorkspaceConfigSchema: z.ZodOptional<z.ZodObject<{
 }, z.core.$strip>>;
 export type WorkspaceConfig = z.infer<typeof WorkspaceConfigSchema>;
 export declare const GatewayBindModeSchema: z.ZodEnum<{
-    auto: "auto";
     custom: "custom";
+    auto: "auto";
     loopback: "loopback";
     lan: "lan";
     tailnet: "tailnet";
@@ -796,8 +796,8 @@ export declare const GatewayWebchatConfigSchema: z.ZodDefault<z.ZodObject<{
 }, z.core.$strip>>;
 export declare const GatewayConfigSchema: z.ZodDefault<z.ZodObject<{
     bind: z.ZodOptional<z.ZodEnum<{
-        auto: "auto";
         custom: "custom";
+        auto: "auto";
         loopback: "loopback";
         lan: "lan";
         tailnet: "tailnet";
@@ -886,7 +886,6 @@ export declare const GatewayConfigSchema: z.ZodDefault<z.ZodObject<{
             off: "off";
         }>>;
     }, z.core.$strip>>>;
-    maxSseConnections: z.ZodOptional<z.ZodNumber>;
     corsOrigins: z.ZodOptional<z.ZodArray<z.ZodString>>;
     publicUrl: z.ZodOptional<z.ZodString>;
     dangerouslyAllowHostHeaderOriginFallback: z.ZodOptional<z.ZodBoolean>;
@@ -1930,8 +1929,8 @@ export declare const ConfigSchema: z.ZodDefault<z.ZodObject<{
     channels: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     gateway: z.ZodDefault<z.ZodObject<{
         bind: z.ZodOptional<z.ZodEnum<{
-            auto: "auto";
             custom: "custom";
+            auto: "auto";
             loopback: "loopback";
             lan: "lan";
             tailnet: "tailnet";
@@ -2020,7 +2019,6 @@ export declare const ConfigSchema: z.ZodDefault<z.ZodObject<{
                 off: "off";
             }>>;
         }, z.core.$strip>>>;
-        maxSseConnections: z.ZodOptional<z.ZodNumber>;
         corsOrigins: z.ZodOptional<z.ZodArray<z.ZodString>>;
         publicUrl: z.ZodOptional<z.ZodString>;
         dangerouslyAllowHostHeaderOriginFallback: z.ZodOptional<z.ZodBoolean>;

package/dist/src/config/schema.js

@@ -465,7 +465,6 @@ activityDetailDefault: z.enum([
 		auth: GatewayAuthSchema.optional(),
 		heartbeat: HeartbeatConfigSchema.optional(),
 		webchat: GatewayWebchatConfigSchema.optional(),
-		maxSseConnections: z.number().optional(),
 		corsOrigins: z.array(z.string()).optional(),
 		/**
 		* Reverse-proxy publicly reachable URL (e.g. `https://gateway.example.com`).
@@ -639,7 +638,6 @@ activityDetailDefault: z.enum([
 			includeSystemPromptSection: false
 		},
 		webchat: { activityDetailDefault: "on" },
-		maxSseConnections: 100,
 		corsOrigins: [],
 		skillsMarketplaceProvider: "store",
 		skillsStoreBaseUrl: "https://store.xopc.ai"
@@ -1042,7 +1040,6 @@ workDiscoveryOnboarding: z.boolean().default(true) }).strict().default({ workDis
 				includeSystemPromptSection: false
 			},
 			webchat: { activityDetailDefault: "on" },
-			maxSseConnections: 100,
 			corsOrigins: [],
 			skillsMarketplaceProvider: "store",
 			skillsStoreBaseUrl: "https://store.xopc.ai"

package/dist/src/config/web-patch.js

@@ -93,7 +93,6 @@ function mergeGatewaySkillsMarketplacePatch(config, patch) {
 			intervalMs: 18e5,
 			includeSystemPromptSection: false
 		},
-		maxSseConnections: 100,
 		corsOrigins: []
 	};
 	if (parsed.data.skillsMarketplaceProvider !== void 0) config.gateway.skillsMarketplaceProvider = parsed.data.skillsMarketplaceProvider.trim();

package/dist/src/endpoint-tools/auth.d.ts

@@ -0,0 +1,20 @@
+import crypto from 'node:crypto';
+import { type EndpointHelloPayload } from '@xopcai/endpoint-tools-protocol';
+import type { EndpointPrincipal } from '../storage/sqlite/index.js';
+export interface EndpointAuthenticatorDeps {
+    getPrincipal(id: string): EndpointPrincipal | undefined;
+    bindEndpoint(endpointId: string, principalId: string, boundAt?: number): boolean;
+    touchPrincipal(id: string, seenAt?: number): void;
+    now?: () => number;
+}
+export declare class EndpointAuthenticationError extends Error {
+}
+export declare function parseEndpointPublicKey(encoded: string): crypto.KeyObject;
+export declare class EndpointAuthenticator {
+    private readonly deps;
+    private readonly usedNonces;
+    private readonly now;
+    constructor(deps: EndpointAuthenticatorDeps);
+    authenticate(payload: EndpointHelloPayload): EndpointPrincipal;
+    private pruneNonces;
+}

package/dist/src/endpoint-tools/auth.js

@@ -0,0 +1,51 @@
+import { endpointHelloSigningPayload } from "../../packages/endpoint-tools-protocol/src/index.js";
+import crypto from "node:crypto";
+//#region src/endpoint-tools/auth.ts
+const MAX_CLOCK_SKEW_MS = 6e4;
+var EndpointAuthenticationError = class extends Error {};
+function parseEndpointPublicKey(encoded) {
+	const key = crypto.createPublicKey({
+		key: Buffer.from(encoded, "base64url"),
+		format: "der",
+		type: "spki"
+	});
+	if (key.asymmetricKeyType !== "ec" || key.asymmetricKeyDetails?.namedCurve !== "prime256v1") throw new Error("Endpoint public key must be ECDSA P-256");
+	return key;
+}
+var EndpointAuthenticator = class {
+	usedNonces = /* @__PURE__ */ new Map();
+	now;
+	constructor(deps) {
+		this.deps = deps;
+		this.now = deps.now ?? Date.now;
+	}
+	authenticate(payload) {
+		const now = this.now();
+		this.pruneNonces(now);
+		if (Math.abs(now - payload.signedAt) > MAX_CLOCK_SKEW_MS) throw new EndpointAuthenticationError("Endpoint signature timestamp is outside the allowed window");
+		const nonceKey = `${payload.principalId}:${payload.nonce}`;
+		if (this.usedNonces.has(nonceKey)) throw new EndpointAuthenticationError("Endpoint hello nonce was already used");
+		const principal = this.deps.getPrincipal(payload.principalId);
+		if (!principal || principal.revokedAt !== void 0) throw new EndpointAuthenticationError("Endpoint principal is unknown or revoked");
+		if (principal.kind !== payload.kind || principal.platform !== payload.platform || principal.displayName !== payload.displayName) throw new EndpointAuthenticationError("Endpoint identity does not match its registered principal");
+		let publicKey;
+		try {
+			publicKey = parseEndpointPublicKey(principal.publicKey);
+		} catch (error) {
+			throw new EndpointAuthenticationError("Endpoint principal public key is invalid", { cause: error });
+		}
+		if (!crypto.verify("sha256", Buffer.from(endpointHelloSigningPayload(payload), "utf8"), {
+			key: publicKey,
+			dsaEncoding: "ieee-p1363"
+		}, Buffer.from(payload.signature, "base64url"))) throw new EndpointAuthenticationError("Endpoint hello signature is invalid");
+		if (!this.deps.bindEndpoint(payload.endpointId, principal.id, now)) throw new EndpointAuthenticationError("Endpoint instance belongs to another principal");
+		this.usedNonces.set(nonceKey, now + MAX_CLOCK_SKEW_MS);
+		this.deps.touchPrincipal(principal.id, now);
+		return principal;
+	}
+	pruneNonces(now) {
+		for (const [key, expiresAt] of this.usedNonces) if (expiresAt <= now) this.usedNonces.delete(key);
+	}
+};
+//#endregion
+export { EndpointAuthenticationError, EndpointAuthenticator, parseEndpointPublicKey };

package/dist/src/endpoint-tools/index.d.ts

@@ -0,0 +1,5 @@
+export { EndpointToolRuntime } from './runtime.js';
+export { EndpointInvocationService, EndpointToolExecutionError, type EndpointInvocationAuditSink, type EndpointInvocationResult, } from './invocation-service.js';
+export { EndpointToolPolicy, EndpointToolPolicyError } from './policy.js';
+export { EndpointRegistry, endpointToolRevision, type EndpointConnectionSnapshot, type RegisteredEndpointTool, } from './registry.js';
+export { EndpointUploadError, EndpointUploadService, ENDPOINT_UPLOAD_MAX_BYTES, type EndpointUploadedFile, type EndpointUploadGrant, } from './upload-service.js';

package/dist/src/endpoint-tools/index.js

@@ -0,0 +1,6 @@
+import { EndpointToolPolicy, EndpointToolPolicyError } from "./policy.js";
+import { EndpointInvocationService, EndpointToolExecutionError } from "./invocation-service.js";
+import { EndpointRegistry, endpointToolRevision } from "./registry.js";
+import { ENDPOINT_UPLOAD_MAX_BYTES, EndpointUploadError, EndpointUploadService } from "./upload-service.js";
+import { EndpointToolRuntime } from "./runtime.js";
+export { ENDPOINT_UPLOAD_MAX_BYTES, EndpointInvocationService, EndpointRegistry, EndpointToolExecutionError, EndpointToolPolicy, EndpointToolPolicyError, EndpointToolRuntime, EndpointUploadError, EndpointUploadService, endpointToolRevision };

package/dist/src/endpoint-tools/invocation-service.d.ts

@@ -0,0 +1,68 @@
+import { type ClientEndpointMessage, type EndpointToolContent, type EndpointToolErrorCode } from '@xopcai/endpoint-tools-protocol';
+import { EndpointRegistry } from './registry.js';
+import { EndpointToolPolicy } from './policy.js';
+import type { EndpointUploadService } from './upload-service.js';
+type ToolClientMessage = Exclude<ClientEndpointMessage, {
+    type: `endpoint.${string}`;
+}>;
+export interface EndpointInvocationAuditSink {
+    started(params: {
+        id: string;
+        principalId: string;
+        endpointId: string;
+        toolCallId: string;
+        toolName: string;
+        effect: 'read' | 'write' | 'destructive';
+        confirmationRequired: boolean;
+        argumentsSha256: string;
+        startedAt: number;
+    }): void;
+    finished(params: {
+        id: string;
+        status: 'succeeded' | 'failed';
+        errorCode?: EndpointToolErrorCode;
+        errorMessage?: string;
+        completedAt: number;
+    }): void;
+}
+export interface EndpointInvocationServiceOptions {
+    audit?: EndpointInvocationAuditSink;
+    uploads?: EndpointUploadService;
+    policy?: EndpointToolPolicy;
+}
+export interface EndpointInvocationResult {
+    content: EndpointToolContent[];
+    details?: Record<string, unknown>;
+}
+export declare class EndpointToolExecutionError extends Error {
+    readonly code: EndpointToolErrorCode;
+    constructor(code: EndpointToolErrorCode, message: string);
+}
+export declare class EndpointInvocationService {
+    private readonly registry;
+    private readonly options;
+    private readonly pending;
+    private readonly policy;
+    constructor(registry: EndpointRegistry, options?: EndpointInvocationServiceOptions);
+    invoke(params: {
+        endpointId: string;
+        toolCallId: string;
+        toolName: string;
+        arguments: Record<string, unknown>;
+        descriptorRevision: string;
+        signal?: AbortSignal;
+        onProgress?: (progress: {
+            message?: string;
+            percent?: number;
+        }) => void;
+    }): Promise<EndpointInvocationResult>;
+    handleMessage(endpointId: string, message: ToolClientMessage): void;
+    failEndpoint(endpointId: string): void;
+    close(): void;
+    private cancel;
+    private succeed;
+    private fail;
+    private take;
+    private error;
+}
+export {};

package/dist/src/endpoint-tools/invocation-service.js

@@ -0,0 +1,190 @@
+import { ENDPOINT_INVOCATION_RECEIPT_TIMEOUT_MS, canonicalJson } from "../../packages/endpoint-tools-protocol/src/index.js";
+import { EndpointToolPolicy, EndpointToolPolicyError } from "./policy.js";
+import crypto from "node:crypto";
+//#region src/endpoint-tools/invocation-service.ts
+var EndpointToolExecutionError = class extends Error {
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "EndpointToolExecutionError";
+	}
+};
+var EndpointInvocationService = class {
+	pending = /* @__PURE__ */ new Map();
+	policy;
+	constructor(registry, options = {}) {
+		this.registry = registry;
+		this.options = options;
+		this.policy = options.policy ?? new EndpointToolPolicy();
+	}
+	invoke(params) {
+		const endpoint = this.registry.get(params.endpointId);
+		if (!endpoint) return Promise.reject(this.error("ENDPOINT_OFFLINE", "Endpoint is offline"));
+		const tool = this.registry.getTool(params.endpointId, params.toolName);
+		if (!tool) return Promise.reject(this.error("TOOL_NOT_FOUND", "Endpoint tool is unavailable"));
+		if (tool.revision !== params.descriptorRevision) return Promise.reject(this.error("TOOL_REVISION_MISMATCH", "Endpoint tool contract changed"));
+		let confirmationRequired;
+		try {
+			confirmationRequired = this.policy.evaluate(tool.descriptor, endpoint.availability).confirmationRequired;
+		} catch (error) {
+			if (error instanceof EndpointToolPolicyError) return Promise.reject(this.error("ENDPOINT_NOT_FOREGROUND", error.message));
+			throw error;
+		}
+		if (params.signal?.aborted) return Promise.reject(this.error("TOOL_CANCELLED", "Endpoint tool call was cancelled"));
+		const endpointPending = [...this.pending.values()].filter((item) => item.endpointId === params.endpointId);
+		if (endpointPending.length >= 4) return Promise.reject(this.error("TOOL_BUSY", "Endpoint has reached its invocation limit"));
+		if (endpointPending.filter((item) => item.toolName === params.toolName).length >= tool.descriptor.maxConcurrency) return Promise.reject(this.error("TOOL_BUSY", "Endpoint tool has reached its invocation limit"));
+		const invocationId = crypto.randomUUID();
+		const startedAt = Date.now();
+		const uploadGrant = tool.descriptor.resultKinds.includes("file") ? this.options.uploads?.createGrant(invocationId, params.endpointId, startedAt) : void 0;
+		try {
+			this.options.audit?.started({
+				id: invocationId,
+				principalId: endpoint.principalId,
+				endpointId: params.endpointId,
+				toolCallId: params.toolCallId,
+				toolName: params.toolName,
+				effect: tool.descriptor.effect,
+				confirmationRequired,
+				argumentsSha256: crypto.createHash("sha256").update(canonicalJson(params.arguments)).digest("hex"),
+				startedAt
+			});
+		} catch (error) {
+			this.options.uploads?.abort(invocationId);
+			return Promise.reject(error);
+		}
+		return new Promise((resolve, reject) => {
+			const pending = {
+				id: invocationId,
+				endpointId: params.endpointId,
+				toolName: params.toolName,
+				state: "sent",
+				receiptTimer: setTimeout(() => {
+					this.fail(invocationId, this.error("TOOL_TIMEOUT", "Endpoint did not receive the invocation"));
+				}, ENDPOINT_INVOCATION_RECEIPT_TIMEOUT_MS),
+				deadlineTimer: setTimeout(() => {
+					this.cancel(invocationId, "Endpoint tool timed out", "TOOL_TIMEOUT");
+				}, tool.descriptor.timeoutMs),
+				abortSignal: params.signal,
+				onProgress: params.onProgress,
+				resolve,
+				reject
+			};
+			if (params.signal) {
+				pending.abortHandler = () => this.cancel(invocationId, "Agent cancelled the tool call", "TOOL_CANCELLED");
+				params.signal.addEventListener("abort", pending.abortHandler, { once: true });
+			}
+			this.pending.set(invocationId, pending);
+			try {
+				this.registry.send(params.endpointId, "tool.invoke", {
+					invocationId,
+					toolCallId: params.toolCallId,
+					toolName: params.toolName,
+					arguments: params.arguments,
+					descriptorRevision: params.descriptorRevision,
+					confirmationRequired,
+					deadlineAt: Date.now() + tool.descriptor.timeoutMs,
+					...uploadGrant ? { uploadGrant } : {}
+				});
+			} catch {
+				this.fail(invocationId, this.error("ENDPOINT_DISCONNECTED", "Endpoint disconnected before invocation"));
+			}
+		});
+	}
+	handleMessage(endpointId, message) {
+		const invocationId = message.payload.invocationId;
+		const pending = this.pending.get(invocationId);
+		if (!pending || pending.endpointId !== endpointId) return;
+		switch (message.type) {
+			case "tool.received":
+				if (pending.state !== "sent") return;
+				pending.state = "running";
+				clearTimeout(pending.receiptTimer);
+				return;
+			case "tool.progress":
+				if (pending.state !== "running") return;
+				pending.onProgress?.({
+					...message.payload.message === void 0 ? {} : { message: message.payload.message },
+					...message.payload.percent === void 0 ? {} : { percent: message.payload.percent }
+				});
+				return;
+			case "tool.result":
+				if (pending.state !== "running") return;
+				try {
+					this.options.uploads?.validateAndClose(invocationId, message.payload.content);
+				} catch (error) {
+					this.fail(invocationId, this.error("PROTOCOL_ERROR", error instanceof Error ? error.message : String(error)));
+					return;
+				}
+				this.succeed(invocationId, {
+					content: message.payload.content,
+					...message.payload.details === void 0 ? {} : { details: message.payload.details }
+				});
+				return;
+			case "tool.error":
+				this.fail(invocationId, this.error(message.payload.code, message.payload.message));
+				return;
+			case "tool.cancelled": this.fail(invocationId, this.error("TOOL_CANCELLED", "Endpoint cancelled the tool call"));
+		}
+	}
+	failEndpoint(endpointId) {
+		for (const pending of this.pending.values()) if (pending.endpointId === endpointId) this.fail(pending.id, this.error("ENDPOINT_DISCONNECTED", "Endpoint disconnected"));
+	}
+	close() {
+		for (const pending of this.pending.values()) this.fail(pending.id, this.error("ENDPOINT_DISCONNECTED", "Endpoint runtime stopped"));
+	}
+	cancel(invocationId, reason, code) {
+		const pending = this.pending.get(invocationId);
+		if (!pending) return;
+		try {
+			this.registry.send(pending.endpointId, "tool.cancel", {
+				invocationId,
+				reason
+			});
+		} catch {}
+		this.fail(invocationId, this.error(code, reason));
+	}
+	succeed(invocationId, result) {
+		const pending = this.take(invocationId);
+		if (!pending) return;
+		try {
+			this.options.audit?.finished({
+				id: invocationId,
+				status: "succeeded",
+				completedAt: Date.now()
+			});
+		} finally {
+			pending.resolve(result);
+		}
+	}
+	fail(invocationId, error) {
+		const pending = this.take(invocationId);
+		if (!pending) return;
+		try {
+			this.options.uploads?.abort(invocationId);
+			this.options.audit?.finished({
+				id: invocationId,
+				status: "failed",
+				...error instanceof EndpointToolExecutionError ? { errorCode: error.code } : {},
+				errorMessage: error.message,
+				completedAt: Date.now()
+			});
+		} finally {
+			pending.reject(error);
+		}
+	}
+	take(invocationId) {
+		const pending = this.pending.get(invocationId);
+		if (!pending) return void 0;
+		this.pending.delete(invocationId);
+		clearTimeout(pending.receiptTimer);
+		clearTimeout(pending.deadlineTimer);
+		if (pending.abortSignal && pending.abortHandler) pending.abortSignal.removeEventListener("abort", pending.abortHandler);
+		return pending;
+	}
+	error(code, message) {
+		return new EndpointToolExecutionError(code, message);
+	}
+};
+//#endregion
+export { EndpointInvocationService, EndpointToolExecutionError };

package/dist/src/endpoint-tools/policy.d.ts

@@ -0,0 +1,10 @@
+import type { EndpointAvailability, EndpointKind, EndpointToolDescriptor } from '@xopcai/endpoint-tools-protocol';
+export interface EndpointToolPolicyDecision {
+    confirmationRequired: boolean;
+}
+export declare class EndpointToolPolicyError extends Error {
+}
+export declare class EndpointToolPolicy {
+    validateDescriptor(kind: EndpointKind, descriptor: EndpointToolDescriptor): void;
+    evaluate(descriptor: EndpointToolDescriptor, availability: EndpointAvailability): EndpointToolPolicyDecision;
+}