@memberjunction/server 5.41.0 → 5.42.0

package/src/__tests__/RealtimeBridgeResolver.test.ts

@@ -0,0 +1,100 @@
+// type-graphql decorators on the resolver call Reflect.getMetadata, which only exists when this polyfill
+// is loaded first. Vitest does not bring it in automatically — this MUST precede the resolver import.
+import 'reflect-metadata';
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { UserInfo } from '@memberjunction/core';
+
+// Mock the server-side LiveKit services so the thin resolver is tested in isolation (no LiveKit creds).
+const h = vi.hoisted(() => ({
+  mintClientToken: vi.fn(async (room: string, identity: string) => ({
+    ServerUrl: 'wss://x.livekit.cloud',
+    Token: `jwt-${identity}`,
+    Identity: identity,
+    RoomName: room,
+  })),
+  startRecording: vi.fn(async () => ({ EgressID: 'eg-1', RoomName: 'room-1', Status: 'EGRESS_ACTIVE' })),
+  stopRecording: vi.fn(async () => ({ EgressID: 'eg-1', RoomName: 'room-1', Status: 'EGRESS_COMPLETE' })),
+}));
+
+vi.mock('@memberjunction/livekit-room-server', () => ({
+  LiveKitTokenService: vi.fn(() => ({ MintClientToken: h.mintClientToken })),
+  // SetSessionFactory is exercised by the resolver's module-load binding of the realtime-session factory.
+  LiveKitAgentRoomCoordinator: { Instance: { StartAgentRoomSession: vi.fn(), SetSessionFactory: vi.fn() } },
+  LiveKitEgressService: vi.fn(() => ({ StartRoomRecording: h.startRecording, StopRecording: h.stopRecording })),
+}));
+
+// Mock the agent factory so importing the resolver doesn't pull the heavy @memberjunction/ai-agents graph
+// into this thin resolver test (the binding only needs the symbol to exist).
+vi.mock('@memberjunction/ai-agents', () => ({
+  CreateBridgeRealtimeSession: vi.fn(),
+  FinalizeBridgeCoAgentRuns: vi.fn(),
+  GetRealtimeModelVoices: vi.fn(),
+  CreateBridgeRoomTranscriptSink: vi.fn(),
+}));
+
+import { RealtimeBridgeResolver, MintLiveKitClientTokenInput, LiveKitRecordingInput } from '../resolvers/RealtimeBridgeResolver';
+import type { AppContext } from '../types.js';
+
+/** A resolver subclass that supplies a fake authenticated user (GetUserFromPayload is protected). */
+class TestableResolver extends RealtimeBridgeResolver {
+  public user: UserInfo | undefined = { ID: 'U1', Name: 'Amith', Email: 'amith@x.com' } as unknown as UserInfo;
+  protected override GetUserFromPayload(): UserInfo | undefined {
+    return this.user;
+  }
+}
+
+const ctx = {} as AppContext;
+
+describe('RealtimeBridgeResolver', () => {
+  let resolver: TestableResolver;
+
+  beforeEach(() => {
+    resolver = new TestableResolver();
+  });
+
+  describe('MintLiveKitClientToken', () => {
+    it('derives the participant identity from the user and returns the token', async () => {
+      const input = Object.assign(new MintLiveKitClientTokenInput(), { RoomName: 'room-1', DisplayName: 'Amith' });
+      const result = await resolver.MintLiveKitClientToken(input, ctx);
+      expect(result.Success).toBe(true);
+      expect(result.Identity).toBe('user-u1'); // lowercased user-${ID}
+      expect(result.Token).toBe('jwt-user-u1');
+      expect(result.RoomName).toBe('room-1');
+      expect(h.mintClientToken).toHaveBeenCalledWith('room-1', 'user-u1', 'Amith');
+    });
+
+    it('fails cleanly when there is no authenticated user', async () => {
+      resolver.user = undefined;
+      const input = Object.assign(new MintLiveKitClientTokenInput(), { RoomName: 'room-1' });
+      const result = await resolver.MintLiveKitClientToken(input, ctx);
+      expect(result.Success).toBe(false);
+      expect(result.ErrorMessage).toMatch(/current user/i);
+      expect(result.RoomName).toBe('room-1');
+    });
+  });
+
+  describe('recording', () => {
+    it('starts a recording and maps the result', async () => {
+      const input = Object.assign(new LiveKitRecordingInput(), { RoomName: 'room-1', Layout: 'grid' });
+      const result = await resolver.StartLiveKitRecording(input, ctx);
+      expect(result.Success).toBe(true);
+      expect(result.EgressID).toBe('eg-1');
+      expect(result.Status).toBe('EGRESS_ACTIVE');
+    });
+
+    it('stops a recording and maps the result', async () => {
+      const result = await resolver.StopLiveKitRecording('eg-1', ctx);
+      expect(result.Success).toBe(true);
+      expect(result.Status).toBe('EGRESS_COMPLETE');
+    });
+
+    it('requires an authenticated user to record', async () => {
+      resolver.user = undefined;
+      const input = Object.assign(new LiveKitRecordingInput(), { RoomName: 'room-1' });
+      const result = await resolver.StartLiveKitRecording(input, ctx);
+      expect(result.Success).toBe(false);
+      expect(result.ErrorMessage).toMatch(/current user/i);
+    });
+  });
+});

