wrangle 0.1.0

data/lib/wrangle/js/snapshot.js

@@ -0,0 +1,118 @@
+// Vendored from browser-use/jev-ultrafast (MIT, Copyright (c) 2026 Browser Use).
+// Modified: the page cache global was renamed from __jevFast to __wrangle.
+(() => {
+  if (!document.body) return null;
+  const cache = window.__wrangle ||= {ids:new WeakMap(), nodes:new Map(), next:1};
+  const identity = e => {
+    if (!cache.ids.has(e)) cache.ids.set(e,cache.next++);
+    const id=cache.ids.get(e); cache.nodes.set(id,e); return id;
+  };
+  for (const [id,e] of cache.nodes) if (!e.isConnected) cache.nodes.delete(id);
+  const safe = e => !['password','file','hidden'].includes(e.type);
+  const visible = e => !e.closest('[aria-hidden="true"],[inert]') &&
+    e.checkVisibility({checkOpacity:true,checkVisibilityCSS:true});
+  const name = (e,seen=new Set()) => {
+    if (!e || seen.has(e)) return '';
+    seen.add(e);
+    const referenced=(e.getAttribute('aria-labelledby')||'').split(/\s+/)
+      .map(id=>name(document.getElementById(id),seen)).filter(Boolean).join(' ');
+    return referenced || e.getAttribute('aria-label') ||
+      [...(e.labels||[])].map(l=>name(l,seen)).filter(Boolean).join(' ') ||
+      (['button','submit','reset'].includes(e.type) ? e.value : '') || e.getAttribute('alt') ||
+      (e.tagName==='INPUT' ? '' : [...e.childNodes].map(n=>n.nodeType===3 ? n.textContent :
+        n.nodeType===1 && n.getAttribute('aria-hidden')!=='true' ? name(n,seen) : '').join(' ').trim()) ||
+      e.getAttribute('title') || e.getAttribute('placeholder') || '';
+  };
+  const roles=['button','link','checkbox','radio','switch','tab','menuitem','menuitemradio',
+    'option','gridcell','combobox','textbox','searchbox','spinbutton'];
+  const selector='a[href],button,input,textarea,select,summary,[contenteditable="true"],'+
+    roles.map(role=>'[role="'+role+'"]').join(',');
+  const role = e => {
+    const explicit=e.getAttribute('role');
+    if (roles.includes(explicit)) return explicit;
+    if (e.tagName==='BUTTON' || e.tagName==='SUMMARY') return 'button';
+    if (e.tagName==='A') return 'link';
+    if (e.tagName==='SELECT') return 'combobox';
+    if (e.tagName==='TEXTAREA' || e.isContentEditable) return 'textbox';
+    if (e.tagName==='INPUT') {
+      if (['checkbox','radio'].includes(e.type)) return e.type;
+      if (['button','submit','reset','image'].includes(e.type)) return 'button';
+      if (e.type==='search') return 'searchbox';
+      if (e.type==='number') return 'spinbutton';
+      if (['text','email','url','tel'].includes(e.type)) return 'textbox';
+    }
+    return null;
+  };
+  // Split by what each part proves, so a stale decision can say which of them moved rather than
+  // reporting that something, somewhere, did: `origin` is the document, `route` is the page within
+  // it, `view` is the viewport, and `form` is the state of every field.
+  //
+  // The route deliberately drops the query string. Sites rewrite it constantly to hold state — a
+  // flight form puts the whole itinerary in `?tfs=` and rewrites it on every keystroke — and
+  // comparing the full URL rejected decisions about controls that had not moved. A real navigation
+  // still shows up: the path changes, or the document does, or the nodes are rebuilt and the
+  // element's own identity changes with them.
+  cache.pageKey=()=>({origin:performance.timeOrigin,route:location.origin+location.pathname,view:[scrollX,scrollY,innerWidth,innerHeight],
+    form:[...document.querySelectorAll('input,textarea,select')].filter(safe)
+      .map(e=>[identity(e),e.value,e.checked,e.selectedIndex,e.disabled,e.readOnly])});
+  cache.guard=e=>{
+    if (!e?.isConnected || !visible(e)) return null;
+    const scope=e.closest('form,dialog,[role="dialog"],article,li,tr,[role="row"]') || e.parentElement;
+    return {self:[identity(e),role(e),name(e),e.value??null,e.checked??null,e.selectedIndex??null,
+      e.readOnly??null,e.matches(':disabled'),e.getAttribute('aria-disabled'),
+      e.getAttribute('aria-expanded'),e.getAttribute('aria-checked'),e.getAttribute('aria-selected'),
+      e.getAttribute('href')],scope:scope?.innerText?.slice(0,6000)||''};
+  };
+  const actions=[];
+  for (const e of document.querySelectorAll(selector)) {
+    if (!safe(e) || !visible(e) || e.matches(':disabled') || e.closest('[aria-disabled="true"]')) continue;
+    const r=e.getBoundingClientRect(), x=r.x+r.width/2, y=r.y+r.height/2, rname=role(e);
+    if (!rname || r.width<=0 || r.height<=0 || x<0 || y<0 || x>=innerWidth || y>=innerHeight) continue;
+    if (rname==='gridcell' && e.querySelector('button,[role="button"]')) continue;
+    const base={node:identity(e),role:rname,label:name(e)||rname,
+      rect:{x:r.x,y:r.y,w:r.width,h:r.height}};
+    for (const key of ['checked','selected','expanded']) {
+      const value=e.getAttribute('aria-'+key);
+      if (value!==null) base[key]=value;
+    }
+    if (['checkbox','radio'].includes(e.type)) base.checked=String(e.checked);
+    if (e.tagName==='SELECT') {
+      for (const o of e.options) if (!o.selected && !o.disabled && !o.closest('optgroup[disabled]'))
+        actions.push({...base,kind:'select',value:o.value,
+          current_value:[...e.selectedOptions].map(o=>o.label).join(', '),label:base.label+' → '+o.label});
+    } else {
+      const editable=!e.readOnly && e.getAttribute('aria-readonly')!=='true' &&
+        (['textbox','searchbox','spinbutton'].includes(rname) ||
+          (rname==='combobox' && ['INPUT','TEXTAREA'].includes(e.tagName)));
+      const value='value' in e ? String(e.value) :
+        e.isContentEditable || rname==='combobox' ? e.innerText.trim() : '';
+      actions.push({...base,kind:editable?'fill':'click',value});
+      if (editable) actions.push({...base,kind:'click',value,label:'Open '+base.label});
+    }
+  }
+  const words=[], walker=document.createTreeWalker(document.body,NodeFilter.SHOW_TEXT);
+  const range=document.createRange(); let node,length=0;
+  while ((node=walker.nextNode()) && length<6000) {
+    const value=node.textContent.trim(), parent=node.parentElement;
+    if (!value || !parent || parent.closest('script,style,noscript,template') || !visible(parent)) continue;
+    range.selectNodeContents(node); const r=range.getBoundingClientRect();
+    if (r.width>0 && r.height>0 && r.bottom>0 && r.top<innerHeight && r.right>0 && r.left<innerWidth) {
+      words.push(value); length+=value.length;
+    }
+  }
+  const text=words.join('\n').slice(0,6000), height=document.documentElement.scrollHeight;
+  const page_key=cache.pageKey(), guards={};
+  for (const a of actions) if (!(a.node in guards)) guards[a.node]=cache.guard(cache.nodes.get(a.node));
+  // Compare meaning and identity. Geometry is always resolved and hit-tested just before input.
+  const semantics=actions.map(({rect,...action})=>action);
+  const marker=[performance.timeOrigin,location.href,scrollX,scrollY,innerWidth,innerHeight,
+    document.title,text,semantics,page_key.form];
+  const omitted_actions=Math.max(0,actions.length-250);
+  actions.splice(250);
+  actions.forEach((a,i)=>a.id='e'+(i+1));
+  if (scrollY+innerHeight<height-2) actions.push({id:'scroll_down',kind:'scroll',label:'Scroll down',delta:560});
+  if (scrollY>0) actions.push({id:'scroll_up',kind:'scroll',label:'Scroll up',delta:-560});
+  actions.push({id:'wait',kind:'wait',label:'Wait for the page to update'});
+  return {url:location.href,title:document.title,w:innerWidth,h:innerHeight,text,
+    scroll:{y:scrollY,height},actions,marker,page_key,guards,omitted_actions};
+})()

