@memberjunction/server 5.43.0 → 5.45.0

package/src/__tests__/RealtimeClientSessionResolver.test.ts

@@ -2603,3 +2603,72 @@ describe('RealtimeClientSessionResolver.StartRealtimeClientSession — runtime-o
         expect(result.EffectiveConfigJson).toBeUndefined();
     });
 });
+
+describe('RealtimeClientSessionResolver — app awareness (applicationId / appContext / allowedAgents)', () => {
+    it('forwards applicationId + parsed appContext to PrepareClientSession and persists the allowed union', async () => {
+        hasPermissionMock.mockResolvedValue(true);
+        currentProvider = makeProvider(() => makeSessionEntity());
+        const createdSession = makeSessionEntity({ ID: 'session-app', ConversationID: 'conv-1' });
+        createSessionMock.mockResolvedValue(createdSession);
+        prepareClientSessionMock.mockResolvedValue({
+            Success: true,
+            ClientConfig: { Provider: 'openai', Model: 'm', EphemeralToken: 'ek', ExpiresAt: '2099-01-01T00:00:00Z', SessionConfig: {} },
+            // Effective config carries the union-accumulated allowed agents (from the app's RelevantAgents).
+            EffectiveConfig: { realtime: { allowedAgents: [{ agentId: 'skip-1', label: 'Skip' }] } },
+        });
+        const resolver = makeResolver();
+        const appContext = { App: { Name: 'Data Explorer', Description: '' }, ActiveNavItem: { Name: 'Queries' }, OtherNavItems: [], User: { Name: 'A', Roles: [] } };
+
+        await resolver.StartRealtimeClientSession(
+            'target-1', makeCtx(),
+            undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined,
+            'app-9', JSON.stringify(appContext),
+        );
+
+        // App context reached the prepare service.
+        const prepArg = prepareClientSessionMock.mock.calls[0][0] as { ApplicationID?: string; AppContext?: { App?: { Name?: string } } };
+        expect(prepArg.ApplicationID).toBe('app-9');
+        expect(prepArg.AppContext?.App?.Name).toBe('Data Explorer');
+
+        // The allowed union + applicationID were persisted onto the session config for relayed-call validation.
+        const persisted = JSON.parse(createdSession.Config_ as string) as { applicationID?: string; allowedAgents?: Array<{ agentId: string }> };
+        expect(persisted.applicationID).toBe('app-9');
+        expect(persisted.allowedAgents?.map(a => a.agentId)).toEqual(['skip-1']);
+    });
+
+    it('tolerates a malformed appContextJson (no app context, never fails the start)', async () => {
+        hasPermissionMock.mockResolvedValue(true);
+        currentProvider = makeProvider(() => makeSessionEntity());
+        createSessionMock.mockResolvedValue(makeSessionEntity({ ID: 'session-bad' }));
+        prepareClientSessionMock.mockResolvedValue({
+            Success: true, ClientConfig: { Provider: 'o', Model: 'm', EphemeralToken: 'ek', ExpiresAt: '2099-01-01T00:00:00Z', SessionConfig: {} },
+        });
+        const resolver = makeResolver();
+
+        await resolver.StartRealtimeClientSession(
+            'target-1', makeCtx(),
+            undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined,
+            'app-9', 'not-json',
+        );
+        const prepArg = prepareClientSessionMock.mock.calls[0][0] as { ApplicationID?: string; AppContext?: unknown };
+        expect(prepArg.ApplicationID).toBe('app-9');
+        expect(prepArg.AppContext).toBeUndefined();
+    });
+
+    it('passes the persisted allowedAgents from the session config into ExecuteRelayedTool', async () => {
+        currentProvider = makeProvider(() =>
+            makeSessionEntity({
+                Config_: JSON.stringify({ targetAgentID: 'lead-1', allowedAgents: [{ agentId: 'skip-1', label: 'Skip' }] }),
+            }),
+        );
+        executeRelayedToolMock.mockResolvedValue({ ResultJson: '{"ok":true}', Success: true });
+        const resolver = makeResolver();
+
+        await resolver.ExecuteRealtimeSessionTool(
+            'session-1', 'call-1', 'invoke-target-agent', '{"agent":"Skip","request":"x"}', makeCtx(), makePubSub(),
+        );
+
+        const relayArg = executeRelayedToolMock.mock.calls[0][0] as { AllowedAgents?: Array<{ agentId: string }> };
+        expect(relayArg.AllowedAgents?.map(a => a.agentId)).toEqual(['skip-1']);
+    });
+});

