ag-ui 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff8366907501490461eb57be56e07c9054ac1632fea8ad6d47c6c3f5b1332cff
-  data.tar.gz: a40b14e97b6d6b9a09daa6016b98a5e19f23ab0594acd37315a5eddc2bebc55c
+  metadata.gz: 6092a88471f821fdd20d43bd3dad28205f114bb5b2068faea39234b4f1bc87da
+  data.tar.gz: 93566155eed8ad3464386a74b8d5afb6db6ea124eccac4bf6382b264e02733ec
 SHA512:
-  metadata.gz: e4a40843efccd8f2a995e86816e7108f34e069aac3698f44c94c3d07873fb1f194630f133dae9521abb30803b5420a93742af89c8bc884997521369ba3d368fc
-  data.tar.gz: 5fedf59e8db8548b66db608308c73733b863b09013640cf82139430f6b2b8ac4882baf638ae0fc240dcfd5cfe458c889edc957b9201e5196e30f07ad86847b94
+  metadata.gz: cf108e6f97a63801cf5b3a936241d187a3492bf8c92209ff0353d5e98ae68bb3752c05aedeffcb8f7a1deee0d91378128dc9608b3a4f997e8a98b9712412fc89
+  data.tar.gz: 541b3da611c70fdd1ec02b97dd9c8fad76d30f20e124d38800896d57b431a099c148d3635193ebef28aaae6d70b303989e41380abeb6c4e489820cd2fc1d6d1c

data/lib/ag_ui/event_bridge.rb

@@ -24,12 +24,19 @@ module AgUi
       tool_call_args: :translate_tool_call_args,
       tool_call_end: :translate_tool_call_end,
       tool_call_result: :translate_tool_call_result,
+      state_snapshot: :translate_state_snapshot,
+      state_delta: :translate_state_delta,
+      messages_snapshot: :translate_messages_snapshot,
       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,
+      step_started: :translate_step_started,
+      step_finished: :translate_step_finished,
+      custom: :translate_custom,
+      raw: :translate_raw,
     }.freeze
 
     def initialize(stream)
@@ -88,6 +95,40 @@ module AgUi
         )
       end
 
