@memberjunction/server 6.2.0-edge.3 → 6.2.0-edge.4

package/src/__tests__/FetchEntityVectorsResolver.test.ts

@@ -0,0 +1,285 @@
+import 'reflect-metadata';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { UserInfo, type DatabaseProviderBase, type EntityInfo, type RunViewParams } from '@memberjunction/core';
+import { MJGlobal } from '@memberjunction/global';
+import type { VectorDBBase } from '@memberjunction/ai-vectordb';
+
+type ViewResult = { Success: boolean; Results: unknown[]; ErrorMessage?: string };
+type RunViewHandler = (params: RunViewParams, contextUser: UserInfo | undefined) => ViewResult;
+
+// Vitest's transform emits no decorator metadata, so type-graphql can't infer field types —
+// stub the decorators; these tests exercise the resolver method, not the schema.
+vi.mock('type-graphql', () => {
+    const decoratorFactory = (..._args: unknown[]) => (..._decorated: unknown[]) => undefined;
+    const exportNames = [
+        'Resolver', 'Query', 'Mutation', 'Subscription', 'Arg', 'Args', 'ArgsType', 'Ctx', 'Root',
+        'Info', 'Field', 'FieldResolver', 'ObjectType', 'InputType', 'InterfaceType', 'Authorized',
+        'UseMiddleware', 'Extensions', 'Directive', 'ID', 'Int', 'Float', 'GraphQLISODateTime',
+        'GraphQLTimestamp', 'registerEnumType', 'createMethodDecorator', 'createParamDecorator',
+        'buildSchema', 'buildSchemaSync', 'PubSub',
+    ];
+    return Object.fromEntries(exportNames.map((name) => [name, decoratorFactory]));
+});
+
+const runViewCalls: Array<{ params: RunViewParams; contextUser: UserInfo | undefined }> = [];
+let runViewHandler: RunViewHandler = () => ({ Success: true, Results: [] });
+
+vi.mock('@memberjunction/core', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@memberjunction/core')>();
+    class MockRunView {
+        async RunView(params: RunViewParams, contextUser?: UserInfo): Promise<ViewResult> {
+            runViewCalls.push({ params, contextUser });
+            return runViewHandler(params, contextUser);
+        }
+    }
+    return { ...actual, RunView: MockRunView, LogStatus: () => undefined, LogError: () => undefined };
+});
+
+// GetAIAPIKey resolves through the ClassFactory too; keep it off the CreateInstance spy below.
+vi.mock('@memberjunction/ai', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@memberjunction/ai')>();
+    return { ...actual, GetAIAPIKey: () => 'test-key' };
+});
+
+vi.mock('@memberjunction/aiengine', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@memberjunction/aiengine')>();
+    return { ...actual, AIEngine: { Instance: { GetProviderIndexName: () => 'provider-index-name' } } };
+});
+
+import { FetchEntityVectorsResolver } from '../resolvers/FetchEntityVectorsResolver.js';
+import type { AppContext } from '../types.js';
+
+/* ───── fixtures ───── */
+
+const DOC_ID = 'DOC-1';
+const contextUser = new UserInfo();
+
+const membersEntity = {
+    Name: 'Members',
+    PrimaryKeys: [{ Name: 'ID' }],
+    Fields: [
+        { Name: 'ID', IsNameField: false },
+        { Name: 'FirstName', IsNameField: true },
+        { Name: 'LastName', IsNameField: true },
+        { Name: 'Email', IsNameField: false },
+    ],
+    NameField: undefined,
+} as unknown as EntityInfo;
+
+const orderLinesEntity = {
+    Name: 'Order Lines',
+    PrimaryKeys: [{ Name: 'OrderID' }, { Name: 'LineNo' }],
+    Fields: [
+        { Name: 'OrderID', IsNameField: false },
+        { Name: 'LineNo', IsNameField: false },
+        { Name: 'Description', IsNameField: false },
+    ],
+    NameField: { Name: 'Description' },
+} as unknown as EntityInfo;
+
+function fakeVectorDB(queryKeyIsEntityDocumentID: boolean) {
+    const queryIndex = vi.fn().mockResolvedValue({
+        success: true,
+        data: { matches: [{ id: 'pc-1', values: [0.5, 0.5], metadata: { Entity: 'Members', RecordID: 'a' } }] },
+    });
+    const db = { QueryKeyIsEntityDocumentID: queryKeyIsEntityDocumentID, QueryIndex: queryIndex } as unknown as VectorDBBase;
+    return { db, queryIndex };
+}
+
+function appContext(entityInfo: EntityInfo): AppContext {
+    const provider = { EntityByName: (name: string) => (name === entityInfo.Name ? entityInfo : undefined) } as unknown as DatabaseProviderBase;
+    return {
+        userPayload: { email: 'test@example.com', sessionId: 's', userRecord: contextUser },
+        providers: [{ type: 'Read-Only', provider }],
+    } as unknown as AppContext;
+}
+
+/** Route RunView by entity: the doc → index → database lookups, then the case-specific views. */
+function routeViews(entityName: string, views: Record<string, (params: RunViewParams) => ViewResult>): void {
+    runViewHandler = (params) => {
+        switch (params.EntityName) {
+            case 'MJ: Entity Documents':
+                return { Success: true, Results: [{ ID: DOC_ID, Name: 'Doc', Entity: entityName, VectorIndexID: 'VI-1' }] };
+            case 'MJ: Vector Indexes':
+                return { Success: true, Results: [{ ID: 'VI-1', Name: 'Index', VectorDatabaseID: 'VDB-1', Dimensions: 2 }] };
+            case 'MJ: Vector Databases':
+                return { Success: true, Results: [{ ID: 'VDB-1', ClassKey: 'TestVectorDB' }] };
+            default: {
+                const view = views[params.EntityName ?? ''];
+                return view ? view(params) : { Success: false, Results: [], ErrorMessage: `unexpected view ${params.EntityName}` };
+            }
+        }
+    };
+}
+
+const storedRows = [
+    { ID: 'ERD-1', RecordID: 'AAA', VectorJSON: '[0.1,0.2]' },
+    { ID: 'ERD-2', RecordID: 'bbb', VectorJSON: '[0.3,0.4]' },
+    { ID: 'ERD-3', RecordID: 'ccc', VectorJSON: '[0.5,0.6]' },
+];
+const memberRows = [
+    { ID: 'aaa', FirstName: 'Ada', LastName: 'Lovelace' },
+    { ID: 'bbb', FirstName: 'Grace', LastName: 'Hopper' },
+    { ID: 'ccc', FirstName: 'Alan', LastName: null },
+];
+
+function callsFor(entityName: string) {
+    return runViewCalls.filter((c) => c.params.EntityName === entityName);
+}
+
+/* ───── tests ───── */
+
+describe('FetchEntityVectorsResolver', () => {
+    let createInstanceSpy: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+        runViewCalls.length = 0;
+    });
+
+    afterEach(() => {
+        createInstanceSpy?.mockRestore();
+    });
+
+    function useVectorDB(queryKeyIsEntityDocumentID: boolean) {
+        const fake = fakeVectorDB(queryKeyIsEntityDocumentID);
+        createInstanceSpy = vi.spyOn(MJGlobal.Instance.ClassFactory, 'CreateInstance').mockReturnValue(fake.db);
+        return fake;
+    }
+
+    describe('local vector store (QueryKeyIsEntityDocumentID)', () => {
+        it('reads VectorJSON for the document with the context user instead of calling QueryIndex', async () => {
+            const { queryIndex } = useVectorDB(true);
+            routeViews('Members', {
+                'MJ: Entity Record Documents': () => ({ Success: true, Results: storedRows }),
+                Members: () => ({ Success: true, Results: memberRows }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, undefined, appContext(membersEntity));
+
+            expect(result.ErrorMessage).toBeUndefined();
+            expect(result.Success).toBe(true);
+            expect(queryIndex).not.toHaveBeenCalled();
+            expect(result.TotalCount).toBe(3);
+            expect(result.Results.map((r) => r.ID)).toEqual(['ERD-1', 'ERD-2', 'ERD-3']);
+            expect(result.Results.map((r) => r.Values)).toEqual([[0.1, 0.2], [0.3, 0.4], [0.5, 0.6]]);
+
+            const [erdCall] = callsFor('MJ: Entity Record Documents');
+            expect(erdCall.contextUser).toBe(contextUser);
+            expect(erdCall.params.ExtraFilter).toBe(`EntityDocumentID='${DOC_ID}' AND VectorJSON IS NOT NULL`);
+            expect(erdCall.params.Fields).toEqual(['ID', 'RecordID', 'VectorJSON']);
+            expect(erdCall.params.ResultType).toBe('simple');
+            expect(erdCall.params.IgnoreMaxRows).toBe(true);
+        });
+
+        it('labels each item with Entity, RecordID and the record name fields (RecordID matched case-insensitively)', async () => {
+            useVectorDB(true);
+            routeViews('Members', {
+                'MJ: Entity Record Documents': () => ({ Success: true, Results: storedRows }),
+                Members: () => ({ Success: true, Results: memberRows }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, undefined, appContext(membersEntity));
+
+            expect(result.Results.map((r) => JSON.parse(r.Metadata))).toEqual([
+                { Entity: 'Members', RecordID: 'AAA', FirstName: 'Ada', LastName: 'Lovelace' },
+                { Entity: 'Members', RecordID: 'bbb', FirstName: 'Grace', LastName: 'Hopper' },
+                { Entity: 'Members', RecordID: 'ccc', FirstName: 'Alan' },
+            ]);
+            const [membersCall] = callsFor('Members');
+            expect(membersCall.contextUser).toBe(contextUser);
+            expect(membersCall.params.Fields).toEqual(['ID', 'FirstName', 'LastName']);
+            expect(membersCall.params.ResultType).toBe('simple');
+            expect(membersCall.params.ExtraFilter).toBeUndefined();
+        });
+
+        it('honours the filter: passes it to the entity view and drops vectors whose record did not pass', async () => {
+            useVectorDB(true);
+            const filter = "LastName = 'Hopper'";
+            routeViews('Members', {
+                'MJ: Entity Record Documents': () => ({ Success: true, Results: storedRows }),
+                Members: (params) => ({
+                    Success: true,
+                    Results: params.ExtraFilter === filter ? memberRows.filter((r) => r.LastName === 'Hopper') : memberRows,
+                }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, filter, appContext(membersEntity));
+
+            expect(result.Success).toBe(true);
+            expect(callsFor('Members')[0].params.ExtraFilter).toBe(filter);
+            expect(result.TotalCount).toBe(1);
+            expect(result.Results[0].ID).toBe('ERD-2');
+            expect(JSON.parse(result.Results[0].Metadata)).toEqual({ Entity: 'Members', RecordID: 'bbb', FirstName: 'Grace', LastName: 'Hopper' });
+        });
+
+        it('stops at maxRecords', async () => {
+            useVectorDB(true);
+            routeViews('Members', {
+                'MJ: Entity Record Documents': () => ({ Success: true, Results: storedRows }),
+                Members: () => ({ Success: true, Results: memberRows }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, 2, undefined, appContext(membersEntity));
+
+            expect(result.Results.map((r) => r.ID)).toEqual(['ERD-1', 'ERD-2']);
+            expect(result.TotalCount).toBe(2);
+        });
+
+        it('matches composite-key records by the compact RecordID segment and falls back to NameField for labels', async () => {
+            useVectorDB(true);
+            routeViews('Order Lines', {
+                'MJ: Entity Record Documents': () => ({
+                    Success: true,
+                    Results: [{ ID: 'ERD-9', RecordID: 'OrderID|o-1||LineNo|2', VectorJSON: '[1,0]' }],
+                }),
+                'Order Lines': () => ({ Success: true, Results: [{ OrderID: 'o-1', LineNo: 2, Description: 'Brie wheel' }] }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, undefined, appContext(orderLinesEntity));
+
+            expect(result.Success).toBe(true);
+            expect(result.Results).toHaveLength(1);
+            expect(JSON.parse(result.Results[0].Metadata)).toEqual({
+                Entity: 'Order Lines',
+                RecordID: 'OrderID|o-1||LineNo|2',
+                Description: 'Brie wheel',
+            });
+            expect(callsFor('Order Lines')[0].params.Fields).toEqual(['OrderID', 'LineNo', 'Description']);
+        });
+
+        it('returns an error result when the entity records cannot be loaded (e.g. an invalid filter)', async () => {
+            useVectorDB(true);
+            routeViews('Members', {
+                'MJ: Entity Record Documents': () => ({ Success: true, Results: storedRows }),
+                Members: () => ({ Success: false, Results: [], ErrorMessage: 'bad filter' }),
+            });
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, undefined, 'nonsense', appContext(membersEntity));
+
+            expect(result.Success).toBe(false);
+            expect(result.Results).toEqual([]);
+            expect(result.ErrorMessage).toBe('Failed to load "Members" records: bad filter');
+        });
+    });
+
+    describe('index-keyed providers (Pinecone path, unchanged)', () => {
+        it('queries the provider index by name and never reads Entity Record Documents', async () => {
+            const { queryIndex } = useVectorDB(false);
+            routeViews('Members', {});
+
+            const result = await new FetchEntityVectorsResolver().FetchEntityVectors(DOC_ID, 50, undefined, appContext(membersEntity));
+
+            expect(result.Success).toBe(true);
+            expect(queryIndex).toHaveBeenCalledTimes(1);
+            const query = queryIndex.mock.calls[0][0];
+            expect(query.id).toBe('provider-index-name');
+            expect(query.topK).toBe(50);
+            expect(query.includeValues).toBe(true);
+            expect(query.filter).toEqual({ Entity: { $eq: 'Members' } });
+            expect(query.vector).toHaveLength(2);
+            expect(result.Results).toEqual([{ ID: 'pc-1', Values: [0.5, 0.5], Metadata: JSON.stringify({ Entity: 'Members', RecordID: 'a' }) }]);
+            expect(callsFor('MJ: Entity Record Documents')).toHaveLength(0);
+            expect(callsFor('Members')).toHaveLength(0);
+        });
+    });
+});

package/src/__tests__/HostInstance.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { hostname } from 'os';
+
+const { logErrorMock } = vi.hoisted(() => ({ logErrorMock: vi.fn() }));
+vi.mock('@memberjunction/core', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@memberjunction/core')>();
+    return { ...actual, LogError: logErrorMock };
+});
+
+import { HostInstanceIdentity } from '../agentSessions/HostInstance.js';
+
+/** A fresh copy of the module: no port set, no identity read yet. */
+async function freshHostInstanceModule(): Promise<typeof import('../agentSessions/HostInstance.js')> {
+    vi.resetModules();
+    return import('../agentSessions/HostInstance.js');
+}
+
+beforeEach(() => {
+    logErrorMock.mockReset();
+});
+
+describe('HostInstanceIdentity', () => {
+    const ours = new HostInstanceIdentity('build-01', '4000', 101, 'boot-ours');
+
+    it('stamps hostname:port:pid:bootId, and every boot of the instance shares hostname:port:', () => {
+        expect(ours.GetHostInstanceID()).toBe('build-01:4000:101:boot-ours');
+        expect(ours.GetInstancePrefix()).toBe('build-01:4000:');
+    });
+
+    describe('IsPriorBoot', () => {
+        it('is true for an earlier boot of the same instance, including one whose pid the OS reused', () => {
+            expect(ours.IsPriorBoot('build-01:4000:99:boot-before')).toBe(true);
+            expect(ours.IsPriorBoot('build-01:4000:101:boot-before')).toBe(true);
+        });
+
+        it.each([
+            ['this boot', 'build-01:4000:101:boot-ours'],
+            ['another MJAPI on the same host (another port)', 'build-01:4100:202:boot-other'],
+            ['an MJAPI on another host', 'build-02:4000:101:boot-other'],
+            ['the format before the port was added, with a pid equal to the port', 'build-01:4000:boot-before'],
+            ['no id', null],
+            ['an empty id', ''],
+        ])('is false for %s', (_case, hostInstanceID) => {
+            expect(ours.IsPriorBoot(hostInstanceID)).toBe(false);
+        });
+
+        it("matches a host name exactly, though a SQL LIKE reads its '_' as any character", () => {
+            const underscored = new HostInstanceIdentity('web_1', '4000', 7, 'boot-ours');
+            expect(underscored.IsPriorBoot('web_1:4000:8:boot-before')).toBe(true);
+            expect(underscored.IsPriorBoot('web-1:4000:8:boot-before')).toBe(false);
+        });
+    });
+});
+
+describe('the current host instance', () => {
+    it('carries the port SetHostInstancePort set before it was first read', async () => {
+        const hostInstance = await freshHostInstanceModule();
+        hostInstance.SetHostInstancePort(4100);
+
+        const current = hostInstance.GetCurrentHostInstance();
+        expect(current.GetHostInstanceID()).toBe(`${hostname()}:4100:${process.pid}:${hostInstance.GetBootID()}`);
+        expect(current.GetInstancePrefix()).toBe(`${hostname()}:4100:`);
+        expect(hostInstance.GetHostInstanceID()).toBe(current.GetHostInstanceID());
+    });
+
+    it('is this process alone (pid-<pid>) when no port was set', async () => {
+        const hostInstance = await freshHostInstanceModule();
+
+        expect(hostInstance.GetCurrentHostInstance().InstanceKey).toBe(`pid-${process.pid}`);
+        expect(hostInstance.GetHostInstanceID()).toBe(`${hostname()}:pid-${process.pid}:${process.pid}:${hostInstance.GetBootID()}`);
+    });
+
+    it('keeps its identity, and logs, when another port is set after it was read', async () => {
+        const hostInstance = await freshHostInstanceModule();
+        hostInstance.SetHostInstancePort(4100);
+        const before = hostInstance.GetHostInstanceID();
+
+        hostInstance.SetHostInstancePort(4200);
+
+        expect(hostInstance.GetHostInstanceID()).toBe(before);
+        expect(logErrorMock).toHaveBeenCalledTimes(1);
+        expect(String(logErrorMock.mock.calls[0][0])).toContain('Port 4200 was set after');
+    });
+});

package/src/__tests__/HumanHandoffResolver.test.ts

@@ -7,6 +7,8 @@ import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
 
 const h = vi.hoisted(() => ({
   configure: vi.fn(),
+  registryConfigure: vi.fn(),
+  getSystemUser: vi.fn(),
   listOffersForUser: vi.fn(),
   acceptOffer: vi.fn(),
   declineOffer: vi.fn(),
@@ -23,8 +25,12 @@ vi.mock('@memberjunction/livekit-room-server', () => ({
       DeclineOffer: h.declineOffer,
     },
   },
+  HandoffOfferRegistry: { Instance: { Configure: h.registryConfigure } },
   LiveKitSipService: class {},
 }));
+vi.mock('@memberjunction/generic-database-provider', () => ({
+  UserCache: { Instance: { GetSystemUser: h.getSystemUser } },
+}));
 vi.mock('@memberjunction/notifications', () => ({
   NotificationEngine: { Instance: { Config: h.notificationConfig, SendNotification: h.sendNotification } },
 }));
@@ -44,6 +50,17 @@ import type { AppContext } from '../types.js';
 /** Captured at module load: the resolver binds the engine's server-only collaborators then. */
 const wiredAtLoad = h.configure.mock.calls[0]?.[0] as { Presence: unknown; Publisher: unknown; Notifier: unknown };
 
+const registryWiredAtLoad = h.registryConfigure.mock.calls[0]?.[0] as { ResolveContextUser: () => UserInfo | undefined };
+
+describe('offer registry server identity wiring', () => {
+  it('configures the registry with a lazy system-user resolver that reads the user cache on every call', () => {
+    const systemUser = { ID: 'sys' } as unknown as UserInfo;
+    h.getSystemUser.mockReturnValueOnce(undefined).mockReturnValueOnce(systemUser);
+    expect(registryWiredAtLoad.ResolveContextUser()).toBeUndefined();
+    expect(registryWiredAtLoad.ResolveContextUser()).toBe(systemUser);
+  });
+});
+
 class TestableResolver extends HumanHandoffResolver {
   public user: UserInfo | undefined = { ID: 'U1', Name: 'Dana', Email: 'dana@x.com' } as unknown as UserInfo;
   protected override GetUserFromPayload(): UserInfo | undefined {

package/src/__tests__/MeetingResolver.test.ts

@@ -3,12 +3,14 @@ import 'reflect-metadata';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
 import type {
+  MJAIAgentSessionEntity,
   MJMeetingEntity,
   MJMeetingParticipantEntity,
   MJPhoneNumberEntity,
   MJInteractionEntity,
   MJInteractionEventEntity,
 } from '@memberjunction/core-entities';
+import type { StartAgentRoomSessionParams } from '@memberjunction/livekit-room-server';
 
 const mocks = vi.hoisted(() => ({
   mintClientToken: vi.fn(async (roomName: string, identity: string, name?: string) => ({
@@ -16,7 +18,7 @@ const mocks = vi.hoisted(() => ({
     Identity: identity,
     ServerUrl: 'wss://livekit.example.com',
   })),
-  startAgentRoomSession: vi.fn(async () => ({
+  startAgentRoomSession: vi.fn(async (_params: StartAgentRoomSessionParams) => ({
     SessionBridgeID: 'bridge-123',
     RoomName: 'room-123',
   })),
@@ -69,6 +71,7 @@ import {
   type RSVPMeetingInput,
 } from '../resolvers/MeetingResolver.js';
 import type { AppContext } from '../types.js';
+import type { SessionManager } from '../agentSessions/SessionManager.js';
 
 class MockEntityBase {
   public ID: string = `mock-${Date.now()}-${Math.random()}`;
@@ -362,6 +365,77 @@ describe('MeetingResolver', () => {
       expect(m.EndedAt).toBeDefined();
       expect(mocks.stopAllAgentsInRoom).toHaveBeenCalledWith('mj-mtg-standup-1', 'Explicit', resolver.user, mockProvider);
     });
+
+    it("closes an agent participant's session when its agent leaves the room (#5356)", async () => {
+      const m = new MockMeetingEntity();
+      m.ID = 'mtg-live-2';
+      m.HostUserID = 'user-host-1';
+      m.RoomName = 'mj-mtg-standup-2';
+      m.Status = 'Scheduled';
+      resolver.mockMeetings.push(m);
+
+      // The resolver's protected seams this test stands in for.
+      const seams = resolver as unknown as {
+        loadMeetingEntity: () => Promise<MockMeetingEntity>;
+        isUserHostOrCoHost: () => Promise<boolean>;
+        loadParticipants: () => Promise<object[]>;
+        sessionManager: SessionManager;
+      };
+      vi.spyOn(seams, 'loadMeetingEntity').mockResolvedValue(m);
+      vi.spyOn(seams, 'isUserHostOrCoHost').mockResolvedValue(true);
+      vi.spyOn(seams, 'loadParticipants').mockResolvedValue([
+        { ID: 'p-1', MeetingID: m.ID, Role: 'Agent', AgentID: 'agent-co-1', InviteStatus: 'Accepted' },
+      ]);
+      vi.spyOn(seams.sessionManager, 'CreateSession').mockResolvedValue({ ID: 'agent-session-789' } as unknown as MJAIAgentSessionEntity);
+      const closeSession = vi.spyOn(seams.sessionManager, 'CloseSession').mockResolvedValue(true);
+
+      await resolver.StartMeeting(m.ID, ctx);
+      const started = mocks.startAgentRoomSession.mock.calls[0][0];
+      expect(started.AgentSessionID).toBe('agent-session-789');
+      expect(closeSession).not.toHaveBeenCalled();
+
+      // The agent leaves (the meeting was ended, or everyone left): the coordinator runs the hook once its bridge has ended.
+      await started.Host?.OnSessionEnded?.('Explicit');
+
+      expect(closeSession).toHaveBeenCalledWith('agent-session-789', resolver.user, mockProvider, 'Explicit');
+    });
+
+    it("closes an agent participant's session at once, as Error, when its agent fails to start (#5308)", async () => {
+      const m = new MockMeetingEntity();
+      m.ID = 'mtg-live-3';
+      m.HostUserID = 'user-host-1';
+      m.RoomName = 'mj-mtg-standup-3';
+      m.Status = 'Scheduled';
+      resolver.mockMeetings.push(m);
+
+      // The resolver's protected seams this test stands in for.
+      const seams = resolver as unknown as {
+        loadMeetingEntity: () => Promise<MockMeetingEntity>;
+        isUserHostOrCoHost: () => Promise<boolean>;
+        loadParticipants: () => Promise<object[]>;
+        sessionManager: SessionManager;
+      };
+      vi.spyOn(seams, 'loadMeetingEntity').mockResolvedValue(m);
+      vi.spyOn(seams, 'isUserHostOrCoHost').mockResolvedValue(true);
+      vi.spyOn(seams, 'loadParticipants').mockResolvedValue([
+        { ID: 'p-1', MeetingID: m.ID, Role: 'Agent', AgentID: 'agent-fails', InviteStatus: 'Accepted' },
+        { ID: 'p-2', MeetingID: m.ID, Role: 'Agent', AgentID: 'agent-joins', InviteStatus: 'Accepted' },
+      ]);
+      vi.spyOn(seams.sessionManager, 'CreateSession')
+        .mockResolvedValueOnce({ ID: 'agent-session-fails' } as unknown as MJAIAgentSessionEntity)
+        .mockResolvedValueOnce({ ID: 'agent-session-joins' } as unknown as MJAIAgentSessionEntity);
+      const closeSession = vi.spyOn(seams.sessionManager, 'CloseSession').mockResolvedValue(true);
+      // The first agent's bridge can't start (the coordinator has closed its model session by the time this throws).
+      mocks.startAgentRoomSession.mockRejectedValueOnce(new Error('Failed to create AIAgentSessionBridge: permission denied'));
+
+      const result = await resolver.StartMeeting(m.ID, ctx);
+
+      // The meeting still starts, with the agent that joined; only the failed agent's session is closed.
+      expect(result.Success).toBe(true);
+      expect(mocks.startAgentRoomSession).toHaveBeenCalledTimes(2);
+      expect(closeSession).toHaveBeenCalledTimes(1);
+      expect(closeSession).toHaveBeenCalledWith('agent-session-fails', resolver.user, mockProvider, 'Error');
+    });
   });
 
   describe('RSVPMeeting', () => {