@xopcai/xopc 0.0.421 → 0.0.422

package/dist/src/gateway/hono/routes/location-sharing.d.ts

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

package/dist/src/gateway/hono/routes/location-sharing.js

@@ -0,0 +1,164 @@
+import { hasGatewayScope } from "../../security/gateway-scopes.js";
+import { locationShareRequestSchema } from "../../../../packages/endpoint-tools-protocol/src/location-sharing.js";
+import { endpointTurnClaimSchema, init_src } from "../../../../packages/endpoint-tools-protocol/src/index.js";
+import { PhoneError, init_contracts } from "../../../phone/contracts.js";
+import { getPhoneRuntime } from "../../../phone/runtime.js";
+import { LocationSharingError } from "../../../endpoint-tools/location-sharing.js";
+import { endpointClaimBelongsToPrincipal } from "../../../endpoint-tools/turn-context.js";
+import { getGatewayPrincipal } from "../../security/gateway-principal.js";
+import { z } from "zod";
+import { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
+//#region src/gateway/hono/routes/location-sharing.ts
+init_src();
+init_contracts();
+const root = "/api/user-context/environment/location-shares";
+const originBody = z.strictObject({ origin: endpointTurnClaimSchema });
+function registerLocationSharingRoutes(parent, deps) {
+	const app = new Hono();
+	app.onError((error, c) => {
+		if (error instanceof LocationSharingError || error instanceof PhoneError) return c.json({
+			ok: false,
+			error: {
+				code: error.code,
+				message: error.message
+			}
+		}, 409);
+		return c.json({
+			ok: false,
+			error: {
+				code: "LOCATION_UNAVAILABLE",
+				message: "Location sharing is unavailable"
+			}
+		}, 503);
+	});
+	const runtime = deps.service.endpointTools;
+	runtime.locations?.setConsumer({
+		apply: (input, signal) => getPhoneRuntime().environment.apply(input, signal),
+		clear: (id, phoneId) => getPhoneRuntime().environment.clear(id, phoneId),
+		state: (id, phoneId) => {
+			const state = getPhoneRuntime().environment.status(phoneId);
+			return state.status === "clean" || state.shareId !== id ? "clean" : state.status === "applied" ? "applied" : state.status === "pending" ? "pending" : "cleanup_pending";
+		}
+	});
+	const authorize = (c, origin) => endpointClaimBelongsToPrincipal(runtime.registry, origin.endpointId, getGatewayPrincipal(c)) && runtime.registry.verifyTurnClaim(origin.endpointId, origin.token);
+	for (const path of [root, `${root}/*`]) app.use(path, bodyLimit({
+		maxSize: 4096,
+		onError: (c) => c.json({
+			ok: false,
+			error: {
+				code: "LOCATION_TOO_LARGE",
+				message: "Location request exceeds 4 KB"
+			}
+		}, 413)
+	}), async (c, next) => {
+		c.header("Cache-Control", "no-store");
+		await next();
+	});
+	app.post(root, async (c) => {
+		const parsed = originBody.extend({
+			request: locationShareRequestSchema,
+			disclosureVersion: z.literal("location-sharing-v1")
+		}).safeParse(await c.req.json().catch(() => null));
+		if (!parsed.success) return c.json({
+			ok: false,
+			error: {
+				code: "LOCATION_INVALID",
+				message: "Invalid location sharing request"
+			}
+		}, 400);
+		if (!authorize(c, parsed.data.origin)) return c.json({
+			ok: false,
+			error: {
+				code: "FORBIDDEN",
+				message: "Location source is not accessible"
+			}
+		}, 403);
+		if (!hasGatewayScope(getGatewayPrincipal(c).scopes, "agents.run") || !await deps.service.sessions.getSession(parsed.data.request.conversationId)) return c.json({
+			ok: false,
+			error: {
+				code: "FORBIDDEN",
+				message: "Conversation is not accessible"
+			}
+		}, 403);
+		if (parsed.data.request.phoneId) {
+			if (!deps.service.currentConfig.phone.enabled) return c.json({
+				ok: false,
+				error: {
+					code: "PHONE_DISABLED",
+					message: "Enable Phone Use before sharing location"
+				}
+			}, 409);
+			const phone = getPhoneRuntime().repository.get(parsed.data.request.phoneId);
+			if (!phone.enabled || phone.connection?.kind !== "aliyun-adb") return c.json({
+				ok: false,
+				error: {
+					code: "PHONE_ENV_UNSUPPORTED",
+					message: "Choose an enabled Alibaba cloud phone"
+				}
+			}, 409);
+		}
+		return c.json({
+			ok: true,
+			payload: runtime.locations.create(parsed.data.origin.endpointId, parsed.data.request)
+		}, 201);
+	});
+	app.get(root, (c) => {
+		const endpointId = c.req.query("endpointId") ?? "";
+		if (!endpointClaimBelongsToPrincipal(runtime.registry, endpointId, getGatewayPrincipal(c))) return c.json({
+			ok: false,
+			error: {
+				code: "FORBIDDEN",
+				message: "Location source is not accessible"
+			}
+		}, 403);
+		return c.json({
+			ok: true,
+			payload: runtime.locations.list(endpointId, c.req.query("conversationId"))
+		});
+	});
+	app.post(`${root}/:id/samples`, async (c) => {
+		const parsed = originBody.extend({
+			sequence: z.number().int().positive(),
+			sample: z.unknown()
+		}).safeParse(await c.req.json().catch(() => null));
+		if (!parsed.success) return c.json({
+			ok: false,
+			error: {
+				code: "LOCATION_INVALID",
+				message: "Invalid location sample"
+			}
+		}, 400);
+		if (!authorize(c, parsed.data.origin)) return c.json({
+			ok: false,
+			error: {
+				code: "FORBIDDEN",
+				message: "Location source is not accessible"
+			}
+		}, 403);
+		return c.json({
+			ok: true,
+			payload: await runtime.locations.sample(c.req.param("id"), parsed.data.origin.endpointId, {
+				sequence: parsed.data.sequence,
+				sample: parsed.data.sample
+			})
+		});
+	});
+	app.delete(`${root}/:id`, async (c) => {
+		const parsed = originBody.safeParse(await c.req.json().catch(() => null));
+		if (!parsed.success || !authorize(c, parsed.data.origin)) return c.json({
+			ok: false,
+			error: {
+				code: "FORBIDDEN",
+				message: "Location source is not accessible"
+			}
+		}, 403);
+		return c.json({
+			ok: true,
+			payload: await runtime.locations.revoke(c.req.param("id"), parsed.data.origin.endpointId)
+		});
+	});
+	parent.route("/", app);
+}
+//#endregion
+export { registerLocationSharingRoutes };

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

@@ -1,16 +1,19 @@
 import { createLogger } from "../../../utils/logger/index.js";
 import { init_logger } from "../../../utils/logger.js";
+import { setDevicePhoneAccess } from "../../../storage/sqlite/device-access-repository.js";
 import { MOCK_PHONE_MODEL, PhoneActionSchema, PhoneConfigSchema, PhoneDeviceSchema, PhoneError, PhoneExecutionModeSchema, PhoneInputSchema, init_contracts } from "../../../phone/contracts.js";
 import { createConversation, init_conversation_repository } from "../../../storage/sqlite/conversation-repository.js";
 import { getDefaultAgentId, init_resolve_route } from "../../../routing/resolve-route.js";
 import { getModelRegistry, init_model_registry } from "../../../providers/model-registry.js";
 import { init_providers, isProviderConfiguredSync } from "../../../providers/index.js";
 import { normalizePhoneAppAccess, phoneAppAccess } from "../../../phone/app-access.js";
+import { cancelPhoneAssistance, pendingPhoneAssistance, phoneAssistance, phoneAssistanceReport } from "../../../phone/assistance.js";
 import { resolveAdbPath } from "../../../phone/adb-driver.js";
 import { createPhoneModel, phoneModelProfile } from "../../../phone/model-adapter.js";
 import { getPhoneRuntime, phoneExecutionContext } from "../../../phone/runtime.js";
 import { registerPhoneSetupRoutes } from "./phone-setup.js";
 import { getGatewayPrincipal } from "../../security/gateway-principal.js";
+import { authorizePhoneAccess, phoneAdministrator } from "../../security/phone-access.js";
 import { registerPhoneWirelessRoutes } from "./phone-wireless.js";
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
@@ -51,20 +54,118 @@ function registerPhoneRoutes(parent, deps, runtime = getPhoneRuntime()) {
 	const { service, strictRateLimitMiddleware } = deps;
 	app.use("/api/phone/*", async (c, next) => {
 		const principal = getGatewayPrincipal(c);
-		if (principal.kind !== "owner" && principal.kind !== "trusted-proxy" || !principal.scopes.includes("gateway.admin")) return c.json({
-			ok: false,
-			error: {
-				code: "PHONE_ADMIN_REQUIRED",
-				message: "Phone settings require Gateway administrator access"
+		if (!phoneAdministrator(principal)) {
+			const path = c.req.path;
+			const conversation = /^\/api\/phone\/conversations\/([0-9a-f-]{36})(?:\/(summary|[0-9a-f-]{36}\/(?:frame|video-ticket|control)))?$/i.test(path);
+			const summary = path.endsWith("/summary") && c.req.method === "GET";
+			if (!(conversation && (c.req.method === "GET" || c.req.method === "POST" && /\/(video-ticket|control)$/.test(path))) || principal.kind !== "device" || !principal.scopes.includes("sessions.read")) throw new PhoneError("PHONE_ADMIN_REQUIRED", "Phone management requires administrator access", 403);
+			if (!summary) authorizePhoneAccess(principal, path.endsWith("/control"));
+		}
+		await next();
+		if (principal.kind === "device" && c.res.status === 200 && c.res.headers.get("Content-Type")?.includes("application/json")) {
+			const body = await c.res.clone().json();
+			const report = body.payload?.report;
+			if (report && body.payload) {
+				const { sessionId, deviceId, deviceName, status, mode, controlOwner, controlEpoch, handoff, assistanceId, reconnectRequired, stopReason, currentAction, updatedAt } = report;
+				body.payload = {
+					ownControl: body.payload.ownControl,
+					textInput: body.payload.textInput,
+					report: {
+						sessionId,
+						deviceId,
+						deviceName,
+						status,
+						mode,
+						controlOwner,
+						controlEpoch,
+						handoff,
+						assistanceId,
+						reconnectRequired,
+						stopReason,
+						currentAction,
+						updatedAt
+					}
+				};
+				c.res = c.json(body);
+				c.header("Cache-Control", "no-store");
+			}
+		}
+	});
+	app.patch("/api/phone/device-access/:id", strictRateLimitMiddleware, async (c) => {
+		const actor = getGatewayPrincipal(c);
+		if (actor.kind === "device" || !actor.scopes.includes("gateway.admin")) return c.json({ ok: false }, 403);
+		const input = z.object({ access: z.enum([
+			"none",
+			"view",
+			"control"
+		]) }).strict().safeParse(await c.req.json().catch(() => null));
+		if (!input.success) return c.json({ ok: false }, 400);
+		const device = setDevicePhoneAccess(c.req.param("id"), input.data.access);
+		if (!device) return c.json({ ok: false }, 404);
+		deps.service.phoneStreams.disconnectPrincipal(device.id);
+		c.header("Cache-Control", "no-store");
+		return c.json({
+			ok: true,
+			payload: {
+				id: device.id,
+				scopes: device.scopes
 			}
-		}, 403);
-		return next();
+		});
 	});
 	registerPhoneSetupRoutes(app, deps);
 	registerPhoneWirelessRoutes(app, deps, runtime);
+	app.get("/api/phone/devices/:id/environment", (c) => {
+		const id = z.uuid().parse(c.req.param("id"));
+		const device = runtime.repository.get(id);
+		c.header("Cache-Control", "no-store");
+		return c.json({
+			ok: true,
+			payload: {
+				...runtime.environment.status(id),
+				supported: device.connection?.kind === "aliyun-adb"
+			}
+		});
+	});
+	app.post("/api/phone/devices/:id/environment/cleanup", strictRateLimitMiddleware, async (c) => {
+		const id = z.uuid().parse(c.req.param("id"));
+		runtime.repository.get(id);
+		const state = runtime.environment.status(id);
+		const cleared = state.shareId ? await runtime.environment.clear(state.shareId, id) : true;
+		return c.json({
+			ok: true,
+			payload: {
+				cleared,
+				...runtime.environment.status(id)
+			}
+		});
+	});
+	const connectionReports = () => {
+		const reports = runtime.reports().filter((report) => report.status !== "closed");
+		for (const wait of pendingPhoneAssistance()) if (!reports.some((report) => report.deviceId === wait.checkpoint.report.deviceId)) reports.push(phoneAssistanceReport(wait));
+		return reports.map((report) => {
+			const wait = phoneAssistance(report.owner);
+			return wait && ["open", "queued"].includes(wait.status) ? {
+				...report,
+				assistanceId: wait.id,
+				...wait.status === "open" && report.controlOwner !== "human" ? { status: "needs_user" } : {}
+			} : report;
+		});
+	};
+	const liveStatus = (owner, id, context, client) => {
+		const state = runtime.liveStatus(owner, id, context, client);
+		const wait = phoneAssistance(owner);
+		return wait && ["open", "queued"].includes(wait.status) ? {
+			...state,
+			report: {
+				...state.report,
+				assistanceId: wait.id,
+				...wait.status === "open" && state.report.controlOwner !== "human" ? { status: "needs_user" } : {}
+			}
+		} : state;
+	};
 	app.get("/api/phone/connections", async (c) => {
 		c.header("Cache-Control", "no-store");
-		const payload = await Promise.all(runtime.reports().filter((report) => report.status !== "closed").map(async (report) => {
+		const payload = await Promise.all(connectionReports().map(async (report) => {
 			const source = report.sourceConversationId ?? report.owner;
 			const conversation = /^[\da-f]{8}-[\da-f-]{27}$/i.test(source) ? await service.sessions.getSession(source) : void 0;
 			const { facts: _facts, readings: _readings, steps: _steps, task: _task, feedback: _feedback, ...metadata } = report;
@@ -235,6 +336,7 @@ function registerPhoneRoutes(parent, deps, runtime = getPhoneRuntime()) {
 			...patch.allowedApps && patch.appAccess === void 0 ? { appAccess: "selected" } : {}
 		});
 		await runtime.stopDevice(id);
+		if (previous.connection) await runtime.environment.recover(id, true);
 		return c.json({
 			ok: true,
 			payload: runtime.repository.save(next, id)
@@ -244,6 +346,7 @@ function registerPhoneRoutes(parent, deps, runtime = getPhoneRuntime()) {
 		const id = c.req.param("id");
 		const device = runtime.repository.get(id);
 		await runtime.stopDevice(id);
+		if (device.connection) await runtime.environment.recover(id, true);
 		await runtime.cloud.remove(device);
 		runtime.repository.remove(id);
 		return c.json({ ok: true });
@@ -332,6 +435,7 @@ function registerPhoneRoutes(parent, deps, runtime = getPhoneRuntime()) {
 		clientId: liveClient,
 		operationId: z.string().uuid(),
 		epoch: z.number().int().positive(),
+		assistanceId: z.string().uuid().optional(),
 		op: z.enum([
 			"takeover",
 			"release",
@@ -342,6 +446,7 @@ function registerPhoneRoutes(parent, deps, runtime = getPhoneRuntime()) {
 			"input",
 			"recover"
 		]),
+		expectedTranscriptId: z.uuid().optional(),
 		frameSeq: z.number().int().positive().optional(),
 		geometry: z.number().int().positive().optional(),
 		action: PhoneActionSchema.optional()
@@ -349,20 +454,22 @@ function registerPhoneRoutes(parent, deps, runtime = getPhoneRuntime()) {
 	async function conversationPhone(conversationId, requestedSessionId) {
 		if (conversationId.startsWith("device:")) {
 			const deviceId = z.string().uuid().parse(conversationId.slice(7));
-			const report = runtime.reports().find((report) => report.deviceId === deviceId && report.status !== "closed");
+			const report = connectionReports().find((report) => report.deviceId === deviceId);
 			if (!report || requestedSessionId && report.sessionId !== requestedSessionId) throw new PhoneError("PHONE_SESSION_NOT_FOUND", "Phone connection changed. Refresh the phone panel.", 404);
 			const conversation = /^[\da-f]{8}-[\da-f-]{27}$/i.test(report.owner) ? await service.sessions.getSession(report.owner) : void 0;
 			return {
 				owner: report.owner,
 				report,
 				transcriptId: conversation?.transcriptId,
-				context: runtime.deviceContext(deviceId, service.currentConfig)
+				context: runtime.status(report.owner) && runtime.status(report.owner)?.status !== "closed" ? runtime.deviceContext(deviceId, service.currentConfig) : phoneExecutionContext(service.currentConfig, report.agentId)
 			};
 		}
 		z.string().uuid().parse(conversationId);
 		const conversation = await service.sessions.getSession(conversationId);
 		if (!conversation) throw new PhoneError("PHONE_CONVERSATION_NOT_FOUND", "Conversation not found", 404);
-		const report = runtime.status(conversationId);
+		const connected = runtime.status(conversationId);
+		const wait = phoneAssistance(conversationId);
+		const report = connected && connected.status !== "closed" ? connected : wait && ["open", "queued"].includes(wait.status) ? phoneAssistanceReport(wait) : void 0;
 		if (requestedSessionId && report?.sessionId !== requestedSessionId) throw new PhoneError("PHONE_SESSION_NOT_FOUND", "Phone session not found", 404);
 		if (report && report.agentId !== conversation.agentId) throw new PhoneError("PHONE_ACCESS_CHANGED", "Conversation Agent changed", 403);
 		return {
@@ -372,6 +479,41 @@ function registerPhoneRoutes(parent, deps, runtime = getPhoneRuntime()) {
 			context: phoneExecutionContext(service.currentConfig, conversation.agentId)
 		};
 	}
+	app.get("/api/phone/conversations/:conversationId/summary", async (c) => {
+		const principal = getGatewayPrincipal(c);
+		const id = c.req.param("conversationId");
+		const { report, transcriptId } = await conversationPhone(id);
+		let access = "none";
+		try {
+			authorizePhoneAccess(principal);
+			access = "view";
+		} catch {}
+		if (access === "view") try {
+			authorizePhoneAccess(principal, true);
+			access = "control";
+		} catch {}
+		const payload = {
+			available: Boolean(report),
+			access,
+			needsUser: Boolean(report && access !== "none" && report.status === "needs_user")
+		};
+		if (report && access !== "none") {
+			payload.deviceName = report.deviceName;
+			payload.taskState = report.status;
+			payload.updatedAt = report.updatedAt;
+			if (transcriptId && report.deviceId) payload.binding = {
+				conversationId: id,
+				transcriptId,
+				phoneSessionId: report.sessionId,
+				phoneDeviceId: report.deviceId
+			};
+		}
+		c.header("Cache-Control", "no-store");
+		return c.json({
+			ok: true,
+			payload
+		});
+	});
 	app.get("/api/phone/conversations/:conversationId", async (c) => {
 		let owner = c.req.param("conversationId");
 		const client = liveClient.parse(c.req.query("clientId"));
@@ -380,7 +522,11 @@ function registerPhoneRoutes(parent, deps, runtime = getPhoneRuntime()) {
 		c.header("Cache-Control", "no-store");
 		return c.json({
 			ok: true,
-			payload: report ? runtime.liveStatus(owner, report.sessionId, context, `${getGatewayPrincipal(c).principalId}:${client}${c.req.param("conversationId").startsWith("device:") ? ":viewer" : ""}`) : null
+			payload: report ? runtime.status(owner)?.status !== "closed" && runtime.status(owner) ? liveStatus(owner, report.sessionId, context, `${getGatewayPrincipal(c).principalId}:${client}${c.req.param("conversationId").startsWith("device:") ? ":viewer" : ""}`) : {
+				report,
+				ownControl: false,
+				frame: null
+			} : null
 		});
 	});
 	app.post("/api/phone/conversations/:conversationId/:sessionId/execution-mode", strictRateLimitMiddleware, async (c) => {
@@ -397,15 +543,23 @@ function registerPhoneRoutes(parent, deps, runtime = getPhoneRuntime()) {
 		c.header("Cache-Control", "no-store");
 		return c.json({
 			ok: true,
-			payload: runtime.liveStatus(owner, c.req.param("sessionId"), context, `${getGatewayPrincipal(c).principalId}:${input.clientId}`)
+			payload: liveStatus(owner, c.req.param("sessionId"), context, `${getGatewayPrincipal(c).principalId}:${input.clientId}`)
 		});
 	});
 	app.get("/api/phone/conversations/:conversationId/:sessionId/frame", async (c) => {
 		let owner = c.req.param("conversationId");
 		const id = c.req.param("sessionId");
-		const { context, owner: resolvedOwner } = await conversationPhone(owner, id);
+		const { context, transcriptId, owner: resolvedOwner } = await conversationPhone(owner, id);
 		owner = resolvedOwner;
+		const principal = getGatewayPrincipal(c);
+		if (principal.kind === "device" && c.req.query("expectedTranscriptId") !== transcriptId) throw new PhoneError("PHONE_BINDING_CHANGED", "Conversation changed", 409);
 		const frame = await runtime.liveFrame(owner, id, context, c.req.raw.signal);
+		try {
+			authorizePhoneAccess(principal);
+		} catch (error) {
+			frame.frame.fill(0);
+			throw error;
+		}
 		c.header("Cache-Control", "no-store");
 		c.header("Content-Type", "image/png");
 		c.header("X-Content-Type-Options", "nosniff");
@@ -421,15 +575,32 @@ function registerPhoneRoutes(parent, deps, runtime = getPhoneRuntime()) {
 	app.post("/api/phone/conversations/:conversationId/:sessionId/video-ticket", strictRateLimitMiddleware, async (c) => {
 		const address = c.req.param("conversationId");
 		const id = c.req.param("sessionId");
-		const { clientId } = z.object({ clientId: liveClient }).strict().parse(await c.req.json());
-		await conversationPhone(address, id);
+		const { clientId, purpose, expectedTranscriptId, epoch } = z.object({
+			clientId: liveClient,
+			purpose: z.enum(["view", "control"]).optional(),
+			expectedTranscriptId: z.uuid().optional(),
+			epoch: z.number().int().positive().optional()
+		}).strict().parse(await c.req.json());
+		const initial = await conversationPhone(address, id);
 		const principal = getGatewayPrincipal(c);
-		const client = `${principal.principalId}:${clientId}${c.req.param("conversationId").startsWith("device:") ? ":viewer" : ""}`;
+		const client = `${principal.principalId}:${clientId}${address.startsWith("device:") || principal.kind === "device" && purpose !== "control" ? ":viewer" : ""}`;
+		const native = principal.kind === "device";
+		const interactive = native ? purpose === "control" : purpose !== "view" && !address.startsWith("device:");
+		if (native && (!expectedTranscriptId || expectedTranscriptId !== initial.transcriptId)) throw new PhoneError("PHONE_BINDING_CHANGED", "Conversation changed; refresh the phone", 409);
 		const validate = async () => {
+			authorizePhoneAccess(principal, interactive);
 			const resolved = await conversationPhone(address, id);
-			runtime.liveStatus(resolved.owner, id, resolved.context, client);
+			if (resolved.transcriptId !== initial.transcriptId) throw new PhoneError("PHONE_BINDING_CHANGED", "Conversation changed", 409);
+			const state = runtime.liveStatus(resolved.owner, id, resolved.context, client);
+			if (native && interactive && (!state.ownControl || epoch !== state.report.controlEpoch)) throw new PhoneError("PHONE_CONTROL_CHANGED", "Take over before opening an interactive stream", 409);
 		};
+		if (native) await validate();
 		const issued = service.phoneStreams.issue({
+			...native ? {
+				deviceId: principal.deviceId,
+				readOnly: !interactive,
+				inputEpoch: interactive ? epoch : void 0
+			} : { readOnly: !interactive },
 			origin: new URL(c.req.url).origin,
 			principal: principal.principalId,
 			client,
@@ -439,8 +610,7 @@ function registerPhoneRoutes(parent, deps, runtime = getPhoneRuntime()) {
 				return runtime.liveVideo(resolved.owner, id, resolved.context);
 			},
 			disconnect: async () => {
-				const resolved = await conversationPhone(address, id).catch(() => void 0);
-				if (resolved) await runtime.disconnectVideo(resolved.owner, id, client);
+				await runtime.disconnectVideo(initial.owner, id, client, native ? epoch : void 0);
 			}
 		});
 		c.header("Cache-Control", "no-store");
@@ -457,22 +627,64 @@ function registerPhoneRoutes(parent, deps, runtime = getPhoneRuntime()) {
 		if (c.req.param("conversationId").startsWith("device:")) throw new PhoneError("PHONE_OBSERVE_ONLY", "The global phone viewer is read only. Use the controlling conversation for input.", 403);
 		let owner = c.req.param("conversationId");
 		const id = c.req.param("sessionId");
-		const { context, transcriptId, owner: resolvedOwner } = await conversationPhone(owner, id);
+		const actor = getGatewayPrincipal(c);
+		const { clientId, assistanceId, expectedTranscriptId, ...input } = liveControlInput.parse(await c.req.json());
+		const requestedWait = phoneAssistance(owner);
+		const allowRecovery = assistanceId && requestedWait?.id === assistanceId && requestedWait.checkpoint.report.sessionId === id && ["takeover", "handback"].includes(input.op);
+		const { context, transcriptId, owner: resolvedOwner } = await conversationPhone(owner, allowRecovery ? void 0 : id);
 		owner = resolvedOwner;
-		const { clientId, ...input } = liveControlInput.parse(await c.req.json());
-		const result = await runtime.liveControl(owner, id, context, `${getGatewayPrincipal(c).principalId}:${clientId}`, input);
-		if (transcriptId && input.op === "handback" && result.resumeTurnRequired && !service.sessions.getActiveRun(owner).active) {
-			if (!(await service.submitSessionInput({
-				conversationId: owner,
-				expectedTranscriptId: transcriptId,
-				clientMessageId: input.operationId,
-				delivery: "next",
-				content: "手机已交还，请先确认当前页面，继续未完成的任务；已完成的步骤不要重复，结束后释放操作权，保持手机连接。",
-				origin: {
-					type: "system",
-					source: "internal"
+		if (getGatewayPrincipal(c).kind === "device" && (!expectedTranscriptId || expectedTranscriptId !== transcriptId)) throw new PhoneError("PHONE_BINDING_CHANGED", "Conversation changed; refresh the phone", 409);
+		const wait = phoneAssistance(owner);
+		if (assistanceId && (!wait || wait.id !== assistanceId || ![
+			"open",
+			"queued",
+			"resuming",
+			"completed"
+		].includes(wait.status))) throw new PhoneError("PHONE_ASSISTANCE_CHANGED", "The phone task changed. Refresh before continuing.", 409);
+		if (input.op === "handback" && assistanceId && wait?.status !== "open") {
+			service.resumePhoneAssistance(owner, assistanceId);
+			return c.json({
+				ok: true,
+				payload: runtime.status(owner) && runtime.status(owner)?.status !== "closed" ? liveStatus(owner, runtime.status(owner).sessionId, context, `${getGatewayPrincipal(c).principalId}:${clientId}`) : {
+					report: phoneAssistanceReport(wait),
+					ownControl: false,
+					frame: null
 				}
-			})).ok) throw new PhoneError("PHONE_RESUME_FAILED", "Phone control returned. Send Continue in chat to resume the task.", 409);
+			});
+		}
+		let sessionId = id;
+		if (wait?.status === "open" && ["takeover", "handback"].includes(input.op)) {
+			const restored = await runtime.restoreAssistance(wait.checkpoint, context, c.req.raw.signal, wait.id);
+			if (restored.sessionId !== id) {
+				sessionId = restored.sessionId;
+				input.epoch = restored.controlEpoch;
+			}
+		}
+		let result;
+		try {
+			const current = runtime.status(owner);
+			result = input.op === "handback" && wait?.status === "open" && current?.status === "ready" && current.controlOwner === "agent" ? liveStatus(owner, sessionId, context, `${getGatewayPrincipal(c).principalId}:${clientId}`) : await runtime.liveControl(owner, sessionId, context, `${getGatewayPrincipal(c).principalId}:${clientId}`, input, () => authorizePhoneAccess(actor, true));
+		} catch (error) {
+			const latest = phoneAssistance(owner);
+			if (input.op !== "handback" || !wait || latest?.id !== wait.id || latest.status === "open" || !(error instanceof PhoneError) || !["PHONE_CONTROL_CHANGED", "PHONE_CONTROL_BUSY"].includes(error.code)) throw error;
+			result = liveStatus(owner, sessionId, context, `${getGatewayPrincipal(c).principalId}:${clientId}`);
+		}
+		if (input.op === "cancel") cancelPhoneAssistance(owner);
+		if (input.op === "handback") {
+			if (wait?.status === "open") service.resumePhoneAssistance(owner, wait.id);
+			else if (transcriptId && result.resumeTurnRequired) {
+				if (!(await service.submitSessionInput({
+					conversationId: owner,
+					expectedTranscriptId: transcriptId,
+					clientMessageId: `phone-handback:${sessionId}:${input.epoch}`,
+					delivery: "next",
+					content: "手机已交还，请先确认当前页面，继续未完成的任务；已完成的步骤不要重复。",
+					origin: {
+						type: "system",
+						source: "internal"
+					}
+				})).ok) throw new PhoneError("PHONE_RESUME_FAILED", "Phone control returned. Send Continue in chat to resume the task.", 409);
+			}
 		}
 		c.header("Cache-Control", "no-store");
 		return c.json({

package/dist/src/gateway/hono/routes/session-command-handler.js

@@ -114,7 +114,7 @@ async function handleSessionCommand(c, deps, materialize = false) {
 		const payload = await receiveSessionCommand(deps.service, id.data, principal.principalId, command, async () => {
 			if (!("input" in command)) return [];
 			const endpoint = command.origin.type === "endpoint" ? deps.service.endpointTools.registry.get(command.origin.endpointId) : void 0;
-			const contexts = endpoint ? [deviceTurnSourceContext(endpoint, command.input.endpointContext)] : [];
+			const contexts = endpoint ? [deviceTurnSourceContext(endpoint, command.input.endpointContext, deps.service.endpointTools.contexts?.view(endpoint.endpointId), deps.service.endpointTools.locations?.list(endpoint.endpointId, id.data))] : [];
 			contexts.push(...(command.input.browserContexts ?? []).map(browserPageContextToAgentContext));
 			if (command.input.appContext) contexts.push(await deps.service.prepareSessionAppContext(command.input.appContext, principal, id.data, command.clientMessageId));
 			return contexts;

package/dist/src/gateway/hono/routes/session-input-handler.js

@@ -193,7 +193,8 @@ async function submitSessionInput(c, deps, conversationId, options) {
 				}, 409);
 			}
 		}
-		const sourceContexts = [deviceTurnSourceContext(deps.service.endpointTools.registry.get(origin.data.endpointId), environment.data), ...browserContexts.data.map(browserPageContextToAgentContext)];
+		const endpoint = deps.service.endpointTools.registry.get(origin.data.endpointId);
+		const sourceContexts = [deviceTurnSourceContext(endpoint, environment.data, deps.service.endpointTools.contexts?.view(endpoint.endpointId), deps.service.endpointTools.locations?.list(endpoint.endpointId, conversationId)), ...browserContexts.data.map(browserPageContextToAgentContext)];
 		if (body.appContext !== void 0) try {
 			sourceContexts.push(await deps.service.prepareSessionAppContext(body.appContext, getGatewayPrincipal(c), conversationId, typeof body.clientMessageId === "string" ? body.clientMessageId.trim() : ""));
 		} catch (error) {

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

@@ -1,6 +1,7 @@
 import { createLogger } from "../../../utils/logger/index.js";
 import { init_logger } from "../../../utils/logger.js";
 import { init_public_url, validatePublicUrl } from "../../../config/public-url.js";
+import { TunnelRecoveryProofRejectedError, TunnelRegistrationKeyRejectedError } from "../../../tunnel/broker-client.js";
 import { TUNNEL_REGISTRATION_SECRET_REQUIRED_CODE, TunnelRegistrationSecretError, getTunnelRegistrationSecretMeta, readTunnelRegistrationSecretFromConfigOnly, resolveTunnelBrokerUrl } from "../../../tunnel/env.js";
 import { logTunnelAudit } from "../../../tunnel/tunnel-audit.js";
 import { getTunnelService, hashGatewayToken } from "../../../tunnel/tunnel-service.js";
@@ -258,6 +259,15 @@ function registerTunnelRoutes(authenticated, deps) {
 			});
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
+			log.warn({
+				err,
+				errorMessage: message,
+				phase: "tunnel_start"
+			}, `Tunnel start failed: ${message}`);
+			if (err instanceof TunnelRegistrationKeyRejectedError || err instanceof TunnelRecoveryProofRejectedError) return c.json({
+				error: message,
+				code: err.code
+			}, 409);
 			if (err instanceof TunnelRegistrationSecretError) return c.json({
 				error: message,
 				code: TUNNEL_REGISTRATION_SECRET_REQUIRED_CODE

package/dist/src/gateway/security/gateway-scopes.js

@@ -17,7 +17,13 @@ function requiredGatewayScope(method, path) {
 	if (path === "/api/realtime/tickets" || path.startsWith("/api/status")) return "gateway.status";
 	if (path === "/api/device-auth/refresh" || path === "/api/devices/me") return "device.self";
 	if (path.startsWith("/api/devices/me/push")) return "notifications.self";
+	if (/^\/api\/phone\/conversations\/[^/]+\/summary$/.test(path) && method === "GET") return "sessions.read";
+	if (/^\/api\/phone\/conversations\/[^/]+$/.test(path) && method === "GET") return "phone.view";
+	if (/^\/api\/phone\/conversations\/[^/]+\/[^/]+\/frame$/.test(path) && method === "GET") return "phone.view";
+	if (/^\/api\/phone\/conversations\/[^/]+\/[^/]+\/video-ticket$/.test(path) && method === "POST") return "phone.view";
+	if (/^\/api\/phone\/conversations\/[^/]+\/[^/]+\/control$/.test(path) && method === "POST") return "phone.control";
 	if (path.startsWith("/api/endpoint-tools")) return "device.self";
+	if (path === "/api/user-context/environment" || path.startsWith("/api/user-context/environment/")) return "device.self";
 	if (path === "/api/personal-agent/activity") return "tasks.read";
 	if (path === "/api/personal-agent" || path.startsWith("/api/personal-agent/")) return methodScope(method, "sessions.read", "sessions.write");
 	if (path.startsWith("/api/browser/recordings/")) return "device.self";

package/dist/src/gateway/security/phone-access.d.ts

@@ -0,0 +1,4 @@
+import type { GatewayPrincipal } from './gateway-principal.js';
+export declare function phoneAdministrator(principal: GatewayPrincipal): boolean;
+/** Reload mutable device grants even for already established streams. */
+export declare function authorizePhoneAccess(principal: GatewayPrincipal, control?: boolean): void;