poetry-agent 0.0.2

data/lib/poetry/agent/a2ui/renderer.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require "erb"
+require_relative "pointer"
+require_relative "markdown"
+
+module Poetry
+  module Agent
+    module A2UI
+      # Renders one {Surface} to HTML through the host's view context,
+      # dispatching each component to the surface's catalog binding. The
+      # surface becomes a form when an `action_url` is given: bound inputs
+      # are named by their absolute data-model pointer and every agent
+      # action is a submit button, so a user action posts the surface's
+      # current inputs plus the source component - the spec's "inputs sync
+      # only on an action" contract, in Hotwire's native shape. The
+      # wrapper carries the surface's version for the versioned Turbo
+      # Stream replace.
+      #
+      # Rendering never raises for an agent's mistake: an unknown
+      # component, a dangling reference, a component the library refuses
+      # to build, or an unsupported function renders nothing and lands in
+      # {#warnings}.
+      #
+      # @example
+      #   renderer = Renderer.new(surface, view: view_context, action_url: "/a2ui/action")
+      #   html = renderer.call
+      #   renderer.warnings # => []
+      class Renderer
+        # The DOM id prefix of a rendered surface.
+        ELEMENT_PREFIX = "a2ui-"
+        # The parameter carrying the bound values, keyed by absolute pointer.
+        VALUES_PARAM = "a2ui[values]"
+        # The parameter carrying the source component of the action.
+        ACTION_PARAM = "a2ui[action]"
+        # The parameter carrying the surface id.
+        SURFACE_PARAM = "a2ui[surface]"
+        # The errors an agent-authored component may provoke in the library.
+        COMPONENT_ERRORS = [ArgumentError, NameError].freeze
+        # The Stimulus controller that runs a surface's checks as the user types.
+        SURFACE_CONTROLLER = "poetry--agent--a2ui-surface"
+        # The form events that re-run the checks.
+        EVALUATE_ACTIONS = "input->#{SURFACE_CONTROLLER}#evaluate change->#{SURFACE_CONTROLLER}#evaluate".freeze
+
+        # @return [Surface]
+        attr_reader :surface
+        # @return [Object] the view context
+        attr_reader :view
+        # @return [String, nil]
+        attr_reader :action_url
+        # @return [Array<String>] what could not be rendered, in render order
+        attr_reader :warnings
+        # @return [Hash{String => Array<Hash>}] check failures by component key (see {Surface#failures})
+        attr_reader :errors
+
+        # @param surface_or_id [Surface, String]
+        # @return [String] the DOM id of the surface's wrapper
+        def self.element_id(surface_or_id)
+          id = surface_or_id.respond_to?(:id) ? surface_or_id.id : surface_or_id
+          "#{ELEMENT_PREFIX}#{id}"
+        end
+
+        # @param surface [Surface]
+        # @param view [Object] an ActionView context (`view_context`)
+        # @param action_url [String, nil] where actions post; nil renders a plain container
+        # @param html [Hash] extra attributes for the wrapper (`class:` etc.)
+        # @param errors [Hash{String => Array<Hash>}] check failures to show, by
+        #   component key (a rejected action's `errors`)
+        def initialize(surface, view:, action_url: nil, html: {}, errors: {})
+          @surface = surface
+          @view = view
+          @action_url = action_url
+          @html = html
+          @errors = errors || {}
+          @warnings = []
+        end
+
+        # @return [String] the surface's HTML (html_safe)
+        def call
+          body = Poetry::Core::StableId.with_seed("a2ui:#{surface.id}") do
+            surface.root ? render_component("root", nil) : blank
+          end
+          data = { a2ui_surface: surface.id, version: surface.version }.merge(@html[:data] || {})
+          attributes = { id: self.class.element_id(surface), data: data }.merge(@html.except(:data))
+          return view.tag.div(body, **attributes) unless action_url
+
+          program = surface.program
+          if program["checks"].any?
+            data[:controller] = [data[:controller], SURFACE_CONTROLLER].compact.join(" ")
+            data[:"#{SURFACE_CONTROLLER}-program-value"] = JSON.generate(program)
+            data[:action] = [data[:action], EVALUATE_ACTIONS].compact.join(" ")
+          end
+          view.form_with(url: action_url, method: :post, **attributes) do
+            view.safe_join([view.hidden_field_tag(SURFACE_PARAM, surface.id, id: nil), body])
+          end
+        end
+
+        # @param component_id [String]
+        # @param scope [String, nil]
+        # @return [String] the component's HTML (empty when it cannot render)
+        def render_component(component_id, scope = nil)
+          component = surface.component(component_id)
+          return warn("unknown component id #{component_id.inspect}") unless component
+
+          previous = @current_key
+          @current_key = surface.source_key(component, scope)
+          surface.catalog.render(component, scope, self) || blank
+        rescue *COMPONENT_ERRORS, Poetry::Core::Error => e
+          warn("#{component["component"]} #{component_id.inspect}: #{e.message}")
+        ensure
+          @current_key = previous
+        end
+
+        # Renders a child reference (an id, an id list, or a template).
+        #
+        # @param reference [String, Array<String>, Hash, nil]
+        # @param scope [String, nil]
+        # @return [String]
+        def render_children(reference, scope = nil)
+          view.safe_join(surface.expand(reference, scope).map { |id, child_scope| render_component(id, child_scope) })
+        end
+
+        # Builds and renders a library component. Every instance gets a
+        # render-stable `key:` (the surface, the component, its scope, and
+        # a suffix for repeated instances), so Turbo morph pairs the same
+        # logical element across updates and local state survives.
+        #
+        # @param klass [Class] the component class
+        # @param attributes [Hash] constructor keywords
+        # @param suffix [String, nil] distinguishes several instances of one class for one component
+        # @param keywords [Hash] constructor keywords given keyword-style (merged into `attributes`)
+        # @yield the content block (the component instance is yielded)
+        # @return [String]
+        def component(klass, attributes = {}, suffix: nil, **keywords, &)
+          attributes = attributes.merge(keywords)
+          attributes = { key: stable_key(suffix) }.merge(attributes) unless attributes.key?(:key)
+          view.render(klass.new(**attributes), &)
+        end
+
+        # @param suffix [String, nil]
+        # @return [String] the render-stable key of the component being rendered
+        def stable_key(suffix = nil)
+          ["a2ui", surface.id, @current_key, suffix].compact.join("-")
+        end
+
+        # @return [String, nil] the key of the component being rendered (`id`, or `id@scope`)
+        attr_reader :current_key
+
+        # The display string of a dynamic value; a function problem warns.
+        #
+        # @param value [Object]
+        # @param scope [String, nil]
+        # @return [String]
+        def text(value, scope = nil)
+          surface.text(value, scope, on_error: method(:warn))
+        end
+
+        # @param value [Object]
+        # @param scope [String, nil]
+        # @return [Object, nil] the resolved dynamic value
+        def resolve(value, scope = nil)
+          surface.resolve(value, scope, on_error: method(:warn))
+        end
+
+        # Calls a catalog function; a problem warns and returns nil.
+        #
+        # @param name [String]
+        # @param args [Hash, nil]
+        # @param scope [String, nil]
+        # @return [Object, nil]
+        def call_function(name, args, scope = nil)
+          Evaluator.new(surface, scope, on_error: method(:warn)).call(name, args)
+        end
+
+        # @param component [Hash]
+        # @param scope [String, nil]
+        # @return [String, nil] the first check failure message for the component
+        def error_for(component, scope = nil)
+          failure = Array(errors[surface.source_key(component, scope)]).first
+          failure && failure[:message]
+        end
+
+        # @param path [String] a bound pointer
+        # @param scope [String, nil]
+        # @return [String] the input's form name
+        def input_name(path, scope = nil)
+          "#{VALUES_PARAM}[#{Pointer.absolute(path, scope)}]"
+        end
+
+        # @param component [Hash]
+        # @param scope [String, nil]
+        # @return [String] a DOM id for the component's control
+        def control_id(component, scope = nil)
+          suffix = scope ? "-#{scope.delete_prefix("/").tr("/", "-")}" : ""
+          "#{self.class.element_id(surface)}-#{component["id"]}#{suffix}"
+        end
+
+        # The attributes that make a button an agent action.
+        #
+        # @param component [Hash]
+        # @param scope [String, nil]
+        # @return [Hash]
+        def submit_attributes(component, scope = nil)
+          return { type: :button } unless action_url
+
+          { type: :submit, name: ACTION_PARAM, value: surface.source_key(component, scope) }
+        end
+
+        # @param component [Hash]
+        # @param scope [String, nil]
+        # @return [String, nil] the component's accessibility label
+        def aria_label(component, scope = nil)
+          accessibility = component["accessibility"]
+          return unless accessibility.is_a?(Hash) && accessibility["label"]
+
+          label = text(accessibility["label"], scope)
+          label.empty? ? nil : label
+        end
+
+        # @param text [String]
+        # @return [String] the Markdown subset rendered (html_safe)
+        def markdown(text)
+          Markdown.render(text).html_safe
+        end
+
+        # @return [String] an empty html_safe string
+        def blank
+          view.safe_join([])
+        end
+
+        # Records a problem and renders nothing for it.
+        #
+        # @param message [String]
+        # @return [String] an empty html_safe string
+        def warn(message)
+          @warnings << message
+          blank
+        end
+      end
+    end
+  end
+end

