@q-agent/agent 0.1.13 → 0.1.15

package/dist/src/api.js

@@ -56,6 +56,9 @@ exports.postExploreDecide = postExploreDecide;
 exports.postExploreEvent = postExploreEvent;
 exports.postExploreFinalize = postExploreFinalize;
 exports.postComplete = postComplete;
+exports.claimNextAuthoring = claimNextAuthoring;
+exports.postAuthoringEvent = postAuthoringEvent;
+exports.postAuthoringFinalize = postAuthoringFinalize;
 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 {
@@ -288,3 +291,33 @@ async function postComplete(cfg, executionId, body) {
     });
     await throwIfNotOk(res);
 }
+/** Claim the next queued authoring session, or null (204) if none. */
+async function claimNextAuthoring(cfg) {
+    const res = await fetch(`${cfg.serverUrl}/agent/authoring/next`, {
+        method: "POST",
+        headers: authHeaders(cfg.deviceToken),
+    });
+    if (res.status === 204)
+        return null;
+    await throwIfNotOk(res);
+    return (await res.json());
+}
+/** Relay an authoring progress event onto the run's WebSocket (server-side). */
+async function postAuthoringEvent(cfg, sessionId, event, payload) {
+    const res = await fetch(`${cfg.serverUrl}/agent/authoring/${sessionId}/events`, {
+        method: "POST",
+        headers: { ...authHeaders(cfg.deviceToken), "Content-Type": "application/json" },
+        body: JSON.stringify({ event, payload }),
+    });
+    await throwIfNotOk(res);
+}
+/** Finalize an authoring session: the server gates + persists the authored spec
+ * and KB-merges the runtime-verified discovery. */
+async function postAuthoringFinalize(cfg, sessionId, body) {
+    const res = await fetchWithTimeout(`${cfg.serverUrl}/agent/authoring/${sessionId}/finalize`, {
+        method: "POST",
+        headers: { ...authHeaders(cfg.deviceToken), "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    }, HEAL_FIX_REQUEST_TIMEOUT_MS);
+    await throwIfNotOk(res);
+}

package/dist/src/paths.js

@@ -42,6 +42,7 @@ exports.agentNodeModules = agentNodeModules;
 exports.playwrightCli = playwrightCli;
 exports.vendorCaptureScript = vendorCaptureScript;
 exports.vendorExploreScript = vendorExploreScript;
+exports.vendorAuthoringScript = vendorAuthoringScript;
 /**
  * Runtime path resolution for the agent's child processes (Playwright CLI +
  * the headed-login capture script), working in three layouts:
@@ -163,3 +164,16 @@ function vendorExploreScript() {
         throw new Error("explore_session.cjs not found — the agent package is missing vendor/");
     return found;
 }
+/** The vendored live-authoring Chrome launcher (`authoring_browser.cjs`, #403).
+ * Uses only Node built-ins (no Playwright), so it runs with a bare `node`. */
+function vendorAuthoringScript() {
+    const root = packagedRoot();
+    const found = firstExisting([
+        ...(root ? [path.join(root, "vendor", "authoring_browser.cjs")] : []),
+        path.join(__dirname, "..", "..", "vendor", "authoring_browser.cjs"),
+        path.join(__dirname, "..", "vendor", "authoring_browser.cjs"),
+    ]);
+    if (!found)
+        throw new Error("authoring_browser.cjs not found — the agent package is missing vendor/");
+    return found;
+}

package/dist/src/runner.js

@@ -44,9 +44,11 @@ exports.killActiveChild = killActiveChild;
 exports.processJob = processJob;
 exports.runExplorationLoop = runExplorationLoop;
 exports.processExplorationJob = processExplorationJob;
+exports.processAuthoringJob = processAuthoringJob;
 exports.runAgentLoop = runAgentLoop;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
+const net = __importStar(require("net"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const readline = __importStar(require("readline"));
@@ -919,6 +921,187 @@ async function processExplorationJob(cfg, session) {
  * Long-poll loop: claim → process → repeat, backing off `IDLE_POLL_MS`
  * between empty claims. Runs until `signal.aborted`.
  */
+// --- Live authoring (#403) — drive `claude` + browser-harness locally ----------
+const AUTHORING_CDP_READY_TIMEOUT_MS = 30_000;
+/** Grab a free localhost TCP port for the dedicated Chrome's CDP endpoint. */
+async function getFreePort() {
+    return new Promise((resolve, reject) => {
+        const srv = net.createServer();
+        srv.on("error", reject);
+        srv.listen(0, "127.0.0.1", () => {
+            const addr = srv.address();
+            const port = typeof addr === "object" && addr ? addr.port : 0;
+            srv.close(() => (port ? resolve(port) : reject(new Error("no free port"))));
+        });
+    });
+}
+/** Poll Chrome's /json/version until it responds (CDP is up) or we time out. */
+async function waitForCdp(port, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const r = await fetch(`http://127.0.0.1:${port}/json/version`);
+            if (r.ok)
+                return true;
+        }
+        catch {
+            /* endpoint not up yet */
+        }
+        await new Promise((r) => setTimeout(r, 300));
+    }
+    return false;
+}
+/**
+ * Author one spec live on this machine (#403): launch the dedicated,
+ * pre-authenticated Chrome (vendored launcher), point the local `browser-harness`
+ * at it via BU_CDP_URL, and run the local `claude` agentically (prompts composed
+ * server-side) to perform the case and write `<specFilename>` + `discovered.json`
+ * into a temp workspace. Posts the result back for the server to gate + persist.
+ * Requires `claude` + `browser-harness` on the agent machine's PATH and a
+ * pre-authenticated `browser-profile` for the origin (from manual-login capture).
+ */
+async function processAuthoringJob(cfg, job) {
+    let origin = job.origin;
+    if (!origin && job.baseUrl) {
+        try {
+            origin = new URL(job.baseUrl).origin;
+        }
+        catch {
+            origin = "";
+        }
+    }
+    const sess = origin ? (0, session_1.sessionPathsForOrigin)(origin) : null;
+    const profileDir = sess ? path.join(sess.dir, "browser-profile") : "";
+    const finalize = async (code, discovered, summary, ok) => {
+        await api
+            .postAuthoringFinalize(cfg, job.sessionId, {
+            code,
+            discovered: discovered || {},
+            summary,
+            ok,
+        })
+            .catch((err) => console.error("postAuthoringFinalize failed:", err));
+    };
+    if (!profileDir || !fs.existsSync(profileDir)) {
+        await finalize("", { routes: [], selectors: [] }, "No authenticated browser profile for this origin — capture a manual login first.", false);
+        return;
+    }
+    const workDir = fs.mkdtempSync(path.join(os.tmpdir(), "qagent-authoring-"));
+    const port = await getFreePort();
+    let launcher = null;
+    let claude = null;
+    try {
+        await api
+            .postAuthoringEvent(cfg, job.sessionId, "authoring.progress", {
+            case: job.caseId, phase: "launching", message: "Starting authenticated browser",
+        })
+            .catch(() => { });
+        // 1) Dedicated pre-auth Chrome (vendored launcher — Node built-ins only).
+        launcher = (0, child_process_1.spawn)((0, paths_1.nodeBin)(), [(0, paths_1.vendorAuthoringScript)(), job.baseUrl, String(port), profileDir], {
+            env: { ...process.env, ...(0, paths_1.childNodeEnv)() },
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        activeChild = launcher;
+        let launcherErr = "";
+        launcher.stderr?.on("data", (d) => { launcherErr += String(d); });
+        if (!(await waitForCdp(port, AUTHORING_CDP_READY_TIMEOUT_MS))) {
+            await finalize("", { routes: [], selectors: [] }, `Chrome CDP did not come up on port ${port}. ${launcherErr.trim()}`.trim(), false);
+            return;
+        }
+        await api
+            .postAuthoringEvent(cfg, job.sessionId, "authoring.progress", {
+            case: job.caseId, phase: "driving", message: "Driving the app live with browser-harness",
+        })
+            .catch(() => { });
+        // 2) Local agentic Claude drives browser-harness (BU_CDP_URL → our Chrome),
+        //    writing the spec + discovered.json into workDir. System prompt via a
+        //    file (avoids a huge argv); task prompt via stdin.
+        const systemFile = path.join(workDir, "system-prompt.txt");
+        fs.writeFileSync(systemFile, job.systemPrompt, "utf-8");
+        // On Windows `claude` is a .cmd shim, which Node can only launch via a shell;
+        // quote the path-bearing args there. On POSIX we spawn without a shell.
+        const useShell = process.platform === "win32";
+        const q = (s) => (useShell ? `"${s}"` : s);
+        const claudeArgs = [
+            "-p",
+            "--output-format", "json",
+            "--model", job.model,
+            "--append-system-prompt-file", q(systemFile),
+            "--allowedTools", "Bash", "Read", "Write", "Glob", "Grep",
+            "--dangerously-skip-permissions",
+            "--add-dir", q(workDir),
+            "--max-budget-usd", String(job.maxBudgetUsd),
+        ];
+        claude = (0, child_process_1.spawn)("claude", claudeArgs, {
+            cwd: workDir,
+            env: { ...process.env, BU_CDP_URL: `http://127.0.0.1:${port}` },
+            stdio: ["pipe", "pipe", "pipe"],
+            shell: useShell,
+        });
+        activeChild = claude;
+        let cout = "";
+        let cerr = "";
+        claude.stdout?.on("data", (d) => { cout += String(d); });
+        claude.stderr?.on("data", (d) => { cerr += String(d); });
+        try {
+            claude.stdin?.write(job.taskPrompt);
+            claude.stdin?.end();
+        }
+        catch { }
+        await new Promise((resolve) => {
+            claude.on("close", () => resolve());
+            claude.on("error", (e) => { cerr += `\nclaude spawn error: ${e.message}`; resolve(); });
+        });
+        // 3) Read emitted artifacts.
+        const specPath = path.join(workDir, job.specFilename);
+        const sidecarPath = path.join(workDir, job.sidecarFilename || "discovered.json");
+        const code = fs.existsSync(specPath) ? fs.readFileSync(specPath, "utf-8") : "";
+        let discovered = { routes: [], selectors: [] };
+        if (fs.existsSync(sidecarPath)) {
+            try {
+                discovered = JSON.parse(fs.readFileSync(sidecarPath, "utf-8"));
+            }
+            catch { /* keep default */ }
+        }
+        let summary = "";
+        try {
+            summary = JSON.parse(cout).result || "";
+        }
+        catch {
+            summary = (cout || cerr).slice(0, 800);
+        }
+        if (!code.trim() && !summary)
+            summary = "Live authoring produced no spec.";
+        const ok = code.trim().length > 0;
+        await api
+            .postAuthoringEvent(cfg, job.sessionId, "authoring.progress", {
+            case: job.caseId, phase: ok ? "done" : "failed", message: summary.slice(0, 400),
+        })
+            .catch(() => { });
+        await finalize(code, discovered, summary, ok);
+    }
+    finally {
+        try {
+            claude?.kill();
+        }
+        catch { }
+        // Closing the launcher's stdin tells it to kill Chrome (cross-platform).
+        try {
+            launcher?.stdin?.end();
+        }
+        catch { }
+        try {
+            launcher?.kill();
+        }
+        catch { }
+        if (activeChild === launcher || activeChild === claude)
+            activeChild = null;
+        try {
+            fs.rmSync(workDir, { recursive: true, force: true });
+        }
+        catch { }
+    }
+}
 async function runAgentLoop(cfg, signal) {
     if (!(await (0, ensureBrowser_1.ensureChromium)())) {
         console.error("Chromium is required to run tests — aborting.");
@@ -967,6 +1150,28 @@ async function runAgentLoop(cfg, signal) {
                 }
                 continue;
             }
+            // No exploration either — check for a queued live-authoring session (#403):
+            // drive `claude` + browser-harness locally to author a spec from the real app.
+            let authoring = null;
+            try {
+                authoring = await api.claimNextAuthoring(cfg);
+            }
+            catch (err) {
+                console.error("Authoring claim failed:", err.message);
+            }
+            if (authoring) {
+                console.log(`Claimed authoring ${authoring.sessionId} (case ${authoring.caseId}, ${authoring.baseUrl})`);
+                (0, bus_1.emit)("authoring-claimed", { sessionId: authoring.sessionId, caseId: authoring.caseId });
+                try {
+                    await processAuthoringJob(cfg, authoring);
+                    console.log(`Authoring ${authoring.sessionId} complete`);
+                }
+                catch (err) {
+                    console.error(`Authoring ${authoring.sessionId} crashed:`, err);
+                    (0, bus_1.emit)("error", { message: `Authoring ${authoring.sessionId} crashed: ${err.message}` });
+                }
+                continue;
+            }
             await new Promise((r) => setTimeout(r, IDLE_POLL_MS));
             continue;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@q-agent/agent",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "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": {

package/vendor/authoring_browser.cjs

@@ -0,0 +1,128 @@
+// Long-lived, pre-authenticated automation Chrome for live spec-authoring (#400).
+// Args: baseUrl, port, profileDir.
+//
+// Launches a real Chrome/Edge (NOT via Playwright's launcher, so no automation
+// fingerprint) on a FIXED --remote-debugging-port using a DEDICATED, persistent
+// --user-data-dir. A dedicated non-default profile is deliberate: it lets
+// browser-harness attach over CDP (BU_CDP_URL=http://127.0.0.1:<port>) without
+// the Chrome "Allow remote debugging" popup / default-profile lockdown (see
+// browser_harness/daemon.py:128-131,148). Auth is inherited from the persistent
+// profile — reuse the capture `browser-profile` dir (already logged in via the
+// manual-login capture flow), so the session is present without any injection.
+//
+// Unlike capture_auth.cjs (a short snapshot loop) this stays ALIVE for the whole
+// authoring session and only tears Chrome down when the parent closes our stdin
+// (cross-platform cleanup), on SIGTERM/SIGINT, or when Chrome exits on its own.
+//
+// Vendored copy of api/app/services/pw_scripts/authoring_browser.cjs — keep in
+// sync (the agent runs this locally; the server runs the api copy in Docker).
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const [, , baseUrl, portArg, profileDir] = process.argv;
+const PORT = parseInt(portArg, 10);
+
+process.on('unhandledRejection', (e) => console.error('authoring_browser unhandledRejection:', e && (e.message || e)));
+process.on('uncaughtException', (e) => console.error('authoring_browser uncaughtException:', e && (e.message || e)));
+
+function findBrowser() {
+  // Explicit override wins (the Docker image sets QAGENT_CHROME_BIN=/usr/bin/chromium).
+  const c = [
+    process.env.QAGENT_CHROME_BIN,
+    // Linux / container (Debian chromium package + common Chrome paths).
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+    '/usr/bin/google-chrome',
+    '/usr/bin/google-chrome-stable',
+    // Windows host (native dev).
+    'C:/Program Files/Google/Chrome/Application/chrome.exe',
+    'C:/Program Files (x86)/Google/Chrome/Application/chrome.exe',
+    (process.env.LOCALAPPDATA || '') + '/Google/Chrome/Application/chrome.exe',
+    'C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe',
+    'C:/Program Files/Microsoft/Edge/Application/msedge.exe',
+  ];
+  for (const p of c) { try { if (p && fs.existsSync(p)) return p; } catch {} }
+  return null;
+}
+
+// Headless container flags: a Linux host with no X display can't run headed
+// Chrome, and Chrome-as-root in a container needs --no-sandbox; the small
+// default /dev/shm makes --disable-dev-shm-usage necessary. On a real desktop
+// (Windows, or Linux with DISPLAY) we launch headed so the operator can watch
+// and MSAL/federated auth behaves like a normal browser.
+function containerFlags() {
+  const headless = process.platform !== 'win32' && !process.env.DISPLAY;
+  return headless
+    ? ['--headless=new', '--no-sandbox', '--disable-dev-shm-usage', '--disable-gpu']
+    : [];
+}
+
+async function waitForCDP(port, timeoutMs) {
+  const end = Date.now() + timeoutMs;
+  while (Date.now() < end) {
+    try { const r = await fetch(`http://127.0.0.1:${port}/json/version`); if (r.ok) return true; } catch {}
+    await new Promise((r) => setTimeout(r, 300));
+  }
+  return false;
+}
+
+(async () => {
+  if (!PORT || Number.isNaN(PORT)) { console.error('authoring_browser: invalid port', portArg); process.exit(1); }
+  const exe = findBrowser();
+  if (!exe) { console.error('authoring_browser: no Chrome/Edge found on this machine'); process.exit(1); }
+  fs.mkdirSync(profileDir, { recursive: true });
+
+  // Same third-party-cookie seed as capture: fresh profiles break the MSAL/Entra
+  // federation redirects. No-op when the profile was already seeded by capture.
+  try {
+    const defDir = path.join(profileDir, 'Default');
+    fs.mkdirSync(defDir, { recursive: true });
+    const prefsPath = path.join(defDir, 'Preferences');
+    if (!fs.existsSync(prefsPath)) {
+      fs.writeFileSync(prefsPath, JSON.stringify({
+        profile: { cookie_controls_mode: 0, block_third_party_cookies: false,
+          default_content_setting_values: { cookies: 1 } },
+      }));
+    }
+  } catch (e) { console.error('pref seed failed:', e && e.message); }
+
+  const child = spawn(exe, [
+    `--remote-debugging-port=${PORT}`,
+    `--user-data-dir=${profileDir}`,
+    '--no-first-run', '--no-default-browser-check', '--new-window',
+    ...containerFlags(),
+    baseUrl,
+  ], { detached: false, stdio: 'ignore' });
+  console.error('authoring_browser launched:', exe, 'port', PORT);
+
+  if (!(await waitForCDP(PORT, 20000))) {
+    console.error('authoring_browser: CDP endpoint never came up on port', PORT);
+    try { child.kill(); } catch {}
+    process.exit(1);
+  }
+
+  // Signal readiness on stdout so the parent can proceed (it also polls
+  // /json/version independently). The daemon resolves BU_CDP_URL to the WS.
+  console.log(`AUTHORING_BROWSER_READY ${PORT}`);
+
+  let shuttingDown = false;
+  const shutdown = (code) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    try { child.kill(); } catch {}
+    process.exit(code || 0);
+  };
+
+  // Cleanup triggers: parent closes our stdin (works cross-platform, incl.
+  // Windows where a terminate() won't run signal handlers), OS signals, or
+  // Chrome exiting on its own.
+  child.on('exit', () => shutdown(0));
+  process.stdin.on('end', () => shutdown(0));
+  process.stdin.on('close', () => shutdown(0));
+  process.on('SIGTERM', () => shutdown(0));
+  process.on('SIGINT', () => shutdown(0));
+  process.stdin.resume();
+})().catch((e) => {
+  console.error('authoring_browser fatal:', e && (e.stack || e.message || e));
+  process.exit(1);
+});