@stim-cli/agent-driver-agent-device 0.0.0 → 1.21.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Janic Duplessis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,10 @@
 # @stim-cli/agent-driver-agent-device
 
-Placeholder. Install a version published with the other Stim packages.
+The [agent-device](https://github.com/callstack/agent-device) driver
+for stim-server hosted apps, selected on the hosting Mac with
+`hosting.agentDriver: agent-device`. It implements the
+[`@stim-cli/agent-driver`](../agent-driver/README.md) contract.
+
+The [stim-server README](../server/README.md#agent-driver-route) describes how
+it starts agent-device, the daemon policy it applies, and how it confines a
+client to one hosted app or device.

package/dist/index.d.mts

@@ -0,0 +1,76 @@
+import { AGENT_DRIVER_API_VERSION, AgentDriverActions, AgentDriverClient, AgentDriverInput, HostedAgentApp, HostedAgentDevice, HostedAgentDriver } from "@stim-cli/agent-driver";
+import { HostedAgentIssuedGrant } from "@stim-cli/core/state";
+import { IncomingMessage, ServerResponse } from "node:http";
+//#region driver.d.ts
+interface AgentDeviceInvocation {
+  command: string;
+  args: string[];
+}
+/**
+ * Finds agent-device at a fixed path: the stim-server LaunchAgent's PATH holds only system directories, and
+ * agent-device's `#!/usr/bin/env node` script cannot find Node there, so a JavaScript entry runs under the
+ * server's own Node.
+ */
+declare function resolveAgentDevice(env: NodeJS.ProcessEnv): AgentDeviceInvocation;
+interface AgentDeviceDriverOptions {
+  env: NodeJS.ProcessEnv;
+  /** agent-device's own host or session state directory; created with mode 0700. */
+  stateDir: string;
+  /** Ownership claim root held for as long as the daemon runs. */
+  claimRoot: string;
+  device?: HostedAgentDevice;
+  startTimeoutMs?: number;
+  stopTimeoutMs?: number;
+  watchMs?: number;
+  leaseRenewMs?: number;
+}
+declare class AgentDeviceDriver implements HostedAgentDriver {
+  readonly name = "agent-device";
+  private readonly options;
+  private running;
+  private claim;
+  private starting;
+  private stopping;
+  private daemonRecord;
+  private deviceProxy;
+  private listener;
+  private androidProbe;
+  private androidVerifiedAt;
+  private readonly leases;
+  private readonly released;
+  constructor(options: AgentDeviceDriverOptions);
+  onExit(listener: () => void): void;
+  start(): Promise<void>;
+  private launch;
+  private listening;
+  private readDaemon;
+  private androidIdentity;
+  private watchDaemon;
+  private exited;
+  stop(): Promise<void>;
+  private teardown;
+  private captured;
+  private stopDaemon;
+  private signalAndWait;
+  private stopAndroidHelpers;
+  private stopIosRunners;
+  /**
+   * Grants one device's automatic instance lease or allocates and renews a macos-app lease over
+   * agent-device's host-only admin route. Forwarded requests are pinned to the grant's scope.
+   */
+  issue(app: HostedAgentApp): Promise<HostedAgentIssuedGrant>;
+  revoke(session: string): Promise<void>;
+  private removeSessionDirectories;
+  forward(session: string, request: IncomingMessage, response: ServerResponse): void;
+  private relayPinned;
+  private relay;
+}
+//#endregion
+//#region index.d.ts
+declare const apiVersion: typeof AGENT_DRIVER_API_VERSION;
+declare const id: string;
+declare function createAgentDriver(input: AgentDriverInput): AgentDeviceDriver;
+declare const client: AgentDriverClient;
+declare const actions: AgentDriverActions;
+//#endregion
+export { AgentDeviceDriver, type AgentDeviceDriverOptions, actions, apiVersion, client, createAgentDriver, id, resolveAgentDevice };

package/dist/index.mjs

@@ -0,0 +1,1132 @@
+import { delimiter, dirname, join } from "node:path";
+import { AGENT_DRIVER_API_VERSION, AGENT_ROUTE_PREFIX, AgentDriverUnavailable, agentRoute, newAgentToken } from "@stim-cli/agent-driver";
+import { createAgentActionReader, isJsonObject } from "@stim-cli/core/state";
+import { execFile, spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { accessSync, chmodSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { request } from "node:http";
+import { homedir } from "node:os";
+import { claimRemoveCommand, clearClaimChild, markClaimChildPending, releaseClaim, setClaimChild, tryAcquireClaim } from "@stim-cli/core/ownership-claim";
+import { captureProcessIdentity, inspectProcessIdentity, waitForProcessExit } from "@stim-cli/core/process-identity";
+//#region processes.ts
+function listProcesses(columns = "pid=,command=") {
+	return new Promise((resolve, reject) => {
+		execFile("/bin/ps", [
+			"-A",
+			"-ww",
+			"-o",
+			columns
+		], {
+			timeout: 1e4,
+			maxBuffer: 64 * 1024 ** 2
+		}, (error, stdout) => error ? reject(error) : resolve(stdout));
+	});
+}
+//#endregion
+//#region driver.ts
+function adbPath(env) {
+	for (const sdk of [
+		env.ANDROID_HOME,
+		env.ANDROID_SDK_ROOT,
+		join(env.HOME ?? homedir(), "Library/Android/sdk")
+	]) if (sdk && existsSync(join(sdk, "platform-tools/adb"))) return join(sdk, "platform-tools/adb");
+	return "adb";
+}
+const UNSCOPED = "Agent control is unavailable: the agent-device on the hosting Mac has no macos-app lease to limit a client to one app, and Stim never hands a client the hosting Mac desktop.";
+/** Names an agent-device binary to use instead of the fixed install locations. */
+const AGENT_DEVICE_BIN_ENV = "STIM_AGENT_DEVICE_BIN";
+const CANDIDATES = (home) => [
+	join(home, ".local", "bin", "agent-device"),
+	"/opt/homebrew/bin/agent-device",
+	"/usr/local/bin/agent-device"
+];
+/**
+* The daemon policy Stim starts agent-device with (agent-device ADR 0029): every request must run under a
+* host-allocated `macos-app` lease, and only these commands run at all.
+*/
+const POLICY = {
+	version: 1,
+	leases: { require: "macos-app" },
+	commands: { allow: [
+		"open",
+		"close",
+		"snapshot",
+		"wait",
+		"find",
+		"get",
+		"is",
+		"click",
+		"fill",
+		"press",
+		"type",
+		"focus",
+		"scroll",
+		"screenshot",
+		"batch"
+	] }
+};
+const DEVICE_COMMANDS = [
+	...POLICY.commands.allow,
+	"devices",
+	"diff",
+	"longpress",
+	"swipe",
+	"back",
+	"home",
+	"orientation",
+	"appstate",
+	"alert"
+];
+function deviceScope(device) {
+	const platform = device.udid === void 0 ? "android" : "ios";
+	return {
+		platform,
+		id: device.udid ?? device.serial,
+		selector: platform === "ios" ? "udid" : "serial",
+		backend: `${platform}-instance`
+	};
+}
+function devicePolicy(device) {
+	const { selector, id } = deviceScope(device);
+	return {
+		version: 1,
+		devices: { allow: [{ [selector]: id }] },
+		commands: { allow: DEVICE_COMMANDS },
+		capabilities: { deny: ["device-shutdown"] }
+	};
+}
+function devicePolicyDigest(device) {
+	const { id } = deviceScope(device);
+	return createHash("sha256").update(JSON.stringify({
+		devices: [id],
+		commands: {
+			mode: "allow",
+			names: DEVICE_COMMANDS.toSorted()
+		},
+		capabilities: ["device-shutdown"]
+	})).digest("hex");
+}
+/** agent-device caps a lease's inactivity window at ten minutes; the host renews well inside it. */
+const LEASE_TTL_MS = 6e5;
+const MAX_RPC_BYTES = 1048576;
+const MAX_ECHO = 64;
+const COMMAND_METHODS = /* @__PURE__ */ new Set(["agent_device.command", "agent-device.command"]);
+const LEASE_METHODS = /* @__PURE__ */ new Set([
+	"agent_device.lease.heartbeat",
+	"agent-device.lease.heartbeat",
+	"agent_device.lease.release",
+	"agent-device.lease.release"
+]);
+/**
+* Finds agent-device at a fixed path: the stim-server LaunchAgent's PATH holds only system directories, and
+* agent-device's `#!/usr/bin/env node` script cannot find Node there, so a JavaScript entry runs under the
+* server's own Node.
+*/
+function resolveAgentDevice(env) {
+	const explicit = env[AGENT_DEVICE_BIN_ENV]?.trim();
+	const candidates = explicit ? [explicit] : CANDIDATES(env.HOME || homedir());
+	for (const candidate of candidates) try {
+		const real = realpathSync(candidate);
+		accessSync(real, constants.R_OK);
+		return /\.(mjs|cjs|js)$/.test(real) ? {
+			command: process.execPath,
+			args: [real]
+		} : {
+			command: real,
+			args: []
+		};
+	} catch {}
+	throw new AgentDriverUnavailable(explicit ? `${AGENT_DEVICE_BIN_ENV} names ${explicit}, which is not a readable agent-device on the hosting Mac.` : `agent-device is not installed on the hosting Mac (looked in ${candidates.join(", ")}). Install it with: npm install --global --prefix "$HOME/.local" agent-device`);
+}
+const FORWARDED = [
+	"content-type",
+	"content-length",
+	"content-range",
+	"range",
+	"accept",
+	"x-request-id",
+	"x-artifact-type",
+	"x-artifact-filename",
+	"x-artifact-hash",
+	"x-artifact-hash-algorithm"
+];
+const HOP_BY_HOP = /* @__PURE__ */ new Set([
+	"connection",
+	"keep-alive",
+	"transfer-encoding",
+	"upgrade",
+	"proxy-authenticate"
+]);
+const LISTENING = /Proxy listening at (http:\/\/127\.0\.0\.1:\d+)/;
+var AgentDeviceDriver = class {
+	name = "agent-device";
+	options;
+	running = null;
+	claim = null;
+	starting = null;
+	stopping = false;
+	daemonRecord = null;
+	deviceProxy = null;
+	listener = null;
+	androidProbe = null;
+	androidVerifiedAt = 0;
+	leases = /* @__PURE__ */ new Map();
+	released = /* @__PURE__ */ new Set();
+	constructor(options) {
+		this.options = {
+			startTimeoutMs: 6e4,
+			stopTimeoutMs: 2e4,
+			watchMs: 5e3,
+			leaseRenewMs: 12e4,
+			...options
+		};
+	}
+	onExit(listener) {
+		this.listener = listener;
+	}
+	start() {
+		if (this.running) return Promise.resolve();
+		this.starting ??= this.launch().finally(() => {
+			this.starting = null;
+		});
+		return this.starting;
+	}
+	async launch() {
+		if (this.claim) try {
+			await this.teardown();
+		} catch {
+			throw new Error(`The previous agent-device daemon is unresolved. Once it is gone, clear its claim with: ${claimRemoveCommand(this.claim.path)}`);
+		}
+		const invocation = resolveAgentDevice(this.options.env);
+		if (this.options.device?.serial) {
+			const version = await new Promise((resolve) => {
+				execFile(invocation.command, [...invocation.args, "--version"], {
+					env: this.options.env,
+					timeout: this.options.startTimeoutMs
+				}, (error, stdout) => resolve(error ? "" : stdout.trim()));
+			});
+			const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+			if (!match || !(Number(match[1]) > 0 || Number(match[2]) > 21 || Number(match[2]) === 21 && Number(match[3]) >= 22)) throw new AgentDriverUnavailable("Agent control requires agent-device 0.21.22 or later with serial daemon policy on the hosting Mac.");
+		}
+		mkdirSync(this.options.stateDir, {
+			recursive: true,
+			mode: 448
+		});
+		chmodSync(this.options.stateDir, 448);
+		const attempt = tryAcquireClaim({
+			root: this.options.claimRoot,
+			mode: "exclusive",
+			label: "agent-device daemon"
+		});
+		if (attempt.pending) releaseClaim(attempt.pending);
+		if (!attempt.acquired) throw new Error(`The agent-device daemon is held by another process: ${this.options.claimRoot}`);
+		const claim = attempt.acquired;
+		this.claim = claim;
+		this.stopping = false;
+		this.androidVerifiedAt = 0;
+		rmSync(join(this.options.stateDir, "daemon.json"), { force: true });
+		const policy = join(this.options.stateDir, "policy.json");
+		writeFileSync(policy, `${JSON.stringify(this.options.device ? devicePolicy(this.options.device) : POLICY)}\n`, { mode: 384 });
+		markClaimChildPending(claim);
+		const token = newAgentToken();
+		let proxy;
+		try {
+			proxy = spawn(invocation.command, [
+				...invocation.args,
+				"proxy",
+				"--host",
+				"127.0.0.1",
+				"--state-dir",
+				this.options.stateDir
+			], {
+				env: {
+					...this.options.env,
+					PATH: [dirname(process.execPath), this.options.env.PATH].filter(Boolean).join(delimiter),
+					AGENT_DEVICE_DAEMON_AUTH_TOKEN: token,
+					AGENT_DEVICE_DAEMON_POLICY: policy,
+					AGENT_DEVICE_MACOS_APP_BACKEND: "native",
+					AGENT_DEVICE_NO_UPDATE_NOTIFIER: "1",
+					...this.options.device?.serial ? { AGENT_DEVICE_ANDROID_SNAPSHOT_HELPER_SESSION: "0" } : {},
+					...this.options.device ? { AGENT_DEVICE_CLAIMS_DIR: join(this.options.stateDir, "device-claims") } : {}
+				},
+				...this.options.device ? { cwd: "/" } : {},
+				detached: true,
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				]
+			});
+			if (this.options.device) this.deviceProxy = {
+				child: proxy,
+				record: proxy.pid === void 0 ? null : this.captured(proxy.pid)
+			};
+			const url = await this.listening(proxy);
+			const { record: daemon, admin } = this.readDaemon();
+			this.daemonRecord = daemon;
+			const proxyIdentity = proxy.pid === void 0 ? null : captureProcessIdentity(proxy.pid);
+			if (!proxyIdentity?.ok) throw new Error("The agent-device proxy identity could not be captured.");
+			setClaimChild(claim, daemon);
+			if (!await leasesBackend(url, this.options.device ? deviceScope(this.options.device).backend : "macos-app")) throw new AgentDriverUnavailable(this.options.device ? this.options.device.serial === void 0 ? "Agent control requires agent-device 0.21.20 or later with the ios-instance backend and daemon policy on the hosting Mac." : "Agent control requires agent-device 0.21.22 or later with the android-instance backend and serial daemon policy on the hosting Mac." : UNSCOPED);
+			const watch = setInterval(() => void this.watchDaemon(), this.options.watchMs);
+			watch.unref();
+			const running = {
+				reported: false,
+				proxy,
+				proxyRecord: {
+					pid: proxy.pid,
+					processToken: proxyIdentity.token
+				},
+				daemon,
+				url,
+				token,
+				admin,
+				watch
+			};
+			this.running = running;
+			proxy.once("exit", () => {
+				if (this.running === running) this.exited();
+			});
+		} catch (error) {
+			this.running = null;
+			if (!this.daemonRecord) try {
+				this.daemonRecord = this.readDaemon().record;
+			} catch {}
+			await this.teardown(proxy).catch(() => void 0);
+			throw error;
+		}
+	}
+	listening(proxy) {
+		return new Promise((resolve, reject) => {
+			let output = "";
+			let errors = "";
+			const timer = setTimeout(() => finish(/* @__PURE__ */ new Error("The agent-device proxy did not report a listening address.")), this.options.startTimeoutMs);
+			const finish = (result) => {
+				clearTimeout(timer);
+				proxy.stdout?.off("data", onData);
+				proxy.stderr?.off("data", onError);
+				proxy.stderr?.resume();
+				proxy.off("close", onExit);
+				proxy.off("error", finish);
+				if (result instanceof Error) reject(result);
+				else resolve(result);
+			};
+			const onData = (chunk) => {
+				output = (output + chunk.toString()).slice(-4096);
+				const match = LISTENING.exec(output);
+				if (match) finish(new URL(match[1]));
+			};
+			const onExit = (code) => finish(/* @__PURE__ */ new Error(`The agent-device proxy exited with ${String(code)} before it was ready.${errors.trim() ? ` ${errors.trim()}` : ""}`));
+			const onError = (chunk) => {
+				errors = (errors + chunk.toString()).slice(-400);
+			};
+			proxy.stdout?.on("data", onData);
+			proxy.stderr?.on("data", onError);
+			proxy.once("close", onExit);
+			proxy.once("error", finish);
+		});
+	}
+	readDaemon() {
+		const value = JSON.parse(readFileSync(join(this.options.stateDir, "daemon.json"), "utf8"));
+		if (!isJsonObject(value) || typeof value.pid !== "number" || !Number.isInteger(value.pid) || value.pid < 2) throw new Error("The agent-device daemon record has no pid.");
+		const identity = captureProcessIdentity(value.pid);
+		if (!identity.ok) throw new Error("The agent-device daemon identity could not be captured.");
+		const record = {
+			pid: value.pid,
+			processToken: identity.token
+		};
+		if (typeof value.httpPort !== "number" || !Number.isInteger(value.httpPort) || typeof value.token !== "string" || !value.token) {
+			this.daemonRecord = record;
+			throw new Error("The agent-device daemon record has no HTTP listener.");
+		}
+		if (this.options.device && value.policyDigest !== devicePolicyDigest(this.options.device)) {
+			this.daemonRecord = record;
+			throw new AgentDriverUnavailable(this.options.device.serial === void 0 ? "Agent control requires agent-device 0.21.20 or later enforcing this hosted simulator policy." : "Agent control requires agent-device 0.21.22 or later enforcing this hosted emulator serial policy.");
+		}
+		return {
+			record,
+			admin: {
+				port: value.httpPort,
+				token: value.token
+			}
+		};
+	}
+	async androidIdentity(cached = false) {
+		const device = this.options.device;
+		if (!device?.serial) return "verified";
+		if (this.androidProbe) return this.androidProbe;
+		if (cached && Date.now() - this.androidVerifiedAt < 2e3) return "verified";
+		this.androidProbe = new Promise((resolve) => {
+			execFile(adbPath(this.options.env), [
+				"-s",
+				device.serial,
+				"emu",
+				"avd",
+				"name"
+			], {
+				env: this.options.env,
+				timeout: 2e3,
+				killSignal: "SIGKILL"
+			}, (error, stdout, stderr) => {
+				if (error) resolve(!error.killed && /device .*not found|device not found|no devices\/emulators found|could not connect to TCP port \d+: Connection refused/.test(`${error.message} ${stderr}`) ? "lost" : "unverified");
+				else resolve(stdout.split("\n")[0]?.trim() === device.avdName ? "verified" : "lost");
+			});
+		});
+		try {
+			const identity = await this.androidProbe;
+			this.androidVerifiedAt = identity === "verified" ? Date.now() : 0;
+			return identity;
+		} finally {
+			this.androidProbe = null;
+		}
+	}
+	async watchDaemon() {
+		const running = this.running;
+		if (!running || this.stopping || running.reported) return;
+		if (inspectProcessIdentity(running.daemon) === "gone") this.exited();
+		else if (await this.androidIdentity() === "lost" && this.running === running && !this.stopping) this.exited();
+	}
+	exited() {
+		const running = this.running;
+		if (this.stopping || !running || running.reported) return;
+		running.reported = true;
+		clearInterval(running.watch);
+		this.listener?.();
+	}
+	async stop() {
+		this.stopping = true;
+		await this.starting?.catch(() => void 0);
+		const sessions = [...this.released];
+		this.released.clear();
+		for (const lease of this.leases.values()) clearInterval(lease.renew);
+		this.leases.clear();
+		const running = this.running;
+		this.running = null;
+		if (running) clearInterval(running.watch);
+		if (!this.claim && this.options.device) {
+			let attempt;
+			try {
+				attempt = tryAcquireClaim({
+					root: this.options.claimRoot,
+					mode: "exclusive",
+					label: "agent-device daemon"
+				});
+			} catch (error) {
+				throw new Error(`The agent-device daemon claim ${this.options.claimRoot} is unresolved: ${error.message}. Once it is gone, clear it with: ${claimRemoveCommand(this.options.claimRoot)}`, { cause: error });
+			}
+			if (attempt.pending) releaseClaim(attempt.pending);
+			if (!attempt.acquired) {
+				const path = attempt.held?.path ?? attempt.waitingFor?.[0]?.path ?? this.options.claimRoot;
+				throw new Error(`The agent-device daemon is unresolved; its claim ${path} was kept. Once it is gone, clear it with: ${claimRemoveCommand(path)}`);
+			}
+			this.claim = attempt.acquired;
+			this.daemonRecord = attempt.reaped.find((holder) => holder.child)?.child ?? null;
+		}
+		if (running || this.claim) await this.teardown(running?.proxy, running ?? void 0);
+		for (const session of sessions) this.removeSessionDirectories(session);
+	}
+	async teardown(proxy, running) {
+		proxy ??= this.deviceProxy?.child;
+		if (proxy?.pid !== void 0) {
+			const record = running?.proxyRecord ?? (this.options.device ? this.deviceProxy?.record : this.captured(proxy.pid));
+			const stopped = record ? await this.signalAndWait(record, true) : proxy.exitCode != null || proxy.signalCode != null;
+			if (this.options.device && !stopped) throw new Error(`The agent-device proxy is unresolved; its claim ${this.claim?.path} was kept. Once it is gone, clear it with: ${claimRemoveCommand(this.claim.path)}`);
+		}
+		await this.stopDaemon();
+		await this.stopIosRunners();
+		await this.stopAndroidHelpers();
+		this.daemonRecord = null;
+		this.deviceProxy = null;
+		if (!this.claim) return;
+		clearClaimChild(this.claim);
+		if (!releaseClaim(this.claim)) throw new Error(`The agent-device claim could not be released: ${this.claim.path}`);
+		this.claim = null;
+	}
+	captured(pid) {
+		const identity = captureProcessIdentity(pid);
+		return identity.ok ? {
+			pid,
+			processToken: identity.token
+		} : null;
+	}
+	async stopDaemon() {
+		if (!this.options.device || this.deviceProxy) try {
+			const invocation = resolveAgentDevice(this.options.env);
+			await new Promise((resolve) => {
+				execFile(invocation.command, [
+					...invocation.args,
+					"daemon",
+					"stop",
+					"--state-dir",
+					this.options.stateDir
+				], {
+					env: {
+						...this.options.env,
+						AGENT_DEVICE_NO_UPDATE_NOTIFIER: "1"
+					},
+					timeout: this.options.stopTimeoutMs
+				}, () => resolve());
+			});
+		} catch {}
+		if (this.deviceProxy?.child.pid !== void 0 && !this.daemonRecord) throw new Error(`The agent-device daemon identity is unresolved; its claim ${this.claim?.path} was kept. Once it is gone, clear it with: ${claimRemoveCommand(this.claim.path)}`);
+		if (this.daemonRecord && !await this.signalAndWait(this.daemonRecord, false)) throw new Error(`The agent-device daemon did not stop; its claim ${this.claim?.path} was kept.`);
+	}
+	async signalAndWait(record, group) {
+		for (const signal of ["SIGTERM", "SIGKILL"]) {
+			const status = inspectProcessIdentity(record);
+			if (status === "gone" || status === "different") return true;
+			if (status === "same") try {
+				process.kill(group ? -record.pid : record.pid, signal);
+			} catch {}
+			if (await waitForProcessExit(record, signal === "SIGTERM" ? 3e3 : 2e3)) return true;
+		}
+		return false;
+	}
+	async stopAndroidHelpers() {
+		const serial = this.options.device?.serial;
+		if (!serial || !this.daemonRecord) return;
+		const identity = await this.androidIdentity();
+		if (identity === "lost") return;
+		if (identity === "unverified") throw new Error("The hosted Android emulator identity could not be verified; its daemon claim was kept.");
+		const adb = (args) => new Promise((resolve, reject) => {
+			execFile(adbPath(this.options.env), [
+				"-s",
+				serial,
+				"shell",
+				...args
+			], {
+				env: this.options.env,
+				timeout: this.options.stopTimeoutMs
+			}, (error, stdout) => {
+				if (error && !(args[0] === "pidof" && error.code === 1 && !stdout.trim())) reject(error);
+				else resolve(stdout);
+			});
+		});
+		try {
+			for (const helper of ["com.callstack.agentdevice.snapshothelper", "com.callstack.agentdevice.imehelper"]) {
+				await adb([
+					"am",
+					"force-stop",
+					helper
+				]);
+				if ((await adb(["pidof", helper])).trim()) throw new Error(`The agent-device Android helper ${helper} did not stop; its daemon claim ${this.claim?.path} was kept.`);
+			}
+		} catch (error) {
+			if (await this.androidIdentity() !== "lost") throw error;
+		}
+	}
+	async stopIosRunners() {
+		if (!this.options.device?.udid) return;
+		const udid = this.options.device.udid.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		const destination = new RegExp(`(?:^|\\s)-destination\\s+platform=iOS Simulator,id=${udid}(?=\\s|$)`, "i");
+		const runners = (ps) => ps.split("\n").flatMap((line) => {
+			const match = /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(line);
+			if (!match || !/^(?:[^\n]*\/)?xcodebuild\s/.test(match[3]) || !/\stest-without-building(?:\s|$)/.test(match[3]) || !/\s-only-testing\s+AgentDeviceRunnerUITests\/RunnerTests\/testCommand(?:\s|$)/.test(match[3]) || !destination.test(match[3])) return [];
+			return [{
+				pid: Number(match[1]),
+				group: Number(match[1]) === Number(match[2])
+			}];
+		});
+		const candidates = runners(await listProcesses("pid=,pgid=,command=")).map((runner) => ({
+			pid: runner.pid,
+			group: runner.group,
+			record: this.captured(runner.pid)
+		}));
+		if (!candidates.length) return;
+		const current = runners(await listProcesses("pid=,pgid=,command="));
+		const failures = [];
+		for (const runner of candidates) {
+			if (!current.some((live) => live.pid === runner.pid && live.group === runner.group)) continue;
+			if (!runner.record || !await this.signalAndWait(runner.record, runner.group)) failures.push(runner.pid);
+		}
+		if (failures.length) throw new Error(`The agent-device iOS runners did not stop (${failures.join(", ")}); their daemon claim ${this.claim?.path} was kept.`);
+	}
+	/**
+	* Grants one device's automatic instance lease or allocates and renews a macos-app lease over
+	* agent-device's host-only admin route. Forwarded requests are pinned to the grant's scope.
+	*/
+	async issue(app) {
+		const running = this.running;
+		if (!running) throw new Error("The agent-device daemon is not running.");
+		if (this.options.device) {
+			if (app.session !== this.options.device.session || app.udid !== this.options.device.udid || app.serial !== this.options.device.serial || app.avdName !== this.options.device.avdName) throw new Error(`The agent-device daemon belongs to another hosted ${this.options.device.serial ? "emulator" : "simulator"}.`);
+			if (await this.androidIdentity() !== "verified") throw new AgentDriverUnavailable("Agent control is refused: the hosted Android emulator identity could not be verified.");
+			const scope = {
+				tenant: `stim.${app.session}`,
+				runId: app.session,
+				clientId: "agent",
+				deviceKey: `${deviceScope(this.options.device).platform}:mobile:${deviceScope(this.options.device).id}`,
+				backend: deviceScope(this.options.device).backend
+			};
+			this.leases.set(app.session, {
+				id: app.session,
+				scope,
+				renewing: Promise.resolve()
+			});
+			return {
+				driver: "agent-device",
+				path: agentRoute(app.session),
+				token: newAgentToken(),
+				scope: app.session,
+				lease: scope
+			};
+		}
+		const scope = {
+			tenant: `stim.${app.session}`,
+			runId: app.session,
+			clientId: "agent",
+			deviceKey: `${app.bundleId}@${app.pid}`
+		};
+		await this.revoke(app.session);
+		const id = randomBytes(16).toString("hex");
+		await putLease(running.admin, id, scope);
+		const lease = {
+			id,
+			scope,
+			renewing: Promise.resolve(),
+			renew: setInterval(() => {
+				if (this.running !== running) return;
+				lease.renewing = putLease(running.admin, id, scope).catch((error) => process.stderr.write(`Hosted agent lease renewal failed: ${error.message}\n`));
+			}, this.options.leaseRenewMs)
+		};
+		lease.renew?.unref();
+		this.leases.set(app.session, lease);
+		return {
+			driver: "agent-device",
+			path: agentRoute(app.session),
+			token: newAgentToken(),
+			scope: id,
+			lease: scope
+		};
+	}
+	async revoke(session) {
+		const lease = this.leases.get(session);
+		if (!lease) return;
+		this.leases.delete(session);
+		this.released.add(session);
+		clearInterval(lease.renew);
+		try {
+			await lease.renewing;
+			if (this.running && !this.options.device) await adminRequest(this.running.admin, "DELETE", lease.id);
+		} finally {
+			this.removeSessionDirectories(session);
+		}
+	}
+	removeSessionDirectories(session) {
+		const sessionsDir = join(this.options.stateDir, "sessions");
+		try {
+			for (const entry of readdirSync(sessionsDir, { withFileTypes: true })) {
+				if (!entry.isDirectory() || !entry.name.startsWith(`stim.${session}_`)) continue;
+				try {
+					rmSync(join(sessionsDir, entry.name), {
+						recursive: true,
+						force: true
+					});
+				} catch (error) {
+					process.stderr.write(`Hosted agent session cleanup failed: ${error.message.replace(/\s+/g, " ")}\n`);
+				}
+			}
+		} catch (error) {
+			if (error.code !== "ENOENT") process.stderr.write(`Hosted agent session cleanup failed: ${error.message.replace(/\s+/g, " ")}\n`);
+		}
+	}
+	forward(session, request, response) {
+		const running = this.running;
+		const lease = this.leases.get(session);
+		if (!running || !lease) {
+			response.writeHead(503, { "content-type": "text/plain" }).end("Agent control is not running.\n");
+			return;
+		}
+		const target = daemonPath(session, request.url ?? "", request.method);
+		if (!target) {
+			response.writeHead(404, { "content-type": "text/plain" }).end("Not found.\n");
+			return;
+		}
+		if (!target.startsWith("/rpc")) {
+			this.relay(running, lease, request, response, target);
+			return;
+		}
+		this.relayPinned(running, lease, request, response, target);
+	}
+	async relayPinned(running, lease, request, response, target) {
+		let body;
+		try {
+			body = await readBody(request, MAX_RPC_BYTES);
+		} catch {
+			response.destroy();
+			return;
+		}
+		const pinned = pinLease(body, lease);
+		if (!Buffer.isBuffer(pinned)) response.writeHead(400, { "content-type": "application/json" }).end(JSON.stringify({
+			jsonrpc: "2.0",
+			id: pinned.id,
+			error: {
+				code: -32e3,
+				message: pinned.message,
+				data: {
+					code: "UNAUTHORIZED",
+					message: pinned.message,
+					hint: `The hosted agent connection allows only ${(this.options.device ? DEVICE_COMMANDS : POLICY.commands.allow).join(", ")} on the one ${this.options.device ? this.options.device.udid ? "hosted iOS simulator" : "hosted Android emulator" : "leased macOS app"}; retrying will not help.`,
+					retriable: false,
+					details: {
+						reason: "STIM_AGENT_REQUEST_REFUSED",
+						rule: pinned.rule,
+						...pinned.details
+					}
+				}
+			}
+		}));
+		else await this.relay(running, lease, request, response, target, pinned);
+	}
+	async relay(running, lease, request$1, response, target, body) {
+		const identity = await this.androidIdentity(true);
+		if (identity !== "verified" || this.running !== running || this.stopping || running.reported) {
+			response.writeHead(503, { "content-type": "text/plain" }).end(this.options.device?.serial ? "Agent control is refused: the hosted emulator is absent, replaced, or its identity could not be verified.\n" : "Agent control is not running.\n");
+			if (identity === "lost" && this.running === running) this.exited();
+			return;
+		}
+		const headers = {
+			authorization: `Bearer ${running.token}`,
+			"x-agent-device-tenant": lease.scope.tenant
+		};
+		for (const name of FORWARDED) {
+			const value = request$1.headers[name];
+			if (typeof value === "string") headers[name] = value;
+		}
+		if (body) headers["content-length"] = String(body.length);
+		const upstream = request({
+			host: running.url.hostname,
+			port: running.url.port,
+			method: request$1.method,
+			path: target,
+			headers
+		}, (answer) => {
+			const out = {};
+			for (const [name, value] of Object.entries(answer.headers)) if (value !== void 0 && !HOP_BY_HOP.has(name)) out[name] = value;
+			response.writeHead(answer.statusCode ?? 502, out);
+			answer.pipe(response);
+			answer.once("error", () => response.destroy());
+		});
+		upstream.once("error", () => {
+			if (response.headersSent) response.destroy();
+			else response.writeHead(502, { "content-type": "text/plain" }).end("Agent control is unavailable.\n");
+		});
+		response.once("close", () => {
+			if (!response.writableFinished) upstream.destroy();
+		});
+		if (body) upstream.end(body);
+		else request$1.pipe(upstream);
+	}
+};
+/**
+* Rewrites one JSON-RPC body so it can act only under the session's lease. The proxy token is one credential
+* for every client, so the lease, its owner scope and tenant session isolation come from the host, never from
+* the client. Methods other than commands and lease renewal or release are refused.
+*/
+function pinLease(body, lease) {
+	let rpc;
+	try {
+		rpc = body === null ? void 0 : JSON.parse(body.toString("utf8"));
+	} catch {}
+	const id = isJsonObject(rpc) && (typeof rpc.id === "string" || typeof rpc.id === "number") ? rpc.id : null;
+	if (!isJsonObject(rpc) || typeof rpc.method !== "string" || !isJsonObject(rpc.params)) return {
+		id,
+		rule: "request",
+		message: "Refused request: expected a JSON object with a string method and object params within the body size limit.",
+		details: {}
+	};
+	if (lease.scope.backend) return pinDeviceRequest(rpc, id, lease);
+	const { tenant, runId, clientId, deviceKey } = lease.scope;
+	const owner = {
+		runId,
+		leaseId: lease.id,
+		clientId,
+		deviceKey,
+		leaseProvider: "proxy"
+	};
+	if (COMMAND_METHODS.has(rpc.method)) {
+		const { runtime: _runtime, meta, flags, input, ...params } = rpc.params;
+		const refuseCommand = (value) => {
+			const command = typeof value === "string" ? value.slice(0, MAX_ECHO) : void 0;
+			return {
+				id,
+				rule: "command",
+				message: `Refused command${command === void 0 ? "" : ` "${command}"`}. Allowed commands: ${POLICY.commands.allow.join(", ")}.`,
+				details: command === void 0 ? {} : { command }
+			};
+		};
+		if (!isAllowedCommand(params.command)) return refuseCommand(params.command);
+		const steps = isJsonObject(flags) && Array.isArray(flags.batchSteps) ? flags.batchSteps : [];
+		for (const step of steps) if (!isJsonObject(step) || !isAllowedCommand(step.command)) return refuseCommand(isJsonObject(step) ? step.command : void 0);
+		rpc.params = {
+			...params,
+			flags: {
+				...withoutDeviceSelectors(flags),
+				platform: "macos",
+				...steps.length ? { batchSteps: steps.map(pinStep) } : {}
+			},
+			...isJsonObject(input) ? { input: withoutDeviceSelectors(input) } : {},
+			meta: {
+				...pickClientMeta(meta),
+				...owner,
+				tenantId: tenant,
+				leaseBackend: "macos-app",
+				sessionIsolation: "tenant"
+			}
+		};
+	} else if (LEASE_METHODS.has(rpc.method)) {
+		const { tenant: _tenant, provider: _provider, ...params } = rpc.params;
+		rpc.params = {
+			...params,
+			...owner,
+			tenantId: tenant,
+			backend: "macos-app"
+		};
+	} else {
+		const method = rpc.method.slice(0, MAX_ECHO);
+		return {
+			id,
+			rule: "method",
+			message: `Refused method "${method}".`,
+			details: { method }
+		};
+	}
+	return Buffer.from(JSON.stringify(rpc));
+}
+const DEVICE_LEASE_METHODS = /* @__PURE__ */ new Set([
+	...LEASE_METHODS,
+	"agent_device.lease.allocate",
+	"agent-device.lease.allocate"
+]);
+const DEVICE_CLIENT_AMBIENT_INPUTS = [
+	"cwd",
+	"stateDir",
+	"config",
+	"remoteConfig",
+	"daemonBaseUrl",
+	"daemonAuthToken",
+	"daemonTransport",
+	"daemonServerMode",
+	"tenant",
+	"tenantId",
+	"runId",
+	"clientId",
+	"deviceKey",
+	"leaseBackend",
+	"sessionIsolation",
+	"leaseProvider",
+	"provider"
+];
+const HOST_INPUTS = [
+	"out",
+	"saveScript",
+	"sessionSaveScript",
+	"baseline",
+	"launchConsole",
+	"launchArgs",
+	"launchUrl",
+	"bundleUrl",
+	"artifactsDir",
+	"stepsFile",
+	"searchPath",
+	"retainPaths",
+	"installSource",
+	"metroProjectRoot",
+	"metroRuntimeFile",
+	"iosXctestrunFile",
+	"iosXctestDerivedDataPath",
+	"iosXctestEnvDir",
+	"developerDir",
+	"artifact",
+	"dsym",
+	"reportJunit",
+	"recordAs",
+	"keyframes"
+];
+function pinDeviceRequest(rpc, id, lease) {
+	const params = rpc.params;
+	const { tenant, runId, clientId, deviceKey } = lease.scope;
+	const owner = {
+		tenantId: tenant,
+		runId,
+		clientId,
+		deviceKey,
+		leaseProvider: "proxy"
+	};
+	const platform = lease.scope.backend === "ios-instance" ? "ios" : "android";
+	const device = {
+		platform,
+		selector: platform === "ios" ? "udid" : "serial",
+		id: deviceKey.slice(`${platform}:mobile:`.length)
+	};
+	if (platform === "android" && [
+		params,
+		params.flags,
+		params.input
+	].some((fields) => isJsonObject(fields) && fields.serial !== void 0 && fields.serial !== device.id)) return {
+		id,
+		rule: "device",
+		message: "Another emulator is refused; this connection targets one hosted emulator.",
+		details: {}
+	};
+	if (COMMAND_METHODS.has(rpc.method)) {
+		const refusal = inspectDeviceCommand(params, id, device);
+		if (refusal) return refusal;
+		rpc.params = {
+			...pinDeviceCommand(params, device),
+			meta: {
+				...pickClientMeta(params.meta),
+				...owner,
+				...isJsonObject(params.meta) && typeof params.meta.leaseId === "string" ? { leaseId: params.meta.leaseId } : {},
+				leaseBackend: lease.scope.backend,
+				sessionIsolation: "tenant"
+			}
+		};
+	} else if (DEVICE_LEASE_METHODS.has(rpc.method)) {
+		if (platform === "android" && typeof params.deviceKey === "string" && params.deviceKey.startsWith("android:mobile:") && params.deviceKey !== deviceKey) return {
+			id,
+			rule: "device",
+			message: "Another emulator lease is refused.",
+			details: {}
+		};
+		rpc.params = {
+			...owner,
+			backend: lease.scope.backend,
+			...typeof params.leaseId === "string" ? { leaseId: params.leaseId } : {},
+			...typeof params.session === "string" ? { session: params.session } : {},
+			...typeof params.ttlMs === "number" ? { ttlMs: params.ttlMs } : {}
+		};
+	} else return {
+		id,
+		rule: "method",
+		message: "Refused method.",
+		details: {}
+	};
+	return Buffer.from(JSON.stringify(rpc));
+}
+function remoteScreenshot(value) {
+	return typeof value === "string" && /^\/tmp\/agent-device-screenshot-\d+-[a-z0-9]+\.png$/.test(value);
+}
+function inspectDeviceCommand(params, id, device) {
+	const refuse = (rule, message) => ({
+		id,
+		rule,
+		message,
+		details: {}
+	});
+	if (typeof params.command !== "string" || !DEVICE_COMMANDS.includes(params.command)) return refuse("command", "Refused command: this connection allows only hosted device inspection and interaction.");
+	if (device.platform === "android" && params.serial !== void 0 && params.serial !== device.id) return refuse("device", "Another emulator is refused; this connection targets one hosted emulator.");
+	const noun = device.platform === "android" ? "emulator" : "simulator";
+	const screenshot = params.command === "screenshot";
+	for (const fields of [params.flags, params.input]) {
+		if (!isJsonObject(fields)) continue;
+		if (device.platform === "android" ? fields.serial !== void 0 && fields.serial !== device.id : typeof fields.udid === "string" && fields.udid.trim() !== device.id) return refuse("device", `Another ${noun} is refused; this connection targets one hosted ${noun}.`);
+		if (HOST_INPUTS.some((key) => fields[key] !== void 0 && fields[key] !== false && !(screenshot && key === "out" && remoteScreenshot(fields[key])))) return refuse("host-path", "Host paths and launch inputs are refused.");
+		if (fields.shutdown === true) return refuse("command", "Simulator shutdown is refused; use stim stop.");
+	}
+	const positionals = Array.isArray(params.positionals) ? params.positionals : [];
+	if (screenshot && positionals.some((value) => !remoteScreenshot(value))) return refuse("host-path", "Screenshots use only agent-device remote artifacts.");
+	if ((params.command === "open" || params.command === "close") && positionals.some((value) => typeof value !== "string" || /[\\:]/.test(value) || value.includes("/") || value.includes(String.fromCharCode(0)))) return refuse("host-path", "Open and close accept only installed simulator app names or bundle ids.");
+	for (const fields of [params.flags, params.input]) {
+		if (!isJsonObject(fields) || fields.batchSteps === void 0) continue;
+		if (!Array.isArray(fields.batchSteps)) return refuse("request", "Invalid batch steps.");
+		for (const step of fields.batchSteps) {
+			if (!isJsonObject(step)) return refuse("request", "Invalid batch step.");
+			const failure = inspectDeviceCommand(step, id, device);
+			if (failure) return failure;
+		}
+	}
+	return null;
+}
+function pinDeviceCommand(params, device) {
+	const { runtime: _runtime, meta: _meta, flags, input, ...rest } = params;
+	const fields = (value) => {
+		const source = withoutDeviceSelectors(value);
+		for (const key of DEVICE_CLIENT_AMBIENT_INPUTS) delete source[key];
+		return {
+			...source,
+			platform: device.platform,
+			[device.selector]: device.id,
+			...Array.isArray(source.batchSteps) ? { batchSteps: source.batchSteps.map((step) => pinDeviceCommand(step, device)) } : {}
+		};
+	};
+	return {
+		command: rest.command,
+		...rest.session !== void 0 ? { session: rest.session } : {},
+		...rest.positionals !== void 0 ? { positionals: rest.positionals } : {},
+		flags: fields(flags),
+		...isJsonObject(input) ? { input: fields(input) } : {}
+	};
+}
+/**
+* Flags that pick a device. The host forces `platform: macos` so a first `open` cannot resolve to a host
+* simulator, emulator or phone; agent-device's `macos-app` admission enforces the same rule.
+*/
+const DEVICE_SELECTORS = [
+	"device",
+	"udid",
+	"serial",
+	"target",
+	"iosSimulatorDeviceSet",
+	"androidDeviceAllowlist"
+];
+function withoutDeviceSelectors(fields) {
+	if (!isJsonObject(fields)) return {};
+	return Object.fromEntries(Object.entries(fields).filter(([key]) => !DEVICE_SELECTORS.includes(key)));
+}
+function pinStep(step) {
+	if (!isJsonObject(step)) return step;
+	const { runtime: _runtime, flags, input, ...rest } = step;
+	return {
+		...rest,
+		flags: {
+			...withoutDeviceSelectors(flags),
+			platform: "macos"
+		},
+		...isJsonObject(input) ? { input: withoutDeviceSelectors(input) } : {}
+	};
+}
+function isAllowedCommand(command) {
+	return typeof command === "string" && POLICY.commands.allow.includes(command);
+}
+/**
+* The request metadata a client may set: reporting preferences and the local paths its own artifacts land
+* at. Host paths (`cwd`, `developerDir`), install sources, lock and lease options and runtime hints stay with
+* the host.
+*/
+const CLIENT_META = [
+	"requestId",
+	"debug",
+	"includeCost",
+	"responseLevel",
+	"sessionExplicit",
+	"clientArtifactPaths"
+];
+function pickClientMeta(meta) {
+	if (!isJsonObject(meta)) return {};
+	return Object.fromEntries(CLIENT_META.filter((key) => meta[key] !== void 0).map((key) => [key, meta[key]]));
+}
+function readBody(request, limit) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let size = 0;
+		request.on("data", (chunk) => {
+			size += chunk.length;
+			if (size <= limit) chunks.push(chunk);
+		});
+		request.once("end", () => resolve(size > limit ? null : Buffer.concat(chunks)));
+		request.once("error", reject);
+	});
+}
+function leasesBackend(url, backend) {
+	return new Promise((resolve) => {
+		const probe = request({
+			host: url.hostname,
+			port: url.port,
+			method: "GET",
+			path: "/health",
+			timeout: 1e4
+		}, (answer) => {
+			let text = "";
+			answer.on("data", (chunk) => text += chunk.toString());
+			answer.once("end", () => {
+				try {
+					const health = JSON.parse(text);
+					const backends = isJsonObject(health) && isJsonObject(health.upstream) ? health.upstream.leaseBackends : null;
+					resolve(Array.isArray(backends) && backends.includes(backend));
+				} catch {
+					resolve(false);
+				}
+			});
+		});
+		probe.once("timeout", () => probe.destroy());
+		probe.once("error", () => resolve(false));
+		probe.end();
+	});
+}
+function putLease(admin, id, scope) {
+	return adminRequest(admin, "PUT", id, {
+		tenantId: scope.tenant,
+		runId: scope.runId,
+		clientId: scope.clientId,
+		leaseBackend: "macos-app",
+		leaseProvider: "proxy",
+		deviceKey: scope.deviceKey,
+		ttlMs: LEASE_TTL_MS
+	});
+}
+/** One call to agent-device's host-only `/admin/leases` route on the daemon's loopback listener. */
+function adminRequest(admin, method, id, body) {
+	const payload = body ? Buffer.from(JSON.stringify(body)) : void 0;
+	return new Promise((resolve, reject) => {
+		const call = request({
+			host: "127.0.0.1",
+			port: admin.port,
+			method,
+			path: `/admin/leases/${id}`,
+			timeout: 1e4,
+			headers: {
+				authorization: `Bearer ${admin.token}`,
+				...payload ? {
+					"content-type": "application/json",
+					"content-length": String(payload.length)
+				} : {}
+			}
+		}, (answer) => {
+			let text = "";
+			answer.on("data", (chunk) => text += chunk.toString());
+			answer.once("end", () => answer.statusCode === 200 ? resolve() : reject(/* @__PURE__ */ new Error(`agent-device refused the lease (${String(answer.statusCode)}): ${text.slice(0, 200)}`)));
+		});
+		call.once("timeout", () => call.destroy(/* @__PURE__ */ new Error("agent-device did not answer the lease request.")));
+		call.once("error", reject);
+		call.end(payload);
+	});
+}
+const DAEMON_PATHS = /^\/(?:rpc|health|artifacts)(?:\/[\w.~-]+)*\/?$/;
+/**
+* The proxy path behind a session route, only for commands (`/rpc`), health and artifact downloads; null
+* otherwise. Uploads serve installs, which a macos-app lease refuses, and session diagnostics are not scoped
+* to one client.
+*/
+function daemonPath(session, url, method) {
+	const prefix = `${AGENT_ROUTE_PREFIX}${session}`;
+	if (!url.startsWith(prefix)) return null;
+	const rest = url.slice(prefix.length);
+	const query = rest.indexOf("?");
+	const path = query < 0 ? rest : rest.slice(0, query);
+	if (!DAEMON_PATHS.test(path) || path.includes("..")) return null;
+	return (path.startsWith("/rpc") ? method === "POST" : method === "GET") ? rest : null;
+}
+//#endregion
+//#region index.ts
+const apiVersion = AGENT_DRIVER_API_VERSION;
+const id = "agent-device";
+function createAgentDriver(input) {
+	return new AgentDeviceDriver(input);
+}
+const client = {
+	configFile: "agent-device-remote.json",
+	access({ grant, baseUrl, file, platform }) {
+		if (grant.driver !== "agent-device" || !grant.lease || grant.lease.backend !== (platform === "macos" ? void 0 : `${platform}-instance`)) return null;
+		const config = {
+			daemonBaseUrl: baseUrl,
+			daemonAuthToken: grant.token,
+			tenant: grant.lease.tenant,
+			sessionIsolation: "tenant",
+			runId: grant.lease.runId,
+			...platform === "macos" ? { leaseId: grant.scope } : {},
+			leaseBackend: platform === "macos" ? "macos-app" : `${platform}-instance`,
+			leaseProvider: "proxy",
+			clientId: grant.lease.clientId,
+			deviceKey: grant.lease.deviceKey,
+			platform
+		};
+		return {
+			config: `${JSON.stringify(config, null, 2)}\n`,
+			command: `agent-device <command> --remote-config ${file}`
+		};
+	}
+};
+const actions = { read: ({ workspaceDir }) => createAgentActionReader({ sessionsDirs: [join(workspaceDir, "agent-device", "sessions")] })() };
+//#endregion
+export { AgentDeviceDriver, actions, apiVersion, client, createAgentDriver, id, resolveAgentDevice };

package/package.json

@@ -1,11 +1,36 @@
 {
   "name": "@stim-cli/agent-driver-agent-device",
-  "version": "0.0.0",
-  "description": "Placeholder. The first real version is published by the Stim release workflow.",
+  "version": "1.21.0",
+  "description": "agent-device driver for stim-server hosted apps.",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/appandflow/stim.git",
     "directory": "packages/agent-driver-agent-device"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "module-sync": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "@stim-cli/agent-driver": "^1.21.0",
+    "@stim-cli/core": "^1.21.0"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "tsdown"
   }
-}
+}