tidewave 0.5.2 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c64d42ec2ee75f35b02997081d24e69fe547d8b9a20a230daeb1d1995a30cd0a
-  data.tar.gz: 74e1cc3e89cdea2b1d4701990ca3fbe3b4b3a5c828735bef5251c91a1d8c074a
+  metadata.gz: 1802cbd495807edd296e6ee4b1a413509159e4b15f5aacbb84a0730bb73e51dc
+  data.tar.gz: 263ca6f1ab17b6b2447a1e93cb414483b46ef5842d6408a3b4fb70716ad863c5
 SHA512:
-  metadata.gz: a2cf21787f51875cbec78b12b5800c7f03b8d516360fd960110f8717dc762f47e58f4f7a4b243c3f0120e254075f17495e86d6c3538d22dd8abe6ac046d3fc6d
-  data.tar.gz: 789f139be709d1bc9a0d55b8cb661b9212b3ce2b4fa546d2c644b3a676a6a2843687407e2efdc87c8a0785290c2aab1806693b07698cd71f9fb9e7f130714786
+  metadata.gz: 63a8ac146282fc3e3619c8981867c1d45aa939a6d4885f476b5ca995ecc9a7e7a18bb4c1e5bdb055bdace0114318127fed5be7c65191677ad05c9747a24b032b
+  data.tar.gz: db620af0482b721917ee736308946624e9d842a250473d72632c11628023cb4c762fa4b21663ab37521007c6bcc7ebf922116545630db821ecc3eb9c0ae7f46f

data/README.md

