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

package/src/__tests__/postgresqlPoolSettings.test.ts

@@ -0,0 +1,131 @@
+/**
+ * PostgreSQL pools read the same databaseSettings values as SQL Server, with the same defaults.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+    BuildPostgreSQLConnectionConfig,
+    CODEGEN_STATEMENT_TIMEOUT_MS,
+    ResolvePostgreSQLEndpoint,
+    ResolvePostgreSQLReadOnlyCredentials,
+    ToPGPoolConfig
+} from '../postgresqlPoolSettings.js';
+import type { DatabaseSettingsInfo } from '../config.js';
+import { DescribeReadOnlyLoginOverreach } from '../postgresqlPoolSettings.js';
+import type { ReadOnlyLoginCheckClient, ReadOnlyLoginGrants } from '../postgresqlPoolSettings.js';
+
+const defaults: DatabaseSettingsInfo = {
+    connectionTimeout: 45000,
+    requestTimeout: 30000,
+    metadataCacheRefreshInterval: 180000,
+    connectionPool: { max: 50, min: 5, idleTimeoutMillis: 30000, acquireTimeoutMillis: 30000 }
+};
+const endpoint = { Host: 'db', Port: 5432, Database: 'mj', User: 'api', Password: 'secret' };
+
+describe('BuildPostgreSQLConnectionConfig', () => {
+    it('gives API pools requestTimeout as the statement timeout and the pool settings SQL Server uses', () => {
+        const config = BuildPostgreSQLConnectionConfig(endpoint, defaults, 'api');
+        expect(config).toMatchObject({
+            ...endpoint,
+            MaxConnections: 50,
+            MinConnections: 5,
+            IdleTimeoutMillis: 30000,
+            ConnectionTimeoutMillis: 30000,
+            StatementTimeoutMs: 30000,
+            IdleInTransactionSessionTimeoutMs: 60000
+        });
+    });
+
+    it('follows a configured requestTimeout and pool', () => {
+        const config = BuildPostgreSQLConnectionConfig(endpoint, {
+            ...defaults,
+            requestTimeout: 5000,
+            connectionPool: { max: 12, min: 1, idleTimeoutMillis: 7000, acquireTimeoutMillis: 9000 }
+        }, 'api');
+        expect(config).toMatchObject({ MaxConnections: 12, MinConnections: 1, IdleTimeoutMillis: 7000, ConnectionTimeoutMillis: 9000, StatementTimeoutMs: 5000, IdleInTransactionSessionTimeoutMs: 10000 });
+    });
+
+    it('sets no timeouts when requestTimeout is 0', () => {
+        const config = BuildPostgreSQLConnectionConfig(endpoint, { ...defaults, requestTimeout: 0 }, 'api');
+        expect(config.StatementTimeoutMs).toBe(0);
+        expect(config.IdleInTransactionSessionTimeoutMs).toBe(0);
+    });
+
+    it('keeps the read-only pool small but gives it the API timeouts', () => {
+        const config = BuildPostgreSQLConnectionConfig(endpoint, defaults, 'read-only');
+        expect(config).toMatchObject({ MaxConnections: 10, MinConnections: 0, StatementTimeoutMs: 30000, IdleInTransactionSessionTimeoutMs: 60000 });
+        expect(BuildPostgreSQLConnectionConfig(endpoint, { ...defaults, connectionPool: { max: 4, min: 1, idleTimeoutMillis: 1, acquireTimeoutMillis: 1 } }, 'read-only').MaxConnections).toBe(4);
+    });
+
+    it('gives the CodeGen pool the long timeout the SQL Server CodeGen pool has, and no idle-in-transaction limit', () => {
+        const config = BuildPostgreSQLConnectionConfig(endpoint, defaults, 'codegen');
+        expect(config.StatementTimeoutMs).toBe(CODEGEN_STATEMENT_TIMEOUT_MS);
+        expect(CODEGEN_STATEMENT_TIMEOUT_MS).toBe(600000);
+        expect(config.IdleInTransactionSessionTimeoutMs).toBe(0);
+        expect(config.MaxConnections).toBe(10);
+    });
+});
+
+describe('ToPGPoolConfig', () => {
+    it('maps the connection config onto pg.Pool option names', () => {
+        const pool = ToPGPoolConfig(BuildPostgreSQLConnectionConfig(endpoint, defaults, 'api'));
+        expect(pool).toEqual({
+            host: 'db', port: 5432, database: 'mj', user: 'api', password: 'secret',
+            max: 50, min: 5, idleTimeoutMillis: 30000, connectionTimeoutMillis: 30000,
+            statement_timeout: 30000, idle_in_transaction_session_timeout: 60000
+        });
+    });
+
+    it('leaves the timeouts out when they are 0', () => {
+        const pool = ToPGPoolConfig(BuildPostgreSQLConnectionConfig(endpoint, { ...defaults, requestTimeout: 0 }, 'api'));
+        expect(pool).not.toHaveProperty('statement_timeout');
+        expect(pool).not.toHaveProperty('idle_in_transaction_session_timeout');
+    });
+});
+
+describe('ResolvePostgreSQLEndpoint', () => {
+    it('prefers PG_* variables over DB_* ones', () => {
+        expect(ResolvePostgreSQLEndpoint({ PG_HOST: 'pg', DB_HOST: 'db', DB_PORT: '6000', DB_DATABASE: 'd', DB_USERNAME: 'u', DB_PASSWORD: 'p' }))
+            .toEqual({ Host: 'pg', Port: 6000, Database: 'd', User: 'u', Password: 'p' });
+    });
+
+    it('falls back to localhost:5432 and the postgres user', () => {
+        expect(ResolvePostgreSQLEndpoint({})).toEqual({ Host: 'localhost', Port: 5432, Database: '', User: 'postgres', Password: '' });
+    });
+});
+
+describe('ResolvePostgreSQLReadOnlyCredentials', () => {
+    it('uses the dbReadOnlyUsername / dbReadOnlyPassword settings SQL Server uses', () => {
+        expect(ResolvePostgreSQLReadOnlyCredentials({ dbReadOnlyUsername: 'ro', dbReadOnlyPassword: 'pw' }, {}))
+            .toEqual({ User: 'ro', Password: 'pw' });
+    });
+
+    it('falls back to PG_READ_ONLY_* when the settings are absent', () => {
+        expect(ResolvePostgreSQLReadOnlyCredentials({}, { PG_READ_ONLY_USERNAME: 'pgro', PG_READ_ONLY_PASSWORD: 'x' }))
+            .toEqual({ User: 'pgro', Password: 'x' });
+    });
+
+    it('returns null when no complete pair is configured', () => {
+        expect(ResolvePostgreSQLReadOnlyCredentials({ dbReadOnlyUsername: 'ro' }, { PG_READ_ONLY_USERNAME: 'pgro' })).toBeNull();
+    });
+});
+
+describe('DescribeReadOnlyLoginOverreach', () => {
+    const clientAnswering = (row: ReadOnlyLoginGrants): ReadOnlyLoginCheckClient => ({
+        query: async () => ({ rows: [row] }),
+    });
+
+    it('says nothing for a login that reads only views', async () => {
+        expect(await DescribeReadOnlyLoginOverreach(clientAnswering({ ReadsServerFiles: false, ReadableBaseTables: 0 }), '__mj')).toEqual([]);
+    });
+
+    it('warns when the login can read base tables', async () => {
+        const warnings = await DescribeReadOnlyLoginOverreach(clientAnswering({ ReadsServerFiles: false, ReadableBaseTables: 412 }), '__mj');
+        expect(warnings).toHaveLength(1);
+        expect(warnings[0]).toMatch(/can read 412 base table\(s\) in schema "__mj"/);
+    });
+
+    it('warns when the login can read server files', async () => {
+        const warnings = await DescribeReadOnlyLoginOverreach(clientAnswering({ ReadsServerFiles: true, ReadableBaseTables: 0 }), '__mj');
+        expect(warnings[0]).toMatch(/pg_read_server_files/);
+    });
+});

package/src/__tests__/pushStatusFanOut.test.ts

@@ -0,0 +1,206 @@
+/**
+ * Tests for cross-instance fan-out of push-status updates (MJ #4222).
+ *
+ * Behind a load balancer the browser's WebSocket lives on one replica while the mutation driving
+ * the agent may be handled by another, so a completion can be published to a topic that has no
+ * subscriber. Replicating progress and completion closes that.
+ *
+ * Three properties are pinned here because each one, if wrong, produces a bug that looks like
+ * something else entirely:
+ *
+ * - **Streaming content is not replicated.** It is hundreds of messages per second, each carrying
+ *   a full serialized agent run. Replicating it would look like a network problem, not a bug here.
+ * - **Every publish carries `SourceServerId`.** Without it, echo suppression on the receiving side
+ *   has nothing to match and every push is delivered twice.
+ * - **A hook that throws does not break local delivery.** The message bus is an optimization over
+ *   the durable tail query; the local path must work when it is down.
+ */
+import 'reflect-metadata';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import {
+    publishStatusUpdate,
+    ParseReplicatedStatusUpdate,
+    ShouldReplicateStatusUpdate,
+    SetPushStatusPublishHook,
+    type PushStatusNotificationPayload,
+} from '../generic/PushStatusResolver.js';
+import { MJGlobal } from '@memberjunction/global';
+import type { PubSubEngine } from 'type-graphql';
+
+const SESSION = 'session-1';
+const OWNER = 'U0000000-0000-0000-0000-000000000000';
+
+function fakePubSub() {
+    const published: Array<{ topic: string; payload: PushStatusNotificationPayload }> = [];
+    const engine = {
+        publish: (topic: string, payload: PushStatusNotificationPayload) => {
+            published.push({ topic, payload });
+            return Promise.resolve();
+        },
+    } as unknown as PubSubEngine;
+    return { engine, published };
+}
+
+const envelope = (type: string) => JSON.stringify({ resolver: 'RunAIAgentResolver', type, status: 'ok', data: {} });
+
+afterEach(() => {
+    SetPushStatusPublishHook(undefined);
+});
+
+describe('ShouldReplicateStatusUpdate', () => {
+    it('replicates execution progress', () => {
+        expect(ShouldReplicateStatusUpdate(envelope('ExecutionProgress'))).toBe(true);
+    });
+
+    it('does not replicate streaming content', () => {
+        expect(ShouldReplicateStatusUpdate(envelope('StreamingContent'))).toBe(false);
+    });
+
+    it('replicates a plain-string message, which is rare and low-rate', () => {
+        expect(ShouldReplicateStatusUpdate('agent finished')).toBe(true);
+    });
+
+    it('does not replicate an empty message', () => {
+        expect(ShouldReplicateStatusUpdate(undefined)).toBe(false);
+        expect(ShouldReplicateStatusUpdate('')).toBe(false);
+    });
+
+    it('replicates JSON that is not the resolver envelope', () => {
+        expect(ShouldReplicateStatusUpdate(JSON.stringify({ hello: 'world' }))).toBe(true);
+    });
+});
+
+describe('publishStatusUpdate fan-out', () => {
+    beforeEach(() => {
+        SetPushStatusPublishHook(undefined);
+    });
+
+    it('stamps the publishing instance on every payload', () => {
+        const { engine, published } = fakePubSub();
+
+        publishStatusUpdate(engine, { sessionId: SESSION, ownerUserId: OWNER, message: envelope('ExecutionProgress') });
+
+        expect(published).toHaveLength(1);
+        expect(published[0].payload.SourceServerId).toBe(MJGlobal.Instance.ProcessUUID);
+    });
+
+    it('still publishes locally when no hook is registered', () => {
+        const { engine, published } = fakePubSub();
+
+        publishStatusUpdate(engine, { sessionId: SESSION, ownerUserId: OWNER, message: envelope('ExecutionProgress') });
+
+        expect(published[0].payload.ownerUserId).toBe(OWNER);
+    });
+
+    it('forwards a replicable update to the hook', () => {
+        const hook = vi.fn();
+        SetPushStatusPublishHook(hook);
+        const { engine } = fakePubSub();
+
+        publishStatusUpdate(engine, { sessionId: SESSION, ownerUserId: OWNER, message: envelope('ExecutionProgress') });
+
+        expect(hook).toHaveBeenCalledTimes(1);
+        const forwarded = hook.mock.calls[0][0] as PushStatusNotificationPayload;
+        expect(forwarded.sessionId).toBe(SESSION);
+        expect(forwarded.ownerUserId).toBe(OWNER);
+        expect(forwarded.SourceServerId).toBe(MJGlobal.Instance.ProcessUUID);
+    });
+
+    it('does not forward streaming content, but still delivers it locally', () => {
+        const hook = vi.fn();
+        SetPushStatusPublishHook(hook);
+        const { engine, published } = fakePubSub();
+
+        publishStatusUpdate(engine, { sessionId: SESSION, ownerUserId: OWNER, message: envelope('StreamingContent') });
+
+        expect(hook).not.toHaveBeenCalled();
+        expect(published).toHaveLength(1);
+    });
+
+    it('delivers locally even when the hook throws', () => {
+        SetPushStatusPublishHook(() => {
+            throw new Error('redis is down');
+        });
+        const { engine, published } = fakePubSub();
+
+        expect(() =>
+            publishStatusUpdate(engine, { sessionId: SESSION, ownerUserId: OWNER, message: envelope('ExecutionProgress') })
+        ).not.toThrow();
+        expect(published).toHaveLength(1);
+    });
+
+    it('publishes locally before attempting fan-out', () => {
+        const order: string[] = [];
+        SetPushStatusPublishHook(() => order.push('hook'));
+        const engine = {
+            publish: () => {
+                order.push('local');
+                return Promise.resolve();
+            },
+        } as unknown as PubSubEngine;
+
+        publishStatusUpdate(engine, { sessionId: SESSION, ownerUserId: OWNER, message: envelope('ExecutionProgress') });
+
+        expect(order).toEqual(['local', 'hook']);
+    });
+
+    it('clears the hook when set with no argument', () => {
+        const hook = vi.fn();
+        SetPushStatusPublishHook(hook);
+        SetPushStatusPublishHook(undefined);
+        const { engine } = fakePubSub();
+
+        publishStatusUpdate(engine, { sessionId: SESSION, ownerUserId: OWNER, message: envelope('ExecutionProgress') });
+
+        expect(hook).not.toHaveBeenCalled();
+    });
+});
+
+describe('ParseReplicatedStatusUpdate', () => {
+    /**
+     * Messages on the shared channel come from other processes, so every field is checked before
+     * the update is republished onto the local topic, where the subscription filter compares
+     * `ownerUserId` against the connection's user.
+     */
+    const LOCAL = 'LOCAL-PROCESS';
+    const raw = (over: Record<string, unknown> = {}) =>
+        JSON.stringify({ sessionId: SESSION, ownerUserId: OWNER, message: 'hello', SourceServerId: 'OTHER', ...over });
+
+    it('returns the update from another instance', () => {
+        expect(ParseReplicatedStatusUpdate(raw(), LOCAL)).toEqual({
+            sessionId: SESSION,
+            ownerUserId: OWNER,
+            message: 'hello',
+            SourceServerId: 'OTHER',
+        });
+    });
+
+    it('drops our own message echoed back by the bus', () => {
+        expect(ParseReplicatedStatusUpdate(raw({ SourceServerId: LOCAL }), LOCAL)).toBeNull();
+    });
+
+    it('drops an update with no identity', () => {
+        expect(ParseReplicatedStatusUpdate(raw({ ownerUserId: '' }), LOCAL)).toBeNull();
+        expect(ParseReplicatedStatusUpdate(raw({ sessionId: undefined }), LOCAL)).toBeNull();
+    });
+
+    it('drops identity fields that are not strings', () => {
+        // A truthy object would pass a presence check and reach the filter as the wrong type.
+        expect(ParseReplicatedStatusUpdate(raw({ ownerUserId: { ID: OWNER } }), LOCAL)).toBeNull();
+        expect(ParseReplicatedStatusUpdate(raw({ sessionId: 42 }), LOCAL)).toBeNull();
+    });
+
+    it('drops a message body that is not a string', () => {
+        expect(ParseReplicatedStatusUpdate(raw({ message: { type: 'x' } }), LOCAL)).toBeNull();
+    });
+
+    it('accepts an update with no message body', () => {
+        expect(ParseReplicatedStatusUpdate(raw({ message: undefined }), LOCAL)?.message).toBeUndefined();
+    });
+
+    it('drops malformed JSON and values that are not objects', () => {
+        expect(ParseReplicatedStatusUpdate('{not json', LOCAL)).toBeNull();
+        expect(ParseReplicatedStatusUpdate('null', LOCAL)).toBeNull();
+        expect(ParseReplicatedStatusUpdate('42', LOCAL)).toBeNull();
+    });
+});

