@xevy/heny-connect 0.2.0 → 0.4.0

package/README.md

@@ -1,60 +1,74 @@
 # @xevy/heny-connect
 
-Heny Connect pairs a computer with a Heny workspace and keeps the device's availability current.
+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.
 
-## Requirements
+Assigned capabilities cover:
 
-- Node.js 20 or newer
-- A six-digit pairing code from the Heny **Desktop** page
+- 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
 
-## Pair a computer
+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.
 
-```bash
-npx @xevy/heny-connect pair --code 123456 --server https://heny.vyte.dev --run
-```
+## Requirements
+
+- Windows 10 or 11
+- Microsoft Edge or Google Chrome
+- Node.js 22 or newer
+- A six-digit code from Heny **Computers**
 
-The pairing code works once and expires after 15 minutes. Pairing state is stored in `.heny-connect.json` in the current user's home directory.
+## Install and pair
 
-## Run an existing pairing
+Open PowerShell once:
 
-```bash
-npx @xevy/heny-connect run
+```powershell
+npm.cmd install -g @xevy/heny-connect@latest
+heny-connect.cmd pair --code 123456 --server https://heny.vyte.dev
+heny-connect.cmd install
 ```
 
-The process sends a heartbeat every 30 seconds. Keep it running for the device to remain available in Heny.
+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.
 
-## Windows system tray
+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.
 
-Install the tray companion after pairing:
+## System tray
 
-```powershell
-heny-connect install
-```
+The tray reports:
 
-Heny Connect starts at Windows sign-in and runs without an open terminal. The tray menu shows the connection state and provides these controls:
+- Browser starting
+- Available
+- Working, including the current action
+- Paused
+- Error
+- Offline
 
-- Open Heny
-- Pause or resume the connection
-- Reconnect now
-- Turn start-at-sign-in on or off
-- Quit until the next sign-in
+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.
 
-To start the tray for the current session without installing start-at-sign-in:
+## Agent runtimes
 
-```powershell
-heny-connect tray
-```
+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 land in the assignment work folder. Popups, external protocols, and browser permission grants are blocked.
 
-To remove start-at-sign-in:
+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
 
 ```powershell
-heny-connect uninstall
+heny-connect.cmd status
+heny-connect.cmd pause
+heny-connect.cmd resume
+heny-connect.cmd tray
+heny-connect.cmd install
+heny-connect.cmd uninstall
 ```
 
-## Check status
+`status` shows server registration plus content-free local worker status. Device tokens, browsing content, URLs, page titles, screenshots, and browser debugger details stay out of console output.
+
+## Remove start-at-sign-in
 
-```bash
-npx @xevy/heny-connect status
+```powershell
+heny-connect.cmd uninstall
 ```
 
-Heny Connect currently provides device registration and availability reporting. Browser and shell execution are planned capabilities.
+Use **Quit** from the tray to end the current worker session.

package/bin/heny-connect.mjs

@@ -1,21 +1,16 @@
 #!/usr/bin/env node
 /**
- * Heny Connect — pairs this computer with a Heny workspace and keeps it
- * reporting in. Node 20+; no dependencies.
- *
- *   npx @xevy/heny-connect pair --code 123456 --server https://heny.example
- *   npx @xevy/heny-connect run
- *   npx @xevy/heny-connect status
- *
- * Pairing state is stored in ~/.heny-connect.json (mode 600).
+ * Heny Connect — pairs a Windows computer, owns a dedicated browser profile,
+ * and runs bounded browser commands without an open terminal.
  */
 import { spawn, spawnSync } from "node:child_process";
-import { chmod, readFile, writeFile } from "node:fs/promises";
-import { homedir, hostname, platform, release } from "node:os";
+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, PROTOCOL_VERSION, DeviceApi, runWorker } from "../lib/worker.mjs";
+import { CONNECT_HOME, PAUSE_FILE, STATUS_FILE, loadState, protectConnectHome, saveState, writeStatus } from "../lib/state.mjs";
 
-const STATE_FILE = join(process.env.HENY_CONNECT_HOME || homedir(), ".heny-connect.json");
 const CLI_FILE = fileURLToPath(import.meta.url);
 const TRAY_SCRIPT = join(dirname(CLI_FILE), "..", "windows", "heny-connect-tray.ps1");
 const args = process.argv.slice(2);
@@ -29,63 +24,73 @@ function systemLabel() {
   return `${os} ${release()}`;
 }
 
