@xopcai/xopc 0.0.187 → 0.0.189

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;
+}

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

@@ -0,0 +1,18 @@
+//#region src/endpoint-tools/policy.ts
+var EndpointToolPolicyError = class extends Error {};
+var EndpointToolPolicy = class {
+	validateDescriptor(kind, descriptor) {
+		if (!descriptor.name.startsWith(`${kind}.`)) throw new EndpointToolPolicyError(`Tool ${descriptor.name} does not belong to ${kind}`);
+		if (descriptor.effect !== "read") {
+			if (descriptor.confirmation !== "always") throw new EndpointToolPolicyError(`Mutating tool ${descriptor.name} must always require confirmation`);
+			if (!descriptor.requiresForeground) throw new EndpointToolPolicyError(`Mutating tool ${descriptor.name} must require foreground`);
+			if (descriptor.requiredPermissions.length === 0) throw new EndpointToolPolicyError(`Mutating tool ${descriptor.name} must declare a permission`);
+		}
+	}
+	evaluate(descriptor, availability) {
+		if (descriptor.requiresForeground && availability !== "foreground") throw new EndpointToolPolicyError("Endpoint is not in the foreground");
+		return { confirmationRequired: descriptor.confirmation === "always" || descriptor.effect !== "read" };
+	}
+};
+//#endregion
+export { EndpointToolPolicy, EndpointToolPolicyError };

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

@@ -0,0 +1,45 @@
+import { type EndpointAvailability, type EndpointHelloPayload, type EndpointKind, type EndpointToolDescriptor } from '@xopcai/endpoint-tools-protocol';
+import { EndpointToolPolicy } from './policy.js';
+export interface EndpointTransport {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+}
+export interface RegisteredEndpointTool {
+    descriptor: EndpointToolDescriptor;
+    revision: string;
+}
+export interface EndpointConnectionSnapshot {
+    principalId: string;
+    endpointId: string;
+    connectionId: string;
+    displayName: string;
+    kind: EndpointKind;
+    platform: string;
+    appVersion: string;
+    availability: EndpointAvailability;
+    lastHeartbeatAt: number;
+    tools: RegisteredEndpointTool[];
+}
+export interface EndpointRegistration {
+    connection: EndpointConnectionSnapshot;
+    turnToken: string;
+}
+export declare function endpointToolRevision(descriptor: EndpointToolDescriptor): string;
+export declare class EndpointRegistry {
+    private readonly policy;
+    private readonly connectionByEndpointId;
+    constructor(policy?: EndpointToolPolicy);
+    register(hello: EndpointHelloPayload, connectionId: string, transport: EndpointTransport, now?: number): EndpointRegistration;
+    remove(endpointId: string, connectionId: string): boolean;
+    heartbeat(endpointId: string, connectionId: string, availability: EndpointAvailability, now?: number): void;
+    get(endpointId: string): EndpointConnectionSnapshot | undefined;
+    isCurrentConnection(endpointId: string, connectionId: string): boolean;
+    list(): EndpointConnectionSnapshot[];
+    getTool(endpointId: string, toolName: string): RegisteredEndpointTool | undefined;
+    verifyTurnClaim(endpointId: string, turnToken: string): boolean;
+    send(endpointId: string, type: 'tool.invoke' | 'tool.cancel', payload: unknown): void;
+    disconnect(endpointId: string, code?: number, reason?: string): boolean;
+    closeAll(code?: number, reason?: string): void;
+    private requireConnection;
+}

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

