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

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

@@ -0,0 +1,170 @@
+/**
+ * @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,
+            false, // trustReservedRunData
+        ];
+        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

@@ -108,6 +108,8 @@ afterEach(() => {
 describe('RunAIAgentFromConversationDetail — agentHistoryFrom', () => {
     let resolver: RunAIAgentResolver;
     let seams: ResolverSeams;
+    /** The floor's position in executeAIAgent / executeAgentInBackground: third from last, before TrustReservedRunData and the branch. */
+    const FLOOR_ARG = -3;
 
     beforeEach(() => {
         ({ resolver, seams } = makeResolver());
@@ -124,7 +126,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(FLOOR_ARG) as Date;
         expect(runFloor.toISOString()).toBe(FLOOR_ISO);
     });
 
@@ -133,7 +135,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(FLOOR_ARG) as Date;
         expect(runFloor.toISOString()).toBe(FLOOR_ISO);
     });
 
@@ -141,7 +143,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(FLOOR_ARG)).toBeUndefined();
     });
 
     it('fails the request on an unreadable floor, before loading or running anything', async () => {
@@ -178,7 +180,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 });
     });
 });

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

@@ -0,0 +1,258 @@
+/**
+ * @fileoverview Every agent-run entry of `RunAIAgentResolver` tells the run whether it may read the reserved scope
+ * and agent-type keys from a client's `data` (`ExecuteAgentParams.TrustReservedRunData`, A12.15).
+ *
+ * The decision is pinned by `agent-run-data-guard.test.ts`, and what an untrusted run loses by the ai-core-plus and
+ * ai-agents suites (`BaseAgent.Execute` drops the keys). These tests pin the call sites: the synchronous and
+ * fire-and-forget paths of `RunAIAgent` and `RunAIAgentFromConversationDetail`, the widget-guest path (judged on
+ * the guest's own payload, not the system principal it is elevated to), the trusted callers, and an API key with and
+ * without the `agent:trusted` scope — each through the real `executeAIAgent`, up to the params handed to
+ * `AgentRunner`. The resolver forwards `data` as sent.
+ */
+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(),
+    resolveWidgetGuestRunContext: vi.fn(),
+    authorize: vi.fn(),
+}));
+
+// Only the key engine is stubbed: Authorize allows `agent:trusted` for the key whose hash is 'hash-trusted'.
+vi.mock('@memberjunction/api-keys', async (importOriginal) => ({
+    ...(await importOriginal<typeof import('@memberjunction/api-keys')>()),
+    GetAPIKeyEngine: () => ({ Authorize: hoisted.authorize }),
+}));
+
+vi.mock('@memberjunction/ai-agents', () => ({
+    AgentRunner: class {
+        RunAgentInConversation(...args: unknown[]) {
+            return hoisted.runAgentInConversation(...args);
+        }
+    },
+    ArtifactToolManager: class {},
+}));
+
+// Only the widget lookup is stubbed; ElevateUserPayload is the real one, so the widget-guest test runs
+// against the elevated system-user payload the resolver really builds.
+vi.mock('../realtimeWidget/widgetGuestElevation.js', async (importOriginal) => ({
+    ...(await importOriginal<typeof import('../realtimeWidget/widgetGuestElevation.js')>()),
+    ResolveWidgetGuestRunContext: hoisted.resolveWidgetGuestRunContext,
+}));
+
+import { UserCache } from '@memberjunction/generic-database-provider';
+import type { UserInfo } from '@memberjunction/core';
+import { RunAIAgentResolver } from '../resolvers/RunAIAgentResolver.js';
+import type { AppContext, UserPayload } from '../types.js';
+
+const SCOPE_RECORD_ID = 'B1A2C3D4-0000-4000-8000-00000000A115';
+const ORDINARY = { conversationId: 'conv-1', latestMessageId: 'detail-1', invocationReason: 'user-message' };
+const CLIENT_DATA = JSON.stringify({
+    ...ORDINARY,
+    PrimaryScopeRecordID: SCOPE_RECORD_ID,
+    PrimaryScopeEntityName: 'MJ: Companies',
+    SecondaryScopes: { TeamID: 'team-other' },
+    __agentTypePromptParams: { enableTaskGraphs: true },
+});
+
+const USER = { ID: 'user-1', Email: 'browser.user@example.com' };
+const SYSTEM_USER = { ID: 'system-user', Email: 'system@example.com' };
+const GUEST = { ID: 'guest-1', Email: 'anonymous@magic-link.local', IsMagicLinkAnonymous: true };
+
+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;
+    validateAgent: Fn;
+    persistInFlightAgentFailure: Fn;
+}
+
+const pubSub = { publish: vi.fn().mockResolvedValue(undefined) } as unknown as PubSubEngine;
+
+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((payload: UserPayload) => payload.userRecord);
+    seams.loadConversationHistoryWithAttachments = vi.fn().mockResolvedValue([{ role: 'user', content: 'hi' }]);
+    seams.validateAgent = vi.fn().mockResolvedValue({ ID: 'agent-1', Name: 'Test Agent' });
+    seams.persistInFlightAgentFailure = vi.fn().mockResolvedValue(undefined);
+    return { resolver, seams };
+}
+
+function makeContext(userPayload: Partial<UserPayload>): AppContext {
+    const provider = {
+        GetEntityObject: vi.fn().mockResolvedValue({ ConversationID: 'conv-1', Load: vi.fn().mockResolvedValue(true) }),
+    };
+    return {
+        userPayload: { sessionId: 'session-1', email: USER.Email, userRecord: USER, ...userPayload } as UserPayload,
+        providers: [{ type: 'Read-Write', provider }],
+        dataSource: {},
+    } as unknown as AppContext;
+}
+
+/** The params the n-th run was handed by the real executeAIAgent (what AgentRunner.RunAgentInConversation received). */
+interface HandedParams {
+    data: Record<string, unknown>;
+    TrustReservedRunData?: boolean;
+    contextUser: { ID: string };
+}
+
+/** Waits for the n-th run to start (the fire-and-forget path starts it after the resolver has returned). */
+async function handedParams(n = 0): Promise<HandedParams> {
+    await vi.waitFor(() => expect(hoisted.runAgentInConversation.mock.calls.length).toBeGreaterThan(n));
+    return hoisted.runAgentInConversation.mock.calls[n][0] as HandedParams;
+}
+
+function runAIAgent(resolver: RunAIAgentResolver, ctx: AppContext, fireAndForget?: boolean) {
+    return resolver.RunAIAgent(
+        'agent-1', ctx, '[{"role":"user","content":"hi"}]', 'session-1', pubSub, CLIENT_DATA,
+        undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined,
+        fireAndForget
+    );
+}
+
+function runFromDetail(resolver: RunAIAgentResolver, ctx: AppContext, fireAndForget?: boolean) {
+    return resolver.RunAIAgentFromConversationDetail(
+        'detail-1', 'agent-1', ctx, 'session-1', pubSub, undefined, CLIENT_DATA,
+        undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, fireAndForget
+    );
+}
+
+beforeEach(() => {
+    hoisted.resolveWidgetGuestRunContext.mockReset().mockResolvedValue(null);
+    // Stop right after the run's params are captured — the rest of the run is out of scope.
+    hoisted.runAgentInConversation.mockReset().mockRejectedValue(new Error('stop here'));
+    hoisted.authorize.mockReset().mockImplementation(async (apiKeyHash: string, _app: string, scopePath: string) =>
+        apiKeyHash === 'hash-trusted' && scopePath === 'agent:trusted'
+            ? { Allowed: true, MatchedKeyRule: { ScopePath: scopePath }, EvaluatedRules: [] }
+            : { Allowed: false, Reason: 'No matching key scope rules', EvaluatedRules: [] });
+    vi.spyOn(UserCache.Instance, 'GetSystemUser').mockReturnValue(SYSTEM_USER as UserInfo);
+    vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+});
+
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+
+describe('RunAIAgent — reserved run-data keys', () => {
+    it('marks the run untrusted for an interactive user and forwards data as sent', async () => {
+        const { resolver } = makeResolver();
+
+        await runAIAgent(resolver, makeContext({}));
+
+        const params = await handedParams();
+        expect(params.TrustReservedRunData).toBe(false);
+        expect(params.data).toEqual(JSON.parse(CLIENT_DATA));
+    });
+
+    it('marks it untrusted on the fire-and-forget path too', async () => {
+        const { resolver } = makeResolver();
+
+        await runAIAgent(resolver, makeContext({}), true);
+
+        expect((await handedParams()).TrustReservedRunData).toBe(false);
+    });
+
+    it('marks it trusted for an API key holding agent:trusted, on both paths', async () => {
+        const { resolver } = makeResolver();
+        const ctx = makeContext({ apiKeyId: 'key-1', apiKeyHash: 'hash-trusted' });
+
+        await runAIAgent(resolver, ctx);
+        await runAIAgent(resolver, ctx, true);
+
+        expect((await handedParams(0)).TrustReservedRunData).toBe(true);
+        expect((await handedParams(1)).TrustReservedRunData).toBe(true);
+    });
+
+    it('marks it untrusted for an API key without agent:trusted, on both paths', async () => {
+        const { resolver } = makeResolver();
+        const ctx = makeContext({ apiKeyId: 'key-2', apiKeyHash: 'hash-plain' });
+
+        await runAIAgent(resolver, ctx);
+        await runAIAgent(resolver, ctx, true);
+
+        expect((await handedParams(0)).TrustReservedRunData).toBe(false);
+        expect((await handedParams(1)).TrustReservedRunData).toBe(false);
+    });
+});
+
+describe('RunAIAgentFromConversationDetail — reserved run-data keys', () => {
+    it('marks the run untrusted for an interactive user on both paths', async () => {
+        const { resolver } = makeResolver();
+
+        await runFromDetail(resolver, makeContext({}));
+        await runFromDetail(resolver, makeContext({}), true);
+
+        expect((await handedParams(0)).TrustReservedRunData).toBe(false);
+        expect((await handedParams(1)).TrustReservedRunData).toBe(false);
+    });
+
+    it('marks a widget-guest run untrusted although it executes as the system user', async () => {
+        const { resolver } = makeResolver();
+        hoisted.resolveWidgetGuestRunContext.mockResolvedValue({
+            ElevatedUser: SYSTEM_USER,
+            Widget: {},
+            PinnedAgentId: 'pinned-agent',
+        });
+
+        await runFromDetail(resolver, makeContext({ email: GUEST.Email, userRecord: GUEST }));
+
+        const params = await handedParams();
+        expect(params.contextUser.ID).toBe(SYSTEM_USER.ID); // the premise: the run is elevated
+        expect(params.TrustReservedRunData).toBe(false);
+    });
+
+    it('marks it trusted for the system user, on both paths', async () => {
+        const { resolver } = makeResolver();
+        const ctx = makeContext({ isSystemUser: true, email: SYSTEM_USER.Email, userRecord: SYSTEM_USER });
+
+        await runFromDetail(resolver, ctx);
+        await runFromDetail(resolver, ctx, true);
+
+        expect((await handedParams(0)).TrustReservedRunData).toBe(true);
+        expect((await handedParams(1)).TrustReservedRunData).toBe(true);
+    });
+
+    it('marks it trusted for an API key holding agent:trusted, and untrusted for one without', async () => {
+        const { resolver } = makeResolver();
+
+        await runFromDetail(resolver, makeContext({ apiKeyId: 'key-1', apiKeyHash: 'hash-trusted' }));
+        await runFromDetail(resolver, makeContext({ apiKeyId: 'key-2', apiKeyHash: 'hash-plain' }));
+
+        expect((await handedParams(0)).TrustReservedRunData).toBe(true);
+        expect((await handedParams(1)).TrustReservedRunData).toBe(false);
+    });
+});
+
+describe('RunAIAgentSystemUser — reserved run-data keys', () => {
+    it('marks the run trusted for the system user it admits, and forwards data as sent', async () => {
+        const { resolver } = makeResolver();
+        const ctx = makeContext({ isSystemUser: true, email: SYSTEM_USER.Email, userRecord: SYSTEM_USER });
+
+        await resolver.RunAIAgentSystemUser('agent-1', ctx, '[]', 'session-1', pubSub, CLIENT_DATA);
+
+        const params = await handedParams();
+        expect(params.TrustReservedRunData).toBe(true);
+        expect(params.data).toEqual(JSON.parse(CLIENT_DATA));
+    });
+});

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

