@tangle-network/browser-agent-driver 0.33.3 → 0.34.0

package/dist/runner/micro-plan.js

@@ -0,0 +1,29 @@
+/**
+ * Micro-plan follow-up selection — given the primary action the LLM chose and
+ * the optional `nextActions` it proposed, pick the safe subset to chain in the
+ * same turn, bounded by the configured per-turn action cap.
+ */
+import { SAFE_MICRO_ACTIONS, DEFAULT_MICRO_PLAN_ACTIONS } from './constants.js';
+export function selectMicroPlanFollowUps(primaryAction, nextActions, microPlanConfig) {
+    if (microPlanConfig?.enabled !== true || !Array.isArray(nextActions) || nextActions.length === 0) {
+        return [];
+    }
+    // Never chain follow-up actions behind terminal/meta actions.
+    if (!SAFE_MICRO_ACTIONS.has(primaryAction.action)) {
+        return [];
+    }
+    const limit = Math.max(1, Math.min(4, microPlanConfig.maxActionsPerTurn ?? DEFAULT_MICRO_PLAN_ACTIONS));
+    const remainingSlots = Math.max(0, limit - 1);
+    if (remainingSlots === 0)
+        return [];
+    const selected = [];
+    for (const action of nextActions) {
+        if (!SAFE_MICRO_ACTIONS.has(action.action))
+            continue;
+        selected.push(action);
+        if (selected.length >= remainingSlots)
+            break;
+    }
+    return selected;
+}
+//# sourceMappingURL=micro-plan.js.map

