@teamlearners/clawops 0.30.0 → 0.32.0

package/dist/agent/index.d.cts

@@ -1,5 +1,5 @@
-import { F as FunctionTool, S as Session, B as BuiltinTool, C as CallSession, a as STT, L as LLM, T as TTS, b as ToolRegistry, c as SessionTelemetry, d as SpeechEvent, e as ConversationMessage, f as LLMChunk } from '../base-Cje1TDJi.cjs';
-export { g as CallDirection, h as CallStatus, O as OpenAIToolDefinition, i as ToolCallRequest, j as functionTool, z as zodToToolParams } from '../base-Cje1TDJi.cjs';
+import { F as FunctionTool, S as Session, B as BuiltinTool, C as CallSession, a as STT, L as LLM, T as TTS, b as ToolRegistry, c as SessionTelemetry, d as SpeechEvent, e as ConversationMessage, f as LLMChunk } from '../base-B6S9WQRN.cjs';
+export { g as CallDirection, h as CallStatus, O as OpenAIToolDefinition, i as ToolCallRequest, j as functionTool, z as zodToToolParams } from '../base-B6S9WQRN.cjs';
 import { Logger } from 'pino';
 export { Logger } from 'pino';
 import 'zod';
@@ -164,6 +164,8 @@ declare class ClawOpsAgent {
     private _recording;
     private _recordingPath;
     private _activeSessions;
+    /** 미디어 정리를 마친 통화가 서버 종료 프레임을 기다리는 자리. callId → resolve. */
+    private _terminalWaiters;
     private _builtinTools;
     private _passiveDtmfDebounceMs;
     private _passiveDtmfBuffer;
@@ -224,6 +226,17 @@ declare class ClawOpsAgent {
         machineDetection?: 'Enable' | 'Hangup';
     }): Promise<CallSession>;
     private _handleIncoming;
+    /**
+     * 서버 종료 프레임을 짧게 기다린다. 미디어 정리 직후에만 부른다.
+     *
+     * 왜 기다리나: `call_end` 는 인바운드 사용자가 통화 결과를 받는 **유일한 통로**인데, 서버는
+     * 미디어 WS 를 먼저 닫고 자원 정리를 마친 뒤에야 control 종료 프레임을 보낸다. 안 기다리면
+     * 그 핸들러 안에서 `endedDuration` 은 영영 null 이다.
+     *
+     * 상한을 다 쓰는 경우는 제어 연결이 죽어 프레임이 아예 안 오는 때뿐이다 — 그 프레임은
+     * 예전부터 늘 오던 것이고(이번에 바뀐 건 내용뿐), 정상 경로에서는 밀리초 안에 풀린다.
+     */
+    private _awaitServerTerminal;
     private _handleEnded;
     /**
      * Drop prewarm bookkeeping for a callId. Used on hangup/failure paths.

package/dist/agent/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FunctionTool, S as Session, B as BuiltinTool, C as CallSession, a as STT, L as LLM, T as TTS, b as ToolRegistry, c as SessionTelemetry, d as SpeechEvent, e as ConversationMessage, f as LLMChunk } from '../base-Cje1TDJi.js';
-export { g as CallDirection, h as CallStatus, O as OpenAIToolDefinition, i as ToolCallRequest, j as functionTool, z as zodToToolParams } from '../base-Cje1TDJi.js';
+import { F as FunctionTool, S as Session, B as BuiltinTool, C as CallSession, a as STT, L as LLM, T as TTS, b as ToolRegistry, c as SessionTelemetry, d as SpeechEvent, e as ConversationMessage, f as LLMChunk } from '../base-B6S9WQRN.js';
+export { g as CallDirection, h as CallStatus, O as OpenAIToolDefinition, i as ToolCallRequest, j as functionTool, z as zodToToolParams } from '../base-B6S9WQRN.js';
 import { Logger } from 'pino';
 export { Logger } from 'pino';
 import 'zod';
@@ -164,6 +164,8 @@ declare class ClawOpsAgent {
     private _recording;
     private _recordingPath;
     private _activeSessions;
+    /** 미디어 정리를 마친 통화가 서버 종료 프레임을 기다리는 자리. callId → resolve. */
+    private _terminalWaiters;
     private _builtinTools;
     private _passiveDtmfDebounceMs;
     private _passiveDtmfBuffer;
@@ -224,6 +226,17 @@ declare class ClawOpsAgent {
         machineDetection?: 'Enable' | 'Hangup';
     }): Promise<CallSession>;
     private _handleIncoming;
