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

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

@@ -0,0 +1,291 @@
+// ResolverBase / RunViewResolver transitively pull in type-graphql decorators, which need the
+// Reflect.metadata polyfill at import time.
+import 'reflect-metadata';
+import { describe, it, expect } from 'vitest';
+import type {
+    DatabaseProviderBase,
+    EntityInfo,
+    IMetadataProvider,
+    RunViewParams,
+    RunViewResult,
+    RunViewWithCacheCheckParams,
+    RunViewsWithCacheCheckResponse,
+    UserInfo,
+} from '@memberjunction/core';
+import type { MJUserViewEntityExtended } from '@memberjunction/core-entities';
+import { ResolverBase } from '../generic/ResolverBase.js';
+import {
+    RunViewResolver,
+    type RunDynamicViewInput,
+    type RunViewByIDInput,
+    type RunViewByNameInput,
+    type RunViewResultRow,
+    type RunViewWithCacheCheckInput,
+} from '../generic/RunViewResolver.js';
+import type { AppContext, UserPayload } from '../types.js';
+
+/**
+ * Binary DB fields (varbinary / bytea) are base64 strings in JS and on the wire, and RunView
+ * omits them unless `IncludeBinaryFields: true`. These tests pin the server half:
+ *
+ *   1. the GraphQL flag reaches the provider's RunView / RunViews / RunViewsWithCacheCheck params
+ *      on every resolver path (single by-ID / by-name / dynamic, batch, and the cache-check batch);
+ *   2. any byte array that still reaches a resolver is serialized as base64 — never as the
+ *      `{"type":"Buffer","data":[...]}` that `JSON.stringify` produces for a Node Buffer.
+ */
+
+const ENTITY_NAME = 'MJ: Vector Things';
+const ENTITY_ID = 'ent-1';
+
+/** Bytes whose base64 form is easy to recognise: [1,2,3,4] → "AQIDBA==". */
+const BYTES = [1, 2, 3, 4];
+const BYTES_BASE64 = 'AQIDBA==';
+
+const fakePayload = () =>
+    ({ email: 'tester@example.com', userRecord: { Email: 'tester@example.com' } as UserInfo } as UserPayload);
+
+function entityStub() {
+    return {
+        ID: ENTITY_ID,
+        Name: ENTITY_NAME,
+        BaseView: 'vwVectorThings',
+        PrimaryKeys: [{ Name: 'ID' }],
+        Fields: [
+            { Name: 'ID', CodeName: 'ID' },
+            { Name: 'Embedding', CodeName: 'Embedding' },
+        ],
+        EncryptedFields: [],
+    };
+}
+
+/** Provider that records every RunView / RunViews call and returns the given rows. */
+function recordingProvider(rows: Record<string, unknown>[] = []) {
+    const runViewCalls: RunViewParams[] = [];
+    const runViewsCalls: RunViewParams[][] = [];
+    const viewInfo = { ID: 'view-1', Name: 'Saved View', Entity: ENTITY_NAME, EntityID: ENTITY_ID };
+    const provider = {
+        Entities: [entityStub()],
+        EntityByName: (name: string) => (name === ENTITY_NAME ? entityStub() : undefined),
+        RunView: async (params: RunViewParams): Promise<RunViewResult> => {
+            // RunViewByNameGeneric looks the saved view up first — answer that lookup with the view row.
+            if (params.EntityName === 'MJ: User Views') {
+                return { Success: true, Results: [viewInfo], RowCount: 1, TotalRowCount: 1, ErrorMessage: '' } as RunViewResult;
+            }
+            runViewCalls.push(params);
+            return { Success: true, Results: rows, RowCount: rows.length, TotalRowCount: rows.length, ErrorMessage: '' } as RunViewResult;
+        },
+        RunViews: async (params: RunViewParams[]): Promise<RunViewResult[]> => {
+            runViewsCalls.push(params);
+            return params.map(() => ({ Success: true, Results: rows, RowCount: rows.length, TotalRowCount: rows.length, ErrorMessage: '' } as RunViewResult));
+        },
+        GetEntityObject: async () => ({ ...viewInfo, Load: async () => true }),
+    } as unknown as DatabaseProviderBase;
+    return { provider, runViewCalls, runViewsCalls };
+}
+
+/** Skips the encrypted-field filter (it needs live Metadata) — irrelevant to these assertions. */
+class Probe extends ResolverBase {
+    protected override async ArrayFilterEncryptedFieldsForAPI(
+        _entityName: string,
+        dataObjectArray: Record<string, unknown>[]
+    ): Promise<Record<string, unknown>[]> {
+        return dataObjectArray;
+    }
+
+    public MapOne(entityName: string, row: unknown, provider: IMetadataProvider) {
+        return this.MapFieldNamesToCodeNames(entityName, row, undefined, provider);
+    }
+}
+
+describe('IncludeBinaryFields forwarding — single-view resolver paths', () => {
+    it('RunDynamicViewGeneric forwards IncludeBinaryFields: true to provider.RunView', async () => {
+        const { provider, runViewCalls } = recordingProvider();
+        await new Probe().RunDynamicViewGeneric(
+            { EntityName: ENTITY_NAME, ExtraFilter: '', OrderBy: '', IncludeBinaryFields: true } as RunDynamicViewInput,
+            provider, fakePayload(), undefined as never,
+        );
+
+        expect(runViewCalls).toHaveLength(1);
+        expect(runViewCalls[0].IncludeBinaryFields).toBe(true);
+    });
+
+    it('RunDynamicViewGeneric leaves IncludeBinaryFields undefined when the caller did not set it', async () => {
+        const { provider, runViewCalls } = recordingProvider();
+        await new Probe().RunDynamicViewGeneric(
+            { EntityName: ENTITY_NAME, ExtraFilter: '', OrderBy: '' } as RunDynamicViewInput,
+            provider, fakePayload(), undefined as never,
+        );
+
+        expect(runViewCalls).toHaveLength(1);
+        expect(runViewCalls[0].IncludeBinaryFields).toBeUndefined();
+    });
+
+    it('RunViewByNameGeneric forwards IncludeBinaryFields to provider.RunView', async () => {
+        const { provider, runViewCalls } = recordingProvider();
+        await new Probe().RunViewByNameGeneric(
+            { ViewName: 'Saved View', ExtraFilter: '', OrderBy: '', IncludeBinaryFields: true } as RunViewByNameInput,
+            provider, fakePayload(), undefined as never,
+        );
+
+        expect(runViewCalls).toHaveLength(1);
+        expect(runViewCalls[0].EntityName).toBe(ENTITY_NAME);
+        expect(runViewCalls[0].IncludeBinaryFields).toBe(true);
+    });
+
+    it('RunViewByIDGeneric forwards IncludeBinaryFields to provider.RunView', async () => {
+        const { provider, runViewCalls } = recordingProvider();
+        await new Probe().RunViewByIDGeneric(
+            { ViewID: 'view-1', ExtraFilter: '', OrderBy: '', IncludeBinaryFields: false } as RunViewByIDInput,
+            provider, fakePayload(), undefined as never,
+        );
+
+        expect(runViewCalls).toHaveLength(1);
+        expect(runViewCalls[0].IncludeBinaryFields).toBe(false);
+    });
+
+    it('RunViewGenericInternal passes binary values through as the provider returned them (base64 strings)', async () => {
+        const { provider } = recordingProvider([{ ID: 'r1', Embedding: BYTES_BASE64 }]);
+        const result = await new Probe().RunDynamicViewGeneric(
+            { EntityName: ENTITY_NAME, ExtraFilter: '', OrderBy: '', IncludeBinaryFields: true } as RunDynamicViewInput,
+            provider, fakePayload(), undefined as never,
+        );
+
+        expect((result?.Results as Record<string, unknown>[])[0].Embedding).toBe(BYTES_BASE64);
+    });
+});
+
+describe('IncludeBinaryFields forwarding — batch resolver path', () => {
+    it('RunViewsGeneric → RunViewsGenericInternal forwards the per-view flag to provider.RunViews', async () => {
+        const { provider, runViewsCalls } = recordingProvider();
+        const inputs = [
+            { EntityName: ENTITY_NAME, ExtraFilter: '', OrderBy: '', IncludeBinaryFields: true },
+            { EntityName: ENTITY_NAME, ExtraFilter: '', OrderBy: '' },
+        ] as (RunViewByNameInput & RunViewByIDInput & RunDynamicViewInput)[];
+
+        await new Probe().RunViewsGeneric(inputs, provider, fakePayload());
+
+        expect(runViewsCalls).toHaveLength(1);
+        expect(runViewsCalls[0]).toHaveLength(2);
+        expect(runViewsCalls[0][0].IncludeBinaryFields).toBe(true);
+        expect(runViewsCalls[0][1].IncludeBinaryFields).toBeUndefined();
+    });
+});
+
+describe('MapFieldNamesToCodeNames — byte arrays become base64', () => {
+    const provider = {
+        EntityByName: (name: string) => (name === ENTITY_NAME ? (entityStub() as unknown as EntityInfo) : undefined),
+    } as unknown as IMetadataProvider;
+
+    it('converts a Buffer value to its base64 string', async () => {
+        const mapped = (await new Probe().MapOne(ENTITY_NAME, { ID: 'r1', Embedding: Buffer.from(BYTES) }, provider)) as Record<string, unknown>;
+
+        expect(mapped.Embedding).toBe(BYTES_BASE64);
+        expect(mapped.ID).toBe('r1');
+    });
+
+    it('converts a plain Uint8Array value too', async () => {
+        const mapped = (await new Probe().MapOne(ENTITY_NAME, { ID: 'r1', Embedding: new Uint8Array(BYTES) }, provider)) as Record<string, unknown>;
+
+        expect(mapped.Embedding).toBe(BYTES_BASE64);
+    });
+
+    it('leaves an already-base64 string untouched', async () => {
+        const mapped = (await new Probe().MapOne(ENTITY_NAME, { ID: 'r1', Embedding: BYTES_BASE64 }, provider)) as Record<string, unknown>;
+
+        expect(mapped.Embedding).toBe(BYTES_BASE64);
+    });
+
+    it('does not mutate the caller\'s row (it may be a frozen cache entry)', async () => {
+        const buffer = Buffer.from(BYTES);
+        const source = Object.freeze({ ID: 'r1', Embedding: buffer }) as Record<string, unknown>;
+
+        const mapped = (await new Probe().MapOne(ENTITY_NAME, source, provider)) as Record<string, unknown>;
+
+        expect(mapped.Embedding).toBe(BYTES_BASE64);
+        expect(source.Embedding).toBe(buffer);
+    });
+});
+
+/** Exposes the protected serializer. */
+class ResolverProbe extends RunViewResolver {
+    public Process(rows: Record<string, unknown>[]): RunViewResultRow[] {
+        return this.processRawData(rows, ENTITY_ID, entityStub() as unknown as EntityInfo);
+    }
+}
+
+describe('RunViewResolver.processRawData — Buffer → base64 in the Data JSON', () => {
+    it('serializes a Buffer value as base64, not {type:"Buffer",data:[...]}', () => {
+        const [row] = new ResolverProbe().Process([{ ID: 'r1', Embedding: Buffer.from(BYTES) }]);
+        const data = JSON.parse(row.Data) as Record<string, unknown>;
+
+        expect(data.Embedding).toBe(BYTES_BASE64);
+        expect(row.Data).not.toContain('"type":"Buffer"');
+        expect(row.PrimaryKey).toEqual([{ FieldName: 'ID', Value: 'r1' }]);
+        expect(row.EntityID).toBe(ENTITY_ID);
+    });
+
+    it('serializes a Uint8Array value as base64 (not an index-keyed object)', () => {
+        const [row] = new ResolverProbe().Process([{ ID: 'r1', Embedding: new Uint8Array(BYTES) }]);
+
+        expect((JSON.parse(row.Data) as Record<string, unknown>).Embedding).toBe(BYTES_BASE64);
+    });
+
+    it('leaves rows without byte arrays serialized exactly as before', () => {
+        const source = { ID: 'r1', Name: 'Plain', Embedding: BYTES_BASE64, Count: 3 };
+        const [row] = new ResolverProbe().Process([source]);
+
+        expect(row.Data).toBe(JSON.stringify(source));
+    });
+
+    it('does not mutate the source row', () => {
+        const buffer = Buffer.from(BYTES);
+        const source: Record<string, unknown> = { ID: 'r1', Embedding: buffer };
+
+        new ResolverProbe().Process([source]);
+
+        expect(source.Embedding).toBe(buffer);
+    });
+});
+
+describe('RunViewResolver.RunViewsWithCacheCheck — IncludeBinaryFields + Buffer serialization', () => {
+    function cacheCheckContext(rows: Record<string, unknown>[]) {
+        const received: RunViewWithCacheCheckParams[][] = [];
+        const provider = {
+            EntityByName: (name: string) => (name === ENTITY_NAME ? entityStub() : undefined),
+            RunViewsWithCacheCheck: async (params: RunViewWithCacheCheckParams[]): Promise<RunViewsWithCacheCheckResponse> => {
+                received.push(params);
+                return {
+                    success: true,
+                    results: params.map((_p, i) => ({ viewIndex: i, status: 'stale', results: rows, maxUpdatedAt: 'T', rowCount: rows.length })),
+                } as RunViewsWithCacheCheckResponse;
+            },
+        };
+        const ctx = { providers: [{ type: 'Read-Only', provider }], userPayload: fakePayload() } as unknown as AppContext;
+        return { ctx, received };
+    }
+
+    it('forwards IncludeBinaryFields into the core params (true, false and unset)', async () => {
+        const { ctx, received } = cacheCheckContext([]);
+        const input = [
+            { params: { EntityName: ENTITY_NAME, IncludeBinaryFields: true } },
+            { params: { EntityName: ENTITY_NAME, IncludeBinaryFields: false } },
+            { params: { EntityName: ENTITY_NAME } },
+        ] as RunViewWithCacheCheckInput[];
+
+        const out = await new RunViewResolver().RunViewsWithCacheCheck(input, ctx);
+
+        expect(out.success).toBe(true);
+        expect(received).toHaveLength(1);
+        expect(received[0].map(p => p.params.IncludeBinaryFields)).toEqual([true, false, undefined]);
+    });
+
+    it('serializes Buffers in stale results as base64', async () => {
+        const { ctx } = cacheCheckContext([{ ID: 'r1', Embedding: Buffer.from(BYTES) }]);
+        const input = [{ params: { EntityName: ENTITY_NAME, IncludeBinaryFields: true } }] as RunViewWithCacheCheckInput[];
+
+        const out = await new RunViewResolver().RunViewsWithCacheCheck(input, ctx);
+        const rows = out.results[0].Results as RunViewResultRow[];
+
+        expect((JSON.parse(rows[0].Data) as Record<string, unknown>).Embedding).toBe(BYTES_BASE64);
+    });
+});

