@talqing/client 0.4.0

package/dist/esm/userdata.d.ts

@@ -0,0 +1,22 @@
+import { type RemoteParticipant, type Room } from "livekit-client";
+import type { JsonObject } from "./json.js";
+/** The agent on this call, or undefined before it has joined.
+ *
+ *  On a video call the avatar worker is an agent participant too, but it joins
+ *  on the agent's behalf and never answers RPCs, so the first one found is the
+ *  one to talk to. */
+export declare function talqingAgentParticipant(room: Room): RemoteParticipant | undefined;
+/** Merge a patch into the live session's userdata, over RPC to the agent.
+ *
+ *  Resolves rather than throws when the agent is not there: a write that did
+ *  not land is a state a page can render. */
+export declare function setTalqingUserdata(room: Room, patch: JsonObject, responseTimeout?: number): Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+/** Read the live session's userdata, or only the keys named.
+ *
+ *  Throws when the agent is not there, unlike `setTalqingUserdata`: a read that
+ *  returned nothing is not a state anything can render. */
+export declare function getTalqingUserdata(room: Room, keys?: string[], responseTimeout?: number): Promise<JsonObject>;
+//# sourceMappingURL=userdata.d.ts.map

package/dist/esm/userdata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"userdata.d.ts","sourceRoot":"","sources":["../../src/userdata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,iBAAiB,EAAE,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACpF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C;;;;sBAIsB;AACtB,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,IAAI,GAAG,iBAAiB,GAAG,SAAS,CAIjF;AAED;;;6CAG6C;AAC7C,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,UAAU,EACjB,eAAe,SAAI,GAClB,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAU1C;AAED;;;2DAG2D;AAC3D,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,EACV,IAAI,CAAC,EAAE,MAAM,EAAE,EACf,eAAe,SAAI,GAClB,OAAO,CAAC,UAAU,CAAC,CAcrB"}

package/dist/esm/userdata.js

@@ -0,0 +1,46 @@
+import { ParticipantKind } from "livekit-client";
+/** The agent on this call, or undefined before it has joined.
+ *
+ *  On a video call the avatar worker is an agent participant too, but it joins
+ *  on the agent's behalf and never answers RPCs, so the first one found is the
+ *  one to talk to. */
+export function talqingAgentParticipant(room) {
+    return [...room.remoteParticipants.values()].find((participant) => participant.kind === ParticipantKind.AGENT);
+}
+/** Merge a patch into the live session's userdata, over RPC to the agent.
+ *
+ *  Resolves rather than throws when the agent is not there: a write that did
+ *  not land is a state a page can render. */
+export async function setTalqingUserdata(room, patch, responseTimeout = 3) {
+    const agent = talqingAgentParticipant(room);
+    if (!agent)
+        return { ok: false, error: "agent participant is not connected" };
+    const response = await room.localParticipant.performRpc({
+        destinationIdentity: agent.identity,
+        method: "talqing.client.userdata_set",
+        payload: JSON.stringify(patch),
+        responseTimeout,
+    });
+    return JSON.parse(response || "{}");
+}
+/** Read the live session's userdata, or only the keys named.
+ *
+ *  Throws when the agent is not there, unlike `setTalqingUserdata`: a read that
+ *  returned nothing is not a state anything can render. */
+export async function getTalqingUserdata(room, keys, responseTimeout = 3) {
+    const agent = talqingAgentParticipant(room);
+    if (!agent)
+        throw new Error("agent participant is not connected");
+    const response = await room.localParticipant.performRpc({
+        destinationIdentity: agent.identity,
+        method: "talqing.client.userdata_get",
+        payload: JSON.stringify(keys ? { keys } : {}),
+        responseTimeout,
+    });
+    const parsed = JSON.parse(response || "{}");
+    if (parsed.ok === false) {
+        throw new Error(String(parsed.error || "userdata RPC failed"));
+    }
+    return parsed;
+}
+//# sourceMappingURL=userdata.js.map

