@memberjunction/server 5.43.0 → 5.45.0

package/src/agentSessions/SessionJanitor.ts

@@ -170,6 +170,49 @@ export class SessionJanitor extends BaseSingleton<SessionJanitor> implements ISh
         return closed;
     }
 
+    /**
+     * Server-authoritative MAX-DURATION enforcement (public web-widget voice cap, public-web-widget.md
+     * W4). Closes any `Active`/`Idle` session whose stored absolute deadline (`Config_.maxSessionDeadlineIso`)
+     * has passed — a hard wall-clock ceiling that fires regardless of activity, so a public voice guest
+     * cannot run a session indefinitely (cost-bombing) even if the client ignores its own abuse guard.
+     *
+     * Only sessions that CARRY a deadline are loaded (a cheap `Config_ LIKE` pre-filter), then the exact
+     * ISO deadline is parsed and compared in JS (`Config_` is JSON, not a queryable column). Stamped
+     * `CloseReason = 'Janitor'`, idempotent + concurrency-safe like the other sweeps. Returns the count closed.
+     */
+    public async RunMaxDurationSweep(provider: IMetadataProvider, systemUser: UserInfo): Promise<number> {
+        const nowMs = Date.now();
+        // Only consider sessions that carry a deadline marker — keeps this sweep cheap (it never touches
+        // the far-more-common uncapped sessions) while the JS check below enforces the exact deadline.
+        const filter = `Status IN ('Active','Idle') AND Config LIKE '%maxSessionDeadlineIso%'`;
+        const isExpired = (session: MJAIAgentSessionEntity): boolean => {
+            const deadlineMs = this.parseSessionDeadlineMs(session.Config_);
+            return deadlineMs != null && deadlineMs <= nowMs;
+        };
+        const closed = await this.sweepAndClose(filter, provider, systemUser, 'Janitor', isExpired);
+        if (closed > 0) {
+            LogStatus(`[SessionJanitor] Max-duration sweep closed ${closed} session(s) past their hard duration cap`);
+        }
+        return closed;
+    }
+
+    /** Parses the absolute deadline (ms) from a session's `Config_` JSON, or null when absent/malformed. */
+    private parseSessionDeadlineMs(configJson: string | null | undefined): number | null {
+        if (!configJson) {
+            return null;
+        }
+        try {
+            const parsed = JSON.parse(configJson) as { maxSessionDeadlineIso?: string };
+            if (typeof parsed.maxSessionDeadlineIso !== 'string') {
+                return null;
+            }
+            const ms = Date.parse(parsed.maxSessionDeadlineIso);
+            return Number.isNaN(ms) ? null : ms;
+        } catch {
+            return null;
+        }
+    }
+
     // ----- internals -------------------------------------------------------------------------
 
     /** Register for graceful shutdown exactly once. */
