@dikshanty94/webnav 0.2.0

package/dist/router/walk-live.js

@@ -0,0 +1,308 @@
+import { PlaywrightAdapter } from '../playwright/adapter.js';
+import { MapStore } from '../mapstore/store.js';
+import { parseSnapshot, findByRoleAndName } from '../playwright/snapshot.js';
+import { makeState, makeAffordance } from '../mapstore/types.js';
+import { walkRoute } from './walk.js';
+/**
+ * Seed the `www.saucedemo.com` page-states + navigation edges inline (STRUCTURE
+ * ONLY, principle #6 — no credentials/names/zips; those are runtime, supplied by
+ * the live browser closure). This replaces the old hand-seeded saucedemo skeleton:
+ * saucedemo is now an agent-built `www.saucedemo.com` graph, and the multi-step
+ * walk seeds its interior inline here for the live wiring + gated e2es.
+ *
+ * Idempotent: upsertState (ON CONFLICT id) and upsertEdge (UNIQUE from,to,step).
+ */
+export function seedSaucedemoForWalk(store) {
+    const N = 'www.saucedemo.com';
+    store.transaction(() => {
+        // The site-node row (so getNode works — needed by the dashboard, the hosted
+        // map pack, and /api/maps). The interior states below are its skeleton.
+        store.upsertNode({ id: N, homeUrl: 'https://www.saucedemo.com/' });
+        // Each state's REPERTOIRE is the source of truth (spec §8). navigate/reveal
+        // affordances with a toState project into the walk's edges; mutate/input never
+        // route (they're fired by the agent at a pause if it wants them). The "Finish"
+        // affordance is commit:true → it projects as a commit-point and is NEVER fired (#2).
+        const states = [
+            makeState({ id: `${N}:login`, nodeId: N, semanticName: `${N}:login`,
+                urlPattern: 'https://www.saucedemo.com/', role: 'detail',
+                fingerprint: ['textbox:Username', 'button:Login'],
+                affordances: [
+                    makeAffordance({ id: 'aff_username', label: 'enter Username', kind: 'input' }),
+                    makeAffordance({ id: 'aff_password', label: 'enter Password', kind: 'input' }),
+                    makeAffordance({ id: 'aff_login', label: 'log in by clicking "Login"', kind: 'navigate',
+                        toState: `${N}:inventory`, needs: ['aff_username', 'aff_password'], acceptsInput: 'credentials', core: true }),
+                ] }),
+            makeState({ id: `${N}:inventory`, nodeId: N, semanticName: `${N}:inventory`,
+                urlPattern: '*inventory*', role: 'detail', fingerprint: ['button:Add to cart'],
+                affordances: [
+                    makeAffordance({ id: 'aff_cart', label: 'open the shopping cart', kind: 'navigate',
+                        toState: `${N}:cart`, addressableUrl: 'https://www.saucedemo.com/cart.html', core: true }),
+                    makeAffordance({ id: 'aff_sort', label: 'sort products', kind: 'mutate' }),
+                    makeAffordance({ id: 'aff_addcart', label: 'add an item to the cart', kind: 'mutate' }),
+                    makeAffordance({ id: 'aff_menu', label: 'open the burger menu', kind: 'reveal', children: [
+                            makeAffordance({ id: 'aff_allitems', label: 'All Items', kind: 'navigate', toState: `${N}:inventory` }),
+                            makeAffordance({ id: 'aff_about', label: 'About', kind: 'navigate', toState: null }), // unexplored (offsite)
+                            makeAffordance({ id: 'aff_logout', label: 'Logout', kind: 'navigate', toState: `${N}:login` }),
+                            makeAffordance({ id: 'aff_reset', label: 'Reset App State', kind: 'mutate' }),
+                        ] }),
+                ] }),
+            makeState({ id: `${N}:cart`, nodeId: N, semanticName: `${N}:cart`,
+                urlPattern: '*cart*', role: 'detail', fingerprint: ['button:Checkout'],
+                affordances: [
+                    makeAffordance({ id: 'aff_checkout', label: 'click "Checkout"', kind: 'navigate',
+                        toState: `${N}:checkout-info`, core: true }),
+                    makeAffordance({ id: 'aff_continue_shopping', label: 'Continue Shopping', kind: 'navigate',
+                        toState: `${N}:inventory` }),
+                ] }),
+            makeState({ id: `${N}:checkout-info`, nodeId: N, semanticName: `${N}:checkout-info`,
+                urlPattern: '*checkout-step-one*', role: 'detail', fingerprint: ['textbox:First Name', 'button:Continue'],
+                affordances: [
+                    makeAffordance({ id: 'aff_first', label: 'enter First Name', kind: 'input' }),
+                    makeAffordance({ id: 'aff_last', label: 'enter Last Name', kind: 'input' }),
+                    makeAffordance({ id: 'aff_zip', label: 'enter Zip/Postal Code', kind: 'input' }),
+                    makeAffordance({ id: 'aff_continue', label: 'click "Continue"', kind: 'navigate',
+                        toState: `${N}:checkout-overview`, needs: ['aff_first', 'aff_last', 'aff_zip'], acceptsInput: 'shipping', core: true }),
+                ] }),
+            makeState({ id: `${N}:checkout-overview`, nodeId: N, semanticName: `${N}:checkout-overview`,
+                urlPattern: '*checkout-step-two*', role: 'detail', fingerprint: ['button:Finish'],
+                affordances: [
+                    makeAffordance({ id: 'aff_finish', label: 'click "Finish"', kind: 'navigate',
+                        toState: `${N}:purchase-complete`, commit: true }),
+                ] }),
+        ];
+        for (const s of states)
+            store.upsertState(s);
+    });
+}
+/**
+ * Build a live WalkBrowser over a playwright adapter, resolving each edge's input
+ * slot from `inputs` at fill time. `inputs` is held only in memory here — never
+ * persisted. Shared by runWalkLive and the walk / walk-resume CLI verbs.
+ *
+ * `browserOpts` (the SAME launch opts — incl. `profile` — the caller opened
+ * `adapter` with) enables the fresh-session SSO-wall retry (design item 2):
+ * when supplied, the returned WalkBrowser gets `currentUrl`/`reopenFresh` so
+ * walkRoute can close this session and open a brand-new one under the SAME
+ * profile on a wall. Omit it (as the saucedemo dry-run wiring below does) to
+ * leave those capabilities off — the walk simply never attempts the retry.
+ */
+export function makeLiveWalkBrowser(adapter, inputs, browserOpts, initialSessionId) {
+    let live = adapter;
+    let liveSessionId = initialSessionId ?? '';
+    let lastSnapshot = '';
+    async function fieldRef(name) {
+        let nodes = parseSnapshot(lastSnapshot);
+        let node = findByRoleAndName(nodes, 'textbox', name);
+        if (!node || !node.ref) {
+            lastSnapshot = await live.snapshot();
+            nodes = parseSnapshot(lastSnapshot);
+            node = findByRoleAndName(nodes, 'textbox', name);
+        }
+        if (!node || !node.ref)
+            throw new Error('walk: could not resolve textbox "' + name + '"');
+        return node.ref;
+    }
+    const browser = {
+        snapshot: async () => {
+            lastSnapshot = await live.snapshot();
+            return lastSnapshot;
+        },
+        callCount: () => live.callCount,
+        goto: async (url) => { await live.goto(url); },
+        waitMs: (ms) => new Promise((r) => setTimeout(r, ms)),
+        act: async (ref, inputSlot) => {
+            if (inputSlot === 'credentials') {
+                await live.fill(await fieldRef('Username'), inputs.username);
+                await live.fill(await fieldRef('Password'), inputs.password);
+                await live.click(ref);
+                return;
+            }
+            if (inputSlot === 'shipping') {
+                await live.fill(await fieldRef('First Name'), inputs.firstName ?? 'A');
+                await live.fill(await fieldRef('Last Name'), inputs.lastName ?? 'B');
+                await live.fill(await fieldRef('Zip/Postal Code'), inputs.zip);
+                await live.click(ref);
+                return;
+            }
+            await live.click(ref);
+        },
+    };
+    if (browserOpts) {
+        browser.currentUrl = () => live.currentUrl();
+        browser.close = () => live.close().then(() => undefined);
+        browser.sessionId = () => liveSessionId;
+        // Close the walled session, open a FRESH one under the SAME profile (same
+        // identity/cookies — equivalent to the user reopening a tab; NOT evasion),
+        // land back on `url`. Never throws on the close (best-effort cleanup).
+        browser.reopenFresh = async (url) => {
+            await live.close().catch(() => { });
+            liveSessionId = 'w-' + Date.now();
+            live = new PlaywrightAdapter(liveSessionId, undefined, undefined, browserOpts);
+            await live.open(url);
+            lastSnapshot = await live.snapshot();
+            return lastSnapshot;
+        };
+    }
+    return browser;
+}
+/**
+ * Live wiring for the saucedemo multi-step walk (increment W2).
+ *
+ * Drives the REAL PlaywrightAdapter against live saucedemo.com through the SAME
+ * async `walkRoute` loop the unit test exercises (zero duplicated loop logic).
+ *
+ * The walk is runtime-value-free: it only passes each edge's `acceptsInput` slot
+ * NAME to `act`. THIS closure owns the `inputs` map and resolves slot -> value(s)
+ * when filling fields (principle #6: inputs are runtime, never stored as map).
+ *
+ * Goal is `www.saucedemo.com:checkout-overview` (a PASS-THROUGH state), so the walk
+ * HALTS there and returns `done` WITHOUT ever attempting the next edge — the
+ * unclassified "Finish" commit point is never fired (principle #2).
+ */
+export async function runWalkLive(inputs, dbPath) {
+    // 1. File-backed MapStore; DB is authoritative — the saucedemo interior is written
+    //    inline here (saucedemo is no longer part of the seeded graph). If it's absent,
+    //    the walk seeds it once (the single bootstrap).
+    const store = new MapStore(dbPath);
+    if (!store.getState('www.saucedemo.com:checkout-overview')) {
+        seedSaucedemoForWalk(store);
+    }
+    // 2. Open a real browser session on the saucedemo login page.
+    const adapter = new PlaywrightAdapter('sd-' + Date.now());
+    await adapter.open('https://www.saucedemo.com/');
+    // Cache the most recent snapshot so `act` can resolve input fields by role+name
+    // WITHOUT an extra playwright call. The walk always snapshots immediately before
+    // calling act() (the top-of-loop read), so `lastSnapshot` is the current page.
+    let lastSnapshot = '';
+    // Resolve a textbox ref by its accessible name on the current (cached) page.
+    // Falls back to a fresh snapshot if the cache is somehow empty (counts as a call).
+    async function fieldRef(name) {
+        let nodes = parseSnapshot(lastSnapshot);
+        let node = findByRoleAndName(nodes, 'textbox', name);
+        if (!node || !node.ref) {
+            lastSnapshot = await adapter.snapshot();
+            nodes = parseSnapshot(lastSnapshot);
+            node = findByRoleAndName(nodes, 'textbox', name);
+        }
+        if (!node || !node.ref) {
+            throw new Error('walk-live: could not resolve textbox "' + name + '" on current page');
+        }
+        return node.ref;
+    }
+    // 3. Build the live WalkBrowser. `act` performs the per-edge field-fills BEFORE
+    //    the resolved click. saucedemo steps are multi-field, so a single edge's act
+    //    fans out into several adapter calls — the walk stays a single linear loop.
+    const browser = {
+        snapshot: async () => {
+            lastSnapshot = await adapter.snapshot();
+            return lastSnapshot;
+        },
+        callCount: () => adapter.callCount,
+        waitMs: (ms) => new Promise((r) => setTimeout(r, ms)),
+        // Tier-1 addressable jump: the walk calls this for an edge with addressableUrl
+        // (the cart link is icon-only / unstable on saucedemo, but cart.html is canonical).
+        goto: async (url) => { await adapter.goto(url); },
+        act: async (ref, inputSlot) => {
+            if (inputSlot === 'credentials') {
+                // LOGIN edge: replayStep resolved `ref` to the "Login" button. Fill
+                // Username + Password first, then click.
+                const userRef = await fieldRef('Username');
+                const passRef = await fieldRef('Password');
+                await adapter.fill(userRef, inputs.username);
+                await adapter.fill(passRef, inputs.password);
+                await adapter.click(ref);
+                return;
+            }
+            if (inputSlot === 'shipping') {
+                // SHIPPING edge (checkout-step-one): fill the three address fields, then
+                // click `ref` (the resolved "Continue" button).
+                const firstRef = await fieldRef('First Name');
+                const lastRef = await fieldRef('Last Name');
+                const zipRef = await fieldRef('Zip/Postal Code');
+                await adapter.fill(firstRef, inputs.firstName);
+                await adapter.fill(lastRef, inputs.lastName);
+                await adapter.fill(zipRef, inputs.zip);
+                await adapter.click(ref);
+                return;
+            }
+            // Plain-click edge (e.g. cart -> checkout-info "Checkout"): click the resolved ref.
+            await adapter.click(ref);
+        },
+    };
+    // 4. Walk login -> checkout-overview through the ONE async loop. Note: `inputs`
+    //    is captured by the browser closure above, NOT passed into walkRoute (it was
+    //    removed from WalkArgs — the walk only forwards the acceptsInput slot name).
+    const result = await walkRoute({
+        goalName: 'complete-checkout-dryrun',
+        startStateId: 'www.saucedemo.com:login',
+        goalStateId: 'www.saucedemo.com:checkout-overview',
+        store,
+        states: store.statesForNode('www.saucedemo.com'),
+        browser,
+    });
+    // 5. Always close the browser session, then return the walk result.
+    await adapter.close();
+    return result;
+}
+/**
+ * Seed the saucedemo interior WITH the post-commit `checkout-complete` state, so a
+ * walk can go all the way through the Finish commit to the "Thank you" page. The
+ * Finish affordance is commit:true → the walk still HALTS there (needs-classification)
+ * unless the agent classifies it safe (which runWalkLiveComplete does, because
+ * saucedemo is a demo with no real payment).
+ */
+export function seedSaucedemoComplete(store) {
+    const N = 'www.saucedemo.com';
+    seedSaucedemoForWalk(store); // login..checkout-overview + menu
+    store.transaction(() => {
+        // Re-point Finish at a REAL checkout-complete state and add that state.
+        store.upsertState(makeState({ id: `${N}:checkout-overview`, nodeId: N, semanticName: `${N}:checkout-overview`,
+            urlPattern: '*checkout-step-two*', role: 'detail', fingerprint: ['button:Finish'],
+            affordances: [
+                makeAffordance({ id: 'aff_finish', label: 'click "Finish"', kind: 'navigate',
+                    toState: `${N}:checkout-complete`, commit: true, core: true }),
+            ] }));
+        store.upsertState(makeState({ id: `${N}:checkout-complete`, nodeId: N, semanticName: `${N}:checkout-complete`,
+            urlPattern: '*checkout-complete*', role: 'detail', fingerprint: ['heading:Thank you for your order!', 'button:Back Home'],
+            affordances: [
+                makeAffordance({ id: 'aff_back_home', label: 'Back Home', kind: 'navigate', toState: `${N}:inventory` }),
+            ] }));
+    });
+}
+/**
+ * Live wiring for the FULL order completion (increment R5): walk login → … →
+ * checkout-overview → (Finish commit, classified SAFE because saucedemo is a demo)
+ * → checkout-complete. Proves the resume loop fires a commit point end-to-end on a
+ * real site after an explicit agent "safe" verdict — the only path that fires a commit.
+ */
+export async function runWalkLiveComplete(inputs, dbPath) {
+    const N = 'www.saucedemo.com';
+    const store = new MapStore(dbPath);
+    if (!store.getState(`${N}:checkout-complete`))
+        seedSaucedemoComplete(store);
+    const adapter = new PlaywrightAdapter('sdc' + (Date.now() % 100000));
+    await adapter.open('https://www.saucedemo.com/');
+    const browser = makeLiveWalkBrowser(adapter, inputs);
+    const states = store.statesForNode(N);
+    const args = {
+        goalName: 'complete-checkout', startStateId: `${N}:login`, goalStateId: `${N}:checkout-complete`,
+        store, states, browser,
+    };
+    try {
+        // Leg 1: walk to the goal. It will HALT at the Finish commit (needs-classification).
+        let result = await walkRoute(args);
+        // Leg 2: agent decides the demo Finish is SAFE → resume; the walk fires it and
+        // continues to checkout-complete. (R5 resume loop.)
+        if (result.status === 'needs-classification') {
+            result = await walkRoute({
+                ...args,
+                startStateId: `${N}:checkout-overview`, // resume from where it halted
+                answer: { kind: 'classify', verdict: 'safe' },
+            });
+        }
+        return result;
+    }
+    finally {
+        await adapter.close().catch(() => { });
+    }
+}