package/src/__tests__/ReturningVisitorRecap.test.ts

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview The returning-visitor recap transcript reads Main.
+ *
+ * The transcript query filters with `ConversationEngine.ScopeFilter(ConversationEngine.TrunkScope(id))`
+ * and takes the newest turns by `Sequence`. It reads no branch or conversation scope first.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
+
+interface ViewCall {
+    EntityName: string;
+    ExtraFilter?: string;
+    OrderBy?: string;
+    MaxRows?: number;
+}
+
+const hoisted = vi.hoisted(() => ({
+    views: [] as ViewCall[],
+    detailRows: [] as Array<{ Role: string; Message: string }>,
+    transcripts: [] as string[],
+    logError: vi.fn(),
+    logStatus: vi.fn(),
+    aiConfig: vi.fn(),
+}));
+
+vi.mock('@memberjunction/core', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@memberjunction/core')>();
+    return {
+        ...actual,
+        LogError: hoisted.logError,
+        LogStatus: hoisted.logStatus,
+        RunView: class {
+            async RunView(params: ViewCall) {
+                hoisted.views.push(params);
+                if (params.EntityName === 'MJ: Conversation Details') {
+                    return { Success: true, Results: hoisted.detailRows };
+                }
+                return { Success: true, Results: [] };
+            }
+        },
+    };
+});
+
+vi.mock('@memberjunction/aiengine', () => ({
+    AIEngine: {
+        Instance: {
+            Config: hoisted.aiConfig,
+            Prompts: [{ Name: 'Returning-Visitor Recap', SelectionStrategy: 'Default', Status: 'Active' }],
+        },
+    },
+}));
+
+vi.mock('@memberjunction/ai-core-plus', () => ({
+    AIPromptParams: class {},
+}));
+
+vi.mock('@memberjunction/ai-prompts', () => ({
+    AIPromptRunner: class {
+        async ExecutePrompt(params: { data?: { transcript?: string } }) {
+            hoisted.transcripts.push(params.data?.transcript ?? '');
+            return { success: true, rawResult: 'NO_RECAP' };
+        }
+    },
+}));
+
+import { ConversationEngine } from '@memberjunction/core-entities';
+import { WriteReturningVisitorRecap } from '../agentSessions/ReturningVisitorRecap.js';
+
+const USER = { ID: 'user-1' } as unknown as UserInfo;
+
+function makeProvider(): IMetadataProvider {
+    const conversation = {
+        ID: 'conv-1',
+        LinkedEntityID: 'entity-1',
+        LinkedRecordID: 'record-1',
+        VisitorKey: null,
+        Load: vi.fn().mockResolvedValue(true),
+    };
+    return {
+        Entities: [],
+        GetEntityObject: vi.fn().mockResolvedValue(conversation),
+    } as unknown as IMetadataProvider;
+}
+
+function detailView(): ViewCall | undefined {
+    return hoisted.views.find((v) => v.EntityName === 'MJ: Conversation Details');
+}
+
+describe('WriteReturningVisitorRecap — transcript scope', () => {
+    beforeEach(() => {
+        hoisted.views.length = 0;
+        hoisted.transcripts.length = 0;
+        hoisted.detailRows = [
+            { Role: 'AI', Message: 'second' },
+            { Role: 'User', Message: 'first' },
+        ];
+        hoisted.logError.mockReset();
+        hoisted.logStatus.mockReset();
+        hoisted.aiConfig.mockReset();
+    });
+
+    it('reads the newest turns in Main with the trunk predicate, in chronological order', async () => {
+        const provider = makeProvider();
+
+        await WriteReturningVisitorRecap('conv-1', 'agent-1', USER, provider);
+
+        const view = detailView();
+        expect(view?.ExtraFilter).toBe(ConversationEngine.LiveRowsFilter(ConversationEngine.ScopeFilter(ConversationEngine.TrunkScope('conv-1'))));
+        expect(view?.ExtraFilter).toBe("[ConversationID]='conv-1' AND [BranchID] IS NULL AND [ReplacedAt] IS NULL");
+        expect(view?.OrderBy).toBe('Sequence DESC');
+        expect(view?.MaxRows).toBe(60);
+        expect(hoisted.views.some((v) => v.EntityName === 'MJ: Conversation Branches' || v.EntityName === 'MJ: Conversations')).toBe(false);
+        expect(hoisted.transcripts).toEqual(['User: first\nAI: second']);
+    });
+});

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