package/src/__tests__/RemoteBrowserAudioStream.test.ts

@@ -55,7 +55,14 @@ vi.mock('@memberjunction/remote-browser-server', () => ({
 // Keep the AI imports (visual interpreter) inert — they aren't exercised by the audio path.
 vi.mock('@memberjunction/aiengine', () => ({ AIEngine: { Instance: { Config: vi.fn(), Prompts: [] } } }));
 vi.mock('@memberjunction/ai-prompts', () => ({ AIPromptRunner: class {} }));
-vi.mock('@memberjunction/ai-core-plus', () => ({ AIPromptParams: class {} }));
+// Spread the real module so transitively-loaded code (e.g. ArtifactToolManager → DataSnapshotToolLibrary,
+// which extends BaseArtifactToolLibrary) still resolves with its REAL base classes; only AIPromptParams is
+// overridden for the test. (Subsumes the narrower stub-two-exports approach — any other transitive export
+// is supplied by the real module rather than coming back undefined.)
+vi.mock('@memberjunction/ai-core-plus', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@memberjunction/ai-core-plus')>()),
+  AIPromptParams: class {},
+}));
 
 import { RemoteBrowserActionResolver } from '../resolvers/RemoteBrowserActionResolver.js';
 

package/src/__tests__/RemoteBrowserGoalEngine.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import type { UserInfo } from '@memberjunction/core';
+import { RunComputerUseParams, type StepRecord } from '@memberjunction/computer-use';
+import { MJComputerUseEngine, MJRunComputerUseParams } from '@memberjunction/computer-use-engine';
+import { CdpRemoteBrowserSession, type ComputerUseGoalRun } from '@memberjunction/remote-browser-cdp';
+import type { MJAIAgentRunStepEntity } from '@memberjunction/core-entities';
+import {
+  buildMJGoalParams,
+  BindRemoteBrowserGoalEngine,
+  MJProgressComputerUseEngine,
+  extractCoAgentRunID,
+  finalizeBrowserGoalStep,
+} from '../agentSessions/remoteBrowserGoalEngine.js';
+
+const USER = { ID: 'u-1', Email: 'amith@bluecypress.io' } as unknown as UserInfo;
+
+/** Builds a base RunComputerUseParams the CDP session would hand to the goal engine. */
+function baseParams(): RunComputerUseParams {
+  return Object.assign(new RunComputerUseParams(), { Goal: 'log in', MaxSteps: 7, StartUrl: 'https://app.test/' });
+}
+
+describe('buildMJGoalParams', () => {
+  it('produces MJ-aware params that carry over the base goal/step/url fields', () => {
+    const mj = buildMJGoalParams(baseParams(), USER);
+    expect(mj).toBeInstanceOf(MJRunComputerUseParams);
+    expect(mj.Goal).toBe('log in');
+    expect(mj.MaxSteps).toBe(7);
+    expect(mj.StartUrl).toBe('https://app.test/');
+  });
+
+  it('injects the acting ContextUser so MJ prompts run as that user', () => {
+    expect(buildMJGoalParams(baseParams(), USER).ContextUser).toBe(USER);
+  });
+
+  it('leaves ContextUser undefined when none is supplied', () => {
+    expect(buildMJGoalParams(baseParams()).ContextUser).toBeUndefined();
+  });
+
+  it('threads the parent run + step ids for observability nesting', () => {
+    const mj = buildMJGoalParams(baseParams(), USER, 'coagent-run-1', 'goal-step-1');
+    expect(mj.AgentRunId).toBe('coagent-run-1');
+    expect(mj.AgentRunStepID).toBe('goal-step-1');
+  });
+
+  it('leaves the run/step ids undefined when not supplied', () => {
+    const mj = buildMJGoalParams(baseParams(), USER);
+    expect(mj.AgentRunId).toBeUndefined();
+    expect(mj.AgentRunStepID).toBeUndefined();
+  });
+});
+
+describe('extractCoAgentRunID', () => {
+  it('pulls coAgentRunID out of a session Config_ blob', () => {
+    expect(extractCoAgentRunID(JSON.stringify({ coAgentRunID: 'run-9', promptRunID: 'p' }))).toBe('run-9');
+  });
+  it('returns undefined for a missing key, null/empty config, or non-string value', () => {
+    expect(extractCoAgentRunID(JSON.stringify({ promptRunID: 'p' }))).toBeUndefined();
+    expect(extractCoAgentRunID(null)).toBeUndefined();
+    expect(extractCoAgentRunID(undefined)).toBeUndefined();
+    expect(extractCoAgentRunID('')).toBeUndefined();
+    expect(extractCoAgentRunID(JSON.stringify({ coAgentRunID: 123 }))).toBeUndefined();
+  });
+  it('returns undefined for malformed JSON (best-effort)', () => {
+    expect(extractCoAgentRunID('{not json')).toBeUndefined();
+  });
+});
+
+describe('finalizeBrowserGoalStep', () => {
+  function fakeStep() {
+    return {
+      StartedAt: new Date(),
+      Save: vi.fn(async () => true),
+      LatestResult: { CompleteMessage: '' },
+    } as unknown as MJAIAgentRunStepEntity & { Save: ReturnType<typeof vi.fn> };
+  }
+
+  it('finalizes the parent step Completed from a successful goal result + saves', async () => {
+    const step = fakeStep();
+    await finalizeBrowserGoalStep(step, { Success: true, Strategy: 'ComputerUse', Status: 'Completed', StepCount: 4, CurrentUrl: 'https://done/' });
+    expect(step.Status).toBe('Completed');
+    expect(step.Success).toBe(true);
+    expect((step as unknown as { Save: ReturnType<typeof vi.fn> }).Save).toHaveBeenCalledOnce();
+    const out = JSON.parse(step.OutputData as string);
+    expect(out.strategy).toBe('ComputerUse');
+    expect(out.stepCount).toBe(4);
+  });
+
+  it('finalizes Failed and carries the detail as the error message', async () => {
+    const step = fakeStep();
+    await finalizeBrowserGoalStep(step, { Success: false, Status: 'Error', Detail: 'login blocked' });
+    expect(step.Status).toBe('Failed');
+    expect(step.ErrorMessage).toBe('login blocked');
+  });
+
+  it('is a no-op when the step is null (no co-agent run to nest under)', async () => {
+    await expect(finalizeBrowserGoalStep(null, { Success: true })).resolves.toBeUndefined();
+  });
+});
+
+describe('MJProgressComputerUseEngine', () => {
+  it('is an MJ computer-use engine that satisfies the goal-run seam', () => {
+    const engine = new MJProgressComputerUseEngine();
+    expect(engine).toBeInstanceOf(MJComputerUseEngine);
+    // Seam surface the CDP session drives:
+    expect(typeof engine.SetBrowserAdapter).toBe('function');
+    expect(typeof engine.Stop).toBe('function');
+    expect(typeof engine.Run).toBe('function');
+  });
+
+  it('forwards a model-safe progress note on each completed step', () => {
+    const engine = new MJProgressComputerUseEngine();
+    const notes: { Step: number; Message: string; Url?: string }[] = [];
+    engine.OnProgress = (p) => notes.push(p);
+
+    // onStepComplete is protected; the base MJ media-persistence path is a no-op here (no prompt-run id /
+    // context user set), so this exercises only the progress forwarding.
+    const step = { StepNumber: 2, ControllerReasoning: 'typing username', Url: 'https://app.test/login', Screenshot: '' } as StepRecord;
+    (engine as unknown as { onStepComplete(s: StepRecord, p: MJRunComputerUseParams): void }).onStepComplete(step, new MJRunComputerUseParams());
+
+    expect(notes).toEqual([{ Step: 2, Message: 'typing username', Url: 'https://app.test/login' }]);
+  });
+});
+
+describe('BindRemoteBrowserGoalEngine', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('binds a factory that yields an MJ progress engine', () => {
+    const spy = vi.spyOn(CdpRemoteBrowserSession, 'SetGoalEngineFactory');
+    BindRemoteBrowserGoalEngine();
+
+    expect(spy).toHaveBeenCalledOnce();
+    const factory = spy.mock.calls[0][0] as () => ComputerUseGoalRun;
+    expect(factory()).toBeInstanceOf(MJProgressComputerUseEngine);
+  });
+
+  it('never throws (a binding hiccup must not abort server boot)', () => {
+    vi.spyOn(CdpRemoteBrowserSession, 'SetGoalEngineFactory').mockImplementation(() => {
+      throw new Error('boom');
+    });
+    expect(() => BindRemoteBrowserGoalEngine()).not.toThrow();
+  });
+});

