feat(mixer): enhance mixer functionality with interaction and tool legs

- Updated mixer to handle participant and isolated leg roles, allowing for IVR and consent interactions.
- Introduced commands for starting and canceling interactions, managing tool legs for recording and transcription.
- Implemented per-source audio handling for tool legs, enabling separate audio processing.
- Enhanced DTMF handling to forward events between participant legs only.
- Added support for PCM recording directly from tool legs, with WAV file generation.
- Updated TypeScript definitions and functions to support new interaction and tool leg features.

ts/proxybridge.ts

@@ -41,6 +41,32 @@ type TProxyCommands = {
     params: { call_id: string };
     result: { file_path: string; duration_ms: number };
   };
+  start_interaction: {
+    params: {
+      call_id: string;
+      leg_id: string;
+      prompt_wav: string;
+      expected_digits: string;
+      timeout_ms: number;
+    };
+    result: { result: 'digit' | 'timeout' | 'cancelled'; digit?: string };
+  };
+  add_tool_leg: {
+    params: {
+      call_id: string;
+      tool_type: 'recording' | 'transcription';
+      config?: Record<string, unknown>;
+    };
+    result: { tool_leg_id: string };
+  };
+  remove_tool_leg: {
+    params: { call_id: string; tool_leg_id: string };
+    result: Record<string, never>;
+  };
+  set_leg_metadata: {
+    params: { call_id: string; leg_id: string; key: string; value: unknown };
+    result: Record<string, never>;
+  };
 };
 
 // ---------------------------------------------------------------------------
@@ -280,11 +306,107 @@ export async function webrtcClose(sessionId: string): Promise<void> {
   } catch { /* ignore */ }
 }
 
+// ---------------------------------------------------------------------------
+// Leg interaction & tool leg commands
+// ---------------------------------------------------------------------------
+
+/**
+ * Start an interaction on a specific leg — isolate it, play a prompt, collect DTMF.
+ * Blocks until the interaction completes (digit pressed, timeout, or cancelled).
+ */
+export async function startInteraction(
+  callId: string,
+  legId: string,
+  promptWav: string,
+  expectedDigits: string,
+  timeoutMs: number,
+): Promise<{ result: 'digit' | 'timeout' | 'cancelled'; digit?: string } | null> {
+  if (!bridge || !initialized) return null;
+  try {
+    const result = await bridge.sendCommand('start_interaction', {
+      call_id: callId,
+      leg_id: legId,
+      prompt_wav: promptWav,
+      expected_digits: expectedDigits,
+      timeout_ms: timeoutMs,
+    } as any);
+    return result as any;
+  } catch (e: any) {
+    logFn?.(`[proxy-engine] start_interaction error: ${e?.message || e}`);
+    return null;
+  }
+}
+
+/**
+ * Add a tool leg (recording or transcription) to a call.
+ * Tool legs receive per-source unmerged audio from all participants.
+ */
+export async function addToolLeg(
+  callId: string,
+  toolType: 'recording' | 'transcription',
+  config?: Record<string, unknown>,
+): Promise<string | null> {
+  if (!bridge || !initialized) return null;
+  try {
+    const result = await bridge.sendCommand('add_tool_leg', {
+      call_id: callId,
+      tool_type: toolType,
+      config,
+    } as any);
+    return (result as any)?.tool_leg_id || null;
+  } catch (e: any) {
+    logFn?.(`[proxy-engine] add_tool_leg error: ${e?.message || e}`);
+    return null;
+  }
+}
+
+/**
+ * Remove a tool leg from a call. Triggers finalization (WAV files, metadata).
+ */
+export async function removeToolLeg(callId: string, toolLegId: string): Promise<boolean> {
+  if (!bridge || !initialized) return false;
+  try {
+    await bridge.sendCommand('remove_tool_leg', {
+      call_id: callId,
+      tool_leg_id: toolLegId,
+    } as any);
+    return true;
+  } catch (e: any) {
+    logFn?.(`[proxy-engine] remove_tool_leg error: ${e?.message || e}`);
+    return false;
+  }
+}
+
+/**
+ * Set a metadata key-value pair on a leg.
+ */
+export async function setLegMetadata(
+  callId: string,
+  legId: string,
+  key: string,
+  value: unknown,
+): Promise<boolean> {
+  if (!bridge || !initialized) return false;
+  try {
+    await bridge.sendCommand('set_leg_metadata', {
+      call_id: callId,
+      leg_id: legId,
+      key,
+      value,
+    } as any);
+    return true;
+  } catch (e: any) {
+    logFn?.(`[proxy-engine] set_leg_metadata error: ${e?.message || e}`);
+    return false;
+  }
+}
+
 /**
  * Subscribe to an event from the proxy engine.
  * Event names: incoming_call, outbound_device_call, call_ringing,
  * call_answered, call_ended, provider_registered, device_registered,
- * dtmf_digit, recording_done, sip_unhandled
+ * dtmf_digit, recording_done, tool_recording_done, tool_transcription_done,
+ * leg_added, leg_removed, sip_unhandled
  */
 export function onProxyEvent(event: string, handler: (data: any) => void): void {
   if (!bridge) throw new Error('proxy engine not initialized');