@@ -12,9 +12,7 @@ Your agent will be able to use this MCP server to talk to your running Rails app
 
 This MCP server is an open-source component of [Tidewave](https://tidewave.ai), the agentic development environment for Rails and Phoenix.
 
-You can use this project as a standalone MCP server or integrated with the [Tidewave product](https://tidewave.ai).
-
-To use it as a standalone MCP server, follow the installation instructions below.
+You can use this project as a standalone MCP server or integrated with the [Tidewave product](https://tidewave.ai) by following the instructions below.
 
 ## Installation
 
@@ -44,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
@@ -117,6 +114,10 @@ Also, because it resolves the location from your running app instead of parsing
 
 ## Troubleshooting
 
+### The Tidewave toolbar is missing
+
+This may happen if you are compressing your responses (gzip, brotli, etc) after the Tidewave middleware runs. Use `bin/rails middleware` and make sure Tidewave comes after `Rack::Deflater` or similar. Also look into your browser and terminal logs for any errors.
+
 ### Using multiple hosts/subdomains
 
 If you are using multiple hosts/subdomains during development, you must use `*.localhost`, as such domains are considered secure by browsers. Additionally, add the following to `config/initializers/development.rb`:
@@ -135,7 +136,7 @@ The above will allow your application to run embedded within Tidewave across mul
 
 ### Content security policy
 
-If you have enabled Content-Security-Policy, Tidewave will automatically enable "unsafe-eval" under `script-src` in order for contextual browser testing to work correctly. It also disables the `frame-ancestors` directive.
+If you have enabled Content-Security-Policy, Tidewave will automatically enable "unsafe-eval" under `script-src` in order for contextual browser testing to work correctly. It also disables the `frame-ancestors` directive. This is done only in the environments that Tidewave is loadead (development by default).
 
 ### Production Environment
 
@@ -153,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
 
@@ -161,6 +162,8 @@ The following config is available:
 
   * `team` - set your Tidewave Team configuration, such as `config.tidewave.team = { id: "my-company" }`
 
+  * `toolbar` - controls whether the Tidewave toolbar is injected into HTML pages. Defaults to `true`
+
 ## Acknowledgements
 
 A thank you to Yorick Jacquin for the initial version of this project.

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,17 +2,22 @@
 
 class Tidewave
   class Configuration
-    attr_accessor :logger, :allow_remote_access, :preferred_orm, :dev, :client_url, :team, :logger_middleware
+    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
       @client_url = "https://tidewave.ai"
       @team = {}
       @logger_middleware = nil
+      @toolbar = true
     end
   end
 end

data/lib/tidewave/magic_bytes.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class Tidewave
+  module MagicBytes
+    module_function
+
+    def type(bytes)
+      case bytes
+      when /\A\xFF\xD8\xFF/n
+        :jpg
+      when /\A\x89PNG\r\n\x1A\n/n
+        :png
+      when /\A\x1A\x45\xDF\xA3/n
+        bytes.include?("webm") ? :webm : :unknown
+      else
+        :unknown
+      end
+    end
+  end
+end

data/lib/tidewave/railtie.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "logger"
+require "uri"
+require "tidewave/browser_control"
 require "tidewave/configuration"
 require "tidewave/exceptions_middleware"
 require "tidewave/quiet_requests_middleware"
@@ -9,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)"
@@ -20,10 +37,12 @@ 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,
         team: tidewave_config.team,
+        toolbar: tidewave_config.toolbar,
         logger: tidewave_config.logger || Rails.logger,
         root: Rails.root,
         log_file: Rails.root.join("log", "#{Rails.env}.log"),
@@ -35,11 +54,21 @@ class Tidewave
         # If the user configured CSP, we need to alter it in dev
         # to allow TC to run browser_eval.
         app.config.content_security_policy.try do |content_security_policy|
-          content_security_policy.directives["script-src"].try do |script_src|
+          directives = content_security_policy.directives
+          script_src = directives["script-src"] || directives["default-src"]&.dup
+          client_origin = URI.parse(tidewave_config.client_url.to_s).origin
+
+          script_src.try do
             script_src << "'unsafe-eval'" unless script_src.include?("'unsafe-eval'")
+            script_src << client_origin unless script_src.include?(client_origin)
+            directives["script-src"] = script_src
+          end
+
+          directives["script-src-elem"].try do |script_src_elem|
+            script_src_elem << client_origin unless script_src_elem.include?(client_origin)
           end
 
-          content_security_policy.directives.delete("frame-ancestors")
+          directives.delete("frame-ancestors")
         end
       end
     end

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/tools/execute_sql_query.rb

@@ -48,6 +48,17 @@ class Tidewave::Tools::ExecuteSqlQuery < Tidewave::Tool
   def call(arguments_hash)
     query = arguments_hash.fetch("query")
     arguments = arguments_hash.fetch("arguments", [])
-    @database_adapter.execute_query(query, arguments)
+    result = @database_adapter.execute_query(query, arguments)
+
+    preamble = if result[:row_count] > result[:rows].length
+      <<~TEXT
+        Query returned #{result[:row_count]} rows. Only the first #{result[:rows].length} rows are included in the result. Use your database's pagination syntax, such as LIMIT + OFFSET, to show more rows if applicable.
+
+      TEXT
+    else
+      ""
+    end
+
+    preamble + result.inspect
   end
 end

data/lib/tidewave/version.rb

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

data/lib/tidewave.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
+require "fileutils"
+require "cgi"
 require "ipaddr"
 require "json"
+require "pathname"
 require "rack/request"
 require "tidewave/version"
 require "tidewave/tool"
 require "tidewave/database_adapter"
+require "tidewave/magic_bytes"
 require "tidewave/railtie" if defined?(Rails::Railtie)
 
 class Tidewave
@@ -25,10 +29,57 @@ Dir[gem_tools_path].sort.each do |file|
 end
 
 class Tidewave
+  class ToolbarBody
+    def initialize(body, toolbar)
+      @body = body
+      @toolbar = toolbar
+      @closed = false
+    end
+
+    def each
+      return enum_for(:each) unless block_given?
+
+      pending = +""
+      injected = false
+
+      @body.each do |part|
+        if injected
+          yield part
+        else
+          pending << part
+
+          if closing_head = pending.downcase.index("</head>")
+            toolbar = @toolbar.dup.force_encoding(pending.encoding)
+            output = pending.insert(closing_head, toolbar)
+            pending = nil
+            injected = true
+            yield output
+          end
+        end
+      end
+
+      yield pending unless injected || pending.empty?
+    end
+
+    def close
+      return if @closed
+
+      @closed = true
+      @body.close if @body.respond_to?(:close)
+    end
+  end
+
   TIDEWAVE_ROUTE = "tidewave".freeze
   MCP_ROUTE = "mcp".freeze
   CONFIG_ROUTE = "config".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
+  ALLOWED_UPLOAD_TYPES = [ "screenshot", "recording" ].freeze
+  TMP_DIR = "tmp".freeze
 
   INVALID_IP = <<~TEXT.freeze
     For security reasons, Tidewave does not accept remote connections by default.
@@ -36,13 +87,22 @@ 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
+    Tidewave could not inject the toolbar because the HTML response is encoded.
+
+    If you use Rack::Deflater or another compression middleware, place it before Tidewave in the middleware stack.
+  TEXT
 
   DEFAULT_OPTIONS = {
     allow_remote_access: false,
+    browser_control: nil,
     client_url: "https://tidewave.ai",
     framework_type: "rack",
-    team: {}
+    team: {},
+    toolbar: true
   }.freeze
 
   def initialize(app, options = {})
@@ -51,6 +111,8 @@ class Tidewave
     raise ArgumentError, "project_name is required" if @options[:project_name].to_s.empty?
 
     @logger = @options[:logger]
+    @root = @options[:root] ? Pathname.new(@options[:root].to_s) : Pathname.pwd
+    @browser_control = @options[:browser_control]
     @tools = build_tool_registry
   end
 
@@ -60,24 +122,34 @@ class Tidewave
 
     if path[0] == TIDEWAVE_ROUTE
       return forbidden(INVALID_IP) unless valid_client_ip?(request)
-      if request.get_header("HTTP_ORIGIN") && !origin_allowed_path?(path)
-        return forbidden(INVALID_ORIGIN)
-      end
+
+      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, 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)
       when [ "POST", [ TIDEWAVE_ROUTE, MCP_ROUTE ] ]
         mcp_endpoint(request)
+      when [ "POST", [ TIDEWAVE_ROUTE, UPLOAD_ROUTE ] ]
+        upload_endpoint(request)
       else
         # The MCP Streamable HTTP transport requires the MCP endpoint to answer
         # non-POST methods with 405 (GET without SSE support, DELETE, etc.)
         path == [ TIDEWAVE_ROUTE, MCP_ROUTE ] ? method_not_allowed() : not_found()
       end
     else
-      strip_x_frame_options(@app.call(env))
+      inject_toolbar(request, strip_x_frame_options(@app.call(env)))
     end
   end
 
@@ -106,17 +178,77 @@ class Tidewave
     [ 200, response_headers("text/html", body), [ body ] ]
   end
 
+  def app_endpoint(request)
+    client_url = @options[:client_url].to_s.sub(%r{/\z}, "")
+    body = <<~HTML
+      <!DOCTYPE html>
+      <html>
+        <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>
+      </html>
+    HTML
+
+    headers = response_headers("text/html", body)
+    headers["content-security-policy"] = "base-uri 'self'; frame-ancestors 'self';"
+    [ 200, headers, [ body ] ]
+  end
+
   def config_endpoint(request)
     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)
