fix: record the user turn an agent renders from its template

[TonsOfFun]

The gap

A trace from a template-rendering agent carries prompt.input.instructions and llm.output.message but not prompt.input.messages. The user turn — what the model was actually asked — is missing.

Easy to miss, because the other two attributes are there: the trace looks populated, the Conversation tab renders System and Assistant, and only the User row is absent. It is also the half an evaluation scores.

Why

The instrumentation serializes prompt_options[:messages], which holds turns a caller passed explicitly. An agent written the idiomatic way —

prompt(
  instructions: { template: "instructions_summaries_batch", locals: shared_locals },
  locals: shared_locals
)

— has none at that point. Its user turn is rendered later, in prepare_prompt_parameters. So the message reaches the model and never reaches the trace.

The fix

Fall back to the rendered parameters when there are no explicit messages.

prepare_prompt_parameters is a pure function of prompt_options — it deep_dups its input and mutates no instance state — so reading it is safe. It does re-render the templates, which is why the fallback is only reached when there is nothing else to record. It never raises: an agent whose templates need context this call cannot supply loses the attribute, not the generation.

Also handles message objects responding to #content, not just hashes and strings, since that is what the rendered parameters contain.

Verification

Against a self-hosted dashboard, same agent, stock gems before and after:

attribute	before	after
prompt.input.instructions	✅	✅
prompt.input.messages	❌	✅
llm.output.message	✅	✅

The captured turn is the real rendered content ("Title: Emergency shutdown procedure\nDocument id: …"), and the trace's Conversation tab now shows System / User / Assistant.

An app-side workaround for exactly this had accumulated in a host app's ApplicationAgent — hooking prepare_prompt_parameters and writing the gem's own attribute name. Removing it and relying on this change reproduces the same result, which is the outcome that matters: apps should not each have to discover and patch this.

Tests

test/telemetry/rendered_messages_test.rb covers reading the rendered messages, failing safe when rendering raises, and skipping agents that do not implement prepare_prompt_parameters.

⚠️ Not run in the repo's harness — the dummy app's encrypted credentials fail to decrypt in my checkout (ActiveSupport::MessageEncryptor::InvalidMessage, no master key), which breaks existing tests on a clean tree too. The three behaviours were verified directly against the module in a host app's console instead; CI should be the judge of the file itself.

Risk

Confined to the telemetry path and only reached when prompt_options[:messages] is blank — an agent that passes messages explicitly takes the existing branch unchanged. The extra template render costs one pass, and only for agents that were previously recording nothing.

🤖 Generated with Claude Code