@dikshanty94/webnav 0.2.0

package/dist/router/search.js

@@ -0,0 +1,62 @@
+import { parseSnapshot } from '../playwright/snapshot.js';
+// Host SUFFIXES that are search chrome / mirrors / license boilerplate, not real
+// results. Suffix-matched so the whole Marginalia family (search.marginalia.nu,
+// about.marginalia-search.com), archive mirrors, the engine's footer license
+// link (creativecommons.org), and Wiby's own nav/footer (wiby.me) are all
+// excluded — same shape across all providers we fan out across.
+const EXCLUDED_HOST_SUFFIXES = [
+    'marginalia.nu', 'marginalia-search.com', 'web.archive.org', 'archive.org', 'creativecommons.org', 'wiby.me',
+];
+function isExcludedHost(host) {
+    const h = host.toLowerCase();
+    return EXCLUDED_HOST_SUFFIXES.some((s) => h === s || h.endsWith('.' + s) || h.includes(s));
+}
+// The engine's own footer/header links can point off-site (e.g. its source repo
+// at github.com/MarginaliaSearch). Exclude such chrome URLs by substring.
+const EXCLUDED_URL_SUBSTRINGS = ['github.com/MarginaliaSearch', '/MarginaliaSearch/'];
+/**
+ * A real search RESULT has a descriptive multi-word TITLE; search-engine chrome
+ * links are short nav labels ("About", "git repository", "CC-BY-SA 4.0"). Require
+ * >=3 whitespace-separated words to separate the dozens of real result titles
+ * from the handful of chrome links that otherwise pass host filtering.
+ * (Live-found bug: those 3 chrome links were leaking in as "results".)
+ */
+function looksLikeResultTitle(name) {
+    return name.trim().split(/\s+/).length >= 3;
+}
+/** Parse external result links from a Marginalia results snapshot. Pure. */
+export function parseSearchResults(resultsYaml, limit) {
+    const nodes = parseSnapshot(resultsYaml);
+    const results = [];
+    const seen = new Set();
+    for (const n of nodes) {
+        if (n.role !== 'link')
+            continue;
+        const url = n.url;
+        if (!url || !url.startsWith('http'))
+            continue;
+        const name = n.name?.trim();
+        if (!name)
+            continue;
+        if (name === url)
+            continue; // bare-url duplicate link
+        if (!looksLikeResultTitle(name))
+            continue; // chrome nav label, not a result title
+        if (EXCLUDED_URL_SUBSTRINGS.some((s) => url.includes(s)))
+            continue;
+        let host;
+        try {
+            host = new URL(url).host;
+        }
+        catch {
+            continue;
+        }
+        if (isExcludedHost(host))
+            continue;
+        if (seen.has(url))
+            continue;
+        seen.add(url);
+        results.push({ title: name, url });
+    }
+    return results.slice(0, limit);
+}

package/dist/router/suite.d.ts

