@teamlearners/clawops 0.16.5 → 0.17.0

package/dist/agent/index.d.cts

@@ -317,8 +317,20 @@ interface LLMChunk {
  * Implementations: OpenAIRealtime, GeminiRealtime
  */
 interface Session {
-    /** Start the realtime session with the call session and tools. */
+    /** Start the realtime session with the call session and tools. Thin wrapper over prewarm + attach. */
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
+    /**
+     * Open LLM connection (and session.update + optional greeting trigger) without a CallSession.
+     *
+     * Audio deltas produced during the prewarm window accumulate in an internal BufferingCall.
+     * attach() then replaces the BufferingCall with the real CallSession and flushes the buffer.
+     *
+     * Tools may optionally be injected here (alternative to calling setToolRegistry separately);
+     * the Session is free to ignore the argument if tools are already set.
+     */
+    prewarm(tools?: ToolRegistry): Promise<void>;
+    /** Attach a real CallSession to a prewarmed session and flush any buffered audio. */
+    attach(callSession: CallSession): Promise<void>;
     /** Feed raw audio into the session. */
     feedAudio(audio: Buffer, timestamp?: number): void;
     /** Feed DTMF digits into the LLM context and trigger a response. */
@@ -440,6 +452,12 @@ interface ClawOpsAgentOptions {
      * The caller hears the gained audio, and recording captures it post-gain.
      */
     txGain?: number;
+    /**
+     * outbound_ready 시점에 session.prewarm() 을 백그라운드로 시작할지 여부.
+     * false 면 기존 start() 단일 경로로 동작 (prewarm 비활성). Default: true.
+     * Python SDK 의 `prewarm_enabled` 과 mirror.
+     */
+    prewarmEnabled?: boolean;
 }
 declare class ClawOpsAgent {
     private _apiKey;
@@ -466,6 +484,11 @@ declare class ClawOpsAgent {
     private _holdAudioChunks;
     private _rxGain;
     private _txGain;
+    private _prewarmTasks;
+    private _prewarmFailed;
+    /** prewarm 세션이 실제 CallSession 에 attach 완료된 callId. attached 이후의 stop() 은 정상 종료 경로가 책임진다. */
+    private _prewarmAttached;
+    private _prewarmEnabled;
     constructor(options: ClawOpsAgentOptions);
     private static _validateGain;
     /**
@@ -502,7 +525,24 @@ declare class ClawOpsAgent {
     }): Promise<CallSession>;
     private _handleIncoming;
     private _handleEnded;
+    /**
+     * Drop prewarm bookkeeping for a callId. Used on hangup/failure paths.
+     *
+     * prewarm 이 진행 중이거나 완료됐지만 attach 전에 호출되면 LLM WS 가 leak 되므로
+     * race 후 session.stop() 으로 정리한다. (TS 에는 Promise.cancel 이 없어 Python
+     * 의 task.cancel() 등가물은 _session.stop() 호출이다.)
+     *
+     * 이미 attach 된 callId 면 stop() 을 호출하지 않는다 — 정상 종료 경로 (call-session
+     * finally) 가 책임지기 때문이다.
+     */
+    private _cleanupPrewarm;
     private _handleOutboundReady;
+    /**
+     * Start the LLM session prewarm task for the given callId. Safe to call
+     * multiple times — only the first invocation starts the task. Failures are
+     * recorded in _prewarmFailed so the call-session path can fall back to start().
+     */
+    private _startPrewarm;
     private _handleRinging;
     private _handleFailed;
     private _onDtmfEvent;
@@ -517,6 +557,64 @@ declare class ClawOpsAgent {
     private _startCallSession;
 }
 
+/**
+ * Control WebSocket for agent signaling (call.incoming, call.ended, etc.).
+ */
+
+interface ControlWsOptions {
+    baseUrl: string;
+    apiKey: string;
+    accountId: string;
+    /** Phone number to register on. */
+    number?: string;
+}
+/**
+ * Control event is a flat JSON object with an 'event' field.
+ * Example: { "event": "call.incoming", "callId": "xxx", "from": "070...", "mediaUrl": "wss://..." }
+ */
+interface ControlEvent {
+    event: string;
+    [key: string]: unknown;
+}
+type ControlEventHandler = (event: ControlEvent) => void | Promise<void>;
+/**
+ * Build the full control WebSocket URL from options.
+ * Matches Python SDK: /v1/accounts/{account_id}/agent/listen?number={number}
+ */
+declare function buildControlWsUrl(options: ControlWsOptions): string;
+declare class ControlWebSocket {
+    private readonly _options;
+    private _url;
+    private _ws;
+    private _handlers;
+    private _transferResolvers;
+    private _reconnectDelay;
+    private _closed;
+    private _connectedResolve;
+    private _connectedPromise;
+    private _log;
+    private _pingTimer;
+    setLogger(logger: Logger): void;
+    constructor(_options: ControlWsOptions);
+    /** Register an event handler for a specific event type. */
+    on(event: string, handler: ControlEventHandler): void;
+    /** Connect to the control WebSocket. */
+    connect(): Promise<void>;
+    /** Wait until the WebSocket is connected. */
+    waitConnected(): Promise<void>;
+    /** Request a call transfer and wait for the result. */
+    requestTransfer(callId: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Send a JSON message over the control WebSocket. */
+    send(message: Record<string, unknown>): void;
+    /** Close the WebSocket and stop reconnecting. */
+    close(): void;
+    private _doConnect;
+    private _dispatchEvent;
+    private _resetPingTimer;
+    private _clearPingTimer;
+    private _scheduleReconnect;
+}
+
 /**
  * Media WebSocket for streaming audio to/from the telephony platform.
  *
@@ -676,6 +774,14 @@ declare class PipelineSession implements Session {
     setHoldAudio(chunks: Buffer[]): void;
     getTelemetry(): SessionTelemetry;
     setLogger(logger: Logger): void;
+    /**
+     * Pre-bootstrap conversation state and (optionally) trigger greeting synthesis
+     * before a real CallSession is attached. Audio chunks are buffered into a
+     * BufferingCall until attach() flushes them.
+     */
+    prewarm(tools?: ToolRegistry): Promise<void>;
+    /** Attach a real CallSession to the prewarmed session and flush buffered audio. */
+    attach(callSession: CallSession): Promise<void>;
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     feedAudio(audio: Buffer): void;
     feedDtmf(digits: string): Promise<void>;
@@ -748,6 +854,10 @@ declare class OpenAIRealtime implements Session {
     setRecorder(recorder: AudioRecorder): void;
     /** Tool 실행 중 재생할 hold audio 청크를 설정한다. */
     setHoldAudio(chunks: Buffer[]): void;
+    /** Open WS + session.update + (optional) response.create without a CallSession. */
+    prewarm(tools?: ToolRegistry): Promise<void>;
+    /** Attach a real CallSession to the prewarmed session and flush buffered audio. */
+    attach(callSession: CallSession): Promise<void>;
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     feedDtmf(digits: string): Promise<void>;
     feedAudio(audio: Buffer, timestamp?: number): void;
@@ -815,6 +925,10 @@ declare class GeminiRealtime implements Session {
     setHoldAudio(chunks: Buffer[]): void;
     setLogger(logger: Logger): void;
     getTelemetry(): SessionTelemetry;
+    /** Open Live session (no CallSession). Audio deltas accumulate into BufferingCall until attach(). */
+    prewarm(tools?: ToolRegistry): Promise<void>;
+    /** Attach a real CallSession to the prewarmed session and flush buffered audio. */
+    attach(callSession: CallSession): Promise<void>;
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     feedAudio(audio: Buffer): void;
     feedDtmf(digits: string): Promise<void>;
@@ -1202,4 +1316,4 @@ declare function createAgentLogger(userLogger?: Logger): Logger;
  */
 declare function createPipelineLogger(parent: Logger): Logger;
 
-export { type AgentEventType, AnthropicLLM, type AnthropicLLMOptions, AudioRecorder, BUILTIN_TOOL_NAMES, BuiltinTool, type CallDirection, CallSession, type CallStatus, ClawOpsAgent, type ClawOpsAgentOptions, type ConversationMessage, DECODE_TABLE, DeepSeekLLM, type DeepSeekLLMOptions, DeepgramSTT, type DeepgramSTTOptions, type DtmfEvent, 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, type MediaEvent, type MediaStartEvent, MediaWebSocket, 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, type ToolCallRequest, type ToolConfig, ToolRegistry, type TracingConfig, XaiLLM, type XaiLLMOptions, createAgentLogger, createPipelineLogger, executeBuiltinTool, functionTool, getBuiltinToolSchemas, getTracingConfig, isBuiltinTool, mcpServerHTTP, mcpServerStdio, pcm16ToUlaw, resamplePcm16, resetTracingConfig, setTracingConfig, ulawToPcm16, zodToToolParams };
+export { type AgentEventType, AnthropicLLM, type AnthropicLLMOptions, AudioRecorder, BUILTIN_TOOL_NAMES, BuiltinTool, type CallDirection, CallSession, type CallStatus, ClawOpsAgent, type ClawOpsAgentOptions, type ControlEvent, ControlWebSocket, type ControlWsOptions, type ConversationMessage, DECODE_TABLE, DeepSeekLLM, type DeepSeekLLMOptions, DeepgramSTT, type DeepgramSTTOptions, type DtmfEvent, 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, type MediaEvent, type MediaStartEvent, MediaWebSocket, 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, type ToolCallRequest, type ToolConfig, ToolRegistry, type TracingConfig, XaiLLM, type XaiLLMOptions, buildControlWsUrl, createAgentLogger, createPipelineLogger, executeBuiltinTool, functionTool, getBuiltinToolSchemas, getTracingConfig, isBuiltinTool, mcpServerHTTP, mcpServerStdio, pcm16ToUlaw, resamplePcm16, resetTracingConfig, setTracingConfig, ulawToPcm16, zodToToolParams };

package/dist/agent/index.d.ts

@@ -317,8 +317,20 @@ interface LLMChunk {
  * Implementations: OpenAIRealtime, GeminiRealtime
  */
 interface Session {
-    /** Start the realtime session with the call session and tools. */
+    /** Start the realtime session with the call session and tools. Thin wrapper over prewarm + attach. */
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
+    /**
+     * Open LLM connection (and session.update + optional greeting trigger) without a CallSession.
+     *
+     * Audio deltas produced during the prewarm window accumulate in an internal BufferingCall.
+     * attach() then replaces the BufferingCall with the real CallSession and flushes the buffer.
+     *
+     * Tools may optionally be injected here (alternative to calling setToolRegistry separately);
+     * the Session is free to ignore the argument if tools are already set.
+     */
+    prewarm(tools?: ToolRegistry): Promise<void>;
+    /** Attach a real CallSession to a prewarmed session and flush any buffered audio. */
+    attach(callSession: CallSession): Promise<void>;
     /** Feed raw audio into the session. */
     feedAudio(audio: Buffer, timestamp?: number): void;
     /** Feed DTMF digits into the LLM context and trigger a response. */
@@ -440,6 +452,12 @@ interface ClawOpsAgentOptions {
      * The caller hears the gained audio, and recording captures it post-gain.
      */
     txGain?: number;
+    /**
+     * outbound_ready 시점에 session.prewarm() 을 백그라운드로 시작할지 여부.
+     * false 면 기존 start() 단일 경로로 동작 (prewarm 비활성). Default: true.
+     * Python SDK 의 `prewarm_enabled` 과 mirror.
+     */
+    prewarmEnabled?: boolean;
 }
 declare class ClawOpsAgent {
     private _apiKey;
@@ -466,6 +484,11 @@ declare class ClawOpsAgent {
     private _holdAudioChunks;
     private _rxGain;
     private _txGain;
+    private _prewarmTasks;
+    private _prewarmFailed;
+    /** prewarm 세션이 실제 CallSession 에 attach 완료된 callId. attached 이후의 stop() 은 정상 종료 경로가 책임진다. */
+    private _prewarmAttached;
+    private _prewarmEnabled;
     constructor(options: ClawOpsAgentOptions);
     private static _validateGain;
     /**
@@ -502,7 +525,24 @@ declare class ClawOpsAgent {
     }): Promise<CallSession>;
     private _handleIncoming;
     private _handleEnded;
+    /**
+     * Drop prewarm bookkeeping for a callId. Used on hangup/failure paths.
+     *
+     * prewarm 이 진행 중이거나 완료됐지만 attach 전에 호출되면 LLM WS 가 leak 되므로
+     * race 후 session.stop() 으로 정리한다. (TS 에는 Promise.cancel 이 없어 Python
+     * 의 task.cancel() 등가물은 _session.stop() 호출이다.)
+     *
+     * 이미 attach 된 callId 면 stop() 을 호출하지 않는다 — 정상 종료 경로 (call-session
+     * finally) 가 책임지기 때문이다.
+     */
+    private _cleanupPrewarm;
     private _handleOutboundReady;
+    /**
+     * Start the LLM session prewarm task for the given callId. Safe to call
+     * multiple times — only the first invocation starts the task. Failures are
+     * recorded in _prewarmFailed so the call-session path can fall back to start().
+     */
+    private _startPrewarm;
     private _handleRinging;
     private _handleFailed;
     private _onDtmfEvent;
@@ -517,6 +557,64 @@ declare class ClawOpsAgent {
     private _startCallSession;
 }
 
+/**
+ * Control WebSocket for agent signaling (call.incoming, call.ended, etc.).
+ */
+
+interface ControlWsOptions {
+    baseUrl: string;
+    apiKey: string;
+    accountId: string;
+    /** Phone number to register on. */
+    number?: string;
+}
+/**
+ * Control event is a flat JSON object with an 'event' field.
+ * Example: { "event": "call.incoming", "callId": "xxx", "from": "070...", "mediaUrl": "wss://..." }
+ */
+interface ControlEvent {
+    event: string;
+    [key: string]: unknown;
+}
+type ControlEventHandler = (event: ControlEvent) => void | Promise<void>;
+/**
+ * Build the full control WebSocket URL from options.
+ * Matches Python SDK: /v1/accounts/{account_id}/agent/listen?number={number}
+ */
+declare function buildControlWsUrl(options: ControlWsOptions): string;
+declare class ControlWebSocket {
+    private readonly _options;
+    private _url;
+    private _ws;
+    private _handlers;
+    private _transferResolvers;
+    private _reconnectDelay;
+    private _closed;
+    private _connectedResolve;
+    private _connectedPromise;
+    private _log;
+    private _pingTimer;
+    setLogger(logger: Logger): void;
+    constructor(_options: ControlWsOptions);
+    /** Register an event handler for a specific event type. */
+    on(event: string, handler: ControlEventHandler): void;
+    /** Connect to the control WebSocket. */
+    connect(): Promise<void>;
+    /** Wait until the WebSocket is connected. */
+    waitConnected(): Promise<void>;
+    /** Request a call transfer and wait for the result. */
+    requestTransfer(callId: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Send a JSON message over the control WebSocket. */
+    send(message: Record<string, unknown>): void;
+    /** Close the WebSocket and stop reconnecting. */
+    close(): void;
+    private _doConnect;
+    private _dispatchEvent;
+    private _resetPingTimer;
+    private _clearPingTimer;
+    private _scheduleReconnect;
+}
+
 /**
  * Media WebSocket for streaming audio to/from the telephony platform.
  *
@@ -676,6 +774,14 @@ declare class PipelineSession implements Session {
     setHoldAudio(chunks: Buffer[]): void;
     getTelemetry(): SessionTelemetry;
     setLogger(logger: Logger): void;
+    /**
+     * Pre-bootstrap conversation state and (optionally) trigger greeting synthesis
+     * before a real CallSession is attached. Audio chunks are buffered into a
+     * BufferingCall until attach() flushes them.
+     */
+    prewarm(tools?: ToolRegistry): Promise<void>;
+    /** Attach a real CallSession to the prewarmed session and flush buffered audio. */
+    attach(callSession: CallSession): Promise<void>;
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     feedAudio(audio: Buffer): void;
     feedDtmf(digits: string): Promise<void>;
@@ -748,6 +854,10 @@ declare class OpenAIRealtime implements Session {
     setRecorder(recorder: AudioRecorder): void;
     /** Tool 실행 중 재생할 hold audio 청크를 설정한다. */
     setHoldAudio(chunks: Buffer[]): void;
+    /** Open WS + session.update + (optional) response.create without a CallSession. */
+    prewarm(tools?: ToolRegistry): Promise<void>;
+    /** Attach a real CallSession to the prewarmed session and flush buffered audio. */
+    attach(callSession: CallSession): Promise<void>;
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     feedDtmf(digits: string): Promise<void>;
     feedAudio(audio: Buffer, timestamp?: number): void;
@@ -815,6 +925,10 @@ declare class GeminiRealtime implements Session {
     setHoldAudio(chunks: Buffer[]): void;
     setLogger(logger: Logger): void;
     getTelemetry(): SessionTelemetry;
+    /** Open Live session (no CallSession). Audio deltas accumulate into BufferingCall until attach(). */
+    prewarm(tools?: ToolRegistry): Promise<void>;
+    /** Attach a real CallSession to the prewarmed session and flush buffered audio. */
+    attach(callSession: CallSession): Promise<void>;
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     feedAudio(audio: Buffer): void;
     feedDtmf(digits: string): Promise<void>;
@@ -1202,4 +1316,4 @@ declare function createAgentLogger(userLogger?: Logger): Logger;
  */
 declare function createPipelineLogger(parent: Logger): Logger;
 
-export { type AgentEventType, AnthropicLLM, type AnthropicLLMOptions, AudioRecorder, BUILTIN_TOOL_NAMES, BuiltinTool, type CallDirection, CallSession, type CallStatus, ClawOpsAgent, type ClawOpsAgentOptions, type ConversationMessage, DECODE_TABLE, DeepSeekLLM, type DeepSeekLLMOptions, DeepgramSTT, type DeepgramSTTOptions, type DtmfEvent, 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, type MediaEvent, type MediaStartEvent, MediaWebSocket, 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, type ToolCallRequest, type ToolConfig, ToolRegistry, type TracingConfig, XaiLLM, type XaiLLMOptions, createAgentLogger, createPipelineLogger, executeBuiltinTool, functionTool, getBuiltinToolSchemas, getTracingConfig, isBuiltinTool, mcpServerHTTP, mcpServerStdio, pcm16ToUlaw, resamplePcm16, resetTracingConfig, setTracingConfig, ulawToPcm16, zodToToolParams };
+export { type AgentEventType, AnthropicLLM, type AnthropicLLMOptions, AudioRecorder, BUILTIN_TOOL_NAMES, BuiltinTool, type CallDirection, CallSession, type CallStatus, ClawOpsAgent, type ClawOpsAgentOptions, type ControlEvent, ControlWebSocket, type ControlWsOptions, type ConversationMessage, DECODE_TABLE, DeepSeekLLM, type DeepSeekLLMOptions, DeepgramSTT, type DeepgramSTTOptions, type DtmfEvent, 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, type MediaEvent, type MediaStartEvent, MediaWebSocket, 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, type ToolCallRequest, type ToolConfig, ToolRegistry, type TracingConfig, XaiLLM, type XaiLLMOptions, buildControlWsUrl, createAgentLogger, createPipelineLogger, executeBuiltinTool, functionTool, getBuiltinToolSchemas, getTracingConfig, isBuiltinTool, mcpServerHTTP, mcpServerStdio, pcm16ToUlaw, resamplePcm16, resetTracingConfig, setTracingConfig, ulawToPcm16, zodToToolParams };