poetry-agent 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 91f531c6479141170644c48162b3a67b82936fdc0a00ea2ae07deb620459e29c
+  data.tar.gz: c8cfb8421e10c1247f4e6e566288dec8fb70d4721653d5a88dac8ec07f3f14d1
+SHA512:
+  metadata.gz: 27a86f9ea8064c7e901d9b9bd43e33e7d76f1d4fd9b0ca90b56a46798336c32574e78b02c510683f871cc9d0631eac9ec9c63d9aad1eb64d33a77d546ae9a804
+  data.tar.gz: 7f9c50d5b9acf878da099a80120268ef387114d0b6f85a48486362a1263434fc0aaf1195350867823703bfd65d0f6757df98089f310050ef02334809ff03cfc6

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+
+## [Unreleased]

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Matt Solt
+
+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,51 @@
+# poetry-agent
+
+The agent-interop gem of the [poetry](https://github.com/roboruby/poetry) component library: every surface through which an agent reaches the component contract, projected from the one registry the other gems build.
+
+Five surfaces ship:
+
+- **The MCP server** — `bundle exec poetry-agent`, a boot-free, read-only stdio MCP server (JSON-RPC 2.0, no SDK dependency) for coding agents in Claude Code, Cursor, VS Code, Zed, and RubyMine: `compose`, `build_page`, `list_components`, `describe_component`, `check`, `list_blocks`, `describe_block`, `list_recipes`, `get_skill`, `guidance`. The same server mounts over HTTP at a same-origin path (`mount Poetry::Agent::MCP::HTTP.new => "/mcp"`) for in-page bridges.
+- **The WebMCP runtime** — `registerPoetryAgent(application)` registers a rendered component's declared tools with the browser's `document.modelContext` when a call opts in (`poetry_tabs(webmcp: "sections")`), dispatching each call to the component's own Stimulus action; declarative forms (`poetry_webmcp_form`) answer agent-invoked submits through `SubmitEvent.respondWith`; an `Origin-Trial` middleware serves trial tokens.
+- **The AG-UI relay** — `Poetry::Agent::AGUI`: a Rails-side client of the Agent-User Interaction protocol. `Client` runs an agent endpoint and yields its events, `Transcript` folds them into chat-shaped messages (text, reasoning, tool calls with state, activities), shared state (JSON Patch), interrupts, and the tool calls the browser must execute, and `Relay` renders every change as a versioned Turbo Stream through the host's own row partial. A rendered component's declared tools are advertised as the agent's frontend tools (`Poetry::Agent::AGUI.tool_descriptor`) and executed by the `poetry--agent--agui-client-tool` bridge through the same registrar WebMCP uses, with or without a WebMCP browser.
+- **The A2UI catalog** — `Poetry::Agent::A2UI::Catalog.from_registry(root)` projects the component registry into an A2UI v1.0 catalog document (JSON Schema per component: style axes as enums, options as typed properties, slots as child references, the content block as `text` or `children`), so any A2UI agent generates against Poetry's vocabulary and a renderer validates against the same document.
+- **The A2UI renderer** — `Poetry::Agent::A2UI::Session` folds the A2UI envelope (`createSurface`, `updateComponents`, `updateDataModel`, `deleteSurface`) into surfaces and answers what it cannot honor with the spec's renderer-to-agent errors; `Renderer` renders a surface through the host's view context with a catalog binding — the spec's basic catalog mapped onto Poetry's components (`Catalogs::Basic`) or Poetry's own catalog rendered straight from the registry (`Catalogs::Native`); `Streams` delivers every change as a versioned Turbo Stream. A surface renders as a form: bound inputs are named by their data-model pointer, every agent action is a submit button, and `Session#action` turns the submitted form into the spec's `action` message (two-way binding syncs on the action, as the spec asks). The catalog's functions run on the server (`Functions.basic`: `formatString` interpolation through the `Expression` grammar, the formatters, the validators behind `checks`, the combinators, `openUrl`) and a failing check rejects the action with its failures rendered under their controls; the same rules run in the browser as the user types (`poetry--agent--a2ui-surface`), disabling a button whose checks fail. Every rendered component carries a render-stable key and updates arrive as morphing replaces, so typed text, a selected tab, and an open dialog survive the agent's next message. A function a catalog marks `agentOnly` or `rendererOrAgent` answers an agent's `callRendererFunction` with a response.
+
+## Install
+
+```ruby
+gem "poetry-agent"
+```
+
+```js
+// app/javascript/controllers/index.js
+import { registerPoetryControllers } from "@poetry/controllers"
+import { registerPoetryAgent } from "@poetry/agent"
+registerPoetryControllers(application)
+registerPoetryAgent(application)
+```
+
+Loading the gem is the integration: the engine registers its controllers manifest with poetry-core (so `webmcp:` roots validate at render), pins `@poetry/agent` in the importmap, and mounts the origin-trial middleware.
+
+```ruby
+# config/initializers/poetry_agent.rb
+Poetry::Agent.configure do |config|
+  config.origin_trial_tokens = ENV.fetch("WEBMCP_ORIGIN_TRIAL_TOKENS", "").split(",")
+  config.registration_budget = 20
+end
+```
+
+## Safety by construction
+
+Nothing registers until a rendered instance opts in. Tools are read-only unless declared `mutating: true`. `autosubmit` is GET-only. Registrations are budgeted per document, never repeated for an unchanged payload, never made under Turbo's cache preview. Every call is validated in code (required, unknown, and mistyped parameters, enum membership) and problems return as descriptive strings so an agent corrects its call; results carry the resulting state. An agent-invoked form answers through `respondWith`, then the page catches up with the answer (a Turbo visit for a GET, a rendered stream, the redirect target of a POST).
+
+## Development
+
+```bash
+bin/setup && bundle exec rake   # tests, rubocop, yard gates
+npm install && npm test         # the runtime's JS tests (vitest + jsdom)
+npm run manifest                # regenerate config/controllers_manifest.json
+```
+
+## License
+
+MIT.

data/app/javascript/poetry/agent/a2ui_surface_controller.js

@@ -0,0 +1,141 @@
+import { Controller } from "@hotwired/stimulus"
+
+// The client side of an A2UI surface's checks: the server renders the
+// program (every checked component's rules with absolute bindings, the
+// bound inputs by path with their kinds, and the data model) and this
+// controller evaluates it as the user types - a button whose own checks
+// fail is disabled, a failing input is marked invalid and its error slot
+// carries the message. The five validators and the three combinators are
+// the checks vocabulary; anything else passes here and is judged by the
+// server, which re-runs every rule on the action.
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+export default class extends Controller {
+  static values = { program: Object }
+
+  connect() {
+    this.evaluate()
+  }
+
+  evaluate() {
+    const checks = this.programValue?.checks || {}
+    for (const [key, entry] of Object.entries(checks)) {
+      const failures = (entry.rules || []).map((rule) => this.failure(rule)).filter(Boolean)
+      this.apply(key, entry.kind, failures)
+    }
+  }
+
+  // The message of a failing rule, or null when it passes.
+  failure(rule) {
+    const result = this.resolve(rule.condition)
+    if (result === null) return null // unknown here; the server decides
+    const valid = result && typeof result === "object" ? result.valid === true : truthy(result)
+    if (valid) return null
+    return (result && typeof result === "object" && result.message) || rule.message || "Check failed"
+  }
+
+  apply(key, kind, failures) {
+    for (const element of this.element.querySelectorAll(`[data-a2ui-key="${escapeAttribute(key)}"]`)) {
+      if (kind === "button") {
+        element.disabled = failures.length > 0
+      } else {
+        element.setAttribute("aria-invalid", failures.length > 0 ? "true" : "false")
+      }
+    }
+    const slot = this.element.querySelector(`[data-a2ui-error-for="${escapeAttribute(key)}"]`)
+    if (slot) {
+      slot.textContent = failures[0] || ""
+      slot.hidden = failures.length === 0
+    }
+  }
+
+  resolve(value) {
+    if (value === null || typeof value !== "object") return value
+    if (Array.isArray(value)) return value.map((item) => this.resolve(item))
+    if (typeof value.path === "string") return this.read(value.path)
+    if (typeof value.call === "string") return this.call(value.call, value.args || {})
+    return value
+  }
+
+  call(name, rawArgs) {
+    const fn = FUNCTIONS[name]
+    if (!fn) return null
+    const args = {}
+    for (const [key, raw] of Object.entries(rawArgs)) args[key] = this.resolve(raw)
+    return fn(args)
+  }
+
+  // The current value of a bound path: the form control first, the
+  // server's model when no control carries it.
+  read(path) {
+    const kind = this.programValue?.inputs?.[path]
+    const name = `a2ui[values][${path}]`
+    if (kind === "boolean") {
+      const box = this.element.querySelector(`input[type="checkbox"][name="${escapeAttribute(name)}"]`)
+      return box ? box.checked : pointer(this.programValue?.model, path)
+    }
+    if (kind === "string_list") {
+      const boxes = [...this.element.querySelectorAll(`input[name="${escapeAttribute(name + "[]")}"]:checked`)].map((box) => box.value).filter((v) => v !== "")
+      if (boxes.length) return boxes
+      const picked = this.element.querySelector(`input[type="radio"][name="${escapeAttribute(name)}"]:checked`)
+      if (picked) return [picked.value]
+      const select = this.element.querySelector(`select[name="${escapeAttribute(name)}"], select[name="${escapeAttribute(name + "[]")}"]`)
+      if (select) return [...select.selectedOptions].map((option) => option.value).filter((v) => v !== "")
+      return this.element.querySelector(`[name="${escapeAttribute(name + "[]")}"], [name="${escapeAttribute(name)}"]`) ? [] : pointer(this.programValue?.model, path)
+    }
+    const control = this.element.querySelector(`[name="${escapeAttribute(name)}"]:not([type="hidden"])`)
+    if (!control) return pointer(this.programValue?.model, path)
+    if (kind === "number") return control.value === "" ? null : Number(control.value)
+    return control.value
+  }
+}
+
+// An attribute-selector value (jsdom has no CSS.escape; quoting is enough).
+const escapeAttribute = (value) => String(value).replace(/["\\]/g, "\\$&")
+
+const pointer = (document, path) => {
+  if (!document || path === "" || path === "/") return document
+  return path.replace(/^\//, "").split("/").reduce((node, token) => {
+    if (node === null || node === undefined) return undefined
+    const key = token.replace(/~1/g, "/").replace(/~0/g, "~")
+    return Array.isArray(node) ? node[Number(key)] : node[key]
+  }, document)
+}
+
+const truthy = (value) => {
+  if (value && typeof value === "object" && !Array.isArray(value)) return value.valid === true
+  if (typeof value === "string") return value !== "" && !["false", "0"].includes(value.toLowerCase())
+  return value !== null && value !== undefined && value !== false
+}
+
+const present = (value) => {
+  if (value === null || value === undefined) return false
+  if (typeof value === "string") return value.trim() !== ""
+  if (Array.isArray(value)) return value.length > 0
+  return true
+}
+
+const within = (n, min, max) => (min === undefined || min === null || n >= min) && (max === undefined || max === null || n <= max)
+
+const number = (value) => {
+  if (typeof value === "number") return Number.isFinite(value) ? value : null
+  if (typeof value !== "string" || value.trim() === "") return null
+  const parsed = Number(value)
+  return Number.isFinite(parsed) ? parsed : null
+}
+
+const FUNCTIONS = {
+  required: ({ value }) => ({ valid: present(value) }),
+  regex: ({ value, pattern }) => {
+    try { return { valid: new RegExp(pattern).test(String(value ?? "")) } } catch { return null }
+  },
+  length: ({ value, min, max }) => ({ valid: within(String(value ?? "").length, min, max) }),
+  numeric: ({ value, min, max }) => {
+    const n = number(value)
+    return { valid: n !== null && within(n, min, max) }
+  },
+  email: ({ value }) => ({ valid: EMAIL.test(String(value ?? "")) }),
+  and: ({ values }) => (Array.isArray(values) ? values : []).every(truthy),
+  or: ({ values }) => (Array.isArray(values) ? values : []).some(truthy),
+  not: ({ value }) => !truthy(value)
+}

data/app/javascript/poetry/agent/adapter.js

@@ -0,0 +1,77 @@
+// The document.modelContext adapter - the ONE file that knows the WebMCP
+// surface's shape, so API churn (the spec has changed twice this summer,
+// and the shipping browser trails it) stays a one-file fix. Everything
+// else in the runtime talks to this.
+//
+// Spec surface (rev 41d12f0): document.modelContext with
+// registerTool(tool, {signal, exposedTo}), getTools({fromOrigins}) resolving
+// RegisteredTool dictionaries whose inputSchema is an object,
+// executeTool(tool, inputObject, {signal}) resolving the stringified
+// result, and the toolchange event.
+//
+// Shipping-browser deltas this file absorbs (Chrome 151, measured
+// 2026-09-01; spec issue #278 tracks them): getTools() reports inputSchema
+// as a serialized JSON string, and executeTool() parses ONLY a JSON-string
+// argument - an object rejects with UnknownError("Failed to parse input
+// arguments"), not a TypeError.
+
+// The live ModelContext, or null where the browser exposes none - callers
+// treat null as "do nothing", exactly like an edge bridge would.
+export const modelContext = () =>
+  (typeof document !== "undefined" && document.modelContext) || null
+
+export const supported = () => modelContext() !== null
+
+// Registers one tool; resolves when the browser accepted it, rejects on a
+// duplicate name, an empty name/description, or an invalid schema.
+export const registerTool = (definition, { signal } = {}) =>
+  modelContext().registerTool(definition, signal ? { signal } : {})
+
+// A serialized schema marks the string-argument build; remembering it lets
+// executeTool go string-first without a wasted rejection.
+let stringArguments = false
+
+// The registered tools with inputSchema normalized to an object: parsed
+// when the browser serialized it, null when the text is not JSON.
+export const getTools = async (options = {}) => {
+  const tools = await modelContext().getTools(options)
+  for (const tool of tools) {
+    if (typeof tool.inputSchema !== "string") continue
+    stringArguments = true
+    try {
+      tool.inputSchema = JSON.parse(tool.inputSchema)
+    } catch {
+      tool.inputSchema = null
+    }
+  }
+  return tools
+}
+
+// Executes a tool with the spec's object arguments, falling back to the
+// JSON-string form the current Chrome build parses; when both shapes
+// reject, the first rejection surfaces.
+export const executeTool = async (tool, args = {}, options = {}) => {
+  const context = modelContext()
+  const asString = () => context.executeTool(tool, JSON.stringify(args), options)
+  if (stringArguments) return asString()
+  try {
+    return await context.executeTool(tool, args, options)
+  } catch (error) {
+    try {
+      const result = await asString()
+      stringArguments = true
+      return result
+    } catch {
+      throw error
+    }
+  }
+}
+
+// WebMCP tool-name grammar: 1-128 chars of ASCII alphanumerics, "_", "-", ".".
+export const TOOL_NAME = /^[A-Za-z0-9_.-]{1,128}$/
+export const validToolName = (name) => TOOL_NAME.test(name)
+
+// Test seam: forget the argument shape the last browser taught us.
+export const _resetArgumentShape = () => {
+  stringArguments = false
+}

data/app/javascript/poetry/agent/agui_client_tool_controller.js

@@ -0,0 +1,53 @@
+import { Controller } from "@hotwired/stimulus"
+import { executeRegisteredTool } from "@poetry/agent/webmcp_controller"
+
+// The AG-UI client-tool bridge: the relay appends one of these (hidden)
+// per tool call the agent made to a FRONTEND tool - a component tool the
+// page declared - and this controller executes it through the registrar
+// (the same dispatch a WebMCP call takes, so it works in every browser,
+// modelContext or not), then POSTs the result to the continue URL. The
+// server folds the tool message into the transcript and answers with the
+// next run's streams, which Turbo renders. One element, one execution:
+// the done flag makes a Turbo re-render inert.
+export default class extends Controller {
+  static values = {
+    call: Object,
+    url: String,
+    done: Boolean
+  }
+
+  static events = ["poetry:agui:client-tool-executed"]
+
+  async connect() {
+    if (this.doneValue) return
+    this.doneValue = true
+
+    const { toolCallId, name, args } = this.callValue
+    let content
+    let error
+    try {
+      content = await executeRegisteredTool(this.application, name, args ?? {})
+    } catch (failure) {
+      error = failure?.message ?? String(failure)
+    }
+    if (typeof content === "string" && content.startsWith("Error:")) error = content
+    const text = typeof content === "string" ? content : JSON.stringify(content ?? null)
+
+    const body = { toolCallId, name, content: text }
+    if (error) body.error = error
+    this.dispatch("client-tool-executed", { prefix: "poetry:agui", detail: { ...body } })
+
+    const response = await fetch(this.urlValue, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "text/vnd.turbo-stream.html, text/html",
+        "X-CSRF-Token": document.querySelector('meta[name="csrf-token"]')?.content ?? ""
+      },
+      body: JSON.stringify(body)
+    })
+    const streams = await response.text()
+    const type = response.headers.get("content-type") || ""
+    if (response.ok && type.includes("text/vnd.turbo-stream.html")) globalThis.Turbo?.renderStreamMessage?.(streams)
+  }
+}

