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

package/src/__tests__/TaskGraphAgentRunner.test.ts

@@ -1,19 +1,54 @@
 /**
- * Tests for `TaskGraphAgentRunner`.
- *
- * Verifies that when a task node in a durable task graph executes a specialist agent
- * (such as Query Builder or Research Report Writer) and finishes with a payload,
- * the runner resolves the originating `ConversationDetailID` and persists artifacts
- * via `AgentRunner.ProcessAgentArtifacts`.
+ * Tests for `TaskGraphAgentRunner`:
+ * - VS-CON-7 preset resolution (`ConfigurationPresetName`)
+ * - VS-INV-2b / VS-QA-3 #9 `parentAgentHierarchy` from submitted task
+ * - Specialist agent artifact persistence (`ProcessAgentArtifacts`), `CanUserRunAgent` permission check,
+ *   task Name/Description prompt formatting, and output normalization.
  */
 import 'reflect-metadata';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import type { TaskAgentRunParams } from '@memberjunction/task-graph';
 
-vi.mock('@memberjunction/core', () => ({
-    LogError: vi.fn(),
-    LogStatus: vi.fn(),
+const {
+    runAgent,
+    processAgentArtifacts,
+    canUserRunAgent,
+    mockEngineAgents,
+    mockGetAgentConfigurationPresets,
+    mockEngineConfig,
+    mockRunView,
+    mockLogError,
+} = vi.hoisted(() => ({
+    runAgent: vi.fn(),
+    processAgentArtifacts: vi.fn(),
+    canUserRunAgent: vi.fn().mockResolvedValue(true),
+    mockEngineAgents: [
+        { ID: 'agent-1', Name: 'Storyboard Artist' },
+        { ID: 'qb-agent' },
+        { ID: 'writer-agent' },
+    ] as Array<{ ID: string; Name?: string }>,
+    mockGetAgentConfigurationPresets: vi.fn(),
+    mockEngineConfig: vi.fn(),
+    mockRunView: vi.fn(),
+    mockLogError: vi.fn(),
 }));
 
+const mockRunAgent = runAgent;
+
+vi.mock('@memberjunction/core', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@memberjunction/core')>();
+    return {
+        ...actual,
+        LogError: (...args: unknown[]) => mockLogError(...args),
+        LogStatus: vi.fn(),
+        RunView: class {
+            static FromMetadataProvider = () => ({ RunView: mockRunView });
+            RunView = mockRunView;
+        },
+    };
+});
+
 vi.mock('@memberjunction/generic-database-provider', () => ({
     UserCache: {
         Instance: { Users: [] },
@@ -31,31 +66,251 @@ vi.mock('@memberjunction/ai-core-plus', () => ({
 }));
 vi.mock('@memberjunction/ai', () => ({ ChatMessageRole: { user: 'user' } }));
 
-const { runAgent, processAgentArtifacts, canUserRunAgent, mockEngineAgents } = vi.hoisted(() => ({
-    runAgent: vi.fn(),
-    processAgentArtifacts: vi.fn(),
-    canUserRunAgent: vi.fn().mockResolvedValue(true),
-    mockEngineAgents: [{ ID: 'qb-agent' }, { ID: 'writer-agent' }] as Array<{ ID: string }>,
-}));
 vi.mock('@memberjunction/ai-agents', () => ({
     AgentRunner: class {
         RunAgent = runAgent;
         ProcessAgentArtifacts = processAgentArtifacts;
     },
 }));
+
 vi.mock('@memberjunction/aiengine', () => ({
     AIEngine: {
         get Instance() {
             return {
+                Config: mockEngineConfig,
                 Agents: mockEngineAgents,
                 CanUserRunAgent: canUserRunAgent,
+                GetAgentConfigurationPresets: mockGetAgentConfigurationPresets,
+                FindActiveAgentConfigurationPreset: (agentId: string, presetName: string) => {
+                    const target = presetName.trim().toLowerCase();
+                    if (!target) return undefined;
+                    const presets = (mockGetAgentConfigurationPresets(agentId, true) ?? []) as Array<{
+                        Name?: string;
+                        DisplayName?: string;
+                    }>;
+                    return presets.find((p) => p.Name?.trim().toLowerCase() === target)
+                        ?? presets.find((p) => p.DisplayName?.trim().toLowerCase() === target);
+                },
             };
         },
     },
 }));
 
 import { TaskGraphAgentRunner } from '../services/TaskGraphAgentRunner';
-import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
+
+interface SubmittingRunOverrides {
+    ID?: string;
+    ConfigurationID?: string | null;
+    Agent?: string | null;
+    AgentID?: string | null;
+    ParentRunID?: string | null;
+    LoadSuccess?: boolean;
+}
+
+function makeParams(
+    overrides: Partial<TaskAgentRunParams> = {},
+    parentConfigurationID: string | null = 'parent-cfg-1',
+    submittingRunOverrides: SubmittingRunOverrides = {},
+): TaskAgentRunParams {
+    const loadSuccess = submittingRunOverrides.LoadSuccess ?? true;
+    const provider = {
+        GetEntityObject: vi.fn().mockImplementation(async (entityName: string) => {
+            if (entityName === 'MJ: AI Agents') {
+                return {
+                    Load: vi.fn().mockResolvedValue(true),
+                    ID: overrides.AgentID ?? 'agent-1',
+                    Name: 'Storyboard Artist',
+                };
+            }
+            if (entityName === 'MJ: Tasks') {
+                return {
+                    Load: vi.fn().mockResolvedValue(false),
+                };
+            }
+            return {
+                Load: vi.fn().mockResolvedValue(loadSuccess),
+                ID: submittingRunOverrides.ID ?? 'submitting-run-1',
+                ConfigurationID:
+                    'ConfigurationID' in submittingRunOverrides
+                        ? submittingRunOverrides.ConfigurationID
+                        : parentConfigurationID,
+                Agent: submittingRunOverrides.Agent ?? null,
+                AgentID: submittingRunOverrides.AgentID ?? null,
+                ParentRunID: submittingRunOverrides.ParentRunID ?? null,
+            };
+        }),
+    } as unknown as IMetadataProvider;
+
+    return {
+        TaskID: 'task-1',
+        AgentID: 'agent-1',
+        InputPayload: 'Draw the opening shot',
+        DependencyOutputs: new Map(),
+        SubmittingAgentRunID: 'submitting-run-1',
+        Provider: provider,
+        ContextUser: { ID: 'user-1' } as unknown as UserInfo,
+        ...overrides,
+    };
+}
+
+describe('VS-CON-7: TaskGraphAgentRunner preset resolution', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        canUserRunAgent.mockResolvedValue(true);
+        processAgentArtifacts.mockResolvedValue(undefined);
+        mockEngineConfig.mockResolvedValue(undefined);
+        mockRunAgent.mockResolvedValue({
+            success: true,
+            agentRun: { ID: 'child-run-1', Message: 'Done' },
+            payload: { result: 'ok' },
+        });
+    });
+
+    it('resolves ConfigurationPresetName to the matching preset AIConfigurationID', async () => {
+        mockGetAgentConfigurationPresets.mockReturnValue([
+            {
+                ID: 'preset-draft',
+                Name: 'Draft',
+                DisplayName: 'Draft Mode',
+                AIConfigurationID: 'cfg-draft-1',
+                Status: 'Active',
+            },
+            {
+                ID: 'preset-high',
+                Name: 'High',
+                DisplayName: 'High Fidelity',
+                AIConfigurationID: 'cfg-high-1',
+                Status: 'Active',
+            },
+        ]);
+
+        const runner = new TaskGraphAgentRunner();
+        const result = await runner.RunAgentForTask(
+            makeParams({ ConfigurationPresetName: 'high fidelity' })
+        );
+
+        expect(result.Success).toBe(true);
+        expect(mockRunAgent).toHaveBeenCalledTimes(1);
+        expect(mockRunAgent.mock.calls[0][0].configurationId).toBe('cfg-high-1');
+    });
+
+    it('passes configurationId: undefined when the matched preset has NULL AIConfigurationID, even if the submitting run has a ConfigurationID', async () => {
+        mockGetAgentConfigurationPresets.mockReturnValue([
+            {
+                ID: 'preset-default',
+                Name: 'SystemDefault',
+                DisplayName: 'System Default',
+                AIConfigurationID: null,
+                Status: 'Active',
+            },
+        ]);
+
+        const runner = new TaskGraphAgentRunner();
+        const result = await runner.RunAgentForTask(
+            makeParams({ ConfigurationPresetName: 'SystemDefault' }, 'parent-cfg-1')
+        );
+
+        expect(result.Success).toBe(true);
+        expect(mockRunAgent).toHaveBeenCalledTimes(1);
+        expect(mockRunAgent.mock.calls[0][0].configurationId).toBeUndefined();
+    });
+
+    it('falls back to the submitting run ConfigurationID when ConfigurationPresetName is not specified', async () => {
+        const runner = new TaskGraphAgentRunner();
+        const result = await runner.RunAgentForTask(makeParams({}, 'parent-cfg-99'));
+
+        expect(result.Success).toBe(true);
+        expect(mockRunAgent).toHaveBeenCalledTimes(1);
+        expect(mockRunAgent.mock.calls[0][0].configurationId).toBe('parent-cfg-99');
+    });
+
+    it('fails the task with a clear message when ConfigurationPresetName does not match any active preset at run time', async () => {
+        mockGetAgentConfigurationPresets.mockReturnValue([
+            {
+                ID: 'preset-draft',
+                Name: 'Draft',
+                DisplayName: 'Draft Mode',
+                AIConfigurationID: 'cfg-draft-1',
+                Status: 'Active',
+            },
+        ]);
+
+        const runner = new TaskGraphAgentRunner();
+        const result = await runner.RunAgentForTask(
+            makeParams({ ConfigurationPresetName: 'DeletedPreset' })
+        );
+
+        expect(result.Success).toBe(false);
+        expect(result.ErrorMessage).toBe(
+            "Agent 'Storyboard Artist' has no active preset 'DeletedPreset'. Available: Draft."
+        );
+        expect(mockRunAgent).not.toHaveBeenCalled();
+    });
+});
+
+describe('VS-INV-2b / VS-QA-3 #9: TaskGraphAgentRunner parentAgentHierarchy from submitted task', () => {
+    const RUN_B_ID = '22222222-2222-4222-8222-222222222222';
+    const RUN_C_ID = '33333333-3333-4333-8333-333333333333';
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+        canUserRunAgent.mockResolvedValue(true);
+        processAgentArtifacts.mockResolvedValue(undefined);
+        mockEngineConfig.mockResolvedValue(undefined);
+        mockRunAgent.mockResolvedValue({
+            success: true,
+            agentRun: { ID: 'child-run-1', Message: 'Done' },
+            payload: { result: 'ok' },
+        });
+    });
+
+    it('reads root-first ParentAgentHierarchy carried from the submitted task without running RunView in a loop (VS-QA-3 #9)', async () => {
+        const runner = new TaskGraphAgentRunner();
+        const params = makeParams(
+            {
+                SubmittingAgentRunID: RUN_C_ID,
+                ParentAgentHierarchy: ['A', 'B', 'C'],
+            },
+            'parent-cfg-1',
+            { ID: RUN_C_ID, Agent: 'C', ParentRunID: RUN_B_ID },
+        );
+
+        const result = await runner.RunAgentForTask(params);
+
+        expect(result.Success).toBe(true);
+        expect(mockRunView).not.toHaveBeenCalled();
+        expect(mockRunAgent).toHaveBeenCalledTimes(1);
+        expect(mockRunAgent.mock.calls[0][0].parentAgentHierarchy).toEqual(['A', 'B', 'C']);
+    });
+
+    it('falls back to the loaded parentRun agent name when ParentAgentHierarchy is omitted, with zero RunView calls', async () => {
+        const runner = new TaskGraphAgentRunner();
+        const params = makeParams(
+            { SubmittingAgentRunID: RUN_C_ID },
+            'parent-cfg-1',
+            { ID: RUN_C_ID, Agent: 'C', ParentRunID: RUN_B_ID },
+        );
+
+        const result = await runner.RunAgentForTask(params);
+
+        expect(result.Success).toBe(true);
+        expect(mockRunView).not.toHaveBeenCalled();
+        expect(mockRunAgent).toHaveBeenCalledTimes(1);
+        expect(mockRunAgent.mock.calls[0][0].parentAgentHierarchy).toEqual(['C']);
+    });
+
+    it('passes undefined parentAgentHierarchy and performs no RunView reads when there is no parentRun and no ParentAgentHierarchy', async () => {
+        const runner = new TaskGraphAgentRunner();
+        const result = await runner.RunAgentForTask(
+            makeParams({ SubmittingAgentRunID: undefined }),
+        );
+
+        expect(result.Success).toBe(true);
+        expect(mockRunView).not.toHaveBeenCalled();
+        expect(mockRunAgent).toHaveBeenCalledTimes(1);
+        expect(mockRunAgent.mock.calls[0][0].parentAgentHierarchy).toBeUndefined();
+    });
+});
 
 describe('TaskGraphAgentRunner', () => {
     beforeEach(() => {
@@ -264,3 +519,4 @@ describe('TaskGraphAgentRunner', () => {
     });
 });
 
+

package/src/__tests__/ViewOperationsHandler.test.ts

@@ -267,16 +267,13 @@ describe('ViewOperationsHandler.getEntityViews', () => {
         expect(outcome.error).toBe('timeout talking to DB');
     });
 
-    it('KNOWN GAP: the entity name is interpolated into ExtraFilter without escaping', async () => {
-        // Reachable only for names registered in metadata, so a hostile value requires a
-        // hostile entity name — but an entity legitimately named with an apostrophe
-        // (e.g. "O'Brien Records") already produces a broken/injectable filter today.
+    it('escapes single quotes in the entity name when building ExtraFilter', async () => {
         registerEntity("O'Brien Records", true);
         mockRunViewFn.mockResolvedValue({ Success: true, Results: [] });
 
         await ViewOperationsHandler.getEntityViews("O'Brien Records", makeUser());
 
         const executed = mockRunViewFn.mock.calls[0][0] as RunViewParams;
-        expect(executed.ExtraFilter).toBe(`Entity = 'O'Brien Records'`); // quote NOT doubled
+        expect(executed.ExtraFilter).toBe(`Entity = 'O''Brien Records'`);
     });
 });

package/src/__tests__/WorkQueueHostService.test.ts

@@ -56,9 +56,9 @@ function enabled(overrides: Partial<WorkQueueConfig> = {}): WorkQueueConfig {
 }
 
 describe('workQueue configuration', () => {
-    it('defaults to disabled, running every MJWorker subscription once enabled', () => {
+    it('defaults to enabled, running every MJWorker subscription out of the box', () => {
         expect(WorkQueueSchema.parse({})).toEqual({
-            enabled: false, systemUserEmail: 'system@memberjunction.org', subscriptions: [{ name: '*', concurrency: 4 }],
+            enabled: true, systemUserEmail: 'system@memberjunction.org', subscriptions: [{ name: '*', concurrency: 4 }],
             idlePollMinMs: 250, idlePollMaxMs: 5000, shutdownDrainMs: 8000, sweeperEnabled: true, sweeperIntervalMs: 60000,
             reconcileIntervalMs: 30000,
         });
@@ -94,7 +94,7 @@ describe('host configuration helpers', () => {
 describe('StartWorkQueueHost', () => {
     it('starts nothing when the section is disabled', async () => {
         const rec = recorder();
-        expect(await StartWorkQueueHost(WorkQueueSchema.parse({}), PROVIDER, PROVIDER_SOURCE, rec.Dependencies)).toBeNull();
+        expect(await StartWorkQueueHost(WorkQueueSchema.parse({ enabled: false }), PROVIDER, PROVIDER_SOURCE, rec.Dependencies)).toBeNull();
         expect(rec.EngineCalls).toBe(0);
     });
 
@@ -109,9 +109,18 @@ describe('StartWorkQueueHost', () => {
         await expect(StartWorkQueueHost(enabled(), PROVIDER, PROVIDER_SOURCE, rec.Dependencies)).rejects.toThrow('System user not found with email: system@memberjunction.org');
     });
 
-    it('names the setting to fix when the placeholder email from DEFAULT_SERVER_CONFIG is still in effect', async () => {
-        const rec = recorder();
-        await expect(StartWorkQueueHost(enabled({ systemUserEmail: 'not.set@nowhere.com' }), PROVIDER, PROVIDER_SOURCE, rec.Dependencies))
+    it('falls back to FindSystemUser when default systemUserEmail is not literal in UserCache', async () => {
+        const rec = recorder([]);
+        rec.Dependencies.FindSystemUser = () => SYSTEM_USER;
+        const host = await StartWorkQueueHost(WorkQueueSchema.parse({}), PROVIDER, PROVIDER_SOURCE, rec.Dependencies);
+        expect(host).not.toBeNull();
+        expect(rec.EngineCalls).toBe(1);
+    });
+
+    it('names the setting to fix when an explicit custom email is not found even if FindSystemUser exists', async () => {
+        const rec = recorder([]);
+        rec.Dependencies.FindSystemUser = () => SYSTEM_USER;
+        await expect(StartWorkQueueHost(enabled({ systemUserEmail: 'missing-worker@example.com' }), PROVIDER, PROVIDER_SOURCE, rec.Dependencies))
             .rejects.toThrow('set workQueue.systemUserEmail');
     });
 
@@ -126,7 +135,16 @@ describe('StartWorkQueueHost', () => {
 });
 
 describe('MJServerWorkQueueProviderSource', () => {
-    it('falls back to the shared server provider when there is no SQL Server pool', async () => {
+    it('mints an independent provider instance when fallback implements CreateIndependentInstance (e.g. PostgreSQL)', async () => {
+        const independent = { Name: 'independent-pg-provider' } as IMetadataProvider;
+        const createIndependent = vi.fn().mockResolvedValue(independent);
+        const pgFallback = Object.assign({}, PROVIDER, { CreateIndependentInstance: createIndependent });
+        const source = new MJServerWorkQueueProviderSource(null, pgFallback);
+        expect(await source.CreateProvider()).toBe(independent);
+        expect(createIndependent).toHaveBeenCalledTimes(1);
+    });
+
+    it('falls back to the shared server provider when there is no SQL Server pool and no CreateIndependentInstance', async () => {
         const source = new MJServerWorkQueueProviderSource(null, PROVIDER);
         expect(await source.CreateProvider()).toBe(PROVIDER);
     });

package/src/__tests__/backgroundSweepConfigUnits.test.ts

@@ -0,0 +1,153 @@
+/**
+ * Config contract for the two background sweeps an idle MJAPI runs against its database: the AI
+ * Agent Session janitor (`agentSessions.janitor`) and the agent-run watchdog (`agentRunWatchdog`).
+ *
+ * Pins three things: the shipped defaults are exactly the values MJAPI always ran with (so existing
+ * deployments see no change), each sweep can be turned off the documented way, and the env-var
+ * readers that feed `DEFAULT_SERVER_CONFIG` reject typos instead of silently running a default or
+ * a zero-delay timer.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+    AgentRunWatchdogDefaultsFromEnv,
+    AgentRunWatchdogSchema,
+    AgentSessionsDefaultsFromEnv,
+    AgentSessionsSchema,
+    ConversationDetailReconcilerDefaultsFromEnv,
+    ConversationDetailReconcilerSchema,
+    EnabledFromEnv,
+    IntervalMsFromEnv,
+} from '../backgroundSweepConfigUnits.js';
+
+describe('agentSessions.janitor schema', () => {
+    it('defaults to what MJAPI has always run: janitor on every 60s (15-minute idle close), bridge reconcile on every 10 min', () => {
+        expect(AgentSessionsSchema.parse({})).toEqual({
+            janitor: { enabled: true, sweepIntervalMs: 60_000, closeThresholdMinutes: 15 },
+            bridgeReconciler: { enabled: true, sweepIntervalMs: 600_000 },
+            handoffOfferExpiry: { enabled: true, sweepIntervalMs: 15_000 },
+        });
+    });
+
+    it('accepts enabled: false and a longer interval', () => {
+        const parsed = AgentSessionsSchema.parse({ janitor: { enabled: false, sweepIntervalMs: 3_600_000 }, bridgeReconciler: { enabled: false } });
+        expect(parsed.janitor).toEqual({ enabled: false, sweepIntervalMs: 3_600_000, closeThresholdMinutes: 15 });
+        expect(parsed.bridgeReconciler).toEqual({ enabled: false, sweepIntervalMs: 600_000 });
+    });
+
+    it('rejects a zero or negative interval (turn the tick off with enabled: false instead)', () => {
+        expect(AgentSessionsSchema.safeParse({ janitor: { sweepIntervalMs: 0 } }).success).toBe(false);
+        expect(AgentSessionsSchema.safeParse({ janitor: { closeThresholdMinutes: -1 } }).success).toBe(false);
+        expect(AgentSessionsSchema.safeParse({ bridgeReconciler: { sweepIntervalMs: 0 } }).success).toBe(false);
+    });
+});
+
+describe('conversationDetailReconciler schema', () => {
+    it('defaults to what MJAPI has always run: on, every 5 minutes', () => {
+        expect(ConversationDetailReconcilerSchema.parse({})).toEqual({ enabled: true, sweepIntervalMs: 300_000 });
+    });
+
+    it('accepts enabled: false and rejects a zero interval', () => {
+        expect(ConversationDetailReconcilerSchema.parse({ enabled: false }).enabled).toBe(false);
+        expect(ConversationDetailReconcilerSchema.safeParse({ sweepIntervalMs: 0 }).success).toBe(false);
+    });
+});
+
+describe('DEFAULT_SERVER_CONFIG blocks from the environment', () => {
+    it('an empty environment gives exactly the shipped defaults', () => {
+        expect(AgentSessionsDefaultsFromEnv({})).toEqual(AgentSessionsSchema.parse({}));
+        expect(ConversationDetailReconcilerDefaultsFromEnv({})).toEqual(ConversationDetailReconcilerSchema.parse({}));
+        expect(AgentRunWatchdogDefaultsFromEnv({})).toEqual(AgentRunWatchdogSchema.parse({}));
+    });
+
+    it('reads every documented variable', () => {
+        const env = {
+            MJ_SESSION_JANITOR_ENABLED: 'false',
+            MJ_SESSION_JANITOR_SWEEP_INTERVAL_MS: '120000',
+            MJ_BRIDGE_RECONCILER_ENABLED: 'off',
+            MJ_BRIDGE_RECONCILER_SWEEP_INTERVAL_MS: '1200000',
+            MJ_CONVERSATION_DETAIL_RECONCILER_ENABLED: '0',
+            MJ_CONVERSATION_DETAIL_RECONCILER_SWEEP_INTERVAL_MS: '900000',
+            MJ_HANDOFF_OFFER_EXPIRY_ENABLED: 'no',
+            MJ_HANDOFF_OFFER_EXPIRY_SWEEP_INTERVAL_MS: '60000',
+            MJ_AGENT_RUN_WATCHDOG_SWEEP_INTERVAL_MS: '0',
+        };
+        expect(AgentSessionsDefaultsFromEnv(env)).toEqual({
+            janitor: { enabled: false, sweepIntervalMs: 120_000, closeThresholdMinutes: 15 },
+            bridgeReconciler: { enabled: false, sweepIntervalMs: 1_200_000 },
+            handoffOfferExpiry: { enabled: false, sweepIntervalMs: 60_000 },
+        });
+        expect(ConversationDetailReconcilerDefaultsFromEnv(env)).toEqual({ enabled: false, sweepIntervalMs: 900_000 });
+        expect(AgentRunWatchdogDefaultsFromEnv(env).sweepIntervalMs).toBe(0);
+    });
+
+    it('a bad value fails, naming the variable', () => {
+        expect(() => AgentSessionsDefaultsFromEnv({ MJ_BRIDGE_RECONCILER_ENABLED: 'nope' }))
+            .toThrow('Invalid MJ_BRIDGE_RECONCILER_ENABLED "nope". Expected true or false.');
+        expect(() => ConversationDetailReconcilerDefaultsFromEnv({ MJ_CONVERSATION_DETAIL_RECONCILER_SWEEP_INTERVAL_MS: '0' }))
+            .toThrow(/Invalid MJ_CONVERSATION_DETAIL_RECONCILER_SWEEP_INTERVAL_MS "0"/);
+    });
+});
+
+describe('agentRunWatchdog schema', () => {
+    it('defaults to the watchdog MJAPI has always run: 5-min sweep, 30s heartbeat, 5-min stale threshold', () => {
+        expect(AgentRunWatchdogSchema.parse({})).toEqual({
+            sweepIntervalMs: 300_000,
+            heartbeatIntervalMs: 30_000,
+            staleThresholdMinutes: 5,
+        });
+    });
+
+    it('accepts sweepIntervalMs: 0 (startup sweep only)', () => {
+        expect(AgentRunWatchdogSchema.parse({ sweepIntervalMs: 0 }).sweepIntervalMs).toBe(0);
+    });
+
+    it('rejects a zero heartbeat (other instances would force-fail this one\'s runs) and negative values', () => {
+        expect(AgentRunWatchdogSchema.safeParse({ heartbeatIntervalMs: 0 }).success).toBe(false);
+        expect(AgentRunWatchdogSchema.safeParse({ staleThresholdMinutes: 0 }).success).toBe(false);
+        expect(AgentRunWatchdogSchema.safeParse({ sweepIntervalMs: -1 }).success).toBe(false);
+    });
+});
+
+describe('EnabledFromEnv', () => {
+    it('returns the fallback when the variable is unset or blank', () => {
+        expect(EnabledFromEnv('X', undefined, true)).toBe(true);
+        expect(EnabledFromEnv('X', null, false)).toBe(false);
+        expect(EnabledFromEnv('X', '  ', true)).toBe(true);
+    });
+
+    it.each(['false', 'FALSE', '0', 'no', 'off', 'n', 'f'])('%j turns the switch off', value => {
+        expect(EnabledFromEnv('X', value, true)).toBe(false);
+    });
+
+    it.each(['true', '1', 'yes', 'on', 'Y', 't'])('%j turns it on', value => {
+        expect(EnabledFromEnv('X', value, false)).toBe(true);
+    });
+
+    it('fails fast on anything else, naming the variable (a typo must not silently turn a sweep off)', () => {
+        expect(() => EnabledFromEnv('MJ_SESSION_JANITOR_ENABLED', 'flase', true))
+            .toThrow('Invalid MJ_SESSION_JANITOR_ENABLED "flase". Expected true or false.');
+    });
+});
+
+describe('IntervalMsFromEnv', () => {
+    it('returns the fallback when the variable is unset or blank', () => {
+        expect(IntervalMsFromEnv('X', undefined, 60_000, false)).toBe(60_000);
+        expect(IntervalMsFromEnv('X', '', 60_000, false)).toBe(60_000);
+    });
+
+    it('reads a number of milliseconds', () => {
+        expect(IntervalMsFromEnv('X', ' 3600000 ', 60_000, false)).toBe(3_600_000);
+    });
+
+    it('accepts 0 only where 0 means off', () => {
+        expect(IntervalMsFromEnv('MJ_AGENT_RUN_WATCHDOG_SWEEP_INTERVAL_MS', '0', 300_000, true)).toBe(0);
+        expect(() => IntervalMsFromEnv('MJ_SESSION_JANITOR_SWEEP_INTERVAL_MS', '0', 60_000, false))
+            .toThrow('Invalid MJ_SESSION_JANITOR_SWEEP_INTERVAL_MS "0". Expected a number of milliseconds greater than 0.');
+    });
+
+    it('fails fast on a typo, naming the variable', () => {
+        expect(() => IntervalMsFromEnv('MJ_AGENT_RUN_WATCHDOG_SWEEP_INTERVAL_MS', '5m', 300_000, true))
+            .toThrow('Invalid MJ_AGENT_RUN_WATCHDOG_SWEEP_INTERVAL_MS "5m". Expected a number of milliseconds, 0 or greater.');
+        expect(() => IntervalMsFromEnv('X', '-5', 60_000, true)).toThrow(/Invalid X/);
+    });
+});

package/src/__tests__/contextRequestOrigin.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Tests that ContextFunction surfaces the request's normalized Origin header on AppContext as
+ * `RequestOrigin`. Database-facing dependencies are mocked; no connection is opened.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { BehaviorSubject } from 'rxjs';
+
+const { mockProviderConfig } = vi.hoisted(() => ({
+  mockProviderConfig: vi.fn(),
+}));
+
+vi.mock('../util.js', () => ({
+  GetReadOnlyDataSource: vi.fn(() => undefined),
+  GetReadWriteDataSource: vi.fn(() => undefined),
+}));
+
+vi.mock('../config.js', () => ({
+  configInfo: { databaseSettings: { metadataCacheRefreshInterval: 0 } },
+  userEmailMap: {},
+  apiKey: 'test-api-key',
+  mj_core_schema: '__mj',
+}));
+
+vi.mock('@memberjunction/sqlserver-dataprovider', () => ({
+  SQLServerDataProvider: class {
+    Config = mockProviderConfig;
+  },
+  SQLServerProviderConfigData: class {},
+}));
+
+vi.mock('@memberjunction/postgresql-dataprovider', () => ({
+  PostgreSQLDataProvider: class {
+    Config = mockProviderConfig;
+  },
+  PostgreSQLProviderConfigData: class {},
+}));
+
+vi.mock('@memberjunction/generic-database-provider', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@memberjunction/generic-database-provider')>();
+  return {
+    ...actual,
+    resolveDbPlatformFromEnv: () => 'sqlserver' as const,
+    UserCache: { Instance: {} } as typeof actual.UserCache,
+  };
+});
+
+vi.mock('@memberjunction/api-keys', () => ({
+  GetAPIKeyEngine: vi.fn(),
+}));
+
+vi.mock('@memberjunction/core', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@memberjunction/core')>();
+  return { ...actual, Metadata: { Provider: { Entities: [{}] } } };
+});
+
+import { ContextFunction } from '../context.js';
+import type { IncomingMessage } from 'http';
+import type { ConnectionPool } from 'mssql';
+import type { UserPayload } from '../types.js';
+
+const MOCK_POOL = {} as ConnectionPool;
+const MOCK_PAYLOAD = { email: 'user@example.com' } as UserPayload;
+
+function makeReq(headers: IncomingMessage['headers']): IncomingMessage {
+  return { headers, body: {}, ip: '127.0.0.1', userPayload: MOCK_PAYLOAD } as unknown as IncomingMessage;
+}
+
+async function contextFor(headers: IncomingMessage['headers']) {
+  const build = ContextFunction({ setupComplete$: new BehaviorSubject<unknown>(true), dataSource: MOCK_POOL, dataSources: [] });
+  return build({ req: makeReq(headers) });
+}
+
+describe('ContextFunction RequestOrigin', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockProviderConfig.mockResolvedValue(true);
+  });
+
+  it('carries the normalized Origin header', async () => {
+    const ctx = await contextFor({ origin: 'https://Embed.Example.com/' });
+    expect(ctx.RequestOrigin).toBe('https://embed.example.com');
+  });
+
+  it('keeps an explicit port', async () => {
+    const ctx = await contextFor({ origin: 'http://localhost:4200' });
+    expect(ctx.RequestOrigin).toBe('http://localhost:4200');
+  });
+
+  it('is undefined when the request sent no Origin header', async () => {
+    const ctx = await contextFor({});
+    expect(ctx.RequestOrigin).toBeUndefined();
+  });
+
+  it('is undefined for a malformed or opaque Origin header', async () => {
+    expect((await contextFor({ origin: 'null' })).RequestOrigin).toBeUndefined();
+    expect((await contextFor({ origin: 'https://a.com/path' })).RequestOrigin).toBeUndefined();
+  });
+
+  it('leaves the existing context fields in place', async () => {
+    const ctx = await contextFor({ origin: 'https://a.com' });
+    expect(ctx.userPayload).toBe(MOCK_PAYLOAD);
+    expect(ctx.ClientIp).toBe('127.0.0.1');
+    expect(ctx.providers).toHaveLength(1);
+  });
+});