feat/adds-delta-snapshot-token-optimization

[meprynshu]

Delta Snapshot Optimization

Problem

On complex, data-dense pages (large tables, CRM dashboards, data grids), every tool call within an agentic step appends a full ariaSnapshot() of the
entire page to the conversation history. Token usage compounds across calls:

Tool call 1 → +80k tokens (full snapshot)
Tool call 2 → +80k tokens (full snapshot again)
Tool call 3 → +80k tokens (full snapshot again)
...
10 tool calls = ~1M tokens for one step

This causes token limit errors on complex multi-action steps and dramatically increases latency and cost.

Solution

Post-action snapshots now return only the lines that changed since the last snapshot, instead of the full page tree. The first snapshot of each step is
always full so the agent has complete context. Every subsequent snapshot within the same step is diffed against the most recently seen snapshot.

On by default. Disable globally with:

configure({ deltaSnapshot: false });

Token impact on a 10-action step over a leads table:

┌───────────┬────────────┐
│           │   Tokens   │
├───────────┼────────────┤
│ Before    │ ~1,000,000 │
├───────────┼────────────┤
│ After     │ ~82,000    │
├───────────┼────────────┤
│ Reduction │ ~92%       │
└───────────┴────────────┘

What the diff looks like for a checkbox click:

[delta snapshot: +1 lines added, -1 lines removed]

  - row: "Melonie Parker, Vice President, Google"
      ...
-     checkbox [unchecked] "Select Melonie Parker"
+     checkbox [checked] "Select Melonie Parker"
      ...
  - row: "Thomas Kurian, CEO, Google"

Safety Guarantees

- First snapshot is always full — agent always starts with complete context
- Savings threshold — if the diff would not save ≥20% of the original size, falls back to the full snapshot; delta mode is never worse than full mode
- lastSnapshot always tracks real DOM state — updated to the full snapshot even when returning a diff, so each subsequent diff is correct
- Navigation resets — navigate(), goBack(), goForward(), and reload() reset lastSnapshot, triggering a full snapshot after any page transition
- Unchanged snapshot — returns a clear message so the agent can decide to retry or verify via screenshot

Files Changed

┌─────────────────────────────────────────────┬─────────────────────────────────────────────────────────────────────────────────────┐
│                    File                     │                                       Change                                        │
├─────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────┤
│ src/utils/snapshot-diff.ts                  │ New — greedy LCS line diff algorithm                                                │
├─────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────┤
│ src/config.ts                               │ deltaSnapshot?: boolean on Config; getDeltaSnapshotEnabled() (default true)         │
├─────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────┤
│ src/constants.ts                            │ DELTA_SNAPSHOT_MIN_SAVINGS_RATIO = 0.2                                              │
├─────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────┤
│ src/tools.ts                                │ Reads delta flag from global config; diff logic in getSnapshot(); navigation resets │
├─────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────┤
│ src/__tests__/snapshot-diff.test.ts         │ 11 new unit tests for diff algorithm                                                │
├─────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────┤
│ src/__tests__/config.test.ts                │ 4 new tests for getDeltaSnapshotEnabled                                             │
├─────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────┤
│ src/__tests__/integration/run-steps.test.ts │ Fixed pre-existing mock missing usage field                                         │
├─────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────┤
│ CHANGELOG.md                                │ Entry under [Unreleased]                                                            │
└─────────────────────────────────────────────┴─────────────────────────────────────────────────────────────────────────────────────┘

Zero breaking changes. Zero new dependencies.