@memberjunction/server 6.2.0-edge.5 → 6.2.0-edge.7

package/src/__tests__/ResolverBase.publishStatusUpdate.test.ts

@@ -0,0 +1,68 @@
+// ResolverBase transitively pulls in type-graphql decorators, which need the
+// Reflect.metadata polyfill at import time.
+import 'reflect-metadata';
+import { describe, it, expect, vi } from 'vitest';
+import type { PubSubEngine } from 'type-graphql';
+import { UserInfo } from '@memberjunction/core';
+import { ResolverBase } from '../generic/ResolverBase.js';
+import { PUSH_STATUS_UPDATES_TOPIC, StatusUpdateOwnerID } from '../generic/PushStatusResolver.js';
+import type { UserPayload } from '../types.js';
+
+/**
+ * `ResolverBase.PublishStatusUpdate` stamps the owner the caller's socket is authenticated as. For a widget guest
+ * whose run is elevated to the system user, that is the guest's owner key: a push stamped with the elevated user's ID
+ * never passes the subscription filter on the guest's socket.
+ */
+
+const ANONYMOUS_USER_ID = 'AAAAAAAA-0000-4000-8000-0000000000A0';
+const SYSTEM_USER_ID = 'BBBBBBBB-0000-4000-8000-0000000000B0';
+
+/** Reaches the protected publish wrapper. */
+class Probe extends ResolverBase {
+    public Publish(pubSub: PubSubEngine, userPayload: UserPayload): void {
+        this.PublishStatusUpdate(pubSub, 'session-1', 'progress', userPayload);
+    }
+}
+
+function elevatedGuestPayload(): UserPayload {
+    const guest = new UserInfo(null, { ID: ANONYMOUS_USER_ID, Email: 'anonymous@magic-link.local' });
+    guest.IsMagicLinkAnonymous = true;
+    guest.AnonymousVisitorID = 'sid-guest-1';
+    return {
+        sessionId: 'session-1',
+        email: 'system@example.com',
+        userRecord: new UserInfo(null, { ID: SYSTEM_USER_ID, Email: 'system@example.com' }),
+        ElevatedFrom: guest,
+    };
+}
+
+describe('ResolverBase.PublishStatusUpdate — the owner it stamps', () => {
+    it("stamps an elevated widget guest's own owner key, not the system user it was elevated to", () => {
+        const publish = vi.fn().mockResolvedValue(undefined);
+        const pubSub: PubSubEngine = { publish, subscribe: vi.fn(), unsubscribe: vi.fn(), asyncIterator: vi.fn() };
+        const userPayload = elevatedGuestPayload();
+
+        new Probe().Publish(pubSub, userPayload);
+
+        expect(publish).toHaveBeenCalledOnce();
+        expect(publish.mock.calls[0][0]).toBe(PUSH_STATUS_UPDATES_TOPIC);
+        const payload = publish.mock.calls[0][1] as { sessionId: string; ownerUserId: string; message: string };
+        expect(payload).toMatchObject({ sessionId: 'session-1', message: 'progress' });
+        expect(payload.ownerUserId).toBe(StatusUpdateOwnerID(userPayload));
+        expect(payload.ownerUserId).toBe(`${ANONYMOUS_USER_ID.toLowerCase()}|sid-guest-1`);
+    });
+
+    it('stamps a signed-in user with their user ID', () => {
+        const publish = vi.fn().mockResolvedValue(undefined);
+        const pubSub: PubSubEngine = { publish, subscribe: vi.fn(), unsubscribe: vi.fn(), asyncIterator: vi.fn() };
+        const userPayload: UserPayload = {
+            sessionId: 'session-1',
+            email: 'user@example.com',
+            userRecord: new UserInfo(null, { ID: 'CCCCCCCC-0000-4000-8000-0000000000C0', Email: 'user@example.com' }),
+        };
+
+        new Probe().Publish(pubSub, userPayload);
+
+        expect((publish.mock.calls[0][1] as { ownerUserId: string }).ownerUserId).toBe('CCCCCCCC-0000-4000-8000-0000000000C0');
+    });
+});