-async function loadState() { try { return JSON.parse(await readFile(STATE_FILE, "utf8")); } catch { return null; } }
-async function saveState(state) { await writeFile(STATE_FILE, JSON.stringify(state, null, 2)); await chmod(STATE_FILE, 0o600).catch(() => undefined); }
-
 async function call(server, path, body, token) {
-  const res = await fetch(new URL(path, server), { method: "POST", headers: { "Content-Type": "application/json", ...(token ? { Authorization: `Bearer ${token}` } : {}) }, body: JSON.stringify(body), signal: AbortSignal.timeout(20_000) });
-  const text = await res.text();
-  let parsed; try { parsed = JSON.parse(text); } catch { parsed = { raw: text }; }
-  if (!res.ok) throw new Error(parsed?.error?.message || `HTTP ${res.status}`);
+  const response = await fetch(new URL(path, server), {
+    method: "POST",
+    headers: { "content-type": "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}) },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(20_000),
+  });
+  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}`), { status: response.status, code: parsed?.error?.code || "server_error" });
   return parsed;
 }
 
 async function pair() {
-  const code = opt("code"); const server = opt("server", process.env.HENY_SERVER);
+  const code = opt("code");
+  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; }
-  const result = await call(server, "/api/devices/pair", { code, system: systemLabel(), hostname: hostname(), capabilities: ["browser", "shell"] });
+  await protectConnectHome();
+  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}.`);
-  if (!args.includes("--once") && args.includes("--run")) await run();
-}
-
-async function heartbeat(state, detail) {
-  return call(state.server, "/api/devices/heartbeat", { state: detail.state, detail: detail.message }, state.token);
-}
-
-async function sendHeartbeat(stateName = "available", message = `${hostname()}: browser ready`) {
-  const state = await loadState();
-  if (!state) { console.error("Not paired. Run: heny-connect pair --code … --server …"); process.exitCode = 2; return false; }
-  if (!["online", "available", "offline"].includes(stateName)) { console.error("State must be online, available, or offline."); process.exitCode = 2; return false; }
-  await heartbeat(state, { state: stateName, message });
-  return true;
+  if (args.includes("--run")) await run();
 }
 
 async function run() {
   const state = await loadState();
-  if (!state) { console.error("Not paired. Run: heny-connect pair --code … --server …"); process.exitCode = 2; return; }
-  const every = Number(opt("every", 30)) * 1000;
-  const beats = Number(opt("beats", 0)); let count = 0;
-  const tick = async () => {
-    try { await heartbeat(state, { state: "available", message: `${hostname()}: browser ready` }); count += 1; console.log(`${new Date().toISOString()} heartbeat ok (${count})`); }
-    catch (err) { console.error(`${new Date().toISOString()} heartbeat failed: ${err.message}`); if (/Unknown device token/.test(err.message)) process.exit(3); }
-    if (beats && count >= beats) process.exit(0);
-  };
-  await tick();
-  if (!beats || count < beats) setInterval(tick, every);
+  if (!state) { console.error("This computer needs pairing. Open Heny Desktop to get a code."); process.exitCode = 2; return; }
+  try {
+    await runWorker(state);
+  } catch (error) {
+    const detailCode = error?.status === 401 ? "re_pair_required" : (/^[a-z0-9_]{1,40}$/.test(error?.code || "") ? error.code : "worker_error");
+    await writeStatus({ state: "error", detailCode, currentCommandId: null, currentAction: null }).catch(() => undefined);
+    console.error(error?.code === "device_revoked" ? "Registration was revoked. Pair this computer again." : error.message);
+    process.exitCode = error?.status === 401 ? 3 : 1;
+  }
 }
 
 async function heartbeatOnce() {
+  const state = await loadState();
+  if (!state) { console.error("This computer needs pairing. Open Heny Desktop to get a code."); process.exitCode = 2; return; }
   const stateName = opt("state", "available");
-  const message = opt("detail", stateName === "offline" ? `${hostname()}: paused locally` : `${hostname()}: browser ready`);
-  if (await sendHeartbeat(stateName, message)) console.log(`Heartbeat reported ${stateName}.`);
+  if (!["available", "paused", "offline", "browser_starting", "error"].includes(stateName)) { console.error("Choose a valid worker state."); process.exitCode = 2; return; }
+  const browserReady = stateName === "available";
+  await new DeviceApi(state).heartbeat(stateName, browserReady);
+  console.log(`Heartbeat reported ${stateName}.`);
 }
 
 async function status() {
   const state = await loadState();
   if (!state) { console.log("Not paired."); return; }
-  const res = await fetch(new URL("/api/devices/me", state.server), { headers: { Authorization: `Bearer ${state.token}` }, signal: AbortSignal.timeout(20_000) });
-  console.log(res.ok ? JSON.stringify(await res.json(), null, 2) : `Server answered HTTP ${res.status}`);
+  const response = await fetch(new URL("/api/devices/me", state.server), { headers: { authorization: `Bearer ${state.token}` }, signal: AbortSignal.timeout(20_000) });
+  let local = null;
+  try { local = JSON.parse(await readFile(STATUS_FILE, "utf8")); } catch {}
+  if (!response.ok) { console.log(`Server answered HTTP ${response.status}`); return; }
+  console.log(JSON.stringify({ ...(await response.json()), local }, null, 2));
+}
+
+async function pause() {
+  await protectConnectHome();
+  await writeFile(PAUSE_FILE, "paused\n", { mode: 0o600 });
+  console.log("Heny Connect is pausing.");
+}
+
+async function resume() {
+  await unlink(PAUSE_FILE).catch(() => undefined);
+  console.log("Heny Connect is resuming.");
 }
 
 function requireWindows() {
@@ -96,7 +101,7 @@ function requireWindows() {
 }
 
 function trayArgs(mode) {
-  const values = ["-NoLogo", "-NoProfile", "-STA", "-ExecutionPolicy", "Bypass", "-WindowStyle", "Hidden", "-File", TRAY_SCRIPT, "-NodePath", process.execPath, "-CliPath", CLI_FILE];
+  const values = ["-NoLogo", "-NoProfile", "-STA", "-ExecutionPolicy", "Bypass", "-WindowStyle", "Hidden", "-File", TRAY_SCRIPT, "-NodePath", process.execPath, "-CliPath", CLI_FILE, "-HomePath", CONNECT_HOME];
   if (mode === "install") values.push("-Install");
   if (mode === "uninstall") values.push("-Uninstall");
   return values;
@@ -104,7 +109,7 @@ function trayArgs(mode) {
 
 async function tray() {
   if (!requireWindows()) return;
-  if (!await loadState()) { console.error("Not paired. Pair this computer before starting the tray."); process.exitCode = 2; return; }
+  if (!await loadState()) { console.error("Pair this computer before starting the tray."); process.exitCode = 2; return; }
   const child = spawn("powershell.exe", trayArgs("tray"), { detached: true, stdio: "ignore", windowsHide: true });
   child.unref();
   console.log("Heny Connect is running in the system tray.");
@@ -112,7 +117,8 @@ async function tray() {
 
 async function install() {
   if (!requireWindows()) return;
-  if (!await loadState()) { console.error("Not paired. Pair this computer before installing the tray."); process.exitCode = 2; return; }
+  if (!await loadState()) { console.error("Pair this computer before installing the tray."); process.exitCode = 2; return; }
+  if (CLI_FILE.includes("\\_npx\\")) { console.error("Install the package globally before enabling start at sign-in: npm.cmd install -g @xevy/heny-connect"); process.exitCode = 2; return; }
   const result = spawnSync("powershell.exe", trayArgs("install"), { encoding: "utf8", windowsHide: true });
   if (result.stdout) process.stdout.write(result.stdout);
   if (result.status !== 0) { if (result.stderr) process.stderr.write(result.stderr); process.exitCode = result.status || 1; }
@@ -125,10 +131,11 @@ async function uninstall() {
   if (result.status !== 0) { if (result.stderr) process.stderr.write(result.stderr); process.exitCode = result.status || 1; }
 }
 
-const commands = { pair, run, status, heartbeat: heartbeatOnce, tray, install, uninstall, help: async () => console.log("Commands: pair --code <6 digits> --server <url> [--run] | run [--every 30] [--beats N] | status | tray | install | uninstall") };
+const help = async () => console.log("Commands: pair --code <6 digits> --server <url> [--run] | run | status | pause | resume | heartbeat --state <state> | tray | install | uninstall");
+const commands = { pair, run, status, pause, resume, heartbeat: heartbeatOnce, tray, install, uninstall, help };
 try {
-  await (commands[command] || commands.help)();
-} catch (err) {
-  console.error(err.message);
+  await (commands[command] || help)();
+} catch (error) {
+  console.error(error.message);
   process.exitCode = 1;
 }