waygraph 0.15.26 → 0.15.28

package/dist/auto-session.d.ts

@@ -1,369 +1,2 @@
-import { type BlockEntry, type ExploreMenu } from "./auto-explore.js";
-import { type PickResult } from "./auto-explore-run.js";
-import { type StubPhaseResult } from "./highlights.js";
-import type { PilotHighlightFixtures } from "./pilot-overlay.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.
- * 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 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 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 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>;
-}
+export * from "./auto-session/helpers.js";
+export * from "./auto-session/session.js";