@memberjunction/ng-conversations 5.40.2 → 5.41.0

package/dist/lib/services/realtime-pairing.js

@@ -0,0 +1,150 @@
+import { NormalizeUUID, UUIDsEqual } from '@memberjunction/global';
+import { AIEngineBase } from '@memberjunction/ai-engine-base';
+/**
+ * Loads the pairing rows for one co-agent from {@link AIEngineBase}'s cached
+ * `MJ: AI Agent Co Agents` metadata (provider-scoped engine instance, lazy `Config`),
+ * in `Sequence` order. The engine's BaseEntity-event reactivity keeps the cache fresh —
+ * no per-call RunView round-trip.
+ *
+ * Tolerant by design: any failure degrades to an EMPTY list — i.e. "no pairing
+ * constraint". The client gate is pure disclosure; the server independently validates
+ * the co-agent/target pairing at session mint.
+ */
+export async function LoadCoAgentPairings(provider, coAgentId) {
+    const id = coAgentId?.trim() ?? '';
+    if (id.length === 0) {
+        return [];
+    }
+    try {
+        const engine = AIEngineBase.GetProviderInstance(provider, AIEngineBase);
+        await engine.Config(false, undefined, provider);
+        const rows = (engine.AgentCoAgents ?? [])
+            .filter(p => p.Type === 'CoAgent' &&
+            p.Status === 'Active' &&
+            p.TargetAgentID != null &&
+            UUIDsEqual(p.CoAgentID, id))
+            .map(p => ({
+            ID: p.ID,
+            CoAgentID: p.CoAgentID,
+            TargetAgentID: p.TargetAgentID,
+            TargetAgent: p.TargetAgent ?? null,
+            IsDefault: p.IsDefault,
+            Sequence: p.Sequence ?? null
+        }));
+        return SortPairings(rows);
+    }
+    catch (error) {
+        console.warn('[RealtimePairing] Co-agent pairing lookup unavailable — treating co-agent as universal:', error);
+        return [];
+    }
+}
+/**
+ * Returns the pairing rows in canonical display order: `Sequence` ascending (null/missing
+ * sequences last), ties broken by target-agent name. Pure; never mutates the input.
+ */
+export function SortPairings(pairings) {
+    return [...pairings].sort((a, b) => {
+        const aSeq = a.Sequence ?? Number.MAX_SAFE_INTEGER;
+        const bSeq = b.Sequence ?? Number.MAX_SAFE_INTEGER;
+        if (aSeq !== bSeq) {
+            return aSeq - bSeq;
+        }
+        return (a.TargetAgent ?? '').localeCompare(b.TargetAgent ?? '');
+    });
+}
+/**
+ * Applies the pairing constraint to a candidate target-agent list:
+ * - ZERO pairing rows → the co-agent is universal; the candidates are returned unchanged
+ *   (today's flow untouched).
+ * - One or more rows → only candidates that appear among the pairing targets are
+ *   returned, ordered by the pairings' `Sequence`. Paired targets the user can't see /
+ *   run (absent from `agents`) are silently dropped.
+ *
+ * Pure and UUID-casing safe (`NormalizeUUID` keys).
+ */
+export function ConstrainTargetsToPairings(agents, pairings) {
+    if (!pairings || pairings.length === 0) {
+        return [...agents];
+    }
+    const agentsById = new Map();
+    for (const agent of agents) {
+        agentsById.set(NormalizeUUID(agent.ID), agent);
+    }
+    const constrained = [];
+    const seen = new Set();
+    for (const pairing of SortPairings(pairings)) {
+        const key = NormalizeUUID(pairing.TargetAgentID);
+        const agent = agentsById.get(key);
+        if (agent && !seen.has(key)) {
+            seen.add(key);
+            constrained.push(agent);
+        }
+    }
+    return constrained;
+}
+/**
+ * The co-agent's default target from its pairing rows — the first `IsDefault` row in
+ * `Sequence` order (server enforces at most one, but the helper stays deterministic
+ * regardless). `null` when there are no rows or none is marked default.
+ */
+export function DefaultPairedTargetId(pairings) {
+    for (const pairing of SortPairings(pairings ?? [])) {
+        if (pairing.IsDefault) {
+            return pairing.TargetAgentID;
+        }
+    }
+    return null;
+}
+/**
+ * Whether the pairing rows permit `targetAgentId` as a target. ZERO rows means the
+ * co-agent is universal (always allowed); otherwise the target must appear among the
+ * rows. Missing/empty target id is never allowed against a constrained co-agent.
+ */
+export function PairingsAllowTarget(pairings, targetAgentId) {
+    if (!pairings || pairings.length === 0) {
+        return true;
+    }
+    if (!targetAgentId) {
+        return false;
+    }
+    return pairings.some(p => UUIDsEqual(p.TargetAgentID, targetAgentId));
+}
+/**
+ * Filters an agent list down to ACTIVE Realtime-type **co-agent** candidates. The input
+ * is expected to already be the run-permission-filtered active-agent set the host uses
+ * for routing/@mentions, so this only applies the agent-TYPE cut (trim +
+ * case-insensitive match on the denormalized `Type` name).
+ */
+export function FilterRealtimeCoAgents(agents) {
+    return agents.filter(a => (a.Type ?? '').trim().toLowerCase() === 'realtime');
+}
+/**
+ * Builds the "Voice model" dropdown options from a cached model list: ACTIVE models whose
+ * type is `Realtime` (trim + case-insensitive — SQL-collation parity with the previous
+ * `IsActive = 1 AND AIModelType = 'Realtime'` filter), projected to {@link RealtimeModelOption}
+ * and sorted by Name. Pure; never mutates the input.
+ */
+export function BuildRealtimeModelOptions(models) {
+    return models
+        .filter(m => m.IsActive && (m.AIModelType ?? '').trim().toLowerCase() === 'realtime')
+        .map(m => ({ ID: m.ID, Name: m.Name }))
+        .sort((a, b) => (a.Name ?? '').localeCompare(b.Name ?? ''));
+}
+/**
+ * Builds the `configOverridesJson` payload for the `StartRealtimeClientSession` mint from
+ * what the (authorization-gated) pickers chose. Currently the only override is the
+ * explicit realtime model preference; the envelope shape —
+ * `{"realtime":{"modelPreference":"<id>"}}` — is the pinned server contract and is
+ * structured so future overrides ride alongside without reshaping.
+ *
+ * @returns The JSON string, or `null` when nothing was overridden (the common case —
+ *   `null` keeps the mint identical to today's behavior).
+ */
+export function BuildRealtimeConfigOverridesJson(preferredModelId) {
+    const modelId = preferredModelId?.trim() ?? '';
+    if (modelId.length === 0) {
+        return null;
+    }
+    return JSON.stringify({ realtime: { modelPreference: modelId } });
+}
+//# sourceMappingURL=realtime-pairing.js.map

