@kernl-sdk/protocol 0.3.1 → 0.4.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @kernl-sdk/protocol@0.3.1 build /home/runner/work/kernl/kernl/packages/protocol
+> @kernl-sdk/protocol@0.4.0 build /home/runner/work/kernl/kernl/packages/protocol
 > tsc && tsc-alias --resolve-full-paths
 

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @kernl/protocol
 
+## 0.4.0
+
+### Minor Changes
+
+- f593374: Add realtime voice agents with multi-provider support.
+  - `RealtimeAgent` and `RealtimeSession` for voice-enabled AI agents
+  - OpenAI GPT-4o realtime with WebSocket streaming
+  - xAI Grok realtime with OpenAI-compatible protocol
+  - React hooks: `useRealtime`, `useBrowserAudio`, `LiveWaveform`
+  - Ephemeral credential pattern for secure browser connections
+  - Tool execution with client-side context support
+
 ## 0.3.1
 
 ### Patch Changes

package/dist/constants.d.ts

@@ -58,4 +58,8 @@ export declare const ZOMBIE = "zombie";
  * Final cleanup in progress, about to be fully deleted.
  */
 export declare const DEAD = "dead";
+export declare const WS_CONNECTING = 0;
+export declare const WS_OPEN = 1;
+export declare const WS_CLOSING = 2;
+export declare const WS_CLOSED = 3;
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,SAAS,cAAc,CAAC;AACrC,eAAO,MAAM,MAAM,WAAW,CAAC;AAM/B;;;;GAIG;AACH,eAAO,MAAM,OAAO,YAAY,CAAC;AAEjC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAE7C;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,oBAAoB,CAAC;AAEjD;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,YAAY,CAAC;AAEjC;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,WAAW,CAAC;AAE/B;;;GAGG;AACH,eAAO,MAAM,IAAI,SAAS,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,SAAS,cAAc,CAAC;AACrC,eAAO,MAAM,MAAM,WAAW,CAAC;AAM/B;;;;GAIG;AACH,eAAO,MAAM,OAAO,YAAY,CAAC;AAEjC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAE7C;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,oBAAoB,CAAC;AAEjD;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,YAAY,CAAC;AAEjC;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,WAAW,CAAC;AAE/B;;;GAGG;AACH,eAAO,MAAM,IAAI,SAAS,CAAC;AAM3B,eAAO,MAAM,aAAa,IAAI,CAAC;AAC/B,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,UAAU,IAAI,CAAC;AAC5B,eAAO,MAAM,SAAS,IAAI,CAAC"}

package/dist/constants.js

@@ -64,3 +64,10 @@ export const ZOMBIE = "zombie";
  * Final cleanup in progress, about to be fully deleted.
  */
 export const DEAD = "dead";
+// ----------------------------
+// WebSocket ready states
+// ----------------------------
+export const WS_CONNECTING = 0;
+export const WS_OPEN = 1;
+export const WS_CLOSING = 2;
+export const WS_CLOSED = 3;

package/dist/realtime/model.d.ts

@@ -1,6 +1,16 @@
+import { TypedEmitter } from "@kernl-sdk/shared";
 import { SharedProviderMetadata } from "../provider/index.js";
 import { RealtimeClientEvent, RealtimeServerEvent } from "./events.js";
-import { RealtimeConnectOptions, TransportStatus } from "./types.js";
+import { RealtimeConnectOptions, RealtimeAuthenticateOptions, TransportStatus, ClientCredential } from "./types.js";
+/**
+ * Events emitted by a realtime connection.
+ */
+export type RealtimeConnectionEvents = {
+    event: [event: RealtimeServerEvent];
+    status: [status: TransportStatus];
+    error: [error: Error];
+    interrupted: [];
+};
 /**
  * A realtime model that can establish bidirectional streaming connections.
  *
@@ -24,13 +34,22 @@ export interface RealtimeModel {
      * Establish a connection and return a connection instance.
      */
     connect(options?: RealtimeConnectOptions): Promise<RealtimeConnection>;
