ruby_llm-ag_ui 0.1.0

data/lib/ruby_llm/ag_ui/interrupt.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module AgUI
+    # One approval request attached to a reserved run, and the answer to it.
+    #
+    # A RubyLLM `requires_approval` pause becomes one interrupt per pending tool
+    # call. The interrupt is the only thing that ties a client resume entry to a
+    # tool call, and it is deliberately narrow:
+    #
+    # * it names the exact `toolCallId` and the digest of the arguments RubyLLM
+    #   asked to run, so a resume that tries to change the arguments cannot pass
+    #   as the same request;
+    # * it carries a host-owned expiry, so an old approval does not stay valid
+    #   forever;
+    # * it records exactly one decision, so a replayed resume entry gets the
+    #   stored decision back instead of running the tool a second time.
+    #
+    # An interrupt is not a permission grant. The host re-authorizes the actor
+    # before the tool runs, whatever this record says.
+    class Interrupt
+      # No decision yet.
+      PENDING = :pending
+      # The actor approved the tool call.
+      APPROVED = :approved
+      # The actor declined the tool call.
+      DENIED = :denied
+      # The actor abandoned the interrupt.
+      CANCELLED = :cancelled
+
+      STATUSES = [PENDING, APPROVED, DENIED, CANCELLED].freeze
+
+      # The statuses that count as an answer.
+      DECISIONS = [APPROVED, DENIED, CANCELLED].freeze
+
+      # The protocol's reason for a tool approval.
+      REASON_TOOL_CALL = 'tool_call_confirmation'
+
+      # An id unique among the interrupts of one thread. A resume entry answers
+      # an interrupt by this id, so it must be unguessable enough that a client
+      # cannot answer someone else's approval.
+      attr_reader :id
+
+      # The RubyLLM tool call this interrupt concerns.
+      attr_reader :tool_call_id
+
+      # Why the run stopped. An open protocol string.
+      attr_reader :reason
+
+      # A human-readable prompt for whoever answers.
+      attr_reader :message
+
+      # The SHA-256 digest of the arguments RubyLLM asked to run. Compared
+      # before execution so changed arguments cannot reuse an approval.
+      attr_reader :arguments_digest
+
+      # When the interrupt stops being answerable.
+      attr_reader :expires_at
+
+      # :pending, :approved, :denied or :cancelled.
+      attr_reader :status
+
+      # When the decision was recorded, or nil while pending.
+      attr_reader :decided_at
+
+      # When the interrupt was created.
+      attr_reader :created_at
+
+      # rubocop:disable Metrics/ParameterLists -- one keyword per field the value object owns
+      def initialize(id:, tool_call_id:, arguments_digest:, expires_at:, reason: REASON_TOOL_CALL,
+                     message: nil, status: PENDING, decided_at: nil, created_at: nil)
+        @id = id
+        @tool_call_id = tool_call_id
+        @arguments_digest = arguments_digest
+        @expires_at = expires_at
+        @reason = reason
+        @message = message
+        @status = assert_status!(status)
+        @decided_at = decided_at
+        @created_at = created_at
+        freeze
+      end
+
+      # Builds an interrupt with an unguessable id.
+      def self.create(tool_call_id:, arguments_digest:, expires_at:, reason: REASON_TOOL_CALL, message: nil,
+                      created_at: nil)
+        new(
+          id: SecureRandom.uuid, tool_call_id: tool_call_id, arguments_digest: arguments_digest,
+          expires_at: expires_at, reason: reason, message: message, created_at: created_at
+        )
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      # Whether the interrupt still waits for an answer.
+      def pending?
+        status == PENDING
+      end
+
+      # Whether a decision has been recorded.
+      def decided?
+        DECISIONS.include?(status)
+      end
+
+      # Whether the actor approved the call.
+      def approved?
+        status == APPROVED
+      end
+
+      # Whether the actor declined the call.
+      def denied?
+        status == DENIED
+      end
+
+      # Whether the actor abandoned the interrupt.
+      def cancelled?
+        status == CANCELLED
+      end
+
+      # Whether the host-owned expiry has passed at +now+.
+      def expired?(now)
+        !expires_at.nil? && now >= expires_at
+      end
+
+      # Whether the interrupt can still be answered at +now+.
+      def answerable?(now)
+        pending? && !expired?(now)
+      end
+
+      # Returns a copy carrying +decision+. Refuses to overwrite an existing
+      # decision: a second answer is a replay or a conflict, never a new grant.
+      def decide(decision, now:)
+        raise ConfigurationError, "decision must be one of #{DECISIONS.join(', ')}" unless DECISIONS.include?(decision)
+        raise StreamError, "interrupt #{id} was already #{status}" if decided?
+
+        self.class.new(
+          id: id, tool_call_id: tool_call_id, arguments_digest: arguments_digest, expires_at: expires_at,
+          reason: reason, message: message, status: decision, decided_at: now, created_at: created_at
+        )
+      end
+
+      # The protocol's Interrupt shape, ready for a RUN_FINISHED interrupt
+      # outcome. Only the fields the pinned schema defines are set.
+      def to_protocol
+        ::AgUiProtocol::Core::Types::Interrupt.new(
+          id: id,
+          reason: reason,
+          message: message,
+          tool_call_id: tool_call_id,
+          expires_at: expires_at&.utc&.iso8601
+        )
+      end
+
+      # The interrupt as plain data, with camelCase keys. The arguments digest
+      # and the caller-supplied ids stay out of it: they are host bookkeeping.
+      def to_h
+        {
+          'id' => id,
+          'toolCallId' => tool_call_id,
+          'reason' => reason,
+          'message' => message,
+          'expiresAt' => iso8601(expires_at),
+          'status' => status.to_s,
+          'decidedAt' => iso8601(decided_at)
+        }
+      end
+
+      # The interrupt in the form a durable store keeps, which #to_h is not: a
+      # store that dropped the arguments digest could not re-verify that a
+      # resume answers the call it approved, and one that dropped the creation
+      # time could not order two interrupts on a thread.
+      def to_storage
+        to_h.merge(
+          'argumentsDigest' => arguments_digest,
+          'createdAt' => iso8601(created_at)
+        )
+      end
+
+      # Rebuilds an interrupt stored by #to_storage.
+      def self.from_storage(hash)
+        new(
+          id: hash.fetch('id'), tool_call_id: hash.fetch('toolCallId'),
+          arguments_digest: hash.fetch('argumentsDigest'), reason: hash.fetch('reason'),
+          message: hash['message'], expires_at: parse_time(hash['expiresAt']),
+          status: hash.fetch('status').to_sym, decided_at: parse_time(hash['decidedAt']),
+          created_at: parse_time(hash['createdAt'])
+        )
+      end
+
+      # The time +value+ names, or nil. Storage writes ISO 8601 strings.
+      def self.parse_time(value)
+        value.nil? ? nil : Time.iso8601(value)
+      end
+
+      private
+
+      def iso8601(time)
+        time&.utc&.iso8601
+      end
+
+      def assert_status!(value)
+        return value if STATUSES.include?(value)
+
+        raise ConfigurationError, "status must be one of #{STATUSES.join(', ')}"
+      end
+    end
+  end
+end

