@memberjunction/ai-agents 5.22.0 → 5.24.0

package/dist/base-agent.js

@@ -24,6 +24,7 @@ import { AgentRunner } from './AgentRunner.js';
 import { PayloadManager } from './PayloadManager.js';
 import { ScratchpadManager } from './ScratchpadManager.js';
 import { AgentDataPreloader } from './AgentDataPreloader.js';
+import { ClientToolRequestManager } from './ClientToolRequestManager.js';
 import { ConversationMessageResolver } from './utils/ConversationMessageResolver.js';
 import _ from 'lodash';
 /**
@@ -831,13 +832,36 @@ export class BaseAgent {
         this._activeProvider = params.provider || Metadata.Provider;
         try {
             this.logStatus(`🤖 Starting execution of agent '${params.agent.Name}'`, true, params);
-            // Check permissions - user must have run permission or be the owner
-            const canRun = await AIAgentPermissionHelper.HasPermission(params.agent.ID, params.contextUser, 'run');
-            if (!canRun) {
-                const errorMessage = `User ${params.contextUser.Email} does not have permission to run agent '${params.agent.Name}' (ID: ${params.agent.ID})`;
-                this.logStatus(`🚫 ${errorMessage}`, false, params);
-                throw new Error(errorMessage);
-            }
+            // =====================================================================================
+            // LATENCY OPTIMIZATION (Opt #4): Parallelized initialization sequence.
+            //
+            // The agent initialization pipeline was originally fully sequential: each operation
+            // awaited before the next began, even when there were no data dependencies between
+            // them. This added ~150-200ms of unnecessary serial wait time.
+            //
+            // The restructured pipeline uses 4 phases:
+            //
+            //   PRE-WORK (sync/fast): Parameter wrapping, markup conversion, payload init,
+            //     cancellation check, payload validation (may exit early).
+            //
+            //   PHASE 1 (parallel): Permission check + Engine init + AgentRun creation.
+            //     These three are mutually independent. If permission fails, we mark the
+            //     already-created AgentRun as failed and terminate — the wasted run record
+            //     is a negligible cost vs. the ~150ms saved by not serializing these.
+            //
+            //   PHASE 2 (parallel): Config load + Data preload + Context memory injection.
+            //     All three depend on Phase 1 completing (engines loaded, agentRun exists)
+            //     but NOT on each other. Config load reads from AIEngine's in-memory cache.
+            //     Data preload fetches agent data sources. Context memory loads notes/examples
+            //     and injects them into the conversation messages.
+            //
+            //   PHASE 3 (sequential): Agent type initialization — must wait for config from
+            //     Phase 2 because it needs the resolved agent type and prompt configuration.
+            //
+            // Original total init time: ~sum of all operations (~400-500ms)
+            // Optimized: ~max(Phase1) + max(Phase2) + Phase3 (~200-300ms)
+            // =====================================================================================
+            // --- PRE-WORK: Fast synchronous setup and early-exit checks ---
             // Wrap the progress callback to capture all events
             const wrappedParams = {
                 ...params,
@@ -849,12 +873,20 @@ export class BaseAgent {
             }
             // Reset scratchpad for each new execution (ephemeral per run)
             this._scratchpadManager.Clear();
+            // Initialize starting payload — must complete before AgentRun creation since the
+            // run record stores the starting payload snapshot.
             await this.initializeStartingPayload(wrappedParams);
             // Check for cancellation at start
             if (params.cancellationToken?.aborted) {
                 this.logStatus(`⚠️ Agent '${params.agent.Name}' execution cancelled before start`, true, params);
                 return await this.createCancelledResult('Cancelled before execution started', params.contextUser);
             }
+            // Handle starting payload validation if configured — may return early with a
+            // validation failure result, so we run this before launching expensive parallel work.
+            const startingValidationResult = await this.handleStartingPayloadValidation(wrappedParams);
+            if (startingValidationResult) {
+                return startingValidationResult;
+            }
             // Report initialization progress
             wrappedParams.onProgress?.({
                 step: 'initialization',
@@ -864,31 +896,44 @@ export class BaseAgent {
                     hierarchicalStep: this.buildHierarchicalStep(0, this._parentStepCounts)
                 }
             });
-            // Initialize execution tracking
-            await this.initializeAgentRun(wrappedParams);
-            // Reset validation retry counters for this run
+            // --- PHASE 1: Permission check + Engine init + AgentRun creation (parallel) ---
+            // These three operations have zero data dependencies on each other:
+            // - Permission check queries the AIAgentPermission entity
+            // - Engine init calls AIEngine.Instance.Config() and ActionEngineServer.Instance.Config()
+            // - AgentRun creation inserts a new AIAgentRun record
+            //
+            // If permission check fails, we mark the AgentRun as failed. This is acceptable:
+            // an orphaned "failed" run record is harmless and far cheaper than serializing these
+            // three operations (~150ms savings).
+            const [canRun] = await Promise.all([
+                AIAgentPermissionHelper.HasPermission(params.agent.ID, params.contextUser, 'run'),
+                this.initializeEngines(params.contextUser),
+                this.initializeAgentRun(wrappedParams)
+            ]);
+            if (!canRun) {
+                // Permission denied — mark the already-created AgentRun as failed so it doesn't
+                // appear as a phantom "running" record in the UI.
+                const errorMessage = `User ${params.contextUser.Email} does not have permission to run agent '${params.agent.Name}' (ID: ${params.agent.ID})`;
+                this.logStatus(`🚫 ${errorMessage}`, false, params);
+                if (this._agentRun) {
+                    this._agentRun.Status = 'Failed';
+                    this._agentRun.ErrorMessage = errorMessage;
+                    await this._agentRun.Save();
+                }
+                throw new Error(errorMessage);
+            }
+            // Reset per-run state (sync, instant — no parallelization needed)
             this._validationRetryCount = 0;
             this._generalValidationRetryCount = 0;
             this._contextRecoveryAttempts = 0;
-            // Reset effective actions and dynamic limits for this run
             this._effectiveActions = [];
             this._dynamicActionLimits = {};
-            // Reset media outputs accumulator for this run
-            // (unified array now includes both promoted media and intercepted binary with refIds)
             this._mediaOutputs = [];
-            // Store message lifecycle callback if provided
             this._messageLifecycleCallback = params.onMessageLifecycle;
-            // Initialize engines
-            await this.initializeEngines(params.contextUser);
-            // Check for cancellation after initialization
+            // Check for cancellation after Phase 1
             if (params.cancellationToken?.aborted) {
                 return await this.createCancelledResult('Cancelled during initialization', params.contextUser);
             }
-            // Handle starting payload validation if configured
-            const startingValidationResult = await this.handleStartingPayloadValidation(wrappedParams);
-            if (startingValidationResult) {
-                return startingValidationResult;
-            }
             // Report validation progress
             wrappedParams.onProgress?.({
                 step: 'validation',
@@ -898,34 +943,26 @@ export class BaseAgent {
                     hierarchicalStep: this.buildHierarchicalStep(0, this._parentStepCounts)
                 }
             });
-            // Create and track validation step
+            // Validate agent — may return early with a failure result. Runs after engines are
+            // initialized (Phase 1) since validation may inspect AIEngine metadata.
             const validationResult = await this.validateAgentWithTracking(params.agent, params.contextUser);
             if (validationResult)
                 return validationResult;
-            // Load agent configuration
+            // --- PHASE 2: Config load + Data preload + Context memory injection (parallel) ---
+            // All three depend on Phase 1 completing (engines initialized, agentRun exists) but
+            // have no dependencies on each other:
+            // - Config load reads agent type, prompts, and agent prompts from AIEngine's in-memory
+            //   cache — typically < 5ms but async due to potential Config() refresh.
+            // - Data preload fetches agent data sources and creates a tracking step entity.
+            // - Context memory resolves scope configuration (pure computation), then loads notes
+            //   and examples from the DB and injects them into conversation messages.
             this.logStatus(`📋 Loading configuration for agent '${params.agent.Name}'`, true, params);
-            const config = await this.loadAgentConfiguration(params.agent);
-            if (!config.success) {
-                this.logError(`Failed to load agent configuration: ${config.errorMessage}`, {
-                    agent: params.agent,
-                    category: 'AgentConfiguration'
-                });
-                return await this.createFailureResult(config.errorMessage || 'Failed to load agent configuration', params.contextUser);
-            }
-            // Preload agent data sources unless disabled
-            await this.preloadAgentData(wrappedParams);
-            // now initialize the agent type which gets us the instance setup in our class plus also gets the agent type to initialize
-            // its state
-            await this.initializeAgentType(wrappedParams, config);
-            // Inject context memory (notes and examples) before execution
+            // Pre-compute scope configuration for context memory injection (pure computation,
+            // no I/O — safe to do before launching the parallel phase).
             const userId = params.userId || params.contextUser?.ID;
             const companyId = params.companyId;
-            // Extract input text from conversation messages (last user message)
-            const lastUserMessage = params.conversationMessages
-                .filter(m => m.role === 'user')
-                .pop();
+            const lastUserMessage = params.conversationMessages.filter(m => m.role === 'user').pop();
             const inputText = lastUserMessage?.content || '';
-            // Parse agent-level scope config for note/example filtering
             const scopeConfigJson = params.agent.ScopeConfig;
             let scopeConfig = null;
             if (scopeConfigJson) {
@@ -934,11 +971,9 @@ export class BaseAgent {
                 }
                 catch { /* ignore bad JSON */ }
             }