@@ -0,0 +1,166 @@
+/**
+ * @fileoverview Continuing from a user-stopped run on `RunAIAgentFromConversationDetail`.
+ *
+ * The chat client never sends `lastRunId`, so the turn after a Stop used to start a fresh,
+ * unchained run. The mutation now looks for a user-stopped newest root run for the agent in the
+ * conversation and, when it finds one, chains the new run to it by LastRunID and rolls its
+ * FinalPayload in when the caller supplied no payload. These tests pin that on both dispatch
+ * paths, that a caller-supplied lastRunId wins, and that no predecessor changes nothing.
+ * Harness as in `RunAIAgentResolver.historyFrom.test.ts`.
+ */
+import 'reflect-metadata';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import type { PubSubEngine } from 'type-graphql';
+
+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]));
+});
+
+vi.mock('@memberjunction/ai-agents', () => ({
+    AgentRunner: class {
+        RunAgentInConversation() {
+            return Promise.resolve({ agentResult: { success: true } });
+        }
+    },
+    ArtifactToolManager: class {},
+}));
+
+vi.mock('../realtimeWidget/widgetGuestElevation.js', () => ({
+    ResolveWidgetGuestRunContext: vi.fn().mockResolvedValue(null),
+    ElevateUserPayload: vi.fn(),
+}));
+
+import { RunAIAgentResolver } from '../resolvers/RunAIAgentResolver.js';
+import type { AppContext, UserPayload } from '../types.js';
+
+const USER = { ID: 'user-1', Email: 'user@example.com' };
+const STOPPED_RUN = '16787b44-29f6-44a5-8bd4-fc1538e79275';
+
+type Fn = ReturnType<typeof vi.fn>;
+
+interface ResolverSeams {
+    CheckAPIKeyScopeAuthorization: Fn;
+    GetUserFromPayload: Fn;
+    loadConversationHistoryWithAttachments: Fn;
+    executeAIAgent: Fn;
+    executeAgentInBackground: Fn;
+    findUserStoppedPredecessorRunId: Fn;
+}
+
+/** Argument positions of lastRunId / autoPopulateLastRunPayload on the two dispatch seams. */
+const SYNC_LAST_RUN = 10, SYNC_AUTO = 11, BG_LAST_RUN = 9, BG_AUTO = 10;
+
+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);
+    seams.loadConversationHistoryWithAttachments = vi.fn().mockResolvedValue([]);
+    seams.executeAIAgent = vi.fn().mockResolvedValue({ success: true, result: '{}' });
+    seams.executeAgentInBackground = vi.fn();
+    seams.findUserStoppedPredecessorRunId = vi.fn().mockResolvedValue(null);
+    return { resolver, seams };
+}
+
+function makeContext(branchId: string | null = 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,
+    options: { payload?: string; lastRunId?: string; autoPopulate?: boolean; fireAndForget?: boolean; branchId?: string | null }
+) {
+    return resolver.RunAIAgentFromConversationDetail(
+        'detail-1', 'agent-1', makeContext(options.branchId ?? null), 'session-1', pubSub,
+        undefined, undefined, options.payload, options.lastRunId, options.autoPopulate, undefined, undefined, undefined,
+        undefined, undefined, options.fireAndForget, undefined, undefined,
+        undefined
+    );
+}
+
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+
+describe('RunAIAgentFromConversationDetail — continuing from a user-stopped run', () => {
+    let resolver: RunAIAgentResolver;
+    let seams: ResolverSeams;
+
+    beforeEach(() => {
+        ({ resolver, seams } = makeResolver());
+    });
+
+    it('chains the new run to the stopped predecessor and rolls its payload in when none was supplied', async () => {
+        seams.findUserStoppedPredecessorRunId.mockResolvedValue(STOPPED_RUN);
+
+        const result = await runMutation(resolver, {});
+
+        expect(result.success).toBe(true);
+        expect(seams.findUserStoppedPredecessorRunId).toHaveBeenCalledWith('conv-1', 'agent-1', null, USER, expect.anything());
+        const args = seams.executeAIAgent.mock.calls[0];
+        expect(args[SYNC_LAST_RUN]).toBe(STOPPED_RUN);
+        expect(args[SYNC_AUTO]).toBe(true);
+    });
+
+    it('keeps the caller\'s payload as the start when one was supplied (chains, but does not roll the old one in)', async () => {
+        seams.findUserStoppedPredecessorRunId.mockResolvedValue(STOPPED_RUN);
+
+        await runMutation(resolver, { payload: '{"fromArtifact":true}' });
+
+        const args = seams.executeAIAgent.mock.calls[0];
+        expect(args[SYNC_LAST_RUN]).toBe(STOPPED_RUN);
+        expect(args[SYNC_AUTO]).toBeUndefined();
+    });
+
+    it('hands the chain to a fire-and-forget run too', async () => {
+        seams.findUserStoppedPredecessorRunId.mockResolvedValue(STOPPED_RUN);
+
+        await runMutation(resolver, { fireAndForget: true });
+
+        expect(seams.executeAIAgent).not.toHaveBeenCalled();
+        const args = seams.executeAgentInBackground.mock.calls[0];
+        expect(args[BG_LAST_RUN]).toBe(STOPPED_RUN);
+        expect(args[BG_AUTO]).toBe(true);
+    });
+
+    it('looks up the predecessor on the branch the reply row was created on', async () => {
+        await runMutation(resolver, { branchId: 'B' });
+        expect(seams.findUserStoppedPredecessorRunId).toHaveBeenCalledWith('conv-1', 'agent-1', 'B', expect.anything(), expect.anything());
+        await runMutation(resolver, {});
+        expect(seams.findUserStoppedPredecessorRunId).toHaveBeenLastCalledWith('conv-1', 'agent-1', null, expect.anything(), expect.anything());
+    });
+
+    it('a caller-supplied lastRunId wins and the lookup is skipped', async () => {
+        await runMutation(resolver, { lastRunId: 'caller-run', autoPopulate: false });
+
+        expect(seams.findUserStoppedPredecessorRunId).not.toHaveBeenCalled();
+        const args = seams.executeAIAgent.mock.calls[0];
+        expect(args[SYNC_LAST_RUN]).toBe('caller-run');
+        expect(args[SYNC_AUTO]).toBe(false);
+    });
+
+    it('with no stopped predecessor the run is dispatched unchained, as before', async () => {
+        await runMutation(resolver, {});
+
+        const args = seams.executeAIAgent.mock.calls[0];
+        expect(args[SYNC_LAST_RUN]).toBeUndefined();
+        expect(args[SYNC_AUTO]).toBeUndefined();
+    });
+});