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

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

@@ -0,0 +1,209 @@
+/**
+ * @fileoverview A fire-and-forget run always ends with one completion on the caller's socket.
+ *
+ * The widget and Explorer return as soon as the mutation acks, then wait for a `complete` status message. When the
+ * run fails (the agent cannot be validated, the run throws, or the agent's reply row cannot be saved), that message
+ * must still arrive, exactly once, with the reason, addressed to the owner the caller's socket is authenticated as.
+ * For a widget guest that is the guest, not the system user its run is elevated to. Without it the client waits for
+ * its idle timeout and then reconciles the run as a success.
+ *
+ * The liveness pulse of the same run is addressed to the same owner.
+ */
+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';
+
+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(),
+    agents: new Map<string, { ID: string; Name: string; Status: string }>(),
+}));
+
+vi.mock('@memberjunction/aiengine', () => ({
+    AIEngine: {
+        Instance: {
+            Config: async () => undefined,
+            GetAgentByID: (id: string) => hoisted.agents.get(id),
+            CanUserRunAgent: async () => true,
+        },
+    },
+    GetAttachmentService: () => ({}),
+}));
+
+vi.mock('@memberjunction/ai-agents', () => ({
+    AgentRunner: class {
+        RunAgentInConversation(...args: unknown[]) {
+            return hoisted.runAgentInConversation(...args);
+        }
+    },
+    ArtifactToolManager: class {},
+}));
+
+import { UserInfo } from '@memberjunction/core';
+import { RunAIAgentResolver } from '../resolvers/RunAIAgentResolver.js';
+import { StatusUpdateOwnerID } from '../generic/PushStatusResolver.js';
+import { DEFAULT_PULSE_INTERVAL_MS, HEARTBEAT_MESSAGE_TYPE } from '../generic/FireAndForgetHeartbeat.js';
+import type { AppContext, UserPayload } from '../types.js';
+
+const ANONYMOUS_USER_ID = 'AAAAAAAA-0000-4000-8000-0000000000A0';
+const SYSTEM_USER_ID = 'BBBBBBBB-0000-4000-8000-0000000000B0';
+const SESSION = 'session-1';
+
+/** A public-widget guest: the shared Anonymous user, told apart by its scope identity. */
+function widgetGuest(): UserInfo {
+    const guest = new UserInfo(null, { ID: ANONYMOUS_USER_ID, Email: 'anonymous@magic-link.local' });
+    guest.IsMagicLinkAnonymous = true;
+    guest.AnonymousVisitorID = 'sid-guest-1';
+    return guest;
+}
+
+/** The payload a widget guest's run executes under: elevated to the system user, standing in for the guest. */
+function elevatedGuestPayload(): UserPayload {
+    return {
+        sessionId: SESSION,
+        email: 'system@example.com',
+        userRecord: new UserInfo(null, { ID: SYSTEM_USER_ID, Email: 'system@example.com' }),
+        ElevatedFrom: widgetGuest(),
+    };
+}
+
+interface PublishedEnvelope {
+    sessionId: string;
+    ownerUserId: string;
+    message: { resolver: string; type: string; data: Record<string, unknown> };
+}
+
+function makePubSub(): { pubSub: PubSubEngine; published: () => PublishedEnvelope[] } {
+    const publish = vi.fn().mockResolvedValue(undefined);
+    const pubSub: PubSubEngine = { publish, subscribe: vi.fn(), unsubscribe: vi.fn(), asyncIterator: vi.fn() };
+    const published = (): PublishedEnvelope[] =>
+        publish.mock.calls.map((call) => {
+            const payload = call[1] as { sessionId: string; ownerUserId: string; message: string };
+            return { sessionId: payload.sessionId, ownerUserId: payload.ownerUserId, message: JSON.parse(payload.message) };
+        });
+    return { pubSub, published };
+}
+
+function completions(envelopes: PublishedEnvelope[]): PublishedEnvelope[] {
+    return envelopes.filter((e) => e.message.type === 'StreamingContent' && e.message.data.type === 'complete');
+}
+
+/** Starts the public RunAIAgent mutation in fire-and-forget mode for `agentId`, answering into `reply-1`. */
+async function startFireAndForget(pubSub: PubSubEngine, userPayload: UserPayload, agentId = 'agent-1') {
+    const ctx = { userPayload, providers: [], dataSource: {} } as AppContext;
+    return new RunAIAgentResolver().RunAIAgent(
+        agentId, ctx, '[{"role":"user","content":"hi"}]', SESSION, pubSub,
+        undefined, undefined, undefined, undefined, undefined, undefined,
+        'reply-1', // conversationDetailId
+        undefined, undefined, undefined, undefined,
+        true, // fireAndForget
+    );
+}
+
+/** Lets the background run settle, then gives any late (double) publish a chance to land. */
+async function settle(published: () => PublishedEnvelope[]): Promise<void> {
+    await vi.waitFor(() => expect(completions(published()).length).toBeGreaterThan(0), { timeout: 1000 });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+}
+
+beforeEach(() => {
+    hoisted.agents.clear();
+    hoisted.agents.set('agent-1', { ID: 'agent-1', Name: 'Research', Status: 'Active' });
+    hoisted.runAgentInConversation.mockReset();
+    vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+});
+
+afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+});
+
+describe('RunAIAgent fire-and-forget — the failure completion', () => {
+    it("publishes one failed completion with the reason when the agent's reply cannot be saved, to the guest's socket", async () => {
+        const reason = "The agent's reply could not be saved: Message exceeds the maximum length";
+        hoisted.runAgentInConversation.mockRejectedValue(new Error(reason));
+        const { pubSub, published } = makePubSub();
+        const userPayload = elevatedGuestPayload();
+
+        const ack = await startFireAndForget(pubSub, userPayload);
+        expect(ack.success).toBe(true); // the ack only says the run started
+
+        await settle(published);
+        const done = completions(published());
+        expect(done).toHaveLength(1);
+        expect(done[0].message.data).toMatchObject({
+            type: 'complete',
+            success: false,
+            errorMessage: reason,
+            conversationDetailId: 'reply-1',
+        });
+        expect(done[0].sessionId).toBe(SESSION);
+        // The guest's owner key, never the system user the run was elevated to.
+        expect(done[0].ownerUserId).toBe(StatusUpdateOwnerID(userPayload));
+        expect(done[0].ownerUserId).toBe(`${ANONYMOUS_USER_ID.toLowerCase()}|sid-guest-1`);
+    });
+
+    it('publishes one failed completion when the run fails before the agent starts (agent not runnable)', async () => {
+        const { pubSub, published } = makePubSub();
+
+        await startFireAndForget(pubSub, elevatedGuestPayload(), 'missing-agent');
+
+        await settle(published);
+        const done = completions(published());
+        expect(done).toHaveLength(1);
+        expect(done[0].message.data).toMatchObject({
+            success: false,
+            errorMessage: 'AI Agent with ID missing-agent not found',
+            conversationDetailId: 'reply-1',
+        });
+        expect(hoisted.runAgentInConversation).not.toHaveBeenCalled();
+    });
+
+    it('publishes only the run\'s own completion when the run returns a failed result (no second completion)', async () => {
+        const run = { ID: 'run-1', ConversationDetailID: 'reply-1', ErrorMessage: 'model refused', Steps: [] };
+        hoisted.runAgentInConversation.mockResolvedValue({
+            agentResult: { success: false, agentRun: run },
+            agentResponseDetailId: 'reply-1',
+            conversationId: 'conv-1',
+        });
+        const { pubSub, published } = makePubSub();
+
+        await startFireAndForget(pubSub, elevatedGuestPayload());
+
+        await settle(published);
+        const done = completions(published());
+        expect(done).toHaveLength(1);
+        expect(done[0].message.data).toMatchObject({ agentRunId: 'run-1', success: false, errorMessage: 'model refused' });
+    });
+});
+
+describe("RunAIAgent fire-and-forget — the liveness pulse", () => {
+    it("addresses heartbeats to the guest's owner key, not to the elevated system user", async () => {
+        vi.useFakeTimers();
+        hoisted.runAgentInConversation.mockReturnValue(new Promise(() => undefined)); // the run is still going
+        const { pubSub, published } = makePubSub();
+        const userPayload = elevatedGuestPayload();
+
+        await startFireAndForget(pubSub, userPayload);
+        await vi.advanceTimersByTimeAsync(DEFAULT_PULSE_INTERVAL_MS);
+
+        const heartbeats = published().filter((e) => e.message.type === HEARTBEAT_MESSAGE_TYPE);
+        expect(heartbeats.length).toBeGreaterThan(0);
+        for (const heartbeat of heartbeats) {
+            expect(heartbeat.ownerUserId).toBe(StatusUpdateOwnerID(userPayload));
+            expect(heartbeat.ownerUserId).not.toBe(SYSTEM_USER_ID);
+        }
+    });
+});

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

