@xopcai/xopc 0.0.421 → 0.0.422

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

@@ -0,0 +1,29 @@
+import { type EndpointContextView } from '@xopcai/endpoint-tools-protocol';
+import type { EndpointRegistry } from './registry.js';
+export declare class EndpointContextError extends Error {
+    readonly code: 'CONTEXT_INVALID' | 'CONTEXT_CONFLICT' | 'SOURCE_UNAVAILABLE';
+    constructor(code: 'CONTEXT_INVALID' | 'CONTEXT_CONFLICT' | 'SOURCE_UNAVAILABLE', message: string);
+}
+/** Bounded, process-local observations. Heartbeats never refresh field timestamps. */
+export declare class EndpointContextStore {
+    private readonly registry;
+    private readonly now;
+    private readonly snapshots;
+    private readonly unsubscribe;
+    constructor(registry: EndpointRegistry, now?: () => number);
+    private require;
+    connection(endpointId: string): {
+        connectionEpoch: string;
+        revision: number;
+        reportSequence: number;
+        heartbeatSequence: number;
+    };
+    report(endpointId: string, input: unknown): {
+        revision: number;
+    };
+    heartbeat(endpointId: string, input: unknown): {
+        revision: number;
+    };
+    view(endpointId: string): EndpointContextView | undefined;
+    close(): void;
+}

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