data/lib/poetry/agent/a2ui/session.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require_relative "surface"
+
+module Poetry
+  module Agent
+    module A2UI
+      # The renderer-side consumer of the A2UI envelope: applies
+      # `createSurface`, `updateComponents`, `updateDataModel`, and
+      # `deleteSurface` to a set of {Surface}s, answers what it cannot
+      # honor with renderer-to-agent error messages, and turns a
+      # submitted form into the spec's `action` message.
+      #
+      # @example Fold a stream of messages and read back the surfaces
+      #   session = Session.new
+      #   session.apply_all(messages)  # => ["login"]
+      #   session.surfaces["login"].data
+      #   session.errors               # => [] or renderer-to-agent error messages
+      class Session
+        # Every message carries exactly one of these keys.
+        MESSAGE_KEYS = %w[createSurface updateComponents updateDataModel deleteSurface
+                          callRendererFunction agentFunctionResponse].freeze
+
+        # A user action, ready for the agent: the spec message plus the
+        # AG-UI placement (`forwardedProps.a2uiAction.userAction`).
+        Action = Struct.new(:message, :surface, :errors, keyword_init: true) do
+          # @return [Boolean] whether every check passed and the message exists
+          def valid?
+            !message.nil? && (errors.nil? || errors.empty?)
+          end
+
+          # @return [Hash, nil] the `{ "version", "action" }` renderer-to-agent
+          #   message; nil when a check failed
+          def to_h
+            message
+          end
+
+          # @return [Hash] the AG-UI `forwardedProps` carrying the action (and the
+          #   data model when the surface asked for it); empty when invalid
+          def forwarded_props
+            return {} unless valid?
+
+            props = { "userAction" => message["action"] }
+            props["dataModel"] = surface.data if surface.send_data_model
+            { "a2uiAction" => props }
+          end
+        end
+
+        # @return [Hash{String => Surface}] live surfaces by id
+        attr_reader :surfaces
+        # @return [Array<Hash>] renderer-to-agent error messages, in order
+        attr_reader :errors
+        # @return [Array<String>] ids of deleted surfaces, in order
+        attr_reader :deleted
+        # @return [Array<Hash>] renderer-to-agent `rendererFunctionResponse` messages, in order
+        attr_reader :responses
+        # @return [Hash{String => Object}] catalog bindings by catalog id
+        attr_reader :catalogs
+
+        # @param catalogs [Hash{String => Object}] catalog bindings by id
+        # @param default_catalog [Object, nil] the binding for unknown catalog ids
+        #   (Poetry's own when nil)
+        def initialize(catalogs: A2UI.catalogs, default_catalog: nil)
+          @catalogs = catalogs
+          @default_catalog = default_catalog || catalogs[Catalog::DEFAULT_ID] || catalogs.values.first
+          @surfaces = {}
+          @errors = []
+          @deleted = []
+          @responses = []
+        end
+
+        # Applies one envelope message. Returns the ids of the surfaces
+        # it changed (a deleted surface counts); problems are recorded in
+        # {#errors} and return no ids.
+        #
+        # @param message [Hash]
+        # @return [Array<String>]
+        def apply(message)
+          key = message_key(message)
+          return [] unless key
+
+          body = message[key]
+          return reject("INVALID_MESSAGE", "#{key} must be an object") unless body.is_a?(Hash)
+
+          send(:"apply_#{key.gsub(/([A-Z])/) { "_#{::Regexp.last_match(1).downcase}" }}", body)
+        end
+
+        # @param messages [Array<Hash>]
+        # @return [Array<String>] the changed surface ids, deduplicated
+        def apply_all(messages)
+          Array(messages).flat_map { |message| apply(message) }.uniq
+        end
+
+        # Applies the A2UI messages an AG-UI `a2ui-surface` activity
+        # carries (an `a2ui_operations`, `messages`, or `operations` list,
+        # or one bare message).
+        #
+        # @param content [Hash, Array]
+        # @return [Array<String>] the changed surface ids
+        def apply_activity(content)
+          list = case content
+                 when Array then content
+                 when Hash
+                   content["a2ui_operations"] || content["messages"] || content["operations"] || [content]
+                 else []
+                 end
+          apply_all(list.grep(Hash))
+        end
+
+        # @param surface_id [String]
+        # @return [Surface, nil]
+        def surface(surface_id)
+          @surfaces[surface_id]
+        end
+
+        # Turns a submitted surface form into the agent's `action`
+        # message: bound input values are written to the data model first
+        # (two-way binding syncs on an action), then the source
+        # component's event context resolves against the updated model.
+        # Returns nil when the source has no agent event (a local action,
+        # or an unknown component), and an invalid action - no message,
+        # `errors` by component key - when a `checks` rule fails.
+        #
+        # @param surface_id [String]
+        # @param source [String] the submit button's value (`id` or `id@scope`)
+        # @param values [Hash{String => Object}] submitted values by absolute pointer
+        # @param timestamp [Time]
+        # @return [Action, nil]
+        def action(surface_id:, source:, values: {}, timestamp: Time.now.utc)
+          surface = @surfaces[surface_id]
+          return unless surface
+
+          write_inputs(surface, values)
+          component_id, scope = source.to_s.split("@", 2)
+          component = surface.component(component_id)
+          event = component&.dig("action", "event")
+          return unless event.is_a?(Hash) && event["name"].is_a?(String)
+
+          failures = surface.failures
+          return Action.new(message: nil, surface: surface, errors: failures) if failures.any?
+
+          context = (event["context"] || {}).to_h { |name, value| [name.to_s, surface.resolve(value, scope)] }
+          action = { "name" => event["name"], "surfaceId" => surface_id, "sourceComponentId" => component_id,
+                     "timestamp" => timestamp.utc.iso8601(3), "context" => context }
+          action["userMessage"] = event["userMessage"] if event["userMessage"].is_a?(String)
+          Action.new(message: { "version" => "v#{PROTOCOL_VERSION}", "action" => action }, surface: surface, errors: {})
+        end
+
+        # @param catalog_id [String, nil]
+        # @return [Object] the catalog binding for an id (the default when unknown)
+        def catalog_for(catalog_id)
+          @catalogs[catalog_id] || @default_catalog
+        end
+
+        private
+
+        def message_key(message)
+          return reject("INVALID_MESSAGE", "message must be an object") && nil unless message.is_a?(Hash)
+
+          version = message["version"]
+          unless version.nil? || version == "v#{PROTOCOL_VERSION}"
+            reject("INVALID_MESSAGE", "unsupported version #{version.inspect}")
+            return
+          end
+
+          keys = MESSAGE_KEYS & message.keys
+          return keys.first if keys.length == 1
+
+          reject("INVALID_MESSAGE", "message must carry exactly one of #{MESSAGE_KEYS.join(", ")}")
+          nil
+        end
+
+        def apply_create_surface(body)
+          surface_id = body["surfaceId"]
+          return reject("INVALID_MESSAGE", "createSurface.surfaceId is required") unless surface_id.is_a?(String)
+          if @surfaces[surface_id]
+            return reject("DUPLICATE_SURFACE", "surface #{surface_id} already exists",
+                          surface_id)
+          end
+
+          catalog_id = body["catalogId"]
+          surface = Surface.new(id: surface_id, catalog: catalog_for(catalog_id), catalog_id: catalog_id,
+                                send_data_model: body["sendDataModel"] == true, data: body["dataModel"])
+          @surfaces[surface_id] = surface
+          record(surface_id, surface.update_components(body["components"])) if body["components"].is_a?(Array)
+          [surface_id]
+        end
+
+        def apply_update_components(body)
+          surface = find(body, "updateComponents") or return []
+          components = body["components"]
+          unless components.is_a?(Array)
+            return reject("INVALID_MESSAGE", "updateComponents.components must be an array", surface.id)
+          end
+
+          record(surface.id, surface.update_components(components))
+          [surface.id]
+        end
+
+        def apply_update_data_model(body)
+          surface = find(body, "updateDataModel") or return []
+          return reject("INVALID_MESSAGE", "updateDataModel.value is required", surface.id) unless body.key?("value")
+
+          surface.update_data(body["path"], body["value"])
+          [surface.id]
+        end
+
+        def apply_delete_surface(body)
+          surface = find(body, "deleteSurface") or return []
+          @surfaces.delete(surface.id)
+          @deleted << surface.id
+          [surface.id]
+        end
+
+        # An agent may invoke a function its catalog admits (`agentOnly` or
+        # `rendererOrAgent`); the value comes back as a
+        # `rendererFunctionResponse`, anything else as the spec's error.
+        def apply_call_renderer_function(body)
+          call = body["callFunction"].is_a?(Hash) ? body["callFunction"] : {}
+          name = call["call"].to_s
+          catalog = catalog_for(call["catalogId"])
+          unless catalog.functions.agent_callable?(name)
+            return refuse_call(body, "function #{name.inspect} is not invocable by an agent")
+          end
+
+          evaluator = Evaluator.new(Surface.new(id: "callRendererFunction", catalog: catalog))
+          value = catalog.functions.call(name, evaluator.argument(call["args"] || {}), evaluator)
+          @responses << { "version" => "v#{PROTOCOL_VERSION}",
+                          "rendererFunctionResponse" => { "functionCallId" => body["functionCallId"],
+                                                          "value" => value } }
+          []
+        rescue Functions::Error, Expression::SyntaxError => e
+          refuse_call(body, e.message)
+        end
+
+        def refuse_call(body, message)
+          error = { "code" => "INVALID_FUNCTION_CALL", "message" => message }
+          error["functionCallId"] = body["functionCallId"] if body["functionCallId"]
+          @errors << { "version" => "v#{PROTOCOL_VERSION}", "error" => error }
+          []
+        end
+
+        # This renderer never calls agent functions; a response has nothing to match.
+        def apply_agent_function_response(_body)
+          []
+        end
+
+        def find(body, key)
+          surface_id = body["surfaceId"]
+          surface = surface_id.is_a?(String) && @surfaces[surface_id]
+          reject("UNKNOWN_SURFACE", "#{key}: no surface #{surface_id.inspect}", surface_id) unless surface
+          surface || nil
+        end
+
+        def record(surface_id, validation_errors)
+          validation_errors.each do |error|
+            @errors << { "version" => "v#{PROTOCOL_VERSION}",
+                         "error" => { "code" => error[:code], "surfaceId" => surface_id, "path" => error[:path],
+                                      "message" => error[:message] } }
+          end
+        end
+
+        def reject(code, message, surface_id = nil)
+          error = { "code" => code, "message" => message }
+          error["surfaceId"] = surface_id if surface_id.is_a?(String)
+          @errors << { "version" => "v#{PROTOCOL_VERSION}", "error" => error }
+          []
+        end
+
+        # Only bound paths are writable, each coerced to its input's kind.
+        def write_inputs(surface, values)
+          return unless values.respond_to?(:each_pair)
+
+          kinds = surface.inputs.to_h { |input| [input[:path], input[:kind]] }
+          values.each_pair do |path, value|
+            kind = kinds[path.to_s] or next
+
+            surface.update_data(path.to_s, coerce(value, kind))
+          end
+        end
+
+        def coerce(value, kind)
+          case kind
+          when :boolean then %w[true 1 on].include?(value.to_s.downcase)
+          when :number then number(value)
+          when :string_list then Array(value).map(&:to_s).reject(&:empty?)
+          else value.is_a?(Array) ? value.join(", ") : value.to_s
+          end
+        end
+
+        def number(value)
+          text = value.to_s
+          return nil if text.strip.empty?
+
+          text.match?(/\A-?\d+\z/) ? text.to_i : Float(text, exception: false)
+        end
+      end
+    end
+  end
+end

data/lib/poetry/agent/a2ui/streams.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "../agui/turbo_stream"
+
+module Poetry
+  module Agent
+    module A2UI
+      # Delivers a {Session}'s surfaces as Turbo Streams: a surface's first
+      # appearance appends into the container (when one is given), every
+      # later change is a versioned replace of its wrapper (`vreplace`,
+      # from the AG-UI relay: a stale version never overwrites a newer
+      # one), and a deletion removes it. The host renders each surface
+      # through the `render` callable (typically a {Renderer}).
+      #
+      # @example
+      #   streams = Streams.new(session: session, container: "surfaces",
+      #                         render: ->(surface) { Renderer.new(surface, view: view_context).call })
+      #   response.stream.write(AGUI::TurboStream.sse(streams.apply(message)))
+      class Streams
+        # @return [Session]
+        attr_reader :session
+
+        # @param session [Session]
+        # @param render [#call] `(surface) -> html`
+        # @param container [String, nil] the DOM id new surfaces append into
+        # @param morph [Boolean] morph replaced surfaces (the default) so local state -
+        #   typed text, a selected tab, an open dialog - survives an update; false swaps
+        def initialize(session:, render:, container: nil, morph: true)
+          @session = session
+          @render = render
+          @container = container
+          @morph = morph
+          @seen = {}
+        end
+
+        # Applies one message and returns the streams for what changed.
+        #
+        # @param message [Hash]
+        # @return [String] Turbo Stream HTML (empty when nothing changed)
+        def apply(message)
+          streams(session.apply(message))
+        end
+
+        # @param messages [Array<Hash>]
+        # @return [String] Turbo Stream HTML
+        def apply_all(messages)
+          streams(session.apply_all(messages))
+        end
+
+        # The streams for a set of surface ids.
+        #
+        # @param ids [Array<String>]
+        # @return [String]
+        def streams(ids)
+          Array(ids).map { |id| stream_for(id) }.join
+        end
+
+        # @param id [String]
+        # @return [String] the stream for one surface (remove, append, or vreplace)
+        def stream_for(id)
+          target = Renderer.element_id(id)
+          surface = session.surface(id)
+          return AGUI::TurboStream.remove(target) unless surface
+
+          html = @render.call(surface)
+          first = @container && !@seen[id]
+          @seen[id] = true
+          first ? AGUI::TurboStream.append(@container, html) : AGUI::TurboStream.vreplace(target, html, morph: @morph)
+        end
+
+        # Marks surfaces as already on the page (rendered server-side), so
+        # their next change replaces instead of appending.
+        #
+        # @param ids [Array<String>]
+        # @return [void]
+        def mark_seen(*ids)
+          ids.flatten.each { |id| @seen[id] = true }
+        end
+      end
+    end
+  end
+end