@qafka/react-native 2.3.8 → 2.4.0

package/dist/services/RealtimeService.d.ts

@@ -11,6 +11,8 @@ export type RealtimeEvent = {
     delta: string;
 } | {
     type: 'response.done';
+} | {
+    type: 'response.interrupted';
 } | {
     type: 'conversation.item.input_audio_transcription.completed';
     transcript: string;
@@ -47,6 +49,12 @@ export declare class RealtimeService {
     private apiKey;
     private ws;
     private audioUnsubscribe;
+    private bargeInUnsubscribe;
+    private bargeInTimes;
+    private echoDowngraded;
+    private micEnabled;
+    private aiSpeaking;
+    private fullDuplex;
     private eventHandler;
     private audioChunksSent;
     private sessionTokenGetter;
@@ -62,8 +70,18 @@ export declare class RealtimeService {
     }): Promise<void>;
     private audioDeltasReceived;
     private handleEvent;
+    /**
+     * Native detected the user talking over the AI (client-side barge-in) — it has
+     * already cut playback locally and is suppressing the cancelled turn. Mirror a
+     * server interrupt so the consumer UI returns to listening immediately; the
+     * gateway's own (slower) interrupt follows and lifts the suppression.
+     */
+    private handleLocalBargeIn;
+    private guardAgainstEcho;
     private attachAudioListener;
     private detachAudioListener;
+    private syncMicForwarding;
+    private setAiSpeaking;
     private startAudioPipeline;
     /**
     * Fully stop the native audio engine (capture + playback). Use when leaving

package/dist/services/RealtimeService.js

@@ -3,11 +3,41 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RealtimeService = void 0;
 const QafkaAudio_1 = require("../native/QafkaAudio");
 const QafkaAttestation_1 = require("../native/QafkaAttestation");
+const decide_interrupt_1 = require("../decide-interrupt");
+const decide_mic_forwarding_1 = require("../decide-mic-forwarding");
+// Full-duplex voice: keep the mic open while the AI speaks and rely on the
+// native OS echo canceler to strip the AI's playback out of the mic, so the
+// user can interrupt by voice (barge-in). When false, the SDK falls back to
+// half-duplex (mic gated while the AI speaks). A failing on-device echo
+// canceler auto-downgrades the session to half-duplex at runtime (see the
+// echo guard below).
+const DEFAULT_FULL_DUPLEX = true;
+// Echo guard: if the device's AEC is failing, the AI's own voice leaks into the
+// mic and the barge-in detector reads it as the user — firing repeatedly. A real
+// user never barges in this often, so this many barge-ins within the window means
+// the AEC isn't working: downgrade the session to half-duplex.
+const ECHO_GUARD_BARGE_INS = 3;
+const ECHO_GUARD_WINDOW_MS = 12000;
 class RealtimeService {
     apiUrl;
     apiKey;
     ws = null;
     audioUnsubscribe = null;
+    // Native client-side barge-in subscription (mic-energy spike while AI speaks).
+    bargeInUnsubscribe = null;
+    // Echo guard — recent barge-in timestamps + whether this session downgraded.
+    bargeInTimes = [];
+    echoDowngraded = false;
+    // Half-duplex mic gating. `micEnabled` reflects the user/system mute state;
+    // `aiSpeaking` is true while the AI's audio is playing. Mic audio is
+    // forwarded to the server only when both allow it — this stops the AI's own
+    // voice (echoed into the mic) from being transcribed as a user turn, since
+    // there is no server-side echo cancellation upstream.
+    micEnabled = true;
+    aiSpeaking = false;
+    // Full-duplex (keep mic open while AI speaks, rely on native hardware AEC).
+    // When false, half-duplex mic gating is used. See DEFAULT_FULL_DUPLEX.
+    fullDuplex = DEFAULT_FULL_DUPLEX;
     eventHandler = null;
     audioChunksSent = 0;
     sessionTokenGetter = null;
@@ -50,6 +80,12 @@ class RealtimeService {
             Object.keys(options.endUserData).length > 0) {
             params.set('endUserData', JSON.stringify(options.endUserData));
         }
+        // Tell the gateway this session is full-duplex so it enables the server-side
+        // barge-in VAD config ONLY for us. Half-duplex builds omit it → the gateway
+        // keeps their exact prior behavior.
+        if (this.fullDuplex) {
+            params.set('fullDuplex', '1');
+        }
         const qs = params.toString();
         const fullUrl = `${wsUrl}/v1/realtime${qs ? `?${qs}` : ''}`;
         // Start the audio engine FIRST so the player is ready to schedule buffers
@@ -117,12 +153,63 @@ class RealtimeService {
     handleEvent(event) {
         if (event.type === 'response.audio.delta' && 'delta' in event) {
             this.audioDeltasReceived++;
+            // Half-duplex: the AI is speaking — stop forwarding mic audio so its own
+            // voice can't echo back into the STT as a user turn.
+            this.setAiSpeaking(true);
             QafkaAudio_1.QafkaAudio.playAudioChunk(event.delta).catch(() => {
                 // playback errors are surfaced to the consumer via eventHandler
             });
         }
+        else if ((0, decide_interrupt_1.shouldStopPlayback)(event)) {
+            // Barge-in: the server signalled the user interrupted. Purge native
+            // playback so queued audio stops; the WS is ordered, so no further
+            // audio delta arrives after this for the cancelled turn. Also lift any
+            // local-barge-in suppression so the AI's NEXT turn can play.
+            this.setAiSpeaking(false);
+            QafkaAudio_1.QafkaAudio.stopPlayback().catch(() => { });
+            QafkaAudio_1.QafkaAudio.resumePlayback().catch(() => { });
+        }
+        else if (event.type === 'response.done') {
+            // AI finished its turn — reopen mic forwarding for the user and clear any
+            // lingering local-barge-in suppression.
+            this.setAiSpeaking(false);
+            QafkaAudio_1.QafkaAudio.resumePlayback().catch(() => { });
+        }
         this.eventHandler?.(event);
     }
+    /**
+     * Native detected the user talking over the AI (client-side barge-in) — it has
+     * already cut playback locally and is suppressing the cancelled turn. Mirror a
+     * server interrupt so the consumer UI returns to listening immediately; the
+     * gateway's own (slower) interrupt follows and lifts the suppression.
+     */
+    handleLocalBargeIn() {
+        if (!this.aiSpeaking)
+            return; // only meaningful while the AI is talking
+        this.setAiSpeaking(false);
+        this.eventHandler?.({ type: 'response.interrupted' });
+        this.guardAgainstEcho();
+    }
+    // A device whose AEC fails leaks the AI's own voice into the mic, which the
+    // barge-in detector reads as the user talking — firing repeatedly. A real user
+    // never barges in this often, so a burst means the AEC isn't working: downgrade
+    // THIS session to half-duplex (mic gated while the AI speaks + native barge-in
+    // disarmed) so the echo can't keep cutting the AI. Per-session — a fresh
+    // session re-tries full-duplex.
+    guardAgainstEcho() {
+        if (this.echoDowngraded)
+            return;
+        const now = Date.now();
+        this.bargeInTimes.push(now);
+        this.bargeInTimes = this.bargeInTimes.filter((t) => now - t <= ECHO_GUARD_WINDOW_MS);
+        if (this.bargeInTimes.length >= ECHO_GUARD_BARGE_INS) {
+            this.echoDowngraded = true;
+            this.fullDuplex = false;
+            QafkaAudio_1.QafkaAudio.setBargeInEnabled(false).catch(() => { });
+            QafkaAudio_1.QafkaAudio.resumePlayback().catch(() => { });
+            this.syncMicForwarding();
+        }
+    }
     attachAudioListener() {
         if (this.audioUnsubscribe)
             return; // already attached
@@ -137,6 +224,26 @@ class RealtimeService {
         this.audioUnsubscribe?.();
         this.audioUnsubscribe = null;
     }
+    // Attach/detach mic→server forwarding from the combined mute + AI-speaking
+    // state. Both underlying calls are idempotent, so this is safe to call often.
+    syncMicForwarding() {
+        if ((0, decide_mic_forwarding_1.shouldForwardMicAudio)({
+            micEnabled: this.micEnabled,
+            aiSpeaking: this.aiSpeaking,
+            fullDuplex: this.fullDuplex,
+        })) {
+            this.attachAudioListener();
+        }
+        else {
+            this.detachAudioListener();
+        }
+    }
+    setAiSpeaking(speaking) {
+        if (this.aiSpeaking === speaking)
+            return;
+        this.aiSpeaking = speaking;
+        this.syncMicForwarding();
+    }
     async startAudioPipeline() {
         try {
             // Android needs the RECORD_AUDIO runtime permission requested explicitly
@@ -152,7 +259,12 @@ class RealtimeService {
             }
             // Attach listener BEFORE startCapture so the native tap
             // doesn't drop early buffers (hasListeners/listenerCount gate).
-            this.attachAudioListener();
+            // Fresh capture: the AI isn't speaking yet; sync respects any mute state.
+            this.aiSpeaking = false;
+            this.syncMicForwarding();
+            if (!this.bargeInUnsubscribe) {
+                this.bargeInUnsubscribe = QafkaAudio_1.QafkaAudio.onBargeIn(() => this.handleLocalBargeIn());
+            }
             await QafkaAudio_1.QafkaAudio.startCapture();
         }
         catch (error) {
@@ -181,10 +293,12 @@ class RealtimeService {
     * tool flows where the user shouldn't interrupt but the AI may still speak.
     */
     muteMic() {
-        this.detachAudioListener();
+        this.micEnabled = false;
+        this.syncMicForwarding();
     }
     unmuteMic() {
-        this.attachAudioListener();
+        this.micEnabled = true;
+        this.syncMicForwarding();
     }
     sendToolResult(payload) {
         if (this.ws?.readyState !== WebSocket.OPEN) {
@@ -213,6 +327,8 @@ class RealtimeService {
     async cleanup() {
         this.audioUnsubscribe?.();
         this.audioUnsubscribe = null;
+        this.bargeInUnsubscribe?.();
+        this.bargeInUnsubscribe = null;
         try {
             await QafkaAudio_1.QafkaAudio.stopCapture();
         }

package/dist/utils/extractionContinuation.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Helpers for auto-continuing a multi-step file-input tool flow after a
+ * document is uploaded and its fields are extracted.
+ *
+ * Background: uploading a file + extracting its fields does NOT, on its own,
+ * start a new model turn. Only a fresh `/chat` turn re-enables tools, which is
+ * what lets the model advance to the next step (e.g. ask the first question).
+ * For multi-step file tools we therefore fire a hidden continuation turn that
+ * carries the extracted fields so the model can proceed.
+ *
+ * These helpers are intentionally generic — they know nothing about any
+ * specific tool, field name, or domain.
+ */
+/** A suggested tool spans multiple steps AND collects a file when it exposes
+ * both a `step` parameter and a file-input module. Single-shot file tools
+ * (extract → render → done) are excluded. */
+export declare function isMultiStepFileTool(tool: any): boolean;
+/** Auto-advance only once a multi-step file tool's extraction has completed.
+ * Incomplete extractions and single-shot tools stay on the normal path. */
+export declare function shouldAutoContinueAfterExtraction(args: {
+    isMultiStepFileTool: boolean;
+    extractionStatus?: string;
+}): boolean;
+/** Build the hidden continuation message. The extracted fields are embedded
+ * inline as JSON: in practice the model only reliably uses the values (and
+ * stays on-script / in-language) when they are present in the message itself —
+ * a generic "read it from context" trigger derails it. The data IS also in the
+ * `context` prop, but this inline copy is what keeps the continuation reliable.
+ * Keeping it out of the persisted transcript is handled separately, server side,
+ * not by stripping it here.
+ */
+export declare function buildExtractionContinuationMessage(data: Record<string, any> | undefined | null): string;

package/dist/utils/extractionContinuation.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Helpers for auto-continuing a multi-step file-input tool flow after a
+ * document is uploaded and its fields are extracted.
+ *
+ * Background: uploading a file + extracting its fields does NOT, on its own,
+ * start a new model turn. Only a fresh `/chat` turn re-enables tools, which is
+ * what lets the model advance to the next step (e.g. ask the first question).
+ * For multi-step file tools we therefore fire a hidden continuation turn that
+ * carries the extracted fields so the model can proceed.
+ *
+ * These helpers are intentionally generic — they know nothing about any
+ * specific tool, field name, or domain.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isMultiStepFileTool = isMultiStepFileTool;
+exports.shouldAutoContinueAfterExtraction = shouldAutoContinueAfterExtraction;
+exports.buildExtractionContinuationMessage = buildExtractionContinuationMessage;
+/** A suggested tool spans multiple steps AND collects a file when it exposes
+ * both a `step` parameter and a file-input module. Single-shot file tools
+ * (extract → render → done) are excluded. */
+function isMultiStepFileTool(tool) {
+    const params = tool?.parameters;
+    const hasStep = !!params && typeof params === 'object' && 'step' in params;
+    return Boolean(tool?.modules?.hasFileInput) && hasStep;
+}
+/** Auto-advance only once a multi-step file tool's extraction has completed.
+ * Incomplete extractions and single-shot tools stay on the normal path. */
+function shouldAutoContinueAfterExtraction(args) {
+    return args.isMultiStepFileTool && args.extractionStatus === 'complete';
+}
+/** Build the hidden continuation message. The extracted fields are embedded
+ * inline as JSON: in practice the model only reliably uses the values (and
+ * stays on-script / in-language) when they are present in the message itself —
+ * a generic "read it from context" trigger derails it. The data IS also in the
+ * `context` prop, but this inline copy is what keeps the continuation reliable.
+ * Keeping it out of the persisted transcript is handled separately, server side,
+ * not by stripping it here.
+ */
+function buildExtractionContinuationMessage(data) {
+    const fields = data && typeof data === 'object' ? JSON.stringify(data) : '{}';
+    return [
+        '[Uploaded document — extracted fields]',
+        fields,
+        '',
+        '(The user just uploaded a document and it was processed. Use these fields to continue the tool flow — proceed to the next step. Do not restart or repeat the greeting.)',
+    ].join('\n');
+}

package/dist/utils/joinNarration.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Joins two pieces of assistant narration into a single text body with a
+ * consistent paragraph break.
+ *
+ * A custom-with-ai tool produces a reply in two streamed parts (e.g. a first
+ * reply, then a follow-up after a file upload). Those parts land in the same
+ * assistant bubble, so they must be separated the same way everywhere — both in
+ * the live render and in what the backend persists — otherwise the live text
+ * comes out glued together with no break (".. yeterli!Harika! ..").
+ *
+ * Rules: empty parts pass through untouched; if `prev` already ends with a
+ * newline, no extra break is added; otherwise the two parts are joined with a
+ * blank line.
+ */
+export declare function joinNarration(prev: string, next: string): string;

package/dist/utils/joinNarration.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.joinNarration = joinNarration;
+/**
+ * Joins two pieces of assistant narration into a single text body with a
+ * consistent paragraph break.
+ *
+ * A custom-with-ai tool produces a reply in two streamed parts (e.g. a first
+ * reply, then a follow-up after a file upload). Those parts land in the same
+ * assistant bubble, so they must be separated the same way everywhere — both in
+ * the live render and in what the backend persists — otherwise the live text
+ * comes out glued together with no break (".. yeterli!Harika! ..").
+ *
+ * Rules: empty parts pass through untouched; if `prev` already ends with a
+ * newline, no extra break is added; otherwise the two parts are joined with a
+ * blank line.
+ */
+function joinNarration(prev, next) {
+    if (!prev)
+        return next || '';
+    if (!next)
+        return prev;
+    const sep = prev.endsWith('\n') ? '' : '\n\n';
+    return prev + sep + next;
+}

package/dist/utils/toolNarration.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Whether to skip the turn-2 narration (the post-tool-result round-trip) for a
+ * suggested tool.
+ *
+ * custom-with-ai tools answer in two streamed parts: the model's first reply
+ * (the "bridge", produced alongside the tool call) and a turn-2 narration of
+ * the tool result. Which one carries the real content is per-tool:
+ *  - **File-input tools** (e.g. an interview driven by an uploaded CV) are
+ *    bridge-primary: the model writes the full reply in the bridge (it responds
+ *    to the post-upload continuation), so the turn-2 narration just repeats it.
+ *    Skip turn-2 for these.
+ *  - **Non-file tools** (e.g. a date-availability check) are turn-2-primary:
+ *    the bridge is a short "checking…" filler and the SUBSTANTIVE result lives
+ *    only in the turn-2 narration. Skipping it would leave the flow hanging, so
+ *    turn-2 must still run.
+ *
+ * We therefore gate on `hasFileInput` in addition to custom-with-ai + card.
+ * (A per-tool flag would be cleaner long-term; this heuristic distinguishes the
+ * current bridge-primary vs turn-2-primary tools.)
+ */
+export declare function shouldSkipTurn2Narration(tool: any): boolean;

package/dist/utils/toolNarration.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldSkipTurn2Narration = shouldSkipTurn2Narration;
+/**
+ * Whether to skip the turn-2 narration (the post-tool-result round-trip) for a
+ * suggested tool.
+ *
+ * custom-with-ai tools answer in two streamed parts: the model's first reply
+ * (the "bridge", produced alongside the tool call) and a turn-2 narration of
+ * the tool result. Which one carries the real content is per-tool:
+ *  - **File-input tools** (e.g. an interview driven by an uploaded CV) are
+ *    bridge-primary: the model writes the full reply in the bridge (it responds
+ *    to the post-upload continuation), so the turn-2 narration just repeats it.
+ *    Skip turn-2 for these.
+ *  - **Non-file tools** (e.g. a date-availability check) are turn-2-primary:
+ *    the bridge is a short "checking…" filler and the SUBSTANTIVE result lives
+ *    only in the turn-2 narration. Skipping it would leave the flow hanging, so
+ *    turn-2 must still run.
+ *
+ * We therefore gate on `hasFileInput` in addition to custom-with-ai + card.
+ * (A per-tool flag would be cleaner long-term; this heuristic distinguishes the
+ * current bridge-primary vs turn-2-primary tools.)
+ */
+function shouldSkipTurn2Narration(tool) {
+    return (tool?.executionMode === 'custom-with-ai' &&
+        tool?.uiConfig?.responseType === 'card' &&
+        tool?.modules?.hasFileInput === true);
+}

package/ios/QafkaAudio.m

@@ -20,4 +20,13 @@ RCT_EXTERN_METHOD(stopPlayback:
                   (RCTPromiseResolveBlock)resolve
                   rejecter:(RCTPromiseRejectBlock)reject)
 
+RCT_EXTERN_METHOD(resumePlayback:
+                  (RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(setBargeInEnabled:
+                  (BOOL)enabled
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
 @end

package/ios/QafkaAudio.swift

@@ -1,6 +1,7 @@
 import Foundation
 import AVFoundation
 import React
+import os
 
 #if DEBUG
 private func qafkaLog(_ message: String) { NSLog("%@", message) }
@@ -18,6 +19,58 @@ class QafkaAudio: RCTEventEmitter {
   private var configChangeObserver: NSObjectProtocol?
   private var playChunkCount = 0
 
+  // MARK: - Client-side barge-in state
+  //
+  // While the AI is playing, a sustained mic-energy spike means the user is
+  // talking over it — cut playback locally and emit `onBargeIn` instead of
+  // waiting for the server's slower interrupt signal. VPIO (Apple AEC) keeps
+  // the mic near-silent during playback, so a spike is a clear user signal.
+  // `suppressPlayback` then drops the rest of the cancelled turn until JS lifts
+  // it at the next turn boundary (resumePlayback) or the safety cap elapses.
+  //
+  // These scalars are read/written from both the capture-tap thread and the
+  // bridge thread (playAudioChunk / resumePlayback / setBargeInEnabled), so all
+  // access goes through `stateLock`. (Android uses @Volatile for the same set.)
+  private let stateLock: os_unfair_lock_t = {
+    let lock = os_unfair_lock_t.allocate(capacity: 1)
+    lock.initialize(to: os_unfair_lock())
+    return lock
+  }()
+  private var lastPlaybackWriteMs: Double = 0
+  private var suppressPlayback = false
+  private var bargeInAtMs: Double = 0
+  // Gates client-side barge-in detection. JS disarms it when it detects the
+  // device's AEC is failing (a burst of barge-ins = the AI's own echo, not a
+  // user) and downgrades to half-duplex, so the echo can't keep cutting the AI.
+  private var bargeInEnabled = true
+  // Consecutive over-threshold reads; only touched on the capture-tap thread.
+  private var bargeInHighReads = 0
+
+  // Barge-in tuning. iOS mic RMS is normalized to [0,1] (sample / Int16.max),
+  // unlike Android's raw Int16 (its threshold 1200/32767 ≈ 0.035). Require a
+  // couple of consecutive reads to reject transient clicks; only armed while the
+  // AI is actively playing. Tune on device.
+  private static let bargeInRmsThreshold: Float = 0.035
+  private static let bargeInSustainReads = 2
+  private static let playbackActiveWindowMs: Double = 350
+  // Safety cap: if no turn-end signal lifts suppression, resume anyway so a
+  // missed event can't permanently mute the next turn.
+  private static let suppressMaxMs: Double = 6000
+
+  @inline(__always)
+  private func withStateLock<T>(_ body: () -> T) -> T {
+    os_unfair_lock_lock(stateLock)
+    defer { os_unfair_lock_unlock(stateLock) }
+    return body()
+  }
+
+  // Monotonic milliseconds for the playback-active window and suppression cap
+  // (wall-clock jumps must not affect timing). Deltas only.
+  @inline(__always)
+  private func nowMs() -> Double {
+    return Double(DispatchTime.now().uptimeNanoseconds) / 1_000_000.0
+  }
+
   // MARK: - RCTEventEmitter overrides
 
   override static func requiresMainQueueSetup() -> Bool {
@@ -25,7 +78,7 @@ class QafkaAudio: RCTEventEmitter {
   }
 
   override func supportedEvents() -> [String]! {
-    return ["onAudioData", "onAmplitude"]
+    return ["onAudioData", "onAmplitude", "onBargeIn"]
   }
 
   override func startObserving() {
@@ -106,6 +159,16 @@ class QafkaAudio: RCTEventEmitter {
   ) {
     qafkaLog("[QafkaAudio] === doStartCapture begin ===")
 
+    // Fresh session starts full-duplex (barge-in armed) with no suppression;
+    // JS downgrades to half-duplex later if it detects the AEC is failing.
+    withStateLock {
+      bargeInEnabled = true
+      suppressPlayback = false
+      lastPlaybackWriteMs = 0
+      bargeInAtMs = 0
+    }
+    bargeInHighReads = 0
+
     // Defensive startup cleanup — recover from any leaked VPIO/audio-unit state
     // left by a prior crashed session. Apple Forums 721535 confirms the combo
     // of (deactivate) + (force category) + (output-port toggle) is needed to
@@ -215,6 +278,29 @@ class QafkaAudio: RCTEventEmitter {
         let rms = sqrt(sumSquares / Float(sampleCount))
         let level = min(rms * 3.0, 1.0)
         self.sendEvent(withName: "onAmplitude", body: ["level": level, "source": "mic"])
+
+        // Client-side barge-in: while the AI is actively playing, a sustained
+        // mic-energy spike means the user is talking over it — cut locally
+        // instead of waiting for the server's slower interrupt signal.
+        // Reuse the raw normalized `rms` (not the *3 display level).
+        let now = self.nowMs()
+        let (suppress, enabled, lastWrite) = self.withStateLock {
+          (self.suppressPlayback, self.bargeInEnabled, self.lastPlaybackWriteMs)
+        }
+        let playbackActive = (now - lastWrite) < QafkaAudio.playbackActiveWindowMs
+        if playbackActive && !suppress && enabled {
+          if rms > QafkaAudio.bargeInRmsThreshold {
+            self.bargeInHighReads += 1
+            if self.bargeInHighReads >= QafkaAudio.bargeInSustainReads {
+              self.bargeInHighReads = 0
+              self.triggerBargeIn()
+            }
+          } else {
+            self.bargeInHighReads = 0
+          }
+        } else {
+          self.bargeInHighReads = 0
+        }
       }
 
       let base64String = audioData.base64EncodedString()
@@ -394,6 +480,8 @@ class QafkaAudio: RCTEventEmitter {
       engine.reset()
       try? AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
     }
+    stateLock.deinitialize(count: 1)
+    stateLock.deallocate()
   }
 
   // MARK: - Playback
@@ -406,6 +494,30 @@ class QafkaAudio: RCTEventEmitter {
     playChunkCount += 1
     let isLoggedChunk = playChunkCount <= 3 || playChunkCount % 50 == 0
 
+    // Drop the AI's remaining audio after a local barge-in until the turn
+    // boundary lifts suppression (or the safety cap elapses). Without this the
+    // in-flight deltas of the just-cancelled turn would refill the player and
+    // the AI would audibly resume right after we cut it.
+    let now = nowMs()
+    var autoLifted = false
+    let drop: Bool = withStateLock {
+      guard suppressPlayback else { return false }
+      if now - bargeInAtMs > QafkaAudio.suppressMaxMs {
+        suppressPlayback = false
+        autoLifted = true
+        return false
+      }
+      return true
+    }
+    if autoLifted {
+      qafkaLog("[QafkaAudio] ⏱️ playAudioChunk #\(playChunkCount): suppression auto-lifted (6s safety cap)")
+    }
+    if drop {
+      qafkaLog("[QafkaAudio] 🚫 playAudioChunk #\(playChunkCount): dropped — barge-in suppression active")
+      resolve(true)
+      return
+    }
+
     guard let player = playerNode, let engine = audioEngine else {
       qafkaLog("[QafkaAudio] ❌ playAudioChunk #\(playChunkCount): engine not running")
       reject("NOT_RUNNING", "Audio engine is not running. Call startCapture first.", nil)
@@ -493,6 +605,9 @@ class QafkaAudio: RCTEventEmitter {
     }
 
     player.scheduleBuffer(outputBuffer, completionHandler: nil)
+    // Mark the playback as active so the capture tap's barge-in detector only
+    // arms while the AI is genuinely streaming audio (see playbackActiveWindowMs).
+    withStateLock { lastPlaybackWriteMs = nowMs() }
     if isLoggedChunk {
       qafkaLog("[QafkaAudio] 🔊 playAudioChunk #\(playChunkCount): scheduled \(outputBuffer.frameLength)f @ \(mixerFormat.sampleRate)Hz playerPlaying=\(player.isPlaying) engineRunning=\(engine.isRunning)")
     }
@@ -516,4 +631,59 @@ class QafkaAudio: RCTEventEmitter {
 
     resolve(true)
   }
+
+  // MARK: - Barge-in
+
+  /// Called from the capture tap when a sustained mic-energy spike is detected
+  /// while the AI is playing. Cuts playback instantly (purging scheduled
+  /// buffers) and starts dropping the cancelled turn's remaining audio; JS lifts
+  /// suppression at the next turn boundary via resumePlayback().
+  private func triggerBargeIn() {
+    withStateLock {
+      suppressPlayback = true
+      bargeInAtMs = nowMs()
+    }
+    // Tell JS immediately (UI → listening). sendEvent from the tap thread is
+    // already used above for onAudioData/onAmplitude.
+    sendEvent(withName: "onBargeIn", body: [String: Any]())
+    // Purge the cancelled turn's queued buffers OFF the capture-tap thread.
+    // AVAudioPlayerNode.stop() called from the tap (audio IO) callback can stall
+    // the IO thread (sluggish cut + choppy mic) and leave the node not rendering
+    // afterwards (the next turn schedules buffers that never sound — "stuck in
+    // listening"). The suppress flag above already drops NEW audio synchronously,
+    // so the cut still feels instant; deferring only the buffer purge to the main
+    // queue (where the config-change handler also does engine ops) is safe. Same
+    // stop()+play() pattern as stopPlayback, just off the IO thread.
+    DispatchQueue.main.async { [weak self] in
+      guard let self = self else { return }
+      self.playerNode?.stop()
+      self.playerNode?.play()
+      qafkaLog("[QafkaAudio] ⚡ Local barge-in cut applied (playerPlaying=\(self.playerNode?.isPlaying ?? false) engineRunning=\(self.audioEngine?.isRunning ?? false))")
+    }
+  }
+
+  @objc func resumePlayback(
+    _ resolve: @escaping RCTPromiseResolveBlock,
+    rejecter reject: @escaping RCTPromiseRejectBlock
+  ) {
+    withStateLock { suppressPlayback = false }
+    qafkaLog("[QafkaAudio] ▶️ resumePlayback — suppression lifted")
+    resolve(true)
+  }
+
+  /// Arm/disarm client-side barge-in. JS disarms it after detecting the device's
+  /// echo cancellation is failing (downgrade to half-duplex), so the AI's own
+  /// leaked echo can't keep triggering a cut. Disarming also clears suppression.
+  @objc func setBargeInEnabled(
+    _ enabled: Bool,
+    resolver resolve: @escaping RCTPromiseResolveBlock,
+    rejecter reject: @escaping RCTPromiseRejectBlock
+  ) {
+    withStateLock {
+      bargeInEnabled = enabled
+      if !enabled { suppressPlayback = false }
+    }
+    qafkaLog("[QafkaAudio] setBargeInEnabled=\(enabled)")
+    resolve(true)
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qafka/react-native",
-  "version": "2.3.8",
+  "version": "2.4.0",
   "description": "Drop-in AI assistant for React Native: chat, voice, and tool execution with screen-aware navigation.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -15,7 +15,7 @@
     "react-native.config.js",
     "qafka.config.js",
     "qafka.config.d.ts",
-    "docs",
+    "docs/qafka-tool-authoring-guide.md",
     "README.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",