-            // Resolve scope params from top-level params or data fallback (for GraphQL callers)
             const primaryScopeEntityName = params.PrimaryScopeEntityName ?? params.data?.PrimaryScopeEntityName;
             const primaryScopeRecordId = params.PrimaryScopeRecordID ?? params.data?.PrimaryScopeRecordID;
             const secondaryScopes = params.SecondaryScopes ?? params.data?.SecondaryScopes;
-            // Resolve entity name to entity ID for scope filtering
             let primaryScopeEntityId;
             if (primaryScopeEntityName) {
                 const primaryEntity = this._metadata.Entities.find(e => e.Name === primaryScopeEntityName);
@@ -946,8 +981,22 @@ export class BaseAgent {
                     primaryScopeEntityId = primaryEntity.ID;
                 }
             }
-            // Inject context memory (notes and examples) into conversation messages
-            await this.InjectContextMemory(typeof inputText === 'string' ? inputText : '', params.agent, userId, companyId, params.contextUser, wrappedParams.conversationMessages, primaryScopeEntityId, primaryScopeRecordId, secondaryScopes, scopeConfig);
+            const [config] = await Promise.all([
+                this.loadAgentConfiguration(params.agent),
+                this.preloadAgentData(wrappedParams),
+                this.InjectContextMemory(typeof inputText === 'string' ? inputText : '', params.agent, userId, companyId, params.contextUser, wrappedParams.conversationMessages, primaryScopeEntityId, primaryScopeRecordId, secondaryScopes, scopeConfig)
+            ]);
+            if (!config.success) {
+                this.logError(`Failed to load agent configuration: ${config.errorMessage}`, {
+                    agent: params.agent,
+                    category: 'AgentConfiguration'
+                });
+                return await this.createFailureResult(config.errorMessage || 'Failed to load agent configuration', params.contextUser);
+            }
+            // --- PHASE 3: Agent type initialization (sequential) ---
+            // Must wait for config from Phase 2 because it needs the resolved agent type and
+            // prompt configuration to initialize the type-specific state machine.
+            await this.initializeAgentType(wrappedParams, config);
             // Execute the agent's internal logic with wrapped parameters
             this.logStatus(`🚀 Executing agent '${params.agent.Name}' internal logic`, true, params);
             const executionResult = await this.executeAgentInternal(wrappedParams, config);