@@ -0,0 +1,121 @@
+import { canonicalJson } from "../../packages/endpoint-tools-protocol/src/index.js";
+import { EndpointToolPolicy } from "./policy.js";
+import crypto from "node:crypto";
+//#region src/endpoint-tools/registry.ts
+function endpointToolRevision(descriptor) {
+	return crypto.createHash("sha256").update(canonicalJson(descriptor)).digest("hex");
+}
+function snapshot(connection) {
+	return {
+		principalId: connection.principalId,
+		endpointId: connection.endpointId,
+		connectionId: connection.connectionId,
+		displayName: connection.displayName,
+		kind: connection.kind,
+		platform: connection.platform,
+		appVersion: connection.appVersion,
+		availability: connection.availability,
+		lastHeartbeatAt: connection.lastHeartbeatAt,
+		tools: [...connection.toolByName.values()]
+	};
+}
+var EndpointRegistry = class {
+	connectionByEndpointId = /* @__PURE__ */ new Map();
+	constructor(policy = new EndpointToolPolicy()) {
+		this.policy = policy;
+	}
+	register(hello, connectionId, transport, now = Date.now()) {
+		const toolByName = /* @__PURE__ */ new Map();
+		for (const descriptor of hello.tools) {
+			this.policy.validateDescriptor(hello.kind, descriptor);
+			if (toolByName.has(descriptor.name)) throw new Error(`Endpoint catalog contains duplicate tool: ${descriptor.name}`);
+			toolByName.set(descriptor.name, {
+				descriptor,
+				revision: endpointToolRevision(descriptor)
+			});
+		}
+		const previous = this.connectionByEndpointId.get(hello.endpointId);
+		if (previous && previous.principalId !== hello.principalId) throw new Error("Endpoint instance belongs to another principal");
+		if (previous) previous.transport.close(4001, "Endpoint connected elsewhere");
+		const connection = {
+			principalId: hello.principalId,
+			endpointId: hello.endpointId,
+			connectionId,
+			displayName: hello.displayName,
+			kind: hello.kind,
+			platform: hello.platform,
+			appVersion: hello.appVersion,
+			availability: hello.availability,
+			lastHeartbeatAt: now,
+			tools: [],
+			transport,
+			turnToken: crypto.randomBytes(32).toString("base64url"),
+			toolByName
+		};
+		this.connectionByEndpointId.set(connection.endpointId, connection);
+		return {
+			connection: snapshot(connection),
+			turnToken: connection.turnToken
+		};
+	}
+	remove(endpointId, connectionId) {
+		const connection = this.connectionByEndpointId.get(endpointId);
+		if (!connection || connection.connectionId !== connectionId) return false;
+		this.connectionByEndpointId.delete(endpointId);
+		return true;
+	}
+	heartbeat(endpointId, connectionId, availability, now = Date.now()) {
+		const connection = this.requireConnection(endpointId, connectionId);
+		connection.availability = availability;
+		connection.lastHeartbeatAt = now;
+	}
+	get(endpointId) {
+		const connection = this.connectionByEndpointId.get(endpointId);
+		return connection ? snapshot(connection) : void 0;
+	}
+	isCurrentConnection(endpointId, connectionId) {
+		return this.connectionByEndpointId.get(endpointId)?.connectionId === connectionId;
+	}
+	list() {
+		return [...this.connectionByEndpointId.values()].map(snapshot);
+	}
+	getTool(endpointId, toolName) {
+		return this.connectionByEndpointId.get(endpointId)?.toolByName.get(toolName);
+	}
+	verifyTurnClaim(endpointId, turnToken) {
+		const connection = this.connectionByEndpointId.get(endpointId);
+		if (!connection || connection.transport.readyState !== 1) return false;
+		const expected = Buffer.from(connection.turnToken);
+		const actual = Buffer.from(turnToken);
+		return expected.length === actual.length && crypto.timingSafeEqual(expected, actual);
+	}
+	send(endpointId, type, payload) {
+		const connection = this.connectionByEndpointId.get(endpointId);
+		if (!connection || connection.transport.readyState !== 1) throw new Error(`Endpoint is offline: ${endpointId}`);
+		const message = {
+			protocolVersion: 1,
+			messageId: crypto.randomUUID(),
+			type,
+			sentAt: Date.now(),
+			payload
+		};
+		connection.transport.send(JSON.stringify(message));
+	}
+	disconnect(endpointId, code = 4003, reason = "Endpoint disconnected") {
+		const connection = this.connectionByEndpointId.get(endpointId);
+		if (!connection) return false;
+		connection.transport.close(code, reason);
+		return true;
+	}
+	closeAll(code = 1001, reason = "Gateway stopping") {
+		for (const connection of this.connectionByEndpointId.values()) connection.transport.close(code, reason);
+		this.connectionByEndpointId.clear();
+	}
+	requireConnection(endpointId, connectionId) {
+		const connection = this.connectionByEndpointId.get(endpointId);
+		if (!connection || connection.connectionId !== connectionId) throw new Error("Endpoint connection is no longer active");
+		return connection;
+	}
+};
+//#endregion
+export { EndpointRegistry, endpointToolRevision };

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