package/dist/esm/userdata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"userdata.js","sourceRoot":"","sources":["../../src/userdata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAqC,MAAM,gBAAgB,CAAC;AAGpF;;;;sBAIsB;AACtB,MAAM,UAAU,uBAAuB,CAAC,IAAU;IAChD,OAAO,CAAC,GAAG,IAAI,CAAC,kBAAkB,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAC/C,CAAC,WAA8B,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,KAAK,eAAe,CAAC,KAAK,CAC/E,CAAC;AACJ,CAAC;AAED;;;6CAG6C;AAC7C,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAU,EACV,KAAiB,EACjB,eAAe,GAAG,CAAC;IAEnB,MAAM,KAAK,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,oCAAoC,EAAE,CAAC;IAC9E,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC;QACtD,mBAAmB,EAAE,KAAK,CAAC,QAAQ;QACnC,MAAM,EAAE,6BAA6B;QACrC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;QAC9B,eAAe;KAChB,CAAC,CAAC;IACH,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAoC,CAAC;AACzE,CAAC;AAED;;;2DAG2D;AAC3D,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAU,EACV,IAAe,EACf,eAAe,GAAG,CAAC;IAEnB,MAAM,KAAK,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IAClE,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC;QACtD,mBAAmB,EAAE,KAAK,CAAC,QAAQ;QACnC,MAAM,EAAE,6BAA6B;QACrC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,eAAe;KAChB,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAkD,CAAC;IAC7F,IAAI,MAAM,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,IAAI,qBAAqB,CAAC,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@talqing/client",
+  "version": "0.4.0",
+  "description": "The Talqing call protocol over a LiveKit room — token, userdata, images, screen share and frontend RPC. Framework-free.",
+  "license": "MIT",
+  "homepage": "https://talqing.com",
+  "bugs": {
+    "email": "hello@talqing.com"
+  },
+  "keywords": [
+    "talqing",
+    "ai",
+    "agents",
+    "voice",
+    "video",
+    "livekit",
+    "webrtc"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node ../../scripts/dist-markers.mjs",
+    "dev": "tsc -w -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "livekit-client": "^2.19.1"
+  },
+  "devDependencies": {
+    "livekit-client": "^2.19.1",
+    "typescript": "~5.9.3"
+  }
+}

package/src/images.ts