package/src/__tests__/remoteBrowserGoalRegistry.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { RemoteBrowserGoalRegistry } from '../agentSessions/remoteBrowserGoalRegistry.js';
+
+/**
+ * The registry is a process singleton; each test uses a UNIQUE session id so tracked state never
+ * bleeds across tests (no reset hook needed for the functional cases).
+ */
+let seq = 0;
+const newSession = () => `sess-${++seq}`;
+
+describe('RemoteBrowserGoalRegistry', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('reports a freshly-begun run as Running with no outcome', () => {
+    const reg = RemoteBrowserGoalRegistry.Instance;
+    const s = newSession();
+    reg.Begin(s, 'g1');
+    const rec = reg.Get(s, 'g1');
+    expect(rec?.Status).toBe('Running');
+    expect(rec?.Outcome).toBeUndefined();
+    expect(rec?.GoalRunID).toBe('g1');
+  });
+
+  it('is case-insensitive on the session id', () => {
+    const reg = RemoteBrowserGoalRegistry.Instance;
+    reg.Begin('AbC-Session', 'g1');
+    expect(reg.Get('abc-session', 'g1')?.Status).toBe('Running');
+  });
+
+  it('returns the terminal outcome after Complete', () => {
+    const reg = RemoteBrowserGoalRegistry.Instance;
+    const s = newSession();
+    reg.Begin(s, 'g1');
+    reg.Complete(s, 'g1', { Success: true, Status: 'Completed', StepCount: 4, CurrentUrl: 'https://x', Detail: 'done' });
+    const rec = reg.Get(s, 'g1');
+    expect(rec?.Status).toBe('Complete');
+    expect(rec?.Outcome).toMatchObject({ Success: true, Status: 'Completed', StepCount: 4 });
+  });
+
+  it('ignores a Complete for a superseded/mismatched goalRunID', () => {
+    const reg = RemoteBrowserGoalRegistry.Instance;
+    const s = newSession();
+    reg.Begin(s, 'g2'); // a newer goal replaced g1
+    reg.Complete(s, 'g1', { Success: true, Status: 'Completed' }); // stale completion — dropped
+    const rec = reg.Get(s, 'g2');
+    expect(rec?.Status).toBe('Running');
+  });
+
+  it('Get with a mismatched goalRunID returns undefined (poll for expired/superseded id reads nothing)', () => {
+    const reg = RemoteBrowserGoalRegistry.Instance;
+    const s = newSession();
+    reg.Begin(s, 'g1');
+    expect(reg.Get(s, 'g-other')).toBeUndefined();
+    expect(reg.Get(s, 'g1')).toBeDefined();
+  });
+
+  it('Begin replaces any prior run for the same session', () => {
+    const reg = RemoteBrowserGoalRegistry.Instance;
+    const s = newSession();
+    reg.Begin(s, 'g1');
+    reg.Complete(s, 'g1', { Success: true, Status: 'Completed' });
+    reg.Begin(s, 'g2'); // new goal supersedes the completed one
+    expect(reg.Get(s, 'g1')).toBeUndefined();
+    expect(reg.Get(s, 'g2')?.Status).toBe('Running');
+  });
+
+  it('sweeps a completed record after its retention TTL', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-01-01T00:00:00Z'));
+    const reg = RemoteBrowserGoalRegistry.Instance;
+    const s = newSession();
+    reg.Begin(s, 'g1');
+    reg.Complete(s, 'g1', { Success: true, Status: 'Completed' });
+    expect(reg.Get(s, 'g1')?.Status).toBe('Complete');
+    // Past the completed-retention TTL (5 min) — the next Get sweeps it.
+    vi.advanceTimersByTime(6 * 60 * 1000);
+    expect(reg.Get(s, 'g1')).toBeUndefined();
+  });
+});

