@xopcai/xopc 0.0.420 → 0.0.422

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/projects.js

@@ -6,12 +6,12 @@ import { loadTranscriptRowsForSession } from "../../../storage/sqlite/transcript
 import "../../../storage/sqlite/index.js";
 import { ActivityService } from "../../../activity/service.js";
 import "../../../activity/index.js";
-import { CapabilityError } from "../../../capabilities/runtime/errors.js";
-import "../../../capabilities/runtime/dispatcher.js";
 import { listKnowledgeItems, writeKnowledgeItem } from "../../../knowledge-memory/repository.js";
 import "../../../knowledge-memory/index.js";
 import { resolveEffectiveAgentProfile } from "../../../config/agent-profile.js";
 import { TaskReadModelProjector } from "../../../tasks/task-read-model-projector.js";
+import { CapabilityError } from "../../../capabilities/runtime/errors.js";
+import "../../../capabilities/runtime/dispatcher.js";
 import { ProjectWorkspaceConflictError, ProjectWorkspaceMissingError } from "../../../projects/workspace-project.js";
 import { inferProjectExecutionMode, inferProjectKind } from "../../../projects/project-kind.js";
 import { ProjectDeletionBlockedError, ProjectWorkspaceInUseError } from "../../../projects/project-service.js";

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

@@ -5,9 +5,9 @@ import { endpointContextSchema } from "../../../../packages/gateway-contract/src
 import { parseUserTurnDocument, userTurnDocumentRefIds } from "../../../../packages/gateway-contract/src/user-turn-document.js";
 import { init_src } from "../../../../packages/gateway-contract/src/index.js";
 import { endpointTurnClaimSchema, init_src as init_src$1 } from "../../../../packages/endpoint-tools-protocol/src/index.js";
+import { init_providers, resolveModel } from "../../../providers/index.js";
 import { CapabilityError } from "../../../capabilities/runtime/errors.js";
 import "../../../capabilities/runtime/dispatcher.js";
-import { init_providers, resolveModel } from "../../../providers/index.js";
 import { getModelThinking } from "../../../providers/model-thinking.js";
 import { parseTurnContextRefs } from "../../../agent/source-context/types.js";
 import { validateWebchatAttachments, validateWebchatContent } from "../../chat-limits.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/tasks.js

@@ -6,9 +6,9 @@ import { hasGatewayScope } from "../../security/gateway-scopes.js";
 import { enqueueTaskChangedEvent, init_task_change_events } from "../../../tasks/task-change-events.js";
 import { TaskRepository, init_task_repository } from "../../../tasks/task-repository.js";
 import { TaskRunRepository, init_task_run_repository } from "../../../tasks/task-run-repository.js";
+import { TaskConversationRepository } from "../../../tasks/task-conversation-repository.js";
 import { CapabilityError } from "../../../capabilities/runtime/errors.js";
 import "../../../capabilities/runtime/dispatcher.js";
-import { TaskConversationRepository } from "../../../tasks/task-conversation-repository.js";
 import { TaskCollaborationRepository } from "../../../tasks/task-collaboration-repository.js";
 import { TaskCriterionReviewRepository } from "../../../tasks/task-criterion-review-repository.js";
 import { TaskContextMutationOutputSchema } from "../../../tasks/capabilities/relations.js";

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/image-generation-setup.js

@@ -1,11 +1,11 @@
 import { normalizeAgentId } from "../agent-catalog/id.js";
 import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
 import { init_agent_scope } from "../agent/agent-scope.js";
-import { AgentCatalogService } from "../agent-catalog/service.js";
 import { ConfigSchema, init_schema } from "../config/schema.js";
 import { resolveEffectiveAgentConfigForAgent } from "../config/agent-profile.js";
 import { fetchWithTimeoutGuarded } from "../media-shared/http/provider-http.js";
 import "../media-shared/http/index.js";
+import { AgentCatalogService } from "../agent-catalog/service.js";
 import { getImageGenerationProvider, listImageGenerationProvidersSummary } from "../agent/image/generation/provider-registry.js";
 //#region src/gateway/image-generation-setup.ts
 init_repository();

package/dist/src/gateway/respawn.js

