poetry-agent 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b23fc776e813d4bc6418bfbdc982f06756c3b7cc12eeac3b36d210fd29e63aac
-  data.tar.gz: 90ee7680d11bcc1fa12cdea0f7dd8543b972af0de5f491b0b364565eea672a05
+  metadata.gz: f94b26ba2c90475193b090c1deba25d33ffad8fbec0c3b4fdee0e22be1c7a977
+  data.tar.gz: 8d504ccbe9f96573ffe89dee1e7ed80ccefd1b5af93a9f9543aa70228ff5c059
 SHA512:
-  metadata.gz: 428611c9a1fe1618a72f5ae5f3236890080f3b8a20dd34cedb80cfa8c8162c1ef571a12b8e1de0efb7d25703475f8096e3da8242bc521a9c7275e99699935388
-  data.tar.gz: 910b7c98b3525cac9059f118b5199a638e360f10dfdc333b6d374255fd5174433a40fd6f50b330f6917b52e0a4b7aef8c030541aa6ec424d11eef2843912e991
+  metadata.gz: 9e565a75006736af0eae0d6ca7e7284c00c7450399abde58de0e9aafac1869a7f72fd77f256a3100e41525eeea2a92751ecb9b3b03a1324450453ab71402f2e3
+  data.tar.gz: 23e554fad8c091dca3ca66f7947452f870f88586d78901470024fd9d8f84b10a15129c35c8f2cba5b4f72044b9f4eb7af3f8d35e07dec630debba4de1b704d87

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.1.3] - 2026-09-13
+
+### Fixed
+
+- A2UI's native catalog supplies the render-stable key as `id:` to a component that requires one (Field, MessageScroller), since an agent never sets ids. On 0.1.2 the values tier refused the missing option and the renderer swallowed the error as a warning, so a Field rendered nothing.
+- The MCP `check` tool knows the app's own `poetry_*` helper methods (`app/helpers`, read boot-free), committed registry or not: the adapter `poetry:pagination` copies in no longer reads as an unknown component.
+
+## [0.1.2] - 2026-09-13
+
+### Changed
+
+- A tool called without one of its declared required arguments (or with it blank) answers an error naming the argument; `check` in particular no longer reports PASS for a call that sent no `source`. `compose` and `build_page` keep answering a blank brief with their own guidance.
+
+- `compose`, `build_page`, `list_components` and `describe_component` name an app component's helper from the registry, and an app component without one by the class to render, never an invented `poetry_` name. Once the app committed its registry that file is the truth and the component sources are not scanned; an invalid committed registry is not a root and does not crash the server.
+
+- The WebMCP agent-focus styling (`:tool-form-active` on the form an agent fills, `:tool-submit-active` on its submit) moves here from poetry-ui's nine theme fragments, where it was identical in every theme: `app/assets/stylesheets/poetry-agent.css`, plain CSS on the theme's tokens, vendored by `poetry:install` into `layer(base)` when this gem is bundled. Hosts without poetry-agent no longer carry the rules or the two warnings the CSS optimizer prints for the origin-trial pseudo-classes on every minified build (the Rails Tailwind task minifies by default).
+- Controllers manifests are registered by the same convention, boot-free: every bundled gem's and the app's own (`bin/rails poetry:stimulus:manifest`), so the `check` tool validates chart, agent and host controllers like core's.
+- The server assembles from every published registry in the bundle plus the app's own committed one (`bin/rails poetry:registry`), by convention: no gem is named, a third-party engine that commits a registry is served, and an app's components describe, check and compose with full contracts under their declared helpers. `Server.from_registries` merges roots; `from_registry` remains for one.
+- The MCP `check` tool knows the host application's own component helpers: a boot-free scan of the app directory's component files for `helper :name` declarations adds those names to the valid set, so the tool agrees with `bin/rails poetry:check` that the helper exists. Their option contracts stay with the booted check.
+
 ## [0.1.1] - 2026-09-08
 
 Lockstep release with the family; no changes in this gem.

data/app/assets/stylesheets/poetry-agent.css