data/lib/ruby_llm/ag_ui/mapper.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module AgUI
+    # Projects one RubyLLM 2.x chat turn onto AG-UI 1.0 events (FR-03).
+    #
+    # The mapper is the only place that decides which AG-UI event a RubyLLM
+    # signal becomes. It is a state machine rather than a set of converters,
+    # because the protocol's rules are about state: a text message must be open
+    # before its content arrives, a tool call must be closed before its result,
+    # consecutive steps must not overlap, and everything must be closed before
+    # the run's terminal event.
+    #
+    # It maps what RubyLLM actually reported and nothing else. It never invents
+    # an event to fill a gap in its own output, and it never re-synthesises tool
+    # arguments that RubyLLM delivered as a stream: the deltas go out as
+    # received, in order.
+    #
+    # Every method returns the events to write, in order. The mapper writes
+    # nothing itself, so the caller owns the transport and can advance the run
+    # record's sequence with the same list.
+    #
+    #   mapper = RubyLLM::AgUI::Mapper.new(thread_id: "t1", run_id: "r1")
+    #
+    #   chat.before_tool_call { |tool_call| write(mapper.before_tool_call(tool_call)) }
+    #   chat.after_message    { |message|   write(mapper.message(message)) }
+    #   chat.complete         { |chunk|     write(mapper.chunk(chunk)) }
+    #
+    #   write(mapper.close)  # before the run's terminal event
+    class Mapper
+      # The two phases a step delimits: one model round-trip that produces text
+      # and/or tool calls, and the tool round that answers those calls. A step
+      # ends as soon as a phase of the other kind begins, so consecutive steps
+      # never overlap.
+      STEP_COMPLETION = :completion
+      STEP_TOOL = :tool
+
+      # The AG-UI conversation this run belongs to.
+      attr_reader :thread_id
+
+      # Identifies this run. Every id the mapper mints is scoped to it, so two
+      # runs on one thread never collide.
+      attr_reader :run_id
+
+      def initialize(thread_id:, run_id:, redact: nil, logger: nil)
+        @thread_id = thread_id
+        @run_id = run_id
+        @redact = redact || RubyLLM::AgUI.config.redact
+        @logger = logger || RubyLLM::AgUI.config.logger
+        @message_count = 0
+        @step_count = 0
+        @open_text_id = nil
+        @last_message_id = nil
+        @text_emitted = false
+        @calls = {}
+        @open_step = nil
+        @step_kind = nil
+        @warned_redaction = false
+        @closed = false
+      end
+
+      # One streamed Chunk from Chat#complete.
+      def chunk(chunk)
+        return [] if @closed
+
+        events = text_events(chunk.content)
+        events.concat(tool_call_events(chunk.tool_calls, streamed: true))
+        events.concat(close_events) if chunk.finish_reason
+        events
+      end
+
+      # One Message appended to the conversation, from Chat#after_message.
+      #
+      # An assistant message ends the completion, so whatever the stream did not
+      # carry is emitted here: a provider that did not stream, or a tool call it
+      # reported only in the final message, still produces a valid AG-UI
+      # sequence instead of a run that silently says nothing.
+      def message(message)
+        return [] if @closed
+        return tool_result_events(message) if message.role == :tool
+
+        assistant_events(message)
+      end
+
+      # A local ToolCall about to execute, from Chat#before_tool_call.
+      #
+      # Its arguments are complete, and its deltas have already gone out if the
+      # provider streamed them, so this only opens a call the stream never
+      # reported and closes the call so the client knows the arguments ended.
+      def before_tool_call(tool_call)
+        return [] if @closed
+
+        events = tool_call_events({ tool_call.id => tool_call }, streamed: false)
+        events.concat(close_tool_calls)
+        events
+      end
+
+      # Closes any open text message, tool call and step, and closes the mapper.
+      #
+      # The caller writes these before the terminal event: AG-UI has no way to
+      # close a run whose content is still open, and a client that never sees
+      # TEXT_MESSAGE_END waits for a message that will not grow.
+      #
+      # Closing is final, and it is the reason a second turn on the same chat is
+      # safe. RubyLLM's callbacks are additive: the callbacks this run registered
+      # stay attached after the run ends, so the next `complete` on that chat
+      # fires this mapper again. A closed mapper maps nothing — the content it
+      # would open belongs to a run that is already over, and writing it would
+      # report the previous run's ids and steps inside the next run's stream.
+      def close
+        @closed = true
+        close_events
+      end
+
+      private
+
+      # --- text ---------------------------------------------------------------
+
+      def text_events(content)
+        return [] if content.nil? || content.empty?
+
+        events = open_text_events
+        events << ::AgUiProtocol::Core::Events::TextMessageContentEvent.new(
+          message_id: @open_text_id, delta: content
+        )
+        @text_emitted = true
+        events
+      end
+
+      def open_text_events
+        return [] if @open_text_id
+
+        @open_text_id = new_message_id('a')
+        @last_message_id = @open_text_id
+        events = ensure_step(STEP_COMPLETION)
+        events << ::AgUiProtocol::Core::Events::TextMessageStartEvent.new(
+          message_id: @open_text_id, role: 'assistant'
+        )
+        events
+      end
+
+      def close_text_events
+        return [] unless @open_text_id
+
+        message_id = @open_text_id
+        @open_text_id = nil
+        [::AgUiProtocol::Core::Events::TextMessageEndEvent.new(message_id: message_id)]
+      end
+
+      # --- assistant message ---------------------------------------------------
+
+      def assistant_events(message)
+        events = []
+        events.concat(text_events(message.content)) unless @text_emitted
+        events.concat(close_text_events)
+        events.concat(tool_call_events(message.tool_calls, streamed: false))
+        events.concat(close_tool_calls)
+        events.concat(close_step)
+        @last_message_id = nil
+        @text_emitted = false
+        events
+      end
+
+      # --- tool calls ----------------------------------------------------------
+
+      def tool_call_events(tool_calls, streamed:)
+        return [] if tool_calls.nil? || tool_calls.empty?
+
+        tool_calls.flat_map do |key, tool_call|
+          record = track(key, tool_call, streamed: streamed)
+          open_tool_call(record) + argument_events(record, tool_call, streamed: streamed)
+        end
+      end
+
+      # The record for one tool call, created on first sight.
+      #
+      # A streamed delta is keyed by index and carries the id only on its first
+      # fragment; the complete message is keyed by id. Both keys point at the
+      # same record, so the call is opened once.
+      def track(key, tool_call, streamed:)
+        record = @calls[key] || find_call(tool_call.id) || new_call
+        record[:id] ||= tool_call.id
+        record[:name] ||= tool_call.name
+        record[:streamed] ||= streamed
+        @calls[key] = record
+        @calls[record[:id]] = record if record[:id]
+        record
+      end
+
+      def new_call
+        { id: nil, name: nil, streamed: false, args_emitted: false, started: false, closed: false, buffered: nil }
+      end
+
+      def find_call(id)
+        id && @calls[id]
+      end
+
+      # Opens the call the first time its id and name are both known. A call
+      # reported as arguments-only deltas stays buffered until its name arrives,
+      # so no fragment of the provider's argument bytes is dropped.
+      def open_tool_call(record)
+        return [] if record[:started] || record[:id].nil? || record[:name].nil?
+
+        record[:started] = true
+        events = close_text_events
+        events.concat(ensure_step(STEP_COMPLETION))
+        events << ::AgUiProtocol::Core::Events::ToolCallStartEvent.new(
+          tool_call_id: record[:id], tool_call_name: record[:name], parent_message_id: @last_message_id
+        )
+        events.concat(buffered_argument_events(record))
+      end
+
+      def buffered_argument_events(record)
+        buffered = record[:buffered]
+        record[:buffered] = nil
+        return [] if buffered.nil? || buffered.empty?
+
+        [::AgUiProtocol::Core::Events::ToolCallArgsEvent.new(tool_call_id: record[:id], delta: buffered)]
+      end
+
+      def argument_events(record, tool_call, streamed:)
+        delta = argument_delta(record, tool_call, streamed: streamed)
+        return [] if delta.nil? || delta.empty?
+        return buffer_argument(record, delta) unless record[:started]
+
+        [::AgUiProtocol::Core::Events::ToolCallArgsEvent.new(tool_call_id: record[:id], delta: delta)]
+      end
+
+      def buffer_argument(record, delta)
+        record[:buffered] = (record[:buffered] || +'') + delta
+        []
+      end
+
+      # A streamed chunk carries a fragment of the provider's own argument bytes
+      # and goes out unchanged. A complete message carries the Hash RubyLLM
+      # reconstructed from those bytes, so it is serialized once and only when
+      # the stream did not already deliver the fragments.
+      def argument_delta(record, tool_call, streamed:)
+        return streamed_delta(tool_call) if streamed
+        return nil if record[:streamed] || record[:args_emitted]
+
+        record[:args_emitted] = true
+        arguments = tool_call.arguments
+        arguments.is_a?(String) ? arguments : Canonical.dump(arguments)
+      end
+
+      def streamed_delta(tool_call)
+        arguments = tool_call.arguments
+        arguments.is_a?(String) ? arguments : arguments.to_s
+      end
+
+      def close_tool_calls
+        @calls.values.uniq.filter_map do |record|
+          next if record[:closed] || !record[:started]
+
+          record[:closed] = true
+          ::AgUiProtocol::Core::Events::ToolCallEndEvent.new(tool_call_id: record[:id])
+        end
+      end
+
+      # --- tool results --------------------------------------------------------
+
+      def tool_result_events(message)
+        events = close_text_events
+        events.concat(close_tool_calls)
+        events.concat(ensure_step(STEP_TOOL))
+        events << ::AgUiProtocol::Core::Events::ToolCallResultEvent.new(
+          message_id: "#{@run_id}:tool:#{message.tool_call_id}",
+          tool_call_id: message.tool_call_id,
+          content: redact(Redaction::TOOL_RESULT, message.content.to_s),
+          role: 'tool'
+        )
+        @text_emitted = false
+        events
+      end
+
+      # --- steps ---------------------------------------------------------------
+
+      # Ensures the step for +kind+ is the open one, closing the previous step
+      # first when the phase changed. Opening a step of the same kind is a no-op,
+      # so the deltas of one completion stay inside a single step.
+      def ensure_step(kind)
+        return [] if @open_step && @step_kind == kind
+
+        events = close_step
+        @step_count += 1
+        @open_step = "step-#{@step_count}"
+        @step_kind = kind
+        events << ::AgUiProtocol::Core::Events::StepStartedEvent.new(step_name: @open_step)
+        events
+      end
+
+      def close_step
+        return [] unless @open_step
+
+        step_name = @open_step
+        @open_step = nil
+        @step_kind = nil
+        [::AgUiProtocol::Core::Events::StepFinishedEvent.new(step_name: step_name)]
+      end
+
+      # --- closing -------------------------------------------------------------
+
+      def close_events
+        events = close_text_events
+        events.concat(close_tool_calls)
+        events.concat(close_step)
+        events
+      end
+
+      # --- redaction -----------------------------------------------------------
+
+      def redact(kind, payload)
+        warn_about_redaction
+        Redaction.apply(@redact, kind, payload)
+      end
+
+      def warn_about_redaction
+        return unless @redact == Redaction.method(:default)
+        return if @warned_redaction
+
+        @warned_redaction = true
+        @logger&.warn('[ruby_llm_ag_ui] tool results are redacted by default; ' \
+                      'configure RubyLLM::AgUI.config.redact to publish them')
+      end
+
+      def new_message_id(suffix)
+        @message_count += 1
+        "#{@run_id}:#{suffix}#{@message_count}"
+      end
+    end
+  end
+end