@@ -1673,6 +1722,9 @@ export class BaseAgent {
             case 'While':
                 // While loops are valid - no additional validation needed
                 return nextStep;
+            case 'ClientTools':
+                // Client tools are valid - execution handled by executeClientToolsStep
+                return nextStep;
             default:
                 // if we get here, the next step is not recognized, we can return a retry step
                 this.logError(`Invalid next step '${nextStep.step}' for agent '${params.agent.Name}'`, {
@@ -2598,9 +2650,9 @@ export class BaseAgent {
                 ? currentStepCount - msg.metadata.turnAdded
                 : 0,
             tokens: this.estimateTokens(msg.content),
-            isActionResult: msg.metadata?.messageType === 'action-result'
+            isToolResult: this.IsToolResultMessage(msg)
         }))
-            .filter(c => c.isActionResult && c.age >= minAge)
+            .filter(c => c.isToolResult && c.age >= minAge)
             .sort((a, b) => b.age - a.age); // Oldest first
         // Remove messages until we've saved enough
         for (const candidate of candidates) {
@@ -2651,10 +2703,10 @@ export class BaseAgent {
                 ? currentStepCount - msg.metadata.turnAdded
                 : 0,
             tokens: this.estimateTokens(msg.content),
-            isActionResult: msg.metadata?.messageType === 'action-result',
+            isToolResult: this.IsToolResultMessage(msg),
             alreadyCompacted: msg.metadata?.wasCompacted === true
         }))