@@ -28,6 +28,7 @@ vi.mock('type-graphql', () => {
 
 const hoisted = vi.hoisted(() => ({
     runAgentInConversation: vi.fn(),
+    reply: { ID: 'reply-1', ConversationID: 'conv-1', __mj_CreatedAt: new Date('2026-10-12T10:00:00.000Z') },
 }));
 
 vi.mock('@memberjunction/ai-agents', () => ({
@@ -35,6 +36,9 @@ vi.mock('@memberjunction/ai-agents', () => ({
         RunAgentInConversation(...args: unknown[]) {
             return hoisted.runAgentInConversation(...args);
         }
+        async CreateAgentReplyDetail() {
+            return hoisted.reply;
+        }
     },
     ArtifactToolManager: class {},
 }));
@@ -94,7 +98,7 @@ async function runMutation(
     options: { agentHistoryFrom?: string; fireAndForget?: boolean }
 ) {
     return resolver.RunAIAgentFromConversationDetail(
-        'detail-1', 'agent-1', makeContext(), 'session-1', pubSub,
+        'user-msg-1', 'agent-1', makeContext(), 'session-1', pubSub,
         undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined,
         undefined, undefined, options.fireAndForget, undefined, undefined,
         options.agentHistoryFrom
@@ -108,6 +112,8 @@ afterEach(() => {
 describe('RunAIAgentFromConversationDetail — agentHistoryFrom', () => {
     let resolver: RunAIAgentResolver;
     let seams: ResolverSeams;
+    /** The floor's position in executeAIAgent / executeAgentInBackground: fourth from last, before TrustReservedRunData, the branch, and the reply detail. */
+    const FLOOR_ARG = -4;
 
     beforeEach(() => {
         ({ resolver, seams } = makeResolver());
@@ -122,9 +128,9 @@ describe('RunAIAgentFromConversationDetail — agentHistoryFrom', () => {
         expect(result.success).toBe(true);
         const loaderArgs = seams.loadConversationHistoryWithAttachments.mock.calls[0];
         expect(loaderArgs[0]).toBe('conv-1');
-        expect(loaderArgs[4]).toEqual(['detail-1']);
+        expect(loaderArgs[4]).toBeUndefined(); // the reply row is created after the history loads, so nothing to exclude
         expect((loaderArgs[5] as Date).toISOString()).toBe(FLOOR_ISO);
-        const runFloor = seams.executeAIAgent.mock.calls[0].at(-2) as Date;
+        const runFloor = seams.executeAIAgent.mock.calls[0].at(FLOOR_ARG) as Date;
         expect(runFloor.toISOString()).toBe(FLOOR_ISO);
     });
 
@@ -133,7 +139,7 @@ describe('RunAIAgentFromConversationDetail — agentHistoryFrom', () => {
 
         expect(result.success).toBe(true);
         expect(seams.executeAIAgent).not.toHaveBeenCalled();
-        const runFloor = seams.executeAgentInBackground.mock.calls[0].at(-2) as Date;
+        const runFloor = seams.executeAgentInBackground.mock.calls[0].at(FLOOR_ARG) as Date;
         expect(runFloor.toISOString()).toBe(FLOOR_ISO);
     });
 
@@ -141,7 +147,7 @@ describe('RunAIAgentFromConversationDetail — agentHistoryFrom', () => {
         await runMutation(resolver, {});
 
         expect(seams.loadConversationHistoryWithAttachments.mock.calls[0][5]).toBeUndefined();
-        expect(seams.executeAIAgent.mock.calls[0].at(-2)).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 () => {
@@ -288,10 +294,13 @@ describe('executeAIAgent — status publishing', () => {
         expect(completion.success).toBe(true);
     });
 
-    it('publishes a failure completion when a fire-and-forget run rejects', async () => {
+    it('logs a fire-and-forget run that rejects, and publishes no second completion', async () => {
+        // executeAIAgent resolves on every failure and publishes the failure completion itself
+        // (RunAIAgentResolver.fireAndForgetCompletion.test.ts). A rejection breaks that contract; the background
+        // runner only logs it, with the agent and session, instead of leaving an unhandled rejection.
         const { resolver, seams } = makeResolver();
         seams.executeAIAgent = vi.fn().mockRejectedValue(new Error('background blew up'));
-        vi.spyOn(console, 'error').mockImplementation(() => undefined);
+        const errors = vi.spyOn(console, 'error').mockImplementation(() => undefined);
         vi.spyOn(console, 'log').mockImplementation(() => undefined);
         const publish = vi.fn().mockResolvedValue(undefined);
         const localPubSub = { publish } as unknown as PubSubEngine;
@@ -304,28 +313,11 @@ describe('executeAIAgent — status publishing', () => {
             {}, {}, 'agent-1', userPayload, '[]', 'session-1', localPubSub,
             undefined, undefined, undefined, undefined, undefined, 'detail-1',
         );
-        await vi.waitFor(() => expect(publish).toHaveBeenCalled());
+        await vi.waitFor(() =>
+            expect(errors.mock.calls.some((call) => String(call[0]).includes('agent-1') && String(call[0]).includes('session-1'))).toBe(true),
+        );
 
-        const sent = envelopes(publish);
-        expect(sent).toHaveLength(1);
-        expect(sent[0].type).toBe('StreamingContent');
-        expect(sent[0].resolver).toBe('RunAIAgentResolver');
-        const completion = sent[0].data as {
-            type: string;
-            agentRunId: string;
-            conversationDetailId: string;
-            success: boolean;
-            errorMessage: string;
-            result: string;
-        };
-        expect(completion).toMatchObject({
-            type: 'complete',
-            agentRunId: 'unknown',
-            conversationDetailId: 'detail-1',
-            success: false,
-            errorMessage: 'background blew up',
-            result: JSON.stringify({ success: false, errorMessage: 'background blew up' }),
-        });
+        expect(publish).not.toHaveBeenCalled();
     });
 
     it('saves a Running run reported by progress as Failed when the agent throws', async () => {

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

@@ -0,0 +1,264 @@
+/**
+ * @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 {
+        async CreateAgentReplyDetail() {
+            return { ID: 'reply-1', __mj_CreatedAt: new Date() };
+        }
+        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' };
+// A widget guest always carries its per-visitor scope id (mj_sid) as its MagicLinkScope.ResourceID, and its
+// conversation is stamped with the same value as ExternalID: that stamp is what tells one guest from another
+// under the shared Anonymous user (MJ#6032), so the fake conversation below carries it.
+const GUEST = { ID: 'guest-1', Email: 'anonymous@magic-link.local', IsMagicLinkAnonymous: true, AnonymousVisitorID: 'sid-1', MagicLinkScope: { ResourceID: 'sid-1' } };
+
+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', UserID: GUEST.ID, ExternalID: 'sid-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));
+    });
+});