@xopcai/xopc 0.0.369 → 0.0.371

package/dist/src/endpoint-tools/bridge-host.js

@@ -0,0 +1,166 @@
+import { endpointHelloSigningPayload, init_src } from "../../packages/endpoint-tools-protocol/src/index.js";
+import { EndpointToolHostController } from "../../packages/endpoint-tools-client/src/index.js";
+import { RealtimeClient } from "../../packages/realtime-client/src/index.js";
+import { dirname } from "node:path";
+import { generateKeyPairSync, randomUUID, sign } from "node:crypto";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import WebSocket from "ws";
+//#region src/endpoint-tools/bridge-host.ts
+init_src();
+async function loadIdentity(path) {
+	try {
+		const info = await stat(path);
+		if (!info.isFile() || process.platform !== "win32" && (info.mode & 63) !== 0) throw new Error("Bridge identity must be a private file (mode 0600)");
+		const identity = JSON.parse(await readFile(path, "utf8"));
+		if (!identity.principalId || !identity.publicKey || !identity.privateKey) throw new Error("Invalid Bridge identity file");
+		return identity;
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+		const pair = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
+		const identity = {
+			principalId: randomUUID(),
+			publicKey: pair.publicKey.export({
+				type: "spki",
+				format: "der"
+			}).toString("base64url"),
+			privateKey: pair.privateKey.export({
+				type: "pkcs8",
+				format: "pem"
+			}).toString()
+		};
+		await mkdir(dirname(path), {
+			recursive: true,
+			mode: 448
+		});
+		await writeFile(path, JSON.stringify(identity), {
+			mode: 384,
+			flag: "wx"
+		});
+		return identity;
+	}
+}
+/** Connects a Node hardware adapter through the existing signed Endpoint v2 transport. */
+async function connectDeviceBridge(options) {
+	const url = new URL(options.gatewayUrl);
+	if (url.username || url.password || url.search || url.hash || url.pathname !== "/") throw new Error("Use a Gateway origin URL without credentials or path");
+	if (url.protocol !== "https:" && !(url.protocol === "http:" && [
+		"localhost",
+		"127.0.0.1",
+		"[::1]"
+	].includes(url.hostname))) throw new Error("Remote Bridge connections require HTTPS");
+	const lifetime = new AbortController();
+	const request = async (path, body, signal) => {
+		const response = await fetch(new URL(path, url), {
+			method: body === void 0 ? "GET" : "POST",
+			headers: {
+				Authorization: `Bearer ${options.token}`,
+				"Content-Type": "application/json"
+			},
+			...body === void 0 ? {} : { body: JSON.stringify(body) },
+			redirect: "error",
+			signal: AbortSignal.any([lifetime.signal, signal ?? AbortSignal.timeout(1e4)])
+		});
+		if (!response.ok) throw new Error(`Bridge Gateway request failed: HTTP ${response.status}`);
+		const result = await response.json();
+		if (!result.ok) throw new Error("Bridge Gateway request was rejected");
+		return result.payload;
+	};
+	if ((await request("/api/endpoint-tools/compatibility")).hardwareBridgeV1 !== true) throw new Error("Gateway does not support hardwareBridgeV1");
+	const identity = await loadIdentity(options.identityPath);
+	const endpointId = `${identity.principalId}:bridge`;
+	const displayName = options.displayName ?? "xopc Device Bridge";
+	if (!displayName.trim() || displayName.length > 80) throw new Error("Bridge name must contain 1–80 characters");
+	const register = () => request("/api/endpoint-tools/principals", {
+		principalId: identity.principalId,
+		publicKey: identity.publicKey,
+		kind: "desktop",
+		platform: process.platform,
+		displayName
+	});
+	await register();
+	const controller = new EndpointToolHostController({
+		registry: options.registry,
+		getAvailability: () => "background",
+		createMessageId: randomUUID,
+		confirm: async () => false,
+		uploadFile: async () => {
+			throw new Error("Bridge sensors cannot upload files");
+		}
+	});
+	const clientId = randomUUID();
+	const websocketUrl = new URL("/api/realtime/v1/ws", url);
+	websocketUrl.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+	const client = new RealtimeClient({
+		clientId,
+		clientKind: "desktop",
+		createMessageId: randomUUID,
+		getWebSocketUrl: () => websocketUrl.href,
+		issueTicket: (signal) => request("/api/realtime/tickets", {
+			clientId,
+			clientKind: "desktop",
+			protocolVersion: 2
+		}, signal),
+		createWebSocket: (address) => new WebSocket(address),
+		onStateChange: (state) => options.onStateChange?.(state)
+	});
+	const close = () => {
+		lifetime.abort();
+		client.disconnect();
+		controller.disconnect();
+	};
+	let resolveReady;
+	const ready = new Promise((resolve) => {
+		resolveReady = resolve;
+	});
+	client.setEndpoint({
+		createHello: async () => {
+			await register();
+			const hello = {
+				principalId: identity.principalId,
+				endpointId,
+				connectionInstanceId: randomUUID(),
+				displayName,
+				kind: "desktop",
+				platform: process.platform,
+				appVersion: "1",
+				availability: "background",
+				nonce: randomUUID(),
+				signedAt: Date.now(),
+				signature: "pending",
+				tools: options.registry.descriptors()
+			};
+			hello.signature = sign("sha256", Buffer.from(endpointHelloSigningPayload(hello)), {
+				key: identity.privateKey,
+				dsaEncoding: "ieee-p1363"
+			}).toString("base64url");
+			return hello;
+		},
+		onReady: () => {
+			controller.connect((message) => client.sendEndpointMessage(message));
+			resolveReady();
+		},
+		onMessage: (message) => {
+			controller.handleMessage(message);
+		},
+		onDisconnected: () => controller.disconnect()
+	});
+	client.connect();
+	let timeout;
+	try {
+		await Promise.race([ready, new Promise((_resolve, reject) => {
+			timeout = setTimeout(() => reject(/* @__PURE__ */ new Error("Bridge endpoint did not become ready")), 15e3);
+		})]);
+	} catch (error) {
+		close();
+		throw error;
+	} finally {
+		clearTimeout(timeout);
+	}
+	return {
+		endpointId,
+		principalId: identity.principalId,
+		close
+	};
+}
+//#endregion
+export { connectDeviceBridge };

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

