little_ghost 0.1.0 → 0.2.0

data/lib/little_ghost/providers/configuration.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  module Providers
+    # Holds trusted provider connection settings independently from model
+    # profiles. Connection names and option keys are normalized to strings, and
+    # the resulting mapping is immutable.
+    class Configuration
+      # Normalized provider connections keyed by application-defined name.
+      attr_reader :connections
+
+      # Copies and freezes +connections+ so callers may safely reuse their input.
+      def initialize(connections = {})
+        unless connections.is_a?(Hash)
+          raise ConfigurationError, "providers must be a mapping"
+        end
+
+        @connections = normalize(connections).freeze
+        validate!
+        freeze
+      end
+
+      # Returns credentials merged into +configuration+ when +provider+ is
+      # constructed with +adapter+. Subclasses may resolve secrets lazily here.
+      # The base implementation adds no credentials.
+      def credentials(provider:, adapter:, configuration:)
+        {}
+      end
+
+      private
+
+      def normalize(connections)
+        connections.to_h do |name, options|
+          unless options.is_a?(Hash)
+            raise ConfigurationError, "providers.#{name} must be a mapping"
+          end
+
+          normalized = options.to_h { |key, value| [key.to_s, deep_copy(value)] }
+          normalized["adapter"] = normalized["adapter"].to_s if normalized.key?("adapter")
+          [name.to_s, deep_freeze(normalized)]
+        end
+      end
+
+      def deep_copy(value)
+        case value
+        when Hash
+          value.to_h { |key, child| [key.to_s, deep_copy(child)] }
+        when Array
+          value.map { |child| deep_copy(child) }
+        when String
+          value.dup
+        else
+          value
+        end
+      end
+
+      def deep_freeze(value)
+        case value
+        when Hash
+          value.each_value { |child| deep_freeze(child) }
+        when Array
+          value.each { |child| deep_freeze(child) }
+        when String
+          value.freeze
+        end
+        value.freeze if value.is_a?(Hash) || value.is_a?(Array)
+        value
+      end
+
+      def validate!
+        connections.each do |name, options|
+          if options["adapter"].to_s.empty?
+            raise ConfigurationError, "providers.#{name}.adapter is required"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/little_ghost/providers/gemini/catalog_source.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  module Providers
+    class Gemini < Base
+      # Enriches Gemini availability and limits from the Developer API.
+      class CatalogSource < Models::Catalog::Source
+        URL = URI("https://generativelanguage.googleapis.com/v1beta/models") # :nodoc:
+
+        # Creates a source for the named provider connection.
+        def initialize(provider:, credential_resolver:)
+          super(name: "gemini")
+          @provider = provider
+          @credential_resolver = credential_resolver
+        end
+
+        def refresh(target: nil)
+          api_key = @credential_resolver.call.fetch("api_key")
+          values = JSON.parse(
+            Support::HTTPClient.new(open_timeout: 5, read_timeout: 30, max_response_bytes: 25 * 1024 * 1024)
+              .request(uri: URL, headers: {"x-goog-api-key" => api_key})
+          ).fetch("models")
+          values.select! { |value| value["name"].to_s.delete_prefix("models/") == target.model_id } if target
+          values.to_h do |value|
+            id = value.fetch("name").delete_prefix("models/")
+            ["#{@provider}:#{id}", {available: true, context_window: value["inputTokenLimit"],
+                                    max_output_tokens: value["outputTokenLimit"]}.compact]
+          end
+        rescue JSON::ParserError, KeyError => error
+          raise ProviderError, "Gemini returned an invalid catalog: #{error.message}"
+        end
+      end
+    end
+  end
+end

