@q-agent/agent 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# @q-agent/agent — Q-Agent Local Agent
+
+Runs Playwright test executions on **your own machine** instead of the
+Q-Agent server. This means:
+
+- Manual login / MFA happens in a real, headed browser right where you are
+  sitting — not on a headless server.
+- Your session cookies/localStorage/sessionStorage **never leave this
+  machine**. Only test specs, pass/fail results, and evidence (screenshots/
+  video/trace) are sent back to the server.
+
+## Prerequisites
+
+- Node.js 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
+
+```bash
+npx @q-agent/agent pair <code> --server https://your-qagent-server.example.com/api
+npx @q-agent/agent start
+```
+
+`--server` is the origin serving the API's `/agent/...` routes. On the
+same-origin (Cloudflare tunnel) deployment that's `<origin>/api`. In local dev
+with the API on its own port, use the API directly (e.g. `http://127.0.0.1:8787`).
+
+Or, if working from a checkout of this package:
+
+```bash
+cd agent
+npm install
+npm run build
+node dist/src/cli.js pair <code> --server http://127.0.0.1:8787
+node dist/src/cli.js start
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `pair <code> [--server <url>] [--name <name>]` | Redeem a one-time pairing code (generated in the Q-Agent SPA's Local Agent screen) for a durable device token. Stored at `~/.qagent-agent/config.json` (mode 0600). |
+| `start [--server <url>]` | Long-poll the server for queued `local-agent` executions and run them. Ctrl-C shuts down cleanly, killing any in-flight Playwright/capture process. |
+| `status` | Show whether this machine is paired, and to which server. |
+| `logout` | Forget the device token. |
+
+## How a job runs
+
+1. Claim a job (`POST /agent/jobs/next`) — spec sources + run params, **never** any session/credentials.
+2. Write the specs and a `playwright.config.ts` into a temp workdir.
+3. If the project requires manual login and no valid local session exists for
+   its origin yet, open a **headed** browser (`vendor/capture_auth.cjs`) for
+   you to log in. The captured session is saved under
+   `~/.qagent-agent/sessions/<origin>/` and reused on future runs until it
+   expires.
+4. Run `@playwright/test` headed, parse `report.json`.
+5. Push each case's result, its evidence (screenshots/video/trace), and
+   progress events back to the server, then mark the job complete.
+
+## Known limitation (flag for the server cleanup phase)
+
+`POST /agent/jobs/next`'s `specs[]` entries currently only carry
+`{filename, code}` — not the case's full `ticketExternalId`/`caseCode`
+(even though the server has both in scope when building the payload, see
+`api/app/routers/agent.py` `claim_next_job`). The agent recovers a
+best-effort identity by parsing the `{shortTicket}-{caseCode}.spec.ts`
+filename convention (`src/report.ts` `parseSpecIdentity`), assuming the
+fixed `TC-NN` case-code format used everywhere else in this codebase. This
+only recovers the ticket's **short numeric suffix** (e.g. `"1428"`), not its
+full provider-prefixed external id (e.g. `"SUR-1428"`) — so:
+
+- `exec.case.running` / `exec.case.result` WS events carry that short id in
+  `ticket`, which may not match what the frontend expects to key rows by.
+- `POST /agent/jobs/{id}/evidence` requires an **exact** `ticket_external_id`
+  match server-side (`ExecutionResult.ticket_external_id == ticket_external_id`)
+  — the short id will likely **not** match, so evidence uploads may 404
+  until this is fixed.
+
+The client (`src/api.ts` `JobSpec`, `src/runner.ts` `identityFor`) already
+prefers explicit `ticketExternalId`/`caseCode` fields on each spec entry if
+present, so the fix is additive: add those two fields to the `specs.append(...)`
+call in `claim_next_job` (the loop variable `r` already has them in scope) —
+no agent-side change needed once that lands.

package/dist/src/api.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * Typed HTTP client for the Local Agent wire protocol served by
+ * `api/app/routers/agent.py`. Every job call sends
+ * `Authorization: Bearer <deviceToken>`. Uses Node's built-in `fetch`
+ * (Node 18+) — no extra HTTP dependency.
+ */
+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.ApiError = void 0;
+exports.redeemDevice = redeemDevice;
+exports.claimNextJob = claimNextJob;
+exports.postEvent = postEvent;
+exports.postResult = postResult;
+exports.postEvidence = postEvidence;
+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). */
+class ApiError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`Request failed with status ${status}: ${body.slice(0, 500)}`);
+        this.status = status;
+        this.body = body;
+    }
+}
+exports.ApiError = ApiError;
+function authHeaders(token) {
+    return { Authorization: `Bearer ${token}` };
+}
+async function throwIfNotOk(res) {
+    if (!res.ok) {
+        throw new ApiError(res.status, await res.text().catch(() => ""));
+    }
+}
+/** Redeem a one-time pairing code for a durable device token (the `pair` command). */
+async function redeemDevice(serverUrl, code, name) {
+    const res = await fetch(`${serverUrl}/agent/devices/redeem`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ code, name }),
+    });
+    await throwIfNotOk(res);
+    return (await res.json());
+}
+/** 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`, {
+        method: "POST",
+        headers: authHeaders(cfg.deviceToken),
+    });
+    if (res.status === 204)
+        return null;
+    await throwIfNotOk(res);
+    return (await res.json());
+}
+/** 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`, {
+        method: "POST",
+        headers: { ...authHeaders(cfg.deviceToken), "Content-Type": "application/json" },
+        body: JSON.stringify({ event, payload }),
+    });
+    await throwIfNotOk(res);
+}
+/** Push one parsed case result; the server matches it to its `ExecutionResult` by filename. */
+async function postResult(cfg, executionId, entry) {
+    const res = await fetch(`${cfg.serverUrl}/agent/jobs/${executionId}/results`, {
+        method: "POST",
+        headers: { ...authHeaders(cfg.deviceToken), "Content-Type": "application/json" },
+        body: JSON.stringify(entry),
+    });
+    await throwIfNotOk(res);
+}
+/** Multipart-upload one evidence artifact (screenshot/video/trace). */
+async function postEvidence(cfg, executionId, ev) {
+    const data = fs.readFileSync(ev.filePath);
+    const form = new FormData();
+    form.set("ticket_external_id", ev.ticketExternalId);
+    form.set("case_code", ev.caseCode);
+    form.set("kind", ev.kind);
+    form.set("file", new Blob([data]), ev.filename);
+    const res = await fetch(`${cfg.serverUrl}/agent/jobs/${executionId}/evidence`, {
+        method: "POST",
+        headers: authHeaders(cfg.deviceToken),
+        body: form,
+    });
+    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`, {
+        method: "POST",
+        headers: { ...authHeaders(cfg.deviceToken), "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    await throwIfNotOk(res);
+}

package/dist/src/cli.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * `qagent-agent` CLI — `npx @q-agent/agent <command>`.
+ *
+ * Commands:
+ *   pair <code> [--server <url>] [--name <name>]  Redeem a one-time pairing code for a device token.
+ *   start [--server <url>]                        Long-poll for jobs and run them.
+ *   status                                        Show pairing state.
+ *   logout                                        Forget the device token.
+ */
+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 });
+const commander_1 = require("commander");
+const os = __importStar(require("os"));
+const config_1 = require("./config");
+const api_1 = require("./api");
+const runner_1 = require("./runner");
+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("--name <name>", "device name shown in the paired-devices list", os.hostname())
+    .action(async (code, opts) => {
+    const serverUrl = opts.server.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.");
+    }
+    catch (err) {
+        console.error("Pairing failed:", err.message);
+        process.exitCode = 1;
+    }
+});
+program
+    .command("start")
+    .description("Long-poll for queued jobs and run them")
+    .option("--server <url>", "override the paired server base URL for this run")
+    .action(async (opts) => {
+    const cfg = (0, config_1.loadConfig)();
+    if (!cfg) {
+        console.error("Not paired yet — run `qagent-agent pair <code>` first.");
+        process.exitCode = 1;
+        return;
+    }
+    if (opts.server)
+        cfg.serverUrl = opts.server.replace(/\/+$/, "");
+    const signal = { aborted: false };
+    const shutdown = () => {
+        console.log("\nShutting down — killing any active Playwright/capture process...");
+        signal.aborted = true;
+        (0, runner_1.killActiveChild)();
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    await (0, runner_1.runAgentLoop)(cfg, signal);
+});
+program
+    .command("status")
+    .description("Show whether this machine is paired")
+    .action(() => {
+    const cfg = (0, config_1.loadConfig)();
+    if (!cfg) {
+        console.log("Not paired. Run `qagent-agent pair <code>` to pair this machine.");
+        return;
+    }
+    console.log(`Paired as device #${cfg.deviceId} (${cfg.deviceName})`);
+    console.log(`Server: ${cfg.serverUrl}`);
+});
+program
+    .command("logout")
+    .description("Forget the paired device token")
+    .action(() => {
+    (0, config_1.clearConfig)();
+    console.log("Device token cleared. Run `qagent-agent pair <code>` to pair again.");
+});
+program.parseAsync(process.argv).catch((err) => {
+    console.error(err);
+    process.exitCode = 1;
+});