-            .filter(c => c.isActionResult && c.age >= minAge && !c.alreadyCompacted)
+            .filter(c => c.isToolResult && c.age >= minAge && !c.alreadyCompacted)
             .sort((a, b) => b.age - a.age); // Oldest first
         for (const candidate of candidates) {
             if (tokensSaved >= tokensToSave)
@@ -2713,10 +2765,10 @@ export class BaseAgent {
             message: msg,
             index: index,
             tokens: this.estimateTokens(msg.content),
-            isActionResult: msg.metadata?.messageType === 'action-result',
+            isToolResult: this.IsToolResultMessage(msg),
             alreadyCompacted: msg.metadata?.wasCompacted === true
         }))
-            .filter(c => c.isActionResult && !c.alreadyCompacted && c.tokens > 200)
+            .filter(c => c.isToolResult && !c.alreadyCompacted && c.tokens > 200)
             .sort((a, b) => b.tokens - a.tokens); // Largest first
         for (const candidate of candidates) {
             if (tokensSaved >= tokensToSave)
@@ -3004,6 +3056,10 @@ The context is now within limits. Please retry your request with the recovered c
             const agentType = engine.AgentTypes.find(at => UUIDsEqual(at.ID, agent.TypeID));
             const runtimePromptParamOverrides = extraData?.__agentTypePromptParams;
             const agentTypePromptParams = this.buildAgentTypePromptParams(agentType, agent, runtimePromptParamOverrides);
+            // Build client tool details for the prompt
+            const clientToolDetails = this.buildClientToolPromptSection(agent, extraData);
+            // Build app context section if provided in extraData
+            const appContext = this.buildAppContextSection(extraData);
             const contextData = {
                 agentName: agent.Name,
                 agentDescription: agent.Description,
@@ -3012,6 +3068,8 @@ The context is now within limits. Please retry your request with the recovered c
                 subAgentDetails: this.formatSubAgentDetails(uniqueActiveSubAgents),
                 actionCount: activeActions.length,
                 actionDetails: this.formatActionDetails(activeActions),
+                clientToolDetails: clientToolDetails,
+                appContext: appContext,
             };
             // Build the final result with __agentTypePromptParams injected
             // Note: extraData can override contextData properties, but __agentTypePromptParams
@@ -3023,7 +3081,11 @@ The context is now within limits. Please retry your request with the recovered c
             if (extraData) {
                 // Spread extraData but don't let it override __agentTypePromptParams
                 // (which was already built with runtime overrides included)
-                const { __agentTypePromptParams: _ignored, ...restExtraData } = extraData;
+                // Spread extraData into the result but exclude properties that were already
+                // processed into formatted prompt sections above. Without this exclusion,
+                // the raw objects from extraData would overwrite the formatted markdown strings
+                // in contextData (e.g., appContext object would replace the markdown string).
+                const { __agentTypePromptParams: _ignored, appContext: _ignoredAppContext, ...restExtraData } = extraData;
                 return {
                     ...result,
                     ...restExtraData
@@ -3501,6 +3563,123 @@ The context is now within limits. Please retry your request with the recovered c
             return lines.join('\n');
         }).join('\n\n');
     }
