Handler-surface parity with the TypeScript SDK: four handlers, four shapes — and the error hook is the one real divergence

Open
#135 0 comments 0 reactions 0 assignees View on GitHub

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.

  • author and channel are reachable here. ConversationSession carries channel: str (src/tac/models/session.py:45), author_info: AuthorInfo | None (:53) and ai_agent_info (:56). The TypeScript handler receives author and channel as flattened members of its params object; here they are one level down, on context. That is depth, not absence.
  • The missing abortSignal is not a missing capability. TypeScript needs an explicit AbortSignal because a Promise is not cancellable. asyncio cancellation is native here, and this SDK deliberately supports it: src/tac/channels/base.py:371-372 and :403-404 re-raise asyncio.CancelledError with 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 no default clause, 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

  1. 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.
  2. 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.
  3. 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

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from twilio/twilio-agent-connect-python

All issues in twilio/twilio-agent-connect-python

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.