package/dist/src/config.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * Local Agent config: server URL + paired device token, persisted at
+ * `~/.qagent-agent/config.json`. This is the ONLY durable credential the
+ * agent holds — a device token, never the user's app session.
+ */
+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.configDir = configDir;
+exports.loadConfig = loadConfig;
+exports.saveConfig = saveConfig;
+exports.clearConfig = clearConfig;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+/** Directory holding the agent's persisted config + local session store. */
+function configDir() {
+    return path.join(os.homedir(), ".qagent-agent");
+}
+function configPath() {
+    return path.join(configDir(), "config.json");
+}
+/**
+ * Load the persisted config, or `null` if the agent has never been paired
+ * (or the file is missing/corrupt).
+ */
+function loadConfig() {
+    try {
+        const raw = fs.readFileSync(configPath(), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist `cfg`, creating the config dir if needed. The file is written
+ * with `0600` permissions (owner read/write only) since it holds a bearer
+ * token; `chmod` is best-effort since it is a no-op on Windows.
+ */
+function saveConfig(cfg) {
+    fs.mkdirSync(configDir(), { recursive: true });
+    const p = configPath();
+    fs.writeFileSync(p, JSON.stringify(cfg, null, 2), { encoding: "utf-8", mode: 0o600 });
+    try {
+        fs.chmodSync(p, 0o600);
+    }
+    catch {
+        // Best-effort — chmod is a no-op on Windows filesystems.
+    }
+}
+/** Remove the persisted config (the `logout` command). */
+function clearConfig() {
+    try {
+        fs.unlinkSync(configPath());
+    }
+    catch {
+        // Already gone — logout is idempotent.
+    }
+}

package/dist/src/ensureBrowser.js

@@ -0,0 +1,102 @@
+"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.ensureChromium = ensureChromium;
+/**
+ * Ensure Playwright's Chromium build is present, downloading it once if absent —
+ * so the user never has to run `npx playwright install chromium` manually.
+ *
+ * Both the headed login capture (`vendor/capture_auth.cjs`) and the spec run use
+ * Chromium from the agent's own Playwright install; this guarantees it exists
+ * before either runs.
+ */
+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"));
+}
+/** Path Playwright expects the Chromium build at, or null if it can't be resolved. */
+function chromiumExecutable() {
+    try {
+        // Resolved from the agent's own node_modules — the same install used to run specs.
+        const { chromium } = require("playwright");
+        return chromium.executablePath();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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.
+ *
+ * Returns:
+ *   true when Chromium is available (already present, or installed successfully);
+ *   false when the install failed — the caller should abort rather than run.
+ */
+async function ensureChromium() {
+    const exe = chromiumExecutable();
+    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" });
+        child.on("close", resolve);
+        child.on("error", () => resolve(null));
+    });
+    if (code !== 0) {
+        console.error("Chromium install failed — run `npx playwright install chromium` manually, then retry.");
+        return false;
+    }
+    console.log("Chromium ready.");
+    return true;
+}