package/src/__tests__/RealtimeCoAgentAppAwareness.integration.test.ts

@@ -0,0 +1,191 @@
+/**
+ * @fileoverview HEADLESS INTEGRATION test — the Realtime Co-Agent "app awareness" stack composed
+ * end-to-end across packages: the app config cascade (`@memberjunction/ai-agents`
+ * realtime-coagent-config), the `AppContextSnapshot` mint-time injection
+ * (`@memberjunction/ai-core-plus`), the colleagues framing, and the multi-target delegation routing
+ * — all driven through the REAL {@link RealtimeClientSessionService} (only DB/SDK seams stubbed).
+ *
+ * This is the integration counterpart to the per-package unit tests: it proves the Move 1/3/4 layers
+ * actually compose (an app's AgentSettings → cascade → effective config → system prompt + allowed
+ * union → delegation), with no provider socket and no DB. Voice itself is not exercised (that is the
+ * live-verification step), but everything up to "what the model is told and which agent a delegation
+ * runs" is.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import {
+    BaseRealtimeModel,
+    ClientRealtimeSessionConfig,
+    IRealtimeSession,
+    RealtimeSessionParams,
+} from '@memberjunction/ai';
+import { UserInfo, IMetadataProvider } from '@memberjunction/core';
+import { MJAIAgentEntityExtended, AppContextSnapshot, ExecuteAgentResult } from '@memberjunction/ai-core-plus';
+import {
+    RealtimeClientSessionService,
+    PrepareClientSessionInput,
+    ExecuteRelayedToolInput,
+    RealtimeModelResolution,
+    CoAgentSystemPromptResolution,
+} from '@memberjunction/ai-agents';
+import {
+    BuildAppRealtimeOverridesJson,
+    INVOKE_TARGET_AGENT_TOOL_NAME,
+    DelegateToTargetRequest,
+} from '@memberjunction/ai-agents';
+
+class StubSession implements IRealtimeSession {
+    SendInput(): void {}
+    async RegisterTools(): Promise<void> {}
+    OnOutput(): void {}
+    OnTranscript(): void {}
+    OnToolCall(): void {}
+    async SendToolResult(): Promise<void> {}
+    OnInterruption(): void {}
+    OnUsage(): void {}
+    OnError(): void {}
+    async Close(): Promise<void> {}
+}
+
+class StubModel extends BaseRealtimeModel {
+    constructor() { super('k'); }
+    public override get SupportsClientDirect(): boolean { return true; }
+    async StartSession(): Promise<IRealtimeSession> { return new StubSession(); }
+    public override async CreateClientSession(params: RealtimeSessionParams): Promise<ClientRealtimeSessionConfig> {
+        return {
+            Provider: 'stub', Model: params.Model, EphemeralToken: 't', ExpiresAt: '2099-01-01T00:00:00Z',
+            SessionConfig: { instructions: params.SystemPrompt },
+        };
+    }
+}
+
+/** Real service with only the DB/SDK seams stubbed; cascade + prompt + delegation routing stay REAL. */
+class IntegrationService extends RealtimeClientSessionService {
+    private model = new StubModel();
+    public AppOverridesJson: string | null = null;
+    /** Captures which agent a delegation actually ran (the routing outcome under test). */
+    public RanAgent: MJAIAgentEntityExtended | null = null;
+    public TargetNames: Record<string, string> = { 'lead-1': 'Sage' };
+
+    protected override async configureEngine(): Promise<void> {}
+    protected override async resolveRealtimeModel(): Promise<RealtimeModelResolution | null> {
+        return { Model: this.model, ModelID: 'm', VendorID: 'v', APIName: 'stub-realtime' };
+    }
+    protected override getCoAgentSystemPromptText(): string { return 'CO-AGENT BODY'; }
+    protected override resolveCoAgentSystemPrompt(): CoAgentSystemPromptResolution {
+        return { Text: 'CO-AGENT BODY', PromptID: 'p1' };
+    }
+    protected override async createCoAgentObservabilityRun(): Promise<{ CoAgentRunID: string } | null> {
+        return { CoAgentRunID: 'run-1' };
+    }
+    protected override resolveTargetAgent(id: string): MJAIAgentEntityExtended | null {
+        if (!id) return null;
+        const name = this.TargetNames[id] ?? id;
+        return { ID: id, Name: name, Description: `${name} agent.` } as unknown as MJAIAgentEntityExtended;
+    }
+    protected override async resolveAppRealtimeOverrides(): Promise<string | null> { return this.AppOverridesJson; }
+    // Capture the routed target without running a real agent.
+    protected override async runDelegatedAgent(
+        _input: ExecuteRelayedToolInput,
+        _request: DelegateToTargetRequest,
+        target: MJAIAgentEntityExtended,
+    ): Promise<ExecuteAgentResult> {
+        this.RanAgent = target;
+        return { success: true, payload: null, agentRun: { Status: 'Completed' } } as unknown as ExecuteAgentResult;
+    }
+    protected override async createDelegatedRunArtifacts(): Promise<undefined> { return undefined; }
+}
+
+const user = { ID: 'u1' } as unknown as UserInfo;
+const provider = {} as unknown as IMetadataProvider;
+
+function coAgent(): MJAIAgentEntityExtended {
+    return { ID: 'co-1', Name: 'Realtime Co-Agent', InjectNotes: false, InjectExamples: false } as unknown as MJAIAgentEntityExtended;
+}
+function input(over: Partial<PrepareClientSessionInput> = {}): PrepareClientSessionInput {
+    return { CoAgent: coAgent(), TargetAgentID: 'lead-1', AgentSessionID: 's1', ConversationMessages: [], ...over };
+}
+
+describe('Realtime Co-Agent app awareness — integration', () => {
+    it('composes app AgentSettings → cascade → prompt (app-context + colleagues) + allowed union', async () => {
+        const svc = new IntegrationService();
+        svc.TargetNames = { 'lead-1': 'Sage', 'skip-1': 'Skip' };
+        svc.AppOverridesJson = BuildAppRealtimeOverridesJson(
+            { Disclosure: 'mention', Persona: { Tone: 'warm', SpeakingStyle: 'concise' } },
+            [{ agentId: 'skip-1', label: 'Skip', disclosure: 'silent' }],
+        );
+        const appContext: AppContextSnapshot = {
+            App: { Name: 'Knowledge Hub', Description: '' },
+            ActiveNavItem: { Name: 'Analytics' },
+            OtherNavItems: [],
+            User: { Name: 'Amith', Roles: [] },
+            View: { FreeText: 'looking at the cluster chart' },
+            Capabilities: { Agents: [{ AgentID: 'skip-1', Name: 'Skip' }] },
+        };
+
+        const result = await svc.PrepareClientSession(input({ AppContext: appContext }), user, provider);
+        expect(result.Success).toBe(true);
+
+        const prompt = result.SessionParams!.SystemPrompt;
+        // Identity (lead) + colleague (from app RelevantAgents) + per-target disclosure guidance.
+        expect(prompt).toContain('voice for the agent "Sage"');
+        expect(prompt).toContain('Your colleagues:');
+        expect(prompt).toContain('"Skip"');
+        expect(prompt).toContain('speak their result as your own'); // Skip's silent disclosure
+        // Persona (app override) folded in.
+        expect(prompt).toContain('Voice & manner');
+        // App-context snapshot injected at mint.
+        expect(prompt).toContain('CURRENT APP CONTEXT');
+        expect(prompt).toContain('Knowledge Hub');
+
+        // Effective config carries the union-accumulated allowed agents (surfaced to the resolver to persist).
+        expect(result.EffectiveConfig?.realtime?.allowedAgents?.map(a => a.agentId)).toContain('skip-1');
+        expect(result.EffectiveConfig?.realtime?.disclosure).toBe('mention');
+    });
+
+    it('routes a relayed invoke-target-agent call to a named colleague in the allowed union', async () => {
+        const svc = new IntegrationService();
+        svc.TargetNames = { 'lead-1': 'Sage', 'skip-1': 'Skip' };
+        const relay: ExecuteRelayedToolInput = {
+            AgentSessionID: 's1',
+            TargetAgentID: 'lead-1',
+            AllowedAgents: [{ agentId: 'skip-1', label: 'Skip' }],
+            Call: {
+                CallID: 'c1',
+                ToolName: INVOKE_TARGET_AGENT_TOOL_NAME,
+                Arguments: JSON.stringify({ agent: 'Skip', request: 'analyze this' }),
+            },
+        };
+        const out = await svc.ExecuteRelayedTool(relay, user, provider);
+        expect(JSON.parse(out.ResultJson).success).toBe(true);
+        expect(svc.RanAgent?.ID).toBe('skip-1'); // routed to the named colleague, not the lead
+    });
+
+    it('routes to the lead when no colleague is named', async () => {
+        const svc = new IntegrationService();
+        const relay: ExecuteRelayedToolInput = {
+            AgentSessionID: 's1',
+            TargetAgentID: 'lead-1',
+            AllowedAgents: [{ agentId: 'skip-1', label: 'Skip' }],
+            Call: { CallID: 'c1', ToolName: INVOKE_TARGET_AGENT_TOOL_NAME, Arguments: JSON.stringify({ request: 'do it' }) },
+        };
+        await svc.ExecuteRelayedTool(relay, user, provider);
+        expect(svc.RanAgent?.ID).toBe('lead-1');
+    });
+
+    it('returns a structured not-available error for an unknown colleague', async () => {
+        const svc = new IntegrationService();
+        const relay: ExecuteRelayedToolInput = {
+            AgentSessionID: 's1',
+            TargetAgentID: 'lead-1',
+            AllowedAgents: [{ agentId: 'skip-1', label: 'Skip' }],
+            Call: { CallID: 'c1', ToolName: INVOKE_TARGET_AGENT_TOOL_NAME, Arguments: JSON.stringify({ agent: 'Ghost', request: 'x' }) },
+        };
+        const out = await svc.ExecuteRelayedTool(relay, user, provider);
+        const parsed = JSON.parse(out.ResultJson);
+        expect(parsed.success).toBe(false);
+        // A not-available colleague is a structured delegation outcome ({success:false, output}),
+        // not a thrown error — the model narrates `output` to self-correct.
+        expect(parsed.output).toContain('Ghost');
+        expect(svc.RanAgent).toBeNull(); // nothing ran
+    });
+});