package/src/__tests__/translateBracketsToPG.test.ts

@@ -0,0 +1,20 @@
+/**
+ * Generated resolvers emit SQL Server bracket-quoted identifiers; on PostgreSQL they become
+ * double-quoted. Only identifiers change: brackets inside a string literal are data.
+ */
+import { describe, it, expect } from 'vitest';
+import { TranslateBracketsToPG } from '../postgresqlCompat.js';
+
+describe('TranslateBracketsToPG', () => {
+    it('turns bracket-quoted identifiers into double-quoted ones', () => {
+        expect(TranslateBracketsToPG('SELECT [ID], [Name] FROM [__mj].[vwUsers]')).toBe('SELECT "ID", "Name" FROM "__mj"."vwUsers"');
+    });
+
+    it('leaves brackets inside a string literal alone', () => {
+        expect(TranslateBracketsToPG("SELECT [ID] FROM [t] WHERE [Note] = '[draft] copy'")).toBe(`SELECT "ID" FROM "t" WHERE "Note" = '[draft] copy'`);
+    });
+
+    it('unescapes ]] and escapes a double quote in the name', () => {
+        expect(TranslateBracketsToPG('SELECT [a]]b], [say "hi"] FROM t')).toBe('SELECT "a]b", "say ""hi""" FROM t');
+    });
+});