@@ -0,0 +1,25 @@
+/* poetry-agent: the WebMCP agent-focus states. The browser applies
+   :tool-form-active to the form an agent is filling through a declarative
+   tool and :tool-submit-active to its submit; these rules make that a
+   designed state on the theme's tokens instead of the browser's default.
+   :where() keeps both rules forgiving (zero specificity, and a browser
+   without the pseudo-classes drops the argument, not the rule), so a host
+   restyles them with any rule of its own. Plain CSS on purpose: the file
+   is vendored into the host's Tailwind entry (`poetry:install` when this
+   gem is bundled) and imported into layer(base) beside the theme.
+
+   The CSS optimizer that runs on every minified build (the Rails
+   Tailwind task minifies by default; TAILWINDCSS_DEBUG=1 skips it) does
+   not yet know these origin-trial pseudo-classes and warns twice; that is
+   the optimizer, not the CSS - the rules compile and ship. Hosts without
+   poetry-agent never carry them. */
+:where(form:tool-form-active) {
+  border-radius: var(--radius);
+  outline: 2px dashed color-mix(in oklab, var(--ring) 60%, transparent);
+  outline-offset: 4px;
+}
+
+:where(:tool-submit-active) {
+  border-color: var(--ring);
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--ring) 50%, transparent);
+}

data/lib/poetry/agent/a2ui/catalogs/native.rb

@@ -97,6 +97,10 @@ module Poetry
             by_name[component["component"].to_s] || [nil, nil]
           end
 
+          def option_required?(entry, name)
+            Array(entry["options"]).any? { |option| option["name"] == name && option["required"] }
+          end
+
           def attributes(component, entry, scope, renderer)
             attributes = {}
             Array(entry["styles"]).each do |axis|
@@ -109,6 +113,10 @@ module Poetry
 
               attributes[name.to_sym] = renderer.resolve(component[name], scope)
             end
+            # An id the component requires (Field: the control its label
+            # names) is not the agent's to set, so the render-stable key
+            # stands in and the component builds instead of vanishing.
+            attributes[:id] = renderer.stable_key if option_required?(entry, "id") && !attributes.key?(:id)
             bound = BOUND_OPTIONS.find { |name| renderer.surface.binding?(component[name]) }
             if bound && option_names.include?("name") && !component.key?("name")
               attributes[:name] = renderer.input_name(component[bound]["path"], scope)

data/lib/poetry/agent/mcp/bundled.rb

@@ -12,23 +12,37 @@ module Poetry
       module Bundled
         module_function
 
-        # @param root [String, nil] a registry root; defaults to poetry-ui
-        # @param app_root [String] the host app (build_page's probe/direct
+        # @param root [String, nil] one more registry root to serve (the
+        #   bundle's published registries and the app's committed one are
+        #   found on their own)
+        # @param app_root [String] the host app (its committed registry, when
+        #   `bin/rails poetry:registry` wrote one; build_page's probe/direct
         #   steps read its config/theme)
         # @return [Server]
         # @raise [ArgumentError] when no component registry is found
         def server(root: nil, app_root: Dir.pwd)
           ui = soft_require("poetry/ui")
-          root ||= ui ? Poetry::Ui.root.to_s : Gem::Specification.find_all_by_name("poetry-ui").first&.gem_dir
-          registry = root && File.join(root, Poetry::Core::Registry::RELATIVE_PATH)
-          unless registry && File.exist?(registry)
-            raise ArgumentError, "no component registry at #{registry || "(no poetry-ui found)"} - pass root:"
-          end
+          roots = Poetry::Core::Registry.gem_roots(app_root: app_root).map(&:to_s)
+          # Controllers manifests by the same convention, boot-free: every
+          # bundled gem's and the app's own, so the check tool validates
+          # chart, agent and host controllers like core's.
+          manifest_roots = Poetry::Core::Registry.gem_roots(app_root: app_root, registry: false)
+          Poetry::Core::Stimulus::Manifest.register_roots(manifest_roots)
+          roots.unshift(root) if root && !roots.include?(root)
+          raise ArgumentError, "no published component registry in the bundle - pass a root" if roots.empty?
 
           skills, helpers, recipes =
-            ui ? [Poetry::Ui.agent_skills, Poetry::Ui.helper_names, Poetry::Ui.recipe_items.summaries] : [{}, nil, []]
-          Server.from_registry(root, icon_names: icon_names, helpers: helpers, skills: skills,
-                                     app_root: app_root, recipes: recipes)
+            if ui
+              [Poetry::Ui.agent_skills(app_root: app_root), Poetry::Ui.helper_names, Poetry::Ui.recipe_items.summaries]
+            else
+              [{}, nil, []]
+            end
+          # The valid helper set: the registries' own sections carry every
+          # gem helper and the app's declared ones; poetry-ui's live names
+          # ride along when the gem is loaded, for a registry that predates
+          # the sections.
+          Server.from_registries(roots, icon_names: icon_names, helpers: helpers, skills: skills,
+                                        app_root: app_root, recipes: recipes)
         end
 
         # The lucide names, or nil for a host without poetry-lucide (check

