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

package/src/__tests__/SessionManager.test.ts

@@ -11,11 +11,13 @@ vi.mock('@memberjunction/ai-engine-base', () => ({
 // --- Mock the client-direct service so CloseSession's run finalization is observable (no DB),
 //     plus the channel-plugin host so the start/close lifecycle notifications are observable. ---
 const finalizeCoAgentRunMock = vi.fn(async () => undefined);
+const keepCoAgentRunAliveMock = vi.fn();
 const hostSessionStartedMock = vi.fn(async () => undefined);
 const hostSessionClosedMock = vi.fn(async () => undefined);
 vi.mock('@memberjunction/ai-agents', () => ({
     RealtimeClientSessionService: class {
         FinalizeCoAgentRun = finalizeCoAgentRunMock;
+        KeepCoAgentRunAlive = keepCoAgentRunAliveMock;
     },
     RealtimeChannelServerHost: {
         get Instance() {
@@ -27,15 +29,18 @@ vi.mock('@memberjunction/ai-agents', () => ({
     },
 }));
 
-// --- Mock RunView.FromMetadataProvider so channel sweeps are controllable, while leaving the
-//     rest of @memberjunction/core intact. ---
+// --- Mock RunView.FromMetadataProvider so channel sweeps and run-id lookups are controllable,
+//     while leaving the rest of @memberjunction/core intact. RunViews runs each view through runViewMock. ---
 const runViewMock = vi.fn();
 vi.mock('@memberjunction/core', async (importOriginal) => {
     const actual = await importOriginal<typeof import('@memberjunction/core')>();
     return {
         ...actual,
         RunView: {
-            FromMetadataProvider: () => ({ RunView: runViewMock }),
+            FromMetadataProvider: () => ({
+                RunView: runViewMock,
+                RunViews: (paramsList: unknown[]) => Promise.all(paramsList.map((params) => runViewMock(params))),
+            }),
         },
     };
 });
@@ -100,6 +105,27 @@ function makeSessionEntity(overrides: Partial<FakeEntity> = {}): FakeEntity {
     };
 }
 
+/** Co-agent observability ids as a voice session's Config holds them. */
+const CO_RUN_ID = 'a5a5a5a5-0000-4000-8000-0000000000c0';
+const PROMPT_RUN_ID = 'a5a5a5a5-0000-4000-8000-0000000000b0';
+const RUN_STEP_ID = 'a5a5a5a5-0000-4000-8000-0000000000a0';
+
+/**
+ * Makes the given runs records of the session for the run-id lookups: `runIDs` carry the session's
+ * id, and `promptRunID` (when given) is the TargetLogID of the co-agent run's Prompt step.
+ */
+function mockSessionRunRecords(runIDs: string[], promptRunID?: string): void {
+    runViewMock.mockImplementation(async (params: { EntityName?: string }) => {
+        if (params.EntityName === 'MJ: AI Agent Runs') {
+            return { Success: true, Results: runIDs.map((ID) => ({ ID })) };
+        }
+        if (params.EntityName === 'MJ: AI Agent Run Steps') {
+            return { Success: true, Results: promptRunID ? [{ ID: RUN_STEP_ID, StepType: 'Prompt', TargetLogID: promptRunID }] : [] };
+        }
+        return { Success: true, Results: [] };
+    });
+}
+
 beforeEach(() => {
     hasPermissionMock.mockReset();
     finalizeCoAgentRunMock.mockClear();
@@ -228,8 +254,9 @@ describe('SessionManager.CloseSession', () => {
         const session = makeSessionEntity({
             ID: 'session-voice',
             Status: 'Active',
-            Config_: JSON.stringify({ targetAgentID: 't1', coAgentRunID: 'co-run-5', promptRunID: 'prompt-run-5' }),
+            Config_: JSON.stringify({ targetAgentID: 't1', coAgentRunID: CO_RUN_ID, promptRunID: PROMPT_RUN_ID }),
         });
+        mockSessionRunRecords([CO_RUN_ID], PROMPT_RUN_ID);
         const { provider } = makeProvider(() => session);
         const mgr = new SessionManager();
         const user = makeUser();
@@ -238,7 +265,7 @@ describe('SessionManager.CloseSession', () => {
 
         expect(ok).toBe(true);
         expect(finalizeCoAgentRunMock).toHaveBeenCalledTimes(1);
-        expect(finalizeCoAgentRunMock).toHaveBeenCalledWith('co-run-5', 'prompt-run-5', user, provider, true, null);
+        expect(finalizeCoAgentRunMock).toHaveBeenCalledWith(CO_RUN_ID, PROMPT_RUN_ID, user, provider, true, null);
     });
 
     it('threads the co-agent run-step id into finalize when the session config carries it', async () => {
@@ -247,11 +274,12 @@ describe('SessionManager.CloseSession', () => {
             Status: 'Active',
             Config_: JSON.stringify({
                 targetAgentID: 't1',
-                coAgentRunID: 'co-run-6',
-                promptRunID: 'prompt-run-6',
-                coAgentRunStepID: 'run-step-6',
+                coAgentRunID: CO_RUN_ID,
+                promptRunID: PROMPT_RUN_ID,
+                coAgentRunStepID: RUN_STEP_ID,
             }),
         });
+        mockSessionRunRecords([CO_RUN_ID], PROMPT_RUN_ID);
         const { provider } = makeProvider(() => session);
         const mgr = new SessionManager();
         const user = makeUser();
@@ -259,7 +287,7 @@ describe('SessionManager.CloseSession', () => {
         const ok = await mgr.CloseSession('session-voice-step', user, provider);
 
         expect(ok).toBe(true);
-        expect(finalizeCoAgentRunMock).toHaveBeenCalledWith('co-run-6', 'prompt-run-6', user, provider, true, 'run-step-6');
+        expect(finalizeCoAgentRunMock).toHaveBeenCalledWith(CO_RUN_ID, PROMPT_RUN_ID, user, provider, true, RUN_STEP_ID);
     });
 
     it('finalizes as the SYSTEM user when a scoped anonymous owner closes their session (issue #3371)', async () => {
@@ -274,8 +302,9 @@ describe('SessionManager.CloseSession', () => {
         const session = makeSessionEntity({
             ID: 'session-anon',
             Status: 'Active',
-            Config_: JSON.stringify({ targetAgentID: 't1', coAgentRunID: 'co-run-9', promptRunID: 'prompt-run-9' }),
+            Config_: JSON.stringify({ targetAgentID: 't1', coAgentRunID: CO_RUN_ID, promptRunID: PROMPT_RUN_ID }),
         });
+        mockSessionRunRecords([CO_RUN_ID], PROMPT_RUN_ID);
         const { provider } = makeProvider(() => session);
         const mgr = new SessionManager();
 
@@ -284,7 +313,7 @@ describe('SessionManager.CloseSession', () => {
         expect(ok).toBe(true);
         // The session-close writes themselves stay on the caller — only finalize elevates.
         expect(session.Status).toBe('Closed');
-        expect(finalizeCoAgentRunMock).toHaveBeenCalledWith('co-run-9', 'prompt-run-9', systemUser, provider, true, null);
+        expect(finalizeCoAgentRunMock).toHaveBeenCalledWith(CO_RUN_ID, PROMPT_RUN_ID, systemUser, provider, true, null);
     });
 
     it('FAILS CLOSED — finalizes as the anonymous caller when no system user is available', async () => {
@@ -297,14 +326,15 @@ describe('SessionManager.CloseSession', () => {
         const session = makeSessionEntity({
             ID: 'session-anon-2',
             Status: 'Active',
-            Config_: JSON.stringify({ targetAgentID: 't1', coAgentRunID: 'co-run-10', promptRunID: null }),
+            Config_: JSON.stringify({ targetAgentID: 't1', coAgentRunID: CO_RUN_ID, promptRunID: null }),
         });
+        mockSessionRunRecords([CO_RUN_ID]);
         const { provider } = makeProvider(() => session);
         const mgr = new SessionManager();
 
         await mgr.CloseSession('session-anon-2', anonUser, provider);
 
-        expect(finalizeCoAgentRunMock).toHaveBeenCalledWith('co-run-10', null, anonUser, provider, true, null);
+        expect(finalizeCoAgentRunMock).toHaveBeenCalledWith(CO_RUN_ID, null, anonUser, provider, true, null);
     });
 
     it('does not finalize when the session config has no run ids (target only)', async () => {
@@ -334,8 +364,9 @@ describe('SessionManager.CloseSession', () => {
         const session = makeSessionEntity({
             ID: 'session-injected',
             Status: 'Active',
-            Config_: JSON.stringify({ targetAgentID: 't1', coAgentRunID: 'co-run-injected', promptRunID: 'prompt-run-injected' }),
+            Config_: JSON.stringify({ targetAgentID: 't1', coAgentRunID: CO_RUN_ID, promptRunID: PROMPT_RUN_ID }),
         });
+        mockSessionRunRecords([CO_RUN_ID], PROMPT_RUN_ID);
         const { provider } = makeProvider(() => session);
         const mgr = new SessionManager(injectedService);
         const user = makeUser();
@@ -345,7 +376,7 @@ describe('SessionManager.CloseSession', () => {
         expect(ok).toBe(true);
         // The finalize call landed on the INJECTED instance, never the module-default one.
         expect(injectedFinalizeMock).toHaveBeenCalledTimes(1);
-        expect(injectedFinalizeMock).toHaveBeenCalledWith('co-run-injected', 'prompt-run-injected', user, provider, true, null);
+        expect(injectedFinalizeMock).toHaveBeenCalledWith(CO_RUN_ID, PROMPT_RUN_ID, user, provider, true, null);
         expect(finalizeCoAgentRunMock).not.toHaveBeenCalled();
     });
 
@@ -353,8 +384,9 @@ describe('SessionManager.CloseSession', () => {
         const session = makeSessionEntity({
             ID: 'session-default-svc',
             Status: 'Active',
-            Config_: JSON.stringify({ targetAgentID: 't1', coAgentRunID: 'co-run-default', promptRunID: 'prompt-run-default' }),
+            Config_: JSON.stringify({ targetAgentID: 't1', coAgentRunID: CO_RUN_ID, promptRunID: PROMPT_RUN_ID }),
         });
+        mockSessionRunRecords([CO_RUN_ID], PROMPT_RUN_ID);
         const { provider } = makeProvider(() => session);
         const mgr = new SessionManager(); // no injection — e.g. SessionJanitor, telephony services
         const user = makeUser();
@@ -362,7 +394,7 @@ describe('SessionManager.CloseSession', () => {
         const ok = await mgr.CloseSession('session-default-svc', user, provider);
 
         expect(ok).toBe(true);
-        expect(finalizeCoAgentRunMock).toHaveBeenCalledWith('co-run-default', 'prompt-run-default', user, provider, true, null);
+        expect(finalizeCoAgentRunMock).toHaveBeenCalledWith(CO_RUN_ID, PROMPT_RUN_ID, user, provider, true, null);
     });
 
     it('stamps CloseReason = Explicit by default (untouched call sites get the right reason)', async () => {
@@ -425,6 +457,79 @@ describe('SessionManager.CloseSession', () => {
     });
 });
 
+describe('SessionManager.CloseSessionForEndedBridge (a bridged agent left its room)', () => {
+    it.each([
+        ['Explicit', 'Explicit'],
+        ['HostEnded', 'Explicit'],
+        ['Error', 'Error'],
+        ['Janitor', 'Janitor'],
+        ['Shutdown', 'Shutdown'],
+    ] as const)('closes the session when its bridge ended with %s, stamping %s', async (bridgeReason, sessionReason) => {
+        const session = makeSessionEntity({ ID: 'session-bridged', Status: 'Active' });
+        const { provider } = makeProvider(() => session);
+        const mgr = new SessionManager();
+
+        const ok = await mgr.CloseSessionForEndedBridge('session-bridged', bridgeReason, makeUser(), provider);
+
+        expect(ok).toBe(true);
+        expect(session.Status).toBe('Closed');
+        expect(session.ClosedAt).toBeInstanceOf(Date);
+        expect(session.CloseReason).toBe(sessionReason);
+        // The same close the janitor runs: the channel plugins hear about it too.
+        expect(hostSessionClosedMock).toHaveBeenCalledWith('session-bridged', sessionReason);
+    });
+
+    it('keeps the reason of a session something else closed first (the janitor, the user)', async () => {
+        const session = makeSessionEntity({ ID: 'session-bridged', Status: 'Closed', CloseReason: 'Janitor' });
+        const { provider } = makeProvider(() => session);
+        const mgr = new SessionManager();
+
+        const ok = await mgr.CloseSessionForEndedBridge('session-bridged', 'Explicit', makeUser(), provider);
+
+        expect(ok).toBe(true);
+        expect(session.CloseReason).toBe('Janitor');
+        expect(session.Save).not.toHaveBeenCalled();
+    });
+
+    it('never throws: a close that fails is reported as not closed, leaving the session to the janitor', async () => {
+        const provider = {
+            GetEntityObject: vi.fn(async () => {
+                throw new Error('database unreachable');
+            }),
+        } as unknown as IMetadataProvider;
+        const mgr = new SessionManager();
+
+        await expect(mgr.CloseSessionForEndedBridge('session-bridged', 'Explicit', makeUser(), provider)).resolves.toBe(false);
+    });
+});
+
+describe('SessionManager.CloseSessionForFailedStart (an agent that never joined its room)', () => {
+    it('closes the session as Error, through the close the janitor runs', async () => {
+        const session = makeSessionEntity({ ID: 'session-unstarted', Status: 'Active' });
+        const { provider } = makeProvider(() => session);
+        const mgr = new SessionManager();
+
+        const ok = await mgr.CloseSessionForFailedStart('session-unstarted', makeUser(), provider);
+
+        expect(ok).toBe(true);
+        expect(session.Status).toBe('Closed');
+        expect(session.ClosedAt).toBeInstanceOf(Date);
+        expect(session.CloseReason).toBe('Error');
+        expect(hostSessionClosedMock).toHaveBeenCalledWith('session-unstarted', 'Error');
+    });
+
+    it('never throws: a close that fails is reported as not closed, leaving the session to the janitor', async () => {
+        const provider = {
+            GetEntityObject: vi.fn(async () => {
+                throw new Error('database unreachable');
+            }),
+        } as unknown as IMetadataProvider;
+        const mgr = new SessionManager();
+
+        await expect(mgr.CloseSessionForFailedStart('session-unstarted', makeUser(), provider)).resolves.toBe(false);
+    });
+});
+
 describe('SessionManager.Heartbeat', () => {
     it('coalesces writes within the min interval (one write, not two)', async () => {
         const session = makeSessionEntity({ ID: 'session-1', Status: 'Active' });
@@ -461,6 +566,36 @@ describe('SessionManager.Heartbeat', () => {
     });
 });
 
+describe('SessionManager.Heartbeat — the session\'s co-agent run stays alive', () => {
+    beforeEach(() => {
+        keepCoAgentRunAliveMock.mockClear();
+    });
+
+    it('keeps the co-agent run alive for the run watchdog on each persisted heartbeat', async () => {
+        const session = makeSessionEntity({ ID: 'session-1', Status: 'Active', Config_: JSON.stringify({ coAgentRunID: CO_RUN_ID, promptRunID: PROMPT_RUN_ID }) });
+        mockSessionRunRecords([CO_RUN_ID], PROMPT_RUN_ID);
+        const { provider } = makeProvider(() => session);
+        const mgr = new SessionManager();
+
+        await mgr.Heartbeat('session-1', makeUser(), provider);
+        await mgr.Heartbeat('session-1', makeUser(), provider); // coalesced: no write, no re-registration
+
+        expect(keepCoAgentRunAliveMock).toHaveBeenCalledOnce();
+        expect(keepCoAgentRunAliveMock.mock.calls[0][0]).toBe(CO_RUN_ID);
+        expect(keepCoAgentRunAliveMock.mock.calls[0][1]).toBe(provider);
+    });
+
+    it('does nothing for a closed session, and passes no run for a session without one', async () => {
+        const closed = makeSessionEntity({ ID: 'session-closed', Status: 'Closed', Config_: JSON.stringify({ coAgentRunID: 'co-run-1' }) });
+        await new SessionManager().Heartbeat('session-closed', makeUser(), makeProvider(() => closed).provider);
+        expect(keepCoAgentRunAliveMock).not.toHaveBeenCalled();
+
+        const workspace = makeSessionEntity({ ID: 'session-2', Status: 'Active', Config_: null });
+        await new SessionManager().Heartbeat('session-2', makeUser(), makeProvider(() => workspace).provider);
+        expect(keepCoAgentRunAliveMock.mock.calls[0][0]).toBeUndefined();
+    });
+});
+
 describe('SessionManager.Heartbeat — bounded heartbeatLastWrite (Round 11 memory-leak fix)', () => {
     // Regression coverage: heartbeatLastWrite used to be a plain, unbounded `Map`. SessionManager
     // is constructed fresh by every resolver that needs one (AgentSessionResolver,
@@ -626,3 +761,64 @@ describe('SessionManager — server-side channel plugin lifecycle notifications'
         expect(session.Status).toBe('Closed');
     });
 });
+
+// A session's Config is writable by its owner (generic CRUD on MJ: AI Agent Sessions), so the run
+// ids in it are acted on only when they are UUIDs of records that belong to the session.
+describe('SessionManager — run ids in the owner-writable session Config', () => {
+    const SESSION_ID = 'c3c3c3c3-1000-4000-8000-000000000001';
+    const FOREIGN_RUN_ID = 'c3c3c3c3-1000-4000-8000-0000000000f1';
+    const FOREIGN_PROMPT_RUN_ID = 'c3c3c3c3-1000-4000-8000-0000000000f2';
+    const FOREIGN_STEP_ID = 'c3c3c3c3-1000-4000-8000-0000000000f3';
+    /** Harmless text that is not a UUID and would change the meaning of a quoted filter. */
+    const NOT_A_UUID = "x' OR '1'='1";
+
+    function issuedFilters(): string[] {
+        return runViewMock.mock.calls.map(([params]) => (params as { ExtraFilter?: string }).ExtraFilter ?? '');
+    }
+
+    beforeEach(() => {
+        keepCoAgentRunAliveMock.mockClear();
+    });
+
+    it('CloseSession does not finalize run ids that are not records of the session', async () => {
+        const session = makeSessionEntity({
+            ID: SESSION_ID,
+            Status: 'Active',
+            Config_: JSON.stringify({
+                targetAgentID: 't1',
+                coAgentRunID: FOREIGN_RUN_ID,
+                promptRunID: FOREIGN_PROMPT_RUN_ID,
+                coAgentRunStepID: FOREIGN_STEP_ID,
+            }),
+        });
+        const { provider } = makeProvider(() => session);
+
+        await new SessionManager().CloseSession(SESSION_ID, makeUser(), provider);
+
+        expect(finalizeCoAgentRunMock).not.toHaveBeenCalled();
+    });
+
+    it('CloseSession does not finalize run ids that are not UUIDs, and never puts them in a filter', async () => {
+        const session = makeSessionEntity({
+            ID: SESSION_ID,
+            Status: 'Active',
+            Config_: JSON.stringify({ targetAgentID: 't1', coAgentRunID: NOT_A_UUID, promptRunID: NOT_A_UUID }),
+        });
+        const { provider } = makeProvider(() => session);
+
+        await new SessionManager().CloseSession(SESSION_ID, makeUser(), provider);
+
+        expect(finalizeCoAgentRunMock).not.toHaveBeenCalled();
+        expect(issuedFilters().filter((f) => f.includes(NOT_A_UUID))).toEqual([]);
+    });
+
+    it('Heartbeat does not keep alive a run that is not a record of the session', async () => {
+        const session = makeSessionEntity({ ID: SESSION_ID, Status: 'Active', Config_: JSON.stringify({ coAgentRunID: FOREIGN_RUN_ID }) });
+        const { provider } = makeProvider(() => session);
+
+        await new SessionManager().Heartbeat(SESSION_ID, makeUser(), provider);
+
+        expect(keepCoAgentRunAliveMock).toHaveBeenCalledOnce();
+        expect(keepCoAgentRunAliveMock.mock.calls[0][0]).toBeUndefined();
+    });
+});

package/src/__tests__/SessionRunIDVerifier.test.ts

@@ -0,0 +1,251 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import type { IMetadataProvider, RunViewParams, UserInfo } from '@memberjunction/core';
+import { UserCache } from '@memberjunction/generic-database-provider';
+import { SessionRunIDVerifier } from '../agentSessions/SessionRunIDVerifier.js';
+
+const SESSION_ID = 'd3d3d3d3-0000-4000-8000-000000000001';
+const CO_RUN_ID = 'd3d3d3d3-0000-4000-8000-000000000002';
+const PROMPT_RUN_ID = 'd3d3d3d3-0000-4000-8000-000000000003';
+const STEP_ID = 'd3d3d3d3-0000-4000-8000-000000000004';
+const PAUSED_RUN_ID = 'd3d3d3d3-0000-4000-8000-000000000005';
+const USER = { ID: 'd3d3d3d3-0000-4000-8000-0000000000aa' } as unknown as UserInfo;
+
+/** Rows each lookup returns, keyed by entity name. */
+type Rows = Record<string, Array<Record<string, unknown>>>;
+
+function makeProvider(rows: Rows, success = true): { provider: IMetadataProvider; runViews: ReturnType<typeof vi.fn> } {
+    const runViews = vi.fn(async (paramsList: RunViewParams[]) =>
+        paramsList.map((params) => ({
+            Success: success,
+            Results: success ? rows[params.EntityName ?? ''] ?? [] : [],
+            ErrorMessage: success ? '' : 'lookup failed',
+        })),
+    );
+    return { provider: { RunViews: runViews } as unknown as IMetadataProvider, runViews };
+}
+
+function issuedViews(runViews: ReturnType<typeof vi.fn>): RunViewParams[] {
+    return runViews.mock.calls.flatMap(([paramsList]) => paramsList as RunViewParams[]);
+}
+
+beforeEach(() => {
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+});
+
+afterEach(() => {
+    UserCache.Instance.SetUsers([]);
+});
+
+describe('SessionRunIDVerifier.Verify', () => {
+    it('keeps nothing, and runs no lookup, when no claim is a UUID', async () => {
+        const { provider, runViews } = makeProvider({});
+
+        const result = await new SessionRunIDVerifier().Verify(
+            SESSION_ID,
+            { CoAgentRunID: "x' OR '1'='1", PromptRunID: 'prompt-run-1', PendingFeedbackRunID: '' },
+            USER,
+            provider,
+        );
+
+        expect(result).toEqual({});
+        expect(runViews).not.toHaveBeenCalled();
+    });
+
+    it('looks up the claimed runs within the session and keeps only the ones it finds', async () => {
+        const { provider, runViews } = makeProvider({ 'MJ: AI Agent Runs': [{ ID: CO_RUN_ID }] });
+
+        const result = await new SessionRunIDVerifier().Verify(
+            SESSION_ID,
+            { CoAgentRunID: CO_RUN_ID, PendingFeedbackRunID: PAUSED_RUN_ID },
+            USER,
+            provider,
+        );
+
+        expect(result.CoAgentRunID).toBe(CO_RUN_ID);
+        expect(result.PendingFeedbackRunID).toBeUndefined();
+        const [runsView] = issuedViews(runViews);
+        expect(runsView.EntityName).toBe('MJ: AI Agent Runs');
+        expect(runsView.ExtraFilter).toBe(`AgentSessionID='${SESSION_ID}' AND ID IN ('${CO_RUN_ID}', '${PAUSED_RUN_ID}')`);
+        // No system user is cached here, so the lookup runs as the acting user.
+        expect(runViews.mock.calls[0][1]).toBe(USER);
+    });
+
+    it('runs the lookup as the system user when one is available', async () => {
+        // Row-level security can hide a session's own runs from its owner: a web-widget guest's
+        // delegated runs carry no ConversationID, so the guest's run filter does not match them.
+        const systemUser = { ID: UserCache.Instance.SYSTEM_USER_ID, Email: 'system@example.com' } as unknown as UserInfo;
+        UserCache.Instance.SetUsers([systemUser]);
+        const { provider, runViews } = makeProvider({ 'MJ: AI Agent Runs': [{ ID: PAUSED_RUN_ID }] });
+
+        const result = await new SessionRunIDVerifier().Verify(SESSION_ID, { PendingFeedbackRunID: PAUSED_RUN_ID }, USER, provider);
+
+        expect(result.PendingFeedbackRunID).toBe(PAUSED_RUN_ID);
+        expect(runViews.mock.calls[0][1]).toBe(systemUser);
+    });
+
+    it('keeps the prompt run and step that belong to the session\'s co-agent run', async () => {
+        const { provider, runViews } = makeProvider({
+            'MJ: AI Agent Runs': [{ ID: CO_RUN_ID }],
+            'MJ: AI Agent Run Steps': [{ ID: STEP_ID, StepType: 'Prompt', TargetLogID: PROMPT_RUN_ID }],
+        });
+
+        const result = await new SessionRunIDVerifier().Verify(
+            SESSION_ID,
+            { CoAgentRunID: CO_RUN_ID, PromptRunID: PROMPT_RUN_ID, CoAgentRunStepID: STEP_ID },
+            USER,
+            provider,
+        );
+
+        expect(result).toEqual({ CoAgentRunID: CO_RUN_ID, PromptRunID: PROMPT_RUN_ID, CoAgentRunStepID: STEP_ID, PendingFeedbackRunID: undefined });
+        const stepsView = issuedViews(runViews).find((view) => view.EntityName === 'MJ: AI Agent Run Steps');
+        expect(stepsView?.ExtraFilter).toBe(`AgentRunID='${CO_RUN_ID}' AND (ID='${STEP_ID}' OR TargetLogID='${PROMPT_RUN_ID}')`);
+    });
+
+    it('drops a prompt run that is the target of a step other than a Prompt step', async () => {
+        const { provider } = makeProvider({
+            'MJ: AI Agent Runs': [{ ID: CO_RUN_ID }],
+            'MJ: AI Agent Run Steps': [{ ID: STEP_ID, StepType: 'Tool', TargetLogID: PROMPT_RUN_ID }],
+        });
+
+        const result = await new SessionRunIDVerifier().Verify(SESSION_ID, { CoAgentRunID: CO_RUN_ID, PromptRunID: PROMPT_RUN_ID }, USER, provider);
+
+        expect(result.PromptRunID).toBeUndefined();
+    });
+
+    it('drops the prompt run and step when the co-agent run is not the session\'s', async () => {
+        const { provider } = makeProvider({
+            'MJ: AI Agent Runs': [],
+            'MJ: AI Agent Run Steps': [{ ID: STEP_ID, StepType: 'Prompt', TargetLogID: PROMPT_RUN_ID }],
+        });
+
+        const result = await new SessionRunIDVerifier().Verify(
+            SESSION_ID,
+            { CoAgentRunID: CO_RUN_ID, PromptRunID: PROMPT_RUN_ID, CoAgentRunStepID: STEP_ID },
+            USER,
+            provider,
+        );
+
+        expect(result).toEqual({ CoAgentRunID: undefined, PromptRunID: undefined, CoAgentRunStepID: undefined, PendingFeedbackRunID: undefined });
+    });
+
+    it('matches ids case-insensitively', async () => {
+        const { provider } = makeProvider({ 'MJ: AI Agent Runs': [{ ID: PAUSED_RUN_ID.toUpperCase() }] });
+
+        const result = await new SessionRunIDVerifier().Verify(SESSION_ID, { PendingFeedbackRunID: PAUSED_RUN_ID }, USER, provider);
+
+        expect(result.PendingFeedbackRunID).toBe(PAUSED_RUN_ID);
+    });
+
+    it('looks up the same claims again on every call', async () => {
+        const { provider, runViews } = makeProvider({ 'MJ: AI Agent Runs': [{ ID: CO_RUN_ID }] });
+        const verifier = new SessionRunIDVerifier();
+
+        await verifier.Verify(SESSION_ID, { CoAgentRunID: CO_RUN_ID }, USER, provider);
+        const second = await verifier.Verify(SESSION_ID, { CoAgentRunID: CO_RUN_ID }, USER, provider);
+
+        expect(second.CoAgentRunID).toBe(CO_RUN_ID);
+        expect(runViews).toHaveBeenCalledTimes(2);
+    });
+
+    it('reads the runs and steps from the database, not from a cached view', async () => {
+        const { provider, runViews } = makeProvider({ 'MJ: AI Agent Runs': [{ ID: CO_RUN_ID }] });
+
+        await new SessionRunIDVerifier().Verify(SESSION_ID, { CoAgentRunID: CO_RUN_ID, PromptRunID: PROMPT_RUN_ID }, USER, provider);
+
+        const views = issuedViews(runViews);
+        expect(views.map((view) => view.EntityName)).toEqual(['MJ: AI Agent Runs', 'MJ: AI Agent Run Steps']);
+        expect(views.every((view) => view.BypassCache === true)).toBe(true);
+    });
+
+    it('keeps nothing when a lookup fails, and looks up again next time', async () => {
+        const { provider, runViews } = makeProvider({}, false);
+        const verifier = new SessionRunIDVerifier();
+
+        const first = await verifier.Verify(SESSION_ID, { CoAgentRunID: CO_RUN_ID }, USER, provider);
+        await verifier.Verify(SESSION_ID, { CoAgentRunID: CO_RUN_ID }, USER, provider);
+
+        expect(first).toEqual({});
+        expect(runViews).toHaveBeenCalledTimes(2);
+    });
+
+    it('keeps nothing, without throwing, when the provider throws', async () => {
+        const provider = { RunViews: vi.fn(async () => { throw new Error('connection lost'); }) } as unknown as IMetadataProvider;
+
+        await expect(new SessionRunIDVerifier().Verify(SESSION_ID, { CoAgentRunID: CO_RUN_ID }, USER, provider)).resolves.toEqual({});
+    });
+});
+
+/**
+ * A run's `AgentSessionID` and a step's `AgentRunID` and `TargetLogID` can change after a lookup (the
+ * generated update mutations accept them), so each call must decide from what the rows say now.
+ */
+describe('SessionRunIDVerifier.Verify — relationships that change between calls', () => {
+    const CLAIMS = { CoAgentRunID: CO_RUN_ID, PromptRunID: PROMPT_RUN_ID, CoAgentRunStepID: STEP_ID, PendingFeedbackRunID: PAUSED_RUN_ID };
+
+    /** Both runs are records of the session, and the step is the co-agent run's Prompt step for the prompt run. */
+    function linkedRows(): Rows {
+        return {
+            'MJ: AI Agent Runs': [{ ID: CO_RUN_ID }, { ID: PAUSED_RUN_ID }],
+            'MJ: AI Agent Run Steps': [{ ID: STEP_ID, StepType: 'Prompt', TargetLogID: PROMPT_RUN_ID }],
+        };
+    }
+
+    it('drops runs that stopped being records of the session since the last call', async () => {
+        const rows = linkedRows();
+        const { provider } = makeProvider(rows);
+        const verifier = new SessionRunIDVerifier();
+        const first = await verifier.Verify(SESSION_ID, CLAIMS, USER, provider);
+
+        // The runs were moved to another session, unlinked or deleted.
+        rows['MJ: AI Agent Runs'] = [];
+        const second = await verifier.Verify(SESSION_ID, CLAIMS, USER, provider);
+
+        expect(first).toEqual(CLAIMS);
+        expect(second).toEqual({ CoAgentRunID: undefined, PromptRunID: undefined, CoAgentRunStepID: undefined, PendingFeedbackRunID: undefined });
+    });
+
+    it('drops the prompt run and step once the step is no longer linked to the co-agent run', async () => {
+        const rows = linkedRows();
+        const { provider } = makeProvider(rows);
+        const verifier = new SessionRunIDVerifier();
+        const first = await verifier.Verify(SESSION_ID, CLAIMS, USER, provider);
+
+        rows['MJ: AI Agent Run Steps'] = [];
+        const second = await verifier.Verify(SESSION_ID, CLAIMS, USER, provider);
+
+        expect(first).toEqual(CLAIMS);
+        expect(second).toEqual({ ...CLAIMS, PromptRunID: undefined, CoAgentRunStepID: undefined });
+    });
+
+    it('still keeps a relationship that has not changed on the next call', async () => {
+        const { provider } = makeProvider(linkedRows());
+        const verifier = new SessionRunIDVerifier();
+
+        await verifier.Verify(SESSION_ID, CLAIMS, USER, provider);
+        const second = await verifier.Verify(SESSION_ID, CLAIMS, USER, provider);
+
+        expect(second).toEqual(CLAIMS);
+    });
+});
+
+describe('SessionRunIDVerifier.Verify — lookups as the acting user', () => {
+    it('does not give a user the result of a lookup made for another user', async () => {
+        // No system user is cached, so each lookup runs as the acting user, and only USER can see the run.
+        const otherUser = { ID: 'd3d3d3d3-0000-4000-8000-0000000000bb' } as unknown as UserInfo;
+        const runViews = vi.fn(async (paramsList: RunViewParams[], user: UserInfo) =>
+            paramsList.map((params) => {
+                const visible = user === USER && params.EntityName === 'MJ: AI Agent Runs';
+                return { Success: true, Results: visible ? [{ ID: CO_RUN_ID }] : [], ErrorMessage: '' };
+            }),
+        );
+        const provider = { RunViews: runViews } as unknown as IMetadataProvider;
+        const verifier = new SessionRunIDVerifier();
+
+        const forUser = await verifier.Verify(SESSION_ID, { CoAgentRunID: CO_RUN_ID }, USER, provider);
+        const forOtherUser = await verifier.Verify(SESSION_ID, { CoAgentRunID: CO_RUN_ID }, otherUser, provider);
+
+        expect(forUser.CoAgentRunID).toBe(CO_RUN_ID);
+        expect(forOtherUser.CoAgentRunID).toBeUndefined();
+        expect(runViews.mock.calls[1]?.[1]).toBe(otherUser);
+    });
+});