ag-ui 0.1.0

data/lib/ag_ui/middleware/tool_router.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "securerandom"
+require "console"
+require "ag_ui"
+
+module AgUi
+  module Middleware
+    # Brute-style turn middleware implementing both halves of the AG-UI
+    # tool model (doc 03).
+    #
+    # Way in: advertises the run's client tool definitions
+    # (RunAgentInput.tools) plus the app's SERVER tool definitions on
+    # env[:tools] (idempotent — the loop re-enters this middleware every
+    # iteration).
+    #
+    # Way out, per tool call the model made:
+    #   - every call emits TOOL_CALL_START / ARGS / END
+    #   - a SERVER tool ({name:, description:, parameters:, handler:})
+    #     executes inline: its result is appended as a :tool message
+    #     (Loop::ToolResult re-invokes the stack so the model continues
+    #     the same run) and emitted as TOOL_CALL_RESULT — the Node
+    #     runtime's exact shape
+    #   - a CLIENT tool sets env[:should_exit]: the run ends with plain
+    #     RUN_FINISHED and the browser executes it (multi-run model)
+    #   - mixed turns: server tools still execute, but any client call
+    #     ends the run
+    class ToolRouter
+      def initialize(app, tools: nil, server_tools: nil)
+        @app = app
+        @client_tools = tools || []
+        @server_tools = (server_tools || []).to_h { |t| [t[:name].to_s, t] }
+      end
+
+      def call(env)
+        advertise(env)
+
+        @app.call(env)
+
+        last = env[:messages].last
+        if last.respond_to?(:tool_call?) && last.tool_call?
+          route(env, last.tool_calls)
+        end
+
+        env
+      end
+
+      private
+
+        def advertise(env)
+          env[:tools] ||= []
+          known = env[:tools].map { |d| definition_name(d) }
+
+          definitions = @client_tools + @server_tools.values.map { |t| server_definition(t) }
+          definitions.each do |definition|
+            name = definition_name(definition)
+            unless known.include?(name)
+              env[:tools] << definition
+              known << name
+            end
+          end
+        end
+
+        def definition_name(definition)
+          if definition.respond_to?(:to_h)
+            definition.to_h["name"]
+          else
+            definition["name"]
+          end
+        end
+
+        def server_definition(tool)
+          {
+            "name" => tool[:name].to_s,
+            "description" => tool[:description].to_s,
+            "parameters" => tool[:parameters] || { "type" => "object" },
+          }
+        end
+
+        def route(env, tool_calls)
+          client_called = false
+
+          tool_calls.each do |tool_call|
+            emit_call(env[:events], tool_call)
+
+            server = @server_tools[tool_call.name]
+            if server
+              execute_server_tool(env, tool_call, server)
+            else
+              client_called = true
+            end
+          end
+
+          if client_called
+            env[:should_exit] = true
+          end
+        end
+
+        def emit_call(events, tool_call)
+          events << {
+            type: :tool_call_start,
+            data: { tool_call_id: tool_call.id, tool_call_name: tool_call.name },
+          }
+          events << {
+            type: :tool_call_args,
+            data: { tool_call_id: tool_call.id, delta: JSON.generate(tool_call.arguments) },
+          }
+          events << {
+            type: :tool_call_end,
+            data: { tool_call_id: tool_call.id },
+          }
+        end
+
+        def execute_server_tool(env, tool_call, tool)
+          begin
+            result = tool[:handler].call(tool_call.arguments)
+          rescue => e
+            Console.error(self, "server tool #{tool_call.name} raised: #{e.message}", e)
+            result = { "error" => e.message }
+          end
+
+          content = result.is_a?(String) ? result : JSON.generate(result)
+          env[:messages].tool(content, tool_call_id: tool_call.id)
+          env[:events] << {
+            type: :tool_call_result,
+            data: {
+              message_id: SecureRandom.uuid,
+              tool_call_id: tool_call.id,
+              content: content,
+            },
+          }
+        end
+    end
+  end
+end
+
+__END__
+
+describe "AgUi::Middleware::ToolRouter" do
+  it "advertises client and server tools idempotently across iterations" do
+    seen = nil
+    server_tool = { name: "get_time", description: "Now", handler: -> (_args) { "12:00" } }
+    mw = AgUi::Middleware::ToolRouter.new(
+      ->(env) { seen = env[:tools] },
+      tools: [{ "name" => "navigate" }],
+      server_tools: [server_tool],
+    )
+
+    env = { messages: Brute.log, events: [] }
+    mw.call(env)
+    mw.call(env) # second loop iteration
+
+    seen.map { |t| t["name"] }.should == %w[navigate get_time]
+    seen.last["parameters"].should == { "type" => "object" }
+  end
+
+  it "executes server tools inline: tool message appended, result emitted, no exit" do
+    server_tool = {
+      name: "lookup",
+      description: "Look something up",
+      parameters: { "type" => "object" },
+      handler: ->(args) { { "found" => args["id"] } },
+    }
+    terminal = ->(env) do
+      env[:messages] << Brute::Message.new(
+        role: :assistant, content: nil,
+        tool_calls: [{ id: "tc1", name: "lookup", arguments: { "id" => 42 } }],
+      )
+    end
+
+    env = { messages: Brute.log, events: [] }
+    AgUi::Middleware::ToolRouter.new(terminal, server_tools: [server_tool]).call(env)
+
+    env[:messages].last.role.should == :tool
+    env[:messages].last.tool_call_id.should == "tc1"
+    env[:messages].last.content.should == "{\"found\":42}"
+
+    env[:events].map { |e| e[:type] }.should == %i[
+      tool_call_start tool_call_args tool_call_end tool_call_result
+    ]
+    env[:events].last[:data][:content].should == "{\"found\":42}"
+    env.key?(:should_exit).should == false
+  end
+
+  it "captures handler errors as the tool result" do
+    server_tool = { name: "boom", description: "x", handler: ->(_a) { raise "kaput" } }
+    terminal = ->(env) do
+      env[:messages] << Brute::Message.new(
+        role: :assistant, content: nil,
+        tool_calls: [{ id: "tc1", name: "boom", arguments: {} }],
+      )
+    end
+
+    env = { messages: Brute.log, events: [] }
+    AgUi::Middleware::ToolRouter.new(terminal, server_tools: [server_tool]).call(env)
+
+    env[:messages].last.content.should == "{\"error\":\"kaput\"}"
+    env.key?(:should_exit).should == false
+  end
+
+  it "mixed turns execute server tools but still end the run for client calls" do
+    server_tool = { name: "lookup", description: "x", handler: ->(_a) { "ok" } }
+    terminal = ->(env) do
+      env[:messages] << Brute::Message.new(
+        role: :assistant, content: nil,
+        tool_calls: [
+          { id: "tc1", name: "lookup", arguments: {} },
+          { id: "tc2", name: "navigate", arguments: { "path" => "/x" } },
+        ],
+      )
+    end
+
+    env = { messages: Brute.log, events: [] }
+    AgUi::Middleware::ToolRouter.new(terminal, server_tools: [server_tool]).call(env)
+
+    env[:should_exit].should == true
+    env[:events].count { |e| e[:type] == :tool_call_result }.should == 1
+  end
+
+  it "emits TOOL_CALL events and exits when the turn ends on client tool calls" do
+    terminal = ->(env) do
+      env[:messages] << Brute::Message.new(
+        role: :assistant, content: nil,
+        tool_calls: [
+          { id: "tc1", name: "navigate", arguments: { "path" => "/data" } },
+          { id: "tc2", name: "queryDataModel", arguments: { "model" => "contacts" } },
+        ],
+      )
+    end
+
+    env = { messages: Brute.log, events: [] }
+    AgUi::Middleware::ToolRouter.new(terminal).call(env)
+
+    env[:events].map { |e| e[:type] }.should == %i[
+      tool_call_start tool_call_args tool_call_end
+      tool_call_start tool_call_args tool_call_end
+    ]
+    env[:events][0][:data].should == { tool_call_id: "tc1", tool_call_name: "navigate" }
+    env[:events][1][:data][:delta].should == "{\"path\":\"/data\"}"
+    env[:should_exit].should == true
+  end
+
+  it "does nothing on the way out for plain text turns" do
+    env = { messages: Brute.log, events: [] }
+    AgUi::Middleware::ToolRouter.new(->(e) { e[:messages].assistant("hi") }).call(env)
+
+    env[:events].should == []
+    env.key?(:should_exit).should == false
+  end
+end

