@qafka/react-native 2.3.9 → 2.4.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+## [2.4.0] — 2026-06-21
+
+### Added
+
+- Full-duplex voice (barge-in): users can now interrupt the AI by speaking while it is talking. The microphone stays open during playback and the AI stops promptly when the user talks over it. On devices whose echo cancellation underperforms, the session automatically falls back to half-duplex so the AI's own audio is never mistaken for user speech.
+
+### Fixed
+
+- Voice echo on both iOS and Android: the AI's playback no longer leaks back into the microphone (where it could be transcribed as user input). Audio is routed through the platform's voice-communication path — Apple VPIO on iOS, communication-mode capture with hardware echo cancellation on Android — and played on the loudspeaker.
+
 ## [2.3.8] — 2026-06-17
 
 ### Added

package/android/src/main/AndroidManifest.xml

@@ -1,4 +1,9 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
     <!-- Required for voice capture. Merged into the consumer app manifest. -->
     <uses-permission android:name="android.permission.RECORD_AUDIO" />
+    <!-- Required to set MODE_IN_COMMUNICATION and route playback to the
+         loudspeaker (setCommunicationDevice / setSpeakerphoneOn) for hands-free
+         voice. Without it those calls are silently denied and audio stays on the
+         earpiece. This is a normal (install-time) permission. -->
+    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
 </manifest>

package/android/src/main/java/com/qafka/audio/QafkaAudioModule.kt

@@ -5,6 +5,7 @@ import android.content.Context
 import android.content.pm.PackageManager
 import android.media.AudioAttributes
 import android.media.AudioFormat
+import android.media.AudioDeviceInfo
 import android.media.AudioManager
 import android.media.AudioRecord
 import android.media.AudioTrack
@@ -12,6 +13,7 @@ import android.media.MediaRecorder
 import android.media.audiofx.AcousticEchoCanceler
 import android.media.audiofx.AutomaticGainControl
 import android.media.audiofx.NoiseSuppressor
+import android.os.Build
 import android.util.Base64
 import android.util.Log
 import androidx.core.content.ContextCompat
@@ -29,6 +31,20 @@ class QafkaAudioModule(reactContext: ReactApplicationContext) :
     @Volatile private var isCapturing = false
     private var listenerCount = 0
 
+    // Client-side barge-in. The server-side VAD interrupt is too slow to
+    // cut the AI promptly, but the on-device AEC keeps the mic clean (the user's
+    // voice is a clear energy spike vs near-zero silence), so we detect the
+    // barge-in locally and cut playback instantly. `suppressPlayback` then drops
+    // the rest of the now-cancelled turn until the next turn boundary, when JS
+    // calls resumePlayback().
+    @Volatile private var lastPlaybackWriteMs = 0L
+    @Volatile private var suppressPlayback = false
+    @Volatile private var bargeInAtMs = 0L
+    // Gates client-side barge-in detection. JS turns it OFF 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.
+    @Volatile private var bargeInEnabled = true
+
     // iOS VPIO equivalent — hardware AEC + NS + AGC (android.media.audiofx).
     // Enables barge-in by cancelling playback echo at mic level.
     // Device-dependent; isAvailable() + null checks keep it safe.
@@ -48,6 +64,17 @@ class QafkaAudioModule(reactContext: ReactApplicationContext) :
         private const val CHANNEL_IN = AudioFormat.CHANNEL_IN_MONO
         private const val CHANNEL_OUT = AudioFormat.CHANNEL_OUT_MONO
         private const val AUDIO_ENCODING = AudioFormat.ENCODING_PCM_16BIT