data/lib/little_ghost/providers/gemini.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "uri"
+require_relative "../support/http_client"
+require_relative "../support/sse_parser"
+require_relative "gemini/catalog_source"
+
+module LittleGhost
+  module Providers
+    # Zero-dependency Gemini generateContent adapter.
+    class Gemini < Base
+      # Request policy supported by Gemini and Vertex AI HTTP clients.
+      def self.request_options = %i[max_response_bytes open_timeout read_timeout].freeze
+
+      DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/" # :nodoc:
+
+      # Provider-owned model identifier.
+      attr_reader :model
+
+      # Creates a Gemini generateContent client for +model+.
+      def initialize(api_key:, model:, base_url: DEFAULT_BASE_URL, open_timeout: 10, read_timeout: 120,
+        max_response_bytes: Support::HTTPClient::DEFAULT_MAX_RESPONSE_BYTES, transport: nil, **)
+        raise CredentialError, "Gemini api_key is required" if api_key.to_s.empty?
+
+        @api_key = api_key
+        @model = model
+        @transport = transport || Support::HTTPClient.new(base_url:, open_timeout:, read_timeout:, max_response_bytes:)
+      end
+
+      def stream(request)
+        return enum_for(__method__, request) unless block_given?
+
+        parser = Support::SSEParser.new
+        normalizer = Normalizer.new(model:)
+        @transport.stream(
+          path: endpoint,
+          headers: request_headers(request),
+          body: JSON.generate(request_body(request)),
+          cancellation_token: request.cancellation_token,
+          deadline: request.deadline
+        ) do |chunk|
+          parser.<<(chunk).each { |data| normalizer.consume(JSON.parse(data)).each { |event| yield event } }
+        end
+        parser.finish.each { |data| normalizer.consume(JSON.parse(data)).each { |event| yield event } }
+        normalizer.finish.each { |event| yield event }
+      rescue JSON::ParserError => error
+        raise ProtocolError, "Google returned invalid JSON: #{error.message}"
+      end
+
+      def capabilities(metadata: {})
+        ModelCapabilities.new(native_structured_output: true, tools: true, tool_choice: true,
+          supported_parameters: metadata[:supported_parameters])
+      end
+
+      protected
+
+      def endpoint
+        "models/#{URI.encode_www_form_component(model)}:streamGenerateContent?alt=sse&key=#{URI.encode_www_form_component(@api_key)}"
+      end
+
+      def request_headers(_request) = {"content-type" => "application/json", "accept" => "text/event-stream"}
+
+      private
+
+      def request_body(request)
+        system, messages = request.messages.partition { |message| message.role == :system }
+        body = {contents: messages.map { |message| google_message(message) }}
+        body[:systemInstruction] = {parts: system.flat_map { |message| message.content.grep(Content::Text).map { |block| {text: block.text} } }} unless system.empty?
+        body[:tools] = [{functionDeclarations: request.tools.map { |tool| google_tool(tool) }}] unless request.tools.empty?
+        body[:toolConfig] = google_tool_choice(request.tool_choice) if request.tool_choice
+        generation = request.settings.to_h.transform_keys { |key| google_setting(key) }
+        if request.output_schema
+          generation[:responseMimeType] = "application/json"
+          generation[:responseJsonSchema] = request.output_schema.fetch(:schema)
+        end
+        body[:generationConfig] = generation unless generation.empty?
+        body
+      end
+
+      def google_setting(key)
+        {max_tokens: :maxOutputTokens, top_p: :topP, top_k: :topK, stop_sequences: :stopSequences}[key.to_sym] || key.to_sym
+      end
+
+      def google_message(message)
+        {role: (message.role == :assistant) ? "model" : "user", parts: message.content.map { |block| google_content(block) }}
+      end
+
+      def google_content(block)
+        case block
+        when Content::Text then {text: block.text}
+        when Content::Image, Content::Document
+          {inlineData: {mimeType: block.media_type, data: Base64.strict_encode64(block.data)}}
+        when Content::ToolUse then {functionCall: {id: block.id, name: block.name, args: block.input}}
+        when Content::ToolResult
+          {functionResponse: {id: block.tool_use_id, name: block.tool_use_id, response: {output: Array(block.content).join("\n")}}}
+        when Content::Reasoning then {text: block.text, thought: true}
+        else raise ConfigurationError, "Unsupported Google content block: #{block.class}"
+        end
+      end
+
+      def google_tool(tool)
+        value = tool.is_a?(Hash) ? tool.transform_keys(&:to_sym) : {name: tool.name, description: tool.description, input_schema: tool.input_schema}
+        {name: value.fetch(:name), description: value[:description], parametersJsonSchema: value[:input_schema] || {}}
+      end
+
+      def google_tool_choice(choice)
+        return {functionCallingConfig: {mode: "ANY"}} if choice == :required
+
+        {functionCallingConfig: {mode: "ANY", allowedFunctionNames: [choice.fetch(:name).to_s]}}
+      end
+
+      class Normalizer # :nodoc:
+        def initialize(model:)
+          @model = model
+          @text = +""
+          @reasoning = +""
+          @tools = []
+          @usage = Usage.new
+          @started = false
+          @terminal = false
+        end
+
+        def consume(event)
+          raise ProviderError, "Google request failed: #{event.dig("error", "message")}" if event["error"]
+
+          events = []
+          unless @started
+            @started = true
+            events << StreamEvent.build(:message_start, id: nil, model: event["modelVersion"] || @model)
+          end
+          candidate = event.fetch("candidates", []).first
+          if candidate
+            candidate.dig("content", "parts")&.each { |part| events.concat(part_events(part)) }
+            if candidate["finishReason"]
+              @stop_reason = normalize_stop(candidate["finishReason"])
+              @terminal = true
+            end
+          end
+          if event["usageMetadata"]
+            @usage = usage(event.fetch("usageMetadata"))
+            events << StreamEvent.build(:usage, usage: @usage)
+          end
+          events
+        end
+
+        def finish
+          raise ProtocolError, "Google stream ended before a finish reason" unless @terminal
+
+          blocks = []
+          blocks << Content::Reasoning.new(text: @reasoning) unless @reasoning.empty?
+          blocks << Content::Text.new(text: @text) unless @text.empty?
+          blocks.concat(@tools)
+          response = ModelResponse.new(message: Message.new(role: :assistant, content: blocks),
+            stop_reason: @stop_reason, usage: @usage, metadata: {model: @model})
+          [StreamEvent.build(:message_stop, response:)]
+        end
+
+        private
+
+        def part_events(part)
+          if part["functionCall"]
+            call = part.fetch("functionCall")
+            index = @tools.length
+            tool = Content::ToolUse.new(id: call["id"] || "call-#{index}", name: call.fetch("name"), input: call["args"] || {})
+            @tools << tool
+            [
+              StreamEvent.build(:tool_call_start, index:, id: tool.id, name: tool.name),
+              StreamEvent.build(:tool_call_stop, index:, tool_use: tool)
+            ]
+          elsif part["text"] && part["thought"]
+            @reasoning << part["text"]
+            [StreamEvent.build(:reasoning_delta, text: part["text"])]
+          elsif part["text"]
+            @text << part["text"]
+            [StreamEvent.build(:text_delta, text: part["text"])]
+          else
+            []
+          end
+        end
+
+        def usage(value)
+          cached = value["cachedContentTokenCount"] || 0
+          reasoning = value["thoughtsTokenCount"] || 0
+          Usage.new(
+            input_tokens: [Integer(value["promptTokenCount"] || 0) - Integer(cached), 0].max,
+            output_tokens: [Integer(value["candidatesTokenCount"] || 0) - Integer(reasoning), 0].max,
+            cache_read_tokens: cached,
+            reasoning_tokens: reasoning
+          )
+        end
+
+        def normalize_stop(value)
+          case value
+          when "MAX_TOKENS" then :max_tokens
+          when "SAFETY", "BLOCKLIST", "PROHIBITED_CONTENT", "SPII" then :content_filter
+          else @tools.empty? ? :end_turn : :tool_use
+          end
+        end
+      end
+    end
+  end
+end

