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

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);
+        }
+    });
+});