@memberjunction/server 5.44.0 → 5.45.1

package/src/__tests__/widgetHostIdentity.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect } from 'vitest';
+import jwt from 'jsonwebtoken';
+import { generateKeyPairSync } from 'node:crypto';
+import { verifyHostAssertion, extractHostIdentity } from '../realtimeWidget/host-identity.js';
+import { buildWidgetGuestClaims } from '../realtimeWidget/widgetCore.js';
+
+/** A throwaway RSA keypair for signing test host assertions. */
+function keypair(): { privatePem: string; publicPem: string } {
+    const { privateKey, publicKey } = generateKeyPairSync('rsa', { modulusLength: 2048 });
+    return {
+        privatePem: privateKey.export({ type: 'pkcs8', format: 'pem' }) as string,
+        publicPem: publicKey.export({ type: 'spki', format: 'pem' }) as string,
+    };
+}
+
+const WIDGET_KEY = 'pk_live_acme';
+
+function sign(privatePem: string, claims: Record<string, unknown>, opts: jwt.SignOptions = {}): string {
+    return jwt.sign(claims, privatePem, { algorithm: 'RS256', audience: WIDGET_KEY, expiresIn: '5m', ...opts });
+}
+
+describe('verifyHostAssertion', () => {
+    it('accepts a valid host assertion and extracts the identity', () => {
+        const kp = keypair();
+        const token = sign(kp.privatePem, { email: 'jane@acme.com', given_name: 'Jane', family_name: 'Doe', sub: 'host-123' });
+        const result = verifyHostAssertion(token, kp.publicPem, WIDGET_KEY);
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.identity).toMatchObject({ email: 'jane@acme.com', firstName: 'Jane', lastName: 'Doe', hostUserId: 'host-123' });
+        }
+    });
+
+    it('rejects a missing assertion', () => {
+        const kp = keypair();
+        expect(verifyHostAssertion(undefined, kp.publicPem, WIDGET_KEY)).toEqual({ ok: false, errorCode: 'missing' });
+    });
+
+    it('rejects when no host key is configured (fail-closed)', () => {
+        const kp = keypair();
+        const token = sign(kp.privatePem, { email: 'x@y.com' });
+        expect(verifyHostAssertion(token, undefined, WIDGET_KEY)).toEqual({ ok: false, errorCode: 'no_key' });
+    });
+
+    it('rejects a signature from the wrong key', () => {
+        const signer = keypair();
+        const other = keypair();
+        const token = sign(signer.privatePem, { email: 'x@y.com' });
+        expect(verifyHostAssertion(token, other.publicPem, WIDGET_KEY)).toEqual({ ok: false, errorCode: 'bad_signature' });
+    });
+
+    it('rejects a wrong-audience assertion', () => {
+        const kp = keypair();
+        const token = sign(kp.privatePem, { email: 'x@y.com' }, { audience: 'pk_live_someone_else' });
+        expect(verifyHostAssertion(token, kp.publicPem, WIDGET_KEY)).toEqual({ ok: false, errorCode: 'bad_signature' });
+    });
+
+    it('rejects an expired assertion', () => {
+        const kp = keypair();
+        const token = sign(kp.privatePem, { email: 'x@y.com' }, { expiresIn: -10 });
+        expect(verifyHostAssertion(token, kp.publicPem, WIDGET_KEY)).toEqual({ ok: false, errorCode: 'expired' });
+    });
+
+    it('rejects an assertion with no email', () => {
+        const kp = keypair();
+        const token = sign(kp.privatePem, { given_name: 'NoEmail' });
+        expect(verifyHostAssertion(token, kp.publicPem, WIDGET_KEY)).toEqual({ ok: false, errorCode: 'no_email' });
+    });
+
+    it('rejects an assertion with no exp (unbounded lifetime)', () => {
+        const kp = keypair();
+        // Sign directly with no expiresIn so the token carries iat but no exp.
+        const token = jwt.sign({ email: 'x@y.com' }, kp.privatePem, { algorithm: 'RS256', audience: WIDGET_KEY });
+        expect(verifyHostAssertion(token, kp.publicPem, WIDGET_KEY)).toEqual({ ok: false, errorCode: 'expired' });
+    });
+
+    it('rejects an assertion older than the maxAge cap even when its exp is still in the future', () => {
+        const kp = keypair();
+        const nowSec = Math.floor(Date.now() / 1000);
+        // iat one hour ago (well past the 10m maxAge) with a far-future exp — the age cap must still reject it.
+        const token = jwt.sign({ email: 'x@y.com', iat: nowSec - 3600, exp: nowSec + 3600 }, kp.privatePem, {
+            algorithm: 'RS256',
+            audience: WIDGET_KEY,
+        });
+        expect(verifyHostAssertion(token, kp.publicPem, WIDGET_KEY)).toEqual({ ok: false, errorCode: 'expired' });
+    });
+});
+
+describe('buildWidgetGuestClaims with hostIdentity', () => {
+    it('carries the host identity as INFORMATIONAL claims but keeps the Anonymous principal email', () => {
+        const claims = buildWidgetGuestClaims({
+            issuer: 'iss',
+            audience: 'mj-magic-link',
+            widgetId: 'W',
+            sessionId: 's',
+            anonymousEmail: 'anonymous@magic-link.local',
+            applicationId: 'A',
+            guestRoleName: 'Widget Guest',
+            nowSeconds: 1000,
+            ttlSeconds: 900,
+            hostIdentity: { email: 'jane@acme.com', firstName: 'Jane', lastName: 'Doe' },
+        });
+        // Principal-resolving email stays anonymous (no escalation into a real account).
+        expect(claims.email).toBe('anonymous@magic-link.local');
+        expect(claims.mj_anon).toBe(true);
+        // Host identity rides as informational claims.
+        expect(claims.mj_host_email).toBe('jane@acme.com');
+        expect(claims.given_name).toBe('Jane');
+        expect(claims.name).toBe('Jane Doe');
+    });
+});
+
+describe('extractHostIdentity', () => {
+    it('tolerates firstName/lastName fallbacks', () => {
+        const id = extractHostIdentity({ email: 'a@b.com', firstName: 'Al', lastName: 'Bo' });
+        expect(id).toMatchObject({ email: 'a@b.com', firstName: 'Al', lastName: 'Bo' });
+    });
+});

