@q-agent/agent 0.1.0 → 0.1.6

package/README.md

@@ -17,7 +17,18 @@ Chromium is installed automatically: the first time you run `qagent-agent start`
 the agent downloads Playwright's Chromium if it isn't already present (one-time,
 ~100 MB, with visible progress). No manual `npx playwright install` step is needed.
 
-## Install & run
+## Run with the UI (easiest)
+
+```bash
+npx @q-agent/agent
+```
+
+Running with no command opens a local web UI in your browser. Paste a pairing
+code (from the Q-Agent app's **Local Agent** screen) and the server URL, click
+**Connect**, and watch the pull/run progress live. The device token is stored
+locally, so next time it reconnects and starts pulling automatically.
+
+## Command-line
 
 ```bash
 npx @q-agent/agent pair <code> --server https://your-qagent-server.example.com/api
@@ -38,6 +49,46 @@ node dist/src/cli.js pair <code> --server http://127.0.0.1:8787
 node dist/src/cli.js start
 ```
 
+## Windows binary (no Node required)
+
+For machines without Node, build a self-contained Windows bundle:
+
+```bash
+cd agent
+npm install
+npm run package:win
+```
+
+This produces `dist-bin/qagent-agent-win-x64/` — a `qagent-agent.exe` (the CLI as
+a Node Single Executable Application) plus a bundled Node runtime, production
+`node_modules`, and `vendor/`. Zip that folder for distribution; the user unzips
+and runs it with **no global Node installed**:
+
+```bat
+qagent-agent.exe pair <code> --server https://your-qagent-server.example.com/api
+qagent-agent.exe start
+```
+
+Chromium still auto-installs on first `start`. Build the bundle on Windows with a
+Node 20+ that supports SEA (the local `node.exe` is used as the executable base —
+no compiler or download needed).
+
+## Desktop app (Electron)
+
+A native window that wraps the same web UI:
+
+```bash
+cd agent
+npm install
+npm run desktop        # dev: builds, then opens the app window
+npm run dist:desktop   # build a Windows installer (electron-builder → dist-bin/desktop/)
+```
+
+The Electron shell runs the agent's UI server in-process and shows it in a
+window — pair by entering the 6-digit code + server URL, then watch progress.
+Child processes (Playwright / login capture) run via Electron-as-Node
+(`ELECTRON_RUN_AS_NODE`), so no separate Node install is needed.
+
 ## Commands
 
 | Command | Description |

package/dist/src/api.js

@@ -41,10 +41,15 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiError = void 0;
 exports.redeemDevice = redeemDevice;
+exports.disconnectDevice = disconnectDevice;
 exports.claimNextJob = claimNextJob;
+exports.claimNextCapture = claimNextCapture;
+exports.postCaptureComplete = postCaptureComplete;
 exports.postEvent = postEvent;
 exports.postResult = postResult;
 exports.postEvidence = postEvidence;
+exports.postHealFix = postHealFix;
+exports.postHealFinalize = postHealFinalize;
 exports.postComplete = postComplete;
 const fs = __importStar(require("fs"));
 /** Raised for any non-2xx/204 response; carries the HTTP status for callers that care (e.g. 409). */
@@ -76,6 +81,16 @@ async function redeemDevice(serverUrl, code, name) {
     await throwIfNotOk(res);
     return (await res.json());
 }
+/** Self-revoke this device on the server (the "Disconnect" action). Best-effort:
+ * the caller wipes the local token regardless, so a failure here only means the
+ * server list clears on `last_seen_at` staleness instead of immediately. */
+async function disconnectDevice(cfg) {
+    const res = await fetch(`${cfg.serverUrl}/agent/disconnect`, {
+        method: "POST",
+        headers: authHeaders(cfg.deviceToken),
+    });
+    await throwIfNotOk(res);
+}
 /** Long-poll claim the next queued job for this device's owner. `null` on 204 (nothing queued). */
 async function claimNextJob(cfg) {
     const res = await fetch(`${cfg.serverUrl}/agent/jobs/next`, {
@@ -87,6 +102,26 @@ async function claimNextJob(cfg) {
     await throwIfNotOk(res);
     return (await res.json());
 }
+/** Claim the next queued auth-capture for this device's owner. `null` on 204. */
+async function claimNextCapture(cfg) {
+    const res = await fetch(`${cfg.serverUrl}/agent/auth/next`, {
+        method: "POST",
+        headers: authHeaders(cfg.deviceToken),
+    });
+    if (res.status === 204)
+        return null;
+    await throwIfNotOk(res);
+    return (await res.json());
+}
+/** Report a capture's outcome so the server clears "capturing" + stamps the marker. */
+async function postCaptureComplete(cfg, captureId, ok, error) {
+    const res = await fetch(`${cfg.serverUrl}/agent/auth/${captureId}/complete`, {
+        method: "POST",
+        headers: { ...authHeaders(cfg.deviceToken), "Content-Type": "application/json" },
+        body: JSON.stringify({ ok, error }),
+    });
+    await throwIfNotOk(res);
+}
 /** Push one progress event; the server re-emits it on the run's WebSocket unchanged. */
 async function postEvent(cfg, executionId, event, payload) {
     const res = await fetch(`${cfg.serverUrl}/agent/jobs/${executionId}/events`, {
@@ -120,6 +155,25 @@ async function postEvidence(cfg, executionId, ev) {
     });
     await throwIfNotOk(res);
 }
+/** Ask the server to classify + fix one failed heal attempt (Claude + KB live server-side). */
+async function postHealFix(cfg, caseId, body) {
+    const res = await fetch(`${cfg.serverUrl}/agent/heal/${caseId}/fix`, {
+        method: "POST",
+        headers: { ...authHeaders(cfg.deviceToken), "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    await throwIfNotOk(res);
+    return (await res.json());
+}
+/** Persist the heal's final outcome + feed a passing DOM-grounded heal into the KB. */
+async function postHealFinalize(cfg, caseId, body) {
+    const res = await fetch(`${cfg.serverUrl}/agent/heal/${caseId}/finalize`, {
+        method: "POST",
+        headers: { ...authHeaders(cfg.deviceToken), "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    await throwIfNotOk(res);
+}
 /** Finalize an execution with its aggregate counts + captured log tail. */
 async function postComplete(cfg, executionId, body) {
     const res = await fetch(`${cfg.serverUrl}/agent/jobs/${executionId}/complete`, {

package/dist/src/bus.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bus = void 0;
+exports.emit = emit;
+exports.recentEvents = recentEvents;
+/**
+ * In-process event bus bridging the job loop (runner.ts) to the local web UI
+ * (ui.ts). The runner emits structured activity events; the UI streams them to
+ * the browser over SSE. A small ring buffer lets a UI that connects mid-run
+ * replay recent activity.
+ */
+const node_events_1 = require("node:events");
+const BUFFER_MAX = 300;
+const buffer = [];
+exports.bus = new node_events_1.EventEmitter();
+/** Record + broadcast an agent activity event. */
+function emit(type, data = {}) {
+    const event = { ts: Date.now(), type, ...data };
+    buffer.push(event);
+    if (buffer.length > BUFFER_MAX)
+        buffer.shift();
+    exports.bus.emit("event", event);
+}
+/** Snapshot of buffered events, for a UI client that just connected. */
+function recentEvents() {
+    return buffer.slice();
+}

package/dist/src/cli.js

@@ -48,22 +48,28 @@ const os = __importStar(require("os"));
 const config_1 = require("./config");
 const api_1 = require("./api");
 const runner_1 = require("./runner");
+const ui_1 = require("./ui");
+/** How the user invoked this agent, for accurate "run X" hints: the bare command
+ * inside a packaged bundle, else the `npx` form of the published package. */
+function invocation() {
+    return process.pkg ? "qagent-agent" : "npx @q-agent/agent";
+}
 const program = new commander_1.Command();
 program.name("qagent-agent").description("Q-Agent Local Agent — runs Playwright locally for this machine's owner.");
 program
     .command("pair")
     .description("Redeem a one-time pairing code (from the Q-Agent SPA) for a device token")
     .argument("<code>", "pairing code shown in the SPA")
-    .option("--server <url>", "Q-Agent server base URL", "http://127.0.0.1:8787")
+    .option("--server <url>", "Q-Agent server base URL (defaults to the server baked into this build)")
     .option("--name <name>", "device name shown in the paired-devices list", os.hostname())
     .action(async (code, opts) => {
-    const serverUrl = opts.server.replace(/\/+$/, "");
+    const serverUrl = (opts.server || (0, config_1.defaultServerUrl)() || "http://127.0.0.1:8787").replace(/\/+$/, "");
     try {
         const { deviceToken, deviceId } = await (0, api_1.redeemDevice)(serverUrl, code, opts.name);
         const cfg = { serverUrl, deviceToken, deviceId, deviceName: opts.name };
         (0, config_1.saveConfig)(cfg);
         console.log(`Paired as device #${deviceId} (${opts.name}) against ${serverUrl}`);
-        console.log("Device token stored — run `qagent-agent start` to begin claiming jobs.");
+        console.log(`Device token stored — run \`${invocation()} start\` to begin claiming jobs.`);
     }
     catch (err) {
         console.error("Pairing failed:", err.message);
@@ -77,7 +83,7 @@ program
     .action(async (opts) => {
     const cfg = (0, config_1.loadConfig)();
     if (!cfg) {
-        console.error("Not paired yet — run `qagent-agent pair <code>` first.");
+        console.error(`Not paired yet — run \`${invocation()} pair <code>\` first.`);
         process.exitCode = 1;
         return;
     }
@@ -99,7 +105,7 @@ program
     .action(() => {
     const cfg = (0, config_1.loadConfig)();
     if (!cfg) {
-        console.log("Not paired. Run `qagent-agent pair <code>` to pair this machine.");
+        console.log(`Not paired. Run \`${invocation()} pair <code>\` to pair this machine.`);
         return;
     }
     console.log(`Paired as device #${cfg.deviceId} (${cfg.deviceName})`);
@@ -110,7 +116,15 @@ program
     .description("Forget the paired device token")
     .action(() => {
     (0, config_1.clearConfig)();
-    console.log("Device token cleared. Run `qagent-agent pair <code>` to pair again.");
+    console.log(`Device token cleared. Run \`${invocation()} pair <code>\` to pair again.`);
+});
+program
+    .command("ui", { isDefault: true })
+    .description("Open the local web UI to pair and watch progress in your browser (default)")
+    .option("--port <port>", "port for the local UI server (default 7420)")
+    .option("--no-open", "start the UI server without opening a browser")
+    .action((opts) => {
+    (0, ui_1.startUi)({ port: opts.port ? Number(opts.port) : undefined, open: opts.open !== false });
 });
 program.parseAsync(process.argv).catch((err) => {
     console.error(err);

package/dist/src/config.js

@@ -38,6 +38,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultServerUrl = defaultServerUrl;
 exports.configDir = configDir;
 exports.loadConfig = loadConfig;
 exports.saveConfig = saveConfig;
@@ -45,6 +46,30 @@ exports.clearConfig = clearConfig;
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
+/** The server URL baked into this build, so the packaged desktop app can
+ * pre-fill it and the user only types the 6-digit code (no URL to enter).
+ *
+ * Resolution: a runtime ``QAGENT_SERVER`` env override wins (dev/testing), then
+ * the ``qagentServer`` field electron-builder merges into the packaged
+ * ``package.json`` (see build.extraMetadata). Empty for the generic npm/npx
+ * build — those callers still pass ``--server`` (or type the URL) as before. */
+function defaultServerUrl() {
+    const fromEnv = (process.env.QAGENT_SERVER || "").trim();
+    if (fromEnv)
+        return fromEnv.replace(/\/+$/, "");
+    try {
+        // dist/src/config.js → ../../package.json (the app's own manifest, which in
+        // a packaged build carries the baked-in qagentServer).
+        const pkgPath = path.join(__dirname, "..", "..", "package.json");
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+        if (typeof pkg.qagentServer === "string")
+            return pkg.qagentServer.trim().replace(/\/+$/, "");
+    }
+    catch {
+        // Generic build / manifest unreadable — no baked server.
+    }
+    return "";
+}
 /** Directory holding the agent's persisted config + local session store. */
 function configDir() {
     return path.join(os.homedir(), ".qagent-agent");

package/dist/src/ensureBrowser.js

@@ -44,19 +44,7 @@ exports.ensureChromium = ensureChromium;
  */
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
-const path = __importStar(require("path"));
-function firstExisting(paths) {
-    for (const p of paths) {
-        if (fs.existsSync(p))
-            return p;
-    }
-    return null;
-}
-/** The agent package's own node_modules (mirrors runner.ts's resolver). */
-function agentNodeModules() {
-    return (firstExisting([path.join(__dirname, "..", "..", "node_modules"), path.join(__dirname, "..", "node_modules")]) ??
-        path.join(__dirname, "..", "..", "node_modules"));
-}
+const paths_1 = require("./paths");
 /** Path Playwright expects the Chromium build at, or null if it can't be resolved. */
 function chromiumExecutable() {
     try {
@@ -72,7 +60,9 @@ function chromiumExecutable() {
  * Ensure Chromium is installed, running `playwright install chromium` if it's missing.
  *
  * Fast no-op once the browser exists. Streams the download progress so a first-run
- * fetch (~100 MB) is visible rather than a silent hang.
+ * fetch (~100 MB) is visible rather than a silent hang. Invokes Playwright's CLI
+ * through the resolved node runtime (`node cli.js install chromium`) so it works
+ * from source, via npx, and in a packaged bundle alike.
  *
  * Returns:
  *   true when Chromium is available (already present, or installed successfully);
@@ -83,13 +73,11 @@ async function ensureChromium() {
     if (exe && fs.existsSync(exe))
         return true;
     console.log("Chromium not found — installing Playwright's Chromium (one-time download)...");
-    const nm = agentNodeModules();
-    const bin = path.join(nm, ".bin", process.platform === "win32" ? "playwright.cmd" : "playwright");
-    const useBin = fs.existsSync(bin);
-    const cmd = useBin ? bin : "npx";
-    const args = useBin ? ["install", "chromium"] : ["playwright", "install", "chromium"];
     const code = await new Promise((resolve) => {
-        const child = (0, child_process_1.spawn)(cmd, args, { stdio: "inherit", shell: process.platform === "win32" });
+        const child = (0, child_process_1.spawn)((0, paths_1.nodeBin)(), [(0, paths_1.playwrightCli)(), "install", "chromium"], {
+            stdio: "inherit",
+            env: { ...process.env, ...(0, paths_1.childNodeEnv)() },
+        });
         child.on("close", resolve);
         child.on("error", () => resolve(null));
     });

package/dist/src/paths.js

@@ -0,0 +1,152 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.firstExisting = firstExisting;
+exports.isElectron = isElectron;
+exports.childNodeEnv = childNodeEnv;
+exports.packagedRoot = packagedRoot;
+exports.nodeBin = nodeBin;
+exports.agentNodeModules = agentNodeModules;
+exports.playwrightCli = playwrightCli;
+exports.vendorCaptureScript = vendorCaptureScript;
+/**
+ * Runtime path resolution for the agent's child processes (Playwright CLI +
+ * the headed-login capture script), working in three layouts:
+ *
+ *   1. from source / `npx @q-agent/agent` — `node` on PATH, deps in the package's
+ *      own node_modules;
+ *   2. a packaged Windows bundle (built by `scripts/package-win.mjs`, run as a
+ *      `@yao-pkg/pkg` binary) — a bundled `node.exe`, `node_modules/`, and
+ *      `vendor/` sit next to the executable.
+ *
+ * Everything the agent spawns is invoked as `nodeBin() <script/cli.js> …`, so
+ * the same code path works whether `node` comes from PATH or the bundle.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function firstExisting(candidates) {
+    for (const c of candidates) {
+        if (fs.existsSync(c))
+            return c;
+    }
+    return null;
+}
+/** True when running inside Electron (the desktop app) rather than plain Node. */
+function isElectron() {
+    return Boolean(process.versions?.electron);
+}
+/**
+ * Environment additions for spawned child node processes. Under Electron,
+ * `process.execPath` is the Electron binary, so `nodeBin()` returns it — set
+ * ELECTRON_RUN_AS_NODE=1 so it runs the given script as Node rather than
+ * launching another app window.
+ */
+function childNodeEnv() {
+    return isElectron() ? { ELECTRON_RUN_AS_NODE: "1" } : {};
+}
+/** True when running as a Node Single Executable Application (the packaged .exe). */
+function isSea() {
+    try {
+        return require("node:sea").isSea();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The folder beside the executable in a packaged bundle (holds the bundled
+ * node runtime, node_modules, and vendor/). Null when running from source/npx.
+ * Set when running as a SEA binary (the Windows bundle) — or a pkg binary.
+ */
+function packagedRoot() {
+    return isSea() || process.pkg ? path.dirname(process.execPath) : null;
+}
+/**
+ * Node runtime used to spawn child processes. Prefers the bundled `node.exe`
+ * in a packaged install (so no global Node is required), else `node` from PATH.
+ */
+function nodeBin() {
+    const root = packagedRoot();
+    if (root) {
+        const bundled = path.join(root, process.platform === "win32" ? "node.exe" : "node");
+        if (fs.existsSync(bundled))
+            return bundled;
+    }
+    // From source / npx, the agent itself runs under a real Node — reuse it. An
+    // absolute path lets children spawn without a shell (safe with spaces in the
+    // path); `process.execPath` is only the pkg binary when packagedRoot() is set.
+    return process.execPath;
+}
+/** node_modules holding `playwright` + `@playwright/test`. */
+function agentNodeModules() {
+    const root = packagedRoot();
+    if (root) {
+        const nm = path.join(root, "node_modules");
+        if (fs.existsSync(nm))
+            return nm;
+    }
+    // From source / npx / global install, let Node's own resolver find the
+    // node_modules that actually holds the deps. npm (and `npx`) HOIST
+    // `@playwright/test` and `playwright` to a parent node_modules — the npx
+    // cache root or the global root — rather than nesting them under the package,
+    // so a hardcoded relative guess misses them (the cause of the
+    // "Cannot find module '@playwright/test'" failure on npx/global installs).
+    // `.../node_modules/@playwright/test/package.json` → `.../node_modules`.
+    const testPkgJson = require.resolve("@playwright/test/package.json");
+    return path.dirname(path.dirname(path.dirname(testPkgJson)));
+}
+/** Playwright's CLI entry — drives both `test` (run specs) and `install` (browsers). */
+function playwrightCli() {
+    const root = packagedRoot();
+    if (root) {
+        const bundled = path.join(root, "node_modules", "playwright", "cli.js");
+        if (fs.existsSync(bundled))
+            return bundled;
+    }
+    // Resolve via Node so it works whether npm nested or hoisted `playwright`.
+    return path.join(path.dirname(require.resolve("playwright/package.json")), "cli.js");
+}
+/** The vendored headed-login capture script (`capture_auth.cjs`). */
+function vendorCaptureScript() {
+    const root = packagedRoot();
+    const found = firstExisting([
+        ...(root ? [path.join(root, "vendor", "capture_auth.cjs")] : []),
+        path.join(__dirname, "..", "..", "vendor", "capture_auth.cjs"),
+        path.join(__dirname, "..", "vendor", "capture_auth.cjs"),
+    ]);
+    if (!found)
+        throw new Error("capture_auth.cjs not found — the agent package is missing vendor/");
+    return found;
+}