@@ -0,0 +1,69 @@
+import type { MapStore } from '../mapstore/store.js';
+import type { State } from '../mapstore/types.js';
+import type { WalkBrowser } from './walk.js';
+export interface CheckpointAssert {
+    repertoireContains?: string[];
+    kinds?: Record<string, string>;
+    snapshotContains?: string[];
+}
+export interface CaseExpect {
+    status?: string;
+    maxInteractions?: number;
+    checkpoint?: Record<string, CheckpointAssert>;
+}
+export interface SuiteCase {
+    name: string;
+    start: string;
+    goal: string;
+    observe?: string[];
+    expect?: CaseExpect;
+}
+export interface Suite {
+    site: string;
+    profile?: string;
+    cases: SuiteCase[];
+}
+export interface CaseResult {
+    name: string;
+    verdict: 'pass' | 'fail';
+    elapsedMs: number;
+    failure?: {
+        at: string;
+        payload: unknown;
+    };
+}
+export interface SuiteResult {
+    status: 'ok' | 'failed';
+    passed: number;
+    failed: number;
+    cases: CaseResult[];
+    preflight?: {
+        auth: string;
+        loginUrl?: string;
+    };
+}
+/** A bad-suite error the CLI maps to exit 2 (config error, with a hint). */
+export declare class SuiteConfigError extends Error {
+}
+/** Validate + normalize a parsed suite JSON. Throws SuiteConfigError with a hint on
+ *  anything malformed — the CLI turns that into exit 2. */
+export declare function parseSuite(raw: unknown): Suite;
+/** Everything the runner needs to execute ONE case without knowing about live
+ *  browsers — the CLI wires the live version, tests wire a fake. `openCase` yields
+ *  a fresh WalkBrowser (the walk drives it) and a `close` to reap it after. */
+export interface SuiteDeps {
+    store: MapStore;
+    states: State[];
+    preflight?: () => Promise<{
+        auth: string;
+        loginUrl?: string;
+    }>;
+    openCase: (startUrl: string) => Promise<{
+        browser: WalkBrowser;
+        close: () => Promise<void>;
+    }>;
+    onProgress?: (line: string) => void;
+}
+/** Run a whole suite: auth pre-flight ONCE, then every case serially with a fresh
+ *  session each. Fails fast on a needs-login pre-flight. */
+export declare function runSuite(suite: Suite, deps: SuiteDeps): Promise<SuiteResult>;

package/dist/router/suite.js

