mistri 0.1.0 → 0.2.0

data/lib/mistri/mcp/oauth.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "net/http"
+require "securerandom"
+require "uri"
+
+module Mistri
+  module MCP
+    # The OAuth 2.1 subset the MCP spec requires of clients, as three
+    # storage-agnostic services a host calls from anywhere: a controller, a
+    # GraphQL mutation, a job. Each returns a string-keyed hash ready to
+    # persist on the host's own connection record.
+    #
+    #   flow = Mistri::MCP::OAuth.start(url: params[:url],
+    #                                   client_name: "Sendoso",
+    #                                   redirect_uri: mcp_callback_url)
+    #   # persist flow, redirect the user to flow["authorize_url"]
+    #
+    #   tokens = Mistri::MCP::OAuth.complete(code: params[:code], **persisted)
+    #   tokens = Mistri::MCP::OAuth.refresh(**persisted)
+    #
+    # Registration happens as the APPLICATION, never as the harness:
+    # client_name has no default because that identity is the host's call.
+    # Servers without dynamic registration take client_id:/client_secret:
+    # directly and skip it.
+    module OAuth
+      module_function
+
+      # Discover the server's authorization setup, register the application,
+      # and build the authorize URL. Returns everything the callback and
+      # refresh need: authorize_url, state, code_verifier, client_id,
+      # client_secret, token_auth_method, token_endpoint, resource,
+      # redirect_uri.
+      #
+      # With no scope given, the server's advertised scopes_supported are
+      # requested, and offline_access rides along when the authorization
+      # server supports it, which is what earns a refresh token from
+      # providers that require it.
+      def start(url:, client_name:, redirect_uri:, scope: nil,
+                client_id: nil, client_secret: nil)
+        resource = canonical(url)
+        resource_metadata = resource_metadata_for(url)
+        metadata = server_metadata(Array(resource_metadata["authorization_servers"]).first)
+        validate_endpoints(metadata)
+        registration = register(metadata, client_name, redirect_uri, client_id, client_secret)
+        verifier = SecureRandom.urlsafe_base64(48)
+        state = SecureRandom.urlsafe_base64(32)
+        grant = { client_id: registration["client_id"], redirect_uri: redirect_uri,
+                  verifier: verifier, state: state, resource: resource,
+                  scope: resolve_scope(scope, resource_metadata, metadata) }
+        {
+          "authorize_url" => authorize_url(metadata, grant),
+          "state" => state, "code_verifier" => verifier,
+          "client_id" => registration["client_id"],
+          "client_secret" => registration["client_secret"],
+          "token_auth_method" => registration["token_endpoint_auth_method"],
+          "token_endpoint" => metadata.fetch("token_endpoint"),
+          "resource" => resource, "redirect_uri" => redirect_uri
+        }
+      end
+
+      # Exchange the callback's code for tokens.
+      def complete(code:, code_verifier:, client_id:, token_endpoint:, resource:,
+                   redirect_uri:, client_secret: nil, token_auth_method: nil, **)
+        form = { "grant_type" => "authorization_code", "code" => code,
+                 "code_verifier" => code_verifier, "client_id" => client_id,
+                 "redirect_uri" => redirect_uri, "resource" => resource }
+        token_request(token_endpoint, form, client_secret, token_auth_method)
+      end
+
+      # Trade a refresh token for a fresh set; OAuth 2.1 rotates refresh
+      # tokens, so persist the returned one.
+      def refresh(refresh_token:, client_id:, token_endpoint:, resource:,
+                  client_secret: nil, token_auth_method: nil, **)
+        form = { "grant_type" => "refresh_token", "refresh_token" => refresh_token,
+                 "client_id" => client_id, "resource" => resource }
+        token_request(token_endpoint, form, client_secret, token_auth_method)
+      end
+
+      # -- discovery ---------------------------------------------------------
+
+      # RFC 9728: a 401's WWW-Authenticate names the resource metadata URL;
+      # servers that skip the header serve the well-known path.
+      def resource_metadata_for(url)
+        metadata_url = challenge_metadata_url(url) || well_known_resource_url(url)
+        document = get_json(metadata_url)
+        if Array(document["authorization_servers"]).empty?
+          raise Error, "#{metadata_url} names no authorization servers"
+        end
+
+        document
+      end
+
+      def challenge_metadata_url(url)
+        uri = URI(url)
+        response = http(uri) do |connection|
+          request = Net::HTTP::Post.new(uri)
+          request["Accept"] = "application/json, text/event-stream"
+          request["Content-Type"] = "application/json"
+          request.body = JSON.generate({ jsonrpc: "2.0", id: 0, method: "ping" })
+          connection.request(request)
+        end
+        challenge = response["WWW-Authenticate"].to_s
+        challenge[/resource_metadata="([^"]+)"/i, 1]
+      end
+
+      def well_known_resource_url(url)
+        uri = URI(url)
+        path = uri.path.chomp("/")
+        origin = "#{uri.scheme}://#{uri.host}:#{uri.port}"
+        "#{origin}/.well-known/oauth-protected-resource#{path unless path.empty?}"
+      end
+
+      # RFC 8414 metadata, with the OpenID Connect path as a fallback since
+      # large providers often serve only that document.
+      def server_metadata(authority)
+        uri = URI(authority)
+        origin = "#{uri.scheme}://#{uri.host}:#{uri.port}"
+        path = uri.path.chomp("/")
+        candidates = ["#{origin}/.well-known/oauth-authorization-server#{path unless path.empty?}",
+                      "#{origin}#{path}/.well-known/openid-configuration"]
+        candidates.each do |candidate|
+          document = try_json(candidate)
+          return document if document&.key?("token_endpoint")
+        end
+        raise Error, "no authorization server metadata at #{authority}"
+      end
+
+      # RFC 7591 dynamic registration, as the application. Servers without a
+      # registration endpoint require a pre-registered client id. The
+      # returned hash keeps the token endpoint auth method the server
+      # granted, so token requests authenticate the way it expects.
+      def register(metadata, client_name, redirect_uri, client_id, client_secret)
+        return { "client_id" => client_id, "client_secret" => client_secret } if client_id
+
+        endpoint = metadata["registration_endpoint"]
+        unless endpoint
+          raise Error, "the server does not offer dynamic client registration; " \
+                       "pass client_id:/client_secret: from a manual registration"
+        end
+
+        registration = post_json(endpoint, {
+                                   "client_name" => client_name,
+                                   "redirect_uris" => [redirect_uri],
+                                   "grant_types" => %w[authorization_code refresh_token],
+                                   "response_types" => ["code"],
+                                   "token_endpoint_auth_method" => "client_secret_post"
+                                 })
+        {
+          "client_id" => presence(registration["client_id"]) ||
+            raise(Error, "registration returned no client_id"),
+          "client_secret" => presence(registration["client_secret"]),
+          "token_endpoint_auth_method" => presence(registration["token_endpoint_auth_method"])
+        }
+      end
+
+      # No scope given: request what the resource advertises, and add
+      # offline_access when the authorization server supports it (that is
+      # what earns a refresh token from providers that require it). An
+      # unsupported offline_access is stripped rather than sent blind.
+      def resolve_scope(scope, resource_metadata, metadata)
+        scopes = scope.to_s.split
+        scopes = Array(resource_metadata["scopes_supported"]) if scopes.empty?
+        supported = Array(metadata["scopes_supported"])
+        if supported.include?("offline_access")
+          scopes |= ["offline_access"]
+        else
+          scopes -= ["offline_access"]
+        end
+        scopes.empty? ? nil : scopes.join(" ")
+      end
+
+      # The spec requires authorization server endpoints over HTTPS;
+      # loopback stays allowed for development.
+      def validate_endpoints(metadata)
+        %w[authorization_endpoint token_endpoint registration_endpoint].each do |key|
+          value = metadata[key] or next
+          uri = URI(value)
+          next if uri.scheme == "https" || %w[localhost 127.0.0.1 ::1].include?(uri.host)
+
+          raise Error, "#{key} #{value} is not HTTPS"
+        end
+      end
+
+      def presence(value)
+        value.to_s.strip.empty? ? nil : value
+      end
+
+      def authorize_url(metadata, grant)
+        challenge = Digest::SHA256.base64digest(grant[:verifier]).tr("+/", "-_").delete("=")
+        params = { "response_type" => "code", "client_id" => grant[:client_id],
+                   "redirect_uri" => grant[:redirect_uri], "state" => grant[:state],
+                   "code_challenge" => challenge, "code_challenge_method" => "S256",
+                   "resource" => grant[:resource] }
+        params["scope"] = grant[:scope] if grant[:scope]
+        endpoint = URI(metadata.fetch("authorization_endpoint"))
+        endpoint.query = [endpoint.query, URI.encode_www_form(params)].compact.join("&")
+        endpoint.to_s
+      end
+
+      # -- plumbing ----------------------------------------------------------
+
+      # RFC 8707 canonical form: lowercase scheme and host, no fragment.
+      def canonical(url)
+        uri = URI(url)
+        uri.fragment = nil
+        uri.scheme = uri.scheme.downcase
+        uri.host = uri.host.downcase if uri.host
+        uri.to_s
+      end
+
+      def token_request(endpoint, form, client_secret, auth_method = nil)
+        basic = client_secret && auth_method == "client_secret_basic"
+        form = form.merge("client_secret" => client_secret) if client_secret && !basic
+        credentials = basic ? [form["client_id"], client_secret] : nil
+        payload = post_form(endpoint, form, basic_auth: credentials)
+        expires_in = payload["expires_in"]
+        {
+          "access_token" => payload.fetch("access_token"),
+          "refresh_token" => payload["refresh_token"],
+          "scope" => payload["scope"],
+          "expires_at" => expires_in ? Time.now.utc + expires_in.to_i : nil
+        }
+      end
+
+      def get_json(url)
+        uri = URI(url)
+        response = http(uri) { |connection| connection.request(Net::HTTP::Get.new(uri)) }
+        raise Error, "GET #{url} answered #{response.code}" unless response.code.to_i == 200
+
+        JSON.parse(response.body)
+      end
+
+      def try_json(url)
+        get_json(url)
+      rescue Error, JSON::ParserError
+        nil
+      end
+
+      def post_json(url, body)
+        uri = URI(url)
+        response = http(uri) do |connection|
+          request = Net::HTTP::Post.new(uri)
+          request["Content-Type"] = "application/json"
+          request.body = JSON.generate(body)
+          connection.request(request)
+        end
+        unless %w[200 201].include?(response.code)
+          raise Error, "POST #{url} answered #{response.code}: #{response.body.to_s[0, 200]}"
+        end
+
+        JSON.parse(response.body)
+      end
+
+      def post_form(url, form, basic_auth: nil)
+        uri = URI(url)
+        response = http(uri) do |connection|
+          request = Net::HTTP::Post.new(uri)
+          request["Content-Type"] = "application/x-www-form-urlencoded"
+          request["Accept"] = "application/json"
+          request.basic_auth(*basic_auth) if basic_auth
+          request.body = URI.encode_www_form(form)
+          connection.request(request)
+        end
+        payload = begin
+          JSON.parse(response.body)
+        rescue StandardError
+          {}
+        end
+        unless response.code.to_i == 200
+          reason = payload["error_description"] || payload["error"] || response.body.to_s[0, 200]
+          raise Error, "token request failed (#{response.code}): #{reason}"
+        end
+
+        payload
+      end
+
+      def http(uri, &)
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                            open_timeout: 15, read_timeout: 30, &)
+      end
+    end
+  end
+end

