@q-agent/agent 0.1.8 → 0.1.10

package/dist/src/api.js

@@ -51,6 +51,10 @@ exports.postResult = postResult;
 exports.postEvidence = postEvidence;
 exports.postHealFix = postHealFix;
 exports.postHealFinalize = postHealFinalize;
+exports.claimNextExploration = claimNextExploration;
+exports.postExploreDecide = postExploreDecide;
+exports.postExploreEvent = postExploreEvent;
+exports.postExploreFinalize = postExploreFinalize;
 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). */
@@ -216,6 +220,65 @@ async function postHealFinalize(cfg, caseId, body) {
     });
     await throwIfNotOk(res);
 }
+/** Claim the next queued exploration session for this device's owner. `null` on 204. */
+async function claimNextExploration(cfg) {
+    const res = await fetch(`${cfg.serverUrl}/agent/explore/next`, {
+        method: "POST",
+        headers: authHeaders(cfg.deviceToken),
+    });
+    if (res.status === 204)
+        return null;
+    await throwIfNotOk(res);
+    return (await res.json());
+}
+/** Ask the server to decide the next exploration step (Claude + budget live
+ * server-side). Starts an async job then polls for the result — same async
+ * start-then-poll shape as {@link postHealFix} so a long decide never trips the
+ * ~100s proxy edge cap. */
+async function postExploreDecide(cfg, sessionId, body) {
+    const startRes = await fetchWithTimeout(`${cfg.serverUrl}/agent/explore/${sessionId}/decide`, {
+        method: "POST",
+        headers: { ...authHeaders(cfg.deviceToken), "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    }, HEAL_FIX_REQUEST_TIMEOUT_MS);
+    await throwIfNotOk(startRes);
+    const { jobId } = (await startRes.json());
+    if (!jobId)
+        throw new Error("Explore decide did not return a job id");
+    const deadline = Date.now() + HEAL_FIX_TOTAL_TIMEOUT_MS;
+    for (;;) {
+        const res = await fetchWithTimeout(`${cfg.serverUrl}/agent/explore/${sessionId}/decide/${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 || "Explore decide failed on the server");
+        if (Date.now() > deadline)
+            throw new Error("Explore decide timed out waiting for the server");
+        await sleep(HEAL_FIX_POLL_INTERVAL_MS);
+    }
+}
+/** Push one exploration progress event; the server relays it to the run WS
+ * (`explore.progress`) when the session carries a runId. */
+async function postExploreEvent(cfg, sessionId, event, payload) {
+    const res = await fetch(`${cfg.serverUrl}/agent/explore/${sessionId}/events`, {
+        method: "POST",
+        headers: { ...authHeaders(cfg.deviceToken), "Content-Type": "application/json" },
+        body: JSON.stringify({ event, payload }),
+    });
+    await throwIfNotOk(res);
+}
+/** Finalize an exploration session: the server KB-merges the observed
+ * discovery (`merge_verified_discovery`) and stores the terminal result. */
+async function postExploreFinalize(cfg, sessionId, body) {
+    const res = await fetch(`${cfg.serverUrl}/agent/explore/${sessionId}/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/paths.js

@@ -41,6 +41,7 @@ exports.nodeBin = nodeBin;
 exports.agentNodeModules = agentNodeModules;
 exports.playwrightCli = playwrightCli;
 exports.vendorCaptureScript = vendorCaptureScript;
+exports.vendorExploreScript = vendorExploreScript;
 /**
  * Runtime path resolution for the agent's child processes (Playwright CLI +
  * the headed-login capture script), working in three layouts:
@@ -150,3 +151,15 @@ function vendorCaptureScript() {
         throw new Error("capture_auth.cjs not found — the agent package is missing vendor/");
     return found;
 }
+/** The vendored persistent DOM-exploration driver (`explore_session.cjs`). */
+function vendorExploreScript() {
+    const root = packagedRoot();
+    const found = firstExisting([
+        ...(root ? [path.join(root, "vendor", "explore_session.cjs")] : []),
+        path.join(__dirname, "..", "..", "vendor", "explore_session.cjs"),
+        path.join(__dirname, "..", "vendor", "explore_session.cjs"),
+    ]);
+    if (!found)
+        throw new Error("explore_session.cjs not found — the agent package is missing vendor/");
+    return found;
+}

package/dist/src/runner.js

@@ -42,11 +42,14 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.killActiveChild = killActiveChild;
 exports.processJob = processJob;
+exports.runExplorationLoop = runExplorationLoop;
+exports.processExplorationJob = processExplorationJob;
 exports.runAgentLoop = runAgentLoop;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
+const readline = __importStar(require("readline"));
 const api = __importStar(require("./api"));
 const bus_1 = require("./bus");
 const ensureBrowser_1 = require("./ensureBrowser");
@@ -607,6 +610,292 @@ async function processHealJob(cfg, job, heal) {
         fs.rmSync(workDir, { recursive: true, force: true });
     }
 }
+/** Actions that mutate app/server state — gated by `allowStateChanging`. `goto`
+ * (navigation) and `expectVisible` (a pure probe) are always allowed. */
+const STATE_CHANGING_ACTIONS = new Set(["click", "fill"]);
+/** How long to wait for any single driver command before giving up on it (a
+ * hung observe/act must not stall the whole loop; the loop tolerates the error
+ * and finalizes). Generous because a `goto` can load a slow page. */
+const EXPLORE_CMD_TIMEOUT_MS = 120_000;
+/** The `{strategy,value}` of a locator, for the discovered-selectors log. */
+function describeSelector(args) {
+    if (!args)
+        return null;
+    if (args.testId)
+        return { strategy: "testId", value: args.testId };
+    if (args.role)
+        return { strategy: "role", value: args.role, name: args.name };
+    if (args.selector)
+        return { strategy: "selector", value: args.selector };
+    return null;
+}
+/**
+ * The pure exploration loop, decoupled from the subprocess/HTTP so it can be
+ * unit-tested with fakes. Observes → asks the server to decide → acts, up to
+ * `maxSteps`, stopping on `done`, on a server `stop` (e.g. budget), or on
+ * repeat detection (a url+a11y signature seen before). A gated state-changing
+ * action is SKIPPED (recorded, not executed). Never throws: any error is logged
+ * and the session is finalized with whatever was accumulated.
+ */
+async function runExplorationLoop(cfg, session, driver, apiClient, emitFn) {
+    const history = [];
+    const log = [];
+    const discovered = { routes: [], selectors: [] };
+    const seen = new Set();
+    let stopReason = "maxSteps";
+    let stepsTaken = 0;
+    try {
+        for (let step = 0; step < session.maxSteps; step++) {
+            const obs = await driver.observe();
+            if (!obs || !obs.ok) {
+                stopReason = "observe-error";
+                log.push({ step, phase: "observe", error: (obs && obs.error) || "observe failed" });
+                break;
+            }
+            // Repeat detection: identical url + a11y snapshot means we're looping.
+            const signature = `${obs.url}::${JSON.stringify(obs.a11y)}`;
+            if (seen.has(signature)) {
+                stopReason = "repeat";
+                log.push({ step, phase: "repeat", url: obs.url });
+                break;
+            }
+            seen.add(signature);
+            let decision;
+            try {
+                decision = await apiClient.postExploreDecide(cfg, session.sessionId, {
+                    observation: { accessibility: obs.a11y, elements: obs.elements, url: obs.url, path: obs.path },
+                    history,
+                    stepsTaken,
+                });
+            }
+            catch (err) {
+                stopReason = "decide-error";
+                log.push({ step, phase: "decide", error: err.message });
+                break;
+            }
+            history.push({ action: decision.action, args: decision.args, reasoning: decision.reasoning });
+            if (decision.stop || decision.action === "done") {
+                stopReason = decision.action === "done" ? "done" : decision.stopReason || "stop";
+                log.push({ step, action: decision.action, reasoning: decision.reasoning, stop: true, stopReason });
+                break;
+            }
+            const gated = STATE_CHANGING_ACTIONS.has(decision.action) && !session.allowStateChanging;
+            const rec = {
+                step,
+                action: decision.action,
+                args: decision.args,
+                reasoning: decision.reasoning,
+            };
+            if (gated) {
+                // Do NOT execute a state-changing action when it isn't allowed — record
+                // the skip and move on so the server sees it was considered.
+                rec.skipped = true;
+                rec.skipReason = "state-changing action gated (allowStateChanging=false)";
+                log.push(rec);
+            }
+            else {
+                let result;
+                try {
+                    result = await driver.act(decision.action, decision.args || {});
+                }
+                catch (err) {
+                    result = { ok: false, error: err.message, changed: false };
+                }
+                rec.result = result;
+                log.push(rec);
+                if (result.ok) {
+                    // Record the route/selector that actually worked (with its strategy).
+                    if (decision.action === "goto") {
+                        const route = (decision.args && decision.args.url) || obs.path || obs.url;
+                        if (route)
+                            discovered.routes.push(route);
+                    }
+                    else {
+                        const sel = describeSelector(decision.args);
+                        if (sel)
+                            discovered.selectors.push({ action: decision.action, ...sel });
+                    }
+                }
+            }
+            stepsTaken++;
+            const progress = {
+                step: step + 1,
+                action: decision.action,
+                reasoning: decision.reasoning,
+                skipped: gated,
+                stepsTaken,
+                maxSteps: session.maxSteps,
+            };
+            await apiClient.postExploreEvent(cfg, session.sessionId, "explore.progress", progress).catch(() => { });
+            emitFn("explore-progress", progress);
+        }
+    }
+    catch (err) {
+        // Belt-and-braces: the loop already guards each awaited step, but never let
+        // an unexpected throw escape — finalize with what we have.
+        stopReason = "error";
+        log.push({ phase: "loop", error: err.message });
+    }
+    finally {
+        try {
+            await driver.close();
+        }
+        catch {
+            // Driver already gone.
+        }
+        await apiClient
+            .postExploreFinalize(cfg, session.sessionId, { discovered, log, stopReason, stepsTaken })
+            .catch((err) => console.error("postExploreFinalize failed:", err));
+        emitFn("explore-complete", { sessionId: session.sessionId, stopReason, stepsTaken });
+    }
+}
+/**
+ * Wrap the persistent explore_session.cjs subprocess in an {@link ExploreDriver}:
+ * a serialized newline-delimited-JSON request/response channel. The driver emits
+ * one unsolicited `{ok,ready}` line at startup (consumed by {@link ExploreDriver.observe}'s
+ * first caller via `ready()`); thereafter it is strictly one response line per
+ * command. Any command that outlives {@link EXPLORE_CMD_TIMEOUT_MS} or a dead
+ * process resolves with an error object rather than hanging.
+ */
+function makeExploreDriver(child) {
+    const rl = readline.createInterface({ input: child.stdout });
+    const pending = [];
+    let gotReady = false;
+    let readyResolve;
+    const readyPromise = new Promise((r) => {
+        readyResolve = r;
+    });
+    rl.on("line", (line) => {
+        if (!line.trim())
+            return;
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            return; // ignore non-JSON diagnostic lines
+        }
+        if (!gotReady) {
+            gotReady = true;
+            readyResolve(obj);
+            return;
+        }
+        const resolve = pending.shift();
+        if (resolve)
+            resolve(obj);
+    });
+    const failAll = () => {
+        if (!gotReady) {
+            gotReady = true;
+            readyResolve({ ok: false, error: "driver exited before ready" });
+        }
+        while (pending.length) {
+            const resolve = pending.shift();
+            if (resolve)
+                resolve({ ok: false, error: "driver process closed" });
+        }
+    };
+    child.on("close", failAll);
+    child.on("error", failAll);
+    const request = (cmd) => new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            const idx = pending.indexOf(wrapped);
+            if (idx >= 0)
+                pending.splice(idx, 1);
+            resolve({ ok: false, error: "driver command timed out" });
+        }, EXPLORE_CMD_TIMEOUT_MS);
+        const wrapped = (v) => {
+            clearTimeout(timer);
+            resolve(v);
+        };
+        pending.push(wrapped);
+        try {
+            child.stdin.write(JSON.stringify(cmd) + "\n");
+        }
+        catch {
+            // stdin closed — the close/error handler will resolve pending.
+        }
+    });
+    return {
+        ready: () => readyPromise,
+        observe: () => request({ cmd: "observe" }),
+        act: (action, args) => request({ cmd: "act", action, args }),
+        close: async () => {
+            try {
+                child.stdin.write(JSON.stringify({ cmd: "close" }) + "\n");
+            }
+            catch {
+                // already gone
+            }
+        },
+    };
+}
+/**
+ * Process one claimed exploration session end-to-end (#338): reuse a saved
+ * local session for the origin (auth never leaves this machine), spawn the
+ * vendored persistent Playwright driver, run the observe→decide→act loop, then
+ * finalize. The driver subprocess is ALWAYS killed in `finally`.
+ */
+async function processExplorationJob(cfg, session) {
+    // Reuse a captured session for the origin if one exists (exploration never
+    // prompts for a headed login — it explores with whatever auth is available).
+    let origin = session.origin;
+    if (!origin && session.baseUrl) {
+        try {
+            origin = new URL(session.baseUrl).origin;
+        }
+        catch {
+            origin = "";
+        }
+    }
+    const storageState = origin && (0, session_1.hasValidSession)(origin) ? (0, session_1.sessionPathsForOrigin)(origin).storageStatePath : "";
+    const script = (0, paths_1.vendorExploreScript)();
+    const nm = (0, paths_1.agentNodeModules)();
+    const args = [script, session.baseUrl];
+    if (storageState)
+        args.push(storageState);
+    const child = (0, child_process_1.spawn)((0, paths_1.nodeBin)(), args, { cwd: nm, env: nodePathEnv(nm) });
+    activeChild = child;
+    // Capture the driver's stderr so a launch failure (missing browser, bad
+    // Playwright resolution, …) is visible instead of a silent "complete".
+    let driverStderr = "";
+    child.stderr?.on("data", (d) => {
+        driverStderr += String(d);
+    });
+    const driver = makeExploreDriver(child);
+    try {
+        // Wait for the driver's readiness signal before the first observe. If the
+        // driver died before signalling ready, finalize with a clear driver-error
+        // (carrying its stderr) rather than letting the loop break silently.
+        const ready = await driver.ready();
+        if (!ready || ready.ok === false) {
+            const error = (ready && ready.error) || "driver failed to start";
+            const detail = driverStderr.trim();
+            await api
+                .postExploreFinalize(cfg, session.sessionId, {
+                discovered: { routes: [], selectors: [] },
+                log: [{ phase: "driver", error, stderr: detail || undefined }],
+                stopReason: "driver-error",
+                stepsTaken: 0,
+            })
+                .catch((err) => console.error("postExploreFinalize failed:", err));
+            (0, bus_1.emit)("explore-complete", { sessionId: session.sessionId, stopReason: "driver-error", error });
+            console.error(`Exploration ${session.sessionId} driver-error: ${error}${detail ? ` — ${detail}` : ""}`);
+            return;
+        }
+        await runExplorationLoop(cfg, session, driver, api, bus_1.emit);
+    }
+    finally {
+        try {
+            child.kill();
+        }
+        catch {
+            // Already gone.
+        }
+        if (activeChild === child)
+            activeChild = null;
+    }
+}
 /**
  * Long-poll loop: claim → process → repeat, backing off `IDLE_POLL_MS`
  * between empty claims. Runs until `signal.aborted`.
@@ -638,6 +927,27 @@ async function runAgentLoop(cfg, signal) {
                 await processCapture(cfg, capture);
                 continue;
             }
+            // No capture either — check for a queued DOM-exploration session (#338).
+            let explore = null;
+            try {
+                explore = await api.claimNextExploration(cfg);
+            }
+            catch (err) {
+                console.error("Exploration claim failed:", err.message);
+            }
+            if (explore) {
+                console.log(`Claimed exploration ${explore.sessionId} (${explore.target?.goal || explore.baseUrl})`);
+                (0, bus_1.emit)("explore-claimed", { sessionId: explore.sessionId, goal: explore.target?.goal });
+                try {
+                    await processExplorationJob(cfg, explore);
+                    console.log(`Exploration ${explore.sessionId} complete`);
+                }
+                catch (err) {
+                    console.error(`Exploration ${explore.sessionId} crashed:`, err);
+                    (0, bus_1.emit)("error", { message: `Exploration ${explore.sessionId} crashed: ${err.message}` });
+                }
+                continue;
+            }
             await new Promise((r) => setTimeout(r, IDLE_POLL_MS));
             continue;
         }

package/dist/test/explore.test.js

@@ -0,0 +1,265 @@
+"use strict";
+/**
+ * Tests for the DOM-exploration slice (#338):
+ *  - `runExplorationLoop` (runner.ts) with the driver + HTTP client MOCKED
+ *    (injected fakes) — asserts the loop stops on `done`, on a server
+ *    `stop:budget`, on `maxSteps`, and on repeat detection; that a gated
+ *    state-changing action is SKIPPED (not executed); and that finalize is
+ *    called with the accumulated discovered/log.
+ *  - the new `api.ts` explore client calls with `fetch` mocked (same style as
+ *    api.test.ts) — request shape + the decide start-then-poll flow.
+ */
+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;
+    };
+})();
+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 api = __importStar(require("../src/api"));
+const runner_1 = require("../src/runner");
+const cfg = {
+    serverUrl: "http://127.0.0.1:8787",
+    deviceToken: "test-token",
+    deviceId: 1,
+    deviceName: "test-machine",
+};
+function makeSession(overrides = {}) {
+    return {
+        sessionId: "S1",
+        baseUrl: "https://app.example.com",
+        origin: "https://app.example.com",
+        target: { ticket: "T1", screen: "Home", goal: "explore home" },
+        maxSteps: 5,
+        allowStateChanging: true,
+        projectKey: "P",
+        repo: "r",
+        ...overrides,
+    };
+}
+/** A fake driver. By default each `observe` returns a DISTINCT page (so repeat
+ * detection never fires); pass `staticObs:true` to return an identical page. */
+function makeFakeDriver(opts = {}) {
+    let n = 0;
+    const acts = [];
+    let closed = false;
+    const driver = {
+        observe: async () => {
+            const i = opts.staticObs ? 0 : ++n;
+            return { ok: true, url: `https://app.example.com/p${i}`, path: `/p${i}`, a11y: { i }, elements: [] };
+        },
+        act: async (action, args) => {
+            acts.push({ action, args });
+            return { ok: true, error: null, changed: true };
+        },
+        close: async () => {
+            closed = true;
+        },
+    };
+    return { driver, acts, isClosed: () => closed };
+}
+/** A fake explore HTTP client that returns scripted decisions in order (the
+ * last one repeats if the loop asks for more). Records events + finalize. */
+function makeFakeApi(decisions) {
+    let di = 0;
+    const events = [];
+    const finalizeCalls = [];
+    const client = {
+        postExploreDecide: async () => decisions[Math.min(di++, decisions.length - 1)],
+        postExploreEvent: async (_cfg, _sid, event, payload) => {
+            events.push({ event, payload });
+        },
+        postExploreFinalize: async (_cfg, _sid, body) => {
+            finalizeCalls.push(body);
+        },
+    };
+    return { client, events, finalizeCalls, decideCount: () => di };
+}
+const noopEmit = () => { };
+(0, node_test_1.test)("loop stops on a `done` action and finalizes with stopReason=done", async () => {
+    const { driver, acts, isClosed } = makeFakeDriver();
+    const fake = makeFakeApi([
+        { action: "click", args: { testId: "menu" }, reasoning: "open menu" },
+        { action: "done", args: {}, reasoning: "goal reached" },
+    ]);
+    await (0, runner_1.runExplorationLoop)(cfg, makeSession(), driver, fake.client, noopEmit);
+    strict_1.default.equal(fake.finalizeCalls.length, 1);
+    const body = fake.finalizeCalls[0];
+    strict_1.default.equal(body.stopReason, "done");
+    strict_1.default.equal(body.stepsTaken, 1); // one click executed, then `done` broke the loop
+    strict_1.default.deepEqual(acts, [{ action: "click", args: { testId: "menu" } }]);
+    // Discovered records the selector that worked, with its strategy.
+    const discovered = body.discovered;
+    strict_1.default.deepEqual(discovered.selectors, [{ action: "click", strategy: "testId", value: "menu" }]);
+    strict_1.default.ok(isClosed(), "driver.close() should be called");
+});
+(0, node_test_1.test)("loop stops when the server returns stop:true (budget)", async () => {
+    const { driver } = makeFakeDriver();
+    const fake = makeFakeApi([
+        { action: "click", args: { selector: ".a" }, reasoning: "step 1" },
+        { action: "noop", args: {}, reasoning: "budget spent", stop: true, stopReason: "budget" },
+    ]);
+    await (0, runner_1.runExplorationLoop)(cfg, makeSession(), driver, fake.client, noopEmit);
+    strict_1.default.equal(fake.finalizeCalls[0].stopReason, "budget");
+    strict_1.default.equal(fake.finalizeCalls[0].stepsTaken, 1);
+});
+(0, node_test_1.test)("loop stops at maxSteps when nothing else stops it", async () => {
+    const { driver, acts } = makeFakeDriver();
+    const fake = makeFakeApi([{ action: "click", args: { role: "button", name: "Next" }, reasoning: "keep going" }]);
+    await (0, runner_1.runExplorationLoop)(cfg, makeSession({ maxSteps: 3 }), driver, fake.client, noopEmit);
+    strict_1.default.equal(fake.finalizeCalls[0].stopReason, "maxSteps");
+    strict_1.default.equal(fake.finalizeCalls[0].stepsTaken, 3);
+    strict_1.default.equal(acts.length, 3);
+});
+(0, node_test_1.test)("loop stops on repeat detection (same url + a11y signature)", async () => {
+    const { driver } = makeFakeDriver({ staticObs: true });
+    const fake = makeFakeApi([{ action: "click", args: { selector: ".x" }, reasoning: "click" }]);
+    await (0, runner_1.runExplorationLoop)(cfg, makeSession(), driver, fake.client, noopEmit);
+    strict_1.default.equal(fake.finalizeCalls[0].stopReason, "repeat");
+    strict_1.default.equal(fake.finalizeCalls[0].stepsTaken, 1); // first step ran, second observe repeated
+});
+(0, node_test_1.test)("a gated state-changing action is SKIPPED, not executed", async () => {
+    const { driver, acts } = makeFakeDriver();
+    const fake = makeFakeApi([{ action: "click", args: { testId: "buy" }, reasoning: "attempt purchase" }]);
+    await (0, runner_1.runExplorationLoop)(cfg, makeSession({ maxSteps: 1, allowStateChanging: false }), driver, fake.client, noopEmit);
+    strict_1.default.equal(acts.length, 0, "driver.act must not be called for a gated action");
+    const body = fake.finalizeCalls[0];
+    const log = body.log;
+    const clickEntry = log.find((e) => e.action === "click");
+    strict_1.default.ok(clickEntry, "the skipped action is still recorded in the log");
+    strict_1.default.equal(clickEntry?.skipped, true);
+    // Nothing was actually exercised, so no discovery is recorded.
+    const discovered = body.discovered;
+    strict_1.default.equal(discovered.selectors.length, 0);
+});
+(0, node_test_1.test)("goto action records the route in discovered", async () => {
+    const { driver } = makeFakeDriver();
+    const fake = makeFakeApi([
+        { action: "goto", args: { url: "/settings" }, reasoning: "navigate" },
+        { action: "done", args: {}, reasoning: "done" },
+    ]);
+    await (0, runner_1.runExplorationLoop)(cfg, makeSession(), driver, fake.client, noopEmit);
+    const discovered = fake.finalizeCalls[0].discovered;
+    strict_1.default.deepEqual(discovered.routes, ["/settings"]);
+});
+(0, node_test_1.test)("progress is emitted via both postExploreEvent and the local bus", async () => {
+    const { driver } = makeFakeDriver();
+    const fake = makeFakeApi([
+        { action: "click", args: { testId: "a" }, reasoning: "r" },
+        { action: "done", args: {}, reasoning: "done" },
+    ]);
+    const emitted = [];
+    await (0, runner_1.runExplorationLoop)(cfg, makeSession(), driver, fake.client, (type, data) => emitted.push({ type, data }));
+    strict_1.default.equal(fake.events.length, 1);
+    strict_1.default.equal(fake.events[0].event, "explore.progress");
+    strict_1.default.ok(emitted.some((e) => e.type === "explore-progress"));
+    strict_1.default.ok(emitted.some((e) => e.type === "explore-complete"));
+});
+let calls = [];
+const originalFetch = globalThis.fetch;
+function mockFetch(handler) {
+    globalThis.fetch = (async (url, init) => {
+        const u = typeof url === "string" ? url : url.toString();
+        calls.push({ url: u, init: init ?? {} });
+        return handler(u, init ?? {});
+    });
+}
+(0, node_test_1.afterEach)(() => {
+    globalThis.fetch = originalFetch;
+    calls = [];
+});
+(0, node_test_1.test)("claimNextExploration returns null on 204", async () => {
+    mockFetch(() => new Response(null, { status: 204 }));
+    const s = await api.claimNextExploration(cfg);
+    strict_1.default.equal(s, null);
+    strict_1.default.equal(calls[0].url, "http://127.0.0.1:8787/agent/explore/next");
+    strict_1.default.equal(calls[0].init.method, "POST");
+    strict_1.default.equal(calls[0].init.headers.Authorization, "Bearer test-token");
+});
+(0, node_test_1.test)("claimNextExploration returns the parsed session on 200", async () => {
+    const payload = makeSession();
+    mockFetch(() => Response.json(payload));
+    const s = await api.claimNextExploration(cfg);
+    strict_1.default.deepEqual(s, payload);
+});
+(0, node_test_1.test)("postExploreDecide starts a job then polls decide/{jobId} for the result", async () => {
+    mockFetch((url, init) => {
+        if (init.method === "POST")
+            return Response.json({ jobId: "d-1", status: "running" });
+        return Response.json({ status: "done", result: { action: "click", args: { testId: "x" }, reasoning: "r" } });
+    });
+    const out = await api.postExploreDecide(cfg, "S1", {
+        observation: { accessibility: {}, elements: [], url: "https://app/x", path: "/x" },
+        history: [],
+        stepsTaken: 0,
+    });
+    strict_1.default.equal(calls[0].url, "http://127.0.0.1:8787/agent/explore/S1/decide");
+    strict_1.default.equal(calls[0].init.method, "POST");
+    strict_1.default.equal(calls[1].url, "http://127.0.0.1:8787/agent/explore/S1/decide/d-1");
+    strict_1.default.equal(calls[1].init.method, "GET");
+    strict_1.default.equal(out.action, "click");
+});
+(0, node_test_1.test)("postExploreDecide surfaces a server-side error job", async () => {
+    mockFetch((url, init) => {
+        if (init.method === "POST")
+            return Response.json({ jobId: "d-2", status: "running" });
+        return Response.json({ status: "error", error: "budget exhausted before start" });
+    });
+    await strict_1.default.rejects(() => api.postExploreDecide(cfg, "S1", {
+        observation: { accessibility: {}, elements: [], url: "u", path: "/" },
+        history: [],
+        stepsTaken: 0,
+    }), /budget exhausted/);
+});
+(0, node_test_1.test)("postExploreEvent wraps event+payload", async () => {
+    mockFetch(() => new Response(null, { status: 200 }));
+    await api.postExploreEvent(cfg, "S1", "explore.progress", { step: 1 });
+    strict_1.default.equal(calls[0].url, "http://127.0.0.1:8787/agent/explore/S1/events");
+    const body = JSON.parse(calls[0].init.body);
+    strict_1.default.deepEqual(body, { event: "explore.progress", payload: { step: 1 } });
+});
+(0, node_test_1.test)("postExploreFinalize posts the accumulated discovery", async () => {
+    mockFetch(() => new Response(null, { status: 200 }));
+    await api.postExploreFinalize(cfg, "S1", {
+        discovered: { routes: ["/x"], selectors: [] },
+        log: [],
+        stopReason: "done",
+        stepsTaken: 2,
+    });
+    strict_1.default.equal(calls[0].url, "http://127.0.0.1:8787/agent/explore/S1/finalize");
+    const body = JSON.parse(calls[0].init.body);
+    strict_1.default.equal(body.stopReason, "done");
+    strict_1.default.equal(body.stepsTaken, 2);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@q-agent/agent",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "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/explore_session.cjs

@@ -0,0 +1,190 @@
+// Long-lived Playwright driver for the DOM Exploration Agent (ADR 0010 §1).
+//
+// Vendored verbatim from api/app/services/pw_scripts/explore_session.cjs so the
+// Local Agent drives the SAME observe/act/close protocol the server built. Like
+// vendor/capture_auth.cjs, it `require('playwright')` — resolved against the
+// agent's bundled @playwright/test via NODE_PATH (set by the spawning code in
+// runner.ts), so no CDN/global Playwright is needed.
+//
+// Unlike the rest of the app — which drives Playwright as one-shot
+// `npx playwright test` subprocesses — the exploration loop is interactive: the
+// agent must OBSERVE page state after each action to DECIDE the next one. So
+// this process launches ONE chromium browser + page and keeps it open for the
+// whole session, reading newline-delimited JSON commands on stdin and writing
+// newline-delimited JSON responses on stdout.
+//
+// Args: baseURL, [storageState]  (storageState = absolute path to a saved
+// Playwright session for auth reuse, per ADR 0002).
+//
+// Protocol (one JSON object per line, each way):
+//   {"cmd":"observe"}
+//     -> {"ok":true,"url":..,"path":..,"a11y":<ariaSnapshot() role+name tree>,
+//         "elements":[<distilled interactive DOM>]}
+//   {"cmd":"act","action":"goto|click|fill|expectVisible","args":{...}}
+//     -> {"ok":bool,"error":str|null,"changed":bool}
+//   {"cmd":"close"}  -> process exits.
+//
+// Every command is guarded so a bad action returns {ok:false,error} and never
+// crashes the process (the session must survive a mis-step, mirroring the
+// self-heal loop's tolerance for stale actions).
+const { chromium } = require('playwright');
+const readline = require('readline');
+
+const [, , baseURL, storageState] = process.argv;
+
+process.on('unhandledRejection', (e) => console.error('explore unhandledRejection:', e && (e.message || e)));
+process.on('uncaughtException', (e) => console.error('explore uncaughtException:', e && (e.message || e)));
+
+// Same selector set + shape as the self-heal distilled DOM (playwright_runner
+// `_fixtures_ts`), so observations ground on identical real identifiers.
+const DISTILL = () => {
+  const SEL = 'a,button,input,select,textarea,[role],[data-testid],[data-test],[id]';
+  return Array.from(document.querySelectorAll(SEL)).slice(0, 400).map((node) => {
+    const el = node;
+    const text = (el.innerText || '').trim().slice(0, 80);
+    return {
+      tag: el.tagName.toLowerCase(),
+      role: el.getAttribute('role') || undefined,
+      testId: el.getAttribute('data-testid') || el.getAttribute('data-test') || undefined,
+      id: el.id || undefined,
+      name: el.getAttribute('name') || undefined,
+      text: text || undefined,
+      placeholder: el.getAttribute('placeholder') || undefined,
+      type: el.getAttribute('type') || undefined,
+    };
+  });
+};
+
+function send(obj) {
+  process.stdout.write(JSON.stringify(obj) + '\n');
+}
+
+let browser = null;
+let page = null;
+
+/**
+ * Resolve a Playwright locator from the action args. Prefers stable strategies:
+ * data-testid -> role -> raw selector (CSS/testid). Returns null when the args
+ * carry neither a role nor a selector.
+ */
+function locatorFor(args) {
+  if (!args) return null;
+  if (args.testId) return page.getByTestId(args.testId);
+  if (args.role) return page.getByRole(args.role, args.name != null ? { name: args.name } : undefined);
+  if (args.selector) return page.locator(args.selector);
+  return null;
+}
+
+/** A cheap page signature (url + distilled interactive DOM) used to detect change. */
+async function signature() {
+  try {
+    const elements = await page.evaluate(DISTILL);
+    return page.url() + '::' + JSON.stringify(elements);
+  } catch {
+    return page.url() + '::';
+  }
+}
+
+async function doAct(action, args) {
+  args = args || {};
+  const before = await signature();
+  switch (action) {
+    case 'goto': {
+      await page.goto(args.url, { waitUntil: 'domcontentloaded' });
+      break;
+    }
+    case 'click': {
+      const loc = locatorFor(args);
+      if (!loc) return { ok: false, error: 'click needs role+name or selector', changed: false };
+      await loc.first().click();
+      break;
+    }
+    case 'fill': {
+      const loc = locatorFor(args);
+      if (!loc) return { ok: false, error: 'fill needs role+name or selector', changed: false };
+      await loc.first().fill(args.value != null ? String(args.value) : '');
+      break;
+    }
+    case 'expectVisible': {
+      // Probe only — report visibility, never throw on absence.
+      const loc = locatorFor(args);
+      if (!loc) return { ok: false, error: 'expectVisible needs role+name or selector', changed: false };
+      let visible = false;
+      try { visible = await loc.first().isVisible(); } catch { visible = false; }
+      return { ok: visible, error: visible ? null : 'not visible', changed: false };
+    }
+    default:
+      return { ok: false, error: `unknown action: ${action}`, changed: false };
+  }
+  const after = await signature();
+  return { ok: true, error: null, changed: after !== before };
+}
+
+async function doObserve() {
+  // Playwright removed page.accessibility; the supported role+name tree is
+  // locator.ariaSnapshot() (a compact YAML string, ideal for the model and
+  // maps directly to getByRole). Best-effort — never fail observe on it.
+  let a11y = '';
+  try { a11y = await page.locator('body').ariaSnapshot(); } catch { a11y = ''; }
+  const elements = await page.evaluate(DISTILL);
+  const url = page.url();
+  let path = '';
+  try { path = new URL(url).pathname; } catch { path = ''; }
+  return { ok: true, url, path, a11y, elements };
+}
+
+async function handle(line) {
+  let msg;
+  try {
+    msg = JSON.parse(line);
+  } catch (e) {
+    send({ ok: false, error: 'invalid JSON command' });
+    return;
+  }
+  try {
+    if (msg.cmd === 'observe') {
+      send(await doObserve());
+    } else if (msg.cmd === 'act') {
+      send(await doAct(msg.action, msg.args));
+    } else if (msg.cmd === 'close') {
+      try { await browser.close(); } catch {}
+      process.exit(0);
+    } else {
+      send({ ok: false, error: `unknown cmd: ${msg.cmd}` });
+    }
+  } catch (e) {
+    send({ ok: false, error: (e && (e.message || String(e))) || 'command failed' });
+  }
+}
+
+(async () => {
+  if (!baseURL) { console.error('explore_session: missing baseURL arg'); process.exit(1); }
+  browser = await chromium.launch({ headless: true });
+  const contextOpts = { baseURL };
+  if (storageState) contextOpts.storageState = storageState;
+  const context = await browser.newContext(contextOpts);
+  page = await context.newPage();
+
+  // Land on the app before the first observe so step 1 sees the real page,
+  // not about:blank. Best-effort — the model can still goto elsewhere.
+  if (baseURL) {
+    try { await page.goto(baseURL, { waitUntil: 'domcontentloaded' }); } catch {}
+  }
+
+  // Serialize commands: one line in -> one response out, in order.
+  const rl = readline.createInterface({ input: process.stdin });
+  let chain = Promise.resolve();
+  rl.on('line', (line) => {
+    if (!line.trim()) return;
+    chain = chain.then(() => handle(line));
+  });
+  rl.on('close', async () => {
+    try { await browser.close(); } catch {}
+    process.exit(0);
+  });
+  // Signal readiness so the agent side knows the browser+page are up.
+  send({ ok: true, ready: true });
+})().catch((e) => {
+  console.error('explore_session fatal:', e && (e.stack || e.message || e));
+  process.exit(1);
+});