@xevy/heny-connect 0.3.0 → 0.4.0

package/README.md

@@ -1,17 +1,21 @@
 # @xevy/heny-connect
 
-Heny Connect runs a dedicated browser worker on a paired Windows PC. It stays in the system tray, starts at sign-in, and executes three explicit commands from Heny Desktop:
+Heny Connect runs a bounded Computer worker on a paired Windows PC. It stays in the system tray, starts at sign-in, and gives each Agent–Computer assignment a separate browser profile and work folder.
 
-- Navigate to an approved public HTTP(S) URL
-- Read up to 50,000 characters of visible page text
-- Capture a viewport PNG up to 2 MiB
+Assigned capabilities cover:
+
+- Browser navigation, semantic snapshots, clicks, form fields, selection, keyboard input, scrolling, history, uploads, downloads, visible text, and screenshots
+- Work-folder listing, UTF-8 reads and atomic writes, directory creation, and deletion
+- Argument-vector process execution for Node.js, npm, and approved local programs
+
+Browser references expire after navigation. Files remain inside the assignment work folder with a 1 MiB per-file limit and 100 MiB folder quota. Process execution uses an argument vector with shell expansion disabled, a scrubbed environment, bounded output, cancellation, and a 120-second ceiling.
 
 ## Requirements
 
 - Windows 10 or 11
 - Microsoft Edge or Google Chrome
 - Node.js 22 or newer
-- A six-digit code from Heny **Desktop**
+- A six-digit code from Heny **Computers**
 
 ## Install and pair
 
@@ -25,7 +29,7 @@ heny-connect.cmd install
 
 The code works once and expires after 15 minutes. `install` starts the tray immediately and registers **HenyConnect** for the current user's Windows sign-in.
 
-Heny Connect stores its registration and dedicated browser profile under `%LOCALAPPDATA%\Heny Connect`. Windows ACLs grant access to the current user and SYSTEM.
+Heny Connect stores its registration and assignment runtimes under `%LOCALAPPDATA%\Heny Connect`. Windows ACLs grant access to the current user and SYSTEM. Retiring an assignment stops its browser and removes its local runtime directory on the next successful heartbeat.
 
 ## System tray
 
@@ -40,13 +44,13 @@ The tray reports:
 
 The menu provides **Open Heny**, **Pause/Resume**, **Reconnect now**, **Start at sign-in**, and **Quit**. Pause aborts current work, closes the dedicated browser, and reaches the local Paused state within five seconds during a network interruption.
 
-## Dedicated browser
+## Agent runtimes
 
-The companion owns a separate persistent Chromium profile. Logins created in that window remain available after worker and browser restarts.
+Every assignment owns a persistent Chromium profile. Logins created in that assignment window remain available after worker and browser restarts and stay separate from other Agents.
 
-Browser traffic uses a loopback validating proxy. Each HTTP request and HTTPS tunnel resolves the destination, rejects local/private/reserved addresses, and connects directly to the validated address. Chromium retains the destination Host and TLS certificate checks. Downloads, popups, external protocols, and browser permission grants are blocked.
+Browser traffic uses a loopback validating proxy. Each HTTP request and HTTPS tunnel resolves the destination, rejects local/private/reserved addresses, and connects directly to the validated address. Chromium retains the destination Host and TLS certificate checks. Downloads land in the assignment work folder. Popups, external protocols, and browser permission grants are blocked.
 
-The command protocol excludes click, type, submit, upload, shell execution, command-supplied JavaScript, and personal-profile attachment.
+The command protocol accepts structured actions with strict payload schemas. Browser commands use snapshot references. Process commands carry an executable and argument array. Heny requires an owner or admin to grant process authority on the assignment, then applies the Agent’s exact-action approval policy before execution.
 
 ## Commands
 

package/bin/heny-connect.mjs

@@ -8,7 +8,7 @@ import { readFile, unlink, writeFile } from "node:fs/promises";
 import { hostname, platform, release } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { CAPABILITIES, DeviceApi, runWorker } from "../lib/worker.mjs";