+
+        // Barge-in detection tuning. Mic RMS is ~0 in silence (AEC removes the
+        // AI's echo) and ~2000-5000 when the user speaks, so the threshold sits
+        // comfortably between. Require a couple of consecutive ~128ms reads to
+        // reject transient clicks; only armed while the AI is actively playing.
+        private const val BARGE_IN_RMS_THRESHOLD = 1200.0
+        private const val BARGE_IN_SUSTAIN_READS = 2
+        private const val PLAYBACK_ACTIVE_WINDOW_MS = 350L
+        // Safety cap: if no turn-end signal arrives to lift suppression, resume
+        // anyway so a missed event can't permanently mute the next turn.
+        private const val SUPPRESS_MAX_MS = 6000L
     }
 
     /**
@@ -98,6 +125,11 @@ class QafkaAudioModule(reactContext: ReactApplicationContext) :
             return
         }
 
+        // Fresh session starts full-duplex (barge-in armed) with no suppression;
+        // JS downgrades to half-duplex later if it detects the AEC is failing.
+        bargeInEnabled = true
+        suppressPlayback = false
+
         // Check permission
         val permission = ContextCompat.checkSelfPermission(
             reactApplicationContext,
@@ -127,13 +159,29 @@ class QafkaAudioModule(reactContext: ReactApplicationContext) :
             val audioManager =
                 reactApplicationContext.getSystemService(Context.AUDIO_SERVICE) as AudioManager
             previousAudioMode = audioManager.mode
-            previousSpeakerphoneOn = audioManager.isSpeakerphoneOn
             audioManager.mode = AudioManager.MODE_IN_COMMUNICATION
-            @Suppress("DEPRECATION")
-            audioManager.isSpeakerphoneOn = true
-            dlogI("✅ AudioManager mode=IN_COMMUNICATION, speakerphone=on")
+            // Route playback to the LOUDSPEAKER for hands-free use. On API 31+
+            // setSpeakerphoneOn is deprecated and a no-op on many devices —
+            // setCommunicationDevice(BUILTIN_SPEAKER) is the supported path.
+            // Requires MODIFY_AUDIO_SETTINGS (declared in the manifest); without
+            // it these calls are silently denied and audio stays on the earpiece.
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+                val speaker = audioManager.availableCommunicationDevices
+                    .firstOrNull { it.type == AudioDeviceInfo.TYPE_BUILTIN_SPEAKER }
+                if (speaker != null) {
+                    val ok = audioManager.setCommunicationDevice(speaker)
+                    dlogI("✅ mode=IN_COMMUNICATION, setCommunicationDevice(speaker)=$ok")
+                } else {
+                    dlogW("⚠️ No BUILTIN_SPEAKER communication device available")
+                }
+            } else {
+                previousSpeakerphoneOn = audioManager.isSpeakerphoneOn
+                @Suppress("DEPRECATION")
+                audioManager.isSpeakerphoneOn = true
+                dlogI("✅ mode=IN_COMMUNICATION, speakerphone=on (legacy)")
+            }
         } catch (e: Exception) {
-            dlogW("⚠️ Failed to set communication audio mode: ${e.message}")
+            dlogW("⚠️ Failed to set communication audio routing: ${e.message}")
         }
 
         try {
@@ -185,17 +233,21 @@ class QafkaAudioModule(reactContext: ReactApplicationContext) :
             }
 
             // Initialize AudioTrack for playback.
-            // The voice-communication output path favors low latency with a
-            // small default buffer; that underruns on jittery streamed network
-            // audio and makes playback choppy ("skipping"). Size the buffer for
-            // ~0.4s of audio to absorb jitter — smoothness matters more than
-            // latency for an assistant reply.
+            // The original ~0.4s jitter buffer (chosen for playback
+            // smoothness) pushes the echo-path delay far out and renders network
+            // audio in large, late, sometimes-underrunning bursts — which the
+            // OS echo canceler cannot align/reference, so the AI's playback
+            // leaks back into the mic. Shrink to ~150ms to pull the echo-path
+            // delay into the AEC's tracking window (and reduce the BUFFER
+            // TIMEOUT underruns seen in logcat). The maxOf floor still keeps it
+            // at/above the device minimum so it can't underflow outright.
             val playMinBuffer = AudioTrack.getMinBufferSize(
                 PLAYBACK_SAMPLE_RATE, CHANNEL_OUT, AUDIO_ENCODING
             )
-            // bytes/sec = sampleRate * 2 (16-bit mono); * 4 / 10 ≈ 0.4s
-            val jitterBufferBytes = PLAYBACK_SAMPLE_RATE * 2 * 4 / 10
+            // bytes/sec = sampleRate * 2 (16-bit mono); * 15 / 100 ≈ 0.15s
+            val jitterBufferBytes = PLAYBACK_SAMPLE_RATE * 2 * 15 / 100
             val playBufferSize = maxOf(playMinBuffer * 2, jitterBufferBytes)
+            dlogI("🔧 playbackBuffer=$playBufferSize bytes (~${playBufferSize * 1000 / (PLAYBACK_SAMPLE_RATE * 2)}ms)")
 
             // iOS VPIO equivalent (part 2): play on the voice-communication path
             // (USAGE_VOICE_COMMUNICATION + CONTENT_TYPE_SPEECH) so the echo
@@ -214,6 +266,13 @@ class QafkaAudioModule(reactContext: ReactApplicationContext) :
                         .setEncoding(AUDIO_ENCODING)
                         .build()
                 )
+                // Bind playback to the SAME audio session as the capture that
+                // AcousticEchoCanceler is attached to. Without this the HAL
+                // cannot correlate the render (AI playback) and capture (mic)
+                // streams, so the echo canceler has no reference to subtract and
+                // silently no-ops — the likely reason hardware AEC "reports
+                // enabled but fails to cancel". Required for full-duplex barge-in.
+                .setSessionId(sessionId)
                 .setBufferSizeInBytes(playBufferSize)
                 .setTransferMode(AudioTrack.MODE_STREAM)
                 .build()
@@ -229,10 +288,36 @@ class QafkaAudioModule(reactContext: ReactApplicationContext) :
             // Start capture thread
             captureThread = Thread {
                 val readBuffer = ShortArray(bufferSize / 2)
+                var highReads = 0
 
                 while (isCapturing) {
                     val shortsRead = record.read(readBuffer, 0, readBuffer.size)
                     if (shortsRead > 0) {
+                        // 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.
+                        val playbackActive =
+                            (System.currentTimeMillis() - lastPlaybackWriteMs) < PLAYBACK_ACTIVE_WINDOW_MS
+                        if (playbackActive && !suppressPlayback && bargeInEnabled) {
+                            var sum = 0.0
+                            for (i in 0 until shortsRead) {
+                                val s = readBuffer[i].toDouble()
+                                sum += s * s
+                            }
+                            val rms = Math.sqrt(sum / shortsRead)
+                            if (rms > BARGE_IN_RMS_THRESHOLD) {
+                                highReads++
+                                if (highReads >= BARGE_IN_SUSTAIN_READS) {
+                                    highReads = 0
+                                    triggerBargeIn()
+                                }
+                            } else {
+                                highReads = 0
+                            }
+                        } else {
+                            highReads = 0
+                        }
                         // Convert shorts to bytes (little-endian PCM 16-bit)
                         val byteBuffer = ByteArray(shortsRead * 2)
                         for (i in 0 until shortsRead) {
@@ -293,11 +378,15 @@ class QafkaAudioModule(reactContext: ReactApplicationContext) :
         try {
             val audioManager =
                 reactApplicationContext.getSystemService(Context.AUDIO_SERVICE) as AudioManager
-            previousAudioMode?.let { audioManager.mode = it }
-            previousSpeakerphoneOn?.let {
-                @Suppress("DEPRECATION")
-                audioManager.isSpeakerphoneOn = it
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+                audioManager.clearCommunicationDevice()
+            } else {
+                previousSpeakerphoneOn?.let {
+                    @Suppress("DEPRECATION")
+                    audioManager.isSpeakerphoneOn = it
+                }
             }
+            previousAudioMode?.let { audioManager.mode = it }
         } catch (_: Exception) {}
         previousAudioMode = null
         previousSpeakerphoneOn = null
@@ -309,6 +398,19 @@ class QafkaAudioModule(reactContext: ReactApplicationContext) :
 
     @ReactMethod
     fun playAudioChunk(base64Data: String, promise: Promise) {
+        // 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 buffer
+        // and the AI would audibly resume right after we cut it.
+        if (suppressPlayback) {
+            if (System.currentTimeMillis() - bargeInAtMs > SUPPRESS_MAX_MS) {
+                suppressPlayback = false
+            } else {
+                promise.resolve(true)
+                return
+            }
+        }
+
         val track = audioTrack
         if (track == null) {
             promise.reject("NOT_RUNNING", "Audio is not running. Call startCapture first.")
@@ -318,6 +420,7 @@ class QafkaAudioModule(reactContext: ReactApplicationContext) :
         try {
             val audioBytes = Base64.decode(base64Data, Base64.DEFAULT)
             track.write(audioBytes, 0, audioBytes.size)
+            lastPlaybackWriteMs = System.currentTimeMillis()
             promise.resolve(true)
         } catch (e: Exception) {
             promise.reject("PLAYBACK_ERROR", "Failed to play audio chunk: ${e.message}", e)
@@ -328,6 +431,8 @@ class QafkaAudioModule(reactContext: ReactApplicationContext) :
 
     @ReactMethod
     fun stopPlayback(promise: Promise) {
+        // Purges queued playback when the server signals the user interrupted
+        // (response.interrupted) so the cancelled turn stops promptly.
         val track = audioTrack ?: run {
             promise.resolve(true)
             return
@@ -342,4 +447,44 @@ class QafkaAudioModule(reactContext: ReactApplicationContext) :
             promise.reject("PLAYBACK_ERROR", "Failed to stop playback: ${e.message}", e)
         }
     }
+
+    // MARK: - Barge-in
+
+    /**
+     * Called from the capture thread when a sustained mic-energy spike is
+     * detected while the AI is playing. Cuts playback instantly and starts
+     * dropping the cancelled turn's remaining audio; JS lifts suppression at the
+     * next turn boundary via resumePlayback().
+     */
+    private fun triggerBargeIn() {
+        suppressPlayback = true
+        bargeInAtMs = System.currentTimeMillis()
+        try {
+            audioTrack?.let {
+                it.pause()
+                it.flush()
+                it.play()
+            }
+        } catch (_: Exception) {}
+        dlogI("⚡ Local barge-in — cut playback, suppressing cancelled turn")
+        sendEvent("onBargeIn", Arguments.createMap())
+    }
+
+    @ReactMethod
+    fun resumePlayback(promise: Promise) {
+        suppressPlayback = false
+        promise.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.
+     */
+    @ReactMethod
+    fun setBargeInEnabled(enabled: Boolean, promise: Promise) {
+        bargeInEnabled = enabled
+        if (!enabled) suppressPlayback = false
+        promise.resolve(true)
+    }
 }

