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

package/src/index.ts

@@ -61,6 +61,12 @@ import { GetAPIKeyEngine } from '@memberjunction/api-keys';
 import { RedisLocalStorageProvider } from '@memberjunction/redis-provider';
 import { GenericDatabaseProvider } from '@memberjunction/generic-database-provider';
 import { PubSubManager } from './generic/PubSubManager.js';
+import { ReconcileOrphanedConversationDetails } from './generic/OrphanedConversationDetailReconciler.js';
+import {
+  PUSH_STATUS_UPDATES_TOPIC,
+  SetPushStatusPublishHook,
+  ParseReplicatedStatusUpdate,
+} from './generic/PushStatusResolver.js';
 import { IntegrationProgressEmitter } from '@memberjunction/integration-progress-artifacts';
 import { PublishIntegrationProgress } from './resolvers/IntegrationProgressResolver.js';
 import { RegisterRSUProgressBridge } from './integration/RSUProgressBridge.js';
@@ -167,7 +173,9 @@ export * from './generic/refusalExtensions.js';
 export * from './generic/RunViewResolver.js';
 export * from './resolvers/RunTemplateResolver.js';
 export * from './resolvers/RunAIPromptResolver.js';
+export * from './resolvers/RunDecisionResolver.js';
 export * from './resolvers/RunAIAgentResolver.js';
+export { AgentRunStatusPublisher } from './resolvers/AgentRunStatusPublisher.js';
 export * from './resolvers/VectorizeEntityResolver.js';
 export * from './resolvers/SearchKnowledgeResolver.js';
 export * from './resolvers/SearchKnowledgeStreamResolver.js';
@@ -224,6 +232,7 @@ export * from './rest/MediaAccessKeys.js';
 export * from './rest/MediaStreamHandler.js';
 export * from './resolvers/InfoResolver.js';
 export * from './resolvers/PotentialDuplicateRecordResolver.js';
+export * from './resolvers/DuplicateEntryCheckResolver.js';
 export * from './resolvers/RunTestResolver.js';
 export * from './resolvers/SearchEntitiesResolver.js';
 export * from './resolvers/UserFavoriteResolver.js';
@@ -292,6 +301,61 @@ function resolveServerVersion(): string | undefined {
   }
 }
 
+/** How often to re-check for conversation details left behind by finished runs. */
+const ORPHAN_DETAIL_SWEEP_INTERVAL_MS = 5 * 60_000;
+
+/** Redis channel carrying replicated push-status updates between server instances. */
+const PUSH_STATUS_FANOUT_CHANNEL = 'push-status-updates';
+
+/**
+ * Replicate push-status updates across server instances over Redis (MJ #4222).
+ *
+ * Outbound: every locally-published update is forwarded on a shared channel. Inbound: a message
+ * from another instance is republished onto THIS instance's local topic, where the normal
+ * subscription filter decides who receives it — so the identity gate (`ownerUserId` vs. the
+ * connection's authenticated user) still applies to a replicated message exactly as it does to a
+ * local one. The replica has no say in who sees what.
+ *
+ * Republishing goes straight to `PubSubManager`, never back through `publishStatusUpdate`, so an
+ * inbound message cannot be re-broadcast and loop. `SourceServerId` guards the remaining case: a
+ * publisher also receives its own message from Redis.
+ */
+async function wirePushStatusFanOut(redisProvider: RedisLocalStorageProvider, startupLog: StartupLogger): Promise<void> {
+  try {
+    await redisProvider.SubscribeToChannel(PUSH_STATUS_FANOUT_CHANNEL, (raw: string) => {
+      try {
+        const payload = ParseReplicatedStatusUpdate(raw, MJGlobal.Instance.ProcessUUID);
+        if (!payload) {
+          return;
+        }
+        // Rebuilt as a plain record: the topic's publish signature takes an index-signature type,
+        // and listing the fields keeps the wire shape explicit at the one place it crosses hosts.
+        PubSubManager.Instance.Publish(PUSH_STATUS_UPDATES_TOPIC, {
+          sessionId: payload.sessionId,
+          ownerUserId: payload.ownerUserId,
+          message: payload.message,
+          SourceServerId: payload.SourceServerId,
+        });
+      } catch {
+        // A malformed message on a shared channel must not take down the subscriber.
+      }
+    });
+
+    SetPushStatusPublishHook((payload) => {
+      redisProvider.PublishMessage(PUSH_STATUS_FANOUT_CHANNEL, JSON.stringify(payload));
+    });
+
+    // Printed unconditionally, not verbose-gated. "Is fan-out actually on?" is the first question
+    // anyone debugging a hung conversation behind a load balancer asks, and a silent default left
+    // no way to answer it.
+    console.log('[MJAPI] Push-status updates: cross-instance fan-out enabled via Redis');
+  } catch (err) {
+    // Single-instance delivery still works, and the durable tail query covers the rest. Degraded,
+    // not broken — so this must not stop the server from starting.
+    console.warn(`Push-status fan-out unavailable: ${(err as Error).message}`);
+  }
+}
+
 // Bind MJStorage as the conversation-attachment blob store. The attachment service itself no longer
 // imports `@memberjunction/storage` — that dependency made it unusable from any browser or React
 // Native client, which is why the same attachment rules had been reimplemented three times.
