@memberjunction/server 6.2.0-edge.4 → 6.2.0-edge.6

package/src/resolvers/RunAIAgentResolver.ts

@@ -1,18 +1,22 @@
 import { Resolver, Mutation, Query, Arg, Ctx, ObjectType, Field, PubSub, PubSubEngine, Subscription, Root, ResolverFilterData, ID, Int } from 'type-graphql';
 import { AppContext, UserPayload } from '../types.js';
 import { DatabaseProviderBase, LogError, LogStatus, Metadata, RunView, UserInfo, IMetadataProvider } from '@memberjunction/core';
-import { MJConversationDetailEntity, MJConversationDetailAttachmentEntity, MJConversationDetailArtifactEntity, MJArtifactVersionEntity, MJAIAgentRequestEntity, ArtifactMetadataEngine, ConversationEngine } from '@memberjunction/core-entities';
+import { MJConversationDetailEntity, MJConversationDetailEntityExtended, MJConversationDetailAttachmentEntity, MJConversationDetailArtifactEntity, MJArtifactVersionEntity, MJAIAgentRequestEntity, ArtifactMetadataEngine, ConversationEngine } from '@memberjunction/core-entities';
 import { RouteArtifact } from './artifact-routing.js';
 import { AgentRunner, ArtifactToolManager } from '@memberjunction/ai-agents';
-import { MJAIAgentEntityExtended, MJAIAgentRunEntityExtended, ExecuteAgentResult, ConversationUtility, AttachmentData } from '@memberjunction/ai-core-plus';
+import { MJAIAgentEntityExtended, MJAIAgentRunEntityExtended, ExecuteAgentResult, ConversationUtility, AttachmentData, ContinuationAnnouncementText } from '@memberjunction/ai-core-plus';
 import { AIEngine } from '@memberjunction/aiengine';
 import { ChatMessage, ChatMessageContent } from '@memberjunction/ai';
 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 { GetAttachmentService } from '@memberjunction/aiengine';
 import { NotificationEngine } from '@memberjunction/notifications';
@@ -31,6 +35,17 @@ function isAgentRunEntity(value: unknown): value is MJAIAgentRunEntityExtended {
     return typeof value === 'object' && value !== null && 'ID' in value;
 }
 
