@q-agent/agent 0.1.16 → 0.1.18

package/dist/src/ensureTooling.js

@@ -0,0 +1,180 @@
+"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.browserHarnessBinDir = browserHarnessBinDir;
+exports.ensureBrowserHarness = ensureBrowserHarness;
+/**
+ * Ensure the `browser-harness` CLI is available for live spec-authoring (#400),
+ * provisioning it on first run so the user never installs anything by hand —
+ * the same "download once, then it's ready" contract as `ensureChromium`.
+ *
+ * browser-harness is a Python CLI, so we can't just add an npm dep. Instead we
+ * self-provision it with `uv` (a single static binary that also installs its own
+ * Python): find `uv` on PATH, else download the platform build once into the
+ * agent's config dir, then `uv tool install browser-harness` into a known bin dir
+ * we can resolve and prepend to the authoring subprocess PATH.
+ *
+ * Everything is best-effort and heavily logged: a failure returns `{ok:false}`
+ * with a message the caller surfaces, rather than throwing.
+ */
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("./config");
+const TOOLS_DIR = path.join((0, config_1.configDir)(), "tools");
+const UV_DIR = path.join(TOOLS_DIR, "uv"); // downloaded uv binary lives here
+const TOOL_BIN = path.join(TOOLS_DIR, "bin"); // UV_TOOL_BIN_DIR — browser-harness lands here
+const TOOL_DATA = path.join(TOOLS_DIR, "data"); // UV_TOOL_DIR — tool venvs
+const isWin = process.platform === "win32";
+const exe = (n) => (isWin ? `${n}.exe` : n);
+/** Directory holding the installed `browser-harness` executable (prepended to the
+ * authoring subprocess PATH so the agent's `claude` can run `browser-harness`). */
+function browserHarnessBinDir() {
+    return TOOL_BIN;
+}
+/** Run a command to completion, returning its exit code (null on spawn error).
+ * Inherits stdio so first-run downloads/installs are visible in the agent log. */
+function run(cmd, args, env) {
+    return new Promise((resolve) => {
+        const child = (0, child_process_1.spawn)(cmd, args, { stdio: "inherit", env: { ...process.env, ...env } });
+        child.on("close", resolve);
+        child.on("error", () => resolve(null));
+    });
+}
+/** True if `browser-harness` is already runnable (in our bin dir or on PATH). */
+async function harnessPresent() {
+    if (fs.existsSync(path.join(TOOL_BIN, exe("browser-harness"))))
+        return true;
+    const code = await run(exe("browser-harness"), ["--version"]);
+    return code === 0;
+}
+/** Resolve a usable `uv`: our downloaded copy, then PATH, else download it once. */
+async function ensureUv() {
+    const local = path.join(UV_DIR, exe("uv"));
+    if (fs.existsSync(local))
+        return local;
+    if ((await run(exe("uv"), ["--version"])) === 0)
+        return exe("uv"); // on PATH
+    const asset = uvAsset();
+    if (!asset) {
+        console.error(`ensureUv: unsupported platform ${process.platform}/${process.arch}`);
+        return null;
+    }
+    fs.mkdirSync(UV_DIR, { recursive: true });
+    const url = `https://github.com/astral-sh/uv/releases/latest/download/${asset}`;
+    const archive = path.join(UV_DIR, asset);
+    console.log(`Downloading uv (one-time) from ${url} ...`);
+    try {
+        const res = await fetch(url);
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        fs.writeFileSync(archive, Buffer.from(await res.arrayBuffer()));
+    }
+    catch (e) {
+        console.error("ensureUv: download failed:", e.message);
+        return null;
+    }
+    // Extract with the system `tar` (bsdtar on Win10+ handles .zip too; unix uses .tar.gz).
+    if ((await run("tar", ["-xf", archive, "-C", UV_DIR])) !== 0) {
+        console.error("ensureUv: extract failed (need `tar` on PATH)");
+        return null;
+    }
+    // Archives may nest the binary in a subdir — find it.
+    const found = findFile(UV_DIR, exe("uv"));
+    if (found && found !== local) {
+        try {
+            fs.copyFileSync(found, local);
+            fs.chmodSync(local, 0o755);
+        }
+        catch { /* best-effort */ }
+    }
+    return fs.existsSync(local) ? local : found;
+}
+/** The uv release asset name for this platform/arch, or null if unsupported. */
+function uvAsset() {
+    const a = process.arch;
+    if (isWin)
+        return a === "arm64" ? "uv-aarch64-pc-windows-msvc.zip" : "uv-x86_64-pc-windows-msvc.zip";
+    if (process.platform === "darwin")
+        return a === "arm64" ? "uv-aarch64-apple-darwin.tar.gz" : "uv-x86_64-apple-darwin.tar.gz";
+    if (process.platform === "linux")
+        return a === "arm64" ? "uv-aarch64-unknown-linux-gnu.tar.gz" : "uv-x86_64-unknown-linux-gnu.tar.gz";
+    return null;
+}
+/** Shallow recursive search for a file named `name` under `dir`. */
+function findFile(dir, name) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            const hit = findFile(full, name);
+            if (hit)
+                return hit;
+        }
+        else if (entry.name === name) {
+            return full;
+        }
+    }
+    return null;
+}
+/**
+ * Ensure `browser-harness` is installed. Returns the bin dir to prepend to PATH.
+ * Fast no-op once present; on first run downloads uv (if needed) and installs
+ * browser-harness (uv fetches its own Python). Never throws.
+ */
+async function ensureBrowserHarness() {
+    try {
+        if (await harnessPresent())
+            return { ok: true, binDir: TOOL_BIN };
+        const uv = await ensureUv();
+        if (!uv) {
+            return { ok: false, binDir: TOOL_BIN, error: "could not obtain `uv` to install browser-harness" };
+        }
+        fs.mkdirSync(TOOL_BIN, { recursive: true });
+        fs.mkdirSync(TOOL_DATA, { recursive: true });
+        console.log("Installing browser-harness (one-time) via uv ...");
+        const code = await run(uv, ["tool", "install", "--force", "browser-harness"], {
+            UV_TOOL_BIN_DIR: TOOL_BIN,
+            UV_TOOL_DIR: TOOL_DATA,
+        });
+        if (code !== 0 || !(await harnessPresent())) {
+            return { ok: false, binDir: TOOL_BIN, error: "browser-harness install via uv failed" };
+        }
+        console.log("browser-harness ready.");
+        return { ok: true, binDir: TOOL_BIN };
+    }
+    catch (e) {
+        return { ok: false, binDir: TOOL_BIN, error: e.message };
+    }
+}

