ruby_llm-ag_ui 0.1.0

data/lib/ruby_llm/ag_ui/redemption.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module AgUI
+    # The result of redeeming an interrupt.
+    #
+    # A caller cannot tell a fresh decision from a replay by the interrupt
+    # alone: both come back approved. The distinction is exactly what decides
+    # whether the tool may run, so the store returns it explicitly. Only the
+    # call that recorded the decision may execute the tool; a replay reports the
+    # answer already given and must not run anything again.
+    class Redemption
+      # The stored interrupt, with its decision.
+      attr_reader :interrupt
+
+      def initialize(interrupt:, replayed:)
+        @interrupt = interrupt
+        @replayed = replayed
+        freeze
+      end
+
+      # Whether this call recorded the decision.
+      def recorded?
+        !@replayed
+      end
+
+      # Whether the decision was already recorded by an earlier call.
+      def replayed?
+        @replayed
+      end
+
+      # The interrupt's status: :approved, :denied or :cancelled.
+      def status
+        interrupt.status
+      end
+
+      # Whether the stored decision is an approval.
+      def approved?
+        interrupt.approved?
+      end
+
+      # Whether the stored decision is a refusal.
+      def denied?
+        interrupt.denied?
+      end
+
+      # Whether the stored decision abandons the interrupt.
+      def cancelled?
+        interrupt.cancelled?
+      end
+
+      # The tool call the decision concerns.
+      def tool_call_id
+        interrupt.tool_call_id
+      end
+
+      def to_h
+        { 'interruptId' => interrupt.id, 'status' => status.to_s, 'replayed' => replayed? }
+      end
+    end
+  end
+end

data/lib/ruby_llm/ag_ui/reservation.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module AgUI
+    # The answer to a run reservation: the record that owns the identity, and
+    # how the reservation was obtained.
+    #
+    # A retried request whose input digest matches an existing reservation gets
+    # ATTACHED, so the host streams or reports the run already in progress
+    # instead of executing it a second time.
+    class Reservation
+      # The identity was free and is now claimed by this call.
+      CREATED = :created
+      # The identity was already claimed by an identical request.
+      ATTACHED = :attached
+
+      # The record that owns the run identity.
+      attr_reader :record
+
+      # :created or :attached.
+      attr_reader :status
+
+      def initialize(record:, status:)
+        @record = record
+        @status = status
+        freeze
+      end
+
+      # Whether this call claimed the identity.
+      def created?
+        status == CREATED
+      end
+
+      # Whether the identity was already claimed by an identical request.
+      def attached?
+        status == ATTACHED
+      end
+
+      def thread_id
+        record.thread_id
+      end
+
+      def run_id
+        record.run_id
+      end
+
+      def digest
+        record.digest
+      end
+
+      def to_h
+        { 'status' => status.to_s, 'threadId' => thread_id, 'runId' => run_id, 'digest' => digest }
+      end
+    end
+  end
+end

