ask-ag-ui 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a496b953fbbbf38bde6bfb2cc1771fc67d8b47a8ed6789ef453e18b8a7d68161
+  data.tar.gz: 94edd256f17e7b5de58a3de085d2d857adc06ec35bb58e83d1e9f92feac457bc
+SHA512:
+  metadata.gz: 711674f104ef94ed5c9e44293781b74970beaf08222cec1e42865bf304b70e8a94ce80849c0f1884f5d4be254d841dfb85547d610d15892d23c61f17bbe76496
+  data.tar.gz: cafe0507a38288621887eb3d31cb663676326d4da15814fd4716cd16fd2c045d9587347ed97c421cb71ecf979a6add14775b5bdc52a34f829f5ddca3f1a923af

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to ask-ag-ui are documented here, following
+the keep-a-changelog format.
+
+## [Unreleased]
+
+## [0.1.0] — 2026-09-28
+
+### Added
+
+- `Ask::AGUI::Emitter` — the seam that turns ask-rb agent/session events
+  into AG-UI protocol frames. Given the run context (thread id, run id,
+  input messages) and a stream of duck-typed agent events, it emits
+  `RUN_STARTED`, the text/reasoning/tool-call chains, `RUN_FINISHED` /
+  `RUN_ERROR`, and a generic `CUSTOM` passthrough for app-defined events.
+  All frames are built with `AgUiProtocol::Core::Events::*` and encoded
+  with `AgUiProtocol::Encoder::EventEncoder`. Adds the `ag-ui-protocol`
+  runtime dependency.
+- `Ask::AGUI::Server` — the mountable Rack surface AG-UI clients expect:
+  `GET /info` (agents map with name, class, and capability information
+  built from ag-ui-protocol's capability and identity types, plus the
+  transport mode), `POST /agent/:id/run` (parses the run input, drives one
+  `Emitter` for the run, streams its SSE frames as the host block's agent
+  events arrive; malformed input answers 400 JSON),
+  `POST /agent/:id/connect` (replays recorded frames, completing
+  immediately when there is nothing to replay), and
+  `POST /agent/:id/stop/:thread_id` (JSON acknowledgement with cooperative
+  cancel). The host supplies the work as a block; the gem owns the socket
+  and the framing, with no Rails or ask-agent dependency. Plain Rack 3 and
+  plain Ruby — an enumerable body, no async or falcon requirement.
+- `Ask::AGUI::Run` — the parsed run input handed to the host block
+  (thread id, run id, messages, tools, context, forwarded props, state),
+  with best-effort coercion to `AgUiProtocol::Core::Types`.
+- `Ask::AGUI::RunStore` — the run-store interface plus the in-memory
+  implementation backing replay and stop. In-memory frames live in one
+  process only; back replay and stop with a shared store past one process.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,125 @@
+# ask-ag-ui
+
+[![Gem Version](https://badge.fury.io/rb/ask-ag-ui.svg)](https://badge.fury.io/rb/ask-ag-ui)
+
+The AG-UI (Agent-User Interaction) protocol server for the ask-rb ecosystem — SSE event streaming and the runtime surface that assistant-ui and CopilotKit frontends expect.
+
+## Installation
+
+```ruby
+gem "ask-ag-ui"
+```
+
+## Quick Start
+
+```ruby
+require "ask-ag-ui"
+
+Ask::AGUI::VERSION  # => "0.1.0"
+```
+
+## The seam: `Ask::AGUI::Emitter`
+
+The emitter turns ask-rb agent/session events into AG-UI protocol frames.
+A transport drives one emitter per run: it hands over the AG-UI run context,
+feeds it agent events, and writes the SSE frames it answers to the stream.
+The transport owns the socket — the emitter only translates and encodes.
+
+```ruby
+require "ask-ag-ui"
+
+messages = [AgUiProtocol::Core::Types::UserMessage.new(id: "u1", content: "Hi")]
+emitter = Ask::AGUI::Emitter.new(thread_id: "t1", run_id: "r1", messages: messages)
+
+emitter.handle(turn_start_event).each { |frame| stream.write(frame) }
+# => ["data: {\"type\":\"RUN_STARTED\",...}\n\n", ...]
+
+emitter.finish.each { |frame| stream.write(frame) }
+# => ["data: {\"type\":\"RUN_FINISHED\",...}\n\n"]
+```
+
+The vocabulary, matched by class name so the emitter never depends on
+ask-agent internals:
+
+| Agent event | AG-UI events |
+|---|---|
+| `TurnStart` | `RUN_STARTED` |
+| `TextDelta` | `TEXT_MESSAGE_START` → `TEXT_MESSAGE_CONTENT` → `TEXT_MESSAGE_END` (only empty deltas dropped — a space is content) |
+| `ThinkingDelta` | `REASONING_START` → `REASONING_MESSAGE_START` → `REASONING_MESSAGE_CONTENT` → `REASONING_MESSAGE_END` → `REASONING_END` (empty deltas dropped) |
+| `ToolCallDelta`, `ToolExecutionStart`, `ToolExecutionEnd` | `TOOL_CALL_START` → `TOOL_CALL_ARGS` → `TOOL_CALL_END` → `TOOL_CALL_RESULT` (empty args deltas dropped) |
+| `SessionEnd` / `#finish` | `RUN_FINISHED` |
+| `Error` / `#fail` | `RUN_ERROR` |
+| anything else | one generic `CUSTOM` passthrough (`name` + `value`) |
+
+Every frame is built with `AgUiProtocol::Core::Events::*` and encoded with
+`AgUiProtocol::Encoder::EventEncoder` — event JSON is never hand-rolled.
+
+## Mounting: `Ask::AGUI::Server`
+
+The server is the conventional Rack surface AG-UI clients expect. The host
+owns the agent and answers agent events; the gem owns the socket, the
+framing, and one `Emitter` per run. Plain Rack 3 with an enumerable body —
+it runs under any Rack server, with no Rails, ask-agent, or async
+dependency.
+
+```ruby
+require "ask-ag-ui"
+
+app = Ask::AGUI::Server.new(agent_id: "default") do |run|
+  # run.thread_id, run.run_id, run.messages, run.tools,
+  # run.context, run.forwarded_props — answer agent events:
+  [TurnStart.new, TextDelta.new(content: "Hello")]
+end
+```
+
+Rackup:
+
+```ruby
+# config.ru
+require "ask-ag-ui"
+
+run Ask::AGUI::Server.new(agent_id: "default") { |run| MyAgent.events_for(run) }
+```
+
+Rails:
+
+```ruby
+# config/routes.rb
+mount Ask::AGUI::Server.new(agent_id: "default") { |run| MyAgent.events_for(run) },
+  at: "/api/copilotkit"
+```
+
+Routes: `GET /info`, `POST /agent/:id/run` (SSE), `POST /agent/:id/connect`
+(replays recorded frames, or an immediately-completed empty stream when
+there is nothing to replay), `POST /agent/:id/stop/:thread_id` (JSON ack).
+Malformed run input answers `400` with a JSON error body.
+
+One curl example (run a thread through the stub above):
+
+```
+curl -N -X POST http://localhost:9292/agent/default/run \
+  -H 'Content-Type: application/json' \
+  -d '{"threadId":"t1","runId":"r1","messages":[{"id":"u1","role":"user","content":"Hi"}],"tools":[],"context":[]}'
+```
+
+The in-memory run store keeps frames in this process only — replay and
+stop need a shared store once you run more than one process.
+
+## Development
+
+```
+bundle install
+bundle exec rake test
+```
+
+The suite validates every emitted SSE frame against the AG-UI protocol's
+canonical JSON Schema, vendored at `test/fixtures/ag_ui.json` (generated
+from the reference Python SDK; the copy came from the reference
+implementation's `data/ag_ui.json`). See `test/fixtures/README.md` for
+provenance and refresh instructions. The fixture resolves through a
+repo-relative path, so a fresh clone needs nothing outside the repo — and
+a missing fixture fails loudly (`ENOENT`) rather than skipping validation.
+
+## License
+
+MIT

data/lib/ask/ag_ui/emitter.rb

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "ag_ui_protocol"
+
+module Ask
+  module AGUI
+    # The seam between ask-rb agent/session events and the AG-UI protocol.
+    #
+    # A transport drives one Emitter per run: it hands the emitter the AG-UI
+    # run context (thread id, run id, input messages), feeds it the stream of
+    # agent events via {#handle}, and collects the SSE frames it returns.
+    # The transport owns the socket; the emitter only translates and encodes.
+    #
+    #   emitter = Ask::AGUI::Emitter.new(thread_id: "t1", run_id: "r1", messages: [...])
+    #   frames = emitter.handle(agent_event)  # => ["data: {...}\n\n", ...]
+    #   frames = emitter.finish               # => ["data: {\"type\":\"RUN_FINISHED\",...}\n\n"]
+    #
+    # Event vocabulary (matched by class name, so the emitter never depends
+    # on ask-agent — any duck-typed object with the same shape works):
+    #
+    # * `TurnStart` / `SessionStart` → `RUN_STARTED` (first one wins)
+    # * `TextDelta` (`content`) → `TEXT_MESSAGE_START`, then
+    #   `TEXT_MESSAGE_CONTENT` per delta (only empty deltas are dropped — a
+    #   space is content, and dropping it would fuse the words around it),
+    #   then `TEXT_MESSAGE_END` on `MessageEnd`
+    # * `ThinkingDelta` (`content`) → `REASONING_START` →
+    #   `REASONING_MESSAGE_START` → `REASONING_MESSAGE_CONTENT` per delta
+    #   (empty deltas dropped) → `REASONING_MESSAGE_END` → `REASONING_END`
+    #   on `MessageEnd`
+    # * `ToolCallDelta` (`name`, `arguments`, `id`) → `TOOL_CALL_START`
+    #   (once per id) → `TOOL_CALL_ARGS` per non-empty delta;
+    #   `ToolExecutionStart` opens calls the stream never announced;
+    #   `MessageEnd` closes open calls with `TOOL_CALL_END`;
+    #   `ToolExecutionEnd` (`name`, `id`, `result`, …) closes the call if
+    #   still open and emits `TOOL_CALL_RESULT`
+    # * `SessionEnd` → `RUN_FINISHED` (first one wins); `Error` (`error`) →
+    #   `RUN_ERROR`. {#finish} and {#fail} drive the same endings manually.
+    # * Anything else rides one generic `CUSTOM` passthrough
+    #   (`name` = event class name, `value` = its `to_h`): the emitter knows
+    #   nothing about any chat application's specific states.
+    #
+    # `MessageEnd` and `TurnEnd` carry no AG-UI counterpart of their own —
+    # they only close whatever text, reasoning, or tool call is still open.
+    #
+    # Every frame is built with `AgUiProtocol::Core::Events::*` and encoded
+    # with `AgUiProtocol::Encoder::EventEncoder` — event JSON is never
+    # hand-rolled. Each {#handle}/{#start}/{#finish}/{#fail} call answers an
+    # array of `"data: <json>\n\n"` SSE frame strings (possibly empty).
+    class Emitter
+      # @return [String] the AG-UI thread this emitter streams for.
+      attr_reader :thread_id
+
+      # @return [String] the AG-UI run this emitter streams for.
+      attr_reader :run_id
+
+      # @param thread_id [String] AG-UI thread id (echoed on RUN_STARTED/RUN_FINISHED).
+      # @param run_id [String] AG-UI run id (echoed on RUN_STARTED/RUN_FINISHED).
+      # @param messages [Array<AgUiProtocol::Core::Types::BaseMessage,
+      #   AgUiProtocol::Core::Types::ActivityMessage>] input messages carried
+      #   on the RUN_STARTED event.
+      def initialize(thread_id:, run_id:, messages: [])
+        @thread_id = thread_id
+        @run_id = run_id
+        @input = AgUiProtocol::Core::Types::RunAgentInput.new(
+          thread_id: thread_id,
+          run_id: run_id,
+          state: {},
+          messages: messages,
+          tools: [],
+          context: [],
+          forwarded_props: {}
+        )
+        @encoder = AgUiProtocol::Encoder::EventEncoder.new
+        @started = false
+        @terminal = false
+        @text_message_id = nil
+        @reasoning_message_id = nil
+        @seen_tool_calls = []
+        @open_tool_calls = []
+      end
+
+      # Feed one agent event through the translator.
+      #
+      # @param event [Object] a duck-typed agent event (see class docs).
+      # @return [Array<String>] SSE frames to write to the stream, in order.
+      def handle(event)
+        case event_name(event)
+        when "TurnStart", "SessionStart"
+          start
+        when "TextDelta"
+          handle_text_delta(event)
+        when "ThinkingDelta"
+          handle_reasoning_delta(event)
+        when "ToolCallDelta"
+          handle_tool_call_delta(event)
+        when "ToolExecutionStart"
+          handle_tool_execution_start(event)
+        when "ToolExecutionEnd"
+          handle_tool_execution_end(event)
+        when "MessageEnd", "TurnEnd"
+          close_open_messages
+        when "SessionEnd"
+          finish
+        when "Error"
+          fail_with(event_error(event))
+        else
+          handle_custom(event)
+        end
+      end
+
+      # Open the run. Idempotent: only the first call emits RUN_STARTED.
+      #
+      # @return [Array<String>] zero or one SSE frames.
+      def start
+        return [] if @started
+
+        @started = true
+        [encode(AgUiProtocol::Core::Events::RunStartedEvent.new(
+          thread_id: @thread_id, run_id: @run_id, input: @input
+        ))]
+      end
+
+      # Close the run normally. Closes any open message first, then emits
+      # RUN_FINISHED once — late calls only close stragglers.
+      #
+      # @return [Array<String>] SSE frames to write to the stream, in order.
+      def finish
+        frames = close_open_messages
+        return frames if @terminal
+
+        @terminal = true
+        frames << encode(AgUiProtocol::Core::Events::RunFinishedEvent.new(
+          thread_id: @thread_id, run_id: @run_id
+        ))
+        frames
+      end
+
+      # Close the run with an error. Accepts an exception, a message string,
+      # or a duck-typed `Error` event (anything answering `error`).
+      # Idempotent like {#finish}; after a terminal event the run stays shut.
+      #
+      # @param reason [Exception, String, Object] what went wrong.
+      # @return [Array<String>] SSE frames to write to the stream, in order.
+      def fail(reason)
+        fail_with(reason)
+      end
+
+      private
+
+      def fail_with(reason)
+        frames = close_open_messages
+        return frames if @terminal
+
+        @terminal = true
+        frames << encode(AgUiProtocol::Core::Events::RunErrorEvent.new(message: error_message(reason)))
+        frames
+      end
+
+      def handle_text_delta(event)
+        frames = start
+        delta = event.respond_to?(:content) ? event.content : nil
+        return frames if delta.to_s.empty?
+
+        unless @text_message_id
+          @text_message_id = SecureRandom.uuid
+          frames << encode(AgUiProtocol::Core::Events::TextMessageStartEvent.new(message_id: @text_message_id))
+        end
+        frames << encode(AgUiProtocol::Core::Events::TextMessageContentEvent.new(
+          message_id: @text_message_id, delta: delta.to_s
+        ))
+        frames
+      end
+
+      def handle_reasoning_delta(event)
+        frames = start
+        delta = event.respond_to?(:content) ? event.content : nil
+        return frames if delta.to_s.empty?
+
+        unless @reasoning_message_id
+          @reasoning_message_id = SecureRandom.uuid
+          frames << encode(AgUiProtocol::Core::Events::ReasoningStartEvent.new(message_id: @reasoning_message_id))
+          frames << encode(AgUiProtocol::Core::Events::ReasoningMessageStartEvent.new(
+            message_id: @reasoning_message_id
+          ))
+        end
+        frames << encode(AgUiProtocol::Core::Events::ReasoningMessageContentEvent.new(
+          message_id: @reasoning_message_id, delta: delta.to_s
+        ))
+        frames
+      end
+
+      def handle_tool_call_delta(event)
+        frames = start
+        id = event_id(event)
+        open_tool_call(frames, id: id, name: event_name_or(event, id), parent_message_id: @text_message_id)
+        args = args_delta(event_arguments(event))
+        frames << encode(AgUiProtocol::Core::Events::ToolCallArgsEvent.new(tool_call_id: id, delta: args)) if args
+        frames
+      end
+
+      def handle_tool_execution_start(event)
+        frames = start
+        id = event_id(event)
+        return frames if @seen_tool_calls.include?(id)
+
+        open_tool_call(frames, id: id, name: event_name_or(event, id), parent_message_id: @text_message_id)
+        args = args_delta(event_arguments(event))
+        frames << encode(AgUiProtocol::Core::Events::ToolCallArgsEvent.new(tool_call_id: id, delta: args)) if args
+        frames
+      end
+
+      def handle_tool_execution_end(event)
+        frames = start
+        id = event_id(event)
+        unless @seen_tool_calls.include?(id)
+          open_tool_call(frames, id: id, name: event_name_or(event, id), parent_message_id: @text_message_id)
+        end
+        if @open_tool_calls.delete(id)
+          frames << encode(AgUiProtocol::Core::Events::ToolCallEndEvent.new(tool_call_id: id))
+        end
+        frames << encode(AgUiProtocol::Core::Events::ToolCallResultEvent.new(
+          message_id: SecureRandom.uuid, tool_call_id: id, content: result_content(event_result(event)), role: "tool"
+        ))
+        frames
+      end
+
+      def handle_custom(event)
+        value = event.respond_to?(:to_h) ? event.to_h : {}
+        value = {} if value.nil?
+        [encode(AgUiProtocol::Core::Events::CustomEvent.new(name: event_name(event), value: value))]
+      end
+
+      def close_open_messages
+        frames = []
+        if @reasoning_message_id
+          frames << encode(AgUiProtocol::Core::Events::ReasoningMessageEndEvent.new(message_id: @reasoning_message_id))
+          frames << encode(AgUiProtocol::Core::Events::ReasoningEndEvent.new(message_id: @reasoning_message_id))
+          @reasoning_message_id = nil
+        end
+        if @text_message_id
+          frames << encode(AgUiProtocol::Core::Events::TextMessageEndEvent.new(message_id: @text_message_id))
+          @text_message_id = nil
+        end
+        @open_tool_calls.each do |id|
+          frames << encode(AgUiProtocol::Core::Events::ToolCallEndEvent.new(tool_call_id: id))
+        end
+        @open_tool_calls = []
+        frames
+      end
+
+      def open_tool_call(frames, id:, name:, parent_message_id:)
+        return if @seen_tool_calls.include?(id)
+
+        @seen_tool_calls << id
+        @open_tool_calls << id
+        frames << encode(AgUiProtocol::Core::Events::ToolCallStartEvent.new(
+          tool_call_id: id, tool_call_name: name, parent_message_id: parent_message_id
+        ))
+      end
+
+      def encode(event)
+        @encoder.encode(event)
+      end
+
+      def event_name(event)
+        event.class.name.to_s.split("::").last
+      end
+
+      def event_id(event)
+        event.respond_to?(:id) ? event.id.to_s : SecureRandom.uuid
+      end
+
+      def event_name_or(event, fallback)
+        name = event.respond_to?(:name) ? event.name : nil
+        name = nil if name.to_s.empty?
+        name ? name.to_s : fallback
+      end
+
+      def event_arguments(event)
+        event.respond_to?(:arguments) ? event.arguments : nil
+      end
+
+      def event_result(event)
+        event.respond_to?(:result) ? event.result : nil
+      end
+
+      def event_error(event)
+        event.respond_to?(:error) ? event.error : event
+      end
+
+      def error_message(reason)
+        if reason.is_a?(Exception)
+          reason.message
+        elsif reason.respond_to?(:error)
+          reason.error.to_s
+        else
+          reason.to_s
+        end
+      end
+
+      # Tool arguments arrive as a JSON string or a Hash — the wire wants a
+      # string delta. Answers nil when there is nothing to send.
+      def args_delta(arguments)
+        return nil if arguments.nil?
+        return nil if arguments.respond_to?(:empty?) && arguments.empty?
+
+        delta = arguments.is_a?(String) ? arguments : JSON.generate(arguments)
+        delta.empty? ? nil : delta
+      end
+
+      # Tool results arrive as the executor's legacy hash ({message:, result:,
+      # …}), a plain string, or a duck-typed object — the wire wants a string.
+      def result_content(result)
+        return result.to_s if result.nil? || result.is_a?(String)
+
+        hash = result_hash(result)
+        if hash
+          content = hash[:message] || hash["message"] || hash[:result] || hash["result"]
+          return content.to_s unless content.nil?
+        end
+        result.to_s
+      end
+
+      def result_hash(result)
+        return result if result.is_a?(Hash)
+        return result.to_h if result.respond_to?(:to_h)
+
+        nil
+      end
+    end
+  end
+end

data/lib/ask/ag_ui/run.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "json"
+require "ag_ui_protocol"
+
+module Ask
+  module AGUI
+    # The parsed AG-UI run input for one `POST /agent/:id/run`.
+    #
+    # The server parses the request body into a Run and hands it to the
+    # host's block. The host reads what it needs (messages, tools, context,
+    # forwarded props) and answers the stream of duck-typed agent events;
+    # the server drives one {Emitter} with those events and owns the socket.
+    #
+    # Message, tool, and context entries are coerced to their
+    # `AgUiProtocol::Core::Types` counterparts on a best-effort basis:
+    # entries that do not coerce are skipped, never fatal. `state` and
+    # `forwarded_props` are opaque user data and ride through verbatim.
+    class Run
+      # Raised on malformed JSON or a missing `threadId` / `runId`. The
+      # server renders this as `400 {"error": ..., "details": ...}`.
+      class InvalidError < StandardError; end
+
+      # @return [String] the `:id` segment of `/agent/:id/run`.
+      attr_reader :agent_id
+
+      # @return [String] the AG-UI thread id.
+      attr_reader :thread_id
+
+      # @return [String] the AG-UI run id.
+      attr_reader :run_id
+
+      # @return [Array<AgUiProtocol::Core::Types::BaseMessage,
+      #   AgUiProtocol::Core::Types::ActivityMessage>] coerced input messages.
+      attr_reader :messages
+
+      # @return [Array<AgUiProtocol::Core::Types::Tool>] coerced tools.
+      attr_reader :tools
+
+      # @return [Array<AgUiProtocol::Core::Types::Context>] coerced context.
+      attr_reader :context
+
+      # @return [Object] opaque forwarded props, verbatim from the client.
+      attr_reader :forwarded_props
+
+      # @return [Object] opaque agent state, verbatim from the client.
+      attr_reader :state
+
+      # @return [Hash] the raw parsed body.
+      attr_reader :raw
+
+      # @param agent_id [String]
+      # @param thread_id [String]
+      # @param run_id [String]
+      # @param messages [Array]
+      # @param tools [Array]
+      # @param context [Array]
+      # @param forwarded_props [Object]
+      # @param state [Object]
+      # @param raw [Hash]
+      def initialize(agent_id:, thread_id:, run_id:, messages: [], tools: [],
+                     context: [], forwarded_props: nil, state: nil, raw: {})
+        @agent_id = agent_id
+        @thread_id = thread_id
+        @run_id = run_id
+        @messages = messages
+        @tools = tools
+        @context = context
+        @forwarded_props = forwarded_props
+        @state = state
+        @raw = raw
+      end
+
+      # Parse a `POST /agent/:id/run` body into a Run.
+      #
+      # @param agent_id [String] the `:id` segment of the request path.
+      # @param body [String] the raw request body.
+      # @return [Run]
+      # @raise [InvalidError] when the body is not a JSON object carrying
+      #   string `threadId` and `runId` members.
+      def self.parse(agent_id, body)
+        raw = begin
+          JSON.parse(body.to_s)
+        rescue JSON::ParserError => e
+          raise InvalidError, "malformed JSON: #{e.message}"
+        end
+
+        unless raw.is_a?(Hash)
+          raise InvalidError, "expected a JSON object, got #{raw.class}"
+        end
+
+        thread_id = raw["threadId"] || raw["thread_id"]
+        run_id = raw["runId"] || raw["run_id"]
+
+        unless thread_id.is_a?(String) && !thread_id.empty?
+          raise InvalidError, "missing required member \"threadId\""
+        end
+
+        unless run_id.is_a?(String) && !run_id.empty?
+          raise InvalidError, "missing required member \"runId\""
+        end
+
+        new(
+          agent_id: agent_id.to_s,
+          thread_id: thread_id,
+          run_id: run_id,
+          messages: coerce_messages(raw["messages"]),
+          tools: coerce_tools(raw["tools"]),
+          context: coerce_context(raw["context"]),
+          forwarded_props: raw.key?("forwardedProps") ? raw["forwardedProps"] : raw["forwarded_props"],
+          state: raw["state"],
+          raw: raw
+        )
+      end
+
+      # Best-effort message coercion. Unknown roles and malformed entries
+      # are skipped so one bad message cannot fail the run.
+      #
+      # @param value [Object]
+      # @return [Array]
+      def self.coerce_messages(value)
+        return [] unless value.is_a?(Array)
+
+        value.filter_map do |entry|
+          coerce_message(entry)
+        rescue StandardError
+          nil
+        end
+      end
+
+      # Coerce one raw message hash to its protocol type.
+      #
+      # @param entry [Object]
+      # @return [AgUiProtocol::Core::Types::Model, nil]
+      def self.coerce_message(entry)
+        return nil unless entry.is_a?(Hash)
+
+        types = AgUiProtocol::Core::Types
+        id = (entry["id"] || entry[:id]).to_s
+        return nil if id.empty?
+
+        case entry["role"] || entry[:role]
+        when "user"
+          types::UserMessage.new(id: id, content: entry["content"] || entry[:content] || "")
+        when "assistant"
+          types::AssistantMessage.new(
+            id: id,
+            content: entry["content"] || entry[:content],
+            tool_calls: entry["toolCalls"] || entry["tool_calls"] || entry[:tool_calls]
+          )
+        when "system"
+          types::SystemMessage.new(id: id, content: (entry["content"] || entry[:content]).to_s)
+        when "developer"
+          types::DeveloperMessage.new(id: id, content: (entry["content"] || entry[:content]).to_s)
+        when "tool"
+          tool_call_id = entry["toolCallId"] || entry["tool_call_id"] || entry[:tool_call_id]
+          return nil if tool_call_id.to_s.empty?
+
+          types::ToolMessage.new(
+            id: id,
+            content: (entry["content"] || entry[:content]).to_s,
+            tool_call_id: tool_call_id.to_s
+          )
+        when "activity"
+          content = entry["content"] || entry[:content]
+          return nil unless content.is_a?(Hash)
+
+          types::ActivityMessage.new(
+            id: id,
+            activity_type: (entry["activityType"] || entry["activity_type"] || "activity").to_s,
+            content: content
+          )
+        when "reasoning"
+          types::ReasoningMessage.new(id: id, content: (entry["content"] || entry[:content]).to_s)
+        end
+      rescue StandardError
+        nil
+      end
+
+      # @param value [Object]
+      # @return [Array<AgUiProtocol::Core::Types::Tool>]
+      def self.coerce_tools(value)
+        return [] unless value.is_a?(Array)
+
+        types = AgUiProtocol::Core::Types
+        value.filter_map do |entry|
+          next unless entry.is_a?(Hash)
+
+          name = entry["name"] || entry[:name]
+          description = entry["description"] || entry[:description]
+          parameters = entry["parameters"] || entry[:parameters]
+          next if name.to_s.empty?
+
+          types::Tool.new(
+            name: name.to_s,
+            description: description.to_s,
+            parameters: parameters.nil? ? {} : parameters
+          )
+        rescue StandardError
+          nil
+        end
+      end
+
+      # @param value [Object]
+      # @return [Array<AgUiProtocol::Core::Types::Context>]
+      def self.coerce_context(value)
+        return [] unless value.is_a?(Array)
+
+        types = AgUiProtocol::Core::Types
+        value.filter_map do |entry|
+          next unless entry.is_a?(Hash)
+
+          description = entry["description"] || entry[:description]
+          content = entry["value"] || entry[:value]
+          next if description.to_s.empty? || content.nil?
+
+          types::Context.new(description: description.to_s, value: content.to_s)
+        rescue StandardError
+          nil
+        end
+      end
+
+      private_class_method :coerce_message
+    end
+  end
+end

data/lib/ask/ag_ui/run_store.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Ask
+  module AGUI
+    # Per-thread run bookkeeping backing `POST /agent/:id/connect`
+    # (replay) and `POST /agent/:id/stop/:thread_id` (cooperative cancel).
+    #
+    # The interface is duck-typed: anything implementing {#begin_run},
+    # {#record}, {#finish_run}, {#replay}, {#request_stop} and
+    # {#stop_requested?} works as a store. A future shared store (Redis,
+    # database) can be dropped in without touching the server.
+    #
+    #   store.begin_run("t1", "r1")
+    #   store.record("t1", "data: {...}\n\n")
+    #   store.finish_run("t1")
+    #   store.replay("t1")            # => ["data: {...}\n\n", ...]
+    #   store.request_stop("t1")      # => true
+    #   store.stop_requested?("t1")   # => true
+    module RunStore
+      # Single-process in-memory store.
+      #
+      # NOTE: frames live in this process's memory only. Two processes
+      # (two Puma workers, two machines) cannot see each other's runs, so
+      # `/connect` replay and `/stop` only work when the client keeps
+      # hitting the same process. Back replay and stop with a shared store
+      # when running more than one process.
+      #
+      # Mutex-guarded, so threads sharing one process are safe.
+      class InMemory
+        # Build an empty store.
+        def initialize
+          @mutex = Mutex.new
+          @frames = Hash.new { |hash, key| hash[key] = [] }
+          @stop_requested = {}
+        end
+
+        # Mark the start of a run. Clears any stale stop request for the
+        # thread so a previous `/stop` cannot cancel the new run.
+        #
+        # @param thread_id [String]
+        # @param run_id [String]
+        # @return [void]
+        def begin_run(thread_id, run_id)
+          @mutex.synchronize do
+            @stop_requested.delete(thread_id.to_s)
+          end
+          nil
+        end
+
+        # Append one SSE frame for later `/connect` replay.
+        #
+        # @param thread_id [String]
+        # @param frame [String] one `"data: <json>\n\n"` frame.
+        # @return [void]
+        def record(thread_id, frame)
+          @mutex.synchronize do
+            @frames[thread_id.to_s] << frame
+          end
+          nil
+        end
+
+        # Mark the run finished. Frames stay available for replay.
+        #
+        # @param thread_id [String]
+        # @return [void]
+        def finish_run(thread_id)
+          nil
+        end
+
+        # Answer every frame recorded for the thread, in order.
+        #
+        # @param thread_id [String]
+        # @return [Array<String>] possibly empty when nothing was recorded.
+        def replay(thread_id)
+          @mutex.synchronize do
+            @frames[thread_id.to_s].dup
+          end
+        end
+
+        # Flag the thread's run for cooperative cancel. The run loop
+        # checks {#stop_requested?} between events and ends the run early.
+        #
+        # @param thread_id [String]
+        # @return [true]
+        def request_stop(thread_id)
+          @mutex.synchronize do
+            @stop_requested[thread_id.to_s] = true
+          end
+          true
+        end
+
+        alias stop request_stop
+
+        # Whether {#request_stop} was called since the last {#begin_run}.
+        #
+        # @param thread_id [String]
+        # @return [Boolean]
+        def stop_requested?(thread_id)
+          @mutex.synchronize do
+            @stop_requested.fetch(thread_id.to_s, false)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/ag_ui/server.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require "json"
+require "ag_ui_protocol"
+
+module Ask
+  module AGUI
+    # Mountable Rack application serving the AG-UI runtime surface.
+    #
+    # This is the conventional surface third-party AG-UI clients
+    # (assistant-ui, CopilotKit) expect when pointed at the gem:
+    #
+    # * `GET /info` — the runtime envelope: the agents map (name, class,
+    #   capabilities), the transport mode, and the gem version.
+    # * `POST /agent/:id/run` — parses the run input, drives one {Emitter}
+    #   for the run, and streams its SSE frames.
+    # * `POST /agent/:id/connect` — replays recorded frames, or completes
+    #   immediately when there is nothing to replay.
+    # * `POST /agent/:id/stop/:thread_id` — flags the run for cooperative
+    #   cancel and answers a JSON acknowledgement.
+    #
+    # The host supplies the work as a block and owns the agent; the gem
+    # owns the socket and the framing and never depends on Rails or
+    # ask-agent:
+    #
+    #   app = Ask::AGUI::Server.new(agent_id: "default") do |run|
+    #     # run.thread_id, run.run_id, run.messages, run.tools,
+    #     # run.context, run.forwarded_props — answer agent events:
+    #     [TurnStart.new, TextDelta.new(content: "Hello")]
+    #   end
+    #
+    # The block answers an enumerable of duck-typed agent events (the same
+    # vocabulary {Emitter} handles). It may answer a lazy enumerator — the
+    # response body pulls events only as it streams, so the run streams
+    # under any Rack server. Every run opens with `RUN_STARTED` and closes
+    # with `RUN_FINISHED` / `RUN_ERROR`, even when the host answers no
+    # events or raises mid-run.
+    #
+    # Matching is on trailing path segments, so the app works standalone
+    # and mounted (`map("/api/copilotkit") { run app }`, Rails `mount`).
+    class Server
+      # Response headers for the SSE streams. Matches the reference
+      # runtime: `text/event-stream`, no caching, keep-alive.
+      SSE_HEADERS = {
+        "content-type" => "text/event-stream",
+        "cache-control" => "no-cache",
+        "connection" => "keep-alive",
+        "x-accel-buffering" => "no"
+      }.freeze
+
+      # Response headers for the JSON endpoints.
+      JSON_HEADERS = { "content-type" => "application/json" }.freeze
+
+      AGENT_RUN_ROUTE = %r{/agent/(?<agent_id>[^/]+)/run\z}
+      AGENT_CONNECT_ROUTE = %r{/agent/(?<agent_id>[^/]+)/connect\z}
+      AGENT_STOP_ROUTE = %r{/agent/(?<agent_id>[^/]+)/stop/(?<thread_id>[^/]+)\z}
+      INFO_ROUTE = %r{(?:\A|/)info\z}
+
+      # @return [String] the agent id advertised on `GET /info`.
+      attr_reader :agent_id
+
+      # Build the Rack application.
+      #
+      # @param agent_id [String] the agent name advertised on `GET /info`.
+      # @param description [String, nil] one-line agent description for discovery UIs.
+      # @param agent_class_name [String] the agent class named on `GET /info`.
+      # @param capabilities [AgUiProtocol::Core::Capabilities::AgentCapabilities, nil]
+      #   capability information for `GET /info`. Defaults to what the
+      #   {Emitter} actually drives: SSE transport, client-provided tools,
+      #   streaming reasoning.
+      # @param store [Ask::AGUI::RunStore::InMemory, nil] run bookkeeping
+      #   for `/connect` replay and `/stop`. Pass `nil` for the stateless
+      #   behaviour (connect completes immediately, stop only acks).
+      # @yield [Run] the run input; answers an enumerable of agent events.
+      # @raise [ArgumentError] when no run-handler block is given.
+      def initialize(agent_id: "default", description: nil, agent_class_name: "BuiltInAgent",
+                     capabilities: nil, store: RunStore::InMemory.new, &block)
+        raise ArgumentError, "Server requires a run-handler block" unless block
+
+        @agent_id = agent_id.to_s
+        @description = description
+        @agent_class_name = agent_class_name.to_s
+        @capabilities = capabilities || default_capabilities
+        @store = store
+        @handler = block
+      end
+
+      # Rack entrypoint.
+      #
+      # @param env [Hash] the Rack environment.
+      # @return [Array(Integer, Hash, Object)] the Rack response.
+      def call(env)
+        method = env["REQUEST_METHOD"].to_s
+        path = env["PATH_INFO"].to_s.chomp("/")
+
+        if method == "OPTIONS"
+          return preflight
+        elsif method == "GET" && path.match?(INFO_ROUTE)
+          return respond_info
+        elsif method == "POST" && (match = path.match(AGENT_STOP_ROUTE))
+          return respond_stop(match[:thread_id])
+        elsif method == "POST" && (match = path.match(AGENT_RUN_ROUTE))
+          return respond_run(env, match[:agent_id])
+        elsif method == "POST" && (match = path.match(AGENT_CONNECT_ROUTE))
+          return respond_connect(env)
+        end
+
+        not_found
+      end
+
+      private
+
+      def respond_info
+        [200, JSON_HEADERS.dup, [JSON.generate(info_payload)]]
+      end
+
+      # The capability information is built from ag-ui-protocol's
+      # capability and identity types — never hand-rolled.
+      def info_payload
+        agent = {
+          "name" => @agent_id,
+          "className" => @agent_class_name,
+          "capabilities" => @capabilities.as_json
+        }
+        agent["description"] = @description unless @description.nil?
+
+        {
+          "agents" => { @agent_id => agent },
+          "mode" => "sse",
+          "version" => VERSION
+        }
+      end
+
+      def default_capabilities
+        capabilities = AgUiProtocol::Core::Capabilities
+        capabilities::AgentCapabilities.new(
+          identity: capabilities::IdentityCapabilities.new(
+            name: @agent_id, description: @description, version: VERSION
+          ),
+          transport: capabilities::TransportCapabilities.new(streaming: true),
+          tools: capabilities::ToolsCapabilities.new(supported: true, client_provided: true),
+          reasoning: capabilities::ReasoningCapabilities.new(supported: true, streaming: true)
+        )
+      end
+
+      def respond_run(env, agent_id)
+        body = env["rack.input"]&.read.to_s
+        run = Run.parse(agent_id, body)
+        emitter = Emitter.new(thread_id: run.thread_id, run_id: run.run_id, messages: run.messages)
+        [200, SSE_HEADERS.dup, run_body(run, emitter)]
+      rescue Run::InvalidError => e
+        bad_request(e.message)
+      end
+
+      # The enumerable body pulls the host's events lazily, translates
+      # each through the emitter, and yields ready-to-write SSE frames —
+      # plain Rack 3 streaming with no async requirement.
+      def run_body(run, emitter)
+        server = self
+        Enumerator.new do |yielder|
+          server.send(:stream_run, run, emitter, yielder)
+        end
+      end
+
+      def stream_run(run, emitter, yielder)
+        @store&.begin_run(run.thread_id, run.run_id)
+        emit = lambda do |frames|
+          frames.each do |frame|
+            @store&.record(run.thread_id, frame)
+            yielder << frame
+          end
+        end
+
+        emit.call(emitter.start)
+
+        events = @handler.call(run)
+        events = [] if events.nil?
+        events = [events] unless events.respond_to?(:each)
+        events.each do |event|
+          break if @store&.stop_requested?(run.thread_id)
+
+          emit.call(emitter.handle(event))
+        end
+
+        emit.call(emitter.finish)
+      rescue StandardError => e
+        begin
+          emit.call(emitter.fail(e))
+        rescue StandardError
+          nil
+        end
+      ensure
+        @store&.finish_run(run.thread_id)
+      end
+
+      # Resume/reattach: replay everything recorded for the thread, then
+      # close. Unknown thread (or no store) answers 200 SSE with zero
+      # events — the client's reconnect stays well behaved.
+      def respond_connect(env)
+        thread_id = extract_thread_id(env["rack.input"]&.read.to_s)
+        frames = (thread_id && @store) ? @store.replay(thread_id) : []
+        [200, SSE_HEADERS.dup, frames]
+      end
+
+      # Flag the thread's run for cooperative cancel and ack. The run loop
+      # checks the flag between events and ends the run early.
+      def respond_stop(thread_id)
+        stopped = @store ? @store.request_stop(thread_id.to_s) : false
+        [200, JSON_HEADERS.dup, [JSON.generate({ "stopped" => stopped })]]
+      end
+
+      # `/connect` bodies carry the run input plus an optional replay
+      # cursor — parsed opportunistically, never fatal.
+      def extract_thread_id(body)
+        return nil if body.empty?
+
+        raw = JSON.parse(body)
+        return nil unless raw.is_a?(Hash)
+
+        thread_id = raw["threadId"] || raw["thread_id"]
+        thread_id.is_a?(String) && !thread_id.empty? ? thread_id : nil
+      rescue JSON::ParserError
+        nil
+      end
+
+      def preflight
+        [204, {
+          "access-control-allow-origin" => "*",
+          "access-control-allow-methods" => "GET, POST, OPTIONS",
+          "access-control-allow-headers" => "*"
+        }, []]
+      end
+
+      def bad_request(details)
+        [400, JSON_HEADERS.dup,
+         [JSON.generate({ "error" => "Invalid request body", "details" => details })]]
+      end
+
+      def not_found
+        [404, JSON_HEADERS.dup, [JSON.generate({ "error" => "Not found" })]]
+      end
+    end
+  end
+end

data/lib/ask/ag_ui/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Ask
+  module AGUI
+    # Gem version, following Semantic Versioning.
+    VERSION = "0.1.0"
+  end
+end

data/lib/ask/ag_ui.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "ag_ui/version"
+require_relative "ag_ui/emitter"
+require_relative "ag_ui/run_store"
+require_relative "ag_ui/run"
+require_relative "ag_ui/server"
+
+# Namespace for the AG-UI (Agent-User Interaction) protocol server.
+#
+# ask-ag-ui is the runtime surface that assistant-ui and CopilotKit
+# frontends expect: SSE event streaming over the AG-UI protocol, backed by
+# the ask-rb ecosystem.
+#
+# The public seam is Ask::AGUI::Emitter — see that class for the contract.
+module Ask
+  # AG-UI protocol surface for ask-rb.
+  module AGUI
+  end
+end

data/lib/ask-ag-ui.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Main entry point for the ask-ag-ui gem.
+#
+# Requires the namespaced implementation directly. This family loads files
+# with manual `require_relative` lists — no Zeitwerk.
+require_relative "ask/ag_ui"

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: ask-ag-ui
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ag-ui-protocol
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+description: The AG-UI (Agent-User Interaction) protocol server for the ask-rb ecosystem
+  — SSE event streaming and the runtime surface that assistant-ui and CopilotKit frontends
+  expect.
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ask-ag-ui.rb
+- lib/ask/ag_ui.rb
+- lib/ask/ag_ui/emitter.rb
+- lib/ask/ag_ui/run.rb
+- lib/ask/ag_ui/run_store.rb
+- lib/ask/ag_ui/server.rb
+- lib/ask/ag_ui/version.rb
+homepage: https://github.com/ask-rb/ask-ag-ui
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ask-rb/ask-ag-ui
+  source_code_uri: https://github.com/ask-rb/ask-ag-ui
+  changelog_uri: https://github.com/ask-rb/ask-ag-ui/blob/master/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.18
+specification_version: 4
+summary: AG-UI protocol server for the ask-rb ecosystem
+test_files: []