fix: rename runtime_context to request_context to match Mastra body schema

[rogercampos]

Summary

Mastra's POST /agents/:agentId/generate handler reads requestContext from the request body. The gem was emitting runtime_context: on the options hash; deep_camelize_keys rewrote that to runtimeContext on the wire, which Mastra's schema does not recognize — the value was silently dropped. Every caller using dynamic instructions was therefore seeing requestContext.get(key) return undefined and falling back to defaults.

Concrete symptoms we hit in factorialco/factorial before tracking this down:

• OCR financial-document agent: categoryHierarchy and currentDate never arrived, so the model saw an empty {} hierarchy and never picked a category.
• FinanceExpensesPolicyCompliance + FinanceExpensesExpenseApprovalRecommendation: language never arrived, output always in English regardless of company locale.
• TalentEngagementMeetingsAiSummary + TalentEngagementMeetingsContextGenerator: language never arrived; template_type also never arrived (separate TS-side fix because of nested camelization — out of scope here).

Origin of the bug

This gem's first commit landed on 2025-06-10 using runtime_context:, which matched the then-current Mastra API (RuntimeContext).

Upstream Mastra renamed the type in mastra-ai/mastra#9511 "Rename RuntimeContext to RequestContext", merged 2025-10-30, and shipped it as a breaking change in @mastra/core@1.0.0 (see the 1.0.0 "Major Changes" section of packages/core/CHANGELOG.md). On the server side the /agents/:agentId/generate handler was changed to read requestContext from the body (agentExecutionBodySchema only declares requestContext; runtimeContext is unknown and falls into ...rest, which agent.generate does not consume).

The gem hadn't been updated in the meantime — we were on 0.5.3 still emitting runtimeContext. Since Mastra's Zod schema uses .passthrough(), the unknown key survived validation and was silently dropped by the handler, so no error surfaced and no logs flagged it. The failure mode was "dynamic instructions fall back to defaults on every request", which is very easy to miss when those defaults produce plausible output (English summaries, empty category hierarchy → "other", etc.).

factorialco/factorial-agent is already running @mastra/core@1.4.0, so the mismatch has been live for the full life of every runtime_context: caller in production.

Change

Rename the public kwarg on Ai::Agent#generate_text and Ai::Agent#generate_object from runtime_context: to request_context:, and rename the options-hash key so deep_camelize_keys emits requestContext — the key Mastra actually reads.

Files touched:

• lib/ai/agent.rb — the rename itself.
• spec/lib/ai/agent_spec.rb — matching spec updates.
• bin/console + README.md — example code.
• lib/ai/version.rb — bumped to 0.6.0 (API rename is a breaking change for callers of this gem).

Caller migration

Anywhere that passes runtime_context: must now pass request_context:. In factorialco/factorial this was five call sites:

• ocr/.../factorial_agent/ocr_client.rb
• expenses/.../generate_policy_flags.rb
• expenses/.../generate_approval_recommendation.rb
• meetings/.../ai_summary/generator.rb
• meetings/.../context/generator.rb

Those will be updated in a matching PR against that repo.

Test plan

• bundle exec rspec — 83 examples, 0 failures.
• Manually verified against the backend: after bundle update ai and restarting Mastra, dynamic instructions are now receiving their context (hierarchy / language / template type / etc.).

🤖 Generated with Claude Code

[notion-workspace]

Expenses submission not working