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

package/dist/resolvers/RunAIAgentResolver.d.ts

@@ -143,20 +143,69 @@ export declare class RunAIAgentResolver extends ResolverBase {
      */
     private sendFeedbackRequestNotification;
     /**
-     * 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)
      */
-    RunAIAgentFromConversationDetail(conversationDetailId: string, agentId: string, { userPayload, providers, dataSource }: AppContext, sessionId: string, pubSub: PubSubEngine, maxHistoryMessages?: number, data?: string, payload?: string, lastRunId?: string, autoPopulateLastRunPayload?: boolean, configurationId?: string, createArtifacts?: boolean, createNotification?: boolean, sourceArtifactId?: string, sourceArtifactVersionId?: string, fireAndForget?: boolean, planMode?: boolean, requestedSkillIDs?: string[], 
+    RunAIAgentFromConversationDetail(userMessageId: string, agentId: string, { userPayload, providers, dataSource }: AppContext, sessionId: string, pubSub: PubSubEngine, maxHistoryMessages?: number, data?: string, payload?: string, lastRunId?: string, autoPopulateLastRunPayload?: boolean, configurationId?: string, createArtifacts?: boolean, createNotification?: boolean, sourceArtifactId?: string, sourceArtifactVersionId?: string, fireAndForget?: boolean, planMode?: boolean, requestedSkillIDs?: string[], 
     /** History floor: an ISO-8601 timestamp, the first moment of the conversation this run may
      *  read. The history is loaded from there and no summary of earlier messages is used, and the
      *  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. */
-    agentHistoryFrom?: string): Promise<AIAgentRunResult>;
+    agentHistoryFrom?: string, 
+    /** The message the reply threads under, when not the user's message: one in the same conversation the
+     *  caller can read. */
+    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. */
+    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`. */
+    replyBranchId?: string): Promise<AIAgentRunResult>;
+    /**
+     * 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 startConversationTurn;
+    /** The conversation, branch (null is Main) and sequence of a message, read as `user`; throws when they can't read it. */
+    private loadPlacementOf;
+    /**
+     * 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 validateReplyBranch;
+    /**
+     * 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 validateReplyParent;
+    /**
+     * 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 postContinuationAnnouncement;
     /**
      * Respond to a pending AIAgentRequest from the dashboard or API.
      * Updates the request record with the response and optionally spawns a
@@ -170,9 +219,8 @@ export declare class RunAIAgentResolver extends ResolverBase {
     ReassignAgentRequest(requestId: string, newUserID: string, { userPayload, providers }: AppContext, note?: string): Promise<AIAgentRunResult>;
     /**
      * 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;
     /**

package/dist/resolvers/RunAIAgentResolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RunAIAgentResolver.d.ts","sourceRoot":"","sources":["../../src/resolvers/RunAIAgentResolver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"RunAIAgentResolver.d.ts","sourceRoot":"","sources":["../../src/resolvers/RunAIAgentResolver.ts"],"names":[],"mappings":"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"}

package/dist/resolvers/RunAIAgentResolver.js

@@ -15,14 +15,17 @@ 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';
@@ -212,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,
@@ -227,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
@@ -314,7 +318,10 @@ 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) {
         const startTime = Date.now();
         // Best-effort handle for persistInFlightAgentFailure. Populated from a
         // progress event carrying metadata.agentRun, or from the successful
@@ -322,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
@@ -346,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({
@@ -381,10 +389,13 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
                 }
             }, {
                 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
@@ -424,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);
@@ -445,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,
@@ -466,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();
@@ -482,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';
@@ -741,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.
      *
-     * @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 +795,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
@@ -779,25 +819,26 @@ let RunAIAgentResolver = class RunAIAgentResolver extends ResolverBase {
         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) {
@@ -806,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, 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 +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
@@ -985,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 */
@@ -1001,27 +1144,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());
     }
     /**
@@ -1318,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')),
@@ -1337,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([