@qafka/react-native 2.3.7 → 2.3.9

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+## [2.3.8] — 2026-06-17
+
+### Added
+
+- Ships `docs/qafka-tool-authoring-guide.md` inside the package — a version-matched guide that tells AI coding assistants (and developers) exactly what to configure in the Qafka dashboard and what to implement in code when authoring a tool. The Qafka CLI points a project's `CLAUDE.md` at this file, so the guidance always matches the installed SDK version.
+
 ## [2.1.1] — 2026-06-03
 
 ### Fixed

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/components/MessageBubble.js

@@ -75,7 +75,8 @@ function MessageBubble({ message, role, timestamp, theme, showTimestamp = true,
                 : dataToRender;
             // Check layout preference (default: vertical)
             const layout = response.layout || 'vertical';
-            // If custom layout, pass entire array to component
+            // If custom layout, pass entire array to component.
+            // VoicePage's tool list branch mirrors this same contract — keep both in sync.
             if (layout === 'custom') {
                 return (<react_native_1.View style={{ marginTop: theme.spacing.md }}>
  <CustomComponent data={items} // Full array

package/dist/components/VoicePage.js

@@ -67,6 +67,18 @@ const BASELINE_PHASE_MS = 800;
 const SPIKE_DURATION_MS = 700;
 const SPIKE_THRESHOLD = 0.3;
 const SPIKE_MIN_INTERVAL_MS = 150;
+// Resolve a uiConfig.dataPath ("data" or nested "data.campaigns") against the
+// tool result envelope. Mirrors MessageBubble's text-mode walk byte-for-byte so
+// list/card data is read from the same level in both render paths. No dataPath
+// → the whole envelope (single-card tools that scope nothing).
+function resolveDataPath(envelope, dataPath) {
+    if (!dataPath)
+        return envelope;
+    let cur = envelope;
+    for (const part of dataPath.split('.'))
+        cur = cur?.[part];
+    return cur;
+}
 // --- Default components (used when customer doesn't provide custom ones) ---
 function DefaultVoiceIndicator({ state, amplitude, theme, isMuted }) {
     // Smoothed amplitude (drives ring opacity factor + core scale).
@@ -532,12 +544,18 @@ function VoicePage({ state, transcript, userTranscript, transcriptHistory, trans
  </react_native_1.View>);
                 }
                 const rt = rtUnion;
+                const ui = rt.tool?.uiConfig;
+                // Resolve list/card data through uiConfig.dataPath BEFORE anything reads it,
+                // so multi-level paths ("data.campaigns") land on the right level instead of
+                // a hardcoded rt.data.data. The empty-data fallback, list slicing and the
+                // non-list branch all read this single resolved value (mirror MessageBubble).
+                const dataToRender = resolveDataPath(rt.data, ui?.dataPath);
+                const isListTool = ui?.responseType === 'list';
                 // Empty-data fallback (matches text chat list-item behavior)
-                const isListTool = rt.tool?.uiConfig?.responseType === 'list';
                 if (isListTool &&
-                    (rt.data?.data === undefined ||
-                        rt.data?.data === null ||
-                        (Array.isArray(rt.data?.data) && rt.data.data.length === 0))) {
+                    (dataToRender === undefined ||
+                        dataToRender === null ||
+                        (Array.isArray(dataToRender) && dataToRender.length === 0))) {
                     return (<react_native_1.View key={rt.toolCallId} style={{
                             padding: 12,
                             backgroundColor: '#f0f0f0',
@@ -546,7 +564,7 @@ function VoicePage({ state, transcript, userTranscript, transcriptHistory, trans
  <react_native_1.Text>No results.</react_native_1.Text>
  </react_native_1.View>);
                 }
-                const componentKey = rt.tool?.uiConfig?.itemComponent || rt.toolKey;
+                const componentKey = ui?.itemComponent || rt.toolKey;
                 const Component = registeredComponents?.[componentKey];
                 if (!Component) {
                     if (__DEV__) {
@@ -554,18 +572,25 @@ function VoicePage({ state, transcript, userTranscript, transcriptHistory, trans
                     }
                     return null;
                 }
-                // List rendering: uiConfig.responseType === 'list' + dataPath === 'data'
-                const listData = rt.tool?.uiConfig?.responseType === 'list' && rt.data?.data
-                    ? rt.data.data
-                    : null;
-                if (Array.isArray(listData)) {
-                    const max = rt.tool?.uiConfig?.maxItems || 10;
+                // List rendering: responseType === 'list' over the dataPath-resolved array.
+                if (isListTool && Array.isArray(dataToRender)) {
+                    const max = ui?.maxItems || 10;
+                    const items = dataToRender.slice(0, max);
+                    // Mirror MessageBubble's text-mode contract (renderToolResult, list
+                    // branch): layout === 'custom' hands the whole array to a single
+                    // component; horizontal/vertical render one component per item. Keep
+                    // these two render paths in lockstep so list output can't diverge again.
+                    if (ui?.layout === 'custom') {
+                        return (<react_native_1.View key={rt.toolCallId}>
+ <Component data={items}/>
+ </react_native_1.View>);
+                    }
                     return (<react_native_1.View key={rt.toolCallId} style={{ gap: 10 }}>
- {listData.slice(0, max).map((item, idx) => (<Component key={`${rt.toolCallId}_${idx}`} data={item}/>))}
+ {items.map((item, idx) => (<Component key={`${rt.toolCallId}_${idx}`} data={item}/>))}
  </react_native_1.View>);
                 }
-                // Non-list: render once with full data
-                return <Component key={rt.toolCallId} data={rt.data}/>;
+                // Non-list: render once with the dataPath-resolved data
+                return <Component key={rt.toolCallId} data={dataToRender}/>;
             })}
  </react_native_1.ScrollView>) : null}
  </react_native_1.View>

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/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/services/BackendService.js

@@ -740,16 +740,40 @@ class BackendService {
                 headers['Authorization'] = `Bearer ${sessionToken}`;
             }
         }
-        const response = await this.fetchWithRefresh(`${this.baseURL}/tools-v2/${toolId}/files/upload`, {
-            method: 'POST',
-            headers,
-            body: formData,
+        // Expo SDK 56+ installs a WinterCG `fetch` that rejects React Native's
+        // {uri,name,type} FormData file parts ("Unsupported FormDataPart
+        // implementation"). Use XHR (same transport as the chat stream) so the
+        // native multipart path handles the file part directly.
+        const url = `${this.baseURL}/tools-v2/${toolId}/files/upload`;
+        return await new Promise((resolve, reject) => {
+            const xhr = new XMLHttpRequest();
+            xhr.open('POST', url);
+            Object.keys(headers).forEach((k) => xhr.setRequestHeader(k, headers[k]));
+            xhr.timeout = this.timeout;
+            xhr.onload = () => {
+                if (xhr.status >= 200 && xhr.status < 300) {
+                    try {
+                        resolve(JSON.parse(xhr.responseText));
+                    }
+                    catch {
+                        resolve({});
+                    }
+                }
+                else {
+                    let message = `Upload failed: ${xhr.status}`;
+                    try {
+                        message = JSON.parse(xhr.responseText).message || message;
+                    }
+                    catch {
+                        message = `Upload failed: ${xhr.status}`;
+                    }
+                    reject(new Error(message));
+                }
+            };
+            xhr.onerror = () => reject(new Error('Upload failed'));
+            xhr.ontimeout = () => reject(new Error('Upload failed: timeout'));
+            xhr.send(formData);
         });
-        if (!response.ok) {
-            const error = await response.json().catch(() => ({ message: 'Upload failed' }));
-            throw new Error(error.message || `Upload failed: ${response.status}`);
-        }
-        return response.json();
     }
 }
 exports.BackendService = BackendService;

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;

package/dist/services/RealtimeService.js

@@ -3,6 +3,7 @@ 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");
 class RealtimeService {
     apiUrl;
     apiKey;
@@ -121,6 +122,12 @@ class RealtimeService {
                 // 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.
+            QafkaAudio_1.QafkaAudio.stopPlayback().catch(() => { });
+        }
         this.eventHandler?.(event);
     }
     attachAudioListener() {

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,16 @@
+/**
+ * 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. 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.
+ *
+ * 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.
+ */
+export declare function shouldSkipTurn2Narration(tool: any): boolean;

package/dist/utils/toolNarration.js

@@ -0,0 +1,22 @@
+"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. 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.
+ *
+ * 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.
+ */
+function shouldSkipTurn2Narration(tool) {
+    return (tool?.executionMode === 'custom-with-ai' &&
+        tool?.uiConfig?.responseType === 'card');
+}

package/docs/qafka-tool-authoring-guide.md

@@ -0,0 +1,328 @@
+# Qafka Tool Authoring Guide
+
+**Audience:** AI coding assistants (and developers) working in an app that has the
+`@qafka/react-native` SDK installed. When the developer says *"I need a tool that does X"*,
+this document is the authoritative reference for **exactly what to configure in the Qafka
+dashboard** and **what to implement in code**.
+
+> **This guide ships inside the SDK package**, so it always matches the SDK version that is
+> actually installed in this project. If a capability is **not described here, it does not
+> exist in this SDK version** — do not tell the developer to enable a field or pass a prop
+> that this guide does not mention. Inventing tool features that aren't real is the single
+> most common way this goes wrong: the assistant says "turn on feature Y", the developer
+> looks for it, it isn't there, and they're stuck. Don't do that.
+
+---
+
+## 1. Mental model: a tool lives in two places
+
+A Qafka tool always has **two halves**, and they are configured in two different places:
+
+| Half | Where it lives | Who configures it |
+|------|----------------|-------------------|
+| **Definition** (name, when to use it, parameters, execution behavior, side effects, result UI) | The **Qafka dashboard** (Tool V2) | The **developer**, by hand, in the web dashboard |
+| **Client behavior** (running on-device actions, rendering custom result UI, supplying transient data, handling file uploads) | The app's **code**, on the `<Qafka />` / `<QafkaProvider />` element | The **developer / you, the assistant** |
+
+**You (the AI assistant) cannot edit the dashboard.** You have no access to it. So your job
+when asked to build a tool is always **hybrid**:
+
+1. Produce **clear, step-by-step dashboard instructions** for the developer ("Create a tool
+   named `…`, set its description to `…`, set execution mode to `…`, add a parameter `…`,
+   turn on `…`").
+2. **Implement only the code side** yourself (handlers, components, props on `<Qafka />`).
+
+Never claim you "created the tool" — you set up the code side and instructed the developer on
+the dashboard side.
+
+> **Auth note:** in production the SDK authenticates via device attestation, not an API key in
+> the bundle. You don't need to handle auth when authoring tools; the only required identity
+> props are `projectId` and `endUserId` (see §6).
+
+---
+
+## 2. The workflow to follow when asked for a tool
+
+When the developer describes a tool, resolve these five questions **before** writing anything.
+If the answer to any of them isn't clear from the request, ask:
+
+1. **What does it do?** — the parameters it needs, where each value comes from, and whether it
+   reads/writes anything (an API call, an email, a navigation).
+2. **Execution mode** — `server`, `custom`, or `custom-with-ai` (§3). This is the most
+   important decision; it determines whether you write client code at all.
+3. **Modality** — should it be available in `text`, `voice`, or both (§4)?
+4. **Result UI** — nothing, a built-in inline display, a custom component, or a card (§6).
+5. **Side effects** — does completing it email someone / call a webhook (§5, *actions*)?
+
+Then produce the two outputs: **dashboard steps** + **code changes**.
+
+---
+
+## 3. Execution mode (the key decision)
+
+A tool's `executionMode` is one of three values. Default is `custom`.
+
+### `server`
+The **backend** calls the tool's configured endpoint, then the AI writes the final answer
+narrating the result. **`onToolSuggested` is NOT fired** — your app does not run anything for
+this tool, so **no client handler code is needed**.
+
+- Use when the action is a server-side API call and you want the AI to answer using the result.
+- The developer configures the **endpoint** (URL, method, body, headers) in the dashboard (§5).
+- Set a **loading message** in the dashboard so the wait feels natural.
+
+### `custom`
+The SDK emits a tool suggestion to your app; **your code runs the action** via the
+`onToolSuggested` prop and reports the result back. There is **no second AI turn** — what your
+handler renders is the final result.
+
+- Use when the action must run **in the app / on-device**: navigate a screen, read local
+  state, call a device API, or hit an endpoint the AI shouldn't see.
+- You **must implement `onToolSuggested`** (§6).
+
+### `custom-with-ai`
+Like `custom` (your code runs the action), **but** after your handler returns data the SDK
+sends it back so the AI produces a follow-up narration.
+
+- Use when the action runs in the app **and** you want the AI to summarize/explain the result.
+- You **must implement `onToolSuggested`** (§6). Set a **loading message** in the dashboard.
+
+> Decision shortcut:
+> *Backend does the work, AI narrates* → **`server`** (no client code).
+> *App does the work, no narration* → **`custom`**.
+> *App does the work, AI narrates the outcome* → **`custom-with-ai`**.
+
+---
+
+## 4. Modality — `availableIn`
+
+In the dashboard, **Available in** controls where the tool can be selected: **Both**,
+**Text only**, or **Voice only** (stored as `availableIn: ["text","voice"]`, `["text"]`, or
+`["voice"]`; default is both). Voice-only requires that voice is enabled for the project — the
+dashboard disables that option otherwise.
+
+---
+
+## 5. Dashboard fields (what you tell the developer to fill in)
+
+These are the fields a developer sets on a Tool V2 in the dashboard. Tell them which to fill
+based on the tool you're building. **Only these exist** — don't reference others.
+
+### Identity & selection
+- **`name`** *(required)* — the tool's identifier.
+- **`description`** *(required)* — **the full behavior protocol the chat AI reads** once the
+  tool is selected. Put the real instructions here: what the tool does, how to use each
+  parameter, what to say. This is the substantive field.
+- **`whenToUse`** *(optional)* — a **short, one-line selector hint** used only to decide *when*
+  to pick this tool. Keep it brief (~200 chars; longer values are truncated for selection). It
+  is **not** a place for behavior detail — that goes in `description`.
+- **`category`**, **`tags`**, **`usageExamples`** — optional metadata to aid organization and
+  selection.
+
+### Parameters
+Each parameter has:
+- **`name`**, **`type`** (`string` | `number` | `boolean` | `object` | `array`),
+  **`required`**, **`description`**.
+- **`source`** — where the value comes from: `ai` (the model fills it), `user_input` (asked
+  from the user), or `context` (pulled from the runtime `context` you pass on `<Qafka />`; use
+  **`contextKey`** to name the context field).
+- For AI-sourced parameters you can also set **`defaultValue`**, **`label`**, **`enumLabels`**
+  (a slug→display-label map so the AI emits a clean slug while the UI/email shows a friendly
+  label), and **`hiddenInEmail`** (omit this parameter from action emails).
+
+### Execution & UX
+- **`executionMode`** — `custom` | `server` | `custom-with-ai` (§3).
+- **`loadingMessage`** — shown while the tool runs; configure for `server` and `custom-with-ai`.
+- **`availableIn`** — modality (§4).
+- **`riskLevel`** (`low` | `medium` | `high`) and **`requiresConfirmation`** — gate sensitive
+  actions behind a confirmation step.
+- **`enabled`** and **`status`** (`DRAFT` / `PUBLISHED`) — a tool must be published & enabled
+  to be used.
+
+### Calling an endpoint (for `server` / `custom` API tools)
+- **Endpoint config:** `url`, `method` (`GET`/`POST`/`PUT`/`DELETE`/`PATCH`), optional
+  `bodyTemplate`, optional `headers`, and `requiredContext` (context keys that must be present).
+- **Token substitution:** in endpoint/webhook/header/description values you can use
+  `{{user.*}}`, `{{system.*}}`, and `{{tool.trackingId}}`; they resolve at runtime.
+
+### Side effects — actions (email / webhook)
+A tool can run actions when it completes (`trigger` is always *on complete*):
+- **Email:** the recipient `to` can be a **single address or multiple targets**, and each
+  target may carry a natural-language **condition** so the AI decides whether to send to it.
+  The action itself can also have an overall **condition**. Options include `subjectPrefix`,
+  `includeConversation`, `attachFile`, and `includeUserContextKeys` (opt-in: which
+  `userContext`/`context` keys to include — nothing about the user is sent unless listed).
+- **Webhook:** `url`, `method` (`POST`/`PUT`), custom `headers` (with token substitution),
+  `include*` toggles (extraction, file, conversation, selected context keys), file delivery
+  format (`url` | `base64` | `formdata`), and an optional `secret` for an HMAC signature.
+
+### Result UI
+- **`uiConfig`** — how structured results render: `responseType` of `list` | `detail` | `card`
+  | `table` | `summary`, plus `dataPath`, `maxItems`, layout/position, and `itemComponent` (the
+  name of a custom component you register in code — see §6). `list`/`detail`/`card`/`table`
+  have built-in default renderers; `summary` has **no** built-in component in this SDK version,
+  so only pick it if you supply your own component via `itemComponent` + the `components` prop.
+- **Card template** — for rich cards, the dashboard has an **AI-assisted card designer** (you
+  describe the card, it generates a template); the tool stores a `cardTemplateId`. The SDK
+  renders the card automatically; card buttons (CTAs) are routed to the `onCard*` props (§6).
+- **`trackingIdFormat`** — optional human-readable tracking id format for the tool run.
+
+### File-upload tools
+- **`fileInput`** — accepted types, max size, allowed sources.
+- **`documentExtractor`** — an extraction prompt + the fields to pull out + a model. After the
+  user uploads a file, the result arrives via `onExtractionResult` in code (§6).
+
+### Response channel (built-ins, automatic)
+- **`responseChannel`** toggle — "send response as a tool action". Turning this on
+  **auto-creates** the built-in `qafka_response_status` / `qafka_add_followup` tools. **Never
+  tell the developer to create those by hand** — they're server-managed and shown locked in the
+  dashboard.
+
+### Versioning (optional, advanced)
+A tool can have multiple **versions**, each with its own `minClientVersion` and `status`
+(`draft` / `staging` / `published`). At chat time the highest version compatible with the app's
+version and the request modality is resolved. Most tools don't need this; mention it only if
+the developer asks about rolling out a change without breaking older app builds.
+
+---
+
+## 6. Code side (what you implement on `<Qafka />`)
+
+The SDK exposes two render components — **`QafkaProvider`** (a floating launcher by default,
+or `inline`/`fullscreen`) and **`Qafka`** (the chat/voice surface itself). The Qafka CLI
+scaffolds one of these into a screen; you add tool-related props to that element.
+
+```tsx
+import { Qafka } from '@qafka/react-native';
+```
+
+### Always-required props
+- **`projectId`** *(required)* — which Qafka project this app talks to.
+- **`endUserId`** *(required, `string | number`)* — stable id for the end user (≤256 chars; not
+  sent to the LLM).
+
+### Running tools in your app — `onToolSuggested`
+Implement this for **`custom`** and **`custom-with-ai`** tools (not needed for `server`):
+
+```tsx
+<Qafka
+  projectId="…"
+  endUserId={user.id}
+  onToolSuggested={async (tools, addResponse) => {
+    for (const tool of tools) {
+      if (tool.name === 'go_to_orders') {
+        navigation.navigate('Orders');
+        // addResponse(data, tool, mode?)  mode: 'ui' | 'data' | 'both' (default 'both')
+        addResponse({ navigated: true }, tool, 'data');
+      }
+    }
+  }}
+/>
+```
+
+`addResponse(data, tool, mode?)` reports the result back:
+- `'ui'` — update the rendered UI only (keeps the flow open),
+- `'data'` — commit the result data without touching the UI,
+- `'both'` *(default)* — both.
+
+For `custom-with-ai` tools, the data you pass is forwarded so the AI can narrate a follow-up.
+
+### Custom result components — the `components` prop
+When a tool returns structured data with a `uiConfig`, the SDK renders it with built-in
+defaults (`DefaultCard`, `DefaultList`, `DefaultDetail`, `DefaultTable`). Override them by
+registering your own by name:
+
+```tsx
+<Qafka
+  components={{ OrderCard: MyOrderCard }}  // matches uiConfig.itemComponent = "OrderCard"
+/>
+```
+
+Each component receives `{ data, tool?, theme?, onAction? }`.
+
+### Transient / lazy data — `onToolDataRequested`
+When a tool needs data the AI shouldn't see or that you don't want persisted, supply it
+on-demand. The SDK calls this just before the tool runs and uses the returned bag for that run
+only (it is not written to the conversation or sent to the LLM):
+
+```tsx
+<Qafka
+  onToolDataRequested={(tool) => {            // tool: { key, name }
+    if (tool.key === 'current_cart') return { items: cart.items };
+    return {};
+  }}
+/>
+```
+
+### File-upload tools — `onFileUploadRequest` + `onExtractionResult`
+There is **no built-in file picker** in this SDK version. For a tool with `fileInput`, you wire
+your own picker:
+
+```tsx
+<Qafka
+  onFileUploadRequest={({ toolId, fileInput, submit, cancel }) => {
+    // open your picker honoring fileInput.accept / maxSize / sources,
+    // then call submit({ uri, name, type }) or cancel()
+  }}
+  onExtractionResult={(result) => { /* { fileId, toolId, data, status, incompleteFields? } */ }}
+/>
+```
+
+### Card CTAs
+If a tool uses a card template, the card renders automatically. Its buttons are delivered to
+these props (wire the ones your cards use): `onCardDeepLink`, `onCardSuggestMessage`,
+`onCardExternalNavigation`, `onCardShare`, `onCardCopy`, `onCardToolTrigger`, `onCardCTAClick`.
+
+### Inline key/value display — `qafka_display` (built-in)
+`qafka_display` is a **built-in tool**: there is nothing to create in the dashboard and nothing
+to handle in code. It shows a small set of key/value chips (or routes text to the transcript).
+You may optionally restyle the chips via `voiceComponents.dataChipList` / `voiceComponents.dataChip`.
+
+### Useful context props
+- **`context`** + **`contextDescription`** — a runtime data bag passed to the AI, with a
+  description of what its keys mean. (Tool parameters with `source: 'context'` read from here.)
+- **`endUserData`** — non-LLM metadata about the user (≤8KB).
+- **`subProjectId`** — multi-tenant routing.
+- **`locale`** — BCP-47 locale.
+
+---
+
+## 7. Recipes (common asks → config + code)
+
+**A. "Call our backend and let the AI answer."**
+Dashboard: execution mode `server`, fill endpoint config, set a loading message, `availableIn`
+both. Code: nothing — `server` tools don't fire `onToolSuggested`.
+
+**B. "Do something in the app (navigate / read local state) and show the result."**
+Dashboard: execution mode `custom` (or `custom-with-ai` if you want the AI to narrate). Add
+parameters. Optionally set `uiConfig`/card for the result. Code: implement `onToolSuggested`;
+register a component via `components` if you used `uiConfig.itemComponent`.
+
+**C. "Collect some info and email it to the team."**
+Dashboard: add an **email action**; use multiple targets with conditions if routing depends on
+the input; opt into the context keys you want via `includeUserContextKeys`. Code: usually none
+(the action runs on completion); add a handler only if the tool also does on-device work.
+
+**D. "User uploads a document; extract fields from it."**
+Dashboard: configure `fileInput` + `documentExtractor` on the tool. Code: implement
+`onFileUploadRequest` (your picker → `submit(...)`) and read `onExtractionResult`.
+
+**E. "Show a couple of key values inline."**
+Use the built-in `qafka_display` — nothing in the dashboard, nothing in code.
+
+---
+
+## 8. Guardrails (read before you answer)
+
+- **Don't invent capabilities.** If it isn't in this guide, it isn't in this SDK version.
+  Don't tell the developer to toggle a field or pass a prop that doesn't exist here.
+- **You can't touch the dashboard.** Always give explicit dashboard steps for the developer and
+  implement only the code side yourself.
+- **`description` carries behavior, `whenToUse` is just a short selector hint.** Don't stuff
+  protocol detail into `whenToUse`.
+- **Built-in tools aren't created by hand** — `qafka_display`, and the `responseChannel`
+  built-ins (`qafka_response_status` / `qafka_add_followup`), appear automatically.
+- **`server` mode means no client handler.** Only `custom` / `custom-with-ai` use
+  `onToolSuggested`.
+- **This guide is version-matched** to the `@qafka/react-native` package it ships inside (see
+  its `package.json` `version`). If the developer is on a different version, the dashboard or
+  props may differ — defer to the dashboard's own field set when in doubt.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qafka/react-native",
-  "version": "2.3.7",
+  "version": "2.3.9",
   "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,6 +15,7 @@
     "react-native.config.js",
     "qafka.config.js",
     "qafka.config.d.ts",
+    "docs",
     "README.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",