package/src/agentSessions/index.ts

@@ -10,6 +10,7 @@
 import { LoadWhiteboardChannelServer, LoadMeetingControlsChannelServer } from '@memberjunction/ai-agents';
 import { LoadRemoteBrowserChannel } from '@memberjunction/remote-browser-server';
 import { LoadSelfHostRemoteBrowser } from '@memberjunction/remote-browser-selfhost';
+import { BindRemoteBrowserGoalEngine } from './remoteBrowserGoalEngine.js';
 
 // Tree-shaking prevention: force the server-side channel plugin registrations
 // (`@RegisterClass(BaseRealtimeChannelServer, ...)`) to execute on any static path that touches
@@ -21,7 +22,11 @@ LoadMeetingControlsChannelServer();
 // Playwright — pulled in transitively through the SelfHost package, documented and acceptable).
 LoadRemoteBrowserChannel();
 LoadSelfHostRemoteBrowser();
+// Bind goal-driven browser control to MJ's computer-use engine (vision-model auto-selection, prompt-run
+// logging, credential resolution). Without this, RunComputerUseGoal falls back to the bare base engine.
+BindRemoteBrowserGoalEngine();
 
+export * from './remoteBrowserGoalEngine.js';
 export * from './HostInstance.js';
 export * from './SessionManager.js';
 export * from './SessionJanitor.js';

