@memberjunction/server 5.43.0 → 5.45.0

package/src/__tests__/widget.test.ts

@@ -0,0 +1,204 @@
+import { describe, it, expect } from 'vitest';
+import jwt from 'jsonwebtoken';
+import { createPublicKey } from 'node:crypto';
+import {
+  parseAllowedOrigins,
+  isOriginAllowed,
+  isModalityEnabled,
+  evaluateWidgetMint,
+  buildWidgetGuestClaims,
+  looksLikeBot,
+} from '../realtimeWidget/widgetCore.js';
+import { MagicLinkKeyManager } from '../auth/magicLink/MagicLinkKeys.js';
+
+describe('widget core — parseAllowedOrigins', () => {
+  it('parses a JSON array of origins', () => {
+    expect(parseAllowedOrigins('["https://a.com","https://b.com"]')).toEqual(['https://a.com', 'https://b.com']);
+  });
+
+  it('tolerates a comma-separated string', () => {
+    expect(parseAllowedOrigins('https://a.com, https://b.com')).toEqual(['https://a.com', 'https://b.com']);
+  });
+
+  it('normalizes case and strips trailing slashes', () => {
+    expect(parseAllowedOrigins('["HTTPS://Acme.COM/"]')).toEqual(['https://acme.com']);
+  });
+
+  it('returns empty (fail-closed) for null / blank / non-array JSON', () => {
+    expect(parseAllowedOrigins(null)).toEqual([]);
+    expect(parseAllowedOrigins('   ')).toEqual([]);
+    expect(parseAllowedOrigins('{"not":"an-array"}')).toEqual([]);
+  });
+});
+
+describe('widget core — isOriginAllowed (fail-closed)', () => {
+  const allowed = ['https://acme.com', 'https://www.acme.com'];
+
+  it('accepts an exact (normalized) match', () => {
+    expect(isOriginAllowed('https://acme.com', allowed)).toBe(true);
+    expect(isOriginAllowed('HTTPS://ACME.COM/', allowed)).toBe(true);
+  });
+
+  it('rejects a non-listed origin', () => {
+    expect(isOriginAllowed('https://evil.com', allowed)).toBe(false);
+    expect(isOriginAllowed('https://sub.acme.com', allowed)).toBe(false);
+  });
+
+  it('rejects a missing request origin', () => {
+    expect(isOriginAllowed(undefined, allowed)).toBe(false);
+    expect(isOriginAllowed('', allowed)).toBe(false);
+  });
+
+  it('rejects everything when the allowlist is empty (never "*")', () => {
+    expect(isOriginAllowed('https://acme.com', [])).toBe(false);
+  });
+});
+
+describe('widget core — isModalityEnabled', () => {
+  it('Both enables text and voice', () => {
+    expect(isModalityEnabled('Both', 'Text')).toBe(true);
+    expect(isModalityEnabled('Both', 'Voice')).toBe(true);
+  });
+  it('Text enables only text', () => {
+    expect(isModalityEnabled('Text', 'Text')).toBe(true);
+    expect(isModalityEnabled('Text', 'Voice')).toBe(false);
+  });
+  it('Voice enables only voice', () => {
+    expect(isModalityEnabled('Voice', 'Voice')).toBe(true);
+    expect(isModalityEnabled('Voice', 'Text')).toBe(false);
+  });
+});
+
+describe('widget core — evaluateWidgetMint', () => {
+  const base = { Status: 'Active', AllowedOrigins: '["https://acme.com"]', Modality: 'Both' };
+
+  it('passes for an active widget from an allowed origin', () => {
+    expect(evaluateWidgetMint(base, 'https://acme.com')).toEqual({ ok: true });
+  });
+
+  it('rejects a disabled widget', () => {
+    expect(evaluateWidgetMint({ ...base, Status: 'Disabled' }, 'https://acme.com')).toEqual({
+      ok: false,
+      errorCode: 'disabled',
+    });
+  });
+
+  it('rejects a disallowed origin', () => {
+    expect(evaluateWidgetMint(base, 'https://evil.com')).toEqual({ ok: false, errorCode: 'origin_not_allowed' });
+  });
+
+  it('rejects a missing origin (fail-closed)', () => {
+    expect(evaluateWidgetMint(base, undefined)).toEqual({ ok: false, errorCode: 'origin_not_allowed' });
+  });
+});
+
+describe('widget core — buildWidgetGuestClaims', () => {
+  const args = {
+    issuer: 'https://mj.example.com',
+    audience: 'mj-magic-link',
+    widgetId: 'WIDGET-123',
+    sessionId: 'sess-abc',
+    anonymousEmail: 'anonymous@magic-link.local',
+    applicationId: 'APP-1',
+    guestRoleName: 'Widget Guest',
+    nowSeconds: 1_000_000,
+    ttlSeconds: 900,
+  };
+
+  it('marks the session anonymous + magic-link and binds the widget id', () => {
+    const claims = buildWidgetGuestClaims(args);
+    expect(claims.mj_anon).toBe(true);
+    expect(claims.mj_magic_link).toBe(true);
+    expect(claims.mj_widget_id).toBe('WIDGET-123');
+  });
+
+  it('scopes to the application + guest role and the configured anon email', () => {
+    const claims = buildWidgetGuestClaims(args);
+    expect(claims.mj_app_id).toBe('APP-1');
+    expect(claims.mj_role).toBe('Widget Guest');
+    expect(claims.email).toBe('anonymous@magic-link.local');
+    expect(claims.sub).toBe('magic-link|sess-abc');
+    expect(claims.mj_sid).toBe('sess-abc');
+  });
+
+  it('carries a single scope entry for the guest grant', () => {
+    const claims = buildWidgetGuestClaims(args);
+    expect(claims.mj_scopes).toHaveLength(1);
+    expect(claims.mj_scopes?.[0]).toMatchObject({ appId: 'APP-1', role: 'Widget Guest' });
+  });
+
+  it('sets exp = iat + ttl', () => {
+    const claims = buildWidgetGuestClaims(args);
+    expect(claims.iat).toBe(1_000_000);
+    expect(claims.exp).toBe(1_000_900);
+  });
+});
+
+describe('widget core — RS256 sign + verify roundtrip (reuses MagicLinkKeyManager)', () => {
+  it('mints a widget guest token that verifies against the published JWKS with the widget claim intact', () => {
+    const km = MagicLinkKeyManager.Instance;
+    km.Initialize(); // ephemeral keypair (idempotent if already initialized in-process)
+
+    const claims = buildWidgetGuestClaims({
+      issuer: 'https://mj.example.com',
+      audience: 'mj-magic-link',
+      widgetId: 'WIDGET-XYZ',
+      sessionId: 'sess-roundtrip',
+      anonymousEmail: 'anonymous@magic-link.local',
+      applicationId: 'APP-9',
+      guestRoleName: 'Widget Guest',
+      nowSeconds: Math.floor(Date.now() / 1000),
+      ttlSeconds: 900,
+    });
+    const token = km.Sign(claims);
+
+    const publicKey = createPublicKey({ key: km.GetJWKS().keys[0] as object, format: 'jwk' });
+    const decoded = jwt.verify(token, publicKey, { algorithms: ['RS256'], audience: 'mj-magic-link' }) as jwt.JwtPayload;
+
+    expect(decoded.mj_widget_id).toBe('WIDGET-XYZ');
+    expect(decoded.mj_anon).toBe(true);
+    expect(decoded.mj_magic_link).toBe(true);
+    expect(decoded.mj_app_id).toBe('APP-9');
+  });
+
+  it('rejects a tampered widget token', () => {
+    const km = MagicLinkKeyManager.Instance;
+    km.Initialize();
+    const claims = buildWidgetGuestClaims({
+      issuer: 'https://mj.example.com',
+      audience: 'mj-magic-link',
+      widgetId: 'W',
+      sessionId: 's',
+      anonymousEmail: 'anonymous@magic-link.local',
+      applicationId: 'A',
+      guestRoleName: 'Widget Guest',
+      nowSeconds: Math.floor(Date.now() / 1000),
+      ttlSeconds: 900,
+    });
+    const token = km.Sign(claims);
+    const publicKey = createPublicKey({ key: km.GetJWKS().keys[0] as object, format: 'jwk' });
+    const tampered = token.slice(0, -3) + 'AAA';
+    expect(() => jwt.verify(tampered, publicKey, { algorithms: ['RS256'] })).toThrow();
+  });
+});
+
+describe('widget core — looksLikeBot (W6 mint heuristic)', () => {
+  it('flags a missing / blank user-agent as a bot', () => {
+    expect(looksLikeBot(undefined)).toBe(true);
+    expect(looksLikeBot(null)).toBe(true);
+    expect(looksLikeBot('   ')).toBe(true);
+  });
+
+  it('flags known automation user-agents', () => {
+    expect(looksLikeBot('curl/8.4.0')).toBe(true);
+    expect(looksLikeBot('python-requests/2.31')).toBe(true);
+    expect(looksLikeBot('Googlebot/2.1 (+http://www.google.com/bot.html)')).toBe(true);
+    expect(looksLikeBot('Mozilla/5.0 (compatible; bingbot/2.0)')).toBe(true);
+    expect(looksLikeBot('HeadlessChrome/120.0.0.0')).toBe(true);
+  });
+
+  it('allows real browser user-agents', () => {
+    expect(looksLikeBot('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36')).toBe(false);
+    expect(looksLikeBot('Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 Version/17.0 Mobile/15E148 Safari/604.1')).toBe(false);
+  });
+});

