@xevy/heny-connect 0.2.0 → 0.4.0

package/lib/browser-controller.mjs

@@ -0,0 +1,377 @@
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, stat } from "node:fs/promises";
+import net from "node:net";
+import { platform } from "node:os";
+import { join } from "node:path";
+import { CdpSession } from "./cdp.mjs";
+import { parsePublicUrl, resolvePublicUrl } from "./network-policy.mjs";
+import { createValidatingProxy } from "./validating-proxy.mjs";
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const DENIED_PERMISSIONS = ["geolocation", "notifications", "midi", "midiSysex", "camera", "microphone", "backgroundSync", "sensors", "clipboardReadWrite", "clipboardSanitizedWrite", "paymentHandler", "idleDetection", "localFonts", "windowManagement"];
+
+async function randomPort() {
+  const server = net.createServer();
+  await new Promise((resolve, reject) => { server.once("error", reject); server.listen(0, "127.0.0.1", resolve); });
+  const port = server.address().port;
+  await new Promise((resolve) => server.close(resolve));
+  return port;
+}
+
+function browserCandidates() {
+  const local = process.env.LOCALAPPDATA;
+  const programs = process.env.PROGRAMFILES;
+  const programs86 = process.env["PROGRAMFILES(X86)"];
+  return [
+    process.env.HENY_BROWSER_PATH,
+    local && join(local, "Microsoft", "Edge", "Application", "msedge.exe"),
+    programs && join(programs, "Microsoft", "Edge", "Application", "msedge.exe"),
+    programs86 && join(programs86, "Microsoft", "Edge", "Application", "msedge.exe"),
+    local && join(local, "Google", "Chrome", "Application", "chrome.exe"),
+    programs && join(programs, "Google", "Chrome", "Application", "chrome.exe"),
+    programs86 && join(programs86, "Google", "Chrome", "Application", "chrome.exe"),
+  ].filter(Boolean);
+}
+
+function findBrowser() {
+  const browser = browserCandidates().find((candidate) => existsSync(candidate));
+  if (!browser) throw Object.assign(new Error("Install Microsoft Edge or Google Chrome."), { code: "browser_missing" });
+  return browser;
+}
+
+export class BrowserController {
+  constructor({ home, workRoot = join(home, "work"), browserPath = findBrowser(), lookup } = {}) {
+    this.home = home;
+    this.workRoot = workRoot;
+    this.browserPath = browserPath;
+    this.lookup = lookup;
+    this.process = null;
+    this.proxy = null;
+    this.session = null;
+    this.targetId = null;
+    this.mainFrameId = null;
+    this.generation = 0;
+    this.references = new Map();
+  }
+
+  async start() {
+    if (this.session) return;
+    const profile = join(this.home, "browser-profile");
+    await mkdir(profile, { recursive: true });
+    this.proxy = await createValidatingProxy({ lookup: this.lookup });
+    const port = await randomPort();
+    const args = [
+      `--remote-debugging-address=127.0.0.1`,
+      `--remote-debugging-port=${port}`,
+      `--user-data-dir=${profile}`,
+      `--proxy-server=http://127.0.0.1:${this.proxy.port}`,
+      "--proxy-bypass-list=<-loopback>",
+      "--host-resolver-rules=MAP * ~NOTFOUND, EXCLUDE 127.0.0.1",
+      "--disable-quic",
+      "--force-webrtc-ip-handling-policy=disable_non_proxied_udp",
+      "--no-first-run",
+      "--no-default-browser-check",
+      "--disable-sync",
+      "--disable-background-networking",
+      "--disable-component-update",
+      "--disable-features=ExternalProtocolDialog",
+      "--disable-notifications",
+      "--disable-extensions",
+      "--disable-session-crashed-bubble",
+      "--no-service-autorun",
+      "--new-window",
+      "about:blank",
+    ];
+    this.process = spawn(this.browserPath, args, { stdio: "ignore", windowsHide: false });
+    const browserProcess = this.process;
+    this.process.once("exit", () => {
+      if (this.process === browserProcess) this.process = null;
+      if (this.session) { const session = this.session; this.session = null; session.close(); }
+      if (this.proxy) { const proxy = this.proxy; this.proxy = null; void proxy.close().catch(() => undefined); }
+    });
+    let version;
+    for (let attempt = 0; attempt < 60; attempt += 1) {
+      try {
+        const response = await fetch(`http://127.0.0.1:${port}/json/version`, { signal: AbortSignal.timeout(500) });
+        if (response.ok) { version = await response.json(); break; }
+      } catch {}
+      await sleep(250);
+    }
+    if (!version) { await this.stop(); throw Object.assign(new Error("The dedicated browser did not start."), { code: "browser_start_failed" }); }
+    let targets = await (await fetch(`http://127.0.0.1:${port}/json/list`)).json();
+    let target = targets.find((entry) => entry.type === "page");
+    if (!target) target = await (await fetch(`http://127.0.0.1:${port}/json/new?about%3Ablank`, { method: "PUT" })).json();
+    this.targetId = target.id;
+    this.session = await CdpSession.open(target.webSocketDebuggerUrl);
+    const connectedSession = this.session;
+    this.session.onClose(() => {
+      if (this.session !== connectedSession) return;
+      this.session = null;
+      this.targetId = null;
+      this.mainFrameId = null;
+      void this.stop();
+    });
+    await Promise.all([
+      this.session.send("Page.enable"),
+      this.session.send("Runtime.enable"),
+      this.session.send("Fetch.enable", { patterns: [{ urlPattern: "*", requestStage: "Request" }] }),
+      this.session.send("Target.setDiscoverTargets", { discover: true }),
+      this.session.send("Browser.setDownloadBehavior", { behavior: "deny" }).catch(() => undefined),
+      this.session.send("Browser.resetPermissions").catch(() => undefined),
+      this.session.send("Page.setInterceptFileChooserDialog", { enabled: true }).catch(() => undefined),
+      ...DENIED_PERMISSIONS.map((name) => this.session.send("Browser.setPermission", { permission: { name }, setting: "denied" }).catch(() => undefined)),
+    ]);
+    const frameTree = await this.session.send("Page.getFrameTree");
+    this.mainFrameId = frameTree.frameTree.frame.id;
+    this.session.on("Fetch.requestPaused", async ({ requestId, request }) => {
+      try {
+        await resolvePublicUrl(request.url, this.lookup);
+        await this.session?.send("Fetch.continueRequest", { requestId });
+      } catch {
+        await this.session?.send("Fetch.failRequest", { requestId, errorReason: "BlockedByClient" }).catch(() => undefined);
+      }
+    });
+    this.session.on("Page.javascriptDialogOpening", () => this.session?.send("Page.handleJavaScriptDialog", { accept: false }).catch(() => undefined));
+    this.session.on("Page.fileChooserOpened", () => undefined);
+    this.session.on("Page.frameRequestedNavigation", ({ frameId, url }) => {
+      let protocol = "";
+      try { protocol = new URL(url).protocol; } catch {}
+      const external = !["http:", "https:", "about:", "data:", "blob:"].includes(protocol);
+      const blockedMainFrame = frameId === this.mainFrameId && !["http:", "https:"].includes(protocol);
+      if (external || blockedMainFrame) {
+        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);
+    });
+  }
+
+  async execute(action, payload, { signal, timeoutMs }) {
+    if (signal?.aborted) throw Object.assign(new Error("Command cancelled."), { code: "command_cancelled" });
+    await this.start();
+    if (signal?.aborted) throw Object.assign(new Error("Command cancelled."), { code: "command_cancelled" });
+    const onAbort = () => { void this.session?.send("Page.stopLoading").catch(() => undefined); };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+      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 {
+      signal?.removeEventListener("abort", onAbort);
+    }
+  }
+
+  async pageIdentity() {
+    const result = await this.session.send("Runtime.evaluate", {
+      expression: "({title:String(document.title||'').slice(0,1000),url:String(location.href)})",
+      returnByValue: true,
+    });
+    return result.result.value;
+  }
+
+  async navigate(value, timeoutMs, signal) {
+    const url = parsePublicUrl(value);
+    await resolvePublicUrl(url.href, this.lookup);
+    const navigationAbort = new AbortController();
+    const abortNavigation = () => navigationAbort.abort();
+    signal?.addEventListener("abort", abortNavigation, { once: true });
+    const loaded = this.session.waitFor("Page.loadEventFired", timeoutMs, navigationAbort.signal).then(
+      () => ({ error: null }),
+      (error) => ({ error }),
+    );
+    try {
+      const result = await this.session.send("Page.navigate", { url: url.href }, timeoutMs);
+      if (result.errorText) throw Object.assign(new Error("Navigation failed."), { code: "navigation_failed" });
+      const loadOutcome = await loaded;
+      if (loadOutcome.error) throw loadOutcome.error;
+      const identity = await this.pageIdentity();
+      parsePublicUrl(identity.url);
+      return identity;
+    } catch (error) {
+      navigationAbort.abort();
+      await loaded;
+      throw error;
+    } finally {
+      signal?.removeEventListener("abort", abortNavigation);
+    }
+  }
+
+  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}})()`,
+      returnByValue: true,
+    });
+    parsePublicUrl(result.result.value.url);
+    return result.result.value;
+  }
+
+  async screenshot() {
+    const identity = await this.pageIdentity();
+    parsePublicUrl(identity.url);
+    const metrics = await this.session.send("Page.getLayoutMetrics");
+    const viewport = metrics.cssVisualViewport || metrics.visualViewport;
+    const result = await this.session.send("Page.captureScreenshot", { format: "png", fromSurface: true, captureBeyondViewport: false });
+    if (Buffer.byteLength(result.data, "base64") > 2 * 1024 * 1024) throw Object.assign(new Error("Screenshot is too large."), { code: "screenshot_too_large" });
+    return { ...identity, mimeType: "image/png", dataBase64: result.data, width: Math.round(viewport.clientWidth), height: Math.round(viewport.clientHeight) };
+  }
+
+  async stop() {
+    const session = this.session;
+    this.session = null;
+    this.mainFrameId = null;
+    await this.clearReferences();
+    const browserProcess = this.process;
+    this.process = null;
+    if (browserProcess) {
+      const exited = browserProcess.exitCode !== null;
+      const exit = exited ? Promise.resolve(true) : new Promise((resolve) => browserProcess.once("exit", () => resolve(true)));
+      if (session) await session.send("Browser.close", {}, 2_000).catch(() => undefined);
+      const closed = exited || await Promise.race([exit, sleep(3_000).then(() => false)]);
+      if (!closed) {
+        if (platform() === "win32" && browserProcess.pid) spawnSync("taskkill.exe", ["/PID", String(browserProcess.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+        else browserProcess.kill();
+      }
+    }
+    session?.close();
+    if (this.proxy) {
+      await this.proxy.close().catch(() => undefined);
+      this.proxy = null;
+    }
+  }
+}

package/lib/cdp.mjs

@@ -0,0 +1,95 @@
+export class CdpSession {
+  constructor(socket) {
+    this.socket = socket;
+    this.id = 0;
+    this.pending = new Map();
+    this.listeners = new Map();
+    this.closeListeners = new Set();
+    this.closed = false;
+    socket.onmessage = (event) => this.onMessage(JSON.parse(typeof event.data === "string" ? event.data : event.data.toString()));
+    socket.onerror = () => this.onClosed();
+    socket.onclose = () => this.onClosed();
+  }
+
+  onClosed() {
+    if (this.closed) return;
+    this.closed = true;
+    const error = Object.assign(new Error("Dedicated browser closed."), { code: "browser_closed" });
+    for (const pending of this.pending.values()) pending.reject(error);
+    this.pending.clear();
+    for (const listener of this.closeListeners) void listener(error);
+    this.closeListeners.clear();
+  }
+
+  static async open(url) {
+    if (typeof WebSocket !== "function") throw Object.assign(new Error("Heny Connect requires Node 22 or newer."), { code: "node_unsupported" });
+    const socket = new WebSocket(url);
+    await new Promise((resolve, reject) => {
+      socket.onopen = resolve;
+      socket.onerror = () => reject(Object.assign(new Error("Dedicated browser connection failed."), { code: "browser_connection_failed" }));
+    });
+    return new CdpSession(socket);
+  }
+
+  onMessage(message) {
+    if (message.id && this.pending.has(message.id)) {
+      const pending = this.pending.get(message.id);
+      this.pending.delete(message.id);
+      if (message.error) pending.reject(Object.assign(new Error(message.error.message), { code: "browser_protocol_error" }));
+      else pending.resolve(message.result);
+      return;
+    }
+    if (message.method) {
+      for (const listener of this.listeners.get(message.method) || []) void listener(message.params || {});
+    }
+  }
+
+  on(method, listener) {
+    const entries = this.listeners.get(method) || [];
+    entries.push(listener);
+    this.listeners.set(method, entries);
+    return () => this.listeners.set(method, entries.filter((entry) => entry !== listener));
+  }
+
+  onClose(listener) {
+    if (this.closed) { void listener(Object.assign(new Error("Dedicated browser closed."), { code: "browser_closed" })); return () => undefined; }
+    this.closeListeners.add(listener);
+    return () => this.closeListeners.delete(listener);
+  }
+
+  send(method, params = {}, timeoutMs = 20_000) {
+    if (this.closed) return Promise.reject(Object.assign(new Error("Dedicated browser closed."), { code: "browser_closed" }));
+    const id = ++this.id;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(Object.assign(new Error("Dedicated browser timed out."), { code: "browser_timeout" }));
+      }, timeoutMs);
+      this.pending.set(id, {
+        resolve: (value) => { clearTimeout(timer); resolve(value); },
+        reject: (error) => { clearTimeout(timer); reject(error); },
+      });
+      try { this.socket.send(JSON.stringify({ id, method, params })); } catch { this.onClosed(); }
+    });
+  }
+
+  waitFor(method, timeoutMs, signal) {
+    return new Promise((resolve, reject) => {
+      const done = (error, value) => {
+        clearTimeout(timer);
+        remove();
+        signal?.removeEventListener("abort", aborted);
+        error ? reject(error) : resolve(value);
+      };
+      const remove = this.on(method, (params) => done(null, params));
+      const timer = setTimeout(() => done(Object.assign(new Error("Dedicated browser timed out."), { code: "browser_timeout" })), timeoutMs);
+      const aborted = () => done(Object.assign(new Error("Command cancelled."), { code: "command_cancelled" }));
+      if (signal?.aborted) queueMicrotask(aborted);
+      else signal?.addEventListener("abort", aborted, { once: true });
+    });
+  }
+
+  close() {
+    try { this.socket.close(); } finally { this.onClosed(); }
+  }
+}

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/network-policy.mjs

@@ -0,0 +1,102 @@
+import { lookup as dnsLookup } from "node:dns/promises";
+import { isIP } from "node:net";
+
+function ipv4Number(address) {
+  const parts = address.split(".").map(Number);
+  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return null;
+  return parts.reduce((value, part) => (value * 256) + part, 0) >>> 0;
+}
+
+function ipv4In(address, base, bits) {
+  const value = ipv4Number(address);
+  const start = ipv4Number(base);
+  if (value === null || start === null) return false;
+  if (bits === 0) return true;
+  const mask = (0xffffffff << (32 - bits)) >>> 0;
+  return (value & mask) === (start & mask);
+}
+
+function expandIpv6(address) {
+  let value = address.toLowerCase().split("%")[0];
+  if (value.includes(".")) {
+    const lastColon = value.lastIndexOf(":");
+    const v4 = ipv4Number(value.slice(lastColon + 1));
+    if (v4 === null) return null;
+    value = `${value.slice(0, lastColon)}:${((v4 >>> 16) & 0xffff).toString(16)}:${(v4 & 0xffff).toString(16)}`;
+  }
+  const halves = value.split("::");
+  if (halves.length > 2) return null;
+  const left = halves[0] ? halves[0].split(":") : [];
+  const right = halves[1] ? halves[1].split(":") : [];
+  const fill = 8 - left.length - right.length;
+  if (fill < 0 || (halves.length === 1 && fill !== 0)) return null;
+  const words = [...left, ...Array(fill).fill("0"), ...right];
+  if (words.length !== 8 || words.some((word) => !/^[0-9a-f]{1,4}$/.test(word))) return null;
+  return words.reduce((result, word) => (result << 16n) | BigInt(parseInt(word, 16)), 0n);
+}
+
+function ipv6In(address, base, bits) {
+  const value = expandIpv6(address);
+  const start = expandIpv6(base);
+  if (value === null || start === null) return false;
+  if (bits === 0) return true;
+  const shift = 128n - BigInt(bits);
+  return (value >> shift) === (start >> shift);
+}
+
+export function isBlockedAddress(address) {
+  const version = isIP(address);
+  if (version === 4) {
+    return [
+      ["0.0.0.0", 8], ["10.0.0.0", 8], ["100.64.0.0", 10], ["127.0.0.0", 8],
+      ["169.254.0.0", 16], ["172.16.0.0", 12], ["192.0.0.0", 24], ["192.0.2.0", 24],
+      ["192.168.0.0", 16], ["198.18.0.0", 15], ["198.51.100.0", 24], ["203.0.113.0", 24],
+      ["224.0.0.0", 4], ["240.0.0.0", 4],
+    ].some(([base, bits]) => ipv4In(address, base, bits));
+  }
+  if (version === 6) {
+    const mapped = address.toLowerCase().match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    if (mapped) return isBlockedAddress(mapped[1]);
+    if (ipv6In(address, "::ffff:0:0", 96)) {
+      const value = expandIpv6(address);
+      const low = Number(value & 0xffffffffn) >>> 0;
+      return isBlockedAddress(`${low >>> 24}.${(low >>> 16) & 255}.${(low >>> 8) & 255}.${low & 255}`);
+    }
+    return [
+      ["::", 96], ["::1", 128], ["64:ff9b::", 96], ["64:ff9b:1::", 48], ["100::", 64],
+      ["2001::", 32], ["2001:db8::", 32], ["2002::", 16], ["3fff::", 20], ["5f00::", 16],
+      ["fc00::", 7], ["fec0::", 10], ["fe80::", 10], ["ff00::", 8],
+    ].some(([base, bits]) => ipv6In(address, base, bits));
+  }
+  return true;
+}
+
+export function parsePublicUrl(value) {
+  let url;
+  try { url = new URL(value); } catch { throw Object.assign(new Error("Destination URL is invalid."), { code: "destination_invalid" }); }
+  if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) {
+    throw Object.assign(new Error("Destination must use HTTP(S) without credentials."), { code: "destination_blocked" });
+  }
+  const port = Number(url.port || (url.protocol === "https:" ? 443 : 80));
+  if (![80, 443].includes(port)) throw Object.assign(new Error("Destination port is blocked."), { code: "destination_blocked" });
+  return url;
+}
+
+export async function resolvePublicHost(hostname, lookup = dnsLookup) {
+  const host = hostname.replace(/^\[|\]$/g, "").toLowerCase();
+  if (!host || host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local") || host === "metadata.google.internal") {
+    throw Object.assign(new Error("Destination is blocked."), { code: "destination_blocked" });
+  }
+  const literal = isIP(host);
+  const answers = literal ? [{ address: host, family: literal }] : await lookup(host, { all: true, verbatim: true });
+  if (!answers.length || answers.some(({ address }) => isBlockedAddress(address))) {
+    throw Object.assign(new Error("Destination is blocked."), { code: "destination_blocked" });
+  }
+  return answers[0];
+}
+
+export async function resolvePublicUrl(value, lookup = dnsLookup) {
+  const url = parsePublicUrl(value);
+  const answer = await resolvePublicHost(url.hostname, lookup);
+  return { url, ...answer };
+}