@q-agent/agent 0.1.6 → 0.1.7

package/dist/src/api.js

@@ -40,6 +40,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiError = void 0;
+exports.fetchWithTimeout = fetchWithTimeout;
 exports.redeemDevice = redeemDevice;
 exports.disconnectDevice = disconnectDevice;
 exports.claimNextJob = claimNextJob;
@@ -71,6 +72,22 @@ async function throwIfNotOk(res) {
         throw new ApiError(res.status, await res.text().catch(() => ""));
     }
 }
+/** Multipart evidence (video/trace) can be multi-MB; cap the upload so a stalled
+ * connection aborts instead of hanging the background uploader forever. */
+const EVIDENCE_UPLOAD_TIMEOUT_MS = 300_000;
+/** `fetch()` with a hard timeout via `AbortController`, so a stalled connection
+ * can't hang indefinitely (Node's `fetch` has no default timeout). Rejects with
+ * an `AbortError` once `timeoutMs` elapses. */
+async function fetchWithTimeout(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 /** 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`, {
@@ -148,22 +165,47 @@ async function postEvidence(cfg, executionId, ev) {
     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`, {
+    const res = await fetchWithTimeout(`${cfg.serverUrl}/agent/jobs/${executionId}/evidence`, {
         method: "POST",
         headers: authHeaders(cfg.deviceToken),
         body: form,
-    });
+    }, EVIDENCE_UPLOAD_TIMEOUT_MS);
     await throwIfNotOk(res);
 }
-/** Ask the server to classify + fix one failed heal attempt (Claude + KB live server-side). */
+/** Heal-fix polling: the server generates the fix (~3 min Claude call) in the
+ * background so no single request stays open long enough to hit a fronting
+ * proxy's ~100s edge cap (Cloudflare 524). Poll every 3s, capped at 6 min
+ * (covers the server's 300s Claude timeout + margin); each request is short. */
+const HEAL_FIX_POLL_INTERVAL_MS = 3_000;
+const HEAL_FIX_TOTAL_TIMEOUT_MS = 360_000;
+const HEAL_FIX_REQUEST_TIMEOUT_MS = 30_000;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Ask the server to classify + fix one failed heal attempt (Claude + KB live
+ * server-side). Starts an async job then polls for the result, so a long fix
+ * generation never trips the ~100s proxy timeout that a synchronous call did. */
 async function postHealFix(cfg, caseId, body) {
-    const res = await fetch(`${cfg.serverUrl}/agent/heal/${caseId}/fix`, {
+    const startRes = await fetchWithTimeout(`${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());
+    }, HEAL_FIX_REQUEST_TIMEOUT_MS);
+    await throwIfNotOk(startRes);
+    const { jobId } = (await startRes.json());
+    if (!jobId)
+        throw new Error("Heal fix did not return a job id");
+    const deadline = Date.now() + HEAL_FIX_TOTAL_TIMEOUT_MS;
+    for (;;) {
+        const res = await fetchWithTimeout(`${cfg.serverUrl}/agent/heal/${caseId}/fix/${jobId}`, { method: "GET", headers: authHeaders(cfg.deviceToken) }, HEAL_FIX_REQUEST_TIMEOUT_MS);
+        await throwIfNotOk(res);
+        const data = (await res.json());
+        if (data.status === "done" && data.result)
+            return data.result;
+        if (data.status === "error")
+            throw new Error(data.error || "Heal fix failed on the server");
+        if (Date.now() > deadline)
+            throw new Error("Heal fix timed out waiting for the server");
+        await sleep(HEAL_FIX_POLL_INTERVAL_MS);
+    }
 }
 /** Persist the heal's final outcome + feed a passing DOM-grounded heal into the KB. */
 async function postHealFinalize(cfg, caseId, body) {

package/dist/src/cli.js

@@ -49,13 +49,19 @@ const config_1 = require("./config");
 const api_1 = require("./api");
 const runner_1 = require("./runner");
 const ui_1 = require("./ui");
+const version_1 = require("./version");
 /** 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
+    .name("qagent-agent")
+    .description("Q-Agent Local Agent — runs Playwright locally for this machine's owner.")
+    // Surfaces the actual installed build (e.g. via `npx @q-agent/agent --version`),
+    // so a stale npx cache serving an old agent is easy to spot.
+    .version((0, version_1.agentVersion)(), "-v, --version", "print the agent version");
 program
     .command("pair")
     .description("Redeem a one-time pairing code (from the Q-Agent SPA) for a device token")

package/dist/src/runner.js

@@ -54,6 +54,7 @@ const paths_1 = require("./paths");
 const playwrightConfig_1 = require("./playwrightConfig");
 const report_1 = require("./report");
 const session_1 = require("./session");
+const version_1 = require("./version");
 // Mirrors api/app/config.py's Settings.exec_timeout_s / auth_capture_timeout_s.
 const EXEC_TIMEOUT_MS = 600_000;
 const AUTH_CAPTURE_TIMEOUT_MS = 300_000;
@@ -224,6 +225,10 @@ async function processJob(cfg, job) {
         return;
     }
     const workDir = fs.mkdtempSync(path.join(os.tmpdir(), "qagent-"));
+    // Set once the (detached) evidence uploader takes ownership of workDir — it
+    // then removes the dir when its uploads finish. Until then, this function's
+    // finally cleans up (error / early-return paths).
+    let handedOff = false;
     try {
         for (const spec of job.specs) {
             fs.writeFileSync(path.join(workDir, spec.filename), spec.code, "utf-8");
@@ -346,11 +351,30 @@ async function processJob(cfg, job) {
         await api.postComplete(cfg, job.executionId, { passed, failed, log: logText });
         (0, bus_1.emit)("job-complete", { executionId: job.executionId, passed, failed });
         // Now that the run is marked done, upload the (deferred) evidence artifacts.
-        // The web already reflects the outcome; these trail in the background and the
-        // Evidence step picks them up as they land.
+        // These run DETACHED from the claim loop: the run's outcome is already
+        // reported, so the agent must be free to claim the next run immediately
+        // rather than blocking here until every (potentially multi-MB) artifact
+        // finishes uploading — that block is what stalled the agent when a new run
+        // was started mid-upload. The uploader owns workDir cleanup from here.
+        handedOff = true;
+        void uploadEvidenceThenCleanup(cfg, job.executionId, pendingEvidence, workDir);
+    }
+    finally {
+        if (!handedOff)
+            fs.rmSync(workDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Upload a completed job's deferred evidence artifacts, then remove its workDir.
+ * Runs detached from the claim loop (see {@link processJob}) so uploads never
+ * delay claiming the next run. Never throws: each upload's failure is logged and
+ * the workDir is always removed, even if some uploads fail or time out.
+ */
+async function uploadEvidenceThenCleanup(cfg, executionId, pendingEvidence, workDir) {
+    try {
         for (const ev of pendingEvidence) {
             await api
-                .postEvidence(cfg, job.executionId, {
+                .postEvidence(cfg, executionId, {
                 ticketExternalId: ev.ticket,
                 caseCode: ev.caseCode,
                 kind: ev.kind,
@@ -592,7 +616,7 @@ async function runAgentLoop(cfg, signal) {
         console.error("Chromium is required to run tests — aborting.");
         return;
     }
-    console.log(`Local Agent started — polling ${cfg.serverUrl} as device #${cfg.deviceId} (${cfg.deviceName})`);
+    console.log(`Local Agent v${(0, version_1.agentVersion)()} started — polling ${cfg.serverUrl} as device #${cfg.deviceId} (${cfg.deviceName})`);
     while (!signal.aborted) {
         let job = null;
         try {

package/dist/src/version.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * The running agent's version.
+ *
+ * Read from the package manifest at runtime (rather than a compile-time import)
+ * so both the `npx @q-agent/agent` package and the packaged desktop bundle report
+ * the *actual* installed build — the number one signal when diagnosing a stale
+ * `npx` cache serving an old agent. Compiled output lives at `dist/src/`, so the
+ * manifest is two levels up. Any failure falls back to `"unknown"` — a missing
+ * version must never crash the CLI.
+ */
+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.agentVersion = agentVersion;
+const path = __importStar(require("path"));
+let cached = null;
+/** The agent's semver (e.g. "0.1.6"), or "unknown" if the manifest can't be read. */
+function agentVersion() {
+    if (cached !== null)
+        return cached;
+    try {
+        const manifest = require(path.join(__dirname, "..", "..", "package.json"));
+        cached = manifest.version || "unknown";
+    }
+    catch {
+        cached = "unknown";
+    }
+    return cached;
+}

package/dist/test/api.test.js

@@ -135,18 +135,37 @@ function mockFetch(handler) {
     const body = JSON.parse(calls[0].init.body);
     strict_1.default.deepEqual(body, { passed: 3, failed: 1, log: "tail" });
 });
-(0, node_test_1.test)("postHealFix posts the attempt to /agent/heal/{caseId}/fix and returns the action", async () => {
-    mockFetch(() => Response.json({ action: "fixed", code: "// fixed", diff: "@@" }));
+(0, node_test_1.test)("postHealFix starts a job then polls /agent/heal/{caseId}/fix/{jobId} for the action", async () => {
+    // Async flow (#313): POST starts the job (returns jobId), GET polls until done.
+    mockFetch((url, init) => {
+        if (init.method === "POST")
+            return Response.json({ jobId: "job-1", status: "running" });
+        return Response.json({ status: "done", result: { action: "fixed", code: "// fixed", diff: "@@" } });
+    });
     const out = await api.postHealFix(cfg, 99, {
         currentCode: "// old", error: "boom", output: "tail", domDistilled: { path: "/x" }, attempt: 2,
     });
+    // First call: POST to start with the attempt body.
     strict_1.default.equal(calls[0].url, "http://127.0.0.1:8787/agent/heal/99/fix");
     strict_1.default.equal(calls[0].init.method, "POST");
     const body = JSON.parse(calls[0].init.body);
     strict_1.default.deepEqual(body, { currentCode: "// old", error: "boom", output: "tail", domDistilled: { path: "/x" }, attempt: 2 });
+    // Second call: GET poll on the returned job id.
+    strict_1.default.equal(calls[1].url, "http://127.0.0.1:8787/agent/heal/99/fix/job-1");
+    strict_1.default.equal(calls[1].init.method, "GET");
     strict_1.default.equal(out.action, "fixed");
     strict_1.default.equal(out.code, "// fixed");
 });
+(0, node_test_1.test)("postHealFix surfaces a server-side error job", async () => {
+    mockFetch((url, init) => {
+        if (init.method === "POST")
+            return Response.json({ jobId: "job-2", status: "running" });
+        return Response.json({ status: "error", error: "Claude timed out" });
+    });
+    await strict_1.default.rejects(() => api.postHealFix(cfg, 99, {
+        currentCode: "// old", error: "boom", output: "", domDistilled: null, attempt: 1,
+    }), /Claude timed out/);
+});
 (0, node_test_1.test)("postHealFinalize posts the outcome to /agent/heal/{caseId}/finalize", async () => {
     mockFetch(() => new Response(null, { status: 200 }));
     await api.postHealFinalize(cfg, 99, { finalStatus: "pass", finalCode: "// x", attempts: [] });
@@ -163,3 +182,15 @@ function mockFetch(handler) {
     const body = JSON.parse(calls[0].init.body);
     strict_1.default.deepEqual(body, { code: "PAIR123", name: "my-laptop" });
 });
+(0, node_test_1.test)("fetchWithTimeout aborts a stalled request once the timeout elapses", async () => {
+    // A server that never responds but honors the abort signal.
+    mockFetch((_u, init) => new Promise((_resolve, reject) => {
+        init.signal.addEventListener("abort", () => reject(new Error("aborted")));
+    }));
+    await strict_1.default.rejects(api.fetchWithTimeout("http://127.0.0.1:8787/slow", { method: "POST" }, 20));
+});
+(0, node_test_1.test)("fetchWithTimeout returns the response when it resolves before the timeout", async () => {
+    mockFetch(() => new Response(null, { status: 200 }));
+    const res = await api.fetchWithTimeout("http://127.0.0.1:8787/ok", {}, 1000);
+    strict_1.default.equal(res.status, 200);
+});

package/dist/test/version.test.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Tests for the runtime version lookup (`src/version.ts`) — the agent must be
+ * able to report its actual installed build (for `--version` and the startup
+ * banner), which is the key signal when diagnosing a stale npx cache.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = require("node:test");
+const version_1 = require("../src/version");
+(0, node_test_1.test)("agentVersion reads a real semver from the package manifest (not 'unknown')", () => {
+    const v = (0, version_1.agentVersion)();
+    strict_1.default.notEqual(v, "unknown", "expected the manifest version to resolve at runtime");
+    strict_1.default.match(v, /^\d+\.\d+\.\d+/, `expected semver, got ${v}`);
+});
+(0, node_test_1.test)("agentVersion is stable across calls (cached)", () => {
+    strict_1.default.equal((0, version_1.agentVersion)(), (0, version_1.agentVersion)());
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@q-agent/agent",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Q-Agent Local Agent — claims execution jobs from the Q-Agent server and runs Playwright locally, so manual login/MFA happens on the user's own machine and session credentials never leave it.",
   "license": "UNLICENSED",
   "bin": {