package/src/__tests__/ResolverBase.userViewCacheAndDedup.test.ts

@@ -0,0 +1,130 @@
+import 'reflect-metadata';
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { UserViewEngine } from '@memberjunction/core-entities';
+import type { MJUserViewEntityExtended } from '@memberjunction/core-entities';
+import { RunView } from '@memberjunction/core';
+import type { IMetadataProvider, IRunViewProvider, RunViewParams, UserInfo } from '@memberjunction/core';
+import { ResolverBase } from '../generic/ResolverBase.js';
+import { RunViewResolver, RunViewByNameInput, RunViewByIDInput } from '../generic/RunViewResolver.js';
+
+class UserViewProbe extends ResolverBase {
+    public async TestRunViewByID(
+        viewInput: RunViewByIDInput,
+        provider: IMetadataProvider,
+        userPayload: { userRecord: UserInfo; email: string }
+    ) {
+        return this.RunViewByIDGeneric(viewInput, provider, userPayload as never);
+    }
+
+    public async TestRunViewByName(
+        viewInput: RunViewByNameInput,
+        provider: IMetadataProvider,
+        userPayload: { userRecord: UserInfo; email: string }
+    ) {
+        return this.RunViewByNameGeneric(viewInput, provider, userPayload as never);
+    }
+}
+
+describe('ResolverBase & RunViewResolver UserViewEngine cache and ViewEntity forwarding (MJ-CORE-9)', () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    it('resolves MJ: User Views from UserViewEngine cache first, forwards ViewEntity into RunViewParams, and reuses _resolvedViewEntity in RunViewResolver', async () => {
+        const mockViewEntity = {
+            ID: 'view-123',
+            Name: 'Active Widgets',
+            EntityID: 'entity-widgets',
+            Entity: 'Widgets',
+            WhereClause: 'Status = 1',
+            GridState: null,
+            SortState: null,
+        } as unknown as MJUserViewEntityExtended;
+
+        vi.spyOn(UserViewEngine.Instance, 'Loaded', 'get').mockReturnValue(true);
+        const getViewByIdSpy = vi.spyOn(UserViewEngine.Instance, 'GetViewById').mockReturnValue(mockViewEntity);
+        const getViewByNameSpy = vi.spyOn(UserViewEngine.Instance, 'GetViewByName').mockReturnValue(mockViewEntity);
+
+        const capturedRunViewParams: RunViewParams[] = [];
+        const providerRunViewSpy = vi.fn().mockImplementation(async (params: RunViewParams) => {
+            capturedRunViewParams.push(params);
+            return {
+                Success: true,
+                Results: [{ ID: 'w-1', Name: 'Widget A' }],
+                RowCount: 1,
+                TotalRowCount: 1,
+                ExecutionTime: 2,
+                ErrorMessage: '',
+                UserViewRunID: '',
+            };
+        });
+        const fakeProvider = {
+            Entities: [
+                {
+                    ID: 'entity-widgets',
+                    Name: 'Widgets',
+                    PrimaryKeys: [{ Name: 'ID', CodeName: 'ID' }],
+                    Fields: [
+                        { Name: 'ID', CodeName: 'ID', AllowInView: true, DefaultInView: true, IsBinaryFieldType: false },
+                        { Name: 'Name', CodeName: 'Name', AllowInView: true, DefaultInView: true, IsBinaryFieldType: false },
+                    ],
+                    EncryptedFields: [],
+                },
+            ],
+            EntityByName: () => ({
+                ID: 'entity-widgets',
+                Name: 'Widgets',
+                PrimaryKeys: [{ Name: 'ID', CodeName: 'ID' }],
+                Fields: [
+                    { Name: 'ID', CodeName: 'ID', AllowInView: true, DefaultInView: true, IsBinaryFieldType: false },
+                    { Name: 'Name', CodeName: 'Name', AllowInView: true, DefaultInView: true, IsBinaryFieldType: false },
+                ],
+                EncryptedFields: [],
+            }),
+            EntityByID: () => ({
+                ID: 'entity-widgets',
+                Name: 'Widgets',
+                PrimaryKeys: [{ Name: 'ID', CodeName: 'ID' }],
+                Fields: [
+                    { Name: 'ID', CodeName: 'ID', AllowInView: true, DefaultInView: true, IsBinaryFieldType: false },
+                    { Name: 'Name', CodeName: 'Name', AllowInView: true, DefaultInView: true, IsBinaryFieldType: false },
+                ],
+                EncryptedFields: [],
+            }),
+            RunView: providerRunViewSpy,
+        } as unknown as IMetadataProvider & IRunViewProvider;
+
+        const userPayload = {
+            email: 'tester@example.com',
+            userRecord: { ID: 'u-1', Email: 'tester@example.com' } as unknown as UserInfo,
+        };
+
+        const resolver = new RunViewResolver();
+        const findBySpy = vi.spyOn(
+            resolver as unknown as { findBy: (...args: unknown[]) => Promise<unknown> },
+            'findBy'
+        );
+
+        const byIdResult = await resolver.RunViewByID(
+            { ViewID: 'view-123' } as RunViewByIDInput,
+            { providers: [{ provider: fakeProvider, type: 'Read-Only' }], userPayload } as never
+        );
+
+        expect(getViewByIdSpy).toHaveBeenCalledWith('view-123');
+        expect(findBySpy).not.toHaveBeenCalled();
+        expect(capturedRunViewParams).toHaveLength(1);
+        expect(capturedRunViewParams[0].ViewEntity).toBe(mockViewEntity);
+        expect(byIdResult?.Results).toHaveLength(1);
+
+        const byNameResult = await resolver.RunViewByName(
+            { ViewName: 'Active Widgets' } as RunViewByNameInput,
+            { providers: [{ provider: fakeProvider, type: 'Read-Only' }], userPayload } as never
+        );
+
+        expect(getViewByNameSpy).toHaveBeenCalledWith('Active Widgets');
+        expect(findBySpy).not.toHaveBeenCalled();
+        expect(capturedRunViewParams).toHaveLength(2);
+        expect(capturedRunViewParams[1].ViewEntity).toBe(mockViewEntity);
+        expect(byNameResult?.Results).toHaveLength(1);
+    });
+});