package/dist/lib/services/realtime-pairing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-pairing.js","sourceRoot":"","sources":["../../../src/lib/services/realtime-pairing.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAgC9D;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,QAA2B,EAAE,SAAiB;IACtF,MAAM,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACnC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,YAAY,CAAC,mBAAmB,CAAe,QAAQ,EAAE,YAAY,CAAiB,CAAC;QACtG,MAAM,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QAChD,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,aAAa,IAAI,EAAE,CAAC;aACtC,MAAM,CAAC,CAAC,CAAC,EAAE,CACV,CAAC,CAAC,IAAI,KAAK,SAAS;YACpB,CAAC,CAAC,MAAM,KAAK,QAAQ;YACrB,CAAC,CAAC,aAAa,IAAI,IAAI;YACvB,UAAU,CAAC,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;aAC7B,GAAG,CAAyB,CAAC,CAAC,EAAE,CAAC,CAAC;YACjC,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,aAAa,EAAE,CAAC,CAAC,aAAc;YAC/B,WAAW,EAAE,CAAC,CAAC,WAAW,IAAI,IAAI;YAClC,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ,IAAI,IAAI;SAC7B,CAAC,CAAC,CAAC;QACN,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,IAAI,CAAC,yFAAyF,EAAE,KAAK,CAAC,CAAC;QAC/G,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,QAA2C;IACtE,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACjC,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,IAAI,MAAM,CAAC,gBAAgB,CAAC;QACnD,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,IAAI,MAAM,CAAC,gBAAgB,CAAC;QACnD,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,OAAO,IAAI,GAAG,IAAI,CAAC;QACrB,CAAC;QACD,OAAO,CAAC,CAAC,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;IAClE,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,0BAA0B,CACxC,MAAoB,EACpB,QAA2C;IAE3C,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvC,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC;IACrB,CAAC;IACD,MAAM,UAAU,GAAG,IAAI,GAAG,EAAa,CAAC;IACxC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,UAAU,CAAC,GAAG,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;IACjD,CAAC;IACD,MAAM,WAAW,GAAQ,EAAE,CAAC;IAC5B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,OAAO,IAAI,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7C,MAAM,GAAG,GAAG,aAAa,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QACjD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,KAAK,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAA2C;IAC/E,KAAK,MAAM,OAAO,IAAI,YAAY,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,CAAC;QACnD,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;YACtB,OAAO,OAAO,CAAC,aAAa,CAAC;QAC/B,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAA2C,EAAE,aAAwC;IACvH,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC,CAAC;AACxE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAoC,MAAoB;IAC5F,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,UAAU,CAAC,CAAC;AAChF,CAAC;AA4BD;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAA0C;IAClF,OAAO,MAAM;SACV,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,UAAU,CAAC;SACpF,GAAG,CAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;SAC3D,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gCAAgC,CAAC,gBAA2C;IAC1F,MAAM,OAAO,GAAG,gBAAgB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC/C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,EAAE,eAAe,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;AACpE,CAAC","sourcesContent":["import { IMetadataProvider } from '@memberjunction/core';\nimport { NormalizeUUID, UUIDsEqual } from '@memberjunction/global';\nimport { AIEngineBase } from '@memberjunction/ai-engine-base';\n\n/**\n * The narrow read-only projection of an `MJ: AI Agent Co Agents` row the voice UI consumes\n * (loaded via {@link LoadCoAgentPairings} from {@link AIEngineBase}'s cached `AgentCoAgents`;\n * only **Active** rows of relationship **Type `'CoAgent'`** with a specific agent target —\n * type-level rows express the resolution-chain default, not a target restriction, and\n * reserved relationship types are ignored until their features ship). Pairing semantics: a\n * co-agent with ZERO such rows is **universal** (it can front any target agent — the\n * zero-config default); a co-agent WITH rows may front exactly the listed targets, with the\n * `IsDefault` row as its preselected target.\n */\nexport interface RealtimePairedAgentRow {\n  /** The pairing row id. */\n  ID: string;\n  /** The Realtime-type co-agent the pairing belongs to. */\n  CoAgentID: string;\n  /** The target agent this co-agent may front. */\n  TargetAgentID: string;\n  /** Denormalized target-agent display name (from the base view). */\n  TargetAgent: string | null;\n  /** When true, this target is the co-agent's default (at most one per co-agent). */\n  IsDefault: boolean;\n  /** Display/list ordering of the pairing rows. */\n  Sequence: number | null;\n}\n\n/** Minimal agent shape the pure pairing/co-agent helpers operate on. */\nexport interface RealtimeAgentLike {\n  ID: string;\n}\n\n/**\n * Loads the pairing rows for one co-agent from {@link AIEngineBase}'s cached\n * `MJ: AI Agent Co Agents` metadata (provider-scoped engine instance, lazy `Config`),\n * in `Sequence` order. The engine's BaseEntity-event reactivity keeps the cache fresh —\n * no per-call RunView round-trip.\n *\n * Tolerant by design: any failure degrades to an EMPTY list — i.e. \"no pairing\n * constraint\". The client gate is pure disclosure; the server independently validates\n * the co-agent/target pairing at session mint.\n */\nexport async function LoadCoAgentPairings(provider: IMetadataProvider, coAgentId: string): Promise<RealtimePairedAgentRow[]> {\n  const id = coAgentId?.trim() ?? '';\n  if (id.length === 0) {\n    return [];\n  }\n  try {\n    const engine = AIEngineBase.GetProviderInstance<AIEngineBase>(provider, AIEngineBase) as AIEngineBase;\n    await engine.Config(false, undefined, provider);\n    const rows = (engine.AgentCoAgents ?? [])\n      .filter(p =>\n        p.Type === 'CoAgent' &&\n        p.Status === 'Active' &&\n        p.TargetAgentID != null &&\n        UUIDsEqual(p.CoAgentID, id))\n      .map<RealtimePairedAgentRow>(p => ({\n        ID: p.ID,\n        CoAgentID: p.CoAgentID,\n        TargetAgentID: p.TargetAgentID!,\n        TargetAgent: p.TargetAgent ?? null,\n        IsDefault: p.IsDefault,\n        Sequence: p.Sequence ?? null\n      }));\n    return SortPairings(rows);\n  } catch (error) {\n    console.warn('[RealtimePairing] Co-agent pairing lookup unavailable — treating co-agent as universal:', error);\n    return [];\n  }\n}\n\n/**\n * Returns the pairing rows in canonical display order: `Sequence` ascending (null/missing\n * sequences last), ties broken by target-agent name. Pure; never mutates the input.\n */\nexport function SortPairings(pairings: readonly RealtimePairedAgentRow[]): RealtimePairedAgentRow[] {\n  return [...pairings].sort((a, b) => {\n    const aSeq = a.Sequence ?? Number.MAX_SAFE_INTEGER;\n    const bSeq = b.Sequence ?? Number.MAX_SAFE_INTEGER;\n    if (aSeq !== bSeq) {\n      return aSeq - bSeq;\n    }\n    return (a.TargetAgent ?? '').localeCompare(b.TargetAgent ?? '');\n  });\n}\n\n/**\n * Applies the pairing constraint to a candidate target-agent list:\n * - ZERO pairing rows → the co-agent is universal; the candidates are returned unchanged\n *   (today's flow untouched).\n * - One or more rows → only candidates that appear among the pairing targets are\n *   returned, ordered by the pairings' `Sequence`. Paired targets the user can't see /\n *   run (absent from `agents`) are silently dropped.\n *\n * Pure and UUID-casing safe (`NormalizeUUID` keys).\n */\nexport function ConstrainTargetsToPairings<T extends RealtimeAgentLike>(\n  agents: readonly T[],\n  pairings: readonly RealtimePairedAgentRow[]\n): T[] {\n  if (!pairings || pairings.length === 0) {\n    return [...agents];\n  }\n  const agentsById = new Map<string, T>();\n  for (const agent of agents) {\n    agentsById.set(NormalizeUUID(agent.ID), agent);\n  }\n  const constrained: T[] = [];\n  const seen = new Set<string>();\n  for (const pairing of SortPairings(pairings)) {\n    const key = NormalizeUUID(pairing.TargetAgentID);\n    const agent = agentsById.get(key);\n    if (agent && !seen.has(key)) {\n      seen.add(key);\n      constrained.push(agent);\n    }\n  }\n  return constrained;\n}\n\n/**\n * The co-agent's default target from its pairing rows — the first `IsDefault` row in\n * `Sequence` order (server enforces at most one, but the helper stays deterministic\n * regardless). `null` when there are no rows or none is marked default.\n */\nexport function DefaultPairedTargetId(pairings: readonly RealtimePairedAgentRow[]): string | null {\n  for (const pairing of SortPairings(pairings ?? [])) {\n    if (pairing.IsDefault) {\n      return pairing.TargetAgentID;\n    }\n  }\n  return null;\n}\n\n/**\n * Whether the pairing rows permit `targetAgentId` as a target. ZERO rows means the\n * co-agent is universal (always allowed); otherwise the target must appear among the\n * rows. Missing/empty target id is never allowed against a constrained co-agent.\n */\nexport function PairingsAllowTarget(pairings: readonly RealtimePairedAgentRow[], targetAgentId: string | null | undefined): boolean {\n  if (!pairings || pairings.length === 0) {\n    return true;\n  }\n  if (!targetAgentId) {\n    return false;\n  }\n  return pairings.some(p => UUIDsEqual(p.TargetAgentID, targetAgentId));\n}\n\n/**\n * Filters an agent list down to ACTIVE Realtime-type **co-agent** candidates. The input\n * is expected to already be the run-permission-filtered active-agent set the host uses\n * for routing/@mentions, so this only applies the agent-TYPE cut (trim +\n * case-insensitive match on the denormalized `Type` name).\n */\nexport function FilterRealtimeCoAgents<T extends { Type: string | null }>(agents: readonly T[]): T[] {\n  return agents.filter(a => (a.Type ?? '').trim().toLowerCase() === 'realtime');\n}\n\n/**\n * A selectable realtime model option in the voice picker (narrow read-only projection of\n * `MJ: AI Models` — only the fields the dropdown renders).\n */\nexport interface RealtimeModelOption {\n  /** The `MJ: AI Models` row id. */\n  ID: string;\n  /** The model's display name. */\n  Name: string;\n}\n\n/**\n * The minimal `MJ: AI Models` row shape {@link BuildRealtimeModelOptions} consumes —\n * structurally satisfied by `AIEngineBase`'s cached `Models` entities.\n */\nexport interface VoiceModelCandidate {\n  /** The `MJ: AI Models` row id. */\n  ID: string;\n  /** The model's display name. */\n  Name: string;\n  /** Denormalized model-type name (e.g. 'LLM', 'Realtime'). */\n  AIModelType: string | null;\n  /** Whether the model is active and selectable. */\n  IsActive: boolean;\n}\n\n/**\n * Builds the \"Voice model\" dropdown options from a cached model list: ACTIVE models whose\n * type is `Realtime` (trim + case-insensitive — SQL-collation parity with the previous\n * `IsActive = 1 AND AIModelType = 'Realtime'` filter), projected to {@link RealtimeModelOption}\n * and sorted by Name. Pure; never mutates the input.\n */\nexport function BuildRealtimeModelOptions(models: ReadonlyArray<VoiceModelCandidate>): RealtimeModelOption[] {\n  return models\n    .filter(m => m.IsActive && (m.AIModelType ?? '').trim().toLowerCase() === 'realtime')\n    .map<RealtimeModelOption>(m => ({ ID: m.ID, Name: m.Name }))\n    .sort((a, b) => (a.Name ?? '').localeCompare(b.Name ?? ''));\n}\n\n/**\n * Builds the `configOverridesJson` payload for the `StartRealtimeClientSession` mint from\n * what the (authorization-gated) pickers chose. Currently the only override is the\n * explicit realtime model preference; the envelope shape —\n * `{\"realtime\":{\"modelPreference\":\"<id>\"}}` — is the pinned server contract and is\n * structured so future overrides ride alongside without reshaping.\n *\n * @returns The JSON string, or `null` when nothing was overridden (the common case —\n *   `null` keeps the mint identical to today's behavior).\n */\nexport function BuildRealtimeConfigOverridesJson(preferredModelId: string | null | undefined): string | null {\n  const modelId = preferredModelId?.trim() ?? '';\n  if (modelId.length === 0) {\n    return null;\n  }\n  return JSON.stringify({ realtime: { modelPreference: modelId } });\n}\n"]}

