@memberjunction/server 6.2.0-edge.5 → 6.2.0-edge.7

package/dist/resolvers/RunAIAgentResolver.js

@@ -14,17 +14,20 @@ import { Resolver, Mutation, Query, Arg, Ctx, ObjectType, Field, PubSub, PubSubE
 import { LogError, LogStatus, RunView } from '@memberjunction/core';
 import { ArtifactMetadataEngine, ConversationEngine } from '@memberjunction/core-entities';
 import { RouteArtifact } from './artifact-routing.js';
-import { AgentRunner, ArtifactToolManager } from '@memberjunction/ai-agents';
-import { MJAIAgentRunEntityExtended, ConversationUtility } from '@memberjunction/ai-core-plus';
+import { AgentRunner, ArtifactToolManager, CanAgentOwnSubAgentConsults, LoadOpenSubAgentConsults, HostAllowedAgentIDs } from '@memberjunction/ai-agents';
+import { MJAIAgentRunEntityExtended, ConversationUtility, ContinuationAnnouncementText } from '@memberjunction/ai-core-plus';
 import { AIEngine } from '@memberjunction/aiengine';
 import { ResolverBase } from '../generic/ResolverBase.js';
 import { AgentRunStatusPublisher } from './AgentRunStatusPublisher.js';
+import { ProjectEntityObjectForCaller } from '../generic/fieldSecurityTransport.js';
 import { StartLivenessPulse } from '../generic/FireAndForgetHeartbeat.js';
+import { StatusUpdateOwnerID } from '../generic/PushStatusResolver.js';
 import { RequireSystemUser } from '../directives/RequireSystemUser.js';
 import { GetReadWriteProvider } from '../util.js';
 import { ResolveWidgetGuestRunContext, ElevateUserPayload } from '../realtimeWidget/widgetGuestElevation.js';
+import { AuthorizeConversationTurn } from '../realtimeSessions/sessionAccess.js';
 import { IsTrustedAgentRunCaller } from './agent-run-data-guard.js';
-import { SafeJSONParse, UUIDsEqual } from '@memberjunction/global';
+import { EscapeSQLString, IsValidUUID, SafeJSONParse, UUIDsEqual } from '@memberjunction/global';
 import { GetAttachmentService } from '@memberjunction/aiengine';
 import { NotificationEngine } from '@memberjunction/notifications';
 /**
@@ -208,11 +211,20 @@ AgentExecutionStreamMessage = __decorate([
 ], AgentExecutionStreamMessage);
 export { AgentExecutionStreamMessage };
 let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
+    constructor() {
+        super(...arguments);
+        /**
+         * Tracks `userPayload` instances originating from interactive user mutations (`RunAIAgent` and
+         * `RunAIAgentFromConversationDetail` without API key or widget guest elevation) that may expose
+         * `Handoff` and follow returned handoff decisions.
+         */
+        this.handoffEligiblePayloads = new WeakSet();
+    }
     /**
      * Sanitize ExecuteAgentResult for JSON serialization
      * Removes circular references and non-serializable objects
      */