data/lib/ruby_llm/ag_ui/resume.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module AgUI
+    # The answers a run's input gives to a previous run's interrupts (FR-06).
+    #
+    # A resume is a request, never a permission grant. Before anything is
+    # written, every entry is checked against the live state: it must name an
+    # interrupt of the *most recent* interrupted run on the same thread, the
+    # tool call it concerns must still be pending on the host's chat, and that
+    # call's arguments must still digest to what the interrupt recorded, so a
+    # resume cannot change what it approves. The decision is then recorded once;
+    # a repeated resume is refused rather than executed again, because the tool
+    # may already have run.
+    #
+    # An approval answers an interrupt. The host still re-authorizes the actor
+    # before the tool executes.
+    class Resume
+      # One entry's effect: the interrupt it answers and the decision to record.
+      Decision = Struct.new(:interrupt, :decision, keyword_init: true)
+
+      def initialize(input:, store:, scope:, chat:)
+        @input = input
+        @store = store
+        @scope = scope
+        @chat = chat
+        @plan = []
+      end
+
+      # Whether the input answers anything at all.
+      def needed?
+        @input.resume?
+      end
+
+      # Checks every entry and builds the plan. Writes nothing, so a rejected
+      # resume is rejected before the run opens a stream.
+      def plan(now:)
+        source = interrupted_run
+        @plan = @input.resume.map { |entry| plan_entry(source, entry, now) }
+        self
+      end
+
+      # Records each planned decision once and tells the chat about it, so the
+      # next completion runs an approved tool or refuses a denied one.
+      def apply(now:)
+        @plan.each { |planned| redeem(planned, now: now) }
+        self
+      end
+
+      private
+
+      # Only the most recent interrupted run on the thread is resumable.
+      # Anything older is stale, and answering it would apply a decision to a
+      # conversation that has already moved on.
+      def interrupted_run
+        record = @store.latest_interrupted(scope: @scope, thread_id: @input.thread_id)
+        raise ResumeRejectedError, "thread #{@input.thread_id} has no interrupted run to resume" if record.nil?
+
+        record
+      end
+
+      def plan_entry(source, entry, now)
+        interrupt = source.interrupt(entry.interrupt_id)
+        raise ResumeRejectedError, "interrupt #{entry.interrupt_id} is not the latest run's" if interrupt.nil?
+        raise ResumeRejectedError, "interrupt #{interrupt.id} has already been answered" unless interrupt.pending?
+        raise ResumeRejectedError, "interrupt #{interrupt.id} has expired" if interrupt.expired?(now)
+
+        ensure_unchanged!(interrupt)
+        Decision.new(interrupt: interrupt, decision: decision_for(entry))
+      end
+
+      # The call an interrupt approves must still be pending on the host's chat
+      # with the same arguments. A resume answers the question that was asked; it
+      # cannot change it.
+      def ensure_unchanged!(interrupt)
+        tool_call = pending_approval(interrupt.tool_call_id)
+        raise ResumeRejectedError, "tool call #{interrupt.tool_call_id} is not pending on this chat" unless tool_call
+
+        return if Canonical.digest(tool_call.arguments) == interrupt.arguments_digest
+
+        raise ResumeRejectedError, "arguments for tool call #{interrupt.tool_call_id} changed since the interrupt"
+      end
+
+      # The store's redemption is atomic: the first answer record wins, and a
+      # repeat comes back as a replay that must not execute anything.
+      def redeem(planned, now:)
+        redemption = @store.redeem_interrupt(
+          scope: @scope, thread_id: @input.thread_id,
+          interrupt_id: planned.interrupt.id, decision: planned.decision, now: now
+        )
+        raise ResumeRejectedError, "interrupt #{planned.interrupt.id} was already answered" if redemption.replayed?
+
+        redemption.approved? ? @chat.approve(redemption.tool_call_id) : @chat.deny(redemption.tool_call_id)
+      end
+
+      # The protocol's resume vocabulary is resolved or cancelled; the interrupt
+      # records the truthful decision, and a cancelled answer denies the call
+      # rather than approving it.
+      def decision_for(entry)
+        entry.resolved? ? Interrupt::APPROVED : Interrupt::CANCELLED
+      end
+
+      def pending_approval(tool_call_id)
+        @chat.pending_approvals.find { |tool_call| tool_call.id == tool_call_id }
+      end
+    end
+  end
+end

data/lib/ruby_llm/ag_ui/resume_entry.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module AgUI
+    # One answer to one interrupt, as the client sends it on the run that
+    # continues from an interrupted one.
+    #
+    # A resume entry is a request, never a permission grant: the run still
+    # checks that the interrupt exists, belongs to the most recent interrupted
+    # run on this thread, has not been redeemed, and has not expired, and the
+    # host still re-authorizes before any tool runs.
+    class ResumeEntry
+      # The protocol's two statuses.
+      RESOLVED = 'resolved'
+      CANCELLED = 'cancelled'
+      STATUSES = [RESOLVED, CANCELLED].freeze
+
+      # Identifies the interrupt this entry answers.
+      attr_reader :interrupt_id
+
+      # "resolved" or "cancelled".
+      attr_reader :status
+
+      # The answer the client supplies, for an interrupt that asked for one.
+      attr_reader :payload
+
+      def initialize(interrupt_id:, status:, payload: nil)
+        @interrupt_id = interrupt_id
+        @status = status
+        @payload = payload
+        freeze
+      end
+
+      # Whether the client answered the interrupt.
+      def resolved?
+        status == RESOLVED
+      end
+
+      # Whether the client abandoned the interrupt.
+      def cancelled?
+        status == CANCELLED
+      end
+
+      def to_h
+        { 'interruptId' => interrupt_id, 'status' => status, 'payload' => payload }
+      end
+    end
+  end
+end