package/dist/src/paths.js

@@ -40,6 +40,7 @@ exports.packagedRoot = packagedRoot;
 exports.nodeBin = nodeBin;
 exports.agentNodeModules = agentNodeModules;
 exports.playwrightCli = playwrightCli;
+exports.claudeCli = claudeCli;
 exports.vendorCaptureScript = vendorCaptureScript;
 exports.vendorExploreScript = vendorExploreScript;
 exports.vendorAuthoringScript = vendorAuthoringScript;
@@ -140,6 +141,31 @@ function playwrightCli() {
     // 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 bundled Claude Code CLI (`@anthropic-ai/claude-code`), so no separate
+ * `claude` install / PATH shim is needed (#400 — live-authoring drives it on the
+ * agent). NOTE: the package ships a NATIVE binary (`bin/claude[.exe]`), not a JS
+ * entry — spawn it DIRECTLY (not via node). Resolves the package's `bin` entry
+ * across source/npx and the packaged bundle. */
+function claudeCli() {
+    const relFromDir = (dir) => {
+        const fallback = path.join(dir, "bin", process.platform === "win32" ? "claude.exe" : "claude");
+        try {
+            const bin = require(path.join(dir, "package.json")).bin;
+            const rel = typeof bin === "string" ? bin : bin ? Object.values(bin)[0] : null;
+            return rel ? path.join(dir, rel) : fallback;
+        }
+        catch {
+            return fallback;
+        }
+    };
+    const root = packagedRoot();
+    if (root) {
+        const dir = path.join(root, "node_modules", "@anthropic-ai", "claude-code");
+        if (fs.existsSync(dir))
+            return relFromDir(dir);
+    }
+    return relFromDir(path.dirname(require.resolve("@anthropic-ai/claude-code/package.json")));
+}
 /** The vendored headed-login capture script (`capture_auth.cjs`). */
 function vendorCaptureScript() {
     const root = packagedRoot();

package/dist/src/runner.js

@@ -56,6 +56,7 @@ const api = __importStar(require("./api"));
 const bus_1 = require("./bus");
 const ensureBrowser_1 = require("./ensureBrowser");
 const paths_1 = require("./paths");
+const ensureTooling_1 = require("./ensureTooling");
 const playwrightConfig_1 = require("./playwrightConfig");
 const report_1 = require("./report");
 const session_1 = require("./session");
@@ -935,22 +936,6 @@ async function getFreePort() {
         });
     });
 }