@@ -52,7 +52,8 @@ function restartGatewayProcessWithFreshPid() {
 		const child = spawn(process.execPath, args, {
 			env: process.env,
 			detached: true,
-			stdio: "inherit"
+			stdio: process.platform === "win32" ? "ignore" : "inherit",
+			windowsHide: true
 		});
 		child.unref();
 		log.info({ pid: child.pid }, "New process spawned, exiting");

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;

package/dist/src/gateway/security/phone-access.js

@@ -0,0 +1,20 @@
+import { getDevice, isDeviceAccessSessionActive } from "../../storage/sqlite/device-access-repository.js";
+import { PhoneError, init_contracts } from "../../phone/contracts.js";
+//#region src/gateway/security/phone-access.ts
+init_contracts();
+function phoneAdministrator(principal) {
+	return principal.kind !== "device" && principal.scopes.includes("gateway.admin");
+}
+/** Reload mutable device grants even for already established streams. */
+function authorizePhoneAccess(principal, control = false) {
+	if (phoneAdministrator(principal)) return;
+	const device = principal.deviceId ? getDevice(principal.deviceId) : void 0;
+	if (principal.kind !== "device" || !device || device.platform === "chrome" || !principal.accessSessionId || !isDeviceAccessSessionActive(device.id, principal.accessSessionId)) throw new PhoneError("PHONE_ACCESS_REVOKED", "Phone access is unavailable for this device", 403);
+	if (![
+		"sessions.read",
+		"phone.view",
+		...control ? ["sessions.write", "phone.control"] : []
+	].every((scope) => device.scopes.includes(scope))) throw new PhoneError("PHONE_PERMISSION_REQUIRED", "Authorize phone access in Gateway device settings", 403);
+}
+//#endregion
+export { authorizePhoneAccess, phoneAdministrator };

package/dist/src/gateway/service/agent-runner.js

@@ -15,6 +15,7 @@ import { TaskCollaborationRepository } from "../../tasks/task-collaboration-repo
 import { reserveEmbeddedRunCancellation } from "../../agent/embedded/runs.js";
 import { TaskApplicationService } from "../../tasks/task-application-service.js";
 import { EphemeralClarificationWaiter } from "../ephemeral-clarification-waiter.js";
+import { completePhoneAssistanceFromUser, preparePhoneContinuation } from "../../phone/assistance-service.js";
 import { describeActiveExecution } from "./active-execution.js";
 import { runGatewayAgent } from "./run-gateway-agent.js";
 import { NextTurnSuggestionService } from "../next-turn-suggestions/service.js";
@@ -67,9 +68,10 @@ var GatewayAgentRunner = class {
 			});
 		});
 		this.inputs = new SessionInputCoordinator({
-			beforeExecute: opts.validateConnectionResume,
+			beforeExecute: async (input) => (await opts.validateConnectionResume?.(input) ?? true) && await preparePhoneContinuation(input, opts.getConfig()),
 			continueConnection: opts.continueConnection,
 			cancelConnection: opts.cancelConnection,
+			completePhone: (wait) => completePhoneAssistanceFromUser(wait, opts.getConfig()),
 			prioritizeInput: (input) => (input.origin.type !== "system" || input.origin.source === "cli") && isPersonalConversation(input.conversationId),
 			interrupt: async (conversationId, runId, reason) => {
 				const execution = this.activeExecutionBySession.get(conversationId);

package/dist/src/gateway/service/config-coordinator.d.ts

@@ -330,6 +330,7 @@ export declare class GatewayConfigCoordinator {
             hierarchicalPlanning: boolean;
             maxActionsPerSession: number;
             maxModelRequests: number;
+            modelRequestTimeoutMs: number;
             maxOperationDurationMs: number;
             maxSessionDurationMs: number;
             idleDisconnectMs: number;

package/dist/src/gateway/service/run-gateway-agent.js

@@ -13,6 +13,7 @@ import { getConversationRouting } from "../../storage/sqlite/conversation-reposi
 import { init_session_key } from "../../routing/session-key.js";
 import { resolveAgentTurnTimeoutMs } from "../../agent/orchestration/run-agent-turn-with-timeout.js";
 import { isPersonalConversation } from "../../personal-agent/repository.js";
+import { isPhoneAssistanceSuspended } from "../../phone/assistance.js";
 import { recordPersonalPerformance } from "../../personal-agent/performance.js";
 import { resolveExecutionContext } from "../../tasks/execution-context.js";
 import { TaskRunCoordinator } from "../../tasks/task-run-coordinator.js";
@@ -224,7 +225,7 @@ async function* runGatewayAgent(deps, message, channel, chatId, origin, attachme
 				for await (const event of coalesceThinkingDeltas(mappedEvents)) yield* emitAndYield([event]);
 				const connectionSuspended = isConnectionSuspended(conversationId, runId);
 				const clarificationSuspended = isClarificationSuspended(conversationId, runId);
-				const suspended = connectionSuspended || clarificationSuspended;
+				const suspended = connectionSuspended || clarificationSuspended || isPhoneAssistanceSuspended(conversationId, runId);
 				const cancelled = mergedSignal.aborted || embeddedAborted;
 				const endStatus = cancelled ? "cancelled" : suspended ? "suspended" : streamError ? "error" : "success";
 				const endSummary = cancelled ? "Interrupted" : connectionSuspended ? "Waiting for connection" : clarificationSuspended ? "Waiting for user input" : streamError ?? "Message processed successfully";

package/dist/src/gateway/service/session-input-coordinator.d.ts

@@ -1,3 +1,4 @@
+import { type PhoneAssistance } from '../../phone/assistance.js';
 import type { TurnOrigin } from '@xopcai/endpoint-tools-protocol';
 import type { ConnectionWait } from '@xopcai/gateway-contract';
 import { type SessionInput } from '../../storage/sqlite/session-input-repository.js';
@@ -36,6 +37,7 @@ export declare class SessionInputCoordinator {
         beforeExecute?: (input: SessionInput) => Promise<boolean>;
         continueConnection?: (wait: ConnectionWait, idempotencyKey: string) => Promise<void>;
         cancelConnection?: (wait: ConnectionWait) => void;
+        completePhone?: (wait: PhoneAssistance) => Promise<void>;
         sessionExists: (conversationId: string) => Promise<boolean>;
         execute: (input: {
             inputReceivedAtMs?: number;
@@ -58,6 +60,7 @@ export declare class SessionInputCoordinator {
     });
     isAcceptingInput(conversationId: string): boolean;
     snapshot(conversationId: string): SessionInputState;
+    resumePhone(conversationId: string, waitId: string): void;
     private connectionTarget;
     prepareInput(input: SubmitSessionInput): Promise<{
         payload?: import("../../storage/sqlite/session-input-repository.js").SessionInputPayload;