@teamlearners/clawops 0.40.0 → 0.42.0

package/dist/agent/index.d.cts

@@ -127,6 +127,16 @@ interface ClawOpsAgentOptions {
     logger?: Logger;
     /** Tool 실행 관련 설정. */
     toolConfig?: ToolConfig;
+    /**
+     * Called when another process takes over this number's control connection — the normal
+     * middle of a rolling deploy, seen from the instance being replaced. New calls already go
+     * elsewhere; finish the calls still in flight and exit. `serve()` handles this for you;
+     * wire this only if you drive `connect()` yourself, and call `drain()` from it.
+     */
+    onTakenOver?: (info: {
+        code: number;
+        reason: string;
+    }) => void;
     /**
      * 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.
@@ -164,6 +174,17 @@ declare class ClawOpsAgent {
     private _recording;
     private _recordingPath;
     private _activeSessions;
+    /** Set once the server hands this number to another process (rolling deploy takeover). */
+    private _takenOver;
+    /**
+     * Set once we deliberately give up the control connection (`drain()`/`disconnect()`).
+     * Distinct from `_controlWs === null`, which also covers "never connected": only after a
+     * hand-back is it certain that no server terminal frame can still arrive.
+     */
+    private _controlGivenUp;
+    /** serve()'s stop hook, so takeover can end the block the same way a signal does. */
+    private _stopServe;
+    private _onTakenOver?;
     /** 미디어 정리를 마친 통화가 서버 종료 프레임을 기다리는 자리. callId → resolve. */
     private _terminalWaiters;
     private _builtinTools;
@@ -206,10 +227,64 @@ declare class ClawOpsAgent {
     /** Connect to the ClawOps platform and start listening for calls. */
     connect(): Promise<void>;
     /**
-     * Connect and block until disconnected.
-     * Convenience method for simple agent scripts.
+     * Connect and block until it is time to stop.
+     *
+     * Returns on SIGINT/SIGTERM, or when another process takes over this number — in every case
+     * after `drain()` has let in-flight calls finish. A second signal skips the wait and cuts them.
+     *
+     * Because it returns on takeover, a rolling deploy needs no shutdown wiring: bring the new
+     * instance up, and the old one hands over the number, finishes the calls it still has, and
+     * exits on its own. Give the platform a grace period longer than the drain timeout
+     * (k8s `terminationGracePeriodSeconds`, ECS `stopTimeout`) so it does not SIGKILL mid-drain.
+     *
+     * @param options.drainTimeoutMs Passed through to `drain()`.
+     */
+    serve(options?: {
+        drainTimeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * The server handed this number's control connection to another process.
+     *
+     * Nothing here is an error: it is the normal middle of a rolling deploy, seen from the
+     * instance being replaced. New calls already go to the new process, so all that is left is
+     * to finish the calls we still hold and get out of the way. `serve()` does that by returning;
+     * callers who wired `connect()` themselves get `onTakenOver` and should call `drain()`.
      */
-    serve(): Promise<void>;
+    private _handleTakenOver;
+    /** Whether another process has taken over this number's control connection. */
+    get takenOver(): boolean;
+    /**
+     * Stop accepting new calls, let the ones already in progress finish, then disconnect.
+     *
+     * This is what a rolling deploy needs. `disconnect()` cuts live calls mid-sentence, which is
+     * correct when you mean "stop now" and wrong when you mean "hand over". The two are separated
+     * because only the caller knows which one a SIGTERM meant.
+     *
+     * It works because control and media are different connections. Closing the control WebSocket
+     * only gives up this number's delivery slot — the server stops sending us `call.incoming` and
+     * routes new calls to whichever process holds the slot next. Calls already up keep streaming
+     * over their own per-call media connections, which nothing here touches, and each one tears
+     * itself down normally when the caller hangs up.
+     *
+     * Deploy shape this is built for: start the new instance, let it take the slot (the server
+     * hands it over and tells us not to reconnect), then drain the old one. New calls go to the
+     * new instance from the moment it connects; in-flight calls end on the old one. No gap.
+     *
+     * One thing is given up: `endedDuration` on `call_end`. That figure rides the control
+     * connection we just closed, so calls finishing during a drain report a null duration.
+     *
+     * @param options.timeoutMs How long to wait for in-flight calls. Default 120s. Calls still
+     *   running when it expires are ended the way `disconnect()` ends them. Keep the platform's
+     *   own grace period longer than this (k8s `terminationGracePeriodSeconds`, ECS
+     *   `stopTimeout`), or it will SIGKILL the process mid-drain and undo the point of draining.
+     * @returns How many calls ended on their own, and how many had to be cut short.
+     */
+    drain(options?: {
+        timeoutMs?: number;
+    }): Promise<{
+        completed: number;
+        forced: number;
+    }>;
     /** Disconnect from the platform. */
     disconnect(): Promise<void>;
     /**
@@ -288,6 +363,15 @@ interface ControlWsOptions {
     accountId: string;
     /** Phone number to register on. */
     number?: string;
+    /**
+     * Called when the server closes the connection with a code that means "do not reconnect"
+     * (the number was handed to another process, or is no longer owned by this account).
+     * Reconnection has already been abandoned by the time this fires.
+     */
+    onTerminalClose?: (info: {
+        code: number;
+        reason: string;
+    }) => void;
 }
 /**
  * Control event is a flat JSON object with an 'event' field.

package/dist/agent/index.d.ts

@@ -127,6 +127,16 @@ interface ClawOpsAgentOptions {
     logger?: Logger;
     /** Tool 실행 관련 설정. */
     toolConfig?: ToolConfig;
+    /**
+     * Called when another process takes over this number's control connection — the normal
+     * middle of a rolling deploy, seen from the instance being replaced. New calls already go
+     * elsewhere; finish the calls still in flight and exit. `serve()` handles this for you;
+     * wire this only if you drive `connect()` yourself, and call `drain()` from it.
+     */
+    onTakenOver?: (info: {
+        code: number;
+        reason: string;
+    }) => void;
     /**
      * 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.
@@ -164,6 +174,17 @@ declare class ClawOpsAgent {
     private _recording;
     private _recordingPath;
     private _activeSessions;
+    /** Set once the server hands this number to another process (rolling deploy takeover). */
+    private _takenOver;
+    /**
+     * Set once we deliberately give up the control connection (`drain()`/`disconnect()`).
+     * Distinct from `_controlWs === null`, which also covers "never connected": only after a
+     * hand-back is it certain that no server terminal frame can still arrive.
+     */
+    private _controlGivenUp;
+    /** serve()'s stop hook, so takeover can end the block the same way a signal does. */
+    private _stopServe;
+    private _onTakenOver?;
     /** 미디어 정리를 마친 통화가 서버 종료 프레임을 기다리는 자리. callId → resolve. */
     private _terminalWaiters;
     private _builtinTools;
@@ -206,10 +227,64 @@ declare class ClawOpsAgent {
     /** Connect to the ClawOps platform and start listening for calls. */
     connect(): Promise<void>;
     /**
-     * Connect and block until disconnected.
-     * Convenience method for simple agent scripts.
+     * Connect and block until it is time to stop.
+     *
+     * Returns on SIGINT/SIGTERM, or when another process takes over this number — in every case
+     * after `drain()` has let in-flight calls finish. A second signal skips the wait and cuts them.
+     *
+     * Because it returns on takeover, a rolling deploy needs no shutdown wiring: bring the new
+     * instance up, and the old one hands over the number, finishes the calls it still has, and
+     * exits on its own. Give the platform a grace period longer than the drain timeout
+     * (k8s `terminationGracePeriodSeconds`, ECS `stopTimeout`) so it does not SIGKILL mid-drain.
+     *
+     * @param options.drainTimeoutMs Passed through to `drain()`.
+     */
+    serve(options?: {
+        drainTimeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * The server handed this number's control connection to another process.
+     *
+     * Nothing here is an error: it is the normal middle of a rolling deploy, seen from the
+     * instance being replaced. New calls already go to the new process, so all that is left is
+     * to finish the calls we still hold and get out of the way. `serve()` does that by returning;
+     * callers who wired `connect()` themselves get `onTakenOver` and should call `drain()`.
      */
-    serve(): Promise<void>;
+    private _handleTakenOver;
+    /** Whether another process has taken over this number's control connection. */
+    get takenOver(): boolean;
+    /**
+     * Stop accepting new calls, let the ones already in progress finish, then disconnect.
+     *
+     * This is what a rolling deploy needs. `disconnect()` cuts live calls mid-sentence, which is
+     * correct when you mean "stop now" and wrong when you mean "hand over". The two are separated
+     * because only the caller knows which one a SIGTERM meant.
+     *
+     * It works because control and media are different connections. Closing the control WebSocket
+     * only gives up this number's delivery slot — the server stops sending us `call.incoming` and
+     * routes new calls to whichever process holds the slot next. Calls already up keep streaming
+     * over their own per-call media connections, which nothing here touches, and each one tears
+     * itself down normally when the caller hangs up.
+     *
+     * Deploy shape this is built for: start the new instance, let it take the slot (the server
+     * hands it over and tells us not to reconnect), then drain the old one. New calls go to the
+     * new instance from the moment it connects; in-flight calls end on the old one. No gap.
+     *
+     * One thing is given up: `endedDuration` on `call_end`. That figure rides the control
+     * connection we just closed, so calls finishing during a drain report a null duration.
+     *
+     * @param options.timeoutMs How long to wait for in-flight calls. Default 120s. Calls still
+     *   running when it expires are ended the way `disconnect()` ends them. Keep the platform's
+     *   own grace period longer than this (k8s `terminationGracePeriodSeconds`, ECS
+     *   `stopTimeout`), or it will SIGKILL the process mid-drain and undo the point of draining.
+     * @returns How many calls ended on their own, and how many had to be cut short.
+     */
+    drain(options?: {
+        timeoutMs?: number;
+    }): Promise<{
+        completed: number;
+        forced: number;
+    }>;
     /** Disconnect from the platform. */
     disconnect(): Promise<void>;
     /**
@@ -288,6 +363,15 @@ interface ControlWsOptions {
     accountId: string;
     /** Phone number to register on. */
     number?: string;
+    /**
+     * Called when the server closes the connection with a code that means "do not reconnect"
+     * (the number was handed to another process, or is no longer owned by this account).
+     * Reconnection has already been abandoned by the time this fires.
+     */
+    onTerminalClose?: (info: {
+        code: number;
+        reason: string;
+    }) => void;
 }
 /**
  * Control event is a flat JSON object with an 'event' field.

package/dist/agent/index.js

@@ -1,8 +1,8 @@
 import { DEFAULT_BASE_URL } from '../chunk-35XJNMFU.js';
 import { AgentError, AgentConnectionError } from '../chunk-SXXOAPMG.js';
-import { NOOP_LOGGER, resolveBuiltinTools, createAgentLogger, createPipelineLogger, getSdkInfo, CallSession, BufferingCall, attachBuffered, ulawToPcm16, resamplePcm16, getBuiltinToolSchemas, BUILTIN_TOOL_NAMES, executeBuiltinTool, CALL_NOT_READY_RESULT, pcm16ToUlaw, applyUlawGain } from '../chunk-AYSW63CJ.js';
-export { BUILTIN_TOOL_NAMES, BuiltinTool, CallSession, DECODE_TABLE, DtmfCollectorBusyError, createAgentLogger, createPipelineLogger, executeBuiltinTool, getBuiltinToolSchemas, isBuiltinTool, pcm16ToUlaw, resamplePcm16, ulawToPcm16 } from '../chunk-AYSW63CJ.js';
-import '../chunk-R6UEIVYE.js';
+import { NOOP_LOGGER, resolveBuiltinTools, createAgentLogger, createPipelineLogger, getSdkInfo, CallSession, BufferingCall, attachBuffered, ulawToPcm16, resamplePcm16, getBuiltinToolSchemas, BUILTIN_TOOL_NAMES, executeBuiltinTool, CALL_NOT_READY_RESULT, pcm16ToUlaw, applyUlawGain } from '../chunk-HJLF7U7U.js';
+export { BUILTIN_TOOL_NAMES, BuiltinTool, CallSession, DECODE_TABLE, DtmfCollectorBusyError, createAgentLogger, createPipelineLogger, executeBuiltinTool, getBuiltinToolSchemas, isBuiltinTool, pcm16ToUlaw, resamplePcm16, ulawToPcm16 } from '../chunk-HJLF7U7U.js';
+import '../chunk-XENRMYVS.js';
 import * as fs from 'fs';
 import * as path from 'path';
 
@@ -10,6 +10,9 @@ import * as path from 'path';
 var INITIAL_RECONNECT_DELAY = 1e3;
 var MAX_RECONNECT_DELAY = 3e4;
 var PING_TIMEOUT = 6e4;
+var CLOSE_REPLACED = 4409;
+var CLOSE_OWNERSHIP_LOST = 4403;
+var NON_RETRYABLE_CLOSE_CODES = /* @__PURE__ */ new Set([CLOSE_REPLACED, CLOSE_OWNERSHIP_LOST]);
 function buildControlWsUrl(options) {
   const scheme = options.baseUrl.startsWith("https") ? "wss" : "ws";
   const host = options.baseUrl.replace(/^https?:\/\//, "").replace(/\/$/, "");
@@ -131,11 +134,21 @@ var ControlWebSocket = class {
         this._log.warn("Control WS parse error");
       }
     });
-    ws.on("close", () => {
+    ws.on("close", (code, reason) => {
       this._clearPingTimer();
-      if (!this._closed) {
-        this._scheduleReconnect();
+      if (this._closed) return;
+      if (NON_RETRYABLE_CLOSE_CODES.has(code)) {
+        const text = reason?.toString() || "";
+        this._closed = true;
+        this._log.info(
+          "Control WS closed by server (%d %s) \u2014 not reconnecting: this number is now served elsewhere",
+          code,
+          text
+        );
+        this._options.onTerminalClose?.({ code, reason: text });
+        return;
       }
+      this._scheduleReconnect();
     });
     ws.on("error", (err) => {
       this._log.warn("Control WS error: %s", err.message);
@@ -1077,6 +1090,8 @@ var ATTR_AGENT_ID = "clawops.agent.id";
 
 // src/agent/agent.ts
 var TERMINAL_FRAME_GRACE_MS = 2e3;
+var DEFAULT_DRAIN_TIMEOUT_MS = 12e4;
+var DRAIN_POLL_INTERVAL_MS = 200;
 var ClawOpsAgent = class _ClawOpsAgent {
   _apiKey;
   _accountId;
@@ -1090,6 +1105,17 @@ var ClawOpsAgent = class _ClawOpsAgent {
   _recording;
   _recordingPath;
   _activeSessions = /* @__PURE__ */ new Map();
+  /** Set once the server hands this number to another process (rolling deploy takeover). */
+  _takenOver = false;
+  /**
+   * Set once we deliberately give up the control connection (`drain()`/`disconnect()`).
+   * Distinct from `_controlWs === null`, which also covers "never connected": only after a
+   * hand-back is it certain that no server terminal frame can still arrive.
+   */
+  _controlGivenUp = false;
+  /** serve()'s stop hook, so takeover can end the block the same way a signal does. */
+  _stopServe = null;
+  _onTakenOver;
   /** 미디어 정리를 마친 통화가 서버 종료 프레임을 기다리는 자리. callId → resolve. */
   _terminalWaiters = /* @__PURE__ */ new Map();
   _builtinTools;
@@ -1126,6 +1152,7 @@ var ClawOpsAgent = class _ClawOpsAgent {
     this._txGain = _ClawOpsAgent._validateGain("txGain", options.txGain ?? 1);
     this._prewarmEnabled = options.prewarmEnabled ?? true;
     this._machineDetection = options.machineDetection;
+    this._onTakenOver = options.onTakenOver;
     if (options.tracing) {
       setTracingConfig(options.tracing);
     }
@@ -1187,6 +1214,11 @@ var ClawOpsAgent = class _ClawOpsAgent {
   /** Connect to the ClawOps platform and start listening for calls. */
   async connect() {
     if (this._controlWs) return;
+    if (this._takenOver) {
+      throw new AgentError(
+        `${this._fromNumber} is now served by another process \u2014 reconnecting would evict it. Start a new agent process instead of reconnecting this one.`
+      );
+    }
     if (!this._apiKey) {
       throw new AgentError("API key is required. Set CLAWOPS_API_KEY or pass apiKey option.");
     }
@@ -1195,11 +1227,13 @@ var ClawOpsAgent = class _ClawOpsAgent {
         "Account ID is required. Set CLAWOPS_ACCOUNT_ID or pass accountId option."
       );
     }
+    this._controlGivenUp = false;
     this._controlWs = new ControlWebSocket({
       baseUrl: this._baseUrl,
       apiKey: this._apiKey,
       accountId: this._accountId,
-      number: this._fromNumber
+      number: this._fromNumber,
+      onTerminalClose: (info) => this._handleTakenOver(info)
     });
     this._controlWs.setLogger(this._log);
     this._controlWs.on("call.incoming", (event) => this._handleIncoming(event));
@@ -1222,21 +1256,140 @@ var ClawOpsAgent = class _ClawOpsAgent {
     this._log.info("ClawOpsAgent connected on %s", this._fromNumber);
   }
   /**
-   * Connect and block until disconnected.
-   * Convenience method for simple agent scripts.
+   * Connect and block until it is time to stop.
+   *
+   * Returns on SIGINT/SIGTERM, or when another process takes over this number — in every case
+   * after `drain()` has let in-flight calls finish. A second signal skips the wait and cuts them.
+   *
+   * Because it returns on takeover, a rolling deploy needs no shutdown wiring: bring the new
+   * instance up, and the old one hands over the number, finishes the calls it still has, and
+   * exits on its own. Give the platform a grace period longer than the drain timeout
+   * (k8s `terminationGracePeriodSeconds`, ECS `stopTimeout`) so it does not SIGKILL mid-drain.
+   *
+   * @param options.drainTimeoutMs Passed through to `drain()`.
    */
-  async serve() {
+  async serve(options) {
     await this.connect();
     return new Promise((resolve) => {
-      const shutdown = () => {
-        this.disconnect().then(resolve).catch(() => resolve());
+      let stopping = false;
+      let signals = 0;
+      const finish = () => {
+        process.off("SIGINT", onSigint);
+        process.off("SIGTERM", onSigterm);
+        this._stopServe = null;
+        resolve();
+      };
+      const stop = (why) => {
+        if (stopping) return;
+        stopping = true;
+        this._log.info("Stopping (%s) \u2014 draining in-flight calls", why);
+        this.drain({ timeoutMs: options?.drainTimeoutMs }).then(finish).catch((err) => {
+          this._log.error({ err }, "Drain failed");
+          finish();
+        });
+      };
+      const onSignal = (why) => {
+        signals += 1;
+        if (signals >= 2) {
+          this._log.warn("Second stop signal (%s) \u2014 ending calls immediately", why);
+          void this.disconnect().finally(finish);
+          return;
+        }
+        if (stopping) {
+          this._log.info(
+            "%s arrived while draining \u2014 still waiting for in-flight calls (signal again to cut)",
+            why
+          );
+          return;
+        }
+        stop(why);
       };
-      process.on("SIGINT", shutdown);
-      process.on("SIGTERM", shutdown);
+      const onSigint = () => onSignal("SIGINT");
+      const onSigterm = () => onSignal("SIGTERM");
+      this._stopServe = stop;
+      process.on("SIGINT", onSigint);
+      process.on("SIGTERM", onSigterm);
     });
   }
+  /**
+   * The server handed this number's control connection to another process.
+   *
+   * Nothing here is an error: it is the normal middle of a rolling deploy, seen from the
+   * instance being replaced. New calls already go to the new process, so all that is left is
+   * to finish the calls we still hold and get out of the way. `serve()` does that by returning;
+   * callers who wired `connect()` themselves get `onTakenOver` and should call `drain()`.
+   */
+  _handleTakenOver(info) {
+    this._takenOver = true;
+    this._log.info(
+      "Another process now serves %s (close %d) \u2014 handing over",
+      this._fromNumber,
+      info.code
+    );
+    this._onTakenOver?.(info);
+    this._stopServe?.("taken over");
+  }
+  /** Whether another process has taken over this number's control connection. */
+  get takenOver() {
+    return this._takenOver;
+  }
+  /**
+   * Stop accepting new calls, let the ones already in progress finish, then disconnect.
+   *
+   * This is what a rolling deploy needs. `disconnect()` cuts live calls mid-sentence, which is
+   * correct when you mean "stop now" and wrong when you mean "hand over". The two are separated
+   * because only the caller knows which one a SIGTERM meant.
+   *
+   * It works because control and media are different connections. Closing the control WebSocket
+   * only gives up this number's delivery slot — the server stops sending us `call.incoming` and
+   * routes new calls to whichever process holds the slot next. Calls already up keep streaming
+   * over their own per-call media connections, which nothing here touches, and each one tears
+   * itself down normally when the caller hangs up.
+   *
+   * Deploy shape this is built for: start the new instance, let it take the slot (the server
+   * hands it over and tells us not to reconnect), then drain the old one. New calls go to the
+   * new instance from the moment it connects; in-flight calls end on the old one. No gap.
+   *
+   * One thing is given up: `endedDuration` on `call_end`. That figure rides the control
+   * connection we just closed, so calls finishing during a drain report a null duration.
+   *
+   * @param options.timeoutMs How long to wait for in-flight calls. Default 120s. Calls still
+   *   running when it expires are ended the way `disconnect()` ends them. Keep the platform's
+   *   own grace period longer than this (k8s `terminationGracePeriodSeconds`, ECS
+   *   `stopTimeout`), or it will SIGKILL the process mid-drain and undo the point of draining.
+   * @returns How many calls ended on their own, and how many had to be cut short.
+   */
+  async drain(options) {
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_DRAIN_TIMEOUT_MS;
+    this._controlGivenUp = true;
+    if (this._controlWs) {
+      this._controlWs.close();
+      this._controlWs = null;
+    }
+    for (const wake of [...this._terminalWaiters.values()]) wake();
+    const inFlight = this._activeSessions.size;
+    if (inFlight === 0) {
+      this._log.info("Drain: no calls in progress");
+      await this.disconnect();
+      return { completed: 0, forced: 0 };
+    }
+    this._log.info("Drain: waiting for %d call(s) to finish (timeout %dms)", inFlight, timeoutMs);
+    const deadline = Date.now() + timeoutMs;
+    while (this._activeSessions.size > 0 && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, DRAIN_POLL_INTERVAL_MS));
+    }
+    const forced = this._activeSessions.size;
+    if (forced > 0) {
+      this._log.warn("Drain timed out \u2014 cutting %d call(s) still in progress", forced);
+    } else {
+      this._log.info("Drain complete: all %d call(s) finished", inFlight);
+    }
+    await this.disconnect();
+    return { completed: inFlight - forced, forced };
+  }
   /** Disconnect from the platform. */
   async disconnect() {
+    this._controlGivenUp = true;
     if (this._controlWs) {
       this._controlWs.close();
       this._controlWs = null;
@@ -1341,6 +1494,7 @@ var ClawOpsAgent = class _ClawOpsAgent {
    */
   async _awaitServerTerminal(session) {
     if (session.endedDuration !== null) return;
+    if (this._controlGivenUp) return;
     await new Promise((resolve) => {
       const done = () => {
         clearTimeout(timer);
@@ -1633,7 +1787,15 @@ var ClawOpsAgent = class _ClawOpsAgent {
           },
           () => mediaWs.isConnected
         );
-        session._transferFn = (params) => this._controlWs.requestTransfer(session.callId, params);
+        session._transferFn = (params) => {
+          const controlWs = this._controlWs;
+          if (!controlWs) {
+            throw new AgentError(
+              "transfer unavailable: the control connection is closed (draining, or this number was taken over)"
+            );
+          }
+          return controlWs.requestTransfer(session.callId, params);
+        };
         session._sendMark = (name) => mediaWs.sendMark(name);
         session._waitForMark = (name, timeoutMs) => mediaWs.waitForMark(name, timeoutMs);
         session._flushTransport = () => mediaWs.flush();