data/app/javascript/poetry/agent/index.js

@@ -0,0 +1,41 @@
+// @poetry/agent - the WebMCP runtime. Register beside poetry's own
+// controllers:
+//
+//   import { Application } from "@hotwired/stimulus"
+//   import { registerPoetryControllers } from "@poetry/controllers"
+//   import { registerPoetryAgent } from "@poetry/agent"
+//   const application = Application.start()
+//   registerPoetryControllers(application)
+//   registerPoetryAgent(application)
+import WebmcpController from "@poetry/agent/webmcp_controller"
+import WebmcpFormController from "@poetry/agent/webmcp_form_controller"
+import AguiClientToolController from "@poetry/agent/agui_client_tool_controller"
+import A2uiSurfaceController from "@poetry/agent/a2ui_surface_controller"
+import { installVersionedReplace, installMorphStateGuard } from "@poetry/agent/stream_actions"
+
+export { default as WebmcpController } from "@poetry/agent/webmcp_controller"
+export { default as WebmcpFormController } from "@poetry/agent/webmcp_form_controller"
+export { default as AguiClientToolController } from "@poetry/agent/agui_client_tool_controller"
+export { default as A2uiSurfaceController } from "@poetry/agent/a2ui_surface_controller"
+export * from "@poetry/agent/adapter"
+export { _registrations, executeRegisteredTool } from "@poetry/agent/webmcp_controller"
+export { installVersionedReplace, installMorphStateGuard, preservesLocalState } from "@poetry/agent/stream_actions"
+
+// identifier -> controller class (the manifest introspects this).
+export const controllers = {
+  "poetry--agent--webmcp": WebmcpController,
+  "poetry--agent--webmcp-form": WebmcpFormController,
+  "poetry--agent--agui-client-tool": AguiClientToolController,
+  "poetry--agent--a2ui-surface": A2uiSurfaceController
+}
+
+// Registers the runtime's controllers, installs the versioned replace
+// stream action the AG-UI relay and the A2UI streams emit (when Turbo is
+// present), and the morph guard that keeps an A2UI surface's local state.
+export const registerPoetryAgent = (application) => {
+  for (const [identifier, controller] of Object.entries(controllers)) {
+    application.register(identifier, controller)
+  }
+  installVersionedReplace()
+  installMorphStateGuard()
+}

