ag-ui 0.1.0

data/lib/ag_ui/event_bridge.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "ag_ui"
+
+module AgUi
+  # The seam between brute's turn pipeline and the AG-UI SSE stream.
+  #
+  # Brute middleware and terminal procs push `{type:, data:}` events into
+  # env[:events]; an EventBridge is that sink, translating each event into
+  # the matching typed SSE emitter as it arrives — the browser sees deltas
+  # mid-turn, not after.
+  #
+  #   pipeline.start(messages, events: AgUi::EventBridge.new(stream))
+  #
+  # Unknown event types (brute's own :log, :tool_result telemetry, etc.)
+  # are ignored — only the AG-UI vocabulary reaches the wire.
+  class EventBridge
+    TRANSLATIONS = {
+      text_message_start: :translate_text_start,
+      text_message_content: :translate_text_content,
+      text_message_end: :translate_text_end,
+      tool_call_start: :translate_tool_call_start,
+      tool_call_args: :translate_tool_call_args,
+      tool_call_end: :translate_tool_call_end,
+      tool_call_result: :translate_tool_call_result,
+      activity_snapshot: :translate_activity_snapshot,
+      reasoning_start: :translate_reasoning_start,
+      reasoning_message_start: :translate_reasoning_message_start,
+      reasoning_message_content: :translate_reasoning_message_content,
+      reasoning_message_end: :translate_reasoning_message_end,
+      reasoning_end: :translate_reasoning_end,
+    }.freeze
+
+    def initialize(stream)
+      @stream = stream
+    end
+
+    def <<(event)
+      handler = TRANSLATIONS[event[:type]]
+      if handler
+        send(handler, event[:data] || {})
+      end
+      self
+    end
+
+    private
+
+      def translate_text_start(data)
+        @stream.text_message_start(message_id: data[:message_id])
+      end
+
+      # Protocol rule: TEXT_MESSAGE_CONTENT.delta must be non-empty —
+      # providers occasionally emit empty chunks; drop them here.
+      def translate_text_content(data)
+        unless data[:delta].to_s.empty?
+          @stream.text_message_content(message_id: data[:message_id], delta: data[:delta])
+        end
+      end
+
+      def translate_text_end(data)
+        @stream.text_message_end(message_id: data[:message_id])
+      end
+
+      def translate_tool_call_start(data)
+        @stream.tool_call_start(
+          tool_call_id: data[:tool_call_id],
+          tool_call_name: data[:tool_call_name],
+          parent_message_id: data[:parent_message_id],
+        )
+      end
+
+      def translate_tool_call_args(data)
+        unless data[:delta].to_s.empty?
+          @stream.tool_call_args(tool_call_id: data[:tool_call_id], delta: data[:delta])
+        end
+      end
+
+      def translate_tool_call_end(data)
+        @stream.tool_call_end(tool_call_id: data[:tool_call_id])
+      end
+
+      def translate_tool_call_result(data)
+        @stream.tool_call_result(
+          message_id: data[:message_id],
+          tool_call_id: data[:tool_call_id],
+          content: data[:content],
+        )
+      end
+
+      def translate_activity_snapshot(data)
+        @stream.activity_snapshot(
+          message_id: data[:message_id],
+          activity_type: data[:activity_type],
+          content: data[:content],
+          replace: data.fetch(:replace, true),
+        )
+      end
+
+      def translate_reasoning_start(data)
+        @stream.reasoning_start(message_id: data[:message_id])
+      end
+
+      def translate_reasoning_message_start(data)
+        @stream.reasoning_message_start(message_id: data[:message_id])
+      end
+
+      def translate_reasoning_message_content(data)
+        unless data[:delta].to_s.empty?
+          @stream.reasoning_message_content(message_id: data[:message_id], delta: data[:delta])
+        end
+      end
+
+      def translate_reasoning_message_end(data)
+        @stream.reasoning_message_end(message_id: data[:message_id])
+      end
+
+      def translate_reasoning_end(data)
+        @stream.reasoning_end(message_id: data[:message_id])
+      end
+  end
+end
+
+__END__
+
+describe "AgUi::EventBridge" do
+  read_frames = ->(stream) do
+    frames = []
+    while (chunk = stream.read)
+      frames << JSON.parse(chunk.sub(/\Adata: /, "").strip)
+    end
+    frames
+  end
+
+  it "translates text events into SSE frames as they arrive" do
+    stream = AgUi::Server::SSE::Stream.new(thread_id: "t1", run_id: "r1")
+    bridge = AgUi::EventBridge.new(stream)
+
+    bridge << { type: :text_message_start, data: { message_id: "m1" } }
+    bridge << { type: :text_message_content, data: { message_id: "m1", delta: "Hel" } }
+    bridge << { type: :text_message_content, data: { message_id: "m1", delta: "lo" } }
+    bridge << { type: :text_message_end, data: { message_id: "m1" } }
+    stream.finish
+
+    frames = read_frames.(stream)
+    frames.map { |f| f["type"] }.should == %w[
+      TEXT_MESSAGE_START TEXT_MESSAGE_CONTENT TEXT_MESSAGE_CONTENT TEXT_MESSAGE_END
+    ]
+    frames[1]["delta"].should == "Hel"
+  end
+
+  it "drops empty deltas (protocol rule)" do
+    stream = AgUi::Server::SSE::Stream.new(thread_id: "t1", run_id: "r1")
+    bridge = AgUi::EventBridge.new(stream)
+
+    bridge << { type: :text_message_content, data: { message_id: "m1", delta: "" } }
+    bridge << { type: :text_message_content, data: { message_id: "m1", delta: nil } }
+    stream.finish
+
+    read_frames.(stream).should == []
+  end
+
+  it "ignores brute telemetry and unknown event types, returning self" do
+    stream = AgUi::Server::SSE::Stream.new(thread_id: "t1", run_id: "r1")
+    bridge = AgUi::EventBridge.new(stream)
+
+    result = bridge << { type: :log, data: { note: "internal" } }
+    bridge << { type: :whatever }
+    stream.finish
+
+    result.should.equal?(bridge)
+    read_frames.(stream).should == []
+  end
+end

