@mobileai/react-native 0.9.17 → 0.9.19

package/lib/module/core/AgentRuntime.js

@@ -16,9 +16,18 @@ import { walkFiberTree } from "./FiberTreeWalker.js";
 import { dehydrateScreen } from "./ScreenDehydrator.js";
 import { buildSystemPrompt, buildKnowledgeOnlyPrompt } from "./systemPrompt.js";
 import { KnowledgeBaseService } from "../services/KnowledgeBaseService.js";
+import { installAlertInterceptor, uninstallAlertInterceptor } from "./NativeAlertInterceptor.js";
 import { createTapTool, createLongPressTool, createTypeTool, createScrollTool, createSliderTool, createPickerTool, createDatePickerTool, createKeyboardTool, createGuideTool, createSimplifyTool, createRestoreTool } from "../tools/index.js";
 import { actionRegistry } from "./ActionRegistry.js";
 const DEFAULT_MAX_STEPS = 25;
+function generateTraceId() {
+  return `trace_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+const APPROVAL_GRANTED_TOKEN = '__APPROVAL_GRANTED__';
+const APPROVAL_REJECTED_TOKEN = '__APPROVAL_REJECTED__';
+const APPROVAL_ALREADY_DONE_TOKEN = '__APPROVAL_ALREADY_DONE__';
+const USER_ALREADY_COMPLETED_MESSAGE = '✅ It looks like you already completed that step yourself. Great — let me know if you want help with anything else.';
+const ACTION_NOT_APPROVED_MESSAGE = "Okay — I won't do that. If you'd like, I can help with something else instead.";
 
 // ─── Agent Runtime ─────────────────────────────────────────────
 
@@ -30,6 +39,7 @@ export class AgentRuntime {
   lastAskUserQuestion = null;
   knowledgeService = null;
   lastDehydratedRoot = null;
+  currentTraceId = null;
 
   // ─── Task-scoped error suppression ──────────────────────────
   // Installed once at execute() start, removed after grace period.
@@ -39,6 +49,14 @@ export class AgentRuntime {
   lastSuppressedError = null;
   graceTimer = null;
   originalReportErrorsAsExceptions = undefined;
+
+  // ─── App-action approval gate ────────────────────────────────
+  // Tracks whether the support consent flow (ask_user + request_app_action=true)
+  // has been issued and whether the user has explicitly approved it via button tap.
+  // Only UI-altering tools are gated; informational tools (done, query_knowledge) are not.
+  appActionApproved = false; // true only after __APPROVAL_GRANTED__ received
+  // Tools that physically alter the app — must be gated by appAction approval
+  static APP_ACTION_TOOLS = new Set(['tap', 'type', 'scroll', 'navigate', 'long_press', 'slider', 'picker', 'date_picker', 'keyboard']);
   getConfig() {
     return this.config;
   }
@@ -182,6 +200,11 @@ export class AgentRuntime {
           description: 'Response message to the user',
           required: true
         },
+        message: {
+          type: 'string',
+          description: 'Alternative to text parameter',
+          required: false
+        },
         success: {
           type: 'boolean',
           description: 'Whether the task was completed successfully',
@@ -189,7 +212,12 @@ export class AgentRuntime {
         }
       },
       execute: async args => {
-        return args.text;
+        let cleanText = args.text || args.message || '';
+        if (typeof cleanText === 'string') {
+          // Strip bracketed indices safely avoiding regex stack overflows on large strings
+          cleanText = cleanText.replace(/\[\d+\]/g, '').replace(/  +/g, ' ').trim();
+        }
+        return cleanText;
       }
     });
 
@@ -214,23 +242,58 @@ export class AgentRuntime {
     // ask_user — ask for clarification
     this.tools.set('ask_user', {
       name: 'ask_user',
-      description: 'Ask the user a question and wait for their answer. Use this if you need more information or clarification.',
+      description: 'Communicate with the user. Use this to ask questions, request permission for app actions, OR answer a question the user asked.',
       parameters: {
         question: {
           type: 'string',
-          description: 'Question to ask the user',
+          description: 'The message or question to say to the user',
+          required: true
+        },
+        request_app_action: {
+          type: 'boolean',
+          description: 'Set to true when requesting permission to take an action in the app (navigate, tap, investigate). Shows explicit approval buttons to the user.',
           required: true
         }
       },
       execute: async args => {
+        // Strip any leaked bracketed indices like [41] safely
+        let cleanQuestion = args.question || '';
+        if (typeof cleanQuestion === 'string') {
+          cleanQuestion = cleanQuestion.replace(/\[\d+\]/g, '').replace(/  +/g, ' ').trim();
+        }
+        const kind = args.request_app_action ? 'approval' : 'freeform';
+
+        // Mark that the support approval flow has been initiated
+        if (args.request_app_action) {
+          this.appActionApproved = false; // reset until user taps Allow
+          logger.info('AgentRuntime', '🔒 App action gate: approval requested, UI tools now BLOCKED until granted');
+        }
+        logger.info('AgentRuntime', `❓ ask_user emitted (kind=${kind}): "${cleanQuestion}"`);
         if (this.config.onAskUser) {
           // Block until user responds, then continue the loop
           this.config.onStatusUpdate?.('Waiting for your answer...');
-          const answer = await this.config.onAskUser(args.question);
+          logger.info('AgentRuntime', `⏸️ Waiting for user response via onAskUser callback (kind=${kind})`);
+          const answer = await this.config.onAskUser({
+            question: cleanQuestion,
+            kind
+          });
+          logger.info('AgentRuntime', `✅ ask_user resolved with: "${String(answer)}"`);
+
+          // Resolve approval gate based on button response
+          if (answer === '__APPROVAL_GRANTED__') {
+            this.appActionApproved = true;
+            logger.info('AgentRuntime', '✅ App action gate: APPROVED — UI tools unblocked');
+          } else if (answer === '__APPROVAL_REJECTED__') {
+            this.appActionApproved = false;
+            logger.info('AgentRuntime', '🚫 App action gate: REJECTED — UI tools remain blocked');
+          }
+          // Any other text answer (conversational interruption) leaves appActionApproved as-is
+
           return `User answered: ${answer}`;
         }
         // Legacy fallback: break the loop (context will be lost)
-        return `❓ ${args.question}`;
+        logger.warn('AgentRuntime', '⚠️ ask_user has no onAskUser callback; returning legacy fallback');
+        return `❓ ${cleanQuestion}`;
       }
     });
 
@@ -712,7 +775,7 @@ ${screen.elementsText}
    * The global ErrorUtils handler is task-scoped (installed in execute()),
    * so this method only needs to CHECK for errors, not install/remove.
    */
-  async executeToolSafely(tool, args, toolName) {
+  async executeToolSafely(tool, args, toolName, stepIndex) {
     // Clear any previous suppressed error before this tool
     this.lastSuppressedError = null;
 
@@ -720,10 +783,20 @@ ${screen.elementsText}
     // This prevents AI-driven taps from being tracked as user_interaction events.
     this.config.onToolExecute?.(true);
     try {
+      this.emitTrace('tool_execution_started', {
+        tool: toolName,
+        args
+      }, stepIndex);
+
       // ── Argument Validation (Pattern from Detox/Appium: typeof checks before native dispatch) ──
       const validationError = this.validateToolArgs(args, toolName);
       if (validationError) {
         logger.warn('AgentRuntime', `🛡️ Arg validation rejected "${toolName}": ${validationError}`);
+        this.emitTrace('tool_validation_rejected', {
+          tool: toolName,
+          args,
+          validationError
+        }, stepIndex);
         return validationError;
       }
 
@@ -732,8 +805,29 @@ ${screen.elementsText}
       // user confirmation before execution. This is the code-level safety net
       // complementing the prompt-level copilot instructions.
       if (this.config.interactionMode !== 'autopilot') {
-        const confirmResult = await this.checkCopilotConfirmation(toolName, args);
+        logger.info('AgentRuntime', `🛡️ Checking copilot confirmation for ${toolName}(${JSON.stringify(args)})`);
+        const confirmResult = await this.checkCopilotConfirmation(toolName, args, stepIndex);
         if (confirmResult) return confirmResult;
+      } else {
+        logger.info('AgentRuntime', `🚀 interactionMode=autopilot, skipping copilot confirmation for "${toolName}"`);
+        this.emitTrace('confirmation_skipped_autopilot', {
+          tool: toolName,
+          args
+        }, stepIndex);
+      }
+
+      // ── App-action approval gate ────────────────────────────────────────
+      // Mandate explicit ask_user approval for all UI-altering tools ONLY if we are in
+      // copilot mode AND the host app has provided an onAskUser callback.
+      // If the model tries to use a UI tool without explicitly getting approval, we block it.
+      if (this.config.interactionMode !== 'autopilot' && this.config.onAskUser && AgentRuntime.APP_ACTION_TOOLS.has(toolName) && !this.appActionApproved) {
+        const blockedMsg = `🚫 APP ACTION BLOCKED: You are attempting to use "${toolName}" but have not yet received explicit user approval. You MUST first call ask_user(request_app_action=true) and wait for the user to explicitly tap 'Allow' before executing ANY UI actions (including navigate, tap, scroll, etc).`;
+        logger.warn('AgentRuntime', blockedMsg);
+        this.emitTrace('app_action_gate_blocked', {
+          tool: toolName,
+          args
+        }, stepIndex);
+        return blockedMsg;
       }
       const result = await tool.execute(args);
 
@@ -744,11 +838,27 @@ ${screen.elementsText}
       if (suppressedError) {
         logger.warn('AgentRuntime', `🛡️ Tool "${toolName}" caused async error (suppressed): ${suppressedError.message}`);
         this.lastSuppressedError = null;
+        this.emitTrace('tool_async_error_suppressed', {
+          tool: toolName,
+          args,
+          result,
+          error: suppressedError.message
+        }, stepIndex);
         return `${result} (⚠️ a background error was safely caught: ${suppressedError.message})`;
       }
+      this.emitTrace('tool_execution_finished', {
+        tool: toolName,
+        args,
+        result
+      }, stepIndex);
       return result;
     } catch (error) {
       logger.error('AgentRuntime', `Tool "${toolName}" threw: ${error.message}`);
+      this.emitTrace('tool_execution_failed', {
+        tool: toolName,
+        args,
+        error: error?.message ?? String(error)
+      }, stepIndex);
       return `❌ Tool "${toolName}" failed: ${error.message}`;
     } finally {
       // Always restore the flag — even on error or validation rejection
@@ -784,6 +894,18 @@ ${screen.elementsText}
     }
     return null;
   }
+  emitTrace(stage, data = {}, stepIndex) {
+    if (!this.currentTraceId || !this.config.onTrace) return;
+    const event = {
+      traceId: this.currentTraceId,
+      stage,
+      timestamp: new Date().toISOString(),
+      stepIndex,
+      screenName: this.getCurrentScreenName(),
+      data
+    };
+    this.config.onTrace(event);
+  }
 
   // ─── Copilot Confirmation ─────────────────────────────────────
 
@@ -794,39 +916,145 @@ ${screen.elementsText}
    * Check if a tool call targets an aiConfirm element and request user confirmation.
    * Returns null if the action should proceed, or an error string if rejected.
    */
-  async checkCopilotConfirmation(toolName, args) {
+  async checkCopilotConfirmation(toolName, args, stepIndex) {
     // Only gate write tools
-    if (!AgentRuntime.WRITE_TOOLS.has(toolName)) return null;
+    if (!AgentRuntime.WRITE_TOOLS.has(toolName)) {
+      logger.info('AgentRuntime', `🛡️ No confirmation needed for "${toolName}" because it is not a write tool`);
+      this.emitTrace('confirmation_not_needed', {
+        tool: toolName,
+        reason: 'not_write_tool',
+        args
+      }, stepIndex);
+      return null;
+    }
 
     // Look up the target element by index
     const index = args.index;
-    if (typeof index !== 'number') return null;
+    if (typeof index !== 'number') {
+      logger.info('AgentRuntime', `🛡️ No confirmation needed for "${toolName}" because no element index was provided`);
+      this.emitTrace('confirmation_not_needed', {
+        tool: toolName,
+        reason: 'missing_index',
+        args
+      }, stepIndex);
+      return null;
+    }
     const screen = this.lastDehydratedRoot;
-    if (!screen?.elements) return null;
+    if (!screen?.elements) {
+      logger.warn('AgentRuntime', `🛡️ Could not evaluate confirmation for "${toolName}" because no dehydrated screen was available`);
+      this.emitTrace('confirmation_not_evaluated', {
+        tool: toolName,
+        reason: 'missing_dehydrated_screen',
+        args
+      }, stepIndex);
+      return null;
+    }
     const element = screen.elements.find(e => e.index === index);
-    if (!element?.requiresConfirmation) return null;
+    if (!element) {
+      logger.warn('AgentRuntime', `🛡️ Could not find element index ${index} for "${toolName}" on screen "${screen.screenName}"`);
+      this.emitTrace('confirmation_not_evaluated', {
+        tool: toolName,
+        reason: 'element_not_found',
+        args,
+        index
+      }, stepIndex);
+      return null;
+    }
+    logger.info('AgentRuntime', `🛡️ Copilot gate inspect: tool="${toolName}" index=${index} label="${element.label}" type="${element.type}" aiConfirm=${element.requiresConfirmation === true}`);
+    if (!element.requiresConfirmation) {
+      logger.info('AgentRuntime', `🛡️ No confirmation needed for "${toolName}" on "${element.label}" because aiConfirm is not set`);
+      this.emitTrace('confirmation_not_needed', {
+        tool: toolName,
+        reason: 'aiConfirm_not_set',
+        args,
+        elementLabel: element.label,
+        elementType: element.type,
+        index
+      }, stepIndex);
+      return null;
+    }
 
     // Element has aiConfirm — request user confirmation
     const label = element.label || `[${element.type}]`;
     const description = this.getToolStatusLabel(toolName, args);
-    const question = `I'm about to ${description} on "${label}". Should I proceed?`;
+    const question = `I can do this in the app for you by tapping and typing where needed, and ${description} on "${label}". If you'd rather do it yourself, I can guide you step by step instead.`;
     logger.info('AgentRuntime', `🛡️ Copilot: aiConfirm gate triggered for "${toolName}" on "${label}"`);
+    this.emitTrace('confirmation_required', {
+      tool: toolName,
+      args,
+      elementLabel: label,
+      elementType: element.type,
+      index,
+      question
+    }, stepIndex);
 
     // Use onAskUser if available (integrated into chat UI), otherwise Alert.alert
     if (this.config.onAskUser) {
-      const response = await this.config.onAskUser(question);
-      const approved = /^(yes|ok|sure|go|proceed|confirm|y)/i.test(response.trim());
-      if (!approved) {
+      logger.info('AgentRuntime', `🛡️ Requesting explicit confirmation via ask_user for "${label}"`);
+      this.emitTrace('confirmation_prompted', {
+        tool: toolName,
+        elementLabel: label,
+        elementType: element.type,
+        question,
+        channel: 'ask_user'
+      }, stepIndex);
+      const response = await this.config.onAskUser({
+        question,
+        kind: 'approval'
+      });
+      logger.info('AgentRuntime', `🛡️ Confirmation response for "${label}": "${String(response)}"`);
+      this.emitTrace('confirmation_response_received', {
+        tool: toolName,
+        elementLabel: label,
+        response: String(response)
+      }, stepIndex);
+      if (response === APPROVAL_ALREADY_DONE_TOKEN) {
+        this.emitTrace('confirmation_already_done', {
+          tool: toolName,
+          elementLabel: label
+        }, stepIndex);
+        return APPROVAL_ALREADY_DONE_TOKEN;
+      }
+      if (response === APPROVAL_GRANTED_TOKEN) {
+        logger.info('AgentRuntime', `✅ User approved "${toolName}" on "${label}"`);
+        this.emitTrace('confirmation_approved', {
+          tool: toolName,
+          elementLabel: label,
+          response: 'explicit_button'
+        }, stepIndex);
+        return null;
+      }
+      if (response === APPROVAL_REJECTED_TOKEN) {
         logger.info('AgentRuntime', `🛑 User rejected "${toolName}" on "${label}"`);
-        return `❌ User rejected "${toolName}" action on "${label}". Ask what they would like to do instead.`;
+        this.emitTrace('confirmation_rejected', {
+          tool: toolName,
+          elementLabel: label,
+          response: 'explicit_button'
+        }, stepIndex);
+        return ACTION_NOT_APPROVED_MESSAGE;
       }
-      return null;
+
+      // If it's conversational input (e.g. "Why?"), pause the action and pass the user's question back to the LLM so it can answer it!
+      this.emitTrace('confirmation_interrupted', {
+        tool: toolName,
+        elementLabel: label,
+        response: String(response)
+      }, stepIndex);
+      return `Action paused because the user interrupted with this message: "${response}". Please answer the user by fully explaining your logic.`;
     }
 
     // Fallback: React Native Alert
     const {
       Alert
     } = require('react-native');
+    logger.info('AgentRuntime', `🛡️ Requesting explicit confirmation via native Alert for "${label}"`);
+    this.emitTrace('confirmation_prompted', {
+      tool: toolName,
+      elementLabel: label,
+      elementType: element.type,
+      question,
+      channel: 'native_alert'
+    }, stepIndex);
     const approved = await new Promise(resolve => {
       Alert.alert('Confirm Action', question, [{
         text: 'Cancel',
@@ -841,8 +1069,19 @@ ${screen.elementsText}
     });
     if (!approved) {
       logger.info('AgentRuntime', `🛑 User rejected "${toolName}" on "${label}"`);
-      return `❌ User rejected "${toolName}" action on "${label}". Ask what they would like to do instead.`;
+      this.emitTrace('confirmation_rejected', {
+        tool: toolName,
+        elementLabel: label,
+        response: 'cancel'
+      }, stepIndex);
+      return ACTION_NOT_APPROVED_MESSAGE;
     }
+    logger.info('AgentRuntime', `✅ User approved "${toolName}" on "${label}" via native Alert`);
+    this.emitTrace('confirmation_approved', {
+      tool: toolName,
+      elementLabel: label,
+      response: 'continue'
+    }, stepIndex);
     return null;
   }
 
@@ -852,7 +1091,8 @@ ${screen.elementsText}
     return {
       interactiveBlacklist: this.config.interactiveBlacklist,
       interactiveWhitelist: this.config.interactiveWhitelist,
-      screenName: this.getCurrentScreenName()
+      screenName: this.getCurrentScreenName(),
+      interceptNativeAlerts: this.config.interceptNativeAlerts
     };
   }
 
@@ -1020,8 +1260,11 @@ ${screen.elementsText}
     this.isRunning = true;
     this.isCancelRequested = false;
     this.history = [];
+    this.currentTraceId = generateTraceId();
     this.observations = [];
     this.lastScreenName = '';
+    // Reset app-action approval gate for each new task
+    this.appActionApproved = false;
     const maxSteps = this.config.maxSteps || DEFAULT_MAX_STEPS;
     const stepDelay = this.config.stepDelay ?? 300;
 
@@ -1044,7 +1287,19 @@ ${screen.elementsText}
     // Lifecycle: onBeforeTask
     await this.config.onBeforeTask?.();
     try {
-      // ── Start error suppression (3 layers) ──────────────────
+      this.emitTrace('task_started', {
+        message: userMessage,
+        contextualMessage,
+        maxSteps,
+        interactionMode: this.config.interactionMode || 'copilot',
+        enableUIControl: this.config.enableUIControl !== false,
+        chatHistoryLength: chatHistory?.length ?? 0
+      });
+
+      // ── Start interceptors & error suppression ──────────────────
+      if (this.config.interceptNativeAlerts) {
+        installAlertInterceptor();
+      }
       this._startErrorSuppression();
 
       // ─── Knowledge-only fast path ─────────────────────────────────
@@ -1120,6 +1375,9 @@ ${screen.elementsText}
         // ── Cancel check ──
         if (this.isCancelRequested) {
           logger.info('AgentRuntime', `Task cancelled by user at step ${step + 1}`);
+          this.emitTrace('task_cancelled', {
+            reason: 'user_cancelled'
+          }, step);
           const cancelResult = {
             success: false,
             message: 'Task was cancelled.',
@@ -1130,6 +1388,11 @@ ${screen.elementsText}
           return cancelResult;
         }
         logger.info('AgentRuntime', `===== Step ${step + 1}/${maxSteps} =====`);
+        this.emitTrace('step_started', {
+          maxSteps,
+          historyLength: this.history.length
+        }, step);
+        logger.info('AgentRuntime', `⚙️ Effective mode: interactionMode=${this.config.interactionMode || 'copilot(default)'} | onAskUser=${!!this.config.onAskUser} | enableUIControl=${this.config.enableUIControl !== false}`);
 
         // Lifecycle: onBeforeStep
         await this.config.onBeforeStep?.(step);
@@ -1141,8 +1404,12 @@ ${screen.elementsText}
 
         // Store root for tooling access (e.g., GuideTool measuring)
         this.lastDehydratedRoot = screen;
+        this.emitTrace('screen_dehydrated', {
+          screenName: screen.screenName,
+          elementCount: screen.elements.length,
+          elementsTextLength: screen.elementsText.length
+        }, step);
         logger.info('AgentRuntime', `Screen: ${screen.screenName}`);
-        logger.debug('AgentRuntime', `Dehydrated:\n${screen.elementsText}`);
 
         // 2. Apply transformScreenContent
         let screenContent = screen.elementsText;
@@ -1160,7 +1427,7 @@ ${screen.elementsText}
         const screenshot = await this.captureScreenshot();
 
         // 5. Send to AI provider
-        this.config.onStatusUpdate?.('Analyzing screen...');
+        this.config.onStatusUpdate?.('Thinking...');
         const hasKnowledge = !!this.knowledgeService;
         const isCopilot = this.config.interactionMode !== 'autopilot';
         const systemPrompt = buildSystemPrompt('en', hasKnowledge, isCopilot);
@@ -1169,6 +1436,19 @@ ${screen.elementsText}
         logger.debug('AgentRuntime', 'System prompt length:', systemPrompt.length);
         logger.debug('AgentRuntime', 'User context message:', contextMessage.substring(0, 300));
         const response = await this.provider.generateContent(systemPrompt, contextMessage, tools, this.history, screenshot);
+        this.emitTrace('provider_response', {
+          text: response.text,
+          toolCalls: response.toolCalls,
+          tokenUsage: response.tokenUsage
+        }, step);
+        logger.info('AgentRuntime', `🤖 Provider response: textLength=${response.text?.length || 0} toolCalls=${response.toolCalls?.length || 0}`);
+        if (response.toolCalls?.length) {
+          response.toolCalls.forEach((toolCall, idx) => {
+            logger.info('AgentRuntime', `🤖 Tool call[${idx}]: ${toolCall.name}(${JSON.stringify(toolCall.args)})`);
+          });
+        } else if (response.text) {
+          logger.info('AgentRuntime', `🤖 Provider text response: ${response.text}`);
+        }
 
         // Accumulate token usage
         if (response.tokenUsage) {
@@ -1182,6 +1462,11 @@ ${screen.elementsText}
         // ── Budget Guards ──────────────────────────────────────
         if (this.config.maxTokenBudget && sessionUsage.totalTokens >= this.config.maxTokenBudget) {
           logger.warn('AgentRuntime', `Token budget exceeded: ${sessionUsage.totalTokens} >= ${this.config.maxTokenBudget}`);
+          this.emitTrace('task_stopped_budget', {
+            budgetType: 'tokens',
+            used: sessionUsage.totalTokens,
+            limit: this.config.maxTokenBudget
+          }, step);
           const budgetResult = {
             success: false,
             message: `Task stopped: token budget exceeded (used ${sessionUsage.totalTokens.toLocaleString()} of ${this.config.maxTokenBudget.toLocaleString()} tokens)`,
@@ -1193,6 +1478,11 @@ ${screen.elementsText}
         }
         if (this.config.maxCostUSD && sessionUsage.estimatedCostUSD >= this.config.maxCostUSD) {
           logger.warn('AgentRuntime', `Cost budget exceeded: $${sessionUsage.estimatedCostUSD.toFixed(4)} >= $${this.config.maxCostUSD}`);
+          this.emitTrace('task_stopped_budget', {
+            budgetType: 'cost_usd',
+            used: sessionUsage.estimatedCostUSD,
+            limit: this.config.maxCostUSD
+          }, step);
           const budgetResult = {
             success: false,
             message: `Task stopped: cost budget exceeded ($${sessionUsage.estimatedCostUSD.toFixed(4)} of $${this.config.maxCostUSD.toFixed(2)} max)`,
@@ -1206,6 +1496,9 @@ ${screen.elementsText}
         // 6. Process tool calls
         if (!response.toolCalls || response.toolCalls.length === 0) {
           logger.warn('AgentRuntime', 'No tool calls in response. Text:', response.text);
+          this.emitTrace('task_completed_without_tool', {
+            responseText: response.text
+          }, step);
           const result = {
             success: true,
             message: response.text || 'Task completed.',
@@ -1232,6 +1525,14 @@ ${screen.elementsText}
           logger.warn('AgentRuntime', `AI returned ${response.toolCalls.length} tool calls, executing only the first one.`);
         }
         logger.info('AgentRuntime', `Tool: ${toolCall.name}(${JSON.stringify(toolCall.args)})`);
+        this.emitTrace('tool_selected', {
+          tool: toolCall.name,
+          args: toolCall.args,
+          reasoning
+        }, step);
+        if (toolCall.name !== 'ask_user' && this.config.interactionMode !== 'autopilot') {
+          logger.info('AgentRuntime', `🛡️ Tool "${toolCall.name}" chosen without prompt-level pause; relying on model plan-following and aiConfirm safeguards if present`);
+        }
 
         // Dynamic status update based on tool being executed + Reasoning
         const statusLabel = this.getToolStatusLabel(toolCall.name, toolCall.args);
@@ -1243,11 +1544,30 @@ ${screen.elementsText}
         const tool = this.tools.get(toolCall.name) || this.buildToolsForProvider().find(t => t.name === toolCall.name);
         let output;
         if (tool) {
-          output = await this.executeToolSafely(tool, toolCall.args, toolCall.name);
+          output = await this.executeToolSafely(tool, toolCall.args, toolCall.name, step);
         } else {
+          this.emitTrace('tool_unknown', {
+            tool: toolCall.name,
+            args: toolCall.args
+          }, step);
           output = `❌ Unknown tool: ${toolCall.name}`;
         }
         logger.info('AgentRuntime', `Result: ${output}`);
+        this.emitTrace('tool_result', {
+          tool: toolCall.name,
+          args: toolCall.args,
+          output
+        }, step);
+        if (output === APPROVAL_ALREADY_DONE_TOKEN) {
+          const result = {
+            success: true,
+            message: USER_ALREADY_COMPLETED_MESSAGE,
+            steps: this.history,
+            tokenUsage: sessionUsage
+          };
+          await this.config.onAfterTask?.(result);
+          return result;
+        }
 
         // Record step with structured reasoning
         const agentStep = {
@@ -1268,24 +1588,37 @@ ${screen.elementsText}
         if (toolCall.name === 'done') {
           const result = {
             success: toolCall.args.success !== false,
-            message: toolCall.args.text || output,
+            message: toolCall.args.text || toolCall.args.message || output || reasoning.plan || (toolCall.args.success === false ? 'Action stopped.' : 'Action completed.'),
             steps: this.history,
             tokenUsage: sessionUsage
           };
           logger.info('AgentRuntime', `Task completed: ${result.message}`);
+          this.emitTrace('task_completed', {
+            success: result.success,
+            message: result.message,
+            steps: this.history.length,
+            tokenUsage: sessionUsage
+          }, step);
           await this.config.onAfterTask?.(result);
           return result;
         }
 
         // Check if asking user (legacy path — only breaks loop when onAskUser is NOT set)
         if (toolCall.name === 'ask_user' && !this.config.onAskUser) {
-          this.lastAskUserQuestion = toolCall.args.question || output;
+          let rawQuestion = toolCall.args.question || output || '';
+          if (typeof rawQuestion === 'string') {
+            rawQuestion = rawQuestion.replace(/\[\d+\]/g, '').replace(/  +/g, ' ').trim();
+          }
+          this.lastAskUserQuestion = rawQuestion;
           const result = {
             success: true,
-            message: output,
+            message: this.lastAskUserQuestion || '',
             steps: this.history,
             tokenUsage: sessionUsage
           };
+          this.emitTrace('task_paused_for_user', {
+            question: this.lastAskUserQuestion || ''
+          }, step);
           await this.config.onAfterTask?.(result);
           return result;
         }
@@ -1306,10 +1639,19 @@ ${screen.elementsText}
       if (__DEV__ && this.config.interactionMode !== 'autopilot') {
         logger.info('AgentRuntime', 'ℹ️ Copilot mode active. Tip: Add aiConfirm={true} to critical buttons (e.g. "Place Order", "Delete") for extra safety.');
       }
+      this.emitTrace('task_failed_max_steps', {
+        success: false,
+        steps: this.history.length,
+        message: result.message
+      });
       await this.config.onAfterTask?.(result);
       return result;
     } catch (error) {
       logger.error('AgentRuntime', 'Execution error:', error);
+      this.emitTrace('task_failed_error', {
+        error: error?.message ?? String(error),
+        steps: this.history.length
+      });
       const result = {
         success: false,
         message: `Error: ${error.message}`,
@@ -1320,6 +1662,10 @@ ${screen.elementsText}
       return result;
     } finally {
       this.isRunning = false;
+      this.currentTraceId = null;
+      if (this.config.interceptNativeAlerts) {
+        uninstallAlertInterceptor();
+      }
       // ── Grace period: keep error suppression for delayed side-effects ──
       // useEffect callbacks, PagerView onPageSelected, scrollToIndex, etc.
       // can fire AFTER execute() returns. Keep suppression active for 10s.