ruby_llm-ag_ui 0.1.0

data/lib/ruby_llm/ag_ui/emitter.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module AgUI
+    # Writes one run's events and keeps its durable record in step.
+    #
+    # The mapper decides which events a RubyLLM signal becomes; the emitter is
+    # what makes them durable and ordered. Every event advances the run record's
+    # sequence, so a reconnect can order snapshots by it instead of by wall
+    # clock, and a terminal outcome is persisted *before* it is written: if the
+    # transport dies after the outcome is decided, the run still cannot be
+    # executed a second time.
+    #
+    # The emitter decides nothing about the outcome and executes nothing. What it
+    # owns is the one ordering rule a caller should never have to remember: a
+    # run's open text, tool calls and step are closed before the terminal event.
+    class Emitter
+      # The run record, including the sequence numbers written so far.
+      attr_reader :record
+
+      # rubocop:disable-next Metrics/ParameterLists -- one keyword per collaborator the caller injects
+      def initialize(writer:, mapper:, store:, record:, clock:, logger: nil)
+        @writer = writer
+        @mapper = mapper
+        @store = store
+        @record = record
+        @clock = clock
+        @logger = logger
+      end
+
+      # Moves the run to started, records +state+ as the host-owned state a
+      # reconnect serves, then opens the run on the wire with +event+.
+      def start(event, state: nil)
+        @record = persist(@record.start(now: now, snapshot: state))
+        write(event)
+        @record
+      end
+
+      # Writes +events+ (one event or an array) and advances the run's sequence
+      # by one per event.
+      def write(events)
+        Array(events).each do |event|
+          emit(event)
+          @record = @record.advance(now: now)
+        end
+      end
+
+      # Writes a reconnect's events without advancing or persisting the record.
+      # The run already ended; a reconnect reports it rather than changing it.
+      def replay(events)
+        Array(events).each { |event| emit(event) }
+        @record
+      end
+
+      # Closes the run as succeeded.
+      def succeed
+        @record = persist(@record.finish(RunRecord::SUCCEEDED, now: now))
+        close(run_finished(Protocol.success_outcome))
+        @record
+      end
+
+      # Closes a run that was stopped before it completed. Never reported as a
+      # success: the outcome carries the protocol's own "cancelled"
+      # discriminator, which 0.2.0 cannot express.
+      def cancel
+        @record = persist(@record.finish(RunRecord::CANCELLED, now: now))
+        close(run_finished(Protocol.cancelled_outcome))
+        @record
+      end
+
+      # Closes the run as paused, recording +interrupts+ so a later resume can
+      # answer them by id. At least one must be unresolved, which RunRecord
+      # enforces.
+      def interrupt(interrupts)
+        @record = persist(@record.interrupted(interrupts, now: now))
+        close(run_finished(Protocol.interrupt_outcome(interrupts)))
+        @record
+      end
+
+      # Closes the run as failed with a sanitized RUN_ERROR.
+      #
+      # The record is persisted first, so a run that failed is not retried
+      # because reporting the failure failed too. The exception's own message is
+      # never sent: it may carry prompts, keys or paths.
+      def fail(error)
+        message, code = ErrorSanitizer.sanitize(error)
+        failure = { 'message' => message, 'code' => code }
+        @logger&.warn("[ruby_llm_ag_ui] run #{@record.run_id} failed: #{error.class}")
+        @record = persist(@record.finish(RunRecord::FAILED, now: now, failure: failure))
+        close(::AgUiProtocol::Core::Events::RunErrorEvent.new(message: message, code: code))
+        @record
+      end
+
+      private
+
+      def emit(event)
+        @writer.write(event)
+      end
+
+      # Closes whatever content is still open, then writes the terminal event.
+      def close(terminal_event)
+        write(@mapper.close)
+        write(terminal_event)
+      end
+
+      def run_finished(outcome)
+        Protocol.run_finished(thread_id: @record.thread_id, run_id: @record.run_id, outcome: outcome)
+      end
+
+      def persist(record)
+        @store.save(record)
+      end
+
+      def now
+        @clock.call
+      end
+    end
+  end
+end

