@q-agent/agent 0.1.1 → 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
@@ -62,6 +73,22 @@ Chromium still auto-installs on first `start`. Build the bundle on Windows with
 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/cli.js

@@ -48,6 +48,7 @@ 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() {
@@ -59,10 +60,10 @@ 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 };
@@ -117,6 +118,14 @@ program
     (0, config_1.clearConfig)();
     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);
     process.exitCode = 1;

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

@@ -74,7 +74,10 @@ async function ensureChromium() {
         return true;
     console.log("Chromium not found — installing Playwright's Chromium (one-time download)...");
     const code = await new Promise((resolve) => {
-        const child = (0, child_process_1.spawn)((0, paths_1.nodeBin)(), [(0, paths_1.playwrightCli)(), "install", "chromium"], { stdio: "inherit" });
+        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

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.firstExisting = firstExisting;
+exports.isElectron = isElectron;
+exports.childNodeEnv = childNodeEnv;
 exports.packagedRoot = packagedRoot;
 exports.nodeBin = nodeBin;
 exports.agentNodeModules = agentNodeModules;
@@ -61,6 +63,19 @@ function firstExisting(candidates) {
     }
     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 {

package/dist/src/playwrightConfig.js

@@ -1,10 +1,10 @@
 "use strict";
 /**
  * Port of `api/app/services/playwright_runner.py`'s config template
- * (`_PLAYWRIGHT_CONFIG_TEMPLATE` + `_write_config`) and the sessionStorage
- * fixture shim (`_auth_fixtures_ts` + `_apply_auth_fixtures`), reproduced
- * faithfully so a spec that runs on the server and one that runs via the
- * Local Agent behave identically.
+ * (`_PLAYWRIGHT_CONFIG_TEMPLATE` + `_write_config`) and the injected-fixtures
+ * shim (`_fixtures_ts` + `_apply_fixtures`), reproduced faithfully so a spec
+ * that runs on the server and one that runs via the Local Agent behave
+ * identically — including always-on DOM capture (raw + distilled).
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -41,8 +41,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.writeConfig = writeConfig;
-exports.authFixturesTs = authFixturesTs;
-exports.applyAuthFixtures = applyAuthFixtures;
+exports.fixturesTs = fixturesTs;
+exports.applyFixtures = applyFixtures;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const PLAYWRIGHT_CONFIG_TEMPLATE = `import { defineConfig } from '@playwright/test';
@@ -83,14 +83,37 @@ function writeConfig(specDir, workers, headless, baseUrl = "", storageState = ""
     fs.writeFileSync(path.join(specDir, "playwright.config.ts"), content, "utf-8");
 }
 /**
- * TypeScript for a generated `fixtures.ts` that replays sessionStorage —
- * port of `_auth_fixtures_ts`.
+ * TypeScript for a generated `fixtures.ts` that captures the page DOM after
+ * every test, and optionally replays a captured sessionStorage — port of
+ * `_fixtures_ts`.
+ *
+ * The module re-exports Playwright's `test` extended with:
+ * - an `{auto: true}` fixture that, after each test, best-effort attaches the
+ *   live page's raw HTML (`qagent-dom-raw`) and a distilled inventory of the
+ *   page's interactable elements (`qagent-dom-distilled`) via `testInfo.attach`,
+ *   so self-heal can ground on the real DOM. Wrapped in try/catch so it never
+ *   fails a test.
+ * - (only when `replaySession`) a `context` override that restores the captured
+ *   `sessionStorage` (MSAL/SPA tokens) for the current origin before app code runs.
  *
  * @param sessionFile Absolute path to the captured `sessionStorage.json`;
- *   embedded as a JSON-encoded string literal so the fixture reads it at
- *   runtime.
+ *   embedded as a JSON-encoded string literal, read at runtime only when
+ *   `replaySession` is set.
+ * @param replaySession Whether to inject the sessionStorage-replay `context`
+ *   override (DOM capture is always injected regardless).
  */
-function authFixturesTs(sessionFile) {
+function fixturesTs(sessionFile, replaySession) {
+    const contextFixture = replaySession
+        ? "  context: async ({ context }, use) => {\n" +
+            "    await context.addInitScript((sessions: Record<string, Record<string, string>>) => {\n" +
+            "      try {\n" +
+            "        const entries = sessions[location.origin];\n" +
+            "        if (entries) for (const k in entries) window.sessionStorage.setItem(k, entries[k]);\n" +
+            "      } catch {}\n" +
+            "    }, SESSIONS);\n" +
+            "    await use(context);\n" +
+            "  },\n"
+        : "";
     return ("import { test as base, expect } from '@playwright/test';\n" +
         "import * as fs from 'fs';\n" +
         "\n" +
@@ -98,47 +121,71 @@ function authFixturesTs(sessionFile) {
         "let SESSIONS: Record<string, Record<string, string>> = {};\n" +
         "try { SESSIONS = JSON.parse(fs.readFileSync(SESSION_FILE, 'utf-8')); } catch {}\n" +
         "\n" +
-        "export const test = base.extend({\n" +
-        "  context: async ({ context }, use) => {\n" +
-        "    await context.addInitScript((sessions: Record<string, Record<string, string>>) => {\n" +
-        "      try {\n" +
-        "        const entries = sessions[location.origin];\n" +
-        "        if (entries) for (const k in entries) window.sessionStorage.setItem(k, entries[k]);\n" +
-        "      } catch {}\n" +
-        "    }, SESSIONS);\n" +
-        "    await use(context);\n" +
-        "  },\n" +
+        "export const test = base.extend<{ _domCapture: void }>({\n" +
+        contextFixture +
+        "  // Always-on DOM capture: after each test, snapshot the live page so the\n" +
+        "  // runner (evidence) and self-heal loop (real selectors) can use it.\n" +
+        "  _domCapture: [async ({ page }, use, testInfo) => {\n" +
+        "    await use();\n" +
+        "    try {\n" +
+        "      const raw = await page.content();\n" +
+        "      const rawPath = testInfo.outputPath('qagent-dom-raw.html');\n" +
+        "      fs.writeFileSync(rawPath, raw, 'utf-8');\n" +
+        "      await testInfo.attach('qagent-dom-raw', { path: rawPath, contentType: 'text/html' });\n" +
+        "    } catch {}\n" +
+        "    try {\n" +
+        "      const snapshot = await page.evaluate(() => {\n" +
+        "        const SEL = 'a,button,input,select,textarea,[role],[data-testid],[data-test],[id]';\n" +
+        "        const elements = Array.from(document.querySelectorAll(SEL)).slice(0, 400).map((node) => {\n" +
+        "          const el = node as HTMLElement;\n" +
+        "          const text = (el.innerText || '').trim().slice(0, 80);\n" +
+        "          return {\n" +
+        "            tag: el.tagName.toLowerCase(),\n" +
+        "            role: el.getAttribute('role') || undefined,\n" +
+        "            testId: el.getAttribute('data-testid') || el.getAttribute('data-test') || undefined,\n" +
+        "            id: el.id || undefined,\n" +
+        "            name: el.getAttribute('name') || undefined,\n" +
+        "            text: text || undefined,\n" +
+        "            placeholder: el.getAttribute('placeholder') || undefined,\n" +
+        "            type: el.getAttribute('type') || undefined,\n" +
+        "          };\n" +
+        "        });\n" +
+        "        return { path: location.pathname, url: location.href, elements };\n" +
+        "      });\n" +
+        "      const distilledPath = testInfo.outputPath('qagent-dom-distilled.json');\n" +
+        "      fs.writeFileSync(distilledPath, JSON.stringify(snapshot), 'utf-8');\n" +
+        "      await testInfo.attach('qagent-dom-distilled', { path: distilledPath, contentType: 'application/json' });\n" +
+        "    } catch {}\n" +
+        "  }, { auto: true }],\n" +
         "});\n" +
         "\n" +
         "export { expect };\n" +
         "export type * from '@playwright/test';\n");
 }
 /**
- * Rewrite each spec's Playwright import to use (or stop using) the
- * sessionStorage fixture — port of `_apply_auth_fixtures`. Only the module
- * specifier is touched.
+ * Point each spec's Playwright import at the generated `fixtures.ts` and write
+ * it — port of `_apply_fixtures`. Only the module specifier is touched.
+ *
+ * DOM capture is always on, so fixtures are ALWAYS injected (unlike the previous
+ * auth-only behavior): each spec's `'@playwright/test'` import is rewritten to
+ * `'./fixtures'` and `fixtures.ts` is (re)written every run. `replaySession` only
+ * controls whether the generated module also replays the captured sessionStorage.
  *
- * The Python version globs `*.spec.ts` in `specDir`; the agent already
- * knows exactly which spec filenames it wrote for this job, so
- * `specFilenames` is passed explicitly instead of re-scanning the
- * directory (equivalent behavior, no extra glob dependency).
+ * The Python version globs `*.spec.ts` in `specDir`; the agent already knows
+ * exactly which spec filenames it wrote for this job, so `specFilenames` is
+ * passed explicitly instead of re-scanning the directory.
  *
  * @param specDir The job's local workdir containing the spec files.
  * @param specFilenames The spec filenames written into `specDir` for this job.
  * @param sessionFile Absolute path to the `sessionStorage.json` snapshot embedded
  *   in the generated `fixtures.ts`.
- * @param enabled Whether sessionStorage replay is active for this run.
+ * @param replaySession Whether sessionStorage replay is active for this run.
  */
-function applyAuthFixtures(specDir, specFilenames, sessionFile, enabled) {
-    const replacements = enabled
-        ? [
-            ["'@playwright/test'", "'./fixtures'"],
-            ['"@playwright/test"', '"./fixtures"'],
-        ]
-        : [
-            ["'./fixtures'", "'@playwright/test'"],
-            ['"./fixtures"', '"@playwright/test"'],
-        ];
+function applyFixtures(specDir, specFilenames, sessionFile, replaySession) {
+    const replacements = [
+        ["'@playwright/test'", "'./fixtures'"],
+        ['"@playwright/test"', '"./fixtures"'],
+    ];
     for (const filename of specFilenames) {
         const specPath = path.join(specDir, filename);
         let text;
@@ -156,7 +203,5 @@ function applyAuthFixtures(specDir, specFilenames, sessionFile, enabled) {
             fs.writeFileSync(specPath, newText, "utf-8");
         }
     }
-    if (enabled) {
-        fs.writeFileSync(path.join(specDir, "fixtures.ts"), authFixturesTs(sessionFile), "utf-8");
-    }
+    fs.writeFileSync(path.join(specDir, "fixtures.ts"), fixturesTs(sessionFile, replaySession), "utf-8");
 }

package/dist/src/report.js

@@ -22,6 +22,10 @@ const ATTACHMENT_KIND_MAP = {
     screenshot: "screenshot",
     video: "video",
     trace: "trace",
+    // DOM captured by the injected fixtures (see playwrightConfig.fixturesTs):
+    // raw page HTML + a distilled interactable-element inventory.
+    "qagent-dom-raw": "dom",
+    "qagent-dom-distilled": "dom-distilled",
 };
 /* eslint-enable @typescript-eslint/no-explicit-any */
 /**