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

package/dist/resolvers/RunAIAgentResolver.js

@@ -15,14 +15,18 @@ 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 { 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 { GetAttachmentService } from '@memberjunction/aiengine';
 import { NotificationEngine } from '@memberjunction/notifications';
@@ -211,7 +215,7 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
      * 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,
@@ -226,8 +230,9 @@ let RunAIAgentResolver = 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
@@ -280,6 +285,13 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
         if (agentEntity.Status !== 'Active') {
             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;
     }
     /**
@@ -303,8 +315,13 @@ let RunAIAgentResolver = 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, 
+    /** 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) {
         const startTime = Date.now();
         // Best-effort handle for persistInFlightAgentFailure. Populated from a
         // progress event carrying metadata.agentRun, or from the successful
@@ -312,6 +329,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
@@ -336,9 +355,8 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
             // singleton's transaction state with concurrent requests (e.g. conversation deletes).
             const agentRunner = new AgentRunner(p);
             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.
             const conversationResult = await agentRunner.RunAgentInConversation({
@@ -364,15 +382,20 @@ let RunAIAgentResolver = 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;
             // Use agent response detail ID if available, otherwise fall back to user message detail ID
@@ -412,7 +435,7 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
                 await Promise.all(postExecutionOps);
             }
             // 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
             statusPublisher.PublishFinal(result, result.agentRun?.ConversationDetailID, returnResult);
@@ -433,10 +456,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,
@@ -454,7 +484,9 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
      * 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();
@@ -470,7 +502,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';
@@ -495,10 +528,13 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
         // Check API key scope authorization for agent execution
         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.
             // The client will receive the result via WebSocket PubSub completion event.
-            this.executeAgentInBackground(p, dataSource, agentId, userPayload, messagesJson, sessionId, pubSub, data, payload, lastRunId, autoPopulateLastRunPayload, configurationId, conversationDetailId, createArtifacts || false, createNotification || false, sourceArtifactId, sourceArtifactVersionId, undefined /*conversationId*/, planMode, requestedSkillIDs, taskGraphDebug);
+            this.executeAgentInBackground(p, dataSource, agentId, userPayload, messagesJson, sessionId, pubSub, data, payload, lastRunId, autoPopulateLastRunPayload, configurationId, conversationDetailId, createArtifacts || false, createNotification || false, sourceArtifactId, sourceArtifactVersionId, undefined /*conversationId*/, planMode, requestedSkillIDs, taskGraphDebug, undefined /*conversationHistoryFrom*/, trustRunData);
             LogStatus(`🔥 Fire-and-forget: Agent ${agentId} execution started in background for session ${sessionId}`);
             return {
                 success: true,
@@ -508,7 +544,8 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
         // Synchronous mode (default): wait for execution to complete
         return this.executeAIAgent(p, dataSource, agentId, userPayload, messagesJson, sessionId, pubSub, data, payload, templateData, lastRunId, autoPopulateLastRunPayload, configurationId, conversationDetailId, createArtifacts || false, createNotification || false, sourceArtifactId, sourceArtifactVersionId, undefined, // conversationId (not pre-resolved on this path)
         undefined, // runRef
-        planMode, requestedSkillIDs, taskGraphDebug);
+        planMode, requestedSkillIDs, taskGraphDebug, undefined, // conversationHistoryFrom
+        trustRunData);
     }
     /**
      * System user query for running AI agents with elevated privileges.
@@ -516,9 +553,14 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
      */
     async RunAIAgentSystemUser(agentId, { userPayload, providers, dataSource }, messagesJson, sessionId, pubSub, data, payload, templateData, lastRunId, autoPopulateLastRunPayload, configurationId, conversationDetailId, createArtifacts, createNotification, sourceArtifactId, sourceArtifactVersionId, planMode, requestedSkillIDs) {
         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, agentId, userPayload, messagesJson, sessionId, pubSub, data, payload, templateData, lastRunId, autoPopulateLastRunPayload, configurationId, conversationDetailId, createArtifacts || false, createNotification || false, sourceArtifactId, sourceArtifactVersionId, undefined, // conversationId (not pre-resolved on this path)
         undefined, // runRef
-        planMode, requestedSkillIDs);
+        planMode, requestedSkillIDs, undefined, // taskGraphDebug
+        undefined, // conversationHistoryFrom
+        trustRunData);
     }
     /**
      * Create a user notification for agent completion with artifact
@@ -720,16 +762,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.
+     *
+     * 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 conversationDetailId - The conversation detail ID (user's message already saved)
+     * @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) {
@@ -744,33 +795,50 @@ 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
+        // 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('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;
+            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
             // supplied no payload, roll the stopped 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);
+                const stoppedRunId = await this.findUserStoppedPredecessorRunId(turn.ConversationId, effectiveAgentId, branchId, currentUser, p);
                 if (stoppedRunId) {
                     effectiveLastRunId = stoppedRunId;
                     if (effectiveAutoPopulate === undefined && payload == null) {
@@ -779,30 +847,29 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
                     LogStatus(`↩️ Continuing from user-stopped run ${stoppedRunId} (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, 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, branchId);
+            historyFrom, trustRunData, branchId, reply);
         }
         catch (error) {
             const errorMessage = error.message || 'Unknown error loading conversation history';
@@ -814,6 +881,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
@@ -958,9 +1129,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 */
@@ -971,28 +1141,29 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
     requestedSkillIDs, taskGraphDebug, 
     /** History floor — threaded through to ExecuteAgentParams.ConversationHistoryFrom. */
     conversationHistoryFrom, 
+    /** 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, 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());
     }
     /**
@@ -1289,7 +1460,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')),
@@ -1308,8 +1479,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([