data/lib/mistri/mcp/wires.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "io/wait"
+require "json"
+
+module Mistri
+  module MCP
+    # The two ways an MCP conversation travels. A wire takes one JSON-RPC
+    # payload, yields every decoded message the server sends back until the
+    # payload's own response arrives, and knows nothing about MCP semantics;
+    # the Client owns those.
+    module Wires
+      # Streamable HTTP: requests POST to one endpoint, responses arrive as
+      # JSON or an SSE stream. Sessions and bearer auth live here.
+      class Http
+        def initialize(url:, token:, headers:, open_timeout:, read_timeout:)
+          uri = URI(url)
+          @path = uri.path.empty? ? "/" : uri.path
+          @path = "#{@path}?#{uri.query}" if uri.query
+          @transport = Transport.new(origin: "#{uri.scheme}://#{uri.host}:#{uri.port}",
+                                     open_timeout: open_timeout, read_timeout: read_timeout)
+          @token = token
+          @headers = headers
+          @session_id = nil
+          @protocol_version = nil
+        end
+
+        attr_writer :protocol_version
+
+        def call(payload, &)
+          meta = @transport.post_either(@path, body: payload, headers: request_headers, &)
+          capture_session(meta)
+          nil
+        end
+
+        def notify(payload)
+          discard = ->(_record) {}
+          @transport.post_either(@path, body: payload, headers: request_headers, &discard)
+          nil
+        end
+
+        def session? = !@session_id.nil?
+
+        def refreshable? = @token.respond_to?(:call)
+
+        def reset_session = @session_id = nil
+
+        def close = @transport.close
+
+        private
+
+        def request_headers
+          headers = { "Accept" => "application/json, text/event-stream" }
+          headers.merge!(@headers)
+          headers["Authorization"] = "Bearer #{resolve_token}" if @token
+          headers["Mcp-Session-Id"] = @session_id if @session_id
+          headers["MCP-Protocol-Version"] = @protocol_version if @protocol_version
+          headers
+        end
+
+        def resolve_token
+          @token.respond_to?(:call) ? @token.call : @token
+        end
+
+        def capture_session(meta)
+          session = meta && meta["mcp-session-id"]
+          @session_id = session if session
+        end
+      end
+
+      # Stdio: a spawned child process, one JSON-RPC message per line, with
+      # credentials in its environment, as the spec prescribes for local
+      # servers. Its stderr stays attached for honest local debugging.
+      class Stdio
+        def initialize(command:, env: {}, read_timeout: 120)
+          @command = Array(command).map(&:to_s)
+          @env = env.transform_keys(&:to_s).transform_values(&:to_s)
+          @read_timeout = read_timeout
+          @pid = nil
+        end
+
+        def call(payload)
+          spawn_server unless @pid
+          write(payload)
+          loop do
+            record = read_record
+            yield record
+            break if record.is_a?(Hash) && record["id"] == payload[:id]
+          end
+          nil
+        end
+
+        def notify(payload)
+          spawn_server unless @pid
+          write(payload)
+          nil
+        end
+
+        def session? = false
+
+        def refreshable? = false
+
+        def reset_session = nil
+
+        def protocol_version=(_version); end
+
+        def close
+          return unless @pid
+
+          [@stdin, @stdout].each { |io| io.close unless io.closed? }
+          terminate
+          @pid = nil
+        end
+
+        private
+
+        def spawn_server
+          child_in, @stdin = IO.pipe
+          @stdout, child_out = IO.pipe
+          @pid = Process.spawn(@env, *@command, in: child_in, out: child_out)
+          child_in.close
+          child_out.close
+        end
+
+        def write(payload)
+          @stdin.write("#{JSON.generate(payload)}\n")
+          @stdin.flush
+        rescue Errno::EPIPE
+          raise Error, "the MCP server closed its input"
+        end
+
+        # The spec requires stdout to carry only protocol messages, so a
+        # line that is not one is corruption worth failing loudly on.
+        def read_record
+          loop do
+            ready = @stdout.wait_readable(@read_timeout)
+            raise Error, "timed out waiting for the MCP server" unless ready
+
+            line = @stdout.gets
+            raise Error, "the MCP server exited" if line.nil?
+            next if line.strip.empty?
+
+            return JSON.parse(line)
+          end
+        rescue JSON::ParserError
+          raise Error, "the MCP server wrote non-protocol output on stdout"
+        end
+
+        def terminate
+          Process.kill("TERM", @pid)
+          20.times do
+            return if Process.waitpid(@pid, Process::WNOHANG)
+
+            sleep(0.05)
+          end
+          Process.kill("KILL", @pid)
+          Process.waitpid(@pid)
+        rescue Errno::ESRCH, Errno::ECHILD
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/mistri/mcp.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  # Bridge Model Context Protocol servers into Mistri tools: list a server's
+  # tools, hand them to an agent, and everything the harness already does
+  # composes — approval gates on third-party write tools, retries, sub-agent
+  # pools, the ui channel.
+  #
+  #   client = Mistri::MCP::Client.new(url: "https://mcp.linear.app/mcp",
+  #                                    token: -> { connection.fresh_token })
+  #   agent = Mistri.agent("claude-opus-4-8",
+  #                        tools: Mistri::MCP.tools(client, prefix: "linear"))
+  #
+  # The bridge is duck-typed: any client responding to tools (an array of
+  # {"name", "description", "inputSchema"} hashes) and call_tool(name, args)
+  # bridges the same way, so the official mcp gem's client plugs in too.
+  module MCP
+    # A protocol-level failure: a JSON-RPC error, a missing response, an
+    # unsupported negotiation.
+    class Error < Mistri::Error
+      attr_reader :code
+
+      def initialize(message = nil, code: nil)
+        @code = code
+        super(message)
+      end
+    end
+
+    # The server expired this client's session (a 404 with a session
+    # attached); the spec says start a fresh one, and Client does.
+    class SessionExpired < Error; end
+
+    module_function
+
+    # The server's tools as Mistri tools. allow/deny filter by remote name,
+    # prefix namespaces local names ("linear__create_issue") against
+    # collisions, and gates marks tools needing human approval
+    # (gates: { "create_issue" => true }, or needs_approval: for all).
+    def tools(client, allow: nil, deny: [], prefix: nil, needs_approval: false, gates: {})
+      listed = client.tools
+      listed = listed.select { |tool| allow.include?(tool["name"]) } if allow
+      listed = listed.reject { |tool| deny.include?(tool["name"]) }
+      listed.map do |tool|
+        bridge(client, tool, prefix: prefix, gate: gates.fetch(tool["name"], needs_approval))
+      end
+    end
+
+    def bridge(client, spec, prefix: nil, gate: false)
+      remote = spec.fetch("name")
+      local = prefix ? "#{prefix}__#{remote}" : remote
+      Tool.define(local, spec["description"].to_s,
+                  input_schema: spec["inputSchema"] || Tool::EMPTY_SCHEMA,
+                  needs_approval: gate) do |args|
+        answer(client.call_tool(remote, args || {}))
+      end
+    end
+
+    # An MCP result becomes model-readable content: text joins, images ride
+    # as image blocks, and isError answers in band so the model can react.
+    def answer(result)
+      blocks = Array(result["content"]).map { |block| convert(block) }
+      if result["isError"]
+        text = blocks.grep(String).join("\n")
+        return "MCP tool error: #{text.empty? ? "unknown error" : text}"
+      end
+      if blocks.empty? && result["structuredContent"]
+        return JSON.generate(result["structuredContent"])
+      end
+      return blocks.join("\n") if blocks.all?(String)
+
+      blocks
+    end
+
+    def convert(block)
+      case block["type"]
+      when "text" then block["text"].to_s
+      when "image"
+        Content::Image.from_bytes(block["data"].to_s.unpack1("m"),
+                                  mime_type: block["mimeType"] || "image/png")
+      when "resource" then resource_text(block["resource"] || {})
+      when "resource_link" then "[resource: #{block["uri"]}]"
+      else "[unsupported #{block["type"]} content]"
+      end
+    end
+
+    def resource_text(resource)
+      resource["text"] || "[resource: #{resource["uri"]}]"
+    end
+  end
+end
+
+require_relative "mcp/wires"
+require_relative "mcp/client"
+require_relative "mcp/oauth"

