@memberjunction/ai-agents 5.43.0 → 5.44.0

package/dist/prompt-component-resolver.d.ts

@@ -0,0 +1,73 @@
+import { MJScopedPromptPartEntity } from "@memberjunction/core-entities";
+import { ChatMessage, ChatMessageRole } from "@memberjunction/ai";
+import { SecondaryScopeValue } from "@memberjunction/ai-core-plus";
+/**
+ * The scope a prompt-component resolution runs in. Mirrors the polymorphic scope the agent
+ * runtime already carries for memory (PrimaryScopeEntity/Record + SecondaryScopes).
+ */
+export interface PromptComponentScope {
+    primaryScopeEntityId?: string;
+    primaryScopeRecordId?: string;
+    secondaryScopes?: Record<string, SecondaryScopeValue>;
+}
+/**
+ * PromptComponentResolver — decides which `MJ: Scoped Prompt Parts` are included for a given
+ * prompt under a given scope, and assembles them into a role-faithful `ChatMessage[]`.
+ *
+ * **Pluggable (ClassFactory) + metadata-driven (template method).**
+ * The public {@link Resolve} / {@link AssembleMessages} fix the orchestration; the protected hooks
+ * ({@link getCandidates}, {@link isInScope}, {@link score}, {@link selectIncluded}, {@link order})
+ * are the extension points. MJ core obtains the resolver via
+ * `MJGlobal.Instance.ClassFactory.CreateInstance(PromptComponentResolver)`, which returns this base
+ * by default (no registration ⇒ base instance) or the highest-priority registered subclass. So any
+ * downstream consumer can plug in custom inclusion logic with **no core change**:
+ *
+ * ```ts
+ * @RegisterClass(PromptComponentResolver)            // priority auto-increments by import order
+ * export class MyResolver extends PromptComponentResolver {
+ *   protected override score(p, scope) { ... }        // custom ranking
+ *   protected override selectIncluded(parts, scope) { ... } // custom merge rules
+ * }
+ * ```
+ *
+ * Base (metadata-driven) defaults:
+ *  - **Additive across part `Name`s** — distinct names all survive.
+ *  - **Within a `Name`**, the row's `MergeBehavior` decides: `'Override'` (default) ⇒ the
+ *    most-specific part wins (replace), `'Append'` ⇒ all in-scope same-named parts are included.
+ *  - Specificity (the override ranking): SecondaryScopes match (+4) > PrimaryScopeRecord (+2) >
+ *    Global (+1), tie-broken by `Priority`.
+ *  - Final order: `Sort` ASC, then `Priority` DESC.
+ *  - Roles are preserved (System/User/Assistant) so the assembled messages drive the model directly.
+ */
+export declare class PromptComponentResolver {
+    /** Resolve the included, ordered parts for `promptID` under `scope`. */
+    Resolve(promptID: string, scope: PromptComponentScope): MJScopedPromptPartEntity[];
+    /** Assemble resolved parts into role-faithful messages, coalescing adjacent same-role. */
+    AssembleMessages(parts: MJScopedPromptPartEntity[]): ChatMessage[];
+    /** Candidate parts for a prompt: same PromptID + resolvable Status. Override to widen/narrow. */
+    protected getCandidates(promptID: string): MJScopedPromptPartEntity[];
+    /** Is this part compatible with the run scope? (cascading: a part may only require dims the run has) */
+    protected isInScope(p: MJScopedPromptPartEntity, scope: PromptComponentScope): boolean;
+    /** Specificity score: SecondaryScopes match (+4) > PrimaryScopeRecord (+2) > Global (+1). */
+    protected score(p: MJScopedPromptPartEntity): number;
+    /**
+     * From in-scope candidates, decide inclusion per `Name`:
+     *  - rank a Name's parts by specificity (score) then `Priority`;
+     *  - the top part's `MergeBehavior` governs the group — `'Override'` keeps only the top,
+     *    `'Append'` keeps all (additive within the Name).
+     * Distinct names always coexist (additive across names).
+     */
+    protected selectIncluded(candidates: MJScopedPromptPartEntity[], _scope: PromptComponentScope): MJScopedPromptPartEntity[];
+    /** Final assembly order: Sort ASC, then Priority DESC, then Name. */
+    protected order(parts: MJScopedPromptPartEntity[]): MJScopedPromptPartEntity[];
+    protected parseScopes(raw: string | null): Record<string, unknown>;
+    protected coerceRole(raw: string | null): ChatMessageRole;
+}
+/**
+ * Convenience used by the agent runtime: obtain the (possibly overridden) resolver via the
+ * class factory, resolve + assemble for `promptID`/`scope`, and unshift the role-faithful messages
+ * onto the front of `conversationMessages` (mirroring how memory/RAG inject). No-op when nothing
+ * resolves. Returns the included parts (for observability).
+ */
+export declare function InjectScopedPromptParts(resolver: PromptComponentResolver, promptID: string, scope: PromptComponentScope, conversationMessages: ChatMessage[]): MJScopedPromptPartEntity[];
+//# sourceMappingURL=prompt-component-resolver.d.ts.map

