waygraph 0.15.54 → 0.16.1

package/dist/live/auto-session/auto-session.js

@@ -0,0 +1,452 @@
+import { collectKnownInteractionSelectors, unmappedInteractionsPageScript } from "../../analysis/coverage-gap.js";
+import { findBlockPathDetailed } from "../../analysis/graph.js";
+import { runStubPhase } from "../../demo/narration/narration.js";
+import { describeOverlayFixtures, phaseToOverlayFixtures } from "../../demo/overlay/phase-fixtures.js";
+import { showPilotFixtures } from "../../demo/overlay/pilot/fixtures.js";
+import { showPilotActivity, showPilotVision } from "../../demo/overlay/pilot/shell.js";
+import { keepOverlayOnNavigation } from "../../demo/overlay/reattach.js";
+import { verboseLog } from "../../demo/verbose-log.js";
+import { Engine } from "../../engine/engine.js";
+import { MemPage } from "../../engine/mem/mem.js";
+import { ignorePageGone } from "../../engine/page-gone.js";
+import { resolveBaseUrl } from "../../runtime/waygraph-config.js";
+import { detectHere, ensureLivePage, runOneBlock } from "../auto/auto.js";
+import { buildExploreContext, buildExploreMenu } from "../auto/explore.js";
+import { ensureMem, seedDefaultMem } from "../auto/mem.js";
+import { updatePilotOverlay } from "../pilot/panel.js";
+import { recordPageConsole } from "./console.js";
+import { CONSOLE_LOG_MAX_ENTRIES, TRACE_MAX_STEPS, buildSessionSnapshot, describeHighlight, parsePick, stubFilePath, stubPhaseHasContent } from "./helpers.js";
+import { inspectDom, inspectStorage } from "./inspect.js";
+import { openSessionBrowser } from "./open-browser.js";
+/** The first element `selector` matches, ringed with the pilot's vision ring; or why there is none. */
+async function rawTarget(page, selector, label) {
+    const locator = page.locator(selector).first();
+    if ((await locator.count()) === 0)
+        return `no element matches selector "${selector}"`;
+    await showPilotVision(page, selector, label);
+    return locator;
+}
+/**
+ * A live session driven over IPC (`browser start`, `pilot start`): the same graph, library, mem and browser as
+ * `waygraph auto`, moved one call at a time (`applyPick`, `applyPath`, the raw actions) instead of a menu loop.
+ */
+export class AutoSession {
+    projectDir;
+    inject;
+    blocksSelect;
+    graph;
+    library;
+    mem;
+    engine;
+    closeBrowser;
+    context;
+    page;
+    startUrl;
+    sessionId;
+    here = null;
+    lastRunNote = null;
+    trace = [];
+    consoleLog = [];
+    knownInteractionSelectors;
+    headless;
+    lastOverlayInfo = null;
+    constructor(projectDir, inject, blocksSelect, graph, library, mem, engine, closeBrowser, context, page, startUrl, sessionId, knownInteractionSelectors, headless) {
+        this.projectDir = projectDir;
+        this.inject = inject;
+        this.blocksSelect = blocksSelect;
+        this.graph = graph;
+        this.library = library;
+        this.mem = mem;
+        this.engine = engine;
+        this.closeBrowser = closeBrowser;
+        this.context = context;
+        this.page = page;
+        this.startUrl = startUrl;
+        this.sessionId = sessionId;
+        this.knownInteractionSelectors = knownInteractionSelectors;
+        this.headless = headless;
+    }
+    static async start(init) {
+        const baseURL = init.baseURL ?? (await resolveBaseUrl(init.projectDir));
+        const skipNav = init.skipInitialNavigation === true;
+        const startUrl = skipNav ? undefined : (init.startUrl ?? baseURL);
+        const exploreOpts = {
+            ...(init.blocksSelect ? { blocksSelect: init.blocksSelect } : {}),
+            ...(init.inject?.length ? { inject: init.inject } : {}),
+        };
+        const { graph, library } = await buildExploreContext(init.projectDir, Object.keys(exploreOpts).length ? exploreOpts : undefined);
+        const mem = new MemPage();
+        seedDefaultMem(library.byName, mem);
+        const headless = init.headless ?? true;
+        const engine = new Engine({ headless });
+        const { closeBrowser, context, page } = await openSessionBrowser(init.projectDir, headless, baseURL, startUrl);
+        const knownInteractionSelectors = collectKnownInteractionSelectors(init.projectDir, library, init.inject);
+        const session = new AutoSession(init.projectDir, init.inject, init.blocksSelect, graph, library, mem, engine, closeBrowser, context, page, startUrl, init.sessionId, knownInteractionSelectors, headless);
+        keepOverlayOnNavigation(page, () => session.repaintOverlayAfterNavigation());
+        if (!headless) {
+            await session.bootstrapOverlay().catch(ignorePageGone);
+            await page.bringToFront().catch(ignorePageGone);
+        }
+        recordPageConsole(page, (entry) => session.pushConsoleLog(entry));
+        return session;
+    }
+    /** Pure getter - returns a copy, not the live array. */
+    getTrace() {
+        return [...this.trace];
+    }
+    pushTrace(step) {
+        this.trace.push(step);
+        if (this.trace.length > TRACE_MAX_STEPS)
+            this.trace.shift();
+    }
+    /** Pure getter - returns a copy, not the live array. */
+    getConsoleLog() {
+        return [...this.consoleLog];
+    }
+    pushConsoleLog(entry) {
+        this.consoleLog.push(entry);
+        if (this.consoleLog.length > CONSOLE_LOG_MAX_ENTRIES)
+            this.consoleLog.shift();
+    }
+    async currentMenu() {
+        this.page = await ensureLivePage(this.context, this.page, this.startUrl);
+        if (this.here === null) {
+            this.here = await detectHere(this.page, this.library.navBlocks);
+        }
+        const menu = await buildExploreMenu(this.page, this.graph, this.library, this.here);
+        // Every read and every action goes through currentMenu(), so the overlay is refreshed here, awaited: someone
+        // watching sees the state an API caller just got back, not a frame behind.
+        this.lastOverlayInfo = {
+            sessionId: this.sessionId,
+            snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
+            graph: this.graph,
+        };
+        await updatePilotOverlay(this.page, this.lastOverlayInfo);
+        await this.warnUnmappedInteractions();
+        return menu;
+    }
+    /** Paint the overlay on about:blank / immediately after session start (headful browser). */
+    async bootstrapOverlay() {
+        await this.currentMenu();
+    }
+    /** Re-apply cached overlay state after navigation (init script restores shell only). */
+    async repaintOverlayAfterNavigation() {
+        if (this.lastOverlayInfo) {
+            await updatePilotOverlay(this.page, this.lastOverlayInfo).catch(ignorePageGone);
+            return;
+        }
+        if (!this.headless) {
+            await this.bootstrapOverlay().catch(ignorePageGone);
+        }
+    }
+    /**
+     * Flags same-origin `<a href>` paths and visible buttons with no NavBlock
+     * URL / Block selector in the loaded library — read via `auto console`.
+     * Deduped per page load so repeated status/send calls stay quiet.
+     */
+    async warnUnmappedInteractions() {
+        const knownPathnames = [];
+        for (const entry of this.library.navBlocks) {
+            const url = entry.block.__waygraphNavUrl;
+            if (!url)
+                continue;
+            try {
+                knownPathnames.push(new URL(url, this.page.url()).pathname);
+            }
+            catch {
+                /* not a resolvable URL (relative to an unset base, etc.) - skip */
+            }
+        }
+        const payload = {
+            knownPathnames,
+            knownSelectors: this.knownInteractionSelectors,
+        };
+        await this.page.evaluate(unmappedInteractionsPageScript, payload).catch(ignorePageGone);
+    }
+    /** Pure getter - no Block runs, no mem/page mutation. */
+    async currentSnapshot() {
+        const menu = await this.currentMenu();
+        return buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote);
+    }
+    /**
+     * Pure getter - reads the live page's structure at the requested fidelity.
+     * No Block runs, no mem/page mutation. `selector` scopes either mode to one
+     * element's subtree; it is a modifier, not a third mode.
+     */
+    async inspectDom(opts) {
+        this.page = await ensureLivePage(this.context, this.page, this.startUrl);
+        return inspectDom(this.page, opts);
+    }
+    /** Reads the live page's client state: storage, cookies, service workers (where web-push state lives). */
+    async inspectStorage() {
+        this.page = await ensureLivePage(this.context, this.page, this.startUrl);
+        return inspectStorage(this.page, this.context);
+    }
+    /** Paint + log a Block's authored waygraph overlay fixtures (same as demo does), best-effort. */
+    async paintStubPhase(tag, phase, holdMs) {
+        if (!this.page || !stubPhaseHasContent(phase))
+            return;
+        const fixtures = phaseToOverlayFixtures(phase, holdMs);
+        for (const line of describeOverlayFixtures(tag, fixtures))
+            verboseLog("pilot", line);
+        await showPilotFixtures(this.page, fixtures).catch(ignorePageGone);
+    }
+    /**
+     * Runs one Block for real: the core of `applyPick` (picked from the live menu) and `applyPath` (named by the route).
+     * `expectedTo` is used when the Block's resolve doesn't set `__state`.
+     */
+    async runNamedBlock(entry, expectedTo, instanceOption) {
+        const from = this.here;
+        const stubBeforeResult = await runStubPhase(entry.block, "stubBefore");
+        await this.paintStubPhase("stub.before", stubBeforeResult, 6000);
+        const stepBase = {
+            block: entry.block.name,
+            from,
+            timestamp: new Date().toISOString(),
+            ...(stubPhaseHasContent(stubBeforeResult) ? { stubBefore: stubBeforeResult } : {}),
+        };
+        try {
+            if (instanceOption) {
+                this.mem.set(instanceOption.key, instanceOption.value);
+            }
+            // Always the non-interactive path (cli: false) - a detached session has
+            // no TTY to prompt on; a missing mem key fails loud instead of hanging.
+            await ensureMem(entry, this.mem, false);
+            const result = await runOneBlock(this.engine, entry, this.context, this.page, this.mem, false);
+            this.here = result.__state ?? expectedTo;
+            this.lastRunNote = `${entry.block.name} -> ${this.here}`;
+            const stubAfterResult = await runStubPhase(entry.block, "stubAfter", { out: result });
+            await this.paintStubPhase("stub.after", stubAfterResult, 6000);
+            this.pushTrace({
+                ...stepBase,
+                to: this.here,
+                ...(stubPhaseHasContent(stubAfterResult) ? { stubAfter: stubAfterResult } : {}),
+            });
+        }
+        catch (err) {
+            this.lastRunNote = `${entry.block.name} failed`;
+            const message = err instanceof Error ? err.message : String(err);
+            const stubOnErrorResult = await runStubPhase(entry.block, "stubOnError", { error: err });
+            await this.paintStubPhase("stub.error", stubOnErrorResult, 8000);
+            this.pushTrace({
+                ...stepBase,
+                error: message,
+                ...(stubPhaseHasContent(stubOnErrorResult) ? { stubOnError: stubOnErrorResult } : {}),
+            });
+            return { ok: false, error: `${entry.block.name} failed - ${message}` };
+        }
+        const nextMenu = await this.currentMenu();
+        return {
+            ok: true,
+            snapshot: buildSessionSnapshot(nextMenu, this.library.byName, this.here, this.lastRunNote),
+            quit: false,
+        };
+    }
+    /** Applies exactly one pick: runs at most one Block, returns the resulting state. */
+    async applyPick(raw) {
+        const menu = await this.currentMenu();
+        const pick = parsePick(raw, menu);
+        if (pick.type === "invalid")
+            return { ok: false, error: pick.reason };
+        if (pick.type === "quit") {
+            return {
+                ok: true,
+                snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
+                quit: true,
+            };
+        }
+        const edge = menu.flat[pick.index];
+        const entry = this.library.byName.get(edge.block);
+        if (!entry) {
+            return { ok: false, error: `Block "${edge.block}" not loaded - skipped` };
+        }
+        await showPilotActivity(this.page, `Running (Block): ${edge.block}`);
+        return this.runNamedBlock(entry, edge.to, edge.instanceOption);
+    }
+    /**
+     * Re-reads the project's Blocks and graph from disk (the same call `start()` makes) and swaps them in, keeping the
+     * page, mem, browser and `here`: a Block written mid-session becomes pickable without a restart.
+     */
+    async reloadLibrary() {
+        if (this.page)
+            await showPilotActivity(this.page, "Running: reload");
+        const exploreOpts = {
+            ...(this.blocksSelect ? { blocksSelect: this.blocksSelect } : {}),
+            ...(this.inject?.length ? { inject: this.inject } : {}),
+        };
+        const { graph, library } = await buildExploreContext(this.projectDir, Object.keys(exploreOpts).length ? exploreOpts : undefined);
+        this.graph = graph;
+        this.library = library;
+        if (this.page)
+            await showPilotActivity(this.page, "Map updated");
+    }
+    /**
+     * Re-detects `here` from the live page, whatever is cached. `here` only changes when this session acts; a person
+     * clicking in a visible session moves the page without it, and later `send` / `reach` calls would use a stale menu.
+     */
+    async resync() {
+        this.page = await ensureLivePage(this.context, this.page, this.startUrl);
+        await showPilotActivity(this.page, "Running: resync");
+        this.here = await detectHere(this.page, this.library.navBlocks);
+        const menu = await this.currentMenu();
+        this.lastRunNote = `resync -> ${this.here ?? "Unknown"}`;
+        return {
+            ok: true,
+            snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
+            quit: false,
+        };
+    }
+    /**
+     * Raw actions for a page no Block covers yet (Blind Pilot). The Checkpoint they land on isn't known ahead, so each
+     * one forgets `here` and the next menu re-detects it. A selector that matches nothing is a reported failure.
+     */
+    async rawClick(selector) {
+        return this.rawStep(`click "${selector}"`, async (page) => {
+            const target = await rawTarget(page, selector, `click: ${selector}`);
+            if (typeof target === "string")
+                return target;
+            await target.click();
+        });
+    }
+    async rawType(selector, text) {
+        return this.rawStep(`type into "${selector}"`, async (page) => {
+            const target = await rawTarget(page, selector, `type: ${selector}`);
+            if (typeof target === "string")
+                return target;
+            await target.fill(text);
+        });
+    }
+    /** Presses a key on an element (`Enter`, `Escape`, ...): inline-edit inputs often commit on Enter, with no Save button. */
+    async rawPress(selector, key) {
+        return this.rawStep(`press "${key}" on "${selector}"`, async (page) => {
+            const target = await rawTarget(page, selector, `press ${key}: ${selector}`);
+            if (typeof target === "string")
+                return target;
+            await target.press(key);
+        });
+    }
+    async rawGoto(url) {
+        return this.rawStep(`goto "${url}"`, async (page) => {
+            try {
+                await page.goto(url, { waitUntil: "domcontentloaded" });
+            }
+            catch (err) {
+                return `goto "${url}" failed - ${err instanceof Error ? err.message : String(err)}`;
+            }
+        });
+    }
+    /** Fills an `<input type="file">` with a built-in stub file ("image", "pdf", "video") or a `filePath` of your own. */
+    async rawUpload(selector, stub) {
+        const filePath = typeof stub === "string" ? stubFilePath(stub) : stub.filePath;
+        const label = typeof stub === "string" ? stub : filePath;
+        return this.rawStep(`upload ${label} into "${selector}"`, async (page) => {
+            const target = await rawTarget(page, selector, `upload ${label}: ${selector}`);
+            if (typeof target === "string")
+                return target;
+            try {
+                await target.setInputFiles(filePath);
+            }
+            catch (err) {
+                return `upload into "${selector}" failed - ${err instanceof Error ? err.message : String(err)}`;
+            }
+        });
+    }
+    /** One raw primitive (no Block): announce it, run it, then forget `here` so the next menu re-detects it. */
+    async rawStep(what, run) {
+        this.page = await ensureLivePage(this.context, this.page, this.startUrl);
+        await showPilotActivity(this.page, `Running (no Block): ${what}`);
+        const failed = await run(this.page);
+        if (failed !== undefined)
+            return { ok: false, error: failed };
+        this.here = null;
+        const menu = await this.currentMenu();
+        this.lastRunNote = `${what} -> ${this.here ?? "Unknown"}`;
+        return {
+            ok: true,
+            snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
+            quit: false,
+        };
+    }
+    /**
+     * Agent-sent highlight fixtures (rings + optional todos) on the live page -
+     * the Pilot equivalent of Block `stubBefore` narration in `waygraph demo`.
+     * Does not run a Block; paint-only. Missing selectors are reported, not fatal.
+     */
+    async applyHighlight(fixtures) {
+        this.page = await ensureLivePage(this.context, this.page, this.startUrl);
+        const detail = describeHighlight(fixtures);
+        // Same bottom-left activity toast as Running (Dom)/(Block) - agent narration.
+        await showPilotActivity(this.page, `Highlighting: ${detail}`);
+        try {
+            for (const line of describeOverlayFixtures("highlight", fixtures))
+                verboseLog("pilot", line);
+            const { painted, missing } = await showPilotFixtures(this.page, fixtures);
+            const menu = await this.currentMenu();
+            this.lastRunNote = fixtures.clear
+                ? "highlight cleared"
+                : `highlight painted ${painted}` +
+                    (missing.length ? ` (missing: ${missing.join(", ")})` : "");
+            return {
+                ok: true,
+                painted,
+                missing,
+                snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
+            };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: `highlight failed - ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    /**
+     * Runs a whole route to `targetCheckpoint` in one call, instead of one `applyPick` per step. The path is computed
+     * once with `findBlockPathDetailed` (the BFS `auto --blocks <From> <To>` uses) and each hop's Block runs directly on
+     * the session's live page and mem, trusting the graph rather than live-menu visibility. Per-step choosing was tried
+     * and fails: a `from: "*"` edge looks reachable from anywhere to a static BFS. A step whose precondition isn't met
+     * fails loud, naming it; so does a step that runs but lands somewhere other than its edge promised.
+     */
+    async applyPath(targetCheckpoint) {
+        await this.currentMenu();
+        const from = this.here;
+        if (from === null) {
+            return { ok: false, error: "cannot path-find: the session's current Checkpoint is unknown (here is null)" };
+        }
+        const path = findBlockPathDetailed(this.graph, from, targetCheckpoint);
+        if (!path) {
+            return { ok: false, error: `no Block path from "${from}" to "${targetCheckpoint}" in the discovered graph` };
+        }
+        for (const step of path) {
+            const entry = this.library.byName.get(step.block);
+            if (!entry) {
+                return { ok: false, error: `path step "${step.block}" is in the discovered graph but not loaded in this session's library` };
+            }
+            if (entry.block.instanceOptions) {
+                return {
+                    ok: false,
+                    error: `path step "${step.block}" needs a specific live option chosen (an instanceOptions Block, e.g. one per product) - ambiguous for automatic routing, use applyPick directly with the specific index`,
+                };
+            }
+            if (this.page)
+                await showPilotActivity(this.page, `Running (Block): ${step.block} (reach -> ${targetCheckpoint})`);
+            const result = await this.runNamedBlock(entry, step.to);
+            if (!result.ok) {
+                return { ok: false, error: `step "${step.block}" failed - ${result.error}` };
+            }
+            // A Block can land somewhere else without throwing (submit-login stays on LoginPage on bad auth): compare with
+            // what this hop's own edge promised (`step.to`; one name can have several edges).
+            if (this.here !== step.to) {
+                return {
+                    ok: false,
+                    error: `step "${step.block}" ran but landed on "${this.here}", not the expected "${step.to}" - it did not throw, but did not make the expected progress either`,
+                };
+            }
+        }
+        return { ok: true, path: path.map((s) => s.block), snapshot: await this.currentSnapshot() };
+    }
+    async close() {
+        await this.context.close();
+        await this.closeBrowser();
+    }
+}