data/lib/ag_ui/protocol/json_schema/definition.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "ag_ui"
+
+module AgUi
+  module Protocol
+    module JsonSchema
+      # Base class for schema-validated AG-UI protocol objects.
+      # Ported from a2a's Protocol::JsonSchema::Definition.
+      #
+      # Each AG-UI definition (RunAgentInput, TextMessageContentEvent, …)
+      # gets a dynamically-generated subclass of Definition with:
+      #   - A JSONSchemer sub-schema attached (.schema)
+      #   - Reader methods for each property (snake_case)
+      #   - Validation via .valid? / .valid!
+      #
+      # NOTE: #to_h deep-compacts nil values (matching pydantic's
+      # exclude_none on the wire). Inbound payloads that carry explicit
+      # nulls (e.g. RunAgentInput.state) should be validated as raw
+      # hashes via JsonSchema.schemer, not round-tripped through here.
+      class Definition
+        def initialize(hash = {})
+          props    = self.class.schema_properties
+          snake    = self.class.snake_to_camel_map
+          refs     = self.class.property_refs
+          @data    = {}
+
+          hash.each do |key, value|
+            k = key.to_s
+
+            # Resolve snake_case input to camelCase storage key
+            camel = snake[k] || k
+
+            if props.include?(camel)
+              @data[camel] = if value.is_a?(Definition)
+                value.to_h
+              elsif (ref_info = refs[camel])
+                wrap_ref(value, ref_info)
+              else
+                value
+              end
+            end
+          end
+        end
+
+        # --- class methods overridden by the factory -----------------------
+
+        def self.schema
+          raise "AgUi::Protocol::JsonSchema::Definition should NOT be instantiated directly"
+        end
+
+        def self.definition_name
+          raise "AgUi::Protocol::JsonSchema::Definition should NOT be instantiated directly"
+        end
+
+        def self.schema_properties
+          raise "AgUi::Protocol::JsonSchema::Definition should NOT be instantiated directly"
+        end
+
+        def self.snake_to_camel_map
+          raise "AgUi::Protocol::JsonSchema::Definition should NOT be instantiated directly"
+        end
+
+        def self.property_refs
+          raise "AgUi::Protocol::JsonSchema::Definition should NOT be instantiated directly"
+        end
+
+        # Reverse of snake_to_camel_map. Built first-entry-wins: the
+        # factory inserts the snake_case key before the camelCase
+        # identity key, so camelCase storage keys map back to their
+        # snake_case reader names.
+        def self.camel_to_snake_map
+          @camel_to_snake_map ||= snake_to_camel_map.each_with_object({}) do |(key, camel), map|
+            map[camel] ||= key
+          end
+        end
+
+        # --- validation ----------------------------------------------------
+
+        def valid?
+          self.class.schema.valid?(to_h)
+        end
+
+        def valid!
+          errors = self.class.schema.validate(to_h).to_a
+
+          if errors.empty?
+            true
+          else
+            raise ValidationError.new(
+              errors,
+              definition_name: self.class.definition_name,
+              data: to_h,
+            )
+          end
+        end
+
+        # --- serialization -------------------------------------------------
+
+        # Returns the data as a plain Hash with camelCase string keys,
+        # matching the JSON wire format. Nested Definition instances
+        # are auto-coerced via deep_compact.
+        def to_h
+          deep_compact(@data)
+        end
+
+        def ==(other)
+          other.is_a?(Definition) && to_h == other.to_h
+        end
+
+        # --- pattern matching ----------------------------------------------
+
+        # Supports Ruby hash pattern matching with snake_case (or camelCase)
+        # keys. Absent properties are omitted so patterns requiring them
+        # fail to match; nested Definitions destructure recursively.
+        def deconstruct_keys(keys)
+          snake = self.class.snake_to_camel_map
+
+          if keys
+            keys.each_with_object({}) do |key, result|
+              camel = snake[key.to_s] || key.to_s
+              if @data.key?(camel)
+                result[key] = @data[camel]
+              end
+            end
+          else
+            camel_to_snake = self.class.camel_to_snake_map
+            @data.each_with_object({}) do |(camel, value), result|
+              result[(camel_to_snake[camel] || camel).to_sym] = value
+            end
+          end
+        end
+
+        def inspect
+          "#<#{self.class.definition_name} #{to_h.inspect}>"
+        end
+
+        private
+
+          def wrap_ref(value, ref_info)
+            kind, name = ref_info
+
+            case kind
+            when :object
+              value.is_a?(Hash) ? AgUi::Protocol::JsonSchema[name].new(value) : value
+            when :array
+              if value.is_a?(Array)
+                value.map { |el| el.is_a?(Hash) ? AgUi::Protocol::JsonSchema[name].new(el) : el }
+              else
+                value
+              end
+            when :map
+              if value.is_a?(Hash)
+                value.transform_values { |v| v.is_a?(Hash) ? AgUi::Protocol::JsonSchema[name].new(v) : v }
+              else
+                value
+              end
+            else
+              value
+            end
+          end
+
+          def deep_compact(obj)
+            case obj
+            when Hash
+              obj.each_with_object({}) do |(k, v), result|
+                compacted = deep_compact(v)
+                unless compacted.nil?
+                  result[k] = compacted
+                end
+              end
+            when Array
+              obj.map { |v| deep_compact(v) }
+            when Definition
+              obj.to_h
+            else
+              obj
+            end
+          end
+      end
+    end
+  end
+end
+
+__END__
+
+describe "AgUi::Protocol::JsonSchema::Definition" do
+  schema = AgUi::Protocol::JsonSchema
+
+  it "exposes snake_case readers over camelCase storage" do
+    event = schema["ToolCallStartEvent"].new(
+      type: "TOOL_CALL_START", tool_call_id: "tc1", tool_call_name: "navigate"
+    )
+    event.tool_call_id.should == "tc1"
+    event.tool_call_name.should == "navigate"
+    event.to_h["toolCallId"].should == "tc1"
+  end
+
+  it "supports hash pattern matching with snake_case keys" do
+    event = schema["ToolCallStartEvent"].new(
+      type: "TOOL_CALL_START", tool_call_id: "tc1", tool_call_name: "navigate"
+    )
+
+    case event
+    in { tool_call_name: String => name }
+      name.should == "navigate"
+    end
+  end
+
+  it "wraps nested array refs into Definitions" do
+    msg = schema["AssistantMessage"].new(
+      id: "a1", role: "assistant",
+      tool_calls: [{ "id" => "tc1", "type" => "function",
+                     "function" => { "name" => "navigate", "arguments" => "{}" } }]
+    )
+    msg.tool_calls.first.should.be.kind_of(AgUi::Protocol::JsonSchema::Definition)
+    msg.to_h["toolCalls"].first["function"]["name"].should == "navigate"
+    msg.valid?.should == true
+  end
+
+  it "raises ValidationError with readable message on valid!" do
+    event = schema["ToolCallStartEvent"].new(type: "TOOL_CALL_START", tool_call_id: "tc1")
+
+    begin
+      event.valid!
+      raise "expected ValidationError"
+    rescue AgUi::Protocol::JsonSchema::ValidationError => e
+      e.message.should.include?("ToolCallStartEvent")
+      e.message.should.include?("toolCallName")
+    end
+  end
+end