data/lib/mistri/reminder.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Mistri
+  # A periodic reminder for long agentic runs: models drift from their
+  # instructions as turns accumulate, and a short reminder at the tail of
+  # the context, where attention is strongest, pulls them back. It rides
+  # transform_context, so it appears fresh on the wire each time it is due
+  # and never persists to the session.
+  #
+  #   agent = Mistri.agent("claude-opus-4-8", tools: tools,
+  #                        transform_context: Mistri::Reminder.every(
+  #                          3, "Stay on gifting. Verify with tools before claiming.",
+  #                        ))
+  #
+  # Due is counted in completed assistant turns: the first reminder lands
+  # once `after` turns have finished (default: one full interval), then
+  # every `interval` turns.
+  class Reminder
+    def self.every(interval, text, after: nil)
+      new(interval: interval, text: text, after: after)
+    end
+
+    def initialize(interval:, text:, after: nil)
+      @interval = [interval.to_i, 1].max
+      @after = (after || @interval).to_i
+      @body = "<system-reminder>\n#{text}\n</system-reminder>"
+    end
+
+    def call(messages)
+      turns = messages.count(&:assistant?)
+      return messages unless turns >= @after && ((turns - @after) % @interval).zero?
+
+      messages + [Message.user(@body)]
+    end
+  end
+end