@@ -0,0 +1,160 @@
+import type { Room, RpcInvocationData } from "livekit-client";
+import { talqingAgentParticipant } from "./userdata.js";
+
+/* ── images ───────────────────────────────────────────────────────────────
+ *
+ * A caller attaches a photo on a web voice or video call and the agent sees
+ * it. The bytes go over a LiveKit byte stream on the `talqing.images` topic,
+ * addressed to the agent; the agent answers on an RPC back, and the id
+ * `sendFile` returns is the id that ack carries, so there is nothing to
+ * correlate by hand.
+ *
+ * The agent deliberately does NOT speak when a photo lands — the caller is
+ * mid-conversation and about to say what it is for. The image is in the
+ * model's view for their next turn.
+ */
+
+export const TALQING_IMAGE_TOPIC = "talqing.images";
+/** Decoded size the server refuses above. The downscale below keeps a phone
+ *  photo far under it; this is the belt for a file that is not a photo. */
+export const TALQING_IMAGE_MAX_BYTES = 10 * 1024 * 1024;
+/** Longest side the server stores. Downscaling to it before sending is a
+ *  courtesy to the data channel, which is ordered and reliable and will
+ *  happily spend a minute pushing 10 MB past a call's audio. */
+export const TALQING_IMAGE_MAX_EDGE_PX = 1568;
+const TALQING_IMAGE_TYPES = ["image/jpeg", "image/png", "image/webp"] as const;
+/** How long to wait for the agent's ack before saying we do not know. Without
+ *  it a thumbnail sits on "sending" for the rest of the call when the worker
+ *  dies mid-upload. */
+export const TALQING_IMAGE_ACK_TIMEOUT_MS = 30_000;
+
+/** Refuse what the browser can see is wrong, instantly and with no round trip.
+ *  Returns the sentence to show, or null when the file is fine. The server
+ *  re-validates everything regardless — this exists so the common mistakes cost
+ *  nothing to catch. */
+export function talqingImageRejection(file: File): string | null {
+  if (!(TALQING_IMAGE_TYPES as readonly string[]).includes(file.type)) {
+    return "that file is not a JPEG, PNG or WebP";
+  }
+  if (file.size > TALQING_IMAGE_MAX_BYTES) return "images are 10 MB or smaller";
+  return null;
+}
+
+/** Downscale to the longest edge the server keeps, re-encoding as JPEG or PNG.
+ *
+ *  Also what normalizes whatever the OS handed the file input — this is how a
+ *  Safari HEIC becomes a JPEG. Throws if the image cannot be decoded, which is
+ *  the third dropzone check. */
+export async function talqingDownscaleImage(file: File): Promise<Blob> {
+  const bitmap = await createImageBitmap(file);
+  try {
+    const longest = Math.max(bitmap.width, bitmap.height);
+    const scale = longest > TALQING_IMAGE_MAX_EDGE_PX ? TALQING_IMAGE_MAX_EDGE_PX / longest : 1;
+    const canvas = document.createElement("canvas");
+    canvas.width = Math.max(1, Math.round(bitmap.width * scale));
+    canvas.height = Math.max(1, Math.round(bitmap.height * scale));
+    const context = canvas.getContext("2d");
+    if (!context) throw new Error("this browser cannot resize images");
+    context.drawImage(bitmap, 0, 0, canvas.width, canvas.height);
+    // PNG keeps transparency; everything else becomes a JPEG, including the
+    // HEIC the OS decoded for us.
+    const type = file.type === "image/png" ? "image/png" : "image/jpeg";
+    const blob = await new Promise<Blob | null>((resolve) =>
+      canvas.toBlob(resolve, type, 0.85),
+    );
+    if (!blob) throw new Error("that image could not be read");
+    return blob;
+  } finally {
+    bitmap.close();
+  }
+}
+
+/** Validate and downscale a file into the `data:` URL a text message carries.
+ *
+ *  `createTextMessage` takes `images: [{data_url, filename}]`; this produces the
+ *  `data_url`. It doubles as the thumbnail's `src`, so there is no object URL to
+ *  create and revoke. Throws the sentence to show if the file is refused. */
+export async function talqingImageDataUrl(file: File): Promise<string> {
+  const rejection = talqingImageRejection(file);
+  if (rejection) throw new Error(rejection);
+  const blob = await talqingDownscaleImage(file);
+  return await new Promise<string>((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onerror = () => reject(new Error("that image could not be read"));
+    reader.onload = () => resolve(String(reader.result));
+    reader.readAsDataURL(blob);
+  });
+}
+
+export type TalqingImageStatus = "sending" | "sent" | "failed" | "unknown";
+
+/** One image the browser sent on a call, and what became of it. */
+export interface TalqingSentImage {
+  /** The stream id `sendFile` returned, which the ack comes back under. */
+  streamId: string;
+  name: string;
+  /** An object URL for the downscaled image, for rendering the thumbnail.
+   *  Revoke it when you are done with it — `useTalqingImages` does. */
+  previewUrl: string;
+  /** When it was handed to the room, so a transcript can put it in the sequence
+   *  it was sent in rather than at the end. */
+  sentAt: number;
+  status: TalqingImageStatus;
+  /** Set when `status` is "failed" or "unknown" — a sentence, shown as-is. */
+  error?: string;
+}
+
+/** Validate, downscale and send one image to the agent on this call.
+ *
+ *  Resolves once the bytes are on their way, with the entry to render. The
+ *  outcome arrives later, on the ack — see `onTalqingImageResult`. Throws the
+ *  sentence to show if the file is refused or the agent is not there yet. */
+export async function sendTalqingImage(room: Room, file: File): Promise<TalqingSentImage> {
+  const agent = talqingAgentParticipant(room);
+  if (!agent) throw new Error("the agent is not on the call yet");
+  const rejection = talqingImageRejection(file);
+  if (rejection) throw new Error(rejection);
+
+  const blob = await talqingDownscaleImage(file);
+  // Addressed to the agent, never broadcast: on video the avatar worker is
+  // a participant too, and a broadcast sends the bytes twice.
+  const { id } = await room.localParticipant.sendFile(
+    new File([blob], file.name, { type: blob.type }),
+    {
+      topic: TALQING_IMAGE_TOPIC,
+      mimeType: blob.type,
+      destinationIdentities: [agent.identity],
+    },
+  );
+  return {
+    streamId: id,
+    name: file.name,
+    previewUrl: URL.createObjectURL(blob),
+    sentAt: Date.now(),
+    status: "sending",
+  };
+}
+
+/** Listen for the agent's verdict on each image sent. Returns the unregister.
+ *
+ *  There is one ack per image even on the happy path, because the agent stays
+ *  silent when a photo lands — so silence cannot double as "it arrived". */
+export function onTalqingImageResult(
+  room: Room,
+  onResult: (result: { streamId: string; ok: boolean; error?: string }) => void,
+): () => void {
+  room.registerRpcMethod("talqing.image_result", async (data: RpcInvocationData) => {
+    const { stream_id, ok, error } = JSON.parse(data.payload || "{}") as {
+      stream_id: string;
+      ok: boolean;
+      error?: string | null;
+    };
+    onResult({
+      streamId: stream_id,
+      ok,
+      error: ok ? undefined : error || "that image was not accepted",
+    });
+    return "{}";
+  });
+  return () => room.unregisterRpcMethod("talqing.image_result");
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+/* The Talqing call protocol, over a LiveKit `Room`. Framework-free.
+ *
+ * Everything here is something only Talqing can write: the mint-once token
+ * source, the two userdata RPC methods, the `talqing.images` byte-stream topic
+ * and its ack, the `talqing.frontend_rpc` envelope, and the measured capture
+ * settings. Nothing here renames LiveKit — for a room, a track or a
+ * participant, use `livekit-client` directly.
+ *
+ * React bindings for all of it are `@talqing/react`.
+ */
+
+export { createTalqingTokenSource } from "./token.js";
+export type { TalqingCallCredentials } from "./token.js";
+
+export {
+  getTalqingUserdata,
+  setTalqingUserdata,
+  talqingAgentParticipant,
+} from "./userdata.js";
+
+export {
+  onTalqingImageResult,
+  sendTalqingImage,
+  talqingDownscaleImage,
+  talqingImageDataUrl,
+  talqingImageRejection,
+  TALQING_IMAGE_ACK_TIMEOUT_MS,
+  TALQING_IMAGE_MAX_BYTES,
+  TALQING_IMAGE_MAX_EDGE_PX,
+  TALQING_IMAGE_TOPIC,
+} from "./images.js";
+export type { TalqingImageStatus, TalqingSentImage } from "./images.js";
+
+export { registerTalqingRpcHandlers, TalqingRpcError } from "./rpc.js";
+export type {
+  TalqingFrontendRpcEnvelope,
+  TalqingRpcHandler,
+  TalqingRpcHandlers,
+  TalqingRpcInvocation,
+} from "./rpc.js";
+
+export {
+  TALQING_AUDIO_CAPTURE_DEFAULTS,
+  TALQING_SCREEN_SHARE_CAPTURE,
+  TALQING_SCREEN_SHARE_PUBLISH,
+} from "./media.js";
+
+export type { JsonObject, JsonPrimitive, JsonValue } from "./json.js";

package/src/json.ts

@@ -0,0 +1,17 @@
+/* Free-form JSON: userdata, a frontend-RPC payload.
+ *
+ * `@talqing/sdk` declares the same three aliases for the same reason, and this
+ * package deliberately does not import them from there: the whole point of the
+ * split is that the call protocol needs no API client. These are structural
+ * aliases, so the two spellings are the same type to a consumer holding both.
+ *
+ * `JsonObject` is exactly what the API says such a field is — an object of
+ * `unknown` — so a value read off a response drops straight into it. Naming it
+ * anything narrower would assert a guarantee the API does not make.
+ *
+ * `JsonValue` is the recursive form, for a payload the CALLER builds: there it
+ * is a real constraint, because it refuses a `Date` or a class instance that
+ * would not survive `JSON.stringify`. */
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+export type JsonObject = { [key: string]: unknown };

package/src/media.ts

@@ -0,0 +1,53 @@
+import type { ScreenShareCaptureOptions, TrackPublishOptions } from "livekit-client";
+
+/* Echo cancellation is what stops the agent hearing its own speech through the
+ * caller's microphone and interrupting itself. It is a default rather than
+ * something each app remembers, because a call without it is broken in a way
+ * that sounds like a bad model. Pass `roomOptions.audioCaptureDefaults` to
+ * override. */
+export const TALQING_AUDIO_CAPTURE_DEFAULTS = {
+  echoCancellation: true,
+  noiseSuppression: true,
+  autoGainControl: true,
+} as const;
+
+/* Screen share, with the four settings that decide whether the agent can read
+ * what is on it.
+ *
+ * Only the first is obvious, and every one of them is upstream of anything we
+ * could do on our side:
+ *
+ *  - `contentHint: "text"` tells the encoder to preserve spatial detail. The
+ *    default for a screen share on an SVC codec is `motion`, which trades
+ *    exactly that away — the wrong trade for reading code, and no JPEG quality
+ *    setting downstream recovers it.
+ *  - `videoCodec: "h264"` is what keeps that hint. `livekit-client` forces
+ *    `contentHint = "motion"` on screen shares published as vp9 or av1,
+ *    together with `scalabilityMode: "L1T3"`. **Publishing on an SVC codec will
+ *    cost you legibility**, and it is the first thing to check if the agent
+ *    starts misreading identifiers.
+ *  - `screenShareEncoding.maxFramerate: 1` is the frame-rate cap that actually
+ *    binds. `resolution.frameRate` reaches `getDisplayMedia` as a bare number,
+ *    which WebRTC reads as `ideal` — a wish, not a limit. The default publish
+ *    ceiling is 15 fps, and every delivered frame is copied into the agent's
+ *    process before it can be dropped, so this is the single biggest lever on
+ *    what a call costs the worker. One frame a second is ample: the agent is
+ *    handed the newest frame at the end of each turn, and turns are seconds
+ *    apart.
+ *  - `resolution` is set explicitly rather than inherited. The default is 1080p
+ *    by `ideal`, which is a strong hint and not a guarantee.
+ *
+ * The picker cannot be opened for the person — `getDisplayMedia` requires a
+ * transient user activation — so sharing must start from a click. The agent
+ * asking out loud is what prompts it; there is no version of this where the
+ * agent turns sharing on.
+ */
+export const TALQING_SCREEN_SHARE_CAPTURE: ScreenShareCaptureOptions = {
+  resolution: { width: 1920, height: 1080, frameRate: 1 },
+  contentHint: "text",
+};
+
+export const TALQING_SCREEN_SHARE_PUBLISH: TrackPublishOptions = {
+  videoCodec: "h264",
+  screenShareEncoding: { maxBitrate: 1_000_000, maxFramerate: 1 },
+};

package/src/rpc.ts

@@ -0,0 +1,81 @@
+import { RpcError, type Room, type RpcInvocationData } from "livekit-client";
+import type { JsonValue } from "./json.js";
+
+/* ── frontend RPC ─────────────────────────────────────────────────────────
+ *
+ * A tool's `frontend_rpc` operation calls back into the page mid-call. The
+ * agent RPCs ONE method — `talqing.frontend_rpc` — carrying an envelope that
+ * names the method the page should run, so a page registers once and dispatches
+ * on `envelope.method` rather than registering a room method per tool.
+ */
+
+export interface TalqingRpcInvocation {
+  payload: string;
+  responseTimeout?: number;
+  callerIdentity?: string;
+}
+
+export type TalqingRpcHandler = (
+  data: TalqingRpcInvocation,
+) => string | Promise<string>;
+export type TalqingRpcHandlers = Record<string, TalqingRpcHandler>;
+
+export interface TalqingFrontendRpcEnvelope {
+  method: string;
+  payload?: JsonValue;
+}
+
+/** Throw this from a handler to choose the code the agent sees. */
+export class TalqingRpcError extends Error {
+  readonly code: number;
+  readonly data?: string;
+
+  constructor(code: number, message: string, data?: string) {
+    super(message);
+    this.name = "TalqingRpcError";
+    this.code = code;
+    this.data = data;
+  }
+}
+
+/** Register the frontend-RPC envelope handler on a room. Returns the unregister.
+ *
+ *  A `"*"` key catches every method with no handler of its own, and receives the
+ *  WHOLE envelope as its payload string so it can tell what it caught. */
+export function registerTalqingRpcHandlers(
+  room: Room,
+  handlers: TalqingRpcHandlers,
+): () => void {
+  room.registerRpcMethod("talqing.frontend_rpc", async (data: RpcInvocationData) => {
+    try {
+      const envelope = JSON.parse(data.payload || "{}") as TalqingFrontendRpcEnvelope;
+      const isWildcard = handlers[envelope.method] === undefined;
+      const handler = handlers[envelope.method] ?? handlers["*"];
+      if (!handler) {
+        throw new TalqingRpcError(
+          1404,
+          `No frontend RPC handler registered for ${envelope.method}`,
+        );
+      }
+      return await handler({
+        payload: isWildcard
+          ? JSON.stringify(envelope)
+          : envelope.payload === undefined
+            ? "{}"
+            : JSON.stringify(envelope.payload),
+        responseTimeout: data.responseTimeout,
+        callerIdentity: data.callerIdentity,
+      });
+    } catch (error) {
+      if (error instanceof TalqingRpcError) {
+        throw new RpcError(error.code, error.message, error.data);
+      }
+      throw new RpcError(
+        1500,
+        error instanceof Error ? error.message : "RPC handler failed",
+      );
+    }
+  });
+
+  return () => room.unregisterRpcMethod("talqing.frontend_rpc");
+}

package/src/token.ts

@@ -0,0 +1,49 @@
+import { TokenSource, type TokenSourceFixed } from "livekit-client";
+
+/** The two fields a browser needs to join a room, and nothing else.
+ *
+ *  Named as `POST /v1/calls/token` names them, so a server that mints one can
+ *  forward the response through to the browser without renaming anything. */
+export interface TalqingCallCredentials {
+  server_url: string;
+  participant_token: string;
+}
+
+/** Turn a one-shot mint into the token source LiveKit's session takes.
+ *
+ *  `fetchToken` is called at most once per source, no matter how often LiveKit
+ *  asks. That is load-bearing rather than an optimization: minting is not free,
+ *  because `POST /v1/calls/token` files the session row the call is later read
+ *  back from. The framework asks three times per call — to warm the connection,
+ *  to connect, and once more as the call ends to drop what it assumes is a
+ *  cached token — and only the middle one is a call anybody placed. Minting for
+ *  the third filed a session nobody ever joined, which sat in the workspace's
+ *  call list as queued for good.
+ *
+ *  `TokenSource.literal` is the LiveKit variant that leaves caching to us, and
+ *  this is us doing it.
+ *
+ *  Freshness comes from a new source per call, never from re-minting inside
+ *  one: the token names the room, and this call has exactly one. Mount the
+ *  session per call and end it on unmount, as LiveKit's own session lifecycle
+ *  does, and that holds by construction. */
+export function createTalqingTokenSource(
+  fetchToken: () => Promise<TalqingCallCredentials>,
+): TokenSourceFixed {
+  let minted: Promise<{ serverUrl: string; participantToken: string }> | null = null;
+
+  return TokenSource.literal(() => {
+    // A mint that failed is not this call's token, and the surface will offer
+    // the call again — so keep the rejection out of the cache.
+    minted ??= fetchToken()
+      .then((credentials) => ({
+        serverUrl: credentials.server_url,
+        participantToken: credentials.participant_token,
+      }))
+      .catch((error: unknown) => {
+        minted = null;
+        throw error;
+      });
+    return minted;
+  });
+}

package/src/userdata.ts

@@ -0,0 +1,57 @@
+import { ParticipantKind, type RemoteParticipant, type Room } from "livekit-client";
+import type { JsonObject } from "./json.js";
+
+/** The agent on this call, or undefined before it has joined.
+ *
+ *  On a video call the avatar worker is an agent participant too, but it joins
+ *  on the agent's behalf and never answers RPCs, so the first one found is the
+ *  one to talk to. */
+export function talqingAgentParticipant(room: Room): RemoteParticipant | undefined {
+  return [...room.remoteParticipants.values()].find(
+    (participant: RemoteParticipant) => participant.kind === ParticipantKind.AGENT,
+  );
+}
+
+/** Merge a patch into the live session's userdata, over RPC to the agent.
+ *
+ *  Resolves rather than throws when the agent is not there: a write that did
+ *  not land is a state a page can render. */
+export async function setTalqingUserdata(
+  room: Room,
+  patch: JsonObject,
+  responseTimeout = 3,
+): Promise<{ ok: boolean; error?: string }> {
+  const agent = talqingAgentParticipant(room);
+  if (!agent) return { ok: false, error: "agent participant is not connected" };
+  const response = await room.localParticipant.performRpc({
+    destinationIdentity: agent.identity,
+    method: "talqing.client.userdata_set",
+    payload: JSON.stringify(patch),
+    responseTimeout,
+  });
+  return JSON.parse(response || "{}") as { ok: boolean; error?: string };
+}
+
+/** Read the live session's userdata, or only the keys named.
+ *
+ *  Throws when the agent is not there, unlike `setTalqingUserdata`: a read that
+ *  returned nothing is not a state anything can render. */
+export async function getTalqingUserdata(
+  room: Room,
+  keys?: string[],
+  responseTimeout = 3,
+): Promise<JsonObject> {
+  const agent = talqingAgentParticipant(room);
+  if (!agent) throw new Error("agent participant is not connected");
+  const response = await room.localParticipant.performRpc({
+    destinationIdentity: agent.identity,
+    method: "talqing.client.userdata_get",
+    payload: JSON.stringify(keys ? { keys } : {}),
+    responseTimeout,
+  });
+  const parsed = JSON.parse(response || "{}") as JsonObject & { ok?: boolean; error?: string };
+  if (parsed.ok === false) {
+    throw new Error(String(parsed.error || "userdata RPC failed"));
+  }
+  return parsed;
+}