data/lib/ag_ui/protocol/json_schema/validation_error.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "ag_ui"
+
+module AgUi
+  module Protocol
+    module JsonSchema
+      # Raised when a Definition instance fails schema validation.
+      # Ported from a2a. Collects JSONSchemer error details and formats
+      # them as a human-readable list with dot-notation field paths.
+      #
+      #   TextMessageContentEvent validation failed:
+      #     - delta is required but missing
+      #
+      class ValidationError < StandardError
+        attr_reader :errors, :definition_name, :data
+
+        def initialize(errors, definition_name:, data: nil)
+          @errors          = errors
+          @definition_name = definition_name
+          @data            = data
+
+          super(build_message)
+        end
+
+        private
+
+          def build_message
+            lines = errors.map { |e| "  - #{format_error(e)}" }
+            "#{definition_name} validation failed:\n#{lines.join("\n")}"
+          end
+
+          def format_error(error)
+            path  = format_path(error)
+            type  = error["type"]
+
+            case type
+            when "required"
+              missing = error.dig("details", "missing_keys")&.join(", ") || "unknown"
+              if path.empty?
+                "#{missing} is required but missing"
+              else
+                "#{path}.#{missing} is required but missing"
+              end
+            when "type"
+              expected = Array(error.dig("schema", "type")).join(" or ")
+              "#{path.empty? ? "(root)" : path} must be #{expected}"
+            when "enum"
+              allowed = error.dig("schema", "enum")&.join(", ") || "?"
+              "#{path.empty? ? "(root)" : path} must be one of: #{allowed}"
+            when "const"
+              "#{path.empty? ? "(root)" : path} must be #{error.dig("schema", "const").inspect}"
+            when "pattern"
+              pattern = error.dig("schema", "pattern")
+              "#{path.empty? ? "(root)" : path} must match pattern #{pattern}"
+            when "format"
+              fmt = error.dig("schema", "format")
+              "#{path.empty? ? "(root)" : path} must be a valid #{fmt}"
+            when "minimum", "maximum"
+              "#{path.empty? ? "(root)" : path} #{error["error"]}"
+            when "additionalProperties"
+              "#{path.empty? ? "(root)" : path} has unknown properties"
+            else
+              detail = error["error"] || error["type"] || "invalid"
+              "#{path.empty? ? "(root)" : path} #{detail}"
+            end
+          end
+
+          # Convert a JSON pointer like "/toolCalls/0/function" to
+          # dot notation like "toolCalls.0.function".
+          def format_path(error)
+            pointer = error["data_pointer"].to_s
+
+            if pointer.empty? || pointer == "/"
+              ""
+            else
+              pointer.delete_prefix("/").gsub("/", ".")
+            end
+          end
+      end
+    end
+  end
+end
+
+__END__
+
+describe "AgUi::Protocol::JsonSchema::ValidationError" do
+  error_data = [
+    {
+      "data_pointer" => "",
+      "type" => "required",
+      "details" => { "missing_keys" => ["delta"] },
+      "schema" => {},
+      "error" => "missing keys: delta"
+    }
+  ]
+
+  err = AgUi::Protocol::JsonSchema::ValidationError.new(
+    error_data, definition_name: "TextMessageContentEvent"
+  )
+
+  it "includes the definition name and formats required errors" do
+    err.message.should.include?("TextMessageContentEvent")
+    err.message.should.include?("delta is required but missing")
+  end
+
+  it "stores errors and definition name" do
+    err.errors.should == error_data
+    err.definition_name.should == "TextMessageContentEvent"
+  end
+
+  nested = AgUi::Protocol::JsonSchema::ValidationError.new(
+    [{ "data_pointer" => "/function/name", "type" => "type",
+       "schema" => { "type" => "string" }, "error" => "wrong type" }],
+    definition_name: "ToolCall"
+  )
+
+  it "formats nested paths with dot notation" do
+    nested.message.should.include?("function.name must be string")
+  end
+end