data/lib/mistri/result.rb

@@ -9,9 +9,11 @@ module Mistri
   #
   # Reads delegate to the final message, so result.text works whether the run
   # completed or suspended.
-  # output is a task's validated value, nil on plain runs.
-  Result = Data.define(:message, :status, :pending, :output) do
-    def initialize(message:, status:, pending: [], output: nil)
+  # output is a task's validated value, nil on plain runs. usage is the
+  # run's own accounting: every persisted turn plus compaction calls, summed
+  # (a resumed run counts from the resume; task sums across its fix passes).
+  Result = Data.define(:message, :status, :pending, :output, :usage) do
+    def initialize(message:, status:, pending: [], output: nil, usage: Usage.zero)
       super
     end
 

data/lib/mistri/tool.rb

@@ -13,7 +13,7 @@ module Mistri
     # bare empty hash.
     EMPTY_SCHEMA = { type: "object", properties: {} }.freeze
 
-    attr_reader :name, :description, :input_schema
+    attr_reader :name, :description, :input_schema, :timeout
 
     # Define a tool. Give the argument shape as a raw JSON Schema hash via
     # input_schema:, or build it in Ruby with a schema: block.
@@ -28,7 +28,7 @@ module Mistri
     end
 
     def initialize(name:, description:, input_schema: EMPTY_SCHEMA, eager_input_streaming: false,
-                   needs_approval: false, &handler)
+                   needs_approval: false, timeout: nil, &handler)
       raise ArgumentError, "tool #{name.inspect} needs a handler block" unless handler
 
       @name = name.to_s
