feat(boson-avatar): add avatar plugin

[warlockee]

Summary

• add livekit-plugins-boson-avatar, a BYOK Avatar plugin for Boson Higgs Audio-Driven Avatar
• compose with the existing AgentSession voice pipeline instead of creating a second voice participant
• accept provider connection settings from the host application; the plugin has no built-in provider hostname
• add project-scoped Avatar discovery so applications can populate a face picker without hard-coded IDs
• mint a least-privilege, room-scoped Avatar token and route generic 24 kHz agent PCM over LiveKit data streams
• add provider start/delete lifecycle handling, idempotent retries, startup compensation, and cancellation-safe cleanup
• register the package in the uv workspace and livekit-agents[boson-avatar] optional dependencies

Developer experience

The host application is the composition root: it supplies its Boson endpoint and API key, loads the project catalog server-side, and passes the Avatar selected by its UI to the session.

from livekit.plugins import boson_avatar

avatars = await boson_avatar.list_avatars()
# Return only avatar_id + name to the browser's face picker.

avatar = boson_avatar.AvatarSession(
    avatar_id=selected_avatar_id,
    api_url="https://your-boson-endpoint.example/v1/avatar/livekit",
)
await avatar.start(session, room=ctx.room)

api_url may alternatively be supplied through BOSON_AVATAR_API_URL; BOSON_API_KEY supplies the API key. The plugin intentionally does not define or assume a production hostname. It accepts the audio output of any compatible AgentSession voice pipeline and has no dependency on a Boson audio model. The URL must be an HTTPS base URL (loopback HTTP is allowed for local development); the plugin appends /avatars and the session resource paths. list_avatars() owns its short-lived HTTP client, so it also works in a normal application server outside a LiveKit job context.

Validation

• uv run ruff format --check . and uv run ruff check . — passed
• uv run python scripts/check_types.py — passed strict mypy
• plugin unit suite — 27 tests plus 33 subtests passed, including catalog validation, endpoint validation, concurrent close, and repeated-cancellation regressions
• wheel and sdist build passed
• exact PR package completed a least-privilege live staging E2E: can_subscribe=False, Avatar joined, targeted PCM streamed, audio and video tracks published, and DELETE cleanup returned all four GPU workers to idle

Integration boundary

Deployment of a compatible Boson Avatar endpoint is an application/provider concern, not a plugin release dependency. The host app owns endpoint selection and composes the voice pipeline, Avatar plugin, LiveKit room, API credentials, and Avatar selection. The browser receives only catalog display data; the provider URL and Boson API key stay server-side.

The provider should retain its project-scoped catalog plus room-disconnect and max-duration reapers for process-kill and lost-response boundaries where a client can never receive the provider session ID.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ warlockee
❌ erik

---

erik seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[devin-ai-integration]

Note

This report is out of date. Scroll down for Devin Review's latest report on this PR.

🔍 Devin Review: 1 flag

Not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)

[warlockee]

Ready for maintainer review at 30625f3.

• All GitHub CI checks, CLA, and Devin Review are green.
• Addressed and resolved all three security review threads. Provider errors are no longer emitted through exception tracebacks; logs retain only a safe error type, and provider identifiers are marked as PII.
• Proactively stripped sensitive provider exception context after exhausted retries and covered compensation, shutdown, background-task, and retry logging with regression tests.
• Local validation: 30 Boson Avatar tests passed, full repository make check passed across 650 typed source files, and both wheel and sdist built successfully.
• The AvatarSession remains audio-provider agnostic and has no Boson audio dependency or hard-coded api.boson.ai endpoint.

@tinalenguyen, would you be able to take a look? You reviewed the recent Runway and Protoface Avatar plugin contributions.

[warlockee]

@tinalenguyen, following up on this Boson Avatar plugin contribution. I've merged current main (3334771d2) into the PR and resolved the dependency/workspace conflicts. The current head is 8e884f83d.

The latest code fixes both new public Devin findings: close can no longer spin on a completed startup-cleanup task while its callback is queued, and an avatar identity matching the agent is rejected before token issuance or provider creation. Regression tests reproduced both problems before the fixes and now pass, including DELETE retry after failed startup cleanup.

All GitHub checks on 8e884f83d are now passing (including Devin Review and CLA); three non-applicable jobs were skipped. All five public review threads are resolved.

Validation on the updated branch:

• make check passed on Python 3.13 (663 typed source files).
• Boson plugin suite: 32 tests and 38 subtests passed on Python 3.13 and 3.14.
• Repository unit/audio end-of-turn suite after merging main: 2,758 passed, 5 skipped on Python 3.14.
• Wheel and sdist built successfully; uv lock --check passed.

The three earlier public security review threads remain resolved. The plugin continues to compose with the existing AgentSession audio pipeline, with no Boson audio dependency or hard-coded provider endpoint.

Could you review this, or help route it to the appropriate avatar-plugin maintainer? I can address any further changes. If there are provider-onboarding or release requirements beyond the code review, please let me know what is needed. Devin also mentions a finding hidden by the repository's GitHub settings; if it remains actionable, could you share it here so I can address it?

[warlockee]

Hi @longcw, would you have time to review this Boson Avatar plugin when convenient? I noticed you reviewed the Spatius integration (#5821) and the recent Avatar audio-stream recovery fix (#7007), so your perspective on the session lifecycle and audio routing would be especially helpful.

The PR is updated with main and has no merge conflicts. CI, CLA, and Devin checks are passing at 8e884f83d; all five public review threads are resolved, with regression tests for the latest cleanup and identity-collision fixes. The validation details are in the comment above.

I'd appreciate any feedback and am happy to make changes to align with the existing Avatar plugins. If someone else is better placed to review this, a pointer would be very helpful. Thank you!