@@ -720,6 +784,15 @@ const setupComplete$ = new ReplaySubject(1);
         }
     });
 
+    // Fan push-status updates across server instances (MJ #4222).
+    //
+    // Behind a load balancer the browser's WebSocket lives on one replica while the mutation that
+    // drives the agent can be handled by another. The push topic is an in-process PubSub, so a
+    // completion published on replica B never reaches a subscriber on replica A — the browser waits
+    // forever for an event that was delivered to nobody. Replicating progress and completion over
+    // Redis closes that, and the durable tail query remains the backstop if Redis is down.
+    await wirePushStatusFanOut(redisProvider, startupLog);
+
     startupLog.LogIf('verbose', `Redis cache provider connected: ${process.env.REDIS_URL}`);
   }
 
@@ -1075,6 +1148,15 @@ const setupComplete$ = new ReplaySubject(1);
     }
   });
 
+  // graphql-ws's ws integration takes its keepalive as a THIRD POSITIONAL argument to useServer,
+  // defaulting to 12_000 when omitted. That default was doing real work here while being invisible
+  // at the call site: the server pings every 12s and terminates the socket after an unanswered
+  // pong, which is why MJAPI notices a half-open link in ~12-24s while the browser — whose
+  // graphql-ws client does nothing on an unanswered pong — noticed nothing at all (MJ #4222).
+  // Stated explicitly so the behaviour is visible and tunable, and so the next reader does not
+  // conclude from the call site that no server-side heartbeat exists. Value unchanged.
+  const WS_SERVER_KEEPALIVE_MS = 12_000;
+
   // Track per-connection expiry timers so we can clean them up on close
   const expiryTimers = new WeakMap<object, ReturnType<typeof setTimeout>>();
 
@@ -1149,7 +1231,8 @@ const setupComplete$ = new ReplaySubject(1);
         console.error('WebSocket error:', errors);
       },
     },
