ask-ag-ui 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a496b953fbbbf38bde6bfb2cc1771fc67d8b47a8ed6789ef453e18b8a7d68161
-  data.tar.gz: 94edd256f17e7b5de58a3de085d2d857adc06ec35bb58e83d1e9f92feac457bc
+  metadata.gz: ed8c9330466744997f9faf115cfe0ef641b191144a6d114b73e086c6c1129f35
+  data.tar.gz: 39fb54b8eb708a4e2b60154891529e92063ff8c46ef0f6d30cb27ae1d0c689dc
 SHA512:
-  metadata.gz: 711674f104ef94ed5c9e44293781b74970beaf08222cec1e42865bf304b70e8a94ce80849c0f1884f5d4be254d841dfb85547d610d15892d23c61f17bbe76496
-  data.tar.gz: cafe0507a38288621887eb3d31cb663676326d4da15814fd4716cd16fd2c045d9587347ed97c421cb71ecf979a6add14775b5bdc52a34f829f5ddca3f1a923af
+  metadata.gz: 423f30841ee3a31742b667fd617525e6896ca2b36809e7ba6a6136a49c27b033c78117b94b6efdb15acec10d7b972781aadf965b2f05cb9a5201814539cb4690
+  data.tar.gz: 0bf9fc79975ee1a28c49c73cb18f7116395e16a6d24c6d05f343d0a12611050e831629a03537146387da90c35ba86d5056d86aed94deeabc15a68de31cf5b54f

data/CHANGELOG.md

@@ -5,6 +5,19 @@ the keep-a-changelog format.
 
 ## [Unreleased]
 
+## [0.1.1] — 2026-09-29
+
+### Added
+
+- `Ask::AGUI::Emitter#custom_name` — the public seam for a host that names
+  its own `CUSTOM` frames. Pass `custom_names:` to the constructor
+  (`{ "VisitorAway" => "resting" }`) or override the method; either way the
+  frame's `name` changes and the event still rides one `CUSTOM` frame with
+  its `to_h` as the value. The default is unchanged — a `CUSTOM` frame
+  named after the event's class — and events nobody named keep riding that
+  default path. A host no longer has to subclass the emitter and override
+  the private `event_name` method to get there.
+
 ## [0.1.0] — 2026-09-28
 
 ### Added

data/README.md

@@ -49,11 +49,42 @@ ask-agent internals:
 | `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`) |
+| anything else | one generic `CUSTOM` passthrough (`name` + `value`), named after the event's class — [rename it](#naming-your-own-custom-frames) |
 
 Every frame is built with `AgUiProtocol::Core::Events::*` and encoded with
 `AgUiProtocol::Encoder::EventEncoder` — event JSON is never hand-rolled.
 
+### Naming your own CUSTOM frames
+
+A host whose states are not event class names — a chat page reading
+`resting`, `done`, `visitor_spent` — says so through the public
+`#custom_name` hook, never by reaching into a private method. Name the
+kinds you know with the `custom_names:` constructor option:
+
+```ruby
+emitter = Ask::AGUI::Emitter.new(
+  thread_id: "t1", run_id: "r1",
+  custom_names: { "VisitorAway" => "resting", "CheckoutClosed" => "visitor_spent" }
+)
+```
+
+or override the method when the name is computed:
+
+```ruby
+class ChatEmitter < Ask::AGUI::Emitter
+  NAMES = { "VisitorAway" => "resting" }
+
+  def custom_name(event)
+    NAMES.fetch(event.class.name.split("::").last) { super }
+  end
+end
+```
+
+Either way only the frame's `name` changes: the event still rides one
+`CUSTOM` frame with its `to_h` as the value, and the vocabulary above is
+untouched. Events nobody names keep the class-name default, so the
+passthrough is exactly what it is without any of this.
+
 ## Mounting: `Ask::AGUI::Server`
 
 The server is the conventional Rack surface AG-UI clients expect. The host