package/src/__tests__/RemoteBrowserSnapshot.test.ts

@@ -0,0 +1,123 @@
+// type-graphql decorators on the resolver call `Reflect.getMetadata`, which only exists when this
+// polyfill is loaded first. MUST precede any import that pulls in the resolver file.
+import 'reflect-metadata';
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// type-graphql's `@Field()`/`@ObjectType()`/`@Query()` decorators need `emitDecoratorMetadata`
+// reflection (a build-time tsc feature) that vitest's esbuild transform does NOT apply, so importing the
+// decorated resolver throws "Unable to infer GraphQL type". This unit test exercises the resolver's plain
+// TS logic (the snapshot best-effort contract), not its GraphQL schema — so we replace the decorators with
+// no-ops. (The real schema is validated by the build + integration tests.)
+vi.mock('type-graphql', () => {
+  const noopDecorator = () => () => undefined;
+  return {
+    Resolver: noopDecorator,
+    Mutation: noopDecorator,
+    Query: noopDecorator,
+    Subscription: noopDecorator,
+    ObjectType: noopDecorator,
+    InputType: noopDecorator,
+    Field: noopDecorator,
+    Arg: noopDecorator,
+    Args: noopDecorator,
+    Ctx: noopDecorator,
+    PubSub: noopDecorator,
+    Root: noopDecorator,
+    Float: class {},
+    Int: class {},
+    ID: class {},
+  };
+});
+
+// --- Mock the live-session engine the resolver reads. A single mutable session object lets each test
+//     script what CaptureScreenshot does (resolve a frame / throw "Browser not launched"). ---
+interface FakeLiveSession {
+  CaptureScreenshot: ReturnType<typeof vi.fn>;
+  GetCurrentUrl: ReturnType<typeof vi.fn>;
+}
+const liveSession: FakeLiveSession = {
+  CaptureScreenshot: vi.fn(async () => 'QUJD'),
+  GetCurrentUrl: vi.fn(() => 'https://www.wikipedia.org/'),
+};
+// The snapshot path is a pure READ: it looks up an existing session via GetSessionForAgentSession and never
+// lazily starts one. `undefined` models "no live browser for this agent session".
+const getSessionMock = vi.fn<[], FakeLiveSession | undefined>(() => liveSession);
+vi.mock('@memberjunction/remote-browser-server', () => ({
+  RemoteBrowserEngine: {
+    Instance: {
+      GetSessionForAgentSession: (...args: unknown[]) => getSessionMock(...(args as [])),
+    },
+  },
+}));
+
+// Keep the AI imports (visual interpreter) inert — they aren't exercised by the snapshot path.
+vi.mock('@memberjunction/aiengine', () => ({ AIEngine: { Instance: { Config: vi.fn(), Prompts: [] } } }));
+vi.mock('@memberjunction/ai-prompts', () => ({ AIPromptRunner: class {} }));
+// Spread the real module so transitively-loaded code still resolves with its REAL base classes; only
+// AIPromptParams is overridden for the test.
+vi.mock('@memberjunction/ai-core-plus', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@memberjunction/ai-core-plus')>()),
+  AIPromptParams: class {},
+}));
+
+import { RemoteBrowserActionResolver } from '../resolvers/RemoteBrowserActionResolver.js';
+
+/**
+ * A test subclass that bypasses the ownership/provider plumbing (covered elsewhere) so the snapshot
+ * best-effort contract is exercised in isolation.
+ */
+class TestableResolver extends RemoteBrowserActionResolver {
+  protected requireUserAndProvider() {
+    return { contextUser: { ID: 'user-1' }, provider: {} } as never;
+  }
+  protected async loadOwnedSession() {
+    return { ID: 'sess-1', AgentID: 'agent-1', UserID: 'user-1' } as never;
+  }
+}
+
+const ctx = { userPayload: { sessionId: 'push-sess-1' }, providers: {} } as never;
+
+describe('RemoteBrowserActionResolver — snapshot (best-effort perception poll)', () => {
+  let resolver: TestableResolver;
+
+  beforeEach(() => {
+    resolver = new TestableResolver();
+    liveSession.CaptureScreenshot.mockReset().mockResolvedValue('QUJD');
+    liveSession.GetCurrentUrl.mockReset().mockReturnValue('https://www.wikipedia.org/');
+    getSessionMock.mockReset().mockReturnValue(liveSession);
+  });
+
+  it('returns the screenshot + URL when the browser is live', async () => {
+    const result = await resolver.RemoteBrowserSnapshot('sess-1', ctx);
+    expect(result).toEqual({ ScreenshotBase64: 'QUJD', CurrentUrl: 'https://www.wikipedia.org/' });
+    expect(liveSession.CaptureScreenshot).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns an empty snapshot when no live browser exists (never started / already torn down)', async () => {
+    getSessionMock.mockReturnValue(undefined);
+    const result = await resolver.RemoteBrowserSnapshot('sess-1', ctx);
+    expect(result).toEqual({});
+    expect(liveSession.CaptureScreenshot).not.toHaveBeenCalled();
+  });
+
+  // The regression the fix targets: a session handle survives in the live map but its underlying browser
+  // adapter has been torn down, so CaptureScreenshot throws "Browser not launched". The ~700ms client poll
+  // must NOT surface that as a recurring GraphQL error — the query's documented contract is empty fields,
+  // not an error. So the resolver catches and degrades to {} (the surface keeps its last good frame).
+  it('degrades to an empty snapshot — does NOT throw — when the adapter is torn down', async () => {
+    liveSession.CaptureScreenshot.mockRejectedValueOnce(
+      new Error('Browser not launched. Call Launch() before using the adapter.'),
+    );
+    const result = await resolver.RemoteBrowserSnapshot('sess-1', ctx);
+    expect(result).toEqual({});
+    expect(liveSession.CaptureScreenshot).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not read the URL when the capture fails (no half-populated snapshot)', async () => {
+    liveSession.CaptureScreenshot.mockRejectedValueOnce(new Error('Target page, context or browser has been closed'));
+    const result = await resolver.RemoteBrowserSnapshot('sess-1', ctx);
+    expect(result).toEqual({});
+    expect(liveSession.GetCurrentUrl).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/SessionManager.test.ts

@@ -397,6 +397,8 @@ describe('SessionManager — server-side channel plugin lifecycle notifications'
             AgentID: 'agent-1',
             UserID: 'user-1',
             ConversationID: 'conv-existing',
+            // Verbatim per-session config blob handed to data-aware channels; null when unset.
+            AgentSessionConfig: null,
         });
         expect((user as { ID: string }).ID).toBe('user-1');
         expect(prov).toBe(provider);

package/src/__tests__/meetingRecordingRegistration.test.ts

@@ -0,0 +1,248 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
+
+// ── Mocks ──────────────────────────────────────────────────────────────────
+// The helper uses `RunView.FromMetadataProvider(provider).RunView(...)` for conversation lookups and
+// `FileStorageEngine.Instance` for storage-account/driver/upload. We stub both so the test is pure
+// (no DB, no network, no LiveKit/storage SDK).
+
+const runViewMock = vi.fn();
+
+vi.mock('@memberjunction/core', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>();
+  class RunView {
+    static FromMetadataProvider() {
+      return { RunView: runViewMock };
+    }
+    RunView = runViewMock;
+  }
+  return { ...actual, RunView, LogError: vi.fn(), LogStatus: vi.fn() };
+});
+
+// FileStorageEngine — a configurable fake. Tests reset its behavior in beforeEach.
+const storage = {
+  accountsByProvider: new Map<string, Array<{ ID: string }>>(),
+  getObject: vi.fn(async () => Buffer.from('mp4-bytes')),
+  uploadFile: vi.fn(async () => ({ FileID: 'copied-file', StoragePath: 'meeting-recordings/2026/x.mp4' })),
+};
+
+vi.mock('@memberjunction/storage', () => ({
+  FileStorageEngine: {
+    Instance: {
+      Config: vi.fn(async () => undefined),
+      GetAccountsByProviderID: (id: string) => storage.accountsByProvider.get(id) ?? [],
+      GetDriver: vi.fn(async () => ({ GetObject: storage.getObject })),
+      UploadFile: (...args: unknown[]) => storage.uploadFile(...args),
+    },
+  },
+}));
+
+vi.mock('@memberjunction/core-entities', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>();
+  return { ...actual };
+});
+
+import {
+  registerMeetingRecordingFile,
+  resolveMeetingConversation,
+  type MeetingRecordingEgressResult,
+} from '../resolvers/meetingRecordingRegistration';
+
+// ── Fakes ──────────────────────────────────────────────────────────────────
+
+const user = { ID: 'U1', Name: 'Amith', Email: 'amith@x.com' } as unknown as UserInfo;
+
+/** A fake BaseEntity for Conversations / Files — records the values set on it. */
+class FakeEntity {
+  public fields: Record<string, unknown> = {};
+  public ID = 'new-id';
+  public saved = false;
+  public loadedID: string | null = null;
+  constructor(public kind: 'conversation' | 'file', private saveResult = true) {}
+  NewRecord() {}
+  async Load(id: string) { this.loadedID = id; return true; }
+  async Save() { this.saved = this.saveResult; return this.saveResult; }
+  get LatestResult() { return { CompleteMessage: 'save failed' }; }
+  // Conversation fields
+  set UserID(v: string) { this.fields.UserID = v; }
+  set Name(v: string) { this.fields.Name = v; }
+  set Type(v: string) { this.fields.Type = v; }
+  set ExternalID(v: string) { this.fields.ExternalID = v; }
+  set ApplicationScope(v: string) { this.fields.ApplicationScope = v; }
+  set RecordingFileID(v: string) { this.fields.RecordingFileID = v; }
+  get RecordingFileID() { return this.fields.RecordingFileID as string; }
+  set EgressID(v: string) { this.fields.EgressID = v; }
+  get EgressID() { return this.fields.EgressID as string; }
+  // File fields
+  set ContentType(v: string) { this.fields.ContentType = v; }
+  set ProviderID(v: string) { this.fields.ProviderID = v; }
+  set ProviderKey(v: string) { this.fields.ProviderKey = v; }
+  set Status(v: string) { this.fields.Status = v; }
+}
+
+/** Builds a provider whose GetEntityObject hands back fresh fakes and records the created Files row. */
+function makeProvider(opts: { fileSaveOk?: boolean } = {}) {
+  const created: { conversation: FakeEntity[]; file: FakeEntity[] } = { conversation: [], file: [] };
+  const provider = {
+    GetEntityObject: vi.fn(async (entityName: string) => {
+      if (entityName === 'MJ: Files') {
+        const f = new FakeEntity('file', opts.fileSaveOk ?? true);
+        f.ID = 'file-123';
+        created.file.push(f);
+        return f;
+      }
+      const c = new FakeEntity('conversation');
+      c.ID = 'conv-new';
+      created.conversation.push(c);
+      return c;
+    }),
+  } as unknown as IMetadataProvider;
+  return { provider, created };
+}
+
+const egress: MeetingRecordingEgressResult = {
+  EgressID: 'eg-1',
+  RoomName: 'room-1',
+  OutputLocation: 'room-1/2026.mp4',
+  OutputSizeBytes: 1234,
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  vi.unstubAllEnvs();
+  runViewMock.mockResolvedValue({ Success: true, Results: [] });
+  storage.accountsByProvider = new Map([['prov-sink', [{ ID: 'acct-sink' }]]]);
+  process.env.MJ_MEETING_RECORDING_STORAGE_PROVIDER = 'prov-sink';
+  delete process.env.MJ_MEETING_RECORDING_CANONICAL_STORAGE_PROVIDER;
+});
+
+describe('registerMeetingRecordingFile', () => {
+  it('resolves the conversation, creates the Files row pointing at the sink, and stamps the Conversation', async () => {
+    // First RunView (by EgressID) → no match; second (by RoomName) → an existing conversation.
+    runViewMock
+      .mockResolvedValueOnce({ Success: true, Results: [] })
+      .mockResolvedValueOnce({ Success: true, Results: [{ ID: 'conv-existing' }] });
+
+    const { provider, created } = makeProvider();
+    const result = await registerMeetingRecordingFile(egress, user, provider);
+
+    expect(result.Success).toBe(true);
+    expect(result.RecordingFileID).toBe('file-123');
+    expect(result.ConversationID).toBe('conv-existing');
+
+    // Files row: correct provider/key/content-type/status, pointing directly at the egress output.
+    const file = created.file[0];
+    expect(file.fields.ProviderID).toBe('prov-sink');
+    expect(file.fields.ProviderKey).toBe('room-1/2026.mp4');
+    expect(file.fields.ContentType).toBe('video/mp4');
+    expect(file.fields.Status).toBe('Uploaded');
+    expect(file.saved).toBe(true);
+
+    // Conversation stamped with the file id (loaded by id, then saved).
+    const conv = created.conversation[0];
+    expect(conv.loadedID).toBe('conv-existing');
+    expect(conv.fields.RecordingFileID).toBe('file-123');
+    expect(conv.fields.EgressID).toBe('eg-1');
+    expect(conv.saved).toBe(true);
+
+    // No byte copy in the default v1 path.
+    expect(storage.getObject).not.toHaveBeenCalled();
+    expect(storage.uploadFile).not.toHaveBeenCalled();
+  });
+
+  it('prefers matching the conversation by EgressID when present', async () => {
+    runViewMock.mockResolvedValueOnce({ Success: true, Results: [{ ID: 'conv-by-egress' }] });
+    const { provider } = makeProvider();
+    const result = await registerMeetingRecordingFile(egress, user, provider);
+    expect(result.ConversationID).toBe('conv-by-egress');
+    // Only the EgressID lookup ran (no fall-through to room-name lookup).
+    expect(runViewMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('creates a Meeting-Room Conversation when none exists', async () => {
+    runViewMock.mockResolvedValue({ Success: true, Results: [] }); // neither lookup matches
+    const { provider, created } = makeProvider();
+    const result = await registerMeetingRecordingFile(egress, user, provider);
+    expect(result.Success).toBe(true);
+    const conv = created.conversation[0];
+    expect(conv.fields.Type).toBe('Meeting Room');
+    expect(conv.fields.ExternalID).toBe('room-1');
+    expect(conv.fields.ApplicationScope).toBe('Application');
+  });
+
+  it('returns a graceful failure when the storage provider is not configured', async () => {
+    delete process.env.MJ_MEETING_RECORDING_STORAGE_PROVIDER;
+    const { provider } = makeProvider();
+    const result = await registerMeetingRecordingFile(egress, user, provider);
+    expect(result.Success).toBe(false);
+    expect(result.ErrorMessage).toMatch(/MJ_MEETING_RECORDING_STORAGE_PROVIDER/);
+    expect(result.RecordingFileID).toBeUndefined();
+  });
+
+  it('returns a graceful failure when no account is linked to the configured provider', async () => {
+    storage.accountsByProvider = new Map(); // no accounts for prov-sink
+    const { provider } = makeProvider();
+    const result = await registerMeetingRecordingFile(egress, user, provider);
+    expect(result.Success).toBe(false);
+    expect(result.ErrorMessage).toMatch(/No active MJStorage account/i);
+  });
+
+  it('returns a graceful failure when the egress has no output yet', async () => {
+    const { provider } = makeProvider();
+    const result = await registerMeetingRecordingFile({ ...egress, OutputLocation: undefined }, user, provider);
+    expect(result.Success).toBe(false);
+    expect(result.ErrorMessage).toMatch(/no output/i);
+  });
+
+  describe('copy-to-canonical (the "copy into Box" option)', () => {
+    it('copies the MP4 into a differing canonical provider and points the Files row there', async () => {
+      storage.accountsByProvider = new Map([
+        ['prov-sink', [{ ID: 'acct-sink' }]],
+        ['prov-canonical', [{ ID: 'acct-canonical' }]],
+      ]);
+      process.env.MJ_MEETING_RECORDING_CANONICAL_STORAGE_PROVIDER = 'prov-canonical';
+      runViewMock.mockResolvedValueOnce({ Success: true, Results: [{ ID: 'conv-1' }] });
+
+      const { provider, created } = makeProvider();
+      const result = await registerMeetingRecordingFile(egress, user, provider);
+
+      expect(result.Success).toBe(true);
+      // Bytes were read from the sink and uploaded into the canonical provider.
+      expect(storage.getObject).toHaveBeenCalledWith({ fullPath: 'room-1/2026.mp4' });
+      expect(storage.uploadFile).toHaveBeenCalledOnce();
+
+      // The Files row points at the canonical provider + its uploaded key.
+      const file = created.file[0];
+      expect(file.fields.ProviderID).toBe('prov-canonical');
+      expect(file.fields.ProviderKey).toBe('meeting-recordings/2026/x.mp4');
+    });
+
+    it('does NOT copy when the canonical provider equals the sink provider', async () => {
+      process.env.MJ_MEETING_RECORDING_CANONICAL_STORAGE_PROVIDER = 'prov-sink'; // same as sink
+      runViewMock.mockResolvedValueOnce({ Success: true, Results: [{ ID: 'conv-1' }] });
+      const { provider, created } = makeProvider();
+      const result = await registerMeetingRecordingFile(egress, user, provider);
+      expect(result.Success).toBe(true);
+      expect(storage.getObject).not.toHaveBeenCalled();
+      expect(created.file[0].fields.ProviderID).toBe('prov-sink');
+    });
+  });
+
+  it('fails gracefully (no throw) when the Files row save fails', async () => {
+    runViewMock.mockResolvedValueOnce({ Success: true, Results: [{ ID: 'conv-1' }] });
+    const { provider } = makeProvider({ fileSaveOk: false });
+    const result = await registerMeetingRecordingFile(egress, user, provider);
+    expect(result.Success).toBe(false);
+    expect(result.ErrorMessage).toMatch(/Files row/i);
+  });
+});
+
+describe('resolveMeetingConversation', () => {
+  it('falls back to creating a conversation when neither lookup matches', async () => {
+    runViewMock.mockResolvedValue({ Success: true, Results: [] });
+    const { provider, created } = makeProvider();
+    const id = await resolveMeetingConversation(egress, user, provider);
+    expect(id).toBe('conv-new');
+    expect(created.conversation).toHaveLength(1);
+  });
+});