data/lib/ruby_llm/ag_ui/error.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module AgUI
+    # Base class for every error this gem raises. Rescue it to catch any
+    # AG-UI mapping failure without catching unrelated RubyLLM or host errors.
+    class Error < StandardError; end
+
+    # Raised when an inbound request cannot be accepted. The message is always
+    # safe to send to a client: it never contains raw request bytes.
+    class InputError < Error
+      # The HTTP status the host should use for this rejection, when it can.
+      def http_status
+        400
+      end
+    end
+
+    # Raised when inbound JSON is not valid JSON, or not an object.
+    class MalformedInputError < InputError; end
+
+    # Raised when inbound JSON exceeds the configured size or member bounds.
+    class InputTooLargeError < InputError
+      def http_status
+        413
+      end
+    end
+
+    # Raised when inbound JSON is well formed but violates the AG-UI 1.0
+    # RunAgentInput schema.
+    class InvalidInputError < InputError; end
+
+    # Raised when the same (scope, threadId, runId) is reserved twice with
+    # different input. A duplicate with an identical input attaches instead.
+    class RunConflictError < InputError
+      def http_status
+        409
+      end
+    end
+
+    # Raised when run identity is required but missing.
+    class InvalidRunIdentityError < InvalidInputError; end
+
+    # Raised when a resume entry does not match a live interrupt of the most
+    # recent interrupted run on the thread, or was already redeemed. Fails
+    # closed: nothing is executed and no decision is recorded.
+    class ResumeRejectedError < InputError
+      def http_status
+        409
+      end
+    end
+
+    # Raised when the host did not supply something a run needs (a chat, a run
+    # store, an actor scope) or supplied something malformed.
+    class ConfigurationError < Error; end
+
+    # Raised when the pinned protocol version is not the one this gem speaks.
+    class UnsupportedProtocolVersionError < InputError; end
+
+    # Raised when the stream cannot be closed in order (for example the
+    # transport died mid-run). The run is reported as RUN_ERROR.
+    class StreamError < Error; end
+
+    # Raised when RubyLLM paused the run for something the pinned AG-UI shape
+    # cannot express as an interrupt this producer may answer, such as an MCP
+    # input request or a long-running MCP task. Reported as a sanitized
+    # RUN_ERROR rather than a success or a bare interrupt.
+    class UnsupportedRunStateError < Error; end
+  end
+end