data/lib/ag_ui/messages.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "ag_ui"
+
+module AgUi
+  # Translates AG-UI wire messages (RunAgentInput.messages — raw camelCase
+  # hashes) into brute's canonical Brute::Message log, ready for the turn
+  # pipeline. This is where client-executed tool results re-enter the
+  # conversation: the assistant's toolCalls and the matching tool messages
+  # must round-trip faithfully or the model repeats calls (doc 03 gotchas).
+  module Messages
+    class << self
+      def to_brute(wire_messages)
+        log = Brute.log
+
+        wire_messages.each do |message|
+          case message["role"]
+          in "user"
+            log.user(text_content(message["content"]))
+          in "assistant"
+            log << assistant_message(message)
+          in "tool"
+            log.tool(message["content"].to_s, tool_call_id: message["toolCallId"])
+          in "system" | "developer"
+            log.system(message["content"].to_s)
+          in "activity" | "reasoning"
+            # Not part of the LLM conversation: activities render client-side
+            # (phase 4) and reasoning is provider-managed (phase 5).
+            nil
+          end
+        end
+
+        log
+      end
+
+      private
+
+        def assistant_message(message)
+          tool_calls = message["toolCalls"]&.map do |tc|
+            Brute::ToolCall.new(
+              id: tc["id"],
+              name: tc.dig("function", "name"),
+              arguments: parse_arguments(tc.dig("function", "arguments")),
+            )
+          end
+
+          Brute::Message.new(
+            role: :assistant,
+            content: message["content"],
+            tool_calls: tool_calls,
+          )
+        end
+
+        # Wire arguments are a JSON-encoded string (OpenAI shape);
+        # Brute::ToolCall wants the parsed Hash.
+        def parse_arguments(arguments)
+          case arguments
+          when nil then {}
+          when Hash then arguments
+          else
+            begin
+              JSON.parse(arguments.to_s)
+            rescue JSON::ParserError
+              {}
+            end
+          end
+        end
+
+        # Multimodal content arrives as an array of InputContent parts.
+        # All-text arrays flatten to a plain string (pipeline middleware
+        # reads string content); arrays carrying media parts stay raw —
+        # the terminal maps them to its provider's attachment API.
+        def text_content(content)
+          case content
+          when Array
+            if content.all? { |part| part["type"] == "text" }
+              content.map { |part| part["text"] }.join("\n")
+            else
+              content
+            end
+          else
+            content.to_s
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+describe "AgUi::Messages.to_brute" do
+  it "translates the core roles" do
+    log = AgUi::Messages.to_brute([
+      { "id" => "s1", "role" => "system", "content" => "be helpful" },
+      { "id" => "u1", "role" => "user", "content" => "hi" },
+      { "id" => "a1", "role" => "assistant", "content" => "hello!" },
+    ])
+
+    log.map(&:role).should == [:system, :user, :assistant]
+    log.last.content.should == "hello!"
+  end
+
+  it "round-trips assistant toolCalls with parsed JSON arguments" do
+    log = AgUi::Messages.to_brute([
+      { "id" => "a1", "role" => "assistant", "content" => nil,
+        "toolCalls" => [{ "id" => "tc1", "type" => "function",
+                          "function" => { "name" => "navigate", "arguments" => "{\"path\":\"/data\"}" } }] },
+      { "id" => "t1", "role" => "tool", "content" => "{\"ok\":true}", "toolCallId" => "tc1" },
+    ])
+
+    assistant = log.first
+    assistant.tool_call?.should.be.true
+    assistant.tool_calls.first.id.should == "tc1"
+    assistant.tool_calls.first.name.should == "navigate"
+    assistant.tool_calls.first.arguments.should == { "path" => "/data" }
+
+    log.last.role.should == :tool
+    log.last.tool_call_id.should == "tc1"
+    log.last.content.should == "{\"ok\":true}"
+  end
+
+  it "tolerates malformed tool-call argument JSON" do
+    log = AgUi::Messages.to_brute([
+      { "id" => "a1", "role" => "assistant",
+        "toolCalls" => [{ "id" => "tc1", "type" => "function",
+                          "function" => { "name" => "x", "arguments" => "{nope" } }] },
+    ])
+    log.first.tool_calls.first.arguments.should == {}
+  end
+
+  it "flattens all-text part arrays and preserves arrays carrying media" do
+    text_only = AgUi::Messages.to_brute([
+      { "id" => "u1", "role" => "user", "content" => [
+        { "type" => "text", "text" => "hello" },
+        { "type" => "text", "text" => "there" },
+      ] },
+    ])
+    text_only.first.content.should == "hello\nthere"
+
+    multimodal = AgUi::Messages.to_brute([
+      { "id" => "u1", "role" => "user", "content" => [
+        { "type" => "text", "text" => "what is this?" },
+        { "type" => "image", "source" => { "type" => "url", "value" => "http://x/y.png" } },
+      ] },
+    ])
+    multimodal.first.content.should.be.kind_of(Array)
+    multimodal.first.content.last["type"].should == "image"
+  end
+
+  it "skips activity and reasoning messages" do
+    log = AgUi::Messages.to_brute([
+      { "id" => "act1", "role" => "activity", "activityType" => "a2ui-surface", "content" => {} },
+      { "id" => "r1", "role" => "reasoning", "content" => "thinking..." },
+      { "id" => "u1", "role" => "user", "content" => "hi" },
+    ])
+    log.map(&:role).should == [:user]
+  end
+end