@memberjunction/ai-agents 5.40.2 → 5.42.0

package/dist/realtime/realtime-coagent-config.js

@@ -0,0 +1,408 @@
+/**
+ * @fileoverview PURE configuration module for Realtime co-agent type configuration —
+ * the deep-merge + parse + normalize pipeline behind the effective-configuration contract:
+ *
+ * ```
+ * AIAgentType.DefaultConfiguration  ←  AIAgent.TypeConfiguration  ←  runtime overrides
+ * (base layer)                          (per-agent layer)             (per-session layer)
+ * ```
+ *
+ * Later layers win **per key**: plain objects deep-merge, while arrays and primitives
+ * replace wholesale. The merged result is normalized into the typed
+ * {@link RealtimeCoAgentConfig} shape (wrong-typed fields are dropped, never thrown on).
+ *
+ * This module is deliberately **framework-free**: no DB, no metadata provider, no logging
+ * imports — every function is a pure transformation so it can be exercised exhaustively in
+ * unit tests and reused verbatim by the session service (`realtime-client-session-service.ts`),
+ * the server-bridged path (`base-agent.ts`), and the MJServer resolver
+ * (`RealtimeClientSessionResolver.ts`).
+ *
+ * The canonical JSON shape (the Realtime agent type's `ConfigSchema` is seeded to this):
+ * ```jsonc
+ * { "realtime": {
+ *     "modelPreference": "<AI Model name or ID>",
+ *     "voice": { "default": { "tone": "…", "speakingStyle": "…" },
+ *                "providers": { "openai": { "voice": "alloy" },
+ *                               "elevenlabs": { "voiceId": "…" },
+ *                               "gemini": { "voice": "…" },
+ *                               "assemblyai": { "voice": "…" } } },
+ *     "allowUserModelOverride": true,
+ *     "narration": { "paceMs": 8000 } } }
+ * ```
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+/**
+ * The MJ Authorization name that gates RUNTIME overrides on realtime session start:
+ * `configOverridesJson` and explicit realtime-model selection that deviates from the
+ * co-agent's metadata-configured preference. Seeded in `metadata/authorizations/.realtime.json`.
+ */
+export const REALTIME_ADVANCED_SESSION_CONTROLS_AUTHORIZATION = 'Realtime: Advanced Session Controls';
+/** True for a plain JSON object (not null, not an array). */
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** Case/whitespace-insensitive id/name equality (UUIDs differ only by case across DB platforms). */
+function idsEqual(a, b) {
+    if (!a || !b) {
+        return false;
+    }
+    return a.trim().toLowerCase() === b.trim().toLowerCase();
+}
+/**
+ * Deep-merges configuration layers, EARLIEST first — later layers win per key.
+ *
+ * Merge rules (per key):
+ * - plain object vs plain object → recursive deep merge;
+ * - anything else (arrays, strings, numbers, booleans, `null`) → the later value REPLACES;
+ * - `null` is a real JSON value and replaces like any primitive;
+ * - `undefined` values in a later layer are skipped (they cannot exist in parsed JSON anyway).
+ *
+ * `null`/`undefined` LAYERS are skipped entirely. The inputs are never mutated; the result is a
+ * fresh object graph.
+ *
+ * @param layers The configuration layers, base first, most-specific last.
+ * @returns The merged configuration object (empty object when every layer is absent).
+ */
+export function DeepMergeConfigs(...layers) {
+    const result = {};
+    for (const layer of layers) {
+        if (!isPlainObject(layer)) {
+            continue;
+        }
+        mergeInto(result, layer);
+    }
+    return result;
+}
+/** Recursive worker for {@link DeepMergeConfigs} — merges `source` into `target` in place. */
+function mergeInto(target, source) {
+    for (const key of Object.keys(source)) {
+        const incoming = source[key];
+        if (incoming === undefined) {
+            continue;
+        }
+        const existing = target[key];
+        if (isPlainObject(existing) && isPlainObject(incoming)) {
+            mergeInto(existing, incoming);
+        }
+        else if (isPlainObject(incoming)) {
+            const copy = {};
+            mergeInto(copy, incoming);
+            target[key] = copy;
+        }
+        else if (Array.isArray(incoming)) {
+            target[key] = incoming.slice();
+        }
+        else {
+            target[key] = incoming;
+        }
+    }
+}
+/**
+ * TOLERANTLY parses one configuration layer (a `TypeConfiguration` / `DefaultConfiguration` /
+ * runtime-overrides JSON string). Returns `null` — never throws — for absent, blank, malformed,
+ * or non-object payloads (arrays and scalars are not valid configuration layers).
+ *
+ * @param json The raw JSON string, or `null`/`undefined`.
+ * @returns The parsed plain object, or `null` when the layer contributes nothing.
+ */
+export function ParseRealtimeTypeConfiguration(json) {
+    if (typeof json !== 'string' || json.trim().length === 0) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(json);
+        return isPlainObject(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolves the EFFECTIVE realtime configuration from the layers of the contract by tolerantly parsing
+ * each (see {@link ParseRealtimeTypeConfiguration}), deep-merging them (later wins per key, see
+ * {@link DeepMergeConfigs}), and normalizing into the typed {@link RealtimeCoAgentConfig} shape
+ * (wrong-typed fields dropped, never thrown on).
+ *
+ * **Precedence (lowest → highest):**
+ * `AIAgentType.DefaultConfiguration` < **co-agent** `AIAgent.TypeConfiguration` < **target agent**
+ * `AIAgent.TypeConfiguration` < runtime override. This is the single, surface-agnostic precedence cascade
+ * for model + voice + persona across EVERY realtime host (native chat, LiveKit, future Zoom/Teams) — see
+ * `plans/realtime/realtime-core-host-convergence.md`. The **target** layer is what lets a voiced agent
+ * (Sage, Marketing Agent, …) carry its own persisted voice/model that the shared co-agent then speaks with;
+ * it wins over the co-agent's defaults but yields to an explicit per-session runtime override.
+ *
+ * @param typeDefaultJson The agent TYPE's `DefaultConfiguration` JSON (base layer).
+ * @param agentJson The CO-AGENT's `TypeConfiguration` JSON (shared per-co-agent layer).
+ * @param overridesJson Runtime overrides JSON (per-session layer; already authorization-gated by the caller).
+ * @param targetAgentJson Optional TARGET agent's `TypeConfiguration` JSON (per-voiced-agent layer). Merged
+ *   ABOVE the co-agent and BELOW the runtime override regardless of argument position. Omit when there is
+ *   no distinct target (e.g. the co-agent voicing itself).
+ * @returns The normalized effective configuration. `realtime` is absent when no layer supplied a usable section.
+ */
+export function ResolveEffectiveRealtimeConfig(typeDefaultJson, agentJson, overridesJson, targetAgentJson) {
+    // Merge order = precedence (later wins): type-default < co-agent < target < runtime-override.
+    const merged = DeepMergeConfigs(ParseRealtimeTypeConfiguration(typeDefaultJson), ParseRealtimeTypeConfiguration(agentJson), ParseRealtimeTypeConfiguration(targetAgentJson), ParseRealtimeTypeConfiguration(overridesJson));
+    return normalizeConfig(merged);
+}
+/** Normalizes a merged raw config object into the typed, sanity-checked shape. */
+function normalizeConfig(merged) {
+    const rawRealtime = merged['realtime'];
+    if (!isPlainObject(rawRealtime)) {
+        return {};
+    }
+    const section = {};
+    const modelPreference = rawRealtime['modelPreference'];
+    if (typeof modelPreference === 'string' && modelPreference.trim().length > 0) {
+        section.modelPreference = modelPreference.trim();
+    }
+    if (typeof rawRealtime['allowUserModelOverride'] === 'boolean') {
+        section.allowUserModelOverride = rawRealtime['allowUserModelOverride'];
+    }
+    const voice = normalizeVoice(rawRealtime['voice']);
+    if (voice) {
+        section.voice = voice;
+    }
+    const narration = normalizeNarration(rawRealtime['narration']);
+    if (narration) {
+        section.narration = narration;
+    }
+    const video = normalizeVideo(rawRealtime['video']);
+    if (video) {
+        section.video = video;
+    }
+    return Object.keys(section).length > 0 ? { realtime: section } : { realtime: {} };
+}
+/** Normalizes the `video` block; returns `null` when nothing usable survives. */
+function normalizeVideo(raw) {
+    if (!isPlainObject(raw)) {
+        return null;
+    }
+    const video = {};
+    if (typeof raw['enabled'] === 'boolean') {
+        video.enabled = raw['enabled'];
+    }
+    if (typeof raw['provider'] === 'string' && raw['provider'].trim().length > 0) {
+        video.provider = raw['provider'].trim();
+    }
+    if (typeof raw['avatarId'] === 'string' && raw['avatarId'].trim().length > 0) {
+        video.avatarId = raw['avatarId'].trim();
+    }
+    const rawProviders = raw['providers'];
+    if (isPlainObject(rawProviders)) {
+        const providers = {};
+        for (const key of Object.keys(rawProviders)) {
+            const settings = rawProviders[key];
+            if (isPlainObject(settings) && key.trim().length > 0) {
+                providers[key] = settings;
+            }
+        }
+        if (Object.keys(providers).length > 0) {
+            video.providers = providers;
+        }
+    }
+    return Object.keys(video).length > 0 ? video : null;
+}
+/** Normalizes the `voice` block; returns `null` when nothing usable survives. */
+function normalizeVoice(raw) {
+    if (!isPlainObject(raw)) {
+        return null;
+    }
+    const voice = {};
+    const rawDefault = raw['default'];
+    if (isPlainObject(rawDefault)) {
+        const persona = {};
+        if (typeof rawDefault['tone'] === 'string' && rawDefault['tone'].trim().length > 0) {
+            persona.tone = rawDefault['tone'].trim();
+        }
+        if (typeof rawDefault['speakingStyle'] === 'string' && rawDefault['speakingStyle'].trim().length > 0) {
+            persona.speakingStyle = rawDefault['speakingStyle'].trim();
+        }
+        if (Object.keys(persona).length > 0) {
+            voice.default = persona;
+        }
+    }
+    const rawProviders = raw['providers'];
+    if (isPlainObject(rawProviders)) {
+        const providers = {};
+        for (const key of Object.keys(rawProviders)) {
+            const settings = rawProviders[key];
+            if (isPlainObject(settings) && key.trim().length > 0) {
+                providers[key] = settings;
+            }
+        }
+        if (Object.keys(providers).length > 0) {
+            voice.providers = providers;
+        }
+    }
+    return Object.keys(voice).length > 0 ? voice : null;
+}
+/** Normalizes the `narration` block; returns `null` when nothing usable survives. */
+function normalizeNarration(raw) {
+    if (!isPlainObject(raw)) {
+        return null;
+    }
+    const paceMs = raw['paceMs'];
+    if (typeof paceMs === 'number' && Number.isFinite(paceMs) && paceMs > 0) {
+        return { paceMs: Math.floor(paceMs) };
+    }
+    return null;
+}
+/** Normalizes a provider key / driver class for matching: lowercase, alphanumerics only. */
+function normalizeKey(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+/**
+ * Picks the provider-specific voice settings for a resolved realtime driver.
+ *
+ * Provider keys (`openai`, `elevenlabs`, `gemini`, `assemblyai`, …) are matched against the
+ * vendor `DriverClass` (e.g. `OpenAIRealtime`, `ElevenLabsRealtime`) by normalized-prefix:
+ * both sides are lowercased and stripped of non-alphanumerics, then the driver class must START
+ * WITH the provider key (`openairealtime`.startsWith(`openai`)). A bare provider name (e.g.
+ * `'openai'` from `ClientRealtimeSessionConfig.Provider`) matches the same way. The LONGEST
+ * matching key wins when several match.
+ *
+ * @param config The effective configuration.
+ * @param driverClassOrProvider The vendor `DriverClass` or the provider key itself.
+ * @returns The matched settings object (opaque driver pact), or `null` when none match.
+ */
+export function GetProviderVoiceSettings(config, driverClassOrProvider) {
+    const providers = config?.realtime?.voice?.providers;
+    if (!providers || !driverClassOrProvider) {
+        return null;
+    }
+    const normalizedDriver = normalizeKey(driverClassOrProvider);
+    if (normalizedDriver.length === 0) {
+        return null;
+    }
+    let best = null;
+    for (const key of Object.keys(providers)) {
+        const normalizedKey = normalizeKey(key);
+        if (normalizedKey.length === 0 || !normalizedDriver.startsWith(normalizedKey)) {
+            continue;
+        }
+        if (!best || normalizedKey.length > normalizeKey(best.key).length) {
+            best = { key, settings: providers[key] };
+        }
+    }
+    return best?.settings ?? null;
+}
+/**
+ * Builds the "Voice & manner" system-prompt section from the effective voice persona —
+ * appended to the server-built companion system prompt at mint. Returns an empty string when
+ * neither `tone` nor `speakingStyle` is configured (the section simply doesn't appear).
+ *
+ * @param config The effective configuration.
+ * @returns The prompt section text, or `''`.
+ */
+export function BuildVoiceMannerSection(config) {
+    const persona = config?.realtime?.voice?.default;
+    if (!persona) {
+        return '';
+    }
+    const lines = [];
+    if (persona.tone) {
+        lines.push(`Tone: ${persona.tone}`);
+    }
+    if (persona.speakingStyle) {
+        lines.push(`Speaking style: ${persona.speakingStyle}`);
+    }
+    if (lines.length === 0) {
+        return '';
+    }
+    return `Voice & manner:\n${lines.join('\n')}`;
+}
+/**
+ * Builds the runtime-override `ConfigOverridesJson` envelope (the highest-precedence cascade layer) from a
+ * per-session model and/or voice choice — the **single, surface-agnostic** shape every realtime host uses
+ * to carry a dev's pick into {@link ResolveEffectiveRealtimeConfig}. The native-chat picker produces the
+ * same shape client-side (`BuildRealtimeConfigOverridesJson` in `@memberjunction/ng-conversations`); the
+ * server-bridged hosts (LiveKit, Zoom/Teams) build it here so both funnel into the one override slot.
+ *
+ * Envelope: `{"realtime":{"modelPreference":"<id>","voice":{"providers":{"openai":{"voice":"<v>"}}}}}`.
+ * `openai` is the realtime provider today; add providers here when others ship realtime voices.
+ *
+ * @param modelId The `MJ: AI Models` Name or ID to prefer, or null/empty for none.
+ * @param voice The provider-native voice id (e.g. `echo`), or null/empty for none.
+ * @returns The JSON string, or `null` when nothing was overridden (keeps the cascade at its lower layers).
+ */
+export function BuildRealtimeOverridesJson(modelId, voice) {
+    const m = modelId?.trim() ?? '';
+    const v = voice?.trim() ?? '';
+    if (m.length === 0 && v.length === 0) {
+        return null;
+    }
+    const realtime = {};
+    if (m.length > 0) {
+        realtime.modelPreference = m;
+    }
+    if (v.length > 0) {
+        realtime.voice = { providers: { openai: { voice: v } } };
+    }
+    return JSON.stringify({ realtime });
+}
+/**
+ * Reads the effective narration pace (minimum gap in ms between spoken progress updates), or
+ * `null` when not configured. Already sanity-checked by normalization (positive finite integer).
+ *
+ * @param config The effective configuration.
+ * @returns The pace in ms, or `null`.
+ */
+export function GetNarrationPaceMs(config) {
+    return config?.realtime?.narration?.paceMs ?? null;
+}
+/**
+ * PURE authorization-policy decision for runtime overrides on a realtime session start.
+ *
+ * Rules (Amith-approved product contract):
+ * 1. No overrides requested → allowed (the everyday flow is never gated here — `CanRun` on the
+ *    target agent remains the only gate for plain session starts and for target selection).
+ * 2. `configOverridesJson` present → caller MUST hold the
+ *    {@link REALTIME_ADVANCED_SESSION_CONTROLS_AUTHORIZATION} authorization.
+ * 3. An explicit runtime model that EQUALS the metadata-configured preference is not a
+ *    deviation → no gate.
+ * 4. A DEVIATING explicit runtime model → caller must hold the authorization AND the effective
+ *    `allowUserModelOverride` must not be `false` (the policy blocks even authorized callers).
+ *
+ * The check is deliberately a structured REJECTION (the caller throws the `DenialReason`), never
+ * a silent ignore — a caller who asked for something specific must learn it was refused.
+ *
+ * @param input The override request + caller authorization + effective policy.
+ * @returns The decision.
+ */
+export function EvaluateRuntimeOverrideAuthorization(input) {
+    const requestedModel = input.RequestedModelID?.trim() ? input.RequestedModelID.trim() : null;
+    const modelDeviates = requestedModel !== null && !idsEqual(requestedModel, input.MetadataPreferredModelID);
+    if (!input.HasConfigOverrides && !modelDeviates) {
+        return { Allowed: true };
+    }
+    if (input.HasConfigOverrides && !input.CallerHasAdvancedControls) {
+        return {
+            Allowed: false,
+            DenialReason: `Runtime configuration overrides (configOverridesJson) require the ` +
+                `'${REALTIME_ADVANCED_SESSION_CONTROLS_AUTHORIZATION}' authorization. The session can be ` +
+                `started without overrides to use the co-agent's configured defaults.`
+        };
+    }
+    if (modelDeviates) {
+        if (!input.CallerHasAdvancedControls) {
+            return {
+                Allowed: false,
+                DenialReason: `Explicit realtime model selection requires the ` +
+                    `'${REALTIME_ADVANCED_SESSION_CONTROLS_AUTHORIZATION}' authorization. Omit preferredModelId ` +
+                    `to use the co-agent's configured model.`
+            };
+        }
+        if (input.AllowUserModelOverride === false) {
+            return {
+                Allowed: false,
+                DenialReason: `This co-agent's configuration sets realtime.allowUserModelOverride=false — per-session ` +
+                    `model overrides are disabled by policy, even for authorized callers. Omit preferredModelId ` +
+                    `to use the configured model.`
+            };
+        }
+    }
+    return { Allowed: true };
+}
+//# sourceMappingURL=realtime-coagent-config.js.map

package/dist/realtime/realtime-coagent-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-coagent-config.js","sourceRoot":"","sources":["../../src/realtime/realtime-coagent-config.ts"],"names":[],"mappings":"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"}

package/dist/realtime/realtime-narration.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Shared narration helpers for BOTH realtime topologies.
+ *
+ * Two concerns live here so they exist exactly once:
+ *
+ * 1. **DB template resolution** — {@link ResolveNarrationInstructionsTemplate} looks up the
+ *    seeded `Realtime Co-Agent - Progress Narration` prompt (with the deprecated pre-rename
+ *    fallback) in {@link AIEngine}'s cached prompts. The client-direct path threads the
+ *    template to the browser at session mint; the server-bridged path
+ *    ({@link import('./realtime-session-runner.js').RealtimeSessionRunner}) consumes it directly.
+ * 2. **Instruction building** — {@link BuildServerNarrationInstructions} substitutes the
+ *    template's placeholders (or falls back to the documented built-in first-person wording)
+ *    for the server-bridged runner's spoken progress updates. The Angular voice session has
+ *    its own richer builder (it also chains the model's PRIOR spoken narrations, which only
+ *    the browser can observe); this server-side builder is deliberately compact.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+/**
+ * The seeded name of the `MJ: AI Prompts` row whose `TemplateText` carries the first-person
+ * progress-narration instructions (with a `{{ progressMessage }}` placeholder).
+ */
+export declare const NARRATION_PROMPT_NAME = "Realtime Co-Agent - Progress Narration";
+/**
+ * DEPRECATED legacy name of {@link NARRATION_PROMPT_NAME}, from before the co-agent's rename
+ * from "Voice Co-Agent" to "Realtime Co-Agent". Deployments that have not re-synced the prompt
+ * seed still carry this name, so {@link ResolveNarrationInstructionsTemplate} falls back to it
+ * (with a deprecation log).
+ */
+export declare const LEGACY_NARRATION_PROMPT_NAME = "Voice Co-Agent - Progress Narration";
+/**
+ * Resolves the DB-driven progress-narration instruction template: the Active `MJ: AI Prompts`
+ * row named {@link NARRATION_PROMPT_NAME}, read from {@link AIEngine}'s cached prompts. When
+ * the current name is absent, falls back to the DEPRECATED {@link LEGACY_NARRATION_PROMPT_NAME}
+ * (pre-rename seed) with a deprecation log. **Tolerant**: returns `null` (never throws) when
+ * neither prompt is present, the text is empty, or the engine cache is unavailable — consumers
+ * fall back to the built-in narration instruction wording.
+ *
+ * @returns The template text (containing a `{{ progressMessage }}` placeholder), or `null`.
+ */
+export declare function ResolveNarrationInstructionsTemplate(): string | null;
+/**
+ * The documented BUILT-IN fallback wording for a server-bridged spoken progress update —
+ * strictly first person (the co-agent owns the work), one short sentence, no repetition.
+ * Used when no DB template resolved for the deployment.
+ *
+ * @param digest The aggregated progress digest (one or more updates, oldest first).
+ * @param updateNumber 1-based number of this spoken update within the current task.
+ * @returns The complete spoken-update instruction text.
+ */
+export declare function DefaultServerNarrationInstructions(digest: string, updateNumber: number): string;
+/**
+ * Builds the spoken-update instructions for the server-bridged runner from the DB template
+ * (substituting `{{ progressMessage }}` / `{{ updateNumber }}`, space and no-space variants),
+ * falling back to {@link DefaultServerNarrationInstructions} when the template is absent or
+ * blank. The `{{ priorNarrations }}` placeholder is substituted with a neutral note — the
+ * server-bridged path cannot observe what the model actually SAID (those transcripts ride the
+ * provider socket), unlike the browser host which chains them.
+ *
+ * @param template The DB-driven instruction template, or `null`/`undefined` when unavailable.
+ * @param digest The aggregated progress digest (one or more updates, oldest first).
+ * @param updateNumber 1-based number of this spoken update within the current task.
+ * @returns The complete spoken-update instruction text.
+ */
+export declare function BuildServerNarrationInstructions(template: string | null | undefined, digest: string, updateNumber: number): string;
+//# sourceMappingURL=realtime-narration.d.ts.map

package/dist/realtime/realtime-narration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-narration.d.ts","sourceRoot":"","sources":["../../src/realtime/realtime-narration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH;;;GAGG;AACH,eAAO,MAAM,qBAAqB,2CAA2C,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,wCAAwC,CAAC;AAOlF;;;;;;;;;GASG;AACH,wBAAgB,oCAAoC,IAAI,MAAM,GAAG,IAAI,CAmBpE;AAwBD;;;;;;;;GAQG;AACH,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAU/F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gCAAgC,CAC5C,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GACrB,MAAM,CAcR"}

package/dist/realtime/realtime-narration.js

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Shared narration helpers for BOTH realtime topologies.
+ *
+ * Two concerns live here so they exist exactly once:
+ *
+ * 1. **DB template resolution** — {@link ResolveNarrationInstructionsTemplate} looks up the
+ *    seeded `Realtime Co-Agent - Progress Narration` prompt (with the deprecated pre-rename
+ *    fallback) in {@link AIEngine}'s cached prompts. The client-direct path threads the
+ *    template to the browser at session mint; the server-bridged path
+ *    ({@link import('./realtime-session-runner.js').RealtimeSessionRunner}) consumes it directly.
+ * 2. **Instruction building** — {@link BuildServerNarrationInstructions} substitutes the
+ *    template's placeholders (or falls back to the documented built-in first-person wording)
+ *    for the server-bridged runner's spoken progress updates. The Angular voice session has
+ *    its own richer builder (it also chains the model's PRIOR spoken narrations, which only
+ *    the browser can observe); this server-side builder is deliberately compact.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+import { LogStatus } from '@memberjunction/core';
+import { AIEngine } from '@memberjunction/aiengine';
+/**
+ * The seeded name of the `MJ: AI Prompts` row whose `TemplateText` carries the first-person
+ * progress-narration instructions (with a `{{ progressMessage }}` placeholder).
+ */
+export const NARRATION_PROMPT_NAME = 'Realtime Co-Agent - Progress Narration';
+/**
+ * DEPRECATED legacy name of {@link NARRATION_PROMPT_NAME}, from before the co-agent's rename
+ * from "Voice Co-Agent" to "Realtime Co-Agent". Deployments that have not re-synced the prompt
+ * seed still carry this name, so {@link ResolveNarrationInstructionsTemplate} falls back to it
+ * (with a deprecation log).
+ */
+export const LEGACY_NARRATION_PROMPT_NAME = 'Voice Co-Agent - Progress Narration';
+/** Placeholder token variants substituted by {@link BuildServerNarrationInstructions}. */
+const PROGRESS_TOKENS = ['{{ progressMessage }}', '{{progressMessage}}'];
+const PRIOR_TOKENS = ['{{ priorNarrations }}', '{{priorNarrations}}'];
+const NUMBER_TOKENS = ['{{ updateNumber }}', '{{updateNumber}}'];
+/**
+ * Resolves the DB-driven progress-narration instruction template: the Active `MJ: AI Prompts`
+ * row named {@link NARRATION_PROMPT_NAME}, read from {@link AIEngine}'s cached prompts. When
+ * the current name is absent, falls back to the DEPRECATED {@link LEGACY_NARRATION_PROMPT_NAME}
+ * (pre-rename seed) with a deprecation log. **Tolerant**: returns `null` (never throws) when
+ * neither prompt is present, the text is empty, or the engine cache is unavailable — consumers
+ * fall back to the built-in narration instruction wording.
+ *
+ * @returns The template text (containing a `{{ progressMessage }}` placeholder), or `null`.
+ */
+export function ResolveNarrationInstructionsTemplate() {
+    try {
+        const current = findActiveNarrationPromptText(NARRATION_PROMPT_NAME);
+        if (current) {
+            return current;
+        }
+        const legacy = findActiveNarrationPromptText(LEGACY_NARRATION_PROMPT_NAME);
+        if (legacy) {
+            LogStatus(`Realtime narration: resolved the narration prompt via its DEPRECATED legacy name ` +
+                `'${LEGACY_NARRATION_PROMPT_NAME}'. Re-sync the prompt seed metadata to rename it to ` +
+                `'${NARRATION_PROMPT_NAME}'.`);
+            return legacy;
+        }
+        return null;
+    }
+    catch {
+        return null; // engine cache unavailable — tolerated, consumers fall back
+    }
+}
+/**
+ * Finds the Active `MJ: AI Prompts` row with the given name (case/whitespace-insensitive) in
+ * {@link AIEngine}'s cached prompts and returns its non-empty `TemplateText`, or `null`.
+ */
+function findActiveNarrationPromptText(promptName) {
+    const wanted = promptName.toLowerCase();
+    const prompt = (AIEngine.Instance.Prompts ?? []).find(p => p.Name?.trim().toLowerCase() === wanted && p.Status === 'Active');
+    const text = prompt?.TemplateText;
+    return text && text.trim().length > 0 ? text : null;
+}
+/** Replaces every occurrence of each token variant with the value. */
+function replaceTokens(text, tokens, value) {
+    let out = text;
+    for (const t of tokens) {
+        out = out.split(t).join(value);
+    }
+    return out;
+}
+/**
+ * The documented BUILT-IN fallback wording for a server-bridged spoken progress update —
+ * strictly first person (the co-agent owns the work), one short sentence, no repetition.
+ * Used when no DB template resolved for the deployment.
+ *
+ * @param digest The aggregated progress digest (one or more updates, oldest first).
+ * @param updateNumber 1-based number of this spoken update within the current task.
+ * @returns The complete spoken-update instruction text.
+ */
+export function DefaultServerNarrationInstructions(digest, updateNumber) {
+    return (`Live progress on the work YOU are doing for the user (oldest first): ${digest}. ` +
+        `This is spoken update #${updateNumber} for this task. ` +
+        `Say ONE short, natural sentence in the FIRST PERSON continuing the story of what you are doing ` +
+        `("I'm pulling that up now", "Got the first part — grabbing the rest"). VARY the phrasing across ` +
+        `updates and never repeat information you've already conveyed — only add what's new. Strictly first ` +
+        `person: the words "it" and the agent's name must not be the subject of your sentence, and never say ` +
+        `generic filler like "it's still running in the background".`);
+}
+/**
+ * Builds the spoken-update instructions for the server-bridged runner from the DB template
+ * (substituting `{{ progressMessage }}` / `{{ updateNumber }}`, space and no-space variants),
+ * falling back to {@link DefaultServerNarrationInstructions} when the template is absent or
+ * blank. The `{{ priorNarrations }}` placeholder is substituted with a neutral note — the
+ * server-bridged path cannot observe what the model actually SAID (those transcripts ride the
+ * provider socket), unlike the browser host which chains them.
+ *
+ * @param template The DB-driven instruction template, or `null`/`undefined` when unavailable.
+ * @param digest The aggregated progress digest (one or more updates, oldest first).
+ * @param updateNumber 1-based number of this spoken update within the current task.
+ * @returns The complete spoken-update instruction text.
+ */
+export function BuildServerNarrationInstructions(template, digest, updateNumber) {
+    if (!template || template.trim().length === 0) {
+        return DefaultServerNarrationInstructions(digest, updateNumber);
+    }
+    let out = replaceTokens(template, PROGRESS_TOKENS, digest);
+    out = replaceTokens(out, PRIOR_TOKENS, updateNumber <= 1
+        ? 'Nothing yet — this is your first spoken update for this task.'
+        : `You have already spoken ${updateNumber - 1} update(s) for this task — do not repeat yourself; only add what's new.`);
+    out = replaceTokens(out, NUMBER_TOKENS, String(updateNumber));
+    return out;
+}
+//# sourceMappingURL=realtime-narration.js.map

package/dist/realtime/realtime-narration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-narration.js","sourceRoot":"","sources":["../../src/realtime/realtime-narration.ts"],"names":[],"mappings":"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"}