+    /**
+     * Create ephemeral credential for client-side connections.
+     *
+     * Call server-side where API key is available, pass result to client.
+     * Client then uses credential in connect() options.
+     *
+     * @param options - Provider-specific options (e.g., agentId for ElevenLabs)
+     */
+    authenticate(options?: RealtimeAuthenticateOptions): Promise<ClientCredential>;
 }
 /**
  * An active bidirectional connection to a realtime model.
  *
  * One connection per session. Providers implement this interface.
  */
-export interface RealtimeConnection {
+export interface RealtimeConnection extends TypedEmitter<RealtimeConnectionEvents> {
     /**
      * Current connection status.
      */
@@ -69,15 +88,6 @@ export interface RealtimeConnection {
      * Convenience for sending response.cancel event.
      */
     interrupt(): void;
-    on(event: "event", listener: (event: RealtimeServerEvent) => void): this;
-    on(event: "status", listener: (status: TransportStatus) => void): this;
-    on(event: "error", listener: (error: Error) => void): this;
-    off(event: "event", listener: (event: RealtimeServerEvent) => void): this;
-    off(event: "status", listener: (status: TransportStatus) => void): this;
-    off(event: "error", listener: (error: Error) => void): this;
-    once(event: "event", listener: (event: RealtimeServerEvent) => void): this;
-    once(event: "status", listener: (status: TransportStatus) => void): this;
-    once(event: "error", listener: (error: Error) => void): this;
 }
 /**
  * A transport factory for custom connection mechanisms (e.g., WebRTC).

package/dist/realtime/model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/realtime/model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAElE;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACxE;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IAEjC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAE/B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAElC;;OAEG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;IAEnD;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAEvC;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;OAEG;IACH,IAAI,IAAI,IAAI,CAAC;IAEb;;OAEG;IACH,MAAM,IAAI,IAAI,CAAC;IAEf;;;OAGG;IACH,SAAS,IAAI,IAAI,CAAC;IAIlB,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GAAG,IAAI,CAAC;IACzE,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,GAAG,IAAI,CAAC;IACvE,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;IAE3D,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GAAG,IAAI,CAAC;IAC1E,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,GAAG,IAAI,CAAC;IACxE,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;IAE5D,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GAAG,IAAI,CAAC;IAC3E,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,GAAG,IAAI,CAAC;IACzE,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;CAC9D;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAE/B;;OAEG;IACH,OAAO,CACL,KAAK,EAAE,aAAa,EACpB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAChC"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/realtime/model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpE,OAAO,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,eAAe,EACf,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,KAAK,EAAE,CAAC,KAAK,EAAE,mBAAmB,CAAC,CAAC;IACpC,MAAM,EAAE,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAClC,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACtB,WAAW,EAAE,EAAE,CAAC;CACjB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAEvE;;;;;;;OAOG;IACH,YAAY,CACV,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBACf,SAAQ,YAAY,CAAC,wBAAwB,CAAC;IAC9C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IAEjC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAE/B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAElC;;OAEG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;IAEnD;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAEvC;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;OAEG;IACH,IAAI,IAAI,IAAI,CAAC;IAEb;;OAEG;IACH,MAAM,IAAI,IAAI,CAAC;IAEf;;;OAGG;IACH,SAAS,IAAI,IAAI,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAE/B;;OAEG;IACH,OAAO,CACL,KAAK,EAAE,aAAa,EACpB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAChC"}

package/dist/realtime/types.d.ts

@@ -1,5 +1,37 @@
+import { TypedEmitter } from "@kernl-sdk/shared";
 import { SharedProviderOptions } from "../provider/index.js";
 import { LanguageModelTool } from "../language-model/index.js";
+/**
+ * Events emitted by a realtime channel.
+ */
+export type RealtimeChannelEvents = {
+    audio: [audio: string];
+    commit: [];
+    interrupt: [];
+};
+/**
+ * Base interface for audio I/O channels.
+ *
+ * Channels bridge between audio sources (browser mic, Twilio, Discord)
+ * and the realtime session. They handle audio capture/playback and emit
+ * events that the session listens to.
+ */
+export interface RealtimeChannel extends TypedEmitter<RealtimeChannelEvents> {
+    /**
+     * Send audio to be played/transmitted by the channel.
+     * Called by session when audio is received from the model.
+     */
+    sendAudio(audio: string): void;
+    /**
+     * Interrupt current audio playback.
+     * Called by session when response is cancelled.
+     */
+    interrupt(): void;
+    /**
+     * Clean up resources and close the channel.
+     */
+    close(): void;
+}
 export interface RealtimeConnectOptions {
     /**
      * Initial session configuration.
@@ -17,6 +49,51 @@ export interface RealtimeConnectOptions {
      * Provider-specific options.
      */
     providerOptions?: SharedProviderOptions;
+    /**
+     * Ephemeral credential for client-side connections.
+     *
+     * Obtained from model.authenticate() on the server.
+     * When provided, used instead of the model's API key.
+     */
+    credential?: ClientCredential;
+    /**
+     * WebSocket constructor for browser/Node compatibility.
+     *
+     * Defaults to globalThis.WebSocket (available in browsers and Node 22+).
+     * For Node.js <22, provide the 'ws' package.
+     *
+     * @example
+     * ```ts
+     * import WebSocket from 'ws';
+     * await model.connect({ websocket: WebSocket });
+     * ```
+     */
+    websocket?: WebSocketConstructor;
+}
+/**
+ * Options for authenticating with a realtime provider.
+ *
+ * Provider-specific options can be added via extension.
+ */
+export interface RealtimeAuthenticateOptions {
+    /**
+     * Agent ID for providers that use pre-configured agents (e.g., ElevenLabs).
+     */
+    agentId?: string;
+}
+/**
+ * WebSocket constructor type for cross-platform compatibility.
+ */
+export type WebSocketConstructor = new (url: string | URL, protocols?: string | string[]) => WebSocketLike;
+/**
+ * Minimal WebSocket interface matching the standard WebSocket API.
+ */
+export interface WebSocketLike {
+    readonly readyState: number;
+    send(data: string | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: string, listener: (event: unknown) => void): void;
+    removeEventListener(type: string, listener: (event: unknown) => void): void;
 }
 /**
  * Configuration for a realtime session.
@@ -187,19 +264,10 @@ export interface RealtimeSession {
 /**
  * Error from a realtime session.
  */
-export interface RealtimeError {
-    /**
-     * Error code.
-     */
-    code: string;
-    /**
-     * Human-readable error message.
-     */
-    message: string;
-    /**
-     * Additional error details.
-     */
-    details?: Record<string, unknown>;
+export declare class RealtimeError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
 }
 /**
  * Token usage information for a response.
@@ -226,4 +294,21 @@ export type ResponseStatus = "completed" | "interrupted" | "cancelled" | "failed
  * Status of a realtime transport connection.
  */
 export type TransportStatus = "disconnected" | "connecting" | "connected" | "reconnecting" | "closed";
+/**
+ * A client credential for browser-based realtime connections.
+ *
+ * Created server-side via model.authenticate(), passed to client
+ * for secure connection without exposing API keys.
+ */
+export type ClientCredential = {
+    /** Ephemeral token for auth header (OpenAI style). */
+    readonly kind: "token";
+    token: string;
+    expiresAt: Date;
+} | {
+    /** Signed URL to connect directly (ElevenLabs style). */
+    readonly kind: "url";
+    url: string;
+    expiresAt: Date;
+};
 //# sourceMappingURL=types.d.ts.map

package/dist/realtime/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/realtime/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/realtime/types.ts"],"names":[],"mappings":"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"}

package/dist/realtime/types.js

@@ -1 +1,13 @@
-export {};
+/**
+ * Error from a realtime session.
+ */
+export class RealtimeError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "RealtimeError";
+        this.code = code;
+        this.details = details;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernl-sdk/protocol",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Protocol specification for kernl",
   "keywords": [
     "kernl",

package/src/constants.ts

@@ -73,3 +73,12 @@ export const ZOMBIE = "zombie";
  * Final cleanup in progress, about to be fully deleted.
  */
 export const DEAD = "dead";
+
+// ----------------------------
+// WebSocket ready states
+// ----------------------------
+
+export const WS_CONNECTING = 0;
+export const WS_OPEN = 1;
+export const WS_CLOSING = 2;
+export const WS_CLOSED = 3;

package/src/realtime/model.ts

@@ -1,6 +1,23 @@
+import { TypedEmitter } from "@kernl-sdk/shared";
+
 import { SharedProviderMetadata } from "@/provider";
 import { RealtimeClientEvent, RealtimeServerEvent } from "./events";
-import { RealtimeConnectOptions, TransportStatus } from "./types";
+import {
+  RealtimeConnectOptions,
+  RealtimeAuthenticateOptions,
+  TransportStatus,
+  ClientCredential,
+} from "./types";
+
+/**
+ * Events emitted by a realtime connection.
+ */
+export type RealtimeConnectionEvents = {
+  event: [event: RealtimeServerEvent];
+  status: [status: TransportStatus];
+  error: [error: Error];
+  interrupted: [];
+};
 
 /**
  * A realtime model that can establish bidirectional streaming connections.
@@ -28,6 +45,18 @@ export interface RealtimeModel {
    * Establish a connection and return a connection instance.
    */
   connect(options?: RealtimeConnectOptions): Promise<RealtimeConnection>;
+
+  /**
+   * Create ephemeral credential for client-side connections.
+   *
+   * Call server-side where API key is available, pass result to client.
+   * Client then uses credential in connect() options.
+   *
+   * @param options - Provider-specific options (e.g., agentId for ElevenLabs)
+   */
+  authenticate(
+    options?: RealtimeAuthenticateOptions,
+  ): Promise<ClientCredential>;
 }
 
 /**
@@ -35,7 +64,8 @@ export interface RealtimeModel {
  *
  * One connection per session. Providers implement this interface.
  */
-export interface RealtimeConnection {
+export interface RealtimeConnection
+  extends TypedEmitter<RealtimeConnectionEvents> {
   /**
    * Current connection status.
    */
@@ -82,20 +112,6 @@ export interface RealtimeConnection {
    * Convenience for sending response.cancel event.
    */
   interrupt(): void;
-
-  // --- event subscription ---
-
-  on(event: "event", listener: (event: RealtimeServerEvent) => void): this;
-  on(event: "status", listener: (status: TransportStatus) => void): this;
-  on(event: "error", listener: (error: Error) => void): this;
-
-  off(event: "event", listener: (event: RealtimeServerEvent) => void): this;
-  off(event: "status", listener: (status: TransportStatus) => void): this;
-  off(event: "error", listener: (error: Error) => void): this;
-
-  once(event: "event", listener: (event: RealtimeServerEvent) => void): this;
-  once(event: "status", listener: (status: TransportStatus) => void): this;
-  once(event: "error", listener: (error: Error) => void): this;
 }
 
 /**

package/src/realtime/types.ts

@@ -1,6 +1,42 @@
+import { TypedEmitter } from "@kernl-sdk/shared";
 import { SharedProviderOptions } from "@/provider";
 import { LanguageModelTool } from "@/language-model";
 
+/**
+ * Events emitted by a realtime channel.
+ */
+export type RealtimeChannelEvents = {
+  audio: [audio: string];
+  commit: [];
+  interrupt: [];
+};
+
+/**
+ * Base interface for audio I/O channels.
+ *
+ * Channels bridge between audio sources (browser mic, Twilio, Discord)
+ * and the realtime session. They handle audio capture/playback and emit
+ * events that the session listens to.
+ */
+export interface RealtimeChannel extends TypedEmitter<RealtimeChannelEvents> {
+  /**
+   * Send audio to be played/transmitted by the channel.
+   * Called by session when audio is received from the model.
+   */
+  sendAudio(audio: string): void;
+
+  /**
+   * Interrupt current audio playback.
+   * Called by session when response is cancelled.
+   */
+  interrupt(): void;
+
+  /**
+   * Clean up resources and close the channel.
+   */
+  close(): void;
+}
+
 export interface RealtimeConnectOptions {
   /**
    * Initial session configuration.
@@ -21,6 +57,59 @@ export interface RealtimeConnectOptions {
    * Provider-specific options.
    */
   providerOptions?: SharedProviderOptions;
+
+  /**
+   * Ephemeral credential for client-side connections.
+   *
+   * Obtained from model.authenticate() on the server.
+   * When provided, used instead of the model's API key.
+   */
+  credential?: ClientCredential;
+
+  /**
+   * WebSocket constructor for browser/Node compatibility.
+   *
+   * Defaults to globalThis.WebSocket (available in browsers and Node 22+).
+   * For Node.js <22, provide the 'ws' package.
+   *
+   * @example
+   * ```ts
+   * import WebSocket from 'ws';
+   * await model.connect({ websocket: WebSocket });
+   * ```
+   */
+  websocket?: WebSocketConstructor;
+}
+
+/**
+ * Options for authenticating with a realtime provider.
+ *
+ * Provider-specific options can be added via extension.
+ */
+export interface RealtimeAuthenticateOptions {
+  /**
+   * Agent ID for providers that use pre-configured agents (e.g., ElevenLabs).
+   */
+  agentId?: string;
+}
+
+/**
+ * WebSocket constructor type for cross-platform compatibility.
+ */
+export type WebSocketConstructor = new (
+  url: string | URL,
+  protocols?: string | string[],
+) => WebSocketLike;
+
+/**
+ * Minimal WebSocket interface matching the standard WebSocket API.
+ */
+export interface WebSocketLike {
+  readonly readyState: number;
+  send(data: string | ArrayBuffer): void;
+  close(code?: number, reason?: string): void;
+  addEventListener(type: string, listener: (event: unknown) => void): void;
+  removeEventListener(type: string, listener: (event: unknown) => void): void;
 }
 
 /**
@@ -219,21 +308,16 @@ export interface RealtimeSession {
 /**
  * Error from a realtime session.
  */
-export interface RealtimeError {
-  /**
-   * Error code.
-   */
-  code: string;
-
-  /**
-   * Human-readable error message.
-   */
-  message: string;
-
-  /**
-   * Additional error details.
-   */
-  details?: Record<string, unknown>;
+export class RealtimeError extends Error {
+  readonly code: string;
+  readonly details?: Record<string, unknown>;
+
+  constructor(code: string, message: string, details?: Record<string, unknown>) {
+    super(message);
+    this.name = "RealtimeError";
+    this.code = code;
+    this.details = details;
+  }
 }
 
 /**
@@ -274,3 +358,24 @@ export type TransportStatus =
   | "connected"
   | "reconnecting"
   | "closed";
+
+/**
+ * A client credential for browser-based realtime connections.
+ *
+ * Created server-side via model.authenticate(), passed to client
+ * for secure connection without exposing API keys.
+ */
+export type ClientCredential =
+  | {
+      /** Ephemeral token for auth header (OpenAI style). */
+      readonly kind: "token";
+      token: string;
+      expiresAt: Date;
+    }
+  | {
+      /** Signed URL to connect directly (ElevenLabs style). */
+      readonly kind: "url";
+      url: string;
+      expiresAt: Date;
+    };
+