package/dist/decide-mic-forwarding.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Decides whether mic audio should be forwarded to the server.
+ *
+ * Gates, in order of precedence:
+ *  - `micEnabled`: the user/system mute state (false = muted). Always wins.
+ *  - `fullDuplex`: when true, the native OS echo canceler
+ *    (MODE_IN_COMMUNICATION + AcousticEchoCanceler bound to the shared capture
+ *    session, see QafkaAudioModule) is trusted to strip the AI's playback out
+ *    of the mic, so the mic stays open while the AI speaks — this is what
+ *    enables voice barge-in. Defaults to false.
+ *  - `aiSpeaking` is false: half-duplex gate, used only when `fullDuplex` is
+ *    off. While the AI is speaking we stop forwarding so its own playback,
+ *    echoed into the mic, isn't transcribed as a user turn (there is no
+ *    server-side echo cancellation upstream).
+ *
+ * Pure function so the gating logic is unit-testable without the native-bound
+ * RealtimeService.
+ */
+export declare function shouldForwardMicAudio(state: {
+    micEnabled: boolean;
+    aiSpeaking: boolean;
+    fullDuplex?: boolean;
+}): boolean;

package/dist/decide-mic-forwarding.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldForwardMicAudio = shouldForwardMicAudio;
+/**
+ * Decides whether mic audio should be forwarded to the server.
+ *
+ * Gates, in order of precedence:
+ *  - `micEnabled`: the user/system mute state (false = muted). Always wins.
+ *  - `fullDuplex`: when true, the native OS echo canceler
+ *    (MODE_IN_COMMUNICATION + AcousticEchoCanceler bound to the shared capture
+ *    session, see QafkaAudioModule) is trusted to strip the AI's playback out
+ *    of the mic, so the mic stays open while the AI speaks — this is what
+ *    enables voice barge-in. Defaults to false.
+ *  - `aiSpeaking` is false: half-duplex gate, used only when `fullDuplex` is
+ *    off. While the AI is speaking we stop forwarding so its own playback,
+ *    echoed into the mic, isn't transcribed as a user turn (there is no
+ *    server-side echo cancellation upstream).
+ *
+ * Pure function so the gating logic is unit-testable without the native-bound
+ * RealtimeService.
+ */
+function shouldForwardMicAudio(state) {
+    if (!state.micEnabled)
+        return false;
+    if (state.fullDuplex)
+        return true;
+    return !state.aiSpeaking;
+}

