@memberjunction/server 6.2.0-edge.1 → 6.2.0-edge.3

package/src/resolvers/RealtimeClientSessionResolver.ts

@@ -26,7 +26,7 @@
  */
 import { Resolver, Mutation, Arg, Ctx, Int, Float, ObjectType, Field, PubSub, PubSubEngine } from 'type-graphql';
 import { AppContext, UserPayload } from '../types.js';
-import { AuthorizationEvaluator, UserInfo, IMetadataProvider, LogError, LogStatus, RunView } from '@memberjunction/core';
+import { AuthorizationEvaluator, UserInfo, IMetadataProvider, LogError, LogStatus, RunView, BaseEntity } from '@memberjunction/core';
 import { UUIDsEqual, IsValidUUID } from '@memberjunction/global';
 import {
     MJAIAgentEntity,
@@ -48,6 +48,8 @@ import {
     FindIgnoredRealtimeConfigKeys,
     ParseRealtimeTypeConfiguration,
     ResolveEffectiveRealtimeConfig,
+    ResolveRealtimeCoAgentID,
+    FilterAllowedAgentsByCanRun,
     RealtimeAllowedAgent,
     RealtimeDirectActionsConfig,
     REALTIME_ADVANCED_SESSION_CONTROLS_AUTHORIZATION,
@@ -56,7 +58,7 @@ import {
     writeRealtimeRecordingSegment,
     deleteRealtimeRecordingSegments,
 } from '@memberjunction/ai-agents';
-import { AgentExecutionProgressCallback, MJAIAgentEntityExtended, AppContextSnapshot } from '@memberjunction/ai-core-plus';
+import { AgentExecutionProgressCallback, AppContextSnapshot } from '@memberjunction/ai-core-plus';
 import { ChatMessage, RealtimeToolDefinition } from '@memberjunction/ai';
 import { ResolverBase } from '../generic/ResolverBase.js';
 import { PUSH_STATUS_UPDATES_TOPIC } from '../generic/PushStatusResolver.js';
@@ -71,32 +73,6 @@ import { ResolveWidgetGuestRunContext, ResolveScopedAnonymousRunUser } from '../
  */
 const SIGNIFICANT_PROGRESS_STEPS = ['prompt_execution', 'action_execution', 'subagent_execution', 'decision_processing'];
 
-/**
- * The seeded name of the internal orchestration agent that fronts a target agent in realtime
- * sessions (voice + interactive channels). This is the GLOBAL DEFAULT co-agent — the final step of
- * the co-agent resolution chain (see {@link RealtimeClientSessionResolver.resolveCoAgentID}).
- * Deployments can override it per agent (`AIAgent.DefaultCoAgentID`), per agent type (an
- * `AIAgentCoAgent` row with `TargetAgentTypeID` + `IsDefault`), or per call (the `coAgentId`
- * mutation argument) without
- * touching this seed.
- */
-const REALTIME_CO_AGENT_NAME = 'Realtime Co-Agent';
-
-/**
- * DEPRECATED legacy seed name of {@link REALTIME_CO_AGENT_NAME}, from before the agent's rename
- * from "Voice Co-Agent" to "Realtime Co-Agent". Deployments that have not re-synced the agent seed
- * still carry this name, so {@link RealtimeClientSessionResolver.resolveGlobalCoAgentID} falls
- * back to it (with a deprecation log) when no agent named {@link REALTIME_CO_AGENT_NAME} exists.
- */
-const LEGACY_REALTIME_CO_AGENT_NAME = 'Voice Co-Agent';
-
-/**
- * The seeded name of the Realtime agent TYPE. Every co-agent candidate (explicit or metadata
- * default) must be an Active agent of this type — a co-agent drives a streaming full-duplex
- * realtime session, which only `RealtimeAgentType`-driven agents support.
- */
-const REALTIME_AGENT_TYPE_NAME = 'Realtime';
-
 /** Entity name — centralised so the `MJ:`-prefix convention is applied in exactly one place. */
 const SESSION_ENTITY = 'MJ: AI Agent Sessions';
 const CO_AGENT_ENTITY = 'MJ: AI Agent Co Agents';
@@ -381,6 +357,31 @@ export class RealtimeClientSessionResolver extends ResolverBase {
     private readonly clientSessionService = new RealtimeClientSessionService();
     private readonly sessionManager = new SessionManager(this.clientSessionService);
 
+    /**
+     * The reason a `Save()`/`Delete()` returned false, for a log line. `CompleteMessage` renders
+     * `Message`, `Error` and every `Errors[]` entry (validation errors included, since `Save()`
+     * runs `Validate()` and records its errors there), so there is no separate `Validate()` call.
+     * When a subclass refused the write without recording anything, say so explicitly instead of
+     * "unknown error", which is what hid MJ#4791.
+     *
+     * Only a NULL `LatestResult` proves the refusal happened before the provider (nothing was
+     * registered at all). A SUCCESS `LatestResult` is an earlier save on the same instance — the
+     * refusal registered nothing — so its text must never be reported as this failure's reason.
+     */
+    private describeSaveFailure(entity: BaseEntity): string {
+        const latest = entity.LatestResult;
+        if (!latest) {
+            return `no failure detail recorded (LatestResult null; ResultHistory length ${entity.ResultHistory.length}) ` +
+                '— the write was refused before reaching the provider';
+        }
+        if (latest.Success) {
+            return 'no failure detail recorded (latest result entry is a prior success; ' +
+                `ResultHistory length ${entity.ResultHistory.length})`;
+        }
+        const detail = latest.CompleteMessage?.trim();
+        return detail || `no failure detail recorded (LatestResult empty; ResultHistory length ${entity.ResultHistory.length})`;
+    }
+
     /**
      * Start a client-direct realtime voice session targeting `targetAgentId`.
      *
@@ -389,7 +390,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
      *    session is created.
      * 2. Resolve the co-agent id via the metadata-driven resolution chain (runtime `coAgentId` →
      *    agent's `DefaultCoAgentID` → type-level `AIAgentCoAgent` default row → global Realtime Co-Agent) —
-     *    see {@link RealtimeClientSessionResolver.resolveCoAgentID} for the full contract.
+     *    see {@link ResolveRealtimeCoAgentID} for the full contract.
      * 3. Create the durable `AIAgentSession` (run by the co-agent), storing `targetAgentID` in its
      *    config server-side — this is the authoritative target for all later relays.
      * 4. Mint the {@link import('@memberjunction/ai').ClientRealtimeSessionConfig} via the service.
@@ -438,7 +439,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
     ): Promise<StartRealtimeClientSessionResult> {
         const { contextUser, provider } = this.requireUserAndProvider(userPayload, providers);
 
-        const coAgentID = await this.resolveCoAgentID(targetAgentId, coAgentId, contextUser, provider);
+        const coAgentID = await ResolveRealtimeCoAgentID(targetAgentId, coAgentId, contextUser, provider);
         // PAIRING CONSTRAINTS: a co-agent with pairing rows is restricted to that target list
         // (with the IsDefault row standing in when no runtime target was supplied); zero rows =
         // universal, today's behavior untouched. Resolves the AUTHORITATIVE target id.
@@ -553,7 +554,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
                 TargetAgentID: config.targetAgentID,
                 // Multi-target (Move 4): the session's persisted allowed-agent union — a model-named
                 // colleague in the call is validated against this; absent ⇒ single-target behavior.
-                AllowedAgents: await this.filterAllowedAgentsByCanRun(config.allowedAgents, contextUser),
+                AllowedAgents: await FilterAllowedAgentsByCanRun(config.allowedAgents, contextUser),
                 DirectActions: config.directActions,
                 // Attribution follows the VISITOR even when `runUser` is elevated: the delegated run
                 // row and its context-memory scope must stay the person's, not the system user's.
@@ -593,7 +594,9 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         // Junction-link any artifacts the delegated run produced into the session's conversation
         // history (best-effort) — so chat, session review, and resume carryover can all see them.
         // Runs as `runUser`: the junction entity is not among an anonymous caller's relay grants.
-        await this.linkDelegatedArtifactsToConversation(session, Artifacts, runUser, provider);
+        // The hidden anchor detail it may need to create, though, is written by the CALLER (#4791)
+        // — same reason `persistDirectActionTurn` is: the System user is not the conversation owner.
+        await this.linkDelegatedArtifactsToConversation(session, Artifacts, runUser, contextUser, provider);
 
         await this.sessionManager.Heartbeat(agentSessionId, contextUser, provider);
         return ResultJson;
@@ -657,7 +660,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         session.Config_ = JSON.stringify(next);
         if (!(await session.Save())) {
             LogError(
-                `RealtimeClientSessionResolver.updatePendingFeedbackRunID save failed: ${session.LatestResult?.CompleteMessage ?? 'unknown error'}`,
+                `RealtimeClientSessionResolver.updatePendingFeedbackRunID save failed for session ${session.ID}: ${this.describeSaveFailure(session)}`,
             );
         }
     }
@@ -1223,39 +1226,6 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         }
     }
 
-    /**
-     * Narrows a session's colleague union (`allowedAgents`) to the agents the CALLER may run.
-     *
-     * {@link assertCanRunTarget} gates the LEAD target at session start, but the union it travels
-     * with was never gated at all — a model-named colleague resolves straight to a delegated run.
-     * That was survivable while the run carried the caller's own identity, because base-agent
-     * re-checks `CanRun` against `contextUser`. Once the run user is elevated for a scoped anonymous
-     * caller (issue #3371) that check sees the SYSTEM user, so this is the only remaining place the
-     * caller's own authority is applied to a colleague. It therefore runs for EVERY caller, elevated
-     * or not — the authorization identity must never depend on the elevation decision.
-     *
-     * `HasPermission` reads AIEngineBase's in-memory caches (no DB round trip) and already fails
-     * closed on error, so an unresolvable agent drops OUT of the union rather than becoming runnable.
-     * A filtered-out colleague is not an error: the delegation layer reports it as "not available in
-     * this session" and lists what remains, which is the same answer the model gets for a typo.
-     *
-     * @param allowedAgents The session's persisted colleague union (absent/empty ⇒ single-target).
-     * @param contextUser The ORIGINAL caller — never the elevated run user.
-     * @returns The subset the caller may run, preserving order.
-     */
-    private async filterAllowedAgentsByCanRun(
-        allowedAgents: RealtimeAllowedAgent[] | undefined,
-        contextUser: UserInfo,
-    ): Promise<RealtimeAllowedAgent[] | undefined> {
-        if (!allowedAgents || allowedAgents.length === 0) {
-            return allowedAgents;
-        }
-        const verdicts = await Promise.all(
-            allowedAgents.map((a) => AIAgentPermissionHelper.HasPermission(a.agentId, contextUser, 'run')),
-        );
-        return allowedAgents.filter((_, i) => verdicts[i]);
-    }
-
     /**
      * Resolves the AUTHORITATIVE target agent id under the co-agent's PAIRING CONSTRAINTS
      * (`MJ: AI Agent Co Agents`, ordered by `Sequence`):
@@ -1498,195 +1468,6 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         }
     }
 
-    /**
-     * Resolves the co-agent (the Realtime-type agent that voices the target agent) for a new
-     * client-direct session via the metadata-driven **CO-AGENT RESOLUTION CHAIN** — first match
-     * wins, evaluated in precedence order:
-     *
-     * 1. **Runtime parameter** — the mutation's explicit `coAgentId`. A per-call override; an
-     *    invalid candidate (unknown, not Active, or not of the Realtime agent type) **throws**
-     *    (fail loud — the caller asked for something specific, mirroring `preferredModelId`).
-     * 2. **Per-agent persona** — the target agent's `AIAgent.DefaultCoAgentID`. An invalid
-     *    reference logs a warning and **falls through** to the next step (stale metadata should
-     *    degrade gracefully, never break calls).
-     * 3. **Per-type default** — an Active `AIAgentCoAgent` row of Type `'CoAgent'` whose
-     *    `TargetAgentTypeID` is the target agent's type and `IsDefault = 1` (lowest `Sequence`
-     *    wins a tie). Same tolerant warn-and-fall-through semantics as step 2.
-     * 4. **Global default** — the seeded {@link REALTIME_CO_AGENT_NAME} agent, looked up by name
-     *    (with a deprecated fallback to {@link LEGACY_REALTIME_CO_AGENT_NAME}). Throws when absent
-     *    entirely (the realtime feature is unconfigured in this deployment).
-     *
-     * Every candidate from steps 1–3 is validated by {@link findValidCoAgent}: it must exist in
-     * {@link AIEngine}'s cached agents, have Status `Active`, and be of the
-     * {@link REALTIME_AGENT_TYPE_NAME} agent type. Step 4 keeps its original name-lookup contract.
-     *
-     * @param targetAgentId The agent the co-agent will voice on behalf of (drives steps 2–3).
-     * @param explicitCoAgentId The runtime `coAgentId` mutation argument, when supplied (step 1).
-     * @returns The resolved co-agent's id (canonical casing from the metadata cache).
-     */
-    private async resolveCoAgentID(
-        targetAgentId: string | undefined,
-        explicitCoAgentId: string | undefined,
-        contextUser: UserInfo,
-        provider: IMetadataProvider,
-    ): Promise<string> {
-        await AIEngine.Instance.Config(false, contextUser, provider);
-
-        // Step 1 — explicit runtime parameter: fail LOUD on any problem.
-        if (explicitCoAgentId) {
-            const { agent, problem } = this.findValidCoAgent(explicitCoAgentId);
-            if (!agent) {
-                throw new Error(`Invalid coAgentId '${explicitCoAgentId}': ${problem}`);
-            }
-            return agent.ID;
-        }
-
-        const targetAgent = targetAgentId
-            ? (AIEngine.Instance.Agents ?? []).find(a => UUIDsEqual(a.ID, targetAgentId))
-            : undefined;
-
-        // Step 2 — the target agent's own DefaultCoAgentID (per-agent persona): warn + fall through.
-        const fromAgent = this.resolveMetadataDefault(
-            targetAgent?.DefaultCoAgentID,
-            `agent '${targetAgent?.Name}' (DefaultCoAgentID)`,
-        );
-        if (fromAgent) {
-            return fromAgent;
-        }
-
-        // Step 3 — the type-level AIAgentCoAgent default row (per-type default): warn + fall through.
-        const agentType = targetAgent?.TypeID
-            ? (AIEngine.Instance.AgentTypes ?? []).find(t => UUIDsEqual(t.ID, targetAgent.TypeID))
-            : undefined;
-        const typeDefaultCoAgentID = agentType
-            ? this.findTypeDefaultCoAgentID(agentType.ID, contextUser, provider)
-            : undefined;
-        const fromType = this.resolveMetadataDefault(
-            await typeDefaultCoAgentID,
-            `agent type '${agentType?.Name}' (AIAgentCoAgent type-default row)`,
-        );
-        if (fromType) {
-            return fromType;
-        }
-
-        // Step 4 — global default: the seeded Realtime Co-Agent, by name (original behavior).
-        return this.resolveGlobalCoAgentID();
-    }
-
-    /**
-     * Chain step 3 lookup: the TYPE-LEVEL default co-agent for an agent type — the Active
-     * `AIAgentCoAgent` row of Type `'CoAgent'` whose `TargetAgentTypeID` matches, with
-     * `IsDefault = 1` preferred and the lowest `Sequence` breaking ties (so a deployment can
-     * stage multiple type-level candidates deterministically). Reads {@link AIEngineBase}'s
-     * cached rows — no RunView. Tolerant: a failed cache read logs and returns `undefined`
-     * (the chain falls through to the global default).
-     */
-    private async findTypeDefaultCoAgentID(
-        agentTypeID: string,
-        contextUser: UserInfo,
-        provider: IMetadataProvider,
-    ): Promise<string | undefined> {
-        try {
-            const engine = await this.configuredAIEngineBase(contextUser, provider);
-            const candidates = (engine.AgentCoAgents ?? [])
-                .filter((r) =>
-                    r.Type === 'CoAgent' &&
-                    r.Status === 'Active' &&
-                    r.TargetAgentTypeID != null &&
-                    UUIDsEqual(r.TargetAgentTypeID, agentTypeID))
-                .sort((a, b) =>
-                    (a.IsDefault === b.IsDefault ? 0 : a.IsDefault ? -1 : 1) ||
-                    (a.Sequence ?? 0) - (b.Sequence ?? 0));
-            return candidates[0]?.CoAgentID;
-        } catch (error) {
-            LogError(
-                `StartRealtimeClientSession: ${CO_AGENT_ENTITY} cache read failed while resolving the type-level ` +
-                    `default co-agent for agent type ${agentTypeID} (${(error as Error).message}) — falling through.`,
-            );
-            return undefined;
-        }
-    }
-
-    /**
-     * Validates one metadata-level co-agent default (chain steps 2/3). Returns the resolved
-     * co-agent id when the reference is valid; logs a warning and returns `null` (caller falls
-     * through to the next chain step) when the reference is set but invalid — metadata drift must
-     * degrade, not break live calls. A `null`/absent reference returns `null` silently.
-     */
-    private resolveMetadataDefault(candidateId: string | null | undefined, source: string): string | null {
-        if (!candidateId) {
-            return null;
-        }
-        const { agent, problem } = this.findValidCoAgent(candidateId);
-        if (agent) {
-            return agent.ID;
-        }
-        LogError(
-            `StartRealtimeClientSession: ignoring co-agent default '${candidateId}' from ${source} — ${problem} ` +
-                'Falling through to the next step of the co-agent resolution chain.',
-        );
-        return null;
-    }
-
-    /**
-     * Validates a co-agent candidate against {@link AIEngine}'s cached metadata. A valid co-agent
-     * must (a) exist, (b) have Status `Active`, and (c) be of the {@link REALTIME_AGENT_TYPE_NAME}
-     * agent type. Returns the cached agent on success, or a human-readable `problem` on failure —
-     * the CALLER decides whether that's fatal (explicit runtime param) or tolerated (metadata default).
-     */
-    private findValidCoAgent(candidateId: string): { agent?: MJAIAgentEntityExtended; problem?: string } {
-        const agent = (AIEngine.Instance.Agents ?? []).find(a => UUIDsEqual(a.ID, candidateId));
-        if (!agent) {
-            return { problem: 'no agent with that ID exists.' };
-        }
-        if (agent.Status !== 'Active') {
-            return { problem: `agent '${agent.Name}' is not Active (Status: ${agent.Status}).` };
-        }
-        const realtimeType = (AIEngine.Instance.AgentTypes ?? []).find(
-            t => t.Name?.trim().toLowerCase() === REALTIME_AGENT_TYPE_NAME.toLowerCase(),
-        );
-        if (!realtimeType) {
-            return { problem: `the '${REALTIME_AGENT_TYPE_NAME}' agent type is not configured in this deployment.` };
-        }
-        if (!agent.TypeID || !UUIDsEqual(agent.TypeID, realtimeType.ID)) {
-            return { problem: `agent '${agent.Name}' is not of the '${REALTIME_AGENT_TYPE_NAME}' agent type.` };
-        }
-        return { agent };
-    }
-
-    /**
-     * Resolves the seeded Realtime Co-Agent's id from {@link AIEngine}'s cached agents — the GLOBAL
-     * DEFAULT (step 4) of the co-agent resolution chain. The engine is already configured by
-     * {@link resolveCoAgentID}. Looks up the current {@link REALTIME_CO_AGENT_NAME} first, then
-     * falls back to the DEPRECATED {@link LEGACY_REALTIME_CO_AGENT_NAME} (pre-rename seed) with a
-     * deprecation log so un-resynced deployments keep working. Throws a clear error when neither
-     * name is present in metadata.
-     */
-    private resolveGlobalCoAgentID(): string {
-        const coAgent = this.findAgentByName(REALTIME_CO_AGENT_NAME);
-        if (coAgent) {
-            return coAgent.ID;
-        }
-        const legacy = this.findAgentByName(LEGACY_REALTIME_CO_AGENT_NAME);
-        if (legacy) {
-            LogStatus(
-                `StartRealtimeClientSession: resolved the global co-agent via its DEPRECATED legacy name ` +
-                    `'${LEGACY_REALTIME_CO_AGENT_NAME}'. Re-sync the agent seed metadata to rename it to ` +
-                    `'${REALTIME_CO_AGENT_NAME}'.`,
-            );
-            return legacy.ID;
-        }
-        throw new Error(
-            `The '${REALTIME_CO_AGENT_NAME}' agent is not configured; cannot start a realtime voice session.`,
-        );
-    }
-
-    /** Case/whitespace-insensitive agent lookup by Name in {@link AIEngine}'s cached agents. */
-    private findAgentByName(name: string): MJAIAgentEntityExtended | undefined {
-        const wanted = name.toLowerCase();
-        return (AIEngine.Instance.Agents ?? []).find(a => a.Name?.trim().toLowerCase() === wanted);
-    }
-
     /**
      * Mints the client session config for a just-created session. On failure, closes the session so
      * no half-open record leaks, then throws the service's error message.
@@ -1812,7 +1593,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         const saved = await session.Save();
         if (!saved) {
             LogError(
-                `RealtimeClientSessionResolver.persistObservabilityRunIDs save failed: ${session.LatestResult?.CompleteMessage ?? 'unknown error'}`,
+                `RealtimeClientSessionResolver.persistObservabilityRunIDs save failed for session ${session.ID}: ${this.describeSaveFailure(session)}`,
             );
         }
     }
@@ -1930,7 +1711,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         if (!saved) {
             LogError(
                 `SaveSessionChannelState: save failed for session ${agentSessionID} / channel ${channelID}: ` +
-                    `${row.LatestResult?.CompleteMessage ?? 'unknown error'}`,
+                    `${this.describeSaveFailure(row)}`,
             );
         }
         return saved;
@@ -2313,7 +2094,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         artifact.UserID = contextUser.ID;
         artifact.Visibility = 'Always';
         if (!(await artifact.Save())) {
-            const message = `SaveSessionChannelArtifact: artifact save failed: ${artifact.LatestResult?.CompleteMessage ?? 'unknown error'}`;
+            const message = `SaveSessionChannelArtifact: artifact save failed for session ${session.ID}: ${this.describeSaveFailure(artifact)}`;
             LogError(message);
             return { Success: false, ErrorMessage: message, ConversationDetailLinked: false };
         }
@@ -2325,7 +2106,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         version.Content = contentJson;
         version.UserID = contextUser.ID;
         if (!(await version.Save())) {
-            const message = `SaveSessionChannelArtifact: artifact version save failed: ${version.LatestResult?.CompleteMessage ?? 'unknown error'}`;
+            const message = `SaveSessionChannelArtifact: artifact version save failed for session ${session.ID} (artifact ${artifact.ID}): ${this.describeSaveFailure(version)}`;
             LogError(message);
             return { Success: false, ErrorMessage: message, ArtifactID: artifact.ID, ConversationDetailLinked: false };
         }
@@ -2383,13 +2164,22 @@ export class RealtimeClientSessionResolver extends ResolverBase {
      * queries (which scan junctions across ALL details) still surface the artifact. This is the
      * least-invasive correct anchor — no fake visible message, no orphaned artifact.
      *
+     * TWO PRINCIPALS, deliberately: the lookup (`findLatestSessionDetailID`) and the junction row
+     * itself (`saveDetailArtifactJunction`, `MJ: Conversation Detail Artifacts`) run as `runUser`
+     * (elevated for a scoped-anonymous caller) — that junction entity is outside an anonymous
+     * caller's relay grants. The hidden ANCHOR `Conversation Detail` this may need to create runs as
+     * `callerUser` instead: like every other `MJ: Conversation Details` write, the System user is
+     * refused because it is not the conversation's owner (see {@link persistDirectActionTurn},
+     * issue #4791) — only the actual caller can create it.
+     *
      * Strictly best-effort: every failure path logs and returns; a relayed tool call NEVER fails
      * because history linking did.
      */
     private async linkDelegatedArtifactsToConversation(
         session: MJAIAgentSessionEntity,
         artifacts: DelegatedRunArtifact[] | undefined,
-        contextUser: UserInfo,
+        runUser: UserInfo,
+        callerUser: UserInfo,
         provider: IMetadataProvider,
     ): Promise<void> {
         if (!artifacts || artifacts.length === 0 || !session.ConversationID) {
@@ -2397,13 +2187,13 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         }
         try {
             const detailID =
-                (await this.findLatestSessionDetailID(session, contextUser, provider)) ??
-                (await this.createHiddenSessionAnchorDetail(session, contextUser, provider));
+                (await this.findLatestSessionDetailID(session, runUser, provider)) ??
+                (await this.createHiddenSessionAnchorDetail(session, callerUser, provider));
             if (!detailID) {
                 return; // anchor unavailable — logged in the helpers
             }
             for (const artifact of artifacts) {
-                await this.saveDetailArtifactJunction(detailID, artifact.ArtifactVersionID, contextUser, provider);
+                await this.saveDetailArtifactJunction(detailID, artifact.ArtifactVersionID, runUser, provider);
             }
         } catch (error) {
             LogError(`ExecuteRealtimeSessionTool: delegated-artifact history link failed: ${(error as Error).message}`);
@@ -2444,25 +2234,25 @@ export class RealtimeClientSessionResolver extends ResolverBase {
      */
     private async createHiddenSessionAnchorDetail(
         session: MJAIAgentSessionEntity,
-        contextUser: UserInfo,
+        callerUser: UserInfo,
         provider: IMetadataProvider,
     ): Promise<string | null> {
-        const detail = await provider.GetEntityObject<MJConversationDetailEntity>(CONVERSATION_DETAIL_ENTITY, contextUser);
+        const detail = await provider.GetEntityObject<MJConversationDetailEntity>(CONVERSATION_DETAIL_ENTITY, callerUser);
         detail.NewRecord();
         detail.ConversationID = session.ConversationID;
         detail.Role = 'AI';
         detail.HiddenToUser = true;
         detail.Message = 'Artifacts produced during a realtime session (system anchor).';
         detail.AgentSessionID = session.ID;
-        // Attribute the anchor to the SESSION owner, not the (possibly elevated) writer — identical
-        // for every non-elevated caller, whose ownership of the session is already proven.
+        // Attribute to the SESSION owner — the caller writing this row, whose ownership
+        // `loadOwnedActiveSession` already proved.
         detail.UserID = session.UserID;
         if (await detail.Save()) {
             return detail.ID;
         }
         LogError(
             `ExecuteRealtimeSessionTool: hidden anchor detail save failed for session ${session.ID}: ` +
-                `${detail.LatestResult?.CompleteMessage ?? 'unknown error'}`,
+                `${this.describeSaveFailure(detail)}`,
         );
         return null;
     }
@@ -2489,7 +2279,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         if (!saved) {
             LogError(
                 `RealtimeClientSessionResolver: artifact junction save failed for detail ${conversationDetailID} / version ${artifactVersionID}: ` +
-                    `${junction.LatestResult?.CompleteMessage ?? 'unknown error'}`,
+                    `${this.describeSaveFailure(junction)}`,
             );
         }
         return saved;
@@ -2529,7 +2319,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
             if (!(await row.Save())) {
                 LogError(
                     `SaveSessionChannelArtifact: LastActiveAt stamp failed for session ${agentSessionID} / channel ${channelID}: ` +
-                        `${row.LatestResult?.CompleteMessage ?? 'unknown error'}`,
+                        `${this.describeSaveFailure(row)}`,
                 );
             }
         } catch (error) {
@@ -2673,12 +2463,6 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         return minutes && minutes > 0 ? minutes * 60 : undefined;
     }
 
-    /**
-     * Persists a single transcript turn as a `Conversation Detail` stamped with the session's
-     * conversation, the mapped role, the turn text, the session id, and the owning user.
-     *
-     * @returns The boolean save result (logs `CompleteMessage` on failure).
-     */
     /**
      * Stamps `RecordingStartedAt` (the recording `t0` alignment origin) + `RecordingMedia` on a
      * just-started session when the browser captured WITH consent. Best-effort: a parse/save failure
@@ -2705,11 +2489,18 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         session.RecordingMedia = 'Audio';
         if (!(await session.Save())) {
             LogError(
-                `RealtimeClientSessionResolver.stampRecordingStart save failed: ${session.LatestResult?.CompleteMessage ?? 'unknown error'}`,
+                `RealtimeClientSessionResolver.stampRecordingStart save failed for session ${session.ID}: ${this.describeSaveFailure(session)}`,
             );
         }
     }
 
+    /**
+     * Persists a single transcript turn as a `Conversation Detail` stamped with the session's
+     * conversation, the mapped role, the turn text, the session id, and the owning user.
+     *
+     * @returns The boolean save result. On failure it logs the session, the write user and the
+     * reason from {@link describeSaveFailure}.
+     */
     private async persistTranscriptTurn(
         session: MJAIAgentSessionEntity,
         role: string,
@@ -2739,7 +2530,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         const saved = await detail.Save();
         if (!saved) {
             LogError(
-                `RealtimeClientSessionResolver.persistTranscriptTurn save failed: ${detail.LatestResult?.CompleteMessage ?? 'unknown error'}`,
+                `RealtimeClientSessionResolver.persistTranscriptTurn save failed for session ${session.ID} (write user ${contextUser.ID}): ${this.describeSaveFailure(detail)}`,
             );
         }
         return saved;
@@ -2780,8 +2571,13 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         // ⚠️ ELEVATING INSTEAD WAS TRIED AND IS A TRAP. `ResolveScopedAnonymousRunUser` returns
         // `UserCache.GetSystemUser()`, which on this deployment resolves to the unconfigured
         // placeholder `not.set@nowhere.com` ("Configured provisioning user not found; falling back
-        // to an Owner"). Saving as a user that does not exist returns false with a NULL
-        // `LatestResult` — indistinguishable from a permission denial, and just as silent.
+        // to an Owner"). That user EXISTS — it is not a missing/invalid principal — and even carries
+        // full CRUD on `MJ: Conversation Details`. It is refused anyway:
+        // `MJConversationDetailEntityExtended`'s owner gate accepts only the conversation's OWNER or
+        // an Edit/Owner Resource Permission grantee, and the System user is neither. Measured on
+        // MJ#4791 (before the core-entities fix that now records the denial): `Save()` → `false`,
+        // `LatestResult` null — indistinguishable from a permission denial, and just as silent. The
+        // denial itself still happens; that fix only made it stop being silent.
         const writeUser = contextUser;
         const rv = RunView.FromMetadataProvider(provider);
         const result = await rv.RunView<MJConversationDetailEntity>(
@@ -2802,8 +2598,8 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         //
         // `ResultType: 'entity_object'` hands back hydrated entities, but they do not carry the
         // context user the way `GetEntityObject(entity, user)` does — so `Save()` ran with no
-        // principal and failed with an EMPTY message ("unknown error"), which is what the elevation
-        // fix above looked like when it was still broken. The insert path beside this one has
+        // principal and failed with an EMPTY message ("unknown error"), which is what an empty-message
+        // failure here looked like before the re-load. The insert path beside this one has
         // always used `GetEntityObject`; this now matches it, which is also why they now succeed
         // and fail for the same reasons.
         const previous = await provider.GetEntityObject<MJConversationDetailEntity>(
@@ -2835,7 +2631,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
                 `RealtimeClientSessionResolver.replacePreviousTranscriptTurn save failed for session `
                 + `${session.ID} — the ${mappedRole} turn keeps its PREVIOUS, shorter text and the `
                 + `transcript now understates what was said: `
-                + `${previous.LatestResult?.CompleteMessage || JSON.stringify(previous.LatestResult ?? null)}`,
+                + `${this.describeSaveFailure(previous)}`,
             );
         }
         return saved;
@@ -2855,6 +2651,23 @@ export class RealtimeClientSessionResolver extends ResolverBase {
      * Stored as stable facts (Role: 'AI', HiddenToUser: true, ExternalID: callId, CompletionTime: durationMs,
      * Message: JSON-serialized tool facts) so that session review can reconstruct the action card dynamically
      * on load (Option 1) without polluting user-facing speech chat bubbles.
+     *
+     * Writes as the CALLER, never the elevated run user (issue #4791). Owning the session
+     * (`loadOwnedActiveSession`'s gate has already run on every path here) does NOT imply owning
+     * the conversation: the conversation id was client-supplied at session start. What authorizes
+     * this write is the save itself, evaluated for the caller — the conversation owner gate in
+     * `MJConversationDetailEntityExtended`, plus the caller's own entity permission and Create RLS
+     * on `MJ: Conversation Details` (for the magic-link role that RLS scopes by the invite's
+     * `ScopeResourceID`, and the role belongs to a downstream app, not MJ core). That is why
+     * writing as the caller is safe even though the conversation id originated client-side.
+     * Elevating to the System user would bypass RLS entirely, and the owner gate refuses it anyway
+     * because the System user is not the conversation owner. Measured on MJ#4791 (before the
+     * core-entities fix that now records the denial): `Save()` returned `false` with a NULL `LatestResult` and an empty
+     * `ResultHistory` — indistinguishable from any other silent failure. Elevating this write is
+     * what silently dropped both hidden tool-execution turns of a real magic-link session; the
+     * denial itself still happens today, only its silence was fixed separately.
+     * `ResolveScopedAnonymousRunUser` elevates AI-**run**-entity writes only (prompt runs, agent
+     * runs, the relayed dispatch itself) — never this one.
      */
     private async persistDirectActionTurn(
         session: MJAIAgentSessionEntity,
@@ -2870,10 +2683,9 @@ export class RealtimeClientSessionResolver extends ResolverBase {
             return false;
         }
         try {
-            const writeUser = ResolveScopedAnonymousRunUser(contextUser);
             const detail = await provider.GetEntityObject<MJConversationDetailEntity>(
                 CONVERSATION_DETAIL_ENTITY,
-                writeUser,
+                contextUser,
             );
             detail.NewRecord();
             detail.ConversationID = session.ConversationID;
@@ -2915,13 +2727,13 @@ export class RealtimeClientSessionResolver extends ResolverBase {
             const saved = await detail.Save();
             if (!saved) {
                 LogError(
-                    `RealtimeClientSessionResolver.persistDirectActionTurn save failed: ${detail.LatestResult?.CompleteMessage ?? 'unknown error'}`,
+                    `RealtimeClientSessionResolver.persistDirectActionTurn save failed for session ${session.ID} (tool '${toolName}', call ${callId ?? 'n/a'}, write user ${contextUser.ID}): ${this.describeSaveFailure(detail)}`,
                 );
             }
             return saved;
         } catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            LogError(`RealtimeClientSessionResolver.persistDirectActionTurn unexpected error: ${message}`);
+            LogError(`RealtimeClientSessionResolver.persistDirectActionTurn unexpected error for session ${session.ID}: ${message}`);
             return false;
         }
     }