+/** What a conversation turn asks for, before its agent runs (see `RunAIAgentFromConversationDetail`). */
+interface ConversationTurnRequest {
+    UserMessageId: string;
+    AgentId: string;
+    MaxHistoryMessages: number;
+    HistoryFrom?: Date;
+    ReplyParentId?: string;
+    AnnouncedByAgentId?: string;
+    ReplyBranchId?: string | null;
+}
+
 @ObjectType()
 export class AIAgentRunResult {
     @Field()
@@ -172,7 +187,7 @@ export class RunAIAgentResolver extends ResolverBase {
      * Sanitize ExecuteAgentResult for JSON serialization
      * Removes circular references and non-serializable objects
      */
-    private sanitizeAgentResult(result: ExecuteAgentResult): any {
+    private sanitizeAgentResult(result: ExecuteAgentResult, recipient?: UserInfo): any {
         const sanitized: any = {
             success: result.success,
             payload: result.payload,
@@ -188,8 +203,9 @@ export class RunAIAgentResolver extends ResolverBase {
 
         // 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
@@ -252,6 +268,14 @@ export class RunAIAgentResolver extends ResolverBase {
             throw new Error(`AI Agent "${agentEntity.Name}" is not active (Status: ${agentEntity.Status})`);
         }
 
+        // Enforce agent run permissions for the calling user
+        if (currentUser && typeof AIEngine.Instance.CanUserRunAgent === 'function') {
+            const canRun = await AIEngine.Instance.CanUserRunAgent(agentEntity.ID, currentUser);
+            if (!canRun) {
+                throw new Error(`User does not have permission to run AI Agent "${agentEntity.Name}" (${agentEntity.ID})`);
+            }
+        }
+
         return agentEntity;
     }
 
@@ -294,8 +318,13 @@ export class RunAIAgentResolver extends ResolverBase {
         /** History floor for a conversation run — threaded into ExecuteAgentParams.ConversationHistoryFrom,
          *  so the framework's own conversation reads (retrieval tools, artifacts, compaction) honour it too. */
         conversationHistoryFrom?: Date,
+        /** ExecuteAgentParams.TrustReservedRunData: true only for a caller IsTrustedAgentRunCaller accepts. */
+        trustReservedRunData: boolean = false,
         /** The conversation branch of the run — threaded into ExecuteAgentParams.ConversationBranchID. */
-        conversationBranchId?: string | null
+        conversationBranchId?: string | null,
+        /** 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?: MJConversationDetailEntityExtended
     ): Promise<AIAgentRunResult> {
         const startTime = Date.now();
         // Best-effort handle for persistInFlightAgentFailure. Populated from a
@@ -304,6 +333,8 @@ export 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 as MJAIAgentRunEntityExtended | 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} ===`);
@@ -337,9 +368,8 @@ export 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);
+            // The resolver still copies the run into agentRunRef, including noise steps, for the
+            // fire-and-forget liveness pulse.
             const publishProgress = statusPublisher.OnProgress;
 
             // Execute the agent in conversation context - handles conversation, artifacts, etc.
@@ -366,15 +396,20 @@ export class RunAIAgentResolver extends ResolverBase {
                 ConversationHistoryFrom: conversationHistoryFrom,
                 ...(conversationBranchId ? { ConversationBranchID: conversationBranchId } : {}),
                 data: parsedData,
+                // Whether the run may read the reserved data keys (scope, agent-type params); BaseAgent drops them otherwise.
+                TrustReservedRunData: trustReservedRunData,
                 context: {
                     dataSource: dataSource
                 }
             }, {
                 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;
@@ -437,7 +472,7 @@ export class RunAIAgentResolver extends ResolverBase {
             }
 
             // Create sanitized payload for JSON serialization
-            const sanitizedResult = this.sanitizeAgentResult(result);
+            const sanitizedResult = this.sanitizeAgentResult(result, currentUser);
             const returnResult = JSON.stringify(sanitizedResult);
 
             // Publish final events with enriched result data for fire-and-forget clients
@@ -460,11 +495,18 @@ export class RunAIAgentResolver extends ResolverBase {
         } catch (error) {
             const executionTime = Date.now() - startTime;
             LogError(`AI Agent run failed:`, undefined, error);
-            const errorMessage = (error as 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,
@@ -490,7 +532,9 @@ export class RunAIAgentResolver extends ResolverBase {
         userPayload: UserPayload,
         run: MJAIAgentRunEntityExtended | null | undefined,
         conversationDetailId: string | undefined,
-        errorMessage: string
+        errorMessage: string,
+        /** The run's reply row, when this request created it: written in place, as the server. */
+        replyDetail?: MJConversationDetailEntityExtended
     ): Promise<void> {
         try {
             if (run && run.Status === 'Running') {
@@ -507,10 +551,11 @@ export class RunAIAgentResolver extends ResolverBase {
                 return;
             }
             if (conversationDetailId) {
-                const detail = await provider.GetEntityObject<MJConversationDetailEntity>(
+                const detail = replyDetail ?? await provider.GetEntityObject<MJConversationDetailEntity>(
                     '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';
@@ -564,6 +609,9 @@ export class RunAIAgentResolver extends ResolverBase {
         await this.CheckAPIKeyScopeAuthorization('agent:execute', agentId, userPayload);
 
         const p = GetReadWriteProvider(providers);
+        // 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 (fireAndForget) {
             // Fire-and-forget mode: start execution in background, return immediately.
@@ -572,7 +620,8 @@ export class RunAIAgentResolver extends ResolverBase {
                 p, dataSource, agentId, userPayload, messagesJson, sessionId, pubSub,
                 data, payload, lastRunId, autoPopulateLastRunPayload, configurationId,
                 conversationDetailId, createArtifacts || false, createNotification || false,
-                sourceArtifactId, sourceArtifactVersionId, undefined /*conversationId*/, planMode, requestedSkillIDs, taskGraphDebug
+                sourceArtifactId, sourceArtifactVersionId, undefined /*conversationId*/, planMode, requestedSkillIDs, taskGraphDebug,
+                undefined /*conversationHistoryFrom*/, trustRunData
             );
 
             LogStatus(`🔥 Fire-and-forget: Agent ${agentId} execution started in background for session ${sessionId}`);
@@ -607,7 +656,9 @@ export class RunAIAgentResolver extends ResolverBase {
             undefined, // runRef
             planMode,
             requestedSkillIDs,
-            taskGraphDebug
+            taskGraphDebug,
+            undefined, // conversationHistoryFrom
+            trustRunData
         );
     }
 
@@ -640,6 +691,9 @@ export class RunAIAgentResolver extends ResolverBase {
         @Arg('requestedSkillIDs', () => [String], { nullable: true }) requestedSkillIDs?: string[]
     ): Promise<AIAgentRunResult> {
         const p = GetReadWriteProvider(providers);
+        // @RequireSystemUser admits only the system user, whom the rule trusts; it is still asked, so every
+        // resolver entry that takes a client's data decides the same way.
+        const trustRunData = await IsTrustedAgentRunCaller({ UserPayload: userPayload, IsWidgetGuestRun: false, AgentID: agentId });
         return this.executeAIAgent(
             p,
             dataSource,
@@ -662,7 +716,10 @@ export class RunAIAgentResolver extends ResolverBase {
             undefined, // conversationId (not pre-resolved on this path)
             undefined, // runRef
             planMode,
-            requestedSkillIDs
+            requestedSkillIDs,
+            undefined, // taskGraphDebug
+            undefined, // conversationHistoryFrom
+            trustRunData
         );
     }
 
@@ -900,16 +957,27 @@ export 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.
+     *
+     * 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.
      *
-     * @param conversationDetailId - The conversation detail ID (user's message already saved)
+     * 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)
      */
     @Mutation(() => AIAgentRunResult)
     async RunAIAgentFromConversationDetail(
-        @Arg('conversationDetailId') conversationDetailId: string,
+        @Arg('userMessageId') userMessageId: string,
         @Arg('agentId') agentId: string,
         @Ctx() { userPayload, providers, dataSource }: AppContext,
         @Arg('sessionId') sessionId: string,
@@ -932,11 +1000,17 @@ export class RunAIAgentResolver extends ResolverBase {
          *  run's own conversation reads honour it too. Omitted (clients send it only when set, so an
          *  older client never does), the run reads the whole conversation as before. An unreadable
          *  value fails the request rather than being dropped. */
-        @Arg('agentHistoryFrom', { nullable: true }) agentHistoryFrom?: string
+        @Arg('agentHistoryFrom', { nullable: true }) agentHistoryFrom?: string,
+        /** The message the reply threads under, when not the user's message: one in the same conversation the
+         *  caller can read. */
+        @Arg('replyParentId', { nullable: true }) replyParentId?: string,
+        /** An active agent (MJ's chat passes its conversation manager) whose fixed line "Continuing with
+         *  **{agent}** for refinement..." the server posts before the reply, which then threads under it. */
+        @Arg('announcedByAgentId', { nullable: true }) announcedByAgentId?: string,
+        /** The fork the reply and history run on, when the turn forks from `userMessageId` (such as Regenerate).
+         *  Checked to be a branch of the conversation whose path holds `userMessageId`. */
+        @Arg('replyBranchId', { nullable: true }) replyBranchId?: string
     ): Promise<AIAgentRunResult> {
-        // Check API key scope authorization for agent execution
-        await this.CheckAPIKeyScopeAuthorization('agent:execute', agentId, userPayload);
-
         const p = GetReadWriteProvider(providers);
         const currentUser = this.GetUserFromPayload(userPayload);
 
@@ -953,31 +1027,44 @@ export 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
+        // guest runs under an elevated server principal but is never trusted.
+        const trustRunData = await IsTrustedAgentRunCaller({
+            UserPayload: userPayload, IsWidgetGuestRun: widgetElevation !== null, AgentID: agentId,
+        });
 
         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<MJConversationDetailEntity>(
-                '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: string | null = currentDetail.BranchID ?? null;
+            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 continues that run rather than starting
             // over: chain it by LastRunID (the chat client never sends one) and, when the caller
@@ -985,7 +1072,7 @@ export class RunAIAgentResolver extends ResolverBase {
             let effectiveLastRunId = lastRunId;
             let effectiveAutoPopulate = autoPopulateLastRunPayload;
             if (!effectiveLastRunId) {
-                const stoppedRunId = await this.findUserStoppedPredecessorRunId(conversationId, effectiveAgentId, branchId, currentUser, p);
+                const stoppedRunId = await this.findUserStoppedPredecessorRunId(turn.ConversationId, effectiveAgentId, branchId, currentUser, p);
                 if (stoppedRunId) {
                     effectiveLastRunId = stoppedRunId;
                     if (effectiveAutoPopulate === undefined && payload == null) {
@@ -995,40 +1082,32 @@ export class RunAIAgentResolver extends ResolverBase {
                 }
             }
 
-            // 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,
+                    p, dataSource, effectiveAgentId, effectiveUserPayload, turn.MessagesJson, sessionId, pubSub,
                     data, payload, effectiveLastRunId, effectiveAutoPopulate, configurationId,
-                    conversationDetailId, createArtifacts || false, createNotification || false,
-                    sourceArtifactId, sourceArtifactVersionId, conversationId, planMode, requestedSkillIDs,
+                    reply.ID, createArtifacts || false, createNotification || false,
+                    sourceArtifactId, sourceArtifactVersionId, turn.ConversationId, planMode, requestedSkillIDs,
                     undefined, // taskGraphDebug
                     historyFrom,
-                    branchId
+                    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 } : {})
+                    })
                 };
             }
 
@@ -1038,7 +1117,7 @@ export class RunAIAgentResolver extends ResolverBase {
                 dataSource,
                 effectiveAgentId,
                 effectiveUserPayload,
-                messagesJson,
+                turn.MessagesJson,
                 sessionId,
                 pubSub,
                 data,
@@ -1047,18 +1126,20 @@ export class RunAIAgentResolver extends ResolverBase {
                 effectiveLastRunId,
                 effectiveAutoPopulate,
                 configurationId,
-                conversationDetailId,
+                reply.ID,
                 createArtifacts || false,
                 createNotification || false,
                 sourceArtifactId,
                 sourceArtifactVersionId,
-                conversationId, // LATENCY OPT #2: pass pre-resolved conversationId
+                turn.ConversationId, // LATENCY OPT #2: pass pre-resolved conversationId
                 undefined, // runRef
                 planMode,
                 requestedSkillIDs,
                 undefined, // taskGraphDebug
                 historyFrom,
-                branchId
+                trustRunData,
+                branchId,
+                reply
             );
         } catch (error) {
             const errorMessage = (error as Error).message || 'Unknown error loading conversation history';
@@ -1071,6 +1152,137 @@ export 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}.
+     */
+    private async startConversationTurn(
+        p: DatabaseProviderBase,
+        user: UserInfo,
+        request: ConversationTurnRequest
+    ): Promise<{ ConversationId: string; BranchId: string | null; MessagesJson: string; Reply: MJConversationDetailEntityExtended; Announcement?: MJConversationDetailEntityExtended }> {
+        // 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. */
+    private async loadPlacementOf(
+        p: DatabaseProviderBase,
+        user: UserInfo,
+        messageId: string
+    ): Promise<{ ConversationId: string; BranchId: string | null; Sequence: number }> {
+        const message = await p.GetEntityObject<MJConversationDetailEntity>('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.
+     */
+    private async validateReplyBranch(
+        p: DatabaseProviderBase,
+        user: UserInfo,
+        conversationId: string,
+        userMessage: { BranchId: string | null; Sequence: number },
+        replyBranchId: string
+    ): Promise<string> {
+        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.
+     */
+    private async validateReplyParent(p: DatabaseProviderBase, user: UserInfo, parentId: string, conversationId: string): Promise<string> {
+        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.
+     */
+    private async postContinuationAnnouncement(
+        runner: AgentRunner,
+        user: UserInfo,
+        conversationId: string,
+        branchId: string | null,
+        parentId: string,
+        announcerId: string,
+        agentId: string
+    ): Promise<MJConversationDetailEntityExtended> {
+        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
@@ -1250,9 +1462,8 @@ export 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.
      */
     private executeAgentInBackground(
         p: DatabaseProviderBase,
@@ -1281,37 +1492,37 @@ export class RunAIAgentResolver extends ResolverBase {
         taskGraphDebug?: string,
         /** History floor — threaded through to ExecuteAgentParams.ConversationHistoryFrom. */
         conversationHistoryFrom?: Date,
+        /** ExecuteAgentParams.TrustReservedRunData — see executeAIAgent. */
+        trustReservedRunData: boolean = false,
         /** The conversation branch of the run — threaded through to ExecuteAgentParams.ConversationBranchID. */
-        conversationBranchId?: string | null
+        conversationBranchId?: string | null,
+        /** The reply row this request created for the run — see executeAIAgent. */
+        replyDetail?: MJConversationDetailEntityExtended
     ): void {
         // Ref the liveness pulse reads to enrich heartbeats once the run is created.
         const runRef: { current: MJAIAgentRunEntityExtended | null } = { 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
+        // 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, conversationBranchId
+            conversationHistoryFrom, trustReservedRunData, conversationBranchId, replyDetail
         ).catch((error: unknown) => {
-            // 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);
+            // 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());
     }