package/src/__tests__/widgetGuestElevation.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import type { DatabaseProviderBase, UserInfo } from '@memberjunction/core';
+import { resolveWidgetGuestRunContext, elevateUserPayload } from '../realtimeWidget/widgetGuestElevation.js';
+import type { UserPayload } from '../types.js';
+
+/** A provider stub — the guard paths under test return before ever touching the provider. */
+const providerStub = {} as DatabaseProviderBase;
+
+/** Builds a UserPayload whose synthesized userRecord carries the given guest flags. */
+function payloadWith(userRecord: Partial<UserInfo>): UserPayload {
+  return { email: 'anonymous@magic-link.local', userRecord, sessionId: 'sess-123' };
+}
+
+describe('widgetGuestElevation — resolveWidgetGuestRunContext (guard paths, no DB)', () => {
+  it('returns null for a normal authenticated user (not anonymous)', async () => {
+    const result = await resolveWidgetGuestRunContext(payloadWith({ IsMagicLinkAnonymous: false }), providerStub);
+    expect(result).toBeNull();
+  });
+
+  it('returns null for an anonymous magic-link session that is NOT a widget guest (no WidgetGuestContext)', async () => {
+    const result = await resolveWidgetGuestRunContext(
+      payloadWith({ IsMagicLinkAnonymous: true, WidgetGuestContext: undefined }),
+      providerStub,
+    );
+    expect(result).toBeNull();
+  });
+
+  it('returns null when userRecord is absent', async () => {
+    const result = await resolveWidgetGuestRunContext({ email: '', userRecord: undefined, sessionId: 's' }, providerStub);
+    expect(result).toBeNull();
+  });
+});
+
+describe('widgetGuestElevation — elevateUserPayload', () => {
+  it('swaps in the elevated principal while preserving the guest sessionId for PubSub routing', () => {
+    const guestPayload = payloadWith({ IsMagicLinkAnonymous: true });
+    const systemUser = { Email: 'system@system.org' } as UserInfo;
+
+    const elevated = elevateUserPayload(guestPayload, systemUser);
+
+    expect(elevated.userRecord).toBe(systemUser);
+    expect(elevated.email).toBe('system@system.org');
+    expect(elevated.isSystemUser).toBe(true);
+    // The session id MUST be preserved so progress/streaming still routes to the guest's websocket.
+    expect(elevated.sessionId).toBe('sess-123');
+  });
+
+  it('does not mutate the original guest payload', () => {
+    const guestPayload = payloadWith({ IsMagicLinkAnonymous: true });
+    const systemUser = { Email: 'system@system.org' } as UserInfo;
+
+    elevateUserPayload(guestPayload, systemUser);
+
+    expect(guestPayload.isSystemUser).toBeUndefined();
+    expect(guestPayload.email).toBe('anonymous@magic-link.local');
+  });
+});

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;
+  }
+}