@teamlearners/clawops 0.16.6 → 0.17.1

package/dist/agent/index.js

@@ -1,4 +1,4 @@
-import { DEFAULT_BASE_URL, AgentError, AgentConnectionError, VERSION } from '../chunk-RYJF2N7K.js';
+import { DEFAULT_BASE_URL, AgentError, AgentConnectionError, VERSION } from '../chunk-LYFVJLIS.js';
 import pino from 'pino';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -1732,6 +1732,11 @@ var ClawOpsAgent = class _ClawOpsAgent {
   _holdAudioChunks = null;
   _rxGain;
   _txGain;
+  _prewarmTasks = /* @__PURE__ */ new Map();
+  _prewarmFailed = /* @__PURE__ */ new Set();
+  /** prewarm 세션이 실제 CallSession 에 attach 완료된 callId. attached 이후의 stop() 은 정상 종료 경로가 책임진다. */
+  _prewarmAttached = /* @__PURE__ */ new Set();
+  _prewarmEnabled;
   constructor(options) {
     this._apiKey = options.apiKey ?? process.env["CLAWOPS_API_KEY"] ?? "";
     this._accountId = options.accountId ?? process.env["CLAWOPS_ACCOUNT_ID"] ?? "";
@@ -1745,6 +1750,7 @@ var ClawOpsAgent = class _ClawOpsAgent {
     this._passiveDtmfDebounceMs = options.passiveDtmfDebounceMs ?? 500;
     this._rxGain = _ClawOpsAgent._validateGain("rxGain", options.rxGain ?? 1);
     this._txGain = _ClawOpsAgent._validateGain("txGain", options.txGain ?? 1);
+    this._prewarmEnabled = options.prewarmEnabled ?? true;
     if (options.tracing) {
       setTracingConfig(options.tracing);
     }
@@ -1903,6 +1909,9 @@ var ClawOpsAgent = class _ClawOpsAgent {
     callSession.setLogger(this._log);
     this._activeSessions.set(callSession.callId, callSession);
     this._log.info("Outbound call initiated: %s -> %s (%s)", this._fromNumber, to, callSession.callId);
+    if (this._prewarmEnabled) {
+      this._startPrewarm(callSession.callId);
+    }
     return callSession;
   }
   _handleIncoming(event) {
@@ -1939,6 +1948,34 @@ var ClawOpsAgent = class _ClawOpsAgent {
       session._markEnded();
       this._activeSessions.delete(callId);
     }
+    void this._cleanupPrewarm(callId);
+  }
+  /**
+   * 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) 가 책임지기 때문이다.
+   */
+  async _cleanupPrewarm(callId) {
+    const task = this._prewarmTasks.get(callId);
+    const attached = this._prewarmAttached.has(callId);
+    this._prewarmTasks.delete(callId);
+    this._prewarmFailed.delete(callId);
+    this._prewarmAttached.delete(callId);
+    if (!task || attached) return;
+    try {
+      await task;
+    } catch {
+    }
+    try {
+      await this._session.stop();
+    } catch (err) {
+      this._log.warn({ err, callId }, "prewarm cleanup stop() failed");
+    }
   }
   _handleOutboundReady(event) {
     const callId = event["callId"];
@@ -1960,16 +1997,60 @@ var ClawOpsAgent = class _ClawOpsAgent {
       }
       this._activeSessions.set(callId, session);
     }
+    if (this._prewarmEnabled) {
+      this._startPrewarm(callId);
+    }
     if (mediaUrl) {
       this._log.info("Outbound call answered: %s -> %s (%s)", this._fromNumber, session.toNumber, callId);
       this._safeStartCallSession(session, mediaUrl, callId);
     }
   }
+  /**
+   * 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().
+   */
+  _startPrewarm(callId) {
+    if (this._prewarmTasks.has(callId)) return;
+    const sessionHandler = this._session;
+    if (typeof sessionHandler.prewarm !== "function") return;
+    const PREWARM_TIMEOUT_MS = 1e4;
+    const t0 = Date.now();
+    this._log.info(`[PREWARM-T] start call_id=${callId} t=${(t0 / 1e3).toFixed(3)}`);
+    const task = (async () => {
+      let timer;
+      try {
+        const timeout = new Promise((_, reject) => {
+          timer = setTimeout(
+            () => reject(new Error("prewarm timeout")),
+            PREWARM_TIMEOUT_MS
+          );
+        });
+        await Promise.race([sessionHandler.prewarm(), timeout]);
+        const elapsed = Date.now() - t0;
+        this._log.info(`[PREWARM-T] done call_id=${callId} elapsed_ms=${elapsed}`);
+      } catch (err) {
+        const elapsed = Date.now() - t0;
+        const reason = err instanceof Error ? err.message : String(err);
+        this._log.warn(
+          { err, callId },
+          `[PREWARM-T] failed call_id=${callId} elapsed_ms=${elapsed} reason=${reason}`
+        );
+        this._prewarmFailed.add(callId);
+      } finally {
+        if (timer) clearTimeout(timer);
+      }
+    })();
+    this._prewarmTasks.set(callId, task);
+  }
   _handleRinging(event) {
     const callId = event["callId"];
     const session = this._activeSessions.get(callId);
     if (session) {
       this._log.info("Outbound call ringing: %s", callId);
+      if (this._prewarmEnabled) {
+        this._startPrewarm(callId);
+      }
     }
   }
   _handleFailed(event) {
@@ -1981,6 +2062,7 @@ var ClawOpsAgent = class _ClawOpsAgent {
       session._markEnded();
       this._activeSessions.delete(callId);
     }
+    void this._cleanupPrewarm(callId);
   }
   _onDtmfEvent(callSession, digit) {
     callSession._emit("dtmf", digit);
@@ -2133,7 +2215,36 @@ var ClawOpsAgent = class _ClawOpsAgent {
         try {
           await mediaWs.connect(mediaWsUrl, this._apiKey);
           this._log.info("Media stream started: %s", session.callId);
-          await sessionHandler.start(session, sessionTools);
+          const prewarmTask = this._prewarmTasks.get(session.callId);
+          if (prewarmTask && !this._prewarmFailed.has(session.callId)) {
+            try {
+              await prewarmTask;
+              if (this._prewarmFailed.has(session.callId)) {
+                await sessionHandler.start(session, sessionTools);
+              } else {
+                this._log.info(
+                  `[PREWARM-T] attach call_id=${session.callId} t=${(Date.now() / 1e3).toFixed(3)}`
+                );
+                await sessionHandler.attach(session);
+                this._prewarmAttached.add(session.callId);
+              }
+            } catch (err) {
+              this._log.warn(
+                { err, callId: session.callId },
+                "prewarm/attach failed, falling back to start()"
+              );
+              try {
+                await sessionHandler.stop();
+              } catch {
+              }
+              await sessionHandler.start(session, sessionTools);
+            }
+          } else {
+            await sessionHandler.start(session, sessionTools);
+          }
+          this._prewarmTasks.delete(session.callId);
+          this._prewarmFailed.delete(session.callId);
+          this._prewarmAttached.delete(session.callId);
           const telemetry = sessionHandler.getTelemetry?.() ?? null;
           if (telemetry) {
             telemetry.toolCount = sessionTools?.size ?? 0;
@@ -2322,6 +2433,86 @@ async function executeBuiltinTool(funcName, args, call) {
   return null;
 }
 
+// src/agent/pipeline/buffering-call.ts
+var MetricsStub = class {
+  recordToolCall() {
+  }
+  recordInterrupt() {
+  }
+  recordToolError() {
+  }
+};
+var BufferingCall = class {
+  _buffer = [];
+  _droppedEvents = {};
+  metrics = new MetricsStub();
+  async sendAudio(chunk) {
+    this._buffer.push(chunk);
+  }
+  /** clearAudio 도 prewarm 동안엔 no-op (드물긴 하지만 안전하게). */
+  clearAudio() {
+    this._buffer = [];
+  }
+  /**
+   * transcript 등 lifecycle 이벤트는 prewarm 동안 무시한다. silent drop 은 디버깅이
+   * 어려우므로 event name 별 카운터로 누적하고 attachBuffered() 시 한 번에 로깅한다.
+   */
+  _emit(...args) {
+    this._recordDropped(args);
+  }
+  async emit(...args) {
+    this._recordDropped(args);
+  }
+  _recordDropped(args) {
+    let eventName = "?";
+    if (args.length > 0 && typeof args[0] === "string") {
+      eventName = args[0];
+    }
+    this._droppedEvents[eventName] = (this._droppedEvents[eventName] ?? 0) + 1;
+  }
+  recordToolCall() {
+  }
+  recordToolError() {
+  }
+  recordFirstResponse() {
+  }
+  recordBargeIn() {
+  }
+  drainBuffer() {
+    const out = this._buffer;
+    this._buffer = [];
+    return out;
+  }
+  drainDroppedEvents() {
+    const out = this._droppedEvents;
+    this._droppedEvents = {};
+    return out;
+  }
+};
+function attachBuffered(prev, next) {
+  if (!(prev instanceof BufferingCall)) {
+    return false;
+  }
+  const drained = prev.drainBuffer();
+  const flushed = drained.length > 0;
+  const callId = next.callId ?? "?";
+  if (flushed) {
+    console.info(
+      `[PREWARM-T] first-audio call_id=${callId} t=${(process.hrtime.bigint() / 1000000n).toString()} buffered_chunks=${drained.length} source=prebuffer`
+    );
+  }
+  for (const chunk of drained) {
+    next.sendAudio(chunk);
+  }
+  const dropped = prev.drainDroppedEvents();
+  if (Object.keys(dropped).length > 0) {
+    console.info(
+      `[PREWARM] dropped events during prewarm call_id=${callId} events=${JSON.stringify(dropped)}`
+    );
+  }
+  return flushed;
+}
+
 // src/agent/pipeline/pipeline-session.ts
 var PipelineSession = class {
   _stt;
@@ -2398,12 +2589,17 @@ var PipelineSession = class {
       this._tts.setLogger(logger);
     }
   }
-  async start(callSession, tools) {
-    this._callSession = callSession;
-    this._tools = tools ?? null;
+  /**
+   * 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.
+   */
+  async prewarm(tools) {
+    if (tools) this._tools = tools;
+    this._callSession = new BufferingCall();
     this._running = true;
-    this._log.info("PipelineSession started");
     this._conversation = [];
+    this._log.info("PipelineSession prewarmed");
     if (this._systemPrompt) {
       this._conversation.push({
         role: "system",
@@ -2419,6 +2615,17 @@ var PipelineSession = class {
       this._log.error({ err }, "STT loop error");
     });
   }
+  /** Attach a real CallSession to the prewarmed session and flush buffered audio. */
+  async attach(callSession) {
+    const prev = this._callSession;
+    this._callSession = callSession;
+    attachBuffered(prev, callSession);
+  }
+  async start(callSession, tools) {
+    this._tools = tools ?? null;
+    await this.prewarm();
+    await this.attach(callSession);
+  }
   feedAudio(audio) {
     if (this._running) {
       this._audioBuffer.push(audio);
@@ -2525,7 +2732,7 @@ var PipelineSession = class {
     const { id, name, arguments: argsStr } = chunk.toolCall;
     try {
       const args = JSON.parse(argsStr);
-      if (BUILTIN_TOOL_NAMES.has(name) && this._callSession) {
+      if (BUILTIN_TOOL_NAMES.has(name) && this._callSession && !(this._callSession instanceof BufferingCall)) {
         const result2 = await executeBuiltinTool(name, args, this._callSession);
         if (result2 !== null) {
           if (name === "hang_up") return;
@@ -2536,7 +2743,7 @@ var PipelineSession = class {
       }
       if (!this._tools) return;
       this._callSession?.recordToolCall();
-      const player = this._holdAudioChunks && this._callSession ? new HoldAudioPlayer(this._callSession, this._holdAudioChunks) : null;
+      const player = this._holdAudioChunks && this._callSession && !(this._callSession instanceof BufferingCall) ? new HoldAudioPlayer(this._callSession, this._holdAudioChunks) : null;
       player?.start();
       let result;
       try {
@@ -2679,24 +2886,23 @@ var OpenAIRealtime = class {
   setHoldAudio(chunks) {
     this._holdAudioChunks = chunks;
   }
-  async start(callSession, tools) {
-    this._call = callSession;
+  /** Open WS + session.update + (optional) response.create without a CallSession. */
+  async prewarm(tools) {
     if (tools) this._tools = tools;
+    this._call = new BufferingCall();
     this._closed = false;
     this._playback = null;
     this._latestMediaTs = 0;
     const { WebSocket } = await import('ws');
     const url = `${OPENAI_REALTIME_URL}${this._model}`;
     this._ws = new WebSocket(url, {
-      headers: {
-        Authorization: `Bearer ${this._apiKey}`
-      }
+      headers: { Authorization: `Bearer ${this._apiKey}` }
     });
     return new Promise((resolve, reject) => {
       const ws = this._ws;
       ws.on("open", () => {
         this._sendSessionUpdate();
-        this._log.info("OpenAI Realtime connected");
+        this._log.info("OpenAI Realtime connected (prewarm)");
         if (this._greeting) {
           this._send({ type: "response.create" });
         }
@@ -2720,6 +2926,17 @@ var OpenAIRealtime = class {
       });
     });
   }
+  /** Attach a real CallSession to the prewarmed session and flush buffered audio. */
+  async attach(callSession) {
+    const prev = this._call;
+    this._call = callSession;
+    attachBuffered(prev, callSession);
+  }
+  async start(callSession, tools) {
+    if (tools) this._tools = tools;
+    await this.prewarm();
+    await this.attach(callSession);
+  }
   async feedDtmf(digits) {
     await this._waitForResponseDone();
     this._send({
@@ -2748,8 +2965,27 @@ var OpenAIRealtime = class {
     }
     this._pendingToolCalls.clear();
     if (this._ws) {
-      this._ws.close();
+      const ws = this._ws;
       this._ws = null;
+      await new Promise((resolve) => {
+        let done = false;
+        const finish = () => {
+          if (done) return;
+          done = true;
+          resolve();
+        };
+        const timer = setTimeout(finish, 2e3);
+        try {
+          ws.on("close", () => {
+            clearTimeout(timer);
+            finish();
+          });
+          ws.close();
+        } catch {
+          clearTimeout(timer);
+          finish();
+        }
+      });
     }
   }
   _sendSessionUpdate() {
@@ -2900,7 +3136,7 @@ var OpenAIRealtime = class {
     const controller = new AbortController();
     this._pendingToolCalls.set(callId, controller);
     try {
-      if (BUILTIN_TOOL_NAMES.has(funcName) && this._call) {
+      if (BUILTIN_TOOL_NAMES.has(funcName) && this._call && !(this._call instanceof BufferingCall)) {
         const args = JSON.parse(item["arguments"] ?? "{}");
         const result2 = await executeBuiltinTool(funcName, args, this._call);
         if (result2 !== null) {
@@ -2934,7 +3170,7 @@ var OpenAIRealtime = class {
         return;
       }
       let result;
-      const player = this._holdAudioChunks && this._call ? new HoldAudioPlayer(this._call, this._holdAudioChunks) : null;
+      const player = this._holdAudioChunks && this._call && !(this._call instanceof BufferingCall) ? new HoldAudioPlayer(this._call, this._holdAudioChunks) : null;
       player?.start();
       try {
         const args = JSON.parse(item["arguments"] ?? "{}");
@@ -3119,9 +3355,10 @@ var GeminiRealtime = class _GeminiRealtime {
       builtinTools: []
     };
   }
-  async start(callSession, tools) {
-    this._call = callSession;
+  /** Open Live session (no CallSession). Audio deltas accumulate into BufferingCall until attach(). */
+  async prewarm(tools) {
     if (tools) this._tools = tools;
+    this._call = new BufferingCall();
     this._closed = false;
     this._sentAudioChunks = 0;
     this._audioRemainder = Buffer.alloc(0);
@@ -3169,10 +3406,22 @@ var GeminiRealtime = class _GeminiRealtime {
         }
       }
     });
+    this._log.info("Gemini Live connected (prewarm)");
     if (this._greeting) {
       this._session.sendRealtimeInput({ text: "\uC778\uC0AC\uD574 \uC8FC\uC138\uC694." });
     }
   }
+  /** Attach a real CallSession to the prewarmed session and flush buffered audio. */
+  async attach(callSession) {
+    const prev = this._call;
+    this._call = callSession;
+    attachBuffered(prev, callSession);
+  }
+  async start(callSession, tools) {
+    if (tools) this._tools = tools;
+    await this.prewarm();
+    await this.attach(callSession);
+  }
   feedAudio(audio) {
     if (this._session && !this._closed) {
       const pcm8k = ulawToPcm16(audio);
@@ -3198,11 +3447,18 @@ var GeminiRealtime = class _GeminiRealtime {
     }
     this._pendingToolCall = null;
     if (this._session) {
-      try {
-        this._session.close();
-      } catch {
-      }
+      const sess = this._session;
       this._session = null;
+      await Promise.race([
+        (async () => {
+          try {
+            const ret = sess.close();
+            if (ret && typeof ret.then === "function") await ret;
+          } catch {
+          }
+        })(),
+        new Promise((resolve) => setTimeout(resolve, 2e3))
+      ]);
     }
   }
   _buildToolSchemas() {
@@ -3317,7 +3573,7 @@ var GeminiRealtime = class _GeminiRealtime {
     const functionCalls = toolCall.functionCalls;
     if (!functionCalls) return;
     const responses = [];
-    const player = this._holdAudioChunks && this._call ? new HoldAudioPlayer(this._call, this._holdAudioChunks) : null;
+    const player = this._holdAudioChunks && this._call && !(this._call instanceof BufferingCall) ? new HoldAudioPlayer(this._call, this._holdAudioChunks) : null;
     player?.start();
     try {
       for (const fc of functionCalls) {
@@ -3325,7 +3581,7 @@ var GeminiRealtime = class _GeminiRealtime {
         const fcId = fc.id ?? "";
         const args = fc.args ?? {};
         this._log.info({ tool: name, args }, "Tool call: %s", name);
-        if (BUILTIN_TOOL_NAMES.has(name) && this._call) {
+        if (BUILTIN_TOOL_NAMES.has(name) && this._call && !(this._call instanceof BufferingCall)) {
           const result = await executeBuiltinTool(
             name,
             args,