@xopcai/xopc 0.0.368 → 0.0.370

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

@@ -0,0 +1,15 @@
+import { type EndpointToolRegistry } from '@xopcai/endpoint-tools-client';
+export interface DeviceBridgeHostOptions {
+    gatewayUrl: string;
+    token: string;
+    identityPath: string;
+    registry: EndpointToolRegistry;
+    displayName?: string;
+    onStateChange?: (state: string) => void;
+}
+/** Connects a Node hardware adapter through the existing signed Endpoint v2 transport. */
+export declare function connectDeviceBridge(options: DeviceBridgeHostOptions): Promise<{
+    endpointId: string;
+    principalId: string;
+    close: () => void;
+}>;

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) || 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,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 };