package/dist/runner/micro-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"micro-plan.js","sourceRoot":"","sources":["../../src/runner/micro-plan.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AAEhF,MAAM,UAAU,wBAAwB,CACtC,aAAqB,EACrB,WAAiC,EACjC,eAA8E;IAE9E,IAAI,eAAe,EAAE,OAAO,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjG,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,8DAA8D;IAC9D,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CACpB,CAAC,EACD,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,eAAe,CAAC,iBAAiB,IAAI,0BAA0B,CAAC,CAC7E,CAAC;IACF,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IAC9C,IAAI,cAAc,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,MAAM,IAAI,WAAW,EAAE,CAAC;QACjC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC;YAAE,SAAS;QACrD,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACtB,IAAI,QAAQ,CAAC,MAAM,IAAI,cAAc;YAAE,MAAM;IAC/C,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/runner/prompt-snippets.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Static prompt snippets the main loop injects into the brain context.
+ */
+export declare const DEFI_BRAIN_CONTEXT: string;
+//# sourceMappingURL=prompt-snippets.d.ts.map

package/dist/runner/prompt-snippets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-snippets.d.ts","sourceRoot":"","sources":["../../src/runner/prompt-snippets.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,kBAAkB,QAS0F,CAAA"}

package/dist/runner/prompt-snippets.js

@@ -0,0 +1,13 @@
+/**
+ * Static prompt snippets the main loop injects into the brain context.
+ */
+export const DEFI_BRAIN_CONTEXT = '\nWALLET/DeFi MODE ACTIVE — crypto app patterns:\n' +
+    '- PERSISTENT WIDGETS: Many DeFi apps have always-on support/chat widgets (bottom-right) that show as alertdialog. These CANNOT be dismissed. Ignore them and interact with the page directly.\n' +
+    '- WALLET CONNECTION: Look for "Connect Wallet" button, select MetaMask. The wallet extension handles the approval popup automatically.\n' +
+    '- TOKEN SELECTION: If you need to change a token, click the token selector button (usually shows token symbol/icon), search for the token name, and select it from the dropdown.\n' +
+    '- TRANSACTION FLOW: Enter amount → wait for quote/estimate to load → click action button (Swap/Supply/etc.) → review dialog appears → stop before confirming in MetaMask.\n' +
+    '- LOADING STATES: DeFi apps make many RPC calls. Wait for balances and quotes to appear before clicking action buttons. If a button says "Enter amount" or is disabled, the app is still loading.\n' +
+    '- NATIVE ETH: Prefer native ETH over wrapped tokens (WETH) when possible — avoids ERC-20 spending approval steps.\n' +
+    '- NETWORK SELECTOR: Do NOT change the network/chain. If a network dropdown opens accidentally, close it immediately.\n' +
+    '- COOKIE BANNERS: Dismiss immediately via Escape or Reject button — don\'t spend multiple turns on consent dialogs.\n';
+//# sourceMappingURL=prompt-snippets.js.map

package/dist/runner/prompt-snippets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-snippets.js","sourceRoot":"","sources":["../../src/runner/prompt-snippets.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAC7B,oDAAoD;IACpD,iMAAiM;IACjM,0IAA0I;IAC1I,oLAAoL;IACpL,6KAA6K;IAC7K,qMAAqM;IACrM,qHAAqH;IACrH,wHAAwH;IACxH,uHAAuH,CAAA"}

package/dist/runner/replay/contracts.d.ts

@@ -0,0 +1,300 @@
+/**
+ * Workflow Replay — contracts.
+ *
+ * Replay re-executes a previously-recorded successful {@link Trajectory} against
+ * the live browser with ZERO per-action LLM calls. A normal run is ~97-98%
+ * LLM-latency-bound (~10-13s per `brain.decide` round-trip); replaying a known
+ * task collapses a ~40s / 3-call run into ~1-3s of pure browser I/O plus a
+ * single goal-verification LLM call at the end.
+ *
+ * Where it slots in: replay is a SIBLING pre-loop path to the planner-first
+ * path in `runner.ts`. The runner attempts replay first; on success it returns,
+ * and on a self-heal abort it falls through to the normal per-action loop FROM
+ * THE CURRENT PAGE STATE (same fall-through pattern the planner path already
+ * uses). Replay never blindly claims success — even a fully-replayed run ends
+ * with the existing `brain.verifyGoalCompletion` (one LLM call).
+ *
+ * Self-heal semantics (the safety net):
+ *   A wrong replay is cheap. Each step is gated twice — by a pure pre-execution
+ *   guard ({@link ReplayGuard}) and by post-execution effect verification — so a
+ *   trajectory that no longer fits the live page ABORTS after at most a few fast
+ *   browser actions and hands control to the agent. The final outcome is never
+ *   worse than running the agent from scratch; the only cost of a bad replay is
+ *   the handful of actions executed before the heal fired. Because of this, the
+ *   guard deliberately gates on ACTION-PERFORMABILITY, not on exact snapshot
+ *   identity: the page legitimately differs run-to-run (timestamps, session
+ *   chrome, ad slots, list ordering), so a hard `snapshotHash` equality gate
+ *   would heal on nearly every replay and defeat the purpose. `snapshotHash`
+ *   drift is at most a secondary heuristic; the real question the guard answers
+ *   is "can THIS action still be performed against the page in front of me?".
+ *
+ * This module is contracts only — no executor logic. The pure guard core
+ * ({@link ReplayGuard}) is kept separate from the IO executor
+ * ({@link ReplayController}) so the decision logic unit-tests without a browser.
+ */
+import type { Action } from '../../types/actions.js';
+import type { PageState } from '../../types/page.js';
+import type { Turn } from '../../types/turn.js';
+import type { GoalVerification } from '../../types/result.js';
+import type { Trajectory, TrajectoryStep } from '../../types/trajectory.js';
+import type { Driver } from '../../drivers/types.js';
+import type { EffectVerificationInput, EffectVerificationResult } from '../effect-verification.js';
+/**
+ * Strict goal-similarity bar for selecting a replay candidate. Far higher than
+ * the 0.5 hint-injection threshold used by {@link TrajectoryStore.findBestMatch}:
+ * an imperfect reference is fine to *show* the LLM as a hint, but replaying it
+ * verbatim against the live page demands a near-exact task match.
+ */
+export declare const DEFAULT_REPLAY_SIMILARITY_THRESHOLD = 0.85;
+/**
+ * A single replayable step. Reuses {@link TrajectoryStep} (url + action +
+ * snapshotHash + verified + the OPTIONAL persisted `expectedEffect`).
+ *
+ * `expectedEffect` now rides on {@link TrajectoryStep} and is persisted by
+ * `save()` from `Turn.expectedEffect` (older trajectories written before that
+ * change simply lack the field). When present, the controller asserts it
+ * against the live page via the injected {@link ReplayContext.verifyEffect}
+ * (the runner's own `verifyExpectedEffect`) — this is the real second gate
+ * behind the "gated twice" safety thesis. When ABSENT, the controller falls
+ * back to a generic "the action executed without error" check and records
+ * whether the page changed for diagnostics only; the guard pre-check plus the
+ * execute-success gate plus the final goal verification remain the safety net.
+ */
+export interface ReplayStep extends TrajectoryStep {
+    /** Effect to assert after executing this step (see effect-verification). */
+    expectedEffect?: string;
+}
+/**
+ * A matched replay candidate plus the metadata that justified selecting it.
+ * Produced from a strict {@link ReplayCandidateSource.findReplayCandidate} hit.
+ */
+export interface ReplayPlan {
+    /** The full source trajectory the steps came from. */
+    trajectory: Trajectory;
+    /** Concrete, executable browser steps (complete/abort already filtered at save time). */
+    steps: ReplayStep[];
+    /** Jaccard goal similarity between the live goal and the trajectory's goal (>= threshold). */
+    goalSimilarity: number;
+    /** Normalized origin the trajectory was scoped to, when known. */
+    origin?: string;
+}
+/**
+ * The minimal live observation the pure guard reads: current URL + snapshot
+ * text. Deliberately narrower than {@link PageState} (no screenshot/diff) so
+ * guard unit tests can pass plain literals with no browser.
+ */
+export type ReplayObservation = Pick<PageState, 'url' | 'snapshot'>;
+/**
+ * Result of the pure pre-execution guard for one step.
+ *
+ * Discriminated so an `abort` always carries a human-readable `reason` (the heal
+ * path must be explicit and logged) while `proceed` never needs one.
+ */
+export type StepGuardResult = {
+    decision: 'proceed';
+} | {
+    decision: 'abort';
+    reason: string;
+};
+/**
+ * Pure decision core: given a recorded step and the current observation, decide
+ * whether the step can still be replayed. NO IO — it never touches the driver.
+ *
+ * It gates on action-performability, not snapshot identity:
+ *   - the action's target must be addressable in the current snapshot (e.g. an
+ *     `@ref` selector's `[ref=...]` token is still present), and
+ *   - the URL/origin must be consistent with `step.url`.
+ * For selectors it cannot statically resolve against snapshot text (CSS, text=,
+ * role=), it returns `proceed` and defers to execution + effect verification —
+ * the guard is a cheap pre-filter, not the hard gate. See the module-level
+ * self-heal note for why exact `snapshotHash` equality is intentionally NOT a
+ * gate.
+ */
+export interface ReplayGuard {
+    check(step: ReplayStep, current: ReplayObservation): StepGuardResult;
+}
+/**
+ * Final goal verification (one LLM call). Matches `brain.verifyGoalCompletion`
+ * so the controller can depend on the capability without importing the brain.
+ */
+export type GoalVerifier = (state: PageState, goal: string, claimedResult: string) => Promise<GoalVerification>;
+/**
+ * Observable lifecycle of a replay attempt. Every heal/abort is surfaced so the
+ * decision is never silent. Wired to the runner's event bus in the executor.
+ */
+export type ReplayEvent = {
+    type: 'replay-started';
+    trajectoryId: string;
+    totalSteps: number;
+    goalSimilarity: number;
+} | {
+    type: 'replay-step';
+    index: number;
+    totalSteps: number;
+    action: Action['action'];
+} | {
+    type: 'replay-guard-abort';
+    index: number;
+    reason: string;
+} | {
+    type: 'replay-effect-failed';
+    index: number;
+    reason: string;
+} | {
+    type: 'replay-healed';
+    completedSteps: number;
+    totalSteps: number;
+    reason: string;
+} | {
+    type: 'replay-completed';
+    completedSteps: number;
+    achieved: boolean;
+};
+/**
+ * Everything the IO executor needs, injected so the controller stays decoupled
+ * from the concrete runner/brain wiring.
+ */
+export interface ReplayContext {
+    /** The live goal being pursued. */
+    goal: string;
+    /** Live browser driver (observe + execute). */
+    driver: Driver;
+    /** Pure step guard. */
+    guard: ReplayGuard;
+    /** Final goal-completion verifier (the single permitted LLM call). */
+    verifyGoal: GoalVerifier;
+    /**
+     * Per-step effect verifier — the runner injects its own pure
+     * `verifyExpectedEffect` (src/runner/effect-verification.ts). Typed against
+     * that module so the controller is FORCED to reuse the runner's verifier
+     * rather than hand-rolling a weaker per-step check, and so the second gate
+     * stays pure + unit-testable. Only consulted when a step carries a persisted
+     * `expectedEffect`. NO LLM call — this is deterministic string/state diffing.
+     */
+    verifyEffect: (input: EffectVerificationInput) => EffectVerificationResult;
+    /** Cooperative cancellation. */
+    signal?: AbortSignal;
+    /** Verbose logging passthrough. */
+    debug?: boolean;
+    /** Optional structured event sink (runner bridges this to its TurnEventBus). */
+    onEvent?: (event: ReplayEvent) => void;
+}
+/** Discriminant for {@link ReplayOutcome}. */
+export type ReplayOutcomeKind = 'completed' | 'healed' | 'no-candidate';
+/** Fields common to every replay outcome. */
+interface ReplayOutcomeBase {
+    /**
+     * Steps that replayed cleanly (guard proceed + execute + effect ok) before
+     * this outcome. EXCLUDES the step that aborted on `healed`. Diagnostic /
+     * event payload only — `turns.length` (below) is the authoritative count the
+     * runner uses to advance its loop index, mirroring the planner path's
+     * `cumulativeTurnsConsumed` semantics. `turns` may therefore contain one more
+     * entry than `completedSteps` when a step executed but its effect failed.
+     */
+    completedSteps: number;
+    /** Total steps in the plan (0 when there was no candidate). */
+    totalSteps: number;
+    /** LLM calls replay itself spent — 1 on `completed` (final verify), 0 otherwise. */
+    llmCallsUsed: number;
+    /**
+     * Replay steps recorded as turns, for merging into the unified run timeline.
+     * AUTHORITATIVE for resume accounting: because replay is the FIRST pre-loop
+     * path it appends to an empty `turns` array, numbering its turns 1..N, and
+     * the runner offsets the per-action loop start by `turns.length` so a
+     * fall-through never re-executes a recorded step.
+     */
+    turns: Turn[];
+}
+/**
+ * The result of a replay attempt.
+ *
+ * - `completed`: all steps replayed and the final goal verification ran. Carries
+ *   the `goalVerification`, the `finalResult` string, and `lastState`.
+ *   `achieved` may still be false — replay surfaces the verdict honestly rather
+ *   than fabricating success. REQUIRED runner behavior: only
+ *   `completed && goalVerification.achieved === true` is terminal (build the
+ *   success result and return). `completed && achieved === false` MUST fall
+ *   through to the per-action loop FROM `lastState`, exactly like `healed` —
+ *   never return a confident failure off the back of a replay, which would be
+ *   strictly worse than running the agent from scratch.
+ * - `healed`: a guard/execute/effect gate aborted mid-replay. Carries `reason`
+ *   and `lastState` so the runner continues its per-action loop from here.
+ * - `no-candidate`: no strict match was found (or replay was disabled); the
+ *   runner proceeds to its normal path untouched (no `lastState`, no turns).
+ */
+export type ReplayOutcome = (ReplayOutcomeBase & {
+    kind: 'completed';
+    lastState: PageState;
+    goalVerification: GoalVerification;
+    finalResult: string;
+}) | (ReplayOutcomeBase & {
+    kind: 'healed';
+    lastState: PageState;
+    reason: string;
+}) | (ReplayOutcomeBase & {
+    kind: 'no-candidate';
+    reason: string;
+});
+/**
+ * IO executor: drives the driver + guard through a {@link ReplayPlan}.
+ *
+ * For each step: observe → {@link ReplayGuard.check} (abort → heal) →
+ * `driver.execute` (error → heal) → verify expected effect (fail → heal). After
+ * all steps replay, run {@link ReplayContext.verifyGoal} once. Implementations
+ * MUST NOT make per-action LLM calls; the final goal verification is the only
+ * permitted model round-trip.
+ */
+export interface ReplayController {
+    replay(plan: ReplayPlan, ctx: ReplayContext): Promise<ReplayOutcome>;
+}
+/** Options for the strict replay-candidate lookup. */
+export interface ReplayMatchOptions {
+    /**
+     * Origin to scope the lookup to. When supplied, only trajectories whose
+     * normalized origin matches exactly are eligible. The replay WIRING always
+     * supplies it from the live run's start URL (`scenario.startUrl`), and the
+     * runner only enters the replay path when an origin resolves — verbatim
+     * browser actions must never be selected cross-origin on lexical goal overlap
+     * alone. Left optional on the type so the store method stays general, but a
+     * production replay call without an origin is a wiring bug.
+     */
+    origin?: string;
+    /** Minimum goal similarity to qualify. Defaults to {@link DEFAULT_REPLAY_SIMILARITY_THRESHOLD}. */
+    minSimilarity?: number;
+}
+/**
+ * A strict replay-candidate hit: the matched trajectory plus the score and
+ * origin that justified it. Returned (rather than a bare {@link Trajectory}) so
+ * the plan-builder can populate {@link ReplayPlan.goalSimilarity} and the
+ * `replay-started` event WITHOUT re-implementing the store's private Jaccard —
+ * the score that passed the gate is the score the plan reports.
+ */
+export interface ReplayCandidate {
+    trajectory: Trajectory;
+    /** Raw Jaccard goal similarity that cleared the threshold. */
+    similarity: number;
+    /** Normalized origin the trajectory was scoped to, when known. */
+    origin?: string;
+}
+/**
+ * The strict-match lookup replay depends on. Separate from `findBestMatch`
+ * (which keeps its 0.5 hint-injection threshold): a replay candidate requires
+ * `success === true`, a non-empty step list, an exact origin match when an
+ * origin is supplied, and goal similarity >= the strict threshold.
+ * {@link TrajectoryStore} satisfies this interface.
+ */
+export interface ReplayCandidateSource {
+    findReplayCandidate(goal: string, options?: ReplayMatchOptions): ReplayCandidate | null;
+}
+/**
+ * Runtime config for replay. OPT-IN (`enabled` defaults to false / `--replay`)
+ * per the repo's experiment discipline until measured non-regressive.
+ */
+export interface ReplayConfig {
+    /** Master switch. Default behavior is byte-identical when false. */
+    enabled: boolean;
+    /** Override the strict similarity bar. Defaults to {@link DEFAULT_REPLAY_SIMILARITY_THRESHOLD}. */
+    minSimilarity?: number;
+}
+export {};
+//# sourceMappingURL=contracts.d.ts.map

package/dist/runner/replay/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../../src/runner/replay/contracts.ts"],"names":[],"mappings":"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"}

package/dist/runner/replay/contracts.js

@@ -0,0 +1,42 @@
+/**
+ * Workflow Replay — contracts.
+ *
+ * Replay re-executes a previously-recorded successful {@link Trajectory} against
+ * the live browser with ZERO per-action LLM calls. A normal run is ~97-98%
+ * LLM-latency-bound (~10-13s per `brain.decide` round-trip); replaying a known
+ * task collapses a ~40s / 3-call run into ~1-3s of pure browser I/O plus a
+ * single goal-verification LLM call at the end.
+ *
+ * Where it slots in: replay is a SIBLING pre-loop path to the planner-first
+ * path in `runner.ts`. The runner attempts replay first; on success it returns,
+ * and on a self-heal abort it falls through to the normal per-action loop FROM
+ * THE CURRENT PAGE STATE (same fall-through pattern the planner path already
+ * uses). Replay never blindly claims success — even a fully-replayed run ends
+ * with the existing `brain.verifyGoalCompletion` (one LLM call).
+ *
+ * Self-heal semantics (the safety net):
+ *   A wrong replay is cheap. Each step is gated twice — by a pure pre-execution
+ *   guard ({@link ReplayGuard}) and by post-execution effect verification — so a
+ *   trajectory that no longer fits the live page ABORTS after at most a few fast
+ *   browser actions and hands control to the agent. The final outcome is never
+ *   worse than running the agent from scratch; the only cost of a bad replay is
+ *   the handful of actions executed before the heal fired. Because of this, the
+ *   guard deliberately gates on ACTION-PERFORMABILITY, not on exact snapshot
+ *   identity: the page legitimately differs run-to-run (timestamps, session
+ *   chrome, ad slots, list ordering), so a hard `snapshotHash` equality gate
+ *   would heal on nearly every replay and defeat the purpose. `snapshotHash`
+ *   drift is at most a secondary heuristic; the real question the guard answers
+ *   is "can THIS action still be performed against the page in front of me?".
+ *
+ * This module is contracts only — no executor logic. The pure guard core
+ * ({@link ReplayGuard}) is kept separate from the IO executor
+ * ({@link ReplayController}) so the decision logic unit-tests without a browser.
+ */
+/**
+ * Strict goal-similarity bar for selecting a replay candidate. Far higher than
+ * the 0.5 hint-injection threshold used by {@link TrajectoryStore.findBestMatch}:
+ * an imperfect reference is fine to *show* the LLM as a hint, but replaying it
+ * verbatim against the live page demands a near-exact task match.
+ */
+export const DEFAULT_REPLAY_SIMILARITY_THRESHOLD = 0.85;
+//# sourceMappingURL=contracts.js.map

package/dist/runner/replay/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../../src/runner/replay/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAUH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,IAAI,CAAC"}

package/dist/runner/replay/controller.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Workflow Replay — the IO executor.
+ *
+ * Drives the live driver + the pure {@link ReplayGuard} through a
+ * {@link ReplayPlan} with ZERO per-action LLM calls. Per step:
+ *   observe → guard.check (abort → heal) → driver.execute (error → heal) →
+ *   verify expected effect when present (fail → heal).
+ * After every step replays cleanly, a single {@link ReplayContext.verifyGoal}
+ * call (the only permitted model round-trip) decides whether the goal was
+ * actually achieved — replay never blindly claims success.
+ *
+ * The first guard/execute/effect failure ABORTS into a `healed` outcome carrying
+ * the live page state, so the runner resumes its per-action loop from exactly
+ * where replay stopped. A wrong replay therefore costs at most a handful of fast
+ * browser actions before control returns to the agent.
+ */
+import type { ReplayContext, ReplayController, ReplayOutcome, ReplayPlan } from './contracts.js';
+/** Default {@link ReplayController}: self-healing, zero per-action LLM calls. */
+export declare class SelfHealingReplayController implements ReplayController {
+    replay(plan: ReplayPlan, ctx: ReplayContext): Promise<ReplayOutcome>;
+    private heal;
+    private safeObserve;
+    private minimalState;
+}
+/** Factory mirroring the rest of the replay module's construction style. */
+export declare function createReplayController(): ReplayController;
+//# sourceMappingURL=controller.d.ts.map

package/dist/runner/replay/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../../src/runner/replay/controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,UAAU,EAEX,MAAM,gBAAgB,CAAC;AA2CxB,iFAAiF;AACjF,qBAAa,2BAA4B,YAAW,gBAAgB;IAC5D,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAoI1E,OAAO,CAAC,IAAI;YAuBE,WAAW;IAQzB,OAAO,CAAC,YAAY;CAGrB;AAED,4EAA4E;AAC5E,wBAAgB,sBAAsB,IAAI,gBAAgB,CAEzD"}

package/dist/runner/replay/controller.js

@@ -0,0 +1,197 @@
+/**
+ * Workflow Replay — the IO executor.
+ *
+ * Drives the live driver + the pure {@link ReplayGuard} through a
+ * {@link ReplayPlan} with ZERO per-action LLM calls. Per step:
+ *   observe → guard.check (abort → heal) → driver.execute (error → heal) →
+ *   verify expected effect when present (fail → heal).
+ * After every step replays cleanly, a single {@link ReplayContext.verifyGoal}
+ * call (the only permitted model round-trip) decides whether the goal was
+ * actually achieved — replay never blindly claims success.
+ *
+ * The first guard/execute/effect failure ABORTS into a `healed` outcome carrying
+ * the live page state, so the runner resumes its per-action loop from exactly
+ * where replay stopped. A wrong replay therefore costs at most a handful of fast
+ * browser actions before control returns to the agent.
+ */
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function hasStateChanged(pre, post) {
+    return pre.url !== post.url || pre.title !== post.title || pre.snapshot !== post.snapshot;
+}
+function buildTurn(turnNumber, state, step, extra) {
+    return {
+        turn: turnNumber,
+        state,
+        action: step.action,
+        reasoning: 'workflow-replay (zero-LLM)',
+        durationMs: extra.durationMs,
+        ...(extra.expectedEffect !== undefined ? { expectedEffect: extra.expectedEffect } : {}),
+        ...(extra.verified !== undefined ? { verified: extra.verified } : {}),
+        ...(extra.verificationFailure !== undefined ? { verificationFailure: extra.verificationFailure } : {}),
+        ...(extra.error !== undefined ? { error: extra.error } : {}),
+    };
+}
+function buildClaim(plan, finalState, completedSteps) {
+    return (`Replayed ${completedSteps} recorded step(s) from a prior successful run of a ` +
+        `near-identical goal (similarity ${plan.goalSimilarity.toFixed(2)}). ` +
+        `Final page: ${finalState.url} — "${finalState.title}".`);
+}
+/** Default {@link ReplayController}: self-healing, zero per-action LLM calls. */
+export class SelfHealingReplayController {
+    async replay(plan, ctx) {
+        const totalSteps = plan.steps.length;
+        const turns = [];
+        ctx.onEvent?.({
+            type: 'replay-started',
+            trajectoryId: plan.trajectory.id,
+            totalSteps,
+            goalSimilarity: plan.goalSimilarity,
+        });
+        // Defensive: a plan with no steps can't be replayed. (The store filters
+        // empty trajectories out of findReplayCandidate, so this is a guard rail.)
+        if (totalSteps === 0) {
+            const lastState = (await this.safeObserve(ctx)) ?? this.minimalState(ctx);
+            return this.heal(ctx, turns, 0, totalSteps, lastState, 'replay plan had no steps');
+        }
+        let lastState;
+        for (let index = 0; index < totalSteps; index++) {
+            const step = plan.steps[index];
+            ctx.onEvent?.({ type: 'replay-step', index, totalSteps, action: step.action.action });
+            // -- observe current state (also the turn.state for this step) --
+            let preState;
+            try {
+                preState = await ctx.driver.observe();
+            }
+            catch (err) {
+                const recover = lastState ?? this.minimalState(ctx);
+                return this.heal(ctx, turns, index, totalSteps, recover, `observe failed before step ${index + 1}: ${errMsg(err)}`);
+            }
+            lastState = preState;
+            // Cooperative cancellation — surface as a heal so the runner's own
+            // abort check finalizes the run.
+            if (ctx.signal?.aborted) {
+                const reason = ctx.signal.reason ? String(ctx.signal.reason) : 'cancelled';
+                return this.heal(ctx, turns, index, totalSteps, preState, reason);
+            }
+            // -- pure guard: can this step still be performed? --
+            const guardResult = ctx.guard.check(step, { url: preState.url, snapshot: preState.snapshot });
+            if (guardResult.decision === 'abort') {
+                ctx.onEvent?.({ type: 'replay-guard-abort', index, reason: guardResult.reason });
+                return this.heal(ctx, turns, index, totalSteps, preState, guardResult.reason);
+            }
+            // -- execute --
+            const stepStartedAt = Date.now();
+            let execError;
+            try {
+                const result = await ctx.driver.execute(step.action);
+                if (!result.success)
+                    execError = result.error ?? 'action reported failure';
+            }
+            catch (err) {
+                execError = errMsg(err);
+            }
+            if (execError) {
+                // Record the attempted (errored) turn so the timeline shows what was
+                // tried, then heal. This is the one case where turns.length exceeds
+                // completedSteps (the contract documents this).
+                turns.push(buildTurn(turns.length + 1, preState, step, {
+                    verified: false,
+                    error: execError,
+                    durationMs: Date.now() - stepStartedAt,
+                    ...(step.expectedEffect !== undefined ? { expectedEffect: step.expectedEffect } : {}),
+                }));
+                return this.heal(ctx, turns, index, totalSteps, preState, `execute failed at step ${index + 1}: ${execError}`);
+            }
+            // -- observe post-state + verify the recorded effect when present --
+            let postState;
+            try {
+                postState = await ctx.driver.observe();
+            }
+            catch {
+                postState = preState;
+            }
+            lastState = postState;
+            let verified;
+            if (step.expectedEffect) {
+                const ev = ctx.verifyEffect({
+                    expectedEffect: step.expectedEffect,
+                    preActionState: preState,
+                    postActionState: postState,
+                });
+                verified = ev.verified;
+                if (!ev.verified) {
+                    const reason = ev.reason ?? 'expected effect not observed';
+                    turns.push(buildTurn(turns.length + 1, preState, step, {
+                        verified: false,
+                        expectedEffect: step.expectedEffect,
+                        verificationFailure: reason,
+                        durationMs: Date.now() - stepStartedAt,
+                    }));
+                    ctx.onEvent?.({ type: 'replay-effect-failed', index, reason });
+                    return this.heal(ctx, turns, index, totalSteps, postState, `effect verification failed at step ${index + 1}: ${reason}`);
+                }
+            }
+            else {
+                // No persisted effect — fall back to change-detection for the
+                // diagnostic `verified` flag only. Absence of change is NOT a heal
+                // signal: typing into a field or an idempotent click can leave the
+                // snapshot materially unchanged. The guard pre-check + execute-success
+                // + final goal verification remain the safety net here.
+                verified = hasStateChanged(preState, postState);
+            }
+            turns.push(buildTurn(turns.length + 1, preState, step, {
+                verified,
+                durationMs: Date.now() - stepStartedAt,
+                ...(step.expectedEffect !== undefined ? { expectedEffect: step.expectedEffect } : {}),
+            }));
+        }
+        // -- all steps replayed: the single permitted LLM round-trip --
+        const finalState = (await this.safeObserve(ctx)) ?? lastState ?? this.minimalState(ctx);
+        const finalResult = buildClaim(plan, finalState, totalSteps);
+        const goalVerification = await ctx.verifyGoal(finalState, ctx.goal, finalResult);
+        ctx.onEvent?.({ type: 'replay-completed', completedSteps: totalSteps, achieved: goalVerification.achieved });
+        return {
+            kind: 'completed',
+            completedSteps: totalSteps,
+            totalSteps,
+            llmCallsUsed: 1,
+            turns,
+            lastState: finalState,
+            goalVerification,
+            finalResult,
+        };
+    }
+    heal(ctx, turns, completedSteps, totalSteps, lastState, reason) {
+        ctx.onEvent?.({ type: 'replay-healed', completedSteps, totalSteps, reason });
+        if (ctx.debug) {
+            console.log(`[Replay] healed after ${completedSteps}/${totalSteps} steps: ${reason}`);
+        }
+        return {
+            kind: 'healed',
+            completedSteps,
+            totalSteps,
+            llmCallsUsed: 0,
+            turns,
+            lastState,
+            reason,
+        };
+    }
+    async safeObserve(ctx) {
+        try {
+            return await ctx.driver.observe();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    minimalState(ctx) {
+        return { url: ctx.driver.getUrl?.() ?? '', title: '', snapshot: '' };
+    }
+}
+/** Factory mirroring the rest of the replay module's construction style. */
+export function createReplayController() {
+    return new SelfHealingReplayController();
+}
+//# sourceMappingURL=controller.js.map