poetry-agent 0.0.2

data/lib/poetry/agent/agui/relay.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Poetry
+  module Agent
+    module AGUI
+      # Turns transcript changes into Turbo Streams. The host supplies the
+      # row renderer (its own partial or component: a message and its
+      # version in, the row's HTML out - the row must carry
+      # `data-version`), the target id scheme, and the container new rows
+      # append to. The relay stays view-free.
+      #
+      # Client tools ride the same channel: when a run ends with tool
+      # calls the browser must execute, {#client_tool_streams} appends
+      # one bridge element per call; the `poetry--agent--agui-client-tool`
+      # controller executes it through the registrar and POSTs the result
+      # to the continue URL, whose response streams the next run.
+      #
+      # @example Streaming a run into a page
+      #   relay = Poetry::Agent::AGUI::Relay.new(transcript: transcript, container: "chat-messages",
+      #                                          render: ->(message, version) { render_row(message, version) })
+      #   client.run(input) { |event| relay.apply(event).each { |stream| write(TurboStream.sse(stream)) } }
+      class Relay
+        # The bridge controller's identifier.
+        CLIENT_TOOL_CONTROLLER = "poetry--agent--agui-client-tool"
+
+        # @return [Transcript]
+        attr_reader :transcript
+
+        # @param transcript [Transcript]
+        # @param render [#call] `(message, version) -> String` the row HTML
+        # @param container [String, nil] the id new rows append to (nil: replace only)
+        # @param target [#call] `(message) -> String` the row's element id
+        # @param action [String] the stream action for updates (`vreplace` by default)
+        # @param append_render [#call, nil] `(message, version) -> String` the HTML a
+        #   first appearance appends - the row inside its list wrapper (a scroller
+        #   item); defaults to `render`
+        def initialize(transcript:, render:, container: nil, target: ->(message) { "row-#{message.id}" }, # rubocop:disable Metrics/ParameterLists
+                       action: "vreplace", append_render: nil, morph: false)
+          @transcript = transcript
+          @render = render
+          @append_render = append_render || render
+          @container = container
+          @target = target
+          @action = action
+          @morph = morph
+          @seen = {}
+        end
+
+        # Applies an event and answers the Turbo Streams it produced: an
+        # append for a message's first appearance (when a container is
+        # set), then the update action for every change.
+        #
+        # @param event [Hash]
+        # @return [Array<String>]
+        def apply(event)
+          @transcript.apply(event).filter_map { |id| stream_for(id) }
+        end
+
+        # Marks message ids the page already renders, so their next change
+        # is an update rather than an append (server-rendered history).
+        #
+        # @param ids [Array<String>]
+        # @return [self]
+        def mark_seen(*ids)
+          ids.flatten.each { |id| @seen[id.to_s] = true }
+          self
+        end
+
+        # The stream for one message id (nil when the message is unknown).
+        #
+        # @param id [String]
+        # @return [String, nil]
+        def stream_for(id)
+          message = @transcript.message(id)
+          return nil unless message
+
+          first = !@seen[id]
+          @seen[id] = true
+          return TurboStream.append(@container, @append_render.call(message, message.version)) if @container && first
+
+          TurboStream.build(@action, @target.call(message), @render.call(message, message.version),
+                            method: @morph ? "morph" : nil)
+        end
+
+        # Bridge elements for every pending client tool call.
+        #
+        # @param continue_url [String] where the browser POSTs `{ toolCallId, name, content, error }`
+        # @param container [String] the element the bridge elements append to
+        # @return [Array<String>]
+        def client_tool_streams(continue_url:, container: @container)
+          @transcript.pending_client_tools.map do |pending|
+            call = { "toolCallId" => pending[:tool_call_id], "name" => pending[:name], "args" => pending[:input] || {} }
+            id = TurboStream.escape(pending[:tool_call_id])
+            element = "<div id=\"agui-client-tool-#{id}\" hidden data-controller=\"#{CLIENT_TOOL_CONTROLLER}\" " \
+                      "data-#{CLIENT_TOOL_CONTROLLER}-call-value=\"#{TurboStream.escape(JSON.generate(call))}\" " \
+                      "data-#{CLIENT_TOOL_CONTROLLER}-url-value=\"#{TurboStream.escape(continue_url)}\"></div>"
+            TurboStream.append(container, element)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/poetry/agent/agui/run_input.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Poetry
+  module Agent
+    module AGUI
+      # Builds the `RunAgentInput` wire hash an AG-UI agent accepts:
+      # camelCased keys, messages in the protocol's shapes, the
+      # frontend-defined tools, context entries, state, forwarded props,
+      # and the resume entries that answer interrupts.
+      module RunInput
+        module_function
+
+        # @param thread_id [String] the conversation thread
+        # @param messages [Array<Hash>] protocol messages (`id`, `role`, `content`, ...)
+        # @param run_id [String] defaults to a fresh UUID
+        # @param tools [Array<Hash>] frontend-defined tools ({AGUI.tool_descriptor})
+        # @param context [Array<Hash>] `{ "description", "value" }` entries
+        # @param state [Hash] the shared state to send
+        # @param forwarded_props [Hash] integration-specific props
+        # @param parent_run_id [String, nil] the run this one branches from
+        # @param resume [Array<Hash>, nil] `{ "interruptId", "status", "payload" }` answers
+        # @return [Hash] the wire hash (string keys)
+        # @example A first run with one client tool
+        #   RunInput.build(thread_id: "t1", messages: [RunInput.user_message("hi")],
+        #                  tools: [Poetry::Agent::AGUI.tool_descriptor("sections", definition)])
+        def build( # rubocop:disable Metrics/ParameterLists -- one keyword per RunAgentInput field
+          thread_id:, messages:, run_id: SecureRandom.uuid, tools: [], context: [], state: {},
+          forwarded_props: {}, parent_run_id: nil, resume: nil
+        )
+          input = {
+            "threadId" => thread_id,
+            "runId" => run_id,
+            "state" => state,
+            "messages" => messages,
+            "tools" => tools,
+            "context" => context,
+            "forwardedProps" => forwarded_props
+          }
+          input["parentRunId"] = parent_run_id if parent_run_id
+          input["resume"] = resume if resume
+          input
+        end
+
+        # A user message.
+        #
+        # @param content [String]
+        # @param id [String]
+        # @return [Hash]
+        def user_message(content, id: SecureRandom.uuid)
+          { "id" => id, "role" => "user", "content" => content }
+        end
+
+        # A tool-result message answering a tool call the browser ran.
+        #
+        # @param tool_call_id [String]
+        # @param content [String] the result as text (JSON for structured results)
+        # @param error [String, nil] set when the tool failed
+        # @param id [String]
+        # @return [Hash]
+        def tool_message(tool_call_id, content, error: nil, id: SecureRandom.uuid)
+          message = { "id" => id, "role" => "tool", "content" => content.to_s, "toolCallId" => tool_call_id }
+          message["error"] = error if error
+          message
+        end
+
+        # A resume entry answering an interrupt.
+        #
+        # @param interrupt_id [String]
+        # @param status [String, nil] e.g. "approved", "rejected"
+        # @param payload [Object, nil]
+        # @return [Hash]
+        def resume_entry(interrupt_id, status: nil, payload: nil)
+          entry = { "interruptId" => interrupt_id }
+          entry["status"] = status if status
+          entry["payload"] = payload unless payload.nil?
+          entry
+        end
+      end
+    end
+  end
+end