data/lib/little_ghost/providers/open_router/catalog_source.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  module Providers
+    class OpenRouter < OpenAICompatible
+      # Adds richer routing metadata and pricing from OpenRouter's live catalog.
+      class CatalogSource < Models::Catalog::Source
+        URL = URI("https://openrouter.ai/api/v1/models") # :nodoc:
+
+        # Creates a source for the named provider connection.
+        def initialize(provider:, credential_resolver:)
+          super(name: "openrouter")
+          @provider = provider
+          @credential_resolver = credential_resolver
+        end
+
+        def refresh(target: nil)
+          api_key = @credential_resolver.call.fetch("api_key")
+          values = JSON.parse(
+            Support::HTTPClient.new(open_timeout: 5, read_timeout: 30, max_response_bytes: 25 * 1024 * 1024)
+              .request(uri: URL, headers: {"Authorization" => "Bearer #{api_key}"})
+          ).fetch("data")
+          values.select! { |value| value["id"] == target.model_id } if target
+          values.to_h do |value|
+            pricing = value.fetch("pricing", {}).each_with_object({}) do |(key, amount), result|
+              normalized = {"prompt" => :input, "completion" => :output, "input_cache_read" => :cache_read,
+                            "input_cache_write" => :cache_write}[key]
+              result[normalized] = Float(amount) * 1_000_000 if normalized
+            end
+            ["#{@provider}:#{value.fetch("id")}", {
+              context_window: value["context_length"], max_output_tokens: value.dig("top_provider", "max_completion_tokens"),
+              supported_parameters: value["supported_parameters"], input_modalities: value.dig("architecture", "input_modalities"),
+              output_modalities: value.dig("architecture", "output_modalities"), pricing:
+            }.compact]
+          end
+        rescue JSON::ParserError, KeyError, ArgumentError => error
+          raise ProviderError, "OpenRouter returned an invalid catalog: #{error.message}"
+        end
+      end
+    end
+  end
+end