data/lib/wrangle/jxa_bridge.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "json"
+require "monitor"
+require "open3"
+
+require_relative "errors"
+
+module Wrangle
+  # A persistent `osascript -l JavaScript` process speaking newline-delimited JSON.
+  #
+  # Spawning osascript costs about 56 ms; a request to a process that is already running costs about
+  # 0.3 ms. Keeping one alive means the only cost left is the Apple Event itself, which is roughly
+  # 17 ms and does not care how much data it carries.
+  class JxaBridge
+    OSASCRIPT = ["/usr/bin/osascript", "-l", "JavaScript"].freeze
+    SCRIPTS = File.expand_path("js", __dir__)
+    MAX_LINE_BYTES = 4_000_000
+    STDERR_LINES = 50
+
+    EOF = :eof
+    INVALID = :invalid
+    OVERSIZED = :oversized
+
+    attr_reader :pid
+
+    def initialize(command: OSASCRIPT, script: File.join(SCRIPTS, "bridge.js"),
+                   request_timeout: 30, startup_timeout: 20)
+      raise ArgumentError, "Bridge timeouts must be positive" unless [request_timeout, startup_timeout].min.positive?
+
+      @command = command
+      @script = script
+      @request_timeout = request_timeout
+      @startup_timeout = startup_timeout
+      @lock = Monitor.new # Monitor, not Mutex: start re-enters request.
+      @lines = Thread::Queue.new
+      @stderr = []
+      @next_id = 1
+      @started = false
+      @closed = false
+    end
+
+    def running? = @wait&.alive? || false
+
+    def stderr = @stderr.dup
+
+    # Spawn the bridge, confirm it answers, and hand it the page scripts once.
+    #
+    # The scripts are sent at startup rather than per call. That keeps about 12 KB off every
+    # subsequent request and, more importantly, means the wire carries data and never program text.
+    def start
+      @lock.synchronize do
+        raise BridgeError, "Bridge is already started" if @started
+        raise BridgeError, "Bridge script is missing: #{@script}" unless File.file?(@script)
+
+        @started = true
+        spawn_process
+        ping = request("ping", timeout: @startup_timeout)
+        request("scripts", timeout: @startup_timeout,
+                           page: File.read(File.join(SCRIPTS, "page.js")),
+                           snapshot: File.read(File.join(SCRIPTS, "snapshot.js")))
+        ping
+      end
+    end
+
+    # Send one operation and return its validated value.
+    def request(op, timeout: nil, **params)
+      @lock.synchronize do
+        ensure_running
+        id = @next_id
+        @next_id += 1
+        begin
+          @stdin.write("#{JSON.generate(params.compact.merge(id: id, op: op))}\n")
+        rescue Errno::EPIPE, IOError
+          raise BridgeError, "The bridge is no longer accepting requests"
+        end
+        response = receive(id, timeout || @request_timeout)
+        raise BridgeCallError.new(response["code"], response["error"]) unless response["ok"]
+
+        response.fetch("value")
+      end
+    end
+
+    # Run one code-owned page request inside the scoped tab and decode its JSON reply.
+    #
+    # The request is encoded here and passed into a fixed page function as a single JSON argument.
+    # It is never interpolated into the program's structure.
+    def evaluate(scope, page_request, verify: false, timeout: nil)
+      raise ArgumentError, "Bridge evaluation needs a scope and a request" unless scope.is_a?(Hash) &&
+                                                                                  page_request.is_a?(Hash)
+
+      value = request("eval", scope: scope, payload: payload(page_request), verify: verify, timeout: timeout)
+      result = value["result"]
+      raise BridgeError, "Bridge evaluation returned no page result" unless result.is_a?(String)
+
+      decoded = begin
+        JSON.parse(result)
+      rescue JSON::ParserError
+        raise BridgeError, "The page returned invalid JSON"
+      end
+      raise BridgeError, "The page returned an invalid result" unless decoded.is_a?(Hash) &&
+                                                                      decoded["status"].is_a?(String)
+
+      decoded
+    end
+
+    # Encode a code-owned page request. Model output only ever travels as a JSON value.
+    def payload(page_request)
+      op = page_request["op"] || page_request[:op]
+      raise ArgumentError, "A page request needs an operation" unless op.is_a?(String)
+
+      JSON.generate(page_request)
+    end
+
+    # Ask the bridge to exit, then make sure the process is gone.
+    def close
+      @lock.synchronize do
+        return if @closed
+        return @closed = true unless @started
+
+        begin
+          # Marked closed only after the request: a bridge must be allowed to answer its own exit.
+          request("exit", timeout: 2) if running?
+        rescue Error
+          nil # A bridge that will not be asked to leave is made to.
+        end
+        @closed = true
+        @stdin&.close unless @stdin&.closed?
+        return if @wait.join(2)
+
+        Process.kill("TERM", @wait.pid)
+        @wait.join(2) || Process.kill("KILL", @wait.pid)
+      end
+    end
+
+    private
+
+    def spawn_process
+      @stdin, stdout, stderr, @wait = Open3.popen3(*@command, @script)
+      @pid = @wait.pid
+      @stdin.sync = true
+      [@stdin, stdout, stderr].each { |io| io.set_encoding("UTF-8") }
+      @readers = [
+        Thread.new do
+          stdout.each_line do |line|
+            @lines << if line.bytesize > MAX_LINE_BYTES
+                        OVERSIZED
+                      else
+                        begin
+                          JSON.parse(line)
+                        rescue JSON::ParserError
+                          INVALID
+                        end
+                      end
+          end
+          @lines << EOF
+        end,
+        Thread.new do
+          stderr.each_line { |line| @stderr.shift if @stderr.push(line.chomp).size > STDERR_LINES }
+        end
+      ]
+      @readers.each { |thread| thread.abort_on_exception = false }
+    rescue SystemCallError => e
+      raise BridgeError, "Could not start osascript: #{e.message}"
+    end
+
+    def receive(id, timeout)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      loop do
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        raise BridgeTimeout, "Bridge request #{id} timed out" if remaining <= 0
+
+        message = @lines.pop(timeout: remaining)
+        raise BridgeTimeout, "Bridge request #{id} timed out" if message.nil?
+        raise BridgeError, "The bridge exited#{" (#{@stderr.last})" if @stderr.any?}" if message == EOF
+        raise BridgeError, "The bridge returned an oversized line" if message == OVERSIZED
+        raise BridgeError, "The bridge wrote invalid JSON" if message == INVALID
+        raise BridgeError, "The bridge returned a non-object response" unless message.is_a?(Hash)
+        # A late reply to an abandoned request is discarded rather than mistaken for this one.
+        next if message["id"].is_a?(Integer) && message["id"] < id
+
+        raise BridgeError, "The bridge returned an unexpected response id" unless message["id"] == id
+
+        return message
+      end
+    end
+
+    def ensure_running
+      raise BridgeError, "Bridge is closed" if @closed
+      raise BridgeError, "Bridge is not started" unless @started
+      raise BridgeError, "Bridge exited with status #{@wait.value.exitstatus}" unless running?
+    end
+  end
+end

data/lib/wrangle/mcp_bridge.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require "json"
+require "monitor"
+require "timeout"
+
+require_relative "errors"
+
+module Wrangle
+  # Drives Safari through `safaridriver --mcp` instead of Apple Events.
+  #
+  # Safari 27 ships an MCP server over stdio, and its `evaluate_javascript` tool is enough to run the
+  # same `snapshot.js` and `page.js` the Apple Events bridge uses. So this is a transport swap, not a
+  # second implementation of the page protocol: the JavaScript, the epoch guard, and the action ids
+  # are identical, and only the pipe underneath changes.
+  #
+  # It is opt-in. The automation server drives its own isolated tab, which means it cannot see the
+  # windows you already have open — including whatever you are signed into. That isolation is the
+  # reason to want it and the reason it is not the default.
+  #
+  # Cost shape, measured on this machine: the first navigation pays about six seconds to bring the
+  # automation browser up, after which an act costs ~3 ms against Apple Events' ~120 ms. It wins on
+  # sessions of roughly thirty actions or more and loses on short ones.
+  class McpBridge
+    COMMAND = ["/usr/bin/safaridriver", "--mcp"].freeze
+    PROTOCOL = "2024-11-05"
+    SCRIPTS = File.expand_path("js", __dir__)
+    MISSING = "__wrangle_runtime_missing__"
+    # Ops that only read. A mutation is never re-dispatched, so only these may be retried after the
+    # runtime is reinstalled.
+    READ_ONLY = %w[install observe marker guard probe].freeze
+
+    def initialize(command: COMMAND, request_timeout: 30, startup_timeout: 25)
+      @command = command
+      @request_timeout = request_timeout
+      @startup_timeout = startup_timeout
+      @lock = Monitor.new
+      @next_id = 1
+      @started = false
+      @closed = false
+      @stderr = []
+      @handle = nil
+    end
+
+    def running? = !@io.nil? && !@io.closed? && !@closed
+
+    def stderr = @stderr.dup
+
+    # Bring the server up and handshake. Returns the Safari instance count the session guard expects;
+    # the automation browser is its own instance, so window ids are never ambiguous here.
+    def start
+      @lock.synchronize do
+        next 1 if @started
+
+        spawn_process
+        rpc("initialize", { protocolVersion: PROTOCOL, capabilities: {},
+                            clientInfo: { name: "wrangle", version: Wrangle::VERSION } }, @startup_timeout)
+        notify("notifications/initialized")
+        @started = true
+        1
+      end
+    end
+
+    def request(op, timeout: nil, **params)
+      @lock.synchronize do
+        start unless @started
+        case op.to_s
+        when "ping" then { "ok" => true }
+        when "open" then open_tab(params, timeout)
+        when "close" then close_tab
+        when "windows" then { "windows" => tabs }
+        when "attach"
+          raise BridgeCallError.new("unsupported", "The MCP backend drives its own tab and cannot " \
+                                                   "attach to a window you already have open.")
+        when "displays", "bounds"
+          raise BridgeCallError.new("unsupported", "The MCP backend has no window geometry; " \
+                                                   "use the Apple Events backend for --display.")
+        else
+          raise BridgeCallError.new("unsupported", "The MCP backend does not support #{op.inspect}")
+        end
+      end
+    end
+
+    # Run one code-owned page request and decode its JSON reply, exactly as the Apple Events bridge
+    # does. `verify` is unnecessary here: the JSON-RPC reply is itself the acknowledgement, so a
+    # request that returns at all was delivered.
+    def evaluate(scope, page_request, verify: false, timeout: nil) # rubocop:disable Lint/UnusedMethodArgument
+      raise ArgumentError, "Bridge evaluation needs a scope and a request" unless scope.is_a?(Hash) &&
+                                                                                  page_request.is_a?(Hash)
+
+      @lock.synchronize do
+        start unless @started
+        decode(dispatch(page_request, timeout))
+      end
+    end
+
+    def close
+      @lock.synchronize do
+        return if @closed
+
+        @closed = true
+        begin
+          close_tab if @handle
+        rescue StandardError
+          nil
+        end
+        shutdown_process
+      end
+    end
+
+    private
+
+    def dispatch(page_request, timeout)
+      op = (page_request["op"] || page_request[:op]).to_s
+      result = run(page_request, timeout)
+      return result unless result == MISSING
+
+      # The document was replaced, so the installed runtime went with it. Reinstalling is a read, but
+      # re-dispatching a mutation is not: an act whose runtime vanished is reported as a lost epoch and
+      # left for the session to resolve by reading it back.
+      install_runtime(timeout)
+      return JSON.generate({ status: "epoch_lost" }) unless READ_ONLY.include?(op)
+
+      result = run(page_request, timeout)
+      raise BridgeError, "The page runtime would not install" if result == MISSING
+
+      result
+    end
+
+    # The runtime is installed once per document; every later call ships only the request.
+    def run(page_request, timeout)
+      expression = "return window.__wrangleRun ? window.__wrangleRun(#{JSON.generate(page_request)}) " \
+                   ": #{JSON.generate(MISSING)}"
+      text = tool("evaluate_javascript", { expression: expression }, timeout)
+      parse_json(text, "page runtime")
+    end
+
+    def install_runtime(timeout)
+      snapshot = File.read(File.join(SCRIPTS, "snapshot.js"))
+      page = File.read(File.join(SCRIPTS, "page.js"))
+      # snapshot.js opens with comments, so it is parenthesised: `return` followed by a comment and a
+      # newline is `return;` under automatic semicolon insertion, which silently yields null.
+      expression = <<~JS
+        window.__wrangleSnapshot = () => (
+        #{snapshot}
+        );
+        window.__wranglePage = (#{page});
+        window.__wrangleRun = (request) => window.__wranglePage(request, window.__wrangleSnapshot);
+        return "installed";
+      JS
+      tool("evaluate_javascript", { expression: expression }, timeout)
+    end
+
+    def decode(result)
+      decoded = begin
+        JSON.parse(result)
+      rescue JSON::ParserError
+        raise BridgeError, "The page returned invalid JSON"
+      end
+      raise BridgeError, "The page returned an invalid result" unless decoded.is_a?(Hash) &&
+                                                                      decoded["status"].is_a?(String)
+
+      decoded
+    end
+
+    def open_tab(params, timeout)
+      url = params[:url] || params["url"]
+      raise BridgeCallError.new("usage", "The MCP backend needs a URL to open") unless url.is_a?(String)
+
+      if params[:display] || params[:bounds]
+        raise BridgeCallError.new("unsupported", "The MCP backend places its own automation tab and " \
+                                                 "cannot honour --display; use the default backend.")
+      end
+
+      tool("navigate_to_url", { url: url }, timeout || @startup_timeout)
+      current = tabs.first || {}
+      @handle = current["handle"]
+      install_runtime(timeout)
+      { "window_id" => 1, "tab_index" => 1, "url" => current["url"] || url, "bounds" => nil }
+    end
+
+    def close_tab
+      handle = @handle
+      @handle = nil
+      return { "closed" => false } unless handle
+
+      tool("close_tab", { handle: handle }, 10)
+      { "closed" => true }
+    end
+
+    def tabs
+      listed = parse_json(tool("list_tabs", {}, 10), "tab list")
+      listed.is_a?(Array) ? listed : []
+    end
+
+    def parse_json(text, what)
+      JSON.parse(text.to_s)
+    rescue JSON::ParserError
+      raise BridgeError, "The MCP server returned an unreadable #{what}"
+    end
+
+    # One MCP tool call, unwrapped to its single text item.
+    def tool(name, arguments, timeout)
+      response = rpc("tools/call", { name: name, arguments: arguments }, timeout || @request_timeout)
+      content = response.dig("result", "content")
+      if response.dig("result", "isError") || !content.is_a?(Array)
+        raise BridgeCallError.new("tool_error", "Safari's #{name} tool failed: #{summarise(response)}")
+      end
+
+      item = content.first
+      raise BridgeError, "Safari's #{name} tool returned no text" unless item.is_a?(Hash) &&
+                                                                         item["text"].is_a?(String)
+
+      item["text"]
+    end
+
+    def summarise(response)
+      text = response.dig("result", "content", 0, "text") || response.dig("error", "message")
+      text.to_s[0, 200]
+    end
+
+    def rpc(method, params, timeout)
+      id = @next_id
+      @next_id += 1
+      write(JSON.generate({ jsonrpc: "2.0", id: id, method: method, params: params }))
+      response = receive(id, timeout)
+      if (error = response["error"])
+        raise BridgeCallError.new("mcp_error", "The MCP server refused #{method}: #{error["message"]}")
+      end
+
+      response
+    end
+
+    def notify(method, params = {})
+      write(JSON.generate({ jsonrpc: "2.0", method: method, params: params }))
+    end
+
+    def write(line)
+      raise BridgeError, "The MCP bridge is no longer accepting requests" unless running?
+
+      @io.write("#{line}\n")
+      @io.flush
+    rescue Errno::EPIPE, IOError
+      raise BridgeError, "The MCP bridge is no longer accepting requests"
+    end
+
+    # Replies are read until the matching id arrives; notifications from the server are discarded.
+    def receive(id, timeout)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      loop do
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        raise BridgeError, "The MCP server did not reply in time" if remaining <= 0
+
+        line = begin
+          Timeout.timeout(remaining) { @io.gets }
+        rescue Timeout::Error
+          raise BridgeError, "The MCP server did not reply in time"
+        end
+        raise BridgeError, "The MCP server closed the connection" if line.nil?
+
+        message = begin
+          JSON.parse(line)
+        rescue JSON::ParserError
+          next
+        end
+        return message if message.is_a?(Hash) && message["id"] == id
+      end
+    end
+
+    def spawn_process
+      @stderr_read, stderr_write = IO.pipe
+      @io = IO.popen(@command, "r+", err: stderr_write)
+      stderr_write.close
+      @stderr_thread = Thread.new do
+        while (line = @stderr_read.gets)
+          @stderr.shift if @stderr.length >= 50
+          @stderr << line.chomp
+        end
+      rescue IOError
+        nil
+      end
+    rescue Errno::ENOENT
+      raise BridgeError, "safaridriver is not available; the MCP backend needs Safari 27 or newer"
+    end
+
+    def shutdown_process
+      @io&.close
+    rescue IOError
+      nil
+    ensure
+      begin
+        @stderr_read&.close
+      rescue IOError
+        nil
+      end
+      @stderr_thread&.kill
+      @io = nil
+    end
+  end
+end

data/lib/wrangle/observation.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Wrangle
+  # Turning an observation into something a decision can be checked against.
+  module Observation
+    # The fields that decide whether a page is "the same page" for the purpose of a decision.
+    FINGERPRINTED = %w[url text actions scroll].freeze
+
+    module_function
+
+    def fingerprint(state)
+      Digest::SHA256.hexdigest(JSON.generate(canonical(state.slice(*FINGERPRINTED))))
+    end
+
+    # Deterministic ordering, so an unchanged page always hashes the same way.
+    def canonical(value)
+      case value
+      when Hash then value.keys.sort.to_h { |key| [key.to_s, canonical(value[key])] }
+      when Array then value.map { |element| canonical(element) }
+      else value
+      end
+    end
+
+    # Return the one observed candidate this action refers to, or refuse to act at all.
+    #
+    # This is the boundary that keeps model output from becoming instructions: a decision may only
+    # name an action the page was just observed to offer, and it must match that candidate exactly.
+    def require_observed(action, page)
+      raise ArgumentError, "Actions require an observed page and action" unless action.is_a?(Hash) && page.is_a?(Hash)
+
+      id = action["id"] || action[:id]
+      candidates = page["actions"]
+      raise ArgumentError, "Action is not bound to an observation" unless id.is_a?(String) && candidates.is_a?(Array)
+
+      matches = candidates.select { |candidate| candidate.is_a?(Hash) && candidate["id"] == id }
+      unless matches.one? && matches.first == stringify(action)
+        raise ArgumentError, "Action is not an exact candidate from the observed page"
+      end
+
+      matches.first
+    end
+
+    def stringify(action)
+      action.to_h { |key, value| [key.to_s, value] }
+    end
+  end
+end