+    /**
+     * Build the client tool prompt section for system prompt injection.
+     *
+     * Tool sources (checked in order, all merged — first registration wins):
+     * 1. Metadata tools from AI Agent Client Tools junction table
+     * 2. Session-level enriched tools from ClientToolRequestManager (set by client SDK)
+     * 3. Tools provided directly in extraData.clientTools (runtime override)
+     */
+    buildClientToolPromptSection(agent, extraData) {
+        const toolMap = new Map();
+        // 1. Metadata tools from junction table (authoritative source)
+        const engine = AIEngine.Instance;
+        const metadataTools = engine.GetClientToolsForAgent(agent.ID);
+        for (const tool of metadataTools) {
+            toolMap.set(tool.Name, {
+                Name: tool.Name,
+                Description: tool.Description,
+                InputSchema: tool.InputSchemaJSON ? JSON.parse(tool.InputSchemaJSON) : {},
+                OutputSchema: tool.OutputSchemaJSON ? JSON.parse(tool.OutputSchemaJSON) : undefined,
+                Category: tool.Category || undefined,
+                DefaultTimeoutMs: tool.DefaultTimeoutMs || undefined
+            });
+        }
+        // 2. Session-level enriched tools (client SDK decorated tools)
+        const sessionID = extraData?.sessionID;
+        if (sessionID) {
+            for (const tool of ClientToolRequestManager.Instance.GetSessionTools(sessionID)) {
+                if (!toolMap.has(tool.Name)) {
+                    toolMap.set(tool.Name, tool);
+                }
+            }
+        }
+        // 3. Runtime extraData override
+        if (extraData?.clientTools) {
+            for (const tool of extraData.clientTools) {
+                if (!toolMap.has(tool.Name)) {
+                    toolMap.set(tool.Name, tool);
+                }
+            }
+        }
+        const tools = Array.from(toolMap.values());
+        if (tools.length === 0) {
+            return ''; // No client tools available
+        }
+        const lines = [];
+        lines.push('### Client Tools (execute in the user\'s browser)');
+        lines.push('Client tools run in the user\'s browser and interact with the UI. Use these when you need');
+        lines.push('to navigate the user somewhere, display a specific view, switch dashboard tabs, or show');
+        lines.push('records. When you choose client tools, set nextStep.type to "ClientTools".');
+        lines.push('');
+        lines.push('NOTE: Do NOT use client tools for asking the user questions or collecting input.');
+        lines.push('Use the "Chat" step for that. Client tools are for programmatic UI interaction only.');
+        lines.push('');
+        for (const tool of tools) {
+            const categoryTag = tool.Category ? ` [${tool.Category}]` : '';
+            lines.push(`- **${tool.Name}**${categoryTag}: ${tool.Description}`);
+            // Show input parameters from InputSchema
+            const props = tool.InputSchema?.properties;
+            const required = tool.InputSchema?.required;
+            if (props) {
+                const paramParts = Object.entries(props).map(([name, schema]) => {
+                    const req = required?.includes(name) ? '\\*' : '';
+                    const desc = schema.description ? ` — ${schema.description}` : '';
+                    return `\`${name}\`${req}${desc}`;
+                });
+                lines.push(`  Inputs: ${paramParts.join(', ')}`);
+            }
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Build the app context section for system prompt injection.
+     * Reads the AppContextSnapshot from extraData.appContext and formats
+     * it as a concise markdown section the LLM can reference.
+     */
+    buildAppContextSection(extraData) {
+        const ctx = extraData?.appContext;
+        if (!ctx)
+            return '';
+        const app = ctx['App'];
+        const activeNav = ctx['ActiveNavItem'];
+        const otherNavs = ctx['OtherNavItems'];
+        const user = ctx['User'];
+        if (!app?.Name)
+            return '';
+        const lines = [];
+        lines.push('### Current Application Context');
+        lines.push(`The user is currently in the **${app.Name}** application${app.Description ? ` — ${app.Description}` : ''}.`);
+        if (activeNav?.Name) {
+            lines.push('');
+            lines.push(`**Active view:** ${activeNav.Name}${activeNav.Description ? ` — ${activeNav.Description}` : ''}${activeNav.ResourceType ? ` (${activeNav.ResourceType})` : ''}`);
+        }
+        if (otherNavs && otherNavs.length > 0) {
+            lines.push('');
+            lines.push('**Other views available in this app:**');
+            for (const nav of otherNavs) {
+                lines.push(`- ${nav.Name}${nav.Description ? ` — ${nav.Description}` : ''}`);
+            }
+        }
+        if (user?.Name) {
+            lines.push('');
+            lines.push(`**User:** ${user.Name}${user.Roles?.length ? ` (Roles: ${user.Roles.join(', ')})` : ''}`);
+        }
+        // Additional context reported by the active view/component
+        const dashboardCtx = ctx['AdditionalContext'];
+        if (dashboardCtx && Object.keys(dashboardCtx).length > 0) {
+            lines.push('');
+            lines.push('**Dashboard state:**');
+            for (const [key, value] of Object.entries(dashboardCtx)) {
+                if (value === null || value === undefined)
+                    continue;
+                const displayValue = typeof value === 'object' ? JSON.stringify(value) : String(value);
+                lines.push(`- ${key}: ${displayValue}`);
+            }
+        }
+        return lines.join('\n');
+    }
     /**
      * Formats a single action parameter as a compact inline string.
      * Uses \* suffix for required, (array) when IsArray, and only shows
@@ -4247,6 +4426,10 @@ The context is now within limits. Please retry your request with the recovered c
                 return await this.processSubAgentStep(params, previousDecision, undefined, undefined, stepCount);
             case 'Actions':
                 return await this.executeActionsStep(params, previousDecision, undefined, true, stepCount);
+            // Type assertion required because 'ClientTools' is not yet in the DB StepType value list.
+            // The LoopAgentType.DetermineNextStep() emits this value when the LLM chooses client tools.
+            case 'ClientTools':
+                return await this.executeClientToolsStep(params, config, previousDecision, stepCount);
             case 'Chat':
                 return await this.executeChatStep(params, previousDecision);
             case 'Success':
@@ -4620,6 +4803,17 @@ The context is now within limits. Please retry your request with the recovered c
             else if (updatedNextStep.step === 'Success' || updatedNextStep.step === 'Failed') {
                 return { ...updatedNextStep, terminate: true };
             }
+            else if (updatedNextStep.step === 'ClientTools') {
+                // ClientTools must return terminate: false so the main loop continues
+                // to the next iteration where executeClientToolsStep actually dispatches
+                // and awaits the tool. The LLM's original terminate intent is preserved in
+                // terminateAfterExecution so executeClientToolsStep can honor it post-execution.
+                return {
+                    ...updatedNextStep,
+                    terminate: false,
+                    terminateAfterExecution: updatedNextStep.terminate
+                };
+            }
             else {
                 return { ...updatedNextStep, terminate: false };
             }
@@ -5821,6 +6015,130 @@ The context is now within limits. Please retry your request with the recovered c
      *
      * @private
      */
+    // ================================================================
+    // Client Tools Step Execution
+    // ================================================================
+    /**
+     * Execute client-side tools requested by the agent.
+     * Sends each tool invocation via PubSub, awaits the client's response
+     * (or timeout), then adds results to the conversation and continues.
+     */
+    async executeClientToolsStep(params, config, previousDecision, stepCount = 0) {
+        const clientTools = previousDecision.clientTools ?? [];
+        if (clientTools.length === 0) {
+            // No tools to execute — continue with next prompt
+            return await this.executePromptStep(params, config, previousDecision, stepCount);
+        }
+        if (!params.sessionID) {
+            // No session ID — can't communicate with client
+            const errorMsg = 'Cannot execute client tools: no sessionID provided in ExecuteAgentParams';
+            LogError(errorMsg);
+            params.conversationMessages.push({
+                role: 'user',
+                content: `Client tool execution skipped: ${errorMsg}`
+            });
+            return await this.executePromptStep(params, config, previousDecision, stepCount);
+        }
+        const currentPayload = previousDecision?.newPayload || previousDecision?.previousPayload || params.payload;
+        // Build assistant message describing the tool invocations
+        const toolMessage = clientTools.length === 1
+            ? `I'm invoking the **${clientTools[0].Name}** client tool${clientTools[0].Description ? ` — ${clientTools[0].Description}` : ''}.`
+            : `I'm invoking **${clientTools.length} client tools**:\n\n` +
+                clientTools.map((t, i) => `${i + 1}. **${t.Name}**${t.Description ? ` — ${t.Description}` : ''}`).join('\n');
+        params.conversationMessages.push({
+            role: 'assistant',
+            content: toolMessage
+        });
+        // Report progress
+        params.onProgress?.({
+            step: 'action_execution', // Reuse action_execution step type for progress reporting
+            message: this.formatHierarchicalMessage(toolMessage),
+            metadata: {
+                toolCount: clientTools.length,
+                toolNames: clientTools.map(t => t.Name),
+                stepCount: stepCount + 1,
+                hierarchicalStep: this.buildHierarchicalStep(stepCount + 1, this._parentStepCounts)
+            },
+            displayMode: 'live'
+        });
+        // Resolve default timeout: per-tool > params > agent config > 30s
+        const defaultTimeout = params.clientToolTimeoutMs ?? 30_000;
+        const results = [];
+        const agentRunID = this._agentRun?.ID ?? 'unknown';
+        // Execute tools sequentially (client may not support parallel UI operations)
+        for (const tool of clientTools) {
+            const stepEntity = await this.createStepEntity({
+                // INTENTIONAL: We use 'Actions' as the DB step type because the MJ: AI Agent Run Steps
+                // entity's StepType value list does not yet include 'ClientTools'. A future database
+                // migration will add 'ClientTools' to the allowed values in the StepType CHECK constraint
+                // and CodeGen will regenerate the types. Until then, client tool steps are recorded under
+                // 'Actions' in the run history. The step name ("Client Tool: {name}") distinguishes them.
+                stepType: 'Actions',
+                stepName: `Client Tool: ${tool.Name}`,
+                inputData: { toolName: tool.Name, params: tool.Params },
+                contextUser: params.contextUser,
+                payloadAtStart: currentPayload,
+                payloadAtEnd: currentPayload
+            });
+            const timeoutMs = tool.TimeoutMs ?? defaultTimeout;
+            const response = await ClientToolRequestManager.Instance.RequestClientTool(`ct_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`, tool.Name, tool.Params, params.sessionID, agentRunID, timeoutMs, tool.Description);
+            await this.finalizeStepEntity(stepEntity, response.Success, response.ErrorMessage, { result: response.Result });
+            results.push({
+                ToolName: tool.Name,
+                Success: response.Success,
+                Result: response.Result,
+                ErrorMessage: response.ErrorMessage
+            });
+        }
+        // Format results as conversation message
+        const resultsMarkdown = this.formatClientToolResultsAsMarkdown(results);
+        params.conversationMessages.push({
+            role: 'user',
+            content: resultsMarkdown,
+            metadata: {
+                turnAdded: this._promptTurnCount,
+                messageType: 'client-tool-result'
+            }
+        });
+        // If the LLM already declared taskComplete=true alongside the client tools,
+        // honor that intent now that tools have executed — no need for another LLM call.
+        if (previousDecision.terminateAfterExecution) {
+            return {
+                step: 'Success',
+                terminate: true,
+                message: previousDecision.message || 'Client tools executed successfully.',
+                payloadChangeRequest: previousDecision.payloadChangeRequest,
+                scratchpad: previousDecision.scratchpad,
+                responseForm: previousDecision.responseForm,
+                actionableCommands: previousDecision.actionableCommands,
+                automaticCommands: previousDecision.automaticCommands
+            };
+        }
+        return await this.executePromptStep(params, config, previousDecision, stepCount);
+    }
+    /**
+     * Format client tool results as a compact markdown summary for the conversation.
+     */
+    formatClientToolResultsAsMarkdown(results) {
+        const failedCount = results.filter(r => !r.Success).length;
+        const header = failedCount > 0
+            ? `${failedCount} of ${results.length} client tool(s) failed:`
+            : 'Client tool results:';
+        const lines = results.map(r => {
+            const icon = r.Success ? '✓' : '✗';
+            let line = `${icon} **${r.ToolName}**: ${r.Success ? 'succeeded' : 'failed'}`;
+            if (r.ErrorMessage)
+                line += ` — ${r.ErrorMessage}`;
+            if (r.Success && r.Result != null) {
+                const resultStr = typeof r.Result === 'string' ? r.Result : JSON.stringify(r.Result);
+                if (resultStr.length <= 500) {
+                    line += `\n  Result: ${resultStr}`;
+                }
+            }
+            return line;
+        });
+        return `${header}\n${lines.join('\n')}`;
+    }
     async executeChatStep(params, previousDecision) {
         const stepEntity = await this.createStepEntity({ stepType: 'Chat', stepName: 'User Interaction', contextUser: params.contextUser });
         // Chat steps are successful - they indicate a need for user interaction
@@ -7165,6 +7483,14 @@ The context is now within limits. Please retry your request with the recovered c
      * @param modelName - Optional model name for accurate tokenization
      * @protected
      */
+    /**
+     * Returns true if the message is a tool result (action or client tool).
+     * Used by recovery strategies to identify compactable result messages.
+     */
+    IsToolResultMessage(msg) {
+        const messageType = msg.metadata?.messageType;
+        return messageType === 'action-result' || messageType === 'client-tool-result';
+    }
     estimateTokens(content, modelName) {
         const text = typeof content === 'string'
             ? content