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

package/src/resolvers/RealtimeClientSessionResolver.ts

@@ -33,8 +33,8 @@
  */
 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, LogErrorEx, LogStatus, RunView, BaseEntity } from '@memberjunction/core';
-import { UUIDsEqual, IsValidUUID } from '@memberjunction/global';
+import { AuthorizationEvaluator, UserInfo, IMetadataProvider, DatabaseProviderBase, LogError, LogErrorEx, LogStatus, RunView, BaseEntity } from '@memberjunction/core';
+import { EscapeSQLString, UUIDsEqual, IsValidUUID } from '@memberjunction/global';
 import {
     MJAIAgentEntity,
     MJAIAgentSessionEntity,
@@ -44,6 +44,8 @@ import {
     MJConversationDetailArtifactEntity,
     MJConversationDetailEntity,
     ConversationEngine,
+    MJConversationDetailEntityExtended,
+    MJConversationEntity,
 } from '@memberjunction/core-entities';
 import { AIEngine } from '@memberjunction/aiengine';
 import { AIAgentPermissionHelper, AIEngineBase, HasRealtimeUsage, ParseRealtimeUsageRecord, type RealtimeUsageRecord } from '@memberjunction/ai-engine-base';
@@ -62,6 +64,7 @@ import {
     RealtimeAllowedAgent,
     RealtimeDirectActionsConfig,
     REALTIME_ADVANCED_SESSION_CONTROLS_AUTHORIZATION,
+    SqlRealtimeRecordingLedger,
     resolveRecordingStorageAccountID,
     storeRealtimeRecording,
     writeRealtimeRecordingSegment,
@@ -88,6 +91,7 @@ import { RunWithTrustedSessionConfigWrites } from '@memberjunction/core-entities
 import { BuildMintConfigStamps, LoadInheritedVerifiedIdentity } from '../realtimeSessions/sessionConfigStamps.js';
 import { ParseConfigObject } from '../realtimeSessions/verificationCore.js';
 import { LoadOwnedRealtimeSession } from '../realtimeSessions/ownedRealtimeSession.js';
+import { AuthorizeSessionAccess, LoadSessionForAccess } from '../realtimeSessions/sessionAccess.js';
 
 /**
  * Progress steps worth narrating to the realtime model — mirrors the normal agent-run path's filter
@@ -102,8 +106,15 @@ const SIGNIFICANT_PROGRESS_STEPS = ['prompt_execution', 'action_execution', 'sub
  */
 const MAX_USAGE_DETAILS_JSON_LENGTH = 4096;
 
+/**
+ * Sessions already logged as having no co-agent prompt run. Usage, transcript and tool-turn relays all read
+ * the id, many times per call, so the gap is logged once per session instead of once per relay. Bounded:
+ * past {@link MAX_LOGGED_MISSING_PROMPT_RUN_SESSIONS} entries the oldest is dropped (a Set keeps insertion order).
+ */
+const sessionsLoggedWithoutPromptRun = new Set<string>();
+const MAX_LOGGED_MISSING_PROMPT_RUN_SESSIONS = 5000;
+
 /** 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';
 const CONVERSATION_DETAIL_ENTITY = 'MJ: Conversation Details';
 const CHANNEL_ENTITY = 'MJ: AI Agent Channels';
@@ -596,7 +607,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         );
 
         // Best-effort: stamp recording-start metadata when the browser captured (with consent) at start.
-        await this.stampRecordingStart(session, recordingConsent, recordingStartedAt);
+        await this.stampRecordingStart(session, recordingConsent, recordingStartedAt, contextUser, provider);
 
         const clientTools = this.parseClientTools(clientToolsJson);
         const channelCandidates = this.parseChannelCandidates(channelCandidatesJson);
@@ -665,10 +676,18 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         contextUser: UserInfo,
         provider: IMetadataProvider,
     ): Promise<void> {
+        let inheritedVerified: Awaited<ReturnType<typeof LoadInheritedVerifiedIdentity>> = undefined;
+        try {
+            inheritedVerified = await LoadInheritedVerifiedIdentity(lastSessionId, contextUser, provider);
+        } catch (error) {
+            LogError(
+                `StartRealtimeClientSession: failed to load inherited verified identity for prior session ${lastSessionId}: ${(error as Error).message}`,
+            );
+        }
         const plan = BuildMintConfigStamps({
             EffectiveRealtime: this.readEffectiveRealtime(effectiveConfigJson),
             ExistingConfigRaw: session.Config_,
-            InheritedVerified: await LoadInheritedVerifiedIdentity(lastSessionId, contextUser, provider),
+            InheritedVerified: inheritedVerified,
             NowMs: Date.now(),
         });
         if (!plan) {
@@ -903,12 +922,15 @@ export class RealtimeClientSessionResolver extends ResolverBase {
     ): Promise<boolean> {
         const { contextUser, provider } = this.requireUserAndProvider(userPayload, providers);
         const session = await this.loadOwnedActiveSession(agentSessionId, contextUser, provider);
-
-        const saved = replacesPrevious
-            ? await this.replacePreviousTranscriptTurn(session, role, text, contextUser, provider, utteranceStartMs, utteranceEndMs)
-            : await this.persistTranscriptTurn(session, role, text, contextUser, provider, utteranceStartMs, utteranceEndMs);
-        if (!saved) {
-            return false;
+        const persistDetail =
+            this.mapTranscriptRole(role) === 'User' || (await this.callerOwnsConversation(session, contextUser, provider));
+        if (persistDetail) {
+            const saved = replacesPrevious
+                ? await this.replacePreviousTranscriptTurn(session, role, text, contextUser, provider, utteranceStartMs, utteranceEndMs)
+                : await this.persistTranscriptTurn(session, role, text, contextUser, provider, utteranceStartMs, utteranceEndMs);
+            if (!saved) {
+                return false;
+            }
         }
         // Mirror the turn onto the co-agent's long-lived prompt run so its Messages capture the full
         // conversation (run-viewer observability parity). Best-effort — never fails the transcript relay.
@@ -927,7 +949,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
             );
         }
         await this.sessionManager.Heartbeat(agentSessionId, contextUser, provider);
-        return true;
+        return persistDetail;
     }
 
     /**
@@ -1016,16 +1038,21 @@ export class RealtimeClientSessionResolver extends ResolverBase {
             });
 
             // Canonical consolidated file written — drop the crash-recovery shards (best-effort).
-            if (stored.FileID) {
+            // A FileID with an ErrorMessage is an uploaded file the session was not stamped with: the
+            // shards are then the only recording the janitor could still recover, so keep them.
+            const storedAndStamped = !!stored.FileID && !stored.ErrorMessage;
+            if (storedAndStamped) {
                 await deleteRealtimeRecordingSegments(agentSessionId, accountID, runUser);
+            } else if (stored.FileID) {
+                LogError(`RealtimeClientSessionResolver.UploadRealtimeRecording: session ${agentSessionId} has file ${stored.FileID} but it is not stamped (${stored.ErrorMessage}); shards kept`);
             }
 
             return {
-                Success: !!stored.FileID,
+                Success: storedAndStamped,
                 FileID: stored.FileID ?? undefined,
                 // Report the reason the storage layer knew (e.g. Drive's "Service Accounts do not have
                 // storage quota"); the generic sentence is only for when no layer supplied one.
-                ErrorMessage: stored.FileID ? undefined : (stored.ErrorMessage ?? 'Storage upload failed.'),
+                ErrorMessage: storedAndStamped ? undefined : (stored.ErrorMessage ?? 'Storage upload failed.'),
             };
         } catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -1311,10 +1338,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
             return null;
         }
         if (!config.promptRunID) {
-            LogStatus(
-                `RelayRealtimeUsage: session ${session.ID} has no co-agent promptRunID (observability run ` +
-                    'creation was skipped or failed) — usage delta dropped.',
-            );
+            this.logMissingPromptRunOnce(session.ID);
             return null;
         }
         const verified = await this.runIDVerifier.Verify(
@@ -1330,6 +1354,29 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         return verified.PromptRunID;
     }
 
+    /**
+     * Logs, once per session, that the session has no co-agent prompt run, so its usage, cost, transcript and
+     * tool turns are not recorded on one. The reason (no active co-agent prompt, or a failed run save) was
+     * logged when the session was prepared.
+     */
+    private logMissingPromptRunOnce(sessionID: string): void {
+        if (sessionsLoggedWithoutPromptRun.has(sessionID)) {
+            return;
+        }
+        sessionsLoggedWithoutPromptRun.add(sessionID);
+        if (sessionsLoggedWithoutPromptRun.size > MAX_LOGGED_MISSING_PROMPT_RUN_SESSIONS) {
+            const oldest = sessionsLoggedWithoutPromptRun.values().next().value;
+            if (oldest !== undefined) {
+                sessionsLoggedWithoutPromptRun.delete(oldest);
+            }
+        }
+        LogError(
+            `RealtimeClientSessionResolver: session ${sessionID} has no co-agent promptRunID, so its usage, cost, ` +
+                'transcript and tool turns are not recorded on a prompt run (the reason was logged when the session ' +
+                'was prepared). Logged once per session.',
+        );
+    }
+
     /**
      * Persist an interactive channel's state of record (e.g. the live whiteboard's serialized
      * scene) onto the session's `MJ: AI Agent Session Channels` row.
@@ -1477,7 +1524,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
     private requireUserAndProvider(
         userPayload: AppContext['userPayload'],
         providers: AppContext['providers'],
-    ): { contextUser: UserInfo; provider: IMetadataProvider } {
+    ): { contextUser: UserInfo; provider: DatabaseProviderBase } {
         const contextUser = this.GetUserFromPayload(userPayload);
         if (!contextUser) {
             throw new Error('Not authenticated: no user context for realtime session operation');
@@ -2013,9 +2060,10 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         const existing = await rv.RunView<MJAIAgentSessionChannelEntity>(
             {
                 EntityName: SESSION_CHANNEL_ENTITY,
-                ExtraFilter: `AgentSessionID='${agentSessionID}' AND ChannelID='${channelID}'`,
+                ExtraFilter: `AgentSessionID='${EscapeSQLString(agentSessionID)}' AND ChannelID='${EscapeSQLString(channelID)}'`,
                 ResultType: 'entity_object',
                 MaxRows: 1,
+                SkipTotalRowCount: true,
             },
             contextUser,
         );
@@ -2064,14 +2112,18 @@ export class RealtimeClientSessionResolver extends ResolverBase {
             return null;
         }
         try {
-            const prior = await provider.GetEntityObject<MJAIAgentSessionEntity>(SESSION_ENTITY, contextUser);
-            if (!(await prior.Load(lastSessionId))) {
+            const loaded = await LoadSessionForAccess(lastSessionId, contextUser, provider);
+            if (!loaded) {
                 LogError(`StartRealtimeClientSession: prior session ${lastSessionId} not found — skipping channel-state restore.`);
                 return null;
             }
-            if (!UUIDsEqual(prior.UserID, contextUser.ID)) {
+            const access = AuthorizeSessionAccess(
+                { SessionUserID: loaded.Session.UserID, ConversationExternalID: loaded.ConversationExternalID, ConversationReadable: loaded.ConversationReadable },
+                contextUser,
+            );
+            if (!access.Allowed) {
                 LogError(
-                    `StartRealtimeClientSession: prior session ${lastSessionId} is not owned by user ${contextUser.ID} — ` +
+                    `StartRealtimeClientSession: prior session ${lastSessionId} is not owned by user ${contextUser.ID} (${access.Reason}) — ` +
                         'skipping channel-state restore.',
                 );
                 return null;
@@ -2278,24 +2330,28 @@ export class RealtimeClientSessionResolver extends ResolverBase {
                 break;
             }
             visited.add(key);
-            const leg = await provider.GetEntityObject<MJAIAgentSessionEntity>(SESSION_ENTITY, contextUser);
-            if (!(await leg.Load(cursor))) {
+            const loaded = await LoadSessionForAccess(cursor, contextUser, provider);
+            if (!loaded) {
                 if (legIDs.length === 0) {
                     LogError(`StartRealtimeClientSession: prior session ${cursor} not found — skipping transcript hydration.`);
                 }
                 break;
             }
-            if (!UUIDsEqual(leg.UserID, contextUser.ID)) {
+            const access = AuthorizeSessionAccess(
+                { SessionUserID: loaded.Session.UserID, ConversationExternalID: loaded.ConversationExternalID, ConversationReadable: loaded.ConversationReadable },
+                contextUser,
+            );
+            if (!access.Allowed) {
                 if (legIDs.length === 0) {
                     LogError(
-                        `StartRealtimeClientSession: prior session ${cursor} is not owned by user ${contextUser.ID} — ` +
+                        `StartRealtimeClientSession: prior session ${cursor} is not owned by user ${contextUser.ID} (${access.Reason}) — ` +
                             'skipping transcript hydration.',
                     );
                 }
                 break;
             }
-            legIDs.push(leg.ID);
-            cursor = leg.LastSessionID ?? null;
+            legIDs.push(loaded.Session.ID);
+            cursor = loaded.Session.LastSessionID ?? null;
         }
         return legIDs;
     }
@@ -2396,6 +2452,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
                 Fields: ['ID', 'IsEnabled'],
                 ResultType: 'simple',
                 MaxRows: 1,
+                SkipTotalRowCount: true,
             },
             contextUser,
         );
@@ -2558,6 +2615,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
                 OrderBy: '__mj_CreatedAt DESC',
                 ResultType: 'simple',
                 MaxRows: 1,
+                SkipTotalRowCount: true,
             },
             contextUser,
         );
@@ -2576,8 +2634,9 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         callerUser: UserInfo,
         provider: IMetadataProvider,
     ): Promise<string | null> {
-        const detail = await provider.GetEntityObject<MJConversationDetailEntity>(CONVERSATION_DETAIL_ENTITY, callerUser);
+        const detail = await provider.GetEntityObject<MJConversationDetailEntityExtended>(CONVERSATION_DETAIL_ENTITY, callerUser);
         detail.NewRecord();
+        detail.MarkServerAuthoredReply(); // a server-written system anchor, not the caller's words
         detail.ConversationID = session.ConversationID;
         detail.BranchID = this.sessionBranchIdOf(session);
         detail.Role = 'AI';
@@ -2645,9 +2704,10 @@ export class RealtimeClientSessionResolver extends ResolverBase {
             const existing = await rv.RunView<MJAIAgentSessionChannelEntity>(
                 {
                     EntityName: SESSION_CHANNEL_ENTITY,
-                    ExtraFilter: `AgentSessionID='${agentSessionID}' AND ChannelID='${channelID}'`,
+                    ExtraFilter: `AgentSessionID='${EscapeSQLString(agentSessionID)}' AND ChannelID='${EscapeSQLString(channelID)}'`,
                     ResultType: 'entity_object',
                     MaxRows: 1,
+                    SkipTotalRowCount: true,
                 },
                 contextUser,
             );
@@ -2845,17 +2905,26 @@ export class RealtimeClientSessionResolver extends ResolverBase {
 
     /**
      * 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
-     * is logged and swallowed — a recording-metadata problem must never fail the session start.
+     * just-started session when the browser captured WITH consent. `RecordingStartedAt` goes through
+     * the entity save (and stays set on the in-memory session, so a later save of it cannot clear it);
+     * `RecordingMedia` is a recording-ledger column that an entity save cannot write (#6010), so it goes
+     * through the ledger's `spStampAIAgentSessionRecordingFile` proc. The proc stamps `t0` as well, so it
+     * lands even when the entity save fails: the janitor recovers only sessions that carry a
+     * `RecordingStartedAt`. Best-effort: a parse/save/stamp failure is logged and swallowed — a
+     * recording-metadata problem must never fail the session start.
      *
      * @param session The freshly created/loaded session.
      * @param recordingConsent Whether the user consented to recording — only `true` stamps anything.
      * @param recordingStartedAt ISO-8601 recording start timestamp from the browser.
+     * @param contextUser The caller, on whose behalf the proc runs.
+     * @param provider The server-side database provider the proc runs through.
      */
     private async stampRecordingStart(
         session: MJAIAgentSessionEntity,
         recordingConsent: boolean | undefined,
         recordingStartedAt: string | undefined,
+        contextUser: UserInfo,
+        provider: DatabaseProviderBase,
     ): Promise<void> {
         if (recordingConsent !== true || !recordingStartedAt) {
             return;
@@ -2866,12 +2935,19 @@ export class RealtimeClientSessionResolver extends ResolverBase {
             return;
         }
         session.RecordingStartedAt = startedAt;
-        session.RecordingMedia = 'Audio';
         if (!(await session.Save())) {
             LogError(
                 `RealtimeClientSessionResolver.stampRecordingStart save failed for session ${session.ID}: ${this.describeSaveFailure(session)}`,
             );
         }
+        try {
+            await new SqlRealtimeRecordingLedger(provider, contextUser).StampFile(session.ID, { media: 'Audio', startedAt });
+        } catch (error) {
+            LogError(
+                `RealtimeClientSessionResolver.stampRecordingStart media stamp failed for session ${session.ID}: ` +
+                    `${error instanceof Error ? error.message : String(error)}`,
+            );
+        }
     }
 
     /**
@@ -2890,11 +2966,14 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         utteranceStartMs?: number,
         utteranceEndMs?: number,
     ): Promise<boolean> {
-        const detail = await provider.GetEntityObject<MJConversationDetailEntity>(
+        const detail = await provider.GetEntityObject<MJConversationDetailEntityExtended>(
             CONVERSATION_DETAIL_ENTITY,
             contextUser,
         );
         detail.NewRecord();
+        // The agent's side of the session's transcript is written here, on the server, for the session's owner
+        // (the user's side is theirs and the marker does not touch it).
+        detail.MarkServerAuthoredReply();
         detail.ConversationID = session.ConversationID;
         detail.BranchID = this.sessionBranchIdOf(session);
         detail.Role = this.mapTranscriptRole(role);
@@ -2967,6 +3046,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
                 ExtraFilter: `AgentSessionID='${session.ID}' AND Role='${mappedRole}'`,
                 OrderBy: '__mj_CreatedAt DESC',
                 MaxRows: 1,
+                SkipTotalRowCount: true,
                 ResultType: 'entity_object',
             },
             writeUser,
@@ -2983,10 +3063,11 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         // 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>(
+        const previous = await provider.GetEntityObject<MJConversationDetailEntityExtended>(
             CONVERSATION_DETAIL_ENTITY,
             writeUser,
         );
+        previous.MarkServerAuthoredReply(); // as persistTranscriptTurn: the session's own transcript turn
         if (!(await previous.Load(found.ID))) {
             LogError(
                 `RealtimeClientSessionResolver.replacePreviousTranscriptTurn could not re-load turn `
@@ -3027,6 +3108,28 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         return role.trim().toLowerCase() === 'user' ? 'User' : 'AI';
     }
 
+    /**
+     * True when the session's conversation belongs to the caller. In client-direct mode the agent's
+     * words and tool facts reach the server only from the browser, so the server can't vouch for them:
+     * they are stored as the agent's reply only in the caller's own conversation (A19). In a
+     * conversation shared with the caller, only the caller's own side of the session is kept.
+     */
+    private async callerOwnsConversation(
+        session: MJAIAgentSessionEntity,
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<boolean> {
+        if (!session.ConversationID) {
+            return false;
+        }
+        const conversation = await provider.GetEntityObject<MJConversationEntity>('MJ: Conversations', contextUser);
+        const owned = (await conversation.Load(session.ConversationID)) && UUIDsEqual(conversation.UserID, contextUser.ID);
+        if (!owned) {
+            LogStatus(`RealtimeClientSessionResolver: session ${session.ID} relays the agent's side only into the caller's own conversation; conversation ${session.ConversationID} is not the caller's, so the agent's turn is not stored.`);
+        }
+        return owned;
+    }
+
     /**
      * Persists a direct action or channel tool execution as a hidden ConversationDetail turn.
      * Stored as stable facts (Role: 'AI', HiddenToUser: true, ExternalID: callId, CompletionTime: durationMs,
@@ -3060,15 +3163,16 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         contextUser: UserInfo,
         provider: IMetadataProvider,
     ): Promise<boolean> {
-        if (!session.ConversationID) {
+        if (!(await this.callerOwnsConversation(session, contextUser, provider))) {
             return false;
         }
         try {
-            const detail = await provider.GetEntityObject<MJConversationDetailEntity>(
+            const detail = await provider.GetEntityObject<MJConversationDetailEntityExtended>(
                 CONVERSATION_DETAIL_ENTITY,
                 contextUser,
             );
             detail.NewRecord();
+            detail.MarkServerAuthoredReply(); // the tool's facts are recorded by the server, as the session's owner
             detail.ConversationID = session.ConversationID;
             detail.BranchID = this.sessionBranchIdOf(session);
             detail.Role = 'AI';