package/src/agentSessions/ReturningVisitorRecap.ts

@@ -0,0 +1,242 @@
+/**
+ * @fileoverview Returning-visitor recap (RV2). When a returning-visitor-enabled conversation ends,
+ * summarize its transcript into an Active agent memory note so the visitor's NEXT session opens with
+ * prior context. The recap is written through the EXISTING agent-notes system (MJ: AI Agent Notes) and
+ * is scoped via the existing polymorphic note scope (PrimaryScopeEntityID + PrimaryScopeRecordID):
+ *
+ *   - resolved visitor  → scope = (Conversation.LinkedEntityID, Conversation.LinkedRecordID)
+ *   - anonymous visitor → scope = (the "MJ: Conversations" entity, this conversation's ID)
+ *
+ * The anonymous scope lets the return-side injector (RV3) resolve the recap by following the
+ * VisitorKey chain (the next conversation's LastConversationID points back here). Either way the
+ * Memory Manager's existing hardening / consolidation / decay maintains the note from here on, and the
+ * existing memory injection (which already filters by the PrimaryScope pair) pulls it in — no parallel
+ * store and no new injection path (per AN-BC's "reuse the memory system" guidance).
+ *
+ * The recap TEXT is produced by the metadata-defined "Returning-Visitor Recap" AI prompt via
+ * AIPromptRunner (MJ's prompt infra) — not a hand-rolled summarizer. The prompt emits NO_RECAP when a
+ * conversation has nothing worth remembering, in which case no note is written.
+ *
+ * Everything here is BEST-EFFORT: a recap failure must never affect session teardown or the visitor.
+ *
+ * @module @memberjunction/server/agentSessions
+ */
+
+import { RunView, UserInfo, LogError, LogStatus, type IMetadataProvider } from '@memberjunction/core';
+import type { MJConversationEntity, MJConversationDetailEntity, MJAIAgentNoteEntity } from '@memberjunction/core-entities';
+import { AIEngine } from '@memberjunction/aiengine';
+import { AIPromptParams } from '@memberjunction/ai-core-plus';
+import { AIPromptRunner } from '@memberjunction/ai-prompts';
+
+const CONVERSATIONS_ENTITY = 'MJ: Conversations';
+const CONVERSATION_DETAILS_ENTITY = 'MJ: Conversation Details';
+const AGENT_NOTES_ENTITY = 'MJ: AI Agent Notes';
+const RECAP_PROMPT_NAME = 'Returning-Visitor Recap';
+
+/** The recap prompt returns this sentinel when a conversation has nothing worth remembering. */
+const NO_RECAP_SENTINEL = 'NO_RECAP';
+
+/** Cap the transcript we summarize (most recent turns) to bound prompt size + cost. */
+const MAX_TRANSCRIPT_TURNS = 60;
+
+/**
+ * Writes a returning-visitor recap note for a finished conversation. Idempotent (skips when a recap for
+ * this conversation already exists) and no-ops for conversations that aren't returning-visitor-enabled.
+ * Never throws.
+ *
+ * @param conversationId the conversation that just ended
+ * @param agentId the agent the recap is attributed to (the session/pinned agent), or null
+ * @param contextUser server context user
+ * @param provider the provider servicing this request/session
+ * @param retentionDays optional per-widget retention; when > 0 the recap note is stamped with an
+ *   `ExpiresAt` that many days out (the Memory Manager's decay phase reaps expired notes). Omit/0
+ *   for no expiry (system default retention applies).
+ */
+export async function writeReturningVisitorRecap(
+  conversationId: string | null | undefined,
+  agentId: string | null | undefined,
+  contextUser: UserInfo,
+  provider: IMetadataProvider,
+  retentionDays?: number | null,
+): Promise<void> {
+  try {
+    if (!conversationId) {
+      return;
+    }
+    LogStatus(`[ReturningVisitorRecap] START for prior conversation ${conversationId}`);
+    const conversation = await getEntity<MJConversationEntity>(provider, CONVERSATIONS_ENTITY, contextUser);
+    if (!conversation || !(await conversation.Load(conversationId))) {
+      LogError(`[ReturningVisitorRecap] could not load conversation ${conversationId} — bailing`);
+      return;
+    }
+
+    const scope = resolveRecapScope(conversation, provider);
+    if (!scope) {
+      // Not a returning-visitor conversation (no VisitorKey, no resolved identity) — nothing to remember.
+      LogStatus(`[ReturningVisitorRecap] no scope (no VisitorKey/resolved identity) for ${conversationId} — bailing`);
+      return;
+    }
+
+    if (await recapAlreadyExists(conversationId, contextUser)) {
+      LogStatus(`[ReturningVisitorRecap] recap already exists for ${conversationId} — skipping`);
+      return;
+    }
+
+    const transcript = await loadTranscript(conversationId, contextUser);
+    if (!transcript) {
+      LogStatus(`[ReturningVisitorRecap] empty transcript for ${conversationId} — bailing`);
+      return;
+    }
+    LogStatus(`[ReturningVisitorRecap] transcript loaded (${transcript.length} chars) for ${conversationId}; running recap prompt`);
+
+    const recap = await summarizeTranscript(transcript, contextUser);
+    if (!recap || recap.trim().toUpperCase().startsWith(NO_RECAP_SENTINEL)) {
+      LogStatus(`[ReturningVisitorRecap] prompt returned ${recap ? 'NO_RECAP' : 'no/empty result'} for ${conversationId} — no note written`);
+      return;
+    }
+
+    await persistRecapNote({ recap, scope, conversationId, agentId, contextUser, provider, retentionDays });
+  } catch (e) {
+    LogError(`[ReturningVisitorRecap] best-effort recap failed for conversation ${conversationId}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+}
+
+/** The polymorphic scope a recap note is filed under. */
+interface RecapScope {
+  entityId: string;
+  recordId: string;
+}
+
+/**
+ * Resolves the note scope for this conversation, or undefined when it isn't a returning-visitor
+ * conversation. Resolved identity wins (R1 polymorphic pair); otherwise an anonymous visitor's recap
+ * is filed against the conversation itself so the VisitorKey chain resolves it on the next visit.
+ */
+function resolveRecapScope(conversation: MJConversationEntity, provider: IMetadataProvider): RecapScope | undefined {
+  if (conversation.LinkedEntityID && conversation.LinkedRecordID) {
+    return { entityId: conversation.LinkedEntityID, recordId: conversation.LinkedRecordID };
+  }
+  if (conversation.VisitorKey) {
+    const conversationsEntityId = provider.Entities.find((e) => e.Name === CONVERSATIONS_ENTITY)?.ID;
+    if (conversationsEntityId) {
+      return { entityId: conversationsEntityId, recordId: conversation.ID };
+    }
+  }
+  return undefined;
+}
+
+/** True when an auto-generated recap note already exists for this conversation (idempotency). */
+async function recapAlreadyExists(conversationId: string, contextUser: UserInfo): Promise<boolean> {
+  const rv = new RunView();
+  const result = await rv.RunView<{ ID: string }>(
+    {
+      EntityName: AGENT_NOTES_ENTITY,
+      ExtraFilter: `SourceConversationID = '${conversationId}' AND IsAutoGenerated = 1 AND Type = 'Context'`,
+      Fields: ['ID'],
+      MaxRows: 1,
+      ResultType: 'simple',
+    },
+    contextUser,
+  );
+  return result.Success && (result.Results?.length ?? 0) > 0;
+}
+
+/** Builds a compact transcript string from the conversation's most-recent detail turns. */
+async function loadTranscript(conversationId: string, contextUser: UserInfo): Promise<string | undefined> {
+  const rv = new RunView();
+  const result = await rv.RunView<MJConversationDetailEntity>(
+    {
+      EntityName: CONVERSATION_DETAILS_ENTITY,
+      ExtraFilter: `ConversationID = '${conversationId}'`,
+      OrderBy: '__mj_CreatedAt DESC',
+      MaxRows: MAX_TRANSCRIPT_TURNS,
+      ResultType: 'entity_object',
+    },
+    contextUser,
+  );
+  if (!result.Success || result.Results.length === 0) {
+    return undefined;
+  }
+  // RunView returned newest-first; reverse to chronological for a readable transcript.
+  const lines = result.Results.slice()
+    .reverse()
+    .map((d) => `${d.Role ?? 'User'}: ${(d.Message ?? '').trim()}`)
+    .filter((l) => l.length > 0);
+  return lines.length > 0 ? lines.join('\n') : undefined;
+}
+
+/** Runs the metadata-defined recap prompt over the transcript and returns its plain-text recap. */
+async function summarizeTranscript(transcript: string, contextUser: UserInfo): Promise<string | undefined> {
+  await AIEngine.Instance.Config(false, contextUser);
+  const promptEntity = AIEngine.Instance.Prompts.find((p) => p.Name?.trim().toLowerCase() === RECAP_PROMPT_NAME.toLowerCase());
+  if (!promptEntity) {
+    LogError(`[ReturningVisitorRecap] recap prompt '${RECAP_PROMPT_NAME}' not found — push metadata/prompts. Skipping recap.`);
+    return undefined;
+  }
+  LogStatus(`[ReturningVisitorRecap] using prompt '${promptEntity.Name}' (strategy=${promptEntity.SelectionStrategy}, status=${promptEntity.Status})`);
+  const params = new AIPromptParams();
+  params.prompt = promptEntity;
+  params.contextUser = contextUser;
+  params.data = { transcript };
+  const result = await new AIPromptRunner().ExecutePrompt(params);
+  if (!result.success) {
+    LogError(`[ReturningVisitorRecap] recap prompt failed: ${result.errorMessage ?? 'unknown'}`);
+    return undefined;
+  }
+  const text = typeof result.rawResult === 'string' ? result.rawResult : String(result.rawResult ?? '');
+  LogStatus(`[ReturningVisitorRecap] prompt succeeded; recap preview: "${text.trim().slice(0, 120)}"`);
+  return text.trim() || undefined;
+}
+
+/** Persists the recap as an Active, auto-generated, Context-typed agent note under the resolved scope. */
+async function persistRecapNote(args: {
+  recap: string;
+  scope: RecapScope;
+  conversationId: string;
+  agentId: string | null | undefined;
+  contextUser: UserInfo;
+  provider: IMetadataProvider;
+  retentionDays?: number | null;
+}): Promise<void> {
+  const note = await getEntity<MJAIAgentNoteEntity>(args.provider, AGENT_NOTES_ENTITY, args.contextUser);
+  if (!note) {
+    return;
+  }
+  note.NewRecord();
+  if (args.agentId) {
+    note.AgentID = args.agentId;
+  }
+  note.Note = args.recap;
+  note.Type = 'Context';
+  note.Status = 'Active';
+  note.AuthorType = 'MemoryManager';
+  note.IsAutoGenerated = true;
+  note.PrimaryScopeEntityID = args.scope.entityId;
+  note.PrimaryScopeRecordID = args.scope.recordId;
+  note.SourceConversationID = args.conversationId;
+  // Per-widget retention: stamp an expiry the Memory Manager's decay phase honors. Omitted/≤0 ⇒ no
+  // expiry (system-default retention). One day = 86_400_000 ms.
+  if (args.retentionDays && args.retentionDays > 0) {
+    note.ExpiresAt = new Date(Date.now() + args.retentionDays * 86_400_000);
+  }
+  const saved = await note.Save();
+  if (!saved) {
+    LogError(`[ReturningVisitorRecap] failed to save recap note: ${note.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+    return;
+  }
+  LogStatus(`[ReturningVisitorRecap] wrote recap note ${note.ID} scoped to ${args.scope.entityId}/${args.scope.recordId} for conversation ${args.conversationId}`);
+}
+
+/** GetEntityObject via the request/session provider (multi-provider-safe — never the global Metadata). */
+async function getEntity<T extends import('@memberjunction/core').BaseEntity>(
+  provider: IMetadataProvider,
+  entityName: string,
+  contextUser: UserInfo,
+): Promise<T | null> {
+  try {
+    return await provider.GetEntityObject<T>(entityName, contextUser);
+  } catch (e) {
+    LogError(`[ReturningVisitorRecap] GetEntityObject('${entityName}') failed: ${e instanceof Error ? e.message : String(e)}`);
+    return null;
+  }
+}

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;
     }
 
@@ -316,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) {
@@ -343,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/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/MagicLinkService.ts

@@ -640,6 +640,13 @@ export class MagicLinkService {
    * a single atomic operation. Returns true ONLY when this call updated the row
    * (won the race); concurrent redemptions of a single-use link see 0 rows.
    *
+   * Dialect-aware: SQL Server uses an `OUTPUT`-into-table-variable win-detect;
+   * PostgreSQL uses `UPDATE … WHERE … RETURNING` (the WHERE guard is itself the
+   * atomic single-use gate). The platform is read from the provider itself
+   * (`PlatformKey`), not from process env, so this is correct even under a
+   * non-default per-connection provider. The invite ID always binds as a
+   * parameter (`@p0` / `$1`), never interpolated.
+   *
    * Fail-closed: any DB error returns false and the redemption is rejected.
    */
   private async consumeInvite(invite: MJMagicLinkInviteEntity, provider: DatabaseProviderBase, contextUser: UserInfo): Promise<boolean> {
@@ -649,9 +656,12 @@ export class MagicLinkService {
         LogError(`[MagicLink] Entity metadata for '${INVITE_ENTITY}' not found; cannot consume invite.`);
         return false;
       }
-      const table = `[${entityInfo.SchemaName}].[${entityInfo.BaseTable}]`;
-      // OUTPUT returns one row iff the WHERE matched — the atomic single-use gate.
-      const sql = buildConsumeInviteSQL(table);
+      const isPg = provider.PlatformKey === 'postgresql';
+      // PG identifiers are auto-quoted by PostgreSQLDataProvider.ExecuteSQL, so
+      // pass the bare `schema.table`; SQL Server takes the bracket-quoted form.
+      const table = isPg ? `${entityInfo.SchemaName}.${entityInfo.BaseTable}` : `[${entityInfo.SchemaName}].[${entityInfo.BaseTable}]`;
+      // OUTPUT/RETURNING yields one row iff the WHERE matched — the atomic single-use gate.
+      const sql = buildConsumeInviteSQL(table, isPg ? 'postgresql' : 'sqlserver');
       const rows = await provider.ExecuteSQL<{ ID: string }>(sql, [invite.ID], { isMutation: true }, contextUser);
       return Array.isArray(rows) && rows.length === 1;
     } catch (e) {

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,