@@ -0,0 +1,169 @@
+/**
+ * @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.
+ */
+import 'reflect-metadata'; // must precede any type-graphql decorator evaluation
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import type { PubSubEngine } from 'type-graphql';
+
+// type-graphql's real decorators need emitDecoratorMetadata, which vitest's esbuild transform
+// does not emit; the schema is irrelevant here, so every decorator is a no-op.
+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(() => ({
+    runAgentInConversation: vi.fn(),
+}));
+
+vi.mock('@memberjunction/ai-agents', () => ({
+    AgentRunner: class {
+        RunAgentInConversation(...args: unknown[]) {
+            return hoisted.runAgentInConversation(...args);
+        }
+    },
+    ArtifactToolManager: class {},
+}));
+
+vi.mock('../realtimeWidget/widgetGuestElevation.js', () => ({
+    ResolveWidgetGuestRunContext: vi.fn().mockResolvedValue(null),
+    ElevateUserPayload: vi.fn(),
+}));
+
+import { ConversationEngine } from '@memberjunction/core-entities';
+import { RunAIAgentResolver } from '../resolvers/RunAIAgentResolver.js';
+import type { AppContext, UserPayload } from '../types.js';
+
+const USER = { ID: 'user-1', Email: 'user@example.com' };
+
+type Fn = ReturnType<typeof vi.fn>;
+
+/** The private members this test reaches, through an explicit shape (no `any`). */
+interface ResolverSeams {
+    CheckAPIKeyScopeAuthorization: Fn;
+    GetUserFromPayload: Fn;
+    loadConversationHistoryWithAttachments: Fn;
+    executeAIAgent: Fn;
+    executeAgentInBackground: Fn;
+    loadInputArtifactsBatch: Fn;
+    validateAgent: Fn;
+    persistInFlightAgentFailure: Fn;
+}
+
+function makeResolver(): { resolver: RunAIAgentResolver; seams: ResolverSeams } {
+    const resolver = new RunAIAgentResolver();
+    const seams = resolver as unknown as ResolverSeams;
+    seams.CheckAPIKeyScopeAuthorization = vi.fn().mockResolvedValue(undefined);
+    seams.GetUserFromPayload = vi.fn().mockReturnValue(USER);
+    return { resolver, seams };
+}
+
+function makeContext(branchId: string | null): AppContext {
+    const provider = {
+        GetEntityObject: vi.fn().mockResolvedValue({
+            ConversationID: 'conv-1',
+            BranchID: branchId,
+            Load: vi.fn().mockResolvedValue(true),
+        }),
+    };
+    return {
+        userPayload: { sessionId: 'session-1', userRecord: USER } as unknown as UserPayload,
+        providers: [{ type: 'Read-Write', provider }],
+        dataSource: {},
+    } as unknown as AppContext;
+}
+
+const pubSub = { publish: vi.fn() } as unknown as PubSubEngine;
+
+async function runMutation(resolver: RunAIAgentResolver, branchId: string | null, fireAndForget?: boolean) {
+    return resolver.RunAIAgentFromConversationDetail(
+        'detail-1', 'agent-1', makeContext(branchId), 'session-1', pubSub,
+        undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined,
+        undefined, undefined, fireAndForget, undefined, undefined, undefined
+    );
+}
+
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+
+describe('RunAIAgentFromConversationDetail — branch', () => {
+    let resolver: RunAIAgentResolver;
+    let seams: ResolverSeams;
+
+    beforeEach(() => {
+        ({ resolver, seams } = makeResolver());
+        seams.loadConversationHistoryWithAttachments = vi.fn().mockResolvedValue([]);
+        seams.executeAIAgent = vi.fn().mockResolvedValue({ success: true, result: '{}' });
+        seams.executeAgentInBackground = vi.fn();
+    });
+
+    it('loads history on the placeholder row\'s branch 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');
+    });
+
+    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');
+    });
+
+    it('reads the trunk when the placeholder 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();
+    });
+});
+
+describe('loadConversationHistoryWithAttachments — branch', () => {
+    it('passes the branch to the fresh loader', async () => {
+        const { resolver, seams } = makeResolver();
+        seams.loadInputArtifactsBatch = vi.fn().mockResolvedValue(new Map());
+        const loadRows = vi.spyOn(ConversationEngine, 'LoadWindowRowsFresh').mockResolvedValue([]);
+        const provider = {};
+        const load = (resolver as unknown as {
+            loadConversationHistoryWithAttachments(
+                conversationId: string, user: unknown, max: number, provider: unknown,
+                exclude?: string[], historyFrom?: Date, branchId?: string | null
+            ): Promise<unknown[]>;
+        }).loadConversationHistoryWithAttachments.bind(resolver);
+        await load('conv-1', USER, 20, provider, ['detail-1'], undefined, 'branch-b');
+        expect(loadRows).toHaveBeenCalledWith('conv-1', USER, provider, undefined, 'branch-b');
+    });
+});
+
+describe('executeAIAgent — ConversationBranchID', () => {
+    it('puts the branch on the run\'s params, and leaves it unset for the trunk', async () => {
+        const { resolver, seams } = makeResolver();
+        seams.validateAgent = vi.fn().mockResolvedValue({ ID: 'agent-1', Name: 'Test Agent' });
+        seams.persistInFlightAgentFailure = vi.fn().mockResolvedValue(undefined);
+        hoisted.runAgentInConversation.mockReset().mockRejectedValue(new Error('stop here'));
+        vi.spyOn(console, 'error').mockImplementation(() => undefined);
+        vi.spyOn(console, 'log').mockImplementation(() => undefined);
+        const execute = (resolver as unknown as { executeAIAgent(...args: unknown[]): Promise<unknown> }).executeAIAgent.bind(resolver);
+        const userPayload = { sessionId: 'session-1', userRecord: USER };
+        const base = [
+            {}, {}, 'agent-1', userPayload, '[{"role":"user","content":"hi"}]', 'session-1', pubSub,
+            undefined, undefined, undefined, undefined, undefined, undefined, 'detail-1', false, false,
+            undefined, undefined, 'conv-1', undefined, undefined, undefined, undefined, undefined,
+        ];
+        await execute(...base, 'branch-b');
+        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(trunk).not.toHaveProperty('ConversationBranchID');
+    });
+});

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

