@minded-ai/mindedjs 1.0.52 → 1.0.53-patch-alpha

package/src/agent.ts

@@ -11,11 +11,11 @@ import { edgeFactory } from './edges/edgeFactory';
 import { AgentEventRequestPayloads, AgentEventResponsePayloads, AgentEvents } from './events/AgentEvents';
 import { z } from 'zod';
 import { MindedConnection } from './platform/mindedConnection';
-import { BaseMindedConnectionSocketMessage, MindedConnectionSocketMessageType, OnAppTrigger } from './platform/mindedConnectionTypes';
+import { BaseMindedConnectionSocketMessage, InvokeMessage, MindedConnectionSocketMessageType, OnAppTrigger } from './platform/mindedConnectionTypes';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
-import { FlowHistoryType, MindedSDKConfig, TriggerInvocationHistory } from './types/Agent.types';
+import { AgentInvokeParams, FlowHistoryType, MindedSDKConfig, TriggerInvocationHistory } from './types/Agent.types';
 import { createLlmInstance } from './llm/createLlmInstance';
 import { createCheckpointSaver } from './checkpointer/checkpointSaverFactory';
 import { getConfig } from './platform/config';
@@ -23,6 +23,8 @@ import { BaseMessage, HumanMessage } from '@langchain/core/messages';
 import triggerTypeToDefaultMessage from './triggers/triggerTypeToDefaultMessage';
 import appActionRunnerToolCreator from './internalTools/appActionRunnerTool';
 import { wait } from './utils/wait';