data/lib/poetry/agent/mcp/server.rb

@@ -27,6 +27,10 @@ module Poetry
       # The serverInfo payload returned by the initialize handshake.
       SERVER_INFO = { "name" => "poetry-agent", "version" => Poetry::Agent::VERSION }.freeze
 
+      # Tools that answer a blank brief with guidance of their own (the
+      # block catalog, what to send) rather than a pass.
+      TOLERATES_BLANK = %w[compose build_page].freeze
+
       # The tool roster the server advertises (tools/list): MCP Tool-shaped
       # definitions, read-only by construction.
       TOOLS = [
@@ -196,13 +200,47 @@ module Poetry
         # Lazy because the usage skill is generated from the registry on
         # first fetch - server boot stays instant.
         def self.from_registry(root, helpers: nil, icon_names: nil, skills: {}, app_root: nil, recipes: [])
-          committed = Poetry::Core::Registry.committed(root)
+          from_registries([root], helpers: helpers, icon_names: icon_names, skills: skills,
+                                  app_root: app_root, recipes: recipes)
+        end
+
+        # Several registry roots as one catalog (Registry.merged: later
+        # roots win a path collision, block templates resolve to absolute
+        # paths): the gems' published registries and, when the app
+        # committed its own with `bin/rails poetry:registry`, the app's -
+        # its components then describe, check and compose like a gem's.
+        def self.from_registries(roots, helpers: nil, icon_names: nil, skills: {}, app_root: nil, recipes: [])
+          committed = Poetry::Core::Registry.merged(roots, source_root: roots.first)
+          # The app's own components declare their helpers in source
+          # (`helper :name`); a boot-free scan of app_root's component files
+          # adds those names to the valid set, so the check tool agrees with
+          # `bin/rails poetry:check` that the helper exists (their option
+          # contracts are only known to the booted check).
+          helper_entries = (committed.helpers || {}).dup
+          # Only for an app that never committed its registry: once the
+          # file exists it is the truth (helpers, contracts), not the scan.
+          if app_root && !Poetry::Core::Registry.published_at?(app_root)
+            Poetry::Core::HostComponents.declared_helpers(root: app_root).each { |name| helper_entries[name] ||= {} }
+          end
+          helpers = (helpers + mapped_helpers(committed.entries)).uniq if helpers
+          # The app's own poetry_* helper methods (app/helpers, boot-free):
+          # valid names with contracts of their own, whether or not the
+          # registry is committed - no registry lists a helper method.
+          host_helpers = app_root ? Poetry::Core::HostComponents.helper_methods(root: app_root) : nil
           catalog = Poetry::Core::Check::Catalog.new(committed.entries, helpers: helpers,
-                                                                        helper_entries: committed.helpers,
+                                                                        helper_entries: helper_entries,
                                                                         icon_names: icon_names,
-                                                                        helper_args: committed.helper_args)
+                                                                        helper_args: committed.helper_args,
+                                                                        host_helpers: host_helpers)
           new(entries: committed.entries, catalog: catalog, blocks: committed.blocks || {},
-              root: root, skills: skills, app_root: app_root, recipes: recipes)
+              root: committed.source_root.to_s, skills: skills, app_root: app_root, recipes: recipes)
+        end
+
+        # The helper each entry names, so an explicit helper list never
+        # hides another root's components (an entry without one has no
+        # helper to map).
+        def self.mapped_helpers(entries)
+          entries.filter_map { |path, entry| Poetry::Core::Registry.helper_for(path, entry) }
         end
 
         # app_root: the HOST app directory (where `bundle exec poetry-agent`
@@ -295,6 +333,10 @@ module Poetry
         def call_tool(params)
           name = params["name"]
           arguments = params["arguments"] || {}
+          if !TOLERATES_BLANK.include?(name) && (missing = missing_arguments(name, arguments)).any?
+            return tool_content("#{name}: missing required argument#{"s" if missing.size > 1} " \
+                                "#{missing.join(", ")} (see tools/list for the schema)", error: true)
+          end
           text =
             case name
             when "compose" then compose(arguments)
@@ -312,12 +354,21 @@ module Poetry
           tool_content(text)
         end
 
