@teamlearners/clawops 0.4.0 → 0.5.3

package/dist/agent/index.d.cts

@@ -142,7 +142,10 @@ interface ClearAudioFn {
     (): void;
 }
 interface HangupFn {
-    (): void;
+    (): void | Promise<void>;
+}
+interface SendDtmfFn {
+    (digit: string): Promise<void>;
 }
 declare class CallSession {
     readonly callId: string;
@@ -156,6 +159,11 @@ declare class CallSession {
     private _sendAudioFn;
     private _clearAudioFn;
     private _hangupFn;
+    /** @internal */ _sendDtmfFn: SendDtmfFn | null;
+    /** @internal */ _isTransportConnected: (() => boolean) | null;
+    private _dtmfCollectorActive;
+    private _dtmfResolvers;
+    private _dtmfBuffer;
     private _handlers;
     private _endedPromise;
     private _resolveEnded;
@@ -170,13 +178,24 @@ declare class CallSession {
     get status(): CallStatus;
     get duration(): number;
     /** Bind transport functions (called internally by the agent). */
-    _bindTransport(send: SendAudioFn, clear: ClearAudioFn, hangup: HangupFn): void;
+    _bindTransport(send: SendAudioFn, clear: ClearAudioFn, hangup: HangupFn, sendDtmf?: SendDtmfFn, isConnected?: () => boolean): void;
     /** Send PCM16 or ulaw audio to the caller. */
     sendAudio(audio: Buffer): void;
     /** Clear any queued outbound audio. */
     clearAudio(): void;
-    /** Hang up the call. */
-    hangup(): void;
+    /** Hang up the call, waiting for pending audio to finish. */
+    hangup(): Promise<void>;
+    /** @internal Route a received DTMF digit to an active collector or buffer. */
+    _routeDtmf(digit: string): void;
+    /** Collect DTMF digits from the caller. */
+    collectDtmf(options: {
+        maxDigits: number;
+        finishOnKey?: string;
+        timeout?: number;
+        secure?: boolean;
+    }): Promise<string>;
+    /** Send a sequence of DTMF digits. */
+    sendDtmfSequence(digits: string): Promise<void>;
     /** Register an event handler. */
     on(event: string, handler: SessionEventHandler): void;
     /** Wait for the call to end. */
@@ -187,6 +206,22 @@ declare class CallSession {
     _emit(event: string, ...args: any[]): void;
 }
 
+/**
+ * Built-in tool definitions and selection constants.
+ */
+declare enum BuiltinTool {
+    /** 전화 종료 도구. AI가 대화 완료 시 통화를 종료합니다. */
+    HANG_UP = "hang_up",
+    /** DTMF 수집 도구. 사용자의 키패드 입력을 수집합니다. */
+    COLLECT_DTMF = "collect_dtmf",
+    /** DTMF 전송 도구. ARS 탐색이나 내선번호 입력에 사용합니다. */
+    SEND_DTMF = "send_dtmf",
+    /** 모든 내장 도구를 활성화합니다. (기본값) */
+    ALL = "all",
+    /** 모든 내장 도구를 비활성화합니다. */
+    NONE = "none"
+}
+
 /**
  * Base interfaces for the voice agent pipeline.
  */
@@ -224,6 +259,8 @@ interface Session {
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     /** Feed raw audio into the session. */
     feedAudio(audio: Buffer): void;
+    /** Feed DTMF digits into the LLM context and trigger a response. */
+    feedDtmf?(digits: string): Promise<void>;
     /** Stop the session. */
     stop(): Promise<void>;
 }
@@ -293,7 +330,7 @@ declare function resetTracingConfig(): void;
  * ClawOpsAgent - main agent class for handling voice calls.
  */
 
-type AgentEventType = 'call_start' | 'call_end' | 'call_failed' | 'transcript';
+type AgentEventType = 'call_start' | 'call_end' | 'call_failed' | 'transcript' | 'dtmf';
 type AgentEventHandler = (...args: any[]) => void | Promise<void>;
 interface ClawOpsAgentOptions {
     /** ClawOps API key. Falls back to CLAWOPS_API_KEY env var. */
@@ -314,6 +351,10 @@ interface ClawOpsAgentOptions {
     mcpServers?: Array<MCPServerStdio | MCPServerHTTP>;
     /** Tracing configuration. */
     tracing?: TracingConfig;
+    /** 활성화할 내장 도구. Default: BuiltinTool.ALL */
+    builtinTools?: BuiltinTool | BuiltinTool[];
+    /** Debounce time (ms) for passive DTMF accumulation. Default: 500 */
+    passiveDtmfDebounceMs?: number;
 }
 declare class ClawOpsAgent {
     private _apiKey;
@@ -328,6 +369,12 @@ declare class ClawOpsAgent {
     private _recording;
     private _recordingPath;
     private _activeSessions;
+    private _builtinTools;
+    private _passiveDtmfDebounceMs;
+    private _passiveDtmfBuffer;
+    private _passiveDtmfTimer;
+    private _passiveDtmfCallId;
+    private _callSessions;
     constructor(options: ClawOpsAgentOptions);
     /**
      * Register a function tool.
@@ -366,6 +413,7 @@ declare class ClawOpsAgent {
     private _handleOutboundReady;
     private _handleRinging;
     private _handleFailed;
+    private _onDtmfEvent;
     private _startCallSession;
 }
 
@@ -436,6 +484,8 @@ declare class OpenAIRealtime implements Session {
     private _language;
     private _eagerness;
     private _greeting;
+    private _builtinTools;
+    setBuiltinTools(tools: Set<BuiltinTool>): void;
     private _ws;
     private _call;
     private _tools;
@@ -445,12 +495,15 @@ declare class OpenAIRealtime implements Session {
     private _responseStartTs;
     private _sentAudioChunks;
     private _audioRemainder;
+    private _responseInProgress;
+    private _onResponseDone;
     constructor(options?: OpenAIRealtimeOptions);
     /** Inject per-call ToolRegistry. */
     setToolRegistry(registry: ToolRegistry): void;
     /** Inject per-call AudioRecorder. */
     setRecorder(recorder: AudioRecorder): void;
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
+    feedDtmf(digits: string): Promise<void>;
     feedAudio(audio: Buffer): void;
     stop(): Promise<void>;
     private _sendSessionUpdate;
@@ -458,13 +511,15 @@ declare class OpenAIRealtime implements Session {
     private _handleAudioDelta;
     private _handleTruncation;
     private _handleToolCall;
+    private _waitForResponseDone;
     private _send;
 }
 
 /**
  * Google Gemini Realtime API session (speech-to-speech).
  *
- * Matches Python SDK's GeminiRealtime implementation.
+ * Uses @google/genai SDK's live.connect() method.
+ * Matches Python SDK's GeminiRealtime implementation (v0.14.0).
  */
 
 interface GeminiRealtimeOptions {
@@ -480,8 +535,6 @@ interface GeminiRealtimeOptions {
     language?: string;
     /** Send initial greeting. Default: true */
     greeting?: boolean;
-    /** Generation config overrides. */
-    generationConfig?: Record<string, unknown>;
 }
 declare class GeminiRealtime implements Session {
     private _apiKey;
@@ -490,26 +543,26 @@ declare class GeminiRealtime implements Session {
     private _voice;
     private _language;
     private _greeting;
-    private _generationConfig;
-    private _ws;
+    private _session;
     private _call;
     private _tools;
     private _recorder;
     private _closed;
     private _sentAudioChunks;
     private _audioRemainder;
+    private _builtinTools;
+    private _toolCallInProgress;
     constructor(options?: GeminiRealtimeOptions);
     /** Inject per-call ToolRegistry. */
     setToolRegistry(registry: ToolRegistry): void;
     /** Inject per-call AudioRecorder. */
     setRecorder(recorder: AudioRecorder): void;
+    setBuiltinTools(tools: Set<BuiltinTool>): void;
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     feedAudio(audio: Buffer): void;
+    feedDtmf(digits: string): Promise<void>;
     stop(): Promise<void>;
-    private _sendSetup;
-    private _waitSetupComplete;
-    private _sendGreeting;
-    private _receiveLoop;
+    private _buildToolSchemas;
     private _handleMessage;
     private _handleAudioData;
     private _flushAudioRemainder;
@@ -561,16 +614,20 @@ declare class PipelineSession implements Session {
     private _audioBuffer;
     private _running;
     private _speaking;
+    private _builtinTools;
     constructor(options: PipelineSessionOptions);
     setToolRegistry(registry: ToolRegistry): void;
     setRecorder(recorder: AudioRecorder): void;
+    setBuiltinTools(tools: Set<BuiltinTool>): void;
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     feedAudio(audio: Buffer): void;
+    feedDtmf(digits: string): Promise<void>;
     stop(): Promise<void>;
     private _runSttLoop;
     private _createAudioStream;
     private _generateGreeting;
     private _handleUserSpeech;
+    private _buildEffectiveTools;
     private _respond;
     private _handleToolCall;
     private _synthesizeAndSend;
@@ -877,4 +934,4 @@ declare class XaiLLM implements LLM {
     }): AsyncGenerator<LLMChunk>;
 }
 
-export { type AgentEventType, AnthropicLLM, type AnthropicLLMOptions, AudioRecorder, type CallDirection, CallSession, type CallStatus, ClawOpsAgent, type ClawOpsAgentOptions, type ConversationMessage, DECODE_TABLE, DeepSeekLLM, type DeepSeekLLMOptions, DeepgramSTT, type DeepgramSTTOptions, ElevenLabsTTS, type ElevenLabsTTSOptions, FireworksLLM, type FireworksLLMOptions, type FunctionTool, GeminiLLM, type GeminiLLMOptions, GeminiRealtime, type GeminiRealtimeOptions, GroqLLM, type GroqLLMOptions, type LLM, type LLMChunk, MCPClient, type MCPServerConfig, type MCPServerHTTP, type MCPServerStdio, MistralLLM, type MistralLLMOptions, OllamaLLM, type OllamaLLMOptions, OpenAICompatLLM, type OpenAICompatLLMOptions, OpenAILLM, type OpenAILLMOptions, OpenAIRealtime, type OpenAIRealtimeOptions, type OpenAIToolDefinition, PerplexityLLM, type PerplexityLLMOptions, PipelineSession, type PipelineSessionOptions, type STT, type Session, type SpeechEvent, type TTS, TogetherLLM, type TogetherLLMOptions, ToolRegistry, type TracingConfig, XaiLLM, type XaiLLMOptions, functionTool, getTracingConfig, mcpServerHTTP, mcpServerStdio, pcm16ToUlaw, resamplePcm16, resetTracingConfig, setTracingConfig, ulawToPcm16, zodToToolParams };
+export { type AgentEventType, AnthropicLLM, type AnthropicLLMOptions, AudioRecorder, BuiltinTool, type CallDirection, CallSession, type CallStatus, ClawOpsAgent, type ClawOpsAgentOptions, type ConversationMessage, DECODE_TABLE, DeepSeekLLM, type DeepSeekLLMOptions, DeepgramSTT, type DeepgramSTTOptions, ElevenLabsTTS, type ElevenLabsTTSOptions, FireworksLLM, type FireworksLLMOptions, type FunctionTool, GeminiLLM, type GeminiLLMOptions, GeminiRealtime, type GeminiRealtimeOptions, GroqLLM, type GroqLLMOptions, type LLM, type LLMChunk, MCPClient, type MCPServerConfig, type MCPServerHTTP, type MCPServerStdio, MistralLLM, type MistralLLMOptions, OllamaLLM, type OllamaLLMOptions, OpenAICompatLLM, type OpenAICompatLLMOptions, OpenAILLM, type OpenAILLMOptions, OpenAIRealtime, type OpenAIRealtimeOptions, type OpenAIToolDefinition, PerplexityLLM, type PerplexityLLMOptions, PipelineSession, type PipelineSessionOptions, type STT, type Session, type SpeechEvent, type TTS, TogetherLLM, type TogetherLLMOptions, ToolRegistry, type TracingConfig, XaiLLM, type XaiLLMOptions, functionTool, getTracingConfig, mcpServerHTTP, mcpServerStdio, pcm16ToUlaw, resamplePcm16, resetTracingConfig, setTracingConfig, ulawToPcm16, zodToToolParams };

package/dist/agent/index.d.ts

@@ -142,7 +142,10 @@ interface ClearAudioFn {
     (): void;
 }
 interface HangupFn {
-    (): void;
+    (): void | Promise<void>;
+}
+interface SendDtmfFn {
+    (digit: string): Promise<void>;
 }
 declare class CallSession {
     readonly callId: string;
@@ -156,6 +159,11 @@ declare class CallSession {
     private _sendAudioFn;
     private _clearAudioFn;
     private _hangupFn;
+    /** @internal */ _sendDtmfFn: SendDtmfFn | null;
+    /** @internal */ _isTransportConnected: (() => boolean) | null;
+    private _dtmfCollectorActive;
+    private _dtmfResolvers;
+    private _dtmfBuffer;
     private _handlers;
     private _endedPromise;
     private _resolveEnded;
@@ -170,13 +178,24 @@ declare class CallSession {
     get status(): CallStatus;
     get duration(): number;
     /** Bind transport functions (called internally by the agent). */
-    _bindTransport(send: SendAudioFn, clear: ClearAudioFn, hangup: HangupFn): void;
+    _bindTransport(send: SendAudioFn, clear: ClearAudioFn, hangup: HangupFn, sendDtmf?: SendDtmfFn, isConnected?: () => boolean): void;
     /** Send PCM16 or ulaw audio to the caller. */
     sendAudio(audio: Buffer): void;
     /** Clear any queued outbound audio. */
     clearAudio(): void;
-    /** Hang up the call. */
-    hangup(): void;
+    /** Hang up the call, waiting for pending audio to finish. */
+    hangup(): Promise<void>;
+    /** @internal Route a received DTMF digit to an active collector or buffer. */
+    _routeDtmf(digit: string): void;
+    /** Collect DTMF digits from the caller. */
+    collectDtmf(options: {
+        maxDigits: number;
+        finishOnKey?: string;
+        timeout?: number;
+        secure?: boolean;
+    }): Promise<string>;
+    /** Send a sequence of DTMF digits. */
+    sendDtmfSequence(digits: string): Promise<void>;
     /** Register an event handler. */
     on(event: string, handler: SessionEventHandler): void;
     /** Wait for the call to end. */
@@ -187,6 +206,22 @@ declare class CallSession {
     _emit(event: string, ...args: any[]): void;
 }
 
+/**
+ * Built-in tool definitions and selection constants.
+ */
+declare enum BuiltinTool {
+    /** 전화 종료 도구. AI가 대화 완료 시 통화를 종료합니다. */
+    HANG_UP = "hang_up",
+    /** DTMF 수집 도구. 사용자의 키패드 입력을 수집합니다. */
+    COLLECT_DTMF = "collect_dtmf",
+    /** DTMF 전송 도구. ARS 탐색이나 내선번호 입력에 사용합니다. */
+    SEND_DTMF = "send_dtmf",
+    /** 모든 내장 도구를 활성화합니다. (기본값) */
+    ALL = "all",
+    /** 모든 내장 도구를 비활성화합니다. */
+    NONE = "none"
+}
+
 /**
  * Base interfaces for the voice agent pipeline.
  */
@@ -224,6 +259,8 @@ interface Session {
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     /** Feed raw audio into the session. */
     feedAudio(audio: Buffer): void;
+    /** Feed DTMF digits into the LLM context and trigger a response. */
+    feedDtmf?(digits: string): Promise<void>;
     /** Stop the session. */
     stop(): Promise<void>;
 }
@@ -293,7 +330,7 @@ declare function resetTracingConfig(): void;
  * ClawOpsAgent - main agent class for handling voice calls.
  */
 
-type AgentEventType = 'call_start' | 'call_end' | 'call_failed' | 'transcript';
+type AgentEventType = 'call_start' | 'call_end' | 'call_failed' | 'transcript' | 'dtmf';
 type AgentEventHandler = (...args: any[]) => void | Promise<void>;
 interface ClawOpsAgentOptions {
     /** ClawOps API key. Falls back to CLAWOPS_API_KEY env var. */
@@ -314,6 +351,10 @@ interface ClawOpsAgentOptions {
     mcpServers?: Array<MCPServerStdio | MCPServerHTTP>;
     /** Tracing configuration. */
     tracing?: TracingConfig;
+    /** 활성화할 내장 도구. Default: BuiltinTool.ALL */
+    builtinTools?: BuiltinTool | BuiltinTool[];
+    /** Debounce time (ms) for passive DTMF accumulation. Default: 500 */
+    passiveDtmfDebounceMs?: number;
 }
 declare class ClawOpsAgent {
     private _apiKey;
@@ -328,6 +369,12 @@ declare class ClawOpsAgent {
     private _recording;
     private _recordingPath;
     private _activeSessions;
+    private _builtinTools;
+    private _passiveDtmfDebounceMs;
+    private _passiveDtmfBuffer;
+    private _passiveDtmfTimer;
+    private _passiveDtmfCallId;
+    private _callSessions;
     constructor(options: ClawOpsAgentOptions);
     /**
      * Register a function tool.
@@ -366,6 +413,7 @@ declare class ClawOpsAgent {
     private _handleOutboundReady;
     private _handleRinging;
     private _handleFailed;
+    private _onDtmfEvent;
     private _startCallSession;
 }
 
@@ -436,6 +484,8 @@ declare class OpenAIRealtime implements Session {
     private _language;
     private _eagerness;
     private _greeting;
+    private _builtinTools;
+    setBuiltinTools(tools: Set<BuiltinTool>): void;
     private _ws;
     private _call;
     private _tools;
@@ -445,12 +495,15 @@ declare class OpenAIRealtime implements Session {
     private _responseStartTs;
     private _sentAudioChunks;
     private _audioRemainder;
+    private _responseInProgress;
+    private _onResponseDone;
     constructor(options?: OpenAIRealtimeOptions);
     /** Inject per-call ToolRegistry. */
     setToolRegistry(registry: ToolRegistry): void;
     /** Inject per-call AudioRecorder. */
     setRecorder(recorder: AudioRecorder): void;
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
+    feedDtmf(digits: string): Promise<void>;
     feedAudio(audio: Buffer): void;
     stop(): Promise<void>;
     private _sendSessionUpdate;
@@ -458,13 +511,15 @@ declare class OpenAIRealtime implements Session {
     private _handleAudioDelta;
     private _handleTruncation;
     private _handleToolCall;
+    private _waitForResponseDone;
     private _send;
 }
 
 /**
  * Google Gemini Realtime API session (speech-to-speech).
  *
- * Matches Python SDK's GeminiRealtime implementation.
+ * Uses @google/genai SDK's live.connect() method.
+ * Matches Python SDK's GeminiRealtime implementation (v0.14.0).
  */
 
 interface GeminiRealtimeOptions {
@@ -480,8 +535,6 @@ interface GeminiRealtimeOptions {
     language?: string;
     /** Send initial greeting. Default: true */
     greeting?: boolean;
-    /** Generation config overrides. */
-    generationConfig?: Record<string, unknown>;
 }
 declare class GeminiRealtime implements Session {
     private _apiKey;
@@ -490,26 +543,26 @@ declare class GeminiRealtime implements Session {
     private _voice;
     private _language;
     private _greeting;
-    private _generationConfig;
-    private _ws;
+    private _session;
     private _call;
     private _tools;
     private _recorder;
     private _closed;
     private _sentAudioChunks;
     private _audioRemainder;
+    private _builtinTools;
+    private _toolCallInProgress;
     constructor(options?: GeminiRealtimeOptions);
     /** Inject per-call ToolRegistry. */
     setToolRegistry(registry: ToolRegistry): void;
     /** Inject per-call AudioRecorder. */
     setRecorder(recorder: AudioRecorder): void;
+    setBuiltinTools(tools: Set<BuiltinTool>): void;
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     feedAudio(audio: Buffer): void;
+    feedDtmf(digits: string): Promise<void>;
     stop(): Promise<void>;
-    private _sendSetup;
-    private _waitSetupComplete;
-    private _sendGreeting;
-    private _receiveLoop;
+    private _buildToolSchemas;
     private _handleMessage;
     private _handleAudioData;
     private _flushAudioRemainder;
@@ -561,16 +614,20 @@ declare class PipelineSession implements Session {
     private _audioBuffer;
     private _running;
     private _speaking;
+    private _builtinTools;
     constructor(options: PipelineSessionOptions);
     setToolRegistry(registry: ToolRegistry): void;
     setRecorder(recorder: AudioRecorder): void;
+    setBuiltinTools(tools: Set<BuiltinTool>): void;
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     feedAudio(audio: Buffer): void;
+    feedDtmf(digits: string): Promise<void>;
     stop(): Promise<void>;
     private _runSttLoop;
     private _createAudioStream;
     private _generateGreeting;
     private _handleUserSpeech;
+    private _buildEffectiveTools;
     private _respond;
     private _handleToolCall;
     private _synthesizeAndSend;
@@ -877,4 +934,4 @@ declare class XaiLLM implements LLM {
     }): AsyncGenerator<LLMChunk>;
 }
 
-export { type AgentEventType, AnthropicLLM, type AnthropicLLMOptions, AudioRecorder, type CallDirection, CallSession, type CallStatus, ClawOpsAgent, type ClawOpsAgentOptions, type ConversationMessage, DECODE_TABLE, DeepSeekLLM, type DeepSeekLLMOptions, DeepgramSTT, type DeepgramSTTOptions, ElevenLabsTTS, type ElevenLabsTTSOptions, FireworksLLM, type FireworksLLMOptions, type FunctionTool, GeminiLLM, type GeminiLLMOptions, GeminiRealtime, type GeminiRealtimeOptions, GroqLLM, type GroqLLMOptions, type LLM, type LLMChunk, MCPClient, type MCPServerConfig, type MCPServerHTTP, type MCPServerStdio, MistralLLM, type MistralLLMOptions, OllamaLLM, type OllamaLLMOptions, OpenAICompatLLM, type OpenAICompatLLMOptions, OpenAILLM, type OpenAILLMOptions, OpenAIRealtime, type OpenAIRealtimeOptions, type OpenAIToolDefinition, PerplexityLLM, type PerplexityLLMOptions, PipelineSession, type PipelineSessionOptions, type STT, type Session, type SpeechEvent, type TTS, TogetherLLM, type TogetherLLMOptions, ToolRegistry, type TracingConfig, XaiLLM, type XaiLLMOptions, functionTool, getTracingConfig, mcpServerHTTP, mcpServerStdio, pcm16ToUlaw, resamplePcm16, resetTracingConfig, setTracingConfig, ulawToPcm16, zodToToolParams };
+export { type AgentEventType, AnthropicLLM, type AnthropicLLMOptions, AudioRecorder, BuiltinTool, type CallDirection, CallSession, type CallStatus, ClawOpsAgent, type ClawOpsAgentOptions, type ConversationMessage, DECODE_TABLE, DeepSeekLLM, type DeepSeekLLMOptions, DeepgramSTT, type DeepgramSTTOptions, ElevenLabsTTS, type ElevenLabsTTSOptions, FireworksLLM, type FireworksLLMOptions, type FunctionTool, GeminiLLM, type GeminiLLMOptions, GeminiRealtime, type GeminiRealtimeOptions, GroqLLM, type GroqLLMOptions, type LLM, type LLMChunk, MCPClient, type MCPServerConfig, type MCPServerHTTP, type MCPServerStdio, MistralLLM, type MistralLLMOptions, OllamaLLM, type OllamaLLMOptions, OpenAICompatLLM, type OpenAICompatLLMOptions, OpenAILLM, type OpenAILLMOptions, OpenAIRealtime, type OpenAIRealtimeOptions, type OpenAIToolDefinition, PerplexityLLM, type PerplexityLLMOptions, PipelineSession, type PipelineSessionOptions, type STT, type Session, type SpeechEvent, type TTS, TogetherLLM, type TogetherLLMOptions, ToolRegistry, type TracingConfig, XaiLLM, type XaiLLMOptions, functionTool, getTracingConfig, mcpServerHTTP, mcpServerStdio, pcm16ToUlaw, resamplePcm16, resetTracingConfig, setTracingConfig, ulawToPcm16, zodToToolParams };