package/dist/native/QafkaAudio.d.ts

@@ -10,6 +10,8 @@ export declare const QafkaAudio: {
     stopCapture: () => Promise<boolean>;
     playAudioChunk: (base64Data: string) => Promise<boolean>;
     stopPlayback: () => Promise<boolean>;
+    resumePlayback: () => Promise<boolean>;
+    setBargeInEnabled: (enabled: boolean) => Promise<boolean>;
     onAudioData: (callback: (data: {
         audio: string;
     }) => void) => () => void | undefined;
@@ -17,5 +19,6 @@ export declare const QafkaAudio: {
         level: number;
         source: "mic" | "speaker";
     }) => void) => () => void | undefined;
+    onBargeIn: (callback: () => void) => () => void | undefined;
     isAvailable: () => boolean;
 };

package/dist/native/QafkaAudio.js

@@ -47,6 +47,12 @@ exports.QafkaAudio = {
     stopCapture: () => lifecycleQueue(() => requireModule().stopCapture()),
     playAudioChunk: (base64Data) => requireModule().playAudioChunk(base64Data),
     stopPlayback: () => requireModule().stopPlayback(),
+    // Lift the post-barge-in playback suppression at a turn boundary so the AI's
+    // next turn can play. No-op if nothing is suppressed.
+    resumePlayback: () => requireModule().resumePlayback(),
+    // Arm/disarm native client-side barge-in. JS disarms it after detecting the
+    // device's echo cancellation is failing (downgrade to half-duplex).
+    setBargeInEnabled: (enabled) => requireModule().setBargeInEnabled(enabled),
     onAudioData: (callback) => {
         const subscription = emitter?.addListener('onAudioData', callback);
         return () => subscription?.remove();
@@ -55,5 +61,12 @@ exports.QafkaAudio = {
         const subscription = emitter?.addListener('onAmplitude', callback);
         return () => subscription?.remove();
     },
+    // Fired by the native capture thread when it detects the user talking over the
+    // AI (client-side barge-in). Native has already cut playback; the SDK uses this
+    // to return the UI to listening without waiting for the slow server interrupt.
+    onBargeIn: (callback) => {
+        const subscription = emitter?.addListener('onBargeIn', () => callback());
+        return () => subscription?.remove();
+    },
     isAvailable: () => NativeQafkaAudio != null,
 };

package/dist/services/RealtimeService.d.ts

@@ -49,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;
@@ -64,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

@@ -4,11 +4,40 @@ 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;
@@ -51,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
@@ -118,6 +153,9 @@ 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
             });
@@ -125,11 +163,53 @@ class RealtimeService {
         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.
+            // 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
@@ -144,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
@@ -159,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) {
@@ -188,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) {
@@ -220,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/toolNarration.d.ts

@@ -4,13 +4,18 @@
  *
  * 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. When the tool renders its result as a CARD, the bridge
- * already carries the conversational text and the card shows the data, so the
- * turn-2 text narration is redundant — it just repeats the bridge in a second
- * message. We skip it for those tools.
+ * 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.
  *
- * Tools WITHOUT a card are left untouched: there the substantive answer often
- * lives only in the turn-2 narration (e.g. a lookup whose bridge is a short
- * "one moment" filler), so it 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

@@ -7,16 +7,22 @@ exports.shouldSkipTurn2Narration = shouldSkipTurn2Narration;
  *
  * 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. When the tool renders its result as a CARD, the bridge
- * already carries the conversational text and the card shows the data, so the
- * turn-2 text narration is redundant — it just repeats the bridge in a second
- * message. We skip it for those tools.
+ * 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.
  *
- * Tools WITHOUT a card are left untouched: there the substantive answer often
- * lives only in the turn-2 narration (e.g. a lookup whose bridge is a short
- * "one moment" filler), so it 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?.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.9",
+  "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",