@@ -125,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)
@@ -154,8 +296,95 @@ class Tidewave
       "orm_adapter" => @options[:orm_adapter],
       "team" => @options[:team] || {},
       "tidewave_version" => VERSION,
-      "local_port" => local_port(request)
+      "local_port" => local_port(request),
+      "tmp_dir" => TMP_DIR
+    }
+  end
+
+  def inject_toolbar(request, response)
+    status, headers, body = response
+    return response if @options[:toolbar] == false || !html_response?(headers)
+
+    if encoded_response?(headers)
+      warn_encoded_html
+      return response
+    end
+
+    return response unless body.respond_to?(:each)
+
+    delete_response_header(headers, "content-length")
+    delete_response_header(headers, "etag")
+    [ status, headers, ToolbarBody.new(body, toolbar_html(request)) ]
+  end
+
+  def html_response?(headers)
+    content_types = Array(response_header(headers, "content-type"))
+
+    content_types.any? { |content_type| content_type.to_s.downcase.start_with?("text/html") }
+  end
+
+  def encoded_response?(headers)
+    Array(response_header(headers, "content-encoding")).any? do |content_encoding|
+      content_encoding.to_s.split(",").any? do |encoding|
+        !encoding.strip.empty? && encoding.strip.downcase != "identity"
+      end
+    end
+  end
+
+  def response_header(headers, name)
+    key = headers.keys.find { |header| header.downcase == name }
+    headers[key] if key
+  end
+
+  def delete_response_header(headers, name)
+    headers.delete_if { |header, _value| header.downcase == name }
+  end
+
+  def warn_encoded_html
+    return if @warned_encoded_html
+
+    @warned_encoded_html = true
+    @logger&.warn(ENCODED_HTML_WARNING)
+  end
+
+  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,
+      "wsl_distro" => ENV["WSL_DISTRO_NAME"],
+      "framework" => {}
     }