package/dist/prompt-component-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-component-resolver.d.ts","sourceRoot":"","sources":["../src/prompt-component-resolver.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAEnE;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACjC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CACzD;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,uBAAuB;IAGhC,wEAAwE;IACjE,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,GAAG,wBAAwB,EAAE;IAMzF,0FAA0F;IACnF,gBAAgB,CAAC,KAAK,EAAE,wBAAwB,EAAE,GAAG,WAAW,EAAE;IAkBzE,iGAAiG;IACjG,SAAS,CAAC,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,wBAAwB,EAAE;IAMrE,wGAAwG;IACxG,SAAS,CAAC,SAAS,CAAC,CAAC,EAAE,wBAAwB,EAAE,KAAK,EAAE,oBAAoB,GAAG,OAAO;IA0BtF,6FAA6F;IAC7F,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,wBAAwB,GAAG,MAAM;IAOpD;;;;;;OAMG;IACH,SAAS,CAAC,cAAc,CACpB,UAAU,EAAE,wBAAwB,EAAE,EACtC,MAAM,EAAE,oBAAoB,GAC7B,wBAAwB,EAAE;IAmB7B,qEAAqE;IACrE,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,wBAAwB,EAAE,GAAG,wBAAwB,EAAE;IAQ9E,SAAS,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAUlE,SAAS,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,eAAe;CAM5D;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACnC,QAAQ,EAAE,uBAAuB,EACjC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,oBAAoB,EAC3B,oBAAoB,EAAE,WAAW,EAAE,GACpC,wBAAwB,EAAE,CAW5B"}

package/dist/prompt-component-resolver.js