-    sanitizeAgentResult(result) {
+    sanitizeAgentResult(result, recipient) {
         const sanitized = {
             success: result.success,
             payload: result.payload,
@@ -223,12 +235,14 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
             finalStep: result.agentRun?.FinalStep,
             cancelled: result.agentRun?.Status === 'Cancelled',
             cancellationReason: result.agentRun?.CancellationReason,
-            feedbackRequestId: result.feedbackRequestId
+            feedbackRequestId: result.feedbackRequestId,
+            handoff: result.handoff
         };
         // Safely extract agent run data using GetAll() for proper serialization
         if (result.agentRun && typeof result.agentRun.GetAll === 'function') {
-            // Use GetAll() to get the full serialized object including extended properties
-            sanitized.agentRun = result.agentRun.GetAll();
+            // GetAll() for the full serialized object including extended properties, projected for
+            // the recipient: the run comes from the agent engine, not from a load bound to them
+            sanitized.agentRun = ProjectEntityObjectForCaller(result.agentRun, recipient);
         }
         else {
             // shouldn't ever get here
@@ -314,7 +328,12 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
     /** ExecuteAgentParams.TrustReservedRunData: true only for a caller IsTrustedAgentRunCaller accepts. */
     trustReservedRunData = false, 
     /** The conversation branch of the run — threaded into ExecuteAgentParams.ConversationBranchID. */
-    conversationBranchId) {
+    conversationBranchId, 
+    /** The reply row this request created on the server for the run (`conversationDetailId` is its ID). The run
+     *  writes into this instance, so its writes carry the server-authored marker and the user it was made as. */
+    replyDetail, 
+    /** Optional explicit handoff override; defaults to whether the caller registered `userPayload` as interactive. */
+    followHandoffs) {
         const startTime = Date.now();
         // Best-effort handle for persistInFlightAgentFailure. Populated from a
         // progress event carrying metadata.agentRun, or from the successful
@@ -322,6 +341,8 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
         // run is not marked Failed — the early-failure case we most want to
         // persist, but we have no run object yet.
         const agentRunRef = runRef ?? { current: null };
+        // The publisher owns every status message, including the failure completion the catch below sends.
+        const statusPublisher = new AgentRunStatusPublisher(pubSub, userPayload, sessionId, conversationDetailId);
         try {
             LogStatus(`=== RUNNING AI AGENT FOR ID: ${agentId} ===`);
             // Parse and validate messages
@@ -348,12 +369,17 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
             console.log(`🚀 Starting agent execution with sessionId: ${sessionId}`);
             // The publisher owns every status message. The resolver still copies the run into
             // agentRunRef, including noise steps, for the fire-and-forget liveness pulse.
-            const statusPublisher = new AgentRunStatusPublisher(pubSub, userPayload, sessionId);
-            const publishProgress = statusPublisher.OnProgress;
-            // Execute the agent in conversation context - handles conversation, artifacts, etc.
-            const conversationResult = await agentRunner.RunAgentInConversation({
+            const sourcePublisher = statusPublisher;
+            let currentPublisher = sourcePublisher;
+            // A widget- or guest-hosted run must not get a handoffChain unless the host also passes an
+            // allow-list under trusted run data.
+            const effectiveFollowHandoffs = followHandoffs ?? this.handoffEligiblePayloads.has(userPayload);
+            const isGuestOrWidgetUser = Boolean(currentUser.IsMagicLinkAnonymous || currentUser.WidgetGuestContext);
+            const allowHandoff = effectiveFollowHandoffs && (!isGuestOrWidgetUser
+                || (trustReservedRunData && HostAllowedAgentIDs(parsedData) !== undefined));
+            const sourceParams = {
                 agent: agentEntity,
-                conversationMessages: parsedMessages,
+                conversationMessages: [...parsedMessages],
                 payload: payload ? SafeJSONParse(payload) : undefined,
                 contextUser: currentUser,
                 sessionID: sessionId,
@@ -362,9 +388,9 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
                     if (isAgentRunEntity(fromEvent)) {
                         agentRunRef.current = fromEvent;
                     }
-                    publishProgress(progress);
+                    sourcePublisher.OnProgress(progress);
                 },
-                onStreaming: statusPublisher.OnStreaming,
+                onStreaming: sourcePublisher.OnStreaming,
                 lastRunId: lastRunId,
                 autoPopulateLastRunPayload: autoPopulateLastRunPayload,
                 configurationId: configurationId,
@@ -373,20 +399,26 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
                 taskGraphDebug: parseTaskGraphDebug(taskGraphDebug),
                 ConversationHistoryFrom: conversationHistoryFrom,
                 ...(conversationBranchId ? { ConversationBranchID: conversationBranchId } : {}),
+                ...(allowHandoff ? { handoffChain: [] } : {}),
                 data: parsedData,
                 // Whether the run may read the reserved data keys (scope, agent-type params); BaseAgent drops them otherwise.
                 TrustReservedRunData: trustReservedRunData,
                 context: {
                     dataSource: dataSource
                 }
-            }, {
+            };
+            // Execute the agent in conversation context - handles conversation, artifacts, etc.
+            const conversationResult = await agentRunner.RunAgentInConversation(sourceParams, {
                 conversationDetailId: conversationDetailId, // Use existing if provided
+                agentResponseDetail: replyDetail, // the reply row this request created, when it did
                 conversationId: conversationId, // LATENCY OPT #2: pre-resolved to skip redundant load in AgentRunner
                 userMessage: userMessage, // Provide user message when conversationDetailId not provided
                 createArtifacts: createArtifacts || false,
-                sourceArtifactId: sourceArtifactId
+                sourceArtifactId: sourceArtifactId,
+                // A widget guest runs as the system user, but its conversation stays the guest's to write (MJ#4791).
+                ConversationWriter: userPayload.ElevatedFrom,
             });
-            const result = conversationResult.agentResult;
+            let result = conversationResult.agentResult;
             // Use agent response detail ID if available, otherwise fall back to user message detail ID
             const finalConversationDetailId = conversationResult.agentResponseDetailId || conversationResult.userMessageDetailId;
             const artifactInfo = conversationResult.artifactInfo;
@@ -394,40 +426,70 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
             if (result.agentRun) {
                 agentRunRef.current = result.agentRun;
             }
-            const executionTime = Date.now() - startTime;
-            // LATENCY OPTIMIZATION (Opt #6): These three post-execution operations are independent
-            // of each other — none reads the output of another. Previously they ran sequentially,
-            // adding their latencies together (~50ms total). Now they run in parallel via Promise.all,
-            // so we only pay the cost of the slowest one.
-            //
-            // 1. syncFeedbackRequestFromConversation — links a prior Chat-step feedback request to
-            //    the new agent run so the conversation thread stays coherent.
-            // 2. sendFeedbackRequestNotification — sends an in-app/email/SMS notification when the
-            //    agent paused for human input (Chat step).
-            // 3. createCompletionNotification — sends an in-app/email/SMS notification that the
-            //    agent finished and created an artifact.
-            const postExecutionOps = [];
-            if (lastRunId && result.agentRun?.ID) {
-                postExecutionOps.push(this.syncFeedbackRequestFromConversation(lastRunId, result.agentRun.ID, userMessage, currentUser, p));
-            }
-            if (result.feedbackRequestId) {
-                postExecutionOps.push(this.sendFeedbackRequestNotification(result, currentUser, pubSub, userPayload));
-            }
-            if (createNotification && result.success && artifactInfo && artifactInfo.artifactId && artifactInfo.versionId && artifactInfo.versionNumber) {
-                postExecutionOps.push(this.createCompletionNotification(result.agentRun, {
-                    artifactId: artifactInfo.artifactId,
-                    versionId: artifactInfo.versionId,
-                    versionNumber: artifactInfo.versionNumber
-                }, conversationResult.conversationId, finalConversationDetailId, currentUser, pubSub, userPayload));
-            }
-            if (postExecutionOps.length > 0) {
-                await Promise.all(postExecutionOps);
+            await this.runPostExecutionNotifications(result, artifactInfo, conversationResult.conversationId, finalConversationDetailId, lastRunId, userMessage, createNotification, currentUser, pubSub, userPayload, p);
+            let handoffPublishedFinal = false;
+            if (allowHandoff && result.handoff && conversationResult.conversationId && conversationResult.agentResponseDetailId) {
+                const outcomes = await agentRunner.FollowHandoffs({
+                    params: { ...sourceParams, conversationMessages: parsedMessages },
+                    sourceResult: result,
+                    conversationId: conversationResult.conversationId,
+                    sourceConversationDetailId: conversationResult.agentResponseDetailId,
+                    createArtifacts: createArtifacts || false,
+                    ConversationWriter: userPayload.ElevatedFrom,
+                    sourceConversationDetail: replyDetail,
+                    hooks: {
+                        OnHopStart: (hop, previousRun) => {
+                            const prevSanitized = JSON.stringify(this.sanitizeAgentResult(previousRun.agentResult, currentUser));
+                            currentPublisher.PublishFinal(previousRun.agentResult, previousRun.agentResult.agentRun?.ConversationDetailID ?? previousRun.conversationDetailId, prevSanitized);
+                            currentPublisher = new AgentRunStatusPublisher(pubSub, userPayload, sessionId, hop.targetConversationDetailId);
+                            return {
+                                onProgress: (progress) => {
+                                    const fromEvent = progress.metadata?.agentRun;
+                                    if (isAgentRunEntity(fromEvent)) {
+                                        agentRunRef.current = fromEvent;
+                                    }
+                                    currentPublisher.OnProgress(progress);
+                                },
+                                onStreaming: currentPublisher.OnStreaming,
+                            };
+                        },
+                        OnHopEnd: async (_hop, outcome) => {
+                            if (!outcome.agentResult) {
+                                return;
+                            }
+                            if (outcome.agentResult.agentRun) {
+                                agentRunRef.current = outcome.agentResult.agentRun;
+                            }
+                            await this.runPostExecutionNotifications(outcome.agentResult, outcome.artifactInfo, conversationResult.conversationId, outcome.targetConversationDetailId, undefined, undefined, createNotification, currentUser, pubSub, userPayload, p);
+                        },
+                    },
+                });
+                const lastOutcome = outcomes[outcomes.length - 1];
+                if (lastOutcome?.error) {
+                    const executionTime = Date.now() - startTime;
+                    currentPublisher.PublishFailure(lastOutcome.targetConversationDetailId, lastOutcome.error);
+                    LogError(`AI Agent handoff hop failed: ${lastOutcome.error}`);
+                    return {
+                        success: false,
+                        errorMessage: lastOutcome.error,
+                        executionTimeMs: executionTime,
+                        result: JSON.stringify({ success: false, errorMessage: lastOutcome.error })
+                    };
+                }
+                if (lastOutcome?.agentResult) {
+                    const lastHopSanitized = JSON.stringify(this.sanitizeAgentResult(lastOutcome.agentResult, currentUser));
+                    currentPublisher.PublishFinal(lastOutcome.agentResult, lastOutcome.agentResult.agentRun?.ConversationDetailID ?? lastOutcome.targetConversationDetailId, lastHopSanitized);
+                    handoffPublishedFinal = true;
+                }
             }
-            // Create sanitized payload for JSON serialization
-            const sanitizedResult = this.sanitizeAgentResult(result);
+            const executionTime = Date.now() - startTime;
+            // Create sanitized payload for JSON serialization (always tied to the source detail)
+            const sanitizedResult = this.sanitizeAgentResult(result, currentUser);
             const returnResult = JSON.stringify(sanitizedResult);
-            // Publish final events with enriched result data for fire-and-forget clients
-            statusPublisher.PublishFinal(result, result.agentRun?.ConversationDetailID, returnResult);
+            // Publish final events with enriched result data when no handoff hop already finalized via OnHopStart
+            if (!handoffPublishedFinal) {
+                currentPublisher.PublishFinal(result, result.agentRun?.ConversationDetailID, returnResult);
+            }
             // Log completion
             if (result.success) {
                 LogStatus(`=== AI AGENT RUN COMPLETED FOR: ${agentEntity.Name} (${executionTime}ms) ===`);
@@ -445,10 +507,17 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
         catch (error) {
             const executionTime = Date.now() - startTime;
             LogError(`AI Agent run failed:`, undefined, error);
-            const errorMessage = error.message || 'Unknown error occurred';
+            // Never dereference a non-Error throw: this catch must not itself throw, since executeAIAgent resolves on
+            // every failure (executeAgentInBackground relies on it).
+            const errorMessage = (error instanceof Error && error.message) || 'Unknown error occurred';
             // Fire-and-forget clients otherwise leave the run Running and the
             // conversation detail In-Progress (Explorer red-pill timer).
-            await this.persistInFlightAgentFailure(p, userPayload, agentRunRef.current, conversationDetailId, errorMessage);
+            await this.persistInFlightAgentFailure(p, userPayload, agentRunRef.current, conversationDetailId, errorMessage, replyDetail);
+            // A fire-and-forget client has only this message to learn the run ended: without it, it waits out its
+            // idle timeout and then reconciles the run as a success. Published after the rows are closed, so a
+            // client that reloads the reply on this message reads the error. PublishFinal is the try's last step
+            // that can throw, so a run gets one completion or the other, never both.
+            statusPublisher.PublishFailure(conversationDetailId, errorMessage);
             const errorResult = {
                 success: false,
                 errorMessage,
@@ -462,11 +531,45 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
             };
         }
     }
+    /**
+     * LATENCY OPTIMIZATION (Opt #6): Runs the three independent post-execution notification/sync
+     * operations in parallel via `Promise.all` (shared by the initial run and each handoff hop):
+     * 1. `syncFeedbackRequestFromConversation` — links a prior Chat-step feedback request to the new run.
+     * 2. `sendFeedbackRequestNotification` — sends an in-app/email/SMS notification when paused for human input.
+     * 3. `createCompletionNotification` — sends an in-app/email/SMS notification when an artifact was created.
+     */
+    async runPostExecutionNotifications(result, artifactInfo, conversationId, conversationDetailId, lastRunId, userMessage, createNotification, currentUser, pubSub, userPayload, provider) {
+        const postExecutionOps = [];
+        if (lastRunId && result.agentRun?.ID) {
+            postExecutionOps.push(this.syncFeedbackRequestFromConversation(lastRunId, result.agentRun.ID, userMessage, currentUser, provider));
+        }
+        if (result.feedbackRequestId) {
+            postExecutionOps.push(this.sendFeedbackRequestNotification(result, currentUser, pubSub, userPayload));
+        }
+        if (createNotification
+            && result.success
+            && artifactInfo
+            && artifactInfo.artifactId
+            && artifactInfo.versionId
+            && artifactInfo.versionNumber
+            && conversationDetailId) {
+            postExecutionOps.push(this.createCompletionNotification(result.agentRun, {
+                artifactId: artifactInfo.artifactId,
+                versionId: artifactInfo.versionId,
+                versionNumber: artifactInfo.versionNumber
+            }, conversationId, conversationDetailId, currentUser, pubSub, userPayload));
+        }
+        if (postExecutionOps.length > 0) {
+            await Promise.all(postExecutionOps);
+        }
+    }
     /**
      * When executeAIAgent throws after the run/detail exist, close them so Explorer
      * does not leave a red-pill timer on Status=Running / ConversationDetail In-Progress.
      */
-    async persistInFlightAgentFailure(provider, userPayload, run, conversationDetailId, errorMessage) {
+    async persistInFlightAgentFailure(provider, userPayload, run, conversationDetailId, errorMessage, 
+    /** The run's reply row, when this request created it: written in place, as the server. */
+    replyDetail) {
         try {
             if (run && run.Status === 'Running') {
                 await run.EnsureSaveComplete();
@@ -482,7 +585,8 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
                 return;
             }
             if (conversationDetailId) {
-                const detail = await provider.GetEntityObject('MJ: Conversation Details', user);
+                const detail = replyDetail ?? await provider.GetEntityObject('MJ: Conversation Details', user);
+                await detail.EnsureSaveComplete(); // the run may still be saving into the same reply instance
                 if (await detail.Load(conversationDetailId) && detail.Status === 'In-Progress') {
                     await detail.EnsureSaveComplete();
                     detail.Status = 'Error';
@@ -510,6 +614,9 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
         // Only the system user or an API key holding the agent:trusted scope may set a run's scope and agent-type
         // params through data; for anyone else BaseAgent drops those keys (ExecuteAgentParams.TrustReservedRunData).
         const trustRunData = await IsTrustedAgentRunCaller({ UserPayload: userPayload, IsWidgetGuestRun: false, AgentID: agentId });
+        if (!userPayload.apiKeyHash) {
+            this.handoffEligiblePayloads.add(userPayload);
+        }
         if (fireAndForget) {
             // Fire-and-forget mode: start execution in background, return immediately.
             // The client will receive the result via WebSocket PubSub completion event.
@@ -620,15 +727,17 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
         }
     }
     /**
-     * The ID of this agent's newest root run in the conversation IF the user stopped it, else
-     * null. The query spans the runs that could be the predecessor (settled, or stopped by the
-     * user) and the newest decides, so a stopped run that a later settled run already followed
-     * is not chained to again. Uses the same filter and recognizer as `BaseAgent.findUserStoppedPredecessorRunId`
-     * (`MJAIAgentRunEntityExtended.BuildStoppedPredecessorFilter` / `IsUserStopped`), which carries the stopped run's
-     * completed results into the new run's context, so the two cannot pick different runs.
-     * Fail-soft: a lookup failure means no chaining, never a failed turn.
+     * Discovers whether this agent's newest root run on this conversation/branch path should be
+     * chained by `LastRunID` on a chat-thread reply — either because the user stopped it
+     * (`reason: 'stopped'`) or because it paused on `FinalStep === 'Chat'` with one or more
+     * unanswered sub-agent consultations (`reason: 'open-consult'`).
+     *
+     * The query spans the runs that could be the predecessor (settled, or stopped by the user)
+     * and the newest decides, so a stopped or paused-consult run that a later settled run already
+     * followed is not chained to again. Fail-soft: a lookup failure means no chaining, never a
+     * failed turn.
      */
-    async findUserStoppedPredecessorRunId(conversationId, agentId, branchId, contextUser, provider) {
+    async findChainablePredecessor(conversationId, agentId, branchId, contextUser, provider) {
         try {
             // The run must have replied on this turn's branch path: a run stopped on a sibling branch is not
             // this path's history. The trunk needs no branch rows; a branch needs them to walk its ancestry.
@@ -639,16 +748,29 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
                 ExtraFilter: MJAIAgentRunEntityExtended.BuildStoppedPredecessorFilter(conversationId, agentId, branchId, branches),
                 OrderBy: '__mj_CreatedAt DESC',
                 MaxRows: 1,
-                Fields: ['ID', 'Status', 'CancellationReason'],
+                SkipTotalRowCount: true,
+                Fields: ['ID', 'Status', 'CancellationReason', 'FinalStep'],
                 ResultType: 'simple',
-                // The row this looks for was written by the Stop button moments ago; read the database, not a cache.
+                // The row this looks for was written by the Stop button or a Chat pause moments ago; read the database, not a cache.
                 BypassCache: true,
             }, contextUser);
             const run = newest.Success ? newest.Results?.[0] : undefined;
-            return run && MJAIAgentRunEntityExtended.IsUserStopped(run.Status, run.CancellationReason) ? run.ID : null;
+            if (!run) {
+                return null;
+            }
+            if (MJAIAgentRunEntityExtended.IsUserStopped(run.Status, run.CancellationReason)) {
+                return { runId: run.ID, reason: 'stopped' };
+            }
+            if (run.FinalStep === 'Chat' && CanAgentOwnSubAgentConsults(agentId)) {
+                const open = await LoadOpenSubAgentConsults(provider, run.ID, contextUser);
+                if (open.length > 0) {
+                    return { runId: run.ID, reason: 'open-consult' };
+                }
+            }
+            return null;
         }
         catch (error) {
-            LogError(`findUserStoppedPredecessorRunId failed; the turn runs unchained: ${error instanceof Error ? error.message : String(error)}`);
+            LogError(`findChainablePredecessor failed; the turn runs unchained: ${error instanceof Error ? error.message : String(error)}`);
             return null;
         }
     }
@@ -661,11 +783,16 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
      */
     async syncFeedbackRequestFromConversation(lastRunId, newRunId, userMessage, contextUser, provider) {
         try {
+            const trimmedLastRunId = typeof lastRunId === 'string' ? lastRunId.trim() : '';
+            if (!IsValidUUID(trimmedLastRunId)) {
+                return;
+            }
             const rv = RunView.FromMetadataProvider(provider);
             const result = await rv.RunView({
                 EntityName: 'MJ: AI Agent Requests',
-                ExtraFilter: `OriginatingAgentRunID='${lastRunId}' AND Status='Requested'`,
+                ExtraFilter: `OriginatingAgentRunID='${EscapeSQLString(trimmedLastRunId)}' AND Status='Requested'`,
                 MaxRows: 1,
+                SkipTotalRowCount: true,
                 ResultType: 'entity_object'
             }, contextUser);
             if (!result.Success || !result.Results || result.Results.length === 0) {
@@ -741,16 +868,25 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
         }
     }
     /**
-     * Optimized mutation that loads conversation history server-side.
-     * This avoids sending large attachment data from client to server.
+     * Runs an agent's turn in a conversation: the server loads the history (attachments included, so the client never
+     * sends them), creates the agent's reply row, and runs the agent into it.
      *
-     * @param conversationDetailId - The conversation detail ID (user's message already saved)
+     * Only the server writes agent replies (A19). The reply row (`Role` `AI`, In-Progress, its `ParentID` the user's
+     * message) is created here, as the person asking, before the run starts. In fire-and-forget mode the
+     * acknowledgement names it, `{ accepted, fireAndForget, conversationDetailId, createdAt }`, and is returned before
+     * the run publishes anything; every progress, streaming and completion message carries the same
+     * `conversationDetailId`. In synchronous mode the result's `agentRun.ConversationDetailID` names it.
+     *
+     * Threading, both optional: `replyParentId` puts the reply under another message of the same conversation the
+     * caller can read (MJ's chat threads a delegate's reply under the manager's); `announcedByAgentId` has the server
+     * first post that agent's fixed line "Continuing with **{agent}** for refinement..." and thread the reply under
+     * it, and the acknowledgement then also carries `announcementDetailId`.
+     *
+     * @param userMessageId - The person's message this turn answers, already saved.
      * @param agentId - The agent to execute
      * @param maxHistoryMessages - Maximum number of history messages to include (default: 20)
      */
-    async RunAIAgentFromConversationDetail(conversationDetailId, agentId, { userPayload, providers, dataSource }, sessionId, pubSub, maxHistoryMessages, data, payload, lastRunId, autoPopulateLastRunPayload, configurationId, createArtifacts, createNotification, sourceArtifactId, sourceArtifactVersionId, fireAndForget, planMode, requestedSkillIDs, agentHistoryFrom) {
-        // Check API key scope authorization for agent execution
-        await this.CheckAPIKeyScopeAuthorization('agent:execute', agentId, userPayload);
+    async RunAIAgentFromConversationDetail(userMessageId, agentId, { userPayload, providers, dataSource }, sessionId, pubSub, maxHistoryMessages, data, payload, lastRunId, autoPopulateLastRunPayload, configurationId, createArtifacts, createNotification, sourceArtifactId, sourceArtifactVersionId, fireAndForget, planMode, requestedSkillIDs, agentHistoryFrom, replyParentId, announcedByAgentId, replyBranchId) {
         const p = GetReadWriteProvider(providers);
         const currentUser = this.GetUserFromPayload(userPayload);
         if (!currentUser) {
@@ -765,10 +901,20 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
         // AUTHORITATIVELY from the widget instance (never the client-supplied arg) — so a guest needs
         // no grants to WRITE the AI run entities and cannot run an arbitrary agent under elevation.
         // Conversation OWNERSHIP is still enforced under the guest principal below: the guest loads its
-        // own ConversationDetail through the Widget Guest RLS filters, so a detail id from another
-        // session resolves to "not found" before any elevated work happens.
+        // own ConversationDetail through its role's RLS filters, and startConversationTurn then checks
+        // the conversation's scope stamp against the visitor (MJ#6032), so a detail id from another
+        // visitor's session is refused before any elevated work happens. The reply row is written
+        // as the guest too, never as the elevated principal, which owns no guest's conversation.
         const widgetElevation = await ResolveWidgetGuestRunContext(userPayload, p);
         const effectiveAgentId = widgetElevation ? widgetElevation.PinnedAgentId : agentId;
+        // Check API key scope authorization for agent execution against the resolved agent id.
+        await this.CheckAPIKeyScopeAuthorization('agent:execute', effectiveAgentId, userPayload);
+        // A widget guest has one pinned agent and never posts a continuation announcement as another agent;
+        // an API-key caller must hold agent:execute for the announcing agent as well as the running agent.
+        const effectiveAnnouncedByAgentId = widgetElevation ? undefined : announcedByAgentId;
+        if (effectiveAnnouncedByAgentId) {
+            await this.CheckAPIKeyScopeAuthorization('agent:execute', effectiveAnnouncedByAgentId, userPayload);
+        }
         const effectiveUserPayload = widgetElevation ? ElevateUserPayload(userPayload, widgetElevation.ElevatedUser) : userPayload;
         // Only the system user or an API key holding the agent:trusted scope may set a run's scope and agent-type
         // params through data (ExecuteAgentParams.TrustReservedRunData). Judged on the caller's own payload: a widget
@@ -776,60 +922,69 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
         const trustRunData = await IsTrustedAgentRunCaller({
             UserPayload: userPayload, IsWidgetGuestRun: widgetElevation !== null, AgentID: agentId,
         });
+        if (!userPayload.apiKeyHash && !widgetElevation) {
+            this.handoffEligiblePayloads.add(effectiveUserPayload);
+        }
         try {
             // Parsed before anything loads: a floor the caller asked for must never be dropped.
             const historyFrom = parseAgentHistoryFrom(agentHistoryFrom);
-            // LATENCY OPTIMIZATION (Opt #2 + #3): Load ConversationDetail once here to extract
-            // conversationId, then pass it downstream. Previously this record was loaded multiple
-            // times: once in loadConversationHistoryWithAttachments (just to get conversationId),
-            // once in AgentRunner (same reason), and once in createCompletionNotification. Now we
-            // load it a single time and thread conversationId through the call chain.
-            const currentDetail = await p.GetEntityObject('MJ: Conversation Details', currentUser);
-            if (!await currentDetail.Load(conversationDetailId)) {
-                throw new Error(`Conversation detail ${conversationDetailId} not found`);
-            }
-            const conversationId = currentDetail.ConversationID;
-            // The branch the placeholder row was created on decides which path the run reads.
-            const branchId = currentDetail.BranchID ?? null;
-            // A turn that follows a run the user STOPPED continues that run rather than starting
-            // over: chain it by LastRunID (the chat client never sends one) and, when the caller
-            // supplied no payload, roll the stopped run's FinalPayload into this run's start.
+            const turn = await this.startConversationTurn(p, currentUser, {
+                UserMessageId: userMessageId,
+                AgentId: effectiveAgentId,
+                MaxHistoryMessages: maxHistoryMessages || 20,
+                HistoryFrom: historyFrom,
+                ReplyParentId: replyParentId,
+                AnnouncedByAgentId: effectiveAnnouncedByAgentId,
+                ReplyBranchId: replyBranchId
+            });
+            const reply = turn.Reply;
+            // The turn's branch (the message's own branch, or a validated fork whose path holds the message)
+            // decides which path the run reads.
+            const branchId = turn.BranchId;
+            // A turn that follows a run the user STOPPED or a run paused on FinalStep === 'Chat'
+            // with an open sub-agent consult continues that run rather than starting over: chain it
+            // by LastRunID (the chat client never sends one) and, when the caller supplied no
+            // payload, roll the prior run's FinalPayload into this run's start.
             let effectiveLastRunId = lastRunId;
             let effectiveAutoPopulate = autoPopulateLastRunPayload;
             if (!effectiveLastRunId) {
-                const stoppedRunId = await this.findUserStoppedPredecessorRunId(conversationId, effectiveAgentId, branchId, currentUser, p);
-                if (stoppedRunId) {
-                    effectiveLastRunId = stoppedRunId;
+                const chainable = await this.findChainablePredecessor(turn.ConversationId, effectiveAgentId, branchId, currentUser, p);
+                if (chainable) {
+                    effectiveLastRunId = chainable.runId;
                     if (effectiveAutoPopulate === undefined && payload == null) {
                         effectiveAutoPopulate = true;
                     }
-                    LogStatus(`↩️ Continuing from user-stopped run ${stoppedRunId} (chained by LastRunID)`);
+                    if (chainable.reason === 'stopped') {
+                        LogStatus(`↩️ Continuing from user-stopped run ${chainable.runId} (chained by LastRunID)`);
+                    }
+                    else {
+                        LogStatus(`Resuming open sub-agent consult(s) from run ${chainable.runId} (chained by LastRunID)`);
+                    }
                 }
             }
-            // Load conversation history with attachments from DB
-            const messages = await this.loadConversationHistoryWithAttachments(conversationId, currentUser, maxHistoryMessages || 20, p, 
-            // The UI creates the agent-response placeholder row ('⏳ ...') before invoking
-            // this mutation — exclude it so the model never sees an empty assistant turn.
-            [conversationDetailId], historyFrom, branchId);
-            // Convert to JSON string for the existing executeAIAgent method
-            const messagesJson = JSON.stringify(messages);
             if (fireAndForget) {
                 // Fire-and-forget mode: start execution in background, return immediately.
                 // The client will receive the result via WebSocket PubSub completion event.
-                this.executeAgentInBackground(p, dataSource, effectiveAgentId, effectiveUserPayload, messagesJson, sessionId, pubSub, data, payload, effectiveLastRunId, effectiveAutoPopulate, configurationId, conversationDetailId, createArtifacts || false, createNotification || false, sourceArtifactId, sourceArtifactVersionId, conversationId, planMode, requestedSkillIDs, undefined, // taskGraphDebug
-                historyFrom, trustRunData, branchId);
+                this.executeAgentInBackground(p, dataSource, effectiveAgentId, effectiveUserPayload, turn.MessagesJson, sessionId, pubSub, data, payload, effectiveLastRunId, effectiveAutoPopulate, configurationId, reply.ID, createArtifacts || false, createNotification || false, sourceArtifactId, sourceArtifactVersionId, turn.ConversationId, planMode, requestedSkillIDs, undefined, // taskGraphDebug
+                historyFrom, trustRunData, branchId, reply);
                 LogStatus(`🔥 Fire-and-forget: Agent ${effectiveAgentId} execution started in background for session ${sessionId}`);
                 return {
                     success: true,
-                    result: JSON.stringify({ accepted: true, fireAndForget: true })
+                    result: JSON.stringify({
+                        accepted: true,
+                        fireAndForget: true,
+                        conversationDetailId: reply.ID,
+                        createdAt: reply.__mj_CreatedAt,
+                        ...(turn.Announcement ? { announcementDetailId: turn.Announcement.ID } : {})
+                    })
                 };
             }
             // Synchronous mode (default): wait for execution to complete
-            return this.executeAIAgent(p, dataSource, effectiveAgentId, effectiveUserPayload, messagesJson, sessionId, pubSub, data, payload, undefined, // templateData
-            effectiveLastRunId, effectiveAutoPopulate, configurationId, conversationDetailId, createArtifacts || false, createNotification || false, sourceArtifactId, sourceArtifactVersionId, conversationId, // LATENCY OPT #2: pass pre-resolved conversationId
+            return this.executeAIAgent(p, dataSource, effectiveAgentId, effectiveUserPayload, turn.MessagesJson, sessionId, pubSub, data, payload, undefined, // templateData
+            effectiveLastRunId, effectiveAutoPopulate, configurationId, reply.ID, createArtifacts || false, createNotification || false, sourceArtifactId, sourceArtifactVersionId, turn.ConversationId, // LATENCY OPT #2: pass pre-resolved conversationId
             undefined, // runRef
             planMode, requestedSkillIDs, undefined, // taskGraphDebug
-            historyFrom, trustRunData, branchId);
+            historyFrom, trustRunData, branchId, reply);
         }
         catch (error) {
             const errorMessage = error.message || 'Unknown error loading conversation history';
@@ -841,6 +996,110 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
             };
         }
     }
+    /**
+     * Everything a conversation turn needs before its agent runs: the user's message (read as the caller, so a
+     * message they can't see is "not found", and for an anonymous visitor also checked against the conversation's
+     * scope stamp), the conversation history, the optional announcement line, and the reply
+     * row, created last so the history never holds the empty reply. Every row is written as `user`, the person asking,
+     * and marked as server-authored by {@link AgentRunner.CreateAgentReplyDetail}.
+     */
+    async startConversationTurn(p, user, request) {
+        // LATENCY OPTIMIZATION (Opt #2 + #3): the user's message is loaded once here for its conversation and
+        // branch, which are threaded through the call chain rather than reloaded downstream.
+        const placement = await this.loadPlacementOf(p, user, request.UserMessageId);
+        const conversationId = placement.ConversationId;
+        // Loading the message as the caller is the whole ownership check for a named user. It is not for an
+        // anonymous visitor: every visitor is the one shared Anonymous user, so under a guest role whose row
+        // filters key on UserID another visitor's message loads fine (MJ#6032). The conversation's scope stamp
+        // decides instead, exactly as it does for the realtime gates — and before any row is written.
+        const access = await AuthorizeConversationTurn(conversationId, user, p);
+        if (!access.Allowed) {
+            LogError(`RunAIAgentFromConversationDetail: anonymous visitor ${user.AnonymousVisitorID ?? '(no visitor id)'} refused a turn in conversation ${conversationId} (${access.Reason})`);
+            throw new Error('Not authorized: you do not own this conversation');
+        }
+        const branchId = request.ReplyBranchId
+            ? await this.validateReplyBranch(p, user, conversationId, placement, request.ReplyBranchId)
+            : placement.BranchId;
+        const parentId = request.ReplyParentId
+            ? await this.validateReplyParent(p, user, request.ReplyParentId, conversationId)
+            : request.UserMessageId;
+        const messages = await this.loadConversationHistoryWithAttachments(conversationId, user, request.MaxHistoryMessages, p, undefined, request.HistoryFrom, branchId);
+        const runner = new AgentRunner(p);
+        const announcement = request.AnnouncedByAgentId
+            ? await this.postContinuationAnnouncement(runner, user, conversationId, branchId, parentId, request.AnnouncedByAgentId, request.AgentId)
+            : undefined;
+        const reply = await runner.CreateAgentReplyDetail({
+            conversationId,
+            branchId,
+            agentId: request.AgentId,
+            contextUser: user,
+            parentId: announcement?.ID ?? parentId,
+            provider: p
+        });
+        return { ConversationId: conversationId, BranchId: branchId, MessagesJson: JSON.stringify(messages), Reply: reply, Announcement: announcement };
+    }
+    /** The conversation, branch (null is Main) and sequence of a message, read as `user`; throws when they can't read it. */
+    async loadPlacementOf(p, user, messageId) {
+        const message = await p.GetEntityObject('MJ: Conversation Details', user);
+        if (!await message.Load(messageId)) {
+            throw new Error(`Conversation detail ${messageId} not found`);
+        }
+        return { ConversationId: message.ConversationID, BranchId: message.BranchID ?? null, Sequence: message.Sequence ?? -1 };
+    }
+    /**
+     * When a turn forks from an earlier message (such as Regenerate), the reply and history run on the fork while the
+     * user's message stays on the branch it was written on. Checks that `replyBranchId` is a branch of the turn's
+     * conversation whose path holds the user's message (`IsRowOnBranchPath` rather than exact `ForkFromSequence`
+     * equality is deliberate: `ConversationEngine.ForkPointFrom` sets `ForkFromSequence = message.Sequence` and the
+     * fork belongs to this conversation); returns `replyBranchId`, or throws before any row is created.
+     */
+    async validateReplyBranch(p, user, conversationId, userMessage, replyBranchId) {
+        if (UUIDsEqual(replyBranchId, userMessage.BranchId)) {
+            return replyBranchId;
+        }
+        if (userMessage.Sequence < 0) {
+            throw new Error(`Conversation detail is not on branch ${replyBranchId}'s path, so the reply cannot be written on that branch`);
+        }
+        const branches = await ConversationEngine.LoadBranchesFresh(conversationId, user, p);
+        const chain = ConversationEngine.BuildBranchChain(branches, replyBranchId);
+        if (!ConversationEngine.IsRowOnBranchPath({ BranchID: userMessage.BranchId, Sequence: userMessage.Sequence }, chain)) {
+            throw new Error(`Conversation detail is not on branch ${replyBranchId}'s path, so the reply cannot be written on that branch`);
+        }
+        return replyBranchId;
+    }
+    /**
+     * A reply's parent is part of what the reply says, so the server sets it, from a checked input: a message the
+     * caller can read, in the turn's own conversation. Returns its ID; throws otherwise.
+     */
+    async validateReplyParent(p, user, parentId, conversationId) {
+        const { ConversationId: parentConversationId } = await this.loadPlacementOf(p, user, parentId);
+        if (!UUIDsEqual(parentConversationId, conversationId)) {
+            throw new Error(`Conversation detail ${parentId} is not in this turn's conversation, so the reply cannot thread under it`);
+        }
+        return parentId;
+    }
+    /**
+     * Posts the announcing agent's line, "Continuing with **{agent}** for refinement...", as a completed reply of the
+     * announcing agent. Its text is fixed and names the agent from metadata, so a caller chooses only whether it is
+     * posted and by which active agent, never what it says.
+     */
+    async postContinuationAnnouncement(runner, user, conversationId, branchId, parentId, announcerId, agentId) {
+        await AIEngine.Instance.Config(false, user);
+        const announcer = AIEngine.Instance.GetAgentByID(announcerId);
+        if (!announcer || announcer.Status !== 'Active') {
+            throw new Error(`Agent ${announcerId} cannot announce the turn: it is not an active agent`);
+        }
+        const agentName = AIEngine.Instance.GetAgentByID(agentId)?.Name ?? 'the agent';
+        return runner.CreateAgentReplyDetail({
+            conversationId,
+            branchId,
+            agentId: announcer.ID,
+            contextUser: user,
+            parentId,
+            message: ContinuationAnnouncementText(agentName),
+            status: 'Complete'
+        });
+    }
     /**
      * Respond to a pending AIAgentRequest from the dashboard or API.
      * Updates the request record with the response and optionally spawns a
@@ -985,9 +1244,8 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
     }
     /**
      * Execute agent in background (fire-and-forget).
-     * Handles errors by publishing error completion events via PubSub,
-     * so the client receives them via WebSocket even though the HTTP response
-     * has already been sent.
+     * The client learns the outcome only from the run's completion status message (executeAIAgent publishes it,
+     * failure included), since the HTTP response has already been sent. A liveness pulse runs until the run ends.
      */
     executeAgentInBackground(p, dataSource, agentId, userPayload, messagesJson, sessionId, pubSub, data, payload, lastRunId, autoPopulateLastRunPayload, configurationId, conversationDetailId, createArtifacts = false, createNotification = false, sourceArtifactId, sourceArtifactVersionId, 
     /** LATENCY OPT #2: Pre-resolved conversationId avoids redundant DB load in AgentRunner */
@@ -1001,27 +1259,26 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
     /** ExecuteAgentParams.TrustReservedRunData — see executeAIAgent. */
     trustReservedRunData = false, 
     /** The conversation branch of the run — threaded through to ExecuteAgentParams.ConversationBranchID. */
-    conversationBranchId) {
+    conversationBranchId, 
+    /** The reply row this request created for the run — see executeAIAgent. */
+    replyDetail) {
         // Ref the liveness pulse reads to enrich heartbeats once the run is created.
         const runRef = { current: null };
         const pulse = StartLivenessPulse({
             pubSub,
             sessionId,
-            ownerUserId: userPayload.userRecord.ID,
+            ownerUserId: StatusUpdateOwnerID(userPayload),
             resolver: 'RunAIAgentResolver',
             readStatus: () => runRef.current
                 ? { runId: runRef.current.ID, status: runRef.current.Status }
                 : undefined,
         });
-        // Execute in background - errors are handled within, not propagated
-        this.executeAIAgent(p, dataSource, agentId, userPayload, messagesJson, sessionId, pubSub, data, payload, undefined, lastRunId, autoPopulateLastRunPayload, configurationId, conversationDetailId, createArtifacts, createNotification, sourceArtifactId, sourceArtifactVersionId, conversationId, runRef, planMode, requestedSkillIDs, taskGraphDebug, conversationHistoryFrom, trustReservedRunData, conversationBranchId).catch((error) => {
-            // Background execution failed unexpectedly (executeAIAgent has its own try-catch,
-            // so this would only fire for truly unexpected errors).
-            const errorMessage = (error instanceof Error) ? error.message : 'Unknown background execution error';
-            LogError(`🔥 Fire-and-forget background execution failed: ${errorMessage}`, undefined, error);
-            // Publish error completion event so the client knows the agent failed.
-            // The publisher is created inside executeAIAgent, which rejected before returning one.
-            new AgentRunStatusPublisher(pubSub, userPayload, sessionId).PublishFailure(conversationDetailId, errorMessage);
+        // executeAIAgent resolves on every failure and publishes the run's completion itself (PublishFinal, or
+        // PublishFailure from its catch), so nothing here publishes one.
+        this.executeAIAgent(p, dataSource, agentId, userPayload, messagesJson, sessionId, pubSub, data, payload, undefined, lastRunId, autoPopulateLastRunPayload, configurationId, conversationDetailId, createArtifacts, createNotification, sourceArtifactId, sourceArtifactVersionId, conversationId, runRef, planMode, requestedSkillIDs, taskGraphDebug, conversationHistoryFrom, trustReservedRunData, conversationBranchId, replyDetail).catch((error) => {
+            // Only a broken executeAIAgent contract lands here. Logged rather than left as an unhandled rejection;
+            // no completion is published, because executeAIAgent may already have sent one.
+            LogError(`🔥 Fire-and-forget run of agent ${agentId} for session ${sessionId} rejected, which executeAIAgent never should`, undefined, error);
         }).finally(() => pulse.Stop());
     }
     /**
@@ -1048,7 +1305,9 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
     /** History floor: only rows written at or after it are loaded, and no summary is used. */
     historyFrom, 
     /** The branch whose path to load; null reads the trunk. */
-    branchId) {
+    branchId, 
+    /** Speaker attribution mode forwarded to `ConversationEngine.AssembleContextWindow`. */
+    speakerAttribution) {
         // Context windowing (summary boundary + raw tail, or legacy last-N when no
         // summary exists) shares ONE fold implementation with all other callers —
         // ConversationEngine.AssembleContextWindow — and the ROWS come from the
@@ -1068,7 +1327,8 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
         const window = ConversationEngine.AssembleContextWindow(rows, {
             maxTailMessages: maxMessages,
             excludeDetailIds,
-            historyFrom
+            historyFrom,
+            speakerAttribution
         });
         // Batch load input artifacts for the windowed messages. Since the backfill migration
         // (V202605271400__Backfill_Attachment_Artifacts) converted all legacy
@@ -1318,7 +1578,7 @@ __decorate([
 ], RunAIAgentResolver.prototype, "RunAIAgentSystemUser", null);
 __decorate([
     Mutation(() => AIAgentRunResult),
-    __param(0, Arg('conversationDetailId')),
+    __param(0, Arg('userMessageId')),
     __param(1, Arg('agentId')),
     __param(2, Ctx()),
     __param(3, Arg('sessionId')),
@@ -1337,8 +1597,11 @@ __decorate([
     __param(16, Arg('planMode', { nullable: true })),
     __param(17, Arg('requestedSkillIDs', () => [String], { nullable: true })),
     __param(18, Arg('agentHistoryFrom', { nullable: true })),
+    __param(19, Arg('replyParentId', { nullable: true })),
+    __param(20, Arg('announcedByAgentId', { nullable: true })),
+    __param(21, Arg('replyBranchId', { nullable: true })),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, String, Object, String, PubSubEngine, Number, String, String, String, Boolean, String, Boolean, Boolean, String, String, Boolean, Boolean, Array, String]),
+    __metadata("design:paramtypes", [String, String, Object, String, PubSubEngine, Number, String, String, String, Boolean, String, Boolean, Boolean, String, String, Boolean, Boolean, Array, String, String, String, String]),
     __metadata("design:returntype", Promise)
 ], RunAIAgentResolver.prototype, "RunAIAgentFromConversationDetail", null);
 __decorate([