kugelaudio 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [kugelaudio-v0.6.0](https://github.com/Kugelaudio/KugelAudio/compare/js-sdk-v0.5.0...js-sdk-v0.6.0) (2026-06-01)
+
+### Features
+
+* streaming barge-in (cancelCurrent) across server + JS/Python/Java SDKs ([#1210](https://github.com/Kugelaudio/KugelAudio/issues/1210)) ([341e54f](https://github.com/Kugelaudio/KugelAudio/commit/341e54f169b4dd9242272b249fca30f005bfc3b8))
+
 ## [kugelaudio-v0.5.0](https://github.com/Kugelaudio/KugelAudio/compare/js-sdk-v0.4.0...js-sdk-v0.5.0) (2026-05-21)
 
 ### Features

package/dist/index.d.mts

@@ -383,6 +383,13 @@ interface StreamingSessionCallbacks {
     onGenerationStarted?: (chunkId: number, text: string) => void;
     /** Called when word-level timestamps arrive (requires `wordTimestamps: true`). */
     onWordTimestamps?: (timestamps: WordTimestamp[]) => void;
+    /**
+     * Called when the server acknowledges a barge-in
+     * ({@link StreamingSession.cancelCurrent}). After this fires, no further
+     * audio chunks from the cancelled turn will arrive and the session is
+     * ready for the next `send()`.
+     */
+    onInterrupted?: () => void;
     /** Called on any error. */
     onError?: (error: Error) => void;
 }
@@ -938,8 +945,14 @@ declare class MultiContextSession {
     flush(contextId: string): void;
     /**
      * Close a specific context.
+     *
+     * @param contextId - The context to close.
+     * @param immediate - When `true`, **barge-in**: the server cancels the
+     *   context's in-flight generation immediately and discards any buffered or
+     *   queued text instead of draining it. Use this when the end user speaks
+     *   over the agent. When `false` (default), queued sentences finish first.
      */
-    closeContext(contextId: string): void;
+    closeContext(contextId: string, immediate?: boolean): void;
     /**
      * Send keep-alive to reset a context's inactivity timeout.
      */
@@ -1016,6 +1029,34 @@ declare class StreamingSession {
      *   handle chunking via `chunkLengthSchedule` / `autoMode` instead.
      */
     send(text: string, flush?: boolean): void;
+    /**
+     * Interrupt (barge-in) the current generation without closing the socket.
+     *
+     * Use this when the end user starts speaking over the agent: it tells the
+     * server to **stop generating audio for the current turn immediately** and
+     * drop any text that was buffered or queued but not yet spoken. Unlike
+     * {@link endSession}, no remaining text is flushed — the turn is abandoned.
+     *
+     * The WebSocket stays open and a fresh session is ready, so you can call
+     * {@link send} for the next user turn right away (config is re-sent
+     * automatically on that first `send`).
+     *
+     * The returned promise resolves once the server acknowledges with an
+     * `interrupted` frame (which also fires
+     * {@link StreamingSessionCallbacks.onInterrupted}), or after a 5 s **quiet**
+     * timeout — i.e. 5 s elapse without any server message arriving. The timer
+     * resets on every incoming frame, so a few in-flight audio chunks still
+     * draining at the moment of cancellation do not trip it prematurely.
+     *
+     * @example
+     * ```typescript
+     * // VAD detected the user speaking over the agent:
+     * await session.cancelCurrent();
+     * // Socket is still open — start the next turn immediately:
+     * session.send(nextLlmToken);
+     * ```
+     */
+    cancelCurrent(): Promise<void>;
     /**
      * End the current session but keep the WebSocket connection open.
      *

package/dist/index.d.ts

@@ -383,6 +383,13 @@ interface StreamingSessionCallbacks {
     onGenerationStarted?: (chunkId: number, text: string) => void;
     /** Called when word-level timestamps arrive (requires `wordTimestamps: true`). */
     onWordTimestamps?: (timestamps: WordTimestamp[]) => void;
+    /**
+     * Called when the server acknowledges a barge-in
+     * ({@link StreamingSession.cancelCurrent}). After this fires, no further
+     * audio chunks from the cancelled turn will arrive and the session is
+     * ready for the next `send()`.
+     */
+    onInterrupted?: () => void;
     /** Called on any error. */
     onError?: (error: Error) => void;
 }
@@ -938,8 +945,14 @@ declare class MultiContextSession {
     flush(contextId: string): void;
     /**
      * Close a specific context.
+     *
+     * @param contextId - The context to close.
+     * @param immediate - When `true`, **barge-in**: the server cancels the
+     *   context's in-flight generation immediately and discards any buffered or
+     *   queued text instead of draining it. Use this when the end user speaks
+     *   over the agent. When `false` (default), queued sentences finish first.
      */
-    closeContext(contextId: string): void;
+    closeContext(contextId: string, immediate?: boolean): void;
     /**
      * Send keep-alive to reset a context's inactivity timeout.
      */
@@ -1016,6 +1029,34 @@ declare class StreamingSession {
      *   handle chunking via `chunkLengthSchedule` / `autoMode` instead.
      */
     send(text: string, flush?: boolean): void;
+    /**
+     * Interrupt (barge-in) the current generation without closing the socket.
+     *
+     * Use this when the end user starts speaking over the agent: it tells the
+     * server to **stop generating audio for the current turn immediately** and
+     * drop any text that was buffered or queued but not yet spoken. Unlike
+     * {@link endSession}, no remaining text is flushed — the turn is abandoned.
+     *
+     * The WebSocket stays open and a fresh session is ready, so you can call
+     * {@link send} for the next user turn right away (config is re-sent
+     * automatically on that first `send`).
+     *
+     * The returned promise resolves once the server acknowledges with an
+     * `interrupted` frame (which also fires
+     * {@link StreamingSessionCallbacks.onInterrupted}), or after a 5 s **quiet**
+     * timeout — i.e. 5 s elapse without any server message arriving. The timer
+     * resets on every incoming frame, so a few in-flight audio chunks still
+     * draining at the moment of cancellation do not trip it prematurely.
+     *
+     * @example
+     * ```typescript
+     * // VAD detected the user speaking over the agent:
+     * await session.cancelCurrent();
+     * // Socket is still open — start the next turn immediately:
+     * session.send(nextLlmToken);
+     * ```
+     */
+    cancelCurrent(): Promise<void>;
     /**
      * End the current session but keep the WebSocket connection open.
      *

package/dist/index.js

@@ -1438,13 +1438,21 @@ var MultiContextSession = class {
   }
   /**
    * Close a specific context.
+   *
+   * @param contextId - The context to close.
+   * @param immediate - When `true`, **barge-in**: the server cancels the
+   *   context's in-flight generation immediately and discards any buffered or
+   *   queued text instead of draining it. Use this when the end user speaks
+   *   over the agent. When `false` (default), queued sentences finish first.
    */
-  closeContext(contextId) {
+  closeContext(contextId, immediate = false) {
     if (!this.ws || this.ws.readyState !== WS_OPEN) return;
-    this.ws.send(JSON.stringify({
+    const msg = {
       close_context: true,
       context_id: contextId
-    }));
+    };
+    if (immediate) msg.immediate = true;
+    this.ws.send(JSON.stringify(msg));
   }
   /**
    * Send keep-alive to reset a context's inactivity timeout.
@@ -1549,6 +1557,9 @@ var StreamingSession = class {
         if (data.generation_started) {
           this.callbacks.onGenerationStarted?.(data.chunk_id ?? 0, data.text ?? "");
         }
+        if (data.interrupted) {
+          this.callbacks.onInterrupted?.();
+        }
         if (data.session_closed) {
           this.callbacks.onSessionClosed?.(
             data.total_audio_seconds ?? 0,
@@ -1629,6 +1640,73 @@ var StreamingSession = class {
     }
     this.ws.send(JSON.stringify(msg));
   }
+  /**
+   * Interrupt (barge-in) the current generation without closing the socket.
+   *
+   * Use this when the end user starts speaking over the agent: it tells the
+   * server to **stop generating audio for the current turn immediately** and
+   * drop any text that was buffered or queued but not yet spoken. Unlike
+   * {@link endSession}, no remaining text is flushed — the turn is abandoned.
+   *
+   * The WebSocket stays open and a fresh session is ready, so you can call
+   * {@link send} for the next user turn right away (config is re-sent
+   * automatically on that first `send`).
+   *
+   * The returned promise resolves once the server acknowledges with an
+   * `interrupted` frame (which also fires
+   * {@link StreamingSessionCallbacks.onInterrupted}), or after a 5 s **quiet**
+   * timeout — i.e. 5 s elapse without any server message arriving. The timer
+   * resets on every incoming frame, so a few in-flight audio chunks still
+   * draining at the moment of cancellation do not trip it prematurely.
+   *
+   * @example
+   * ```typescript
+   * // VAD detected the user speaking over the agent:
+   * await session.cancelCurrent();
+   * // Socket is still open — start the next turn immediately:
+   * session.send(nextLlmToken);
+   * ```
+   */
+  cancelCurrent() {
+    if (!this.ws || this.ws.readyState !== WS_OPEN) return Promise.resolve();
+    const ws = this.ws;
+    const QUIET_TIMEOUT_MS = 5e3;
+    return new Promise((resolve) => {
+      let settled = false;
+      let timer;
+      const prevMessage = ws.onmessage;
+      const prevClose = ws.onclose;
+      const done = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        ws.onmessage = prevMessage;
+        ws.onclose = prevClose;
+        this.configSent = false;
+        resolve();
+      };
+      const armQuietTimer = () => {
+        clearTimeout(timer);
+        timer = setTimeout(done, QUIET_TIMEOUT_MS);
+      };
+      armQuietTimer();
+      ws.onmessage = (event) => {
+        armQuietTimer();
+        if (prevMessage) prevMessage.call(ws, event);
+        try {
+          const raw = typeof event.data === "string" ? event.data : event.data instanceof Buffer ? event.data.toString() : String(event.data);
+          if (JSON.parse(raw).interrupted) done();
+        } catch {
+        }
+      };
+      ws.onclose = (event) => {
+        this.ws = null;
+        if (prevClose) prevClose.call(ws, event);
+        done();
+      };
+      ws.send(JSON.stringify({ cancel: true }));
+    });
+  }
   /**
    * End the current session but keep the WebSocket connection open.
    *

package/dist/index.mjs

@@ -1400,13 +1400,21 @@ var MultiContextSession = class {
   }
   /**
    * Close a specific context.
+   *
+   * @param contextId - The context to close.
+   * @param immediate - When `true`, **barge-in**: the server cancels the
+   *   context's in-flight generation immediately and discards any buffered or
+   *   queued text instead of draining it. Use this when the end user speaks
+   *   over the agent. When `false` (default), queued sentences finish first.
    */
-  closeContext(contextId) {
+  closeContext(contextId, immediate = false) {
     if (!this.ws || this.ws.readyState !== WS_OPEN) return;
-    this.ws.send(JSON.stringify({
+    const msg = {
       close_context: true,
       context_id: contextId
-    }));
+    };
+    if (immediate) msg.immediate = true;
+    this.ws.send(JSON.stringify(msg));
   }
   /**
    * Send keep-alive to reset a context's inactivity timeout.
@@ -1511,6 +1519,9 @@ var StreamingSession = class {
         if (data.generation_started) {
           this.callbacks.onGenerationStarted?.(data.chunk_id ?? 0, data.text ?? "");
         }
+        if (data.interrupted) {
+          this.callbacks.onInterrupted?.();
+        }
         if (data.session_closed) {
           this.callbacks.onSessionClosed?.(
             data.total_audio_seconds ?? 0,
@@ -1591,6 +1602,73 @@ var StreamingSession = class {
     }
     this.ws.send(JSON.stringify(msg));
   }
+  /**
+   * Interrupt (barge-in) the current generation without closing the socket.
+   *
+   * Use this when the end user starts speaking over the agent: it tells the
+   * server to **stop generating audio for the current turn immediately** and
+   * drop any text that was buffered or queued but not yet spoken. Unlike
+   * {@link endSession}, no remaining text is flushed — the turn is abandoned.
+   *
+   * The WebSocket stays open and a fresh session is ready, so you can call
+   * {@link send} for the next user turn right away (config is re-sent
+   * automatically on that first `send`).
+   *
+   * The returned promise resolves once the server acknowledges with an
+   * `interrupted` frame (which also fires
+   * {@link StreamingSessionCallbacks.onInterrupted}), or after a 5 s **quiet**
+   * timeout — i.e. 5 s elapse without any server message arriving. The timer
+   * resets on every incoming frame, so a few in-flight audio chunks still
+   * draining at the moment of cancellation do not trip it prematurely.
+   *
+   * @example
+   * ```typescript
+   * // VAD detected the user speaking over the agent:
+   * await session.cancelCurrent();
+   * // Socket is still open — start the next turn immediately:
+   * session.send(nextLlmToken);
+   * ```
+   */
+  cancelCurrent() {
+    if (!this.ws || this.ws.readyState !== WS_OPEN) return Promise.resolve();
+    const ws = this.ws;
+    const QUIET_TIMEOUT_MS = 5e3;
+    return new Promise((resolve) => {
+      let settled = false;
+      let timer;
+      const prevMessage = ws.onmessage;
+      const prevClose = ws.onclose;
+      const done = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        ws.onmessage = prevMessage;
+        ws.onclose = prevClose;
+        this.configSent = false;
+        resolve();
+      };
+      const armQuietTimer = () => {
+        clearTimeout(timer);
+        timer = setTimeout(done, QUIET_TIMEOUT_MS);
+      };
+      armQuietTimer();
+      ws.onmessage = (event) => {
+        armQuietTimer();
+        if (prevMessage) prevMessage.call(ws, event);
+        try {
+          const raw = typeof event.data === "string" ? event.data : event.data instanceof Buffer ? event.data.toString() : String(event.data);
+          if (JSON.parse(raw).interrupted) done();
+        } catch {
+        }
+      };
+      ws.onclose = (event) => {
+        this.ws = null;
+        if (prevClose) prevClose.call(ws, event);
+        done();
+      };
+      ws.send(JSON.stringify({ cancel: true }));
+    });
+  }
   /**
    * End the current session but keep the WebSocket connection open.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kugelaudio",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Official JavaScript/TypeScript SDK for KugelAudio TTS API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/client.test.ts

@@ -333,6 +333,10 @@ function makeGenerationStartedMsg(chunkId: number, text: string): string {
   });
 }
 
+function makeInterruptedMsg(): string {
+  return JSON.stringify({ interrupted: true });
+}
+
 describe('StreamingSession', () => {
   let client: KugelAudio;
 
@@ -545,4 +549,115 @@ describe('StreamingSession', () => {
     expect(session.isConnected).toBe(true);
     expect(() => session.send('Hello.', true)).not.toThrow();
   });
+
+  // -------------------------------------------------------------------------
+  // cancelCurrent() — barge-in (KUG-1050)
+  // -------------------------------------------------------------------------
+
+  it('cancelCurrent() sends {cancel:true}, fires onInterrupted, keeps socket open', async () => {
+    const interruptedCalls: number[] = [];
+
+    const session = client.tts.streamingSession(
+      { voiceId: 1 },
+      { onInterrupted: () => interruptedCalls.push(1) },
+    );
+
+    session.connect();
+    await new Promise<void>((r) => setTimeout(r, 10));
+
+    session.send('A very long sentence the user is about to talk over.');
+    mockWs.onmessage?.({ data: makeAudioMsg(0, 100) });
+
+    const cancelPromise = session.cancelCurrent();
+
+    // The barge-in frame was sent to the server.
+    const lastSent = JSON.parse(mockWs.send.mock.calls[mockWs.send.mock.calls.length - 1][0] as string);
+    expect(lastSent.cancel).toBe(true);
+
+    // Server acks the barge-in.
+    mockWs.onmessage?.({ data: makeInterruptedMsg() });
+    await cancelPromise;
+
+    // onInterrupted fired and the socket stayed open for the next turn.
+    expect(interruptedCalls).toHaveLength(1);
+    expect(session.isConnected).toBe(true);
+    expect(mockWs.close).not.toHaveBeenCalled();
+  });
+
+  it('cancelCurrent() re-sends config on the next send (fresh server session)', async () => {
+    const session = client.tts.streamingSession({ voiceId: 42 }, {});
+
+    session.connect();
+    await new Promise<void>((r) => setTimeout(r, 10));
+
+    // First send carries config (voice_id).
+    session.send('Hello.');
+    expect(JSON.parse(mockWs.send.mock.calls[mockWs.send.mock.calls.length - 1][0] as string).voice_id).toBe(42);
+
+    const cancelPromise = session.cancelCurrent();
+    mockWs.onmessage?.({ data: makeInterruptedMsg() });
+    await cancelPromise;
+
+    // The server started a fresh session, so the next send must re-send config.
+    session.send('Next turn.');
+    expect(JSON.parse(mockWs.send.mock.calls[mockWs.send.mock.calls.length - 1][0] as string).voice_id).toBe(42);
+  });
+
+  it('cancelCurrent() resolves on quiet timeout if server never acks', async () => {
+    const session = client.tts.streamingSession({ voiceId: 1 }, {});
+
+    session.connect();
+    await new Promise<void>((r) => setTimeout(r, 10));
+    session.send('Hello.');
+
+    vi.useFakeTimers();
+    const cancelPromise = session.cancelCurrent();
+
+    // No interrupted ack — the 5 s quiet timeout resolves it.
+    await vi.advanceTimersByTimeAsync(6_000);
+    await cancelPromise;
+
+    vi.useRealTimers();
+    // Socket was never closed; still reusable.
+    expect(session.isConnected).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// MultiContextSession barge-in — closeContext immediate (KUG-1050)
+// ---------------------------------------------------------------------------
+
+describe('MultiContextSession closeContext', () => {
+  let client: KugelAudio;
+
+  beforeEach(() => {
+    client = new KugelAudio({ apiKey: 'test-key-xxx' });
+  });
+
+  it('closeContext(id, true) sends the immediate barge-in flag', async () => {
+    const session = client.tts.createMultiContextSession({ defaultVoiceId: 1 });
+    await session.connect({});
+
+    session.closeContext('ctx1', true);
+
+    const sent = JSON.parse(
+      mockWs.send.mock.calls[mockWs.send.mock.calls.length - 1][0] as string
+    );
+    expect(sent.close_context).toBe(true);
+    expect(sent.context_id).toBe('ctx1');
+    expect(sent.immediate).toBe(true);
+  });
+
+  it('closeContext(id) omits immediate (graceful drain)', async () => {
+    const session = client.tts.createMultiContextSession({ defaultVoiceId: 1 });
+    await session.connect({});
+
+    session.closeContext('ctx1');
+
+    const sent = JSON.parse(
+      mockWs.send.mock.calls[mockWs.send.mock.calls.length - 1][0] as string
+    );
+    expect(sent.close_context).toBe(true);
+    expect(sent.immediate).toBeUndefined();
+  });
 });

package/src/client.ts

@@ -1195,14 +1195,22 @@ class MultiContextSession {
 
   /**
    * Close a specific context.
+   *
+   * @param contextId - The context to close.
+   * @param immediate - When `true`, **barge-in**: the server cancels the
+   *   context's in-flight generation immediately and discards any buffered or
+   *   queued text instead of draining it. Use this when the end user speaks
+   *   over the agent. When `false` (default), queued sentences finish first.
    */
-  closeContext(contextId: string): void {
+  closeContext(contextId: string, immediate = false): void {
     if (!this.ws || this.ws.readyState !== WS_OPEN) return;
 
-    this.ws.send(JSON.stringify({
+    const msg: Record<string, unknown> = {
       close_context: true,
       context_id: contextId,
-    }));
+    };
+    if (immediate) msg.immediate = true;
+    this.ws.send(JSON.stringify(msg));
   }
 
   /**
@@ -1362,6 +1370,10 @@ class StreamingSession {
           this.callbacks.onGenerationStarted?.(data.chunk_id ?? 0, data.text ?? '');
         }
 
+        if (data.interrupted) {
+          this.callbacks.onInterrupted?.();
+        }
+
         if (data.session_closed) {
           this.callbacks.onSessionClosed?.(
             data.total_audio_seconds ?? 0,
@@ -1461,6 +1473,97 @@ class StreamingSession {
     this.ws.send(JSON.stringify(msg));
   }
 
+  /**
+   * Interrupt (barge-in) the current generation without closing the socket.
+   *
+   * Use this when the end user starts speaking over the agent: it tells the
+   * server to **stop generating audio for the current turn immediately** and
+   * drop any text that was buffered or queued but not yet spoken. Unlike
+   * {@link endSession}, no remaining text is flushed — the turn is abandoned.
+   *
+   * The WebSocket stays open and a fresh session is ready, so you can call
+   * {@link send} for the next user turn right away (config is re-sent
+   * automatically on that first `send`).
+   *
+   * The returned promise resolves once the server acknowledges with an
+   * `interrupted` frame (which also fires
+   * {@link StreamingSessionCallbacks.onInterrupted}), or after a 5 s **quiet**
+   * timeout — i.e. 5 s elapse without any server message arriving. The timer
+   * resets on every incoming frame, so a few in-flight audio chunks still
+   * draining at the moment of cancellation do not trip it prematurely.
+   *
+   * @example
+   * ```typescript
+   * // VAD detected the user speaking over the agent:
+   * await session.cancelCurrent();
+   * // Socket is still open — start the next turn immediately:
+   * session.send(nextLlmToken);
+   * ```
+   */
+  cancelCurrent(): Promise<void> {
+    if (!this.ws || this.ws.readyState !== WS_OPEN) return Promise.resolve();
+
+    const ws = this.ws;
+    // Quiet timeout: resets on every incoming server message. Trips only
+    // when the server has been silent for this long. A short window is fine
+    // here because the server cancels in-flight generation promptly; we only
+    // need to outlast a handful of already-emitted audio frames in transit.
+    const QUIET_TIMEOUT_MS = 5_000;
+
+    return new Promise<void>((resolve) => {
+      let settled = false;
+      let timer: ReturnType<typeof setTimeout>;
+
+      const prevMessage = ws.onmessage;
+      const prevClose = ws.onclose;
+
+      const done = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        // Restore the original handlers so subsequent calls don't stack
+        // wrappers and the typed-error onclose installed by connect() stays
+        // in effect for the next turn.
+        ws.onmessage = prevMessage;
+        ws.onclose = prevClose;
+        // The server starts a fresh session after a cancel, so the next
+        // send() must re-send config.
+        this.configSent = false;
+        resolve();
+      };
+
+      const armQuietTimer = () => {
+        clearTimeout(timer);
+        timer = setTimeout(done, QUIET_TIMEOUT_MS);
+      };
+
+      armQuietTimer();
+
+      ws.onmessage = (event: MessageEvent) => {
+        // Reset the quiet timer on EVERY incoming frame — late audio chunks
+        // from the cancelled turn count as liveness, not just the ack.
+        armQuietTimer();
+        if (prevMessage) prevMessage.call(ws, event);
+        try {
+          const raw = typeof event.data === 'string'
+            ? event.data
+            : event.data instanceof Buffer
+              ? event.data.toString()
+              : String(event.data);
+          if (JSON.parse(raw).interrupted) done();
+        } catch { /* ignore parse errors */ }
+      };
+
+      ws.onclose = (event: CloseEvent) => {
+        this.ws = null;
+        if (prevClose) prevClose.call(ws, event);
+        done();
+      };
+
+      ws.send(JSON.stringify({ cancel: true }));
+    });
+  }
+
   /**
    * End the current session but keep the WebSocket connection open.
    *

package/src/types.ts

@@ -408,6 +408,13 @@ export interface StreamingSessionCallbacks {
   onGenerationStarted?: (chunkId: number, text: string) => void;
   /** Called when word-level timestamps arrive (requires `wordTimestamps: true`). */
   onWordTimestamps?: (timestamps: WordTimestamp[]) => void;
+  /**
+   * Called when the server acknowledges a barge-in
+   * ({@link StreamingSession.cancelCurrent}). After this fires, no further
+   * audio chunks from the cancelled turn will arrive and the session is
+   * ready for the next `send()`.
+   */
+  onInterrupted?: () => void;
   /** Called on any error. */
   onError?: (error: Error) => void;
 }