@@ -0,0 +1,226 @@
+import { walkRoute } from './walk.js';
+import { findPath } from './path.js';
+/** A bad-suite error the CLI maps to exit 2 (config error, with a hint). */
+export class SuiteConfigError extends Error {
+}
+/** Validate + normalize a parsed suite JSON. Throws SuiteConfigError with a hint on
+ *  anything malformed — the CLI turns that into exit 2. */
+export function parseSuite(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        throw new SuiteConfigError('suite must be a JSON object');
+    const o = raw;
+    if (typeof o.site !== 'string' || !o.site)
+        throw new SuiteConfigError('suite.site (the host) is required');
+    if (!Array.isArray(o.cases) || o.cases.length === 0)
+        throw new SuiteConfigError('suite.cases must be a non-empty array');
+    const cases = o.cases.map((c, i) => {
+        if (typeof c !== 'object' || c === null)
+            throw new SuiteConfigError(`cases[${i}] must be an object`);
+        const cc = c;
+        if (typeof cc.name !== 'string' || !cc.name)
+            throw new SuiteConfigError(`cases[${i}].name is required`);
+        if (typeof cc.start !== 'string' || !cc.start)
+            throw new SuiteConfigError(`cases[${i}] (${cc.name ?? i}).start is required`);
+        if (typeof cc.goal !== 'string' || !cc.goal)
+            throw new SuiteConfigError(`cases[${i}] (${cc.name ?? i}).goal is required`);
+        const expect = (cc.expect ?? {});
+        if (expect.maxInteractions !== undefined && (typeof expect.maxInteractions !== 'number' || expect.maxInteractions < 0))
+            throw new SuiteConfigError(`cases[${i}] (${cc.name}).expect.maxInteractions must be a non-negative number`);
+        return { name: cc.name, start: cc.start, goal: cc.goal,
+            observe: Array.isArray(cc.observe) ? cc.observe : undefined, expect };
+    });
+    return { site: o.site, profile: typeof o.profile === 'string' ? o.profile : undefined, cases };
+}
+// Resolve a label (state id OR bare semanticName) to a concrete state id in the
+// site's states. Mirrors the CLI's --start/--goal/--observe resolution so a suite
+// author can write a bare state name (e.g. "report-list") instead of the fully
+// qualified id ("<site>:report-list").
+function resolveState(states, label) {
+    if (states.some((s) => s.id === label))
+        return label;
+    const byName = states.find((s) => s.semanticName === label || s.semanticName === label.split(':').pop());
+    if (byName)
+        return byName.id;
+    // suite authors use the bare tail (e.g. "report-list") — match the id suffix.
+    const bySuffix = states.find((s) => s.id.endsWith(':' + label));
+    return bySuffix ? bySuffix.id : null;
+}
+// Flatten a repertoire (affordances + nested reveal children) to label->kind, so a
+// checkpoint can assert against the FULL stored repertoire the state declares.
+function flatRepertoire(affs) {
+    const m = new Map();
+    const walk = (list) => {
+        for (const a of list) {
+            if (!m.has(a.label))
+                m.set(a.label, a.kind);
+            if (a.children)
+                walk(a.children);
+        }
+    };
+    walk(affs);
+    return m;
+}
+/** Assert one checkpoint payload against its CheckpointAssert. Returns a failure
+ *  reason string, or null if all assertions hold. */
+function assertCheckpoint(cp, a) {
+    const rep = flatRepertoire(cp.repertoire ?? []);
+    for (const label of a.repertoireContains ?? []) {
+        if (!rep.has(label))
+            return `repertoire missing "${label}" (have: ${[...rep.keys()].join(', ')})`;
+    }
+    for (const [label, kind] of Object.entries(a.kinds ?? {})) {
+        if (rep.get(label) !== kind)
+            return `"${label}" expected kind ${kind}, got ${rep.get(label) ?? 'ABSENT'}`;
+    }
+    for (const sub of a.snapshotContains ?? []) {
+        if (!cp.snapshot.includes(sub))
+            return `snapshot does not contain "${sub}"`;
+    }
+    return null;
+}
+// A checkpoint id in the suite may be written as a bare label; match it to the fired
+// checkpoint state either by exact id or by the id's tail.
+function checkpointAssertFor(expectCp, stateId) {
+    if (!expectCp)
+        return undefined;
+    if (expectCp[stateId])
+        return expectCp[stateId];
+    for (const [k, v] of Object.entries(expectCp))
+        if (stateId.endsWith(':' + k) || stateId === k)
+            return v;
+    return undefined;
+}
+/**
+ * Run one case: pathfind, walk on autopilot, auto-assert + --continue past every
+ * checkpoint, and charge every needs-* escalation against maxInteractions. Fails
+ * the case (with the pause payload) when the budget is exceeded, when a commit
+ * point is hit (needs-classification — never classified safe here), on drift, or
+ * when a checkpoint assertion or the terminal status doesn't match expect.
+ */
+async function runCase(c, deps) {
+    const t0 = Date.now();
+    const done = (verdict, failure) => ({ name: c.name, verdict, elapsedMs: Date.now() - t0, failure });
+    const startId = resolveState(deps.states, c.start);
+    const goalId = resolveState(deps.states, c.goal);
+    if (!startId)
+        return done('fail', { at: 'resolve', payload: `unknown start state "${c.start}"` });
+    if (!goalId)
+        return done('fail', { at: 'resolve', payload: `unknown goal state "${c.goal}"` });
+    const observe = [];
+    for (const label of c.observe ?? []) {
+        const id = resolveState(deps.states, label);
+        if (!id)
+            return done('fail', { at: 'resolve', payload: `unknown observe state "${label}"` });
+        observe.push(id);
+    }
+    const path = findPath(deps.store, startId, goalId);
+    if (!path)
+        return done('fail', { at: 'route', payload: `no route from ${startId} to ${goalId}` });
+    const expect = c.expect ?? {};
+    const wantStatus = expect.status ?? 'done';
+    const maxInteractions = expect.maxInteractions ?? 0;
+    const startState = deps.store.getState(startId);
+    const { browser, close } = await deps.openCase(startState.urlPattern || 'about:blank');
+    const observedSoFar = [];
+    let interactions = 0;
+    try {
+        let answer;
+        let from = startId;
+        // The walk loop: run walkRoute; on a checkpoint, assert then --continue; on a
+        // needs-* escalation, charge the budget and either fail or (if there were more
+        // states before the halt) there is nothing to continue with — the runner never
+        // answers navigation/classification, so any such pause ends the case.
+        // Guard against a pathological non-advancing loop with a bounded iteration cap.
+        for (let iter = 0; iter <= path.length + observe.length + 2; iter++) {
+            const res = await walkRoute({
+                goalName: 'suite:' + goalId, startStateId: from, goalStateId: goalId,
+                store: deps.store, states: deps.states, browser, path, answer,
+                observe, observed: observedSoFar,
+            });
+            answer = undefined;
+            if (res.status === 'checkpoint') {
+                observedSoFar.push(res.state);
+                const a = checkpointAssertFor(expect.checkpoint, res.state);
+                if (a) {
+                    const fail = assertCheckpoint(res, a);
+                    if (fail)
+                        return done('fail', { at: res.state, payload: fail });
+                }
+                // auto-assert done → --continue from where it paused (relative `at` over path)
+                from = path[res.at] ?? from;
+                answer = { kind: 'continue' };
+                continue;
+            }
+            if (res.status === 'needs-navigation' || res.status === 'needs-classification') {
+                // A needs-* is the walk asking for judgment. The runner answers NONE (a
+                // release check has no judge — including the commit-point classification,
+                // which therefore ALWAYS fails a case). Charge it against the budget; a case
+                // that escalates beyond maxInteractions (default 0) is a regression signal or
+                // a bad case. Since the runner can't answer, the pause ends the case either
+                // way — but we report the budget in the failure so intent stays visible.
+                interactions++;
+                deps.onProgress?.(`  interaction ${interactions} (budget ${maxInteractions}): ${res.status}`);
+                return done('fail', { at: interactions > maxInteractions ? 'interaction-budget' : 'needs-answer',
+                    payload: { interactions, maxInteractions, pause: res } });
+            }
+            if (res.status === 'needs-auth') {
+                return done('fail', { at: 'needs-auth', payload: res });
+            }
+            // terminal: done or failed
+            if (res.status !== wantStatus) {
+                return done('fail', { at: 'terminal', payload: { expected: wantStatus, got: res } });
+            }
+            // A checkpoint on the GOAL state does NOT fire as a `checkpoint` pause — the
+            // walk halts at the goal and returns `done`, attaching the goal's live snapshot
+            // + repertoire to evidence (walkRoute's goal-state enrichment). So a start==goal
+            // observe case is asserted HERE, against the done evidence, using the same
+            // assertCheckpoint machinery (the repertoire is the stored one).
+            if (res.status === 'done') {
+                for (const obsId of observe) {
+                    if (observedSoFar.includes(obsId))
+                        continue;
+                    const a = checkpointAssertFor(expect.checkpoint, obsId);
+                    if (!a)
+                        continue;
+                    const goalRep = deps.store.getState(obsId)?.affordances ?? res.evidence.repertoire ?? [];
+                    const synthetic = { status: 'checkpoint', at: 0, state: obsId,
+                        snapshot: res.evidence.snapshot ?? '', repertoire: goalRep };
+                    const fail = assertCheckpoint(synthetic, a);
+                    if (fail)
+                        return done('fail', { at: obsId, payload: fail });
+                }
+            }
+            return done('pass');
+        }
+        return done('fail', { at: 'loop', payload: 'walk did not terminate within the step budget' });
+    }
+    finally {
+        await close().catch(() => { });
+    }
+}
+/** Run a whole suite: auth pre-flight ONCE, then every case serially with a fresh
+ *  session each. Fails fast on a needs-login pre-flight. */
+export async function runSuite(suite, deps) {
+    if (deps.preflight) {
+        deps.onProgress?.(`pre-flight: checking auth for ${suite.site}...`);
+        const pf = await deps.preflight();
+        if (pf.auth === 'needs-login') {
+            deps.onProgress?.(`pre-flight FAILED: not logged in — ${pf.loginUrl ?? suite.site}`);
+            return { status: 'failed', passed: 0, failed: suite.cases.length,
+                preflight: pf,
+                cases: suite.cases.map((c) => ({ name: c.name, verdict: 'fail', elapsedMs: 0,
+                    failure: { at: 'preflight', payload: `not logged in for ${suite.site} — log in by hand, then re-run (loginUrl: ${pf.loginUrl ?? 'n/a'})` } })) };
+        }
+        deps.onProgress?.(`pre-flight ok: auth=${pf.auth}`);
+    }
+    const cases = [];
+    for (const c of suite.cases) {
+        deps.onProgress?.(`case: ${c.name}`);
+        const r = await runCase(c, deps);
+        deps.onProgress?.(`  → ${r.verdict}${r.failure ? ' @ ' + r.failure.at : ''} (${r.elapsedMs}ms)`);
+        cases.push(r);
+    }
+    const passed = cases.filter((c) => c.verdict === 'pass').length;
+    const failed = cases.length - passed;
+    return { status: failed === 0 ? 'ok' : 'failed', passed, failed, cases };
+}