+    /**
+     * 서버 종료 프레임을 짧게 기다린다. 미디어 정리 직후에만 부른다.
+     *
+     * 왜 기다리나: `call_end` 는 인바운드 사용자가 통화 결과를 받는 **유일한 통로**인데, 서버는
+     * 미디어 WS 를 먼저 닫고 자원 정리를 마친 뒤에야 control 종료 프레임을 보낸다. 안 기다리면
+     * 그 핸들러 안에서 `endedDuration` 은 영영 null 이다.
+     *
+     * 상한을 다 쓰는 경우는 제어 연결이 죽어 프레임이 아예 안 오는 때뿐이다 — 그 프레임은
+     * 예전부터 늘 오던 것이고(이번에 바뀐 건 내용뿐), 정상 경로에서는 밀리초 안에 풀린다.
+     */
+    private _awaitServerTerminal;
     private _handleEnded;
     /**
      * Drop prewarm bookkeeping for a callId. Used on hangup/failure paths.

package/dist/agent/index.js

@@ -1,6 +1,6 @@
-import { DEFAULT_BASE_URL, AgentError, AgentConnectionError, VERSION } from '../chunk-622J6BJ5.js';
-import { NOOP_LOGGER, resolveBuiltinTools, createAgentLogger, createPipelineLogger, BufferingCall, attachBuffered, ulawToPcm16, resamplePcm16, getBuiltinToolSchemas, BUILTIN_TOOL_NAMES, executeBuiltinTool, CALL_NOT_READY_RESULT, pcm16ToUlaw, applyUlawGain } from '../chunk-WKGTY7QT.js';
-export { BUILTIN_TOOL_NAMES, BuiltinTool, DECODE_TABLE, createAgentLogger, createPipelineLogger, executeBuiltinTool, getBuiltinToolSchemas, isBuiltinTool, pcm16ToUlaw, resamplePcm16, ulawToPcm16 } from '../chunk-WKGTY7QT.js';
+import { DEFAULT_BASE_URL, AgentError, AgentConnectionError, VERSION } from '../chunk-MXJ2LM6R.js';
+import { NOOP_LOGGER, resolveBuiltinTools, createAgentLogger, createPipelineLogger, BufferingCall, attachBuffered, ulawToPcm16, resamplePcm16, getBuiltinToolSchemas, BUILTIN_TOOL_NAMES, executeBuiltinTool, CALL_NOT_READY_RESULT, pcm16ToUlaw, applyUlawGain } from '../chunk-4YLSDMLL.js';
+export { BUILTIN_TOOL_NAMES, BuiltinTool, DECODE_TABLE, createAgentLogger, createPipelineLogger, executeBuiltinTool, getBuiltinToolSchemas, isBuiltinTool, pcm16ToUlaw, resamplePcm16, ulawToPcm16 } from '../chunk-4YLSDMLL.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import os from 'os';
@@ -740,6 +740,7 @@ var CallSession = class {
   metadata;
   _status;
   _endedStatus = null;
+  _endedDuration = null;
   _sendAudioFn = null;
   _clearAudioFn = null;
   _hangupFn = null;
@@ -799,9 +800,22 @@ var CallSession = class {
   get endedStatus() {
     return this._endedStatus;
   }
+  /**
+   * 서버가 확정한 통화 시간(초). 통화가 끝나기 전에는 `null`.
+   *
+   * ⚠️ `duration` 과 다르다 — 그쪽은 SDK 가 로컬 시계로 재는 **경과 시간**이라 통화 중에도
+   * 읽히고, 세션이 붙기 전후의 오차를 포함한다. 기록·정산에 쓸 값은 이쪽이다.
+   */
+  get endedDuration() {
+    return this._endedDuration;
+  }
   get duration() {
     return (Date.now() - this.startTime.getTime()) / 1e3;
   }
+  /** @internal 서버가 통보한 통화 시간을 확정한다. */
+  _setEndedDuration(seconds) {
+    this._endedDuration = seconds;
+  }
   get metrics() {
     return this._metrics;
   }