-/** 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`
@@ -996,16 +981,37 @@ async function processAuthoringJob(cfg, job) {
             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"],
-        });
+        // 1) Dedicated pre-auth Chrome (vendored launcher). Pass the saved
+        //    sessionStorage path so the launcher replays MSAL/SPA tokens into the
+        //    Chrome browser-harness attaches to; NODE_PATH lets the launcher resolve
+        //    the bundled Playwright it uses for that replay. Wait for its READY line
+        //    (emitted AFTER the replay is armed) so browser-harness never navigates
+        //    before the session is restored.
+        const nm = (0, paths_1.agentNodeModules)();
+        launcher = (0, child_process_1.spawn)((0, paths_1.nodeBin)(), [(0, paths_1.vendorAuthoringScript)(), job.baseUrl, String(port), profileDir, sess ? sess.sessionStoragePath : ""], { env: nodePathEnv(nm), 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);
+        const ready = await new Promise((resolve) => {
+            const to = setTimeout(() => resolve(false), AUTHORING_CDP_READY_TIMEOUT_MS);
+            launcher.stdout?.on("data", (d) => {
+                if (String(d).includes("AUTHORING_BROWSER_READY")) {
+                    clearTimeout(to);
+                    resolve(true);
+                }
+            });
+            launcher.on("exit", () => { clearTimeout(to); resolve(false); });
+        });
+        if (!ready) {
+            await finalize("", { routes: [], selectors: [] }, `Authoring browser did not become ready on port ${port}. ${launcherErr.trim()}`.trim(), false);
+            return;
+        }
+        // Ensure browser-harness is installed (first run provisions it via uv). Its
+        // bin dir is prepended to the claude subprocess PATH so `browser-harness`
+        // resolves for the Bash calls Claude makes.
+        const bh = await (0, ensureTooling_1.ensureBrowserHarness)();
+        if (!bh.ok) {
+            await finalize("", { routes: [], selectors: [] }, `browser-harness unavailable: ${bh.error || "unknown"}`, false);
             return;
         }
         await api
@@ -1015,28 +1021,51 @@ async function processAuthoringJob(cfg, job) {
             .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.
+        //    file (avoids a huge argv); task prompt via stdin. Invoked as
+        //    `nodeBin() <bundled claude cli.js>` so no `claude` install/PATH shim is
+        //    needed (and no Windows .cmd shell hack).
         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);
+        // Use the app's saved Claude credential (shipped in the claim) so we don't
+        // need a separate `claude login` on this machine. Write it locked-down into
+        // the temp workspace (removed with workDir); empty ⇒ fall back to the agent's
+        // own login (no CLAUDE_CONFIG_DIR override).
+        let claudeConfigDir = "";
+        if (job.claudeCredentials) {
+            claudeConfigDir = path.join(workDir, ".claude-config");
+            fs.mkdirSync(claudeConfigDir, { recursive: true });
+            const credFile = path.join(claudeConfigDir, ".credentials.json");
+            fs.writeFileSync(credFile, job.claudeCredentials, "utf-8");
+            try {
+                fs.chmodSync(credFile, 0o600);
+            }
+            catch { /* best-effort on Windows */ }
+        }
         const claudeArgs = [
             "-p",
             "--output-format", "json",
             "--model", job.model,
-            "--append-system-prompt-file", q(systemFile),
+            "--append-system-prompt-file", systemFile,
             "--allowedTools", "Bash", "Read", "Write", "Glob", "Grep",
             "--dangerously-skip-permissions",
-            "--add-dir", q(workDir),
+            "--add-dir", workDir,
             "--max-budget-usd", String(job.maxBudgetUsd),
         ];
