@bytexbyte/nxtlinq-ai-agent-ui-react-development 0.4.0 → 0.4.2

package/src/context/ChatBotContext.tsx

@@ -25,6 +25,10 @@ import type {
   Message,
   ServicePermission,
 } from '@bytexbyte/nxtlinq-ai-agent-core-development';
+import {
+  authorizeTextFrontendTool,
+  hasRecordedWalletVerification,
+} from '@bytexbyte/nxtlinq-ai-agent-core-development';
 import {
   AIModel,
   ChatBotContextType,
@@ -79,8 +83,6 @@ export const ChatBotProvider: React.FC<ChatBotProps> = ({
   isStopRecordingOnSend = false,
   // Custom error message to display in chat
   customError,
-  // PII display mode
-  piiDisplayMode = 'redacted',
   voiceThresholds,
   debugVoiceRms = false,
   sttGlossary,
@@ -894,6 +896,12 @@ export const ChatBotProvider: React.FC<ChatBotProps> = ({
   const [modelsFromApi, setModelsFromApi] = React.useState<AIModel[]>([]);
   const [selectedModelIndex, setSelectedModelIndex] = useLocalStorage<number>('selectedAIModelIndex', 0);
 
+  // PII protection status: fetched from the service's own config (via serviceId + credentials
+  // already provided to the SDK), not passed in by the host app. Defaults to off until the fetch
+  // below resolves, matching how modelsFromApi starts empty.
+  const [enablePiiProtection, setEnablePiiProtection] = React.useState(false);
+  const piiDisplayMode: 'plain' | 'redacted' = enablePiiProtection ? 'redacted' : 'plain';
+
   // Use models from API only (no default fallback)
   // This ensures SDK always uses Dashboard-configured models
   const effectiveAvailableModels = React.useMemo(() => {
@@ -915,6 +923,9 @@ export const ChatBotProvider: React.FC<ChatBotProps> = ({
         if ('availableModels' in result && Array.isArray(result.availableModels)) {
           setModelsFromApi(result.availableModels);
         }
+        if ('enablePiiProtection' in result) {
+          setEnablePiiProtection(!!result.enablePiiProtection);
+        }
       } catch (error) {
         console.error('Failed to fetch available models from API:', error);
         // Silently fail and use default models
@@ -999,13 +1010,18 @@ export const ChatBotProvider: React.FC<ChatBotProps> = ({
 
     setIsAITLoading(true);
     try {
+      let walletAllowsAITLookup = !requireWalletIDVVerification;
+
       // Get wallet info first - always try to get wallet info if we have a token
       if (nxtlinqAITServiceAccessToken) {
         try {
           const walletResponse = await nxtlinqApi.wallet.getWallet({ address: hitAddress }, nxtlinqAITServiceAccessToken);
           if (!('error' in walletResponse)) {
             setWalletInfo(walletResponse);
+            walletAllowsAITLookup = !requireWalletIDVVerification
+              || hasRecordedWalletVerification(walletResponse);
           } else {
+            setWalletInfo(null);
             // Check if the error is due to invalid/expired token
             if (walletResponse.error.includes('Invalid or expired token')) {
               console.log('Token appears to be invalid during wallet info fetch, clearing it');
@@ -1013,10 +1029,19 @@ export const ChatBotProvider: React.FC<ChatBotProps> = ({
             }
           }
         } catch (error) {
+          setWalletInfo(null);
           console.error('Failed to fetch wallet info:', error);
         }
       }
 
+      // AIT existence is not identity verification. In strict mode, stop before
+      // the legacy AIT lookup can synthesize a custom wallet record.
+      if (nxtlinqAITServiceAccessToken && !walletAllowsAITLookup) {
+        setAit(null);
+        setPermissions([]);
+        return;
+      }
+
       // Only try to fetch AIT if we have a token
       if (nxtlinqAITServiceAccessToken) {
         const response = await nxtlinqApi.ait.getAITByServiceIdAndController({
@@ -1267,363 +1292,70 @@ export const ChatBotProvider: React.FC<ChatBotProps> = ({
   };
 
   // Check permissions
-  const hasPermission = async (requiredPermission: string, autoRetry = true, onAutoConnect?: () => void, onAutoSignIn?: () => void): Promise<boolean> => {
+  const hasPermission = async (
+    requiredPermission: string,
+  ): Promise<boolean> => {
     // Use refs to get latest state values
     const currentHitAddress = hitAddressRef.current;
-    const currentAit = aitRef.current;
-    const currentPermissions = permissionsRef.current;
     const currentToken = nxtlinqAITServiceAccessTokenRef.current;
 
-    if (!currentHitAddress) {
-      if (autoRetry) {
-        setIsLoading(false); // Stop thinking before showing message
-        setMessages(prev => [...prev, {
-          id: Date.now().toString(),
-          content: walletTextUtils.getWalletText('Please connect your HIT wallet to continue.', serviceId),
-          role: 'assistant',
-          timestamp: new Date().toISOString(),
-          button: 'connectWallet'
-        }]);
-
-        try {
-          setIsAutoConnecting(true); // Mark as auto-connecting
-          await connectWallet(false); // Don't show sign-in message yet
-          setIsAutoConnecting(false); // Clear auto-connecting state
-
-          // Show brief success message for auto-connect
-          showSuccess(walletTextUtils.getWalletText('Auto wallet connection successful', serviceId));
-
-
-          onAutoConnect?.(); // Call callback if provided
-          await new Promise(resolve => setTimeout(resolve, 2000));
-
-          // After auto connect, if not signed in, then auto sign-in
-          const tokenAfterConnect = nxtlinqAITServiceAccessTokenRef.current;
-          if (!tokenAfterConnect) {
-            setIsAutoConnecting(true);
-            await signInWallet(false);
-            onAutoSignIn?.(); // Call callback if provided
-            setIsAutoConnecting(false);
-            showSuccess(walletTextUtils.getWalletText('Auto sign-in successful after wallet connect', serviceId));
-            await refreshAIT();
-            // Wait for AIT to be fully loaded with polling
-            let attempts = 0;
-            const maxAttempts = 5;
-            while (!aitRef.current && attempts < maxAttempts) {
-              await new Promise(resolve => setTimeout(resolve, 2000));
-              attempts++;
-            }
-          }
-
-          // If connection (and sign-in if needed) successful, continue with permission check
-          const result = await hasPermission(requiredPermission, false);
-          return result;
-        } catch (error) {
-          console.error('Failed to auto-connect wallet:', error);
-          setIsAutoConnecting(false); // Clear auto-connecting state on error
-          return false;
-        }
-      }
-      // If autoRetry is false, don't show message again, just return false
-      return false;
-    }
-
-    if (!currentToken) {
-      if (autoRetry) {
-        setIsLoading(false); // Stop thinking before showing message
-        setMessages(prev => [...prev, {
-          id: Date.now().toString(),
-          content: walletTextUtils.getWalletText('Please sign in with your HIT wallet to continue.', serviceId),
-          role: 'assistant',
-          timestamp: new Date().toISOString(),
-          button: 'signIn'
-        }]);
-
-        try {
-          setIsAutoConnecting(true); // Mark as auto-signing
-          await signInWallet(false); // Don't show success message yet
-          onAutoSignIn?.(); // Call callback if provided
-          setIsAutoConnecting(false); // Clear auto-signing state
-
-          // Show brief success message for auto-sign-in
-          showSuccess('Auto sign-in successful');
-
-          // Ensure AIT is refreshed after sign-in
-          await refreshAIT();
-
-          // Wait for AIT to be fully loaded with polling
-          let attempts = 0;
-          const maxAttempts = 5; // Wait up to 10 seconds (5 * 2000ms)
-          while (!aitRef.current && attempts < maxAttempts) {
-            await new Promise(resolve => setTimeout(resolve, 2000));
-            attempts++;
-          }
-
-          // Only continue if AIT is actually loaded
-          if (aitRef.current) {
-            // Wait a bit more to ensure permissions are also loaded
-            await new Promise(resolve => setTimeout(resolve, 2000));
-            // If sign-in successful, continue with permission check
-            const result = await hasPermission(requiredPermission, false);
-            return result;
-          } else {
-            return false;
-          }
-        } catch (error) {
-          console.error('Failed to auto-sign-in wallet:', error);
-          setIsAutoConnecting(false); // Clear auto-signing state on error
-          return false;
-        }
-      }
-      // If autoRetry is false, don't show message again, just return false
-      return false;
-    }
-
-    try {
-      const payload = JSON.parse(atob(currentToken.split('.')[1]));
-      const address = payload.address;
-      if (address !== currentHitAddress) {
-        setNxtlinqAITServiceAccessToken('');
-        if (autoRetry) {
-          setIsLoading(false); // Stop thinking before showing message
-          setMessages(prev => [...prev, {
-            id: Date.now().toString(),
-            content: walletTextUtils.getWalletText('Wallet address mismatch. Please sign in with the correct wallet.', serviceId),
-            role: 'assistant',
-            timestamp: new Date().toISOString(),
-            button: 'signIn'
-          }]);
-
-          try {
-            setIsAutoConnecting(true); // Mark as auto-signing
-            await signInWallet(false); // Don't show success message yet
-            onAutoSignIn?.(); // Call callback if provided
-            setIsAutoConnecting(false); // Clear auto-signing state
-
-            // Show brief success message for auto-sign-in after address mismatch
-            showSuccess('Auto sign-in successful after address mismatch');
-
-            // Ensure AIT is refreshed after sign-in
-            await refreshAIT();
-
-            // Wait for AIT to be fully loaded with polling
-            let attempts = 0;
-            const maxAttempts = 5; // Wait up to 10 seconds (5 * 2000ms)
-            while (!aitRef.current && attempts < maxAttempts) {
-              await new Promise(resolve => setTimeout(resolve, 2000));
-              attempts++;
-            }
-
-            // Only continue if AIT is actually loaded
-            if (aitRef.current) {
-              // Wait a bit more to ensure permissions are also loaded
-              await new Promise(resolve => setTimeout(resolve, 2000));
-              // If sign-in successful, continue with permission check
-              const result = await hasPermission(requiredPermission, false);
-              return result;
-            } else {
-              return false;
-            }
-          } catch (error) {
-            console.error('Failed to auto-sign-in after address mismatch:', error);
-            setIsAutoConnecting(false); // Clear auto-signing state on error
-            return false;
-          }
-        }
-        // If autoRetry is false, don't show message again, just return false
-        return false;
-      }
-    } catch (error) {
-      console.error('Error parsing token:', error);
-      setNxtlinqAITServiceAccessToken('');
-      if (autoRetry) {
-        setIsLoading(false); // Stop thinking before showing message
-        setMessages(prev => [...prev, {
-          id: Date.now().toString(),
-          content: walletTextUtils.getWalletText('Invalid wallet session. Please sign in again.', serviceId),
-          role: 'assistant',
-          timestamp: new Date().toISOString(),
-          button: 'signIn'
-        }]);
-
-        try {
-          setIsAutoConnecting(true); // Mark as auto-signing
-          await signInWallet(false); // Don't show success message yet
-          onAutoSignIn?.(); // Call callback if provided
-          setIsAutoConnecting(false); // Clear auto-signing state
-
-          // Show brief success message for auto-sign-in after token parse error
-          showSuccess('Auto sign-in successful after token error');
-
-          // Ensure AIT is refreshed after sign-in
-          await refreshAIT();
-
-          // Wait for AIT to be fully loaded with polling
-          let attempts = 0;
-          const maxAttempts = 5; // Wait up to 10 seconds (5 * 2000ms)
-          while (!aitRef.current && attempts < maxAttempts) {
-            await new Promise(resolve => setTimeout(resolve, 2000));
-            attempts++;
-          }
-
-          // Only continue if AIT is actually loaded
-          if (aitRef.current) {
-            // Wait a bit more to ensure permissions are also loaded
-            await new Promise(resolve => setTimeout(resolve, 2000));
-            // If sign-in successful, continue with permission check
-            const result = await hasPermission(requiredPermission, false);
-            return result;
-          } else {
-            return false;
-          }
-        } catch (signInError) {
-          console.error('Failed to auto-sign-in after token parse error:', signInError);
-          setIsAutoConnecting(false); // Clear auto-signing state on error
-          return false;
-        }
-      }
-      // If autoRetry is false, don't show message again, just return false
-      return false;
-    }
-
-    if (!currentAit) {
-      // Show loading message if AIT is still loading
-      if (isAITLoading) {
-        setIsLoading(false); // Stop thinking before showing message
-        setMessages(prev => [...prev, {
-          id: Date.now().toString(),
-          content: walletTextUtils.getWalletText('Loading your wallet configuration... Please wait a moment.', serviceId),
-          role: 'assistant',
-          timestamp: new Date().toISOString()
-        }]);
-        return false;
-      }
-
-      // If AIT is not loaded but we have a token, try to refresh it once
-      if (currentToken && !isAITLoading) {
-        try {
-          await refreshAIT();
-          // Wait for AIT to be loaded with polling
-          let attempts = 0;
-          const maxAttempts = 5; // Wait up to 10 seconds (5 * 2000ms)
-          while (!aitRef.current && attempts < maxAttempts) {
-            await new Promise(resolve => setTimeout(resolve, 2000));
-            attempts++;
-          }
-          // Check again after refresh
-          if (!aitRef.current) {
-            setIsLoading(false); // Stop thinking before showing message
-            setMessages(prev => [...prev, {
-              id: Date.now().toString(),
-              content: walletTextUtils.getWalletText('No AIT found for your wallet. Please click the settings button (⚙️) to configure your AIT permissions.', serviceId),
-              role: 'assistant',
-              timestamp: new Date().toISOString()
-            }]);
-            return false;
-          }
-        } catch (error) {
-          console.error('Failed to refresh AIT during permission check:', error);
-          setIsLoading(false); // Stop thinking before showing message
-          setMessages(prev => [...prev, {
-            id: Date.now().toString(),
-            content: 'No AIT found for your wallet. Please click the settings button (⚙️) to configure your AIT permissions.',
-            role: 'assistant',
-            timestamp: new Date().toISOString()
-          }]);
-          return false;
-        }
-      } else {
-        setIsLoading(false); // Stop thinking before showing message
-        setMessages(prev => [...prev, {
-          id: Date.now().toString(),
-          content: 'No AIT found for your wallet. Please click the settings button (⚙️) to configure your AIT permissions.',
-          role: 'assistant',
-          timestamp: new Date().toISOString()
-        }]);
-        return false;
-      }
-    }
-
-    if (availablePermissions.length === 0) {
-      setIsLoading(false); // Stop thinking before showing message
-      setMessages(prev => [...prev, {
-        id: Date.now().toString(),
-        content: `No permissions available for your current identity provider. Please check your service configuration or contact support. Service ID: ${serviceId}, Permission Group: ${permissionGroup || 'None'}`,
-        role: 'assistant',
-        timestamp: new Date().toISOString()
-      }]);
-      return false;
-    }
-
-    const checkToolPermissionResult = await nxtlinqApi.agent.checkToolPermission({
+    const authorization = await authorizeTextFrontendTool({
+      api: nxtlinqApi,
+      serviceId,
+      toolName: requiredPermission,
+      snapshot: {
+        walletAddress: currentHitAddress,
+        walletToken: currentToken,
+        // Legacy AIT issuance is unscoped (`externalId=''`). Do not impose a
+        // wallet-address subject until issuance/migration supports it.
+        externalId: undefined,
+        requireWalletIDVVerification,
+        loading: isAITLoading || isAutoConnecting,
+      },
       ...authFields(),
-      aitToken: currentToken!,
-      controller: currentHitAddress!,
-      toolName: requiredPermission
-    })
-
-    if ('error' in checkToolPermissionResult) {
-      // Check if AIT is still loading or if we just auto-connected
-      if (isAITLoading || isAutoConnecting) {
-        setIsLoading(false); // Stop thinking before showing message
-        setMessages(prev => [...prev, {
-          id: Date.now().toString(),
-          content: walletTextUtils.getWalletText('Loading your wallet configuration... Please wait a moment.', serviceId),
-          role: 'assistant',
-          timestamp: new Date().toISOString()
-        }]);
-        return false;
-      }
-
-      // Refresh service permissions before judging; use latest result to decide message
-      const freshAvailablePermissions = await fetchAvailablePermissions();
-      const latestAvailablePermissions = freshAvailablePermissions ?? availablePermissions;
-
-      const requiredPermission = checkToolPermissionResult.requiredPermission;
-      const isInServiceList = latestAvailablePermissions.some((p) => p.label === requiredPermission);
-
-      // Permission not in service's available list → "not available for your current identity provider"
-      if (!isInServiceList) {
-        setIsLoading(false); // Stop thinking before showing message
-        setMessages(prev => [...prev, {
-          id: Date.now().toString(),
-          content: `This permission (${requiredPermission}) is not available for your current identity provider.`,
-          role: 'assistant',
-          timestamp: new Date().toISOString()
-        }]);
-        return false;
-      }
-
-      // AIT loaded but permissions empty (no AIT found)
-      if (currentAit && currentPermissions.length === 0) {
-        setIsLoading(false); // Stop thinking before showing message
-        setMessages(prev => [...prev, {
-          id: Date.now().toString(),
-          content: 'No AIT found for your wallet. Please click the settings button (⚙️) to configure your AIT permissions.',
-          role: 'assistant',
-          timestamp: new Date().toISOString()
-        }]);
-        return false;
-      }
-
-      // User has AIT but hasn't enabled this permission → prompt to enable
-      setIsLoading(false); // Stop thinking before showing message
-      const permissionMsg = `You don't have the required AIT permission: ${requiredPermission}. Would you like to enable AIT permission?`;
-      setMessages(prev => [
-        ...prev,
-        {
-          id: Date.now().toString(),
-          content: permissionMsg,
-          role: 'assistant',
-          timestamp: new Date().toISOString(),
-          button: 'enableAIT',
-          metadata: { requiredPermission }
-        }
-      ]);
-      return false;
-    }
-
-    return true;
+      customUsername: (!requireWalletIDVVerification && customUsername)
+        ? getFinalCustomUsername(customUsername)
+        : undefined,
+    });
+    if (authorization.status === 'allowed') return true;
+
+    setIsLoading(false);
+    const recovery: Message = {
+      id: Date.now().toString(),
+      content: 'Authorization is temporarily unavailable. Please try again.',
+      role: 'assistant',
+      timestamp: new Date().toISOString(),
+    };
+    switch (authorization.status) {
+      case 'wallet_disconnected':
+        recovery.content = walletTextUtils.getWalletText('Please connect your HIT wallet to continue.', serviceId);
+        recovery.button = 'connectWallet';
+        break;
+      case 'wallet_signed_out':
+        recovery.content = walletTextUtils.getWalletText('Please sign in with your HIT wallet to continue.', serviceId);
+        recovery.button = 'signIn';
+        break;
+      case 'wallet_session_invalid':
+        recovery.content = walletTextUtils.getWalletText('Invalid wallet session. Please sign in again.', serviceId);
+        recovery.button = 'signIn';
+        break;
+      case 'wallet_verification_required':
+        recovery.content = 'Please verify your wallet identity before using this tool.';
+        recovery.button = 'verifyWallet';
+        break;
+      case 'ait_not_found':
+        recovery.content = 'No AIT found for your wallet. Please open settings to configure your AIT.';
+        break;
+      case 'permission_denied':
+        recovery.content = `You don't have the required AIT permission: ${authorization.requiredPermission}. Would you like to enable AIT permission?`;
+        recovery.button = 'enableAIT';
+        recovery.metadata = { requiredPermission: authorization.requiredPermission };
+        break;
+      case 'authorization_unavailable':
+        break;
+    }
+    setMessages(prev => [...prev, recovery]);
+    return false;
   };
 
   // AI Model related functions
@@ -1679,6 +1411,9 @@ export const ChatBotProvider: React.FC<ChatBotProps> = ({
     const hasContent = content.trim() || (attachments && attachments.length > 0);
     if (!hasContent || isLoading) return;
     setPendingAutoTts(null);
+    const turnExternalId = typeof window !== 'undefined'
+      ? localStorage.getItem('walletAddress') || undefined
+      : hitAddressRef.current || undefined;
 
     const currentModel = getCurrentModel();
     // Initialize with current model, will be updated with actual model from backend response
@@ -1757,7 +1492,7 @@ export const ChatBotProvider: React.FC<ChatBotProps> = ({
         model: currentModel.value,
         ...authFields(),
         pseudoId: pseudoId,
-        externalId: localStorage.getItem('walletAddress') || undefined,
+        externalId: turnExternalId,
         customUserInfo,
         customUsername,
         message: content || (attachments && attachments.length > 0 ? `Uploaded ${attachments.length} file(s)` : ''),
@@ -1987,93 +1722,13 @@ export const ChatBotProvider: React.FC<ChatBotProps> = ({
 
         let toolMsg = '';
         if (onToolUse) {
-          let wasAutoConnected = false;
-          let wasAutoSignedIn = false;
-          // Added: Mark if permission denied due to missing AIT permission
-          let permissionDenied = false;
-          // Use requiredPermission from response if available, otherwise fall back to toolUse.name
-          const permissionToCheck = (response as any)?.requiredPermission || toolUse.name;
-
           const isToolAllowed = await hasPermission(
-            permissionToCheck,
-            true,
-            () => { wasAutoConnected = true },
-            () => { wasAutoSignedIn = true }
+            toolUse.name,
           );
 
-          // If currentPermissions does not include permissionToCheck and availablePermissionLabels includes permissionToCheck, it means AIT permission is missing
-          if (!isToolAllowed && !permissions.includes(permissionToCheck) && availablePermissions.map(p => p.label).includes(permissionToCheck)) {
-            permissionDenied = true;
-          }
+          // Typed preflight already emitted the only permitted recovery UI.
           if (!isToolAllowed) {
-            // If permission denied due to missing AIT permission return
-            if (permissionDenied) {
-              setIsLoading(false);
-              return;
-            }
-
-            if (isSemiAutomaticMode) {
-              setIsLoading(false);
-              setMessages(prev => [...prev, {
-                id: Date.now().toString(),
-                content: 'Click button to continue using tool',
-                role: 'assistant',
-                timestamp: new Date().toISOString(),
-                button: 'continue'
-              }]);
-              return;
-            } else {
-              // Only retry for auto-connect/auto-sign-in scenarios
-              if (wasAutoConnected && retryCount < 1) {
-                // Clear loading state and retry immediately
-                setIsLoading(false);
-
-                // Check if wallet is already signed in
-                const currentToken = nxtlinqAITServiceAccessTokenRef.current;
-
-                if (!currentToken) {
-                  // If not signed in, directly retry the message without waiting for AIT
-                  setTimeout(() => {
-                    sendMessage(content, retryCount + 1, isPresetMessage);
-                  }, 2000);
-                } else {
-                  // If already signed in, wait for AIT to be fully loaded before retrying
-                  setTimeout(async () => {
-                    // Wait for AIT to be loaded if needed
-                    if (!aitRef.current && nxtlinqAITServiceAccessTokenRef.current) {
-                      await refreshAIT();
-                    }
-
-                    // Wait for AIT to be fully loaded with polling
-                    let attempts = 0;
-                    const maxAttempts = 5; // Wait up to 10 seconds (5 * 2000ms)
-                    while (!aitRef.current && attempts < maxAttempts) {
-                      await new Promise(resolve => setTimeout(resolve, 2000));
-                      attempts++;
-                    }
-
-                    // Only retry if AIT is actually loaded
-                    if (aitRef.current) {
-                      // Wait a bit more to ensure permissions are also loaded
-                      await new Promise(resolve => setTimeout(resolve, 3000));
-                      sendMessage(content, retryCount + 1, isPresetMessage);
-                    }
-                  }, 2000);
-                }
-              }
-              return;
-            }
-          }
-
-          if (isSemiAutomaticMode && wasAutoSignedIn) {
             setIsLoading(false);
-            setMessages(prev => [...prev, {
-              id: Date.now().toString(),
-              content: 'Click button to continue using tool',
-              role: 'assistant',
-              timestamp: new Date().toISOString(),
-              button: 'continue'
-            }]);
             return;
           }
 

package/src/index.ts

@@ -32,6 +32,8 @@ export type {
   Message,
   SendMessageOptions,
   NxtlinqAgentSnapshot,
+  TextToolAuthorizationSnapshot,
+  TextToolAuthorizationOutcome,
   VoiceSession,
   VoiceStatus,
 } from '@bytexbyte/nxtlinq-ai-agent-core-development';
@@ -41,6 +43,9 @@ export {
   setApiHosts,
   VoiceNotSupportedError,
   STORAGE_KEYS,
+  authorizeTextFrontendTool,
+  hasRecordedWalletVerification,
+  validateWalletSession,
 } from '@bytexbyte/nxtlinq-ai-agent-core-development';
 
 export {

package/src/types/ChatBotTypes.ts

@@ -81,11 +81,6 @@ export interface ChatBotProps {
   isStopRecordingOnSend?: boolean; // Stop recording automatically when sending message (default: false)
   // Custom error message to display in chat
   customError?: string; // Custom error message to display as a chat message when provided
-  /** PII display mode: how PII protection is visualized in chat messages
-   * - 'plain': No visualization, messages look like normal chat
-   * - 'redacted': Anonymized text with PII tokens displayed (default)
-   */
-  piiDisplayMode?: 'plain' | 'redacted';
   /** Override mic VAD thresholds. Useful for tuning sensitivity per deployment. */
   voiceThresholds?: {
     speechRmsThreshold?: number;
@@ -139,7 +134,8 @@ export interface ChatBotContextType {
   selectedModelIndex: number;
   showModelSelector: boolean;
   suggestions: PresetMessage[];
-  // PII Protection visualization
+  // PII Protection visualization — derived internally from the service's own config
+  // (fetched via serviceId + credentials), never settable from outside the provider.
   piiDisplayMode: 'plain' | 'redacted';
   // Realtime voice mode (WebRTC)
   isVoiceMode: boolean;