@@ -0,0 +1,27 @@
+import { EndpointToolRegistry } from '@xopcai/endpoint-tools-client';
+import { z } from 'zod';
+declare const resourceSchema: z.ZodObject<{
+    resourceId: z.ZodString;
+    name: z.ZodString;
+    measurement: z.ZodEnum<{
+        temperature: "temperature";
+        humidity: "humidity";
+    }>;
+    unit: z.ZodEnum<{
+        celsius: "celsius";
+        percent: "percent";
+    }>;
+    simulated: z.ZodBoolean;
+}, z.core.$strict>;
+export type BridgeResource = z.infer<typeof resourceSchema>;
+export interface BridgeSensorAdapter {
+    resource: BridgeResource;
+    read(signal: AbortSignal): Promise<{
+        value: number | null;
+        capturedAt: number;
+    }>;
+}
+/** Drivers return one sample; transport, identity, cancellation and policy remain host-owned. */
+export declare function createDeviceBridge(adapters: readonly BridgeSensorAdapter[], now?: () => number): EndpointToolRegistry;
+export declare function simulatedEnvironmentSensors(now?: () => number): BridgeSensorAdapter[];
+export {};

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

@@ -0,0 +1,88 @@
+import { bridgeDescriptor } from "../../packages/endpoint-tools-protocol/src/bridge.js";
+import { init_src } from "../../packages/endpoint-tools-protocol/src/index.js";
+import { EndpointToolRegistry } from "../../packages/endpoint-tools-client/src/index.js";
+import { z } from "zod";
+//#region src/endpoint-tools/bridge.ts
+init_src();
+const resourceSchema = z.object({
+	resourceId: z.string().regex(/^[a-zA-Z0-9._:-]{1,128}$/),
+	name: z.string().min(1).max(80),
+	measurement: z.enum(["temperature", "humidity"]),
+	unit: z.enum(["celsius", "percent"]),
+	simulated: z.boolean()
+}).strict().refine((item) => item.unit === (item.measurement === "temperature" ? "celsius" : "percent"), "Unit does not match measurement");
+/** Drivers return one sample; transport, identity, cancellation and policy remain host-owned. */
+function createDeviceBridge(adapters, now = Date.now) {
+	if (adapters.length > 100) throw new Error("Bridge supports at most 100 resources");
+	const resources = /* @__PURE__ */ new Map();
+	for (const adapter of adapters) {
+		const resource = resourceSchema.parse(adapter.resource);
+		if (resources.has(resource.resourceId)) throw new Error("Duplicate Bridge resource ID");
+		resources.set(resource.resourceId, {
+			resource,
+			read: adapter.read.bind(adapter)
+		});
+	}
+	return new EndpointToolRegistry([{
+		descriptor: bridgeDescriptor("list_resources"),
+		execute: async (args) => {
+			z.object({}).strict().parse(args);
+			return { content: [{
+				type: "json",
+				value: [...resources.values()].map((item) => ({ ...item.resource }))
+			}] };
+		}
+	}, {
+		descriptor: bridgeDescriptor("read_sensor"),
+		execute: async (args, context) => {
+			const { resourceId } = z.object({ resourceId: z.string() }).strict().parse(args);
+			const adapter = resources.get(resourceId);
+			if (!adapter) throw new TypeError("Unknown Bridge resource");
+			context.signal.throwIfAborted();
+			const sample = await adapter.read(context.signal);
+			context.signal.throwIfAborted();
+			const time = now();
+			if (!Number.isSafeInteger(sample.capturedAt) || sample.capturedAt > time + 6e4 || sample.capturedAt < time - 3e4) throw new TypeError("Bridge sample has an invalid or stale timestamp");
+			const { value } = sample;
+			const range = adapter.resource.measurement === "humidity" ? [0, 100] : [-100, 200];
+			if (value !== null && (!Number.isFinite(value) || value < range[0] || value > range[1])) throw new TypeError("Invalid Bridge sample value");
+			return { content: [{
+				type: "json",
+				value: {
+					...adapter.resource,
+					value,
+					capturedAt: sample.capturedAt
+				}
+			}] };
+		}
+	}]);
+}
+function simulatedEnvironmentSensors(now = Date.now) {
+	return [{
+		resource: {
+			resourceId: "sim.room.temperature",
+			name: "Simulated room temperature",
+			measurement: "temperature",
+			unit: "celsius",
+			simulated: true
+		},
+		read: async () => ({
+			value: 23.5,
+			capturedAt: now()
+		})
+	}, {
+		resource: {
+			resourceId: "sim.room.humidity",
+			name: "Simulated room humidity",
+			measurement: "humidity",
+			unit: "percent",
+			simulated: true
+		},
+		read: async () => ({
+			value: 45,
+			capturedAt: now()
+		})
+	}];
+}
+//#endregion
+export { createDeviceBridge, simulatedEnvironmentSensors };