@@ -36,6 +36,7 @@ module Mistri
       @input_schema = input_schema
       @eager_input_streaming = eager_input_streaming
       @needs_approval = needs_approval
+      @timeout = timeout
       @handler = handler
     end
 

data/lib/mistri/tool_executor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "timeout"
+
 module Mistri
   # Runs a turn's tool calls and returns their results in the order the model
   # emitted them, regardless of completion order. Independent calls run
@@ -23,7 +25,10 @@ module Mistri
       calls.each_with_index { |call, index| queue << [call, index] }
       workers = max_concurrency.clamp(1, calls.length)
       Array.new(workers) { worker(queue, results, tools_by_name, context) }.each(&:join)
-      calls.zip(results).map { |call, result| [call, result || INTERRUPTED] }
+      calls.zip(results).map do |call, entry|
+        value, seconds = entry || [INTERRUPTED, nil]
+        [call, value, seconds]
+      end
     end
 
     def worker(queue, results, tools_by_name, context)
@@ -34,8 +39,14 @@ module Mistri
           rescue ThreadError
             break
           end
-          interrupted = context.signal&.aborted?
-          results[index] = interrupted ? INTERRUPTED : run_one(call, tools_by_name, context)
+          if context.signal&.aborted?
+            results[index] = [INTERRUPTED, nil]
+            next
+          end
+
+          started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          value = run_one(call, tools_by_name, context)
+          results[index] = [value, Process.clock_gettime(Process::CLOCK_MONOTONIC) - started]
         end
       end
     end
@@ -44,11 +55,21 @@ module Mistri
       tool = tools_by_name[call.name]
       return "Error: unknown tool #{call.name.inspect}" unless tool
 
-      with_rails_executor { tool.call(call.arguments, context) }
+      with_rails_executor { invoke(tool, call, context) }
     rescue StandardError => e
       "Error running tool #{call.name.inspect}: #{e.class}: #{e.message}"
     end
 
+    # A tool with a timeout answers in band when it stalls, so one hung
+    # handler cannot stall the whole run.
+    def invoke(tool, call, context)
+      return tool.call(call.arguments, context) unless tool.timeout
+
+      Timeout.timeout(tool.timeout) { tool.call(call.arguments, context) }
+    rescue Timeout::Error
+      "Error running tool #{call.name.inspect}: timed out after #{tool.timeout}s"
+    end
+
     # Concurrent tools share the caller's sink; sinks are not required to be
     # thread-safe, so forwarded events serialize here.
     def thread_safe(emit)