@xopcai/xopc 0.0.433 → 0.0.435

package/dist/src/phone/setup/service.js

@@ -75,7 +75,7 @@ var PhoneSetupService = class {
 			settingsPath: `/settings/phone-use?phoneSetup=${setup.id}&conversationId=${context.conversationId}`,
 			guidanceRefs: [{
 				sceneId: "phone",
-				path: `references/phone/${setup.state === "verifying" ? "acceptance" : setup.error || interrupted || stale ? "troubleshooting" : setup.source === "aliyun" ? "aliyun" : setup.source === "local" ? "local" : "overview"}.md`,
+				path: `references/phone/${setup.state === "verifying" ? "acceptance" : setup.error || interrupted || stale ? "troubleshooting" : setup.source === "aliyun" ? "aliyun" : setup.source === "harmonyos" ? "harmonyos" : setup.source === "local" ? "local" : "overview"}.md`,
 				resourceVersion: "1"
 			}]
 		};
@@ -136,7 +136,7 @@ var PhoneSetupService = class {
 			if (!context.canConfigure) throw new Error("PHONE_SETUP_INTERACTIVE_REQUIRED: Continue in an authorized interactive conversation.");
 			if (!Number.isInteger(args.expectedRevision) || args.expectedRevision !== setup.revision) throw new Error("PHONE_SETUP_CONFLICT: Re-read current progress.");
 			if (command === "source") {
-				if (args.source !== "local" && args.source !== "aliyun") throw new Error("Choose local or aliyun");
+				if (args.source !== "local" && args.source !== "aliyun" && args.source !== "harmonyos") throw new Error("Choose local, harmonyos or aliyun");
 				return this.source(context, setup.id, args.source, setup.revision);
 			}
 			if (command === "begin_verification") {
@@ -181,20 +181,36 @@ var PhoneSetupService = class {
 						await this.deps.setModel(context.agentId, args.modelRef, mutation);
 					}
 				} else if (command === "install_dependency") {
-					if (!this.deps.install || args.kind !== "adb" && args.kind !== "scrcpy" || args.repair !== void 0 && typeof args.repair !== "boolean") throw new Error("Choose a managed Phone dependency");
+					if (!this.deps.install || ![
+						"adb",
+						"scrcpy",
+						"hdc",
+						"hoscrcpy",
+						"java",
+						"harmonyos"
+					].includes(String(args.kind)) || args.repair !== void 0 && typeof args.repair !== "boolean") throw new Error("Choose a managed Phone dependency");
 					if (args.kind === "adb" && setup.source === "aliyun") throw new Error("Cloud direct connections do not need local ADB");
-					const dependency = (await this.deps.inspect(context, setup.source)).dependencies.find((item) => item.kind === args.kind);
-					if (dependency?.state !== "ready" || args.repair === true) {
-						if (!dependency?.canInstall) throw new Error("PHONE_SETUP_INSTALL_UNAVAILABLE: Use an existing verified dependency or review runtime download settings.");
-						mutation.check();
-						operation.committing = true;
-						await this.deps.install(args.kind, args.repair === true, mutation);
+					const kinds = args.kind === "harmonyos" ? [
+						"hdc",
+						"java",
+						"hoscrcpy"
+					] : [args.kind];
+					for (const kind of kinds) {
+						const dependency = (await this.deps.inspect(context, setup.source)).dependencies.find((item) => item.kind === kind);
+						if (dependency?.state !== "ready" || args.repair === true) {
+							if (!dependency?.canInstall) throw new Error(`PHONE_SETUP_INSTALL_UNAVAILABLE: ${kind} cannot be installed. Review runtime download settings or use an existing verified dependency.`);
+							mutation.check();
+							operation.committing = true;
+							await this.deps.install(kind, args.repair === true, mutation);
+							mutation.check();
+							if (!(await this.deps.inspect(context, setup.source)).dependencies.some((item) => item.kind === kind && item.state === "ready")) throw new Error(`PHONE_SETUP_INSTALL_UNVERIFIED: ${kind} is not ready after installation.`);
+						}
 					}
 				} else {
-					if (!this.deps.registerLocal || setup.source !== "local" || typeof args.serial !== "string" || args.name !== void 0 && (typeof args.name !== "string" || args.name.length > 100)) throw new Error("Select a discovered local phone");
+					if (!this.deps.registerLocal || !["local", "harmonyos"].includes(setup.source ?? "") || typeof args.serial !== "string" || args.name !== void 0 && (typeof args.name !== "string" || args.name.length > 100)) throw new Error("Select a discovered local phone");
 					mutation.check();
 					operation.committing = true;
-					await this.deps.registerLocal(args.serial, args.name, mutation);
+					await this.deps.registerLocal(args.serial, args.name, mutation, setup.source === "harmonyos" ? "harmonyos" : "android");
 				}
 				mutation.check();
 				return this.view(context, this.save(context, this.owned(context, setup.id)));
@@ -237,6 +253,7 @@ var PhoneSetupService = class {
 		if (!device?.enabled || !device.settingsAllowed) throw new Error("PHONE_SETUP_DEVICE_REQUIRED: Choose an enabled phone allowing Settings.");
 		if (setup.source && setup.source !== device.source) throw new Error("PHONE_SETUP_SOURCE_MISMATCH");
 		if (device.source === "local" && !readiness.dependencies.some((item) => item.kind === "adb" && item.state === "ready")) throw new Error("PHONE_SETUP_ADB_REQUIRED");
+		if (device.source === "harmonyos" && !readiness.dependencies.some((item) => item.kind === "hdc" && item.state === "ready")) throw new Error("PHONE_SETUP_HDC_REQUIRED");
 		if (!await this.deps.connected(deviceId, signal)) throw new Error("PHONE_SETUP_DEVICE_OFFLINE: Authorize USB debugging or check cloud connection.");
 		const latest = this.owned(context, id);
 		if (!this.scopeCurrent(latest) || latest.revision !== revision || environmentRevision !== this.deps.revision(context, deviceId)) throw new Error("PHONE_SETUP_CONFLICT");
@@ -244,10 +261,10 @@ var PhoneSetupService = class {
 			id: randomUUID(),
 			deviceId,
 			modelRef: readiness.model.ref,
-			goal: "From the Android Settings About phone page, open Android version details and read the version. Do not change any setting.",
+			goal: device.source === "harmonyos" ? "In HarmonyOS Settings, open About phone and read the HarmonyOS version. Do not change any setting." : "From the Android Settings About phone page, open Android version details and read the version. Do not change any setting.",
 			completion: {
-				appPackage: "com.android.settings",
-				textAny: [
+				appPackage: device.source === "harmonyos" ? "com.huawei.hmos.settings" : "com.android.settings",
+				textAny: device.source === "harmonyos" ? ["HarmonyOS", "鸿蒙"] : [
 					"Android version",
 					"Android 版本",
 					"Android版本"
@@ -284,7 +301,7 @@ var PhoneSetupService = class {
 		if (!setup?.attempt || setup.attempt.released || input.op === "discover") return void 0;
 		const cleanup = input.op === "close" || input.op === "cancel";
 		if (!cleanup && (!this.scopeCurrent(setup) || setup.state !== "verifying" || Date.now() > setup.attempt.expiresAt || setup.calls >= 12 || setup.environmentRevision !== this.deps.revision(context, setup.attempt.deviceId))) throw new Error("PHONE_SETUP_STOPPED: Release the setup test and review the current state.");
-		if (!(cleanup || input.op === "status" || input.op === "observe" || input.op === "pause" || input.op === "open" && input.deviceId === setup.attempt.deviceId && input.mode === "control" && input.appPackage === "com.android.settings" || (input.op === "run" || input.op === "step") && input.goal === setup.attempt.goal && !input.scenario && input.completion?.appPackage === setup.attempt.completion.appPackage && input.completion.requireChange === true && JSON.stringify(input.completion.textAny) === JSON.stringify(setup.attempt.completion.textAny) && !input.completion.textAll && !input.completion.field && (input.maxActions ?? 6) <= 6)) throw new Error("PHONE_SETUP_ACTION_DENIED: Use only the approved Settings test.");
+		if (!(cleanup || input.op === "status" || input.op === "observe" || input.op === "pause" || input.op === "open" && input.deviceId === setup.attempt.deviceId && input.mode === "control" && input.appPackage === setup.attempt.completion.appPackage || (input.op === "run" || input.op === "step") && input.goal === setup.attempt.goal && !input.scenario && input.completion?.appPackage === setup.attempt.completion.appPackage && input.completion.requireChange === true && JSON.stringify(input.completion.textAny) === JSON.stringify(setup.attempt.completion.textAny) && !input.completion.textAll && !input.completion.field && (input.maxActions ?? 6) <= 6)) throw new Error("PHONE_SETUP_ACTION_DENIED: Use only the approved Settings test.");
 		this.save(context, {
 			...setup,
 			calls: setup.calls + 1
@@ -304,7 +321,7 @@ var PhoneSetupService = class {
 		}
 		return {
 			owner: setup.owner,
-			input: input.op === "open" ? {
+			input: input.op === "open" && setup.source !== "harmonyos" ? {
 				...input,
 				settingsPage: "about-phone"
 			} : input

package/dist/src/platform/client.d.ts

@@ -64,9 +64,9 @@ export declare const RuntimeCommandSchema: z.ZodObject<{
                     delete: "delete";
                     read: "read";
                     write: "write";
+                    send: "send";
                     execute: "execute";
                     purchase: "purchase";
-                    send: "send";
                     publish: "publish";
                     admin: "admin";
                 }>>;

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

@@ -150,9 +150,9 @@ export declare const AgentManifestSchema: z.ZodObject<{
             delete: "delete";
             read: "read";
             write: "write";
+            send: "send";
             execute: "execute";
             purchase: "purchase";
-            send: "send";
             publish: "publish";
             admin: "admin";
         }>>;

package/dist/src/process/phone-process.d.ts

@@ -2,4 +2,4 @@ import { type ChildProcess } from 'node:child_process';
 export declare function runPhoneCommandBuffer(program: string, args: string[], signal?: AbortSignal, timeoutMs?: number): Promise<Buffer>;
 export declare function runPhoneCommandText(program: string, args: string[], signal: AbortSignal): Promise<string>;
 export declare function spawnPhoneCommand(program: string, args: string[]): ChildProcess;
-export declare function spawnPhoneInteractiveCommand(program: string, args: string[]): import("node:child_process").ChildProcessByStdio<import("node:stream").Writable, import("node:stream").Readable, null>;
+export declare function spawnPhoneInteractiveCommand(program: string, args: string[], captureStderr?: boolean): ChildProcess;

package/dist/src/process/phone-process.js

@@ -34,12 +34,12 @@ function spawnPhoneCommand(program, args) {
 		windowsHide: true
 	});
 }
-function spawnPhoneInteractiveCommand(program, args) {
+function spawnPhoneInteractiveCommand(program, args, captureStderr = false) {
 	return spawn(program, args, {
 		stdio: [
 			"pipe",
 			"pipe",
-			"ignore"
+			captureStderr ? "pipe" : "ignore"
 		],
 		windowsHide: true
 	});

package/dist/src/runtime-tools/downloader.d.ts

@@ -17,5 +17,6 @@ export declare function downloadVerifiedArchive(params: {
     timeoutMs: number;
     proxy?: string;
     signal?: AbortSignal;
+    expectedBytes?: number;
     onProgress?: (downloadedBytes: number, totalBytes?: number) => void;
 }): Promise<string>;

package/dist/src/runtime-tools/downloader.js

@@ -52,6 +52,7 @@ async function sha256File(path) {
 	return hash.digest("hex");
 }
 async function downloadVerifiedArchive(params) {
+	const maxBytes = Math.min(MAX_ARCHIVE_BYTES, params.expectedBytes ?? MAX_ARCHIVE_BYTES);
 	await mkdir(dirname(params.targetPath), { recursive: true });
 	const completedPath = params.targetPath.replace(/\.partial$/, "");
 	try {
@@ -61,7 +62,7 @@ async function downloadVerifiedArchive(params) {
 	} catch {}
 	try {
 		let resumeOffset = await stat(params.targetPath).then((info) => info.isFile() ? info.size : 0).catch(() => 0);
-		if (resumeOffset > MAX_ARCHIVE_BYTES) {
+		if (resumeOffset > maxBytes) {
 			await rm(params.targetPath, { force: true });
 			resumeOffset = 0;
 		}
@@ -75,7 +76,10 @@ async function downloadVerifiedArchive(params) {
 					signal: params.signal,
 					init: {
 						redirect: "follow",
-						headers: offset > 0 ? { Range: `bytes=${offset}-` } : void 0
+						headers: {
+							...params.expectedBytes === void 0 ? {} : { "Accept-Encoding": "identity" },
+							...offset > 0 ? { Range: `bytes=${offset}-` } : {}
+						}
 					}
 				});
 			} catch (error) {
@@ -108,14 +112,14 @@ async function downloadVerifiedArchive(params) {
 			}
 			total = Number(response.headers.get("content-length")) || void 0;
 		}
-		if (total && total > MAX_ARCHIVE_BYTES) {
+		if (total && total > maxBytes) {
 			await response.body.cancel().catch(() => {});
 			throw new Error("Archive exceeds size limit");
 		}
 		let downloaded = resumeOffset;
 		const transform = new TransformStream({ transform(chunk, controller) {
 			downloaded += chunk.byteLength;
-			if (downloaded > MAX_ARCHIVE_BYTES) throw new Error("Archive exceeds size limit");
+			if (downloaded > maxBytes) throw new Error("Archive exceeds size limit");
 			params.onProgress?.(downloaded, total);
 			controller.enqueue(chunk);
 		} });

package/dist/src/runtime-tools/harmony-dependencies.d.ts

@@ -0,0 +1,24 @@
+import type { PhoneConfig } from '../phone/contracts.js';
+import { type HarmonyDependencyKind } from './harmony-dependency-catalog.js';
+import type { PhoneDependencyProgress, PhoneDependencyStatus } from './phone-dependencies.js';
+import type { RuntimeToolsConfig } from '../config/schema.js';
+export interface HarmonyInstallOptions {
+    repair?: boolean;
+    signal?: AbortSignal;
+    beforeCommit?: () => void;
+}
+export declare function probePhoneHdc(path: string, signal?: AbortSignal): Promise<string>;
+export declare function probePhoneJava(home: string, signal?: AbortSignal): Promise<string>;
+export declare function probePhoneHos(config: PhoneConfig, stateDir: string, signal?: AbortSignal): Promise<string>;
+export declare class HarmonyDependencyManager {
+    private options;
+    private emit;
+    constructor(options: {
+        stateDir: string;
+        config: RuntimeToolsConfig;
+        phone: PhoneConfig;
+    }, emit: (event: PhoneDependencyProgress) => void);
+    private key;
+    status(kind: HarmonyDependencyKind): Promise<PhoneDependencyStatus>;
+    install(kind: HarmonyDependencyKind, options?: HarmonyInstallOptions): Promise<void>;
+}

package/dist/src/runtime-tools/harmony-dependencies.js

@@ -0,0 +1,272 @@
+import { HDC_VERSION, HOSCRCPY_VERSION, managedHdcDir, managedHdcPath, managedHosDir, managedHosJar, managedJavaDir, managedJavaHome } from "./harmony-paths.js";
+import { PHONE_JAVA_VERSION } from "./harmony-dependency-catalog.js";
+import { phoneDependencyAsset } from "./phone-dependency-catalog.js";
+import { resolveHdcPath } from "../phone/hdc-driver.js";
+import { compileHdcVideoBridge, resolveHdcJavaHome, resolveHdcVideoTools } from "../phone/hdc-video-tools.js";
+import { RuntimeError } from "./errors.js";
+import { extractRuntimeArchive } from "./archive.js";
+import { runRuntimeCommand } from "./command.js";
+import { downloadVerifiedArchive, sha256File } from "./downloader.js";
+import { withInstallLock } from "./install-lock.js";
+import { runtimeDownloadPath } from "./paths.js";
+import { stageHdcFiles, verifyHdcFiles } from "./hdc-files.js";
+import { dirname, isAbsolute, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { copyFile, mkdir, rename, rm, stat } from "node:fs/promises";
+//#region src/runtime-tools/harmony-dependencies.ts
+const operations = /* @__PURE__ */ new Set();
+const versions = {
+	hdc: HDC_VERSION,
+	hoscrcpy: HOSCRCPY_VERSION,
+	java: PHONE_JAVA_VERSION
+};
+async function probePhoneHdc(path, signal) {
+	const result = await runRuntimeCommand({
+		command: path,
+		args: ["-v"],
+		signal
+	});
+	const version = /(?:Ver:\s*|version\s*)(\d+\.\d+(?:\.\d+)?[\w.-]*)/i.exec(result.stdout)?.[1];
+	if (!result.ok || !version) throw new Error("A compatible HDC executable was not found");
+	return version;
+}
+async function probePhoneJava(home, signal) {
+	const suffix = process.platform === "win32" ? ".exe" : "";
+	const java = await runRuntimeCommand({
+		command: join(home, "bin", `java${suffix}`),
+		args: ["-version"],
+		signal
+	});
+	const javac = await runRuntimeCommand({
+		command: join(home, "bin", `javac${suffix}`),
+		args: ["-version"],
+		signal
+	});
+	const version = /(?:openjdk|java) version "([^\"]+)"/.exec(`${java.stdout}\n${java.stderr}`)?.[1];
+	const compiler = /javac (\d+)/.exec(`${javac.stdout}\n${javac.stderr}`)?.[1];
+	if (!java.ok || !javac.ok || !version || Number(version.split(".")[0]) < 17 || Number(compiler) < 17) throw new Error("A full JDK 17+ with java and javac is required");
+	return version;
+}
+async function verifyHosJar(path) {
+	const info = await stat(path);
+	if (!info.isFile() || info.size > 64 * 1024 * 1024 || await sha256File(path) !== "2ce60b1893cc2be471a8cd7eab7e4127e41921f1f89a32a134c730ba15c8c0fd") throw new Error("HOScrcpy does not match the verified compatible library");
+}
+/** Device-free bridge validation: never starts HDC, captures a screen or installs device helpers. */
+async function probePhoneHosUncached(config, stateDir, signal = new AbortController().signal) {
+	const tools = resolveHdcVideoTools(config, stateDir);
+	if (await verifyHosJar(tools?.jar ?? config.hdcVideo?.sdkJar ?? managedHosJar(stateDir)).then(() => true, () => false)) return HOSCRCPY_VERSION;
+	if (!tools) throw new Error("HOScrcpy validation requires a compatible library and a JDK");
+	const bridge = await compileHdcVideoBridge(tools, signal);
+	try {
+		if (!(await runRuntimeCommand({
+			command: bridge.program,
+			args: [
+				...bridge.args,
+				"--probe",
+				"",
+				tools.jar
+			],
+			timeoutMs: 15e3,
+			signal
+		})).ok) throw new Error("HOScrcpy failed the device-free bridge compatibility check");
+		return "compatible";
+	} finally {
+		await bridge.cleanup();
+	}
+}
+const hosProbes = /* @__PURE__ */ new Map();
+async function probePhoneHos(config, stateDir, signal) {
+	const tools = resolveHdcVideoTools(config, stateDir);
+	const path = tools?.jar ?? config.hdcVideo?.sdkJar ?? managedHosJar(stateDir);
+	const identity = await Promise.all([
+		path,
+		tools?.java,
+		tools?.javac
+	].map(async (file) => file ? stat(file).then((info) => [
+		file,
+		info.size,
+		info.mtimeMs
+	], () => [file]) : void 0));
+	const key = JSON.stringify([identity, tools?.classpath]);
+	const cached = hosProbes.get(key);
+	if (cached && cached.expires > Date.now()) return cached.result;
+	if (hosProbes.size >= 32) hosProbes.clear();
+	const result = probePhoneHosUncached(config, stateDir, signal);
+	hosProbes.set(key, {
+		result,
+		expires: Date.now() + 1e4
+	});
+	return result;
+}
+var HarmonyDependencyManager = class {
+	constructor(options, emit) {
+		this.options = options;
+		this.emit = emit;
+	}
+	key(kind) {
+		return `${this.options.stateDir}:${kind}`;
+	}
+	async status(kind) {
+		const { stateDir, phone } = this.options;
+		const asset = phoneDependencyAsset(kind);
+		const canInstall = this.options.config.enabled && Boolean(asset);
+		const base = {
+			kind,
+			requestedVersion: asset?.version ?? versions[kind],
+			canInstall,
+			distribution: kind === "hoscrcpy" ? "HOScrcpy 1.0.18-beta via @nszzj/dsh-hos-scrcpy 3.0.2 (third-party distribution)" : kind === "hdc" ? `HDC ${HDC_VERSION} via hdw2 2.3.10 (third-party distribution; ${((asset?.files?.reduce((sum, file) => sum + file.sizeBytes, 0) ?? 0) / 1024 ** 2).toFixed(1)} MiB for this host)` : "Amazon Corretto JDK 17",
+			downloadUrl: asset?.url
+		};
+		if (operations.has(this.key(kind))) return {
+			...base,
+			state: "installing"
+		};
+		const path = kind === "hdc" ? resolveHdcPath(phone.hdcPath, stateDir) : kind === "java" ? resolveHdcJavaHome(phone, stateDir) : resolveHdcVideoTools(phone, stateDir)?.jar ?? phone.hdcVideo?.sdkJar ?? managedHosJar(stateDir);
+		const custom = kind === "hdc" ? phone.hdcPath : kind === "java" ? phone.hdcVideo?.javaHome : phone.hdcVideo?.sdkJar;
+		const managed = kind === "hdc" ? managedHdcPath(stateDir) : kind === "java" ? managedJavaHome(stateDir) : managedHosJar(stateDir);
+		try {
+			if (!path) throw new Error("Dependency not found");
+			if (kind === "hdc" && path === managed && asset) await verifyHdcFiles(dirname(path), asset);
+			const version = kind === "hdc" ? await probePhoneHdc(path) : kind === "java" ? await probePhoneJava(path) : await probePhoneHos(phone, stateDir);
+			return {
+				...base,
+				state: "ready",
+				version,
+				path,
+				source: path === managed ? "managed" : custom ? "custom" : "system"
+			};
+		} catch {
+			const exists = path && await stat(path).then(() => true, () => false);
+			return {
+				...base,
+				state: exists || custom ? "corrupted" : !asset ? "unsupported" : "absent",
+				path: exists || custom ? path : void 0,
+				error: "RUNTIME_PROBE_FAILED"
+			};
+		}
+	}
+	async install(kind, options = {}) {
+		const check = () => {
+			options.signal?.throwIfAborted();
+			options.beforeCommit?.();
+		};
+		check();
+		const asset = phoneDependencyAsset(kind);
+		if (!this.options.config.enabled) throw new RuntimeError("Managed runtime installation is disabled", "RUNTIME_DISABLED", kind, "install", false);
+		if (!asset) throw new RuntimeError("No verified managed dependency is available for this platform", "RUNTIME_UNSUPPORTED", kind, "install", false);
+		if (operations.has(this.key(kind))) throw new Error("This dependency is already being installed");
+		operations.add(this.key(kind));
+		const progress = (phase) => this.emit({
+			kind,
+			phase
+		});
+		try {
+			await withInstallLock(join(this.options.stateDir, "tools", "locks", `phone-${kind}.lock`), { kind }, async () => {
+				check();
+				const target = kind === "hdc" ? managedHdcDir(this.options.stateDir) : kind === "java" ? managedJavaDir(this.options.stateDir) : managedHosDir(this.options.stateDir);
+				const probe = async (root) => {
+					if (kind === "hdc") {
+						await verifyHdcFiles(root, asset);
+						if (await probePhoneHdc(join(root, process.platform === "win32" ? "hdc.exe" : "hdc"), options.signal) !== asset.version) throw new Error("HDC version does not match the catalog");
+					} else if (kind === "java") await probePhoneJava(process.platform === "darwin" ? join(root, "Contents", "Home") : root, options.signal);
+					else await verifyHosJar(join(root, `hosScrcpy-${HOSCRCPY_VERSION}.jar`));
+				};
+				if (!options.repair && await probe(target).then(() => true, () => false)) return;
+				let source;
+				if (kind !== "hdc") {
+					if (this.options.config.download.bundleDir) {
+						if (!isAbsolute(this.options.config.download.bundleDir)) throw new Error("Offline bundle directory must be an absolute path on the Gateway host");
+						source = join(this.options.config.download.bundleDir, asset.filename);
+					} else {
+						if (this.options.config.download.source === "website-only") throw new Error("Select Auto or Direct downloads, or configure an offline bundle directory");
+						progress("download");
+						source = await downloadVerifiedArchive({
+							runtime: kind,
+							url: asset.url,
+							expectedSha256: asset.sha256,
+							targetPath: runtimeDownloadPath(this.options.stateDir, asset.filename),
+							timeoutMs: this.options.config.download.timeoutMs,
+							proxy: this.options.config.download.proxy,
+							signal: options.signal,
+							onProgress: (downloadedBytes, totalBytes) => this.emit({
+								kind,
+								phase: "download",
+								downloadedBytes,
+								totalBytes
+							})
+						});
+					}
+					check();
+					progress("verify");
+					if (await sha256File(source) !== asset.sha256) throw new RuntimeError("Dependency checksum mismatch", "RUNTIME_CHECKSUM_MISMATCH", kind, "verify", true);
+				}
+				const staging = join(this.options.stateDir, "tools", "staging", `phone-${kind}-${randomUUID()}`);
+				const backup = `${target}.${randomUUID()}.backup`;
+				let backedUp = false;
+				try {
+					if (kind !== "hdc") progress("extract");
+					let root;
+					if (kind === "hdc") root = await stageHdcFiles({
+						asset,
+						stateDir: this.options.stateDir,
+						config: this.options.config,
+						root: join(staging, "hdc"),
+						signal: options.signal,
+						check,
+						progress: this.emit
+					});
+					else {
+						if (!source) throw new Error("Dependency archive is unavailable");
+						const unpacked = await extractRuntimeArchive({
+							runtime: kind,
+							archivePath: source,
+							archiveType: asset.filename.endsWith(".zip") ? "zip" : "tar.gz",
+							stagingDir: staging
+						});
+						if (kind === "hoscrcpy") {
+							root = join(staging, "library");
+							await mkdir(root);
+							await copyFile(join(unpacked, "resources", `hosScrcpy-${HOSCRCPY_VERSION}.jar`), join(root, `hosScrcpy-${HOSCRCPY_VERSION}.jar`));
+							for (const name of ["LICENSE", "THIRD_PARTY_NOTICES.md"]) await copyFile(join(unpacked, name), join(root, name));
+						} else root = unpacked;
+					}
+					progress("probe");
+					await probe(root);
+					check();
+					await mkdir(dirname(target), { recursive: true });
+					check();
+					progress("install");
+					try {
+						await rename(target, backup);
+						backedUp = true;
+					} catch (error) {
+						if (error.code !== "ENOENT") throw error;
+					}
+					try {
+						await rename(root, target);
+					} catch (error) {
+						if (backedUp) {
+							await rename(backup, target);
+							backedUp = false;
+						}
+						throw error;
+					}
+				} finally {
+					await rm(staging, {
+						recursive: true,
+						force: true
+					});
+					if (backedUp) await rm(backup, {
+						recursive: true,
+						force: true
+					});
+				}
+			});
+			progress("complete");
+		} finally {
+			operations.delete(this.key(kind));
+		}
+	}
+};
+//#endregion
+export { HarmonyDependencyManager, probePhoneHdc, probePhoneHos, probePhoneJava };

package/dist/src/runtime-tools/harmony-dependency-catalog.d.ts

@@ -0,0 +1,4 @@
+import type { PhoneDependencyAsset } from './phone-dependency-catalog.js';
+export type HarmonyDependencyKind = 'hdc' | 'hoscrcpy' | 'java';
+export declare const PHONE_JAVA_VERSION = "17.0.21.0.11";
+export declare function harmonyDependencyAsset(kind: HarmonyDependencyKind, platform: NodeJS.Platform, arch: string): PhoneDependencyAsset | undefined;

package/dist/src/runtime-tools/harmony-dependency-catalog.js

@@ -0,0 +1,54 @@
+import { HOSCRCPY_VERSION } from "./harmony-paths.js";
+import { hdcDependencyAsset } from "./hdc-dependency-catalog.js";
+//#region src/runtime-tools/harmony-dependency-catalog.ts
+const PHONE_JAVA_VERSION = "17.0.21.0.11";
+const JAVA_ASSETS = {
+	"darwin-arm64": {
+		"filename": "amazon-corretto-17.0.21.0.11-macosx-aarch64.tar.gz",
+		"url": "https://corretto.aws/downloads/resources/17.0.21.0.11/amazon-corretto-17.0.21.0.11-macosx-aarch64.tar.gz",
+		"sha256": "3cd5a2bdd380a5654aa1ef5eda3032f60021e8e48a0bdd552e8e39b032705732"
+	},
+	"darwin-x64": {
+		"filename": "amazon-corretto-17.0.21.0.11-macosx-x64.tar.gz",
+		"url": "https://corretto.aws/downloads/resources/17.0.21.0.11/amazon-corretto-17.0.21.0.11-macosx-x64.tar.gz",
+		"sha256": "dca4175d94d404533c4230eff1a64cc3ae9f3919bfdf35902c64bfd4d3bcb70e"
+	},
+	"linux-x64": {
+		"filename": "amazon-corretto-17.0.21.0.11-linux-x64.tar.gz",
+		"url": "https://corretto.aws/downloads/resources/17.0.21.0.11/amazon-corretto-17.0.21.0.11-linux-x64.tar.gz",
+		"sha256": "8f9a2ddb131ec5317419f2b0769240fe22ce27f8a0ae43f5346d53e1c8aec6a0"
+	},
+	"linux-arm64": {
+		"filename": "amazon-corretto-17.0.21.0.11-linux-aarch64.tar.gz",
+		"url": "https://corretto.aws/downloads/resources/17.0.21.0.11/amazon-corretto-17.0.21.0.11-linux-aarch64.tar.gz",
+		"sha256": "33412bba53b912b21528150df7cf60c161d10fc3b7dae89cd5383d8f3c0362c0"
+	},
+	"win32-x64": {
+		"filename": "amazon-corretto-17.0.21.0.11-windows-x64-jdk.zip",
+		"url": "https://corretto.aws/downloads/resources/17.0.21.0.11/amazon-corretto-17.0.21.0.11-windows-x64-jdk.zip",
+		"sha256": "59d6514305f6fab3b18955fb17185562f0a0bbf20e1466eda33a5429f3b31618"
+	}
+};
+function harmonyDependencyAsset(kind, platform, arch) {
+	const key = `${platform}-${arch}`;
+	if (kind === "hoscrcpy") return {
+		kind,
+		version: HOSCRCPY_VERSION,
+		archive: true,
+		filename: "dsh-hos-scrcpy-3.0.2.tgz",
+		url: "https://registry.npmjs.org/@nszzj/dsh-hos-scrcpy/-/dsh-hos-scrcpy-3.0.2.tgz",
+		sha256: "955a5f6dfa72cc8e61905fa6960a149e4a75f3167c2984afb1fcc5f4ab99868a"
+	};
+	if (kind === "java") {
+		const asset = JAVA_ASSETS[key];
+		return asset && {
+			...asset,
+			kind,
+			version: "17.0.21.0.11",
+			archive: true
+		};
+	}
+	return hdcDependencyAsset(platform, arch);
+}
+//#endregion
+export { PHONE_JAVA_VERSION, harmonyDependencyAsset };

package/dist/src/runtime-tools/harmony-paths.d.ts

@@ -0,0 +1,9 @@
+export declare const HDC_VERSION = "3.2.0c";
+export declare const HOSCRCPY_VERSION = "1.0.18-beta";
+export declare const HOSCRCPY_SHA256 = "2ce60b1893cc2be471a8cd7eab7e4127e41921f1f89a32a134c730ba15c8c0fd";
+export declare const managedHdcDir: (stateDir?: string) => string;
+export declare const managedHdcPath: (stateDir?: string) => string;
+export declare const managedHosDir: (stateDir?: string) => string;
+export declare const managedHosJar: (stateDir?: string) => string;
+export declare const managedJavaDir: (stateDir?: string) => string;
+export declare const managedJavaHome: (stateDir?: string) => string;

package/dist/src/runtime-tools/harmony-paths.js

@@ -0,0 +1,15 @@
+import { init_paths_state, resolveStateDir } from "../config/paths-state.js";
+import { join } from "node:path";
+//#region src/runtime-tools/harmony-paths.ts
+init_paths_state();
+const HDC_VERSION = "3.2.0c";
+const HOSCRCPY_VERSION = "1.0.18-beta";
+const HOSCRCPY_SHA256 = "2ce60b1893cc2be471a8cd7eab7e4127e41921f1f89a32a134c730ba15c8c0fd";
+const managedHdcDir = (stateDir = resolveStateDir()) => join(stateDir, "tools", "hdc", `${HDC_VERSION}-hdw2-2.3.10`);
+const managedHdcPath = (stateDir = resolveStateDir()) => join(managedHdcDir(stateDir), process.platform === "win32" ? "hdc.exe" : "hdc");
+const managedHosDir = (stateDir = resolveStateDir()) => join(stateDir, "tools", "hoscrcpy", HOSCRCPY_VERSION);
+const managedHosJar = (stateDir = resolveStateDir()) => join(managedHosDir(stateDir), `hosScrcpy-${HOSCRCPY_VERSION}.jar`);
+const managedJavaDir = (stateDir = resolveStateDir()) => join(stateDir, "tools", "phone-java", "current");
+const managedJavaHome = (stateDir = resolveStateDir()) => process.platform === "darwin" ? join(managedJavaDir(stateDir), "Contents", "Home") : managedJavaDir(stateDir);
+//#endregion
+export { HDC_VERSION, HOSCRCPY_SHA256, HOSCRCPY_VERSION, managedHdcDir, managedHdcPath, managedHosDir, managedHosJar, managedJavaDir, managedJavaHome };

package/dist/src/runtime-tools/hdc-dependency-catalog.d.ts

@@ -0,0 +1,8 @@
+import type { PhoneDependencyAsset } from './phone-dependency-catalog.js';
+export declare const HDC_DISTRIBUTION: {
+    readonly package: "hdw2";
+    readonly version: "2.3.10";
+    readonly url: "https://www.npmjs.com/package/hdw2/v/2.3.10";
+    readonly archiveIntegrity: "sha512-Kcbz0pfxgeSN3zeB3LcaAERfwWAz3unUtzrG7GgJy8fSUW5rb8Tb8jG13dEjfx8oVv69NaIhDGQk+fyscDT1UQ==";
+};
+export declare function hdcDependencyAsset(platform: NodeJS.Platform, arch: string): PhoneDependencyAsset | undefined;