package/dist/router/walk-session.d.ts

@@ -0,0 +1,49 @@
+import Database from 'better-sqlite3';
+export interface WalkSession {
+    sessionId: string;
+    startState: string;
+    goalState: string;
+    path: string[];
+    pos: number;
+    browserSession: string;
+    status: string;
+    profile?: string;
+    observe: string[];
+    observeDynamic: boolean;
+    observed: string[];
+    pauseKind?: string;
+}
+/** Persists a PAUSED walk's position + the playwright session NAME (the browser
+ *  itself survives across CLI processes, so we don't serialize browser state).
+ *  No inputs are ever stored — credentials/form values are runtime-only. */
+export declare class WalkSessionStore {
+    private db;
+    constructor(path?: string);
+    static fromDatabase(db: Database.Database): WalkSessionStore;
+    private migrate;
+    create(args: {
+        startState: string;
+        goalState: string;
+        path: string[];
+        browserSession: string;
+        profile?: string;
+        nowMs?: number;
+        observe?: string[];
+        observeDynamic?: boolean;
+    }): string;
+    load(sessionId: string): WalkSession | null;
+    advance(sessionId: string, pos: number): void;
+    /** Persist checkpoint fire-once state + the pause kind this call returned, so a
+     *  subsequent walk-resume (a) doesn't re-fire an already-observed checkpoint and
+     *  (b) can reject `--continue` unless it's actually answering a checkpoint pause. */
+    setPause(sessionId: string, observed: string[], pauseKind: string): void;
+    /** Repoint a paused session at a DIFFERENT live browser — a wall retry (design
+     *  item 2) may rotate to a brand-new session mid-walk; the session_id the agent
+     *  already has (and resumes against) stays stable, only the browser it reattaches
+     *  to changes. */
+    rebrowser(sessionId: string, browserSession: string): void;
+    close(sessionId: string): void;
+    /** browser_session ids of paused walks older than `maxAgeMs` (abandoned pauses whose live
+     *  browser nothing else reaps — the ceiling pre-check closes these). */
+    staleBrowserSessions(maxAgeMs: number, nowMs?: number): string[];
+}