data/lib/ruby_llm/ag_ui/error_sanitizer.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module AgUI
+    # Turns an exception into a safe (message, code) pair for RUN_ERROR.
+    #
+    # Upstream Rails examples put `e.message` straight into RUN_ERROR, which
+    # can leak prompts, request bodies, API keys and internal paths. This
+    # module never does that: it classifies the error by class and returns a
+    # fixed, public message. The raw exception goes to the host logger, if the
+    # host configured one, and nowhere else.
+    module ErrorSanitizer
+      # Ordered by specificity. The first ancestor of the error whose name is a
+      # key wins, so subclass relationships are respected without loading
+      # optional error classes eagerly.
+      MESSAGES = {
+        'RubyLLM::UnauthorizedError' => ['The model provider rejected the request.', 'provider_unauthorized'],
+        'RubyLLM::ForbiddenError' => ['The model provider refused the request.', 'provider_forbidden'],
+        'RubyLLM::PaymentRequiredError' => ['The model provider account needs attention.', 'provider_payment_required'],
+        'RubyLLM::RateLimitError' => ['The model provider rate limit was reached.', 'provider_rate_limited'],
+        'RubyLLM::ContextLengthExceededError' => [
+          'The conversation exceeded the model context window.', 'context_length_exceeded'
+        ],
+        'RubyLLM::ContentFilterError' => ['The model provider filtered the response.', 'content_filtered'],
+        'RubyLLM::OverloadedError' => ['The model provider is temporarily unavailable.', 'provider_unavailable'],
+        'RubyLLM::ServiceUnavailableError' => [
+          'The model provider is temporarily unavailable.', 'provider_unavailable'
+        ],
+        'RubyLLM::ServerError' => ['The model provider is temporarily unavailable.', 'provider_unavailable'],
+        'RubyLLM::BadRequestError' => ['The model provider rejected the request shape.', 'provider_bad_request'],
+        'RubyLLM::InvalidToolChoiceError' => ['The requested tool choice is not available.', 'invalid_tool_choice'],
+        'RubyLLM::ToolCallParseError' => ['The model produced an unparseable tool call.', 'tool_call_parse_error'],
+        'RubyLLM::UnsupportedAttachmentError' => ['An attachment could not be sent.', 'unsupported_attachment'],
+        'RubyLLM::ModelNotFoundError' => ['The model is not available.', 'model_not_found'],
+        'RubyLLM::AgUI::UnsupportedRunStateError' => [
+          'The run paused for input this producer cannot express.', 'unsupported_run_state'
+        ],
+        'RubyLLM::AgUI::ResumeRejectedError' => [
+          'The resume request could not be accepted.', 'resume_rejected'
+        ],
+        'RubyLLM::AgUI::StreamError' => ['The run could not be streamed to completion.', 'stream_failed'],
+        'RubyLLM::Error' => ['The model provider returned an error.', 'provider_error'],
+        'Faraday::Error' => ['The model provider request failed.', 'transport_error'],
+        'Timeout::Error' => ['The model provider request timed out.', 'transport_timeout'],
+        'Errno::ETIMEDOUT' => ['The model provider request timed out.', 'transport_timeout']
+      }.freeze
+
+      FALLBACK = ['The run failed before it could finish.', 'internal_error'].freeze
+
+      module_function
+
+      # Returns a [message, code] pair safe to put on the wire.
+      def sanitize(error)
+        match = classify(error)
+        match || FALLBACK
+      end
+
+      # Returns the [message, code] pair for +error+, falling back to FALLBACK.
+      def classify(error)
+        names = error.class.ancestors.map(&:name).compact
+        names.each do |name|
+          entry = MESSAGES[name]
+          return entry if entry
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/ruby_llm/ag_ui/input.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module AgUI
+    # A validated AG-UI 1.0 RunAgentInput.
+    #
+    # The community Ruby SDK models RunAgentInput but has no JSON to model
+    # parser, so hosts parse and authorize the body by hand. This class does
+    # that once: it bounds the body size, decodes it, strips members the pinned
+    # schema does not define, validates the shapes the schema requires, and
+    # hands the run typed values and a stable digest for run identity.
+    #
+    #   input = RubyLLM::AgUI::Input.parse(request_body, max_bytes: 256_000)
+    #   input.thread_id   # => "thread-1"
+    #   input.resume      # => [#<RubyLLM::AgUI::ResumeEntry ...>]
+    #   input.digest      # => "9f2c..."
+    #
+    # Nothing here grants trust. Client messages, state, tools, context and
+    # forwardedProps are accepted as data only; the host decides which tools
+    # and model a run may use, and client history is reconciled by id against
+    # host-stored history rather than appended as trusted system or tool turns.
+    class Input
+      # The protocol versions this gem can act on.
+      SUPPORTED_PROTOCOL_VERSIONS = [Protocol::PROTOCOL_VERSION].freeze
+
+      # Members the pinned RunAgentInput schema defines. Anything else is not
+      # part of the contract and is stripped (or rejected with strict: true).
+      TOP_LEVEL_KEYS = %w[
+        threadId runId protocolVersion parentRunId state messages tools context forwardedProps resume
+      ].freeze
+
+      # The conversation this run belongs to.
+      attr_reader :thread_id
+
+      # Identifies this run.
+      attr_reader :run_id
+
+      # The run that spawned this one, when the client sets one.
+      attr_reader :parent_run_id
+
+      # The AG-UI protocol version the client declared, or nil when absent.
+      attr_reader :protocol_version
+
+      # The state the run starts from.
+      attr_reader :state
+
+      # The parsed conversation, as AgUiProtocol::Core::Types message models.
+      attr_reader :messages
+
+      # The client-supplied tool definitions, as frozen hashes. Never used to
+      # authorize a host tool.
+      attr_reader :tools
+
+      # The client-supplied context entries, as frozen hashes.
+      attr_reader :context
+
+      # Application-specific values passed through untouched.
+      attr_reader :forwarded_props
+
+      # The resume entries answering a previous run's interrupts.
+      attr_reader :resume
+
+      # The canonical digest of the accepted input, for run identity.
+      attr_reader :digest
+
+      # Non-fatal observations made while parsing (unknown members stripped).
+      attr_reader :warnings
+
+      def self.parse(raw, max_bytes: nil, strict: false, logger: nil)
+        Parser.new(raw, max_bytes: max_bytes, strict: strict, logger: logger).parse
+      end
+
+      def initialize(attributes)
+        @thread_id = attributes[:thread_id]
+        @run_id = attributes[:run_id]
+        @parent_run_id = attributes[:parent_run_id]
+        @protocol_version = attributes[:protocol_version]
+        @state = attributes[:state]
+        @messages = attributes[:messages]
+        @tools = attributes[:tools]
+        @context = attributes[:context]
+        @forwarded_props = attributes[:forwarded_props]
+        @resume = attributes[:resume]
+        @digest = attributes[:digest]
+        @normalized = attributes[:normalized]
+        @warnings = attributes[:warnings]
+        freeze
+      end
+
+      # The accepted input as a plain hash with camelCase keys and the members
+      # the schema defines. Suitable for echoing as RUN_STARTED.input.
+      def to_h
+        @normalized
+      end
+
+      # The names of the client-supplied tools. Informational only.
+      def tool_names
+        @tools.filter_map { |tool| tool['name'] }
+      end
+
+      # Whether the client supplied tool definitions. The first release never
+      # grants them; a run reports them and stops.
+      def client_tools?
+        !@tools.empty?
+      end
+
+      # Whether this run answers a previous run's interrupts.
+      def resume?
+        !@resume.empty?
+      end
+
+      # The resume entry for +interrupt_id+, or nil.
+      def resume_entry(interrupt_id)
+        @resume.find { |entry| entry.interrupt_id == interrupt_id }
+      end
+
+      # Decodes and validates one request body.
+      #
+      # Kept separate from Input so the value object stays immutable and every
+      # failure message stays in one place.
+      class Parser
+        include Validation
+
+        MAX_NESTING = 32
+
+        def initialize(raw, max_bytes:, strict:, logger:)
+          @raw = raw
+          @max_bytes = max_bytes || RubyLLM::AgUI.config.max_input_bytes
+          @strict = strict
+          @logger = logger || RubyLLM::AgUI.config.logger
+          @warnings = []
+          @parts = PartBuilder.new
+        end
+
+        def parse
+          document = strip_unknown_members(decode(read_body))
+          validate_common(document)
+          build(document)
+        end
+
+        private
+
+        def read_body
+          case @raw
+          when String
+            bounded!(@raw.bytesize)
+            @raw
+          when Hash
+            bounded!(Canonical.dump(@raw).bytesize)
+            @raw
+          when nil then raise MalformedInputError, 'The request body is empty.'
+          else read_stream
+          end
+        end
+
+        def read_stream
+          unless @raw.respond_to?(:read)
+            raise MalformedInputError, 'The request body must be a JSON object or a readable stream.'
+          end
+
+          body = @raw.read(@max_bytes + 1) || ''
+          bounded!(body.bytesize)
+          body
+        end
+
+        def bounded!(bytes)
+          return if bytes <= @max_bytes
+
+          raise InputTooLargeError, "The request body exceeds the #{@max_bytes} byte limit."
+        end
+
+        def decode(body)
+          source = body.is_a?(String) ? body : Canonical.dump(body)
+          parsed = JSON.parse(source, max_nesting: MAX_NESTING)
+          raise MalformedInputError, 'The request body must be a JSON object.' unless parsed.is_a?(Hash)
+
+          parsed
+        rescue JSON::ParserError
+          raise MalformedInputError, 'The request body is not valid JSON.'
+        end
+
+        def strip_unknown_members(document)
+          unknown = document.keys - TOP_LEVEL_KEYS
+          reject_unknown!(unknown) if @strict && !unknown.empty?
+          unknown.sort.each { |key| warn_unknown(key) }
+          document.slice(*TOP_LEVEL_KEYS)
+        end
+
+        def reject_unknown!(unknown)
+          raise InvalidInputError, "Unknown RunAgentInput members: #{unknown.sort.join(', ')}."
+        end
+
+        def warn_unknown(key)
+          @warnings << "stripped unknown RunAgentInput member #{key.inspect}"
+          @logger&.warn("[ruby_llm_ag_ui] stripped unknown RunAgentInput member #{key.inspect}")
+        end
+
+        def validate_common(document)
+          document['threadId'] = identifier!(document['threadId'], 'threadId')
+          document['runId'] = identifier!(document['runId'], 'runId')
+          document['parentRunId'] = identifier!(document['parentRunId'], 'parentRunId') if document.key?('parentRunId')
+          validate_protocol_version(document['protocolVersion'])
+          document['messages'] = array!(document['messages'], 'messages', required: true)
+          validate_messages_count(document['messages'])
+          document['tools'] = array!(document['tools'], 'tools', max: RubyLLM::AgUI.config.max_tools)
+          document['context'] = array!(document['context'], 'context', max: RubyLLM::AgUI.config.max_context)
+          document['resume'] = array!(document['resume'], 'resume')
+          document['state'] ||= {}
+          document['forwardedProps'] ||= {}
+        end
+
+        def validate_protocol_version(value)
+          return if value.nil?
+          return if value.is_a?(String) && SUPPORTED_PROTOCOL_VERSIONS.include?(value)
+
+          raise UnsupportedProtocolVersionError,
+                "Unsupported protocolVersion #{value.inspect}. " \
+                "This producer speaks #{SUPPORTED_PROTOCOL_VERSIONS.join(', ')}."
+        end
+
+        def validate_messages_count(messages)
+          max = RubyLLM::AgUI.config.max_messages
+          return if messages.size <= max
+
+          raise InputTooLargeError, "messages exceeds the #{max} message limit."
+        end
+
+        def build(document)
+          Input.new(
+            thread_id: document['threadId'],
+            run_id: document['runId'],
+            parent_run_id: document['parentRunId'],
+            protocol_version: document['protocolVersion'],
+            state: document['state'],
+            messages: MessageParser.new(logger: @logger).parse(document['messages']),
+            tools: @parts.tools(document['tools']),
+            context: @parts.context(document['context']),
+            forwarded_props: document['forwardedProps'],
+            resume: @parts.resume(document['resume']),
+            digest: Canonical.digest(document),
+            normalized: Canonical.sort(document),
+            warnings: @warnings.dup.freeze
+          )
+        end
+      end
+
+      # Builds the composite members of a RunAgentInput: the client tool
+      # definitions, the context entries and the resume entries.
+      class PartBuilder
+        include Validation
+
+        def tools(values)
+          values.map { |value| build_tool(value) }.freeze
+        end
+
+        def context(values)
+          values.map { |value| build_context(value) }.freeze
+        end
+
+        def resume(values)
+          values.map { |value| build_resume(value) }.freeze
+        end
+
+        private
+
+        def build_tool(value)
+          hash = object!(value, 'tools[]')
+          {
+            'name' => identifier!(hash['name'], 'tools[].name'),
+            'description' => optional_string(hash['description'], 'tools[].description'),
+            'parameters' => hash['parameters']
+          }.freeze
+        end
+
+        def build_context(value)
+          hash = object!(value, 'context[]')
+          {
+            'description' => string!(hash['description'], 'context[].description'),
+            'value' => string!(hash['value'], 'context[].value')
+          }.freeze
+        end
+
+        def build_resume(value)
+          hash = object!(value, 'resume[]')
+          status = string!(hash['status'], 'resume[].status', max: 32)
+          unless ResumeEntry::STATUSES.include?(status)
+            raise InvalidInputError, "resume[].status must be one of #{ResumeEntry::STATUSES.join(', ')}."
+          end
+
+          ResumeEntry.new(
+            interrupt_id: identifier!(hash['interruptId'], 'resume[].interruptId'),
+            status: status,
+            payload: hash['payload']
+          )
+        end
+      end
+    end
+  end
+end