package/src/agentSessions/remoteBrowserGoalEngine.ts

@@ -0,0 +1,191 @@
+/**
+ * @fileoverview **Production binding** of the Remote Browser goal-engine seam to MJ's computer-use engine.
+ *
+ * The CDP remote-browser session ({@link CdpRemoteBrowserSession}) runs goal-driven browser control through
+ * an injectable {@link ComputerUseGoalRun} factory. By default that factory yields a bare
+ * `ProgressComputerUseEngine` (base computer-use), which has no model auto-selection — so it can't run a goal
+ * unsupervised. This module binds the factory to {@link MJProgressComputerUseEngine}: an MJ-aware engine that
+ * routes controller/judge prompts through `AIPromptRunner`, auto-selects a vision-capable model from MJ
+ * metadata, persists step media, AND forwards per-step progress for live narration.
+ *
+ * Called once at server startup from `agentSessions/index.ts` (the realtime composition point), so every
+ * goal-driven run on this process uses the MJ engine. Kept here (an application package), not in any library,
+ * because it is the seam where the transport-neutral CDP layer is wired to MJ's AI stack.
+ *
+ * @module @memberjunction/server
+ */
+
+import { UserInfo, LogError, IMetadataProvider, RunView } from '@memberjunction/core';
+import { MJAIAgentRunStepEntity } from '@memberjunction/core-entities';
+import { initAgentRunStep, finalizeAgentRunStep } from '@memberjunction/ai-core-plus';
+import type { ComputerUseResult, RunComputerUseParams, StepRecord } from '@memberjunction/computer-use';
+import { MJComputerUseEngine, MJRunComputerUseParams } from '@memberjunction/computer-use-engine';
+import type { RemoteBrowserGoalResult } from '@memberjunction/remote-browser-base';
+import { buildProgressNote, CdpRemoteBrowserSession, type ComputerUseGoalProgress, type ComputerUseGoalRun } from '@memberjunction/remote-browser-cdp';
+
+/**
+ * Adapts the transport-neutral base computer-use params into {@link MJRunComputerUseParams}, injecting the
+ * acting user so the MJ engine can run its controller/judge prompts as that user. Pure + exported for unit
+ * testing; {@link MJProgressComputerUseEngine.Run} is a one-liner over it.
+ *
+ * @param params The base computer-use params the CDP session built (goal + step cap + start url).
+ * @param contextUser The acting MJ user (may be undefined; the MJ engine handles the unset case).
+ * @param agentRunID Optional parent agent-run id (links the goal's prompt runs to the realtime agent run).
+ * @param agentRunStepID Optional parent agent-run-step id (nests a child prompt step per prompt under it).
+ * @returns The MJ-aware params to hand to `MJComputerUseEngine.Run`.
+ */
+export function buildMJGoalParams(params: RunComputerUseParams, contextUser?: UserInfo, agentRunID?: string, agentRunStepID?: string): MJRunComputerUseParams {
+  const mjParams = Object.assign(new MJRunComputerUseParams(), params);
+  mjParams.ContextUser = contextUser;
+  mjParams.AgentRunId = agentRunID;
+  mjParams.AgentRunStepID = agentRunStepID;
+  return mjParams;
+}
+
+/**
+ * The MJ-aware goal engine bound in production. Extends {@link MJComputerUseEngine} (prompt-runner routing,
+ * vision-model auto-selection, credential resolution, media persistence) and satisfies the
+ * {@link ComputerUseGoalRun} seam:
+ *
+ * - {@link SetBrowserAdapter} / {@link Stop} are inherited from the base computer-use engine.
+ * - {@link OnProgress} + {@link ContextUser} are set by the CDP session before {@link Run}.
+ * - {@link Run} adapts the transport-neutral base params into {@link MJRunComputerUseParams} (injecting the
+ *   acting user) so the MJ engine can run its prompts.
+ * - {@link onStepComplete} chains the MJ media-persistence behavior, then forwards a model-safe progress note.
+ */
+export class MJProgressComputerUseEngine extends MJComputerUseEngine implements ComputerUseGoalRun {
+  /** Per-step progress hook the CDP session sets before {@link Run} (drives live narration). */
+  public OnProgress?: (progress: ComputerUseGoalProgress) => void;
+
+  /** The MJ user the goal run executes as; the CDP session sets it from the session's context user. */
+  public ContextUser?: UserInfo;
+
+  /** Parent agent-run id the CDP session sets before {@link Run} (links the goal's prompt runs to it). */
+  public AgentRunID?: string;
+
+  /** Parent agent-run-step id the CDP session sets before {@link Run} (nests child prompt steps under it). */
+  public AgentRunStepID?: string;
+
+  /**
+   * Adapts the transport-neutral base params into {@link MJRunComputerUseParams} (carrying the acting user
+   * + the parent run/step linkage) and delegates to the MJ engine, which auto-selects a vision-capable
+   * controller model from MJ metadata and nests a child step per prompt when the linkage is present.
+   *
+   * @param params The base computer-use params the CDP session built (goal + step cap + start url).
+   * @returns The computer-use run result.
+   */
+  public override async Run(params: RunComputerUseParams): Promise<ComputerUseResult> {
+    return super.Run(buildMJGoalParams(params, this.ContextUser, this.AgentRunID, this.AgentRunStepID));
+  }
+
+  protected override onStepComplete(step: StepRecord, params: MJRunComputerUseParams): void {
+    super.onStepComplete(step, params); // keep MJ media persistence
+    this.OnProgress?.(buildProgressNote(step)); // shared note shape with the base ProgressComputerUseEngine
+  }
+}
+
+/**
+ * Extracts the realtime co-agent observability run id from an `AIAgentSession.Config_` JSON blob (the
+ * `coAgentRunID` a voice session persists). Returns `undefined` for a missing/non-voice/un-parseable
+ * config — goal-run observability is best-effort and degrades to "no parent run" cleanly.
+ *
+ * @param configJson The session's `Config_` string.
+ * @returns The co-agent run id, or `undefined`.
+ */
+export function extractCoAgentRunID(configJson: string | null | undefined): string | undefined {
+  if (!configJson) {
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(configJson) as { coAgentRunID?: unknown };
+    return typeof parsed.coAgentRunID === 'string' ? parsed.coAgentRunID : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Truncates a goal to a step-name-friendly length. */
+function goalStepName(goal: string): string {
+  const trimmed = goal.trim();
+  return `Browser goal: ${trimmed.length > 120 ? `${trimmed.slice(0, 120)}…` : trimmed}`;
+}
+
+/**
+ * Creates the parent `Tool` step ("Browser goal: …") on the realtime co-agent run for a goal-driven browser
+ * run — a single top-level timeline node the computer-use prompt steps then nest under. Best-effort: returns
+ * `null` (so the goal still runs, just unlinked) when there's no co-agent run to attach to, or on any error.
+ * Uses the shared {@link initAgentRunStep} helper so the field shape matches every other agent-run step.
+ *
+ * @param provider The metadata provider.
+ * @param contextUser The acting user.
+ * @param coAgentRunID The realtime co-agent run id (the parent run), or `undefined`.
+ * @param goal The natural-language goal (becomes the step name).
+ * @returns The saved parent step (to finalize + nest under), or `null`.
+ */
+export async function beginBrowserGoalStep(
+  provider: IMetadataProvider,
+  contextUser: UserInfo | undefined,
+  coAgentRunID: string | undefined,
+  goal: string,
+): Promise<MJAIAgentRunStepEntity | null> {
+  if (!coAgentRunID) {
+    return null;
+  }
+  try {
+    const rv = new RunView();
+    const countResult = await rv.RunView(
+      { EntityName: 'MJ: AI Agent Run Steps', ExtraFilter: `AgentRunID='${coAgentRunID.replace(/'/g, "''")}'`, Fields: ['ID'], ResultType: 'simple' },
+      contextUser,
+    );
+    const stepNumber = (countResult.Success ? (countResult.Results?.length ?? 0) : 0) + 1;
+    const step = await provider.GetEntityObject<MJAIAgentRunStepEntity>('MJ: AI Agent Run Steps', contextUser);
+    step.NewRecord();
+    initAgentRunStep(step, { AgentRunID: coAgentRunID, StepNumber: stepNumber, StepType: 'Tool', StepName: goalStepName(goal) });
+    if (await step.Save()) {
+      return step;
+    }
+    LogError(`[RemoteBrowserGoalEngine] beginBrowserGoalStep save failed: ${step.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+    return null;
+  } catch (err) {
+    LogError(`[RemoteBrowserGoalEngine] beginBrowserGoalStep threw: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}
+
+/**
+ * Finalizes the parent browser-goal step from the goal outcome — `Completed`/`Failed` with an `OutputData`
+ * envelope of strategy/status/step-count/url. A no-op when `step` is `null`. Best-effort (logged, never thrown).
+ *
+ * @param step The parent step from {@link beginBrowserGoalStep} (or `null`).
+ * @param result The goal outcome.
+ */
+export async function finalizeBrowserGoalStep(step: MJAIAgentRunStepEntity | null, result: RemoteBrowserGoalResult): Promise<void> {
+  if (!step) {
+    return;
+  }
+  try {
+    finalizeAgentRunStep(step, {
+      success: result.Success,
+      errorMessage: result.Success ? undefined : result.Detail,
+      outputData: { strategy: result.Strategy, status: result.Status, stepCount: result.StepCount, currentUrl: result.CurrentUrl },
+    });
+    if (!(await step.Save())) {
+      LogError(`[RemoteBrowserGoalEngine] finalizeBrowserGoalStep save failed: ${step.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+    }
+  } catch (err) {
+    LogError(`[RemoteBrowserGoalEngine] finalizeBrowserGoalStep threw: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+/**
+ * Binds the CDP goal-engine factory to {@link MJProgressComputerUseEngine}. Idempotent and safe to call at
+ * startup; failures are logged (never thrown) so a binding hiccup can't abort server boot — goal runs would
+ * simply fall back to the base engine.
+ */
+export function BindRemoteBrowserGoalEngine(): void {
+  try {
+    CdpRemoteBrowserSession.SetGoalEngineFactory(() => new MJProgressComputerUseEngine());
+  } catch (err) {
+    LogError(`[RemoteBrowserGoalEngine] Failed to bind MJ computer-use goal engine: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}