@@ -197,6 +240,9 @@ export class SessionJanitor extends BaseSingleton<SessionJanitor> implements ISh
         this._sweepRunning = true;
         try {
             await this.RunStalenessSweep(this._provider, this._systemUser);
+            // Hard wall-clock cap (public web-widget voice). Runs alongside the idle sweep so a capped
+            // session is finalized within one sweep interval of its deadline even if it's still "active".
+            await this.RunMaxDurationSweep(this._provider, this._systemUser);
         } catch (err) {
             LogError(`SessionJanitor periodic sweep failed: ${err instanceof Error ? err.message : String(err)}`);
         } finally {
@@ -215,19 +261,33 @@ export class SessionJanitor extends BaseSingleton<SessionJanitor> implements ISh
         provider: IMetadataProvider,
         systemUser: UserInfo,
         closeReason: SessionCloseReason,
+        shouldClose?: (session: MJAIAgentSessionEntity) => boolean,
     ): Promise<number> {
         let closedCount = 0;
         let afterKey: CompositeKey | undefined;
 
         // eslint-disable-next-line no-constant-condition
         while (true) {
-            const page = await this.fetchPage(filter, afterKey, provider, systemUser);
-            if (page == null) {
+            const fetched = await this.fetchPage(filter, afterKey, provider, systemUser);
+            if (fetched == null) {
                 break; // load failure already logged
             }
-            if (page.length === 0) {
+            if (fetched.length === 0) {
                 break;
             }
+            // Advance the keyset BEFORE the optional JS predicate narrows the page (we must page by the
+            // SQL-matched set, not the post-filtered subset, or pagination would stall/skip).
+            const lastFetchedId = fetched[fetched.length - 1].ID;
+            const fetchedCount = fetched.length;
+            // Optional in-JS narrowing (e.g. exact deadline check the SQL pre-filter can't express).
+            const page = shouldClose ? fetched.filter(shouldClose) : fetched;
+            if (page.length === 0) {
+                if (fetchedCount < SWEEP_PAGE_SIZE) {
+                    break;
+                }
+                afterKey = CompositeKey.FromID(lastFetchedId);
+                continue;
+            }
             // Batch-load every channel for this whole page of sessions in ONE query, then hand each
             // session its own slice to CloseSession — avoids the N+1 channel read (one RunView per
             // closing session) that tripped the sequential / multiple-same-entity telemetry.
@@ -248,10 +308,10 @@ export class SessionJanitor extends BaseSingleton<SessionJanitor> implements ISh
                     closedCount++;
                 }
             }
-            if (page.length < SWEEP_PAGE_SIZE) {
-                break; // partial page => end of data
+            if (fetchedCount < SWEEP_PAGE_SIZE) {
+                break; // partial page (by the SQL-matched set) => end of data
             }
-            afterKey = CompositeKey.FromID(page[page.length - 1].ID);
+            afterKey = CompositeKey.FromID(lastFetchedId);
         }
         return closedCount;
     }

package/src/agentSessions/SessionManager.ts

@@ -7,6 +7,7 @@ import {
 import { AIAgentPermissionHelper } from '@memberjunction/ai-engine-base';
 import { RealtimeClientSessionService, RealtimeChannelServerHost } from '@memberjunction/ai-agents';
 import { GetHostInstanceID } from './HostInstance.js';
+import { writeReturningVisitorRecap } from './ReturningVisitorRecap.js';
 
 /** Entity names — centralised so the `MJ:`-prefix convention is applied in exactly one place. */
 const SESSION_ENTITY = 'MJ: AI Agent Sessions';
@@ -160,6 +161,10 @@ export class SessionManager {
         await this.disconnectChannels(agentSessionID, contextUser, provider, preloadedChannels);
         await this.finalizeObservabilityRuns(session, contextUser, provider);
         await this.notifyChannelPluginsSessionClosed(agentSessionID, closeReason);
+        // Returning-visitor recap (RV2): if this session's conversation is returning-visitor-enabled,
+        // summarize it into an Active memory note so the visitor's next session opens with prior context.
+        // Best-effort + no-op for non-returning-visitor conversations; never blocks teardown.
+        await writeReturningVisitorRecap(session.ConversationID, session.AgentID, contextUser, provider);
         return true;
     }
 
@@ -181,6 +186,9 @@ export class SessionManager {
                     AgentID: session.AgentID,
                     UserID: session.UserID,
                     ConversationID: session.ConversationID ?? null,
+                    // Hand the verbatim per-session config blob to data-aware channels (e.g. the Media
+                    // channel reads a per-session mediaCollectionID override from it). Opaque here.
+                    AgentSessionConfig: session.Config_ ?? null,
                 },
                 contextUser,
                 provider,
@@ -313,6 +321,31 @@ export class SessionManager {
         conversation.NewRecord();
         conversation.UserID = input.userID;
         conversation.Name = 'Agent Session';
+        // For a magic-link-anonymous principal (e.g. a public web-widget voice guest), stamp the
+        // session's conversation with the signed per-session scope so the Widget Guest RLS filters
+        // ({{ScopeResourceID}}) isolate this session — and everything chained to it (AI Agent
+        // Sessions via ConversationID, Session Channels via the session) — from other guests
+        // sharing the Anonymous UserID. No-op for named principals (no scope → default ExternalID).
+        if (contextUser.MagicLinkScope?.ResourceID) {
+            conversation.ExternalID = contextUser.MagicLinkScope.ResourceID;
+        }
+
+        // Returning-visitor memory (RV1/RV2/RV4) for the VOICE path: the widget guest token carries the
+        // resolved VisitorKey / prior-conversation / linked identity (surfaced on ReturningVisitorContext),
+        // so a server-created voice conversation gets the same anchor the text path stamps client-side.
+        // The resolved counterparty reuses the existing polymorphic LinkedEntityID/LinkedRecordID pair.
+        // Absent for non-widget sessions and widgets with returning-visitor memory off — a no-op default.
+        const visitor = contextUser.ReturningVisitorContext;
+        if (visitor?.VisitorKey) {
+            conversation.VisitorKey = visitor.VisitorKey;
+            if (visitor.LastConversationID) {
+                conversation.LastConversationID = visitor.LastConversationID;
+            }
+            if (visitor.LinkedEntityID && visitor.LinkedRecordID) {
+                conversation.LinkedEntityID = visitor.LinkedEntityID;
+                conversation.LinkedRecordID = visitor.LinkedRecordID;
+            }
+        }
 
         const saved = await conversation.Save();
         if (!saved) {
@@ -340,6 +373,14 @@ export class SessionManager {
         session.HostInstanceID = GetHostInstanceID();
         session.Config_ = input.config ?? null;
         session.LastActiveAt = new Date();
+        // Mirror the conversation's resolved counterparty onto the session's own polymorphic pair, so a
+        // session carries its linked identity directly (parallels Conversation.LinkedEntityID/RecordID).
+        // Sourced from the same widget visitor context; a no-op for non-widget / anonymous sessions.
+        const visitor = contextUser.ReturningVisitorContext;
+        if (visitor?.LinkedEntityID && visitor.LinkedRecordID) {
+            session.LinkedEntityID = visitor.LinkedEntityID;
+            session.LinkedRecordID = visitor.LinkedRecordID;
+        }
 
         const saved = await session.Save();
         if (!saved) {

package/src/agentSessions/index.ts

@@ -7,7 +7,7 @@
  *
  * @module @memberjunction/server
  */
-import { LoadWhiteboardChannelServer, LoadMeetingControlsChannelServer } from '@memberjunction/ai-agents';
+import { LoadWhiteboardChannelServer, LoadMeetingControlsChannelServer, LoadMediaChannelServer, LoadClientContextChannelServer } from '@memberjunction/ai-agents';
 import { LoadRemoteBrowserChannel } from '@memberjunction/remote-browser-server';
 import { LoadSelfHostRemoteBrowser } from '@memberjunction/remote-browser-selfhost';
 import { BindRemoteBrowserGoalEngine } from './remoteBrowserGoalEngine.js';
@@ -17,6 +17,8 @@ import { BindRemoteBrowserGoalEngine } from './remoteBrowserGoalEngine.js';
 // the session lifecycle — `SessionManager.CreateSession` resolves them via the ClassFactory.
 LoadWhiteboardChannelServer();
 LoadMeetingControlsChannelServer();
+LoadMediaChannelServer();
+LoadClientContextChannelServer();
 // Remote Browser native channel (client-direct): the lifecycle-only server channel plugin + the
 // Self-Hosted Chrome backend driver (whose default runner launches a local headless Chromium via
 // Playwright — pulled in transitively through the SelfHost package, documented and acceptable).

package/src/auth/magicLink/MagicLinkRouter.ts

@@ -177,6 +177,23 @@ export function createMagicLinkHandler(publicUrl: string, config: MagicLinkConfi
   return { publicRouter, authenticatedRouter };
 }
 
+/**
+ * A minimal PUBLIC router that serves ONLY the JWKS endpoint (the magic-link
+ * signing key's public half). Mount this when the full magic-link flow is
+ * disabled but another feature reuses the same RS256 key + `magic-link` auth
+ * provider — today, the public web widget. Without the published public key the
+ * unified auth middleware cannot validate the reused-key guest tokens and every
+ * request 401s. Assumes the key is already initialized (the widget handler does
+ * this via `MagicLinkKeyManager.Instance.Initialize` at startup).
+ */
+export function createMagicLinkJwksRouter(): Router {
+  const router = Router();
+  router.get('/jwks.json', (_req: Request, res: Response) => {
+    res.status(200).json(MagicLinkKeyManager.Instance.GetJWKS());
+  });
+  return router;
+}
+
 /**
  * Registers the `magic-link` auth provider so MJServer's issuer-driven JWT
  * validation accepts MJ-issued session tokens. Issuer = public URL, JWKS URL =

package/src/auth/magicLink/index.ts

@@ -11,6 +11,7 @@ export { MagicLinkKeyManager } from './MagicLinkKeys.js';
 export { MagicLinkService } from './MagicLinkService.js';
 export {
   createMagicLinkHandler,
+  createMagicLinkJwksRouter,
   registerMagicLinkAuthProvider,
   MAGIC_LINK_MOUNT_PATH,
   MAGIC_LINK_JWKS_PATH,

package/src/auth/magicLink/types.ts

@@ -58,6 +58,32 @@ export interface MagicLinkJWTClaims {
   mj_anon?: boolean;
   /** Opaque per-session id — correlates one anonymous session's activity across audit rows without a real user. */
   mj_sid?: string;
+  /**
+   * Public web widget instance id (additive — set only for widget guest sessions
+   * minted by WidgetSessionService). Binds the synthesized guest principal to one
+   * widget instance so its pinned agent / guest role can be locked down. Absent on
+   * ordinary magic-link sessions.
+   */
+  mj_widget_id?: string;
+  /**
+   * Host-asserted visitor email for a widget `host-identity` session (additive). The
+   * authoritative `email`/`sub` still resolve the constrained shared Anonymous principal;
+   * this carries WHO the host says the visitor is, for the agent to look up their account —
+   * without granting that account's permissions. Absent on anonymous/ordinary sessions.
+   */
+  mj_host_email?: string;
+  /**
+   * Returning-visitor anchor for a widget guest session (additive, RV1). Carried so the VOICE path —
+   * whose conversation is created server-side — can stamp the same Conversation.VisitorKey the text
+   * path stamps client-side. Present only when the widget remembers returning visitors.
+   */
+  mj_visitor_key?: string;
+  /** The prior conversation this visit chains from (RV2), for the voice path to stamp Conversation.LastConversationID. */
+  mj_last_conversation_id?: string;
+  /** Resolved polymorphic identity entity id (RV4), for the voice path to stamp the existing Conversation.LinkedEntityID / AIAgentSession.LinkedEntityID. */
+  mj_linked_entity_id?: string;
+  /** Resolved polymorphic identity record id (RV4), for the voice path to stamp the existing Conversation.LinkedRecordID / AIAgentSession.LinkedRecordID. */
+  mj_linked_record_id?: string;
   /** Marks the session as magic-link so the Explorer can confine the UI. */
   mj_magic_link: true;
 }

package/src/config.ts

@@ -68,23 +68,6 @@ const zodBooleanWithTransforms = () => {
           })
 }
 
-const askSkipInfoSchema = z.object({
-  url: z.string().optional(), // Base URL for Skip API
-  apiKey: z.string().optional(),
-  orgID: z.string().optional(),
-  organizationInfo: z.string().optional(),
-  entitiesToSend: z
-    .object({
-      excludeSchemas: z.array(z.string()).optional(),
-      includeEntitiesFromExcludedSchemas: z.array(z.string()).optional(),
-    })
-    .optional(),
-  chatURL: z.string().optional(),
-  learningCycleRunUponStartup: zodBooleanWithTransforms(),
-  learningCycleEnabled: zodBooleanWithTransforms(),
-  learningCycleURL: z.string().optional(),
-  learningCycleIntervalInMinutes: z.coerce.number().optional(),
-});
 
 const sqlLoggingOptionsSchema = z.object({
   formatAsMigration: z.boolean().optional().default(false),
@@ -330,13 +313,178 @@ const magicLinkSchema = z.object({
   explorerUrl: z.string().optional(),
 }).passthrough();
 
+/**
+ * Public web widget config (plans/realtime/bridges-and-widget/public-web-widget.md).
+ * The widget REUSES the magic-link RS256 key + `anonymous-embed` synthesis, so it
+ * shares the magic-link `audience`/issuer/JWKS by default — the same auth provider
+ * validates both. When `enabled`, the server ensures the magic-link key manager is
+ * initialized and the provider registered even if `magicLink.enabled` is false.
+ */
+const widgetSchema = z.object({
+  /** Master switch. When false, the /widget routes are not mounted. */
+  enabled: zodBooleanWithTransforms().default(false),
+  /**
+   * Which signing mechanism the widget reuses. Only `magic-link` is supported today
+   * (shares MagicLinkKeyManager + the magic-link auth provider). Recorded so a future
+   * dedicated widget key is a config flip, not a code change.
+   */
+  signingReuse: z.enum(['magic-link']).optional().default('magic-link'),
+  /**
+   * Audience claim for minted guest JWTs. MUST equal the magic-link audience so the
+   * auto-registered `magic-link` auth provider validates widget tokens.
+   */
+  audience: z.string().optional().default('mj-magic-link'),
+  /** Email of the shared Anonymous principal used in guest claims (resolves the synthesized guest user). */
+  anonymousEmail: z.string().optional().default('anonymous@magic-link.local'),
+  /** Fallback session-token TTL (minutes) when a widget instance does not set its own. */
+  defaultSessionTtlMinutes: z.coerce.number().optional().default(15),
+  /** Fallback mint rate-limit (per IP per window) when a widget instance does not set its own. */
+  defaultRateLimitPerMinute: z.coerce.number().optional().default(30),
+  /** Rate-limit window (ms) for the public /widget/session endpoints. Default 60s. */
+  rateLimitWindowMs: z.coerce.number().optional().default(60_000),
+  /** Server-wide default hard ceiling (minutes) on a voice session when an instance omits one (W4). */
+  voiceDefaultMaxSessionMinutes: z.coerce.number().optional().default(10),
+  /** Email/name of the internal user whose context READS widget config at mint time (falls back to system/Owner). */
+  contextUserForLookup: z.string().optional(),
+  /**
+   * Host-identity public keys (PEM), keyed by widget PublicKey, for the `host-identity` auth
+   * strategy (D1). The host signs a short-lived RS256 assertion; the mint verifies it against
+   * the key here. INTERIM location — production should store the host key per widget instance
+   * (a HostPublicKey column on WidgetInstance, pending a migration). When a widget's strategy is
+   * HostIdentity and no key is configured here, host mints fail closed.
+   */
+  hostPublicKeys: z.record(z.string(), z.string()).optional().default({}),
+  /**
+   * Returning-visitor identity-resolution target (RV4). When a visitor verifies (magic-link upgrade)
+   * or a host asserts their identity, their email is resolved to a record `(entityName, recordId)`
+   * and prior anonymous memory is merged onto that polymorphic pair. Deployment-configurable so the
+   * resolved record need NOT be an MJ User — point it at any entity that carries the visitor's email
+   * (e.g. a CRM `Persons` table). Defaults to the core `Users` entity keyed by `Email`.
+   */
+  identityResolution: z.object({
+    entityName: z.string().optional().default('Users'),
+    emailField: z.string().optional().default('Email'),
+  }).optional(),
+}).passthrough();
+
+/**
+ * Telephony bridge config (plans/realtime/bridges-and-widget/telephony-vendor-bindings.md).
+ * Holds the per-vendor credentials + public stream URL the MJAPI telephony ingress wires onto
+ * the already-stubbed native SDK seams. Credentials resolve here from `mj.config.cjs` / env —
+ * never inlined in code. When `twilio` is omitted, the Twilio telephony routes are not mounted.
+ */
+const twilioTelephonySchema = z.object({
+  /** Twilio Account SID (`AC…`). */
+  accountSid: z.string(),
+  /** Account auth token — REST auth (when no API key pair) AND the HMAC key for X-Twilio-Signature verification. */
+  authToken: z.string().optional(),
+  /** API Key SID (`SK…`) — preferred over the auth token for REST auth when paired with apiKeySecret. */
+  apiKeySid: z.string().optional(),
+  /** API Key secret — paired with apiKeySid. */
+  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). */
+  webhookSigningSecret: z.string().optional(),
+  /** Optional status-callback URL Twilio posts call lifecycle events to. */
+  statusCallbackUrl: z.string().optional(),
+}).passthrough();
+
+/**
+ * Vonage Voice + WebSocket-media telephony binding. Voice-API auth is application-scoped
+ * (application id + RSA private key) with an optional account API key pair for key-scoped ops;
+ * signatureSecret is the HMAC key for signed-request `sig` AND HS256 webhook-JWT verification.
+ * When `vonage` is omitted, the Vonage telephony routes are not mounted.
+ */
+const vonageTelephonySchema = z.object({
+  /** Vonage Application ID (UUID) — the JWT-auth identity for the Voice API. */
+  applicationId: z.string().optional(),
+  /** The application's RSA private key (PEM) used to sign Voice-API JWTs. */
+  privateKey: z.string().optional(),
+  /** Account API key — used for key-scoped operations when no application credential pair is supplied. */
+  apiKey: z.string().optional(),
+  /** Account API secret — paired with apiKey. */
+  apiSecret: z.string().optional(),
+  /** The publicly reachable `wss://…/telephony/vonage/media` URL the call's connect NCCO opens. */
+  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). */
+  eventUrl: z.string().optional(),
+}).passthrough();
+
+/**
+ * RingCentral telephony binding: **SIP device credentials** for the headless softphone (the
+ * `ringcentral-softphone` SIP/RTP path — the only RingCentral product that carries bidirectional call
+ * audio; the WebSocket "Call Streaming" product is receive-only). These come from a RingCentral
+ * "Other Phone" (BYO-device) registration's SIP info, resolved here from `mj.config.cjs` / env — never
+ * inlined. When `ringcentral` is omitted, the RingCentral softphone is not started.
+ *
+ * Unlike Twilio/Vonage, there is NO public HTTP webhook or media WSS: the softphone is an outbound SIP
+ * registration that receives inbound INVITEs directly over its own SIP/TLS connection. So this block has
+ * no signing secret or public URL — just the SIP device creds + codec.
+ */
+const ringcentralTelephonySchema = z.object({
+  /** SIP domain (e.g. `sip.ringcentral.com`). */
+  sipDomain: z.string(),
+  /** SIP outbound proxy (`host:port`, e.g. `sip10.ringcentral.com:5096`). */
+  sipOutboundProxy: z.string(),
+  /** SIP auth username (the device's phone number / extension). */
+  sipUsername: z.string(),
+  /** SIP auth password (resolved upstream — never inlined). */
+  sipPassword: z.string(),
+  /** SIP authorization id (the device's RingCentral authorization id). */
+  sipAuthorizationId: z.string(),
+  /** Codec to negotiate. Defaults to `OPUS/16000` (clean wideband PCM16 — the least-friction realtime path). */
+  codec: z.enum(['OPUS/16000', 'OPUS/48000/2', 'PCMU/8000']).optional(),
+  /** Skip TLS cert validation (sandbox/test only — never in production). */
+  ignoreTlsCertErrors: zodBooleanWithTransforms().optional().default(false),
+}).passthrough();
+
+/**
+ * Teams meetings bridge config (plans/realtime/bridges-and-widget/meeting-vendor-bindings-teams-slack.md M1).
+ * Holds the bot credentials + Graph webhook shared secret + ACS audio rate the MJAPI meetings ingress wires
+ * onto the Teams binding seams. Credentials resolve here from `mj.config.cjs` / env — never inlined in code.
+ * When `teams` is omitted (or disabled), the Teams meetings routes are not mounted.
+ */
+const teamsMeetingsSchema = z.object({
+  /** Master switch for the Teams meetings ingress. */
+  enabled: zodBooleanWithTransforms().default(false),
+  /** The bot's Azure AD application (client) id (resolved upstream; carried for diagnostics). */
+  appId: z.string().optional(),
+  /** The Azure tenant id the bot operates in. */
+  tenantId: z.string().optional(),
+  /** A pre-resolved OAuth bearer / application token for the bot's Graph calls (resolved upstream — never inline). */
+  botAccessToken: z.string().optional(),
+  /** The shared secret set as `clientState` on the Graph subscription; gates the change-notification webhook. */
+  notificationClientState: z.string().optional(),
+  /** The ACS application-hosted-media PCM sample rate (Hz) the audio plane negotiates. Defaults to 16000. */
+  acsSampleRate: z.coerce.number().optional().default(16000),
+  /** The realtime model's PCM16 sample rate (Hz) the binding resamples to/from. Defaults to 16000. */
+  modelSampleRate: z.coerce.number().optional().default(16000),
+}).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),
+  /** 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(),
+  /** Microsoft Teams meetings (Graph cloud-communications + ACS application-hosted media) binding. */
+  teams: teamsMeetingsSchema.optional(),
+}).passthrough();
+
 const configInfoSchema = z.object({
   userHandling: userHandlingInfoSchema,
   magicLink: magicLinkSchema.optional().default({}),
+  widget: widgetSchema.optional().default({}),
+  telephony: telephonySchema.optional().default({}),
   databaseSettings: databaseSettingsInfoSchema,
   viewingSystem: viewingSystemInfoSchema.optional(),
   restApiOptions: restApiOptionsSchema.optional().default({}),
-  askSkip: askSkipInfoSchema.optional(),
   sqlLogging: sqlLoggingSchema.optional(),
   authProviders: z.array(authProviderSchema).optional(),
   componentRegistries: z.array(componentRegistrySchema).optional(),
@@ -384,10 +532,15 @@ const configInfoSchema = z.object({
 
 export type UserHandlingInfo = z.infer<typeof userHandlingInfoSchema>;
 export type MagicLinkConfig = z.infer<typeof magicLinkSchema>;
+export type WidgetConfig = z.infer<typeof widgetSchema>;
+export type TelephonyConfig = z.infer<typeof telephonySchema>;
+export type TwilioTelephonyConfig = z.infer<typeof twilioTelephonySchema>;
+export type VonageTelephonyConfig = z.infer<typeof vonageTelephonySchema>;
+export type RingCentralTelephonyConfig = z.infer<typeof ringcentralTelephonySchema>;
+export type TeamsMeetingsConfig = z.infer<typeof teamsMeetingsSchema>;
 export type DatabaseSettingsInfo = z.infer<typeof databaseSettingsInfoSchema>;
 export type ViewingSystemSettingsInfo = z.infer<typeof viewingSystemInfoSchema>;
 export type RESTApiOptions = z.infer<typeof restApiOptionsSchema>;
-export type AskSkipInfo = z.infer<typeof askSkipInfoSchema>;
 export type SqlLoggingOptions = z.infer<typeof sqlLoggingOptionsSchema>;
 export type SqlLoggingInfo = z.infer<typeof sqlLoggingSchema>;
 export type AuthProviderConfig = z.infer<typeof authProviderSchema>;
@@ -477,25 +630,6 @@ export const DEFAULT_SERVER_CONFIG: Partial<ConfigInfo> = {
     enabled: false,
   },
 
-  // Ask Skip configuration (environment-driven)
-  askSkip: {
-    url: process.env.ASK_SKIP_URL,
-    chatURL: process.env.ASK_SKIP_CHAT_URL,
-    learningCycleURL: process.env.ASK_SKIP_LEARNING_URL,
-    learningCycleIntervalInMinutes: process.env.ASK_SKIP_LEARNING_CYCLE_INTERVAL_IN_MINUTES
-      ? parseInt(process.env.ASK_SKIP_LEARNING_CYCLE_INTERVAL_IN_MINUTES, 10)
-      : undefined,
-    learningCycleEnabled: process.env.ASK_SKIP_RUN_LEARNING_CYCLES === 'true',
-    learningCycleRunUponStartup: process.env.ASK_SKIP_RUN_LEARNING_CYCLES_UPON_STARTUP === 'true',
-    orgID: process.env.ASK_SKIP_ORGANIZATION_ID,
-    apiKey: process.env.ASK_SKIP_API_KEY,
-    organizationInfo: process.env.ASK_SKIP_ORGANIZATION_INFO,
-    entitiesToSend: {
-      excludeSchemas: [],
-      includeEntitiesFromExcludedSchemas: [],
-    },
-  },
-
   // SQL logging defaults
   sqlLogging: {
     enabled: true,

package/src/context.ts

@@ -15,7 +15,7 @@ import { GetReadOnlyDataSource, GetReadWriteDataSource } from './util.js';
 import { v4 as uuidv4 } from 'uuid';
 import e from 'express';
 import type { RequestHandler, Request, Response, NextFunction } from 'express';
-import { DatabaseProviderBase, UserInfo, type MagicLinkScope } from '@memberjunction/core';
+import { DatabaseProviderBase, UserInfo, type MagicLinkScope, type ReturningVisitorContext, type WidgetGuestContext } from '@memberjunction/core';
 import { SQLServerDataProvider, SQLServerProviderConfigData, UserCache } from '@memberjunction/sqlserver-dataprovider';
 import { Metadata } from '@memberjunction/core';
 import { UUIDsEqual } from '@memberjunction/global';
@@ -242,8 +242,17 @@ function buildMagicLinkSessionUser(userRecord: UserInfo, payload: jwt.JwtPayload
     }
   }
 
-  // Named session with no resource scope → no per-request state needed, use the cached user.
-  if (!isAnon && !scope) {
+  // Returning-visitor context (RV1/RV2/RV4): carried on a widget guest token so the voice path
+  // (server-created conversation) stamps the same returning-visitor anchor + resolved identity.
+  const visitorContext = extractReturningVisitorContext(payload);
+
+  // Widget-instance identity (mj_widget_id): present on every public web-widget guest token. The
+  // privileged agent-dispatch path reads it to resolve the AUTHORITATIVE pinned agent for the guest
+  // (so a guest can never run an arbitrary agent under the elevated server principal).
+  const widgetGuestContext = extractWidgetGuestContext(payload);
+
+  // Named session with no resource scope and no widget/visitor context → no per-request state needed.
+  if (!isAnon && !scope && !visitorContext && !widgetGuestContext) {
     return userRecord;
   }
 
@@ -255,6 +264,12 @@ function buildMagicLinkSessionUser(userRecord: UserInfo, payload: jwt.JwtPayload
   if (scope) {
     sessionUser.MagicLinkScope = scope;
   }
+  if (visitorContext) {
+    sessionUser.ReturningVisitorContext = visitorContext;
+  }
+  if (widgetGuestContext) {
+    sessionUser.WidgetGuestContext = widgetGuestContext;
+  }
   if (isAnon) {
     // Mark the session so the CurrentUser field resolver serves these synthesized roles
     // (the shared Anonymous principal holds none in the DB). See UserInfo.IsMagicLinkAnonymous.
@@ -263,6 +278,38 @@ function buildMagicLinkSessionUser(userRecord: UserInfo, payload: jwt.JwtPayload
   return sessionUser;
 }
 
+/**
+ * Extracts the returning-visitor context (RV1/RV2/RV4) from a widget guest token's claims, or
+ * undefined when the token carries no VisitorKey (the default, remembering-off case). Used so the
+ * voice path can stamp the conversation with the same anchor/identity the text path stamps client-side.
+ */
+function extractReturningVisitorContext(payload: jwt.JwtPayload): ReturningVisitorContext | undefined {
+  const visitorKey = payload['mj_visitor_key'];
+  if (typeof visitorKey !== 'string' || !visitorKey) {
+    return undefined;
+  }
+  const str = (v: unknown): string | undefined => (typeof v === 'string' && v ? v : undefined);
+  return {
+    VisitorKey: visitorKey,
+    LastConversationID: str(payload['mj_last_conversation_id']),
+    LinkedEntityID: str(payload['mj_linked_entity_id']),
+    LinkedRecordID: str(payload['mj_linked_record_id']),
+  };
+}
+
+/**
+ * Extracts the widget-instance identity (`mj_widget_id`) from a public web-widget guest token, or
+ * undefined when the token carries none (every non-widget session). Carried so the privileged
+ * agent-dispatch path can resolve the authoritative pinned agent for the guest from the trusted token.
+ */
+function extractWidgetGuestContext(payload: jwt.JwtPayload): WidgetGuestContext | undefined {
+  const widgetId = payload['mj_widget_id'];
+  if (typeof widgetId !== 'string' || !widgetId) {
+    return undefined;
+  }
+  return { WidgetID: widgetId };
+}
+
 const verifyAsync = async (issuer: string, token: string): Promise<jwt.JwtPayload> =>
   new Promise((resolve, reject) => {
     const options = getValidationOptions(issuer);