@@ -929,11 +943,27 @@ var CallSession = class {
    * directly to a SIP endpoint without going through the PSTN carrier. Requires the
    * account to have an active `sip_trunk` add-on; otherwise the transfer fails and
    * the call continues with the AI (result `{ status: 'failed', ... }`).
+   *
+   * 전환받는 쪽에 표시되는 발신번호는 기본이 **계정 보유번호**(인바운드면 착신 070)다.
+   *
+   * `callerIdMode: 'original'` 은 인바운드 통화의 **원 발신자 번호를 승계하려는 선호**다.
+   * 승계할 수 없는 통화(KCT 직결 인입이 아니거나 국내 번호로 정규화되지 않는 발신번호)면
+   * 조용히 계정 보유번호로 내려앉고 **전환은 그대로 성사된다**.
+   *
+   * `callerId` 는 번호를 직접 주는 **지시**라 성격이 다르다. 허용 범위(계정 보유번호 또는
+   * KCT 직결 인입의 원 발신자)를 벗어나면 전환 자체가 실패한다. 둘 다 주면 `callerId` 가
+   * 이기고 `callerIdMode` 는 무시된다 — 우선순위 판단은 서버가 한다.
    */
   async transfer(to, options) {
     if (!this._transferFn) {
       throw new Error("transfer not available");
     }
+    const callerIdMode = options?.callerIdMode;
+    if (callerIdMode !== void 0 && callerIdMode !== "account" && callerIdMode !== "original") {
+      throw new Error(
+        `callerIdMode must be 'account' or 'original', got ${JSON.stringify(callerIdMode)}`
+      );
+    }
     return this._transferFn({
       to,
       destinationType: options?.destinationType ?? "pstn",
@@ -943,7 +973,9 @@ var CallSession = class {
       whisper: options?.whisper ?? null,
       context: options?.context ?? null,
       callerId: options?.callerId ?? null,
-      timeout: options?.timeout ?? 30
+      timeout: options?.timeout ?? 30,
+      // 안 주면 키를 붙이지 않는다 — 구 서버와 기존 동작을 그대로 둔다(additive).
+      ...callerIdMode !== void 0 ? { callerIdMode } : {}
     });
   }
   /** Register an event handler. */
@@ -1373,6 +1405,7 @@ var ATTR_CALL_DIRECTION = "clawops.call.direction";
 var ATTR_AGENT_ID = "clawops.agent.id";
 
 // src/agent/agent.ts
+var TERMINAL_FRAME_GRACE_MS = 2e3;
 var ClawOpsAgent = class _ClawOpsAgent {
   _apiKey;
   _accountId;
@@ -1386,6 +1419,8 @@ var ClawOpsAgent = class _ClawOpsAgent {
   _recording;
   _recordingPath;
   _activeSessions = /* @__PURE__ */ new Map();
+  /** 미디어 정리를 마친 통화가 서버 종료 프레임을 기다리는 자리. callId → resolve. */
+  _terminalWaiters = /* @__PURE__ */ new Map();
   _builtinTools;
   _passiveDtmfDebounceMs;
   _passiveDtmfBuffer = [];
@@ -1535,6 +1570,7 @@ var ClawOpsAgent = class _ClawOpsAgent {
       this._controlWs.close();
       this._controlWs = null;
     }
+    for (const wake of [...this._terminalWaiters.values()]) wake();
     for (const session of this._activeSessions.values()) {
       session._markEnded();
     }
@@ -1622,12 +1658,43 @@ var ClawOpsAgent = class _ClawOpsAgent {
       this._safeStartCallSession(session, mediaUrl, callId);
     }
   }
+  /**
+   * 서버 종료 프레임을 짧게 기다린다. 미디어 정리 직후에만 부른다.
+   *
+   * 왜 기다리나: `call_end` 는 인바운드 사용자가 통화 결과를 받는 **유일한 통로**인데, 서버는
+   * 미디어 WS 를 먼저 닫고 자원 정리를 마친 뒤에야 control 종료 프레임을 보낸다. 안 기다리면
+   * 그 핸들러 안에서 `endedDuration` 은 영영 null 이다.
+   *
+   * 상한을 다 쓰는 경우는 제어 연결이 죽어 프레임이 아예 안 오는 때뿐이다 — 그 프레임은
+   * 예전부터 늘 오던 것이고(이번에 바뀐 건 내용뿐), 정상 경로에서는 밀리초 안에 풀린다.
+   */
+  async _awaitServerTerminal(session) {
+    if (session.endedDuration !== null) return;
+    await new Promise((resolve) => {
+      const done = () => {
+        clearTimeout(timer);
+        this._terminalWaiters.delete(session.callId);
+        resolve();
+      };
+      const timer = setTimeout(() => {
+        this._log.debug(
+          "\uC11C\uBC84 \uC885\uB8CC \uD504\uB808\uC784\uC774 %dms \uC548\uC5D0 \uC624\uC9C0 \uC54A\uC558\uB2E4 \u2014 endedDuration \uC5C6\uC774 \uC9C4\uD589: %s",
+          TERMINAL_FRAME_GRACE_MS,
+          session.callId
+        );
+        done();
+      }, TERMINAL_FRAME_GRACE_MS);
+      this._terminalWaiters.set(session.callId, done);
+    });
+  }
   _handleEnded(event) {
     const callId = event["callId"];
     const status = event["status"] || "completed";
+    const endedDuration = event["duration"];
     const session = this._activeSessions.get(callId);
     if (session) {
       this._log.info("Call ended (server): %s (status=%s)", callId, status);
+      if (typeof endedDuration === "number") session._setEndedDuration(endedDuration);
       if (status !== "completed") {
         this._log.info("Outbound call not connected: %s (%s)", callId, status);
         session._emit("call_failed", status);
@@ -1635,6 +1702,7 @@ var ClawOpsAgent = class _ClawOpsAgent {
       session._markEnded(status);
       this._activeSessions.delete(callId);
     }
+    this._terminalWaiters.get(callId)?.();
     void this._cleanupPrewarm(callId);
   }
   /**
@@ -1989,6 +2057,7 @@ var ClawOpsAgent = class _ClawOpsAgent {
             this._controlWs?.send({ event: "call.metrics", callId: session.callId, metrics: session.metrics });
           } catch {
           }
+          await this._awaitServerTerminal(session);
           session._emit("call_end");
           session._markEnded();
           this._activeSessions.delete(session.callId);