waygraph 0.13.6 → 0.14.0

package/dist/auto-session.d.ts

@@ -0,0 +1,342 @@
+import { type BlockEntry, type ExploreMenu } from "./auto-explore.js";
+import { type PickResult } from "./auto-explore-run.js";
+import { type StubPhaseResult } from "./highlights.js";
+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.
+ */
+export declare function parsePick(raw: string, menuLength: number): 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 interface AutoSessionInit {
+    projectDir: string;
+    baseURL?: string;
+    startUrl?: string;
+    blocksSelect?: import("./blocks-select.js").BlocksSelect;
+    /** 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 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 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[];
+}
+/**
+ * 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 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 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;
+    /**
+     * Real, direct user request: a Blind Pilot agent had no way to ask "which
+     * of the links visible on THIS page are already covered by a NavBlock" -
+     * only manual DOM inspection + guessing hrefs, exactly what this session
+     * had been doing by hand the whole time this feature was built. Compares
+     * every same-origin `<a href>` on the page against every NavBlock's own
+     * static url (`__waygraphNavUrl` - see `defineNavBlock`'s own comment for
+     * why only plain-string urls qualify), and `console.warn()`s each pathname
+     * with no NavBlock at all - surfaced through the same real console capture
+     * `auto console` already reads, not a separate channel. Deduped per path
+     * per page load (a `Set` living on `window`, so it survives repeated
+     * `currentMenu()` calls but resets on a real navigation) - once is enough
+     * to flag a gap, repeating it on every status/send call would just be noise.
+     */
+    private warnUnmappedLinks;
+    /** 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>;
+    /**
+     * 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>;
+}