@qafka/react-native 2.3.8 → 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/components/ChatPage.js

@@ -60,7 +60,9 @@ function ChatPage({ displayMessages, isTyping, isSending, streamingMessage, tool
  </react_native_1.View>)}
 
  {/* Message List */}
- <react_native_1.FlatList ref={flatListRef} data={displayMessages} renderItem={renderMessage} keyExtractor={(item) => item.id} style={{ flex: 1, flexGrow: 1, flexShrink: 1 }} contentContainerStyle={styles.messageListStyle} ListEmptyComponent={renderEmpty} showsVerticalScrollIndicator={false} keyboardShouldPersistTaps="handled" onContentSizeChange={() => {
+ <react_native_1.FlatList ref={flatListRef} data={displayMessages} renderItem={renderMessage} keyExtractor={(item) => item.id} style={{ flex: 1, flexGrow: 1, flexShrink: 1 }} contentContainerStyle={styles.messageListStyle} ListEmptyComponent={renderEmpty} showsVerticalScrollIndicator={false} keyboardShouldPersistTaps="handled" ListFooterComponent={toolStatus ? (<react_native_1.View style={{ paddingHorizontal: 8, paddingTop: 4, alignItems: 'flex-start' }}>
+ <ToolStatusPill_1.ToolStatusPill message={toolStatus.message} theme={theme}/>
+ </react_native_1.View>) : null} onContentSizeChange={() => {
             if (displayMessages.length > 0) {
                 flatListRef.current?.scrollToEnd({ animated: true });
             }
@@ -71,10 +73,8 @@ function ChatPage({ displayMessages, isTyping, isSending, streamingMessage, tool
  <TypingIndicator_1.TypingIndicator theme={theme}/>
  </react_native_1.View>)}
 
- {/* Tool Status Pill (server-managed modes) */}
- {toolStatus && (<react_native_1.View style={{ paddingHorizontal: 8, alignItems: 'flex-start' }}>
- <ToolStatusPill_1.ToolStatusPill message={toolStatus.message} theme={theme}/>
- </react_native_1.View>)}
+ {/* Tool Status Pill now renders inside the list (ListFooterComponent)
+        so it sits directly under the last message and scrolls with it. */}
 
  {/* Input Area — hidden until SDK is ready so users can't type a message
         that would be rejected by an un-attested send. TypingIndicator in the

package/dist/decide-interrupt.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns true when a realtime event signals a server-side interruption
+ * (user barge-in), so the caller can stop audio playback and let the user's
+ * new turn take over. Kept as a pure function so the decision is unit-testable
+ * without loading the native-bound RealtimeService.
+ */
+export declare function shouldStopPlayback(event: {
+    type?: string;
+} | null | undefined): boolean;

package/dist/decide-interrupt.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldStopPlayback = shouldStopPlayback;
+/**
+ * Returns true when a realtime event signals a server-side interruption
+ * (user barge-in), so the caller can stop audio playback and let the user's
+ * new turn take over. Kept as a pure function so the decision is unit-testable
+ * without loading the native-bound RealtimeService.
+ */
+function shouldStopPlayback(event) {
+    return event?.type === 'response.interrupted';
+}

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/hooks/useChatMessages.js

@@ -4,6 +4,9 @@ exports.useChatMessages = void 0;
 const react_1 = require("react");
 const QafkaSDK_1 = require("../QafkaSDK");
 const Qafka_utils_1 = require("../components/Qafka.utils");
+const joinNarration_1 = require("../utils/joinNarration");
+const extractionContinuation_1 = require("../utils/extractionContinuation");
+const toolNarration_1 = require("../utils/toolNarration");
 /**
  * Custom hook for managing chat messages and sending
  */
@@ -32,29 +35,47 @@ const useChatMessages = ({ enableStreaming = true, context = {}, contextDescript
     const lastConversationIdRef = (0, react_1.useRef)(null);
     // guard against double-fire of postToolResult per toolKey
     const inFlightPostToolResultRef = (0, react_1.useRef)(new Set());
+    // The most recent suggested tool that is BOTH multi-step and file-input.
+    // Uploading + extracting a file does not start a new model turn on its own,
+    // so when extraction completes we fire a hidden continuation turn (tools
+    // enabled) to let the model advance to the next step. Captured here at
+    // suggestion time because the extraction callback only carries the result,
+    // not the tool definition.
+    const activeMultiStepFileToolRef = (0, react_1.useRef)(null);
+    // Always-current `context` so a deferred send (the post-extraction
+    // continuation) reads the consumer's freshly-updated context (e.g. a CV
+    // summary it set in onExtractionResult) rather than a stale closure value.
+    const contextRef = (0, react_1.useRef)(context);
+    contextRef.current = context;
     const scrollToBottom = (animated = true) => {
         setTimeout(() => {
             flatListRef.current?.scrollToEnd({ animated });
         }, 100);
     };
-    const handleSend = async (message) => {
+    // `hidden` turns send a message to the backend WITHOUT rendering a user
+    // bubble — used to auto-advance a tool flow (e.g. after a file upload) where
+    // the "message" is a system continuation the end user never typed.
+    const handleSend = async (message, options) => {
         if (isSending)
             return;
+        const hidden = options?.hidden === true;
         setIsSending(true);
         setIsTyping(true);
         setStreamingMessage('');
         finalChunkBufferRef.current = '';
-        // Add user message
-        const userMessage = {
-            id: Date.now().toString(),
-            role: 'user',
-            text: message,
-            content: message,
-            timestamp: new Date(),
-        };
-        setMessages((prev) => [...prev, userMessage]);
-        onMessageSent?.(message);
-        scrollToBottom();
+        // Add user message (skipped for hidden continuation turns)
+        if (!hidden) {
+            const userMessage = {
+                id: Date.now().toString(),
+                role: 'user',
+                text: message,
+                content: message,
+                timestamp: new Date(),
+            };
+            setMessages((prev) => [...prev, userMessage]);
+            onMessageSent?.(message);
+            scrollToBottom();
+        }
         const messageToSendAI = contextDescription
             ? `${contextDescription}\n\n${message}`
             : message;
@@ -179,7 +200,7 @@ const useChatMessages = ({ enableStreaming = true, context = {}, contextDescript
                 // onError
                 (err) => {
                     handleError(err);
-                }, context, contextDescription, 
+                }, contextRef.current, contextDescription, 
                 // onToolSuggested
                 async (tools, conversationId, messageId) => {
                     if (conversationId) {
@@ -188,6 +209,12 @@ const useChatMessages = ({ enableStreaming = true, context = {}, contextDescript
                     if (messageId) {
                         lastMessageIdRef.current = messageId;
                     }
+                    // Remember a multi-step file tool so a completed extraction can
+                    // auto-advance the flow (see the onExtractionResult handler below).
+                    const multiStepFileTool = (tools || []).find(extractionContinuation_1.isMultiStepFileTool);
+                    if (multiStepFileTool) {
+                        activeMultiStepFileToolRef.current = multiStepFileTool;
+                    }
                     if (onToolSuggested) {
                         // Tracks tools the consumer's `onToolSuggested` handler explicitly
                         // called `addResponse` for. The auto-fire loop below uses this — NOT
@@ -251,7 +278,13 @@ const useChatMessages = ({ enableStreaming = true, context = {}, contextDescript
                             // In managed follow-up mode the SDK should POST the
                             // tool result back to the backend, which runs a second LLM turn
                             // and streams a `final_chunk` reply.
-                            if (commits && tool?.executionMode === 'custom-with-ai') {
+                            //
+                            // Skipped for card-rendering tools: there the model's first reply
+                            // (bridge) already carries the conversation and the card shows the
+                            // data, so the turn-2 narration only repeats it in a second message.
+                            if (commits &&
+                                tool?.executionMode === 'custom-with-ai' &&
+                                !(0, toolNarration_1.shouldSkipTurn2Narration)(tool)) {
                                 const conversationId = lastConversationIdRef.current;
                                 const messageId = lastMessageIdRef.current;
                                 if (conversationId && messageId) {
@@ -288,7 +321,10 @@ const useChatMessages = ({ enableStreaming = true, context = {}, contextDescript
                                             setMessages((prev) => {
                                                 const lastMsg = prev[prev.length - 1];
                                                 if (lastMsg && lastMsg.role === 'assistant') {
-                                                    const nextText = (lastMsg.text || '') + content;
+                                                    // Turn-2 (post file-upload) narration appends to the same bubble; keep a
+                                                    // paragraph break so it doesn't glue onto turn-1 ("..yeterli!Harika!").
+                                                    // Matches the streaming path's separator and the backend persisted join.
+                                                    const nextText = (0, joinNarration_1.joinNarration)(lastMsg.text || '', content);
                                                     return [
                                                         ...prev.slice(0, -1),
                                                         {
@@ -401,8 +437,26 @@ const useChatMessages = ({ enableStreaming = true, context = {}, contextDescript
                     }
                     onFileUploadRequest?.(request);
                 }, 
-                // onExtractionResult
-                onExtractionResult, 
+                // onExtractionResult — forward to consumer, then auto-advance multi-step
+                // file flows. A completed extraction does not start a new model turn by
+                // itself, so we fire a hidden continuation turn (tools enabled) carrying
+                // the extracted fields, letting the model proceed to the next step.
+                (result) => {
+                    onExtractionResult?.(result);
+                    const tool = activeMultiStepFileToolRef.current;
+                    if ((0, extractionContinuation_1.shouldAutoContinueAfterExtraction)({
+                        isMultiStepFileTool: !!tool,
+                        extractionStatus: result?.status,
+                    })) {
+                        activeMultiStepFileToolRef.current = null;
+                        // A completed extraction does not start a new model turn by itself; fire a
+                        // hidden continuation (tools enabled) carrying the extracted fields inline
+                        // so the model reliably advances to the next step.
+                        void handleSend((0, extractionContinuation_1.buildExtractionContinuationMessage)(result?.data), {
+                            hidden: true,
+                        });
+                    }
+                }, 
                 // onToolStatus: show pill
                 (status) => {
                     setToolStatus(status);
@@ -439,15 +493,12 @@ const useChatMessages = ({ enableStreaming = true, context = {}, contextDescript
                     setToolStatus(null);
                     finalChunkBufferRef.current +=
                         (finalChunkBufferRef.current ? '\n\n' : '') + content;
-                    setStreamingMessage((prev) => {
-                        const sep = prev && !prev.endsWith('\n') ? '\n\n' : '';
-                        return prev + sep + content;
-                    });
+                    setStreamingMessage((prev) => (0, joinNarration_1.joinNarration)(prev, content));
                 });
             }
             else {
                 // Non-streaming
-                const response = await sdk.sendMessage(message, context, contextDescription);
+                const response = await sdk.sendMessage(message, contextRef.current, contextDescription);
                 const aiMessage = {
                     id: response.id,
                     role: 'assistant',

package/dist/hooks/useVoiceChat.js

@@ -131,6 +131,22 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolS
                 }
                 return;
             }
+            case 'response.interrupted': {
+                // Barge-in: the user cut in. RealtimeService already stopped native
+                // playback; finalize the partial AI turn (matching the server, which
+                // persists what was already streamed) and return to listening.
+                const partialAi = transcriptRef.current;
+                if (partialAi && partialAi.trim().length > 0) {
+                    setTranscriptHistory((h) => [
+                        ...h,
+                        { id: `a_${Date.now()}_${h.length}`, role: 'assistant', text: partialAi },
+                    ]);
+                }
+                transcriptRef.current = '';
+                setTranscript('');
+                setState('listening');
+                return;
+            }
             case 'session.closed':
                 setState('idle');
                 setNavigationSuggestion(null);

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