package/dist/src/endpoint-tools/capability-catalog.d.ts

@@ -0,0 +1,2 @@
+/** Server-owned targeting rules; device descriptors cannot change these defaults. */
+export declare function deviceCapabilityTarget(toolName: string): 'turn_origin' | 'session_bound';

package/dist/src/endpoint-tools/capability-catalog.js

@@ -0,0 +1,8 @@
+//#region src/endpoint-tools/capability-catalog.ts
+/** Server-owned targeting rules; device descriptors cannot change these defaults. */
+function deviceCapabilityTarget(toolName) {
+	if (/^(mobile|desktop|web|browser)\.device\./.test(toolName) || /^(mobile|desktop|web)\.(file\.pick|media\.pick|camera\.capture|contacts\.(pick|search|get)|calendar\.query_(events|free_busy))$/.test(toolName) || toolName === "desktop.clipboard.read" || toolName === "web.page.get_selection") return "turn_origin";
+	return "session_bound";
+}
+//#endregion
+export { deviceCapabilityTarget };

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

@@ -0,0 +1,69 @@
+import { type LocationRequest, type TurnOrigin } from '@xopcai/endpoint-tools-protocol';
+import type { DeviceGrantAuditEvent } from '../storage/sqlite/device-grant-audit-repository.js';
+import type { EndpointRegistry } from './registry.js';
+export interface DeviceGrantLease {
+    signal: AbortSignal;
+    complete: () => void;
+}
+interface DeviceGrant {
+    id: string;
+    conversationId: string;
+    requestorPrincipalId: string;
+    targetEndpointId: string;
+    targetPrincipalId: string;
+    arguments: LocationRequest;
+    connectionId: string;
+    toolName: string;
+    argumentsDigest: string;
+    expiresAt: number;
+    state: 'ready' | 'running';
+    controller: AbortController;
+}
+/** Deliberately non-durable: restart, expiry, disconnect or revoke invalidates single-call consent. */
+export declare class DeviceGrantService {
+    private readonly registry;
+    private readonly now;
+    private readonly audit?;
+    private readonly grants;
+    constructor(registry: EndpointRegistry, now?: () => number, audit?: (event: DeviceGrantAuditEvent) => void);
+    issue(input: {
+        conversationId: string;
+        requestorPrincipalId: string;
+        targetEndpointId: string;
+        toolName: string;
+        arguments: Record<string, unknown>;
+    }): {
+        id: string;
+        conversationId: string;
+        requestorPrincipalId: string;
+        targetEndpointId: string;
+        targetPrincipalId: string;
+        arguments: LocationRequest;
+        connectionId: string;
+        toolName: string;
+        expiresAt: number;
+        state: "ready" | "running";
+    };
+    private requestor;
+    candidates(conversationId: string, origin: TurnOrigin): DeviceGrant[];
+    find(conversationId: string, origin: TurnOrigin, endpointId: string, toolName: string): DeviceGrant;
+    reserve(id: string, args: Record<string, unknown>): DeviceGrantLease;
+    list(): {
+        id: string;
+        conversationId: string;
+        requestorPrincipalId: string;
+        targetEndpointId: string;
+        targetPrincipalId: string;
+        arguments: LocationRequest;
+        connectionId: string;
+        toolName: string;
+        expiresAt: number;
+        state: "ready" | "running";
+    }[];
+    revoke(id: string, reason?: 'consumed' | 'revoked' | 'expired'): boolean;
+    revokeEndpoint(endpointId: string, principalId?: string): void;
+    close(): void;
+    private prune;
+    private summary;
+}
+export {};

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