data/app/javascript/poetry/agent/stream_actions.js

@@ -0,0 +1,65 @@
+// The versioned replace Turbo Stream action the AG-UI relay and the A2UI
+// surface streams emit: a streamed frame re-renders the SAME element from
+// a server stream, which inherits an out-of-order delivery race, so every
+// payload carries data-version and this action applies only strictly-newer
+// frames - older or duplicate frames are dropped silently. With
+// method="morph" the newer frame morphs the element through Turbo's own
+// replace action (idiomorph), so local state survives an update. Installed
+// on Turbo by registerPoetryAgent when the host has Turbo and no vreplace
+// of its own.
+export const installVersionedReplace = (turbo = globalThis.Turbo) => {
+  if (!turbo?.StreamActions || turbo.StreamActions.vreplace) return false
+
+  turbo.StreamActions.vreplace = function () {
+    const incoming = this.templateContent.firstElementChild
+    const version = Number(incoming?.dataset?.version || 0)
+    const targets = this.targetElements.filter((element) => version > Number(element.dataset.version || -1))
+    if (targets.length === 0) return
+
+    const method = typeof this.getAttribute === "function" ? this.getAttribute("method") : null
+    if (method === "morph" && typeof turbo.StreamActions.replace === "function") {
+      turbo.StreamActions.replace.call({ getAttribute: () => "morph", targetElements: targets, templateContent: this.templateContent })
+    } else {
+      targets.forEach((element) => element.replaceWith(this.templateContent.cloneNode(true)))
+    }
+  }
+  return true
+}
+
+// Local state a morph must not reset inside an A2UI surface: the
+// selection a tab strip holds, a dialog's open state, a popup's expanded
+// state, and a control the user has edited (its value or checked state
+// differs from what the server last rendered). The server does not know
+// this state, so its frame would carry the defaults; canceling Turbo's
+// before-morph-attribute event keeps the page's own.
+const LOCAL_STATE = {
+  "tabs-trigger": ["aria-selected", "tabindex", "data-active"],
+  "tabs-content": ["hidden", "data-hidden"],
+  "dialog-content": ["open", "data-closed"]
+}
+const EXPANDED = ["aria-expanded", "data-open", "data-state"]
+
+export const preservesLocalState = (element, attributeName) => {
+  if (!element?.closest?.("[data-a2ui-surface]")) return false
+  if (attributeName === "value" || attributeName === "checked") return isDirty(element)
+  if (EXPANDED.includes(attributeName)) return true
+  return (LOCAL_STATE[element.dataset?.slot] || []).includes(attributeName)
+}
+
+const isDirty = (element) => {
+  if (element instanceof HTMLInputElement) {
+    if (element.type === "checkbox" || element.type === "radio") return element.checked !== element.defaultChecked
+    return element.value !== element.defaultValue
+  }
+  if (element instanceof HTMLTextAreaElement) return element.value !== element.defaultValue
+  return false
+}
+
+export const installMorphStateGuard = (doc = globalThis.document) => {
+  if (!doc || doc.__poetryA2uiMorphGuard) return false
+  doc.__poetryA2uiMorphGuard = true
+  doc.addEventListener("turbo:before-morph-attribute", (event) => {
+    if (preservesLocalState(event.target, event.detail?.attributeName)) event.preventDefault()
+  })
+  return true
+}