package/dist/router/walk-session.js

@@ -0,0 +1,90 @@
+import Database from 'better-sqlite3';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { dbPath } from '../paths.js';
+const SCHEMA = readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'mapstore', 'schema.sql'), 'utf8');
+/** Persists a PAUSED walk's position + the playwright session NAME (the browser
+ *  itself survives across CLI processes, so we don't serialize browser state).
+ *  No inputs are ever stored — credentials/form values are runtime-only. */
+export class WalkSessionStore {
+    db;
+    constructor(path = dbPath()) {
+        this.db = new Database(path);
+        this.db.exec(SCHEMA);
+        this.migrate();
+    }
+    static fromDatabase(db) {
+        const s = Object.create(WalkSessionStore.prototype);
+        s.db = db;
+        db.exec(SCHEMA);
+        s.migrate();
+        return s;
+    }
+    // profile = the named browser profile this walk is running under. Persisted so
+    // walk-resume can rebuild the SAME BrowserOpts the original `walk` used (needed
+    // for the fresh-session SSO-wall retry, which requires knowing the profile to
+    // reopen under). Additive column, same pattern as record_sessions.profile.
+    migrate() {
+        const cols = new Set(this.db.prepare('PRAGMA table_info(walk_sessions)').all().map((c) => c.name));
+        if (!cols.has('profile'))
+            this.db.exec('ALTER TABLE walk_sessions ADD COLUMN profile TEXT');
+        if (!cols.has('observe'))
+            this.db.exec('ALTER TABLE walk_sessions ADD COLUMN observe TEXT');
+        if (!cols.has('observe_dynamic'))
+            this.db.exec('ALTER TABLE walk_sessions ADD COLUMN observe_dynamic INTEGER');
+        if (!cols.has('observed'))
+            this.db.exec('ALTER TABLE walk_sessions ADD COLUMN observed TEXT');
+        if (!cols.has('pause_kind'))
+            this.db.exec('ALTER TABLE walk_sessions ADD COLUMN pause_kind TEXT');
+    }
+    create(args) {
+        const id = `walk-${args.browserSession}`;
+        this.db.prepare(`INSERT INTO walk_sessions (session_id,start_state,goal_state,path,pos,browser_session,status,created_at,profile,observe,observe_dynamic,observed,pause_kind)
+       VALUES (?,?,?,?,0,?,'paused',?,?,?,?,?,?)
+       ON CONFLICT(session_id) DO UPDATE SET start_state=excluded.start_state, goal_state=excluded.goal_state,
+         path=excluded.path, pos=0, browser_session=excluded.browser_session, status='paused', created_at=excluded.created_at,
+         profile=excluded.profile, observe=excluded.observe, observe_dynamic=excluded.observe_dynamic,
+         observed=excluded.observed, pause_kind=excluded.pause_kind`)
+            .run(id, args.startState, args.goalState, JSON.stringify(args.path), args.browserSession, args.nowMs ?? Date.now(), args.profile ?? null, JSON.stringify(args.observe ?? []), args.observeDynamic ? 1 : 0, JSON.stringify([]), null);
+        return id;
+    }
+    load(sessionId) {
+        const r = this.db.prepare("SELECT * FROM walk_sessions WHERE session_id=? AND status='paused'").get(sessionId);
+        if (!r)
+            return null;
+        return { sessionId: r.session_id, startState: r.start_state, goalState: r.goal_state,
+            path: JSON.parse(r.path), pos: r.pos, browserSession: r.browser_session, status: r.status,
+            profile: r.profile ?? undefined,
+            observe: r.observe ? JSON.parse(r.observe) : [],
+            observeDynamic: !!r.observe_dynamic,
+            observed: r.observed ? JSON.parse(r.observed) : [],
+            pauseKind: r.pause_kind ?? undefined };
+    }
+    advance(sessionId, pos) {
+        this.db.prepare('UPDATE walk_sessions SET pos=? WHERE session_id=?').run(pos, sessionId);
+    }
+    /** Persist checkpoint fire-once state + the pause kind this call returned, so a
+     *  subsequent walk-resume (a) doesn't re-fire an already-observed checkpoint and
+     *  (b) can reject `--continue` unless it's actually answering a checkpoint pause. */
+    setPause(sessionId, observed, pauseKind) {
+        this.db.prepare('UPDATE walk_sessions SET observed=?, pause_kind=? WHERE session_id=?')
+            .run(JSON.stringify(observed), pauseKind, sessionId);
+    }
+    /** Repoint a paused session at a DIFFERENT live browser — a wall retry (design
+     *  item 2) may rotate to a brand-new session mid-walk; the session_id the agent
+     *  already has (and resumes against) stays stable, only the browser it reattaches
+     *  to changes. */
+    rebrowser(sessionId, browserSession) {
+        this.db.prepare('UPDATE walk_sessions SET browser_session=? WHERE session_id=?').run(browserSession, sessionId);
+    }
+    close(sessionId) {
+        this.db.prepare("UPDATE walk_sessions SET status='done' WHERE session_id=?").run(sessionId);
+    }
+    /** browser_session ids of paused walks older than `maxAgeMs` (abandoned pauses whose live
+     *  browser nothing else reaps — the ceiling pre-check closes these). */
+    staleBrowserSessions(maxAgeMs, nowMs = Date.now()) {
+        const rows = this.db.prepare("SELECT browser_session, created_at FROM walk_sessions WHERE status='paused'").all();
+        return rows.filter((r) => nowMs - r.created_at >= maxAgeMs).map((r) => r.browser_session);
+    }
+}