@@ -0,0 +1,166 @@
+import { LogStatus } from "@memberjunction/core";
+import { UUIDsEqual } from "@memberjunction/global";
+import { AIEngine } from "@memberjunction/aiengine";
+/** Statuses eligible for resolution. Archived parts are excluded. */
+const RESOLVABLE_STATUSES = new Set(["Active", "Provisional"]);
+/**
+ * PromptComponentResolver — decides which `MJ: Scoped Prompt Parts` are included for a given
+ * prompt under a given scope, and assembles them into a role-faithful `ChatMessage[]`.
+ *
+ * **Pluggable (ClassFactory) + metadata-driven (template method).**
+ * The public {@link Resolve} / {@link AssembleMessages} fix the orchestration; the protected hooks
+ * ({@link getCandidates}, {@link isInScope}, {@link score}, {@link selectIncluded}, {@link order})
+ * are the extension points. MJ core obtains the resolver via
+ * `MJGlobal.Instance.ClassFactory.CreateInstance(PromptComponentResolver)`, which returns this base
+ * by default (no registration ⇒ base instance) or the highest-priority registered subclass. So any
+ * downstream consumer can plug in custom inclusion logic with **no core change**:
+ *
+ * ```ts
+ * @RegisterClass(PromptComponentResolver)            // priority auto-increments by import order
+ * export class MyResolver extends PromptComponentResolver {
+ *   protected override score(p, scope) { ... }        // custom ranking
+ *   protected override selectIncluded(parts, scope) { ... } // custom merge rules
+ * }
+ * ```
+ *
+ * Base (metadata-driven) defaults:
+ *  - **Additive across part `Name`s** — distinct names all survive.
+ *  - **Within a `Name`**, the row's `MergeBehavior` decides: `'Override'` (default) ⇒ the
+ *    most-specific part wins (replace), `'Append'` ⇒ all in-scope same-named parts are included.
+ *  - Specificity (the override ranking): SecondaryScopes match (+4) > PrimaryScopeRecord (+2) >
+ *    Global (+1), tie-broken by `Priority`.
+ *  - Final order: `Sort` ASC, then `Priority` DESC.
+ *  - Roles are preserved (System/User/Assistant) so the assembled messages drive the model directly.
+ */
+export class PromptComponentResolver {
+    // ── Public template methods ────────────────────────────────────────────────
+    /** Resolve the included, ordered parts for `promptID` under `scope`. */
+    Resolve(promptID, scope) {
+        const inScope = this.getCandidates(promptID).filter((p) => this.isInScope(p, scope));
+        const included = this.selectIncluded(inScope, scope);
+        return this.order(included);
+    }
+    /** Assemble resolved parts into role-faithful messages, coalescing adjacent same-role. */
+    AssembleMessages(parts) {
+        const out = [];
+        for (const p of parts) {
+            const content = (p.Text ?? "").trim();
+            if (!content)
+                continue;
+            const role = this.coerceRole(p.Role);
+            const last = out[out.length - 1];
+            if (last && last.role === role) {
+                last.content = `${last.content}\n\n${content}`;
+            }
+            else {
+                out.push({ role, content });
+            }
+        }
+        return out;
+    }
+    // ── Protected hooks (override points) ──────────────────────────────────────
+    /** Candidate parts for a prompt: same PromptID + resolvable Status. Override to widen/narrow. */
+    getCandidates(promptID) {
+        return AIEngine.Instance.ScopedPromptParts.filter((p) => UUIDsEqual(p.PromptID, promptID) && RESOLVABLE_STATUSES.has(p.Status));
+    }
+    /** Is this part compatible with the run scope? (cascading: a part may only require dims the run has) */
+    isInScope(p, scope) {
+        if (p.PrimaryScopeRecordID) {
+            if (!scope.primaryScopeRecordId ||
+                p.PrimaryScopeRecordID.toLowerCase() !== scope.primaryScopeRecordId.toLowerCase()) {
+                return false;
+            }
+            if (p.PrimaryScopeEntityID &&
+                scope.primaryScopeEntityId &&
+                !UUIDsEqual(p.PrimaryScopeEntityID, scope.primaryScopeEntityId)) {
+                return false;
+            }
+        }
+        const partScopes = this.parseScopes(p.SecondaryScopes);
+        for (const key of Object.keys(partScopes)) {
+            const runValue = scope.secondaryScopes?.[key];
+            if (runValue === undefined || String(runValue) !== String(partScopes[key])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /** Specificity score: SecondaryScopes match (+4) > PrimaryScopeRecord (+2) > Global (+1). */
+    score(p) {
+        let s = 1;
+        if (p.PrimaryScopeRecordID)
+            s += 2;
+        if (Object.keys(this.parseScopes(p.SecondaryScopes)).length > 0)
+            s += 4;
+        return s;
+    }
+    /**
+     * From in-scope candidates, decide inclusion per `Name`:
+     *  - rank a Name's parts by specificity (score) then `Priority`;
+     *  - the top part's `MergeBehavior` governs the group — `'Override'` keeps only the top,
+     *    `'Append'` keeps all (additive within the Name).
+     * Distinct names always coexist (additive across names).
+     */
+    selectIncluded(candidates, _scope) {
+        const byName = new Map();
+        for (const p of candidates) {
+            const arr = byName.get(p.Name) ?? [];
+            arr.push(p);
+            byName.set(p.Name, arr);
+        }
+        const result = [];
+        for (const group of byName.values()) {
+            group.sort((a, b) => this.score(b) - this.score(a) || b.Priority - a.Priority);
+            if (group[0].MergeBehavior === "Append") {
+                result.push(...group);
+            }
+            else {
+                result.push(group[0]);
+            }
+        }
+        return result;
+    }
+    /** Final assembly order: Sort ASC, then Priority DESC, then Name. */
+    order(parts) {
+        return [...parts].sort((a, b) => a.Sort - b.Sort || b.Priority - a.Priority || a.Name.localeCompare(b.Name));
+    }
+    // ── Helpers ────────────────────────────────────────────────────────────────
+    parseScopes(raw) {
+        if (!raw)
+            return {};
+        try {
+            const o = JSON.parse(raw);
+            return o && typeof o === "object" ? o : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    coerceRole(raw) {
+        const lower = typeof raw === "string" ? raw.toLowerCase() : "";
+        if (lower === "user")
+            return "user";
+        if (lower === "assistant")
+            return "assistant";
+        return "system";
+    }
+}
+/**
+ * Convenience used by the agent runtime: obtain the (possibly overridden) resolver via the
+ * class factory, resolve + assemble for `promptID`/`scope`, and unshift the role-faithful messages
+ * onto the front of `conversationMessages` (mirroring how memory/RAG inject). No-op when nothing
+ * resolves. Returns the included parts (for observability).
+ */
+export function InjectScopedPromptParts(resolver, promptID, scope, conversationMessages) {
+    const parts = resolver.Resolve(promptID, scope);
+    if (parts.length === 0)
+        return [];
+    const messages = resolver.AssembleMessages(parts);
+    if (messages.length === 0)
+        return [];
+    conversationMessages.unshift(...messages);
+    LogStatus(`PromptComponentResolver: injected ${messages.length} message(s) from ${parts.length} ` +
+        `part(s) for prompt ${promptID} (scope record=${scope.primaryScopeRecordId ?? "global"})`);
+    return parts;
+}
+//# sourceMappingURL=prompt-component-resolver.js.map

package/dist/prompt-component-resolver.js.map

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

package/dist/realtime/agent-media-library.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Resolves an agent's curated **media kit** — a `MJ: Collections` of `MJ: Artifacts`
+ * bound to the agent (or supplied as a per-session override) — into a compact, model-readable
+ * manifest the realtime agent reasons over to decide what to show on the Media channel.
+ *
+ * Design: a Collection IS the kit; each `MJ: Collection Artifacts` membership row carries the
+ * per-kit `Sequence` (priority), `ContextDescription` (agent "when to show it") and `Preload`
+ * (eager hint). The artifact's current version supplies the actual media (`FileID` -> `MJ: Files`,
+ * `MimeType`, display name). We add NO new top-level entity — the agent reuses the existing
+ * `Media_ShowMedia({ fileId, mediaType, displayName })` client tool to surface a chosen item, which
+ * streams through the authenticated `/media` route. Nothing here duplicates `MJ: Files`.
+ *
+ * Pure helpers ({@link mediaTypeFromMimeType}, {@link formatAgentMediaManifest}) are exported for
+ * unit testing; the DB-touching resolvers accept an explicit `provider` + `contextUser` so they are
+ * multi-provider safe and mockable.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+/** The media kinds the realtime Media channel can render (mirrors the client `Media_ShowMedia` enum). */
+export type AgentMediaKind = 'image' | 'video' | 'audio' | 'pdf' | 'web';
+/** One resolved, model-readable media item in an agent's kit (ordered by its membership `Sequence`). */
+export interface AgentMediaManifestItem {
+    /** The `MJ: Collection Artifacts` membership id (stable per kit). */
+    ResourceID: string;
+    /** The `MJ: Files` id to show — streamed securely via the `/media` route by `Media_ShowMedia`. */
+    FileID: string;
+    /** The media kind derived from the artifact version's MIME type. */
+    MediaType: AgentMediaKind;
+    /** Short label for the item's tab (the artifact version's name). */
+    DisplayName: string;
+    /** Agent-facing "what this is / when to show it" (membership override, else the version description). */
+    ContextDescription: string | null;
+    /** When true, the agent is told to show this at session start rather than waiting for relevance. */
+    Preload: boolean;
+}
+/**
+ * Maps an artifact version's MIME type to a Media-channel kind. Returns `null` for types the Media
+ * surface can't render as media (so the caller drops the item from the kit).
+ */
+export declare function mediaTypeFromMimeType(mimeType: string | null | undefined): AgentMediaKind | null;
+/**
+ * Resolves the Collection id that is the agent's media kit for this session:
+ * `override > AIAgent.DefaultMediaCollectionID > null`.
+ */
+export declare function resolveAgentMediaCollectionID(provider: IMetadataProvider, contextUser: UserInfo, agentID: string, overrideCollectionID?: string | null): Promise<string | null>;
+/**
+ * Loads a Collection's artifacts (ordered by membership `Sequence`) and resolves each to a media
+ * manifest item, dropping memberships whose current version has no `FileID` or a non-media MIME type.
+ */
+export declare function resolveAgentMediaManifest(provider: IMetadataProvider, contextUser: UserInfo, collectionID: string): Promise<AgentMediaManifestItem[]>;
+/**
+ * Formats a media manifest into a single background context note for the realtime agent. Lists each
+ * item with its `fileId`, media type, display name and when-to-show guidance, and instructs the agent
+ * to surface items with the existing `Media_ShowMedia` tool. Returns `null` for an empty manifest.
+ */
+export declare function formatAgentMediaManifest(items: AgentMediaManifestItem[]): string | null;
+/**
+ * End-to-end: resolves the agent's media kit (override > agent default) and returns the formatted
+ * agent context note, or `null` when there is no kit / no showable items. Best-effort: logs and
+ * returns `null` on any failure so it can never break session start.
+ */
+export declare function buildAgentMediaContextNote(provider: IMetadataProvider, contextUser: UserInfo, agentID: string, overrideCollectionID?: string | null): Promise<string | null>;
+//# sourceMappingURL=agent-media-library.d.ts.map

package/dist/realtime/agent-media-library.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-media-library.d.ts","sourceRoot":"","sources":["../../src/realtime/agent-media-library.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,iBAAiB,EAAW,QAAQ,EAAY,MAAM,sBAAsB,CAAC;AAItF,yGAAyG;AACzG,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,GAAG,KAAK,CAAC;AAEzE,wGAAwG;AACxG,MAAM,WAAW,sBAAsB;IACnC,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,kGAAkG;IAClG,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,SAAS,EAAE,cAAc,CAAC;IAC1B,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB,yGAAyG;IACzG,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,oGAAoG;IACpG,OAAO,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,cAAc,GAAG,IAAI,CAQhG;AAED;;;GAGG;AACH,wBAAsB,6BAA6B,CAC/C,QAAQ,EAAE,iBAAiB,EAC3B,WAAW,EAAE,QAAQ,EACrB,OAAO,EAAE,MAAM,EACf,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,GACrC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAuBxB;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,CAC3C,QAAQ,EAAE,iBAAiB,EAC3B,WAAW,EAAE,QAAQ,EACrB,YAAY,EAAE,MAAM,GACrB,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAwBnC;AAgDD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,sBAAsB,EAAE,GAAG,MAAM,GAAG,IAAI,CAevF;AAED;;;;GAIG;AACH,wBAAsB,0BAA0B,CAC5C,QAAQ,EAAE,iBAAiB,EAC3B,WAAW,EAAE,QAAQ,EACrB,OAAO,EAAE,MAAM,EACf,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,GACrC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAYxB"}

package/dist/realtime/agent-media-library.js

@@ -0,0 +1,160 @@
+/**
+ * @fileoverview Resolves an agent's curated **media kit** — a `MJ: Collections` of `MJ: Artifacts`
+ * bound to the agent (or supplied as a per-session override) — into a compact, model-readable
+ * manifest the realtime agent reasons over to decide what to show on the Media channel.
+ *
+ * Design: a Collection IS the kit; each `MJ: Collection Artifacts` membership row carries the
+ * per-kit `Sequence` (priority), `ContextDescription` (agent "when to show it") and `Preload`
+ * (eager hint). The artifact's current version supplies the actual media (`FileID` -> `MJ: Files`,
+ * `MimeType`, display name). We add NO new top-level entity — the agent reuses the existing
+ * `Media_ShowMedia({ fileId, mediaType, displayName })` client tool to surface a chosen item, which
+ * streams through the authenticated `/media` route. Nothing here duplicates `MJ: Files`.
+ *
+ * Pure helpers ({@link mediaTypeFromMimeType}, {@link formatAgentMediaManifest}) are exported for
+ * unit testing; the DB-touching resolvers accept an explicit `provider` + `contextUser` so they are
+ * multi-provider safe and mockable.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+import { RunView, LogError } from '@memberjunction/core';
+import { IsValidUUID } from '@memberjunction/global';
+/**
+ * Maps an artifact version's MIME type to a Media-channel kind. Returns `null` for types the Media
+ * surface can't render as media (so the caller drops the item from the kit).
+ */
+export function mediaTypeFromMimeType(mimeType) {
+    const mime = (mimeType ?? '').trim().toLowerCase();
+    if (mime.startsWith('image/'))
+        return 'image';
+    if (mime.startsWith('video/'))
+        return 'video';
+    if (mime.startsWith('audio/'))
+        return 'audio';
+    if (mime === 'application/pdf')
+        return 'pdf';
+    if (mime === 'text/html' || mime === 'application/xhtml+xml')
+        return 'web';
+    return null;
+}
+/**
+ * Resolves the Collection id that is the agent's media kit for this session:
+ * `override > AIAgent.DefaultMediaCollectionID > null`.
+ */
+export async function resolveAgentMediaCollectionID(provider, contextUser, agentID, overrideCollectionID) {
+    if (overrideCollectionID) {
+        // The override may come from a calling app / per-session input, so validate it as a UUID before it
+        // ever reaches a filter. A malformed override is ignored (logged) and resolution falls back to the
+        // agent default — never a broken or injected query.
+        const trimmed = overrideCollectionID.trim();
+        if (IsValidUUID(trimmed)) {
+            return trimmed;
+        }
+        LogError(`[agent-media-library] Ignoring malformed overrideCollectionID '${overrideCollectionID}' — ` +
+            'falling back to the agent default media kit.');
+    }
+    const rv = RunView.FromMetadataProvider(provider);
+    const result = await rv.RunView({ EntityName: 'AI Agents', ExtraFilter: `ID='${agentID}'`, ResultType: 'entity_object' }, contextUser);
+    if (!result.Success || result.Results.length === 0) {
+        return null;
+    }
+    return result.Results[0].DefaultMediaCollectionID ?? null;
+}
+/**
+ * Loads a Collection's artifacts (ordered by membership `Sequence`) and resolves each to a media
+ * manifest item, dropping memberships whose current version has no `FileID` or a non-media MIME type.
+ */
+export async function resolveAgentMediaManifest(provider, contextUser, collectionID) {
+    const rv = RunView.FromMetadataProvider(provider);
+    const memberships = await rv.RunView({
+        EntityName: 'MJ: Collection Artifacts',
+        ExtraFilter: `CollectionID='${collectionID}'`,
+        OrderBy: 'Sequence ASC',
+        ResultType: 'entity_object',
+    }, contextUser);
+    if (!memberships.Success || memberships.Results.length === 0) {
+        return [];
+    }
+    const versionsByID = await loadArtifactVersions(rv, contextUser, memberships.Results.map((m) => m.ArtifactVersionID));
+    const items = [];
+    for (const membership of memberships.Results) {
+        const item = toManifestItem(membership, versionsByID.get(membership.ArtifactVersionID));
+        if (item) {
+            items.push(item);
+        }
+    }
+    return items;
+}
+/** Loads the artifact versions referenced by a kit's memberships, keyed by id. */
+async function loadArtifactVersions(rv, contextUser, versionIDs) {
+    const byID = new Map();
+    const uniqueIDs = [...new Set(versionIDs.filter((id) => !!id))];
+    if (uniqueIDs.length === 0) {
+        return byID;
+    }
+    const inList = uniqueIDs.map((id) => `'${id}'`).join(',');
+    const result = await rv.RunView({ EntityName: 'MJ: Artifact Versions', ExtraFilter: `ID IN (${inList})`, ResultType: 'entity_object' }, contextUser);
+    if (result.Success) {
+        for (const version of result.Results) {
+            byID.set(version.ID, version);
+        }
+    }
+    return byID;
+}
+/** Resolves one membership + its artifact version to a manifest item, or `null` if not showable. */
+function toManifestItem(membership, version) {
+    if (!version || !version.FileID) {
+        return null; // text-only / unresolved versions can't be shown as media
+    }
+    const mediaType = mediaTypeFromMimeType(version.MimeType);
+    if (!mediaType) {
+        return null; // non-media MIME type — drop from the kit
+    }
+    return {
+        ResourceID: membership.ID,
+        FileID: version.FileID,
+        MediaType: mediaType,
+        DisplayName: version.Name?.trim() || 'Media',
+        ContextDescription: membership.ContextDescription?.trim() || version.Description?.trim() || null,
+        Preload: !!membership.Preload,
+    };
+}
+/**
+ * Formats a media manifest into a single background context note for the realtime agent. Lists each
+ * item with its `fileId`, media type, display name and when-to-show guidance, and instructs the agent
+ * to surface items with the existing `Media_ShowMedia` tool. Returns `null` for an empty manifest.
+ */
+export function formatAgentMediaManifest(items) {
+    if (items.length === 0) {
+        return null;
+    }
+    const lines = items.map((item, index) => {
+        const when = item.ContextDescription ? ` — ${item.ContextDescription}` : '';
+        const preload = item.Preload ? ' [PRELOAD: show at the start of the call]' : '';
+        return `${index + 1}. "${item.DisplayName}" (${item.MediaType})${when} fileId: ${item.FileID}${preload}`;
+    });
+    return ('[media-library] You have a curated media kit you can show on the shared Media surface during this call. ' +
+        'To show an item, call Media_ShowMedia with its fileId, mediaType and displayName. Show an item only when ' +
+        'it is relevant (or now, if it is marked PRELOAD). Do NOT read this list aloud. Available items, in priority order:\n' +
+        lines.join('\n'));
+}
+/**
+ * End-to-end: resolves the agent's media kit (override > agent default) and returns the formatted
+ * agent context note, or `null` when there is no kit / no showable items. Best-effort: logs and
+ * returns `null` on any failure so it can never break session start.
+ */
+export async function buildAgentMediaContextNote(provider, contextUser, agentID, overrideCollectionID) {
+    try {
+        const collectionID = await resolveAgentMediaCollectionID(provider, contextUser, agentID, overrideCollectionID);
+        if (!collectionID) {
+            return null;
+        }
+        const items = await resolveAgentMediaManifest(provider, contextUser, collectionID);
+        return formatAgentMediaManifest(items);
+    }
+    catch (error) {
+        LogError(`[agent-media-library] Failed to build media manifest for agent ${agentID}: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+//# sourceMappingURL=agent-media-library.js.map

package/dist/realtime/agent-media-library.js.map

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

package/dist/realtime/client-context-channel-server.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview Server-side channel plugin for the **headless** Client Context channel — the live
+ * wire that streams the user's app context (where they are, what they see, the available client-tool
+ * and agent manifest) to the realtime co-agent, and through which the model's single stable
+ * `ContextTool` proxy drives in-app actions.
+ *
+ * Paired with the browser's `ClientContextChannel` client plugin through the seeded
+ * `MJ: AI Agent Channels` row (`Name: 'ClientContextChannel'`, `IsHeadless: 1`,
+ * `ServerPluginClass: 'ClientContextChannelServer'`, `ClientPluginClass: 'ClientContextChannel'`).
+ *
+ * **Why the server half is intentionally thin.** This channel is *headless* (it never mounts a tab)
+ * and *ephemeral* (it persists no state of record — it is a live wire, not a document like the
+ * whiteboard). In the client-direct topology the work lives in the browser: the client plugin
+ * publishes context deltas via the provider's `SendContextNote` and executes `ContextTool` calls
+ * locally through the unified client-tool resolver (`ResolveClientTools` in
+ * `@memberjunction/ai-core-plus`) with no server round-trip. The server half exists to (a) complete
+ * the channel registry pairing so the channel is discoverable/loadable like every other channel, and
+ * (b) be the home for any *future* server-side context tooling. It contributes no server tools today
+ * and saves no state — both base defaults, made explicit here.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+import { BaseRealtimeChannelServer, RealtimeToolDefinition } from '@memberjunction/ai';
+/** The stable channel name, matching the seeded `MJ: AI Agent Channels` row. */
+export declare const CLIENT_CONTEXT_CHANNEL_NAME = "ClientContextChannel";
+/**
+ * Server half of the headless Client Context channel. One instance per realtime session (created by
+ * `RealtimeChannelServerHost` from the channel registry — never construct directly).
+ *
+ * Contributes **no server tools** ({@link GetServerToolDefinitions} returns `[]`) — the channel's
+ * `ContextTool` and client tools execute client-side — and persists **no state of record**
+ * ({@link OnChannelStateSave} returns `null`, the "keep nothing / live-only" posture), so a session
+ * resume never tries to rehydrate it.
+ */
+export declare class ClientContextChannelServer extends BaseRealtimeChannelServer {
+    /** Matches the seeded `MJ: AI Agent Channels` row's `Name`. */
+    get ChannelName(): string;
+    /**
+     * No server-executed tools: the channel's stable `ContextTool` proxy and all surface client tools
+     * execute in the browser via the unified client-tool resolver. Explicit `[]` documents the intent.
+     */
+    GetServerToolDefinitions(): RealtimeToolDefinition[];
+    /**
+     * Live-only channel: it carries no state of record (it is a wire, not a document), so a landed
+     * state save is intentionally not persisted. Returning `null` keeps nothing — a session resume
+     * never rehydrates this channel.
+     *
+     * @returns `null` — never persist.
+     */
+    OnChannelStateSave(): Promise<string | null>;
+}
+/**
+ * Tree-shaking prevention for {@link ClientContextChannelServer}'s `@RegisterClass` registration.
+ * Called from a static code path in the server host so the registration always executes — mirroring
+ * every other `Load...()` in the realtime stack.
+ */
+export declare function LoadClientContextChannelServer(): void;
+//# sourceMappingURL=client-context-channel-server.d.ts.map

package/dist/realtime/client-context-channel-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-context-channel-server.d.ts","sourceRoot":"","sources":["../../src/realtime/client-context-channel-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAGvF,gFAAgF;AAChF,eAAO,MAAM,2BAA2B,yBAAyB,CAAC;AAElE;;;;;;;;GAQG;AACH,qBACa,0BAA2B,SAAQ,yBAAyB;IACrE,+DAA+D;IAC/D,IAAW,WAAW,IAAI,MAAM,CAE/B;IAED;;;OAGG;IACa,wBAAwB,IAAI,sBAAsB,EAAE;IAIpE;;;;;;OAMG;IACmB,kBAAkB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAGrE;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,IAAI,IAAI,CAErD"}

package/dist/realtime/client-context-channel-server.js

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Server-side channel plugin for the **headless** Client Context channel — the live
+ * wire that streams the user's app context (where they are, what they see, the available client-tool
+ * and agent manifest) to the realtime co-agent, and through which the model's single stable
+ * `ContextTool` proxy drives in-app actions.
+ *
+ * Paired with the browser's `ClientContextChannel` client plugin through the seeded
+ * `MJ: AI Agent Channels` row (`Name: 'ClientContextChannel'`, `IsHeadless: 1`,
+ * `ServerPluginClass: 'ClientContextChannelServer'`, `ClientPluginClass: 'ClientContextChannel'`).
+ *
+ * **Why the server half is intentionally thin.** This channel is *headless* (it never mounts a tab)
+ * and *ephemeral* (it persists no state of record — it is a live wire, not a document like the
+ * whiteboard). In the client-direct topology the work lives in the browser: the client plugin
+ * publishes context deltas via the provider's `SendContextNote` and executes `ContextTool` calls
+ * locally through the unified client-tool resolver (`ResolveClientTools` in
+ * `@memberjunction/ai-core-plus`) with no server round-trip. The server half exists to (a) complete
+ * the channel registry pairing so the channel is discoverable/loadable like every other channel, and
+ * (b) be the home for any *future* server-side context tooling. It contributes no server tools today
+ * and saves no state — both base defaults, made explicit here.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BaseRealtimeChannelServer } from '@memberjunction/ai';
+import { RegisterClass } from '@memberjunction/global';
+/** The stable channel name, matching the seeded `MJ: AI Agent Channels` row. */
+export const CLIENT_CONTEXT_CHANNEL_NAME = 'ClientContextChannel';
+/**
+ * Server half of the headless Client Context channel. One instance per realtime session (created by
+ * `RealtimeChannelServerHost` from the channel registry — never construct directly).
+ *
+ * Contributes **no server tools** ({@link GetServerToolDefinitions} returns `[]`) — the channel's
+ * `ContextTool` and client tools execute client-side — and persists **no state of record**
+ * ({@link OnChannelStateSave} returns `null`, the "keep nothing / live-only" posture), so a session
+ * resume never tries to rehydrate it.
+ */
+let ClientContextChannelServer = class ClientContextChannelServer extends BaseRealtimeChannelServer {
+    /** Matches the seeded `MJ: AI Agent Channels` row's `Name`. */
+    get ChannelName() {
+        return CLIENT_CONTEXT_CHANNEL_NAME;
+    }
+    /**
+     * No server-executed tools: the channel's stable `ContextTool` proxy and all surface client tools
+     * execute in the browser via the unified client-tool resolver. Explicit `[]` documents the intent.
+     */
+    GetServerToolDefinitions() {
+        return [];
+    }
+    /**
+     * Live-only channel: it carries no state of record (it is a wire, not a document), so a landed
+     * state save is intentionally not persisted. Returning `null` keeps nothing — a session resume
+     * never rehydrates this channel.
+     *
+     * @returns `null` — never persist.
+     */
+    async OnChannelStateSave() {
+        return null;
+    }
+};
+ClientContextChannelServer = __decorate([
+    RegisterClass(BaseRealtimeChannelServer, 'ClientContextChannelServer')
+], ClientContextChannelServer);
+export { ClientContextChannelServer };
+/**
+ * Tree-shaking prevention for {@link ClientContextChannelServer}'s `@RegisterClass` registration.
+ * Called from a static code path in the server host so the registration always executes — mirroring
+ * every other `Load...()` in the realtime stack.
+ */
+export function LoadClientContextChannelServer() {
+    // no-op — the import + call create a static reference bundlers cannot eliminate
+}
+//# sourceMappingURL=client-context-channel-server.js.map

package/dist/realtime/client-context-channel-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-context-channel-server.js","sourceRoot":"","sources":["../../src/realtime/client-context-channel-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;;;;;;AAEH,OAAO,EAAE,yBAAyB,EAA0B,MAAM,oBAAoB,CAAC;AACvF,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvD,gFAAgF;AAChF,MAAM,CAAC,MAAM,2BAA2B,GAAG,sBAAsB,CAAC;AAElE;;;;;;;;GAQG;AAEI,IAAM,0BAA0B,GAAhC,MAAM,0BAA2B,SAAQ,yBAAyB;IACrE,+DAA+D;IAC/D,IAAW,WAAW;QAClB,OAAO,2BAA2B,CAAC;IACvC,CAAC;IAED;;;OAGG;IACa,wBAAwB;QACpC,OAAO,EAAE,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACa,KAAK,CAAC,kBAAkB;QACpC,OAAO,IAAI,CAAC;IAChB,CAAC;CACJ,CAAA;AAxBY,0BAA0B;IADtC,aAAa,CAAC,yBAAyB,EAAE,4BAA4B,CAAC;GAC1D,0BAA0B,CAwBtC;;AAED;;;;GAIG;AACH,MAAM,UAAU,8BAA8B;IAC1C,gFAAgF;AACpF,CAAC"}