data/lib/little_ghost/providers/open_router.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
 require_relative "openai_compatible"
+require_relative "open_router/catalog_source"
 
 module LittleGhost
   module Providers
     # OpenRouter gives one LittleGhost provider access to models routed through
-    # OpenRouter. Agents keep their model roles while the registry selects an
-    # OpenRouter model for each role.
+    # OpenRouter. Agents may select an OpenRouter target directly or keep a
+    # logical role while shared configuration selects its physical model.
     #
     #   provider = LittleGhost::Providers::OpenRouter.new(
     #     api_key: ENV.fetch("OPENROUTER_API_KEY"),
@@ -19,6 +20,9 @@ module LittleGhost
     # Requests that need a capability ask OpenRouter to route only to providers
     # that advertise it.
     class OpenRouter < OpenAICompatible
+      # Adds OpenRouter attribution to the shared OpenAI-compatible policy.
+      def self.request_options = (super + [:app_name]).freeze
+
       # The OpenRouter API endpoint used when +base_url+ is omitted.
       DEFAULT_BASE_URL = "https://openrouter.ai/api/v1/"
       TOP_LEVEL_CACHE_MODELS = ["anthropic/", "~anthropic/"].freeze # :nodoc:

data/lib/little_ghost/providers/openai_compatible.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 require "json"
-require_relative "sse_parser"
-require_relative "http_transport"
+require_relative "../support/sse_parser"
+require_relative "../support/http_client"
 
 module LittleGhost
   module Providers
@@ -25,7 +25,12 @@ module LittleGhost
     # A +:model_retry+ event reports each retry and whether text had already been
     # emitted. Partial text may repeat after a retry, so consumers that assemble
     # streams must use that event to discard or replace superseded output.
-    class OpenAICompatible
+    class OpenAICompatible < Base
+      # Request policy supported by OpenAI-compatible HTTP clients.
+      def self.request_options
+        %i[max_response_bytes max_retries max_retry_delay open_timeout read_timeout].freeze
+      end
+
       # The OpenAI API endpoint used when +base_url+ is omitted.
       DEFAULT_BASE_URL = "https://api.openai.com/v1/"
       INITIAL_RETRY_DELAY = 1 # :nodoc:
@@ -89,7 +94,7 @@ module LittleGhost
         open_timeout: 10,
         read_timeout: 120,
         allow_insecure_http: false,
-        max_response_bytes: HTTPTransport::DEFAULT_MAX_RESPONSE_BYTES,
+        max_response_bytes: Support::HTTPClient::DEFAULT_MAX_RESPONSE_BYTES,
         max_retries: 2,
         max_retry_delay: MAX_RETRY_DELAY,
         transport: nil,
@@ -104,7 +109,7 @@ module LittleGhost
         @headers = headers.transform_keys(&:to_s).freeze
         @max_retries = Integer(max_retries)
         @max_retry_delay = Integer(max_retry_delay)