data/lib/ask/ag_ui/emitter.rb

@@ -39,7 +39,9 @@ module Ask
     #   `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.
+    #   nothing about any chat application's specific states. A host with
+    #   its own state vocabulary renames those frames by overriding
+    #   {#custom_name} — no private method to reach for.
     #
     # `MessageEnd` and `TurnEnd` carry no AG-UI counterpart of their own —
     # they only close whatever text, reasoning, or tool call is still open.
@@ -60,7 +62,10 @@ module Ask
       # @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: [])
+      # @param custom_names [Hash] the host's own `CUSTOM` frame names, keyed
+      #   by the event's class name (`"VisitorAway" => "resting"`). Events
+      #   left out keep the default. See {#custom_name}.
+      def initialize(thread_id:, run_id:, messages: [], custom_names: {})
         @thread_id = thread_id
         @run_id = run_id
         @input = AgUiProtocol::Core::Types::RunAgentInput.new(
@@ -72,6 +77,7 @@ module Ask
           context: [],
           forwarded_props: {}
         )
+        @custom_names = normalize_custom_names(custom_names)
         @encoder = AgUiProtocol::Encoder::EventEncoder.new
         @started = false
         @terminal = false
@@ -147,8 +153,54 @@ module Ask
         fail_with(reason)
       end
 
+      # The `CUSTOM` frame name an app-defined event rides as.
+      #
+      # This is the seam for a host that has a state vocabulary of its own —
+      # a chat page reading "resting", "done", "visitor_spent" instead of
+      # the event classes. Two ways in, both public:
+      #
+      #   # 1. name the kinds you know, at construction:
+      #   emitter = Ask::AGUI::Emitter.new(thread_id: "t1", run_id: "r1",
+      #     custom_names: { "VisitorAway" => "resting", "CheckoutClosed" => "visitor_spent" })
+      #
+      #   # 2. override this method when the name is computed:
+      #   class ChatEmitter < Ask::AGUI::Emitter
+      #     NAMES = { "VisitorAway" => "resting" }
+      #
+      #     def custom_name(event)
+      #       NAMES.fetch(event.class.name.split("::").last) { super }
+      #     end
+      #   end
+      #
+      # Either way only the frame's `name` changes: the event still rides
+      # one `CUSTOM` frame with its `to_h` as the value, and the rest of
+      # the vocabulary is untouched. An event nobody names — or a name that
+      # comes back nil or empty — falls back to the event's class name, so
+      # the default is exactly what it is without any of this.
+      #
+      # @param event [Object] the app-defined event about to ride a frame.
+      # @return [String] the `name` that frame carries.
+      def custom_name(event)
+        name = event_name(event)
+        custom = @custom_names[name]
+        custom.to_s.empty? ? name : custom.to_s
+      end
+
       private
 
+      # The host's names, keyed by event class name, normalized once so
+      # `{ VisitorAway: :resting }` reads like `{ "VisitorAway" => "resting" }`.
+      def normalize_custom_names(custom_names)
+        custom_names.to_h { |kind, name| [kind.to_s, name.to_s] }.freeze
+      end
+
+      # The key the emitter matches an event by — the event's demodulized
+      # class name. Internal: renaming a `CUSTOM` frame is {#custom_name}'s
+      # job, and renaming the vocabulary would move the mapping itself.
+      def event_name(event)
+        event.class.name.to_s.split("::").last
+      end
+
       def fail_with(reason)
         frames = close_open_messages
         return frames if @terminal
@@ -229,7 +281,7 @@ module Ask
       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))]
+        [encode(AgUiProtocol::Core::Events::CustomEvent.new(name: custom_name(event), value: value))]
       end
 
       def close_open_messages
@@ -264,10 +316,6 @@ module Ask
         @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

data/lib/ask/ag_ui/version.rb

@@ -3,6 +3,6 @@
 module Ask
   module AGUI
     # Gem version, following Semantic Versioning.
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-ag-ui
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Kaka Ruto