poetry-agent API

.config

.configure

Poetry::Agent.configure do |config|
  config.origin_trial_tokens = [ENV["WEBMCP_ORIGIN_TRIAL_TOKEN"]].compact
end

.root

.from_registry(root, helpers: nil, icon_names: nil, skills: {}, app_root: nil, recipes: [])

#handle(request)

• request (Hash) — one parsed JSON-RPC 2.0 request

Returns (Hash, nil) — the response hash, or nil for a notification

#initialize(entries:, catalog:, blocks: {}, root: nil, skills: {}, app_root: nil, recipes: [])

Returns (Server) — a new instance of Server

#serve(input: $stdin, output: $stdout)

#call(env)

• env (Hash) — the Rack environment

Returns (Array(Integer, Hash, Array<String>)) — status, headers, body

#initialize(server = nil)

• server (Server, Proc, nil) — the server, a lambda building it on first request, or nil for the bundled assembly

Returns (HTTP) — a new instance of HTTP

.icon_names

.server(root: nil, app_root: Dir.pwd)

• root (String, nil) — a registry root; defaults to poetry-ui
• app_root (String) — the host app (build_page's probe/direct steps read its config/theme)

.manifest_path

#call(env)

• env (Hash) — the Rack environment

Returns (Array(Integer, Hash, Object)) — the downstream response

#initialize(app, tokens: nil)

Returns (OriginTrial) — a new instance of OriginTrial

.current

#initialize

Returns (Config) — a new instance of Config

#origin_trial_tokens

#origin_trial_tokens=(value)

#registration_budget

#registration_budget=(count)

• count (Integer) —

.catalogs

.component_name(path)

• path (String) —

.from_registry(root = nil, **)

• root (String, Pathname, nil) —

.load_entries(root = nil)

• root (String, Pathname, nil) —

Returns (Hash{String => Hash}) — entries by registry path

.skipped_option?(name)

• name (String) — an option name

Returns (Boolean) — whether an agent never sets it

#catalog_id

#component_name(path)

• path (String) —

#components

#functions

#initialize(entries:, catalog_id: DEFAULT_ID, title: "Poetry UI Catalog", description: "Poetry's component library as an A2UI catalog, projected from its registry.", instructions: DEFAULT_INSTRUCTIONS, exclude: [])

• entries (Hash{String => Hash}) — registry entries by path
• catalog_id (String) —
• title (String) —
• description (String) —
• instructions (String) — catalog-level guidance for the model
• exclude (Array<String>) — registry paths to leave out

Returns (Catalog) — a new instance of Catalog

#inline

Returns (Hash) — { "catalogId", "components" }

#to_h

#to_json(*)

Returns (String) — the document as JSON

#functions

Returns (Functions) — the basic catalog's function set

#id

#inputs(component, scope)

• component (Hash) —
• scope (String, nil) —

Returns (Array<Hash>) — { path:, kind: }

#references(component)

• component (Hash) —

#render(component, scope, renderer)

• component (Hash) —
• scope (String, nil) —
• renderer (Renderer) —

Returns (String) — HTML

#label

Returns (Object) — the current value of label

#label=(value)

• value (Object) — the value to set the attribute label to.

Returns (Object) — the newly set value

#options

Returns (Object) — the current value of options

#options=(value)

• value (Object) — the value to set the attribute options to.

Returns (Object) — the newly set value

#path

Returns (Object) — the current value of path

#path=(value)

• value (Object) — the value to set the attribute path to.

Returns (Object) — the newly set value

#selected

Returns (Object) — the current value of selected

#selected=(value)

• value (Object) — the value to set the attribute selected to.

Returns (Object) — the newly set value

#by_name

Returns (Hash{String => Array(String, Hash)}) — [path, entry] by component name

#entries

Returns (Hash{String => Hash}) — registry entries by path

#functions

Returns (Functions) — the function set Poetry's catalog declares (the basic one)

#id

#initialize(entries: nil, id: Catalog::DEFAULT_ID)

• entries (Hash{String => Hash}, nil) — registry entries by path (the poetry-ui registry when nil)
• id (String) — the catalog id this binding answers to

Returns (Native) — a new instance of Native

#inputs(component, scope)

• component (Hash) —
• scope (String, nil) —

Returns (Array<Hash>) — { path:, kind: } for each bound option

#references(component)

• component (Hash) —

#render(component, scope, renderer)

• component (Hash) —
• scope (String, nil) —
• renderer (Renderer) —

Returns (String) — HTML

.failures(component, evaluator)

• component (Hash) —
• evaluator (Evaluator) —

Returns (Array<Hash>) — failures as { code:, message:, severity: }

#argument(value)

• value (Object) —

#call(name, args, resolved: false)

• name (String) —
• args (Hash, nil) — raw arguments (resolved here unless resolved:)
• resolved (Boolean) — whether the arguments are already resolved

#evaluate(node)

• node (Array) —

#index

Returns (Integer, nil) — the collection index the scope carries

#initialize(surface, scope = nil, on_error: nil)

• surface (Surface) —
• scope (String, nil) —
• on_error (#call, nil) — receives each problem's message

Returns (Evaluator) — a new instance of Evaluator

#interpolate(text)

• text (String) —

#resolve(value)

• value (Object) —

#scope

Returns (String, nil) — the collection-item pointer in effect

#stringify(value)

• value (Object) —

#surface

.dynamic?(text)

• text (String) —

Returns (Boolean) — whether the text carries an interpolation block

.parse(text)

• text (String) —

Returns (Array) — the [:template, nodes] tree

#initialize(source)

• source (String) —

Returns (Parser) — a new instance of Parser

#template

Returns (Array) — the [:template, nodes] tree

.basic

.number(value)

• value (Object) —

Returns (Numeric, nil) — the value as a number, when it is one

.truthy?(value)

• value (Object) —

#agent_callable?(name)

• name (String) —

Returns (Boolean) — whether an agent may invoke the function through callRendererFunction

#any_function

#call(name, args, evaluator)

• name (String) —
• args (Hash{String => Object}) —
• evaluator (Evaluator) —

#declared?(name)

• name (String) —

#define(name, description:, returns:, params: {}, required: [], activation: false, # rubocop:disable Metrics/ParameterLists callers: "rendererOnly", &impl)

• name (String) —
• description (String) —
• returns (String) — the spec's returnType
• params (Hash{String => Hash}) — argument schemas by name
• required (Array<String>) — required argument names
• activation (Boolean) — whether the call needs a user activation
• callers (String) — the execution boundary (rendererOnly - the default - keeps the function out of an agent's callRendererFunction; agentOnly / rendererOrAgent admit it)

Returns (Functions) — self

#initialize

Returns (Functions) — a new instance of Functions

#names

Returns (Array<String>) — the declared names

#schema

.install(registry)

• registry (Functions) —

.list

#activation

Returns (Object) — the current value of activation

#activation=(value)

• value (Object) — the value to set the attribute activation to.

Returns (Object) — the newly set value

#callers

Returns (Object) — the current value of callers

#callers=(value)

• value (Object) — the value to set the attribute callers to.

Returns (Object) — the newly set value

#description

Returns (Object) — the current value of description

#description=(value)

• value (Object) — the value to set the attribute description to.

Returns (Object) — the newly set value

#impl

Returns (Object) — the current value of impl

#impl=(value)

• value (Object) — the value to set the attribute impl to.

Returns (Object) — the newly set value

#name

Returns (Object) — the current value of name

#name=(value)

• value (Object) — the value to set the attribute name to.

Returns (Object) — the newly set value

#params

Returns (Object) — the current value of params

#params=(value)

• value (Object) — the value to set the attribute params to.

Returns (Object) — the newly set value

#required

Returns (Object) — the current value of required

#required=(value)

• value (Object) — the value to set the attribute required to.

Returns (Object) — the newly set value

#returns

Returns (Object) — the current value of returns

#returns=(value)

• value (Object) — the value to set the attribute returns to.

Returns (Object) — the newly set value

.render(text)

• text (String) —

Returns (String) — HTML (unmarked; wrap in html_safe at the render site)

.strip(text)

• text (String) —

Returns (String) — plain text

.absolute(path, scope = nil)

• path (String) —
• scope (String, nil) — the collection-item pointer in effect

Returns (String) — an absolute pointer

.build(parts)

• parts (Array<String>) —

.get(document, path)

• document (Object) —
• path (String) —

.tokens(path)

• path (String) —

.upsert(document, path, value)

• document (Hash, Array, nil) —
• path (String) —
• value (Object, nil) —

Returns (Object) — the updated document

.element_id(surface_or_id)

• surface_or_id (Surface, String) —

Returns (String) — the DOM id of the surface's wrapper

#action_url

#aria_label(component, scope = nil)

• component (Hash) —
• scope (String, nil) —

Returns (String, nil) — the component's accessibility label

#blank

Returns (String) — an empty html_safe string

#call

Returns (String) — the surface's HTML (html_safe)

#call_function(name, args, scope = nil)

• name (String) —
• args (Hash, nil) —
• scope (String, nil) —

#component(klass, attributes = {}, suffix: nil, **keywords, &)

• klass (Class) — the component class
• attributes (Hash) — constructor keywords
• suffix (String, nil) — distinguishes several instances of one class for one component
• keywords (Hash) — constructor keywords given keyword-style (merged into attributes)

#control_id(component, scope = nil)

• component (Hash) —
• scope (String, nil) —

Returns (String) — a DOM id for the component's control

#current_key

Returns (String, nil) — the key of the component being rendered (id, or id@scope)

#error_for(component, scope = nil)

• component (Hash) —
• scope (String, nil) —

Returns (String, nil) — the first check failure message for the component

#errors

Returns (Hash{String => Array<Hash>}) — check failures by component key (see {Surface#failures})

#initialize(surface, view:, action_url: nil, html: {}, errors: {})

• surface (Surface) —
• view (Object) — an ActionView context (view_context)
• action_url (String, nil) — where actions post; nil renders a plain container
• html (Hash) — extra attributes for the wrapper (class: etc.)
• errors (Hash{String => Array<Hash>}) — check failures to show, by component key (a rejected action's errors)

Returns (Renderer) — a new instance of Renderer

#input_name(path, scope = nil)

• path (String) — a bound pointer
• scope (String, nil) —

Returns (String) — the input's form name

#markdown(text)

• text (String) —

Returns (String) — the Markdown subset rendered (html_safe)

#render_children(reference, scope = nil)

• reference (String, Array<String>, Hash, nil) —
• scope (String, nil) —

#render_component(component_id, scope = nil)

• component_id (String) —
• scope (String, nil) —

Returns (String) — the component's HTML (empty when it cannot render)

#resolve(value, scope = nil)

• value (Object) —
• scope (String, nil) —

Returns (Object, nil) — the resolved dynamic value

#stable_key(suffix = nil)

• suffix (String, nil) —

Returns (String) — the render-stable key of the component being rendered

#submit_attributes(component, scope = nil)

• component (Hash) —
• scope (String, nil) —

#surface

#text(value, scope = nil)

• value (Object) —
• scope (String, nil) —

#view

Returns (Object) — the view context

#warn(message)

• message (String) —

Returns (String) — an empty html_safe string

#warnings

Returns (Array<String>) — what could not be rendered, in render order

#action(surface_id:, source:, values: {}, timestamp: Time.now.utc)

• surface_id (String) —
• source (String) — the submit button's value (id or id@scope)
• values (Hash{String => Object}) — submitted values by absolute pointer
• timestamp (Time) —

#apply(message)

• message (Hash) —

#apply_activity(content)

• content (Hash, Array) —

Returns (Array<String>) — the changed surface ids

#apply_all(messages)

• messages (Array<Hash>) —

Returns (Array<String>) — the changed surface ids, deduplicated

#catalog_for(catalog_id)

• catalog_id (String, nil) —

Returns (Object) — the catalog binding for an id (the default when unknown)

#catalogs

Returns (Hash{String => Object}) — catalog bindings by catalog id

#deleted

Returns (Array<String>) — ids of deleted surfaces, in order

#errors

Returns (Array<Hash>) — renderer-to-agent error messages, in order

#initialize(catalogs: A2UI.catalogs, default_catalog: nil)

• catalogs (Hash{String => Object}) — catalog bindings by id
• default_catalog (Object, nil) — the binding for unknown catalog ids (Poetry's own when nil)

Returns (Session) — a new instance of Session

#responses

Returns (Array<Hash>) — renderer-to-agent rendererFunctionResponse messages, in order

#surface(surface_id)

• surface_id (String) —

#surfaces

Returns (Hash{String => Surface}) — live surfaces by id

#errors

Returns (Object) — the current value of errors

#errors=(value)

• value (Object) — the value to set the attribute errors to.

Returns (Object) — the newly set value

#forwarded_props

Returns (Hash) — the AG-UI forwardedProps carrying the action (and the data model when the surface asked for it); empty when invalid

#message

Returns (Object) — the current value of message

#message=(value)

• value (Object) — the value to set the attribute message to.

Returns (Object) — the newly set value

#surface

Returns (Object) — the current value of surface

#surface=(value)

• value (Object) — the value to set the attribute surface to.

Returns (Object) — the newly set value

#to_h

Returns (Hash, nil) — the { "version", "action" } renderer-to-agent message; nil when a check failed

#valid?

Returns (Boolean) — whether every check passed and the message exists

#apply(message)

• message (Hash) —

Returns (String) — Turbo Stream HTML (empty when nothing changed)

#apply_all(messages)

• messages (Array<Hash>) —

Returns (String) — Turbo Stream HTML

#initialize(session:, render:, container: nil, morph: true)

• session (Session) —
• render (#call) — (surface) -> html
• container (String, nil) — the DOM id new surfaces append into
• morph (Boolean) — morph replaced surfaces (the default) so local state - typed text, a selected tab, an open dialog - survives an update; false swaps

Returns (Streams) — a new instance of Streams

#mark_seen(*ids)

• ids (Array<String>) —

#session

#stream_for(id)

• id (String) —

Returns (String) — the stream for one surface (remove, append, or vreplace)

#streams(ids)

• ids (Array<String>) —

#binding?(value)

• value (Object) —

Returns (Boolean) — whether the value is a { "path" => ... } data binding

#catalog

Returns (Object) — the catalog binding (see {Catalogs::Basic})

#catalog_id

Returns (String, nil) — the catalog id the agent named

#component(component_id)

• component_id (String) —

#components

Returns (Hash{String => Hash}) — components by id

#data

Returns (Hash) — the data model

#expand(reference, scope = nil)

• reference (Array<String>, Hash, String, nil) —
• scope (String, nil) —

#failures(on_error: nil)

• on_error (#call, nil) — receives each function problem's message

Returns (Hash{String => Array<Hash>}) — failures by component key

#function_call?(value)

• value (Object) —

Returns (Boolean) — whether the value is a { "call" => ... } function call

#id

#initialize(id:, catalog:, catalog_id: nil, send_data_model: false, data: nil, components: [])

• id (String) —
• catalog (Object) — the catalog binding
• catalog_id (String, nil) —
• send_data_model (Boolean) —
• data (Hash, nil) — the initial data model
• components (Array<Hash>) — the initial component list

Returns (Surface) — a new instance of Surface

#inputs

Returns (Array<Hash>) — { path:, kind: } (kind: :string, :boolean, :number, :string_list)

#program

Returns (Hash) — { "checks" => { key => { "kind", "rules" } }, "inputs" => { path => kind }, "model" => data }

#read(path, scope = nil)

• path (String) —
• scope (String, nil) —

#resolve(value, scope = nil, on_error: nil)

• value (Object) —
• scope (String, nil) — the collection-item pointer in effect
• on_error (#call, nil) — receives each function problem's message

#root

Returns (Hash, nil) — the top-level component

#send_data_model

Returns (Boolean) — whether actions carry the whole data model

#source_key(component, scope = nil)

• component (Hash) —
• scope (String, nil) —

Returns (String) — id, or id@scope inside a template

#template?(value)

• value (Object) —

Returns (Boolean) — whether the value is a { "componentId", "path" } template

#text(value, scope = nil, on_error: nil)

• value (Object) —
• scope (String, nil) —
• on_error (#call, nil) — receives each function problem's message

#to_h

Returns (Hash) — a JSON-ready snapshot

#update_components(list)

• list (Array<Hash>) —

#update_data(path, value)

• path (String, nil) —
• value (Object, nil) —

#version

Returns (Integer) — bumps on every applied change

#walk(&)

.field(hash, name)

• hash (Hash) —
• name (String) — the camelCase name

.tool_descriptor(instance, definition)

• instance (String) — the webmcp: instance name
• definition (Hash) — one entry of Component#webmcp_tools

Returns (Hash) — { "name", "description", "parameters" }

Poetry::Agent::AGUI.tool_descriptor("sections", tabs.webmcp_tools.first)
# => { "name" => "poetry.sections.set_value", "description" => "...", "parameters" => {...} }

#initialize(url:, headers: {}, open_timeout: 10, read_timeout: 120)

• url (String) — the agent's run endpoint
• headers (Hash{String => String}) — extra request headers (auth)
• open_timeout (Numeric) — seconds
• read_timeout (Numeric) — seconds between chunks

Returns (Client) — a new instance of Client

#run(input, &)

• input (Hash) — the wire hash ({RunInput.build})

Returns (SSE::Parser) — the parser (its errors list any unreadable lines)

client.run(input) { |event| transcript.apply(event) }

#initialize(message, status:)

Returns (Error) — a new instance of Error

#status

.apply(document, operations)

• document (Hash, Array) —
• operations (Array<Hash>) — RFC 6902 operations (string or symbol keys)

Returns (Hash, Array) — the new document

JsonPatch.apply({ "a" => 1 }, [{ "op" => "replace", "path" => "/a", "value" => 2 }])
# => { "a" => 2 }

.get(document, path)

• document (Hash, Array) —
• path (String) — RFC 6901 pointer ("" is the whole document)

#apply(event)

• event (Hash) —

#client_tool_streams(continue_url:, container: @container)

• continue_url (String) — where the browser POSTs { toolCallId, name, content, error }
• container (String) — the element the bridge elements append to

#initialize(transcript:, render:, container: nil, target: ->(message) { "row-#{message.id}" }, # rubocop:disable Metrics/ParameterLists action: "vreplace", append_render: nil, morph: false)

• transcript (Transcript) —
• render (#call) — (message, version) -> String the row HTML
• container (String, nil) — the id new rows append to (nil: replace only)
• target (#call) — (message) -> String the row's element id
• action (String) — the stream action for updates (vreplace by default)
• append_render (#call, nil) — (message, version) -> String the HTML a first appearance appends - the row inside its list wrapper (a scroller item); defaults to render

Returns (Relay) — a new instance of Relay

#mark_seen(*ids)

• ids (Array<String>) —

#stream_for(id)

• id (String) —

#transcript

.build( # rubocop:disable Metrics/ParameterLists -- one keyword per RunAgentInput field thread_id:, messages:, run_id: SecureRandom.uuid, tools: [], context: [], state: {}, forwarded_props: {}, parent_run_id: nil, resume: nil)

• thread_id (String) — the conversation thread
• messages (Array<Hash>) — protocol messages (id, role, content, ...)
• run_id (String) — defaults to a fresh UUID
• tools (Array<Hash>) — frontend-defined tools ({AGUI.tool_descriptor})
• context (Array<Hash>) — { "description", "value" } entries
• state (Hash) — the shared state to send
• forwarded_props (Hash) — integration-specific props
• parent_run_id (String, nil) — the run this one branches from
• resume (Array<Hash>, nil) — { "interruptId", "status", "payload" } answers

Returns (Hash) — the wire hash (string keys)

RunInput.build(thread_id: "t1", messages: [RunInput.user_message("hi")],
               tools: [Poetry::Agent::AGUI.tool_descriptor("sections", definition)])

.resume_entry(interrupt_id, status: nil, payload: nil)

• interrupt_id (String) —
• status (String, nil) — e.g. "approved", "rejected"
• payload (Object, nil) —

.tool_message(tool_call_id, content, error: nil, id: SecureRandom.uuid)

• tool_call_id (String) —
• content (String) — the result as text (JSON for structured results)
• error (String, nil) — set when the tool failed
• id (String) —

.user_message(content, id: SecureRandom.uuid)

• content (String) —
• id (String) —

.parse(source, &block)

• source (String, #each) —

Returns (Array<Hash>) — every event, when no block is given

Poetry::Agent::AGUI::SSE.parse("data: {\"type\":\"RUN_STARTED\"}\n\n") # => [{ "type" => "RUN_STARTED" }]

#errors

#feed(chunk, &)

• chunk (String) —

#finish(&)

#initialize

Returns (Parser) — a new instance of Parser

#activities

#apply(event)

• event (Hash) — an AG-UI event (camelCase or snake_case keys)

Returns (Array<String>) — the ids of the messages this event changed

#apply_all(events)

• events (#each) — event hashes

#client_tools

#custom_events

#ended?

Returns (Boolean) — the run ended (finished, interrupted, or errored)

#error

#frame(id)

• id (String) —

Returns (Hash) — { parts:, version: }

#initialize(client_tools: [])

• client_tools (Array<String>) — names of tools the browser executes

Returns (Transcript) — a new instance of Transcript

#interrupted?

#interrupts

#message(id)

• id (String) —

#messages

#messages_for_input

#pending_client_tools

#resolve_client_tool(tool_call_id, content, error: nil)

• tool_call_id (String) —
• content (Object) — the result (a string, or data serialized as JSON)
• error (String, nil) —

Returns (String, nil) — the id of the message that changed

#run

#state

#unknown_events

#version

#id

Returns (Object) — the current value of id

#id=(value)

• value (Object) — the value to set the attribute id to.

Returns (Object) — the newly set value

#parts

Returns (Object) — the current value of parts

#parts=(value)

• value (Object) — the value to set the attribute parts to.

Returns (Object) — the newly set value

#role

Returns (Object) — the current value of role

#role=(value)

• value (Object) — the value to set the attribute role to.

Returns (Object) — the newly set value

#version

Returns (Object) — the current value of version

#version=(value)

• value (Object) — the value to set the attribute version to.

Returns (Object) — the newly set value

.append(target, html)

• target (String) —
• html (String) —

.build(action, target, html = nil, method: nil)

• action (String) — a Turbo Stream action (append, replace, vreplace, remove, ...)
• target (String) — the target element id
• html (String, nil) — the template content (already rendered, trusted)
• method (String, nil) — Turbo's method attribute ("morph" morphs instead of swapping)

.remove(target)

• target (String) —

.replace(target, html)

• target (String) —
• html (String) —

.sse(html)

• html (String) —

.vreplace(target, html, morph: false)

• target (String) —
• html (String) —
• morph (Boolean) — morph the target (Turbo's idiomorph) instead of swapping it, so local state - typed text, a selected tab, an open dialog - survives the update