@memberjunction/server 5.43.0 → 5.44.0

package/src/__tests__/MediaStreamHandler.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect } from 'vitest';
+import { parseRangeHeaderLoose, parseRange } from '../rest/mediaRange.js';
+
+/**
+ * Tests for the pure HTTP-Range parsing helpers behind the authenticated `/media/:fileId`
+ * stream route. They decide whether a request gets a 206 partial body (and over which byte
+ * window) or a 200/416 — the load-bearing logic for native `<audio>`/`<video>` seeking. Both
+ * helpers are deliberately strict: anything malformed/multi-range yields `undefined` so the
+ * handler falls back to a full read (streaming path) or a 416 (buffer path).
+ *
+ *  - `parseRangeHeaderLoose` — streaming path, NO known total: open-ended `bytes=start-` leaves
+ *    `end` undefined so the driver streams to EOF.
+ *  - `parseRange` — buffer path WITH a known total: clamps `end` to the last byte and rejects
+ *    unsatisfiable ranges (start past EOF) so the caller returns 416.
+ */
+
+describe('parseRangeHeaderLoose (streaming path — no known total)', () => {
+    it('parses a closed range bytes=start-end into inclusive offsets', () => {
+        expect(parseRangeHeaderLoose('bytes=0-499')).toEqual({ start: 0, end: 499 });
+        expect(parseRangeHeaderLoose('bytes=200-1023')).toEqual({ start: 200, end: 1023 });
+    });
+
+    it('leaves end undefined for an open-ended range bytes=start- (stream to EOF)', () => {
+        expect(parseRangeHeaderLoose('bytes=500-')).toEqual({ start: 500 });
+        expect(parseRangeHeaderLoose('bytes=0-')).toEqual({ start: 0 });
+    });
+
+    it('tolerates surrounding whitespace', () => {
+        expect(parseRangeHeaderLoose('  bytes=10-20  ')).toEqual({ start: 10, end: 20 });
+    });
+
+    it('returns undefined when end < start (nonsensical range)', () => {
+        expect(parseRangeHeaderLoose('bytes=500-100')).toBeUndefined();
+    });
+
+    it('returns undefined for malformed / multi-range / suffix-only headers', () => {
+        expect(parseRangeHeaderLoose('bytes=abc-def')).toBeUndefined();
+        expect(parseRangeHeaderLoose('bytes=-500')).toBeUndefined(); // suffix range — left to a full read
+        expect(parseRangeHeaderLoose('bytes=0-100,200-300')).toBeUndefined(); // multi-range
+        expect(parseRangeHeaderLoose('items=0-100')).toBeUndefined(); // wrong unit
+        expect(parseRangeHeaderLoose('bytes=')).toBeUndefined();
+        expect(parseRangeHeaderLoose('')).toBeUndefined();
+    });
+
+    it('accepts a zero-length point range bytes=N-N', () => {
+        expect(parseRangeHeaderLoose('bytes=42-42')).toEqual({ start: 42, end: 42 });
+    });
+});
+
+describe('parseRange (buffer path — known total)', () => {
+    const TOTAL = 1000;
+
+    it('parses a closed range within bounds', () => {
+        expect(parseRange('bytes=0-499', TOTAL)).toEqual({ start: 0, end: 499 });
+    });
+
+    it('clamps end to the last byte when the requested end exceeds total', () => {
+        // bytes=500-99999 against a 1000-byte file → end clamps to 999.
+        expect(parseRange('bytes=500-99999', TOTAL)).toEqual({ start: 500, end: 999 });
+    });
+
+    it('resolves an open-ended range to the last byte', () => {
+        expect(parseRange('bytes=200-', TOTAL)).toEqual({ start: 200, end: 999 });
+    });
+
+    it('returns undefined when start is at or past EOF (unsatisfiable → 416)', () => {
+        expect(parseRange('bytes=1000-1100', TOTAL)).toBeUndefined(); // start === total
+        expect(parseRange('bytes=2000-', TOTAL)).toBeUndefined(); // start > total
+    });
+
+    it('returns undefined when end < start after parsing', () => {
+        expect(parseRange('bytes=600-100', TOTAL)).toBeUndefined();
+    });
+
+    it('returns undefined for malformed / multi-range / suffix-only headers', () => {
+        expect(parseRange('bytes=abc-', TOTAL)).toBeUndefined();
+        expect(parseRange('bytes=-200', TOTAL)).toBeUndefined();
+        expect(parseRange('bytes=0-100,200-300', TOTAL)).toBeUndefined();
+        expect(parseRange('items=0-100', TOTAL)).toBeUndefined();
+        expect(parseRange('', TOTAL)).toBeUndefined();
+    });
+
+    it('handles the very first byte and the very last byte exactly', () => {
+        expect(parseRange('bytes=0-0', TOTAL)).toEqual({ start: 0, end: 0 });
+        expect(parseRange('bytes=999-999', TOTAL)).toEqual({ start: 999, end: 999 });
+    });
+
+    it('tolerates surrounding whitespace', () => {
+        expect(parseRange('  bytes=10-20  ', TOTAL)).toEqual({ start: 10, end: 20 });
+    });
+});