@@ -0,0 +1,113 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { locationRequestSchema } from "../../packages/endpoint-tools-protocol/src/location.js";
+import { canonicalJson, init_src } from "../../packages/endpoint-tools-protocol/src/index.js";
+import { createHash, randomUUID } from "node:crypto";
+//#region src/endpoint-tools/grant-service.ts
+init_src();
+init_logger();
+const grantLog = createLogger("DeviceGrants");
+const digest = (args) => createHash("sha256").update(canonicalJson(args)).digest("hex");
+/** Deliberately non-durable: restart, expiry, disconnect or revoke invalidates single-call consent. */
+var DeviceGrantService = class {
+	grants = /* @__PURE__ */ new Map();
+	constructor(registry, now = Date.now, audit) {
+		this.registry = registry;
+		this.now = now;
+		this.audit = audit;
+	}
+	issue(input) {
+		this.prune();
+		if (this.grants.size >= 100) throw new Error("Too many outstanding device authorizations");
+		const target = this.registry.get(input.targetEndpointId);
+		if (!target || target.availability !== "foreground" || !this.registry.list().some((endpoint) => endpoint.principalId === input.requestorPrincipalId)) throw new Error("Device is offline");
+		if (!/^(mobile|web|desktop)\.device\.get_location$/.test(input.toolName) || !this.registry.getTool(target.endpointId, input.toolName)) throw new Error("Unsupported device authorization");
+		const args = locationRequestSchema.parse(input.arguments);
+		for (const grant of this.grants.values()) if (grant.conversationId === input.conversationId && grant.requestorPrincipalId === input.requestorPrincipalId && grant.toolName === input.toolName) this.revoke(grant.id);
+		const grant = {
+			conversationId: input.conversationId,
+			requestorPrincipalId: input.requestorPrincipalId,
+			targetEndpointId: input.targetEndpointId,
+			toolName: input.toolName,
+			arguments: args,
+			id: randomUUID(),
+			targetPrincipalId: target.principalId,
+			connectionId: target.connectionId,
+			argumentsDigest: digest(args),
+			expiresAt: this.now() + 6e4,
+			state: "ready",
+			controller: new AbortController()
+		};
+		this.audit?.({
+			...grant,
+			event: "issued"
+		});
+		this.grants.set(grant.id, grant);
+		const timer = setTimeout(() => this.revoke(grant.id, "expired"), 6e4);
+		timer.unref();
+		grant.controller.signal.addEventListener("abort", () => clearTimeout(timer), { once: true });
+		return this.summary(grant);
+	}
+	requestor(origin) {
+		return origin.type === "endpoint" ? this.registry.get(origin.endpointId)?.principalId : void 0;
+	}
+	candidates(conversationId, origin) {
+		this.prune();
+		const principal = this.requestor(origin);
+		return [...this.grants.values()].filter((grant) => grant.state === "ready" && grant.conversationId === conversationId && grant.requestorPrincipalId === principal);
+	}
+	find(conversationId, origin, endpointId, toolName) {
+		return this.candidates(conversationId, origin).find((grant) => grant.targetEndpointId === endpointId && grant.toolName === toolName);
+	}
+	reserve(id, args) {
+		this.prune();
+		const grant = this.grants.get(id);
+		if (!grant || grant.state !== "ready" || grant.argumentsDigest !== digest(args)) throw new Error("Device authorization expired, consumed or outside its scope");
+		this.audit?.({
+			...grant,
+			event: "reserved"
+		});
+		grant.state = "running";
+		return {
+			signal: grant.controller.signal,
+			complete: () => this.revoke(id, "consumed")
+		};
+	}
+	list() {
+		this.prune();
+		return [...this.grants.values()].map((grant) => this.summary(grant));
+	}
+	revoke(id, reason = "revoked") {
+		const grant = this.grants.get(id);
+		if (!grant) return false;
+		this.grants.delete(id);
+		grant.controller.abort();
+		try {
+			this.audit?.({
+				...grant,
+				event: reason
+			});
+		} catch (err) {
+			grantLog.error({
+				err,
+				grantId: id
+			}, "Device grant invalidated but audit write failed");
+		}
+		return true;
+	}
+	revokeEndpoint(endpointId, principalId = this.registry.get(endpointId)?.principalId) {
+		for (const grant of this.grants.values()) if (grant.targetEndpointId === endpointId || grant.requestorPrincipalId === principalId) this.revoke(grant.id);
+	}
+	close() {
+		for (const id of this.grants.keys()) this.revoke(id);
+	}
+	prune() {
+		for (const grant of this.grants.values()) if (grant.expiresAt <= this.now() || this.registry.get(grant.targetEndpointId)?.connectionId !== grant.connectionId || !this.registry.list().some((endpoint) => endpoint.principalId === grant.requestorPrincipalId)) this.revoke(grant.id, grant.expiresAt <= this.now() ? "expired" : "revoked");
+	}
+	summary(grant) {
+		const { controller: _controller, argumentsDigest: _digest, ...summary } = grant;
+		return summary;
+	}
+};
+//#endregion
+export { DeviceGrantService };

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

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

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