package/src/auth/__tests__/backward-compatibility.test.ts

@@ -21,6 +21,7 @@ describe('Authentication Provider Backward Compatibility', () => {
   let factory: AuthProviderFactory;
   
   beforeEach(() => {
+    vi.spyOn(AuthProviderFactory, 'DiscoverFromEnvironment').mockReturnValue([]);
     factory = AuthProviderFactory.Instance;
     factory.clear();
   });

package/src/config.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { DEFAULT_WORK_QUEUE_CONFIG, WorkQueueSchema } from './services/workQueueConfig.js';
 import { cosmiconfigSync } from 'cosmiconfig';
 import { LogError, LogStatus, LogStatusEx } from '@memberjunction/core';
 import { mergeConfigs, parseBooleanEnv } from '@memberjunction/config';
@@ -470,10 +471,20 @@ const twilioTelephonySchema = z.object({
   apiKeySecret: z.string().optional(),
   /** The publicly reachable `wss://…/telephony/twilio/media` URL Twilio's <Connect><Stream> connects to. */
   streamPublicUrl: z.string(),
-  /** Optional shared secret gating the public webhook/WSS endpoints (defense-in-depth beyond signature verification). */
+  /**
+   * Reserved; currently unused. The Media-Streams websocket is authenticated by a per-call token MJ mints and
+   * embeds in the TwiML (`<Parameter name="mjToken">`), and webhooks by `X-Twilio-Signature`.
+   */
   webhookSigningSecret: z.string().optional(),
-  /** Optional status-callback URL Twilio posts call lifecycle events to. */
+  /**
+   * URL Twilio posts outbound-call lifecycle events to. Defaults to `<public URL>/telephony/twilio/status`, the
+   * route that ends the bridge session when a call is busy / unanswered / failed / completed.
+   */
   statusCallbackUrl: z.string().optional(),
+  /** URL Twilio posts the async answering-machine verdict to. Defaults to `<public URL>/telephony/twilio/amd`. */
+  amdStatusCallbackUrl: z.string().optional(),
+  /** What to do when a machine or fax answers an outbound call: `hangup` (default) ends it, `continue` only logs the verdict. */
+  onMachine: z.enum(['hangup', 'continue']).optional(),
 }).passthrough();
 
 /**
@@ -495,8 +506,14 @@ const vonageTelephonySchema = z.object({
   mediaPublicUrl: z.string(),
   /** Vonage account signature secret — HMAC key for signed-request `sig` AND HS256 webhook-JWT verification. */
   signatureSecret: z.string().optional(),
-  /** Optional event-webhook URL Vonage posts call lifecycle events to (passed on outbound createCall). */
+  /**
+   * Event-webhook URL Vonage posts call lifecycle events to (passed on outbound createCall). Defaults to
+   * `<public URL>/telephony/vonage/event`, the route that ends the bridge session when a call is busy /
+   * unanswered / failed / completed.
+   */
   eventUrl: z.string().optional(),
+  /** What to do when a machine answers an outbound call — Vonage's `machine_detection`: `hangup` (default) or `continue`. */
+  onMachine: z.enum(['hangup', 'continue']).optional(),
 }).passthrough();
 
 /**
@@ -550,15 +567,119 @@ const teamsMeetingsSchema = z.object({
   modelSampleRate: z.coerce.number().optional().default(16000),
 }).passthrough();
 
+/**
+ * LiveKit SIP binding: phone calls carried by a SIP trunk and landed in a LiveKit room (every conversation lives in a room;
+ * the carrier is only the pipe). LiveKit credentials default to the `LIVEKIT_URL` / `LIVEKIT_API_KEY` /
+ * `LIVEKIT_API_SECRET` env vars the Meet room already uses. When `livekitSip` is omitted, the LiveKit SIP webhook is not mounted.
+ * Point a LiveKit project webhook at `<public URL>/telephony/livekit-sip/webhook` (the signature is verified with the API secret).
+ */
+const livekitSipTelephonySchema = z.object({
+  /** LiveKit server URL (`wss://…`). Defaults to `LIVEKIT_URL`. */
+  serverUrl: z.string().optional(),
+  /** LiveKit API key. Defaults to `LIVEKIT_API_KEY`. */
+  apiKey: z.string().optional(),
+  /** LiveKit API secret (resolved upstream — never inlined). Defaults to `LIVEKIT_API_SECRET`. */
+  apiSecret: z.string().optional(),
+  /** Inbound calls land in a room whose name starts with this. Defaults to `call-`. */
+  roomPrefix: z.string().optional(),
+  /** The numbers (E.164) this deployment answers. Each routes to the agent identity registered for it (on the LiveKit provider). */
+  numbers: z.array(z.string()).optional(),
+  /** The LiveKit inbound trunk id, when created by hand. */
+  inboundTrunkId: z.string().optional(),
+  /** The LiveKit OUTBOUND trunk used to dial out (outbound calls, fallback legs, transfers to a number). Dialing out is off without it. */
+  outboundTrunkId: z.string().optional(),
+  /** The caller ID presented on calls dialed out through the outbound trunk. */
+  outboundFromNumber: z.string().optional(),
+  /** Create the inbound trunk and dispatch rule at startup when missing (idempotent). Defaults to false. */
+  autoProvision: zodBooleanWithTransforms().optional().default(false),
+  /** Source addresses the inbound trunk accepts calls from (the carrier's SIP signalling addresses). Used when provisioning. */
+  allowedAddresses: z.array(z.string()).optional(),
+  /** The carrier behind the trunk, for configuration checks only (no carrier API is called). */
+  carrier: z
+    .object({
+      type: z.literal('twilio-elastic-sip'),
+      /** The LiveKit SIP URI the Twilio trunk's origination URI points at, e.g. `sip:<project>.sip.livekit.cloud`. */
+      originationUri: z.string().optional(),
+      /** The trunk's Termination SIP URI on Twilio (`<name>.pstn.twilio.com`). Needed only when dialing out. */
+      terminationUri: z.string().optional(),
+      /** How Twilio authenticates LiveKit's outbound requests. */
+      terminationAuth: z.enum(['credential-list', 'ip-acl']).optional(),
+      /** The Twilio numbers associated with the trunk (E.164). */
+      numbers: z.array(z.string()).optional(),
+    })
+    .optional(),
+}).passthrough();
+
+/**
+ * Outbound-call policy applied to every `PlaceTwilioCall` / `PlaceVonageCall` / `PlaceRingCentralCall`
+ * mutation, on top of the caller's right to run the agent. Defaults are deliberately conservative.
+ * The rate limiter is in-memory and therefore PER PROCESS: with N MJAPI instances a user can place up to
+ * N × `maxCallsPerUserPerHour` calls.
+ */
+const outboundTelephonySchema = z.object({
+  /** Destination prefixes a call may go to (E.164, e.g. `+1`). An empty list refuses every destination. Defaults to `['+1']`. */
+  allowedPrefixes: z.array(z.string()).optional().default(['+1']),
+  /**
+   * Destination prefixes that are always refused, even when an allowed prefix matches. Deliberately has NO default
+   * here: when omitted, `@memberjunction/telephony-adapters` applies its own `DEFAULT_BLOCKED_PREFIXES` (NANP
+   * premium-rate plus the Caribbean +1 countries abused for toll fraud), so the list lives in exactly one place.
+   * Setting this REPLACES that list.
+   */
+  blockedPrefixes: z.array(z.string()).optional(),
+  /** Max outbound calls one user may place per rolling hour (per process). Defaults to 20. */
+  maxCallsPerUserPerHour: z.coerce.number().int().positive().optional().default(20),
+}).passthrough();
+
 const telephonySchema = z.object({
   /** Master switch. When false (or when no vendor block is present), telephony routes are not mounted. */
   enabled: zodBooleanWithTransforms().default(false),
+  /**
+   * Email of the user INBOUND calls run as. A caller is an anonymous member of the public, so the call needs a
+   * principal to create its agent session and run the agent. Point this at a DEDICATED LEAST-PRIVILEGE user.
+   * There is deliberately no fallback: if unset, unknown, inactive, or the system user, inbound calls are
+   * rejected with a polite message and the rejection is logged. Applies to Twilio, Vonage and RingCentral.
+   */
+  inboundRunAsUserEmail: z.string().optional(),
+  /** Maximum length of one phone call, in seconds. The bridge session is stopped (and the call hung up) at the cap. Defaults to 1800. */
+  maxCallSeconds: z.coerce.number().int().positive().optional().default(1800),
+  /**
+   * Most phone calls (every carrier together, both directions) the server carries at once. Past it an inbound
+   * caller hears "all agents are busy" and an outbound request is refused. Keep it at or below the realtime
+   * model plan's concurrent-session limit. Defaults to 25.
+   */
+  maxConcurrentCalls: z.coerce.number().int().positive().optional().default(25),
+  /** Outbound destination policy + per-user rate limit (see {@link outboundTelephonySchema}). */
+  outbound: outboundTelephonySchema.optional().default({}),
+  /**
+   * The places the agent may hand a live call to, by name (the agent names a target, never a number, an email or an agent
+   * id). `kind` is `number` (the default; a phone number), `user` (a person at an Explorer console, who may accept or
+   * decline; `userEmail`, optional `fallbackNumber` the room dials if they do not take it) or `agent` (another MJ AI agent,
+   * by `agentName`). `user` and `agent` targets work on calls that live in a LiveKit room; a carrier call can only transfer to
+   * a `number`. Every number is validated at startup against the outbound allow/block lists; an invalid entry is dropped
+   * and logged. Empty (the default) means the agent cannot hand calls over at all.
+   */
+  transferTargets: z
+    .array(
+      z.object({
+        name: z.string().min(1),
+        kind: z.enum(['number', 'user', 'agent']).optional(),
+        number: z.string().optional(),
+        userEmail: z.string().optional(),
+        fallbackNumber: z.string().optional(),
+        agentName: z.string().optional(),
+        description: z.string().optional(),
+      }),
+    )
+    .optional()
+    .default([]),
   /** Twilio Programmable Voice + Media Streams binding. */
   twilio: twilioTelephonySchema.optional(),
   /** Vonage Voice + WebSocket-media binding. */
   vonage: vonageTelephonySchema.optional(),
   /** RingCentral Call Control + media-stream binding. */
   ringcentral: ringcentralTelephonySchema.optional(),
+  /** LiveKit SIP binding: phone calls carried by a SIP trunk, landed in a LiveKit room. */
+  livekitSip: livekitSipTelephonySchema.optional(),
   /** Microsoft Teams meetings (Graph cloud-communications + ACS application-hosted media) binding. */
   teams: teamsMeetingsSchema.optional(),
 }).passthrough();