@@ -0,0 +1,23 @@
+import { type ClientEndpointMessage, type EndpointHelloPayload } from '@xopcai/endpoint-tools-protocol';
+import { type EndpointAuthenticatorDeps } from './auth.js';
+import { EndpointInvocationService, type EndpointInvocationAuditSink } from './invocation-service.js';
+import { EndpointRegistry, type EndpointRegistration, type EndpointTransport } from './registry.js';
+import { EndpointUploadService } from './upload-service.js';
+export declare class EndpointToolRuntime {
+    readonly registry: EndpointRegistry;
+    readonly invocations: EndpointInvocationService;
+    readonly uploads: EndpointUploadService;
+    private readonly authenticator;
+    private closed;
+    constructor(options?: {
+        auth?: EndpointAuthenticatorDeps;
+        audit?: EndpointInvocationAuditSink;
+        uploadRoot?: string;
+    });
+    connect(hello: EndpointHelloPayload, connectionId: string, transport: EndpointTransport): EndpointRegistration;
+    handleMessage(endpointId: string, connectionId: string, message: ClientEndpointMessage): void;
+    touch(endpointId: string, connectionId: string): void;
+    remove(endpointId: string, connectionId: string): void;
+    disconnect(endpointId: string, reason: string): void;
+    close(): void;
+}

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

@@ -0,0 +1,86 @@
+import { resolveStateDir } from "../config/paths-state.js";
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { bindEndpointPrincipal, getEndpointPrincipal, touchEndpointPrincipal } from "../storage/sqlite/endpoint-principal-repository.js";
+import { finishEndpointToolInvocationAudit, startEndpointToolInvocationAudit } from "../storage/sqlite/endpoint-tool-invocation-repository.js";
+import "../storage/sqlite/index.js";
+import { init_paths } from "../config/paths.js";
+import { EndpointAuthenticator } from "./auth.js";
+import { EndpointToolPolicy } from "./policy.js";
+import { EndpointInvocationService } from "./invocation-service.js";
+import { EndpointRegistry } from "./registry.js";
+import { EndpointUploadService } from "./upload-service.js";
+import { join } from "node:path";
+//#region src/endpoint-tools/runtime.ts
+init_paths();
+init_logger();
+const log = createLogger("EndpointTools");
+const MAX_MESSAGE_CLOCK_SKEW_MS = 6e4;
+var EndpointToolRuntime = class {
+	registry;
+	invocations;
+	uploads;
+	authenticator;
+	closed = false;
+	constructor(options = {}) {
+		const policy = new EndpointToolPolicy();
+		this.registry = new EndpointRegistry(policy);
+		this.authenticator = new EndpointAuthenticator(options.auth ?? {
+			getPrincipal: getEndpointPrincipal,
+			bindEndpoint: bindEndpointPrincipal,
+			touchPrincipal: touchEndpointPrincipal
+		});
+		this.uploads = new EndpointUploadService(options.uploadRoot ?? join(resolveStateDir(), "endpoint-tool-files"));
+		this.invocations = new EndpointInvocationService(this.registry, {
+			audit: options.audit ?? {
+				started: startEndpointToolInvocationAudit,
+				finished: finishEndpointToolInvocationAudit
+			},
+			uploads: this.uploads,
+			policy
+		});
+	}
+	connect(hello, connectionId, transport) {
+		if (this.closed) throw new Error("Endpoint runtime is closed");
+		this.authenticator.authenticate(hello);
+		const registration = this.registry.register(hello, connectionId, transport);
+		log.info({
+			endpointId: hello.endpointId,
+			connectionId,
+			kind: hello.kind
+		}, "Endpoint connected");
+		return registration;
+	}
+	handleMessage(endpointId, connectionId, message) {
+		if (!this.registry.isCurrentConnection(endpointId, connectionId)) throw new Error("Endpoint connection is no longer active");
+		if (Math.abs(Date.now() - message.sentAt) > MAX_MESSAGE_CLOCK_SKEW_MS) throw new Error("Endpoint message timestamp is outside the allowed window");
+		if (message.type === "endpoint.availability_changed") {
+			this.registry.heartbeat(endpointId, connectionId, message.payload.availability);
+			return;
+		}
+		this.invocations.handleMessage(endpointId, message);
+	}
+	touch(endpointId, connectionId) {
+		const endpoint = this.registry.get(endpointId);
+		if (endpoint?.connectionId === connectionId) this.registry.heartbeat(endpointId, connectionId, endpoint.availability);
+	}
+	remove(endpointId, connectionId) {
+		if (!this.registry.remove(endpointId, connectionId)) return;
+		this.invocations.failEndpoint(endpointId);
+		log.info({
+			endpointId,
+			connectionId
+		}, "Endpoint disconnected");
+	}
+	disconnect(endpointId, reason) {
+		this.registry.disconnect(endpointId, 4003, reason);
+	}
+	close() {
+		if (this.closed) return;
+		this.closed = true;
+		this.invocations.close();
+		this.registry.closeAll();
+	}
+};
+//#endregion
+export { EndpointToolRuntime };

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