+import { VoiceSession } from './voice/voiceSession';
+import { BaseVoiceMessage, OnVoiceAudioOut } from './platform/mindedConnectionTypes';
 
 type CreateAgentParams<Memory> = {
   memorySchema: z.ZodSchema;
@@ -55,13 +57,14 @@ export class Agent {
   private flows!: Flow[];
   public tools!: Tool<any, any>[];
   private llm!: BaseLanguageModel;
-  private mindedConnection: MindedConnection | null = null;
+  public mindedConnection: MindedConnection | null = null;
   // Langgraph memory saver. In memory for local development, Custom for Platform
   private checkpointer!: BaseCheckpointSaver;
   // Langgraph compiled graph
-  private compiledGraph!: CompiledGraph;
+  public compiledGraph!: CompiledGraph;
   // Cache for secrets to avoid repeated API calls
   private secretsCache: Record<string, string> | null = null;
+  public config: MindedSDKConfig;
 
   // Event handlers storage keyed by event name. Handlers can optionally return a value.
   private eventHandlers: {
@@ -73,6 +76,9 @@ export class Agent {
   private initialized = false;
   private initPromise: Promise<void> | null = null;
 
+  // Add the voiceSessions property to the Agent class (place near other class fields)
+  public voiceSessions: Map<string, VoiceSession> = new Map();
+
   /**
    * Create a new Agent instance.
    *
@@ -108,6 +114,7 @@ export class Agent {
     const { memorySchema } = params;
     this.memorySchema = memorySchema;
     this.initPromise = this.init(params);
+    this.config = params.config;
   }
 
   private async init(params: CreateAgentParams<z.infer<typeof this.memorySchema>>): Promise<void> {
@@ -127,6 +134,17 @@ export class Agent {
             sessionId: trigger.sessionId,
           });
         });
+
+        this.mindedConnection.on(MindedConnectionSocketMessageType.INVOKE, async (message, callback) => {
+          const invokeMessage = message as InvokeMessage;
+          const result = await this.invoke({
+            triggerBody: invokeMessage.triggerBody,
+            triggerName: invokeMessage.triggerName,
+            appName: invokeMessage.appName,
+            sessionId: invokeMessage.sessionId,
+          });
+          callback(result);
+        });
       }
       const [, flows] = (await Promise.all([this.loadSecrets(), this.loadFlows(config.flows)])) as [Record<string, string>, Flow[]];
       this.flows = flows;
@@ -139,6 +157,10 @@ export class Agent {
       this.llm = createLlmInstance(config.llm);
       this.compiledGraph = this.initializeGraph();
       this.initialized = true;
+
+      if (params.config.voice) {
+        this.setupVoice();
+      }
     } catch (error) {
       this.initialized = false;
       throw error;
@@ -318,16 +340,11 @@ export class Agent {
     triggerName,
     sessionId,
     appName,
-  }: {
-    triggerBody: any;
-    triggerName: string;
-    sessionId?: string;
-    appName?: string;
-  }) {
+  }: AgentInvokeParams) {
     await this.waitForInitialization();
     let messages: Array<BaseMessage> = [];
     let memoryUpdate = {};
-    if (triggerName === KnownTriggerNames.DASHBOARD_MESSAGE) {
+    if (triggerName === KnownTriggerNames.DASHBOARD_MESSAGE || triggerName === KnownTriggerNames.VOICE_MESSAGE) {
       messages.push(new HumanMessage(triggerBody.content));
     } else {
       const results = await this.emit(AgentEvents.TRIGGER_EVENT, {
@@ -362,8 +379,8 @@ export class Agent {
       },
     ];
     console.log(`Invoking trigger ${triggerName} with session ${sessionId}`);
-    const config = { configurable: { thread_id: sessionId || uuidv4(), recursionLimit: 3 } };
-    const state = await this.compiledGraph.getState(config);
+    const langraphConfig = this.getLangraphConfig(sessionId || uuidv4());
+    const state = await this.compiledGraph.getState(langraphConfig);
     // Resume interruption
     if (state.tasks?.[0]?.interrupts?.length > 0) {
       console.log('Resuming interruption');
@@ -371,13 +388,13 @@ export class Agent {
         new Command({
           resume: { memory: memoryUpdate, messages, history, triggerInvocations: [triggerInvocation] },
         }),
-        config,
+        langraphConfig,
       );
       return res;
     } else {
       const res = await this.compiledGraph.invoke(
         { messages, memory: memoryUpdate, history, triggerInvocations: [triggerInvocation] },
-        config,
+        langraphConfig,
       );
       return res;
     }
@@ -597,4 +614,63 @@ export class Agent {
       throw new Error(`Failed to fetch secrets: ${error instanceof Error ? error.message : 'Unknown error'}`);
     }
   }
+
+  public getLangraphConfig(sessionId: string): { configurable: { thread_id: string; recursionLimit: number } } {
+    return { configurable: { thread_id: sessionId, recursionLimit: 3 } };
+  }
+
+  private setupVoice(): void {
+    if (!this.mindedConnection) {
+      throw new Error('Minded connection is required');
+    }
+
+    const connection = this.mindedConnection;
+    const { dashboardConnected } = getConfig();
+
+    if (dashboardConnected) {
+      // Listen for voice session start
+      connection.on(MindedConnectionSocketMessageType.DASHBOARD_VOICE_SESSION_START, async (message) => {
+        const sessionStart = message as BaseVoiceMessage;
+        await this.startVoiceSession({ sessionId: sessionStart.sessionId });
+      });
+
+      // Listen for incoming audio from the platform
+      connection.on(MindedConnectionSocketMessageType.DASHBOARD_VOICE_USER_AUDIO, (message) => {
+        const audioMessage = message as OnVoiceAudioOut;
+        const voiceSession = this.voiceSessions.get(audioMessage.sessionId);
+        if (voiceSession) {
+          voiceSession.sendAudio(audioMessage.audioData);
+        } else {
+          console.warn({ message: 'Voice session not found for sessionId', sessionId: audioMessage.sessionId });
+        }
+      });
+
+      // Hangup / end session handler
+      connection.on(MindedConnectionSocketMessageType.DASHBOARD_VOICE_SESSION_END, (message) => {
+        const hangup = message as BaseVoiceMessage;
+        const voiceSession = this.voiceSessions.get(hangup.sessionId);
+        if (voiceSession) {
+          voiceSession.hangup();
+        } else {
+          console.warn({ message: 'Voice session not found for sessionId', sessionId: hangup.sessionId });
+        }
+      });
+    }
+
+  }
+
+  private async startVoiceSession(params: { sessionId: string }): Promise<VoiceSession> {
+    if (!this.config.voice) {
+      throw new Error('Voice configuration is required');
+    }
+    const voiceSession = new VoiceSession({
+      agent: this,
+      sessionId: params.sessionId,
+      firstMessage: this.config.voice.firstMessage,
+      voiceId: this.config.voice.voiceId,
+    });
+    await voiceSession.init();
+    this.voiceSessions.set(params.sessionId, voiceSession);
+    return voiceSession;
+  }
 }

package/src/index.ts

@@ -1,6 +1,7 @@
 import { Agent } from './agent';
 import events from './events';
 
+export type { ElevenLabsContext } from './types/Voice.types';
 export { Agent, events };
 
 export type {
@@ -17,8 +18,11 @@ export type {
   JunctionNode,
   ToolNode,
   AppToolNode,
+  VoiceTriggerNode,
+  WebhookTriggerNode,
 } from './types/Flows.types';
 export { NodeType, TriggerType, EdgeType, AppNodeMetadata, AppNodeMetadataType, NodeMetadata, KnownTriggerNames } from './types/Flows.types';
 export type { Tool } from './types/Tools.types';
 export { FlowHistoryType, FlowHistory, TriggerInvocationHistory, AppActionInvocationHistory } from './types/Agent.types';
+export type { AgentInvokeParams } from './types/Agent.types';
 export type { Environment } from './types/Platform.types';

package/src/nodes/addPromptNode.ts

@@ -81,6 +81,7 @@ export const addPromptNode = async ({ graph, node, llm, tools, emit }: AddPrompt
         memory: state.memory,
         sessionId: configurable.thread_id,
       });
+      console.log('AI Message', result.content);
     }
 
     return {

package/src/platform/config.ts

@@ -1,7 +1,9 @@
 import { resolve } from 'path';
 import { config } from 'dotenv';
 import { Environment } from '../types/Platform.types';
-config({ path: resolve(__dirname, '../../.env') });
+const path = resolve(__dirname, '../../.env');
+console.log(`Loading config from ${path}`);
+config({ path });
 
 type MindedConfig = {
   baseUrl: string;
@@ -9,6 +11,9 @@ type MindedConfig = {
   token: string | null;
   runLocally: boolean;
   isDeployed: boolean;
+  dashboardConnected: boolean;
+  elevenLabsKey: string | null;
+  elevenLabsAgentId: string | null;
 };
 
 export const getConfig = (): MindedConfig => {
@@ -21,6 +26,9 @@ export const getConfig = (): MindedConfig => {
         token: process.env.MINDED_CONNECTION_TOKEN || '',
         runLocally: process.env.RUN_LOCALLY !== 'false',
         isDeployed: process.env.IS_DEPLOYED_AGENT === 'true',
+        dashboardConnected: false,
+        elevenLabsKey: process.env.ELEVEN_LABS_API_KEY || null,
+        elevenLabsAgentId: process.env.ELEVEN_LABS_AGENT_ID || null,
       };
     case 'development':
       return {
@@ -29,6 +37,9 @@ export const getConfig = (): MindedConfig => {
         token: process.env.MINDED_CONNECTION_TOKEN || '',
         runLocally: process.env.RUN_LOCALLY === 'true',
         isDeployed: process.env.IS_DEPLOYED_AGENT === 'true',
+        dashboardConnected: true,
+        elevenLabsKey: process.env.ELEVEN_LABS_API_KEY || null,
+        elevenLabsAgentId: process.env.ELEVEN_LABS_AGENT_ID || 'Iyr6DCOj80AdvVEVHSGt',
       };
     case 'sandbox-staging':
       return {
@@ -37,6 +48,9 @@ export const getConfig = (): MindedConfig => {
         token: process.env.MINDED_CONNECTION_TOKEN || '',
         runLocally: false,
         isDeployed: process.env.IS_DEPLOYED_AGENT === 'true',
+        elevenLabsKey: process.env.ELEVEN_LABS_API_KEY || null,
+        dashboardConnected: true,
+        elevenLabsAgentId: process.env.ELEVEN_LABS_AGENT_ID || 'agent_01jye194psezr909nwec27m2t9',
       };
     case 'sandbox':
       return {
@@ -45,6 +59,9 @@ export const getConfig = (): MindedConfig => {
         token: process.env.MINDED_CONNECTION_TOKEN || '',
         runLocally: false,
         isDeployed: process.env.IS_DEPLOYED_AGENT === 'true',
+        elevenLabsKey: process.env.ELEVEN_LABS_API_KEY || null,
+        dashboardConnected: true,
+        elevenLabsAgentId: process.env.ELEVEN_LABS_AGENT_ID || 'agent_01jye194psezr909nwec27m2t9',
       };
     case 'production':
       return {
@@ -53,6 +70,9 @@ export const getConfig = (): MindedConfig => {
         token: process.env.MINDED_CONNECTION_TOKEN || '',
         runLocally: false,
         isDeployed: process.env.IS_DEPLOYED_AGENT === 'true',
+        elevenLabsKey: process.env.ELEVEN_LABS_API_KEY || null,
+        dashboardConnected: false,
+        elevenLabsAgentId: process.env.ELEVEN_LABS_AGENT_ID || 'agent_01jye1ajkaf17axpcxg220qwcm',
       };
   }
 };

package/src/platform/mindedConnection.ts

@@ -1,26 +1,29 @@
 import { io, Socket } from 'socket.io-client';
-import { BaseMindedConnectionSocketMessage, MindedConnectionSocketMessageType } from './mindedConnectionTypes';
+import { BaseMindedConnectionSocketMessage, MindedConnectionSocketMessageType, MindedConnectionSocketMessageTypeMap } from './mindedConnectionTypes';
 import { stringify } from 'flatted';
 import { getConfig } from './config';
 
 export class MindedConnection {
   private socket: Socket | null = null;
   listeners: {
-    [key: string]: ((message: BaseMindedConnectionSocketMessage) => void)[];
+    [key: string]: ((message: BaseMindedConnectionSocketMessage, callback: (response: any) => void) => void)[];
   } = {};
 
   public get isConnected(): boolean {
     return this.socket?.connected ?? false;
   }
 
-  public on = (event: MindedConnectionSocketMessageType, callback: (message: BaseMindedConnectionSocketMessage) => void) => {
+  public on = (event: MindedConnectionSocketMessageType, callback: (message: BaseMindedConnectionSocketMessage, callback: (response: any) => void) => void) => {
     if (!this.listeners[event]) {
       this.listeners[event] = [];
     }
     this.listeners[event].push(callback);
   };
 
-  public emit = (event: MindedConnectionSocketMessageType, message: BaseMindedConnectionSocketMessage) => {
+  public emit = <E extends keyof MindedConnectionSocketMessageTypeMap>(
+    event: E,
+    message: MindedConnectionSocketMessageTypeMap[E]
+  ) => {
     if (this.socket) {
       this.socket.emit(event, message);
     }
@@ -34,7 +37,7 @@ export class MindedConnection {
     return new Promise((resolve, reject) => {
       // Set up timeout
       const timeout = setTimeout(() => {
-        reject(new Error(`Acknowledgement timeout after ${timeoutMs}ms`));
+        reject(new Error(`Acknowledgement timeout after ${timeoutMs}ms; Message: ${message}`));
       }, timeoutMs);
 
       // Emit with acknowledgement callback
@@ -70,8 +73,8 @@ export class MindedConnection {
       });
 
       this.socket.on('connect_error', () => {
-        console.error('Failed to connect to minded platform');
-        reject(new Error('Failed to connect to minded platform'));
+        console.error('Minded connection error');
+        reject(new Error('Minded connection error'));
       });
 
       this.socket.on('disconnect', () => {
@@ -96,12 +99,15 @@ export class MindedConnection {
       });
 
       // Listen for specific message types
-      this.socket.onAny((event, message) => {
+      this.socket.onAny((event, message, callback) => {
         if (this.listeners[event]) {
           this.listeners[event].forEach((listener) => {
-            listener(message);
+            listener(message, callback);
           });
         }
+        else {
+          console.warn({ message: 'No listeners found for event', event });
+        }
       });
 
       // Handle process termination

package/src/platform/mindedConnectionTypes.ts

@@ -7,16 +7,43 @@ import type {
   CheckpointTuple,
 } from '@langchain/langgraph-checkpoint';
 import type { RunnableConfig } from '@langchain/core/runnables';
+import { AgentInvokeParams } from '../types/Agent.types';
 
 export enum MindedConnectionSocketMessageType {
   OnAppTrigger = 'on-app-trigger',
   OnAppAction = 'on-app-action',
+  GET_SECRETS = 'get-secrets',
+  GET_FLOWS = 'get-flows',
+  INVOKE = 'invoke',
+  // Checkpoints
   CHECKPOINT_GET_TUPLE = 'checkpoint-get-tuple',
   CHECKPOINT_PUT = 'checkpoint-put',
   CHECKPOINT_LIST = 'checkpoint-list',
   CHECKPOINT_PUT_WRITES = 'checkpoint-put-writes',
-  GET_SECRETS = 'get-secrets',
-  GET_FLOWS = 'get-flows',
+  // Voice
+  DASHBOARD_VOICE_USER_AUDIO = 'dashboard-voice-user-audio',
+  DASHBOARD_VOICE_AGENT_AUDIO = 'dashboard-voice-agent-audio',
+  DASHBOARD_VOICE_SESSION_START = 'dashboard-voice-session-start',
+  DASHBOARD_VOICE_SESSION_END = 'dashboard-voice-session-end',
+  DASHBOARD_VOICE_INTERRUPTION = 'dashboard-voice-interruption',
+  DASHBOARD_VOICE_AGENT_RESPONSE_CORRECTION = 'dashboard-voice-agent-response-correction',
+}
+
+export type MindedConnectionSocketMessageTypeMap = {
+  [MindedConnectionSocketMessageType.OnAppTrigger]: OnAppTrigger;
+  [MindedConnectionSocketMessageType.OnAppAction]: BaseMindedConnectionSocketMessage;
+  [MindedConnectionSocketMessageType.GET_SECRETS]: BaseMindedConnectionSocketMessage;
+  [MindedConnectionSocketMessageType.GET_FLOWS]: BaseMindedConnectionSocketMessage;
+  [MindedConnectionSocketMessageType.INVOKE]: InvokeMessage;
+  [MindedConnectionSocketMessageType.CHECKPOINT_GET_TUPLE]: OnCheckpointGetTuple;
+  [MindedConnectionSocketMessageType.CHECKPOINT_PUT]: OnCheckpointPut;
+  [MindedConnectionSocketMessageType.CHECKPOINT_LIST]: OnCheckpointList;
+  [MindedConnectionSocketMessageType.CHECKPOINT_PUT_WRITES]: OnCheckpointPutWrites;
+  [MindedConnectionSocketMessageType.DASHBOARD_VOICE_USER_AUDIO]: OnVoiceAudioIn;
+  [MindedConnectionSocketMessageType.DASHBOARD_VOICE_AGENT_AUDIO]: OnVoiceAudioOut;
+  [MindedConnectionSocketMessageType.DASHBOARD_VOICE_SESSION_START]: BaseVoiceMessage;
+  [MindedConnectionSocketMessageType.DASHBOARD_VOICE_SESSION_END]: OnVoiceSessionEnd;
+  [MindedConnectionSocketMessageType.DASHBOARD_VOICE_INTERRUPTION]: OnVoiceInterruption;
 }
 
 export interface BaseMindedConnectionSocketMessage {
@@ -66,3 +93,40 @@ export interface OnCheckpointList extends BaseMindedConnectionSocketMessage {
 export interface OnCheckpointListResponse extends BaseSdkConnectionSocketMessageResponseCallbackAck {
   checkpoints?: CheckpointTuple[];
 }
+
+export interface BaseVoiceMessage extends BaseMindedConnectionSocketMessage {
+  sessionId: string;
+  timestamp: number;
+}
+
+// Voice/Audio event interfaces
+export interface OnVoiceAudioIn extends BaseVoiceMessage {
+  audioData: string; // base64 encoded audio data
+}
+
+export interface OnVoiceAudioOut extends BaseVoiceMessage {
+  audioData: string; // base64 encoded audio data
+}
+
+export interface OnVoiceMessageIn extends BaseVoiceMessage {
+  text: string;
+}
+
+export interface OnVoiceMessageOut extends BaseMindedConnectionSocketMessage {
+  sessionId: string;
+  text: string;
+  timestamp: number;
+}
+
+export interface OnVoiceInterruption extends BaseMindedConnectionSocketMessage {
+  sessionId: string;
+  timestamp: number;
+}
+export interface OnVoiceSessionEnd extends BaseMindedConnectionSocketMessage {
+  sessionId: string;
+  timestamp: number;
+}
+
+export interface InvokeMessage extends BaseMindedConnectionSocketMessage, AgentInvokeParams {
+  type: MindedConnectionSocketMessageType.INVOKE;
+}

package/src/types/Agent.types.ts

@@ -7,6 +7,24 @@ export type MindedSDKConfig = {
   flows: string[];
   llm: LLMConfig;
   tools: string[];
+  voice?: {
+    firstMessage: string;
+    voiceId?: string;
+  }
+}
+
+/**
+ * Parameters for the Agent invoke method
+ */
+export interface AgentInvokeParams {
+  /** The payload/data associated with the trigger */
+  triggerBody: any;
+  /** The name/type of the trigger being invoked */
+  triggerName: string;
+  /** Optional session identifier for conversation continuity */
+  sessionId?: string;
+  /** Optional name of the application triggering the agent in case of an app trigger */
+  appName?: string;
 }
 
 export enum FlowHistoryType {

package/src/types/Flows.types.ts

@@ -30,6 +30,7 @@ export enum TriggerType {
   APP = 'app',
   WEBHOOK = 'webhook',
   MANUAL = 'manual',
+  VOICE = 'voice',
 }
 
 export interface BaseTriggerNode extends BaseNode {
@@ -56,6 +57,14 @@ export interface WebhookTriggerNode extends BaseTriggerNode {
   triggerType: TriggerType.WEBHOOK;
 }
 
+export interface VoiceTriggerNode extends BaseTriggerNode {
+  triggerType: TriggerType.VOICE;
+  /**
+   * Text that will be spoken as the very first message in a voice interaction.
+   */
+  firstMessage: string;
+}
+
 export interface ManualTriggerNode extends BaseTriggerNode {
   triggerType: TriggerType.MANUAL;
 }
@@ -66,7 +75,7 @@ export interface PromptNode extends BaseNode {
   llmConfig?: LLMConfig;
 }
 
-export type TriggerNode = AppTriggerNode | WebhookTriggerNode | ManualTriggerNode;
+export type TriggerNode = AppTriggerNode | WebhookTriggerNode | ManualTriggerNode | VoiceTriggerNode;
 
 export interface JunctionNode extends BaseNode {
   type: NodeType.JUNCTION;
@@ -153,4 +162,5 @@ export interface Flow {
 export enum KnownTriggerNames {
   WEBHOOK = 'webhook',
   DASHBOARD_MESSAGE = 'dashboard_message',
+  VOICE_MESSAGE = 'voice_message',
 }

package/src/types/Voice.types.ts

@@ -0,0 +1,4 @@
+export type ElevenLabsContext = {
+  sessionId: string;
+  mindedToken: string;
+}

package/src/voice/elevenLabsUtils.ts

@@ -0,0 +1,101 @@
+/** ElevenLabs LLM proxy request body shape */
+export interface LLMRequestBody {
+  messages: Array<{
+    content: string;
+    role: string;
+    tool_call_id?: string;
+  }>;
+  model: string;
+  max_tokens: number;
+  stream: boolean;
+  temperature: number;
+  tools: null;
+}
+
+// ----------------- ElevenLabs WebSocket event types -----------------
+
+interface BaseEvent {
+  type: string;
+}
+
+interface UserTranscriptEvent extends BaseEvent {
+  type: 'user_transcript';
+  user_transcription_event: {
+    user_transcript: string;
+  };
+}
+
+interface AgentResponseEvent extends BaseEvent {
+  type: 'agent_response';
+  agent_response_event: {
+    agent_response: string;
+  };
+}
+
+interface AudioResponseEvent extends BaseEvent {
+  type: 'audio';
+  audio_event: {
+    audio_base_64: string;
+    event_id: number;
+  };
+}
+
+interface InterruptionEvent extends BaseEvent {
+  type: 'interruption';
+  interruption_event: {
+    event_id: number;
+  };
+}
+
+interface PingEvent extends BaseEvent {
+  type: 'ping';
+  ping_event: {
+    event_id: number;
+    ping_ms: number;
+  };
+}
+
+interface ConversationInitiationMetadataEvent extends BaseEvent {
+  type: 'conversation_initiation_metadata';
+  conversation_initiation_metadata_event: {
+    conversation_id: string;
+  };
+}
+
+export interface AgentResponseCorrectionEvent extends BaseEvent {
+  type: 'agent_response_correction';
+  agent_response_correction_event: {
+    corrected_agent_response: string;
+    original_agent_response: string;
+  };
+}
+
+/** Union of all possible WebSocket events we care about */
+export type ElevenLabsWebSocketEvent =
+  | UserTranscriptEvent
+  | AgentResponseEvent
+  | AudioResponseEvent
+  | InterruptionEvent
+  | PingEvent
+  | ConversationInitiationMetadataEvent
+  | AgentResponseCorrectionEvent;
+
+// ----------------- ElevenLabs Utility Functions -----------------
+
+/** Fetch signed URL from ElevenLabs API */
+export const getSignedUrl = async ({ agentId, apiKey }: { agentId: string; apiKey: string }): Promise<string> => {
+  const response = await fetch(
+    `https://api.elevenlabs.io/v1/convai/conversation/get_signed_url?agent_id=${agentId}`,
+    {
+      method: 'GET',
+      headers: {
+        'xi-api-key': apiKey,
+      },
+    },
+  );
+  if (!response.ok) {
+    throw new Error(`Failed to fetch signed url - status ${response.status}`);
+  }
+  const body = await response.json();
+  return body.signed_url;
+};