@@ -582,6 +703,7 @@ const configInfoSchema = z.object({
   componentRegistries: z.array(componentRegistrySchema).optional(),
   scheduledJobs: scheduledJobsSchema.optional().default({}),
   integrationSyncWorker: integrationSyncWorkerSchema.optional().default({}),
+  workQueue: WorkQueueSchema.optional().default({}),
   telemetry: telemetrySchema.optional().default({}),
   queryDialects: queryDialectSchema.optional().default({}),
   multiTenancy: multiTenancySchema.optional().default({}),
@@ -632,6 +754,7 @@ export type RealtimeConfig = z.infer<typeof realtimeSchema>;
 export type TwilioTelephonyConfig = z.infer<typeof twilioTelephonySchema>;
 export type VonageTelephonyConfig = z.infer<typeof vonageTelephonySchema>;
 export type RingCentralTelephonyConfig = z.infer<typeof ringcentralTelephonySchema>;
+export type LiveKitSipTelephonyConfig = z.infer<typeof livekitSipTelephonySchema>;
 export type TeamsMeetingsConfig = z.infer<typeof teamsMeetingsSchema>;
 export type DatabaseSettingsInfo = z.infer<typeof databaseSettingsInfoSchema>;
 export type ViewingSystemSettingsInfo = z.infer<typeof viewingSystemInfoSchema>;
@@ -642,6 +765,7 @@ export type AuthProviderConfig = z.infer<typeof authProviderSchema>;
 export type ComponentRegistryConfig = z.infer<typeof componentRegistrySchema>;
 export type ScheduledJobsConfig = z.infer<typeof scheduledJobsSchema>;
 export type IntegrationSyncWorkerConfig = z.infer<typeof integrationSyncWorkerSchema>;
+export type { WorkQueueConfig } from './services/workQueueConfig.js';
 export type TelemetryConfig = z.infer<typeof telemetrySchema>;
 export type QueryDialectConfig = z.infer<typeof queryDialectSchema>;
 export type MultiTenancyConfig = z.infer<typeof multiTenancySchema>;
@@ -775,6 +899,9 @@ export const DEFAULT_SERVER_CONFIG: Partial<ConfigInfo> = {
     maxConcurrentRuns: 3
   },
 
+  // Work queue host defaults (off until an instance opts in)
+  workQueue: DEFAULT_WORK_QUEUE_CONFIG,
+
   // Realtime WebRTC SDP broker defaults (on by default; can be disabled via MJ_REALTIME_ENABLED=false)
   realtime: {
     enabled: RealtimeEnabledDefault(process.env.MJ_REALTIME_ENABLED),

package/src/context.ts

@@ -10,7 +10,8 @@ import { CloneUserForSessionContext } from './auth/sessionUserClone.js';
 import { GetAPIKeyActingContextResolver } from './auth/actingContextResolver.js';
 import { TokenExpiredError, AuthProviderFactory } from '@memberjunction/auth-providers';
 import { AuthCache } from './cache.js';
-import { userEmailMap, apiKey, mj_core_schema } from './config.js';
+import { userEmailMap, apiKey, mj_core_schema, configInfo } from './config.js';
+import { BuildPostgreSQLConnectionConfig, PostgreSQLReadOnlyPool, ResolvePostgreSQLEndpoint, ResolvePostgreSQLReadOnlyCredentials } from './postgresqlPoolSettings.js';
 import { BuildBoundaryLogPayload } from './logging/boundaryLogPayload.js';
 import { StartupLogger } from './logging/StartupLogger.js';
 import { DataSourceInfo, UserPayload } from './types.js';
@@ -831,15 +832,10 @@ async function createPerRequestProviders(
  */
 async function createPostgresProvider(): Promise<DatabaseProviderBase> {
   const { PostgreSQLDataProvider, PostgreSQLProviderConfigData } = await import('@memberjunction/postgresql-dataprovider');
-  const pgHost = process.env.PG_HOST || process.env.DB_HOST || 'localhost';
-  const pgPort = parseInt(process.env.PG_PORT || process.env.DB_PORT || '5432', 10);
-  const pgUser = process.env.PG_USERNAME || process.env.DB_USERNAME || 'postgres';
-  const pgPass = process.env.PG_PASSWORD || process.env.DB_PASSWORD || '';
-  const pgDatabase = process.env.PG_DATABASE || process.env.DB_DATABASE || '';
 
   const pgProvider = new PostgreSQLDataProvider();
   const pgConfig = new PostgreSQLProviderConfigData(
-    { Host: pgHost, Port: pgPort, Database: pgDatabase, User: pgUser, Password: pgPass },
+    BuildPostgreSQLConnectionConfig(ResolvePostgreSQLEndpoint(), configInfo.databaseSettings, 'api'),
     mj_core_schema,
     0,
     undefined,
@@ -859,39 +855,30 @@ async function createPostgresProvider(): Promise<DatabaseProviderBase> {
 }
 
 /**
- * Attempts to create a read-only PostgreSQL provider using DB_READ_ONLY_USERNAME/PASSWORD.
- * Shares the connection pool from the primary provider. Returns null if no read-only credentials are configured.
+ * Creates a read-only PostgreSQL per-request provider on the read-only pool MJAPI opened at
+ * startup with the read-only login. Returns null when no read-only login is configured, so the
+ * caller never falls back to the read-write pool.
  */
 async function tryCreateReadOnlyPostgresProvider(): Promise<DatabaseProviderBase | null> {
-  const roUser = process.env.PG_READ_ONLY_USERNAME || process.env.DB_READ_ONLY_USERNAME;
-  const roPass = process.env.PG_READ_ONLY_PASSWORD || process.env.DB_READ_ONLY_PASSWORD;
-  if (!roUser || !roPass) {
+  const readOnlyPool = PostgreSQLReadOnlyPool.Instance.Pool;
+  const credentials = ResolvePostgreSQLReadOnlyCredentials(configInfo);
+  if (!readOnlyPool || !credentials) {
     return null;
   }
 
   try {
     const { PostgreSQLDataProvider, PostgreSQLProviderConfigData } = await import('@memberjunction/postgresql-dataprovider');
-    const pgHost = process.env.PG_HOST || process.env.DB_HOST || 'localhost';
-    const pgPort = parseInt(process.env.PG_PORT || process.env.DB_PORT || '5432', 10);
-    const pgDatabase = process.env.PG_DATABASE || process.env.DB_DATABASE || '';
 
     const roProvider = new PostgreSQLDataProvider();
     const roConfig = new PostgreSQLProviderConfigData(
-      { Host: pgHost, Port: pgPort, Database: pgDatabase, User: roUser, Password: roPass },
+      BuildPostgreSQLConnectionConfig({ ...ResolvePostgreSQLEndpoint(), ...credentials }, configInfo.databaseSettings, 'read-only'),
       mj_core_schema,
       0,
       undefined,
       undefined,
       false,
     );
-
-    const primaryProvider = Metadata.Provider as unknown as { DatabaseConnection?: import('pg').Pool }; // global-provider-ok: bootstrap (share primary provider's PG pool with the read-only provider)
-    if (primaryProvider?.DatabaseConnection) {
-      await roProvider.ConfigWithSharedPool(roConfig, primaryProvider.DatabaseConnection);
-    } else {
-      await roProvider.Config(roConfig);
-    }
-
+    await roProvider.ConfigWithSharedPool(roConfig, readOnlyPool);
     return roProvider;
   } catch (_err) {
     return null;