package/dist/lib/services/realtime-session-review.service.d.ts

@@ -0,0 +1,233 @@
+import { IMetadataProvider } from '@memberjunction/core';
+import { RealtimeDelegationCardVM, RealtimeThreadItem } from '../components/realtime/realtime-session-state';
+import { ParsedDelegationArtifact } from './delegation-result-parser';
+import * as i0 from "@angular/core";
+/**
+ * Why a reviewed session was closed, as stamped server-side by `SessionManager.CloseSession`
+ * (mirrors `MJAIAgentSessionEntity.CloseReason`). `null` means the session is still open OR a
+ * legacy row was closed before the column existed.
+ */
+export type RealtimeReviewCloseReason = 'Error' | 'Explicit' | 'Janitor' | 'Shutdown';
+/** One historical caption turn of a reviewed session (a persisted `MJ: Conversation Details` row). */
+export interface RealtimeSessionReviewTurn {
+    /** Who spoke the turn. Persisted `AI` rows map to `Assistant`. */
+    Role: 'User' | 'Assistant';
+    /** The transcript text. */
+    Text: string;
+    /** When the turn was persisted (`__mj_CreatedAt`), or null when unknown. */
+    At: Date | null;
+}
+/**
+ * A compact preview of one DELEGATED agent run the reviewed session spawned (an
+ * `MJ: AI Agent Runs` row linked via `AgentSessionID`, EXCLUDING the co-agent's own
+ * observability run). Carries just enough to render a done delegation card.
+ */
+export interface RealtimeSessionReviewRun {
+    /** `MJ: AI Agent Runs.ID`. */
+    RunID: string;
+    /** The delegated agent's id. */
+    AgentID: string;
+    /** Denormalized agent display name from the run view, when available. */
+    AgentName: string | null;
+    /** Terminal (or last-known) run status (`Completed` | `Failed` | `Running` | …). */
+    Status: string;
+    /** Whether the run reported success. */
+    Success: boolean;
+    /** The run's user-facing result message, when one was recorded. */
+    Message: string | null;
+    /** The run's error message, when it failed. */
+    ErrorMessage: string | null;
+    /** The final step the run reported (`Success` | `Failed` | `Retry` | …), when known. */
+    FinalStep: string | null;
+    StartedAt: Date | null;
+    CompletedAt: Date | null;
+}
+/** The persisted state of one interactive channel of the reviewed session. */
+export interface RealtimeSessionReviewChannelState {
+    /** Channel display name (e.g. `Whiteboard`), denormalized on the session-channel row. */
+    ChannelName: string;
+    /** The channel's serialized state of record (`AIAgentSessionChannel.Config`), or null when none was saved. */
+    StateJson: string | null;
+}
+/**
+ * MULTI-LEG channel-state merge: folds every leg's channel rows into one state set,
+ * NEWEST leg wins per channel name — but only a leg that actually SAVED state counts.
+ * A resumed session whose final leg never touched the whiteboard therefore still
+ * reviews with the board an EARLIER leg drew (previously only the primary/newest leg's
+ * rows were consulted, so that board silently vanished from review).
+ *
+ * @param legChannelStates Per-leg channel states, ordered OLDEST → NEWEST (the chain order).
+ * @returns One entry per channel name (case-insensitive), each from the newest leg that
+ *   saved a non-empty state; channels no leg ever saved keep a null-state entry so the
+ *   review still knows the channel existed.
+ */
+export declare function MergeChainChannelStates(legChannelStates: ReadonlyArray<ReadonlyArray<RealtimeSessionReviewChannelState>>): RealtimeSessionReviewChannelState[];
+/**
+ * One LEG of a reviewed session chain: a single `MJ: AI Agent Sessions` row plus its own
+ * caption turns and delegated-run previews. A session resumed via `lastSessionId` chains
+ * legs together (newest leg's `LastSessionID` → prior leg); the review loader walks that
+ * chain BACKWARDS (capped — see the loader docs) so review mode can render the FULL
+ * conversation arc chronologically, with a divider between legs.
+ */
+export interface RealtimeSessionReviewLeg {
+    /** `MJ: AI Agent Sessions.ID` of this leg. */
+    SessionID: string;
+    /** When this leg started (`__mj_CreatedAt`). */
+    StartedAt: Date | null;
+    /** When this leg closed (null while still open). */
+    ClosedAt: Date | null;
+    /** Why this leg closed (null while open / legacy rows). */
+    CloseReason: RealtimeReviewCloseReason | null;
+    /** This leg's chronological caption turns (oldest first). */
+    Turns: RealtimeSessionReviewTurn[];
+    /** This leg's delegated-run previews (oldest first, minus its co-agent observability run). */
+    DelegatedRuns: RealtimeSessionReviewRun[];
+}
+/**
+ * Everything the call overlay's SESSION REVIEW mode renders for one past realtime session:
+ * the session identity/lifecycle row, the chronological caption turns, previews of the
+ * delegated runs, and the saved per-channel states (e.g. the whiteboard board).
+ */
+export interface RealtimeSessionReview {
+    /** `MJ: AI Agent Sessions.ID` of the reviewed session. */
+    SessionID: string;
+    /** The session's fronting agent id (`AIAgentSession.AgentID` — usually the Realtime Co-Agent). */
+    AgentID: string;
+    /** Display name shown in the review banner (target agent when resolvable, else the session agent). */
+    AgentName: string;
+    /**
+     * The agent a RESUMED live session should front: the session Config's `targetAgentID`,
+     * falling back to the session's own `AgentID` when the config doesn't carry one.
+     */
+    TargetAgentID: string;
+    /** Conversation the session was bound to, when any. */
+    ConversationID: string | null;
+    Status: 'Active' | 'Closed' | 'Idle';
+    CloseReason: RealtimeReviewCloseReason | null;
+    /** When the session started (`__mj_CreatedAt`). */
+    StartedAt: Date | null;
+    LastActiveAt: Date | null;
+    ClosedAt: Date | null;
+    /** Chronological caption turns (oldest first) — ALL legs of the chain, flattened. */
+    Turns: RealtimeSessionReviewTurn[];
+    /** Delegated run previews (oldest first, all legs), minus each leg's co-agent observability run. */
+    DelegatedRuns: RealtimeSessionReviewRun[];
+    /**
+     * Saved channel states, one per session-channel row that carried a name. Channel state
+     * (e.g. the whiteboard board) is the LATEST leg's only — earlier legs' states were
+     * superseded when the chain resumed.
+     */
+    ChannelStates: RealtimeSessionReviewChannelState[];
+    /**
+     * The session-chain LEGS, chronological (oldest first; the LAST leg is the reviewed
+     * session itself). Single-session reviews carry exactly one leg. Drives the per-leg
+     * dividers `BuildReviewThreadItems` renders.
+     */
+    Legs: RealtimeSessionReviewLeg[];
+    /**
+     * ARTIFACTS attached to the chain's conversation history: every `MJ: Conversation
+     * Detail Artifacts` junction (Direction `Output`) hanging off the chain's
+     * session-stamped `Conversation Details`, resolved to `{ArtifactID, ArtifactVersionID,
+     * Name}`. Review mode registers each as an (unfocused) artifact tab on the surface
+     * panel, and they carry into a resumed live session. Empty when none / on any
+     * tolerated load failure.
+     */
+    Artifacts: ParsedDelegationArtifact[];
+}
+/** Maximum number of chain legs the review loader walks (the reviewed session included). */
+export declare const MAX_REVIEW_LEGS = 5;
+/** Maximum total caption-detail rows loaded across the whole chain (oldest legs trimmed first). */
+export declare const MAX_REVIEW_DETAILS = 500;
+/** Maps one delegated-run preview to the done delegation-card VM the thread/rail render. */
+export declare function BuildReviewDelegationCard(run: RealtimeSessionReviewRun, fallbackAgentName: string): RealtimeDelegationCardVM;
+/**
+ * Builds the chronological thread (caption turns + done delegation cards, oldest first)
+ * for a reviewed session — the items `RealtimeSessionState.LoadHistoricalItems` takes.
+ *
+ * CHAIN-AWARE: when the review carries multiple {@link RealtimeSessionReview.Legs}, each
+ * leg's items render in leg order with a `divider` item between legs ("Session leg
+ * started · <time>", carrying the PREVIOUS leg's CloseReason as a chip). A single-leg
+ * review (or a legless legacy shape) renders the flat thread with no divider —
+ * byte-identical to the pre-chain behavior.
+ */
+export declare function BuildReviewThreadItems(review: RealtimeSessionReview): RealtimeThreadItem[];
+/**
+ * STATELESS loader for the call overlay's SESSION REVIEW mode: given a past
+ * `MJ: AI Agent Sessions` id, batch-loads the session row, its persisted caption turns
+ * (`MJ: Conversation Details` linked by `AgentSessionID`), its delegated agent runs
+ * (minus the co-agent observability run named in the session Config's `coAgentRunID`),
+ * and its saved channel states — and folds them into one {@link RealtimeSessionReview}.
+ *
+ * CHAIN-AWARE: when the reviewed session carries a `LastSessionID` (it RESUMED an earlier
+ * session), the loader walks the chain BACKWARDS — capped at {@link MAX_REVIEW_LEGS} legs
+ * and {@link MAX_REVIEW_DETAILS} caption rows total (oldest legs trimmed first), with a
+ * cycle guard so a corrupt A→B→A chain can never loop — and surfaces ALL legs
+ * chronologically on {@link RealtimeSessionReview.Legs}. Channel state stays the
+ * reviewed (latest) leg's only. The chain's conversation-history ARTIFACTS (junction
+ * rows on the session-stamped details) are collected onto
+ * {@link RealtimeSessionReview.Artifacts}.
+ *
+ * TOLERANT by design: any missing piece degrades to an empty collection; the loader
+ * returns `null` only when the reviewed session row itself can't be found.
+ */
+export declare class RealtimeSessionReviewService {
+    /**
+     * Loads everything review mode renders for one past session (and its prior-leg chain).
+     *
+     * @param agentSessionId The `MJ: AI Agent Sessions.ID` to review.
+     * @param provider Optional metadata provider (multi-server apps); falls back to the global default.
+     * @returns The assembled review, or `null` when the session doesn't exist / can't be read.
+     */
+    LoadSessionReview(agentSessionId: string, provider?: IMetadataProvider): Promise<RealtimeSessionReview | null>;
+    /**
+     * One batched RunViews pass for one chain leg: session row + caption turns + linked
+     * runs (+ channel rows for the PRIMARY leg only — channel state is latest-leg-only).
+     * Returns `null` when the session row can't be found.
+     */
+    private loadLegRows;
+    /**
+     * Walks the `LastSessionID` chain BACKWARDS from the reviewed (primary) leg, collecting
+     * raw leg rows OLDEST-FIRST (primary last). Safety rails:
+     *  - at most {@link MAX_REVIEW_LEGS} legs total;
+     *  - at most {@link MAX_REVIEW_DETAILS} caption rows across the chain — an older leg
+     *    whose details would overflow the budget is trimmed to its NEWEST rows and ends
+     *    the walk;
+     *  - a visited-set cycle guard (case-insensitive ids) so A→B→A can never loop;
+     *  - a leg that fails to load simply ends the walk (the collected legs still render).
+     */
+    private collectChainLegs;
+    /**
+     * Collects the chain's conversation-history ARTIFACTS: `MJ: Conversation Detail
+     * Artifacts` junction rows (Direction `Output`) hanging off the chain's session-stamped
+     * details, resolved through `MJ: Artifact Versions` to `{ArtifactID, ArtifactVersionID,
+     * Name}` (version name, falling back to the artifact name). Order follows junction
+     * creation; duplicate versions are deduped. TOLERANT: any failure returns `[]`.
+     */
+    private loadChainArtifacts;
+    /** Unique, non-empty `ArtifactVersionID`s from junction rows, in arrival order (case-insensitive dedupe). */
+    private uniqueVersionIDs;
+    /** Case-insensitive UUID key for Set/Map membership (SQL Server uppercase vs PostgreSQL lowercase). */
+    private normalizeID;
+    /**
+     * Folds the chain's raw leg rows into the typed review. The PRIMARY (reviewed) leg —
+     * the chain's LAST entry — supplies identity/lifecycle/channel state; turns and runs
+     * are surfaced both per-leg (`Legs`) and flattened chronologically (`Turns` /
+     * `DelegatedRuns`). Each leg excludes ITS OWN config's co-agent observability run.
+     */
+    private assembleReview;
+    /** Maps one leg's raw rows to the public leg shape (per-leg co-agent-run exclusion). */
+    private mapLeg;
+    /** Persisted detail rows → caption turns: visible `User`/`AI` rows with text (AI → Assistant). */
+    private mapTurns;
+    /** Linked run rows → delegated-run previews, EXCLUDING the co-agent's observability run. */
+    private mapRuns;
+    /** Session-channel rows → named channel states (rows without a channel name are skipped). */
+    private mapChannels;
+    /** Tolerant Config JSON parse — malformed/missing payloads degrade to `{}`. */
+    private parseSessionConfig;
+    /** Tolerant date conversion — view rows arrive as ISO strings (or Dates from some providers). */
+    private toDate;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RealtimeSessionReviewService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<RealtimeSessionReviewService>;
+}
+//# sourceMappingURL=realtime-session-review.service.d.ts.map

package/dist/lib/services/realtime-session-review.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-session-review.service.d.ts","sourceRoot":"","sources":["../../../src/lib/services/realtime-session-review.service.ts"],"names":[],"mappings":"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"}