@xopcai/xopc 0.0.369 → 0.0.370

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,9 @@ 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 (params.toolName.endsWith(".device.get_location")) {
+			if (!this.ajv.compile(tool.descriptor.inputSchema)(params.arguments)) return Promise.reject(this.error("INVALID_ARGUMENTS", "Invalid location task request"));
+		}
 		let confirmationRequired;
 		try {
 			confirmationRequired = this.policy.evaluate(tool.descriptor, endpoint.availability).confirmationRequired;
@@ -113,6 +116,7 @@ var EndpointInvocationService = class {
 				clearTimeout(pending.receiptTimer);
 				return;
 			case "tool.progress":
+				if (pending.toolName.endsWith(".device.get_location")) return;
 				if (pending.state !== "running") return;
 				pending.onProgress?.({
 					...message.payload.message === void 0 ? {} : { message: message.payload.message },
@@ -126,7 +130,7 @@ var EndpointInvocationService = class {
 					if (!validate(message.payload.content)) throw new Error(`Endpoint result does not match its contract: ${this.ajv.errorsText(validate.errors)}`);
 					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.toolName.endsWith(".device.get_location") ? "Invalid location result" : error instanceof Error ? error.message : String(error)));
 					return;
 				}
 				this.succeed(invocationId, {
@@ -135,7 +139,7 @@ var EndpointInvocationService = class {
 				});
 				return;
 			case "tool.error":
-				this.fail(invocationId, this.error(message.payload.code, message.payload.message));
+				this.fail(invocationId, this.error(message.payload.code, pending.toolName.endsWith(".device.get_location") ? `Location 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>;
+}>;

package/dist/src/endpoint-tools/location-task.js

@@ -0,0 +1,114 @@
+import { locationRequestSchema, locationSampleSchema } from "../../packages/endpoint-tools-protocol/src/location.js";
+import { init_src } from "../../packages/endpoint-tools-protocol/src/index.js";
+//#region src/endpoint-tools/location-task.ts
+init_src();
+const WEATHER_URL = "https://api.open-meteo.com/v1/forecast";
+const PLACES_URL = "https://overpass-api.de/api/interpreter";
+const CATEGORY_FILTER = {
+	restaurant: "amenity=restaurant",
+	cafe: "amenity=cafe",
+	pharmacy: "amenity=pharmacy",
+	park: "leisure=park"
+};
+/** Sensitive samples never leave this processor as model, stream or persistence content. */
+async function processLocationTask(args, content, source, signal, request = fetch, now = Date.now) {
+	const input = locationRequestSchema.parse(args);
+	if (content.length !== 1 || content[0].type !== "json") throw new Error("Invalid location sample");
+	const sample = locationSampleSchema.parse(content[0].value);
+	if (sample.capturedAt < now() - 3e4 || sample.capturedAt > now() + 6e4) throw new Error("Location sample expired or has an invalid clock");
+	const approximate = input.precision === "approximate" || sample.precision === "approximate";
+	const latitude = approximate ? Math.round(sample.latitude * 50) / 50 : sample.latitude;
+	const longitude = approximate ? Math.round(sample.longitude * 50) / 50 : sample.longitude;
+	const scopedSignal = AbortSignal.any([signal ?? new AbortController().signal, AbortSignal.timeout(15e3)]);
+	const readResponse = async (response) => {
+		if (!response.ok || response.redirected) throw new Error("Location lookup service is unavailable");
+		const reader = response.body?.getReader();
+		if (!reader) throw new Error("Location lookup service returned no data");
+		let bytes = 0;
+		const chunks = [];
+		try {
+			while (true) {
+				const part = await reader.read();
+				if (part.done) break;
+				bytes += part.value.length;
+				if (bytes > 512e3) throw new Error("Location lookup response is too large");
+				chunks.push(part.value);
+			}
+		} finally {
+			await reader.cancel().catch(() => {});
+		}
+		const joined = new Uint8Array(bytes);
+		let offset = 0;
+		for (const chunk of chunks) {
+			joined.set(chunk, offset);
+			offset += chunk.length;
+		}
+		return JSON.parse(new TextDecoder().decode(joined));
+	};
+	let data;
+	try {
+		scopedSignal.throwIfAborted();
+		if (input.purpose === "weather") {
+			const url = new URL(WEATHER_URL);
+			url.searchParams.set("latitude", String(latitude));
+			url.searchParams.set("longitude", String(longitude));
+			url.searchParams.set("current", "temperature_2m,relative_humidity_2m,weather_code,wind_speed_10m");
+			const current = (await readResponse(await request(url, {
+				signal: scopedSignal,
+				redirect: "error"
+			}))).current ?? {};
+			if (typeof current.temperature_2m !== "number" || !Number.isFinite(current.temperature_2m)) throw new Error("Invalid weather response");
+			const numeric = (key, min, max) => typeof current[key] === "number" && Number.isFinite(current[key]) && current[key] >= min && current[key] <= max ? current[key] : null;
+			data = {
+				provider: "Open-Meteo",
+				sourceUrl: "https://open-meteo.com/",
+				temperatureCelsius: numeric("temperature_2m", -100, 100),
+				humidityPercent: numeric("relative_humidity_2m", 0, 100),
+				weatherCode: numeric("weather_code", 0, 99),
+				windSpeedKmh: numeric("wind_speed_10m", 0, 500)
+			};
+		} else {
+			const query = `[out:json][timeout:10];nwr(around:2000,${latitude},${longitude})[${CATEGORY_FILTER[input.category]}];out tags 10;`;
+			const response = await readResponse(await request(PLACES_URL, {
+				method: "POST",
+				signal: scopedSignal,
+				redirect: "error",
+				headers: { "Content-Type": "application/x-www-form-urlencoded" },
+				body: new URLSearchParams({ data: query })
+			}));
+			if (!Array.isArray(response.elements)) throw new Error("Invalid nearby service result");
+			const text = (value) => typeof value === "string" ? value.slice(0, 160).replaceAll(String(sample.latitude), "[location]").replaceAll(String(sample.longitude), "[location]") : "";
+			data = {
+				provider: "OpenStreetMap",
+				sourceUrl: "https://www.openstreetmap.org/",
+				category: input.category,
+				radiusMeters: 2e3,
+				places: response.elements.slice(0, 10).map((element) => ({
+					name: text(element.tags?.name),
+					street: text(element.tags?.["addr:street"]),
+					houseNumber: text(element.tags?.["addr:housenumber"])
+				})).filter((place) => place.name.length > 0)
+			};
+		}
+	} catch {
+		throw new Error(scopedSignal.aborted ? "Location lookup cancelled or timed out" : "Location lookup service is unavailable");
+	}
+	scopedSignal.throwIfAborted();
+	if (sample.capturedAt < now() - 3e4) throw new Error("Location sample expired during lookup");
+	return {
+		version: 1,
+		source,
+		capturedAt: sample.capturedAt,
+		receivedAt: now(),
+		validUntil: Math.min(sample.capturedAt, now()) + 3e4,
+		cached: false,
+		retention: "summary",
+		purpose: input.purpose,
+		precision: approximate ? "approximate" : "precise",
+		accuracyMeters: approximate ? Math.max(3e3, sample.accuracyMeters) : sample.accuracyMeters,
+		status: "ok",
+		data
+	};
+}
+//#endregion
+export { processLocationTask };

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

@@ -1,4 +1,6 @@
-import { ENDPOINT_CONTACT_LIST_OUTPUT_SCHEMA, ENDPOINT_CONTACT_OUTPUT_SCHEMA, ENDPOINT_FILE_OUTPUT_SCHEMA, ENDPOINT_TEXT_OUTPUT_SCHEMA, canonicalJson, init_src } from "../../packages/endpoint-tools-protocol/src/index.js";
+import { BRIDGE_LIST_OUTPUT_SCHEMA, BRIDGE_READ_INPUT_SCHEMA, BRIDGE_READ_OUTPUT_SCHEMA } from "../../packages/endpoint-tools-protocol/src/bridge.js";
+import { LOCATION_INPUT_SCHEMA, LOCATION_OUTPUT_SCHEMA } from "../../packages/endpoint-tools-protocol/src/location.js";
+import { DEVICE_EMPTY_INPUT_SCHEMA, DEVICE_POWER_OUTPUT_SCHEMA, DEVICE_STATE_OUTPUT_SCHEMA, ENDPOINT_CONTACT_LIST_OUTPUT_SCHEMA, ENDPOINT_CONTACT_OUTPUT_SCHEMA, ENDPOINT_FILE_OUTPUT_SCHEMA, ENDPOINT_TEXT_OUTPUT_SCHEMA, canonicalJson, init_src } from "../../packages/endpoint-tools-protocol/src/index.js";
 import { COMPUTER_INPUT_SCHEMA, COMPUTER_OUTPUT_SCHEMA, init_src as init_src$1 } from "../../packages/computer-control-contract/src/index.js";
 import { BROWSER_CONTROL_ENDPOINT_DESCRIPTOR, BROWSER_CONTROL_ENDPOINT_INPUT_SCHEMA, BROWSER_CONTROL_ENDPOINT_OUTPUT_SCHEMA, BROWSER_RECORDING_ENDPOINT_DESCRIPTOR, BROWSER_RECORDING_ENDPOINT_INPUT_SCHEMA } from "../../packages/browser-control-contract/src/index.js";
 import Ajv2020 from "ajv/dist/2020.js";
@@ -17,6 +19,19 @@ function contract(policyId, outputSchema, resultKinds, permissions, legacyPolicy
 	};
 }
 const POLICY_BY_TOOL = {
+	...Object.fromEntries([
+		"mobile",
+		"desktop",
+		"web",
+		"browser"
+	].flatMap((kind) => [[`${kind}.device.get_state`, contract("public.background-read", DEVICE_STATE_OUTPUT_SCHEMA, ["json"], [], [], DEVICE_EMPTY_INPUT_SCHEMA)], [`${kind}.device.get_power`, contract("public.background-read", DEVICE_POWER_OUTPUT_SCHEMA, ["json"], [], [], DEVICE_EMPTY_INPUT_SCHEMA)]])),
+	...Object.fromEntries([
+		"mobile",
+		"desktop",
+		"web"
+	].map((kind) => [`${kind}.device.get_location`, contract("personal.foreground-read", LOCATION_OUTPUT_SCHEMA, ["json"], ["location-read-once"], [], LOCATION_INPUT_SCHEMA)])),
+	"desktop.bridge.list_resources": contract("public.background-read", BRIDGE_LIST_OUTPUT_SCHEMA, ["json"], [], [], DEVICE_EMPTY_INPUT_SCHEMA),
+	"desktop.bridge.read_sensor": contract("public.background-read", BRIDGE_READ_OUTPUT_SCHEMA, ["json"], [], [], BRIDGE_READ_INPUT_SCHEMA),
 	"desktop.computer.control": contract("computer.session-scoped", COMPUTER_OUTPUT_SCHEMA, ["json", "file"], ["computer-control"], [], COMPUTER_INPUT_SCHEMA),
 	"web.file.pick": contract("personal.foreground-read", ENDPOINT_FILE_OUTPUT_SCHEMA, ["file"], ["file-read"]),
 	"web.file.download": contract("user.foreground-write", ENDPOINT_TEXT_OUTPUT_SCHEMA, ["text"], ["file-download"]),

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

@@ -29,6 +29,8 @@ export declare function endpointToolRevision(descriptor: EndpointToolDescriptor)
 export declare class EndpointRegistry {
     private readonly policy;
     private readonly connectionByEndpointId;
+    private readonly changeListeners;
+    onChange(listener: (endpointId: string) => void): () => void;
     constructor(policy?: EndpointToolPolicy);
     register(hello: EndpointHelloPayload, connectionId: string, transport: EndpointTransport, now?: number): EndpointRegistration;
     remove(endpointId: string, connectionId: string): boolean;

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

@@ -22,6 +22,13 @@ function snapshot(connection) {
 }
 var EndpointRegistry = class {
 	connectionByEndpointId = /* @__PURE__ */ new Map();
+	changeListeners = /* @__PURE__ */ new Set();
+	onChange(listener) {
+		this.changeListeners.add(listener);
+		return () => {
+			this.changeListeners.delete(listener);
+		};
+	}
 	constructor(policy = new EndpointToolPolicy()) {
 		this.policy = policy;
 	}
@@ -54,6 +61,7 @@ var EndpointRegistry = class {
 			toolByName
 		};
 		this.connectionByEndpointId.set(connection.endpointId, connection);
+		for (const listener of this.changeListeners) listener(connection.endpointId);
 		return {
 			connection: snapshot(connection),
 			turnToken: connection.turnToken
@@ -63,6 +71,7 @@ var EndpointRegistry = class {
 		const connection = this.connectionByEndpointId.get(endpointId);
 		if (!connection || connection.connectionId !== connectionId) return false;
 		this.connectionByEndpointId.delete(endpointId);
+		for (const listener of this.changeListeners) listener(endpointId);
 		return true;
 	}
 	heartbeat(endpointId, connectionId, availability, now = Date.now()) {

package/dist/src/endpoint-tools/result-projector.d.ts

@@ -0,0 +1,15 @@
+import type { EndpointToolContent } from '@xopcai/endpoint-tools-protocol';
+/** Only fixed bounded state contracts are retained; personal tools use their existing policies. */
+export declare function projectDeviceReading(toolName: string, endpointId: string, principalId: string, content: EndpointToolContent[], receivedAt?: number, args?: Record<string, unknown>): {
+    version: number;
+    source: {
+        resourceId?: unknown;
+        endpointId: string;
+        principalId: string;
+    };
+    capturedAt: number;
+    receivedAt: number;
+    validUntil: number;
+    cached: boolean;
+    data: object;
+};

package/dist/src/endpoint-tools/result-projector.js

@@ -0,0 +1,31 @@
+//#region src/endpoint-tools/result-projector.ts
+/** Only fixed bounded state contracts are retained; personal tools use their existing policies. */
+function projectDeviceReading(toolName, endpointId, principalId, content, receivedAt = Date.now(), args) {
+	const sensor = toolName === "desktop.bridge.read_sensor";
+	if (!sensor && !/^(mobile|desktop|web|browser)\.device\.get_(state|power)$/.test(toolName)) return void 0;
+	const item = content[0];
+	if (item?.type !== "json" || !item.value || typeof item.value !== "object") throw new Error("Invalid device reading");
+	if (sensor) {
+		const reading = item.value;
+		if (reading.resourceId !== args?.resourceId) throw new Error("Bridge returned a different resource");
+		const expectedUnit = reading.measurement === "humidity" ? "percent" : "celsius";
+		if (reading.unit !== expectedUnit || reading.measurement === "humidity" && reading.value !== null && (typeof reading.value !== "number" || reading.value < 0 || reading.value > 100)) throw new Error("Invalid Bridge measurement");
+	}
+	const capturedAt = item.value.capturedAt;
+	if (typeof capturedAt !== "number" || !Number.isSafeInteger(capturedAt) || capturedAt > receivedAt + 6e4 || capturedAt < receivedAt - 3e4) throw new Error("Device sample is stale or has an invalid clock");
+	return {
+		version: 1,
+		source: {
+			endpointId,
+			principalId,
+			...sensor ? { resourceId: item.value.resourceId } : {}
+		},
+		capturedAt,
+		receivedAt,
+		validUntil: Math.min(receivedAt, capturedAt) + 3e4,
+		cached: false,
+		data: item.value
+	};
+}
+//#endregion
+export { projectDeviceReading };

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

@@ -1,11 +1,13 @@
 import { type ClientEndpointMessage, type EndpointHelloPayload } from '@xopcai/endpoint-tools-protocol';
 import { type EndpointAuthenticatorDeps } from './auth.js';
+import { DeviceGrantService } from './grant-service.js';
 import { EndpointBindingService } from './binding-service.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 grants: DeviceGrantService;
     readonly invocations: EndpointInvocationService;
     readonly uploads: EndpointUploadService;
     readonly bindings: EndpointBindingService;

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

@@ -7,10 +7,12 @@ import { bindEndpointPrincipal, getEndpointPrincipal, touchEndpointPrincipal } f
 import { finishEndpointToolInvocationAudit, startEndpointToolInvocationAudit } from "../storage/sqlite/endpoint-tool-invocation-repository.js";
 import { init_sqlite } from "../storage/sqlite/index.js";
 import { init_paths } from "../config/paths.js";
-import { EndpointAuthenticator } from "./auth.js";
-import { EndpointBindingService } from "./binding-service.js";
 import { EndpointToolPolicy } from "./policy.js";
 import { EndpointInvocationService } from "./invocation-service.js";
+import { EndpointAuthenticator } from "./auth.js";
+import { EndpointBindingService } from "./binding-service.js";
+import { DeviceGrantService } from "./grant-service.js";
+import { recordDeviceGrantEvent } from "../storage/sqlite/device-grant-audit-repository.js";
 import { EndpointRegistry } from "./registry.js";
 import { EndpointUploadService } from "./upload-service.js";
 import { join } from "node:path";
@@ -22,6 +24,7 @@ const log = createLogger("EndpointTools");
 const MAX_MESSAGE_CLOCK_SKEW_MS = 6e4;
 var EndpointToolRuntime = class {
 	registry;
+	grants;
 	invocations;
 	uploads;
 	bindings;
@@ -30,6 +33,7 @@ var EndpointToolRuntime = class {
 	constructor(options = {}) {
 		const policy = new EndpointToolPolicy();
 		this.registry = new EndpointRegistry(policy);
+		this.grants = new DeviceGrantService(this.registry, Date.now, recordDeviceGrantEvent);
 		this.bindings = new EndpointBindingService(this.registry, {
 			get: getEndpointSessionBinding,
 			set: setEndpointSessionBinding,
@@ -53,6 +57,11 @@ var EndpointToolRuntime = class {
 	connect(hello, connectionId, transport) {
 		if (this.closed) throw new Error("Endpoint runtime is closed");
 		this.authenticator.authenticate(hello);
+		const previous = this.registry.get(hello.endpointId);
+		if (previous) {
+			this.grants.revokeEndpoint(previous.endpointId, previous.principalId);
+			this.invocations.failEndpoint(previous.endpointId);
+		}
 		const registration = this.registry.register(hello, connectionId, transport);
 		log.info({
 			endpointId: hello.endpointId,
@@ -75,7 +84,9 @@ var EndpointToolRuntime = class {
 		if (endpoint?.connectionId === connectionId) this.registry.heartbeat(endpointId, connectionId, endpoint.availability);
 	}
 	remove(endpointId, connectionId) {
+		const principalId = this.registry.get(endpointId)?.principalId;
 		if (!this.registry.remove(endpointId, connectionId)) return;
+		this.grants.revokeEndpoint(endpointId, principalId);
 		this.invocations.failEndpoint(endpointId);
 		deleteBrowserTabBindingsByEndpoint(endpointId);
 		log.info({
@@ -84,11 +95,13 @@ var EndpointToolRuntime = class {
 		}, "Endpoint disconnected");
 	}
 	disconnect(endpointId, reason) {
+		this.grants.revokeEndpoint(endpointId);
 		this.registry.disconnect(endpointId, 4003, reason);
 	}
 	close() {
 		if (this.closed) return;
 		this.closed = true;
+		this.grants.close();
 		this.invocations.close();
 		this.uploads.close();
 		this.registry.closeAll();

package/dist/src/endpoint-tools/target-resolver.d.ts

@@ -0,0 +1,12 @@
+import type { TurnOrigin } from '@xopcai/endpoint-tools-protocol';
+import type { DeviceGrantService } from './grant-service.js';
+import type { EndpointBindingService } from './binding-service.js';
+import type { EndpointRegistry } from './registry.js';
+export declare class DeviceTargetResolver {
+    private readonly registry;
+    private readonly bindings;
+    private readonly grants?;
+    constructor(registry: EndpointRegistry, bindings: EndpointBindingService, grants?: DeviceGrantService);
+    candidates(conversationId: string, origin: TurnOrigin): import("./registry.js").EndpointConnectionSnapshot[];
+    resolve(conversationId: string, origin: TurnOrigin, endpointId: string, toolName: string): import("./registry.js").EndpointConnectionSnapshot;
+}

package/dist/src/endpoint-tools/target-resolver.js

@@ -0,0 +1,27 @@
+import { deviceCapabilityTarget } from "./capability-catalog.js";
+//#region src/endpoint-tools/target-resolver.ts
+var DeviceTargetResolver = class {
+	constructor(registry, bindings, grants) {
+		this.registry = registry;
+		this.bindings = bindings;
+		this.grants = grants;
+	}
+	candidates(conversationId, origin) {
+		const source = origin.type === "endpoint" ? this.registry.get(origin.endpointId) : void 0;
+		const execution = this.bindings.get(conversationId) ? this.bindings.resolve(conversationId) : source;
+		const authorized = (this.grants?.candidates(conversationId, origin) ?? []).map((grant) => this.registry.get(grant.targetEndpointId));
+		return [...new Map([
+			source,
+			execution,
+			...authorized
+		].filter((endpoint) => endpoint !== void 0).map((endpoint) => [endpoint.endpointId, endpoint])).values()];
+	}
+	resolve(conversationId, origin, endpointId, toolName) {
+		const grant = this.grants?.find(conversationId, origin, endpointId, toolName);
+		if (grant) return this.registry.get(grant.targetEndpointId);
+		const binding = this.bindings.get(conversationId);
+		return (deviceCapabilityTarget(toolName) === "turn_origin" ? origin.type === "endpoint" ? origin.endpointId : void 0 : binding?.endpointId ?? (origin.type === "endpoint" ? origin.endpointId : void 0)) === endpointId ? this.registry.get(endpointId) : void 0;
+	}
+};
+//#endregion
+export { DeviceTargetResolver };

package/dist/src/endpoint-tools/turn-context.d.ts

@@ -0,0 +1,6 @@
+import type { EndpointContext } from '@xopcai/gateway-contract';
+import type { AgentSourceContext } from '../agent/source-context/types.js';
+import type { GatewayPrincipal } from '../gateway/security/gateway-principal.js';
+import type { EndpointConnectionSnapshot, EndpointRegistry } from './registry.js';
+export declare function endpointClaimBelongsToPrincipal(registry: EndpointRegistry, endpointId: string, principal: GatewayPrincipal): boolean;
+export declare function deviceTurnSourceContext(endpoint: EndpointConnectionSnapshot, environment?: EndpointContext): AgentSourceContext;

package/dist/src/endpoint-tools/turn-context.js

@@ -0,0 +1,29 @@
+import { getEndpointDeviceSettings } from "../storage/sqlite/endpoint-device-settings-repository.js";
+import { createHash } from "node:crypto";
+//#region src/endpoint-tools/turn-context.ts
+function endpointClaimBelongsToPrincipal(registry, endpointId, principal) {
+	const endpoint = registry.get(endpointId);
+	return Boolean(endpoint && (principal.kind === "owner" || principal.kind === "device" && endpoint.principalId === principal.deviceId));
+}
+function deviceTurnSourceContext(endpoint, environment) {
+	const name = getEndpointDeviceSettings(endpoint.principalId)?.nickname ?? endpoint.displayName;
+	const snapshot = {
+		endpointId: endpoint.endpointId,
+		principalId: endpoint.principalId,
+		name: name.slice(0, 80),
+		platform: endpoint.platform.slice(0, 40),
+		kind: endpoint.kind,
+		...environment ? { environment } : {}
+	};
+	const text = JSON.stringify(snapshot).replaceAll("<", "\\u003c").replaceAll(">", "\\u003e");
+	return {
+		kind: "device_context",
+		sourceId: endpoint.endpointId,
+		version: createHash("sha256").update(text).digest("hex"),
+		title: name.slice(0, 80),
+		text,
+		capturedAt: environment?.capturedAt ?? Date.now()
+	};
+}
+//#endregion
+export { deviceTurnSourceContext, endpointClaimBelongsToPrincipal };

package/dist/src/extensions/agent-plugins/auth.d.ts

@@ -4,9 +4,7 @@ import { type PluginServer } from './validation.js';
 declare const bindingSchema: z.ZodObject<{
     serverName: z.ZodString;
     mode: z.ZodEnum<{
-        none: "none";
         auto: "auto";
-        oauth: "oauth";
         "api-key": "api-key";
     }>;
     identityScope: z.ZodLiteral<"owner">;