feat(voice): type on_interrupt callback payload as InterruptMessage (AA-1428)

[wenzhu1587]

Summary

Addresses AA-1428 without a breaking change. The ticket asks that the Python on_interrupt callback provide the same detail as TypeScript's onInterrupt (conversationId, utteranceUntilInterrupt, durationUntilInterruptMs, session).

Python already passes all of this. The second callback argument is the parsed ConversationRelay InterruptMessage, and the session carries conversation_id. But the argument was typed Any and undocumented, so callers couldn't discover the fields. This PR:

• Types the callback payload as InterruptMessage in on_interrupt, _interrupt_callback, and trigger_interrupt.
• Exports InterruptMessage from tac.models so callers can annotate their callbacks.
• Rewrites the on_interrupt docstring (published API docs) to describe utterance_until_interrupt / duration_until_interrupt_ms with a working example.

The runtime value is unchanged. Callbacks annotated (session, data: Any) still type-check.

Deferred (per discussion):

• InterruptParams single-object signature: breaking, so it goes with the AA-1427 on_message_ready params-object change. Both callbacks then move together.
• on_interrupt not fired by the OpenAI Realtime provider: barge-in is handled and tracked in analytics, but trigger_interrupt isn't called. The TS SDK has the same gap, so it should be a separate cross-SDK follow-up.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Refactoring
• Release / version bump

Checklist

• Tests added/updated
• Documentation updated
• Tested E2E

New and updated tests:

• InterruptMessage is importable from tac.models.
• The ConversationRelay provider test now asserts that the callback receives the session and the parsed utterance_until_interrupt / duration_until_interrupt_ms. Previously it only checked that no exception was raised.

make check passes.

SDK Parity

This is the Python SDK. If this change affects shared functionality, ensure the TypeScript SDK is updated as well.

Tip: Use the /sync-to-ts-sdk skill in Claude Code to automatically generate and create a TypeScript SDK PR from your changes.

• Change is Python-specific (no TypeScript update needed). TS InterruptCallback already exposes these fields.
• TypeScript SDK PR created:

🤖 Generated with Claude Code

[Copilot]

🟢 Approval recommended

The focused changes preserve runtime behavior, match the existing payload contract, and have no identified blocking issues.

0 open findings

What changed in this PR

Makes voice interruption callback fields discoverable through explicit typing and published documentation, without changing runtime behavior.

Changes:

• Types interrupt callback payloads as InterruptMessage and exports the model.
• Documents payload fields with a usage example.
• Adds export coverage and strengthens callback payload assertions.

File	Description
tests/​test_voice_channel.py	Verifies callback session and interrupt details.
tests/​test_interrupt.py	Tests the public model export.
src/​tac/​models/​__init__.py	Exports InterruptMessage.
src/​tac/​core/​tac.py	Updates callback types and documentation.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.