tidewave 0.8.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8aec0fffb76b0c91651452a2d8e2b1adc3fe37681a0c778c01a4762602985ed
-  data.tar.gz: d0f6abae17bcc8281baed3f3db784b0243186c5008a8866a612e42bda4333e14
+  metadata.gz: 1802cbd495807edd296e6ee4b1a413509159e4b15f5aacbb84a0730bb73e51dc
+  data.tar.gz: 263ca6f1ab17b6b2447a1e93cb414483b46ef5842d6408a3b4fb70716ad863c5
 SHA512:
-  metadata.gz: 8b683cb4a188e66e456078a39467a10ff6bc9aa1ac3b3f2e92338eadf5cbe1b0a693e6d80dd32d6e8dfdb167dd0b83af1d1183c442fc6d8348beb036180e05ba
-  data.tar.gz: b3366af6bdd77c9312e8e6d70e56d898b02f75555f9b1932fea379bdb36621a8381f31df8696f86f7a6a5604885ae0ded2f22ee51a9bf323e80c7c7e52422c99
+  metadata.gz: 63a8ac146282fc3e3619c8981867c1d45aa939a6d4885f476b5ca995ecc9a7e7a18bb4c1e5bdb055bdace0114318127fed5be7c65191677ad05c9747a24b032b
+  data.tar.gz: db620af0482b721917ee736308946624e9d842a250473d72632c11628023cb4c762fa4b21663ab37521007c6bcc7ebf922116545630db821ecc3eb9c0ae7f46f

data/README.md