-        @transport = transport || HTTPTransport.new(
+        @transport = transport || Support::HTTPClient.new(
           base_url:,
           open_timeout:,
           read_timeout:,
@@ -155,10 +160,10 @@ module LittleGhost
         end
       end
 
-      # Returns the legacy capability contract expected from compatible APIs.
+      # Returns the permissive capability contract expected from compatible APIs.
       # Subclasses can override this when the endpoint advertises precise support.
       def capabilities(metadata: {})
-        ModelCapabilities.legacy
+        ModelCapabilities.permissive
       end
 
       private
@@ -186,14 +191,14 @@ module LittleGhost
 
       def context_window_overflow?(error)
         values = [error.message]
-        values << error.body if error.respond_to?(:body)
+        values << error.body if error.is_a?(HTTPError)
         values << error.error_type << error.code if error.is_a?(StreamError)
         text = values.compact.join(" ").downcase
         CONTEXT_OVERFLOW_MARKERS.any? { |marker| text.include?(marker) }
       end
 
       def stream_once(request)
-        parser = SSEParser.new
+        parser = Support::SSEParser.new
         normalizer = normalizer_for(request)
 
         @transport.stream(
@@ -382,21 +387,12 @@ module LittleGhost
       end
 
       def tool_definition(tool)
-        if tool.is_a?(Hash)
-          definition = tool.transform_keys(&:to_sym)
-          return {
-            name: definition.fetch(:name),
-            description: definition[:description],
-            input_schema: definition[:input_schema] || {},
-            strict: definition[:strict]
-          }
-        end
-
+        definition = tool.to_h.transform_keys(&:to_sym)
         {
-          name: tool.public_send(:name),
-          description: tool.public_send(:description),
-          input_schema: tool.public_send(:input_schema),
-          strict: tool.respond_to?(:strict) ? tool.public_send(:strict) : nil
+          name: definition.fetch(:name),
+          description: definition[:description],
+          input_schema: definition[:input_schema] || {},
+          strict: definition[:strict]
         }
       end
 

data/lib/little_ghost/providers/vertex_ai/credential_resolver.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+require "uri"
+
+module LittleGhost
+  module Providers
+    class VertexAI < Gemini
+      # Resolves Vertex access tokens from explicit values, service-account ADC,
+      # or the Google metadata server.
+      class CredentialResolver
+        TOKEN_URI = URI("https://oauth2.googleapis.com/token") # :nodoc:
+        SCOPE = "https://www.googleapis.com/auth/cloud-platform" # :nodoc:
+
+        # Uses an explicit token or Google application credentials in +environment+.
+        def initialize(environment: ENV, access_token: nil, clock: -> { Time.now.to_i })
+          @environment = environment
+          @access_token = access_token
+          @clock = clock
+          @mutex = Mutex.new
+        end
+
+        # Returns a current access token, refreshing cached credentials as needed.
+        def call(cancellation_token: nil, deadline: nil)
+          return @access_token unless @access_token.to_s.empty?
+
+          @mutex.synchronize do
+            return @cached_token if @cached_token && @expires_at && @expires_at > @clock.call + 60
+
+            file = @environment["GOOGLE_APPLICATION_CREDENTIALS"]
+            token, expires_in = if file
+              service_account_token(file, cancellation_token:, deadline:)
+            else
+              metadata_token(cancellation_token:, deadline:)
+            end
+            @cached_token = token
+            @expires_at = @clock.call + Integer(expires_in || 3600)
+            token
+          end
+        end
+
+        private
+
+        def service_account_token(path, cancellation_token:, deadline:)
+          document = JSON.parse(File.read(path))
+          raise CredentialError, "Google application credentials must be a service_account" unless document["type"] == "service_account"
+
+          now = @clock.call
+          header = urlsafe(JSON.generate(alg: "RS256", typ: "JWT"))
+          claim = urlsafe(JSON.generate(iss: document.fetch("client_email"), scope: SCOPE,
+            aud: document["token_uri"] || TOKEN_URI.to_s, iat: now, exp: now + 3600))
+          signature = OpenSSL::PKey::RSA.new(document.fetch("private_key")).sign(OpenSSL::Digest.new("SHA256"), "#{header}.#{claim}")
+          assertion = "#{header}.#{claim}.#{urlsafe(signature)}"
+          response = http_client.request(uri: URI(document["token_uri"] || TOKEN_URI.to_s), method: :post,
+            headers: {"content-type" => "application/x-www-form-urlencoded"},
+            body: URI.encode_www_form(grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer", assertion:),
+            cancellation_token:, deadline:)
+          token_json(response)
+        rescue Errno::ENOENT, JSON::ParserError, KeyError, OpenSSL::PKey::PKeyError => error
+          raise CredentialError, "Google service-account credentials are invalid: #{error.message}"
+        end
+
+        def metadata_token(cancellation_token:, deadline:)
+          response = http_client.request(
+            uri: URI("http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token"),
+            method: :get,
+            headers: {"Metadata-Flavor" => "Google"}, body: nil, cancellation_token:, deadline:,
+            allow_insecure_http: true
+          )
+          token_json(response)
+        rescue HTTPError
+          raise CredentialError, "No Vertex AI access token, service-account credentials, or metadata credentials were found"
+        end
+
+        def token_json(body)
+          value = JSON.parse(body)
+          [value.fetch("access_token"), value["expires_in"]]
+        rescue JSON::ParserError, KeyError => error
+          raise CredentialError, "Google token endpoint returned an invalid response: #{error.message}"
+        end
+
+        def urlsafe(value) = Base64.urlsafe_encode64(value, padding: false)
+
+        def http_client = Support::HTTPClient.new(open_timeout: 2, read_timeout: 5, max_response_bytes: 1024 * 1024)
+      end
+    end
+  end
+end

data/lib/little_ghost/providers/vertex_ai.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "gemini"
+require_relative "vertex_ai/credential_resolver"
+
+module LittleGhost
+  module Providers
+    # Google Vertex AI variant of the Gemini wire protocol.
+    class VertexAI < Gemini
+      # Creates a Vertex AI client for a Google Cloud +project+ and +location+.
+      def initialize(model:, project:, location: "global", access_token: nil, credential_resolver: nil,
+        base_url: nil, **arguments)
+        @project = project.to_s
+        @location = location.to_s
+        @credential_resolver = credential_resolver || CredentialResolver.new(access_token:)
+        raise ConfigurationError, "Vertex AI project is required" if @project.empty?
+
+        base_url ||= "https://#{@location}-aiplatform.googleapis.com/v1/"
+        super(api_key: "unused", model:, base_url:, **arguments)
+      end
+
+      protected
+
+      def endpoint
+        "projects/#{URI.encode_www_form_component(@project)}/locations/#{URI.encode_www_form_component(@location)}/publishers/google/models/#{URI.encode_www_form_component(model)}:streamGenerateContent?alt=sse"
+      end
+
+      def request_headers(request)
+        super.merge(
+          "authorization" => "Bearer #{@credential_resolver.call(
+            cancellation_token: request.cancellation_token,
+            deadline: request.deadline
+          )}"
+        )
+      end
+    end
+  end
+end

data/lib/little_ghost/run.rb

@@ -12,10 +12,11 @@ module LittleGhost
   #   run.outcome    # => "completed"
   #   run.response   # => "Transfer 481 is waiting for the receiving bank."
   #
-  # Agent.ask[rdoc-ref:LittleGhost::Agent.ask] or standalone
-  # ask[rdoc-ref:LittleGhost::Agent#ask] consumes the event stream and returns
-  # the Run. For a live interface,
-  # stream_ask[rdoc-ref:LittleGhost::Agent#stream_ask] yields StreamEvent objects
+  # The class-level ask helper[rdoc-ref:LittleGhost::Agent.ask] or standalone
+  # ask method[rdoc-ref:LittleGhost::Agent#ask] consumes the event stream and
+  # returns the Run. For a live interface, the class-level streaming
+  # helper[rdoc-ref:LittleGhost::Agent.stream_ask] or standalone streaming
+  # method[rdoc-ref:LittleGhost::Agent#stream_ask] yields StreamEvent objects
   # and returns the same run after enumeration. A run can execute only once.
   #
   # Completion, failure, deadline, and cancellation become the +completed+,
@@ -119,7 +120,7 @@ module LittleGhost
 
         @entrypoint
       end
-      unless entrypoint.respond_to?(:interrupt_response)
+      unless entrypoint.is_a?(Agent)
         raise AgentInterruptError, "Run entrypoint does not support interruptions"
       end
 
@@ -417,7 +418,7 @@ module LittleGhost
     def entrypoint_name
       return entrypoint_class.name.to_s if workflow_run?
 
-      return @entrypoint.entrypoint_name if @entrypoint&.respond_to?(:entrypoint_name)
+      return @entrypoint.entrypoint_name if @entrypoint.is_a?(Agent)
 
       entrypoint_class.agent_id
     end
@@ -563,7 +564,6 @@ module LittleGhost
 
     def diagnostic_invocation_message
       message = invocation.message
-      return message unless message.respond_to?(:text)
       return message.text unless message.text.empty?
 
       {