package/dist/live/auto-session/console.d.ts

@@ -0,0 +1,4 @@
+import type { Page } from "@playwright/test";
+import type { ConsoleLogEntry } from "./helpers.js";
+/** Records what the page logs into `push` for `auto console`. */
+export declare function recordPageConsole(page: Page, push: (entry: ConsoleLogEntry) => void): void;

package/dist/live/auto-session/console.js

@@ -0,0 +1,41 @@
+/** Records what the page logs into `push` for `auto console`. */
+export function recordPageConsole(page, push) {
+    // Attached once, on the page created here - `ensureLivePage` only swaps
+    // to a fresh Page if the current one closed (a rare case, e.g. the human
+    // closing the tab), not on ordinary same-page SPA navigation, which is
+    // all this target (and most real sites) actually do.
+    page.on("console", (msg) => {
+        push({
+            type: "console",
+            level: msg.type(),
+            text: msg.text(),
+            timestamp: new Date().toISOString(),
+        });
+    });
+    page.on("pageerror", (err) => {
+        push({
+            type: "pageerror",
+            text: err instanceof Error ? err.message : String(err),
+            timestamp: new Date().toISOString(),
+        });
+    });
+    page.on("response", (res) => {
+        // Every failed response (the original case), PLUS every mutation
+        // (non-GET) response regardless of status - a real gap found live:
+        // "auto console" only logging failures made a SUCCESSFUL POST that
+        // simply didn't navigate anywhere look identical to "nothing
+        // happened at all," undiagnosable the same way a real failure was.
+        // A mutation's outcome (2xx or not) is always diagnostically
+        // relevant; a GET's usually isn't (assets, trackers) unless it failed.
+        const method = res.request().method();
+        if (res.status() < 400 && method === "GET")
+            return;
+        push({
+            type: "response",
+            text: `${method} ${res.statusText()}`,
+            url: res.url(),
+            status: res.status(),
+            timestamp: new Date().toISOString(),
+        });
+    });
+}