data/lib/ruby_llm/ag_ui/run.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module AgUI
+    # Runs one RubyLLM 2.x chat turn as one AG-UI 1.0 run.
+    #
+    #   input = RubyLLM::AgUI::Input.parse(request_body)
+    #   chat  = host_chat_for(actor, input.thread_id)   # host-owned RubyLLM::Chat
+    #   RubyLLM::AgUI::Run.new(chat:, input:, scope: "tenant:#{actor.id}").stream(to: response.stream)
+    #
+    # The host owns authentication, authorization, the chat, the tools a run may
+    # use and the transport. This class owns the run's identity (reserved before
+    # any provider work), the ordering of the events, and the outcome: a
+    # cancelled run is never reported as success, a provider failure is a
+    # sanitized RUN_ERROR, a paused run is an interrupt rather than a success,
+    # and an identity that is already reserved is never executed a second time.
+    #
+    # +scope+ is the host's tenant/actor boundary, built from authenticated
+    # identity. The gem takes it from the host rather than deriving it from the
+    # input, because a scope derived from anything the client sent would let one
+    # client attach to another's run.
+    class Run
+      # The run's authoritative record, once it has been reserved.
+      attr_reader :record
+
+      # rubocop:disable-next Metrics/ParameterLists -- one keyword per host-supplied or overridable value
+      def initialize(chat:, input:, scope:, store: nil, logger: nil, redact: nil, clock: nil, expires_in: nil,
+                     state: nil)
+        @chat = chat
+        @input = input
+        @scope = scope
+        @store = store || RubyLLM::AgUI.config.run_store!
+        @logger = logger || RubyLLM::AgUI.config.logger
+        @redact = redact
+        @clock = clock || RubyLLM::AgUI.config.clock
+        @expires_in = expires_in || RubyLLM::AgUI.config.interrupt_ttl
+        @mutex = Mutex.new
+        validate!
+        @state = state.nil? ? @input.state : state
+      end
+
+      # Reserves the run and streams it to +to+, an IO-like stream. Returns the
+      # run's record, which carries the status the run ended with.
+      #
+      # The reservation happens before any provider work: a request whose input
+      # digest matches an identity already reserved attaches instead of
+      # executing, and a changed input under the same key is refused by the
+      # store. A reserved run that already ended is served as a reconnect — its
+      # outcome and state snapshot — never as a second execution.
+      def stream(to:)
+        resume.plan(now: @clock.call) if resume.needed?
+        reservation = reserve
+        return execute(reservation.record, to) if reservation.created?
+
+        reconnect(reservation.record, to)
+      end
+
+      private
+
+      def resume
+        @resume ||= Resume.new(input: @input, store: @store, scope: @scope, chat: @chat)
+      end
+
+      def reserve
+        @store.reserve(
+          scope: @scope, thread_id: @input.thread_id, run_id: @input.run_id, digest: @input.digest
+        )
+      end
+
+      # An identity that is already reserved is never executed a second time.
+      # A run that ended is served as a reconnect: its outcome and state
+      # snapshot, without replaying the deltas or running anything again.
+      #
+      # A run that has not ended cannot be served here. A second stream cannot
+      # join a live one without a relay the gem does not own, and pretending it
+      # did would either hang or duplicate the work, so it fails closed.
+      def reconnect(record, to)
+        unless Reconnect.serves?(record)
+          raise StreamError, "run #{record.run_id} on thread #{record.thread_id} is still #{record.status}; " \
+                             'a live run cannot be joined by a second stream'
+        end
+
+        build_emitter(record, to).replay(Reconnect.new(record: record, input: @input).events)
+      end
+
+      def execute(record, to)
+        @mapper = build_mapper(record)
+        @emitter = build_emitter(record, to, mapper: @mapper)
+        @emitter.start(run_started_event(record), state: @state)
+        resume.apply(now: @clock.call) if resume.needed?
+        drive
+        @record = finish
+      rescue RubyLLM::CancelledError
+        @record = @emitter.cancel
+      rescue StandardError => e
+        @record = @emitter.fail(e)
+      end
+
+      def build_emitter(record, to, mapper: build_mapper(record))
+        Emitter.new(
+          writer: SSEWriter.new(to, logger: @logger), mapper: mapper,
+          store: @store, record: record, clock: @clock, logger: @logger
+        )
+      end
+
+      # Drives RubyLLM and projects what it reports.
+      #
+      # RubyLLM runs a host's local tools concurrently when asked to
+      # (`tool_concurrency`), so `before_tool_call` can arrive from several
+      # threads at once. The mapper is per-run state, so mapping and writing
+      # happen under one lock: two callbacks never interleave inside it, and the
+      # run's sequence stays a single ordered list.
+      def drive
+        @chat.before_tool_call { |tool_call| project { @mapper.before_tool_call(tool_call) } }
+        @chat.after_message { |message| project { @mapper.message(message) } }
+        @chat.complete { |chunk| project { @mapper.chunk(chunk) } }
+      end
+
+      def project
+        @mutex.synchronize { @emitter.write(yield) }
+      end
+
+      # A run that stopped for a human is an interrupt, never a success. Any
+      # other pause is something this producer cannot express on the wire, so it
+      # is a failure with a fixed, safe message rather than a run reported as
+      # finished.
+      def finish
+        return @emitter.succeed unless @chat.waiting?
+        raise UnsupportedRunStateError unless @chat.awaiting_approval?
+
+        @emitter.interrupt(build_interrupts)
+      end
+
+      # One interrupt per pending approval, carrying the tool call, the digest of
+      # the arguments RubyLLM asked to run, and a host-owned expiry. The host
+      # still re-authorizes before the tool executes: an approval answers an
+      # interrupt, it never grants a permission.
+      def build_interrupts
+        expires_at = @clock.call + @expires_in
+        @chat.pending_approvals.map do |tool_call|
+          Interrupt.create(
+            tool_call_id: tool_call.id,
+            arguments_digest: Canonical.digest(tool_call.arguments),
+            expires_at: expires_at,
+            message: "Approve the #{tool_call.name} tool call?"
+          )
+        end
+      end
+
+      def build_mapper(record)
+        Mapper.new(thread_id: record.thread_id, run_id: record.run_id, redact: @redact, logger: @logger)
+      end
+
+      def run_started_event(record)
+        Protocol.run_started(
+          thread_id: record.thread_id, run_id: record.run_id,
+          parent_run_id: @input.parent_run_id, input: @input.to_h
+        )
+      end
+
+      def validate!
+        unless @chat.respond_to?(:complete)
+          raise ConfigurationError, 'chat must be a RubyLLM::Chat or act like one (it does not respond to #complete)'
+        end
+        raise ConfigurationError, 'input must be a RubyLLM::AgUI::Input' unless @input.is_a?(Input)
+
+        validate_scope!
+      end
+
+      def validate_scope!
+        return if @scope.is_a?(String) && !@scope.empty?
+
+        raise ConfigurationError, 'scope must be a non-empty String built from authenticated identity'
+      end
+    end
+  end
+end