-    webSocketServer
+    webSocketServer,
+    WS_SERVER_KEEPALIVE_MS
   );
 
   const apolloServer = buildApolloServer(
@@ -1580,8 +1663,25 @@ const setupComplete$ = new ReplaySubject(1);
   // instance is still heart-beating. The watchdog also self-registers for graceful-shutdown
   // cancellation (via ShutdownRegistry) once it begins tracking this process's first live run.
   if (resumeUser && Metadata.Provider instanceof DatabaseProviderBase) { // global-provider-ok: server startup recovery — one-shot orphaned-run sweep at boot
-    AgentRunWatchdog.SweepOrphanedRuns(Metadata.Provider, resumeUser) // global-provider-ok: server startup recovery — one-shot orphaned-run sweep at boot
+    const sweepUser = resumeUser;
+    const sweepProvider = Metadata.Provider; // global-provider-ok: server startup recovery — one-shot orphaned-run sweep at boot
+    AgentRunWatchdog.SweepOrphanedRuns(sweepProvider, sweepUser)
       .catch(err => console.warn(`[AgentRunWatchdog] Startup sweep failed: ${err}`));
+
+    // The watchdog repairs the RUN; nothing repaired the conversation detail, which is the row the
+    // chat actually renders from (MJ #4222). A process that dies mid-run leaves a terminal run
+    // beside a message that still claims to be generating, and it spins forever for anyone who
+    // opens it. Runs at boot (closes restart orphans) and on a timer (closes mid-life orphans),
+    // mirroring the watchdog's own two-phase shape.
+    const reconcileOrphans = () =>
+      ReconcileOrphanedConversationDetails(sweepProvider, sweepUser)
+        .catch(err => console.warn(`[OrphanDetailReconciler] Pass failed: ${err}`));
+    void reconcileOrphans();
+    const orphanDetailTimer = setInterval(() => void reconcileOrphans(), ORPHAN_DETAIL_SWEEP_INTERVAL_MS);
+    ShutdownRegistry.Instance.Register({
+      ShutdownName: 'OrphanDetailReconciler',
+      Shutdown: () => { clearInterval(orphanDetailTimer); },
+    });
   }
 
   // Launch the AI Agent Session janitor: run own-host orphan recovery once at boot, then keep a

package/src/resolvers/AgentRunStatusPublisher.ts

@@ -0,0 +1,175 @@
+/**
+ * Publishes one agent run's live status on the caller's session.
+ *
+ * `RunAIAgentResolver` uses this for every status it sends. A host whose
+ * `AgentTurnHandler` answers with an In-Progress reply uses the same publisher,
+ * on that caller's session, so the chat follows the turn: significant-step
+ * progress, streamed text, the partial result, and the completion. When the
+ * turn throws instead of returning a result, call `PublishFailure` with the
+ * reply row's id and the error.
+ */
+import type { PubSubEngine } from 'type-graphql';
+import type {
+    AgentExecutionProgressCallback,
+    AgentExecutionStreamingCallback,
+    ExecuteAgentResult,
+} from '@memberjunction/ai-core-plus';
+import type { UserPayload } from '../types.js';
+import { PublishStatusUpdate } from '../generic/PushStatusResolver.js';
+
+const SIGNIFICANT_STEPS = ['prompt_execution', 'action_execution', 'subagent_execution', 'decision_processing'];
+
+/** The run fields the published messages read. Entities and test fakes both satisfy this. */
+interface StatusRun {
+    ID?: string;
+    ConversationDetailID?: string;
+    ErrorMessage?: string;
+    Steps?: Array<{ StepName?: string }>;
+    GetAll?: () => unknown;
+}
+
+export class AgentRunStatusPublisher {
+    private run: StatusRun | null = null;
+
+    /**
+     * @param sessionId Session stamped on the message body. Defaults to the payload's session.
+     *   The push itself is always addressed to `userPayload.sessionId`, matching the resolver.
+     */
+    constructor(
+        private readonly pubSub: PubSubEngine,
+        private readonly userPayload: UserPayload,
+        private readonly sessionId: string = userPayload.sessionId,
+    ) {}
+
+    /** Latest run observed from a progress event, including steps that are not published. */
+    public get AgentRun(): StatusRun | null {
+        return this.run;
+    }
+
+    /** AgentRunner's progress callback. Noise steps are kept for {@link AgentRun} and not published. */
+    public get OnProgress(): AgentExecutionProgressCallback {
+        return (progress) => {
+            const fromEvent = progress.metadata?.agentRun as StatusRun | undefined;
+            if (fromEvent) {
+                this.run = fromEvent;
+            }
+            if (!SIGNIFICANT_STEPS.includes(progress.step)) {
+                return;
+            }
+            const agentRun = fromEvent || this.run;
+            if (!agentRun?.ID) {
+                // A host that streams before the first progress event otherwise sees nothing and no reason.
+                console.error('❌ No agent run available for progress callback');
+                return;
+            }
+            this.publish('ExecutionProgress', {
+                sessionId: this.sessionId,
+                agentRunId: agentRun.ID,
+                type: 'progress',
+                agentRun: agentRun.GetAll ? agentRun.GetAll() : agentRun,
+                progress: {
+                    currentStep: progress.step,
+                    percentage: progress.percentage,
+                    message: progress.message,
+                    agentName: progress.metadata?.agentName,
+                    agentType: progress.metadata?.agentType,
+                    stepCount: progress.metadata?.stepCount,
+                    hierarchicalStep: progress.metadata?.hierarchicalStep,
+                },
+                timestamp: new Date(),
+            });
+        };
+    }
+
+    /** AgentRunner's streaming callback. Publishes nothing until a progress event has carried the run. */
+    public get OnStreaming(): AgentExecutionStreamingCallback {
+        return (chunk) => {
+            const agentRun = this.run;
+            if (!agentRun?.ID) {
+                console.error('❌ No agent run available for streaming callback');
+                return;
+            }
+            this.publish('StreamingContent', {
+                sessionId: this.sessionId,
+                agentRunId: agentRun.ID,
+                type: 'streaming',
+                agentRun: agentRun.GetAll ? agentRun.GetAll() : agentRun,
+                streaming: {
+                    content: chunk.content,
+                    isPartial: !chunk.isComplete,
+                    stepName: chunk.stepType,
+                    agentName: chunk.modelName,
+                    kind: chunk.kind,
+                },
+                timestamp: new Date(),
+            });
+        };
+    }
+
+    /**
+     * The partial result, then the completion. `conversationDetailId` is the reply row the
+     * chat should update. When omitted, the completion uses the run's own detail id.
+     */
+    public PublishFinal(result: ExecuteAgentResult, conversationDetailId?: string, resultJson?: string): void {
+        const agentRun = result.agentRun as StatusRun | undefined;
+        if (agentRun?.ID) {
+            let lastStep = 'Completed';
+            const steps = agentRun.Steps;
+            if (steps && steps.length > 0) {
+                lastStep = steps[steps.length - 1]?.StepName || 'Completed';
+            }
+            this.publish('StreamingContent', {
+                sessionId: this.sessionId,
+                agentRunId: agentRun.ID,
+                type: 'partial_result',
+                partialResult: {
+                    currentStep: lastStep,
+                    partialOutput: result.payload || undefined,
+                },
+                timestamp: new Date(),
+            });
+        }
+        this.publish('StreamingContent', {
+            sessionId: this.sessionId,
+            agentRunId: agentRun?.ID || 'unknown',
+            type: 'complete',
+            timestamp: new Date(),
+            conversationDetailId: conversationDetailId || agentRun?.ConversationDetailID,
+            success: result.success,
+            errorMessage: agentRun?.ErrorMessage || undefined,
+            result: resultJson || undefined,
+        });
+    }
+
+    /**
+     * Completion for a failure that has no run. The fire-and-forget path uses this when
+     * `executeAIAgent` rejects. A host uses it the same way: when the turn throws
+     * instead of returning a result, call `PublishFailure` with the reply row's id
+     * and the error. That completion is what tells the chat the reply finished.
+     */
+    public PublishFailure(conversationDetailId: string | undefined, errorMessage: string): void {
+        this.publish('StreamingContent', {
+            sessionId: this.sessionId,
+            agentRunId: 'unknown',
+            type: 'complete',
+            timestamp: new Date(),
+            conversationDetailId,
+            success: false,
+            errorMessage,
+            result: JSON.stringify({ success: false, errorMessage }),
+        });
+    }
+
+    private publish(type: 'ExecutionProgress' | 'StreamingContent', data: unknown): void {
+        PublishStatusUpdate(this.pubSub, {
+            sessionId: this.userPayload.sessionId,
+            ownerUserId: this.userPayload?.userRecord?.ID ?? '',
+            message: JSON.stringify({
+                resolver: 'RunAIAgentResolver',
+                type,
+                status: 'ok',
+                data,
+            }),
+        });
+    }
+}

package/src/resolvers/ConversationRunEventsResolver.ts

@@ -0,0 +1,308 @@
+import { Arg, Ctx, Field, Int, ObjectType, Query, Resolver } from 'type-graphql';
+import { RunView } from '@memberjunction/core';
+import { EscapeSQLString } from '@memberjunction/global';
+import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import type { MJAIAgentRunEntity, MJAIAgentRunStepEntity, MJConversationDetailEntity } from '@memberjunction/core-entities';
+import type { AppContext } from '../types.js';
+import { GetReadOnlyProvider } from '../util.js';
+
+/** The run columns the tail reads. */
+type TailRunRow = Pick<MJAIAgentRunEntity, 'ID' | 'Status' | 'Result'>;
+
+/** The step columns an event carries. The large data columns are never read. */
+type TailStepRow = Pick<
+    MJAIAgentRunStepEntity,
+    'StepNumber' | 'StepType' | 'StepName' | 'Status' | 'Success' | 'ErrorMessage' | 'StartedAt' | 'CompletedAt'
+>;
+
+const RUN_FIELDS: (keyof TailRunRow)[] = ['ID', 'Status', 'Result'];
+const STEP_FIELDS: (keyof TailStepRow)[] = [
+    'StepNumber', 'StepType', 'StepName', 'Status', 'Success', 'ErrorMessage', 'StartedAt', 'CompletedAt',
+];
+
+/**
+ * One step of an agent run, projected for the client's progress view.
+ *
+ * Carries metadata only. `InputData`, `OutputData` and the payload snapshots are
+ * deliberately excluded: they are the largest columns on the row and a run can hold
+ * hundreds of steps, so including them would let a single tail call return tens of
+ * megabytes. The final result is delivered once, via `FinalPayload`, when the run
+ * reaches a terminal state.
+ */
+@ObjectType()
+export class ConversationRunEvent {
+    /** Monotonic position within the run. The cursor a client pages from. */
+    @Field(() => Int)
+    Seq: number;
+
+    @Field(() => String)
+    StepType: string;
+
+    @Field(() => String)
+    StepName: string;
+
+    @Field(() => String)
+    Status: string;
+
+    @Field(() => Boolean, { nullable: true })
+    Success?: boolean;
+
+    @Field(() => String, { nullable: true })
+    ErrorMessage?: string;
+
+    @Field(() => Date)
+    StartedAt: Date;
+
+    @Field(() => Date, { nullable: true })
+    CompletedAt?: Date;
+}
+
+/** Result of a tail call. */
+@ObjectType()
+export class ConversationRunEventsOutput {
+    @Field(() => Boolean)
+    Success: boolean;
+
+    @Field(() => String)
+    Message: string;
+
+    @Field(() => [ConversationRunEvent])
+    Events: ConversationRunEvent[];
+
+    /**
+     * Highest `Seq` the caller has now seen. Pass it back as `sinceSeq` on the next call.
+     * Echoes the request's `sinceSeq` when nothing new has landed, so a client that polls
+     * a quiet run never rewinds.
+     */
+    @Field(() => Int)
+    LatestSeq: number;
+
+    /**
+     * True while the run is still executing, including a run `Paused` on a workflow that is still
+     * running. False means terminal — stop tailing, and `FinalPayload` / `RunStatus` hold the
+     * outcome. A failed call (`Success` false) reports true, because it knows nothing about the run.
+     */
+    @Field(() => Boolean)
+    IsInFlight: boolean;
+
+    @Field(() => String, { nullable: true })
+    RunID?: string;
+
+    @Field(() => String, { nullable: true })
+    RunStatus?: string;
+
+    /**
+     * The run's answer, returned only once the run is terminal.
+     *
+     * Sourced from `AIAgentRun.Result`, falling back to the conversation detail's message because
+     * `Result` is agent-dependent and null on many successful runs. Still nullable: a caller must
+     * decide a message is finished from {@link IsInFlight} / {@link DetailStatus}, never from the
+     * presence of this field, or it will wait forever on an agent that writes neither.
+     */
+    @Field(() => String, { nullable: true })
+    FinalPayload?: string;
+
+    /** `ConversationDetail.Status` — the value the chat UI renders from. */
+    @Field(() => String, { nullable: true })
+    DetailStatus?: string;
+}
+
+/**
+ * Every read here sets `BypassCache`. This is the last-resort recovery path, and the rows it
+ * judges are written by callers that fire no cache invalidation — `spSweepStaleAIAgentRuns`
+ * force-fails a run with a direct set-based UPDATE. `TrustServerCacheCompletely` defaults on, so
+ * a cached read would keep reporting a swept run as `Running` and recovery would never fire.
+ */
+
+/** Ceiling on events returned per call. A client with a gap larger than this pages. */
+const MAX_EVENTS_PER_TAIL = 200;
+
+/**
+ * Run statuses that mean execution is still in progress. `Paused` is a run parked on a workflow
+ * that is still executing; the orphan reconciler and the process panel treat it the same way.
+ */
+const IN_FLIGHT_STATUSES: MJAIAgentRunEntity['Status'][] = ['Running', 'Paused'];
+
+/**
+ * Durable, resumable read of an agent run's progress (MJ #4222).
+ *
+ * The `statusUpdates` subscription is the only live path a conversation has, and it has no
+ * replay: the server topic is an in-memory PubSub and the client subject is explicitly
+ * unbuffered. Anything published while a socket is half-open is gone, and the client cannot
+ * tell the difference between "nothing happened" and "I missed everything".
+ *
+ * This query is the durable counterpart, mirroring `IntegrationTailRunEvents` — the same
+ * shape the integration subsystem already uses, where the subscription is a latency
+ * optimization over a log rather than the only delivery path. A client keeps the `LatestSeq`
+ * it has seen and re-reads from there after any interruption.
+ *
+ * It is a READ MODEL over tables that already exist. `AIAgentRunStep` rows are inserted when
+ * a step starts and updated when it finishes, so progress is visible mid-run, and
+ * `StepNumber` is already monotonic per run. No new table and no migration.
+ *
+ * Authorization is delegated to `RunView` executed as the calling user, so MJ's existing
+ * row-level security decides what is visible. A caller who cannot read the conversation
+ * detail gets the same answer as one asking about a detail that does not exist.
+ */
+@Resolver()
+export class ConversationRunEventsResolver {
+    @Query(() => ConversationRunEventsOutput)
+    async TailConversationEvents(
+        @Arg('conversationDetailID', () => String) conversationDetailID: string,
+        @Ctx() ctx: AppContext,
+        @Arg('sinceSeq', () => Int, { defaultValue: 0 }) sinceSeq?: number
+    ): Promise<ConversationRunEventsOutput> {
+        const from = Math.max(0, sinceSeq ?? 0);
+        const empty = (message: string): ConversationRunEventsOutput => ({
+            Success: false,
+            Message: message,
+            Events: [],
+            LatestSeq: from,
+            IsInFlight: true,
+        });
+
+        try {
+            const user = ctx.userPayload?.userRecord;
+            if (!user) {
+                return empty('User is not authenticated');
+            }
+
+            const provider = GetReadOnlyProvider(ctx.providers, { allowFallbackToReadWrite: true });
+            const detail = await this.loadDetail(provider, conversationDetailID, user);
+            if (!detail) {
+                // Not found and not authorized are deliberately indistinguishable — answering
+                // "exists but denied" would confirm the id to someone probing for one.
+                return empty(`Conversation detail '${conversationDetailID}' not found`);
+            }
+
+            const run = await this.loadLatestRun(provider, conversationDetailID, user);
+            if (!run) {
+                // The mutation is acknowledged before the run row exists, so this is an
+                // ordinary early-poll result, not an error. Reported as success with nothing
+                // to show so a client does not treat a race as a failure.
+                return {
+                    Success: true,
+                    Message: 'No agent run yet for this conversation detail',
+                    Events: [],
+                    LatestSeq: from,
+                    IsInFlight: false,
+                    DetailStatus: detail.Status ?? undefined,
+                };
+            }
+
+            const isInFlight = IN_FLIGHT_STATUSES.includes(run.Status);
+            const steps = await this.loadSteps(provider, run.ID, from, user);
+            const events = steps.map((s) => this.toEvent(s));
+
+            return {
+                Success: true,
+                Message: `${events.length} event(s)`,
+                Events: events,
+                // Never rewind: a quiet run returns the cursor the caller already held.
+                LatestSeq: events.length > 0 ? events[events.length - 1].Seq : from,
+                IsInFlight: isInFlight,
+                RunID: run.ID,
+                RunStatus: run.Status,
+                // Only meaningful once terminal; sending it mid-run would hand the client a
+                // partial payload it could mistake for the final answer.
+                //
+                // `AIAgentRun.Result` is agent-dependent — it is null on a large share of
+                // genuinely successful runs — so the conversation detail's own message is the
+                // fallback. That is the text the chat renders, so it is the answer a caller
+                // waiting on this field actually wants.
+                FinalPayload: isInFlight ? undefined : (run.Result ?? detail.Message ?? undefined),
+                DetailStatus: detail.Status ?? undefined,
+            };
+        } catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return empty(`TailConversationEvents failed: ${message}`);
+        }
+    }
+
+    /** Loads the conversation detail as the calling user; null when absent or not permitted. */
+    private async loadDetail(
+        provider: IMetadataProvider,
+        conversationDetailID: string,
+        user: UserInfo
+    ): Promise<MJConversationDetailEntity | undefined> {
+        const rv = RunView.FromMetadataProvider(provider);
+        const result = await rv.RunView<MJConversationDetailEntity>(
+            {
+                EntityName: 'MJ: Conversation Details',
+                ExtraFilter: `ID='${this.escape(conversationDetailID)}'`,
+                MaxRows: 1,
+                ResultType: 'entity_object',
+                BypassCache: true,
+            },
+            user
+        );
+        return result.Success ? result.Results?.[0] : undefined;
+    }
+
+    /**
+     * Newest run for the detail. A conversation detail can be retried, and the latest run is
+     * the one the UI is showing.
+     */
+    private async loadLatestRun(
+        provider: IMetadataProvider,
+        conversationDetailID: string,
+        user: UserInfo
+    ): Promise<TailRunRow | undefined> {
+        const rv = RunView.FromMetadataProvider(provider);
+        const result = await rv.RunView<TailRunRow>(
+            {
+                EntityName: 'MJ: AI Agent Runs',
+                ExtraFilter: `ConversationDetailID='${this.escape(conversationDetailID)}'`,
+                OrderBy: '__mj_CreatedAt DESC',
+                MaxRows: 1,
+                Fields: RUN_FIELDS,
+                ResultType: 'simple',
+                BypassCache: true,
+            },
+            user
+        );
+        return result.Success ? result.Results?.[0] : undefined;
+    }
+
+    /** Steps after `sinceSeq`, oldest first, bounded by {@link MAX_EVENTS_PER_TAIL}. */
+    private async loadSteps(
+        provider: IMetadataProvider,
+        agentRunID: string,
+        sinceSeq: number,
+        user: UserInfo
+    ): Promise<TailStepRow[]> {
+        const rv = RunView.FromMetadataProvider(provider);
+        const result = await rv.RunView<TailStepRow>(
+            {
+                EntityName: 'MJ: AI Agent Run Steps',
+                ExtraFilter: `AgentRunID='${this.escape(agentRunID)}' AND StepNumber > ${Math.floor(sinceSeq)}`,
+                OrderBy: 'StepNumber ASC',
+                MaxRows: MAX_EVENTS_PER_TAIL,
+                Fields: STEP_FIELDS,
+                ResultType: 'simple',
+                BypassCache: true,
+            },
+            user
+        );
+        return result.Success ? (result.Results ?? []) : [];
+    }
+
+    /** Projects a plain step row to an event. Plain rows may carry dates as strings. */
+    private toEvent(step: TailStepRow): ConversationRunEvent {
+        return {
+            Seq: step.StepNumber,
+            StepType: step.StepType,
+            StepName: step.StepName,
+            Status: step.Status,
+            Success: step.Success ?? undefined,
+            ErrorMessage: step.ErrorMessage ?? undefined,
+            StartedAt: new Date(step.StartedAt),
+            CompletedAt: step.CompletedAt != null ? new Date(step.CompletedAt) : undefined,
+        };
+    }
+
+    /** Escapes a value for the `ExtraFilter` string. Ids are UUIDs, but never trust the shape. */
+    private escape(value: string): string {
+        return EscapeSQLString(value);
+    }
+}