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

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,6 +36,9 @@ vi.mock('@memberjunction/ai-agents', () => ({
         RunAgentInConversation(...args: unknown[]) {
             return hoisted.runAgentInConversation(...args);
         }
+        CreateAgentReplyDetail(...args: unknown[]) {
+            return hoisted.createAgentReplyDetail(...args);
+        }
     },
     ArtifactToolManager: class {},
 }));
@@ -70,11 +76,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 +94,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 +122,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();
     });
 });
 

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

@@ -0,0 +1,210 @@
+/**
+ * @fileoverview A widget guest's agent run executes as the system user, but the conversation belongs to the guest,
+ * and only the owner (or a grantee) may write a conversation's messages (MJConversationDetailEntityExtended, MJ#4791).
+ * So the resolver names the guest as `ConversationWriter`: AgentRunner then writes the reply as the guest and the
+ * run's own records as the system user. Before this, every reply save of a widget guest was refused and the widget
+ * never showed the agent's answer.
+ */
+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(),
+    createAgentReplyDetail: 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);
+        }
+        CreateAgentReplyDetail(...args: unknown[]) {
+            return hoisted.createAgentReplyDetail(...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.createAgentReplyDetail.mockReset().mockResolvedValue({ ID: 'reply-1', __mj_CreatedAt: new Date() });
+    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();
+});
+
+/** The options the n-th run was handed (the second argument of AgentRunner.RunAgentInConversation). */
+async function handedOptions(n = 0): Promise<{ ConversationWriter?: { ID: string } }> {
+    await vi.waitFor(() => expect(hoisted.runAgentInConversation.mock.calls.length).toBeGreaterThan(n));
+    return hoisted.runAgentInConversation.mock.calls[n][1] as { ConversationWriter?: { ID: string } };
+}
+
+describe('RunAIAgentFromConversationDetail — who writes the conversation', () => {
+    it('runs a widget guest as the system user but writes its conversation as the guest, on both paths', async () => {
+        const { resolver } = makeResolver();
+        hoisted.resolveWidgetGuestRunContext.mockResolvedValue({ ElevatedUser: SYSTEM_USER, Widget: {}, PinnedAgentId: 'pinned-agent' });
+        const ctx = makeContext({ email: GUEST.Email, userRecord: GUEST });
+
+        await runFromDetail(resolver, ctx);
+        await runFromDetail(resolver, ctx, true);
+
+        expect((await handedParams(0)).contextUser.ID).toBe(SYSTEM_USER.ID);
+        expect((await handedOptions(0)).ConversationWriter?.ID).toBe(GUEST.ID);
+        expect((await handedParams(1)).contextUser.ID).toBe(SYSTEM_USER.ID);
+        expect((await handedOptions(1)).ConversationWriter?.ID).toBe(GUEST.ID);
+        // The server-created reply row (A19) is written as the guest too, never as the elevated system user.
+        for (const [args] of hoisted.createAgentReplyDetail.mock.calls) {
+            expect((args as { contextUser: { ID: string } }).contextUser.ID).toBe(GUEST.ID);
+        }
+        expect(hoisted.createAgentReplyDetail).toHaveBeenCalledTimes(2);
+    });
+
+    it('refuses a widget guest on another visitor\'s conversation before any row is written (MJ#6032)', async () => {
+        const { resolver } = makeResolver();
+        hoisted.resolveWidgetGuestRunContext.mockResolvedValue({ ElevatedUser: SYSTEM_USER, Widget: {}, PinnedAgentId: 'pinned-agent' });
+        // The conversation is stamped sid-1; this guest's scope is sid-2, so the shared Anonymous user must not be
+        // enough. Without the AuthorizeConversationTurn gate the run would proceed and the reply row below be created.
+        const ctx = makeContext({ email: GUEST.Email, userRecord: { ...GUEST, AnonymousVisitorID: 'sid-2', MagicLinkScope: { ResourceID: 'sid-2' } } as UserPayload['userRecord'] });
+
+        const result = await runFromDetail(resolver, ctx);
+
+        expect(result.success).toBe(false);
+        expect(result.errorMessage).toContain('Not authorized: you do not own this conversation');
+        expect(hoisted.createAgentReplyDetail).not.toHaveBeenCalled();
+        expect(hoisted.runAgentInConversation).not.toHaveBeenCalled();
+    });
+
+    it('names no separate writer for an ordinary user (it runs and writes as itself)', async () => {
+        const { resolver } = makeResolver();
+
+        await runFromDetail(resolver, makeContext({}));
+
+        expect((await handedOptions()).ConversationWriter).toBeUndefined();
+        expect((await handedParams()).contextUser.ID).toBe(USER.ID);
+    });
+});

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,8 +112,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;
+    /** 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());
@@ -124,7 +128,7 @@ 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(FLOOR_ARG) as Date;
         expect(runFloor.toISOString()).toBe(FLOOR_ISO);
@@ -290,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;
@@ -306,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 () => {