kugelaudio 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [kugelaudio-v0.6.1](https://github.com/Kugelaudio/KugelAudio/compare/js-sdk-v0.6.0...js-sdk-v0.6.1) (2026-06-04)
+
+### Bug Fixes
+
+* **python-sdk:** propagate ingress errors through SDK integrations ([#1313](https://github.com/Kugelaudio/KugelAudio/issues/1313)) ([3ae2e03](https://github.com/Kugelaudio/KugelAudio/commit/3ae2e03745b49cca0712c20d9a658c160f4b6f38))
+
+## [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.
      *
@@ -1183,6 +1224,8 @@ declare const ErrorCodes: {
     readonly VALIDATION: "VALIDATION_ERROR";
     readonly INTERNAL: "INTERNAL_ERROR";
     readonly NOT_FOUND: "NOT_FOUND";
+    readonly MISSING_VOICE_ID: "MISSING_VOICE_ID";
+    readonly TOO_MANY_CONTEXTS: "TOO_MANY_CONTEXTS";
 };
 type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
 declare const WsCloseCodes: {
@@ -1264,11 +1307,12 @@ interface HttpResponseLike {
 declare function classifyHttpError(status: number, bodyText: string, headers: HttpResponseLike['headers']): KugelAudioError;
 /**
  * Build a `KugelAudioError` from a server-sent WebSocket error frame
- * (`{error, error_code, retry_after}`).
+ * (`{error, error_code, code}`).
  */
 declare function classifyWsFrame(data: {
     error?: string;
     error_code?: string;
+    code?: number;
     retry_after?: number;
 }): KugelAudioError;
 /**

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.
      *
@@ -1183,6 +1224,8 @@ declare const ErrorCodes: {
     readonly VALIDATION: "VALIDATION_ERROR";
     readonly INTERNAL: "INTERNAL_ERROR";
     readonly NOT_FOUND: "NOT_FOUND";
+    readonly MISSING_VOICE_ID: "MISSING_VOICE_ID";
+    readonly TOO_MANY_CONTEXTS: "TOO_MANY_CONTEXTS";
 };
 type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
 declare const WsCloseCodes: {
@@ -1264,11 +1307,12 @@ interface HttpResponseLike {
 declare function classifyHttpError(status: number, bodyText: string, headers: HttpResponseLike['headers']): KugelAudioError;
 /**
  * Build a `KugelAudioError` from a server-sent WebSocket error frame
- * (`{error, error_code, retry_after}`).
+ * (`{error, error_code, code}`).
  */
 declare function classifyWsFrame(data: {
     error?: string;
     error_code?: string;
+    code?: number;
     retry_after?: number;
 }): KugelAudioError;
 /**

package/dist/index.js

@@ -233,7 +233,9 @@ var ErrorCodes = {
   EMPTY_AUDIO: "EMPTY_AUDIO",
   VALIDATION: "VALIDATION_ERROR",
   INTERNAL: "INTERNAL_ERROR",
-  NOT_FOUND: "NOT_FOUND"
+  NOT_FOUND: "NOT_FOUND",
+  MISSING_VOICE_ID: "MISSING_VOICE_ID",
+  TOO_MANY_CONTEXTS: "TOO_MANY_CONTEXTS"
 };
 var WsCloseCodes = {
   UNAUTHORIZED: 4001,
@@ -317,10 +319,10 @@ function build(status, errorCode, message, opts = {}) {
   if (errorCode === ErrorCodes.INSUFFICIENT_CREDITS || status === 402) {
     return new InsufficientCreditsError(message || void 0, common);
   }
-  if (errorCode === ErrorCodes.RATE_LIMITED || status === 429) {
+  if (errorCode === ErrorCodes.RATE_LIMITED || errorCode === ErrorCodes.TOO_MANY_CONTEXTS || status === 429) {
     return new RateLimitError(message || void 0, common);
   }
-  if (errorCode === ErrorCodes.VALIDATION || status === 400) {
+  if (errorCode === ErrorCodes.VALIDATION || errorCode === ErrorCodes.MISSING_VOICE_ID || status === 400) {
     return new ValidationError(message || "Request validation failed.", common);
   }
   if (errorCode === ErrorCodes.MODEL_UNAVAILABLE || status === 503) {
@@ -380,8 +382,9 @@ function classifyHttpError(status, bodyText, headers) {
 function classifyWsFrame(data) {
   const errorCode = data.error_code;
   const message = data.error ?? "Server reported an error.";
+  const status = typeof data.code === "number" ? data.code : void 0;
   const retryAfter = typeof data.retry_after === "number" ? data.retry_after : void 0;
-  return build(void 0, errorCode, message, { retryAfter });
+  return build(status, errorCode, message, { retryAfter });
 }
 function classifyWsClose(code, reason) {
   const reasonTxt = (reason ?? "").trim();
@@ -1303,7 +1306,7 @@ var MultiContextSession = class {
         const data = JSON.parse(messageData);
         if (data.error) {
           this.callbacks.onError?.(
-            new KugelAudioError(data.error),
+            classifyWsFrame(data),
             data.context_id
           );
           return;
@@ -1438,13 +1441,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 +1560,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 +1643,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

@@ -195,7 +195,9 @@ var ErrorCodes = {
   EMPTY_AUDIO: "EMPTY_AUDIO",
   VALIDATION: "VALIDATION_ERROR",
   INTERNAL: "INTERNAL_ERROR",
-  NOT_FOUND: "NOT_FOUND"
+  NOT_FOUND: "NOT_FOUND",
+  MISSING_VOICE_ID: "MISSING_VOICE_ID",
+  TOO_MANY_CONTEXTS: "TOO_MANY_CONTEXTS"
 };
 var WsCloseCodes = {
   UNAUTHORIZED: 4001,
@@ -279,10 +281,10 @@ function build(status, errorCode, message, opts = {}) {
   if (errorCode === ErrorCodes.INSUFFICIENT_CREDITS || status === 402) {
     return new InsufficientCreditsError(message || void 0, common);
   }
-  if (errorCode === ErrorCodes.RATE_LIMITED || status === 429) {
+  if (errorCode === ErrorCodes.RATE_LIMITED || errorCode === ErrorCodes.TOO_MANY_CONTEXTS || status === 429) {
     return new RateLimitError(message || void 0, common);
   }
-  if (errorCode === ErrorCodes.VALIDATION || status === 400) {
+  if (errorCode === ErrorCodes.VALIDATION || errorCode === ErrorCodes.MISSING_VOICE_ID || status === 400) {
     return new ValidationError(message || "Request validation failed.", common);
   }
   if (errorCode === ErrorCodes.MODEL_UNAVAILABLE || status === 503) {
@@ -342,8 +344,9 @@ function classifyHttpError(status, bodyText, headers) {
 function classifyWsFrame(data) {
   const errorCode = data.error_code;
   const message = data.error ?? "Server reported an error.";
+  const status = typeof data.code === "number" ? data.code : void 0;
   const retryAfter = typeof data.retry_after === "number" ? data.retry_after : void 0;
-  return build(void 0, errorCode, message, { retryAfter });
+  return build(status, errorCode, message, { retryAfter });
 }
 function classifyWsClose(code, reason) {
   const reasonTxt = (reason ?? "").trim();
@@ -1265,7 +1268,7 @@ var MultiContextSession = class {
         const data = JSON.parse(messageData);
         if (data.error) {
           this.callbacks.onError?.(
-            new KugelAudioError(data.error),
+            classifyWsFrame(data),
             data.context_id
           );
           return;
@@ -1400,13 +1403,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 +1522,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 +1605,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.1",
   "description": "Official JavaScript/TypeScript SDK for KugelAudio TTS API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/client.test.ts

@@ -8,6 +8,7 @@
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { KugelAudio } from './client';
+import { RateLimitError } from './errors';
 
 // ---------------------------------------------------------------------------
 // Minimal WebSocket mock
@@ -333,6 +334,10 @@ function makeGenerationStartedMsg(chunkId: number, text: string): string {
   });
 }
 
+function makeInterruptedMsg(): string {
+  return JSON.stringify({ interrupted: true });
+}
+
 describe('StreamingSession', () => {
   let client: KugelAudio;
 
@@ -545,4 +550,138 @@ 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();
+  });
+
+  it('maps ingress context-cap errors to typed callback errors', async () => {
+    const errors: Array<{ contextId?: string; error: Error }> = [];
+    const session = client.tts.createMultiContextSession({ defaultVoiceId: 1 });
+    await session.connect({
+      onError: (error, contextId) => errors.push({ contextId, error }),
+    });
+
+    mockWs.onmessage?.({
+      data: JSON.stringify({
+        error: 'Too many concurrent contexts',
+        error_code: 'TOO_MANY_CONTEXTS',
+        code: 429,
+        context_id: 'ctx1',
+      }),
+    });
+
+    expect(errors).toHaveLength(1);
+    expect(errors[0].contextId).toBe('ctx1');
+    expect(errors[0].error).toBeInstanceOf(RateLimitError);
+    expect((errors[0].error as RateLimitError).statusCode).toBe(429);
+    expect((errors[0].error as RateLimitError).errorCode).toBe('TOO_MANY_CONTEXTS');
+  });
 });

package/src/client.ts

@@ -873,7 +873,7 @@ class TTSResource {
     }
   }
 
-  private parseError(data: { error?: string; error_code?: string; retry_after?: number }): Error {
+  private parseError(data: { error?: string; error_code?: string; code?: number; retry_after?: number }): Error {
     return classifyWsFrame(data);
   }
 
@@ -1019,7 +1019,7 @@ class MultiContextSession {
 
         if (data.error) {
           this.callbacks.onError?.(
-            new KugelAudioError(data.error),
+            classifyWsFrame(data),
             data.context_id
           );
           return;
@@ -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/errors.ts

@@ -17,6 +17,8 @@ export const ErrorCodes = {
   VALIDATION: 'VALIDATION_ERROR',
   INTERNAL: 'INTERNAL_ERROR',
   NOT_FOUND: 'NOT_FOUND',
+  MISSING_VOICE_ID: 'MISSING_VOICE_ID',
+  TOO_MANY_CONTEXTS: 'TOO_MANY_CONTEXTS',
 } as const;
 export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
 
@@ -175,10 +177,18 @@ function build(
   if (errorCode === ErrorCodes.INSUFFICIENT_CREDITS || status === 402) {
     return new InsufficientCreditsError(message || undefined, common);
   }
-  if (errorCode === ErrorCodes.RATE_LIMITED || status === 429) {
+  if (
+    errorCode === ErrorCodes.RATE_LIMITED ||
+    errorCode === ErrorCodes.TOO_MANY_CONTEXTS ||
+    status === 429
+  ) {
     return new RateLimitError(message || undefined, common);
   }
-  if (errorCode === ErrorCodes.VALIDATION || status === 400) {
+  if (
+    errorCode === ErrorCodes.VALIDATION ||
+    errorCode === ErrorCodes.MISSING_VOICE_ID ||
+    status === 400
+  ) {
     return new ValidationError(message || 'Request validation failed.', common);
   }
   if (errorCode === ErrorCodes.MODEL_UNAVAILABLE || status === 503) {
@@ -263,17 +273,19 @@ export function classifyHttpError(
 
 /**
  * Build a `KugelAudioError` from a server-sent WebSocket error frame
- * (`{error, error_code, retry_after}`).
+ * (`{error, error_code, code}`).
  */
 export function classifyWsFrame(data: {
   error?: string;
   error_code?: string;
+  code?: number;
   retry_after?: number;
 }): KugelAudioError {
   const errorCode = data.error_code;
   const message = data.error ?? 'Server reported an error.';
+  const status = typeof data.code === 'number' ? data.code : undefined;
   const retryAfter = typeof data.retry_after === 'number' ? data.retry_after : undefined;
-  return build(undefined, errorCode, message, { retryAfter });
+  return build(status, errorCode, message, { retryAfter });
 }
 
 /**

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;
 }