+        # The tool's declared required arguments that are absent or blank -
+        # a wrong key never reaches a tool as an empty value it would pass.
+        def missing_arguments(name, arguments)
+          tool = TOOLS.find { |candidate| candidate["name"] == name }
+          return [] unless tool
+
+          Array(tool.dig("inputSchema", "required")).select { |key| arguments[key].to_s.strip.empty? }
+        end
+
         # --- the tools (project the built surfaces) ---
 
         def list_components
           @entries.map do |path, entry|
             interactive = entry["controllers"]&.any? ? " [interactive]" : ""
-            "- #{title(path)} (`#{helper(path)}`)#{interactive}: #{summary(entry)}"
+            "- #{title(path)} (#{helper_label(path)})#{interactive}: #{summary(entry)}"
           end.join("\n")
         end
 
@@ -327,7 +378,7 @@ module Poetry
 
           entry = @entries.fetch(path)
           detail = arguments.fetch("detail", "detailed")
-          lines = ["# #{title(path)} (`#{helper(path)}`)", summary(entry)]
+          lines = ["# #{title(path)} (#{helper_label(path)})", summary(entry)]
           lines.concat(surface_lines(entry)) if %w[detailed full].include?(detail)
           lines.concat(full_lines(entry)) if detail == "full"
           # The block back-reference: a screen containing this
@@ -434,7 +485,9 @@ module Poetry
         def component_route(scored, components)
           lines = ["No block covers this brief - component-scale work."]
           lines << if components.any?
-                     "Matched components: #{components.map { |name| "#{name} (`poetry_#{name}`)" }.join(", ")} - " \
+                     "Matched components: #{components.map do |name|
+                       "#{name} (#{helper_label(path_for(name))})"
+                     end.join(", ")} - " \
                        "describe_component for the contracts."
                    else
                      "No component name matched either - list_components for the catalog."
@@ -860,7 +913,7 @@ module Poetry
               convention = args && slot["types"].all? { |type| args[type]&.zero? } ? " - options as keywords" : ""
               facets << "types #{slot["types"].join("|")}#{convention}"
             end
-            facets << "takes #{helper(slot["component"])} props, not a block" if slot["component"]
+            facets << "takes #{helper_text(slot["component"])} props, not a block" if slot["component"]
             # The render-crash seams, stated where agents read them.
             if (yieldless = slot["yieldless"])
               setters = yieldless.map { |name| "with_#{name}" }.join("/")
@@ -936,14 +989,24 @@ module Poetry
         end
 
         # name may be the title (button, command_dialog) or the full path.
+        # A registry path, a title, or a helper name (the poetry_ convention
+        # or an app component's declared helper).
         def resolve(name)
           return name if @entries.key?(name)
 
-          @entries.keys.find { |path| title(path) == name }
+          @entries.keys.find { |path| title(path) == name || helper(path) == name }
         end
 
-        def title(path) = path.split("/").drop(2).join("_")
-        def helper(path) = "poetry_#{title(path)}"
+        # A gem path drops its poetry/<gem>/ prefix; an app path is its own.
+        def title(path) = (path.start_with?("poetry/") ? path.split("/").drop(2) : path.split("/")).join("_")
+        # The helper the registry names for the entry, nil for an app
+        # component that declared none (it renders by class).
+        def helper(path) = Poetry::Core::Registry.helper_for(path, @entries[path] || {})
+        # The helper to render the entry by, or the class when it has none.
+        def helper_text(path) = helper(path) || "render #{@entries.dig(path, "class_name") || path}"
+        # The same, the helper in backticks.
+        def helper_label(path) = (name = helper(path)) ? "`#{name}`" : helper_text(path)
+        def path_for(name) = @entries.keys.find { |path| title(path) == name }
 
         def result(id, value) = { "jsonrpc" => "2.0", "id" => id, "result" => value }
 

data/lib/poetry/agent/version.rb

@@ -3,6 +3,6 @@
 module Poetry
   module Agent
     # The gem version (lockstep with the poetry family).
-    VERSION = "0.1.1"
+    VERSION = "0.1.3"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: poetry-agent
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Matt Solt
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.1
+        version: 0.1.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.1
+        version: 0.1.3
 description: 'The agent-interop gem of Poetry, the AI-native UI component library.
   Five surfaces: the boot-free poetry-agent MCP server (the component contract over
   Model Context Protocol, with runtime skill delivery); the WebMCP runtime that registers
@@ -43,6 +43,7 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- app/assets/stylesheets/poetry-agent.css
 - app/javascript/poetry/agent/a2ui_surface_controller.js
 - app/javascript/poetry/agent/adapter.js
 - app/javascript/poetry/agent/agui_client_tool_controller.js