package/src/__tests__/RunAIAgentResolver.branch.test.ts

@@ -1,10 +1,12 @@
 /**
  * @fileoverview The conversation branch on `RunAIAgentFromConversationDetail`.
  *
- * The branch comes from the placeholder row the mutation is given, never from a request argument.
- * These tests pin that the mutation loads history along that branch's path, hands the branch to the
- * agent run on both the synchronous and fire-and-forget paths, and reads the trunk when the row has
- * no branch; and that `executeAIAgent` puts the branch on the run's params only when there is one.
+ * The branch defaults to the person's message the mutation is given, or — when `replyBranchId` is supplied
+ * (such as Regenerate forking from an earlier message) — is validated to be a branch of the conversation
+ * whose path holds the person's message. These tests pin that the mutation loads history along that branch's
+ * path, creates the reply on that branch, hands the branch to the agent run on both the synchronous and
+ * fire-and-forget paths, and reads the trunk when the message has no branch; and that `executeAIAgent` puts
+ * the branch on the run's params only when there is one.
  */
 import 'reflect-metadata'; // must precede any type-graphql decorator evaluation
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
@@ -26,6 +28,7 @@ vi.mock('type-graphql', () => {
 
 const hoisted = vi.hoisted(() => ({
     runAgentInConversation: vi.fn(),
+    createAgentReplyDetail: vi.fn(),
 }));
 
 vi.mock('@memberjunction/ai-agents', () => ({
@@ -33,8 +36,13 @@ vi.mock('@memberjunction/ai-agents', () => ({
         RunAgentInConversation(...args: unknown[]) {
             return hoisted.runAgentInConversation(...args);
         }
+        CreateAgentReplyDetail(...args: unknown[]) {
+            return hoisted.createAgentReplyDetail(...args);
+        }
     },
     ArtifactToolManager: class {},
+    CanAgentOwnSubAgentConsults: vi.fn(() => false),
+    LoadOpenSubAgentConsults: vi.fn(async () => []),
 }));
 
 vi.mock('../realtimeWidget/widgetGuestElevation.js', () => ({
@@ -70,11 +78,12 @@ function makeResolver(): { resolver: RunAIAgentResolver; seams: ResolverSeams }
     return { resolver, seams };
 }
 
-function makeContext(branchId: string | null): AppContext {
+function makeContext(branchId: string | null, sequence = 3): AppContext {
     const provider = {
         GetEntityObject: vi.fn().mockResolvedValue({
             ConversationID: 'conv-1',
             BranchID: branchId,
+            Sequence: sequence,
             Load: vi.fn().mockResolvedValue(true),
         }),
     };
@@ -87,11 +96,18 @@ function makeContext(branchId: string | null): AppContext {
 
 const pubSub = { publish: vi.fn() } as unknown as PubSubEngine;
 
-async function runMutation(resolver: RunAIAgentResolver, branchId: string | null, fireAndForget?: boolean) {
+async function runMutation(
+    resolver: RunAIAgentResolver,
+    branchId: string | null,
+    fireAndForget?: boolean,
+    replyBranchId?: string,
+    sequence = 3
+) {
     return resolver.RunAIAgentFromConversationDetail(
-        'detail-1', 'agent-1', makeContext(branchId), 'session-1', pubSub,
+        'detail-1', 'agent-1', makeContext(branchId, sequence), 'session-1', pubSub,
         undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined,
-        undefined, undefined, fireAndForget, undefined, undefined, undefined
+        undefined, undefined, fireAndForget, undefined, undefined, undefined,
+        undefined, undefined, replyBranchId
     );
 }
 
@@ -108,23 +124,64 @@ describe('RunAIAgentFromConversationDetail — branch', () => {
         seams.loadConversationHistoryWithAttachments = vi.fn().mockResolvedValue([]);
         seams.executeAIAgent = vi.fn().mockResolvedValue({ success: true, result: '{}' });
         seams.executeAgentInBackground = vi.fn();
+        hoisted.createAgentReplyDetail.mockReset().mockResolvedValue({ ID: 'reply-1', __mj_CreatedAt: new Date() });
     });
 
-    it('loads history on the placeholder row\'s branch and hands the branch to the run', async () => {
+    // executeAIAgent / executeAgentInBackground end with (..., branchId, replyDetail).
+    it('loads history on the message\'s branch, creates the reply there, and hands the branch to the run', async () => {
         await runMutation(resolver, 'branch-b');
         expect(seams.loadConversationHistoryWithAttachments.mock.calls[0][6]).toBe('branch-b');
-        expect(seams.executeAIAgent.mock.calls[0].at(-1)).toBe('branch-b');
+        expect(hoisted.createAgentReplyDetail).toHaveBeenCalledWith(expect.objectContaining({ branchId: 'branch-b' }));
+        expect(seams.executeAIAgent.mock.calls[0].at(-2)).toBe('branch-b');
     });
 
     it('passes the branch to the background path too', async () => {
         await runMutation(resolver, 'branch-b', true);
-        expect(seams.executeAgentInBackground.mock.calls[0].at(-1)).toBe('branch-b');
+        expect(seams.executeAgentInBackground.mock.calls[0].at(-2)).toBe('branch-b');
     });
 
-    it('reads the trunk when the placeholder has no branch (control)', async () => {
+    it('reads the trunk when the message has no branch (control)', async () => {
         await runMutation(resolver, null);
         expect(seams.loadConversationHistoryWithAttachments.mock.calls[0][6]).toBeNull();
-        expect(seams.executeAIAgent.mock.calls[0].at(-1)).toBeNull();
+        expect(hoisted.createAgentReplyDetail).toHaveBeenCalledWith(expect.objectContaining({ branchId: null }));
+        expect(seams.executeAIAgent.mock.calls[0].at(-2)).toBeNull();
+    });
+
+    it('places the reply and history on replyBranchId when a regeneration forks from a message on its ancestor path', async () => {
+        vi.spyOn(ConversationEngine, 'LoadBranchesFresh').mockResolvedValue([
+            {
+                ID: 'branch-regen',
+                ConversationID: 'conv-1',
+                ParentBranchID: null,
+                ForkFromSequence: 5,
+            } as never,
+        ]);
+
+        const result = await runMutation(resolver, null, false, 'branch-regen', 3);
+
+        expect(result.success).toBe(true);
+        expect(seams.loadConversationHistoryWithAttachments.mock.calls[0][6]).toBe('branch-regen');
+        expect(hoisted.createAgentReplyDetail).toHaveBeenCalledWith(expect.objectContaining({ branchId: 'branch-regen' }));
+        expect(seams.executeAIAgent.mock.calls[0].at(-2)).toBe('branch-regen');
+    });
+
+    it('refuses a replyBranchId whose path does not include the user message, and creates nothing', async () => {
+        vi.spyOn(console, 'error').mockImplementation(() => undefined);
+        vi.spyOn(ConversationEngine, 'LoadBranchesFresh').mockResolvedValue([
+            {
+                ID: 'branch-regen',
+                ConversationID: 'conv-1',
+                ParentBranchID: null,
+                ForkFromSequence: 5,
+            } as never,
+        ]);
+
+        const result = await runMutation(resolver, null, false, 'branch-regen', 8);
+
+        expect(result.success).toBe(false);
+        expect(result.errorMessage).toContain('branch-regen');
+        expect(hoisted.createAgentReplyDetail).not.toHaveBeenCalled();
+        expect(seams.executeAIAgent).not.toHaveBeenCalled();
     });
 });
 
@@ -165,6 +222,8 @@ describe('executeAIAgent — ConversationBranchID', () => {
         await execute(...base, null);
         const [withBranch, trunk] = hoisted.runAgentInConversation.mock.calls.map(c => c[0] as Record<string, unknown>);
         expect(withBranch.ConversationBranchID).toBe('branch-b');
+        expect(withBranch.handoffChain).toBeUndefined();
         expect(trunk).not.toHaveProperty('ConversationBranchID');
+        expect(trunk.handoffChain).toBeUndefined();
     });
 });

package/src/__tests__/RunAIAgentResolver.consultPredecessor.test.ts

@@ -0,0 +1,289 @@
+/**
+ * @fileoverview Unit tests for `RunAIAgentResolver.findChainablePredecessor` (VS-CON-8).
+ *
+ * Verifies how `findChainablePredecessor` selects the newest root run on the conversation/branch
+ * path via `MJAIAgentRunEntityExtended.BuildStoppedPredecessorFilter`, distinguishes a user-stopped
+ * run (`reason: 'stopped'`) from a `FinalStep === 'Chat'` run with open sub-agent consults
+ * (`reason: 'open-consult'`), short-circuits before querying steps when the agent cannot own
+ * consults (`CanAgentOwnSubAgentConsults(agentId) === false`), returns `null` on normal Chat turns
+ * or settled `Success` turns, and fails soft when `RunView` or `LoadOpenSubAgentConsults` throws.
+ */
+import 'reflect-metadata';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+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 hoisted = vi.hoisted(() => ({
+    canAgentOwnSubAgentConsults: vi.fn<(agentOrId: unknown) => boolean>(),
+    loadOpenSubAgentConsults: vi.fn<
+        (provider: unknown, runId: string, contextUser: unknown) => Promise<unknown[]>
+    >(),
+    logError: vi.fn(),
+}));
+
+vi.mock('@memberjunction/core', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@memberjunction/core')>();
+    return {
+        ...actual,
+        LogError: (...args: unknown[]) => hoisted.logError(...args),
+    };
+});
+
+vi.mock('@memberjunction/ai-agents', () => ({
+    AgentRunner: class {},
+    ArtifactToolManager: class {},
+    CanAgentOwnSubAgentConsults: (...args: [unknown]) => hoisted.canAgentOwnSubAgentConsults(...args),
+    LoadOpenSubAgentConsults: (...args: [unknown, string, unknown]) =>
+        hoisted.loadOpenSubAgentConsults(...args),
+}));
+
+vi.mock('../realtimeWidget/widgetGuestElevation.js', () => ({
+    ResolveWidgetGuestRunContext: vi.fn().mockResolvedValue(null),
+    ElevateUserPayload: vi.fn(),
+}));
+
+import { RunView } from '@memberjunction/core';
+import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { ConversationEngine } from '@memberjunction/core-entities';
+import { MJAIAgentRunEntityExtended } from '@memberjunction/ai-core-plus';
+import { RunAIAgentResolver } from '../resolvers/RunAIAgentResolver.js';
+
+const USER = { ID: 'user-1', Email: 'user@example.com' } as unknown as UserInfo;
+const PROVIDER = { __tag: 'mock-provider' } as unknown as IMetadataProvider;
+const CONV_ID = '11111111-1111-4111-8111-111111111111';
+const AGENT_ID = '22222222-2222-4222-8222-222222222222';
+const RUN_ID = '33333333-3333-4333-8333-333333333333';
+
+interface FindChainablePredecessorCallable {
+    findChainablePredecessor(
+        conversationId: string,
+        agentId: string,
+        branchId: string | null,
+        contextUser: UserInfo,
+        provider: IMetadataProvider
+    ): Promise<{ runId: string; reason: 'stopped' | 'open-consult' } | null>;
+}
+
+describe('RunAIAgentResolver.findChainablePredecessor (VS-CON-8)', () => {
+    let resolver: FindChainablePredecessorCallable;
+    let runViewMock: ReturnType<typeof vi.fn>;
+
+    beforeEach(() => {
+        resolver = new RunAIAgentResolver() as unknown as FindChainablePredecessorCallable;
+        runViewMock = vi.fn();
+        vi.spyOn(RunView, 'FromMetadataProvider').mockReturnValue({
+            RunView: runViewMock,
+        } as unknown as RunView);
+        hoisted.canAgentOwnSubAgentConsults.mockReset();
+        hoisted.loadOpenSubAgentConsults.mockReset();
+        hoisted.logError.mockReset();
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    it('returns { runId, reason: "stopped" } when the newest run is user-stopped, without calling LoadOpenSubAgentConsults', async () => {
+        runViewMock.mockResolvedValue({
+            Success: true,
+            Results: [
+                {
+                    ID: RUN_ID,
+                    Status: 'Cancelled',
+                    CancellationReason: 'User Request',
+                    FinalStep: null,
+                },
+            ],
+        });
+
+        const result = await resolver.findChainablePredecessor(CONV_ID, AGENT_ID, null, USER, PROVIDER);
+
+        expect(result).toEqual({ runId: RUN_ID, reason: 'stopped' });
+        expect(hoisted.canAgentOwnSubAgentConsults).not.toHaveBeenCalled();
+        expect(hoisted.loadOpenSubAgentConsults).not.toHaveBeenCalled();
+    });
+
+    it('returns { runId, reason: "open-consult" } when the newest run has Status=Completed, FinalStep=Chat, the agent can own consults, and LoadOpenSubAgentConsults returns a non-empty list', async () => {
+        runViewMock.mockResolvedValue({
+            Success: true,
+            Results: [
+                {
+                    ID: RUN_ID,
+                    Status: 'Completed',
+                    CancellationReason: null,
+                    FinalStep: 'Chat',
+                },
+            ],
+        });
+        hoisted.canAgentOwnSubAgentConsults.mockReturnValue(true);
+        hoisted.loadOpenSubAgentConsults.mockResolvedValue([
+            {
+                childRunId: '44444444-4444-4444-8444-444444444444',
+                subAgentId: '55555555-5555-4555-8555-555555555555',
+                subAgentName: 'Producer',
+                question: 'Which aspect ratio?',
+                openedAtStepId: '66666666-6666-4666-8666-666666666666',
+                parentRunId: RUN_ID,
+            },
+        ]);
+
+        const result = await resolver.findChainablePredecessor(CONV_ID, AGENT_ID, null, USER, PROVIDER);
+
+        expect(result).toEqual({ runId: RUN_ID, reason: 'open-consult' });
+        expect(hoisted.canAgentOwnSubAgentConsults).toHaveBeenCalledWith(AGENT_ID);
+        expect(hoisted.loadOpenSubAgentConsults).toHaveBeenCalledWith(PROVIDER, RUN_ID, USER);
+    });
+
+    it('returns null when the newest run has FinalStep=Chat for a consult-capable agent, but LoadOpenSubAgentConsults returns [] (normal Chat question)', async () => {
+        runViewMock.mockResolvedValue({
+            Success: true,
+            Results: [
+                {
+                    ID: RUN_ID,
+                    Status: 'Completed',
+                    CancellationReason: null,
+                    FinalStep: 'Chat',
+                },
+            ],
+        });
+        hoisted.canAgentOwnSubAgentConsults.mockReturnValue(true);
+        hoisted.loadOpenSubAgentConsults.mockResolvedValue([]);
+
+        const result = await resolver.findChainablePredecessor(CONV_ID, AGENT_ID, null, USER, PROVIDER);
+
+        expect(result).toBeNull();
+        expect(hoisted.canAgentOwnSubAgentConsults).toHaveBeenCalledWith(AGENT_ID);
+        expect(hoisted.loadOpenSubAgentConsults).toHaveBeenCalledWith(PROVIDER, RUN_ID, USER);
+    });
+
+    it('returns null and does NOT call LoadOpenSubAgentConsults (zero step queries) when CanAgentOwnSubAgentConsults(agentId) === false', async () => {
+        runViewMock.mockResolvedValue({
+            Success: true,
+            Results: [
+                {
+                    ID: RUN_ID,
+                    Status: 'Completed',
+                    CancellationReason: null,
+                    FinalStep: 'Chat',
+                },
+            ],
+        });
+        hoisted.canAgentOwnSubAgentConsults.mockReturnValue(false);
+
+        const result = await resolver.findChainablePredecessor(CONV_ID, AGENT_ID, null, USER, PROVIDER);
+
+        expect(result).toBeNull();
+        expect(hoisted.canAgentOwnSubAgentConsults).toHaveBeenCalledWith(AGENT_ID);
+        expect(hoisted.loadOpenSubAgentConsults).not.toHaveBeenCalled();
+    });
+
+    it('returns null when the newest run has FinalStep=Success, querying MaxRows: 1 + OrderBy: __mj_CreatedAt DESC', async () => {
+        runViewMock.mockResolvedValue({
+            Success: true,
+            Results: [
+                {
+                    ID: RUN_ID,
+                    Status: 'Completed',
+                    CancellationReason: null,
+                    FinalStep: 'Success',
+                },
+            ],
+        });
+
+        const result = await resolver.findChainablePredecessor(CONV_ID, AGENT_ID, null, USER, PROVIDER);
+
+        expect(result).toBeNull();
+        expect(runViewMock).toHaveBeenCalledWith(
+            expect.objectContaining({
+                EntityName: 'MJ: AI Agent Runs',
+                OrderBy: '__mj_CreatedAt DESC',
+                MaxRows: 1,
+                Fields: ['ID', 'Status', 'CancellationReason', 'FinalStep'],
+                ResultType: 'simple',
+                BypassCache: true,
+            }),
+            USER
+        );
+        expect(hoisted.canAgentOwnSubAgentConsults).not.toHaveBeenCalled();
+        expect(hoisted.loadOpenSubAgentConsults).not.toHaveBeenCalled();
+    });
+
+    it('passes branchId and loaded branches into BuildStoppedPredecessorFilter (branch-path isolation), and skips LoadBranchesFresh when branchId is null (trunk)', async () => {
+        const fakeBranches = [{ ID: 'branch-B', ParentBranchID: null }];
+        const loadBranchesSpy = vi
+            .spyOn(ConversationEngine, 'LoadBranchesFresh')
+            .mockResolvedValue(fakeBranches as never);
+        const filterSpy = vi
+            .spyOn(MJAIAgentRunEntityExtended, 'BuildStoppedPredecessorFilter')
+            .mockReturnValue("ConversationID = 'conv' AND BranchFilter = 1");
+        runViewMock.mockResolvedValue({ Success: true, Results: [] });
+
+        // 1. Trunk (branchId === null): skips LoadBranchesFresh and passes null + []
+        const trunkResult = await resolver.findChainablePredecessor(
+            CONV_ID,
+            AGENT_ID,
+            null,
+            USER,
+            PROVIDER
+        );
+        expect(trunkResult).toBeNull();
+        expect(loadBranchesSpy).not.toHaveBeenCalled();
+        expect(filterSpy).toHaveBeenCalledWith(CONV_ID, AGENT_ID, null, []);
+
+        // 2. Branch (branchId === 'branch-B'): calls LoadBranchesFresh and passes 'branch-B' + fakeBranches
+        filterSpy.mockClear();
+        const branchResult = await resolver.findChainablePredecessor(
+            CONV_ID,
+            AGENT_ID,
+            'branch-B',
+            USER,
+            PROVIDER
+        );
+
+        expect(branchResult).toBeNull();
+        expect(loadBranchesSpy).toHaveBeenCalledWith(CONV_ID, USER, PROVIDER);
+        expect(filterSpy).toHaveBeenCalledWith(CONV_ID, AGENT_ID, 'branch-B', fakeBranches);
+        expect(runViewMock).toHaveBeenCalledWith(
+            expect.objectContaining({
+                ExtraFilter: "ConversationID = 'conv' AND BranchFilter = 1",
+            }),
+            USER
+        );
+    });
+
+    it('logs an error and returns null (never fails dispatch) if RunView or LoadOpenSubAgentConsults throws', async () => {
+        // 1. RunView throws
+        runViewMock.mockRejectedValueOnce(new Error('DB connection lost'));
+        const res1 = await resolver.findChainablePredecessor(CONV_ID, AGENT_ID, null, USER, PROVIDER);
+        expect(res1).toBeNull();
+        expect(hoisted.logError).toHaveBeenCalledTimes(1);
+
+        // 2. LoadOpenSubAgentConsults throws
+        runViewMock.mockResolvedValueOnce({
+            Success: true,
+            Results: [
+                {
+                    ID: RUN_ID,
+                    Status: 'Completed',
+                    CancellationReason: null,
+                    FinalStep: 'Chat',
+                },
+            ],
+        });
+        hoisted.canAgentOwnSubAgentConsults.mockReturnValue(true);
+        hoisted.loadOpenSubAgentConsults.mockRejectedValueOnce(new Error('Step query timed out'));
+        const res2 = await resolver.findChainablePredecessor(CONV_ID, AGENT_ID, null, USER, PROVIDER);
+        expect(res2).toBeNull();
+        expect(hoisted.logError).toHaveBeenCalledTimes(2);
+    });
+});