@@ -42,7 +42,6 @@ We also have specific instructions for:
 - [Neovim](https://tidewave.hexdocs.pm/mcp_neovim.html)
 - [OpenCode](https://tidewave.hexdocs.pm/mcp_opencode.html)
 - [VS Code](https://tidewave.hexdocs.pm/mcp_vscode.html)
-- [Zed](https://tidewave.hexdocs.pm/mcp_zed.html)
 - [Others](https://tidewave.hexdocs.pm/mcp.html)
 
 ## Usage
@@ -155,7 +154,7 @@ You may configure `tidewave` using the following syntax:
 
 The following config is available:
 
-  * `allow_remote_access` - Tidewave only allows requests from localhost by default, even if your server listens on other interfaces, for security purposes. Read [our security guidelines for more information and when to allow remote access](https://hexdocs.pm/tidewave/security.html) (if you know what you are doing)
+  * `allow_remote_access` - Tidewave only allows requests from localhost by default, even if your server listens on other interfaces, for security purposes. Read [our security guidelines for more information and when to allow remote access](https://tidewave.hexdocs.pm/security.html) (if you know what you are doing)
 
   * `logger_middleware` - The logger middleware Tidewave should wrap to silence its own logs
 

data/lib/tidewave/browser_control.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require "action_cable"
+# Action Cable's event loop uses concurrent-ruby without requiring it,
+# so we load it explicitly.
+require "concurrent"
+require "json"
+require "logger"
+require "securerandom"
+
+class Tidewave
+  # Server side of Tidewave browser control.
+  #
+  # The WebSocket endpoint is a dedicated Action Cable server, since the user
+  # app may not have one, and if it does it likely has auth. Commands/replies
+  # are routed between MCP request threads and browser connections over Action
+  # Cable pub/sub streams:
+  #
+  #   * tidewave:clients      - all registered pages (used for discovery)
+  #   * tidewave:client:name  - the page registered under name
+  #   * tidewave:reply:ref    - replies to a single run_tool command
+  #
+  # Consequently the routing works across processes whenever the configured
+  # cable adapter does, such as "solid_cable", whereas the default "async"
+  # adapter is single-process.
+  #
+  # The pub/sub bus cannot tell whether a stream has any subscribers, so
+  # the channel broadcasts an "ack" on the reply stream as soon as it picks
+  # up a command, letting the caller fail fast when no client is connected.
+  # Similarly, when a page disconnects, its channel broadcasts "disconnected"
+  # for every command still awaiting a reply, so the caller does not wait
+  # out the full timeout.
+  class BrowserControl
+    CLIENTS_STREAM = "tidewave:clients"
+
+    def self.client_stream(name)
+      "tidewave:client:#{name}"
+    end
+
+    def self.reply_stream(ref)
+      "tidewave:reply:#{ref}"
+    end
+
+    attr_reader :server
+
+    def initialize(cable:, logger: nil, ack_timeout: 1.0)
+      @ack_timeout = ack_timeout
+      @server = Server.new(cable: cable, logger: logger || ::Logger.new(IO::NULL))
+    end
+
+    # Rack entrypoint for the WebSocket endpoint.
+    def call(env)
+      @server.call(env)
+    end
+
+    # Runs the tool against the client owning `sid` and waits for the reply.
+    # `timeout_ms` may be nil to wait indefinitely.
+    #
+    # Returns `[ :ok, reply ]` (the page's response) or `[ :error, reason ]`,
+    # where reason is :invalid_sid, :unknown_client, :timeout, or :disconnected.
+    def run(sid, tool_name, input, timeout_ms)
+      name = parse_sid(sid)
+      return [ :error, :invalid_sid ] unless name
+
+      call_tool(self.class.client_stream(name), tool_name, sid, input, timeout_ms, await_ack: true)
+    end
+
+    # Sends the tool to every connected client and returns the first reply.
+    #
+    # Used for the discovery handshake (a browser_eval call with no sid).
+    # Returns `[ :ok, reply ]` or `[ :error, :timeout ]` when no client
+    # answered in time (the bus cannot tell whether anyone is connected).
+    def broadcast_run(tool_name, input, timeout_ms)
+      call_tool(CLIENTS_STREAM, tool_name, nil, input, timeout_ms, await_ack: false)
+    end
+
+    private
+
+    def parse_sid(sid)
+      name, suffix = sid.split("#", 2)
+      name if name && suffix && !name.empty? && !suffix.empty?
+    end
+
+    def call_tool(stream, tool_name, sid, input, timeout_ms, await_ack:)
+      # The reply stream is derived from the ref, so it must be unique
+      # across processes (unlike a per-process counter).
+      ref = SecureRandom.random_number(2**53)
+      reply_stream = self.class.reply_stream(ref)
+      queue = Queue.new
+      on_message = ->(payload) { queue << decode(payload) }
+      on_subscribed = -> { queue << :subscribed }
+
+      @server.pubsub.subscribe(reply_stream, on_message, on_subscribed)
+
+      # Waiting on the browser can trigger requests back into the app (the
+      # page evaluating code issues requests of its own); if such a request
+      # needs to reload code, the exclusive reload would wait on this
+      # thread's share of the reload interlock, deadlocking until timeout.
+      ActiveSupport::Dependencies.interlock.permit_concurrent_loads do
+        # Adapters confirm subscriptions asynchronously; broadcasting
+        # before the confirmation could lose the reply.
+        if queue.pop(timeout: 5) == :subscribed
+          message = { "type" => "run_tool", "ref" => ref, "name" => tool_name, "sid" => sid, "input" => input }
+          @server.broadcast(stream, message)
+          await_reply(queue, timeout_ms && timeout_ms / 1000.0, await_ack)
+        else
+          [ :error, :timeout ]
+        end
+      end
+    ensure
+      @server.pubsub.unsubscribe(reply_stream, on_message)
+    end
+
+    def await_reply(queue, timeout, await_ack)
+      deadline = timeout && now + timeout
+      ack_deadline = await_ack ? now + @ack_timeout : nil
+
+      loop do
+        wait_until = [ deadline, ack_deadline ].compact.min
+        message = queue.pop(timeout: wait_until && [ wait_until - now, 0 ].max)
+
+        case message.is_a?(Hash) && message["type"]
+        when "tool_reply"
+          return [ :ok, message["reply"] ]
+        when "disconnected"
+          return [ :error, :disconnected ]
+        when "ack"
+          ack_deadline = nil
+        else
+          # No ack means no connected client picked the command up,
+          # so that client is likely already disconnected.
+          return [ :error, :unknown_client ] if ack_deadline && now >= ack_deadline
+          return [ :error, :timeout ] if deadline && now >= deadline
+        end
+      end
+    end
+
+    def decode(payload)
+      JSON.parse(payload)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    class Server < ActionCable::Server::Base
+      # Registry of client names owned by connections in this process,
+      # backing the "hello" name-uniqueness check.
+      attr_reader :client_registry
+
+      def initialize(cable:, logger:)
+        config = ActionCable::Server::Configuration.new
+        config.cable = cable
+        config.connection_class = -> { Tidewave::BrowserControl::Connection }
+        # The origin is validated by the Tidewave middleware before the
+        # request reaches this server.
+        config.disable_request_forgery_protection = true
+        config.logger = logger
+        super(config: config)
+        @client_registry = ClientRegistry.new
+      end
+    end
+
+    class Connection < ActionCable::Connection::Base
+    end
+
+    # Handles a single control page connection.
+    class Channel < ActionCable::Channel::Base
+      def initialize(connection, identifier, params = {})
+        super
+        @mutex = Mutex.new
+        @name = nil
+        @pending_refs = {}
+      end
+
+      def receive(data)
+        case data["type"]
+        when "hello"
+          hello(data["name"])
+        when "tool_reply"
+          tool_reply(data)
+        end
+
+        # "ping" and unknown messages are ignored; the page pings to keep
+        # the socket alive through proxies
+      end
+
+      def unsubscribed
+        server.client_registry.unregister(@name, self) if @name
+
+        refs = @mutex.synchronize do
+          @pending_refs.keys.tap { @pending_refs.clear }
+        end
+
+        refs.each do |ref|
+          server.broadcast(BrowserControl.reply_stream(ref), { "type" => "disconnected" })
+        end
+      end
+
+      private
+
+      def hello(name)
+        return unless name.is_a?(String)
+
+        if server.client_registry.register(name, self)
+          @name = name
+
+          # Commands, including broadcasts, are only delivered to pages
+          # registered under a name.
+          stream_from(BrowserControl.client_stream(name), coder: ActiveSupport::JSON) do |message|
+            handle_command(message)
+          end
+
+          stream_from(CLIENTS_STREAM, coder: ActiveSupport::JSON) do |message|
+            handle_command(message)
+          end
+
+          transmit({ "type" => "hello_ok", "name" => name })
+        else
+          transmit({ "type" => "hello_error", "reason" => "name_taken" })
+        end
+      end
+
+      def handle_command(message)
+        return unless message.is_a?(Hash) && message["type"] == "run_tool"
+
+        ref = message["ref"]
+        return unless ref.is_a?(Integer)
+
+        @mutex.synchronize { @pending_refs[ref] = true }
+        # The ack tells the caller the command reached a connected page
+        # (the pub/sub bus cannot tell whether anyone is subscribed).
+        server.broadcast(BrowserControl.reply_stream(ref), { "type" => "ack" })
+        transmit(message)
+      end
+
+      def tool_reply(data)
+        ref = data["ref"]
+        return unless @mutex.synchronize { @pending_refs.delete(ref) }
+
+        server.broadcast(BrowserControl.reply_stream(ref), data)
+      end
+
+      def server
+        connection.server
+      end
+    end
+
+    class ClientRegistry
+      def initialize
+        @mutex = Mutex.new
+        @clients = {}
+      end
+
+      # Registers `owner` under `name`. Returns false when a different live
+      # owner already holds the name.
+      #
+      # The registry is per-process, so with a multi-process cable adapter
+      # the uniqueness check is best-effort (client-generated names carry
+      # enough entropy for collisions to be negligible).
+      def register(name, owner)
+        @mutex.synchronize do
+          current = @clients[name]
+
+          if current.nil? || current.equal?(owner)
+            @clients[name] = owner
+            true
+          else
+            false
+          end
+        end
+      end
+
+      def unregister(name, owner)
+        @mutex.synchronize do
+          @clients.delete(name) if @clients[name].equal?(owner)
+        end
+      end
+    end
+  end
+end

data/lib/tidewave/configuration.rb

@@ -2,11 +2,15 @@
 
 class Tidewave
   class Configuration
-    attr_accessor :logger, :allow_remote_access, :preferred_orm, :dev, :client_url, :team, :logger_middleware, :toolbar
+    attr_accessor :logger, :allow_remote_access, :cable, :preferred_orm, :dev, :client_url, :team, :logger_middleware, :toolbar
 
     def initialize
       # Rails has a hosts middleware which already checks for this
       @allow_remote_access = true
+      # Cable adapter configuration for the browser control WebSocket.
+      # Defaults to the app's config/cable.yml (or the in-process "async"
+      # adapter when there is none).
+      @cable = nil
       @logger = nil
       @preferred_orm = :active_record
       @dev = false

data/lib/tidewave/railtie.rb

@@ -2,6 +2,7 @@
 
 require "logger"
 require "uri"
+require "tidewave/browser_control"
 require "tidewave/configuration"
 require "tidewave/exceptions_middleware"
 require "tidewave/quiet_requests_middleware"
@@ -10,6 +11,21 @@ class Tidewave
   class Railtie < Rails::Railtie
     config.tidewave = Tidewave::Configuration.new()
 
+    def self.cable_config(app)
+      cable =
+        begin
+          if app.root.join("config", "cable.yml").exist?
+            app.config_for(:cable)&.to_h&.deep_stringify_keys
+          end
+        rescue StandardError => error
+          Rails.logger&.warn("Tidewave could not load config/cable.yml: #{error.message}")
+          nil
+        end
+
+      # Default to the in-process async adapter, as Rails does in development.
+      cable.presence || { "adapter" => "async" }
+    end
+
     initializer "tidewave.setup" do |app|
       unless app.config.enable_reloading
         raise "For security reasons, Tidewave is only supported in environments where config.enable_reloading is true (typically development)"
@@ -21,6 +37,7 @@ class Tidewave
         ActionDispatch::Callbacks,
         Tidewave,
         allow_remote_access: tidewave_config.allow_remote_access,
+        browser_control: Tidewave::BrowserControl.new(cable: tidewave_config.cable || Railtie.cable_config(app)),
         client_url: tidewave_config.client_url,
         framework_type: "rails",
         project_name: app.class.module_parent.name,

data/lib/tidewave/tool.rb

@@ -24,7 +24,7 @@ class Tidewave
       raise NotImplementedError, "#{self.class} must implement #call"
     end
 
-    def validate_and_call(arguments)
+    def validate_and_call(arguments, context = {})
       arguments ||= {}
 
       unless arguments.is_a?(Hash)
@@ -36,7 +36,14 @@ class Tidewave
       # `minLength`, `maxLength`, `enum`, and `pattern` remain descriptive until
       # Tidewave grows broader schema support.
       validate_schema(arguments, definition.fetch("inputSchema", {}))
-      call(arguments)
+
+      # Tools opt into request context (such as the request URL) by
+      # accepting a second argument.
+      if method(:call).arity.abs >= 2
+        call(arguments, context)
+      else
+        call(arguments)
+      end
     end
 
     private

data/lib/tidewave/tools/browser_eval.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+class Tidewave::Tools::BrowserEval < Tidewave::Tool
+  DESCRIPTION = <<~DESCRIPTION
+    Runs JavaScript in a real browser to interact with the application.
+
+    You MUST use "help" action first to learn the full API.
+  DESCRIPTION
+
+  BROADCAST_TIMEOUT_MS = 5_000
+
+  def initialize(options = {})
+    super
+    @browser_control = options[:browser_control]
+  end
+
+  def browser_tool?
+    true
+  end
+
+  def definition
+    return nil unless @browser_control
+
+    {
+      "name" => "browser_eval",
+      "description" => DESCRIPTION,
+      "inputSchema" => {
+        "type" => "object",
+        "properties" => {
+          "action" => {
+            "type" => "string"
+          },
+          "sid" => {
+            "description" => 'The session to target, e.g. "nice-cactus#1".',
+            "type" => "string"
+          },
+          "args" => {
+            "description" => 'Parameters for the action, as documented by "help".',
+            "type" => "object",
+            "additionalProperties" => true
+          }
+        },
+        "required" => [ "action" ]
+      }
+    }
+  end
+
+  def call(arguments, context = {})
+    url = context[:url]
+    sid = arguments["sid"]
+
+    if sid.is_a?(String) && !sid.empty?
+      result = @browser_control.run(sid, "browser_eval", arguments, nil)
+      direct_result(result, sid, url)
+    else
+      # The broadcast case is only expected to run for initial discovery.
+      # We can safely retry once if the first attempt times out.
+      result = @browser_control.broadcast_run("browser_eval", arguments, BROADCAST_TIMEOUT_MS)
+      result = @browser_control.broadcast_run("browser_eval", arguments, BROADCAST_TIMEOUT_MS) if result == [ :error, :timeout ]
+      broadcast_result(result, url)
+    end
+  end
+
+  private
+
+  def direct_result(result, sid, url)
+    status, value = result
+    return value.fetch("result") if status == :ok
+
+    case value
+    when :invalid_sid
+      error_result(%(Invalid sid "#{sid}". A sid looks like "nice-cactus#1".))
+    when :unknown_client
+      error_result(
+        "No connected browser owns sid \"#{sid}\". It may have disconnected — " \
+        'call browser_eval({"action": "new-session"}) to start a new one.'
+      )
+    when :timeout
+      error_result("browser_eval timed out waiting for the browser to respond.")
+    when :disconnected
+      error_result("The browser disconnected before responding. #{open_message(url)}")
+    end
+  end
+
+  def broadcast_result(result, url)
+    status, value = result
+    return value.fetch("result") if status == :ok
+
+    error_result("No browser is connected to the Tidewave control page. #{open_message(url)}")
+  end
+
+  def open_message(url)
+    "Use the `open` command (or similar) to open #{url}/tidewave in the browser and try again"
+  end
+
+  def error_result(text)
+    {
+      "content" => [ { "type" => "text", "text" => text } ],
+      "isError" => true
+    }
+  end
+end

data/lib/tidewave/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Tidewave
-  VERSION = "0.8.0"
+  VERSION = "0.8.1"
 end

data/lib/tidewave.rb

@@ -6,7 +6,6 @@ require "ipaddr"
 require "json"
 require "pathname"
 require "rack/request"
-require "uri"
 require "tidewave/version"
 require "tidewave/tool"
 require "tidewave/database_adapter"
@@ -73,8 +72,9 @@ class Tidewave
   TIDEWAVE_ROUTE = "tidewave".freeze
   MCP_ROUTE = "mcp".freeze
   CONFIG_ROUTE = "config".freeze
-  APP_ROUTE = "app".freeze
+  CONNECT_ROUTE = "connect".freeze
   UPLOAD_ROUTE = "upload".freeze
+  WS_ROUTE = "ws".freeze
   PROTOCOL_VERSION = "2025-03-26".freeze
   MAX_UPLOAD_SIZE = 10_000_000
   ALLOWED_UPLOAD_CONTENT_TYPES = [ "image/png", "image/jpeg", "video/webm" ].freeze
@@ -87,6 +87,7 @@ class Tidewave
     If you really want to allow remote connections, configure Tidewave with the `allow_remote_access: true` option
   TEXT
 
+  INVALID_FETCH_SITE = "For security reasons, Tidewave only accepts requests from the same origin your web app is running on.".freeze
   INVALID_ORIGIN = "For security reasons, Tidewave does not accept requests with an origin header for this endpoint.".freeze
   INVALID_UPLOAD = "Bad Request: missing or invalid file parameter".freeze
   ENCODED_HTML_WARNING = <<~TEXT.freeze
@@ -97,6 +98,7 @@ class Tidewave
 
   DEFAULT_OPTIONS = {
     allow_remote_access: false,
+    browser_control: nil,
     client_url: "https://tidewave.ai",
     framework_type: "rack",
     team: {},
@@ -110,6 +112,7 @@ class Tidewave
 
     @logger = @options[:logger]
     @root = @options[:root] ? Pathname.new(@options[:root].to_s) : Pathname.pwd
+    @browser_control = @options[:browser_control]
     @tools = build_tool_registry
   end
 
@@ -120,12 +123,19 @@ class Tidewave
     if path[0] == TIDEWAVE_ROUTE
       return forbidden(INVALID_IP) unless valid_client_ip?(request)
 
-      return forbidden(INVALID_ORIGIN) if request.get_header("HTTP_ORIGIN") && !origin_allowed_path?(path)
+      origin_error = check_origin(request, path)
+      return origin_error if origin_error
 
       case [ request.request_method, path ]
       when [ "GET", [ TIDEWAVE_ROUTE ] ]
         home_endpoint(request)
-      when [ "GET", [ TIDEWAVE_ROUTE, APP_ROUTE ] ]
+      when [ "GET", [ TIDEWAVE_ROUTE, WS_ROUTE ] ]
+        unless @browser_control
+          raise "this route is currently only supported for Rails"
+        end
+
+        @browser_control.call(request.env)
+      when [ "GET", [ TIDEWAVE_ROUTE, CONNECT_ROUTE ] ]
         app_endpoint(request)
       when [ "GET", [ TIDEWAVE_ROUTE, CONFIG_ROUTE ] ]
         config_endpoint(request)
@@ -168,7 +178,7 @@ class Tidewave
     [ 200, response_headers("text/html", body), [ body ] ]
   end
 
-  def app_endpoint(_request)
+  def app_endpoint(request)
     client_url = @options[:client_url].to_s.sub(%r{/\z}, "")
     body = <<~HTML
       <!DOCTYPE html>
@@ -176,6 +186,7 @@ class Tidewave
         <head>
           <meta charset="UTF-8" />
           <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+          #{config_meta_tag(request)}
           <script type="module" src="#{client_url}/tc/control.js"></script>
         </head>
         <body></body>
@@ -191,13 +202,53 @@ class Tidewave
     json_response(config_data(request), headers: { "access-control-allow-origin" => "*" })
   end
 
+  # Returns a 403 response when the request is not allowed for the given
+  # path, nil otherwise.
+  def check_origin(request, path)
+    case path
+    when [ TIDEWAVE_ROUTE ], [ TIDEWAVE_ROUTE, CONFIG_ROUTE ]
+      # Allow any origin:
+      # * /tidewave is loaded by IDE in a cross-origin iframe
+      # * /config contains metadata for discovery
+      nil
+    when [ TIDEWAVE_ROUTE, CONNECT_ROUTE ], [ TIDEWAVE_ROUTE, WS_ROUTE ], [ TIDEWAVE_ROUTE, UPLOAD_ROUTE ]
+      # Browser-facing routes are subject to the fetch metadata policy
+      forbidden(INVALID_FETCH_SITE) unless allowed_fetch_site?(request)
+    else
+      # The MCP endpoint (and everything else) is meant for MCP clients
+      # and never the browser, so we reject even same-origin browser
+      # requests (browsers set the origin header on all POST requests)
+      forbidden(INVALID_ORIGIN) unless request.get_header("HTTP_ORIGIN").nil?
+    end
+  end
+
+  def allowed_fetch_site?(request)
+    # Note that these checks do not prevent DNS rebinding, but Rails
+    # already guards against it through the HostAuthorization middleware.
+
+    fetch_site = request.get_header("HTTP_SEC_FETCH_SITE")
+    fetch_mode = request.get_header("HTTP_SEC_FETCH_MODE")
+    fetch_dest = request.get_header("HTTP_SEC_FETCH_DEST")
+
+    # Same-origin request or user-originated request.
+    return true if fetch_site.nil? || [ "same-origin", "none" ].include?(fetch_site)
+
+    # Allow regular cross-site top-level navigations, such as following
+    # a link to the /tidewave/connect page. Form submissions are
+    # navigations too, hence the GET check.
+    return true if request.get? && fetch_mode == "navigate" && fetch_dest == "document"
+
+    false
+  end
+
   def mcp_endpoint(request)
     message = JSON.parse(request.body.read)
+    context = mcp_context(request)
 
     if message.is_a?(Array)
-      handle_mcp_batch(message)
+      handle_mcp_batch(message, context)
     else
-      handle_mcp_single(message)
+      handle_mcp_single(message, context)
     end
   rescue JSON::ParserError
     jsonrpc_error_response(nil, -32700, "Parse error", status: 400)
@@ -206,26 +257,36 @@ class Tidewave
     jsonrpc_error_response(nil, -32603, "Internal error")
   end
 
-  def handle_mcp_single(message)
+  def mcp_context(request)
+    tools = @tools
+
+    if request.GET["include_browser_tools"] == "false"
+      tools = tools.reject { |_name, tool| tool.respond_to?(:browser_tool?) && tool.browser_tool? }
+    end
+
+    { tools: tools, url: request.base_url }
+  end
+
+  def handle_mcp_single(message, context)
     validation_error = validate_jsonrpc_message(message)
     return jsonrpc_error_response(nil, -32600, validation_error, status: 400) if validation_error
 
-    response = handle_mcp_message(message)
+    response = handle_mcp_message(message, context)
     response.nil? ? accepted_response : json_response(response)
   end
 
-  def handle_mcp_batch(messages)
+  def handle_mcp_batch(messages, context)
     return jsonrpc_error_response(nil, -32600, "Invalid Request", status: 400) if messages.empty?
 
-    responses = messages.map { |message| handle_mcp_batch_message(message) }.compact
+    responses = messages.map { |message| handle_mcp_batch_message(message, context) }.compact
     responses.empty? ? accepted_response : json_response(responses)
   end
 
-  def handle_mcp_batch_message(message)
+  def handle_mcp_batch_message(message, context)
     validation_error = validate_jsonrpc_message(message)
     return jsonrpc_error_response_body(nil, -32600, validation_error) if validation_error
 
-    handle_mcp_message(message)
+    handle_mcp_message(message, context)
   end
 
   def config_data(request)
@@ -288,6 +349,14 @@ class Tidewave
 
   def toolbar_html(request)
     client_url = @options[:client_url].to_s.sub(%r{/\z}, "")
+
+    <<~HTML
+      #{config_meta_tag(request)}
+      <script async type="module" src="#{client_url}/tc/toolbar.js"></script>
+    HTML
+  end
+
+  def config_meta_tag(request)
     payload = {
       "tidewave" => config_data(request),
       "root" => @root.to_s,
@@ -295,10 +364,7 @@ class Tidewave
       "framework" => {}
     }
 
-    <<~HTML
-      <meta name="tidewave:config" content="#{CGI.escapeHTML(JSON.generate(payload))}" />
-      <script async type="module" src="#{client_url}/tc/toolbar.js"></script>
-    HTML
+    %(<meta name="tidewave:config" content="#{CGI.escapeHTML(JSON.generate(payload))}" />)
   end
 
   def upload_endpoint(request)
@@ -359,15 +425,6 @@ class Tidewave
     }
   end
 
-  def origin_allowed_path?(path)
-    [
-      [ TIDEWAVE_ROUTE ],
-      [ TIDEWAVE_ROUTE, APP_ROUTE ],
-      [ TIDEWAVE_ROUTE, CONFIG_ROUTE ],
-      [ TIDEWAVE_ROUTE, UPLOAD_ROUTE ]
-    ].include?(path)
-  end
-
   def local_port(request)
     sock = request.env["puma.socket"]
     return unless sock
@@ -466,7 +523,7 @@ class Tidewave
   # Returns the JSON-RPC response for a request, or nil for messages that
   # must not be replied to (notifications and client-sent responses), which
   # the transport acknowledges with 202 Accepted.
-  def handle_mcp_message(message)
+  def handle_mcp_message(message, context)
     return nil unless message.key?("method") && message.key?("id")
 
     method = message["method"]
@@ -477,11 +534,11 @@ class Tidewave
     when "ping"
       jsonrpc_success_response_body(request_id, {})
     when "initialize"
-      handle_initialize(request_id, params)
+      handle_initialize(request_id, params, context)
     when "tools/list"
-      jsonrpc_success_response_body(request_id, { "tools" => tool_definitions })
+      jsonrpc_success_response_body(request_id, { "tools" => tool_definitions(context) })
     when "tools/call"
-      handle_tool_call(request_id, params)
+      handle_tool_call(request_id, params, context)
     when "prompts/list"
       jsonrpc_success_response_body(request_id, { "prompts" => [] })
     when "resources/list"
@@ -501,7 +558,7 @@ class Tidewave
     end
   end
 
-  def handle_initialize(request_id, params)
+  def handle_initialize(request_id, params, context)
     client_version = params["protocolVersion"]
     return jsonrpc_error_response_body(request_id, -32602, "Protocol version is required") if client_version.nil? || client_version.empty?
 
@@ -515,20 +572,20 @@ class Tidewave
         "name" => "tidewave",
         "version" => VERSION
       },
-      "tools" => tool_definitions
+      "tools" => tool_definitions(context)
     })
   end
 
-  def handle_tool_call(request_id, params)
+  def handle_tool_call(request_id, params, context)
     tool_name = params["name"]
     arguments = params["arguments"].is_a?(Hash) ? params["arguments"] : {}
 
     return jsonrpc_error_response_body(request_id, -32602, "Tool name is required") if tool_name.nil? || tool_name.empty?
 
-    tool = @tools[tool_name]
+    tool = context[:tools][tool_name]
     return jsonrpc_error_response_body(request_id, -32601, "Tool '#{tool_name}' not found") if tool.nil?
 
-    result = tool.validate_and_call(arguments)
+    result = tool.validate_and_call(arguments, context)
     jsonrpc_success_response_body(request_id, tool_result(result))
   rescue StandardError => error
     @logger&.error("Tool execution error: #{error.message}")
@@ -558,8 +615,8 @@ class Tidewave
     }
   end
 
-  def tool_definitions
-    @tools.values.map(&:definition)
+  def tool_definitions(context)
+    context[:tools].values.map(&:definition)
   end
 
   def tool_error_result(message)
@@ -571,10 +628,9 @@ class Tidewave
 
   def tool_result(result)
     if result.is_a?(Hash)
-      {
-        "content" => [ text_content(JSON.generate(result)) ],
-        "structuredContent" => result
-      }
+      # The tool returned a complete MCP result (browser_eval passes the
+      # browser's reply, including isError, through verbatim)
+      result
     else
       {
         "content" => [ text_content(result.to_s) ]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tidewave
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Yorick Jacquin
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-22 00:00:00.000000000 Z
+date: 2026-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -36,6 +36,7 @@ files:
 - README.md
 - config/database.yml
 - lib/tidewave.rb
+- lib/tidewave/browser_control.rb
 - lib/tidewave/configuration.rb
 - lib/tidewave/database_adapter.rb
 - lib/tidewave/database_adapters/active_record.rb
@@ -45,6 +46,7 @@ files:
 - lib/tidewave/quiet_requests_middleware.rb
 - lib/tidewave/railtie.rb
 - lib/tidewave/tool.rb
+- lib/tidewave/tools/browser_eval.rb
 - lib/tidewave/tools/execute_sql_query.rb
 - lib/tidewave/tools/get_docs.rb
 - lib/tidewave/tools/get_logs.rb
@@ -67,7 +69,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="