Handler-surface parity with the TypeScript SDK: four handlers, four shapes — and the error hook is the one real divergence
Maintainers usually reply within 5 days
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 25/100
- Issue type
- Feature
- Clarity
- Mostly clear
- Activity status
- Active
- Tech stack
- python, typescript
- Domain
- api
Research direction
Start with the cited handler definitions in src/tac/core/tac.py and compare them with the TypeScript references in the issue; the companion issue is twilio-agent-connect-typescript#106. The request is to decide and publish a canonical handler surface and document the cross-SDK mapping, not to make a specified code change. Done means the intended convention and any deliberate language-specific differences are clearly stated for both SDKs.
Written by the indexing model from the issue text.
Description
This SDK and twilio-agent-connect-typescript expose the same four conceptual event handlers with four different registration shapes. Most of the difference is idiomatic and we are not asking for it to be removed. One of the four is not idiomatic, and that is the part worth a decision.
Filing in both repositories because neither alone can settle it. Companion: twilio/twilio-agent-connect-typescript#106.
Citations are file:line at 2c24bd988c29cdefbb69875ac38ed739b9215a7b (main HEAD, transcribed 2026-10-08) and, for TypeScript, at 022449cf3a730d7877c23c5f5e2d3655e2e40897. Navigation only.
The measured divergence
| handler | this SDK | twilio-agent-connect-typescript |
|---|---|---|
| message ready | three positionals — (message: str, context: ConversationSession, memory: TACMemoryResponse | None) -> str | None (src/tac/core/tac.py:266-272) |
one object, 8 members — { conversationId, profileId, message, author, memory, session, channel, abortSignal? } (packages/core/src/lib/tac.ts:29-38) |
| interrupt | two positionals — (context, interrupt_data: Any) (tac.py:294-300) |
one object — { conversationId, utteranceUntilInterrupt, durationUntilInterruptMs, session } (tac.ts:40-45) |
| conversation ended | one positional — (context) (tac.py:318-323) |
one object — { session } (tac.ts:47-49) |
| error | TAC.on_error(cb) — on TAC, typed (Exception, dict[str, Any]) (tac.py:341-347) |
channel.on('error', cb) — on the channel, untyped (...args: any[]), dispatched by a switch on a string (packages/core/src/channels/base.ts:123-134) |
What we checked and found is NOT a gap
Recording these because they are the obvious-looking differences and they do not hold up — we would rather not send anyone after them.
authorandchannelare reachable here.ConversationSessioncarrieschannel: str(src/tac/models/session.py:45),author_info: AuthorInfo | None(:53) andai_agent_info(:56). The TypeScript handler receivesauthorandchannelas flattened members of its params object; here they are one level down, oncontext. That is depth, not absence.- The missing
abortSignalis not a missing capability. TypeScript needs an explicitAbortSignalbecause aPromiseis not cancellable.asynciocancellation is native here, and this SDK deliberately supports it:src/tac/channels/base.py:371-372and:403-404re-raiseasyncio.CancelledErrorwith the comment "Re-raise to allow proper cancellation (e.g., Voice channel interrupts)". Two idioms for one capability.
The one that is a real divergence
The error handler is registered on a different object in each SDK, and only one of them is typed. This SDK's design is the better one and we think it should be the one that wins:
- it is on
TAC, so an application registers once and observes everything the SDK handles internally, rather than once per channel; - it is typed —
(Exception, dict[str, Any])— where the TypeScript side accepts(...args: any[])through a stringly-typed dispatcher that has nodefaultclause, so a misspelled event name there registers nothing and reports nothing; - its docstring states the purpose exactly right: "surface failures that TAC handles internally but that would otherwise be invisible to your application". That is the problem both SDKs have, and only this one gives the application a hook for it.
What we think should happen
- Decide and publish which handler surface is canonical, so handlers added to either SDK converge rather than diverge further. The event surface is the newest and most active part of both, which is where divergence accumulates fastest.
- For the error hook specifically, we think the TypeScript side should adopt this SDK's shape — a typed,
TAC-level handler — rather than this SDK adopting theirs. Raised on the companion issue. - If the positional-versus-object difference is deliberately per-language (which is defensible — a params object is natural in TS, keyword arguments are native here), documenting the mapping somewhere both SDKs point at would be enough. A table like the one above.
Context, offered as motivation rather than a request: we maintain a code generator that emits Agent Connect clients, and it has to choose one event-handler shape. Where the two hand-written SDKs disagree, any choice is wrong for one of them. "This is intentional, here is the mapping" is a perfectly good answer and is actionable in a way silence is not.
Thanks for reading.
- Dominant language
- Python
- Stars
- 17
- Forks
- 11
- Avg merge
- 5d 19h
- Merged PRs (30d)
- 6
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from twilio/twilio-agent-connect-python
-
ParticipantResponse.name is required where the API definition marks it nullable, so a nameless participant fails to parsePossibly taken @TheeCoderAhmed claimed this 22 days ago. Open
Difficulty 1/5 Under an hour Newbie friendliness 86/100
twilio/twilio-agent-connect-python#134 ·
Maintainers usually reply within 5 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 50/100
twilio/twilio-agent-connect-python#136 ·
Maintainers usually reply within 5 days
-
Difficulty 4/5 3-5 days Newbie friendliness 45/100
twilio/twilio-agent-connect-python#133 ·
Maintainers usually reply within 5 days
-
Difficulty 5/5 Over a week Newbie friendliness 30/100
twilio/twilio-agent-connect-python#101 ·
Maintainers usually reply within 5 days
-
add tac config validationsPossibly taken @rahulsjha claimed this 4 days ago. Open
Difficulty 3/5 1-2 days Newbie friendliness 45/100
twilio/twilio-agent-connect-python#70 · 1 comment ·
Maintainers usually reply within 5 days
All issues in twilio/twilio-agent-connect-python
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
Maintainers usually reply within 1 day
-
area:cli area:security enhancement priority:medium size:small
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
RonaldHensbergen/composable-data-stack#1338 ·
Maintainers usually reply within 1 day
-
area:stdlib effort:S impact:med platform:linux type:bug
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
Maintainers usually reply within 1 day
-
automated endpoint-dead needs-curation
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
almanac-data/climate-almanac#139 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
UKGovernmentBEIS/inspect_ai#6695 · 1 comment ·
Maintainers usually reply within 1 day