package/dist/live/auto-session/files.d.ts

@@ -0,0 +1,44 @@
+export interface SessionMeta {
+    sessionId: string;
+    socketPath: string;
+    pid: number;
+    projectDir: string;
+    startedAt: string;
+    headless: boolean;
+}
+export declare function sessionDir(projectDir: string): string;
+export declare function metaPath(projectDir: string, sessionId: string): string;
+/** Global index so session control works even when cwd ≠ the project that spawned the session. */
+export declare function globalMetaPath(sessionId: string): string;
+export declare function isPidAlive(pid: number): boolean;
+/**
+ * Deliberately NOT under the project directory (unlike meta/log files) -
+ * a real bug found while proving out openspec/changes/waygraph-map's own
+ * "waypack" loading claim: a project loaded through a consumer's own deeply
+ * nested `node_modules/<pkg>` path can push the socket's absolute path past
+ * the OS's AF_UNIX `sun_path` limit (~108 bytes on Linux), failing with
+ * `listen EINVAL`. A short, fixed-location directory sidesteps this
+ * regardless of how deep `projectDir` itself is nested. `sessionId` alone
+ * (8 hex chars, `generateSessionId()`) is enough to keep this collision-safe
+ * across every project on the machine sharing this one flat directory - the
+ * same randomness space this package already relied on per-project.
+ */
+export declare function socketDir(): string;
+export declare function socketPathFor(sessionId: string): string;
+export declare function logPathFor(projectDir: string, sessionId: string): string;
+export declare function generateSessionId(): string;
+export declare function readSessionMeta(projectDir: string, sessionId: string): SessionMeta | null;
+/**
+ * Resolve session metadata from a project hint (cwd) or the global registry.
+ * Fixes "session unreachable" when the agent calls status/send from a different
+ * directory or pane than the one that ran `pilot start`.
+ */
+export declare function resolveSessionMeta(sessionId: string, projectDirHint?: string): SessionMeta | null;
+export declare function writeGlobalSessionMeta(meta: SessionMeta): void;
+export declare function removeSessionFiles(projectDir: string, sessionId: string): void;
+/** Stop one detached session (SIGTERM + cleanup metadata/socket). */
+export declare function stopBrowserSession(projectDir: string, sessionId: string): boolean;
+/** Stop every live session registered for a project. */
+export declare function stopAllBrowserSessions(projectDir: string): number;
+/** Live browser sessions for a project (metadata + socket + pid still present). */
+export declare function listBrowserSessions(projectDir: string): SessionMeta[];