@@ -0,0 +1,41 @@
+import { type EndpointToolContent } from '@xopcai/endpoint-tools-protocol';
+export declare const ENDPOINT_UPLOAD_MAX_BYTES: number;
+export interface EndpointUploadedFile {
+    fileId: string;
+    invocationId: string;
+    name: string;
+    mimeType: string;
+    size: number;
+    sha256: string;
+    path: string;
+}
+export interface EndpointUploadGrant {
+    path: string;
+    token: string;
+    maxBytes: number;
+    maxFiles: number;
+    expiresAt: number;
+}
+export declare class EndpointUploadError extends Error {
+}
+export declare class EndpointUploadService {
+    private readonly rootDir;
+    private readonly grants;
+    private readonly files;
+    constructor(rootDir: string);
+    createGrant(invocationId: string, endpointId: string, now?: number): EndpointUploadGrant;
+    upload(params: {
+        invocationId: string;
+        endpointId: string;
+        token: string;
+        name: string;
+        mimeType: string;
+        bytes: Uint8Array;
+        now?: number;
+    }): EndpointUploadedFile;
+    validateAndClose(invocationId: string, content: EndpointToolContent[]): void;
+    abort(invocationId: string): void;
+    getFile(fileId: string): EndpointUploadedFile | undefined;
+    readFile(fileId: string): Uint8Array | undefined;
+    private deleteFile;
+}

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

