@xopcai/xopc 0.0.420 → 0.0.422

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;

package/dist/src/phone/cloud-phones.js

@@ -2,6 +2,7 @@ import { PhoneError, init_contracts } from "./contracts.js";
 import { PhoneCloudKeyStore, parseCloudEndpoint, parseCloudPrivateKey } from "./cloud-adb-connection.js";
 import { CloudAdbConnection } from "./cloud-adb.js";
 import { CloudScrcpyProvider } from "./cloud-scrcpy.js";
+import { WuyingLocationAdapter } from "./wuying-location.js";
 import { randomUUID } from "node:crypto";
 import sharp from "sharp";
 //#region src/phone/cloud-phones.ts
@@ -126,6 +127,19 @@ var CloudPhones = class {
 		if (!binding) throw new PhoneError("PHONE_CONNECTION_INVALID", "Missing cloud connection");
 		return new CloudScrcpyProvider(binding.endpoint, await this.keys.load(binding.credentialId), failed, this.connect);
 	}
+	async locationAdapter(device) {
+		if (device.connection?.kind !== "aliyun-adb") throw new PhoneError("PHONE_ENV_UNSUPPORTED", "Choose an Alibaba cloud phone", 409);
+		const connection = this.connect(device.connection.endpoint, await this.keys.load(device.connection.credentialId));
+		return {
+			adapter: new WuyingLocationAdapter(async (args, signal) => (await connection.command("", [
+				"-s",
+				device.connection.endpoint,
+				"shell",
+				...args
+			], signal, 15e3)).toString()),
+			close: () => connection.dispose()
+		};
+	}
 	disconnect(id) {
 		this.connections.get(id)?.dispose();
 		this.connections.delete(id);

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

@@ -27,6 +27,7 @@ export declare const PhoneConfigSchema: z.ZodPrefault<z.ZodObject<{
     hierarchicalPlanning: z.ZodDefault<z.ZodBoolean>;
     maxActionsPerSession: z.ZodDefault<z.ZodNumber>;
     maxModelRequests: z.ZodDefault<z.ZodNumber>;
+    modelRequestTimeoutMs: z.ZodDefault<z.ZodNumber>;
     maxOperationDurationMs: z.ZodDefault<z.ZodNumber>;
     maxSessionDurationMs: z.ZodDefault<z.ZodNumber>;
     idleDisconnectMs: z.ZodDefault<z.ZodNumber>;
@@ -292,6 +293,9 @@ export type PhoneTaskFeedback = {
     nextAction: 'wait' | 'replan' | 'inspect' | 'user' | 'done';
 };
 export declare const PhoneInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    op: z.ZodLiteral<"request_user">;
+    reason: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
     op: z.ZodLiteral<"discover">;
 }, z.core.$strict>, z.ZodObject<{
     op: z.ZodLiteral<"set_mode">;
@@ -304,8 +308,8 @@ export declare const PhoneInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     op: z.ZodLiteral<"open">;
     deviceId: z.ZodOptional<z.ZodString>;
     mode: z.ZodEnum<{
-        observe: "observe";
         control: "control";
+        observe: "observe";
     }>;
     appPackage: z.ZodOptional<z.ZodString>;
     settingsPage: z.ZodOptional<z.ZodLiteral<"about-phone">>;
@@ -371,6 +375,8 @@ export type PhoneReading = {
     reason?: string;
 };
 export type PhoneReport = {
+    assistanceId?: string;
+    reconnectRequired?: boolean;
     sessionId: string;
     deviceId: string;
     deviceName: string;

package/dist/src/phone/contracts.js

@@ -16,6 +16,7 @@ var init_contracts = __esmMin((() => {
 		hierarchicalPlanning: z.boolean().default(false),
 		maxActionsPerSession: z.number().int().min(1).max(80).default(40),
 		maxModelRequests: z.number().int().min(1).max(120).default(60),
+		modelRequestTimeoutMs: z.number().int().min(1e3).max(3e5).default(45e3),
 		maxOperationDurationMs: z.number().int().min(1e3).max(9e5).default(3e5),
 		maxSessionDurationMs: z.number().int().min(1e3).max(9e5).default(9e5),
 		idleDisconnectMs: z.number().int().min(0).max(864e5).default(0)
@@ -130,6 +131,10 @@ var init_contracts = __esmMin((() => {
 		requestedOutputs: z.array(PhoneRequestedOutputSchema).max(8).refine((items) => new Set(items.map((item) => item.key)).size === items.length, "Output keys must be unique").optional()
 	};
 	PhoneInputSchema = z.discriminatedUnion("op", [
+		z.object({
+			op: z.literal("request_user"),
+			reason: z.string().trim().min(1).max(1e3)
+		}).strict(),
 		z.object({ op: z.literal("discover") }).strict(),
 		z.object({
 			op: z.literal("set_mode"),

package/dist/src/phone/environment-adapter.d.ts

@@ -0,0 +1,3 @@
+import type { PhoneEnvironmentAdapter } from '@xopcai/endpoint-tools-protocol';
+/** No environment writes until provider format, grants and cleanup are verified. */
+export declare const unsupportedPhoneEnvironmentAdapter: PhoneEnvironmentAdapter;

package/dist/src/phone/environment-adapter.js

@@ -0,0 +1,11 @@
+//#region src/phone/environment-adapter.ts
+/** No environment writes until provider format, grants and cleanup are verified. */
+const unsupportedPhoneEnvironmentAdapter = {
+	supportedFields: [],
+	async apply(_request, signal) {
+		signal.throwIfAborted();
+		return { status: "unsupported" };
+	}
+};
+//#endregion
+export { unsupportedPhoneEnvironmentAdapter };

package/dist/src/phone/location-baseline-store.d.ts

@@ -0,0 +1,9 @@
+/** Only the pre-sharing phone baseline is persisted; source-device location never enters this store. */
+export declare class LocationBaselineCipher {
+    private readonly root;
+    private key?;
+    constructor(root?: string);
+    private loadKey;
+    seal(value: string, phoneId: string): Promise<string>;
+    open(value: string, phoneId: string): Promise<string>;
+}

package/dist/src/phone/location-baseline-store.js

@@ -0,0 +1,61 @@
+import { resolveStateDir } from "../config/paths-state.js";
+import { init_paths } from "../config/paths.js";
+import { join } from "node:path";
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { mkdir, open, readFile } from "node:fs/promises";
+//#region src/phone/location-baseline-store.ts
+init_paths();
+/** Only the pre-sharing phone baseline is persisted; source-device location never enters this store. */
+var LocationBaselineCipher = class {
+	key;
+	constructor(root = join(resolveStateDir(), "credentials")) {
+		this.root = root;
+	}
+	loadKey() {
+		return this.key ??= (async () => {
+			await mkdir(this.root, {
+				recursive: true,
+				mode: 448
+			});
+			const path = join(this.root, "phone-location-baseline.key");
+			const candidate = randomBytes(32);
+			try {
+				const file = await open(path, "wx", 384);
+				try {
+					await file.writeFile(candidate);
+					await file.sync();
+				} finally {
+					await file.close();
+				}
+			} catch (error) {
+				if (error.code !== "EEXIST") throw error;
+			} finally {
+				candidate.fill(0);
+			}
+			const key = await readFile(path);
+			if (key.length !== 32) throw new Error("Invalid phone baseline key");
+			return key;
+		})();
+	}
+	async seal(value, phoneId) {
+		const iv = randomBytes(12);
+		const cipher = createCipheriv("aes-256-gcm", await this.loadKey(), iv);
+		cipher.setAAD(Buffer.from(phoneId));
+		const encrypted = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
+		return Buffer.concat([
+			iv,
+			cipher.getAuthTag(),
+			encrypted
+		]).toString("base64");
+	}
+	async open(value, phoneId) {
+		const bytes = Buffer.from(value, "base64");
+		if (bytes.length < 29 || bytes.length > 4096) throw new Error("Invalid phone baseline");
+		const cipher = createDecipheriv("aes-256-gcm", await this.loadKey(), bytes.subarray(0, 12));
+		cipher.setAAD(Buffer.from(phoneId));
+		cipher.setAuthTag(bytes.subarray(12, 28));
+		return Buffer.concat([cipher.update(bytes.subarray(28)), cipher.final()]).toString("utf8");
+	}
+};
+//#endregion
+export { LocationBaselineCipher };

package/dist/src/phone/location-environment.d.ts

@@ -0,0 +1,61 @@
+import { DurableState } from '../storage/sqlite/durable-state.js';
+import type { LocationConsumer } from '../endpoint-tools/location-sharing.js';
+import { type PhoneDevice } from './contracts.js';
+import type { PhoneRepository } from './repository.js';
+import { LocationBaselineCipher } from './location-baseline-store.js';
+import type { WuyingLocationAdapter } from './wuying-location.js';
+export interface PhoneLocationJournal {
+    id: string;
+    phoneId: string;
+    shareId: string;
+    conversationId: string;
+    deviceRevision: number;
+    baseline: string;
+    phase: 'pending' | 'applied' | 'cleanup_pending';
+    validUntil: number;
+}
+interface EnvironmentAccess {
+    adapter(device: PhoneDevice): Promise<{
+        adapter: WuyingLocationAdapter;
+        close(): void;
+    }>;
+    exclusive<T>(phoneId: string, owner: string, cleanup: boolean, action: () => Promise<T>): Promise<T>;
+}
+/** Write-ahead cleanup journal; an interrupted application quarantines the phone until recovery. */
+export declare class PhoneLocationEnvironment implements LocationConsumer {
+    private readonly repository;
+    private readonly access;
+    private readonly cipher;
+    private readonly now;
+    private readonly journal;
+    private readonly active;
+    private readonly required;
+    private readonly ended;
+    private readonly verified;
+    private readonly operations;
+    private readonly timer;
+    private readonly cleaning;
+    constructor(repository: PhoneRepository, access: EnvironmentAccess, cipher?: LocationBaselineCipher, now?: () => number, journal?: Pick<DurableState<PhoneLocationJournal>, 'get' | 'set' | 'delete' | 'values'>);
+    sweep(): Promise<void>;
+    hasVerified(phoneId: string, owner: string): boolean;
+    status(phoneId: string): {
+        status: "pending" | "applied" | "cleanup_pending";
+        shareId: string;
+        validUntil: number;
+        recoveryRequired: boolean;
+    } | {
+        status: string;
+        shareId?: undefined;
+        validUntil?: undefined;
+        recoveryRequired?: undefined;
+    };
+    assertAllowed(phoneId: string, owner: string): void;
+    recover(phoneId: string, force?: boolean): Promise<void>;
+    apply(input: Parameters<LocationConsumer['apply']>[0], signal: AbortSignal): Promise<void>;
+    clear(shareId: string, phoneId: string): Promise<boolean>;
+    private cleanup;
+    releaseOwner(owner: string): Promise<void>;
+    releaseDevice(phoneId: string): Promise<void>;
+    close(): Promise<void>;
+}
+export {};