feat(protoface): add avatar plugin#1876
Conversation
🦋 Changeset detectedLatest commit: e6d4664 The changes in this PR will be included in the next version bump. This PR includes changesets to release 36 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
| this.apiUrl = (options.apiUrl ?? process.env.PROTOFACE_API_URL ?? DEFAULT_API_URL).replace( | ||
| /\/+$/, | ||
| '', | ||
| ); |
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| /** Protoface API key. Falls back to the `PROTOFACE_API_KEY` env var. */ | ||
| apiKey?: string | null; | ||
| /** Optional maximum session duration. Protoface applies the lower of this and the plan limit. */ | ||
| maxDurationSeconds?: number | null; |
There was a problem hiding this comment.
🟡 Time-based parameter maxDurationSeconds violates CLAUDE.md naming convention
The CLAUDE.md convention explicitly states: "Use milliseconds for all time-based values by default. Only use seconds when the name explicitly ends with InS." The maxDurationSeconds field name uses seconds but ends with Seconds instead of InS. This appears in both plugins/protoface/src/avatar.ts:34 (the AvatarSessionOptions interface) and plugins/protoface/src/api.ts:41 (the StartSessionOptions interface), as well as the class field at plugins/protoface/src/avatar.ts:61. Per the convention, this should either be stored as milliseconds (e.g., maxDurationMs) with conversion at the API boundary, or named with the InS suffix (e.g., maxDurationInS).
Prompt for agents
The CLAUDE.md convention requires all time-based values to use milliseconds by default, with the InS suffix being the only exception for seconds. The maxDurationSeconds field appears in AvatarSessionOptions (avatar.ts:34), the AvatarSession class field (avatar.ts:61), StartSessionOptions (api.ts:41), and usages in avatar.ts:72,126 and api.ts:80-81. Either rename to maxDurationInS across both files (keeping seconds, matching the InS convention), or rename to maxDurationMs (using milliseconds) and convert to seconds at the API call site in api.ts startSession() where it sets body.max_duration_seconds.
Was this helpful? React with 👍 or 👎 to provide feedback.
| try { | ||
| const jobCtx = getJobContext(); | ||
| localParticipantIdentity = jobCtx.agent?.identity || ''; | ||
| } catch { | ||
| // Fall back to the connected room below when no job context is available. | ||
| } |
There was a problem hiding this comment.
🚩 Protoface uses jobCtx.agent?.identity while Bey/Trugen use jobCtx.job.participant?.identity for publish-on-behalf
In mintWorkerToken, the Protoface plugin resolves the local participant identity via jobCtx.agent?.identity (plugins/protoface/src/avatar.ts:175), which is room.localParticipant — the agent's own identity. In contrast, Bey (plugins/bey/src/avatar.ts:175) and Trugen (plugins/trugen/src/avatar.ts:140) use jobCtx.job.participant?.identity, which is the remote human participant who triggered the job. For the lk.publish_on_behalf attribute, the avatar should publish on behalf of the local agent, so the Protoface approach appears semantically more correct. However, this inconsistency between plugins is worth noting — the older plugins may have a latent bug.
Was this helpful? React with 👍 or 👎 to provide feedback.
1 participant
Summary
@livekit/agents-plugin-protofaceavatar plugin ported from feat: add Protoface avatar plugin agents#6164Testing
pnpm --filter @livekit/agents buildpnpm --filter @livekit/agents-plugin-protoface lintpnpm --filter @livekit/agents-plugin-protoface buildpnpm --filter @livekit/agents-plugin-protoface api:updatepnpm --filter @livekit/agents-plugin-protoface api:checkNote:
pnpm --filter livekit-agents-examples buildis currently blocked by pre-existing unbuilt workspace plugin declaration outputs; it also caught and I fixed the new Protoface example option name.Ported from livekit/agents#6164
Original PR description
Docs
Public demo