package/dist/router/walk.d.ts

@@ -0,0 +1,48 @@
+import type { State } from '../mapstore/types.js';
+import type { MapStore } from '../mapstore/store.js';
+import type { RecallResponse } from '../protocol.js';
+export interface WalkBrowser {
+    snapshot(): Promise<string>;
+    act(ref: string, inputSlot: string | null): Promise<void>;
+    typeText?(ref: string, text: string): Promise<void>;
+    goto?(url: string, inputSlot: string | null): Promise<void>;
+    waitMs?(ms: number): Promise<void>;
+    scroll?(dy: number): Promise<void>;
+    callCount(): number;
+    currentUrl?(): Promise<string>;
+    reopenFresh?(url: string): Promise<string>;
+    close?(): Promise<void>;
+    sessionId?(): string;
+}
+export type WalkAnswer = {
+    kind: 'ref';
+    ref: string;
+} | {
+    kind: 'classify';
+    verdict: 'safe' | 'commit';
+} | {
+    kind: 'continue';
+};
+export interface WalkArgs {
+    goalName: string;
+    startStateId: string;
+    goalStateId: string;
+    store: MapStore;
+    states: State[];
+    browser: WalkBrowser;
+    path?: string[];
+    answer?: WalkAnswer;
+    profile?: string;
+    observe?: string[];
+    observeDynamic?: boolean;
+    observed?: string[];
+}
+/**
+ * The interactive multi-step walk (design §3). Walks a linear route edge-by-edge
+ * from `startStateId` toward `goalStateId`, verifying every step (prediction vs
+ * observation) and escalating to the agent on drift or at a commit point.
+ *
+ * Zero LLM: replayStep resolves deterministically (cached ref, then role+name);
+ * any decision webnav isn't allowed to make is handed back as a `needs-*` response.
+ */
+export declare function walkRoute(args: WalkArgs): Promise<RecallResponse>;