@@ -33,6 +33,11 @@ var EndpointInvocationService = class {
 		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"));
+		if (!this.ajv.compile(tool.descriptor.inputSchema)(params.arguments)) return Promise.reject(this.error("INVALID_ARGUMENTS", "Invalid endpoint tool arguments"));
+		if (params.toolName.startsWith("mobile.calendar.")) {
+			const { startAt, endAt } = params.arguments;
+			if (typeof startAt !== "number" || typeof endAt !== "number" || endAt <= startAt || endAt - startAt > 7 * 864e5) return Promise.reject(this.error("INVALID_ARGUMENTS", "Calendar range must be positive and at most seven days"));
+		}
 		let confirmationRequired;
 		try {
 			confirmationRequired = this.policy.evaluate(tool.descriptor, endpoint.availability).confirmationRequired;
@@ -42,11 +47,12 @@ var EndpointInvocationService = class {
 		}
 		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 (tool.descriptor.sensitivity === "personal" && tool.descriptor.requiresForeground && endpointPending.some((item) => item.descriptor.sensitivity === "personal" && item.descriptor.requiresForeground)) return Promise.reject(this.error("TOOL_BUSY", "A personal device request is already awaiting user participation"));
 		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, params.toolName === "desktop.computer.control" ? "computer-frame" : "durable") : void 0;
+		const uploadGrant = tool.descriptor.resultKinds.includes("file") ? this.options.uploads?.createGrant(invocationId, params.endpointId, startedAt, params.toolName === "desktop.computer.control" ? "computer-frame" : params.toolName.startsWith("mobile.") ? "personal" : "durable", endpoint.principalId) : void 0;
 		try {
 			this.options.audit?.started({
 				id: invocationId,
@@ -69,6 +75,7 @@ var EndpointInvocationService = class {
 				endpointId: params.endpointId,
 				toolName: params.toolName,
 				descriptor: tool.descriptor,
+				arguments: params.arguments,
 				state: "sent",
 				receiptTimer: setTimeout(() => {
 					this.fail(invocationId, this.error("TOOL_TIMEOUT", "Endpoint did not receive the invocation"));
@@ -113,6 +120,7 @@ var EndpointInvocationService = class {
 				clearTimeout(pending.receiptTimer);
 				return;
 			case "tool.progress":
+				if (pending.descriptor.sensitivity === "personal" && pending.descriptor.effect === "read") return;
 				if (pending.state !== "running") return;
 				pending.onProgress?.({
 					...message.payload.message === void 0 ? {} : { message: message.payload.message },
@@ -124,18 +132,27 @@ var EndpointInvocationService = class {
 				try {
 					const validate = this.ajv.compile(pending.descriptor.outputSchema);
 					if (!validate(message.payload.content)) throw new Error(`Endpoint result does not match its contract: ${this.ajv.errorsText(validate.errors)}`);
+					const reading = message.payload.content[0];
+					if (pending.toolName.startsWith("mobile.calendar.") && reading?.type === "json") {
+						const value = reading.value;
+						if (value.startAt !== pending.arguments.startAt || value.endAt !== pending.arguments.endAt || value.events.some((event) => event.endAt <= event.startAt || event.endAt <= value.startAt || event.startAt >= value.endAt) || pending.toolName.endsWith("free_busy") && value.events.some((event) => event.title !== void 0)) throw new Error("Calendar result exceeded the approved scope");
+					}
+					if (pending.toolName === "mobile.contacts.pick" && reading?.type === "json" && pending.arguments.field) {
+						const value = reading.value;
+						if (pending.arguments.field === "phone" && (value.phones.length > 1 || value.emails.length) || pending.arguments.field === "email" && (value.emails.length > 1 || value.phones.length)) throw new Error("Contact result exceeded the selected field");
+					}
 					this.options.uploads?.validateAndClose(invocationId, message.payload.content);
 				} catch (error) {
-					this.fail(invocationId, this.error("PROTOCOL_ERROR", error instanceof Error ? error.message : String(error)));
+					this.fail(invocationId, this.error("PROTOCOL_ERROR", pending.descriptor.sensitivity === "personal" && pending.descriptor.effect === "read" ? "Invalid personal device result" : error instanceof Error ? error.message : String(error)));
 					return;
 				}
 				this.succeed(invocationId, {
 					content: message.payload.content,
-					...message.payload.details === void 0 ? {} : { details: message.payload.details }
+					...message.payload.details === void 0 || pending.descriptor.sensitivity === "personal" && pending.descriptor.effect === "read" ? {} : { details: message.payload.details }
 				});
 				return;
 			case "tool.error":
-				this.fail(invocationId, this.error(message.payload.code, message.payload.message));
+				this.fail(invocationId, this.error(message.payload.code, pending.descriptor.sensitivity === "personal" && pending.descriptor.effect === "read" ? `Personal device request failed: ${message.payload.code}` : message.payload.message));
 				return;
 			case "tool.cancelled": this.fail(invocationId, this.error("TOOL_CANCELLED", "Endpoint cancelled the tool call"));
 		}

package/dist/src/endpoint-tools/location-task.d.ts

@@ -0,0 +1,22 @@
+import { type EndpointToolContent } from '@xopcai/endpoint-tools-protocol';
+/** Sensitive samples never leave this processor as model, stream or persistence content. */
+export declare function processLocationTask(args: Record<string, unknown>, content: EndpointToolContent[], source: {
+    endpointId: string;
+    principalId: string;
+}, signal?: AbortSignal, request?: typeof fetch, now?: () => number): Promise<{
+    version: number;
+    source: {
+        endpointId: string;
+        principalId: string;
+    };
+    capturedAt: number;
+    receivedAt: number;
+    validUntil: number;
+    cached: boolean;
+    retention: string;
+    purpose: "weather" | "nearby";
+    precision: string;
+    accuracyMeters: number;
+    status: string;
+    data: Record<string, unknown>;
+}>;