@xopcai/xopc 0.0.421 → 0.0.422

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;

package/dist/src/gateway/service/session-input-coordinator.js

@@ -10,6 +10,7 @@ import { cancelConnectionObjective, consumeConnectionResume, getActiveConnection
 import { appendTranscriptEntry } from "../../storage/sqlite/transcript-repository.js";
 import "../../storage/sqlite/index.js";
 import { emitSessionTranscriptUpdate } from "../../session/transcript-events.js";
+import { consumePhoneAssistance, finishPhoneAssistance, phoneAssistance, queuePhoneAssistance, reconcilePhoneAssistance } from "../../phone/assistance.js";
 import { summarizeSourceContext } from "../../agent/source-context/types.js";
 import { TaskApplicationService } from "../../tasks/task-application-service.js";
 import { injectSourceContextsIntoUserMessage } from "../../agent/source-context/injector.js";
@@ -91,6 +92,11 @@ var SessionInputCoordinator = class {
 	snapshot(conversationId) {
 		return getSessionInputState(conversationId);
 	}
+	resumePhone(conversationId, waitId) {
+		queuePhoneAssistance(conversationId, waitId);
+		this.publish(conversationId);
+		this.drain(conversationId);
+	}
 	connectionTarget(conversationId, runtime = this.snapshot(conversationId)) {
 		const active = runtime.activeInputId ? getSessionInputById(conversationId, runtime.activeInputId) : void 0;
 		return getActiveConnectionWait(conversationId) ?? (active?.kind === "connection_resume" && active.payload ? getConnectionWait(active.payload.waitId) : void 0);
@@ -346,6 +352,41 @@ var SessionInputCoordinator = class {
 			};
 		}
 		const runtime = this.snapshot(conversationId);
+		const phoneWait = phoneAssistance(conversationId);
+		if (/^(?:我已(?:完成|登录|登陆|输入验证码)[，,、\s]*(?:请)?继续(?:原任务|任务)?|(?:登录|登陆|验证码|手机操作)(?:已)?完成[了]?[，,、\s]*(?:请)?继续(?:原任务|任务)?|好了[，,、\s]*继续(?:原任务|任务)?|(?:i(?: have|'ve) )?(?:logged in|finished on the phone|completed the phone action)[,\s]+(?:please )?(?:continue|resume)(?: the task)?)[。.!！\s]*$/iu.test(content) && phoneWait?.status === "open" && this.deps.completePhone && input.origin.type !== "system" && !attachments?.length && !input.contextRefs?.length && !getActiveConnectionWait(conversationId) && !getActiveClarification(conversationId)) {
+			if (input.expectedTranscriptId && input.expectedTranscriptId !== phoneWait.transcriptId) return {
+				ok: false,
+				code: "SESSION_CHANGED"
+			};
+			await this.deps.completePhone(phoneWait);
+			runSqliteWriteTransaction(() => {
+				const row = insertSessionInput({
+					id: crypto.randomUUID(),
+					conversationId,
+					clientMessageId,
+					expectedTranscriptId: phoneWait.transcriptId,
+					content,
+					requestedDelivery: "next",
+					effectiveDelivery: "next",
+					status: "queued",
+					origin: input.origin
+				});
+				queuePhoneAssistance(conversationId, phoneWait.id);
+				appendTranscriptEntry(conversationId, {
+					role: "user",
+					content,
+					timestamp: row.createdAtMs
+				});
+				setSessionInputStatus(row.id, "completed");
+			});
+			emitSessionTranscriptUpdate({ conversationId });
+			this.drain(conversationId);
+			return {
+				ok: true,
+				effectiveDelivery: "next",
+				state: this.publish(conversationId)
+			};
+		}
 		const wait = this.connectionTarget(conversationId, runtime);
 		const control = wait?.principalId === "local-owner" ? connectionControl(input, wait) : void 0;
 		const payload = connectionInputPayload(wait, control);
@@ -436,7 +477,7 @@ var SessionInputCoordinator = class {
 						this.publish(conversationId);
 						continue;
 					}
-					allowed = allowed && consumeConnectionResume(input) && consumeClarificationResume(input);
+					allowed = allowed && consumeConnectionResume(input) && consumeClarificationResume(input) && consumePhoneAssistance(input);
 				} catch (err) {
 					log.warn({
 						err,
@@ -444,6 +485,7 @@ var SessionInputCoordinator = class {
 						runId,
 						inputId: input.id
 					}, "Session input preflight failed");
+					finishPhoneAssistance(input, false);
 					finishSessionInputRun(conversationId, runId, "failed", "Input preflight failed");
 					if (input.kind === "connection_resume") reconcileConnectionWaits();
 					this.publish(conversationId);
@@ -451,6 +493,7 @@ var SessionInputCoordinator = class {
 				}
 				if (!allowed) {
 					finishSessionInputRun(conversationId, runId, "cancelled");
+					finishPhoneAssistance(input, false);
 					this.publish(conversationId);
 					continue;
 				}
@@ -513,6 +556,7 @@ var SessionInputCoordinator = class {
 				}
 				const terminal = cancelled ? "cancelled" : result.status === "suspended" ? "suspended" : result.status === "ok" ? "completed" : result.status === "aborted" ? "cancelled" : "failed";
 				finishSessionInputRun(conversationId, runId, terminal, terminal === "failed" ? result.summary : void 0);
+				finishPhoneAssistance(input, terminal === "completed");
 				this.publish(conversationId);
 			}
 		} finally {
@@ -664,7 +708,11 @@ var SessionInputCoordinator = class {
 	recover() {
 		const interrupted = recoverSessionInputState();
 		new TaskRunRepository().reconcileCancelledRuns();
-		for (const conversationId of new Set([...interrupted, ...reconcileConnectionWaits(true)])) {
+		for (const conversationId of new Set([
+			...interrupted,
+			...reconcileConnectionWaits(true),
+			...reconcilePhoneAssistance()
+		])) {
 			this.publish(conversationId);
 			this.drain(conversationId);
 		}

package/dist/src/gateway/service.d.ts

@@ -155,6 +155,7 @@ export declare class GatewayService {
         ok: false;
         code: "BAD_REQUEST" | "QUEUE_FULL" | "CONTEXT_UNAVAILABLE" | "SESSION_CHANGED";
     }>;
+    resumePhoneAssistance(conversationId: string, waitId: string): void;
     withSessionInputSubmission<T>(conversationId: string, operation: () => Promise<T>): Promise<T>;
     prepareSessionCommandInput(input: Parameters<GatewayAgentRunner['inputs']['prepareInput']>[0]): Promise<{
         payload?: import("../storage/sqlite/session-input-repository.js").SessionInputPayload;

package/dist/src/gateway/service.js

@@ -1093,6 +1093,9 @@ var GatewayService = class {
 	submitSessionInput(...args) {
 		return this.agentRunner.submitSessionInput(...args);
 	}
+	resumePhoneAssistance(conversationId, waitId) {
+		this.agentRunner.inputs.resumePhone(conversationId, waitId);
+	}
 	withSessionInputSubmission(conversationId, operation) {
 		return this.agentRunner.inputs.withSubmission(conversationId, operation);
 	}
@@ -1320,6 +1323,10 @@ var GatewayService = class {
 		await this.localApps.recoverPendingReleases();
 		const { recoverCapabilityImports } = await import("../imports/runtime.js");
 		await recoverCapabilityImports();
+		if (getSqliteDatabase().prepare("SELECT 1 FROM durable_state WHERE namespace = 'phone.location-environment' LIMIT 1").get()) {
+			const { getPhoneRuntime } = await import("../phone/runtime.js");
+			getPhoneRuntime().environment.sweep().catch(() => log.warn({ phase: "phone_location_recovery" }, "Phone location recovery remains pending"));
+		}
 		this.createNotificationService().start();
 		this.startTime = Date.now();
 		this.running = true;
@@ -1631,6 +1638,7 @@ var GatewayService = class {
 		log.debug("Stopping gateway service...");
 		await this._workDiscovery?.stop();
 		this.readiness.markStarting();
+		await this.endpointTools.locations.close();
 		this.endpointTools.close();
 		await this.sideChats.disposeAll();
 		this.homeIntelligenceHost?.stop();

package/dist/src/gateway/session-reset-service.js

@@ -1,6 +1,8 @@
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { isPersonalConversation } from "../personal-agent/repository.js";
+import { cancelPhoneAssistance } from "../phone/assistance.js";
+import { getPhoneRuntime } from "../phone/runtime.js";
 import { abortEmbeddedRun } from "../agent/embedded/runs.js";
 //#region src/gateway/session-reset-service.ts
 init_logger();
@@ -26,6 +28,8 @@ async function performSessionReset(conversationId, deps) {
 		ok: false,
 		error: "Session not found"
 	};
+	cancelPhoneAssistance(key);
+	await getPhoneRuntime().stop(key, "cancel");
 	try {
 		deps.getAgentService().evictSessionAgent(key);
 	} catch (err) {

package/dist/src/notifications/planner.js

@@ -136,15 +136,15 @@ function automationPlan(payload) {
 			},
 			priority: completed ? "normal" : "high",
 			title: completed ? {
-				en: "Automation completed",
-				zh: "自动化已完成"
+				en: `${run.automationName} · Completed`,
+				zh: `${run.automationName} · 已完成`
 			} : {
-				en: "Automation needs attention",
-				zh: "自动化需要处理"
+				en: `${run.automationName} · Needs attention`,
+				zh: `${run.automationName} · 需要处理`
 			},
 			body: {
-				en: (run.error || run.summary || run.automationName).slice(0, 180),
-				zh: (run.error || run.summary || run.automationName).slice(0, 180)
+				en: completed ? (run.summary || run.automationName).slice(0, 180) : "This run did not finish. Open it to see the reason and fix it in chat.",
+				zh: completed ? (run.summary || run.automationName).slice(0, 180) : "这次运行未完成，打开查看原因，或通过对话修复。"
 			},
 			payload: {
 				automationId: run.automationId,

package/dist/src/phone/assistance-service.d.ts

@@ -0,0 +1,6 @@
+import type { Config } from '../config/schema.js';
+import type { SessionInput } from '../storage/sqlite/session-input-repository.js';
+import { type PhoneAssistance } from './assistance.js';
+import { type PhoneRuntime } from './runtime.js';
+export declare function completePhoneAssistanceFromUser(wait: PhoneAssistance, config: Config, runtime?: PhoneRuntime): Promise<void>;
+export declare function preparePhoneContinuation(input: SessionInput, config: Config, runtime?: PhoneRuntime): Promise<boolean>;

package/dist/src/phone/assistance-service.js

@@ -0,0 +1,32 @@
+import { getSessionMetadata } from "../storage/sqlite/session-read-repository.js";
+import { init_session_repository } from "../storage/sqlite/session-repository.js";
+import { PhoneError, init_contracts } from "./contracts.js";
+import { phoneAssistance } from "./assistance.js";
+import { getPhoneRuntime, phoneExecutionContext } from "./runtime.js";
+import { randomUUID } from "node:crypto";
+//#region src/phone/assistance-service.ts
+init_session_repository();
+init_contracts();
+async function completePhoneAssistanceFromUser(wait, config, runtime = getPhoneRuntime()) {
+	if (getSessionMetadata(wait.conversationId)?.agentId !== wait.checkpoint.report.agentId) throw new PhoneError("PHONE_ACCESS_CHANGED", "The conversation Agent changed", 409);
+	const context = phoneExecutionContext(config, wait.checkpoint.report.agentId);
+	await runtime.restoreAssistance(wait.checkpoint, context, void 0, wait.id);
+	await runtime.completeAssistanceForUser(wait.conversationId, context);
+}
+async function preparePhoneContinuation(input, config, runtime = getPhoneRuntime()) {
+	if (!input.clientMessageId.startsWith("phone-assistance:")) return true;
+	const wait = phoneAssistance(input.conversationId);
+	if (!wait || wait.queuedInputId !== input.id || wait.status !== "queued") return false;
+	if (getSessionMetadata(input.conversationId)?.agentId !== wait.checkpoint.report.agentId) throw new PhoneError("PHONE_ACCESS_CHANGED", "The conversation Agent changed. Inspect the original task before continuing.", 409);
+	const context = phoneExecutionContext(config, wait.checkpoint.report.agentId);
+	const report = await runtime.restoreAssistance(wait.checkpoint, context, void 0, wait.id);
+	if (report.controlOwner === "human") throw new PhoneError("PHONE_PAUSED", "The user is still operating the phone. Finish and continue again.", 409);
+	if (report.status === "needs_user" || report.status === "paused") await runtime.liveControl(input.conversationId, report.sessionId, context, `phone-resume:${wait.id}`, {
+		op: "handback",
+		epoch: report.controlEpoch,
+		operationId: randomUUID()
+	});
+	return true;
+}
+//#endregion
+export { completePhoneAssistanceFromUser, preparePhoneContinuation };

package/dist/src/phone/assistance.d.ts

@@ -0,0 +1,40 @@
+import { type SessionInput } from '../storage/sqlite/session-input-repository.js';
+import { type PhoneReport, type PhoneTaskContract } from './contracts.js';
+export type PhoneCheckpoint = {
+    report: Pick<PhoneReport, 'sessionId' | 'deviceId' | 'deviceName' | 'owner' | 'agentId' | 'modelRef' | 'executionMode'>;
+    deviceRevision: number;
+    task: PhoneTaskContract;
+    usage: {
+        actions: number;
+        modelRequests: number;
+        activeDurationMs: number;
+    };
+};
+export type PhoneAssistance = {
+    id: string;
+    conversationId: string;
+    transcriptId: string;
+    originRunId: string;
+    toolCallId: string;
+    checkpoint: PhoneCheckpoint;
+    version: number;
+    createdAt: number;
+    status: 'open' | 'queued' | 'resuming' | 'completed' | 'cancelled';
+    queuedInputId?: string;
+    taskRunId?: string;
+    objectiveInputId?: string;
+};
+export declare function phoneAssistance(conversationId: string): PhoneAssistance | undefined;
+export declare function pendingPhoneAssistance(): PhoneAssistance[];
+export declare function isPhoneAssistanceSuspended(conversationId: string, runId: string): boolean;
+export declare function requirePhoneAssistance(conversationId: string, runId: string, toolCallId: string, checkpoint: PhoneCheckpoint): PhoneAssistance;
+export declare function cancelPhoneAssistance(conversationId: string): void;
+/** The wait and its deduplicated continuation commit together, even while the old run is closing. */
+export declare function queuePhoneAssistance(conversationId: string, waitId: string): PhoneAssistance;
+export declare function consumePhoneAssistance(input: SessionInput): boolean;
+export declare function updatePhoneCheckpoint(conversationId: string, checkpoint: PhoneCheckpoint): void;
+export declare function phoneResumeForRun(conversationId: string, runId: string): PhoneAssistance | undefined;
+/** Interrupted continuations require another explicit handback, never automatic replay after restart. */
+export declare function reconcilePhoneAssistance(): string[];
+export declare function finishPhoneAssistance(input: SessionInput, succeeded: boolean): void;
+export declare function phoneAssistanceReport(wait: PhoneAssistance): PhoneReport;

package/dist/src/phone/assistance.js

@@ -0,0 +1,273 @@
+import { init_connection, isXopcDatabaseOpen } from "../storage/sqlite/connection.js";
+import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { init_session_instance_repository, readCurrentTranscriptId } from "../storage/sqlite/session-instance-repository.js";
+import { findSessionInputByRunId, getSessionInputById, init_session_input_repository, insertSessionInput } from "../storage/sqlite/session-input-repository.js";
+import { TaskRunRepository, init_task_run_repository } from "../tasks/task-run-repository.js";
+import { PhoneError, init_contracts } from "./contracts.js";
+import { DurableState } from "../storage/sqlite/durable-state.js";
+import { randomUUID } from "node:crypto";
+//#region src/phone/assistance.ts
+init_connection();
+init_transaction();
+init_session_instance_repository();
+init_session_input_repository();
+init_contracts();
+init_task_run_repository();
+const waits = new DurableState("phone.assistance");
+function markTaskWaiting(wait) {
+	if (!wait.taskRunId) return;
+	const runs = new TaskRunRepository();
+	const run = runs.get(wait.taskRunId);
+	if (run?.status !== "running") return;
+	if (!runs.listActiveWaits(run.taskId).some((item) => item.taskRunId === run.id && item.condition.phoneTaskId === wait.checkpoint.task.taskId)) runs.createWait({
+		taskId: run.taskId,
+		taskRunId: run.id,
+		kind: "user_input",
+		reason: "Phone requires manual operation",
+		condition: {
+			phoneAssistanceId: wait.id,
+			phoneTaskId: wait.checkpoint.task.taskId
+		}
+	});
+	runs.setStatus({
+		runId: run.id,
+		expectedVersion: run.version,
+		from: ["running"],
+		to: "waiting",
+		actor: { kind: "system" }
+	});
+}
+function phoneAssistance(conversationId) {
+	if (!isXopcDatabaseOpen()) return void 0;
+	const wait = waits.get(conversationId);
+	if (wait && readCurrentTranscriptId(getSqliteDatabase(), conversationId) !== wait.transcriptId) {
+		waits.delete(conversationId);
+		return;
+	}
+	return wait;
+}
+function pendingPhoneAssistance() {
+	return isXopcDatabaseOpen() ? waits.values().filter((wait) => ["open", "queued"].includes(wait.status) && phoneAssistance(wait.conversationId)?.id === wait.id) : [];
+}
+function isPhoneAssistanceSuspended(conversationId, runId) {
+	return phoneAssistance(conversationId)?.originRunId === runId;
+}
+function requirePhoneAssistance(conversationId, runId, toolCallId, checkpoint) {
+	return runSqliteWriteTransaction((db) => {
+		const transcriptId = readCurrentTranscriptId(db, conversationId);
+		if (!transcriptId) throw new PhoneError("PHONE_CONVERSATION_NOT_FOUND", "Phone assistance requires a saved conversation", 409);
+		const current = phoneAssistance(conversationId);
+		if (current?.originRunId === runId && current.toolCallId === toolCallId) return current;
+		const origin = findSessionInputByRunId(conversationId, runId);
+		const wait = {
+			id: randomUUID(),
+			conversationId,
+			transcriptId,
+			originRunId: runId,
+			toolCallId,
+			checkpoint,
+			status: "open",
+			version: 1,
+			createdAt: Date.now(),
+			taskRunId: origin?.taskRunId,
+			objectiveInputId: current?.queuedInputId === origin?.id ? current?.objectiveInputId : origin?.id
+		};
+		markTaskWaiting(wait);
+		waits.set(conversationId, wait);
+		return wait;
+	});
+}
+function cancelPhoneAssistance(conversationId) {
+	if (!isXopcDatabaseOpen()) return;
+	runSqliteWriteTransaction(() => {
+		const wait = isXopcDatabaseOpen() ? waits.get(conversationId) : void 0;
+		if (!wait) return;
+		if (wait.taskRunId && [
+			"open",
+			"queued",
+			"resuming"
+		].includes(wait.status)) {
+			const runs = new TaskRunRepository();
+			const run = runs.get(wait.taskRunId);
+			if (run && [
+				"queued",
+				"running",
+				"waiting",
+				"verifying"
+			].includes(run.status)) {
+				for (const item of runs.listActiveWaits(run.taskId)) if (item.condition.phoneTaskId === wait.checkpoint.task.taskId) runs.resolveWait({
+					waitId: item.id,
+					actor: { kind: "user" },
+					resolution: { cancelled: true }
+				});
+				runs.finalize({
+					runId: run.id,
+					expectedVersion: run.version,
+					actor: { kind: "user" },
+					terminalCode: "cancelled_by_user",
+					receipt: {
+						status: "cancelled",
+						summary: "Phone task cancelled",
+						changes: [],
+						evidence: [],
+						verification: {
+							status: "unverified",
+							checks: []
+						},
+						remainingWork: [],
+						needsUser: false,
+						completionVerdict: "not_achieved"
+					}
+				});
+			}
+		}
+		waits.set(conversationId, {
+			...wait,
+			status: "cancelled",
+			version: wait.version + 1
+		});
+	});
+}
+/** The wait and its deduplicated continuation commit together, even while the old run is closing. */
+function queuePhoneAssistance(conversationId, waitId) {
+	return runSqliteWriteTransaction(() => {
+		const wait = phoneAssistance(conversationId);
+		if (!wait || wait.id !== waitId || wait.status === "cancelled") throw new PhoneError("PHONE_ASSISTANCE_CHANGED", "The phone task changed. Refresh before continuing.", 409);
+		if (wait.status !== "open") return wait;
+		const original = (wait.objectiveInputId ? getSessionInputById(conversationId, wait.objectiveInputId) : void 0) ?? findSessionInputByRunId(conversationId, wait.originRunId);
+		const input = insertSessionInput({
+			id: randomUUID(),
+			conversationId,
+			expectedTranscriptId: wait.transcriptId,
+			clientMessageId: `phone-assistance:${wait.id}`,
+			requestedDelivery: "next",
+			effectiveDelivery: "next",
+			status: "queued",
+			content: `用户已完成手机上的人工操作，请继续原任务。原请求时间：${new Date(original?.createdAtMs ?? wait.createdAt).toISOString()}；原目标：${original?.content ?? wait.checkpoint.task.goal}。相对日期沿用原请求时间。先观察当前页面，不重复已完成操作，沿用 taskId 和剩余预算。手机片段：${JSON.stringify(wait.checkpoint.task)}`,
+			origin: {
+				type: "system",
+				source: "internal"
+			},
+			thinking: original?.thinking,
+			taskRunId: original?.taskRunId,
+			contextRefs: original?.contextRefs,
+			contextSnapshots: original?.contextSnapshots
+		});
+		if (input.origin.type !== "system" || input.origin.source !== "internal" || input.status !== "queued") throw new PhoneError("PHONE_ASSISTANCE_CHANGED", "The continuation request changed. Refresh before continuing.", 409);
+		const next = {
+			...wait,
+			status: "queued",
+			queuedInputId: input.id,
+			version: wait.version + 1
+		};
+		waits.set(conversationId, next);
+		return next;
+	});
+}
+function consumePhoneAssistance(input) {
+	if (!input.clientMessageId.startsWith("phone-assistance:")) return true;
+	return runSqliteWriteTransaction(() => {
+		const wait = phoneAssistance(input.conversationId);
+		if (!wait || wait.queuedInputId !== input.id || wait.status !== "queued" || input.origin.type !== "system" || input.origin.source !== "internal") return false;
+		if (wait.taskRunId) {
+			const runs = new TaskRunRepository();
+			const run = runs.get(wait.taskRunId);
+			if (!run || run.status !== "waiting") return false;
+			const active = runs.listActiveWaits(run.taskId).filter((item) => item.taskRunId === run.id);
+			if (active.some((item) => item.condition.phoneTaskId !== wait.checkpoint.task.taskId)) return false;
+			for (const item of active) runs.resolveWait({
+				waitId: item.id,
+				actor: { kind: "system" },
+				resolution: { phoneAssistanceId: wait.id }
+			});
+			runs.setStatus({
+				runId: run.id,
+				expectedVersion: run.version,
+				from: ["waiting"],
+				to: "running",
+				actor: { kind: "system" }
+			});
+		}
+		waits.set(input.conversationId, {
+			...wait,
+			status: "resuming",
+			version: wait.version + 1
+		});
+		return true;
+	});
+}
+function updatePhoneCheckpoint(conversationId, checkpoint) {
+	const wait = phoneAssistance(conversationId);
+	if (wait?.status === "resuming" && wait.checkpoint.task.taskId === checkpoint.task.taskId) waits.set(conversationId, {
+		...wait,
+		checkpoint
+	});
+}
+function phoneResumeForRun(conversationId, runId) {
+	const wait = phoneAssistance(conversationId);
+	if (!wait?.queuedInputId || wait.status !== "resuming") return void 0;
+	return getSessionInputById(conversationId, wait.queuedInputId)?.runId === runId ? wait : void 0;
+}
+/** Interrupted continuations require another explicit handback, never automatic replay after restart. */
+function reconcilePhoneAssistance() {
+	if (!isXopcDatabaseOpen()) return [];
+	const conversations = [];
+	for (const wait of waits.values()) {
+		if (phoneAssistance(wait.conversationId)?.id !== wait.id) continue;
+		const input = wait.queuedInputId ? getSessionInputById(wait.conversationId, wait.queuedInputId) : void 0;
+		if (wait.status === "resuming" || wait.status === "queued" && input?.status !== "queued") {
+			const next = {
+				...wait,
+				status: "open",
+				queuedInputId: void 0,
+				id: randomUUID(),
+				version: wait.version + 1
+			};
+			markTaskWaiting(next);
+			waits.set(wait.conversationId, next);
+		} else if (wait.status === "queued") conversations.push(wait.conversationId);
+	}
+	return conversations;
+}
+function finishPhoneAssistance(input, succeeded) {
+	if (!isXopcDatabaseOpen()) return;
+	runSqliteWriteTransaction(() => {
+		const wait = phoneAssistance(input.conversationId);
+		if (wait?.queuedInputId !== input.id || !["queued", "resuming"].includes(wait.status)) return;
+		const next = {
+			...wait,
+			status: succeeded ? "completed" : "open",
+			...succeeded ? {} : {
+				id: randomUUID(),
+				queuedInputId: void 0
+			},
+			version: wait.version + 1
+		};
+		if (!succeeded) markTaskWaiting(next);
+		waits.set(input.conversationId, next);
+	});
+}
+function phoneAssistanceReport(wait) {
+	return {
+		...wait.checkpoint.report,
+		assistanceId: wait.id,
+		reconnectRequired: true,
+		mock: false,
+		mode: "control",
+		status: wait.status === "completed" ? "completed" : "needs_user",
+		controlOwner: "none",
+		controlEpoch: 1,
+		handoff: "idle",
+		actions: wait.checkpoint.usage.actions,
+		modelRequests: wait.checkpoint.usage.modelRequests,
+		createdAt: wait.createdAt,
+		updatedAt: wait.createdAt,
+		verified: false,
+		verificationLevel: "none",
+		steps: [],
+		stopReason: "user_takeover",
+		message: "任务进度已保留。请接管手机完成操作，然后继续任务。"
+	};
+}
+//#endregion
+export { cancelPhoneAssistance, consumePhoneAssistance, finishPhoneAssistance, isPhoneAssistanceSuspended, pendingPhoneAssistance, phoneAssistance, phoneAssistanceReport, phoneResumeForRun, queuePhoneAssistance, reconcilePhoneAssistance, requirePhoneAssistance, updatePhoneCheckpoint };

package/dist/src/phone/cloud-phones.d.ts

@@ -2,6 +2,7 @@ import { CloudAdbConnection, PhoneCloudKeyStore } from './cloud-adb.js';
 import { CloudScrcpyProvider } from './cloud-scrcpy.js';
 import { type PhoneDevice } from './contracts.js';
 import type { PhoneRepository } from './repository.js';
+import { WuyingLocationAdapter } from './wuying-location.js';
 export declare class CloudPhones {
     private repository;
     private keys;
@@ -23,6 +24,10 @@ export declare class CloudPhones {
     cancel(owner: string, token: string): void;
     driver(device: PhoneDevice): Promise<import("./adb-driver.js").AdbPhoneDriver>;
     interactive(device: PhoneDevice, failed: () => void): Promise<CloudScrcpyProvider>;
+    locationAdapter(device: PhoneDevice): Promise<{
+        adapter: WuyingLocationAdapter;
+        close: () => void;
+    }>;
     disconnect(id: string): void;
     remove(device: PhoneDevice): Promise<void>;
     close(): void;