+
+    %(<meta name="tidewave:config" content="#{CGI.escapeHTML(JSON.generate(payload))}" />)
+  end
+
+  def upload_endpoint(request)
+    return text_response(400, INVALID_UPLOAD) if upload_too_large?(request)
+
+    params = request.POST
+    type = params["type"]
+    upload = normalize_upload(params["file"])
+
+    unless ALLOWED_UPLOAD_TYPES.include?(type) && allowed_upload?(upload)
+      return text_response(400, INVALID_UPLOAD)
+    end
+
+    FileUtils.mkdir_p(upload_dir(type))
+    destination = upload_path(type, upload[:filename])
+    FileUtils.cp(upload[:path], destination)
+
+    json_response({ "status" => "ok", "path" => relative_path_from_root(destination) })
+  rescue ArgumentError
+    text_response(400, INVALID_UPLOAD)
   end
 
   def json_response(payload, status: 200, headers: {})
@@ -196,10 +425,6 @@ class Tidewave
     }
   end
 
-  def origin_allowed_path?(path)
-    path == [ TIDEWAVE_ROUTE ] || path == [ TIDEWAVE_ROUTE, CONFIG_ROUTE ]
-  end
-
   def local_port(request)
     sock = request.env["puma.socket"]
     return unless sock
@@ -220,6 +445,67 @@ class Tidewave
     false
   end
 
+  def upload_too_large?(request)
+    request.content_length && request.content_length.to_i > MAX_UPLOAD_SIZE
+  end
+
+  def normalize_upload(upload)
+    case upload
+    when Hash
+      tempfile = upload[:tempfile] || upload["tempfile"]
+      {
+        filename: upload[:filename] || upload["filename"],
+        content_type: upload[:type] || upload["type"],
+        path: tempfile&.path
+      }
+    else
+      return {} unless upload.respond_to?(:original_filename) && upload.respond_to?(:content_type)
+
+      {
+        filename: upload.original_filename,
+        content_type: upload.content_type,
+        path: upload.tempfile&.path
+      }
+    end
+  end
+
+  def allowed_upload?(upload)
+    ALLOWED_UPLOAD_CONTENT_TYPES.include?(upload[:content_type].to_s.split(";").first) &&
+      upload[:path] &&
+      Tidewave::MagicBytes.type(File.binread(upload[:path], 128)) != :unknown
+  end
+
+  def upload_dir(type)
+    @root.join(TMP_DIR, "tidewave", folder_for_upload_type(type)).to_s
+  end
+
+  def upload_path(type, filename)
+    filename = filename.to_s
+
+    unless filename.match?(/\A[A-Za-z0-9_.-]+\z/) && !filename.include?("..")
+      raise ArgumentError, "filename must only contain numbers, letters, hyphens, and underscores: #{filename}"
+    end
+
+    unless [ ".png", ".jpg", ".jpeg", ".webm" ].include?(File.extname(filename).downcase)
+      raise ArgumentError, "filename must have a valid extension (.png, .jpg, .jpeg, .webm): #{filename}"
+    end
+
+    File.join(upload_dir(type), filename)
+  end
+
+  def folder_for_upload_type(type)
+    case type
+    when "screenshot"
+      "screenshots"
+    when "recording"
+      "recordings"
+    end
+  end
+
+  def relative_path_from_root(path)
+    Pathname.new(path).relative_path_from(@root).to_s
+  end
+
   def validate_jsonrpc_message(message)
     return "Message must be a JSON object" unless message.is_a?(Hash)
     return "Invalid JSON-RPC version" unless message["jsonrpc"] == "2.0"
@@ -237,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"]
@@ -248,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"
@@ -272,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?
 
@@ -286,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}")
@@ -329,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)
@@ -342,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.5.2
+  version: 0.8.1
 platform: ruby
 authors:
 - Yorick Jacquin
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-09 00:00:00.000000000 Z
+date: 2026-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -36,14 +36,17 @@ 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
 - lib/tidewave/database_adapters/sequel.rb
 - lib/tidewave/exceptions_middleware.rb
+- lib/tidewave/magic_bytes.rb
 - 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
@@ -66,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:
   - - ">="