waygraph 0.15.26 → 0.15.27

package/dist/auto-session/helpers.d.ts

@@ -0,0 +1,203 @@
+import type { StubPhaseResult } from "../highlights.js";
+import type { BlockEntry, ExploreMenu } from "../auto-explore.js";
+import type { PickResult } from "../auto-explore-run.js";
+/** True when a stub-phase result actually carries authored content worth keeping. */
+export declare function stubPhaseHasContent(r: StubPhaseResult): boolean;
+export interface SessionSnapshotEdge {
+    /** 1-based, matching the numbers a human/agent picks by (same as printCliMenu). */
+    index: number;
+    block: string;
+    kind: "nav" | "action";
+    to: string;
+    label?: string;
+    description?: string;
+}
+export interface SessionSnapshotSection {
+    title: string;
+    edges: SessionSnapshotEdge[];
+}
+export interface SessionSnapshot {
+    here: string | null;
+    sections: SessionSnapshotSection[];
+    /** True when there are no runnable moves from `here` right now. */
+    done: boolean;
+    lastRunNote: string | null;
+}
+/** Plain, JSON-serializable view of a menu - no Block/MemKey/class references. */
+export declare function buildSessionSnapshot(menu: ExploreMenu, library: Map<string, BlockEntry>, here: string | null, lastRunNote: string | null): SessionSnapshot;
+export type ParsedPick = PickResult | {
+    type: "invalid";
+    reason: string;
+};
+/**
+ * Same number/`q`/range rules `cliPick` already applies, but returning a
+ * result instead of looping to re-prompt - one request gets one answer.
+ * Also accepts a Block name (exact, case-sensitive) as a shorthand for its
+ * menu index - `send <id> "submit-login"` instead of hunting the number.
+ * Ambiguous (the same Block name appearing more than once in one menu)
+ * refuses rather than guessing which occurrence was meant - a pick runs a
+ * real browser action, not something to silently get wrong.
+ */
+export declare function parsePick(raw: string, menu: {
+    readonly flat: readonly {
+        readonly block: string;
+    }[];
+}): ParsedPick;
+export interface DomSnapshot {
+    mode: "aria" | "full";
+    selector?: string;
+    /** Always false for aria mode - Playwright's own ariaSnapshotJSON bounds itself. */
+    truncated: boolean;
+    tree: unknown;
+}
+export interface InspectDomOptions {
+    mode?: "aria" | "full";
+    /** Scopes either mode to one element's subtree - a modifier, not a third mode. */
+    selector?: string;
+    depth?: number;
+}
+export type InspectDomResult = {
+    ok: true;
+    snapshot: DomSnapshot;
+} | {
+    ok: false;
+    error: string;
+};
+export declare const FULL_MODE_DEFAULT_DEPTH = 12;
+export declare const FULL_MODE_MAX_NODES = 800;
+export declare const FULL_MODE_MAX_TEXT_LENGTH = 300;
+interface FullDomNode {
+    tag: string;
+    attrs?: Record<string, string>;
+    text?: string;
+    children?: FullDomNode[];
+}
+export interface FullDomCaps {
+    depth: number;
+    maxNodes: number;
+    maxTextLength: number;
+}
+/** Runs entirely inside the browser (page.evaluate) - no closures over outer TS state. */
+export declare function walkFullDom(root: Element, caps: FullDomCaps): {
+    tree: FullDomNode;
+    truncated: boolean;
+};
+export interface AutoSessionInit {
+    projectDir: string;
+    baseURL?: string;
+    startUrl?: string;
+    blocksSelect?: import("../blocks-select.js").BlocksSelect;
+    /** Absolute paths — merged Block libraries (see `waygraph browser --inject`). */
+    inject?: string[];
+    /** When true, open about:blank instead of baseURL/startUrl (browser default). */
+    skipInitialNavigation?: boolean;
+    /** Default true. false launches a real visible browser window. */
+    headless?: boolean;
+    /**
+     * Shown on the on-page Pilot overlay badge, when known - purely cosmetic,
+     * this class has no other use for it. `auto --cli --detach`'s spawned
+     * child (`runAutoServeCommand`) always knows and passes its own generated
+     * id; a directly-constructed `AutoSession` (e.g. in a test) simply omits
+     * it, and the badge shows "no session id" instead.
+     */
+    sessionId?: string;
+}
+export type ApplyPickResult = {
+    ok: true;
+    snapshot: SessionSnapshot;
+    quit: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+export type ApplyPathResult = {
+    ok: true;
+    path: string[];
+    snapshot: SessionSnapshot;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * One Checkpoint/Block-level step in a session's history - not a raw action
+ * recording (no clicks/fills). Kept lean by design: an agent that wants DOM
+ * evidence at a specific step already has `inspectDom` to call itself.
+ */
+export interface TraceStep {
+    block: string;
+    from: string | null;
+    to?: string;
+    error?: string;
+    timestamp: string;
+    /**
+     * Resolved demo-narration fixtures (highlights/todos/device), when the
+     * Block actually authors `stubBefore`/`stubAfter`/`stubOnError` - the same
+     * data `waygraph demo`'s lifecycle logging already computes (`runStubPhase`
+     * in highlights.ts), reused here for extra context on what a step meant to
+     * convey. Omitted when the Block has none, or the result carries nothing.
+     */
+    stubBefore?: StubPhaseResult;
+    stubAfter?: StubPhaseResult;
+    stubOnError?: StubPhaseResult;
+}
+export declare const TRACE_MAX_STEPS = 500;
+export type StubFileKind = "image" | "pdf" | "video";
+/**
+ * Real, minimal, valid fixture files bundled at `assets/stubs/` - not
+ * placeholder/renamed-empty files: `stub.png` is a real 1x1 PNG,
+ * `stub.pdf` a real single-page PDF, `stub.mp4` a real ffmpeg-encoded
+ * 1s black clip. Real, direct user request: Blind Pilot hitting a real
+ * `<input type="file">` (e.g. an avatar upload) had no way to supply
+ * anything without a human handing over a real file each time - these are
+ * small enough to ship in the package and pass most apps' basic file-type
+ * checks (magic bytes, not just extension).
+ */
+/**
+ * Public so a Block a consumer writes can reach the same real fixture files
+ * `rawUpload` uses - not just the raw primitive. Needed when a real upload
+ * flow has no stable `<input type="file">` to hand a selector to at all
+ * (e.g. one created on the fly inside a click handler, then immediately
+ * `.click()`'d to open the OS picker and possibly torn down right after) -
+ * a Block's own `act()` should pair this with `page.waitForEvent("filechooser")`
+ * around the triggering click, not go hunting for a selector that may not
+ * exist for more than a moment.
+ */
+export declare function stubFilePath(kind: StubFileKind): string;
+/**
+ * Real gap found live (Blind Pilot against veciro.com): a form submit that
+ * does nothing observable in the DOM - no navigation, no visible error text -
+ * is undiagnosable through `inspectDom` alone, since a silent client-side
+ * validation failure or a failed network request never touches the DOM at
+ * all. `auto dom` reads what's rendered; this reads what the page/network
+ * actually SAID, independent of whether the app chose to show it.
+ */
+export interface ConsoleLogEntry {
+    type: "console" | "pageerror" | "response";
+    level?: string;
+    text: string;
+    url?: string;
+    status?: number;
+    timestamp: string;
+}
+export declare const CONSOLE_LOG_MAX_ENTRIES = 200;
+export interface ServiceWorkerRegistrationInfo {
+    scope: string;
+    activeUrl?: string;
+    state?: string;
+}
+export interface CookieInfo {
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    httpOnly: boolean;
+    secure: boolean;
+}
+export interface StorageSnapshot {
+    localStorage: Record<string, string>;
+    sessionStorage: Record<string, string>;
+    cookies: CookieInfo[];
+    serviceWorkers: string[];
+    serviceWorkerRegistrations: ServiceWorkerRegistrationInfo[];
+}
+export {};

package/dist/auto-session/helpers.js

@@ -0,0 +1,148 @@
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/** True when a stub-phase result actually carries authored content worth keeping. */
+export function stubPhaseHasContent(r) {
+    return (Object.keys(r.highlights).length > 0 ||
+        r.todos.length > 0 ||
+        r.device !== undefined ||
+        r.todoDock !== undefined);
+}
+/** Plain, JSON-serializable view of a menu - no Block/MemKey/class references. */
+export function buildSessionSnapshot(menu, library, here, lastRunNote) {
+    let n = 0;
+    const sections = menu.sections.map((section) => ({
+        title: section.title,
+        edges: section.edges.map((edge) => {
+            n++;
+            const entry = library.get(edge.block);
+            return {
+                index: n,
+                block: edge.block,
+                kind: edge.kind,
+                to: edge.to,
+                ...(edge.label ? { label: edge.label } : {}),
+                ...(entry?.description ? { description: entry.description } : {}),
+            };
+        }),
+    }));
+    return { here, sections, done: menu.flat.length === 0, lastRunNote };
+}
+/**
+ * Same number/`q`/range rules `cliPick` already applies, but returning a
+ * result instead of looping to re-prompt - one request gets one answer.
+ * Also accepts a Block name (exact, case-sensitive) as a shorthand for its
+ * menu index - `send <id> "submit-login"` instead of hunting the number.
+ * Ambiguous (the same Block name appearing more than once in one menu)
+ * refuses rather than guessing which occurrence was meant - a pick runs a
+ * real browser action, not something to silently get wrong.
+ */
+export function parsePick(raw, menu) {
+    const ans = raw.trim();
+    const lower = ans.toLowerCase();
+    if (lower === "q" || lower === "quit")
+        return { type: "quit" };
+    const n = Number(lower);
+    if (Number.isInteger(n) && n >= 1 && n <= menu.flat.length) {
+        return { type: "pick", index: n - 1 };
+    }
+    const matches = [];
+    menu.flat.forEach((edge, i) => {
+        if (edge.block === ans)
+            matches.push(i);
+    });
+    if (matches.length === 1) {
+        return { type: "pick", index: matches[0] };
+    }
+    if (matches.length > 1) {
+        return {
+            type: "invalid",
+            reason: `"${raw}" matches ${matches.length} menu entries - use the numeric index instead of the Block name`,
+        };
+    }
+    return {
+        type: "invalid",
+        reason: `"${raw}" is not a valid pick - enter a number from 1 to ${menu.flat.length}, a Block name, or "q" to quit`,
+    };
+}
+export const FULL_MODE_DEFAULT_DEPTH = 12;
+export const FULL_MODE_MAX_NODES = 800;
+export const FULL_MODE_MAX_TEXT_LENGTH = 300;
+/** Runs entirely inside the browser (page.evaluate) - no closures over outer TS state. */
+export function walkFullDom(root, caps) {
+    let count = 0;
+    let truncated = false;
+    function walk(el, depth) {
+        if (depth > caps.depth) {
+            truncated = true;
+            return null;
+        }
+        if (count >= caps.maxNodes) {
+            truncated = true;
+            return null;
+        }
+        count++;
+        const node = { tag: el.tagName.toLowerCase() };
+        const attrs = {};
+        for (const a of Array.from(el.attributes))
+            attrs[a.name] = a.value;
+        if (Object.keys(attrs).length > 0)
+            node.attrs = attrs;
+        const directText = Array.from(el.childNodes)
+            .filter((n) => n.nodeType === 3)
+            .map((n) => n.textContent ?? "")
+            .join("")
+            .trim();
+        if (directText) {
+            node.text =
+                directText.length > caps.maxTextLength
+                    ? directText.slice(0, caps.maxTextLength) + "..."
+                    : directText;
+        }
+        const children = [];
+        for (const child of Array.from(el.children)) {
+            if (count >= caps.maxNodes) {
+                truncated = true;
+                break;
+            }
+            const c = walk(child, depth + 1);
+            if (c)
+                children.push(c);
+        }
+        if (children.length > 0)
+            node.children = children;
+        return node;
+    }
+    const tree = walk(root, 0) ?? { tag: root.tagName.toLowerCase() };
+    return { tree, truncated };
+}
+export const TRACE_MAX_STEPS = 500;
+/**
+ * Real, minimal, valid fixture files bundled at `assets/stubs/` - not
+ * placeholder/renamed-empty files: `stub.png` is a real 1x1 PNG,
+ * `stub.pdf` a real single-page PDF, `stub.mp4` a real ffmpeg-encoded
+ * 1s black clip. Real, direct user request: Blind Pilot hitting a real
+ * `<input type="file">` (e.g. an avatar upload) had no way to supply
+ * anything without a human handing over a real file each time - these are
+ * small enough to ship in the package and pass most apps' basic file-type
+ * checks (magic bytes, not just extension).
+ */
+/**
+ * Public so a Block a consumer writes can reach the same real fixture files
+ * `rawUpload` uses - not just the raw primitive. Needed when a real upload
+ * flow has no stable `<input type="file">` to hand a selector to at all
+ * (e.g. one created on the fly inside a click handler, then immediately
+ * `.click()`'d to open the OS picker and possibly torn down right after) -
+ * a Block's own `act()` should pair this with `page.waitForEvent("filechooser")`
+ * around the triggering click, not go hunting for a selector that may not
+ * exist for more than a moment.
+ */
+export function stubFilePath(kind) {
+    const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+    const names = {
+        image: "stub.png",
+        pdf: "stub.pdf",
+        video: "stub.mp4",
+    };
+    return join(packageRoot, "assets", "stubs", names[kind]);
+}
+export const CONSOLE_LOG_MAX_ENTRIES = 200;

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

@@ -0,0 +1,191 @@
+import type { ApplyPathResult, ApplyPickResult, AutoSessionInit, ConsoleLogEntry, InspectDomOptions, InspectDomResult, SessionSnapshot, StorageSnapshot, StubFileKind, TraceStep } from "./helpers.js";
+import type { PilotHighlightFixtures } from "../pilot-overlay.js";
+/**
+ * Non-interactive explore session: same graph/library/mem/browser setup
+ * `runAutoExplore` runs in `--cli` mode, driven by `applyPick` instead of a
+ * blocking `readline` loop. Headless by default (matching
+ * `runAutoExplore`'s own `cli` branch), optionally visible via
+ * `AutoSessionInit.headless: false` - this type only ever backs the `--cli`
+ * picker, never the headful page-embedded panel, headless or not.
+ */
+export declare class AutoSession {
+    private readonly projectDir;
+    private readonly inject;
+    private readonly blocksSelect;
+    private graph;
+    private library;
+    private readonly mem;
+    private readonly engine;
+    private readonly browser;
+    private readonly context;
+    private page;
+    private readonly startUrl;
+    private readonly sessionId;
+    private here;
+    private lastRunNote;
+    private readonly trace;
+    private readonly consoleLog;
+    private readonly knownInteractionSelectors;
+    private readonly headless;
+    private lastOverlayInfo;
+    private constructor();
+    static start(init: AutoSessionInit): Promise<AutoSession>;
+    /** Pure getter - returns a copy, not the live array. */
+    getTrace(): TraceStep[];
+    private pushTrace;
+    /** Pure getter - returns a copy, not the live array. */
+    getConsoleLog(): ConsoleLogEntry[];
+    private pushConsoleLog;
+    private currentMenu;
+    /** Paint the overlay on about:blank / immediately after session start (headful browser). */
+    private bootstrapOverlay;
+    /** Re-apply cached overlay state after navigation (init script restores shell only). */
+    private repaintOverlayAfterNavigation;
+    /**
+     * 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.
+     */
+    private warnUnmappedInteractions;
+    /** Pure getter - no Block runs, no mem/page mutation. */
+    currentSnapshot(): Promise<SessionSnapshot>;
+    /**
+     * 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.
+     */
+    inspectDom(opts: InspectDomOptions): Promise<InspectDomResult>;
+    /**
+     * Pure getter - reads the live page's client-side state: localStorage,
+     * sessionStorage, and registered service workers (scope/active URL/state).
+     * Real, direct follow-up to `auto console`'s own gap: a site doing web
+     * push (this target has a real `NOTIFICATION_VAPID` config, confirmed via
+     * `auto dom` earlier) keeps push-subscription/auth state in these places,
+     * not in the rendered DOM `inspectDom` reads.
+     */
+    inspectStorage(): Promise<StorageSnapshot>;
+    /**
+     * Runs one already-resolved Block entry for real - the shared core both
+     * `applyPick` (resolved via a live-menu index) and `applyPath` (resolved
+     * directly by name, bypassing live-menu-visibility entirely - see
+     * `applyPath`'s own comment for why) call. `expectedTo` is only used as a
+     * fallback when a Block's own `resolve()` doesn't set `__state` - same
+     * behavior `applyPick` always had, just factored out, not changed.
+     */
+    private runNamedBlock;
+    /** Applies exactly one pick: runs at most one Block, returns the resulting state. */
+    applyPick(raw: string): Promise<ApplyPickResult>;
+    /**
+     * Re-discovers the project's Block library and graph from disk, using the
+     * exact same call `start()` itself makes - not a duplicated read - and
+     * replaces `this.library`/`this.graph` in place. Leaves the live page,
+     * mem, browser/context, and current Checkpoint (`here`) untouched, so a
+     * Block written to disk mid-session becomes pickable via a later
+     * `applyPick` without restarting the session. See
+     * openspec/changes/waygraph-blind-pilot/design.md.
+     */
+    reloadLibrary(): Promise<void>;
+    /**
+     * Forces `here` to be re-detected from the real live page, discarding
+     * whatever was cached - the fix for a real, confirmed gap: `here` is only
+     * ever updated by an action this class itself ran (`applyPick`/`applyPath`
+     * set it to a Block's own resolved Checkpoint; `rawClick`/`rawType`/
+     * `rawGoto` reset it to `null` because *they* just changed the page). If a
+     * human co-driving the same visible session clicks/types/navigates
+     * directly - a real scenario for a headful Pilot session someone is
+     * watching, not hypothetical - none of that goes through this class at
+     * all, so `here` silently goes stale: `currentMenu()`'s own lazy check
+     * (`if (this.here === null)`, just above) only re-detects when `here` is
+     * already unknown, never to confirm a *known* value is still correct.
+     * This does not crash the session (the process/socket/page all stay
+     * alive) but subsequent `send`/`reach` calls would act on a menu built
+     * from the wrong Checkpoint until something forces re-detection - this
+     * method is that: unconditionally re-run the same `detectHere` logic the
+     * lazy path already uses, regardless of what `here` currently holds.
+     */
+    resync(): Promise<ApplyPickResult>;
+    /**
+     * Raw interaction primitives for a page no Block covers yet (Blind Pilot -
+     * see openspec/changes/waygraph-blind-pilot). Unlike `applyPick`, the
+     * resulting Checkpoint isn't known ahead of time from a Block's own
+     * `resolve()`, so each of these invalidates the cached `here` (forcing
+     * `currentMenu()`'s existing lazy `detectHere` call to run again) rather
+     * than assuming the page didn't move anywhere a Block now recognizes.
+     * A selector matching nothing is a reported failure, not a silent no-op.
+     */
+    rawClick(selector: string): Promise<ApplyPickResult>;
+    rawType(selector: string, text: string): Promise<ApplyPickResult>;
+    /**
+     * Presses a real key on a real focused element - a real gap found live:
+     * many real inline-edit inputs (no visible Save button at all) commit on
+     * Enter, not on blur/click-elsewhere. `key` is a Playwright key name
+     * (e.g. "Enter", "Escape", "Tab") - same vocabulary as
+     * `page.keyboard.press`, which this wraps.
+     */
+    rawPress(selector: string, key: string): Promise<ApplyPickResult>;
+    rawGoto(url: string): Promise<ApplyPickResult>;
+    /**
+     * Fills a real `<input type="file">` - a built-in stub kind
+     * ("image"/"pdf"/"video", see `stubFilePath`) or a caller-supplied
+     * `filePath` for anything else ("whatever", per the real request this
+     * responds to). Same raw-primitive shape as click/type/goto: works with
+     * zero Blocks, invalidates `here` since the app may react to the upload.
+     */
+    rawUpload(selector: string, stub: StubFileKind | {
+        filePath: string;
+    }): Promise<ApplyPickResult>;
+    /**
+     * 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.
+     */
+    applyHighlight(fixtures: PilotHighlightFixtures): Promise<{
+        ok: true;
+        painted: number;
+        missing: string[];
+        snapshot: SessionSnapshot;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    /**
+     * Runs a whole multi-step route to `targetCheckpoint` in one call, instead
+     * of an agent hand-picking one index at a time across many separate
+     * `applyPick` round trips - real, reported pain for any non-trivial task
+     * on a rich graph ("the entire prompts of the day" driving one step per
+     * call).
+     *
+     * Two other designs were tried and rejected by direct reproduction against
+     * live saucedemo.com before this one, both undone by the same root cause:
+     * a `from: "*"` edge (e.g. "Checkout", only clickable once you're actually
+     * on the cart page with items) looks globally reachable to
+     * `findBlockPath`'s static-graph BFS, which has no live-page access and
+     * can't know the edge's real precondition isn't showing yet. Computing the
+     * whole route once upfront names a premature wildcard step immediately;
+     * scoring each live menu option by its static-graph distance to the
+     * target (greedy best-first) doesn't fix it either - a harmless self-loop
+     * Method can score just as well as real progress once wildcard "shortcuts"
+     * are baked into every distance calculation, and the session gets stuck
+     * repeating it.
+     *
+     * The fix that actually works: stop trying to be clever about live-menu
+     * visibility per step, and reuse `auto --blocks <From> <To>`'s own already
+     * -proven approach instead - compute the path ONCE (via
+     * `findBlockPathDetailed`, the same BFS `findBlockPath`/`runChainAuto`
+     * already use, extended to also return each hop's specific edge - see its
+     * own doc comment for why that extra detail is load-bearing, not cosmetic),
+     * then run each Block in it directly via `runNamedBlock`, trusting the
+     * graph the same way `runChain`'s own flow execution already does, not
+     * gated on live-menu visibility at all. The one real difference from
+     * `runChainAuto`: this runs against the session's own already-live
+     * page/context/mem, not a freshly spawned browser - the whole point of
+     * staying in one session. A step whose real precondition genuinely isn't
+     * met still fails loud, naming that step, exactly the way a mis-ordered
+     * `runChain` spec would - and a step that runs without throwing but lands
+     * somewhere other than what its own edge promised (a real, observed case,
+     * not hypothetical - see this method's own test suite) fails loud too,
+     * rather than reporting false success.
+     */
+    applyPath(targetCheckpoint: string): Promise<ApplyPathResult>;
+    close(): Promise<void>;
+}