package/src/__tests__/RealtimeBridgeResolver.test.ts

@@ -33,6 +33,13 @@ vi.mock('@memberjunction/ai-agents', () => ({
   CreateBridgeRoomTranscriptSink: vi.fn(),
 }));
 
+// Mock the meeting-recording registration so the thin resolver is tested in isolation (no MJStorage /
+// core-entities graph). Its own behavior is covered by meetingRecordingRegistration.test.ts.
+vi.mock('../resolvers/meetingRecordingRegistration', () => ({
+  registerMeetingRecordingFile: vi.fn(async () => ({ Success: true, RecordingFileID: 'file-1', ConversationID: 'conv-1' })),
+  correlateRecordingStart: vi.fn(async () => true),
+}));
+
 import { RealtimeBridgeResolver, MintLiveKitClientTokenInput, LiveKitRecordingInput } from '../resolvers/RealtimeBridgeResolver';
 import type { AppContext } from '../types.js';
 
@@ -83,10 +90,12 @@ describe('RealtimeBridgeResolver', () => {
       expect(result.Status).toBe('EGRESS_ACTIVE');
     });
 
-    it('stops a recording and maps the result', async () => {
+    it('stops a recording, registers the MP4, and returns the RecordingFileID', async () => {
       const result = await resolver.StopLiveKitRecording('eg-1', ctx);
       expect(result.Success).toBe(true);
       expect(result.Status).toBe('EGRESS_COMPLETE');
+      // The registration mock returns a file id, which the resolver surfaces on the result.
+      expect(result.RecordingFileID).toBe('file-1');
     });
 
     it('requires an authenticated user to record', async () => {

package/src/__tests__/RealtimeClientSessionResolver.test.ts

@@ -2603,3 +2603,72 @@ describe('RealtimeClientSessionResolver.StartRealtimeClientSession — runtime-o
         expect(result.EffectiveConfigJson).toBeUndefined();
     });
 });
+
+describe('RealtimeClientSessionResolver — app awareness (applicationId / appContext / allowedAgents)', () => {
+    it('forwards applicationId + parsed appContext to PrepareClientSession and persists the allowed union', async () => {
+        hasPermissionMock.mockResolvedValue(true);
+        currentProvider = makeProvider(() => makeSessionEntity());
+        const createdSession = makeSessionEntity({ ID: 'session-app', ConversationID: 'conv-1' });
+        createSessionMock.mockResolvedValue(createdSession);
+        prepareClientSessionMock.mockResolvedValue({
+            Success: true,
+            ClientConfig: { Provider: 'openai', Model: 'm', EphemeralToken: 'ek', ExpiresAt: '2099-01-01T00:00:00Z', SessionConfig: {} },
+            // Effective config carries the union-accumulated allowed agents (from the app's RelevantAgents).
+            EffectiveConfig: { realtime: { allowedAgents: [{ agentId: 'skip-1', label: 'Skip' }] } },
+        });
+        const resolver = makeResolver();
+        const appContext = { App: { Name: 'Data Explorer', Description: '' }, ActiveNavItem: { Name: 'Queries' }, OtherNavItems: [], User: { Name: 'A', Roles: [] } };
+
+        await resolver.StartRealtimeClientSession(
+            'target-1', makeCtx(),
+            undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined,
+            'app-9', JSON.stringify(appContext),
+        );
+
+        // App context reached the prepare service.
+        const prepArg = prepareClientSessionMock.mock.calls[0][0] as { ApplicationID?: string; AppContext?: { App?: { Name?: string } } };
+        expect(prepArg.ApplicationID).toBe('app-9');
+        expect(prepArg.AppContext?.App?.Name).toBe('Data Explorer');
+
+        // The allowed union + applicationID were persisted onto the session config for relayed-call validation.
+        const persisted = JSON.parse(createdSession.Config_ as string) as { applicationID?: string; allowedAgents?: Array<{ agentId: string }> };
+        expect(persisted.applicationID).toBe('app-9');
+        expect(persisted.allowedAgents?.map(a => a.agentId)).toEqual(['skip-1']);
+    });
+
+    it('tolerates a malformed appContextJson (no app context, never fails the start)', async () => {
+        hasPermissionMock.mockResolvedValue(true);
+        currentProvider = makeProvider(() => makeSessionEntity());
+        createSessionMock.mockResolvedValue(makeSessionEntity({ ID: 'session-bad' }));
+        prepareClientSessionMock.mockResolvedValue({
+            Success: true, ClientConfig: { Provider: 'o', Model: 'm', EphemeralToken: 'ek', ExpiresAt: '2099-01-01T00:00:00Z', SessionConfig: {} },
+        });
+        const resolver = makeResolver();
+
+        await resolver.StartRealtimeClientSession(
+            'target-1', makeCtx(),
+            undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined,
+            'app-9', 'not-json',
+        );
+        const prepArg = prepareClientSessionMock.mock.calls[0][0] as { ApplicationID?: string; AppContext?: unknown };
+        expect(prepArg.ApplicationID).toBe('app-9');
+        expect(prepArg.AppContext).toBeUndefined();
+    });
+
+    it('passes the persisted allowedAgents from the session config into ExecuteRelayedTool', async () => {
+        currentProvider = makeProvider(() =>
+            makeSessionEntity({
+                Config_: JSON.stringify({ targetAgentID: 'lead-1', allowedAgents: [{ agentId: 'skip-1', label: 'Skip' }] }),
+            }),
+        );
+        executeRelayedToolMock.mockResolvedValue({ ResultJson: '{"ok":true}', Success: true });
+        const resolver = makeResolver();
+
+        await resolver.ExecuteRealtimeSessionTool(
+            'session-1', 'call-1', 'invoke-target-agent', '{"agent":"Skip","request":"x"}', makeCtx(), makePubSub(),
+        );
+
+        const relayArg = executeRelayedToolMock.mock.calls[0][0] as { AllowedAgents?: Array<{ agentId: string }> };
+        expect(relayArg.AllowedAgents?.map(a => a.agentId)).toEqual(['skip-1']);
+    });
+});

package/src/__tests__/RealtimeCoAgentAppAwareness.integration.test.ts

@@ -0,0 +1,191 @@
+/**
+ * @fileoverview HEADLESS INTEGRATION test — the Realtime Co-Agent "app awareness" stack composed
+ * end-to-end across packages: the app config cascade (`@memberjunction/ai-agents`
+ * realtime-coagent-config), the `AppContextSnapshot` mint-time injection
+ * (`@memberjunction/ai-core-plus`), the colleagues framing, and the multi-target delegation routing
+ * — all driven through the REAL {@link RealtimeClientSessionService} (only DB/SDK seams stubbed).
+ *
+ * This is the integration counterpart to the per-package unit tests: it proves the Move 1/3/4 layers
+ * actually compose (an app's AgentSettings → cascade → effective config → system prompt + allowed
+ * union → delegation), with no provider socket and no DB. Voice itself is not exercised (that is the
+ * live-verification step), but everything up to "what the model is told and which agent a delegation
+ * runs" is.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import {
+    BaseRealtimeModel,
+    ClientRealtimeSessionConfig,
+    IRealtimeSession,
+    RealtimeSessionParams,
+} from '@memberjunction/ai';
+import { UserInfo, IMetadataProvider } from '@memberjunction/core';
+import { MJAIAgentEntityExtended, AppContextSnapshot, ExecuteAgentResult } from '@memberjunction/ai-core-plus';
+import {
+    RealtimeClientSessionService,
+    PrepareClientSessionInput,
+    ExecuteRelayedToolInput,
+    RealtimeModelResolution,
+    CoAgentSystemPromptResolution,
+} from '@memberjunction/ai-agents';
+import {
+    BuildAppRealtimeOverridesJson,
+    INVOKE_TARGET_AGENT_TOOL_NAME,
+    DelegateToTargetRequest,
+} from '@memberjunction/ai-agents';
+
+class StubSession implements IRealtimeSession {
+    SendInput(): void {}
+    async RegisterTools(): Promise<void> {}
+    OnOutput(): void {}
+    OnTranscript(): void {}
+    OnToolCall(): void {}
+    async SendToolResult(): Promise<void> {}
+    OnInterruption(): void {}
+    OnUsage(): void {}
+    OnError(): void {}
+    async Close(): Promise<void> {}
+}
+
+class StubModel extends BaseRealtimeModel {
+    constructor() { super('k'); }
+    public override get SupportsClientDirect(): boolean { return true; }
+    async StartSession(): Promise<IRealtimeSession> { return new StubSession(); }
+    public override async CreateClientSession(params: RealtimeSessionParams): Promise<ClientRealtimeSessionConfig> {
+        return {
+            Provider: 'stub', Model: params.Model, EphemeralToken: 't', ExpiresAt: '2099-01-01T00:00:00Z',
+            SessionConfig: { instructions: params.SystemPrompt },
+        };
+    }
+}
+
+/** Real service with only the DB/SDK seams stubbed; cascade + prompt + delegation routing stay REAL. */
+class IntegrationService extends RealtimeClientSessionService {
+    private model = new StubModel();
+    public AppOverridesJson: string | null = null;
+    /** Captures which agent a delegation actually ran (the routing outcome under test). */
+    public RanAgent: MJAIAgentEntityExtended | null = null;
+    public TargetNames: Record<string, string> = { 'lead-1': 'Sage' };
+
+    protected override async configureEngine(): Promise<void> {}
+    protected override async resolveRealtimeModel(): Promise<RealtimeModelResolution | null> {
+        return { Model: this.model, ModelID: 'm', VendorID: 'v', APIName: 'stub-realtime' };
+    }
+    protected override getCoAgentSystemPromptText(): string { return 'CO-AGENT BODY'; }
+    protected override resolveCoAgentSystemPrompt(): CoAgentSystemPromptResolution {
+        return { Text: 'CO-AGENT BODY', PromptID: 'p1' };
+    }
+    protected override async createCoAgentObservabilityRun(): Promise<{ CoAgentRunID: string } | null> {
+        return { CoAgentRunID: 'run-1' };
+    }
+    protected override resolveTargetAgent(id: string): MJAIAgentEntityExtended | null {
+        if (!id) return null;
+        const name = this.TargetNames[id] ?? id;
+        return { ID: id, Name: name, Description: `${name} agent.` } as unknown as MJAIAgentEntityExtended;
+    }
+    protected override async resolveAppRealtimeOverrides(): Promise<string | null> { return this.AppOverridesJson; }
+    // Capture the routed target without running a real agent.
+    protected override async runDelegatedAgent(
+        _input: ExecuteRelayedToolInput,
+        _request: DelegateToTargetRequest,
+        target: MJAIAgentEntityExtended,
+    ): Promise<ExecuteAgentResult> {
+        this.RanAgent = target;
+        return { success: true, payload: null, agentRun: { Status: 'Completed' } } as unknown as ExecuteAgentResult;
+    }
+    protected override async createDelegatedRunArtifacts(): Promise<undefined> { return undefined; }
+}
+
+const user = { ID: 'u1' } as unknown as UserInfo;
+const provider = {} as unknown as IMetadataProvider;
+
+function coAgent(): MJAIAgentEntityExtended {
+    return { ID: 'co-1', Name: 'Realtime Co-Agent', InjectNotes: false, InjectExamples: false } as unknown as MJAIAgentEntityExtended;
+}
+function input(over: Partial<PrepareClientSessionInput> = {}): PrepareClientSessionInput {
+    return { CoAgent: coAgent(), TargetAgentID: 'lead-1', AgentSessionID: 's1', ConversationMessages: [], ...over };
+}
+
+describe('Realtime Co-Agent app awareness — integration', () => {
+    it('composes app AgentSettings → cascade → prompt (app-context + colleagues) + allowed union', async () => {
+        const svc = new IntegrationService();
+        svc.TargetNames = { 'lead-1': 'Sage', 'skip-1': 'Skip' };
+        svc.AppOverridesJson = BuildAppRealtimeOverridesJson(
+            { Disclosure: 'mention', Persona: { Tone: 'warm', SpeakingStyle: 'concise' } },
+            [{ agentId: 'skip-1', label: 'Skip', disclosure: 'silent' }],
+        );
+        const appContext: AppContextSnapshot = {
+            App: { Name: 'Knowledge Hub', Description: '' },
+            ActiveNavItem: { Name: 'Analytics' },
+            OtherNavItems: [],
+            User: { Name: 'Amith', Roles: [] },
+            View: { FreeText: 'looking at the cluster chart' },
+            Capabilities: { Agents: [{ AgentID: 'skip-1', Name: 'Skip' }] },
+        };
+
+        const result = await svc.PrepareClientSession(input({ AppContext: appContext }), user, provider);
+        expect(result.Success).toBe(true);
+
+        const prompt = result.SessionParams!.SystemPrompt;
+        // Identity (lead) + colleague (from app RelevantAgents) + per-target disclosure guidance.
+        expect(prompt).toContain('voice for the agent "Sage"');
+        expect(prompt).toContain('Your colleagues:');
+        expect(prompt).toContain('"Skip"');
+        expect(prompt).toContain('speak their result as your own'); // Skip's silent disclosure
+        // Persona (app override) folded in.
+        expect(prompt).toContain('Voice & manner');
+        // App-context snapshot injected at mint.
+        expect(prompt).toContain('CURRENT APP CONTEXT');
+        expect(prompt).toContain('Knowledge Hub');
+
+        // Effective config carries the union-accumulated allowed agents (surfaced to the resolver to persist).
+        expect(result.EffectiveConfig?.realtime?.allowedAgents?.map(a => a.agentId)).toContain('skip-1');
+        expect(result.EffectiveConfig?.realtime?.disclosure).toBe('mention');
+    });
+
+    it('routes a relayed invoke-target-agent call to a named colleague in the allowed union', async () => {
+        const svc = new IntegrationService();
+        svc.TargetNames = { 'lead-1': 'Sage', 'skip-1': 'Skip' };
+        const relay: ExecuteRelayedToolInput = {
+            AgentSessionID: 's1',
+            TargetAgentID: 'lead-1',
+            AllowedAgents: [{ agentId: 'skip-1', label: 'Skip' }],
+            Call: {
+                CallID: 'c1',
+                ToolName: INVOKE_TARGET_AGENT_TOOL_NAME,
+                Arguments: JSON.stringify({ agent: 'Skip', request: 'analyze this' }),
+            },
+        };
+        const out = await svc.ExecuteRelayedTool(relay, user, provider);
+        expect(JSON.parse(out.ResultJson).success).toBe(true);
+        expect(svc.RanAgent?.ID).toBe('skip-1'); // routed to the named colleague, not the lead
+    });
+
+    it('routes to the lead when no colleague is named', async () => {
+        const svc = new IntegrationService();
+        const relay: ExecuteRelayedToolInput = {
+            AgentSessionID: 's1',
+            TargetAgentID: 'lead-1',
+            AllowedAgents: [{ agentId: 'skip-1', label: 'Skip' }],
+            Call: { CallID: 'c1', ToolName: INVOKE_TARGET_AGENT_TOOL_NAME, Arguments: JSON.stringify({ request: 'do it' }) },
+        };
+        await svc.ExecuteRelayedTool(relay, user, provider);
+        expect(svc.RanAgent?.ID).toBe('lead-1');
+    });
+
+    it('returns a structured not-available error for an unknown colleague', async () => {
+        const svc = new IntegrationService();
+        const relay: ExecuteRelayedToolInput = {
+            AgentSessionID: 's1',
+            TargetAgentID: 'lead-1',
+            AllowedAgents: [{ agentId: 'skip-1', label: 'Skip' }],
+            Call: { CallID: 'c1', ToolName: INVOKE_TARGET_AGENT_TOOL_NAME, Arguments: JSON.stringify({ agent: 'Ghost', request: 'x' }) },
+        };
+        const out = await svc.ExecuteRelayedTool(relay, user, provider);
+        const parsed = JSON.parse(out.ResultJson);
+        expect(parsed.success).toBe(false);
+        // A not-available colleague is a structured delegation outcome ({success:false, output}),
+        // not a thrown error — the model narrates `output` to self-correct.
+        expect(parsed.output).toContain('Ghost');
+        expect(svc.RanAgent).toBeNull(); // nothing ran
+    });
+});

package/src/__tests__/RemoteBrowserSnapshot.test.ts

@@ -0,0 +1,123 @@
+// type-graphql decorators on the resolver call `Reflect.getMetadata`, which only exists when this
+// polyfill is loaded first. MUST precede any import that pulls in the resolver file.
+import 'reflect-metadata';
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// type-graphql's `@Field()`/`@ObjectType()`/`@Query()` decorators need `emitDecoratorMetadata`
+// reflection (a build-time tsc feature) that vitest's esbuild transform does NOT apply, so importing the
+// decorated resolver throws "Unable to infer GraphQL type". This unit test exercises the resolver's plain
+// TS logic (the snapshot best-effort contract), not its GraphQL schema — so we replace the decorators with
+// no-ops. (The real schema is validated by the build + integration tests.)
+vi.mock('type-graphql', () => {
+  const noopDecorator = () => () => undefined;
+  return {
+    Resolver: noopDecorator,
+    Mutation: noopDecorator,
+    Query: noopDecorator,
+    Subscription: noopDecorator,
+    ObjectType: noopDecorator,
+    InputType: noopDecorator,
+    Field: noopDecorator,
+    Arg: noopDecorator,
+    Args: noopDecorator,
+    Ctx: noopDecorator,
+    PubSub: noopDecorator,
+    Root: noopDecorator,
+    Float: class {},
+    Int: class {},
+    ID: class {},
+  };
+});
+
+// --- Mock the live-session engine the resolver reads. A single mutable session object lets each test
+//     script what CaptureScreenshot does (resolve a frame / throw "Browser not launched"). ---
+interface FakeLiveSession {
+  CaptureScreenshot: ReturnType<typeof vi.fn>;
+  GetCurrentUrl: ReturnType<typeof vi.fn>;
+}
+const liveSession: FakeLiveSession = {
+  CaptureScreenshot: vi.fn(async () => 'QUJD'),
+  GetCurrentUrl: vi.fn(() => 'https://www.wikipedia.org/'),
+};
+// The snapshot path is a pure READ: it looks up an existing session via GetSessionForAgentSession and never
+// lazily starts one. `undefined` models "no live browser for this agent session".
+const getSessionMock = vi.fn<[], FakeLiveSession | undefined>(() => liveSession);
+vi.mock('@memberjunction/remote-browser-server', () => ({
+  RemoteBrowserEngine: {
+    Instance: {
+      GetSessionForAgentSession: (...args: unknown[]) => getSessionMock(...(args as [])),
+    },
+  },
+}));
+
+// Keep the AI imports (visual interpreter) inert — they aren't exercised by the snapshot path.
+vi.mock('@memberjunction/aiengine', () => ({ AIEngine: { Instance: { Config: vi.fn(), Prompts: [] } } }));
+vi.mock('@memberjunction/ai-prompts', () => ({ AIPromptRunner: class {} }));
+// Spread the real module so transitively-loaded code still resolves with its REAL base classes; only
+// AIPromptParams is overridden for the test.
+vi.mock('@memberjunction/ai-core-plus', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@memberjunction/ai-core-plus')>()),
+  AIPromptParams: class {},
+}));
+
+import { RemoteBrowserActionResolver } from '../resolvers/RemoteBrowserActionResolver.js';
+
+/**
+ * A test subclass that bypasses the ownership/provider plumbing (covered elsewhere) so the snapshot
+ * best-effort contract is exercised in isolation.
+ */
+class TestableResolver extends RemoteBrowserActionResolver {
+  protected requireUserAndProvider() {
+    return { contextUser: { ID: 'user-1' }, provider: {} } as never;
+  }
+  protected async loadOwnedSession() {
+    return { ID: 'sess-1', AgentID: 'agent-1', UserID: 'user-1' } as never;
+  }
+}
+
+const ctx = { userPayload: { sessionId: 'push-sess-1' }, providers: {} } as never;
+
+describe('RemoteBrowserActionResolver — snapshot (best-effort perception poll)', () => {
+  let resolver: TestableResolver;
+
+  beforeEach(() => {
+    resolver = new TestableResolver();
+    liveSession.CaptureScreenshot.mockReset().mockResolvedValue('QUJD');
+    liveSession.GetCurrentUrl.mockReset().mockReturnValue('https://www.wikipedia.org/');
+    getSessionMock.mockReset().mockReturnValue(liveSession);
+  });
+
+  it('returns the screenshot + URL when the browser is live', async () => {
+    const result = await resolver.RemoteBrowserSnapshot('sess-1', ctx);
+    expect(result).toEqual({ ScreenshotBase64: 'QUJD', CurrentUrl: 'https://www.wikipedia.org/' });
+    expect(liveSession.CaptureScreenshot).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns an empty snapshot when no live browser exists (never started / already torn down)', async () => {
+    getSessionMock.mockReturnValue(undefined);
+    const result = await resolver.RemoteBrowserSnapshot('sess-1', ctx);
+    expect(result).toEqual({});
+    expect(liveSession.CaptureScreenshot).not.toHaveBeenCalled();
+  });
+
+  // The regression the fix targets: a session handle survives in the live map but its underlying browser
+  // adapter has been torn down, so CaptureScreenshot throws "Browser not launched". The ~700ms client poll
+  // must NOT surface that as a recurring GraphQL error — the query's documented contract is empty fields,
+  // not an error. So the resolver catches and degrades to {} (the surface keeps its last good frame).
+  it('degrades to an empty snapshot — does NOT throw — when the adapter is torn down', async () => {
+    liveSession.CaptureScreenshot.mockRejectedValueOnce(
+      new Error('Browser not launched. Call Launch() before using the adapter.'),
+    );
+    const result = await resolver.RemoteBrowserSnapshot('sess-1', ctx);
+    expect(result).toEqual({});
+    expect(liveSession.CaptureScreenshot).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not read the URL when the capture fails (no half-populated snapshot)', async () => {
+    liveSession.CaptureScreenshot.mockRejectedValueOnce(new Error('Target page, context or browser has been closed'));
+    const result = await resolver.RemoteBrowserSnapshot('sess-1', ctx);
+    expect(result).toEqual({});
+    expect(liveSession.GetCurrentUrl).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/SessionManager.test.ts

@@ -397,6 +397,8 @@ describe('SessionManager — server-side channel plugin lifecycle notifications'
             AgentID: 'agent-1',
             UserID: 'user-1',
             ConversationID: 'conv-existing',
+            // Verbatim per-session config blob handed to data-aware channels; null when unset.
+            AgentSessionConfig: null,
         });
         expect((user as { ID: string }).ID).toBe('user-1');
         expect(prov).toBe(provider);