@@ -124,7 +124,7 @@ describe('RunAIAgentFromConversationDetail — agentHistoryFrom', () => {
         expect(loaderArgs[0]).toBe('conv-1');
         expect(loaderArgs[4]).toEqual(['detail-1']);
         expect((loaderArgs[5] as Date).toISOString()).toBe(FLOOR_ISO);
-        const runFloor = seams.executeAIAgent.mock.calls[0].at(-1) as Date;
+        const runFloor = seams.executeAIAgent.mock.calls[0].at(-2) as Date;
         expect(runFloor.toISOString()).toBe(FLOOR_ISO);
     });
 
@@ -133,7 +133,7 @@ describe('RunAIAgentFromConversationDetail — agentHistoryFrom', () => {
 
         expect(result.success).toBe(true);
         expect(seams.executeAIAgent).not.toHaveBeenCalled();
-        const runFloor = seams.executeAgentInBackground.mock.calls[0].at(-1) as Date;
+        const runFloor = seams.executeAgentInBackground.mock.calls[0].at(-2) as Date;
         expect(runFloor.toISOString()).toBe(FLOOR_ISO);
     });
 
@@ -141,7 +141,7 @@ describe('RunAIAgentFromConversationDetail — agentHistoryFrom', () => {
         await runMutation(resolver, {});
 
         expect(seams.loadConversationHistoryWithAttachments.mock.calls[0][5]).toBeUndefined();
-        expect(seams.executeAIAgent.mock.calls[0].at(-1)).toBeUndefined();
+        expect(seams.executeAIAgent.mock.calls[0].at(-2)).toBeUndefined();
     });
 
     it('fails the request on an unreadable floor, before loading or running anything', async () => {
@@ -178,7 +178,7 @@ describe('loadConversationHistoryWithAttachments — history floor', () => {
         }).loadConversationHistoryWithAttachments.bind(resolver);
         await load('conv-1', USER, 20, provider, ['detail-1'], floor);
 
-        expect(loadRows).toHaveBeenCalledWith('conv-1', USER, provider, floor);
+        expect(loadRows).toHaveBeenCalledWith('conv-1', USER, provider, floor, undefined);
         expect(assemble.mock.calls[0][1]).toEqual({ maxTailMessages: 20, excludeDetailIds: ['detail-1'], historyFrom: floor });
     });
 });