feat(stt): add stt context options

[rosetta-livekit-bot]

Summary

Ports livekit/agents#6475 to agents-js:

• Adds sttContextOptions with keyterms, keytermDetection, and forwardChatContext.
• Keeps deprecated keytermsOptions mapped to the new STT context shape.
• Gates STT chat-context forwarding through sttContextOptions.forwardChatContext.
• Enables AssemblyAI U3 Pro chat-context carryover by default, with deprecated agentContextCarryover retained as an opt-out/compat flag.
• Updates inference STT chat-context capability detection for AssemblyAI U3 Pro models.

Source diff coverage

Coverage table

Source file	Classification
examples/voice_agents/basic_agent.py	Ported to examples/src/basic_agent.ts: renamed keytermsOptions to sttContextOptions in the matching example.
livekit-agents/livekit/agents/__init__.py	Adapted via agents/src/voice/index.ts and root agents/src/index.ts: root already re-exports voice; added STTContextOptions to voice public exports.
livekit-agents/livekit/agents/inference/stt.py	Adapted to agents/src/inference/stt.ts: JS inference STT does not expose agentContextCarryover; chat-context capability now follows AssemblyAI U3 Pro model support and is refreshed on model changes.
livekit-agents/livekit/agents/voice/__init__.py	Ported to agents/src/voice/index.ts: exported STTContextOptions.
livekit-agents/livekit/agents/voice/agent_activity.py	Ported to agents/src/voice/agent_activity.ts: STT conversation-item forwarding is gated on sttContextOptions.forwardChatContext.
livekit-agents/livekit/agents/voice/agent_session.py	Adapted to agents/src/voice/agent_session.ts and agents/src/voice/turn_config/utils.ts: added sttContextOptions, preserved deprecated keytermsOptions, mapped old option to the new shape, and made the new option take precedence.
livekit-agents/livekit/agents/voice/keyterm_detection.py	Ported to agents/src/voice/keyterm_detection.ts: added STTContextOptions, resolver defaults, and deprecated keyterms-to-STT-context mapping.
livekit-plugins/livekit-plugins-assemblyai/livekit/plugins/assemblyai/stt.py	Adapted to plugins/assemblyai/src/stt.ts: carryover is default-on for U3 Pro models, and deprecated agentContextCarryover remains as an opt-out/compat flag with warnings.
tests/test_agent_session.py	Ported to agents/src/voice/agent_session.test.ts: added defaults, passthrough, deprecated mapping, and precedence tests.
tests/test_inference_stt_context.py	Ported to agents/src/inference/stt.test.ts: added chat-context capability tests to the existing inference STT test file.
tests/test_plugin_assemblyai_stt.py	Ported to plugins/assemblyai/src/stt.test.ts: added AssemblyAI carryover default/deprecation behavior tests.
tests/test_stt_context.py	Ported to agents/src/voice/keyterm_detection.test.ts: added resolver and deprecated mapping tests.

No source diff files were marked not applicable.

Validation

Passed:

• pnpm test agents/src/voice/keyterm_detection.test.ts agents/src/voice/agent_session.test.ts agents/src/inference/stt.test.ts
• pnpm test plugins/assemblyai/src
• pnpm --filter @livekit/agents build
• pnpm --filter @livekit/agents-plugin-silero build
• pnpm --filter @livekit/agents-plugins-test build
• pnpm --filter @livekit/agents-plugin-assemblyai build
• pnpm --filter @livekit/agents lint
• pnpm --filter @livekit/agents-plugin-assemblyai lint
• pnpm --filter livekit-agents-examples lint
• pnpm build
• pnpm lint
• pnpm format:check
• cue-cli text-mode runtime validation against a temporary JS agent, asserting the expected assistant conversation_item_added framework event.

Known validation gaps:

• pnpm test agents/src fails on existing agents/src/voice/amd.test.ts expectations; agents/src/voice/amd.test.ts also fails when run alone with 11 AMD classification/timeout failures. The focused STT/session tests added by this PR pass.
• The full pnpm test agents/src run also observed one agents/src/inference/eot/transports.test.ts timeout; that file passed in a focused rerun alongside amd.test.ts.
• pnpm --filter @livekit/agents api:check fails before API diffing on existing API Extractor unsupported syntax: export * as ___ in agents/dist/index.d.ts.
• pnpm --filter @livekit/agents-plugin-assemblyai api:check exits non-zero on existing API Extractor warnings/missing report (etc/agents-plugin-assemblyai.api.md).

---

Ported from livekit/agents#6475

Original PR description

Adds stt_context_options on AgentSession — a single conversation-aware STT option grouping static keyterms, LLM keyterm_detection, and a forward_chat_context toggle that forwards agent replies to STTs that consume context natively (e.g. AssemblyAI Universal-3 Pro).

forward_chat_context is on by default and is the only control for carryover, applied consistently across the inference STT and the AssemblyAI plugin. Agent replies are now sent to AssemblyAI u3-pro by default when used via AgentSession; opt out with stt_context_options={"forward_chat_context": False}.

Deprecated (still work, warn):

• AgentSession(keyterms_options=...) → use stt_context_options
• AssemblyAI plugin agent_context_carryover → use stt_context_options.forward_chat_context (pass False to opt out)

Removes the unpublished agent_context_carryover param from the inference STT.

[changeset-bot]

🦋 Changeset detected

Latest commit: 7a0c614

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 37 packages

Name	Type
@livekit/agents	Major
@livekit/agents-plugin-assemblyai	Major
@livekit/agents-plugin-anam	Major
@livekit/agents-plugin-anthropic	Major
@livekit/agents-plugin-azure	Major
@livekit/agents-plugin-baseten	Major
@livekit/agents-plugin-bey	Major
@livekit/agents-plugin-cartesia	Major
@livekit/agents-plugin-cerebras	Major
@livekit/agents-plugin-deepgram	Major
@livekit/agents-plugin-did	Major
@livekit/agents-plugin-elevenlabs	Major
@livekit/agents-plugin-fishaudio	Major
@livekit/agents-plugin-google	Major
@livekit/agents-plugin-hedra	Major
@livekit/agents-plugin-hume	Major
@livekit/agents-plugin-inworld	Major
@livekit/agents-plugin-lemonslice	Major
@livekit/agents-plugin-liveavatar	Major
@livekit/agents-plugin-livekit	Major
@livekit/agents-plugin-minimax	Major
@livekit/agents-plugin-mistral	Major
@livekit/agents-plugin-mistralai	Major
@livekit/agents-plugin-neuphonic	Major
@livekit/agents-plugin-openai	Major
@livekit/agents-plugin-perplexity	Major
@livekit/agents-plugin-phonic	Major
@livekit/agents-plugin-resemble	Major
@livekit/agents-plugin-rime	Major
@livekit/agents-plugin-runway	Major
@livekit/agents-plugin-sarvam	Major
@livekit/agents-plugin-silero	Major
@livekit/agents-plugin-soniox	Major
@livekit/agents-plugin-tavus	Major
@livekit/agents-plugins-test	Major
@livekit/agents-plugin-trugen	Major
@livekit/agents-plugin-xai	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 2 additional findings.