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

package/src/__tests__/SessionJanitor.test.ts

@@ -81,6 +81,8 @@ interface FakeSession {
     LatestResult?: { CompleteMessage?: string };
     ClosedAt?: Date | null;
     CloseReason?: string | null;
+    Config_?: string | null;
+    LastActiveAt?: Date | string | null;
 }
 
 function makeUser(): UserInfo {
@@ -111,6 +113,10 @@ function makeProvider(store: Map<string, 'Active' | 'Idle' | 'Closed'>): {
                     if (status == null) return false;
                     entity.ID = id;
                     entity.Status = status;
+                    // CloseSession verifies a TimeLimit against the loaded row's stored deadline, so the
+                    // fake row carries the swept row's Config_ like the real table row does.
+                    entity.Config_ = sweptRows.get(id)?.Config_ ?? null;
+                    entity.LastActiveAt = sweptRows.get(id)?.LastActiveAt ?? null;
                     return true;
                 }),
                 Save: vi.fn(async () => {
@@ -130,6 +136,9 @@ function makeProvider(store: Map<string, 'Active' | 'Idle' | 'Closed'>): {
     return { provider, closedIds, closedReasons };
 }
 
+/** Config_/LastActiveAt of rows a test swept, by session ID: sessionPages is consumed by the sweep before CloseSession loads the row. */
+const sweptRows = new Map<string, { Config_?: string | null; LastActiveAt?: Date | string | null }>();
+
 /**
  * Queue of result-sets for the *session* sweep pages (entity 'MJ: AI Agent Sessions'). Channel
  * sweeps (entity 'MJ: AI Agent Session Channels', issued by CloseSession) always resolve empty so
@@ -145,6 +154,7 @@ function sessionSweepCalls(): Array<[{ EntityName: string; ExtraFilter: string;
 }
 
 beforeEach(() => {
+    sweptRows.clear();
     runViewMock.mockReset();
     logErrorMock.mockReset();
     logStatusMock.mockReset();
@@ -292,9 +302,114 @@ describe('SessionJanitor.RunStartupRecovery with two MJAPIs on one host (#5309)'
     });
 });
 
+/** An ISO moment `minutes` before now, for a row's `LastActiveAt` / deadline. */
+function minutesAgo(minutes: number): string {
+    return new Date(Date.now() - minutes * 60_000).toISOString();
+}
+
+/** Config_ JSON carrying an authored hard deadline `minutes` from now (negative = already passed). */
+function deadlineConfig(minutesFromNow: number): string {
+    return JSON.stringify({ maxSessionDeadlineIso: new Date(Date.now() + minutesFromNow * 60_000).toISOString() });
+}
+
+describe('SessionJanitor close reasons (#6182): sweeps stamp TimeLimit / Idle via ExpiryCloseReason', () => {
+    // Idle threshold is 15 min (the janitor default); each row below is placed relative to it.
+    beforeEach(() => {
+        SessionJanitor.Instance.Configure({ closeThresholdMinutes: 15 });
+    });
+
+    async function runSweep(
+        sweep: 'RunStalenessSweep' | 'RunMaxDurationSweep',
+        row: Record<string, unknown>,
+    ): Promise<{ count: number; reason: string | null | undefined; closed: boolean }> {
+        const id = row.ID as string;
+        sweptRows.set(id, { Config_: row.Config_ as string | null, LastActiveAt: row.LastActiveAt as Date | string | null });
+        sessionPages = [{ Success: true, Results: [row] }];
+        const { provider, closedIds, closedReasons } = makeProvider(new Map([[id, 'Active']]));
+        const count = await SessionJanitor.Instance[sweep](provider, makeUser());
+        return { count, reason: closedReasons.get(id), closed: closedIds.includes(id) };
+    }
+
+    it('the staleness sweep stamps Idle for a quiet row without a deadline', async () => {
+        const r = await runSweep('RunStalenessSweep', { ID: 'q1', Status: 'Active', LastActiveAt: minutesAgo(60), Config_: null });
+        expect(r.reason).toBe('Idle');
+    });
+
+    it('the max-duration sweep stamps TimeLimit for an expired row', async () => {
+        const r = await runSweep('RunMaxDurationSweep', {
+            ID: 'd1', Status: 'Active', LastActiveAt: minutesAgo(1), Config_: deadlineConfig(-5),
+        });
+        expect(r.reason).toBe('TimeLimit');
+    });
+
+    it('the idle sweep stamps TimeLimit when the deadline came first', async () => {
+        // Idle moment = 60-15 = 45 min ago; deadline 50 min ago is earlier.
+        const r = await runSweep('RunStalenessSweep', {
+            ID: 'both1', Status: 'Active', LastActiveAt: minutesAgo(60), Config_: deadlineConfig(-50),
+        });
+        expect(r.reason).toBe('TimeLimit');
+    });
+
+    it('the deadline sweep stamps Idle when the idle moment came first', async () => {
+        // Idle moment = 60-15 = 45 min ago; deadline 5 min ago is later.
+        const r = await runSweep('RunMaxDurationSweep', {
+            ID: 'both2', Status: 'Active', LastActiveAt: minutesAgo(60), Config_: deadlineConfig(-5),
+        });
+        expect(r.reason).toBe('Idle');
+    });
+
+    /*
+     * The SQL already judged this row stale (LastActiveAt < cutoff), so an unparseable LastActiveAt
+     * must not make it immortal: it closes as Idle, and the fallback is logged with the session ID.
+     */
+    it('the staleness sweep closes a stale row with an unparseable LastActiveAt as Idle and LogErrors the fallback', async () => {
+        logErrorMock.mockClear();
+        const r = await runSweep('RunStalenessSweep', { ID: 'garbled1', Status: 'Active', LastActiveAt: 'not-a-date', Config_: null });
+        expect(r.closed).toBe(true);
+        expect(r.reason).toBe('Idle');
+        const messages = logErrorMock.mock.calls.map((c) => String(c[0]));
+        expect(messages.some((m) => m.includes('garbled1') && m.includes('LastActiveAt unparseable; closing as Idle'))).toBe(true);
+    });
+
+    it('the staleness sweep does not LogError for a row ExpiryCloseReason decides', async () => {
+        logErrorMock.mockClear();
+        await runSweep('RunStalenessSweep', { ID: 'q2', Status: 'Active', LastActiveAt: minutesAgo(60), Config_: null });
+        expect(logErrorMock).not.toHaveBeenCalled();
+    });
+
+    it('skips rows the callback returns null for, without loading their channels', async () => {
+        const row = { ID: 'future1', Status: 'Active', LastActiveAt: minutesAgo(1), Config_: deadlineConfig(30) };
+        sessionPages = [{ Success: true, Results: [row] }];
+        const { provider, closedIds } = makeProvider(new Map([['future1', 'Active']]));
+
+        const count = await SessionJanitor.Instance.RunMaxDurationSweep(provider, makeUser());
+
+        expect(count).toBe(0);
+        expect(closedIds).toEqual([]);
+        const channelReads = runViewMock.mock.calls.filter(
+            (c) => (c[0] as { EntityName: string }).EntityName === 'MJ: AI Agent Session Channels',
+        );
+        expect(channelReads).toHaveLength(0);
+    });
+
+    it('startup recovery still stamps Janitor and the shutdown drain Shutdown', async () => {
+        const ours = GetCurrentHostInstance();
+        const orphan = { ID: 'orphan1', Status: 'Active', HostInstanceID: `${ours.GetInstancePrefix()}31337:boot-before` };
+        sessionPages = [{ Success: true, Results: [orphan] }];
+        const recovery = makeProvider(new Map([['orphan1', 'Active']]));
+        await SessionJanitor.Instance.RunStartupRecovery(recovery.provider, makeUser());
+        expect(recovery.closedReasons.get('orphan1')).toBe('Janitor');
+
+        sessionPages = [{ Success: true, Results: [{ ID: 'live1', Status: 'Active' }] }];
+        const drain = makeProvider(new Map([['live1', 'Active']]));
+        await SessionJanitor.Instance.RunShutdownDrain(drain.provider, makeUser());
+        expect(drain.closedReasons.get('live1')).toBe('Shutdown');
+    });
+});
+
 describe('SessionJanitor.RunStalenessSweep', () => {
     it('closes only past-threshold sessions (filter is staleness-scoped)', async () => {
-        const stale = { ID: 'stale-1', Status: 'Idle' };
+        const stale = { ID: 'stale-1', Status: 'Idle', LastActiveAt: minutesAgo(60) };
         sessionPages = [{ Success: true, Results: [stale] }];
 
         const store = new Map<string, 'Active' | 'Idle' | 'Closed'>([['stale-1', 'Idle']]);
@@ -304,8 +419,8 @@ describe('SessionJanitor.RunStalenessSweep', () => {
 
         expect(count).toBe(1);
         expect(closedIds).toContain('stale-1');
-        // Staleness sweep stamps the janitor close cause.
-        expect(closedReasons.get('stale-1')).toBe('Janitor');
+        // A quiet row without a deadline closes as Idle.
+        expect(closedReasons.get('stale-1')).toBe('Idle');
 
         const filter = sessionSweepCalls()[0][0].ExtraFilter as string;
         expect(filter).toContain("Status IN ('Active','Idle')");
@@ -313,7 +428,7 @@ describe('SessionJanitor.RunStalenessSweep', () => {
     });
 
     it('is idempotent — re-closing already-Closed rows is a harmless no-op', async () => {
-        const alreadyClosed = { ID: 'done-1', Status: 'Closed' };
+        const alreadyClosed = { ID: 'done-1', Status: 'Closed', LastActiveAt: minutesAgo(60) };
         sessionPages = [{ Success: true, Results: [alreadyClosed] }];
 
         const store = new Map<string, 'Active' | 'Idle' | 'Closed'>([['done-1', 'Closed']]);
@@ -1414,3 +1529,79 @@ describe('SessionJanitor.Configure', () => {
         expect(sessionSweepCalls()).toHaveLength(0);
     });
 });
+
+describe('SessionJanitor.StartWithSettings (agentSessions.janitor)', () => {
+    const HOUR = 60 * 60_000;
+    const DEFAULTS = { enabled: true, sweepIntervalMs: 60_000, closeThresholdMinutes: 15 };
+
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        SessionJanitor.Instance.Stop();
+        SessionJanitor.Instance.Configure({ sweepIntervalMs: DEFAULTS.sweepIntervalMs, closeThresholdMinutes: DEFAULTS.closeThresholdMinutes });
+        vi.clearAllTimers();
+        vi.useRealTimers();
+    });
+
+    it('enabled: runs startup recovery, then ticks on the configured interval with the configured threshold', async () => {
+        const { provider } = makeProvider(new Map());
+        await SessionJanitor.Instance.StartWithSettings({ ...DEFAULTS, sweepIntervalMs: 120_000, closeThresholdMinutes: 30 }, provider, makeUser());
+        expect(sessionSweepCalls()).toHaveLength(1); // startup recovery
+        expect(SessionJanitor.Instance.IsSweepScheduled).toBe(true);
+
+        vi.setSystemTime(new Date('2026-10-29T12:00:00.000Z'));
+        await vi.advanceTimersByTimeAsync(120_000);
+
+        const staleness = sessionSweepCalls().map(c => c[0].ExtraFilter).find(f => f.includes('LastActiveAt <'));
+        expect(staleness).toBeTruthy();
+        // 30 minutes before the tick, not the default 15.
+        expect(staleness).toContain('2026-10-29T11:32:00.000Z');
+    });
+
+    it('disabled: runs startup recovery once and then issues no queries at all', async () => {
+        const { provider } = makeProvider(new Map());
+        await SessionJanitor.Instance.StartWithSettings({ ...DEFAULTS, enabled: false }, provider, makeUser());
+        expect(sessionSweepCalls()).toHaveLength(1);
+        runViewMock.mockClear();
+
+        await vi.advanceTimersByTimeAsync(HOUR);
+
+        expect(runViewMock).not.toHaveBeenCalled();
+        expect(ledgerMock.PurgeClosedBefore).not.toHaveBeenCalled();
+        expect(SessionJanitor.Instance.IsSweepScheduled).toBe(false);
+    });
+
+    it('disabled: still drains this host\'s live sessions on graceful shutdown', async () => {
+        sessionPages = [
+            { Success: true, Results: [] },                                   // startup recovery
+            { Success: true, Results: [{ ID: 'mine-3', Status: 'Active' }] }, // shutdown drain
+        ];
+        const store = new Map<string, 'Active' | 'Idle' | 'Closed'>([['mine-3', 'Active']]);
+        const { provider, closedIds, closedReasons } = makeProvider(store);
+
+        await SessionJanitor.Instance.StartWithSettings({ ...DEFAULTS, enabled: false }, provider, makeUser());
+        await SessionJanitor.Instance.Shutdown();
+
+        expect(closedIds).toContain('mine-3');
+        expect(closedReasons.get('mine-3')).toBe('Shutdown');
+    });
+
+    it('disabled after an earlier Start stops the tick that Start scheduled', async () => {
+        const { provider } = makeProvider(new Map());
+        await SessionJanitor.Instance.Start(provider, makeUser());
+        expect(SessionJanitor.Instance.IsSweepScheduled).toBe(true);
+
+        await SessionJanitor.Instance.StartWithSettings({ ...DEFAULTS, enabled: false }, provider, makeUser());
+
+        expect(SessionJanitor.Instance.IsSweepScheduled).toBe(false);
+    });
+
+    it('rejects an invalid interval before doing any work', async () => {
+        const { provider } = makeProvider(new Map());
+        await expect(SessionJanitor.Instance.StartWithSettings({ ...DEFAULTS, sweepIntervalMs: 0 }, provider, makeUser()))
+            .rejects.toThrow(/sweepIntervalMs must be a finite number greater than 0/);
+        expect(sessionSweepCalls()).toHaveLength(0);
+        expect(SessionJanitor.Instance.IsSweepScheduled).toBe(false);
+    });
+});

package/src/__tests__/SessionManager.test.ts

@@ -42,10 +42,12 @@ vi.mock('../realtimeSessions/RecordingAssemblyScheduler.js', () => ({
 // --- 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();
+const logStatusMock = vi.fn();
 vi.mock('@memberjunction/core', async (importOriginal) => {
     const actual = await importOriginal<typeof import('@memberjunction/core')>();
     return {
         ...actual,
+        LogStatus: (...args: unknown[]) => logStatusMock(...args),
         RunView: {
             FromMetadataProvider: () => ({
                 RunView: runViewMock,
@@ -71,6 +73,7 @@ vi.mock('@memberjunction/generic-database-provider', async (importOriginal) => {
 });
 
 import { SessionManager, SessionAuthorizationError } from '../agentSessions/SessionManager.js';
+import { IsTrustedSessionConfigWriteActive } from '@memberjunction/core-entities-server';
 import type { UserInfo, IMetadataProvider } from '@memberjunction/core';
 
 /** Minimal fake BaseEntity-shaped record with the fields/methods SessionManager touches. */
@@ -336,6 +339,24 @@ describe('SessionManager.CreateSession', () => {
 });
 
 describe('SessionManager.CloseSession', () => {
+    // The session entity refuses a server-only CloseReason (TimeLimit, Idle, Janitor, Shutdown) from an untrusted save,
+    // so the one server path that stamps it must save inside the trusted session-write scope.
+    it('stamps the close reason inside the trusted session-write scope', async () => {
+        runViewMock.mockResolvedValue({ Success: true, Results: [] });
+        let trustedAtSave: boolean | null = null;
+        const session = makeSessionEntity({ ID: 'session-1', Status: 'Active' });
+        session.Save = vi.fn(async () => {
+            trustedAtSave = IsTrustedSessionConfigWriteActive();
+            return true;
+        });
+        const { provider } = makeProvider(() => session);
+
+        expect(await new SessionManager().CloseSession('session-1', makeUser(), provider, 'Janitor')).toBe(true);
+
+        expect(session.CloseReason).toBe('Janitor');
+        expect(trustedAtSave).toBe(true);
+    });
+
     it('sets Closed + ClosedAt, disconnects channels', async () => {
         const channel = makeSessionEntity({ ID: 'chan-1', Status: 'Connected' });
         runViewMock.mockResolvedValue({ Success: true, Results: [channel] });
@@ -529,6 +550,54 @@ describe('SessionManager.CloseSession', () => {
         },
     );
 
+    describe('a TimeLimit close is verified against the stored deadline', () => {
+        beforeEach(() => logStatusMock.mockClear());
+
+        it('is downgraded to Explicit and logged when the stored deadline is far away', async () => {
+            const deadline = new Date(Date.now() + 10 * 60_000).toISOString();
+            const session = makeSessionEntity({ ID: 'session-far', Status: 'Active', Config_: JSON.stringify({ maxSessionDeadlineIso: deadline }) });
+            const { provider } = makeProvider(() => session);
+
+            const ok = await new SessionManager().CloseSession('session-far', makeUser(), provider, 'TimeLimit');
+
+            expect(ok).toBe(true);
+            expect(session.CloseReason).toBe('Explicit');
+            const logged = logStatusMock.mock.calls.map((c) => String(c[0])).join('\n');
+            expect(logged).toContain('session-far');
+            expect(logged).toContain(deadline);
+        });
+
+        it('is stamped TimeLimit when the stored deadline has passed', async () => {
+            const deadline = new Date(Date.now() - 1_000).toISOString();
+            const session = makeSessionEntity({ ID: 'session-due', Status: 'Active', Config_: JSON.stringify({ maxSessionDeadlineIso: deadline }) });
+            const { provider } = makeProvider(() => session);
+
+            await new SessionManager().CloseSession('session-due', makeUser(), provider, 'TimeLimit');
+
+            expect(session.CloseReason).toBe('TimeLimit');
+            expect(logStatusMock).not.toHaveBeenCalled();
+        });
+
+        it('tells channel plugins the verified reason: Explicit for a downgraded claim, TimeLimit for a backed one', async () => {
+            const far = makeSessionEntity({ ID: 'session-far2', Status: 'Active', Config_: JSON.stringify({ maxSessionDeadlineIso: new Date(Date.now() + 10 * 60_000).toISOString() }) });
+            await new SessionManager().CloseSession('session-far2', makeUser(), makeProvider(() => far).provider, 'TimeLimit');
+            expect(hostSessionClosedMock).toHaveBeenLastCalledWith('session-far2', 'Explicit');
+
+            const due = makeSessionEntity({ ID: 'session-due2', Status: 'Active', Config_: JSON.stringify({ maxSessionDeadlineIso: new Date(Date.now() - 1_000).toISOString() }) });
+            await new SessionManager().CloseSession('session-due2', makeUser(), makeProvider(() => due).provider, 'TimeLimit');
+            expect(hostSessionClosedMock).toHaveBeenLastCalledWith('session-due2', 'TimeLimit');
+        });
+
+        it('is downgraded to Explicit when the session stores no deadline', async () => {
+            const session = makeSessionEntity({ ID: 'session-none', Status: 'Active', Config_: null });
+            const { provider } = makeProvider(() => session);
+
+            await new SessionManager().CloseSession('session-none', makeUser(), provider, 'TimeLimit');
+
+            expect(session.CloseReason).toBe('Explicit');
+        });
+    });
+
     it('does not overwrite the original CloseReason on an idempotent re-close', async () => {
         const session = makeSessionEntity({ ID: 'session-1', Status: 'Closed', CloseReason: 'Janitor' });
         const { provider } = makeProvider(() => session);

package/src/__tests__/TaskGraphActionRunner.durablePayload.test.ts

@@ -170,7 +170,7 @@ describe('TaskGraphActionRunner: outputs must be storable', () => {
         expect(result).toMatchObject({ Success: true, Output: { AgentRunID: 'RUN-1' }, ActionLogID: 'LOG-2' });
     });
 
-    it('merges structured JSON Message properties into Output and aliases handle/Handle', async () => {
+    it('merges structured JSON Message properties into Output without synthesizing handle/Handle aliases', async () => {
         vi.mocked(ActionEngineServer.Instance.RunAction).mockResolvedValue({
             Success: true,
             Message: JSON.stringify({
@@ -188,10 +188,10 @@ describe('TaskGraphActionRunner: outputs must be storable', () => {
         expect(result.Success).toBe(true);
         expect(result.Output).toMatchObject({
             handle: 'doc-handle-99',
-            Handle: 'doc-handle-99',
             documentType: 'pdf',
             fileName: 'Sales_Demo_Report.pdf',
         });
+        expect(result.Output).not.toHaveProperty('Handle');
     });
 });