@hamsa-ai/voice-agents-sdk 0.5.8 → 0.6.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hamsa-ai/voice-agents-sdk",
-  "version": "0.5.8",
+  "version": "0.6.0-beta.1",
   "description": "Hamsa AI - Voice Agents JavaScript SDK",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
@@ -56,7 +56,7 @@
   "dependencies": {
     "events": "^3.3.0",
     "jwt-decode": "^4.0.0",
-    "livekit-client": "^2.18.0"
+    "livekit-client": "^2.20.0"
   },
   "repository": {
     "type": "git",

package/types/classes/livekit-connection.d.ts

@@ -190,6 +190,8 @@ export declare class LiveKitConnection extends EventEmitter {
     private hasEmittedConnected;
     /** Debug logger instance for conditional logging */
     private readonly logger;
+    /** When true, the session is text/chat-only and the microphone is never enabled */
+    private readonly isChatOnly;
     /**
      * Creates a new LiveKitConnection instance
      *
@@ -200,6 +202,7 @@ export declare class LiveKitConnection extends EventEmitter {
      * @param lkUrl - LiveKit WebSocket URL (e.g., 'wss://livekit.example.com')
      * @param accessToken - JWT token for room authentication and authorization
      * @param debug - Enable debug logging (defaults to false)
+     * @param isChatOnly - When true, the microphone is never enabled (text/chat-only session)
      *
      * @example
      * ```typescript
@@ -213,7 +216,7 @@ export declare class LiveKitConnection extends EventEmitter {
      * await connection.connect();
      * ```
      */
-    constructor(lkUrl: string, accessToken: string, debug?: boolean);
+    constructor(lkUrl: string, accessToken: string, debug?: boolean, isChatOnly?: boolean);
     /**
      * Provides access to the underlying LiveKit room instance
      *

package/types/classes/livekit-manager.d.ts

@@ -90,9 +90,10 @@ export default class LiveKitManager extends EventEmitter {
      * );
      * ```
      */
-    constructor(lkUrl: string, accessToken: string, tools?: Tool[], { debug, avatarContainerSelector, }?: {
+    constructor(lkUrl: string, accessToken: string, tools?: Tool[], { debug, avatarContainerSelector, isChatOnly, }?: {
         debug?: boolean;
         avatarContainerSelector?: string;
+        isChatOnly?: boolean;
     });
     /**
      * Establishes connection to the LiveKit room and initializes voice agent communication

package/types/classes/livekit-tool-registry.d.ts

@@ -199,6 +199,8 @@ export declare class LiveKitToolRegistry extends EventEmitter {
     private readonly registeredMethods;
     /** Debug logger instance for conditional logging */
     private readonly logger;
+    /** Monotonic counter for synthesizing message ids when a segment lacks one */
+    private fallbackMessageIdCounter;
     /**
      * Creates a new LiveKitToolRegistry instance
      *
@@ -463,9 +465,17 @@ export declare class LiveKitToolRegistry extends EventEmitter {
      * ```
      */
     handleTranscriptionReceived(transcriptions: Array<{
+        id?: string;
         text?: string;
         final?: boolean;
     }>, participantIdentity?: string): void;
+    /**
+     * Emits a structured, streaming-aware `messageReceived` event.
+     *
+     * Synthesizes a stable id when the source segment lacks one so consumers can
+     * still key the message, and stamps the observation time.
+     */
+    private emitMessageReceived;
     /**
      * Returns the count of currently registered tools
      *

package/types/classes/types.d.ts

@@ -7,6 +7,31 @@ import type { ConnectionQuality, Track, TrackPublication } from 'livekit-client'
  * Represents the current state of the voice agent
  */
 export type AgentState = 'idle' | 'initializing' | 'listening' | 'thinking' | 'speaking';
+/** Identifies who authored a conversation message. */
+export type MessageRole = 'user' | 'agent';
+/**
+ * A structured conversation message surfaced to chat UIs.
+ *
+ * Emitted via the `messageReceived` event for both agent replies and user
+ * transcriptions. Unlike the plain-string `answerReceived`/`transcriptionReceived`
+ * events, this carries the metadata a streaming chat UI needs:
+ * - `id` is stable across a message's streaming updates, so the UI can update the
+ *   same bubble in place instead of appending a new one for each partial.
+ * - `isFinal` distinguishes a streaming partial (`false`) from the completed
+ *   message (`true`).
+ */
+export type ReceivedMessage = {
+    /** Stable id for this message; identical across streaming updates of the same message. */
+    id: string;
+    /** Who authored the message. */
+    role: MessageRole;
+    /** The message text. For streaming segments this is the full text received so far. */
+    text: string;
+    /** True for the completed message, false for an in-progress streaming partial. */
+    isFinal: boolean;
+    /** Unix epoch milliseconds when the SDK observed this update. */
+    timestamp: number;
+};
 /**
  * Function signature for client-side tools that can be executed by the agent.
  * Tools can be synchronous or asynchronous and accept variable arguments.

package/types/main.d.ts

@@ -2,11 +2,11 @@ import { EventEmitter } from 'events';
 import type { ConnectionState, LocalTrack, LocalTrackPublication, Participant, RemoteParticipant, RemoteTrack, Room } from 'livekit-client';
 import LiveKitManager, { type AgentState, type AudioLevelsResult, type CallAnalyticsResult, type ConnectionStatsResult, type ParticipantData, type PerformanceMetricsResult, type TrackStatsResult } from './classes/livekit-manager';
 import ScreenWakeLock from './classes/screen-wake-lock';
-import type { AudioCaptureCallback, AudioCaptureOptions, ConnectionQualityData, DTMFDigit, TrackSubscriptionData, TrackUnsubscriptionData } from './classes/types';
+import type { AudioCaptureCallback, AudioCaptureOptions, ConnectionQualityData, DTMFDigit, ReceivedMessage, TrackSubscriptionData, TrackUnsubscriptionData } from './classes/types';
 export type { RpcInvocationData } from 'livekit-client';
 export { RpcError } from 'livekit-client';
 export type { AgentState } from './classes/livekit-manager';
-export type { AudioCaptureCallback, AudioCaptureFormat, AudioCaptureMetadata, AudioCaptureOptions, AudioCaptureSource, DTMFDigit, } from './classes/types';
+export type { AudioCaptureCallback, AudioCaptureFormat, AudioCaptureMetadata, AudioCaptureOptions, AudioCaptureSource, DTMFDigit, MessageRole, ReceivedMessage, } from './classes/types';
 /**
  * Custom error class that includes both human-readable message and machine-readable messageKey
  * for internationalization and programmatic error handling
@@ -63,6 +63,12 @@ type StartOptions = {
     params?: Record<string, unknown>;
     /** Whether to enable voice interactions. If false, agent runs in text-only mode */
     voiceEnablement?: boolean;
+    /**
+     * Whether the conversation runs in chat-only mode (no audio media).
+     * When true, the SDK requests a chat-only session from the backend via the
+     * participant-token and conversation-init endpoints.
+     */
+    isChatOnly?: boolean;
     /** Array of client-side tools that the agent can call during conversations */
     tools?: Tool[];
     /** Optional user identifier for tracking and analytics */
@@ -205,6 +211,13 @@ type HamsaVoiceAgentEvents = {
     transcriptionReceived: (text: string) => void;
     /** Emitted when agent response is received */
     answerReceived: (text: string) => void;
+    /**
+     * Emitted for every conversation message (agent reply or user transcription)
+     * with structured, streaming-aware metadata (id, role, isFinal, timestamp).
+     * Use this to drive a chat UI; prefer it over the plain-string
+     * `answerReceived`/`transcriptionReceived` events when rendering message bubbles.
+     */
+    messageReceived: (message: ReceivedMessage) => void;
     /** Emitted when agent starts speaking */
     speaking: () => void;
     /** Emitted when agent is listening */
@@ -213,6 +226,8 @@ type HamsaVoiceAgentEvents = {
     agentStateChanged: (state: AgentState) => void;
     /** Emitted when a DTMF digit is successfully sent */
     dtmfSent: (digit: DTMFDigit) => void;
+    /** Emitted when a chat message is successfully sent to the agent */
+    messageSent: (text: string) => void;
     /** Emitted when an error occurs */
     error: (error: Error | HamsaApiError) => void;
     /** Emitted when a remote track is subscribed */
@@ -647,6 +662,37 @@ declare class HamsaVoiceAgent extends EventEmitter {
      * ```
      */
     sendDTMF(digit: DTMFDigit): void;
+    /**
+     * Sends a text chat message to the agent
+     *
+     * Publishes the user's typed message to the agent over LiveKit's text-stream
+     * channel ({@link LIVEKIT_CHAT_TOPIC}). Use this to drive a text/chat UI,
+     * typically alongside a chat-only session started with `start({ isChatOnly: true })`.
+     *
+     * The agent's reply arrives asynchronously through the `answerReceived` event.
+     * This method does not return the reply.
+     *
+     * @param text - The message to send. Must be a non-empty string.
+     * @throws {Error} If called when not connected (no active session)
+     * @throws {Error} If `text` is empty or not a string
+     * @fires messageSent When the message is successfully sent to the agent
+     *
+     * @example
+     * ```typescript
+     * await agent.start({ agentId: 'support_agent', isChatOnly: true });
+     *
+     * // Render the agent's replies
+     * agent.on('answerReceived', (reply) => appendToChat('agent', reply));
+     *
+     * // Send the user's typed message
+     * sendButton.onclick = async () => {
+     *   const text = input.value;
+     *   appendToChat('user', text);
+     *   await agent.sendMessage(text);
+     * };
+     * ```
+     */
+    sendMessage(text: string): Promise<void>;
     /**
      * Gets frequency data from the user's microphone input
      *
@@ -890,7 +936,7 @@ declare class HamsaVoiceAgent extends EventEmitter {
      * await agent.start({ agentId: 'my_agent', voiceEnablement: true });
      * ```
      */
-    start({ agentId, params, voiceEnablement, tools, userId: _userId, preferHeadphonesForIosDevices: _preferHeadphonesForIosDevices, connectionDelay: _connectionDelay, disableWakeLock: _disableWakeLock, onAudioData, captureAudio, avatarContainerSelector, }: StartOptions): Promise<void>;
+    start({ agentId, params, voiceEnablement, isChatOnly, tools, userId: _userId, preferHeadphonesForIosDevices: _preferHeadphonesForIosDevices, connectionDelay: _connectionDelay, disableWakeLock: _disableWakeLock, onAudioData, captureAudio, avatarContainerSelector, }: StartOptions): Promise<void>;
     /**
      * Terminates the current voice agent conversation
      *