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

Aperta
#135 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 5 giorni

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
25/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
python, typescript
Ambito
api

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.

Lingua principale
Python
Stelle
17
Fork
11
Merge medio
5g 19h
PR unite (30g)
6

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di twilio/twilio-agent-connect-python

Tutte le issue di twilio/twilio-agent-connect-python

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.