data/lib/ruby_llm/ag_ui/message_parser.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module AgUI
+    # Parses the RunAgentInput messages array into typed protocol message
+    # models.
+    #
+    # Hosts must reconcile client history by id against their own store; the
+    # gem never trusts a client message as a system instruction or a tool
+    # result. This parser only guarantees the shapes the pinned schema defines,
+    # so a mismatch is a clear InputError instead of a downstream surprise.
+    class MessageParser
+      include Validation
+
+      # The roles the pinned schema defines.
+      ROLES = %w[developer system assistant user tool activity reasoning].freeze
+
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM::AgUI.config.logger
+      end
+
+      # Returns an array of AgUiProtocol::Core::Types message models.
+      def parse(messages)
+        messages.each_with_index.map { |message, index| build(message, index) }.freeze
+      end
+
+      private
+
+      def build(value, index)
+        hash = object!(value, "messages[#{index}]")
+        id = identifier!(hash['id'], "messages[#{index}].id")
+        role = string!(hash['role'], "messages[#{index}].role", max: 32)
+        unless ROLES.include?(role)
+          raise InvalidInputError, "messages[#{index}].role #{role.inspect} is not a known role."
+        end
+
+        send(:"build_#{role}", hash, index, id)
+      rescue ArgumentError, KeyError, TypeError
+        raise InvalidInputError, "messages[#{index}] is not a valid #{role} message."
+      end
+
+      def build_developer(hash, index, id)
+        types = ::AgUiProtocol::Core::Types
+        types::DeveloperMessage.new(
+          id: id,
+          content: string!(hash['content'], "messages[#{index}].content"),
+          name: optional_string(hash['name'], "messages[#{index}].name")
+        )
+      end
+
+      def build_system(hash, index, id)
+        types = ::AgUiProtocol::Core::Types
+        types::SystemMessage.new(
+          id: id,
+          content: string!(hash['content'], "messages[#{index}].content"),
+          name: optional_string(hash['name'], "messages[#{index}].name")
+        )
+      end
+
+      def build_user(hash, index, id)
+        content = hash['content']
+        unless content.is_a?(String) || content.is_a?(Array)
+          raise InvalidInputError, "messages[#{index}].content must be text or an array of parts."
+        end
+
+        string!(content, "messages[#{index}].content") if content.is_a?(String)
+        ::AgUiProtocol::Core::Types::UserMessage.new(
+          id: id, content: content, name: optional_string(hash['name'], "messages[#{index}].name")
+        )
+      end
+
+      def build_assistant(hash, index, id)
+        content = hash['content']
+        string!(content, "messages[#{index}].content") unless content.nil?
+        ::AgUiProtocol::Core::Types::AssistantMessage.new(
+          id: id,
+          content: content,
+          tool_calls: tool_calls(hash['toolCalls'], index),
+          name: optional_string(hash['name'], "messages[#{index}].name")
+        )
+      end
+
+      def build_tool(hash, index, id)
+        ::AgUiProtocol::Core::Types::ToolMessage.new(
+          id: id,
+          content: tool_content(hash['content'], index),
+          tool_call_id: identifier!(hash['toolCallId'], "messages[#{index}].toolCallId"),
+          error: optional_string(hash['error'], "messages[#{index}].error")
+        )
+      end
+
+      def build_activity(hash, index, id)
+        activity_type = string!(hash['activityType'], "messages[#{index}].activityType", max: MAX_ID_LENGTH)
+        content = object!(hash['content'], "messages[#{index}].content")
+        ::AgUiProtocol::Core::Types::ActivityMessage.new(
+          id: id, activity_type: activity_type, content: content
+        )
+      end
+
+      def build_reasoning(hash, index, id)
+        ::AgUiProtocol::Core::Types::ReasoningMessage.new(
+          id: id, content: string!(hash['content'], "messages[#{index}].content")
+        )
+      end
+
+      def tool_calls(value, index)
+        return nil if value.nil?
+
+        array!(value, "messages[#{index}].toolCalls").map do |call|
+          object!(call, "messages[#{index}].toolCalls[]")
+        end
+      end
+
+      # The schema allows a tool result to be text or an ordered list of parts.
+      # ToolMessage models text only, so a structured result is serialized to
+      # JSON text, which is how the schema says structured data travels.
+      def tool_content(value, index)
+        raise InvalidInputError, "messages[#{index}].content is required." if value.nil?
+
+        return value if value.is_a?(String)
+
+        array!(value, "messages[#{index}].content")
+        Canonical.dump(value)
+      end
+    end
+  end
+end