@teamlearners/clawops 0.16.0 → 0.16.4

package/dist/agent/index.d.cts

@@ -320,7 +320,7 @@ interface Session {
     /** Start the realtime session with the call session and tools. */
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     /** Feed raw audio into the session. */
-    feedAudio(audio: Buffer): void;
+    feedAudio(audio: Buffer, timestamp?: number): void;
     /** Feed DTMF digits into the LLM context and trigger a response. */
     feedDtmf?(digits: string): Promise<void>;
     /** Stop the session. */
@@ -430,6 +430,16 @@ interface ClawOpsAgentOptions {
     logger?: Logger;
     /** Tool 실행 관련 설정. */
     toolConfig?: ToolConfig;
+    /**
+     * Gain applied to inbound audio (caller → AI). 1.0 = pass-through (default), 0 = mute, 2.0 = 2x amplify.
+     * AI/STT receive the gained audio, and recording captures it post-gain.
+     */
+    rxGain?: number;
+    /**
+     * Gain applied to outbound audio (AI → caller). 1.0 = pass-through (default), 0 = mute, 2.0 = 2x amplify.
+     * The caller hears the gained audio, and recording captures it post-gain.
+     */
+    txGain?: number;
 }
 declare class ClawOpsAgent {
     private _apiKey;
@@ -454,7 +464,10 @@ declare class ClawOpsAgent {
     private _pipelineLog;
     private _isPipelineSession;
     private _holdAudioChunks;
+    private _rxGain;
+    private _txGain;
     constructor(options: ClawOpsAgentOptions);
+    private static _validateGain;
     /**
      * Register a function tool.
      *
@@ -493,6 +506,14 @@ declare class ClawOpsAgent {
     private _handleRinging;
     private _handleFailed;
     private _onDtmfEvent;
+    /**
+     * _startCallSession 의 예외를 잡아 control WS 로 call.session_failed 전송한다.
+     *
+     * OpenAI/Gemini API 키 누락 등 session.start() 단계 실패는 media WS connect 에
+     * 도달하지 못해 call-engine 이 30 초간 무음 통화를 유지하게 만든다. 서버에 즉시
+     * 알려서 fail-fast 시키고 _activeSessions 에서 정리한다.
+     */
+    private _safeStartCallSession;
     private _startCallSession;
 }
 
@@ -584,17 +605,18 @@ declare class AudioRecorder {
     private _inWritten;
     private _outWritten;
     private _mixWritten;
-    private _startTime;
     private _started;
+    private _baseTs;
+    private _outCursor;
     private _log;
     setLogger(logger: Logger): void;
     constructor(recordingPath: string, callId: string);
     start(): void;
-    private _expectedBytes;
+    private _timestampToBytes;
     private _padSilence;
     private _writeToMix;
-    writeInbound(pcm16_8k: Buffer): void;
-    writeOutbound(pcm16_8k: Buffer): void;
+    writeInbound(pcm16_8k: Buffer, mediaTsMs?: number): void;
+    writeOutbound(pcm16_8k: Buffer, mediaTsMs?: number): void;
     stop(): void;
 }
 
@@ -679,7 +701,7 @@ interface OpenAIRealtimeOptions {
     apiKey?: string;
     /** System prompt / instructions for the AI. */
     systemPrompt?: string;
-    /** Model to use. Default: 'gpt-realtime-1.5' */
+    /** Model to use. Default: 'gpt-realtime-2' */
     model?: string;
     /** Voice ID. Default: 'marin' */
     voice?: string;
@@ -728,7 +750,7 @@ declare class OpenAIRealtime implements Session {
     setHoldAudio(chunks: Buffer[]): void;
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     feedDtmf(digits: string): Promise<void>;
-    feedAudio(audio: Buffer): void;
+    feedAudio(audio: Buffer, timestamp?: number): void;
     stop(): Promise<void>;
     private _sendSessionUpdate;
     private _handleMessage;

package/dist/agent/index.d.ts

@@ -320,7 +320,7 @@ interface Session {
     /** Start the realtime session with the call session and tools. */
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     /** Feed raw audio into the session. */
-    feedAudio(audio: Buffer): void;
+    feedAudio(audio: Buffer, timestamp?: number): void;
     /** Feed DTMF digits into the LLM context and trigger a response. */
     feedDtmf?(digits: string): Promise<void>;
     /** Stop the session. */
@@ -430,6 +430,16 @@ interface ClawOpsAgentOptions {
     logger?: Logger;
     /** Tool 실행 관련 설정. */
     toolConfig?: ToolConfig;
+    /**
+     * Gain applied to inbound audio (caller → AI). 1.0 = pass-through (default), 0 = mute, 2.0 = 2x amplify.
+     * AI/STT receive the gained audio, and recording captures it post-gain.
+     */
+    rxGain?: number;
+    /**
+     * Gain applied to outbound audio (AI → caller). 1.0 = pass-through (default), 0 = mute, 2.0 = 2x amplify.
+     * The caller hears the gained audio, and recording captures it post-gain.
+     */
+    txGain?: number;
 }
 declare class ClawOpsAgent {
     private _apiKey;
@@ -454,7 +464,10 @@ declare class ClawOpsAgent {
     private _pipelineLog;
     private _isPipelineSession;
     private _holdAudioChunks;
+    private _rxGain;
+    private _txGain;
     constructor(options: ClawOpsAgentOptions);
+    private static _validateGain;
     /**
      * Register a function tool.
      *
@@ -493,6 +506,14 @@ declare class ClawOpsAgent {
     private _handleRinging;
     private _handleFailed;
     private _onDtmfEvent;
+    /**
+     * _startCallSession 의 예외를 잡아 control WS 로 call.session_failed 전송한다.
+     *
+     * OpenAI/Gemini API 키 누락 등 session.start() 단계 실패는 media WS connect 에
+     * 도달하지 못해 call-engine 이 30 초간 무음 통화를 유지하게 만든다. 서버에 즉시
+     * 알려서 fail-fast 시키고 _activeSessions 에서 정리한다.
+     */
+    private _safeStartCallSession;
     private _startCallSession;
 }
 
@@ -584,17 +605,18 @@ declare class AudioRecorder {
     private _inWritten;
     private _outWritten;
     private _mixWritten;
-    private _startTime;
     private _started;
+    private _baseTs;
+    private _outCursor;
     private _log;
     setLogger(logger: Logger): void;
     constructor(recordingPath: string, callId: string);
     start(): void;
-    private _expectedBytes;
+    private _timestampToBytes;
     private _padSilence;
     private _writeToMix;
-    writeInbound(pcm16_8k: Buffer): void;
-    writeOutbound(pcm16_8k: Buffer): void;
+    writeInbound(pcm16_8k: Buffer, mediaTsMs?: number): void;
+    writeOutbound(pcm16_8k: Buffer, mediaTsMs?: number): void;
     stop(): void;
 }
 
@@ -679,7 +701,7 @@ interface OpenAIRealtimeOptions {
     apiKey?: string;
     /** System prompt / instructions for the AI. */
     systemPrompt?: string;
-    /** Model to use. Default: 'gpt-realtime-1.5' */
+    /** Model to use. Default: 'gpt-realtime-2' */
     model?: string;
     /** Voice ID. Default: 'marin' */
     voice?: string;
@@ -728,7 +750,7 @@ declare class OpenAIRealtime implements Session {
     setHoldAudio(chunks: Buffer[]): void;
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     feedDtmf(digits: string): Promise<void>;
-    feedAudio(audio: Buffer): void;
+    feedAudio(audio: Buffer, timestamp?: number): void;
     stop(): Promise<void>;
     private _sendSessionUpdate;
     private _handleMessage;

package/dist/agent/index.js

@@ -1,4 +1,4 @@
-import { DEFAULT_BASE_URL, AgentError, AgentConnectionError, VERSION } from '../chunk-N5EKKQVO.js';
+import { DEFAULT_BASE_URL, AgentError, AgentConnectionError, VERSION } from '../chunk-B3SD2KKR.js';
 import pino from 'pino';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -304,6 +304,27 @@ function ulawToPcm16(ulaw) {
   }
   return out;
 }
+function applyPcm16Gain(pcm, gain) {
+  if (!pcm.length) return Buffer.alloc(0);
+  if (gain === 1) return pcm;
+  if (!Number.isFinite(gain) || gain < 0) {
+    throw new Error("gain must be a finite number >= 0");
+  }
+  const nSamples = pcm.length >> 1;
+  const out = Buffer.alloc(nSamples * 2);
+  for (let i = 0; i < nSamples; i++) {
+    let value = Math.round(pcm.readInt16LE(i * 2) * gain);
+    if (value > 32767) value = 32767;
+    else if (value < -32768) value = -32768;
+    out.writeInt16LE(value, i * 2);
+  }
+  return out;
+}
+function applyUlawGain(ulaw, gain) {
+  if (!ulaw.length) return Buffer.alloc(0);
+  if (gain === 1) return ulaw;
+  return pcm16ToUlaw(applyPcm16Gain(ulawToPcm16(ulaw), gain));
+}
 function resamplePcm16(pcm, fromRate, toRate) {
   if (fromRate === toRate || !pcm.length) return pcm;
   const nSamples = pcm.length >> 1;
@@ -892,8 +913,9 @@ var AudioRecorder = class {
   _inWritten = 0;
   _outWritten = 0;
   _mixWritten = 0;
-  _startTime = 0;
   _started = false;
+  _baseTs = null;
+  _outCursor = 0;
   _log = NOOP_LOGGER;
   setLogger(logger) {
     this._log = logger;
@@ -910,17 +932,18 @@ var AudioRecorder = class {
     fs.writeSync(this._fdIn, header);
     fs.writeSync(this._fdOut, header);
     fs.writeSync(this._fdMix, header);
-    this._startTime = performance.now();
     this._started = true;
     this._log.info("Recording started: %s", this._dir);
   }
-  _expectedBytes() {
-    const elapsed = (performance.now() - this._startTime) / 1e3;
-    return Math.floor(elapsed * BYTES_PER_SECOND);
+  _timestampToBytes(mediaTsMs) {
+    if (this._baseTs === null) {
+      this._baseTs = mediaTsMs;
+    }
+    const target = Math.floor((mediaTsMs - this._baseTs) * BYTES_PER_SECOND / 1e3);
+    return Math.max(0, target - target % 2);
   }
-  _padSilence(fd, written) {
-    const expected = this._expectedBytes();
-    let gap = expected - written;
+  _padSilence(fd, written, target) {
+    let gap = target - written;
     if (gap <= 0) return 0;
     gap = gap - gap % 2;
     if (gap > 0) {
@@ -930,9 +953,12 @@ var AudioRecorder = class {
   }
   _writeToMix(data, trackPos) {
     if (this._fdMix === null) return;
+    data = data.subarray(0, data.length - data.length % 2);
+    if (data.length === 0) return;
     const filePos = 44 + trackPos;
     if (trackPos < this._mixWritten) {
-      const overlap = Math.min(data.length, this._mixWritten - trackPos);
+      let overlap = Math.min(data.length, this._mixWritten - trackPos);
+      overlap = overlap - overlap % 2;
       const existing = Buffer.alloc(overlap);
       fs.readSync(this._fdMix, existing, 0, overlap, filePos);
       const mixed = mixSamples(existing, data.subarray(0, overlap));
@@ -955,10 +981,13 @@ var AudioRecorder = class {
       this._mixWritten += data.length;
     }
   }
-  writeInbound(pcm16_8k) {
+  writeInbound(pcm16_8k, mediaTsMs = 0) {
     if (!this._started || this._fdIn === null) return;
     try {
-      const gap = this._padSilence(this._fdIn, this._inWritten);
+      pcm16_8k = pcm16_8k.subarray(0, pcm16_8k.length - pcm16_8k.length % 2);
+      if (pcm16_8k.length === 0) return;
+      const target = this._timestampToBytes(mediaTsMs);
+      const gap = this._padSilence(this._fdIn, this._inWritten, target);
       this._inWritten += gap;
       const posBefore = this._inWritten;
       fs.writeSync(this._fdIn, pcm16_8k);
@@ -968,14 +997,21 @@ var AudioRecorder = class {
       this._log.error({ err }, "Recording write error (inbound)");
     }
   }
-  writeOutbound(pcm16_8k) {
+  writeOutbound(pcm16_8k, mediaTsMs) {
     if (!this._started || this._fdOut === null) return;
     try {
-      const gap = this._padSilence(this._fdOut, this._outWritten);
+      pcm16_8k = pcm16_8k.subarray(0, pcm16_8k.length - pcm16_8k.length % 2);
+      if (pcm16_8k.length === 0) return;
+      let target = this._outCursor;
+      if (mediaTsMs !== void 0) {
+        target = Math.max(target, this._timestampToBytes(mediaTsMs));
+      }
+      const gap = this._padSilence(this._fdOut, this._outWritten, target);
       this._outWritten += gap;
       const posBefore = this._outWritten;
       fs.writeSync(this._fdOut, pcm16_8k);
       this._outWritten += pcm16_8k.length;
+      this._outCursor = this._outWritten;
       this._writeToMix(pcm16_8k, posBefore);
     } catch (err) {
       this._log.error({ err }, "Recording write error (outbound)");
@@ -1671,7 +1707,7 @@ var ATTR_CALL_DIRECTION = "clawops.call.direction";
 var ATTR_AGENT_ID = "clawops.agent.id";
 
 // src/agent/agent.ts
-var ClawOpsAgent = class {
+var ClawOpsAgent = class _ClawOpsAgent {
   _apiKey;
   _accountId;
   _baseUrl;
@@ -1694,6 +1730,8 @@ var ClawOpsAgent = class {
   _pipelineLog;
   _isPipelineSession = false;
   _holdAudioChunks = null;
+  _rxGain;
+  _txGain;
   constructor(options) {
     this._apiKey = options.apiKey ?? process.env["CLAWOPS_API_KEY"] ?? "";
     this._accountId = options.accountId ?? process.env["CLAWOPS_ACCOUNT_ID"] ?? "";
@@ -1705,6 +1743,8 @@ var ClawOpsAgent = class {
     this._mcpServers = options.mcpServers ?? [];
     this._builtinTools = resolveBuiltinTools(options.builtinTools ?? "all" /* ALL */);
     this._passiveDtmfDebounceMs = options.passiveDtmfDebounceMs ?? 500;
+    this._rxGain = _ClawOpsAgent._validateGain("rxGain", options.rxGain ?? 1);
+    this._txGain = _ClawOpsAgent._validateGain("txGain", options.txGain ?? 1);
     if (options.tracing) {
       setTracingConfig(options.tracing);
     }
@@ -1715,6 +1755,12 @@ var ClawOpsAgent = class {
       this._holdAudioChunks = loadHoldAudio(options.toolConfig.holdAudio);
     }
   }
+  static _validateGain(name, gain) {
+    if (typeof gain !== "number" || !Number.isFinite(gain) || gain < 0) {
+      throw new AgentError(`${name}=${gain} must be a finite number >= 0`);
+    }
+    return gain;
+  }
   /**
    * Register a function tool.
    *
@@ -1882,9 +1928,7 @@ var ClawOpsAgent = class {
       this._controlWs.send({ event: "call.accept", callId });
     }
     if (mediaUrl) {
-      this._startCallSession(session, mediaUrl).catch((err) => {
-        this._log.error({ err }, "Call session error: %s", callId);
-      });
+      this._safeStartCallSession(session, mediaUrl, callId);
     }
   }
   _handleEnded(event) {
@@ -1918,9 +1962,7 @@ var ClawOpsAgent = class {
     }
     if (mediaUrl) {
       this._log.info("Outbound call answered: %s -> %s (%s)", this._fromNumber, session.toNumber, callId);
-      this._startCallSession(session, mediaUrl).catch((err) => {
-        this._log.error({ err }, "Call session error: %s", callId);
-      });
+      this._safeStartCallSession(session, mediaUrl, callId);
     }
   }
   _handleRinging(event) {
@@ -1964,6 +2006,32 @@ var ClawOpsAgent = class {
       }
     }, this._passiveDtmfDebounceMs);
   }
+  /**
+   * _startCallSession 의 예외를 잡아 control WS 로 call.session_failed 전송한다.
+   *
+   * OpenAI/Gemini API 키 누락 등 session.start() 단계 실패는 media WS connect 에
+   * 도달하지 못해 call-engine 이 30 초간 무음 통화를 유지하게 만든다. 서버에 즉시
+   * 알려서 fail-fast 시키고 _activeSessions 에서 정리한다.
+   */
+  _safeStartCallSession(session, mediaWsUrl, callId) {
+    this._startCallSession(session, mediaWsUrl).catch((err) => {
+      const error = err;
+      this._log.error({ err }, "Session start failed for %s", callId);
+      if (this._controlWs) {
+        try {
+          this._controlWs.send({
+            event: "call.session_failed",
+            callId,
+            reason: error?.name ?? "Error",
+            message: error?.message ?? String(err)
+          });
+        } catch {
+        }
+      }
+      this._activeSessions.delete(callId);
+      this._callSessions.delete(callId);
+    });
+  }
   async _startCallSession(session, mediaWsUrl) {
     await withSpan(
       "clawops.call_session",
@@ -1997,9 +2065,14 @@ var ClawOpsAgent = class {
         }
         const mediaWs = new MediaWebSocket();
         mediaWs.setLogger(this._log);
+        let latestMediaTs = 0;
         session._bindTransport(
           (audio) => {
-            mediaWs.sendAudio(audio.toString("base64"));
+            const gained = applyUlawGain(audio, this._txGain);
+            if (recorder) {
+              recorder.writeOutbound(ulawToPcm16(gained), latestMediaTs);
+            }
+            mediaWs.sendAudio(gained.toString("base64"));
             session.recordFirstResponse();
           },
           () => {
@@ -2036,12 +2109,14 @@ var ClawOpsAgent = class {
           sessionHandler.setHoldAudio(this._holdAudioChunks);
         }
         this._callSessions.set(session.callId, sessionHandler);
-        mediaWs.onAudio((ulawAudio, _timestamp) => {
-          if (sessionHandler) {
-            sessionHandler.feedAudio(ulawAudio);
-          }
+        mediaWs.onAudio((ulawAudio, timestamp) => {
+          latestMediaTs = timestamp;
+          const gained = applyUlawGain(ulawAudio, this._rxGain);
           if (recorder) {
-            recorder.writeInbound(ulawToPcm16(ulawAudio));
+            recorder.writeInbound(ulawToPcm16(gained), timestamp);
+          }
+          if (sessionHandler) {
+            sessionHandler.feedAudio(gained, timestamp);
           }
         });
         mediaWs.onDtmf((digit) => {
@@ -2512,10 +2587,6 @@ var PipelineSession = class {
         sampleRate: this._sampleRate
       })) {
         if (!this._running || !this._speaking) break;
-        if (this._recorder) {
-          const pcm8k2 = this._sampleRate !== 8e3 ? resamplePcm16(audioChunk, this._sampleRate, 8e3) : audioChunk;
-          this._recorder.writeOutbound(pcm8k2);
-        }
         const pcm8k = resamplePcm16(audioChunk, this._sampleRate, 8e3);
         const ulaw = pcm16ToUlaw(pcm8k);
         for (let off = 0; off < ulaw.length; off += 160) {
@@ -2584,8 +2655,13 @@ var OpenAIRealtime = class {
   _holdAudioChunks = null;
   constructor(options = {}) {
     this._apiKey = options.apiKey ?? process.env["OPENAI_API_KEY"] ?? "";
+    if (!this._apiKey) {
+      throw new Error(
+        "OpenAI API key is required. Set OPENAI_API_KEY env var or pass apiKey option."
+      );
+    }
     this._systemPrompt = options.systemPrompt ?? "";
-    this._model = options.model ?? "gpt-realtime-1.5";
+    this._model = options.model ?? "gpt-realtime-2";
     this._voice = options.voice ?? "marin";
     this._language = options.language ?? "ko";
     this._turnDetection = options.turnDetection !== void 0 ? options.turnDetection : { type: "semantic_vad", eagerness: "medium", interrupt_response: true };
@@ -2609,9 +2685,6 @@ var OpenAIRealtime = class {
     this._closed = false;
     this._playback = null;
     this._latestMediaTs = 0;
-    if (!this._apiKey) {
-      throw new Error("OpenAI API key is required. Set OPENAI_API_KEY or pass apiKey option.");
-    }
     const { WebSocket } = await import('ws');
     const url = `${OPENAI_REALTIME_URL}${this._model}`;
     this._ws = new WebSocket(url, {
@@ -2660,8 +2733,8 @@ var OpenAIRealtime = class {
     });
     this._send({ type: "response.create" });
   }
-  feedAudio(audio) {
-    this._latestMediaTs = Date.now();
+  feedAudio(audio, timestamp) {
+    this._latestMediaTs = timestamp ?? this._latestMediaTs;
     if (this._ws && this._ws.readyState === 1 && !this._closed) {
       this._send({
         type: "input_audio_buffer.append",
@@ -2772,7 +2845,7 @@ var OpenAIRealtime = class {
     if (this._playback === null) {
       this._playback = {
         itemId: msg["item_id"] || "",
-        startTs: this._latestMediaTs || Date.now(),
+        startTs: this._latestMediaTs,
         sentChunks: 0,
         generating: true,
         audioRemainder: Buffer.alloc(0)
@@ -2782,9 +2855,6 @@ var OpenAIRealtime = class {
     }
     const pb = this._playback;
     const ulaw = Buffer.from(msg["delta"], "base64");
-    if (this._recorder) {
-      this._recorder.writeOutbound(ulawToPcm16(ulaw));
-    }
     const combined = Buffer.concat([pb.audioRemainder, ulaw]);
     const chunkSize = 160;
     const fullEnd = Math.floor(combined.length / chunkSize) * chunkSize;
@@ -2808,7 +2878,7 @@ var OpenAIRealtime = class {
     if (pb === null) {
       return;
     }
-    const playedMs = Math.max(0, (this._latestMediaTs || Date.now()) - pb.startTs);
+    const playedMs = Math.max(0, this._latestMediaTs - pb.startTs);
     this._log.info(
       "[Interrupt] item=%s played=%dms total=%dms",
       pb.itemId,
@@ -3100,9 +3170,6 @@ var GeminiRealtime = class _GeminiRealtime {
   feedAudio(audio) {
     if (this._session && !this._closed) {
       const pcm8k = ulawToPcm16(audio);
-      if (this._recorder) {
-        this._recorder.writeInbound(pcm8k);
-      }
       const pcm16k = resamplePcm16(pcm8k, 8e3, 16e3);
       this._session.sendRealtimeInput({
         audio: {
@@ -3200,9 +3267,6 @@ var GeminiRealtime = class _GeminiRealtime {
   _handleAudioData(b64Data) {
     if (!this._call) return;
     const pcm24k = Buffer.from(b64Data, "base64");
-    if (this._recorder) {
-      this._recorder.writeOutbound(resamplePcm16(pcm24k, 24e3, 8e3));
-    }
     const pcm8k = resamplePcm16(pcm24k, 24e3, 8e3);
     const ulaw = pcm16ToUlaw(pcm8k);
     const combined = Buffer.concat([this._audioRemainder, ulaw]);