@@ -0,0 +1,103 @@
+import { ENDPOINT_MAX_FILE_BYTES } from "../../packages/endpoint-tools-protocol/src/index.js";
+import { join } from "node:path";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import crypto from "node:crypto";
+//#region src/endpoint-tools/upload-service.ts
+const GRANT_TTL_MS = 5 * 6e4;
+const ENDPOINT_UPLOAD_MAX_BYTES = ENDPOINT_MAX_FILE_BYTES;
+const DEFAULT_MAX_FILES = 8;
+var EndpointUploadError = class extends Error {};
+var EndpointUploadService = class {
+	grants = /* @__PURE__ */ new Map();
+	files = /* @__PURE__ */ new Map();
+	constructor(rootDir) {
+		this.rootDir = rootDir;
+		mkdirSync(rootDir, {
+			recursive: true,
+			mode: 448
+		});
+	}
+	createGrant(invocationId, endpointId, now = Date.now()) {
+		const token = crypto.randomUUID();
+		const grant = {
+			invocationId,
+			endpointId,
+			token,
+			expiresAt: now + GRANT_TTL_MS,
+			maxBytes: ENDPOINT_UPLOAD_MAX_BYTES,
+			maxFiles: DEFAULT_MAX_FILES,
+			uploadedFileIds: []
+		};
+		this.grants.set(invocationId, grant);
+		return {
+			path: `/api/endpoint-tools/invocations/${encodeURIComponent(invocationId)}/files`,
+			token,
+			maxBytes: grant.maxBytes,
+			maxFiles: grant.maxFiles,
+			expiresAt: grant.expiresAt
+		};
+	}
+	upload(params) {
+		const grant = this.grants.get(params.invocationId);
+		const now = params.now ?? Date.now();
+		const expectedToken = grant ? Buffer.from(grant.token) : void 0;
+		const receivedToken = Buffer.from(params.token);
+		if (!grant || grant.endpointId !== params.endpointId || expectedToken?.byteLength !== receivedToken.byteLength || !crypto.timingSafeEqual(expectedToken, receivedToken)) throw new EndpointUploadError("Upload grant is invalid");
+		if (grant.expiresAt <= now) throw new EndpointUploadError("Upload grant expired");
+		if (grant.uploadedFileIds.length >= grant.maxFiles) throw new EndpointUploadError("Upload grant file limit exceeded");
+		if (params.bytes.byteLength > grant.maxBytes) throw new EndpointUploadError("Uploaded file is too large");
+		if (!params.name || params.name.length > 255 || !params.mimeType || params.mimeType.length > 255) throw new EndpointUploadError("Uploaded file metadata is invalid");
+		const fileId = crypto.randomUUID();
+		const path = join(this.rootDir, fileId);
+		const sha256 = crypto.createHash("sha256").update(params.bytes).digest("hex");
+		writeFileSync(path, params.bytes, {
+			flag: "wx",
+			mode: 384
+		});
+		const file = {
+			fileId,
+			invocationId: params.invocationId,
+			name: params.name,
+			mimeType: params.mimeType,
+			size: params.bytes.byteLength,
+			sha256,
+			path
+		};
+		this.files.set(fileId, file);
+		grant.uploadedFileIds.push(fileId);
+		return file;
+	}
+	validateAndClose(invocationId, content) {
+		const grant = this.grants.get(invocationId);
+		const referenced = content.filter((item) => item.type === "file");
+		for (const item of referenced) {
+			const file = this.files.get(item.fileId);
+			if (!file || file.invocationId !== invocationId || file.name !== item.name || file.mimeType !== item.mimeType || file.size !== item.size || file.sha256 !== item.sha256) throw new EndpointUploadError(`Endpoint file is not valid for invocation: ${item.fileId}`);
+		}
+		if (grant) {
+			for (const fileId of grant.uploadedFileIds) if (!referenced.some((item) => item.fileId === fileId)) this.deleteFile(fileId);
+			this.grants.delete(invocationId);
+		} else if (referenced.length > 0) throw new EndpointUploadError("Invocation did not have an upload grant");
+	}
+	abort(invocationId) {
+		const grant = this.grants.get(invocationId);
+		if (!grant) return;
+		for (const fileId of grant.uploadedFileIds) this.deleteFile(fileId);
+		this.grants.delete(invocationId);
+	}
+	getFile(fileId) {
+		return this.files.get(fileId);
+	}
+	readFile(fileId) {
+		const file = this.files.get(fileId);
+		return file ? readFileSync(file.path) : void 0;
+	}
+	deleteFile(fileId) {
+		const file = this.files.get(fileId);
+		if (!file) return;
+		rmSync(file.path, { force: true });
+		this.files.delete(fileId);
+	}
+};
+//#endregion
+export { ENDPOINT_UPLOAD_MAX_BYTES, EndpointUploadError, EndpointUploadService };

package/dist/src/extensions/extension-registry-impl.d.ts

@@ -17,6 +17,7 @@ export declare class ExtensionRegistryImpl implements ExtensionRegistry {
     services: Map<string, ExtensionService>;
     gatewayMethods: Map<string, GatewayMethodHandler>;
     tools: Map<string, AgentTool<any, any>>;
+    private toolExtensionIds;
     channelPlugins: ChannelPlugin[];
     private cliRegistrations;
     private reloadRegistrations;
@@ -36,10 +37,11 @@ export declare class ExtensionRegistryImpl implements ExtensionRegistry {
     getService(id: string): ExtensionService | undefined;
     addGatewayMethod(method: string, handler: GatewayMethodHandler): void;
     getGatewayMethod(method: string): GatewayMethodHandler | undefined;
-    addTool(tool: any): void;
+    addTool(tool: any, extensionId: string): void;
     removeTool(name: string): void;
     getTools(): Map<string, any>;
     getTool(name: string): any | undefined;
+    getToolExtensionId(name: string): string | undefined;
     getAllTools(): any[];
     addCliRegistration(reg: ExtensionCliRegistration): void;
     getCliRegistrations(): readonly ExtensionCliRegistration[];