+import { CAPABILITIES, PROTOCOL_VERSION, DeviceApi, runWorker } from "../lib/worker.mjs";
 import { CONNECT_HOME, PAUSE_FILE, STATUS_FILE, loadState, protectConnectHome, saveState, writeStatus } from "../lib/state.mjs";
 
 const CLI_FILE = fileURLToPath(import.meta.url);
@@ -42,7 +42,7 @@ async function pair() {
   const server = opt("server", process.env.HENY_SERVER);
   if (!code || !server) { console.error("Usage: heny-connect pair --code 123456 --server https://heny.example"); process.exitCode = 2; return; }
   await protectConnectHome();
-  const result = await call(server, "/api/devices/pair", { code, system: systemLabel(), hostname: hostname(), capabilities: CAPABILITIES });
+  const result = await call(server, "/api/devices/pair", { code, system: systemLabel(), hostname: hostname(), capabilities: CAPABILITIES, protocolVersion: PROTOCOL_VERSION });
   await saveState({ server, token: result.token, deviceId: result.deviceId, workspace: result.workspace, pairedAt: new Date().toISOString() });
   await unlink(PAUSE_FILE).catch(() => undefined);
   console.log(`Paired with ${result.workspace?.name ?? "workspace"} as device ${result.deviceId}.`);

package/lib/browser-controller.mjs

@@ -1,6 +1,6 @@
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { mkdir } from "node:fs/promises";
+import { mkdir, stat } from "node:fs/promises";
 import net from "node:net";
 import { platform } from "node:os";
 import { join } from "node:path";
@@ -41,8 +41,9 @@ function findBrowser() {
 }
 
 export class BrowserController {
-  constructor({ home, browserPath = findBrowser(), lookup } = {}) {
+  constructor({ home, workRoot = join(home, "work"), browserPath = findBrowser(), lookup } = {}) {
     this.home = home;
+    this.workRoot = workRoot;
     this.browserPath = browserPath;
     this.lookup = lookup;
     this.process = null;
@@ -50,6 +51,8 @@ export class BrowserController {
     this.session = null;
     this.targetId = null;
     this.mainFrameId = null;
+    this.generation = 0;
+    this.references = new Map();
   }
 
   async start() {
@@ -140,6 +143,9 @@ export class BrowserController {
         void this.session?.send("Page.stopLoading").catch(() => undefined);
       }
     });
+    this.session.on("Page.frameNavigated", ({ frame }) => {
+      if (frame?.id === this.mainFrameId) void this.clearReferences();
+    });
     this.session.on("Target.targetCreated", ({ targetInfo }) => {
       if (targetInfo?.type === "page" && targetInfo.targetId !== this.targetId) void this.session?.send("Target.closeTarget", { targetId: targetInfo.targetId }).catch(() => undefined);
     });
@@ -152,10 +158,22 @@ export class BrowserController {
     const onAbort = () => { void this.session?.send("Page.stopLoading").catch(() => undefined); };
     signal?.addEventListener("abort", onAbort, { once: true });
     try {
-      const operation = action === "browser.navigate" ? this.navigate(payload.url, timeoutMs, signal)
-        : action === "browser.read" ? this.read()
-          : action === "browser.screenshot" ? this.screenshot()
-            : Promise.reject(Object.assign(new Error("Unsupported command."), { code: "unsupported_action" }));
+      const operations = {
+        "browser.navigate": () => this.navigate(payload.url, timeoutMs, signal),
+        "browser.snapshot": () => this.snapshot(),
+        "browser.read": () => this.read(),
+        "browser.screenshot": () => this.screenshot(),
+        "browser.click": () => this.click(payload.ref),
+        "browser.fill": () => this.fill(payload.ref, payload.value),
+        "browser.select": () => this.select(payload.ref, payload.value),
+        "browser.press": () => this.press(payload.key),
+        "browser.scroll": () => this.scroll(payload.direction, payload.amount),
+        "browser.wait": () => this.wait(payload.milliseconds, signal),
+        "browser.back": () => this.back(timeoutMs, signal),
+        "browser.upload": () => this.upload(payload.ref, payload.filePath),
+        "browser.download": () => this.download(payload.ref, timeoutMs, signal),
+      };
+      const operation = operations[action]?.() ?? Promise.reject(Object.assign(new Error("Unsupported command."), { code: "unsupported_action" }));
       const cancelled = new Promise((_, reject) => signal?.addEventListener("abort", () => reject(Object.assign(new Error("Command cancelled."), { code: "command_cancelled" })), { once: true }));
       return await Promise.race([operation, cancelled]);
     } finally {
@@ -198,6 +216,122 @@ export class BrowserController {
     }
   }
 
+  async clearReferences() {
+    for (const objectId of this.references.values()) await this.session?.send("Runtime.releaseObject", { objectId }).catch(() => undefined);
+    this.references.clear();
+    this.generation += 1;
+  }
+
+  async snapshot() {
+    await this.clearReferences();
+    const evaluated = await this.session.send("Runtime.evaluate", {
+      expression: `Array.from(document.querySelectorAll('a[href],button,input,textarea,select,[role="button"],[role="link"],[role="checkbox"],[role="radio"],[role="textbox"],[tabindex]')).filter(el=>{const r=el.getBoundingClientRect();const s=getComputedStyle(el);return r.width>0&&r.height>0&&s.visibility!=="hidden"&&s.display!=="none"&&!el.disabled}).slice(0,500)`,
+      returnByValue: false,
+    });
+    const arrayId = evaluated.result.objectId;
+    if (!arrayId) throw Object.assign(new Error("The page did not return an interactive snapshot."), { code: "snapshot_failed" });
+    const properties = await this.session.send("Runtime.getProperties", { objectId: arrayId, ownProperties: true });
+    const elements = [];
+    for (const property of properties.result ?? []) {
+      if (!/^\d+$/.test(property.name) || !property.value?.objectId) continue;
+      const objectId = property.value.objectId;
+      const details = await this.session.send("Runtime.callFunctionOn", {
+        objectId,
+        functionDeclaration: `function(){const role=this.getAttribute('role')||({A:'link',BUTTON:'button',INPUT:(this.type||'textbox'),TEXTAREA:'textbox',SELECT:'combobox'}[this.tagName]||this.tagName.toLowerCase());const name=(this.getAttribute('aria-label')||this.innerText||this.value||this.getAttribute('title')||this.getAttribute('placeholder')||'').replace(/\s+/g,' ').trim().slice(0,500);return {role:String(role).slice(0,80),name,value:('value'in this?String(this.value).slice(0,2000):undefined)}}`,
+        returnByValue: true,
+      });
+      const ref = `e${elements.length + 1}`;
+      this.references.set(ref, objectId);
+      elements.push({ ref, ...details.result.value });
+    }
+    await this.session.send("Runtime.releaseObject", { objectId: arrayId }).catch(() => undefined);
+    const identity = await this.pageIdentity();
+    parsePublicUrl(identity.url);
+    return { ...identity, generation: this.generation, elements, truncated: (properties.result ?? []).filter((property) => /^\d+$/.test(property.name)).length >= 500 };
+  }
+
+  element(ref) {
+    const objectId = this.references.get(ref);
+    if (!objectId) throw Object.assign(new Error("This element reference is stale. Take a new browser snapshot."), { code: "stale_element_ref" });
+    return objectId;
+  }
+
+  async callElement(ref, functionDeclaration, arguments_ = []) {
+    const result = await this.session.send("Runtime.callFunctionOn", { objectId: this.element(ref), functionDeclaration, arguments: arguments_.map((value) => ({ value })), awaitPromise: true, returnByValue: true });
+    if (result.exceptionDetails) throw Object.assign(new Error("The page interaction failed."), { code: "interaction_failed" });
+    await sleep(250);
+    return this.pageIdentity();
+  }
+
+  click(ref) {
+    return this.callElement(ref, "function(){this.scrollIntoView({block:'center'});this.focus();this.click();return true}");
+  }
+
+  fill(ref, value) {
+    return this.callElement(ref, "function(value){this.scrollIntoView({block:'center'});this.focus();const p=this instanceof HTMLTextAreaElement?HTMLTextAreaElement.prototype:HTMLInputElement.prototype;const setter=Object.getOwnPropertyDescriptor(p,'value')?.set;if(!setter)throw new Error('not fillable');setter.call(this,value);this.dispatchEvent(new Event('input',{bubbles:true}));this.dispatchEvent(new Event('change',{bubbles:true}));return true}", [value]);
+  }
+
+  select(ref, value) {
+    return this.callElement(ref, "function(value){if(!(this instanceof HTMLSelectElement))throw new Error('not selectable');this.focus();this.value=value;this.dispatchEvent(new Event('input',{bubbles:true}));this.dispatchEvent(new Event('change',{bubbles:true}));return true}", [value]);
+  }
+
+  async press(key) {
+    const text = key.length === 1 ? key : "";
+    const code = key.length === 1 ? `Key${key.toUpperCase()}` : key;
+    await this.session.send("Input.dispatchKeyEvent", { type: "keyDown", key, code, text });
+    await this.session.send("Input.dispatchKeyEvent", { type: "keyUp", key, code });
+    await sleep(250);
+    return this.pageIdentity();
+  }
+
+  async scroll(direction, amount = 700) {
+    await this.session.send("Runtime.evaluate", { expression: `window.scrollBy({top:${direction === "up" ? -Math.abs(amount) : Math.abs(amount)},behavior:'auto'});true`, returnByValue: true });
+    return this.pageIdentity();
+  }
+
+  async wait(milliseconds, signal) {
+    await Promise.race([
+      sleep(milliseconds),
+      new Promise((_, reject) => signal?.addEventListener("abort", () => reject(Object.assign(new Error("Command cancelled."), { code: "command_cancelled" })), { once: true })),
+    ]);
+    return this.pageIdentity();
+  }
+
+  async back(timeoutMs, signal) {
+    const history = await this.session.send("Page.getNavigationHistory");
+    const entry = history.entries?.[history.currentIndex - 1];
+    if (!entry) return this.pageIdentity();
+    const loaded = this.session.waitFor("Page.loadEventFired", timeoutMs, signal).catch(() => undefined);
+    await this.session.send("Page.navigateToHistoryEntry", { entryId: entry.id });
+    await loaded;
+    return this.pageIdentity();
+  }
+
+  async upload(ref, filePath) {
+    if (typeof filePath !== "string") throw Object.assign(new Error("Choose a file from the Agent work folder."), { code: "invalid_upload_path" });
+    await this.session.send("DOM.setFileInputFiles", { objectId: this.element(ref), files: [filePath] });
+    return this.pageIdentity();
+  }
+
+  async download(ref, timeoutMs, signal) {
+    const downloadRoot = join(this.workRoot, "downloads");
+    await mkdir(downloadRoot, { recursive: true, mode: 0o700 });
+    await this.session.send("Browser.setDownloadBehavior", { behavior: "allow", downloadPath: downloadRoot, eventsEnabled: true });
+    try {
+      const begin = this.session.waitFor("Browser.downloadWillBegin", timeoutMs, signal);
+      await this.click(ref);
+      const started = await begin;
+      let progress;
+      do { progress = await this.session.waitFor("Browser.downloadProgress", timeoutMs, signal); } while (progress.guid !== started.guid || progress.state === "inProgress");
+      if (progress.state !== "completed") throw Object.assign(new Error("The browser download did not complete."), { code: "download_failed" });
+      const target = join(downloadRoot, started.suggestedFilename);
+      const info = await stat(target);
+      return { ...(await this.pageIdentity()), download: { path: `downloads/${started.suggestedFilename}`, bytes: info.size } };
+    } finally {
+      await this.session?.send("Browser.setDownloadBehavior", { behavior: "deny" }).catch(() => undefined);
+    }
+  }
+
   async read() {
     const result = await this.session.send("Runtime.evaluate", {
       expression: `(()=>{const raw=(document.body?.innerText||"").replace(/\\r/g,"").replace(/[ \\t]+/g," ").replace(/\\n{3,}/g,"\\n\\n").trim();return {title:String(document.title||"").slice(0,1000),url:String(location.href),text:raw.slice(0,50000),truncated:raw.length>50000}})()`,
@@ -221,6 +355,7 @@ export class BrowserController {
     const session = this.session;
     this.session = null;
     this.mainFrameId = null;
+    await this.clearReferences();
     const browserProcess = this.process;
     this.process = null;
     if (browserProcess) {

package/lib/computer-runtime.mjs

@@ -0,0 +1,68 @@
+import { mkdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { BrowserController } from "./browser-controller.mjs";
+import { runProcess } from "./process-runner.mjs";
+import { WorkFolder } from "./work-folder.mjs";
+
+function safeRuntimeKey(value) {
+  if (value === "workspace") return value;
+  if (typeof value !== "string" || !/^[A-Za-z0-9_-]{20,80}$/.test(value)) throw Object.assign(new Error("The Computer assignment runtime is invalid."), { code: "runtime_key_invalid" });
+  return value;
+}
+
+export class ComputerRuntime {
+  constructor({ home, browserFactory = (options) => new BrowserController(options) }) {
+    this.home = home;
+    this.browserFactory = browserFactory;
+    this.runtimes = new Map();
+  }
+
+  async runtime(key) {
+    const safeKey = safeRuntimeKey(key);
+    if (this.runtimes.has(safeKey)) return this.runtimes.get(safeKey);
+    const root = join(this.home, "agents", safeKey);
+    const workRoot = join(root, "work");
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const work = new WorkFolder(workRoot);
+    await work.start();
+    const browser = this.browserFactory({ home: root, workRoot });
+    const runtime = { root, work, browser };
+    this.runtimes.set(safeKey, runtime);
+    return runtime;
+  }
+
+  async start() {
+    const runtime = await this.runtime("workspace");
+    await runtime.browser.start();
+  }
+
+  async execute(command, { signal, timeoutMs }) {
+    const runtime = await this.runtime(command.runtime?.key ?? "workspace");
+    if (command.action === "browser.upload") {
+      const resolved = await runtime.work.resolvePath(command.payload.path);
+      return runtime.browser.execute(command.action, { ref: command.payload.ref, filePath: resolved.target }, { signal, timeoutMs });
+    }
+    if (command.action.startsWith("browser.")) return runtime.browser.execute(command.action, command.payload, { signal, timeoutMs });
+    if (command.action === "file.list") return runtime.work.list(command.payload.path);
+    if (command.action === "file.read") return runtime.work.read(command.payload.path);
+    if (command.action === "file.write") return runtime.work.write(command.payload.path, command.payload.content);
+    if (command.action === "file.mkdir") return runtime.work.mkdir(command.payload.path);
+    if (command.action === "file.delete") return runtime.work.delete(command.payload.path);
+    if (command.action === "process.run") return runProcess({ ...command.payload, cwd: runtime.work.root, signal });
+    throw Object.assign(new Error("Unsupported Computer command."), { code: "unsupported_action" });
+  }
+
+  async synchronise(assignments) {
+    const active = new Set((assignments ?? []).map((assignment) => safeRuntimeKey(assignment.key)));
+    for (const [key, runtime] of this.runtimes) {
+      if (key === "workspace" || active.has(key)) continue;
+      await runtime.browser.stop().catch(() => undefined);
+      this.runtimes.delete(key);
+      await rm(runtime.root, { recursive: true, force: true, maxRetries: 3 }).catch(() => undefined);
+    }
+  }
+
+  async stop() {
+    await Promise.all([...this.runtimes.values()].map((runtime) => runtime.browser.stop().catch(() => undefined)));
+  }
+}

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/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

@@ -1,8 +1,12 @@
 import { open, readFile, unlink } from "node:fs/promises";
-import { BrowserController } from "./browser-controller.mjs";
+import { ComputerRuntime } from "./computer-runtime.mjs";
 import { clearState, CONNECT_HOME, LOCK_FILE, PAUSE_FILE, STOP_FILE, writeStatus } from "./state.mjs";
 
-export const CAPABILITIES = ["browser.navigate", "browser.read", "browser.screenshot"];
+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;
@@ -89,6 +93,7 @@ export class DeviceApi {
       state,
       browserReady,
       capabilities: CAPABILITIES,
+      protocolVersion: PROTOCOL_VERSION,
       ...(current ? { currentCommandId: current.id, currentAction: current.action } : {}),
       detailCode: current ? "command_running" : state,
     });
@@ -111,12 +116,16 @@ export async function runWorker(state, options = {}) {
   await unlink(STOP_FILE).catch(() => undefined);
   const releaseLock = await acquireLock();
   const api = options.api || new DeviceApi(state);
-  const browser = options.browser || new BrowserController({ home: CONNECT_HOME });
+  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 browser.stop().catch(() => undefined); };
+  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 });
@@ -131,7 +140,7 @@ export async function runWorker(state, options = {}) {
         active?.controller.abort();
         if (!pauseHandled) {
           pauseHandled = true;
-          await browser.stop().catch(() => undefined);
+          await runtime.stop().catch(() => undefined);
           await writeStatus({ state: isPaused ? "paused" : "offline", currentCommandId: null, currentAction: null }).catch(() => undefined);
         }
       } else {
@@ -142,7 +151,8 @@ export async function runWorker(state, options = {}) {
 
   async function report(workerState, browserReady, current) {
     await writeStatus({ state: workerState, currentCommandId: current?.id ?? null, currentAction: current?.action ?? null });
-    await api.heartbeat(workerState, browserReady, current);
+    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;
   }
 
@@ -153,7 +163,7 @@ export async function runWorker(state, options = {}) {
       if (await shutdownRequested()) { stopped = true; break; }
       if (await paused()) {
         active?.controller.abort();
-        await browser.stop();
+        await runtime.stop();
         const reportBudget = pauseDeadline ? Math.max(0, pauseDeadline - Date.now()) : 5_000;
         await settleWithin(report("paused", false), reportBudget);
         pauseDeadline = 0;
@@ -166,7 +176,7 @@ export async function runWorker(state, options = {}) {
         await api.heartbeat("browser_starting", false).catch(() => undefined);
       }
       try {
-        await browser.start();
+        await runtime.start();
         if (stopped) break;
         if (await paused()) continue;
         if (Date.now() >= nextHeartbeat) await report("available", true);
@@ -190,16 +200,16 @@ export async function runWorker(state, options = {}) {
           let result;
           let completionError;
           try {
-            result = await browser.execute(command.action, command.payload, { signal: controller.signal, timeoutMs: deadlineMs });
+            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 browser action 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 browser.stop().catch(() => undefined);
+            await runtime.stop().catch(() => undefined);
             await writeStatus({ state: "paused", currentCommandId: null, currentAction: null }).catch(() => undefined);
           }
           const commandDeadline = new Date(command.deadlineAt).getTime();
@@ -219,7 +229,7 @@ export async function runWorker(state, options = {}) {
         if (error.status === 401) throw error;
         if (stopped) break;
         if (await paused()) continue;
-        await browser.stop().catch(() => undefined);
+        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)}`);
@@ -229,7 +239,7 @@ export async function runWorker(state, options = {}) {
   } finally {
     clearInterval(localWatch);
     active?.controller.abort();
-    await browser.stop().catch(() => undefined);
+    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);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xevy/heny-connect",
-  "version": "0.3.0",
-  "description": "Run Heny's isolated, permission-bounded desktop browser worker.",
+  "version": "0.4.0",
+  "description": "Run Heny's isolated, permission-bounded Windows Computer worker.",
   "type": "module",
   "bin": {
     "heny-connect": "bin/heny-connect.mjs"