poetry-agent 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b431842dfbb921394ed37568220e59c06ac11b2efc67d8845f9087faa472eda
-  data.tar.gz: 83b79d109c54cf5de587c8d3d61751c5d4da2a64408693cce714f0ed2b1404a0
+  metadata.gz: cdfdb5620724755c575e18ce6bfd75b48bd4237ca0f637d0b909057a52cfc46f
+  data.tar.gz: 23014ea1b745fafb3e48e3337f399df235417352650a469e07d26a52821d905b
 SHA512:
-  metadata.gz: 7cfdb8e3c559c77d2eae086165cf35ce7337a156c229cd5bf9e9ab9c143d89b1ec269cd62586cab010d8442e285a22c6b9dba299c0841e52ca6f55079ac4a4cf
-  data.tar.gz: 8698481f32a719b868bf2d3cbf36d217e140754e627075b6d892d4e22d6a0e518950a58e92a3eb8a688bfff4d87f713f2781d495310ba8d0321c21761209ac60
+  metadata.gz: 0fed74653f7b49002c96d01a6157bca3d22c0c2fde05a01570c3e1c8cc7e22a39157a062a516f5ae263dc758180576ac56bcc2d9d9d8fbfbe83b3501c5ea1636
+  data.tar.gz: b6d84fc27e506a684f77cf6b088a545f62b826aac36cd09c2d4eb0f3dae9f29217d0f9d7f36f261005117ec3a71c853eff0fe91f23f2e33733d4c5b9515f8e03

data/CHANGELOG.md

@@ -1,6 +1,21 @@
 # Changelog
 
-## [Unreleased]
+## [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.
 
 ## [0.1.0] - 2026-09-05
 

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/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,42 @@ 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
           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)
           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 +328,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 +349,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 +373,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 +480,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 +908,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 +984,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.0"
+    VERSION = "0.1.2"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: poetry-agent
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Matt Solt
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.2
 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