@xopcai/xopc 0.0.420 → 0.0.422

package/dist/src/computer/broker.js

@@ -195,8 +195,9 @@ var ComputerBroker = class {
 		return this.result(s);
 	}
 	async observe(s) {
-		let frame = await this.driver.observe(s.target, s.controller.signal);
+		let frame;
 		try {
+			frame = await this.driver.observe(s.target, s.controller.signal);
 			const validateFrame = () => {
 				this.active(s);
 				if (frame.target.appId !== s.appId || frame.target.processIdentity !== s.target.processIdentity || frame.target.windowId !== s.target.windowId) throw new Error("COMPUTER_TARGET_CHANGED");
@@ -251,7 +252,13 @@ var ComputerBroker = class {
 				}
 			};
 		} catch (error) {
-			frame.image.fill(0);
+			frame?.image.fill(0);
+			await this.stop().catch(() => {
+				log.warn({
+					sessionId: s.id,
+					phase: "cleanup"
+				}, "Computer driver cleanup failed after observation failure");
+			});
 			throw error;
 		}
 	}
@@ -302,7 +309,13 @@ var ComputerBroker = class {
 		const precheckStarted = this.now();
 		let matched = false;
 		for (let sample = 0; sample < 4; sample++) {
-			const current = await this.driver.observe(s.target, s.controller.signal);
+			let current;
+			try {
+				current = await this.driver.observe(s.target, s.controller.signal);
+			} catch (error) {
+				await this.stop().catch(() => {});
+				throw error;
+			}
 			try {
 				this.active(s);
 				if (!(JSON.stringify(current.target) === JSON.stringify(observed.target)) || e.deadlineAt <= this.now()) break;

package/dist/src/computer/diagnostics.js

@@ -173,7 +173,7 @@ function classifyComputerFailure(error, phase, dispatch = "notStarted", aborted
 	let category = categories[errorCode];
 	if (/^COMPUTER_MODEL_HTTP_[1-5]\d\d$/.test(errorCode)) category = "model";
 	if (/^COMPUTER_FRAME_UPLOAD_(HTTP_[1-5]\d\d|INVALID_GRANT|TOO_LARGE|TIMEOUT|NETWORK|INVALID_IMAGE|BUSY|INVALID_RESPONSE)$/.test(errorCode)) category = "transport";
-	if (/^COMPUTER_DRIVER_(CLICK|SET_VALUE|TYPE_TEXT|DRAG|KEY|SCROLL|BRING_TO_FRONT|LAUNCH_APP)_REFUSED$/.test(errorCode) || /^COMPUTER_DRIVER_SETUP_(START|BINARY|SDK|IDENTITY|PERMISSIONS)_FAILED$/.test(errorCode) || /^COMPUTER_DRIVER_(PRESS_KEY|HOTKEY)_REFUSED$/.test(errorCode) || /^COMPUTER_WINDOWS_(KEY|EDIT)_TARGET_CHANGED$/.test(errorCode)) category = "native";
+	if (errorCode === "COMPUTER_DRIVER_CLEANUP_UNCONFIRMED" || /^COMPUTER_DRIVER_(CLICK|SET_VALUE|TYPE_TEXT|DRAG|KEY|SCROLL|BRING_TO_FRONT|LAUNCH_APP)_REFUSED$/.test(errorCode) || /^COMPUTER_DRIVER_SETUP_(START|BINARY|SDK|IDENTITY|PERMISSIONS)_FAILED$/.test(errorCode) || /^COMPUTER_DRIVER_(PRESS_KEY|HOTKEY)_REFUSED$/.test(errorCode) || /^COMPUTER_WINDOWS_(KEY|EDIT)_TARGET_CHANGED$/.test(errorCode)) category = "native";
 	if (!category) {
 		category = "unknown";
 		errorCode = "COMPUTER_OPERATION_FAILED";

package/dist/src/computer/errors.js

@@ -75,6 +75,10 @@ function computerRecovery(code) {
 		case "COMPUTER_EXPECTED_SINGLE_ACTION": return "The GUI model returned an invalid action after bounded format correction. No input from this prediction was dispatched. Report validationReason and diagnosticId; do not guess coordinates, replay the action or change providers.";
 		case "COMPUTER_MODEL_HTTP_400": return "The configured model service rejected the request. No input was dispatched from this model request. Report serviceErrorCode, requestId and diagnosticId; check the model request format and input/output limits before reopening. Do not automatically retry or change providers.";
 		case "COMPUTER_RELEASE_UNCONFIRMED": return "Desktop release was not confirmed. Do not switch to other tools. Stop desktop control locally or restore the endpoint connection, then call close again to confirm release.";
+		case "COMPUTER_DRIVER_CLEANUP_UNCONFIRMED": return "The private desktop driver did not confirm shutdown. The old grant is revoked and a new driver cannot start. Stop desktop control locally and confirm cleanup before reopening; never replay the previous input.";
+		case "COMPUTER_DRIVER_HOTKEY_REFUSED":
+		case "COMPUTER_DRIVER_PRESS_KEY_REFUSED":
+		case "COMPUTER_DRIVER_KEY_REFUSED": return "The native key delivery was refused and desktop control is stopped. Inspect the application locally and complete the key operation manually. Never replay it or switch to foreground/global key injection to bypass the refusal.";
 		case "COMPUTER_MODEL_HTTP_429": return "The configured model service is rate-limited. No input was dispatched from this model request. Check the service quota and retry only after it resets; do not automatically change providers.";
 		case "COMPUTER_MODEL_HTTP_409": return "The pinned model deployment changed. No input was dispatched from this model request. Refresh the model catalog and reopen after reviewing the configured screenshot recipient.";
 		case "COMPUTER_OBSERVATION_CHANGED": return "No input was dispatched. Observe the changed window and re-plan with fresh evidence; the old proposed action was discarded.";

package/dist/src/computer/runtime.d.ts

@@ -118,8 +118,8 @@ export declare const ComputerUseInputSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
     appRef: z.ZodString;
     windowRef: z.ZodOptional<z.ZodString>;
     mode: z.ZodEnum<{
-        observe: "observe";
         control: "control";
+        observe: "observe";
     }>;
     prepare: z.ZodBoolean;
 }, z.core.$strict>, z.ZodObject<{

package/dist/src/config/agent-profile.js

@@ -1,6 +1,6 @@
+import { normalizeAgentId } from "../agent-catalog/id.js";
 import { resolveEffectiveAgentConfig } from "../agent-config/resolver.js";
 import { init_agent_config } from "../agent-config/index.js";
-import { normalizeAgentId } from "../agent-catalog/id.js";
 import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
 import { init_agent_scope, resolveAgentWorkspaceDir } from "../agent/agent-scope.js";
 import { getConversationRouting } from "../storage/sqlite/conversation-repository.js";

package/dist/src/config/schema.d.ts

@@ -1789,6 +1789,7 @@ export declare const ConfigSchema: z.ZodDefault<z.ZodObject<{
         hierarchicalPlanning: z.ZodDefault<z.ZodBoolean>;
         maxActionsPerSession: z.ZodDefault<z.ZodNumber>;
         maxModelRequests: z.ZodDefault<z.ZodNumber>;
+        modelRequestTimeoutMs: z.ZodDefault<z.ZodNumber>;
         maxOperationDurationMs: z.ZodDefault<z.ZodNumber>;
         maxSessionDurationMs: z.ZodDefault<z.ZodNumber>;
         idleDisconnectMs: z.ZodDefault<z.ZodNumber>;

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/execution-environments/local-worktree-manager.js

@@ -8,8 +8,8 @@ import { assertManagedWorktreePath, assertNoNestedRegisteredWorktrees, readDirec
 import { dirname, resolve } from "node:path";
 import { existsSync } from "node:fs";
 import { randomUUID } from "node:crypto";
-import { mkdir, rm, stat } from "node:fs/promises";
 import lockfile from "proper-lockfile";
+import { mkdir, rm, stat } from "node:fs/promises";
 //#region src/execution-environments/local-worktree-manager.ts
 init_logger();
 const log = createLogger("ExecutionEnvironment:LocalWorktree");

package/dist/src/extensions/agent-plugins/skill-catalog.js

@@ -1,7 +1,7 @@
-import { parseFrontmatter } from "../../markdown/frontmatter.js";
 import { containedPath } from "./contained-path.js";
 import "./validation.js";
 import { AgentPluginStore } from "./store.js";
+import { parseFrontmatter } from "../../markdown/frontmatter.js";
 import { createSkillConfigManager } from "../../agent/skills/config.js";
 import { parseSkillLocalizations } from "../../agent/skills/parse-skill-metadata.js";
 import { buildSkillMarkdownPreviewFromRaw } from "../../agent/skills/skill-markdown-preview-from-raw.js";

package/dist/src/extensions/agent-plugins/validation.js

@@ -9,8 +9,8 @@ import { dirname, join, resolve } from "node:path";
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { z } from "zod";
-import yaml from "js-yaml";
 import { validateHeaderName, validateHeaderValue } from "node:http";
+import yaml from "js-yaml";
 //#region src/extensions/agent-plugins/validation.ts
 init_schema();
 const PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";

package/dist/src/gateway/agents-admin.js

@@ -1,10 +1,10 @@
 import { normalizeAgentId, validateAgentIdForNewAgent } from "../agent-catalog/id.js";
 import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
 import { init_agent_scope, listAgentEntries, resolveAgentProfileDir, resolveAgentWorkspaceDir, resolveDefaultAgentId, resolveUserPath } from "../agent/agent-scope.js";
-import { AGENT_PROFILE_MARKDOWN_SYSTEM_FILES, REQUIRED_AGENT_PROFILE_MARKDOWN_FILE_SET } from "../agent/context/workspace.js";
-import { AgentCatalogService } from "../agent-catalog/service.js";
 import { resolveEffectiveAgentProfile } from "../config/agent-profile.js";
+import { AGENT_PROFILE_MARKDOWN_SYSTEM_FILES, REQUIRED_AGENT_PROFILE_MARKDOWN_FILE_SET } from "../agent/context/workspace.js";
 import { isPathUnderWorkspace, resolveWorkspaceSafePath } from "./workspace-editor-path.js";
+import { AgentCatalogService } from "../agent-catalog/service.js";
 import { GATEWAY_BUILTIN_TOOL_IDS } from "./agent-builtin-tools.js";
 import { resolve } from "node:path";
 import { mkdir, readFile, realpath, stat, unlink, writeFile } from "node:fs/promises";

package/dist/src/gateway/automation-completion-delivery.d.ts

@@ -0,0 +1,4 @@
+import type { AutomationRun, AutomationRunDeliveryContext } from '../automations/domain/types.js';
+import type { NotificationService } from '../notifications/service.js';
+/** Commit the inbox handoff before acknowledging the durable result outbox. */
+export declare function deliverAutomationCompletion(run: AutomationRun, context: AutomationRunDeliveryContext, notifications: NotificationService, emit: (type: string, payload: unknown) => void): void;