-        claude = (0, child_process_1.spawn)("claude", claudeArgs, {
+        // Prepend browser-harness's bin dir to PATH (overwrite the same-case key so
+        // Windows doesn't end up with both Path and PATH).
+        const pathVar = Object.keys(process.env).find((k) => k.toLowerCase() === "path") || "PATH";
+        const claudeEnv = {
+            ...process.env,
+            BU_CDP_URL: `http://127.0.0.1:${port}`,
+            [pathVar]: `${bh.binDir}${path.delimiter}${process.env[pathVar] || ""}`,
+        };
+        if (claudeConfigDir)
+            claudeEnv.CLAUDE_CONFIG_DIR = claudeConfigDir;
+        // Spawn the native `claude` binary directly (it is not a JS entry).
+        claude = (0, child_process_1.spawn)((0, paths_1.claudeCli)(), claudeArgs, {
             cwd: workDir,
-            env: { ...process.env, BU_CDP_URL: `http://127.0.0.1:${port}` },
+            env: claudeEnv,
             stdio: ["pipe", "pipe", "pipe"],
-            shell: useShell,
         });
         activeChild = claude;
         let cout = "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@q-agent/agent",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "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": {
@@ -32,6 +32,7 @@
     "dist:desktop": "npm run build && electron-builder --win"
   },
   "dependencies": {
+    "@anthropic-ai/claude-code": "^2.1.0",
     "@playwright/test": "^1.61.1",
     "commander": "^12.1.0",
     "electron-updater": "^6.3.9",

package/vendor/authoring_browser.cjs

@@ -1,5 +1,5 @@
 // Long-lived, pre-authenticated automation Chrome for live spec-authoring (#400).
-// Args: baseUrl, port, profileDir.
+// Args: baseUrl, port, profileDir, [sessionStoragePath].
 //
 // Launches a real Chrome/Edge (NOT via Playwright's launcher, so no automation
 // fingerprint) on a FIXED --remote-debugging-port using a DEDICATED, persistent
@@ -8,7 +8,16 @@
 // 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.
+// manual-login capture flow), so cookies + localStorage are present.
+//
+// sessionStorage (where MSAL/SPA auth tokens live) is NEVER persisted to a Chrome
+// profile on disk, so a profile-only relaunch lands unauthenticated for such apps.
+// When a `sessionStoragePath` is given AND Playwright is resolvable (agent side —
+// the API container ships no Playwright and passes no path), we attach over CDP
+// and register an init script that replays the saved sessionStorage for the
+// matching origin before app code runs — the same trick the run/explore paths use.
+// The Playwright connection is kept alive for the whole session so the init-script
+// registration persists for the tabs browser-harness opens.
 //
 // 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
@@ -19,7 +28,7 @@
 const { spawn } = require('child_process');
 const fs = require('fs');
 const path = require('path');
-const [, , baseUrl, portArg, profileDir] = process.argv;
+const [, , baseUrl, portArg, profileDir, sessionStoragePath] = process.argv;
 const PORT = parseInt(portArg, 10);
 
 process.on('unhandledRejection', (e) => console.error('authoring_browser unhandledRejection:', e && (e.message || e)));
@@ -66,6 +75,38 @@ async function waitForCDP(port, timeoutMs) {
   return false;
 }
 
+// Replay saved sessionStorage into the running Chrome so MSAL/SPA apps that keep
+// their token in sessionStorage are authenticated. Playwright is OPTIONAL: if it
+// can't be required (the API container ships none) or no path was given, this is
+// a no-op. Returns the connected Playwright browser (kept alive so the init-script
+// registration survives) or null.
+async function replaySessionStorage(port) {
+  if (!sessionStoragePath) return null;
+  let byOrigin;
+  try { byOrigin = JSON.parse(fs.readFileSync(sessionStoragePath, 'utf-8')); }
+  catch { return null; }
+  if (!byOrigin || typeof byOrigin !== 'object' || !Object.keys(byOrigin).length) return null;
+  let chromium;
+  try { ({ chromium } = require('playwright')); } catch { return null; }
+  try {
+    const browser = await chromium.connectOverCDP(`http://127.0.0.1:${port}`);
+    const ctx = browser.contexts()[0];
+    if (ctx) {
+      await ctx.addInitScript((data) => {
+        try {
+          const o = data && data[location.origin];
+          if (o) for (const k of Object.keys(o)) window.sessionStorage.setItem(k, o[k]);
+        } catch (e) {}
+      }, byOrigin);
+      console.error('authoring_browser: sessionStorage replay armed for', Object.keys(byOrigin).join(','));
+    }
+    return browser;
+  } catch (e) {
+    console.error('authoring_browser: sessionStorage replay failed:', e && e.message);
+    return null;
+  }
+}
+
 (async () => {
   if (!PORT || Number.isNaN(PORT)) { console.error('authoring_browser: invalid port', portArg); process.exit(1); }
   const exe = findBrowser();
@@ -101,14 +142,19 @@ async function waitForCDP(port, timeoutMs) {
     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.
+  // Arm sessionStorage replay (best-effort) BEFORE signalling readiness, so the
+  // token is restored before browser-harness navigates.
+  const pw = await replaySessionStorage(PORT);
+
+  // Signal readiness on stdout so the parent proceeds. 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 { if (pw) pw.close(); } catch {}
     try { child.kill(); } catch {}
     process.exit(code || 0);
   };