package/dist/router/tokens.d.ts

@@ -0,0 +1,13 @@
+export declare function estimateTokens(text: string): number;
+export interface TokenSavings {
+    /** Estimated tokens the agent would have ingested reading the raw snapshots itself. */
+    raw_snapshot_tokens: number;
+    /** Estimated tokens of the compact bundle the agent actually receives. */
+    bundle_tokens: number;
+    /** raw_snapshot_tokens - bundle_tokens (>= 0). The agent-token cost webnav absorbs. */
+    tokens_saved: number;
+    /** Rough chars-per-token divisor used for the estimate (for transparency). */
+    chars_per_token: number;
+}
+/** Compute the savings estimate from total raw snapshot chars vs. the bundle's serialized size. */
+export declare function tokenSavings(rawSnapshotChars: number, bundleSerialized: string): TokenSavings;

package/dist/router/tokens.js

@@ -0,0 +1,26 @@
+/**
+ * Token estimation for the cost thesis (criterion #2). The real saving webnav
+ * delivers is the calling AGENT's LLM tokens: without webnav, the agent would
+ * have to ingest every raw page snapshot into its own context and reason about
+ * navigation. webnav parses those snapshots deterministically (zero LLM) and
+ * returns a compact evidence bundle instead. The saving = tokens in the raw
+ * snapshots the agent DIDN'T read, minus the tokens in the bundle it DID receive.
+ *
+ * Estimate, not exact: ~4 characters per token is the standard rough heuristic
+ * for English/markup. We report it as an estimate, never as a precise count.
+ */
+const CHARS_PER_TOKEN = 4;
+export function estimateTokens(text) {
+    return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+/** Compute the savings estimate from total raw snapshot chars vs. the bundle's serialized size. */
+export function tokenSavings(rawSnapshotChars, bundleSerialized) {
+    const raw = Math.ceil(rawSnapshotChars / CHARS_PER_TOKEN);
+    const bundle = estimateTokens(bundleSerialized);
+    return {
+        raw_snapshot_tokens: raw,
+        bundle_tokens: bundle,
+        tokens_saved: Math.max(0, raw - bundle),
+        chars_per_token: CHARS_PER_TOKEN,
+    };
+}

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

@@ -0,0 +1,57 @@
+import { PlaywrightAdapter, type BrowserOpts } from '../playwright/adapter.js';
+import { MapStore } from '../mapstore/store.js';
+import { type WalkBrowser } from './walk.js';
+import type { RecallResponse } from '../protocol.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 declare function seedSaucedemoForWalk(store: MapStore): void;
+/**
+ * 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 declare function makeLiveWalkBrowser(adapter: PlaywrightAdapter, inputs: Record<string, string>, browserOpts?: BrowserOpts, initialSessionId?: string): WalkBrowser;
+/**
+ * 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 declare function runWalkLive(inputs: Record<string, string>, dbPath?: string): Promise<RecallResponse>;
+/**
+ * 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 declare function seedSaucedemoComplete(store: MapStore): void;
+/**
+ * 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 declare function runWalkLiveComplete(inputs: Record<string, string>, dbPath?: string): Promise<RecallResponse>;