@xevy/heny-connect 0.2.0 → 0.4.0

package/lib/process-runner.mjs

@@ -0,0 +1,62 @@
+import { spawn, spawnSync } from "node:child_process";
+import { platform } from "node:os";
+
+const OUTPUT_LIMIT = 1024 * 1024;
+
+function cleanEnvironment() {
+  const allowed = ["SystemRoot", "ComSpec", "PATH", "PATHEXT", "TEMP", "TMP", "WINDIR", "LOCALAPPDATA", "APPDATA"];
+  return Object.fromEntries(allowed.flatMap((key) => typeof process.env[key] === "string" ? [[key, process.env[key]]] : []));
+}
+
+function stopTree(child) {
+  if (!child.pid) return;
+  if (platform() === "win32") spawnSync("taskkill.exe", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+  else {
+    try { process.kill(-child.pid, "SIGKILL"); } catch { try { child.kill("SIGKILL"); } catch {} }
+  }
+}
+
+export function runProcess({ executable, args = [], timeoutMs = 120_000, cwd, signal }) {
+  if (typeof executable !== "string" || !executable.trim() || executable.includes("\0") || /[\r\n]/.test(executable)) throw Object.assign(new Error("Choose a valid executable."), { code: "invalid_executable" });
+  if (!Array.isArray(args) || args.length > 100 || args.some((arg) => typeof arg !== "string" || arg.includes("\0") || arg.length > 8192)) throw Object.assign(new Error("Process arguments are invalid."), { code: "invalid_process_args" });
+  const started = Date.now();
+  return new Promise((resolve, reject) => {
+    const child = spawn(executable, args, { cwd, env: cleanEnvironment(), windowsHide: true, shell: false, detached: platform() !== "win32", stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let truncated = false;
+    let settled = false;
+    const collect = (kind, chunk) => {
+      const text = chunk.toString("utf8");
+      if (kind === "stdout") {
+        const remaining = Math.max(0, OUTPUT_LIMIT - Buffer.byteLength(stdout));
+        stdout += Buffer.from(text).subarray(0, remaining).toString("utf8");
+        if (Buffer.byteLength(text) > remaining) truncated = true;
+      } else {
+        const remaining = Math.max(0, OUTPUT_LIMIT - Buffer.byteLength(stderr));
+        stderr += Buffer.from(text).subarray(0, remaining).toString("utf8");
+        if (Buffer.byteLength(text) > remaining) truncated = true;
+      }
+    };
+    child.stdout.on("data", (chunk) => collect("stdout", chunk));
+    child.stderr.on("data", (chunk) => collect("stderr", chunk));
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      reject(error);
+    };
+    const abort = () => { stopTree(child); fail(Object.assign(new Error("Process cancelled."), { code: "command_cancelled" })); };
+    signal?.addEventListener("abort", abort, { once: true });
+    const timer = setTimeout(() => { stopTree(child); fail(Object.assign(new Error("Process exceeded its time limit."), { code: "process_timeout" })); }, Math.min(120_000, Math.max(100, timeoutMs)));
+    child.once("error", (error) => { fail(Object.assign(new Error("The process could not start."), { code: error.code === "ENOENT" ? "executable_not_found" : "process_start_failed" })); });
+    child.once("close", (exitCode, exitSignal) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      resolve({ executable, exitCode, signal: exitSignal, stdout, stderr, truncated, durationMs: Date.now() - started });
+    });
+  });
+}

package/lib/state.mjs

@@ -0,0 +1,54 @@
+import { spawnSync } from "node:child_process";
+import { chmod, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+
+export const CONNECT_HOME = process.env.HENY_CONNECT_HOME || (platform() === "win32" && process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, "Heny Connect") : homedir());
+export const STATE_FILE = join(CONNECT_HOME, ".heny-connect.json");
+export const STATUS_FILE = join(CONNECT_HOME, "worker-status.json");
+export const PAUSE_FILE = join(CONNECT_HOME, "paused");
+export const STOP_FILE = join(CONNECT_HOME, "stopping");
+export const LOCK_FILE = join(CONNECT_HOME, "worker.lock");
+
+export async function protectConnectHome() {
+  await mkdir(CONNECT_HOME, { recursive: true });
+  if (platform() === "win32") {
+    const script = [
+      "$target=$env:HENY_ACL_TARGET",
+      "$acl=New-Object System.Security.AccessControl.DirectorySecurity",
+      "$acl.SetAccessRuleProtection($true,$false)",
+      "$inherit=[System.Security.AccessControl.InheritanceFlags]'ContainerInherit,ObjectInherit'",
+      "$prop=[System.Security.AccessControl.PropagationFlags]::None",
+      "$allow=[System.Security.AccessControl.AccessControlType]::Allow",
+      "$full=[System.Security.AccessControl.FileSystemRights]::FullControl",
+      "$user=[System.Security.Principal.WindowsIdentity]::GetCurrent().User",
+      "$system=[System.Security.Principal.SecurityIdentifier]::new('S-1-5-18')",
+      "$acl.AddAccessRule([System.Security.AccessControl.FileSystemAccessRule]::new($user,$full,$inherit,$prop,$allow))",
+      "$acl.AddAccessRule([System.Security.AccessControl.FileSystemAccessRule]::new($system,$full,$inherit,$prop,$allow))",
+      "Set-Acl -LiteralPath $target -AclObject $acl",
+    ].join(";");
+    const result = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", script], { windowsHide: true, stdio: "ignore", env: { ...process.env, HENY_ACL_TARGET: CONNECT_HOME } });
+    if (result.status !== 0) throw Object.assign(new Error("Heny Connect could not protect its local state."), { code: "acl_failed" });
+  }
+}
+
+export async function loadState() {
+  try { return JSON.parse(await readFile(STATE_FILE, "utf8")); } catch { return null; }
+}
+
+export async function saveState(state) {
+  await protectConnectHome();
+  const temporary = `${STATE_FILE}.tmp`;
+  await writeFile(temporary, JSON.stringify(state, null, 2), { mode: 0o600 });
+  await rename(temporary, STATE_FILE);
+  await chmod(STATE_FILE, 0o600).catch(() => undefined);
+}
+
+export async function clearState() {
+  await unlink(STATE_FILE).catch(() => undefined);
+}
+
+export async function writeStatus(status) {
+  await mkdir(CONNECT_HOME, { recursive: true });
+  await writeFile(STATUS_FILE, JSON.stringify({ ...status, updatedAt: new Date().toISOString() }), { mode: 0o600 });
+}

package/lib/validating-proxy.mjs

@@ -0,0 +1,70 @@
+import http from "node:http";
+import net from "node:net";
+import { resolvePublicHost, resolvePublicUrl } from "./network-policy.mjs";
+
+function safeDestroy(stream) {
+  try { stream.destroy(); } catch {}
+}
+
+export async function createValidatingProxy(options = {}) {
+  const lookup = options.lookup;
+  const server = http.createServer(async (request, response) => {
+    try {
+      const { url, address, family } = await resolvePublicUrl(request.url, lookup);
+      const headers = { ...request.headers, host: url.host };
+      delete headers["proxy-connection"];
+      const upstream = http.request({
+        host: address,
+        family,
+        port: Number(url.port || 80),
+        method: request.method,
+        path: `${url.pathname}${url.search}`,
+        headers,
+      }, (incoming) => {
+        response.writeHead(incoming.statusCode || 502, incoming.statusMessage, incoming.headers);
+        incoming.pipe(response);
+      });
+      upstream.on("error", () => {
+        if (!response.headersSent) response.writeHead(502);
+        response.end();
+      });
+      request.pipe(upstream);
+    } catch {
+      response.writeHead(403, { "content-type": "text/plain", connection: "close" });
+      response.end("Destination blocked");
+    }
+  });
+
+  server.on("connect", async (request, client, head) => {
+    try {
+      const authority = request.url || "";
+      const match = authority.match(/^\[([^\]]+)]:(\d+)$/) || authority.match(/^([^:]+):(\d+)$/);
+      if (!match) throw new Error("Invalid authority");
+      const host = match[1];
+      const port = Number(match[2]);
+      if (port !== 443 && port !== 80) throw new Error("Port blocked");
+      const { address, family } = await resolvePublicHost(host, lookup);
+      const upstream = net.connect({ host: address, family, port }, () => {
+        client.write("HTTP/1.1 200 Connection Established\r\nProxy-Agent: Heny\r\n\r\n");
+        if (head.length) upstream.write(head);
+        client.pipe(upstream);
+        upstream.pipe(client);
+      });
+      upstream.on("error", () => safeDestroy(client));
+      client.on("error", () => safeDestroy(upstream));
+    } catch {
+      client.write("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
+      safeDestroy(client);
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  const address = server.address();
+  return {
+    port: address.port,
+    close: () => new Promise((resolve) => server.close(resolve)),
+  };
+}

package/lib/work-folder.mjs

@@ -0,0 +1,129 @@
+import { lstat, mkdir, open, readdir, readFile, realpath, rename, rm, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+const MAX_FILE_BYTES = 1024 * 1024;
+const MAX_FOLDER_BYTES = 100 * 1024 * 1024;
+const MAX_ENTRIES = 1000;
+
+function invalidPath(message = "Use a relative path inside the Agent work folder.") {
+  return Object.assign(new Error(message), { code: "invalid_work_path" });
+}
+
+function normaliseRelative(value, allowEmpty = false) {
+  if (typeof value !== "string" || value.includes("\0") || isAbsolute(value) || /^[a-zA-Z]:[\\/]/.test(value)) throw invalidPath();
+  const parts = value.split(/[\\/]+/).filter(Boolean);
+  if (parts.some((part) => part === "." || part === "..")) throw invalidPath();
+  const output = parts.join(sep);
+  if (!allowEmpty && !output) throw invalidPath();
+  if (output.length > 500) throw invalidPath("The Agent work path is too long.");
+  return output;
+}
+
+async function rejectLinks(root, target, allowMissingLeaf = false) {
+  const rel = relative(root, target);
+  if (rel.startsWith(`..${sep}`) || rel === ".." || isAbsolute(rel)) throw invalidPath();
+  const parts = rel ? rel.split(sep) : [];
+  let current = root;
+  for (let index = 0; index < parts.length; index += 1) {
+    current = join(current, parts[index]);
+    try {
+      const info = await lstat(current);
+      if (info.isSymbolicLink()) throw Object.assign(new Error("Links and Windows reparse points are unavailable in Agent work folders."), { code: "work_link_denied" });
+    } catch (error) {
+      if (error.code === "ENOENT" && allowMissingLeaf && index === parts.length - 1) return;
+      throw error;
+    }
+  }
+}
+
+async function folderBytes(path, ceiling = MAX_FOLDER_BYTES) {
+  let total = 0;
+  const walk = async (dir) => {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      const target = join(dir, entry.name);
+      if (entry.isSymbolicLink()) throw Object.assign(new Error("Links are unavailable in Agent work folders."), { code: "work_link_denied" });
+      if (entry.isDirectory()) await walk(target);
+      else if (entry.isFile()) total += (await stat(target)).size;
+      if (total > ceiling) return;
+    }
+  };
+  await walk(path);
+  return total;
+}
+
+export class WorkFolder {
+  constructor(root) { this.root = resolve(root); }
+
+  async start() {
+    await mkdir(this.root, { recursive: true, mode: 0o700 });
+    const canonical = await realpath(this.root);
+    if (canonical !== this.root && canonical.toLowerCase() !== this.root.toLowerCase()) throw invalidPath("The Agent work folder must resolve to its configured directory.");
+  }
+
+  async resolvePath(value, { allowEmpty = false, allowMissingLeaf = false } = {}) {
+    await this.start();
+    const rel = normaliseRelative(value, allowEmpty);
+    const target = resolve(this.root, rel);
+    await rejectLinks(this.root, target, allowMissingLeaf);
+    return { target, relative: rel.replaceAll(sep, "/") };
+  }
+
+  async list(value = "") {
+    const { target, relative: rel } = await this.resolvePath(value, { allowEmpty: true });
+    const info = await stat(target);
+    if (!info.isDirectory()) throw Object.assign(new Error("The requested work path is not a directory."), { code: "work_not_directory" });
+    const all = await readdir(target, { withFileTypes: true });
+    const entries = [];
+    for (const entry of all.slice(0, MAX_ENTRIES)) {
+      if (entry.isSymbolicLink()) continue;
+      const item = { name: entry.name, type: entry.isDirectory() ? "directory" : "file" };
+      if (entry.isFile()) item.bytes = (await stat(join(target, entry.name))).size;
+      entries.push(item);
+    }
+    return { path: rel, entries, truncated: all.length > MAX_ENTRIES };
+  }
+
+  async read(value) {
+    const { target, relative: rel } = await this.resolvePath(value);
+    const info = await stat(target);
+    if (!info.isFile()) throw Object.assign(new Error("The requested work path is not a file."), { code: "work_not_file" });
+    if (info.size > MAX_FILE_BYTES) throw Object.assign(new Error("The requested file exceeds 1 MiB."), { code: "work_file_too_large" });
+    const content = await readFile(target, "utf8");
+    return { path: rel, content, bytes: Buffer.byteLength(content), truncated: false };
+  }
+
+  async write(value, content) {
+    if (typeof content !== "string" || Buffer.byteLength(content) > MAX_FILE_BYTES) throw Object.assign(new Error("Work-folder writes are limited to 1 MiB."), { code: "work_file_too_large" });
+    const { target, relative: rel } = await this.resolvePath(value, { allowMissingLeaf: true });
+    const parent = dirname(target);
+    await rejectLinks(this.root, parent);
+    const existingBytes = await folderBytes(this.root);
+    let replacedBytes = 0;
+    try { replacedBytes = (await stat(target)).size; } catch (error) { if (error.code !== "ENOENT") throw error; }
+    if (existingBytes - replacedBytes + Buffer.byteLength(content) > MAX_FOLDER_BYTES) throw Object.assign(new Error("The Agent work folder exceeds its 100 MiB quota."), { code: "work_quota_exceeded" });
+    const temporary = join(parent, `.${basename(target)}.${process.pid}.${Date.now()}.tmp`);
+    const file = await open(temporary, "wx", 0o600);
+    try {
+      await file.writeFile(content, "utf8");
+      await file.close();
+      await rename(temporary, target);
+    } catch (error) {
+      await file.close().catch(() => undefined);
+      await rm(temporary, { force: true }).catch(() => undefined);
+      throw error;
+    }
+    return { path: rel, ok: true, bytes: Buffer.byteLength(content) };
+  }
+
+  async mkdir(value) {
+    const { target, relative: rel } = await this.resolvePath(value, { allowMissingLeaf: true });
+    await mkdir(target, { recursive: false, mode: 0o700 });
+    return { path: rel, ok: true };
+  }
+
+  async delete(value) {
+    const { target, relative: rel } = await this.resolvePath(value);
+    await rm(target, { recursive: false, force: false });
+    return { path: rel, ok: true };
+  }
+}

package/lib/worker.mjs

@@ -0,0 +1,251 @@
+import { open, readFile, unlink } from "node:fs/promises";
+import { ComputerRuntime } from "./computer-runtime.mjs";
+import { clearState, CONNECT_HOME, LOCK_FILE, PAUSE_FILE, STOP_FILE, writeStatus } from "./state.mjs";
+
+export const PROTOCOL_VERSION = 2;
+export const CAPABILITIES = [
+  "browser.navigate", "browser.snapshot", "browser.read", "browser.screenshot", "browser.click", "browser.fill", "browser.select", "browser.press", "browser.scroll", "browser.wait", "browser.back", "browser.upload", "browser.download",
+  "file.list", "file.read", "file.write", "file.mkdir", "file.delete", "process.run",
+];
+const LEASE_MS = 10_000;
+const POLL_MS = 2_000;
+const HEARTBEAT_MS = 30_000;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const settleWithin = (promise, milliseconds) => new Promise((resolve) => {
+  const timer = setTimeout(resolve, milliseconds);
+  timer.unref?.();
+  Promise.resolve(promise).then((value) => { clearTimeout(timer); resolve(value); }, () => { clearTimeout(timer); resolve(undefined); });
+});
+
+const attemptWithin = (promise, milliseconds) => new Promise((resolve) => {
+  const timer = setTimeout(() => resolve({ acknowledged: false }), milliseconds);
+  Promise.resolve(promise).then(
+    (value) => { clearTimeout(timer); resolve({ acknowledged: true, value }); },
+    (error) => { clearTimeout(timer); resolve({ acknowledged: false, error }); },
+  );
+});
+
+async function completeWithRetry(api, command, claimToken, status, result, error, cutoff) {
+  while (Date.now() < cutoff) {
+    const remaining = cutoff - Date.now();
+    const outcome = await attemptWithin(api.complete(command, claimToken, status, result, error), Math.min(2_000, remaining));
+    if (outcome.acknowledged) return true;
+    if (outcome.error?.status === 401) throw outcome.error;
+    if (outcome.error && [400, 409].includes(outcome.error.status)) return false;
+    const delay = Math.min(250, Math.max(0, cutoff - Date.now()));
+    if (delay) await sleep(delay);
+  }
+  return false;
+}
+
+function sanitizedCode(error) {
+  const value = typeof error?.code === "string" ? error.code : "worker_error";
+  return /^[a-z0-9_]{1,40}$/.test(value) ? value : "worker_error";
+}
+
+async function paused() {
+  try { await readFile(PAUSE_FILE); return true; } catch { return false; }
+}
+
+async function shutdownRequested() {
+  try { await readFile(STOP_FILE); return true; } catch { return false; }
+}
+
+async function acquireLock() {
+  try {
+    const file = await open(LOCK_FILE, "wx", 0o600);
+    await file.writeFile(String(process.pid));
+    return async () => { await file.close(); await unlink(LOCK_FILE).catch(() => undefined); };
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    let pid = 0;
+    try { pid = Number(await readFile(LOCK_FILE, "utf8")); process.kill(pid, 0); } catch {
+      await unlink(LOCK_FILE).catch(() => undefined);
+      return acquireLock();
+    }
+    throw Object.assign(new Error("Heny Connect is already running."), { code: "worker_running" });
+  }
+}
+
+export class DeviceApi {
+  constructor(state) { this.state = state; }
+
+  async request(path, body = {}) {
+    const response = await fetch(new URL(path, this.state.server), {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${this.state.token}` },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(20_000),
+    });
+    if (response.status === 401) {
+      await clearState();
+      throw Object.assign(new Error("Registration was revoked. Pair this computer again."), { code: "device_revoked", status: 401 });
+    }
+    if (response.status === 204) return null;
+    let parsed = null;
+    try { parsed = await response.json(); } catch {}
+    if (!response.ok) throw Object.assign(new Error(parsed?.error?.message || `Server answered HTTP ${response.status}`), { code: parsed?.error?.code || "server_error", status: response.status });
+    return parsed;
+  }
+
+  heartbeat(state, browserReady, current) {
+    return this.request("/api/devices/heartbeat", {
+      state,
+      browserReady,
+      capabilities: CAPABILITIES,
+      protocolVersion: PROTOCOL_VERSION,
+      ...(current ? { currentCommandId: current.id, currentAction: current.action } : {}),
+      detailCode: current ? "command_running" : state,
+    });
+  }
+
+  claim() { return this.request("/api/devices/commands/claim"); }
+  lease(command, claimToken) { return this.request(`/api/devices/commands/${command.id}/lease`, { claimToken, attempt: command.attempt }); }
+  complete(command, claimToken, status, result, error) {
+    return this.request(`/api/devices/commands/${command.id}/complete`, {
+      claimToken,
+      attempt: command.attempt,
+      status,
+      ...(result !== undefined ? { result } : {}),
+      ...(error ? { error } : {}),
+    });
+  }
+}
+
+export async function runWorker(state, options = {}) {
+  await unlink(STOP_FILE).catch(() => undefined);
+  const releaseLock = await acquireLock();
+  const api = options.api || new DeviceApi(state);
+  const runtime = options.runtime || (options.browser ? {
+    start: () => options.browser.start(),
+    stop: () => options.browser.stop(),
+    execute: (command, executeOptions) => options.browser.execute(command.action, command.payload, executeOptions),
+  } : new ComputerRuntime({ home: CONNECT_HOME }));
+  let active = null;
+  let stopped = false;
+  let nextHeartbeat = 0;
+  let pauseDeadline = 0;
+  const stop = () => { stopped = true; active?.controller.abort(); void runtime.stop().catch(() => undefined); };
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+  options.signal?.addEventListener("abort", stop, { once: true });
+  let watchBusy = false;
+  let pauseHandled = false;
+  const localWatch = setInterval(() => {
+    if (watchBusy) return;
+    watchBusy = true;
+    void Promise.all([paused(), shutdownRequested()]).then(async ([isPaused, shutdown]) => {
+      if (shutdown) stopped = true;
+      if (isPaused || shutdown) {
+        active?.controller.abort();
+        if (!pauseHandled) {
+          pauseHandled = true;
+          await runtime.stop().catch(() => undefined);
+          await writeStatus({ state: isPaused ? "paused" : "offline", currentCommandId: null, currentAction: null }).catch(() => undefined);
+        }
+      } else {
+        pauseHandled = false;
+      }
+    }).finally(() => { watchBusy = false; });
+  }, 250);
+
+  async function report(workerState, browserReady, current) {
+    await writeStatus({ state: workerState, currentCommandId: current?.id ?? null, currentAction: current?.action ?? null });
+    const heartbeat = await api.heartbeat(workerState, browserReady, current);
+    if (Array.isArray(heartbeat?.assignments) && typeof runtime.synchronise === "function") await runtime.synchronise(heartbeat.assignments);
+    nextHeartbeat = Date.now() + HEARTBEAT_MS;
+  }
+
+  try {
+    await writeStatus({ state: "browser_starting", currentCommandId: null, currentAction: null });
+    await api.heartbeat("browser_starting", false).catch(() => undefined);
+    while (!stopped) {
+      if (await shutdownRequested()) { stopped = true; break; }
+      if (await paused()) {
+        active?.controller.abort();
+        await runtime.stop();
+        const reportBudget = pauseDeadline ? Math.max(0, pauseDeadline - Date.now()) : 5_000;
+        await settleWithin(report("paused", false), reportBudget);
+        pauseDeadline = 0;
+        while (!stopped && await paused()) {
+          if (await shutdownRequested()) { stopped = true; break; }
+          await sleep(250);
+        }
+        if (stopped) break;
+        await writeStatus({ state: "browser_starting", currentCommandId: null, currentAction: null });
+        await api.heartbeat("browser_starting", false).catch(() => undefined);
+      }
+      try {
+        await runtime.start();
+        if (stopped) break;
+        if (await paused()) continue;
+        if (Date.now() >= nextHeartbeat) await report("available", true);
+        if (stopped) break;
+        if (await paused()) continue;
+        const claimed = await api.claim();
+        if (!claimed) { await sleep(options.pollMs ?? POLL_MS); continue; }
+        const { command, claimToken } = claimed;
+        const controller = new AbortController();
+        active = { command, claimToken, controller };
+        if (await paused()) controller.abort();
+        else await report("working", true, command);
+        const deadlineMs = Math.max(1, new Date(command.deadlineAt).getTime() - Date.now());
+        const deadline = setTimeout(() => controller.abort(), deadlineMs);
+        const pauseWatch = setInterval(() => { void Promise.all([paused(), shutdownRequested()]).then(([isPaused, shutdown]) => { if (shutdown) stopped = true; if (isPaused || shutdown) controller.abort(); }); }, 250);
+        const leaseWatch = setInterval(() => {
+          void api.lease(command, claimToken).then((lease) => { if (lease?.cancelRequested) controller.abort(); }).catch(() => controller.abort());
+        }, options.leaseMs ?? LEASE_MS);
+        try {
+          let status = "succeeded";
+          let result;
+          let completionError;
+          try {
+            result = await runtime.execute(command, { signal: controller.signal, timeoutMs: deadlineMs });
+          } catch (error) {
+            const cancelled = controller.signal.aborted;
+            status = cancelled ? "cancelled" : "failed";
+            completionError = { code: cancelled ? "command_cancelled" : sanitizedCode(error), message: cancelled ? "Command cancelled." : "The Computer action failed." };
+          }
+          const locallyPaused = status === "cancelled" && await paused();
+          if (locallyPaused) {
+            pauseDeadline = Date.now() + (await shutdownRequested() ? 3_000 : 5_000);
+            await runtime.stop().catch(() => undefined);
+            await writeStatus({ state: "paused", currentCommandId: null, currentAction: null }).catch(() => undefined);
+          }
+          const commandDeadline = new Date(command.deadlineAt).getTime();
+          const completionCutoff = locallyPaused ? Math.min(commandDeadline, pauseDeadline) : commandDeadline;
+          const acknowledged = await completeWithRetry(api, command, claimToken, status, result, completionError, completionCutoff);
+          if (!acknowledged && !locallyPaused) throw Object.assign(new Error("Command completion was not acknowledged."), { code: "completion_unconfirmed" });
+          const outcome = acknowledged ? status : "cancellation unconfirmed";
+          console.log(`${new Date().toISOString()} command ${command.id} ${command.action} ${outcome}`);
+        } finally {
+          clearTimeout(deadline);
+          clearInterval(pauseWatch);
+          clearInterval(leaseWatch);
+          active = null;
+        }
+        if (!await paused()) await report("available", true);
+      } catch (error) {
+        if (error.status === 401) throw error;
+        if (stopped) break;
+        if (await paused()) continue;
+        await runtime.stop().catch(() => undefined);
+        await writeStatus({ state: "error", detailCode: sanitizedCode(error), currentCommandId: null, currentAction: null });
+        await api.heartbeat("error", false).catch(() => undefined);
+        console.error(`${new Date().toISOString()} worker error ${sanitizedCode(error)}`);
+        await sleep(5_000);
+      }
+    }
+  } finally {
+    clearInterval(localWatch);
+    active?.controller.abort();
+    await runtime.stop().catch(() => undefined);
+    await settleWithin(api.heartbeat("offline", false), 5_000);
+    await writeStatus({ state: "offline", currentCommandId: null, currentAction: null }).catch(() => undefined);
+    await unlink(STOP_FILE).catch(() => undefined);
+    await releaseLock();
+    process.off("SIGINT", stop);
+    process.off("SIGTERM", stop);
+    options.signal?.removeEventListener("abort", stop);
+  }
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@xevy/heny-connect",
-  "version": "0.2.0",
-  "description": "Pair a computer with Heny and keep its device presence online.",
+  "version": "0.4.0",
+  "description": "Run Heny's isolated, permission-bounded Windows Computer worker.",
   "type": "module",
   "bin": {
     "heny-connect": "bin/heny-connect.mjs"
   },
   "files": [
     "bin",
+    "lib",
     "windows",
     "README.md"
   ],
@@ -15,7 +16,7 @@
     "test": "node --test test/*.node-test.mjs"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "publishConfig": {
     "access": "public"