Merge commit e95582a: PR #20 proactive chat, topic chips, low-info turn plan

- Merge staging workflow parent and resolve conflicts with English/i18n and WS pool
- Re-greeting: language-aware fallbacks and prompts; router passes user_language
- RealtimeSession: topic suggestion callbacks + TTS sync path preserved

Co-authored-by: Cursor <cursoragent@cursor.com>

app-expo/src/features/conversation/conversation-ws-background-pool.ts

@@ -32,6 +32,7 @@ function disposeSlot(): void {
 const offScreenUi = {
   onStreamingText: () => {},
   onTtsSegment: () => {},
+  onTopicSuggestions: () => {},
   onError: () => {},
   onStateChange: () => {},
 };
@@ -44,6 +45,7 @@ export function releaseConversationWsUi(
   session.releaseUiCallbacks(owner, {
     onStreamingText: offScreenUi.onStreamingText,
     onTtsSegment: offScreenUi.onTtsSegment,
+    onTopicSuggestions: offScreenUi.onTopicSuggestions,
     onError: offScreenUi.onError,
     onStateChange: offScreenUi.onStateChange,
   });

app-expo/src/features/conversation/hooks.ts

@@ -4,7 +4,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import { AppState, type AppStateStatus } from 'react-native';
 
 import i18n from '@/i18n';
-import type { WsConnectionState } from '@/core/ws/types';
+import type { TopicSuggestion, WsConnectionState } from '@/core/ws/types';
 
 import { conversationApi } from './api';
 import {
@@ -196,12 +196,11 @@ interface RealtimeSessionState {
   /** 已发出用户消息，尚未收到助手首段流式文本（用于「正在回复」气泡） */
   awaitingAssistantReply: boolean;
   error: string | null;
-  sendText: (text: string, options?: { ttsThisTurn?: boolean }) => void;
-  sendVoiceMessage: (
-    uri: string,
-    durationMs: number,
-    options?: { ttsThisTurn?: boolean },
-  ) => Promise<boolean>;
+  /** 服务端下发的 quick-start 话题 chips；用户首次发文本/语音后清空 */
+  topicSuggestions: TopicSuggestion[];
+  dismissTopicSuggestions: () => void;
+  sendText: (text: string) => void;
+  sendVoiceMessage: (uri: string, durationMs: number) => Promise<boolean>;
   sendEndConversation: () => void;
   sendTtsCancel: () => void;
   requestAssistantSegmentTts: (body: {
@@ -237,6 +236,9 @@ export function useRealtimeSession({
     useState<StreamingAgentMessage | null>(null);
   const [awaitingAssistantReply, setAwaitingAssistantReply] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const [topicSuggestions, setTopicSuggestions] = useState<TopicSuggestion[]>(
+    [],
+  );
 
   const [foregroundResumeGeneration, setForegroundResumeGeneration] =
     useState(0);
@@ -270,29 +272,16 @@ export function useRealtimeSession({
     setError(message);
   }, []);
 
-  uiRef.current.handleStreamingText = handleStreamingText;
-  uiRef.current.handleError = handleError;
-  uiRef.current.onTtsSegment = onTtsSegment;
+  const handleTopicSuggestions = useCallback(
+    (payload: { suggestions: TopicSuggestion[] }) => {
+      setTopicSuggestions(payload.suggestions);
+    },
+    [],
+  );
 
-  useEffect(() => {
-    if (!enabled || !conversationId) return;
-
-    const sub = AppState.addEventListener('change', (next: AppStateStatus) => {
-      if (next === 'background') {
-        needsResumeAfterBackgroundRef.current = true;
-        disposeAllBackgroundConversationWs();
-        sessionRef.current = null;
-        setConnectionState('disconnected');
-        setStreamingMessage(null);
-        setAwaitingAssistantReply(false);
-      } else if (next === 'active' && needsResumeAfterBackgroundRef.current) {
-        needsResumeAfterBackgroundRef.current = false;
-        setForegroundResumeGeneration((g) => g + 1);
-      }
-    });
-
-    return () => sub.remove();
-  }, [enabled, conversationId]);
+  const dismissTopicSuggestions = useCallback(() => {
+    setTopicSuggestions([]);
+  }, []);
 
   useEffect(() => {
     if (!enabled || !conversationId) return;
@@ -310,6 +299,8 @@ export function useRealtimeSession({
           uiRef.current.handleStreamingText(text, isComplete);
         },
         onTtsSegment: (payload) => uiRef.current.onTtsSegment?.(payload),
+        onTopicSuggestions: (payload) =>
+          handleTopicSuggestions({ suggestions: payload.suggestions }),
         onError: (message, code) => uiRef.current.handleError(message, code),
         onStateChange: setConnectionState,
       },
@@ -325,8 +316,17 @@ export function useRealtimeSession({
       setConnectionState('disconnected');
       setStreamingMessage(null);
       setAwaitingAssistantReply(false);
+      setTopicSuggestions([]);
     };
-  }, [conversationId, enabled, queryClient, foregroundResumeGeneration]);
+  }, [
+    conversationId,
+    enabled,
+    queryClient,
+    handleStreamingText,
+    handleError,
+    handleTopicSuggestions,
+    onTtsSegment,
+  ]);
 
   const sendText = useCallback(
     (text: string, options?: { ttsThisTurn?: boolean }) => {
@@ -341,6 +341,7 @@ export function useRealtimeSession({
       onUserSendTtsPreference?.(options?.ttsThisTurn === true);
 
       setAwaitingAssistantReply(true);
+      setTopicSuggestions([]);
       onTtsPlaybackResume?.();
 
       const localId = `pending_${Date.now()}`;
@@ -407,6 +408,7 @@ export function useRealtimeSession({
         onUserSendTtsPreference?.(options?.ttsThisTurn === true);
 
         setAwaitingAssistantReply(true);
+        setTopicSuggestions([]);
         const localId = `pending_voice_${Date.now()}`;
         await voiceSegmentStore.recordSentSegment({
           voiceSessionId,
@@ -475,6 +477,8 @@ export function useRealtimeSession({
     streamingMessage,
     awaitingAssistantReply,
     error,
+    topicSuggestions,
+    dismissTopicSuggestions,
     sendText,
     sendVoiceMessage,
     sendEndConversation,

app-expo/src/features/conversation/realtime-session.ts

@@ -5,7 +5,11 @@ import {
   type WsEventListener,
   type WsStateListener,
 } from '@/core/ws/client';
-import type { WsConnectionState, WsEvent } from '@/core/ws/types';
+import type {
+  TopicSuggestion,
+  WsConnectionState,
+  WsEvent,
+} from '@/core/ws/types';
 
 import { handleWsEvent } from './event-handlers';
 import { assistantSegmentMessageId, lastSegmentPreview } from './message-split';
@@ -22,6 +26,11 @@ function looksLikeUuidAssistantMessageId(id: string): boolean {
 export type StreamingTextCallback = (text: string, isComplete: boolean) => void;
 export type ErrorCallback = (message: string, code?: string) => void;
 export type RealtimeSessionUiOwner = symbol;
+export type TopicSuggestionsCallback = (payload: {
+  reason: string;
+  stage?: string;
+  suggestions: TopicSuggestion[];
+}) => void;
 
 /** WebSocket `tts_audio`：服务端可能只带 base64、只带 COS URL，或两者都有 */
 export type TtsSegmentPayload = {
@@ -43,6 +52,8 @@ interface RealtimeSessionOptions {
   onStreamingText?: StreamingTextCallback;
   /** 收到 TTS 片段时入队播放（与「气泡上的手动朗读按钮」无关） */
   onTtsSegment?: (payload: TtsSegmentPayload) => void;
+  /** 服务端下发 quick-start 话题 chips 时回调；用户点击后调 sendText */
+  onTopicSuggestions?: TopicSuggestionsCallback;
   onError?: ErrorCallback;
   onStateChange?: WsStateListener;
 }
@@ -64,6 +75,7 @@ export class RealtimeSession {
   private queryClient: QueryClient;
   private onStreamingText?: StreamingTextCallback;
   private onTtsSegment?: (payload: TtsSegmentPayload) => void;
+  private onTopicSuggestions?: TopicSuggestionsCallback;
   private onError?: ErrorCallback;
   private uiStateListener?: WsStateListener;
   private uiOwner: RealtimeSessionUiOwner | null = null;
@@ -104,6 +116,7 @@ export class RealtimeSession {
     this.queryClient = options.queryClient;
     this.onStreamingText = options.onStreamingText;
     this.onTtsSegment = options.onTtsSegment;
+    this.onTopicSuggestions = options.onTopicSuggestions;
     this.onError = options.onError;
     this.uiStateListener = options.onStateChange;
 
@@ -119,6 +132,7 @@ export class RealtimeSession {
     options: {
       onStreamingText?: StreamingTextCallback;
       onTtsSegment?: (payload: TtsSegmentPayload) => void;
+      onTopicSuggestions?: TopicSuggestionsCallback;
       onError?: ErrorCallback;
       onStateChange?: WsStateListener;
     },
@@ -135,6 +149,9 @@ export class RealtimeSession {
     if (options.onTtsSegment !== undefined) {
       this.onTtsSegment = options.onTtsSegment;
     }
+    if (options.onTopicSuggestions !== undefined) {
+      this.onTopicSuggestions = options.onTopicSuggestions;
+    }
     if (options.onError !== undefined) {
       this.onError = options.onError;
     }
@@ -152,6 +169,7 @@ export class RealtimeSession {
     options: {
       onStreamingText?: StreamingTextCallback;
       onTtsSegment?: (payload: TtsSegmentPayload) => void;
+      onTopicSuggestions?: TopicSuggestionsCallback;
       onError?: ErrorCallback;
       onStateChange?: WsStateListener;
     },
@@ -375,6 +393,15 @@ export class RealtimeSession {
       return;
     }
 
+    if (event.kind === 'topic_suggestions') {
+      this.onTopicSuggestions?.({
+        reason: event.reason,
+        stage: event.stage,
+        suggestions: event.suggestions,
+      });
+      return;
+    }
+
     handleWsEvent(this.queryClient, event);
 
     if (event.kind === 'session_error') {