@@ -0,0 +1,138 @@
+import { ENDPOINT_CONTEXT_OFFLINE_MS, endpointContextHeartbeatSchema, endpointContextReportSchema } from "../../packages/endpoint-tools-protocol/src/context.js";
+import { canonicalJson, init_src } from "../../packages/endpoint-tools-protocol/src/index.js";
+import { createHash } from "node:crypto";
+//#region src/endpoint-tools/context-store.ts
+init_src();
+var EndpointContextError = class extends Error {
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+/** Bounded, process-local observations. Heartbeats never refresh field timestamps. */
+var EndpointContextStore = class {
+	snapshots = /* @__PURE__ */ new Map();
+	unsubscribe;
+	constructor(registry, now = Date.now) {
+		this.registry = registry;
+		this.now = now;
+		this.unsubscribe = registry.onChange((endpointId, reason) => {
+			this.snapshots.delete(endpointId);
+			const endpoint = registry.get(endpointId);
+			if (reason === "authorization" || !endpoint) return;
+			if (this.snapshots.size >= 256) return;
+			this.snapshots.set(endpointId, {
+				epoch: endpoint.connectionId,
+				revision: 0,
+				sequence: 0,
+				heartbeatSequence: 0,
+				lastSeenAt: 0,
+				availability: "background",
+				fields: /* @__PURE__ */ new Map(),
+				receipts: /* @__PURE__ */ new Map()
+			});
+		});
+	}
+	require(endpointId) {
+		const state = this.snapshots.get(endpointId);
+		if (!state || this.registry.get(endpointId)?.connectionId !== state.epoch) throw new EndpointContextError("SOURCE_UNAVAILABLE", "Context source is unavailable");
+		return state;
+	}
+	connection(endpointId) {
+		const state = this.require(endpointId);
+		return {
+			connectionEpoch: state.epoch,
+			revision: state.revision,
+			reportSequence: state.sequence,
+			heartbeatSequence: state.heartbeatSequence
+		};
+	}
+	report(endpointId, input) {
+		const parsed = endpointContextReportSchema.safeParse(input);
+		if (!parsed.success) throw new EndpointContextError("CONTEXT_INVALID", "Invalid endpoint context report");
+		const report = parsed.data;
+		const state = this.require(endpointId);
+		if (report.connectionEpoch !== state.epoch) throw new EndpointContextError("SOURCE_UNAVAILABLE", "Context connection changed");
+		const digest = createHash("sha256").update(canonicalJson(report)).digest("hex");
+		const receipt = state.receipts.get(report.reportId);
+		if (receipt) {
+			if (receipt.digest !== digest) throw new EndpointContextError("CONTEXT_CONFLICT", "Report identity was reused");
+			return { revision: receipt.revision };
+		}
+		if (report.sequence <= state.sequence || report.mode === "patch" && report.baseRevision !== state.revision) throw new EndpointContextError("CONTEXT_CONFLICT", "Context baseline or sequence changed; send a full report");
+		const now = this.now();
+		if (report.capturedAt > now + 6e4 || report.capturedAt < now - 3e4) throw new EndpointContextError("CONTEXT_INVALID", "Context sample is stale or has an invalid clock");
+		const fields = report.mode === "full" ? /* @__PURE__ */ new Map() : new Map(state.fields);
+		for (const key of report.cleared) fields.delete(key);
+		for (const [key, value] of Object.entries(report.values)) {
+			if (value === void 0) continue;
+			const field = key;
+			const prior = state.fields.get(field);
+			if (prior && report.capturedAt < prior.capturedAt) throw new EndpointContextError("CONTEXT_CONFLICT", "Context sample moved backwards");
+			if (prior && report.capturedAt === prior.capturedAt) {
+				if (canonicalJson(prior.value) !== canonicalJson(value)) throw new EndpointContextError("CONTEXT_CONFLICT", "Context sample identity changed");
+				fields.set(field, prior);
+				continue;
+			}
+			fields.set(field, {
+				value: structuredClone(value),
+				capturedAt: report.capturedAt,
+				receivedAt: now,
+				validUntil: Math.min(report.capturedAt, now) + (field === "device.power" ? 3e4 : 3e5)
+			});
+		}
+		state.fields = fields;
+		state.sequence = report.sequence;
+		state.revision += 1;
+		state.receipts.set(report.reportId, {
+			digest,
+			revision: state.revision
+		});
+		if (state.receipts.size > 64) state.receipts.delete(state.receipts.keys().next().value);
+		return { revision: state.revision };
+	}
+	heartbeat(endpointId, input) {
+		const parsed = endpointContextHeartbeatSchema.safeParse(input);
+		if (!parsed.success) throw new EndpointContextError("CONTEXT_INVALID", "Invalid context heartbeat");
+		const state = this.require(endpointId);
+		if (parsed.data.connectionEpoch !== state.epoch || parsed.data.sequence <= state.heartbeatSequence) throw new EndpointContextError("CONTEXT_CONFLICT", "Context heartbeat connection or sequence changed");
+		state.heartbeatSequence = parsed.data.sequence;
+		state.lastSeenAt = this.now();
+		state.availability = parsed.data.availability;
+		return { revision: state.revision };
+	}
+	view(endpointId) {
+		let state;
+		try {
+			state = this.require(endpointId);
+		} catch {
+			return;
+		}
+		const now = this.now();
+		const availability = state.lastSeenAt === 0 || now - state.lastSeenAt >= 45e3 ? "offline" : this.registry.get(endpointId)?.kind !== "browser" && this.registry.get(endpointId)?.availability === "background" ? "background" : state.availability;
+		const fields = {};
+		for (const [key, reading] of state.fields) {
+			const status = availability !== "foreground" ? "unavailable" : reading.validUntil <= now ? "stale" : "fresh";
+			fields[key] = {
+				status,
+				capturedAt: reading.capturedAt,
+				validUntil: reading.validUntil,
+				...status === "fresh" ? { value: structuredClone(reading.value) } : {}
+			};
+		}
+		return {
+			version: 1,
+			endpointId,
+			revision: state.revision,
+			availability,
+			sourceValidUntil: state.lastSeenAt + ENDPOINT_CONTEXT_OFFLINE_MS,
+			fields
+		};
+	}
+	close() {
+		this.unsubscribe();
+		this.snapshots.clear();
+	}
+};
+//#endregion
+export { EndpointContextError, EndpointContextStore };

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

@@ -0,0 +1,42 @@
+import { type LocationSample, type LocationShareRequest, type LocationShareSummary } from '@xopcai/endpoint-tools-protocol';
+import type { EndpointRegistry } from './registry.js';
+import type { EndpointContextStore } from './context-store.js';
+export declare class LocationSharingError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface LocationConsumer {
+    apply(input: {
+        shareId: string;
+        conversationId: string;
+        phoneId: string;
+        sample: LocationSample;
+        validUntil: number;
+        assertCurrent(): void;
+    }, signal: AbortSignal): Promise<void>;
+    clear(shareId: string, phoneId: string): Promise<boolean>;
+    state?(shareId: string, phoneId: string): LocationShareSummary['sync'];
+}
+/** Explicitly authorized coordinates remain transient and are never part of public context values. */
+export declare class LocationSharingService {
+    private readonly registry;
+    private readonly contexts;
+    private readonly now;
+    private readonly shares;
+    private consumer?;
+    private readonly timer;
+    private readonly unsubscribe;
+    constructor(registry: EndpointRegistry, contexts: EndpointContextStore, now?: () => number);
+    setConsumer(consumer: LocationConsumer): void;
+    create(endpointId: string, input: LocationShareRequest): LocationShareSummary;
+    private usable;
+    sample(id: string, endpointId: string, input: unknown): Promise<LocationShareSummary>;
+    private require;
+    private summary;
+    list(endpointId: string, conversationId?: string): LocationShareSummary[];
+    revoke(id: string, endpointId: string): Promise<LocationShareSummary>;
+    private invalidate;
+    private clear;
+    sweep(): Promise<void>;
+    close(): Promise<void>;
+}

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

@@ -0,0 +1,203 @@
+import { locationShareRequestSchema, locationShareSampleSchema } from "../../packages/endpoint-tools-protocol/src/location-sharing.js";
+import { init_src } from "../../packages/endpoint-tools-protocol/src/index.js";
+import { randomUUID } from "node:crypto";
+//#region src/endpoint-tools/location-sharing.ts
+init_src();
+var LocationSharingError = class extends Error {
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+/** Explicitly authorized coordinates remain transient and are never part of public context values. */
+var LocationSharingService = class {
+	shares = /* @__PURE__ */ new Map();
+	consumer;
+	timer;
+	unsubscribe;
+	constructor(registry, contexts, now = Date.now) {
+		this.registry = registry;
+		this.contexts = contexts;
+		this.now = now;
+		this.timer = setInterval(() => {
+			this.sweep();
+		}, 1e3);
+		this.timer.unref();
+		this.unsubscribe = registry.onChange((endpointId) => {
+			for (const share of this.shares.values()) if (share.summary.endpointId === endpointId) this.invalidate(share, "source_unavailable");
+		});
+	}
+	setConsumer(consumer) {
+		this.consumer = consumer;
+	}
+	create(endpointId, input) {
+		const request = locationShareRequestSchema.parse(input);
+		const endpoint = this.registry.get(endpointId);
+		if (!endpoint || this.contexts.view(endpointId)?.availability !== "foreground") throw new LocationSharingError("SOURCE_UNAVAILABLE", "Open the source device before sharing location");
+		for (const [id, share] of this.shares) if ([
+			"revoked",
+			"expired",
+			"source_unavailable"
+		].includes(share.summary.status) && share.summary.sync !== "cleanup_pending") this.shares.delete(id);
+		if (this.shares.size >= 64) throw new LocationSharingError("SHARING_CAPACITY", "Too many location shares");
+		if ([...this.shares.values()].some((share) => share.summary.endpointId === endpointId && share.summary.conversationId === request.conversationId && ![
+			"revoked",
+			"expired",
+			"source_unavailable"
+		].includes(share.summary.status))) throw new LocationSharingError("SHARING_EXISTS", "Stop the current location share first");
+		const summary = {
+			...request,
+			id: randomUUID(),
+			endpointId,
+			expiresAt: this.now() + request.durationMs,
+			status: "waiting",
+			sync: request.phoneId ? "pending" : "not_requested"
+		};
+		const share = {
+			summary,
+			epoch: endpoint.connectionId,
+			sequence: 0,
+			controller: new AbortController(),
+			operation: Promise.resolve()
+		};
+		this.shares.set(summary.id, share);
+		return { ...summary };
+	}
+	usable(share) {
+		return !share.controller.signal.aborted && share.summary.expiresAt > this.now() && this.registry.get(share.summary.endpointId)?.connectionId === share.epoch && this.contexts.view(share.summary.endpointId)?.availability === "foreground";
+	}
+	async sample(id, endpointId, input) {
+		const share = this.require(id, endpointId);
+		const parsed = locationShareSampleSchema.safeParse(input);
+		if (!parsed.success) throw new LocationSharingError("LOCATION_INVALID", "Invalid location sample");
+		if (!this.usable(share)) {
+			await this.invalidate(share, share.summary.expiresAt <= this.now() ? "expired" : "source_unavailable");
+			throw new LocationSharingError("GRANT_REVOKED", "Location sharing is no longer active");
+		}
+		const { sequence, sample } = parsed.data;
+		if (sequence <= share.sequence || share.summary.mode === "once" && share.sequence > 0) throw new LocationSharingError("LOCATION_REPLAY", "Location sample was already consumed");
+		if (sample.capturedAt < this.now() - 3e4 || sample.capturedAt > this.now() + 6e4 || share.sample && sample.capturedAt <= share.sample.capturedAt) throw new LocationSharingError("CONTEXT_STALE", "Acquire a fresh location sample");
+		if (share.summary.precision === "precise" && sample.precision !== "precise") throw new LocationSharingError("PRECISION_UNAVAILABLE", "Precise location is unavailable; choose approximate sharing");
+		const value = share.summary.precision === "approximate" || sample.precision === "approximate" ? {
+			...sample,
+			latitude: Math.round(sample.latitude * 50) / 50,
+			longitude: Math.round(sample.longitude * 50) / 50,
+			accuracyMeters: Math.max(3e3, sample.accuracyMeters),
+			precision: "approximate"
+		} : sample;
+		share.sequence = sequence;
+		share.sample = value;
+		share.sampleController?.abort();
+		share.sampleController = new AbortController();
+		const valueRef = randomUUID();
+		Object.assign(share.summary, {
+			status: "fresh",
+			capturedAt: value.capturedAt,
+			accuracyMeters: value.accuracyMeters,
+			validUntil: Math.min(value.capturedAt, this.now()) + 3e4,
+			valueRef
+		});
+		share.summary.validUntil = Math.min(share.summary.validUntil, share.summary.expiresAt);
+		if (share.summary.phoneId) {
+			share.summary.sync = "pending";
+			const consumer = this.consumer;
+			if (!consumer) throw new LocationSharingError("PHONE_ENV_UNSUPPORTED", "Phone location synchronization is unavailable");
+			const validUntil = share.summary.validUntil;
+			const signal = AbortSignal.any([
+				share.controller.signal,
+				share.sampleController.signal,
+				AbortSignal.timeout(Math.max(1, validUntil - this.now()))
+			]);
+			const assertCurrent = () => {
+				if (!this.usable(share) || share.summary.valueRef !== valueRef || validUntil <= this.now()) throw new LocationSharingError("CONTEXT_STALE", "Location authorization or sample expired");
+			};
+			share.operation = share.operation.catch(() => {}).then(async () => {
+				try {
+					assertCurrent();
+					await consumer.apply({
+						shareId: id,
+						conversationId: share.summary.conversationId,
+						phoneId: share.summary.phoneId,
+						sample: value,
+						validUntil,
+						assertCurrent
+					}, signal);
+					assertCurrent();
+					share.summary.sync = "applied";
+				} catch {
+					if (share.summary.valueRef === valueRef && share.summary.status === "fresh") share.summary.sync = "failed";
+				}
+			});
+			await share.operation;
+		}
+		return this.summary(share);
+	}
+	require(id, endpointId) {
+		const share = this.shares.get(id);
+		if (!share || share.summary.endpointId !== endpointId) throw new LocationSharingError("SHARE_NOT_FOUND", "Location share is unavailable");
+		return share;
+	}
+	summary(share) {
+		const result = { ...share.summary };
+		if (result.phoneId && ["applied", "cleanup_pending"].includes(result.sync)) result.sync = this.consumer?.state?.(result.id, result.phoneId) ?? result.sync;
+		if (!this.usable(share) || !share.sample || (result.validUntil ?? 0) <= this.now()) {
+			delete result.valueRef;
+			if (result.status === "fresh") result.status = "stale";
+		}
+		return result;
+	}
+	list(endpointId, conversationId) {
+		return [...this.shares.values()].filter((share) => share.summary.endpointId === endpointId && (!conversationId || share.summary.conversationId === conversationId)).map((share) => this.summary(share));
+	}
+	async revoke(id, endpointId) {
+		return this.invalidate(this.require(id, endpointId), "revoked");
+	}
+	async invalidate(share, status) {
+		share.controller.abort();
+		share.sampleController?.abort();
+		share.sample = void 0;
+		delete share.summary.valueRef;
+		if (![
+			"revoked",
+			"expired",
+			"source_unavailable"
+		].includes(share.summary.status)) share.summary.status = status;
+		await this.clear(share);
+		return this.summary(share);
+	}
+	async clear(share) {
+		if (!share.summary.phoneId || !this.consumer) return;
+		share.summary.sync = "cleanup_pending";
+		share.operation = share.operation.catch(() => {}).then(async () => {
+			try {
+				share.summary.sync = await this.consumer.clear(share.summary.id, share.summary.phoneId) ? "clean" : "cleanup_pending";
+			} catch {
+				share.summary.sync = "cleanup_pending";
+			}
+		});
+		await share.operation;
+	}
+	async sweep() {
+		const pending = [];
+		for (const share of this.shares.values()) {
+			if (share.summary.status === "waiting" && share.summary.expiresAt > this.now() && this.registry.get(share.summary.endpointId)?.connectionId === share.epoch) continue;
+			if (!share.controller.signal.aborted && !this.usable(share)) pending.push(this.invalidate(share, share.summary.expiresAt <= this.now() ? "expired" : "source_unavailable"));
+			else if (share.sample && (share.summary.validUntil ?? 0) <= this.now()) {
+				share.sampleController?.abort();
+				share.sample = void 0;
+				delete share.summary.valueRef;
+				share.summary.status = "stale";
+				pending.push(this.clear(share));
+			}
+		}
+		await Promise.all(pending);
+	}
+	async close() {
+		clearInterval(this.timer);
+		this.unsubscribe();
+		await Promise.all([...this.shares.values()].map((share) => this.invalidate(share, "revoked")));
+		this.shares.clear();
+	}
+};
+//#endregion
+export { LocationSharingError, LocationSharingService };

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

@@ -5,8 +5,12 @@ 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';
+import { EndpointContextStore } from './context-store.js';
+import { LocationSharingService } from './location-sharing.js';
 export declare class EndpointToolRuntime {
     readonly registry: EndpointRegistry;
+    readonly contexts: EndpointContextStore;
+    readonly locations: LocationSharingService;
     readonly grants: DeviceGrantService;
     readonly invocations: EndpointInvocationService;
     readonly uploads: EndpointUploadService;

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

@@ -11,10 +11,12 @@ import { EndpointToolPolicy } from "./policy.js";
 import { EndpointInvocationService } from "./invocation-service.js";
 import { EndpointAuthenticator } from "./auth.js";
 import { EndpointBindingService } from "./binding-service.js";
+import { EndpointContextStore } from "./context-store.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 { LocationSharingService } from "./location-sharing.js";
 import { join } from "node:path";
 //#region src/endpoint-tools/runtime.ts
 init_paths();
@@ -23,6 +25,8 @@ const log = createLogger("EndpointTools");
 const MAX_MESSAGE_CLOCK_SKEW_MS = 6e4;
 var EndpointToolRuntime = class {
 	registry;
+	contexts;
+	locations;
 	grants;
 	invocations;
 	uploads;
@@ -32,6 +36,8 @@ var EndpointToolRuntime = class {
 	constructor(options = {}) {
 		const policy = new EndpointToolPolicy();
 		this.registry = new EndpointRegistry(policy);
+		this.contexts = new EndpointContextStore(this.registry);
+		this.locations = new LocationSharingService(this.registry, this.contexts);
 		this.grants = new DeviceGrantService(this.registry, Date.now, recordDeviceGrantEvent);
 		this.bindings = new EndpointBindingService(this.registry, {
 			get: getEndpointSessionBinding,
@@ -103,6 +109,8 @@ var EndpointToolRuntime = class {
 		this.grants.close();
 		this.invocations.close();
 		this.uploads.close();
+		this.contexts.close();
+		this.locations.close();
 		this.registry.closeAll();
 	}
 };

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

@@ -1,6 +1,7 @@
 import type { EndpointContext } from '@xopcai/gateway-contract';
+import type { EndpointContextView, LocationShareSummary } from '@xopcai/endpoint-tools-protocol';
 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;
+export declare function deviceTurnSourceContext(endpoint: EndpointConnectionSnapshot, environment?: EndpointContext, taskContext?: EndpointContextView, locationShares?: LocationShareSummary[]): AgentSourceContext;

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

@@ -5,7 +5,7 @@ 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) {
+function deviceTurnSourceContext(endpoint, environment, taskContext, locationShares) {
 	const name = getEndpointDeviceSettings(endpoint.principalId)?.nickname ?? endpoint.displayName;
 	const snapshot = {
 		endpointId: endpoint.endpointId,
@@ -13,7 +13,9 @@ function deviceTurnSourceContext(endpoint, environment) {
 		name: name.slice(0, 80),
 		platform: endpoint.platform.slice(0, 40),
 		kind: endpoint.kind,
-		...environment ? { environment } : {}
+		...environment ? { environment } : {},
+		...taskContext ? { taskContext } : {},
+		...locationShares?.length ? { locationShares: locationShares.slice(-3) } : {}
 	};
 	const text = JSON.stringify(snapshot).replaceAll("<", "\\u003c").replaceAll(">", "\\u003e");
 	return {

package/dist/src/gateway/hono/middleware/auth.js

@@ -9,8 +9,8 @@ import { authenticateDeviceAccessToken, getDevice } from "../../../storage/sqlit
 import { getOrCreateGatewayIdentity } from "../../../storage/sqlite/gateway-identity-repository.js";
 import { safeEqualSecret } from "../../security/secret-equal.js";
 import { resolveClientIpFromRequest } from "../../client-ip.js";
-import { authenticateBrowserSession } from "../../../storage/sqlite/browser-session-repository.js";
 import { PROOF_HEADER, acquireProofBodyBudget, consumeRequestNonce, parseRequestProof, proofDigest, requestProofMessage, verifyRequestProofSignature } from "../../security/device-request-proof.js";
+import { authenticateBrowserSession } from "../../../storage/sqlite/browser-session-repository.js";
 import { isChromeExtensionOrigin } from "../../security/origin-check.js";
 import { browserCookieRequestAllowed, readBrowserSessionCookie, writeBrowserSessionCookie } from "../../security/browser-session.js";
 import { authorizeTrustedProxy } from "../../trusted-proxy.js";

package/dist/src/gateway/hono/routes/devices.js

@@ -230,6 +230,7 @@ function registerDeviceRoutes(authenticated, deps) {
 			deps.service.endpointTools.registry.revokePrincipal(principal.deviceId);
 			deps.service.realtime.disconnectPrincipal(principal.deviceId);
 			deps.service.voiceRealtime.disconnectPrincipal(principal.deviceId);
+			deps.service.phoneStreams.disconnectPrincipal(principal.deviceId);
 		}
 		return c.json({
 			ok: true,

package/dist/src/gateway/hono/routes/endpoint-compatibility.js

@@ -19,6 +19,10 @@ function registerEndpointCompatibilityRoutes(authenticated) {
 					capabilities: REALTIME_CAPABILITIES
 				},
 				turnDeviceContextV1: true,
+				endpointEnvironmentV1: true,
+				locationSharingV1: true,
+				mobilePhoneWorkspaceV1: true,
+				phoneMediaProtocolVersion: 1,
 				deviceStateToolsV1: true,
 				hardwareBridgeV1: true,
 				deviceLocationTasksV1: true,

package/dist/src/gateway/hono/routes/endpoint-environment.d.ts

@@ -0,0 +1,3 @@
+import type { Hono } from 'hono';
+import type { AuthenticatedRouteDeps } from './deps.js';
+export declare function registerEndpointEnvironmentRoutes(app: Hono, deps: AuthenticatedRouteDeps): void;

package/dist/src/gateway/hono/routes/endpoint-environment.js

@@ -0,0 +1,98 @@
+import { endpointTurnClaimSchema, init_src } from "../../../../packages/endpoint-tools-protocol/src/index.js";
+import { EndpointContextError } from "../../../endpoint-tools/context-store.js";
+import { endpointClaimBelongsToPrincipal } from "../../../endpoint-tools/turn-context.js";
+import { getGatewayPrincipal } from "../../security/gateway-principal.js";
+import { z } from "zod";
+import { bodyLimit } from "hono/body-limit";
+//#region src/gateway/hono/routes/endpoint-environment.ts
+init_src();
+const root = "/api/user-context/environment";
+const mutationSchema = z.strictObject({
+	origin: endpointTurnClaimSchema,
+	report: z.unknown().optional(),
+	heartbeat: z.unknown().optional()
+});
+function registerEndpointEnvironmentRoutes(app, deps) {
+	const runtime = deps.service.endpointTools;
+	app.get(root, (c) => {
+		const actor = getGatewayPrincipal(c);
+		c.header("Cache-Control", "no-store");
+		const snapshots = runtime.registry.list().filter((endpoint) => endpointClaimBelongsToPrincipal(runtime.registry, endpoint.endpointId, actor)).map((endpoint) => runtime.contexts.view(endpoint.endpointId)).filter(Boolean);
+		return c.json({
+			ok: true,
+			payload: snapshots
+		});
+	});
+	app.get(`${root}/endpoints/:endpointId`, (c) => {
+		c.header("Cache-Control", "no-store");
+		const id = c.req.param("endpointId");
+		if (!endpointClaimBelongsToPrincipal(runtime.registry, id, getGatewayPrincipal(c))) return c.json({
+			ok: false,
+			error: {
+				code: "FORBIDDEN",
+				message: "Context source is not accessible"
+			}
+		}, 403);
+		try {
+			return c.json({
+				ok: true,
+				payload: {
+					...runtime.contexts.connection(id),
+					context: runtime.contexts.view(id)
+				}
+			});
+		} catch {
+			return c.json({
+				ok: false,
+				error: {
+					code: "SOURCE_UNAVAILABLE",
+					message: "Context source is unavailable"
+				}
+			}, 409);
+		}
+	});
+	for (const action of ["reports", "heartbeats"]) app.post(`${root}/${action}`, bodyLimit({ maxSize: 16384 }), async (c) => {
+		c.header("Cache-Control", "no-store");
+		const parsed = mutationSchema.safeParse(await c.req.json().catch(() => null));
+		if (!parsed.success || (action === "reports" ? parsed.data.heartbeat !== void 0 || parsed.data.report === void 0 : parsed.data.report !== void 0 || parsed.data.heartbeat === void 0)) return c.json({
+			ok: false,
+			error: {
+				code: "CONTEXT_INVALID",
+				message: "Invalid context request"
+			}
+		}, 400);
+		const { origin } = parsed.data;
+		if (!endpointClaimBelongsToPrincipal(runtime.registry, origin.endpointId, getGatewayPrincipal(c))) return c.json({
+			ok: false,
+			error: {
+				code: "FORBIDDEN",
+				message: "Context source is not accessible"
+			}
+		}, 403);
+		if (!runtime.registry.verifyTurnClaim(origin.endpointId, origin.token)) return c.json({
+			ok: false,
+			error: {
+				code: "SOURCE_UNAVAILABLE",
+				message: "Context connection changed"
+			}
+		}, 409);
+		try {
+			const payload = action === "reports" ? runtime.contexts.report(origin.endpointId, parsed.data.report) : runtime.contexts.heartbeat(origin.endpointId, parsed.data.heartbeat);
+			return c.json({
+				ok: true,
+				payload
+			});
+		} catch (error) {
+			if (!(error instanceof EndpointContextError)) throw error;
+			return c.json({
+				ok: false,
+				error: {
+					code: error.code,
+					message: error.message
+				}
+			}, error.code === "CONTEXT_INVALID" ? 400 : 409);
+		}
+	});
+}
+//#endregion
+export { registerEndpointEnvironmentRoutes };

package/dist/src/gateway/hono/routes/endpoint-tools.js

@@ -106,6 +106,7 @@ function registerEndpointToolRoutes(authenticated, deps) {
 			if (accessRevoked) {
 				deps.service.realtime.disconnectPrincipal(id);
 				deps.service.voiceRealtime.disconnectPrincipal(id);
+				deps.service.phoneStreams.disconnectPrincipal(id);
 			}
 			if (principalRevoked) {
 				for (const endpoint of deps.service.endpointTools.registry.list()) if (endpoint.principalId === id) deps.service.endpointTools.disconnect(endpoint.endpointId, "Device revoked");

package/dist/src/gateway/hono/routes/lazy-bundles.js

@@ -3,6 +3,22 @@ function startsWithAny(path, prefixes) {
 	return prefixes.some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
 }
 const AUTHENTICATED_LAZY_ROUTE_BUNDLES = [
+	{
+		id: "location-sharing",
+		match: (path) => /^\/api\/user-context\/environment\/location-shares(?:\/[^/]+(?:\/samples)?)?$/.test(path),
+		load: async () => {
+			const { registerLocationSharingRoutes } = await import("./location-sharing.js");
+			return { register: registerLocationSharingRoutes };
+		}
+	},
+	{
+		id: "endpoint-environment",
+		match: (path) => /^\/api\/user-context\/environment(?:\/(?:reports|heartbeats|endpoints\/[^/]+))?$/.test(path),
+		load: async () => {
+			const { registerEndpointEnvironmentRoutes } = await import("./endpoint-environment.js");
+			return { register: registerEndpointEnvironmentRoutes };
+		}
+	},
 	{
 		id: "phone",
 		match: (path) => startsWithAny(path, ["/api/phone"]),