data/lib/poetry/agent/agui/sse.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Poetry
+  module Agent
+    module AGUI
+      # A `text/event-stream` parser for AG-UI: every event is a JSON
+      # object on one or more `data:` lines, terminated by a blank line.
+      # Incremental (feed chunks as they arrive) and tolerant of comments,
+      # `event:` / `id:` / `retry:` fields, and CRLF.
+      module SSE
+        # The incremental parser.
+        class Parser
+          # Lines that carried data the parser could not read as JSON.
+          #
+          # @return [Array<String>]
+          attr_reader :errors
+
+          def initialize
+            @buffer = +""
+            @data = []
+            @errors = []
+          end
+
+          # Feeds a chunk and yields each completed event.
+          #
+          # @param chunk [String]
+          # @yieldparam event [Hash] the parsed JSON object (string keys)
+          # @return [void]
+          def feed(chunk, &)
+            @buffer << chunk
+            while (newline = @buffer.index("\n"))
+              line = @buffer.slice!(0..newline).chomp
+              consume(line, &)
+            end
+          end
+
+          # Flushes a trailing event that lacked its blank line.
+          #
+          # @yieldparam event [Hash]
+          # @return [void]
+          def finish(&)
+            consume(@buffer.chomp, &) unless @buffer.empty?
+            @buffer = +""
+            dispatch(&)
+          end
+
+          private
+
+          def consume(line, &)
+            if line.empty?
+              dispatch(&)
+            elsif line.start_with?("data:")
+              @data << line.delete_prefix("data:").delete_prefix(" ")
+            end
+            # Comments (":"), event:, id:, retry: carry nothing AG-UI reads.
+          end
+
+          def dispatch
+            return if @data.empty?
+
+            payload = @data.join("\n")
+            @data = []
+            event = JSON.parse(payload)
+            yield event if event.is_a?(Hash) && block_given?
+          rescue JSON::ParserError
+            @errors << payload
+          end
+        end
+
+        module_function
+
+        # Parses a complete stream (a String or anything responding to
+        # `each` with chunks) and yields every event.
+        #
+        # @param source [String, #each]
+        # @yieldparam event [Hash]
+        # @return [Array<Hash>] every event, when no block is given
+        # @example
+        #   Poetry::Agent::AGUI::SSE.parse("data: {\"type\":\"RUN_STARTED\"}\n\n") # => [{ "type" => "RUN_STARTED" }]
+        def parse(source, &block)
+          events = []
+          collector = block || ->(event) { events << event }
+          parser = Parser.new
+          if source.is_a?(String)
+            parser.feed(source, &collector)
+          else
+            source.each { |chunk| parser.feed(chunk.to_s, &collector) }
+          end
+          parser.finish(&collector)
+          block ? nil : events
+        end
+      end
+    end
+  end
+end