+      # Shared state (CoAgents). snapshot replaces the whole state; delta is a
+      # JSON Patch (RFC 6902) op array the client applies to its own store.
+      def translate_state_snapshot(data)
+        @stream.state_snapshot(snapshot: data[:snapshot])
+      end
+
+      def translate_state_delta(data)
+        @stream.state_delta(delta: data[:delta])
+      end
+
+      def translate_messages_snapshot(data)
+        @stream.messages_snapshot(messages: data[:messages])
+      end
+
+      # Structured progress markers (paired start/finish by step name).
+      def translate_step_started(data)
+        @stream.step_started(step_name: data[:step_name])
+      end
+
+      def translate_step_finished(data)
+        @stream.step_finished(step_name: data[:step_name])
+      end
+
+      # Escape hatches: CUSTOM carries app/agent-defined events (e.g. the
+      # "PredictState" convention for predictive state updates); RAW passes a
+      # framework event straight through.
+      def translate_custom(data)
+        @stream.custom(name: data[:name], value: data[:value])
+      end
+
+      def translate_raw(data)
+        @stream.raw(event: data[:event], source: data[:source])
+      end
+
       def translate_activity_snapshot(data)
         @stream.activity_snapshot(
           message_id: data[:message_id],
@@ -171,4 +212,36 @@ describe "AgUi::EventBridge" do
     result.should.equal?(bridge)
     read_frames.(stream).should == []
   end
+
+  it "translates shared-state events (snapshot + JSON-Patch delta)" do
+    stream = AgUi::Server::SSE::Stream.new(thread_id: "t1", run_id: "r1")
+    bridge = AgUi::EventBridge.new(stream)
+
+    bridge << { type: :state_snapshot, data: { snapshot: { "theme" => "dark" } } }
+    bridge << { type: :state_delta,
+                data: { delta: [{ "op" => "replace", "path" => "/theme", "value" => "light" }] } }
+    stream.finish
+
+    frames = read_frames.(stream)
+    frames.map { |f| f["type"] }.should == %w[STATE_SNAPSHOT STATE_DELTA]
+    frames[0]["snapshot"].should == { "theme" => "dark" }
+    frames[1]["delta"].first["path"].should == "/theme"
+  end
+
+  it "translates CUSTOM (e.g. the PredictState convention) and STEP markers" do
+    stream = AgUi::Server::SSE::Stream.new(thread_id: "t1", run_id: "r1")
+    bridge = AgUi::EventBridge.new(stream)
+
+    bridge << { type: :step_started, data: { step_name: "plan" } }
+    bridge << { type: :custom,
+                data: { name: "PredictState",
+                        value: [{ "state_key" => "document", "tool" => "write" }] } }
+    bridge << { type: :step_finished, data: { step_name: "plan" } }
+    stream.finish
+
+    frames = read_frames.(stream)
+    frames.map { |f| f["type"] }.should == %w[STEP_STARTED CUSTOM STEP_FINISHED]
+    frames[0]["stepName"].should == "plan"
+    frames[1]["name"].should == "PredictState"
+  end
 end

data/lib/ag_ui/middleware/state.rb

@@ -0,0 +1,341 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "securerandom"
+require "hana"
+require "ag_ui"
+
+module AgUi
+  module Middleware
+    # Shared state (CoAgents) — the Ruby side of AG-UI's STATE_SNAPSHOT /
+    # STATE_DELTA channel (doc 05). Bidirectional state sync between the
+    # frontend's `agent.state` and the running agent.
+    #
+    # Way in:
+    #   - seeds env[:state] from RunAgentInput.state (the state the frontend
+    #     last held, pushed via agent.setState) so downstream middleware,
+    #     tools, and the app can READ what the UI currently shows
+    #   - injects two tools the model calls to WRITE state:
+    #       AGUISendStateSnapshot({ snapshot })  — replace the whole state
+    #       AGUISendStateDelta({ delta })        — RFC 6902 JSON Patch ops
+    #
+    # Way out, per state-tool call the model made:
+    #   - snapshot: env[:state] = snapshot; emits STATE_SNAPSHOT
+    #   - delta:    patches env[:state] (Hana); emits STATE_DELTA
+    #   - both append a {"status":"ok"} :tool message and emit a
+    #     TOOL_CALL_RESULT — the same shape a server tool produces — then let
+    #     the run CONTINUE (unlike a browser/client tool) so the model can act
+    #     on the new state or confirm to the user. State tools are server-side.
+    #
+    # The TOOL_CALL_START/ARGS/END chrome is left to ToolRouter (it advertises
+    # nothing about these being "client" vs "server" — it just streams the
+    # call), exactly as A2ui leaves its render_a2ui call to ToolRouter. Compose
+    # State OUTSIDE ToolRouter:
+    #
+    #   use Loop::ToolResult
+    #   use State, state: input.state
+    #   use ToolRouter, tools: input.tools
+    #
+    # The frontend applies the same snapshot/patch to its own store; env[:state]
+    # is kept coherent so the agent's own later reads (and further deltas) see
+    # the current value.
+    class State
+      SNAPSHOT_TOOL = "AGUISendStateSnapshot"
+      DELTA_TOOL    = "AGUISendStateDelta"
+      TOOL_NAMES    = [SNAPSHOT_TOOL, DELTA_TOOL].freeze
+
+      SNAPSHOT_DEFINITION = {
+        "name" => SNAPSHOT_TOOL,
+        "description" =>
+          "Replace the shared application state with a new snapshot; the " \
+          "frontend re-renders from it. Send the COMPLETE next state object, " \
+          "not a diff. Prefer AGUISendStateDelta for small targeted changes.",
+        "parameters" => {
+          "type" => "object",
+          "properties" => {
+            "snapshot" => {
+              "type" => "object",
+              "description" => "The complete new application state.",
+            },
+          },
+          "required" => %w[snapshot],
+        },
+      }.freeze
+
+      DELTA_DEFINITION = {
+        "name" => DELTA_TOOL,
+        "description" =>
+          "Apply a JSON Patch (RFC 6902) to the shared application state — an " \
+          "array of {op, path, value} operations. Use for small, targeted " \
+          "changes. Paths are JSON Pointers, e.g. " \
+          "\"/documentEditor/activeTabId\". ops: add, replace, remove, move, " \
+          "copy, test.",
+        "parameters" => {
+          "type" => "object",
+          "properties" => {
+            "delta" => {
+              "type" => "array",
+              "description" =>
+                "JSON Patch operations, e.g. " \
+                "[{\"op\":\"replace\",\"path\":\"/theme\",\"value\":\"dark\"}].",
+              "items" => { "type" => "object" },
+            },
+          },
+          "required" => %w[delta],
+        },
+      }.freeze
+
+      def initialize(app, state: nil)
+        @app = app
+        @initial_state = normalize(state)
+      end
+
+      def call(env)
+        seed_state(env)
+        advertise(env)
+
+        before = env[:messages].length
+        @app.call(env)
+
+        # Only this iteration's assistant message — seeded history can carry
+        # old state-tool turns that must not re-emit.
+        appended = env[:messages][before..] || []
+        assistant = appended.reverse.find { |m| m.respond_to?(:tool_call?) && m.tool_call? }
+        if assistant
+          apply_state_calls(env, assistant)
+        end
+
+        env
+      end
+
+      private
+
+        def apply_state_calls(env, assistant)
+          state_calls = assistant.tool_calls.select { |tc| TOOL_NAMES.include?(tc.name) }
+          unless state_calls.empty?
+            state_calls.each { |tool_call| handle(env, tool_call) }
+
+            # State tools don't end the run — they're server-side, not browser
+            # tools — so let Loop::ToolResult continue (last message is now
+            # :tool). Only override the exit for a PURE state turn; a real
+            # client tool mixed in still ends the run so the browser runs it.
+            if assistant.tool_calls.all? { |tc| TOOL_NAMES.include?(tc.name) }
+              env[:should_exit] = false
+            end
+          end
+        end
+
+        def seed_state(env)
+          unless env.key?(:state)
+            env[:state] = @initial_state
+          end
+        end
+
+        # Idempotent — the turn loop re-enters every iteration.
+        def advertise(env)
+          env[:tools] ||= []
+          names = env[:tools].map { |t| t.is_a?(Hash) ? t["name"] : nil }
+          [SNAPSHOT_DEFINITION, DELTA_DEFINITION].each do |definition|
+            unless names.include?(definition["name"])
+              env[:tools] << definition
+            end
+          end
+        end
+
+        def handle(env, tool_call)
+          case tool_call.name
+          when SNAPSHOT_TOOL then apply_snapshot(env, tool_call)
+          when DELTA_TOOL    then apply_delta(env, tool_call)
+          end
+        end
+
+        def apply_snapshot(env, tool_call)
+          snapshot = tool_call.arguments["snapshot"]
+          if snapshot.is_a?(Hash)
+            env[:state] = snapshot
+            env[:events] << { type: :state_snapshot, data: { snapshot: snapshot } }
+            ack(env, tool_call)
+          else
+            ack(env, tool_call, error: "snapshot must be an object")
+          end
+        end
+
+        def apply_delta(env, tool_call)
+          delta = tool_call.arguments["delta"]
+          if delta.is_a?(Array)
+            patch_state(env, tool_call, delta)
+          else
+            ack(env, tool_call, error: "delta must be an array of JSON Patch operations")
+          end
+        end
+
+        # Keep our copy coherent for later reads/deltas; the frontend applies
+        # the same patch to its own store. A bad patch is reported back to the
+        # model as a tool error rather than raising the run.
+        def patch_state(env, tool_call, delta)
+          patched = Hana::Patch.new(delta).apply(deep_dup(env[:state] || {}))
+        rescue StandardError => e
+          ack(env, tool_call, error: "invalid JSON Patch: #{e.message}")
+        else
+          env[:state] = patched
+          env[:events] << { type: :state_delta, data: { delta: delta } }
+          ack(env, tool_call)
+        end
+
+        # Append the tool result (so the assistant tool-call has its matching
+        # :tool message and Loop::ToolResult continues) and emit TOOL_CALL_RESULT
+        # on the wire — the exact shape server tools produce.
+        def ack(env, tool_call, error: nil)
+          content = error ? { "status" => "error", "error" => error } : { "status" => "ok" }
+          json = JSON.generate(content)
+          env[:messages].tool(json, tool_call_id: tool_call.id)
+          env[:events] << {
+            type: :tool_call_result,
+            data: {
+              message_id: SecureRandom.uuid,
+              tool_call_id: tool_call.id,
+              content: json,
+            },
+          }
+        end
+
+        def normalize(state)
+          if state.nil?
+            nil
+          elsif state.respond_to?(:to_h)
+            state.to_h
+          else
+            state
+          end
+        end
+
+        def deep_dup(obj)
+          case obj
+          when Hash  then obj.each_with_object({}) { |(k, v), h| h[k] = deep_dup(v) }
+          when Array then obj.map { |v| deep_dup(v) }
+          else obj
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+describe "AgUi::Middleware::State" do
+  snapshot_call = ->(args) do
+    Brute::Message.new(
+      role: :assistant, content: nil,
+      tool_calls: [{ id: "tc1", name: "AGUISendStateSnapshot", arguments: args }],
+    )
+  end
+
+  delta_call = ->(args) do
+    Brute::Message.new(
+      role: :assistant, content: nil,
+      tool_calls: [{ id: "tc1", name: "AGUISendStateDelta", arguments: args }],
+    )
+  end
+
+  it "advertises both state tools idempotently and seeds env[:state] from input" do
+    seen = nil
+    mw = AgUi::Middleware::State.new(->(env) { seen = env }, state: { "theme" => "light" })
+    env = { messages: Brute.log, events: [], tools: [{ "name" => "navigate" }] }
+    mw.call(env)
+    mw.call(env) # second loop iteration — no dupes
+
+    seen[:tools].map { |t| t["name"] }.should ==
+      %w[navigate AGUISendStateSnapshot AGUISendStateDelta]
+    seen[:state].should == { "theme" => "light" }
+  end
+
+  it "seeds from a Definition-like state via to_h" do
+    definition = Object.new
+    def definition.to_h = { "count" => 1 }
+    seen = nil
+    AgUi::Middleware::State.new(->(env) { seen = env }, state: definition)
+      .call({ messages: Brute.log, events: [], tools: [] })
+    seen[:state].should == { "count" => 1 }
+  end
+
+  it "AGUISendStateSnapshot: sets state, emits STATE_SNAPSHOT + result, continues the run" do
+    terminal = ->(env) { env[:messages] << snapshot_call.("snapshot" => { "count" => 3 }) }
+    env = { messages: Brute.log, events: [], tools: [], should_exit: true }
+    AgUi::Middleware::State.new(terminal).call(env)
+
+    env[:state].should == { "count" => 3 }
+    env[:events].map { |e| e[:type] }.should == %i[state_snapshot tool_call_result]
+    env[:events][0][:data][:snapshot].should == { "count" => 3 }
+    env[:messages].last.role.should == :tool
+    env[:messages].last.tool_call_id.should == "tc1"
+    env[:messages].last.content.should == "{\"status\":\"ok\"}"
+    env[:should_exit].should == false
+  end
+
+  it "AGUISendStateDelta: patches state (Hana), emits STATE_DELTA with the raw ops" do
+    delta = [{ "op" => "replace", "path" => "/theme", "value" => "dark" }]
+    terminal = ->(env) { env[:messages] << delta_call.("delta" => delta) }
+    env = { messages: Brute.log, events: [], tools: [], state: { "theme" => "light" }, should_exit: true }
+    AgUi::Middleware::State.new(terminal).call(env)
+
+    env[:state].should == { "theme" => "dark" }
+    env[:events].map { |e| e[:type] }.should == %i[state_delta tool_call_result]
+    env[:events][0][:data][:delta].should == delta
+    env[:should_exit].should == false
+  end
+
+  it "adds a nested key via delta against seeded state" do
+    delta = [{ "op" => "add", "path" => "/documentEditor", "value" => { "activeTabId" => "doc-2" } }]
+    terminal = ->(env) { env[:messages] << delta_call.("delta" => delta) }
+    env = { messages: Brute.log, events: [], tools: [], should_exit: true }
+    AgUi::Middleware::State.new(terminal, state: { "documentEditor" => { "activeTabId" => "doc-1" } })
+      .call(env)
+
+    env[:state].should == { "documentEditor" => { "activeTabId" => "doc-2" } }
+    env[:events][0][:type].should == :state_delta
+  end
+
+  it "reports a bad patch back to the model as a tool error, no STATE_DELTA emitted" do
+    delta = [{ "op" => "replace", "path" => "/missing/deep", "value" => 1 }]
+    terminal = ->(env) { env[:messages] << delta_call.("delta" => delta) }
+    env = { messages: Brute.log, events: [], tools: [], state: {}, should_exit: true }
+    AgUi::Middleware::State.new(terminal).call(env)
+
+    env[:events].map { |e| e[:type] }.should == %i[tool_call_result]
+    JSON.parse(env[:events][0][:data][:content])["status"].should == "error"
+    env[:messages].last.role.should == :tool
+  end
+
+  it "rejects a non-array delta and a non-object snapshot as tool errors" do
+    [delta_call.("delta" => "nope"), snapshot_call.("snapshot" => "nope")].each do |msg|
+      terminal = ->(env) { env[:messages] << msg }
+      env = { messages: Brute.log, events: [], tools: [] }
+      AgUi::Middleware::State.new(terminal).call(env)
+      JSON.parse(env[:events].last[:data][:content])["status"].should == "error"
+    end
+  end
+
+  it "leaves should_exit set when a real client tool is mixed into the turn" do
+    terminal = ->(env) do
+      env[:messages] << Brute::Message.new(
+        role: :assistant, content: nil,
+        tool_calls: [
+          { id: "tc1", name: "AGUISendStateSnapshot", arguments: { "snapshot" => { "a" => 1 } } },
+          { id: "tc2", name: "navigate", arguments: { "path" => "/x" } },
+        ],
+      )
+    end
+    env = { messages: Brute.log, events: [], tools: [], should_exit: true }
+    AgUi::Middleware::State.new(terminal).call(env)
+
+    env[:events].any? { |e| e[:type] == :state_snapshot }.should == true
+    env[:should_exit].should == true # browser still needs to run navigate
+  end
+
+  it "does nothing on a plain text turn" do
+    env = { messages: Brute.log, events: [], tools: [] }
+    AgUi::Middleware::State.new(->(e) { e[:messages].assistant("hi") }).call(env)
+    env[:events].should == []
+    env.key?(:should_exit).should == false
+  end
+end

data/lib/ag_ui/terminals/ruby_llm.rb

@@ -14,8 +14,8 @@ module AgUi
     #   require "ag_ui/terminals/ruby_llm"
     #
     #   RubyLLM.configure { |c| c.anthropic_api_key = ENV["ANTHROPIC_API_KEY"] }
-    #   run_loop = AgUi::RunLoop.new(system_prompt: PROMPT,
-    #                                &AgUi::Terminals::RubyLLM.new)
+    #   terminal = AgUi::Terminals::RubyLLM.new
+    #   agent = Brute.agent.use(...).run(terminal)   # standard Brute agent
     #
     # One assistant turn per call: seeds the chat from env[:messages]
     # (including prior tool-call turns), registers env[:tools] as
@@ -517,7 +517,7 @@ describe "AgUi::Terminals::RubyLLM" do
     captured.should == [[:anthropic, "claude-sonnet-4-5"], [:anthropic, "claude-sonnet-4-5"]]
   end
 
-  it "drives the full client-tool run through RunLoop + ToolRouter" do
+  it "drives the full client-tool run through a standard Brute agent + ToolRouter" do
     tool_calls = {
       "tc1" => ::RubyLLM::ToolCall.new(id: "tc1", name: "navigate",
                                        arguments: { "path" => "/data" }),
@@ -525,8 +525,23 @@ describe "AgUi::Terminals::RubyLLM" do
     fake = fake_chat_class.new(final: nil, tool_calls: tool_calls)
     terminal = AgUi::Terminals::RubyLLM.new(chat_factory: ->(**) { fake })
 
-    run_loop = AgUi::RunLoop.new(system_prompt: "Be terse.", &terminal)
-    app = AgUi.agent(agent_id: "default", &run_loop)
+    app = AgUi.agent(agent_id: "default") do |env|
+      input = env["ag_ui.input"]
+      agent = Brute.agent
+                   .use(AgUi::Middleware::SystemPrompt, prompt: "Be terse.", context: input.context)
+                   .use(AgUi::Middleware::ForwardedProps, props: input.forwarded_props)
+                   .use(Brute::Middleware::Loop::ToolResult)
+                   .use(Brute::Middleware::MaxIterations, max_iterations: 10)
+                   .use(AgUi::Middleware::ToolRouter, tools: input.tools, server_tools: [])
+                   .run(terminal)
+      env["ag_ui.stream"].open(thread_id: input.thread_id, run_id: input.run_id) do |stream|
+        stream.run_started
+        agent.start(AgUi::Messages.to_brute(input.messages), events: AgUi::EventBridge.new(stream))
+        stream.run_finished
+      rescue => e
+        stream.run_error(message: e.message, code: e.class.name)
+      end
+    end
 
     body = JSON.generate({
       "threadId" => "t1", "runId" => "r1", "state" => nil,

data/lib/ag_ui/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AgUi
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/ag_ui.rb

@@ -25,8 +25,8 @@ require "ag_ui/event_bridge"
 require "ag_ui/middleware/system_prompt"
 require "ag_ui/middleware/forwarded_props"
 require "ag_ui/middleware/tool_router"
+require "ag_ui/middleware/state"
 require "ag_ui/a2ui/catalog"
 require "ag_ui/a2ui/validate"
 require "ag_ui/a2ui/recovery"
 require "ag_ui/middleware/a2ui"
-require "ag_ui/run_loop"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ag-ui
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - AgUi Contributors
@@ -65,6 +65,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: hana
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: brute
   requirement: !ruby/object:Gem::Requirement
@@ -200,13 +214,13 @@ files:
 - lib/ag_ui/messages.rb
 - lib/ag_ui/middleware/a2ui.rb
 - lib/ag_ui/middleware/forwarded_props.rb
+- lib/ag_ui/middleware/state.rb
 - lib/ag_ui/middleware/system_prompt.rb
 - lib/ag_ui/middleware/tool_router.rb
 - lib/ag_ui/protocol/json_schema.rb
 - lib/ag_ui/protocol/json_schema/definition.rb
 - lib/ag_ui/protocol/json_schema/validation_error.rb
 - lib/ag_ui/run_input.rb
-- lib/ag_ui/run_loop.rb
 - lib/ag_ui/run_store.rb
 - lib/ag_ui/server.rb
 - lib/ag_ui/server/info.rb

data/lib/ag_ui/run_loop.rb

@@ -1,285 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/setup"
-require "console"
-require "ag_ui"
-
-module AgUi
-  # The run loop: drives one AG-UI run through a brute turn pipeline.
-  #
-  # The terminal block is the LLM call (ruby_llm or anything else) — it
-  # receives brute's env ({messages:, events:, ...}), streams deltas into
-  # env[:events] (translated live to SSE by EventBridge) and appends the
-  # assistant message to env[:messages]. The gem stays LLM-agnostic.
-  #
-  #   run_loop = AgUi::RunLoop.new(system_prompt: PROMPT) do |env|
-  #     env[:events] << { type: :text_message_start, data: { message_id: id } }
-  #     ... stream provider chunks ...
-  #     env[:events] << { type: :text_message_end, data: { message_id: id } }
-  #     env[:messages].assistant(full_text)
-  #   end
-  #
-  #   app = AgUi.agent(agent_id: "default", &run_loop)
-  #
-  # Lifecycle per run (the AG-UI contract): RUN_STARTED first; then the
-  # pipeline streams; then RUN_FINISHED — or RUN_ERROR if the pipeline
-  # raised. Schema-validation failures are wire-contract bugs and re-raise
-  # after RUN_ERROR so they fail loudly in dev.
-  class RunLoop
-    # a2ui: nil/false = off; an AgUi::A2ui::Catalog = on with that catalog;
-    # true = on degraded (tool injected, no component schema).
-    # server_tools: [{name:, description:, parameters:, handler:}] execute
-    # inline and the turn loops (Loop::ToolResult) until the model answers
-    # in text, a client tool defers to the browser, or max_iterations hits.
-    def initialize(system_prompt: nil, validate: true, middleware: [], a2ui: nil,
-                   server_tools: [], max_iterations: 10, &terminal)
-      unless terminal
-        raise ArgumentError, "RunLoop requires a terminal block (the LLM call)"
-      end
-
-      @system_prompt = system_prompt
-      @validate = validate
-      @middleware = middleware
-      @a2ui = a2ui
-      @server_tools = server_tools
-      @max_iterations = max_iterations
-      @terminal = terminal
-    end
-
-    def a2ui_enabled?
-      !(@a2ui.nil? || @a2ui == false)
-    end
-
-    # AgUi.agent takes a block; RunLoop quacks like one.
-    def to_proc
-      run_loop = self
-      proc { |rack_env| run_loop.handle(rack_env) }
-    end
-
-    def handle(rack_env)
-      input = rack_env["ag_ui.input"]
-
-      rack_env["ag_ui.stream"].open(
-        thread_id: input.thread_id,
-        run_id: input.run_id,
-        validate: @validate,
-      ) do |stream|
-        stream.run_started
-        run(stream, input)
-      end
-    end
-
-    private
-
-      def run(stream, input)
-        pipeline(input).start(
-          Messages.to_brute(input.messages),
-          events: EventBridge.new(stream),
-        )
-        stream.run_finished
-      rescue Protocol::JsonSchema::ValidationError => e
-        Console.error(self, "wire-contract bug: #{e.message}", e)
-        stream.run_error(message: "Internal error", code: "validation")
-        raise
-      rescue => e
-        Console.error(self, "run failed: #{e.class}: #{e.message}", e)
-        stream.run_error(message: e.message, code: e.class.name)
-      end
-
-      def pipeline(input)
-        agent = Brute.agent
-        agent.use(
-          AgUi::Middleware::SystemPrompt,
-          prompt: @system_prompt,
-          context: input.context,
-        )
-        agent.use(AgUi::Middleware::ForwardedProps, props: input.forwarded_props)
-        agent.use(Brute::Middleware::Loop::ToolResult)
-        agent.use(Brute::Middleware::MaxIterations, max_iterations: @max_iterations)
-        if a2ui_enabled?
-          catalog = @a2ui.is_a?(AgUi::A2ui::Catalog) ? @a2ui : nil
-          agent.use(AgUi::Middleware::A2ui, catalog: catalog)
-        end
-        agent.use(AgUi::Middleware::ToolRouter, tools: input.tools, server_tools: @server_tools)
-        @middleware.each do |(klass, options)|
-          agent.use(klass, **(options || {}))
-        end
-        agent.run(@terminal)
-      end
-  end
-end
-
-__END__
-
-describe "AgUi::RunLoop" do
-  minimal_input = JSON.generate({
-    "threadId" => "t1", "runId" => "r1", "state" => nil,
-    "messages" => [{ "id" => "u1", "role" => "user", "content" => "hi" }],
-    "tools" => [], "context" => [{ "description" => "currentPath", "value" => "/data" }],
-    "forwardedProps" => nil,
-  })
-
-  request = ->(app, body) do
-    app.call({
-      "REQUEST_METHOD" => "POST",
-      "PATH_INFO" => "/agent/default/run",
-      "rack.input" => StringIO.new(body),
-    })
-  end
-
-  read_frames = ->(stream) do
-    frames = []
-    while (chunk = stream.read)
-      frames << JSON.parse(chunk.sub(/\Adata: /, "").strip)
-    end
-    frames
-  end
-
-  it "streams a full run through a brute pipeline" do
-    seen_env = nil
-    run_loop = AgUi::RunLoop.new(system_prompt: "Be terse.") do |env|
-      seen_env = env
-      env[:events] << { type: :text_message_start, data: { message_id: "m1" } }
-      env[:events] << { type: :text_message_content, data: { message_id: "m1", delta: "Hello" } }
-      env[:events] << { type: :text_message_end, data: { message_id: "m1" } }
-      env[:messages].assistant("Hello")
-    end
-
-    app = AgUi.agent(agent_id: "default", &run_loop)
-    _status, _headers, body = request.(app, minimal_input)
-
-    frames = read_frames.(body)
-    frames.map { |f| f["type"] }.should == %w[
-      RUN_STARTED TEXT_MESSAGE_START TEXT_MESSAGE_CONTENT TEXT_MESSAGE_END RUN_FINISHED
-    ]
-
-    # The pipeline saw: system prompt (with context addendum) + history.
-    seen_env[:messages].map(&:role).should == [:system, :user, :assistant]
-    seen_env[:messages].first.content.should.include?("Be terse.")
-    seen_env[:messages].first.content.should.include?("currentPath: /data")
-  end
-
-  it "ends the run with RUN_ERROR when the terminal raises" do
-    run_loop = AgUi::RunLoop.new { |_env| raise "provider exploded" }
-    app = AgUi.agent(agent_id: "default", &run_loop)
-
-    _status, _headers, body = request.(app, minimal_input)
-    frames = read_frames.(body)
-
-    frames.map { |f| f["type"] }.should == %w[RUN_STARTED RUN_ERROR]
-    frames.last["message"].should == "provider exploded"
-    frames.last["code"].should == "RuntimeError"
-  end
-
-  it "supports extra brute middleware" do
-    marker = Class.new do
-      def initialize(app, note:)
-        @app = app
-        @note = note
-      end
-
-      def call(env)
-        env[:metadata][:note] = @note
-        @app.call(env)
-      end
-    end
-
-    seen = nil
-    run_loop = AgUi::RunLoop.new(middleware: [[marker, { note: "hi" }]]) do |env|
-      seen = env[:metadata][:note]
-      env[:messages].assistant("ok")
-    end
-
-    request.(AgUi.agent(&run_loop), minimal_input)
-    seen.should == "hi"
-  end
-
-  it "requires a terminal block" do
-    lambda { AgUi::RunLoop.new }.should.raise(ArgumentError)
-  end
-
-  it "executes server tools inline and loops the turn to completion" do
-    weather_tool = {
-      name: "get_weather",
-      description: "Weather for a city",
-      parameters: { "type" => "object" },
-      handler: ->(args) { { "city" => args["city"], "temp" => 21 } },
-    }
-
-    iterations = 0
-    terminal = ->(env) do
-      iterations += 1
-      if iterations == 1
-        env[:messages] << Brute::Message.new(
-          role: :assistant, content: nil,
-          tool_calls: [{ id: "tc1", name: "get_weather", arguments: { "city" => "Lisbon" } }],
-        )
-      else
-        # The model sees its own call + the executed result.
-        env[:messages].last.role.should == :tool
-        env[:messages].last.content.should == "{\"city\":\"Lisbon\",\"temp\":21}"
-        env[:events] << { type: :text_message_start, data: { message_id: "m2" } }
-        env[:events] << { type: :text_message_content, data: { message_id: "m2", delta: "21C in Lisbon" } }
-        env[:events] << { type: :text_message_end, data: { message_id: "m2" } }
-        env[:messages].assistant("21C in Lisbon")
-      end
-    end
-
-    run_loop = AgUi::RunLoop.new(server_tools: [weather_tool], &terminal)
-    app = AgUi.agent(agent_id: "default", &run_loop)
-
-    _status, _headers, stream = request.(app, minimal_input)
-    frames = read_frames.(stream)
-
-    iterations.should == 2
-    frames.map { |f| f["type"] }.should == %w[
-      RUN_STARTED
-      TOOL_CALL_START TOOL_CALL_ARGS TOOL_CALL_END TOOL_CALL_RESULT
-      TEXT_MESSAGE_START TEXT_MESSAGE_CONTENT TEXT_MESSAGE_END
-      RUN_FINISHED
-    ]
-    frames[4]["content"].should == "{\"city\":\"Lisbon\",\"temp\":21}"
-  end
-
-  it "streams the full A2UI sequence when the model renders a surface" do
-    catalog = AgUi::A2ui::Catalog.new(
-      catalog_id: "host://ai-catalog",
-      components: { "Card" => {} },
-    )
-
-    terminal = ->(env) do
-      env[:tools].map { |t| t["name"] }.should.include?("render_a2ui")
-      env[:messages].first.content.should.include?("A2UI Component Schema")
-
-      env[:messages] << Brute::Message.new(
-        role: :assistant, content: nil,
-        tool_calls: [{ id: "tc9", name: "render_a2ui", arguments: {
-          "surfaceId" => "s1",
-          "components" => [{ "id" => "root", "component" => "Card" }],
-        } }],
-      )
-    end
-
-    run_loop = AgUi::RunLoop.new(a2ui: catalog, &terminal)
-    app = AgUi.agent(agent_id: "default", &run_loop)
-
-    _status, _headers, stream = request.(app, minimal_input)
-    frames = read_frames.(stream)
-
-    frames.map { |f| f["type"] }.should == %w[
-      RUN_STARTED TOOL_CALL_START TOOL_CALL_ARGS TOOL_CALL_END
-      ACTIVITY_SNAPSHOT TOOL_CALL_RESULT RUN_FINISHED
-    ]
-
-    snapshot = frames[4]
-    snapshot["messageId"].should == "a2ui-surface-tc9"
-    snapshot["activityType"].should == "a2ui-surface"
-    snapshot["replace"].should == true
-    snapshot["content"]["a2ui_operations"][0]["createSurface"]["catalogId"]
-      .should == "host://ai-catalog"
-
-    result = frames[5]
-    result["toolCallId"].should == "tc9"
-    result["content"].should == "{\"status\":\"rendered\"}"
-  end
-end