@teamlearners/clawops 0.16.6 → 0.17.1

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;
@@ -734,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>;
@@ -806,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;
@@ -873,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>;

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;
@@ -734,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>;
@@ -806,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;
@@ -873,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>;