actionagent 1.7.2 → 1.8.0

data/app/services/action_agent/local_sandbox_databases.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # The database a :local sandbox boots on, unless its sandbox.yml says
+  # otherwise. A checkout of the app the dashboard itself runs names the same
+  # development database in its config/database.yml, and its `db:prepare`
+  # would migrate the developer's own; so every sandbox gets databases of its
+  # own, through the variables Rails merges over database.yml
+  # (ActiveRecord::DatabaseConfigurations#environment_value_for):
+  # DATABASE_URL for the `primary` entry, <NAME>_DATABASE_URL for any other
+  # (QUEUE_DATABASE_URL for Solid Queue's `queue`).
+  #
+  # Only the adapter and database names are read, from the checkout's
+  # config/database.yml, and nothing of the checkout runs in the dashboard:
+  # ERB tags are blanked out rather than evaluated, and the YAML is read with
+  # safe_load. What is left over is enough to know the adapter, which is
+  # all a URL needs; the host, user and password stay whatever database.yml
+  # or the process environment (PGHOST and the like) say, because Rails
+  # merges a URL over the entry rather than replacing it.
+  #
+  #   sqlite3            sqlite3:<workspace>/db/<env>[_<name>].sqlite3, removed with the workspace
+  #   postgresql/postgis postgresql:///<database>_sandbox_<short id>, dropped on terminate
+  #   mysql2/trilogy     mysql2:///<database>_sandbox_<short id>, dropped on terminate
+  #
+  # Any variable the sandbox.yml env sets is left to it.
+  class LocalSandboxDatabases
+    CONFIG_PATH = File.join("config", "database.yml")
+    # Larger than any database.yml; a checkout could point the path anywhere.
+    MAX_CONFIG_BYTES = 256 * 1024
+    # Stands in for every <%= %> output. Not an identifier, so a database
+    # name built from ERB is never mistaken for a real one.
+    ERB_OUTPUT = "(erb)"
+    ERB_TAG = /<%(?!%)(=|-|\#)?.*?-?%>/m
+    FILE_ADAPTERS = %w[sqlite3].freeze
+    SERVER_ADAPTERS = %w[postgresql postgis mysql2 trilogy].freeze
+    # PostgreSQL cuts identifiers at 63 bytes, MySQL at 64.
+    MAX_DATABASE_NAME = 63
+    IDENTIFIER = /\A[A-Za-z0-9_]+\z/
+    ENTRY_NAME = /\A[A-Za-z][A-Za-z0-9_]*\z/
+
+    # What the backend does with a checkout's databases.
+    #
+    # env      the variables to add to every boot step's environment
+    # drop_targets the named server database URLs terminate may drop
+    # notes    one line per decision, for the setup log
+    Plan = Struct.new(:env, :drop_targets, :rails_env, :notes, keyword_init: true) do
+      def drop
+        drop_targets.any?
+      end
+
+      def empty?
+        env.empty?
+      end
+    end
+
+    # @param app [Pathname] the checkout
+    # @param workspace [Pathname] the sandbox's workspace
+    # @param session_id [String]
+    # @param overrides [Hash] the sandbox.yml env: what it sets is its own
+    # @param fallback_name [String, nil] a database name base when
+    #   database.yml gives none (the repository's name)
+    # @return [Plan]
+    def self.plan(app:, workspace:, session_id:, overrides: {}, fallback_name: nil)
+      new(app: app, workspace: workspace, session_id: session_id, overrides: overrides, fallback_name: fallback_name).plan
+    end
+
+    def initialize(app:, workspace:, session_id:, overrides:, fallback_name:)
+      @app = Pathname(app)
+      @workspace = Pathname(workspace)
+      @session_id = session_id.to_s
+      @overrides = overrides.to_h
+      @fallback_name = fallback_name
+      @notes = []
+    end
+
+    def plan
+      env = {}
+      drop_targets = {}
+      entries = read_entries || []
+      urls = {}
+
+      # Resolve writers before their replicas, independent of YAML order.
+      entries.sort_by { |_name, config| truthy?(config["replica"]) ? 1 : 0 }.each do |name, config|
+        variable = database_variable(name)
+        if @overrides.key?(variable)
+          urls[name] = @overrides[variable] unless config.key?("url")
+          note("#{variable}: left to .activeagents/sandbox.yml")
+          next
+        end
+
+        url, server = url_for(name, config, entries, urls)
+        next unless url
+
+        urls[name] = url
+        env[variable] = url
+        drop_targets[name] = url if server
+        note("#{variable}=#{url}")
+      end
+
+      # db:prepare and db:drop in development also reach the test
+      # database, unless DATABASE_URL is set; that one is the developer's.
+      env["SKIP_TEST_DATABASE"] = "1" if env.any? && !@overrides.key?("SKIP_TEST_DATABASE")
+      Plan.new(env: env, drop_targets: drop_targets, rails_env: rails_env, notes: @notes)
+    end
+
+    private
+
+    def rails_env
+      @overrides["RAILS_ENV"].presence || @overrides["RACK_ENV"].presence || "development"
+    end
+
+    # [[name, config], ...] for the Rails environment the sandbox boots in,
+    # or nil when database.yml cannot say.
+    def read_entries
+      text = read_config
+      return nil unless text
+
+      data = begin
+        YAML.safe_load(text.gsub(ERB_TAG) { ::Regexp.last_match(1) == "=" ? ERB_OUTPUT : "" }, aliases: true)
+      rescue Psych::Exception
+        nil
+      end
+      return adapter_from_text(text) unless data.is_a?(Hash)
+
+      config = data[rails_env]
+      case config
+      when Hash
+        if config.any? && config.values.all?(Hash)
+          config.select { |name, _| ENTRY_NAME.match?(name.to_s) }.map { |name, entry| [ name.to_s, entry ] }
+        else
+          [ [ "primary", config ] ]
+        end
+      when String
+        note("#{CONFIG_PATH}: #{rails_env} is a URL, which Rails does not let DATABASE_URL override; set it in .activeagents/sandbox.yml")
+        nil
+      else
+        note("#{CONFIG_PATH}: no #{rails_env} configuration")
+        nil
+      end
+    end
+
+    # A config that does not parse once its ERB is blanked (a tag that
+    # emits whole keys) still names its adapter somewhere: the first
+    # `adapter:` line, as one primary database.
+    def adapter_from_text(text)
+      adapter = text[/^\s*adapter:\s*["']?([A-Za-z0-9_]+)/, 1]
+      unless adapter
+        note("#{CONFIG_PATH}: could not be read without running its ERB; no sandbox database set")
+        return nil
+      end
+
+      [ [ "primary", { "adapter" => adapter } ] ]
+    end
+
+    def read_config
+      path = @app.join(CONFIG_PATH)
+      return nil unless path.file?
+
+      # Read only inside the checkout: a symlink could name any file the
+      # dashboard's user can read.
+      real = path.realpath
+      unless real.to_s.start_with?("#{@app.realpath}#{File::SEPARATOR}")
+        note("#{CONFIG_PATH}: points outside the checkout; not read")
+        return nil
+      end
+      if real.size > MAX_CONFIG_BYTES
+        note("#{CONFIG_PATH}: too large to read")
+        return nil
+      end
+
+      real.read.force_encoding(Encoding::UTF_8).scrub
+    rescue SystemCallError
+      nil
+    end
+
+    # [url, server?] for one entry, or nil when it is left alone.
+    def url_for(name, config, entries, urls)
+      unless config.is_a?(Hash)
+        note("#{name}: not a mapping; left alone")
+        return nil
+      end
+      if config.key?("url")
+        # A url: entry is a UrlConfig, which Rails merges no variable over.
+        note("#{name}: has its own url:, which Rails does not let a variable override; set it in .activeagents/sandbox.yml")
+        return nil
+      end
+      if config.key?("database_tasks") && !truthy?(config["database_tasks"])
+        note("#{name}: database_tasks is off (a database the app does not manage); left alone")
+        return nil
+      end
+      return [ replica_url(name, config, entries, urls), false ] if truthy?(config["replica"])
+
+      adapter = config["adapter"].to_s
+      if FILE_ADAPTERS.include?(adapter)
+        [ sqlite_url(name), false ]
+      elsif SERVER_ADAPTERS.include?(adapter)
+        [ "#{adapter}:///#{database_name(name, config)}", true ]
+      else
+        what = adapter.empty? || adapter == ERB_OUTPUT ? "its adapter is unknown" : "adapter #{adapter} is not one it knows"
+        note("#{name}: #{what}; no sandbox database set")
+        Rails.logger.info("[ActionAgent] sandbox #{@session_id}: #{CONFIG_PATH} #{name}: #{what}; its database is left as configured")
+        nil
+      end
+    end
+
+    # Hostnames can differ between a writer and its read replica. Match the
+    # adapter and literal database name, but refuse ambiguous or ERB-derived
+    # identities instead of silently reading another database.
+    def replica_url(name, config, entries, urls)
+      database = config["database"].to_s
+      matches = if database.present? && !database.include?(ERB_OUTPUT)
+        entries.select do |_candidate, entry|
+          !truthy?(entry["replica"]) && entry["adapter"] == config["adapter"] && entry["database"] == database
+        end
+      else
+        []
+      end
+      url = urls[matches.first.first] if matches.one?
+      return url if url.present?
+
+      raise ArgumentError, "#{CONFIG_PATH}: cannot identify a unique sandbox database for replica #{name}; " \
+        "set #{database_variable(name)} in .activeagents/sandbox.yml"
+    end
+
+    def database_variable(name)
+      name == "primary" ? "DATABASE_URL" : "#{name.upcase}_DATABASE_URL"
+    end
+
+    def truthy?(value)
+      value == true || value.to_s == "true"
+    end
+
+    # Inside the workspace, so it goes when the workspace does.
+    def sqlite_url(name)
+      FileUtils.mkdir_p(@workspace.join("db"), mode: 0o700)
+      file = @workspace.join("db", name == "primary" ? "#{rails_env}.sqlite3" : "#{rails_env}_#{name}.sqlite3")
+      "sqlite3:#{URI::RFC2396_Parser.new.escape(file.to_s)}"
+    end
+
+    # <database>_sandbox_<first 8 of the session id>: recognizably the
+    # app's, and one per sandbox.
+    def database_name(name, config)
+      base = config["database"].to_s
+      unless IDENTIFIER.match?(base)
+        app = @fallback_name.to_s.gsub(/[^A-Za-z0-9_]/, "_").presence || "app"
+        base = [ app, rails_env, (name unless name == "primary") ].compact.join("_")
+      end
+      suffix = "_sandbox_#{@session_id.delete("-").downcase.first(8)}"
+      "#{base.first(MAX_DATABASE_NAME - suffix.length)}#{suffix}"
+    end
+
+    def note(line)
+      @notes << line
+      nil
+    end
+  end
+end

data/app/services/action_agent/mcp_client.rb

@@ -17,9 +17,12 @@ module ActionAgent
 
     class Error < StandardError; end
 
-    def initialize(url:, label: nil)
+    # +headers+ are sent with every request: a checkout sandbox's runtime
+    # authenticates its MCP facade with a bearer token.
+    def initialize(url:, label: nil, headers: {})
       @uri = URI(url)
       @label = label.presence || @uri.host
+      @headers = headers.to_h
       @mutex = Mutex.new
     end
 
@@ -113,6 +116,7 @@ module ActionAgent
       request["Content-Type"] = "application/json"
       request["Accept"] = "application/json, text/event-stream"
       request["Mcp-Session-Id"] = session if session
+      @headers.each { |name, value| request[name.to_s] = value }
       request.body = payload.to_json
 
       response = http.request(request)

data/app/services/action_agent/mcp_tool_dispatcher.rb

@@ -4,23 +4,53 @@ module ActionAgent
   # Routes a tool call to the MCP server that serves it.
   #
   # An agent names the servers it uses in +mcp_servers+, and a catalog entry
-  # carries the url to reach one over HTTP. A tool the agent's servers claim is
-  # called there; anything else returns nil, and the caller falls back to the
-  # engine's own AgentToolbox.
+  # carries the url to reach one over HTTP. A tool the agent's servers claim,
+  # and that the agent's entry for that server does not switch off, is called
+  # there; anything else returns nil, and the caller falls back to the engine's
+  # own AgentToolbox.
   #
   # Only HTTP transports are dispatchable. A stdio server runs as a child
   # process of whatever launched it, so the dashboard has no address to call —
   # those stay listable and attributable without being callable.
+  #
+  # A single run can also reach a checkout sandbox's app runtime the agent
+  # does not name (+extra_server_keys+, "sandbox:<session_id>"): evaluating
+  # an agent against a checkout someone is experimenting in, without saving
+  # that sandbox on the agent. Such a key is treated as if the agent had it
+  # enabled, and resolves exactly as a saved one does: through
+  # SandboxSession.runtime_server_entry, among the agent's owner's sessions,
+  # and only while it is live. Only runtime keys are taken; a catalog server
+  # the agent does not enable stays out of reach.
   class MCPToolDispatcher
     HTTP_TRANSPORTS = %w[http streamable_http sse].freeze
+    class SandboxUnavailable < MCPClient::Error; end
+
+    attr_reader :extra_server_keys
+
+    # A runtime explicitly selected for this run must not silently disappear
+    # between enqueue, discovery and a tool call.
+    def ensure_extra_servers_live!
+      extra_server_keys.each do |key|
+        sandbox = SandboxSession.for_owner(agent.try(:owner)).find_by(session_id: key.delete_prefix(SandboxSession::RUNTIME_SERVER_PREFIX))
+        next if sandbox && (sandbox.ready? || sandbox.running?) && sandbox.runtime_server_entry
+
+        raise SandboxUnavailable, "Sandbox #{key.delete_prefix(SandboxSession::RUNTIME_SERVER_PREFIX)} is no longer running; " \
+          "start it again, or run without it"
+      end
+    end
 
-    def initialize(agent)
+    def initialize(agent, extra_server_keys: [])
       @agent = agent
       @resolver = EvaluationToolResolver.new(agent)
+      @extra_server_keys = Array(extra_server_keys).map { |key| key.to_s.strip }
+        .select { |key| SandboxSession.runtime_server_key?(key) }.uniq
       @clients = {}
+      @listed_by = {}
     end
 
-    # Whether this tool belongs to one of the agent's own reachable servers.
+    # Whether this tool belongs to one of the agent's own reachable servers —
+    # by its name, or because one of them listed it in the last
+    # +tool_definitions+.
     def dispatchable?(tool_name)
       endpoint_for(tool_name).present?
     end
@@ -28,8 +58,8 @@ module ActionAgent
     # Whether the agent names any server the dashboard can call. An agent with
     # none has nothing to execute beyond the engine's own toolbox.
     def any_reachable_server?
-      resolver.declared_server_keys.any? do |key|
-        entry = MCPCatalog.find(key)
+      server_keys.any? do |key|
+        entry = catalog_entry(key)
         entry && entry[:transport].to_s.in?(HTTP_TRANSPORTS) && entry[:url].present?
       end
     end
@@ -41,6 +71,7 @@ module ActionAgent
     #
     # @return [Hash, nil] nil when no configured server claims the tool
     def call(tool_name, arguments = {})
+      ensure_extra_servers_live!
       endpoint = endpoint_for(tool_name)
       return nil unless endpoint
 
@@ -63,16 +94,37 @@ module ActionAgent
     # from a server that legitimately serves no tools — and an agent offered no
     # tools answers from the model alone, which reads as a confident, fabricated
     # result rather than a transport failure (#425).
+    #
+    # A server entry that carries an allow-list ({key, tools: [...]}, which the
+    # Tools tab saves when tools are switched off) contributes only the tools
+    # it names: a tool switched off is not offered.
+    #
+    # A sandbox explicitly selected for a run takes precedence for duplicate
+    # names and must answer discovery; its failure aborts the run.
+    #
+    # Each tool offered is also remembered against the server that listed it,
+    # which is how a call finds its way back (see endpoint_for).
     def tool_definitions
+      ensure_extra_servers_live!
       @discovery_errors = {}
+      @listed_by = {}
 
-      resolver.declared_server_keys.flat_map do |key|
-        entry = MCPCatalog.find(key)
+      server_keys.flat_map do |key|
+        entry = catalog_entry(key)
         next [] unless entry && entry[:transport].to_s.in?(HTTP_TRANSPORTS) && entry[:url].present?
 
         begin
-          client_for(entry).list_tools
+          client_for(entry).list_tools.select do |tool|
+            name = (tool[:name] || tool["name"]).to_s
+            next false if name.blank? || listed_by.key?(name) || !allowed?(key, name)
+
+            @listed_by[name] = key
+            true
+          end
         rescue MCPClient::Error => e
+          if extra_server_keys.include?(key)
+            raise SandboxUnavailable, "Cannot load tools from selected sandbox #{key.delete_prefix(SandboxSession::RUNTIME_SERVER_PREFIX)}: #{e.message}"
+          end
           Rails.logger.warn("[MCPToolDispatcher] #{key} tools/list failed: #{e.message}")
           @discovery_errors[key] =
             "Cannot load tools from MCP server '#{key}' (#{entry[:url]}): #{e.message}. " \
@@ -95,8 +147,8 @@ module ActionAgent
     # execution that follows cannot produce a meaningful result, so a caller
     # can fail loudly instead of scoring an answer the model invented.
     def all_servers_failed?
-      keys = resolver.declared_server_keys.select do |key|
-        entry = MCPCatalog.find(key)
+      keys = server_keys.select do |key|
+        entry = catalog_entry(key)
         entry && entry[:transport].to_s.in?(HTTP_TRANSPORTS) && entry[:url].present?
       end
 
@@ -105,28 +157,96 @@ module ActionAgent
 
     private
 
-    attr_reader :agent, :resolver
+    attr_reader :agent, :resolver, :listed_by
+
+    # The selected checkout replaces matching tools from the agent's normal
+    # servers. Discovery and dispatch must agree on that precedence.
+    def server_keys
+      declared = resolver.declared_server_keys
+      (extra_server_keys + declared).uniq { |key| normalize(key) }
+    end
+
+    # Whether the agent enabled +key+, or this run was given it.
+    def enabled?(key)
+      resolver.status_for(key) == EvaluationToolResolver::ENABLED ||
+        extra_server_keys.any? { |extra| normalize(extra) == normalize(key) }
+    end
+
+    def normalize(key)
+      key.to_s.strip.downcase
+    end
 
     # The catalog entry for the server that serves this tool, but only when the
     # agent configured that server and the entry carries an http url. Scoping to
     # the agent's own servers is what keeps one agent's tools from reaching
     # another's.
+    #
+    # The resolver names a server from the tool's own name: a namespace, a
+    # catalog hint, or an allow-list the agent's entry carries. A bare name
+    # from a server entry that lists no tools — a checkout runtime enabled as
+    # "sandbox:<id>", or {key, name} as the Tools tab saves it — gives it
+    # nothing to go on, and the tool the model was just offered would fall
+    # through to the toolbox. Prefer the server that listed the tool in
+    # tool_definitions: it is one the agent can reach, and it is where the
+    # schema the model called came from. Resolver hints are the fallback
+    # when no discovered schema names a server.
+    #
+    # Either way the server's allow-list has the last word. A tool the agent's
+    # entry leaves out goes to the toolbox, where the call fails, rather than
+    # to a server the user switched it off on — whether the catalog hints it
+    # there or the server lists it.
     def endpoint_for(tool_name)
-      key = resolver.server_key_for(tool_name)
+      name = tool_name.to_s.strip
+
+      [ listed_by[name], resolver.server_key_for(name) ].each do |key|
+        entry = reachable_entry(key)
+        return entry if entry && allowed?(key, name)
+      end
+
+      nil
+    end
+
+    # Whether the agent's entry for +key+ lets this tool through: it names no
+    # allow-list, or its allow-list holds the tool, under its bare name or as
+    # called (+mcp__<server>__<tool>+).
+    def allowed?(key, tool_name)
+      allowed = resolver.allowed_tools_for(key)
+      return true if allowed.nil?
+
+      allowed.include?(tool_name) || allowed.include?(ActiveAgent::Telemetry::ToolOrigin.classify(tool_name)[:tool])
+    end
+
+    # The entry for +key+ when the agent enabled that server and it has an
+    # http url to call; nil otherwise.
+    def reachable_entry(key)
       return nil if key.blank?
-      return nil unless resolver.status_for(key) == EvaluationToolResolver::ENABLED
+      return nil unless enabled?(key)
 
-      entry = MCPCatalog.find(key)
+      entry = catalog_entry(key)
       return nil unless entry && entry[:transport].to_s.in?(HTTP_TRANSPORTS)
       return nil if entry[:url].blank?
 
       entry
     end
 
+    # A catalog server, or the app runtime of a checkout sandbox the agent's
+    # owner started (keys "sandbox:<session_id>"). The sandbox lookup is scoped
+    # to the agent's owner, so naming another tenant's session resolves to
+    # nothing.
+    def catalog_entry(key)
+      return MCPCatalog.find(key) unless SandboxSession.runtime_server_key?(key)
+
+      SandboxSession.runtime_server_entry(key, owner: agent.try(:owner))
+    end
+
     # One client per server for the life of this dispatcher, so a run's tool
     # calls share the MCP session the first call opens.
     def client_for(entry)
-      @clients[entry[:key]] ||= MCPClient.new(url: absolute_url(entry[:url]), label: entry[:name] || entry[:key])
+      @clients[entry[:key]] ||= MCPClient.new(
+        url: absolute_url(entry[:url]),
+        label: entry[:name] || entry[:key],
+        headers: entry[:headers] || {}
+      )
     end
 
     # A host registers its own servers with a path ("/mcp/diagnostic"), since it

data/app/services/action_agent/mock_sandbox_backend.rb

@@ -29,6 +29,18 @@ module ActionAgent
         hourly_cost: tier.hourly_cost.to_f,
         created_at: Time.current
       }
+
+      # A checkout sandbox: record what would be cloned (never the token) and
+      # which credentials would be passed in, and
+      # report the runtime's MCP endpoint the way a real backend does. Nothing
+      # answers there — this backend runs nothing.
+      if (checkout = session.try(:checkout_spec))
+        @sandboxes[name][:checkout] = checkout.except(:token)
+        # Which variables would be set, never their values.
+        @sandboxes[name][:environment_keys] = session.runtime_environment.keys
+        @sandboxes[name][:mcp_url] = "http://127.0.0.1:8080/activeagents/mcp"
+      end
+
       @sandboxes[name]
     end
 
@@ -48,5 +60,32 @@ module ActionAgent
     def cleanup_expired
       0
     end
+
+    # A Claude Code session that runs nothing, reported the way a real one
+    # streams it (stream-json: init, the assistant's text, the result), so
+    # the dashboard's session flow can be exercised end to end without the
+    # CLI or a checkout.
+    def run_code_session(_sandbox_session, _code_session, &on_event)
+      note = "The mock sandbox backend runs nothing: no Claude Code session ran and nothing in the checkout changed."
+
+      [
+        { "type" => "system", "subtype" => "init", "model" => "mock" },
+        {
+          "type" => "assistant",
+          "message" => { "role" => "assistant", "content" => [ { "type" => "text", "text" => note } ] }
+        },
+        {
+          "type" => "result", "subtype" => "success", "is_error" => false, "result" => note,
+          "num_turns" => 1, "duration_ms" => 0, "total_cost_usd" => 0
+        }
+      ].each { |event| on_event&.call(event) }
+
+      { exit_status: 0, diff: "", stderr_tail: "" }
+    end
+
+    # Nothing runs, so there is nothing to stop.
+    def cancel_code_session(_sandbox_session, _code_session)
+      true
+    end
   end
 end

data/app/services/action_agent/ollama_host_probe.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "net/http"
+
+module ActionAgent
+  # Checks that an Ollama (or any OpenAI-compatible) endpoint is reachable and
+  # lists the models it serves. Used by Settings -> Provider API Keys ("Test
+  # connection") and by the agent builder's live model catalog.
+  #
+  # The host is the OpenAI-compatible base URL (".../v1"); the probe calls
+  # GET {host}/models. An optional API key is sent as a Bearer token for
+  # remote servers behind an authenticating proxy or Ollama Cloud.
+  class OllamaHostProbe
+    TIMEOUT_SECONDS = 4
+
+    Result = Struct.new(:ok, :host, :models, :latency_ms, :error, keyword_init: true) do
+      def to_h
+        { ok: ok, host: host, models: models, latency_ms: latency_ms, error: error }
+      end
+    end
+
+    def self.call(host:, api_key: nil)
+      new(host: host, api_key: api_key).call
+    end
+
+    def initialize(host:, api_key: nil)
+      @host = ProviderKey.normalize_host(host)
+      @api_key = api_key.presence
+    end
+
+    def call
+      return failure("No host configured") if @host.blank?
+
+      uri = URI.join("#{@host.chomp('/')}/", "models")
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      response = Net::HTTP.start(
+        uri.host, uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: TIMEOUT_SECONDS,
+        read_timeout: TIMEOUT_SECONDS
+      ) { |http| http.get(uri.request_uri, headers) }
+      latency_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+
+      status = response.code.to_i
+      unless status == 200
+        hint = " — check the API key" if [ 401, 403 ].include?(status)
+        return failure("#{uri} responded #{status}#{hint}", latency_ms)
+      end
+
+      data = JSON.parse(response.body)
+      models = Array(data["data"]).filter_map { |model| model["id"] }.sort
+      Result.new(ok: true, host: @host, models: models, latency_ms: latency_ms, error: nil)
+    rescue JSON::ParserError
+      failure("#{@host} did not return JSON — is this the OpenAI-compatible /v1 endpoint?")
+    rescue URI::InvalidURIError, ArgumentError
+      failure("#{@host} is not a valid URL")
+    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH, SocketError => e
+      failure("Could not connect to #{@host} (#{e.class.name.demodulize}) — is the server running and reachable from this machine?")
+    rescue Net::OpenTimeout, Net::ReadTimeout
+      failure("Timed out after #{TIMEOUT_SECONDS}s connecting to #{@host}")
+    rescue StandardError => e
+      failure("#{e.class}: #{e.message}")
+    end
+
+    private
+
+    def headers
+      @api_key ? { "Authorization" => "Bearer #{@api_key}" } : {}
+    end
+
+    def failure(message, latency_ms = nil)
+      Result.new(ok: false, host: @host, models: [], latency_ms: latency_ms, error: message)
+    end
+  end
+end

data/app/services/action_agent/payload_bounds.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Used to cap the size of JSON-like data handed to an MCP client, whose
+  # context window pays for every character. Each cut leaves a marker saying
+  # what was dropped, so a reader never mistakes a truncated value for the
+  # whole one.
+  module PayloadBounds
+    module_function
+
+    # Returns a copy of +value+ with every string cut to +max_string+
+    # characters and every array to +max_items+ entries, at any depth. A cut
+    # string ends in `…[truncated: N more characters]`; a cut array ends in
+    # the string `[truncated: N more items]`. Other values come back as they
+    # are.
+    #
+    #   bound({ "output" => "x" * 5 }, max_string: 3)
+    #   # => { "output" => "xxx…[truncated: 2 more characters]" }
+    def bound(value, max_string: 2_000, max_items: 50)
+      case value
+      when String then truncate_string(value, max_string)
+      when Hash then value.to_h { |key, item| [ key, bound(item, max_string: max_string, max_items: max_items) ] }
+      when Array
+        kept = value.first(max_items).map { |item| bound(item, max_string: max_string, max_items: max_items) }
+        value.size > max_items ? kept << "[truncated: #{value.size - max_items} more items]" : kept
+      else value
+      end
+    end
+
+    def truncate_string(value, max)
+      return value if value.length <= max
+
+      "#{value[0, max]}…[truncated: #{value.length - max} more characters]"
+    end
+  end
+end