data/lib/ruby_llm/ag_ui/run_record.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module AgUI
+    # The authoritative server-side progress of one reserved run.
+    #
+    # The record is immutable: every transition returns a new record that the
+    # store persists. That keeps a run's identity, status and progress honest
+    # across processes, and it is what makes "a cancelled run is never reported
+    # as success" checkable rather than a comment: once a record reaches a
+    # terminal status, no transition can move it to a different one.
+    #
+    # A record is host bookkeeping, not business truth. The host still owns the
+    # conversation, the messages and whatever the tool calls actually did.
+    class RunRecord
+      # The statuses a run moves through: identity is claimed (RESERVED), the run
+      # streams (STARTED), and it ends in exactly one of the terminal statuses.
+      RESERVED = :reserved
+      STARTED = :started
+      # The run ended normally.
+      SUCCEEDED = :succeeded
+      # The run paused for human input.
+      INTERRUPTED = :interrupted
+      # The run was stopped before it completed and did not fail.
+      CANCELLED = :cancelled
+      # The run failed.
+      FAILED = :failed
+
+      STATUSES = [RESERVED, STARTED, SUCCEEDED, INTERRUPTED, CANCELLED, FAILED].freeze
+
+      # The statuses a run can end in. A run has exactly one.
+      TERMINAL_STATUSES = [SUCCEEDED, INTERRUPTED, CANCELLED, FAILED].freeze
+
+      # The host's tenant/actor/thread scope. Part of every reservation key.
+      attr_reader :scope
+
+      # The AG-UI conversation this run belongs to.
+      attr_reader :thread_id
+
+      # Identifies this run. Unique within (scope, thread_id).
+      attr_reader :run_id
+
+      # The digest of the input this run was reserved for. A retry that sends
+      # the same input attaches to this record instead of running twice; a
+      # different input under the same key is a conflict.
+      attr_reader :digest
+
+      # The run's current status.
+      attr_reader :status
+
+      # The highest event sequence number handed out for this run. Snapshots on
+      # reconnect are ordered by it rather than by wall-clock time.
+      attr_reader :sequence
+
+      # The host-owned run state kept for a reconnect snapshot, or nil.
+      attr_reader :snapshot
+
+      # The sanitized failure a reconnect reports for a run that failed, as
+      # `{"message" =>, "code" =>}`, or nil. Never the exception itself: a
+      # reconnect must not re-leak what the original RUN_ERROR withheld.
+      attr_reader :failure
+
+      # The interrupts raised by this run, oldest first.
+      attr_reader :interrupts
+
+      attr_reader :created_at, :updated_at
+
+      # rubocop:disable-next Metrics/ParameterLists -- one keyword per field the record owns
+      def initialize(scope:, thread_id:, run_id:, digest:, created_at:, status: RESERVED, sequence: 0,
+                     snapshot: nil, interrupts: [], failure: nil, updated_at: nil)
+        @scope = scope
+        @thread_id = thread_id
+        @run_id = run_id
+        @digest = digest
+        @status = assert_status!(status)
+        @sequence = sequence
+        @snapshot = snapshot
+        @interrupts = interrupts.freeze
+        @failure = failure
+        @created_at = created_at
+        @updated_at = updated_at || created_at
+        freeze
+      end
+
+      # One predicate per status, so callers read `record.interrupted?` rather
+      # than comparing symbols.
+      STATUSES.each do |status|
+        define_method(:"#{status}?") { self.status == status }
+      end
+
+      # Whether the run has ended.
+      def terminal?
+        TERMINAL_STATUSES.include?(status)
+      end
+
+      # Whether the run is waiting on a human. Reported as an interrupt outcome;
+      # never reported as success.
+      def awaiting_approval?
+        interrupted? && interrupts.any?(&:pending?)
+      end
+
+      # The interrupts that still wait for an answer.
+      def pending_interrupts
+        interrupts.select(&:pending?)
+      end
+
+      # The interrupt with +id+, or nil.
+      def interrupt(id)
+        interrupts.find { |interrupt| interrupt.id == id }
+      end
+
+      # Moves a reserved run to :started, remembering the host-owned state a
+      # reconnect serves. Idempotent for an already-started run.
+      def start(now:, snapshot: nil)
+        return self if started?
+
+        transition_to(STARTED, now: now, snapshot: snapshot)
+      end
+
+      # Hands out the next event sequence number.
+      def advance(now:)
+        with(now: now, sequence: sequence + 1)
+      end
+
+      # Closes the run with +status+: :succeeded, :interrupted, :cancelled or
+      # :failed, and, for a failure, the sanitized error a reconnect reports.
+      # Re-applying the same terminal status is an idempotent no-op — so the
+      # first failure wins rather than being replaced by a second, possibly
+      # different, explanation — and any other terminal status is a protocol
+      # violation, because a run has exactly one outcome.
+      def finish(status, now:, failure: nil)
+        raise ConfigurationError, "cannot finish a run as #{status.inspect}" unless TERMINAL_STATUSES.include?(status)
+        return self if terminal? && self.status == status
+        raise StreamError, "run #{run_id} already ended as #{self.status}, not #{status}" if terminal?
+
+        transition_to(status, now: now, failure: failure)
+      end
+
+      # Closes the run as interrupted and records the interrupts it raised.
+      def interrupted(interrupts, now:)
+        raise ConfigurationError, 'an interrupted run needs at least one interrupt' if interrupts.empty?
+
+        pending = interrupts.reject(&:decided?)
+        raise ConfigurationError, 'an interrupted run needs at least one unresolved interrupt' if pending.empty?
+
+        transition_to(INTERRUPTED, now: now, interrupts: interrupts)
+      end
+
+      # Replaces the interrupt with the same id, keeping its position.
+      #
+      # This is the one transition that also applies to a terminal record: an
+      # interrupted run is closed, and answering its interrupt records the
+      # decision on that closed record.
+      def replace_interrupt(decided, now:)
+        raise ConfigurationError, "no interrupt #{decided.id} on run #{run_id}" unless interrupt(decided.id)
+
+        replaced = interrupts.map { |existing| existing.id == decided.id ? decided : existing }
+        with(now: now, interrupts: replaced)
+      end
+
+      def to_h
+        {
+          'scope' => scope.to_s,
+          'threadId' => thread_id,
+          'runId' => run_id,
+          'digest' => digest,
+          'status' => status.to_s,
+          'sequence' => sequence,
+          'snapshot' => snapshot,
+          'failure' => failure,
+          'interrupts' => interrupts.map(&:to_h),
+          'createdAt' => iso8601(created_at),
+          'updatedAt' => iso8601(updated_at)
+        }
+      end
+
+      # The record in the form a durable store keeps. #to_h is the reporting
+      # shape; it leaves out what an interrupt needs to be re-verified, so a
+      # store round-trips this instead.
+      def to_storage
+        to_h.merge('interrupts' => interrupts.map(&:to_storage))
+      end
+
+      # Rebuilds a record stored by #to_storage.
+      def self.from_storage(hash)
+        new(
+          scope: hash.fetch('scope'), thread_id: hash.fetch('threadId'), run_id: hash.fetch('runId'),
+          digest: hash.fetch('digest'), status: hash.fetch('status').to_sym,
+          sequence: hash.fetch('sequence'), snapshot: hash['snapshot'], failure: hash['failure'],
+          interrupts: interrupts_from_storage(hash['interrupts']),
+          created_at: Interrupt.parse_time(hash.fetch('createdAt')),
+          updated_at: Interrupt.parse_time(hash.fetch('updatedAt'))
+        )
+      end
+
+      def self.interrupts_from_storage(list)
+        (list || []).map { |interrupt| Interrupt.from_storage(interrupt) }
+      end
+
+      private
+
+      # rubocop:disable-next Metrics/ParameterLists -- one keyword per field, each defaulted to the record's own
+      def with(now:, status: self.status, sequence: self.sequence, snapshot: self.snapshot,
+               interrupts: self.interrupts, failure: self.failure)
+        self.class.new(
+          scope: scope, thread_id: thread_id, run_id: run_id, digest: digest, status: status,
+          sequence: sequence, snapshot: snapshot, interrupts: interrupts, failure: failure,
+          created_at: created_at, updated_at: now
+        )
+      end
+
+      def transition_to(status, now:, **attributes)
+        raise StreamError, "run #{run_id} already ended as #{self.status}" if terminal?
+
+        with(now: now, status: status, **attributes)
+      end
+
+      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