@memberjunction/server 5.41.0 → 5.43.0

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/SessionJanitor.ts

@@ -228,8 +228,22 @@ export class SessionJanitor extends BaseSingleton<SessionJanitor> implements ISh
             if (page.length === 0) {
                 break;
             }
+            // Batch-load every channel for this whole page of sessions in ONE query, then hand each
+            // session its own slice to CloseSession — avoids the N+1 channel read (one RunView per
+            // closing session) that tripped the sequential / multiple-same-entity telemetry.
+            const channelsBySession = await this.sessionManager.LoadActiveChannelsBySession(
+                page.map(s => s.ID),
+                systemUser,
+                provider,
+            );
             for (const session of page) {
-                const closed = await this.sessionManager.CloseSession(session.ID, systemUser, provider, closeReason);
+                const closed = await this.sessionManager.CloseSession(
+                    session.ID,
+                    systemUser,
+                    provider,
+                    closeReason,
+                    channelsBySession.get(session.ID.toLowerCase()) ?? [],
+                );
                 if (closed) {
                     closedCount++;
                 }

package/src/agentSessions/SessionManager.ts

@@ -137,6 +137,7 @@ export class SessionManager {
         contextUser: UserInfo,
         provider: IMetadataProvider,
         closeReason: SessionCloseReason = 'Explicit',
+        preloadedChannels?: MJAIAgentSessionChannelEntity[],
     ): Promise<boolean> {
         const session = await this.loadSession(agentSessionID, contextUser, provider);
         if (!session) {
@@ -156,7 +157,7 @@ export class SessionManager {
         if (!closed) {
             return false;
         }
-        await this.disconnectChannels(agentSessionID, contextUser, provider);
+        await this.disconnectChannels(agentSessionID, contextUser, provider, preloadedChannels);
         await this.finalizeObservabilityRuns(session, contextUser, provider);
         await this.notifyChannelPluginsSessionClosed(agentSessionID, closeReason);
         return true;
@@ -376,24 +377,72 @@ export class SessionManager {
         agentSessionID: string,
         contextUser: UserInfo,
         provider: IMetadataProvider,
+        preloadedChannels?: MJAIAgentSessionChannelEntity[],
     ): Promise<void> {
+        // Sweep callers (the janitor) close a whole page of sessions at once and pre-load every
+        // session's channels in ONE batched query (see LoadActiveChannelsBySession), passing this
+        // session's slice here to avoid an N+1 channel read (one RunView per closing session).
+        // Every other close path passes nothing and reads just this session's channels.
+        const channels = preloadedChannels
+            ?? await this.loadActiveChannels([agentSessionID], contextUser, provider);
+        const now = new Date();
+        for (const channel of channels) {
+            channel.Status = 'Disconnected';
+            channel.DisconnectedAt = now;
+            await this.saveOrLog(channel, 'disconnectChannels');
+        }
+    }
+
+    /**
+     * Loads the non-Disconnected channels for one or more sessions in a SINGLE RunView
+     * (`AgentSessionID IN (...)`). Session IDs are server-generated GUIDs (never user input), so
+     * inline interpolation carries no injection risk. Returns [] on empty input or load failure.
+     */
+    private async loadActiveChannels(
+        sessionIDs: string[],
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<MJAIAgentSessionChannelEntity[]> {
+        if (sessionIDs.length === 0) {
+            return [];
+        }
+        const inList = sessionIDs.map(id => `'${id}'`).join(',');
         const rv = RunView.FromMetadataProvider(provider);
         const result = await rv.RunView<MJAIAgentSessionChannelEntity>({
             EntityName: SESSION_CHANNEL_ENTITY,
-            ExtraFilter: `AgentSessionID='${agentSessionID}' AND Status <> 'Disconnected'`,
+            ExtraFilter: `AgentSessionID IN (${inList}) AND Status <> 'Disconnected'`,
             ResultType: 'entity_object',
         }, contextUser);
-
         if (!result.Success) {
-            LogError(`SessionManager.disconnectChannels failed to load channels: ${result.ErrorMessage}`);
-            return;
+            LogError(`SessionManager.loadActiveChannels failed to load channels: ${result.ErrorMessage}`);
+            return [];
         }
-        const now = new Date();
-        for (const channel of result.Results) {
-            channel.Status = 'Disconnected';
-            channel.DisconnectedAt = now;
-            await this.saveOrLog(channel, 'disconnectChannels');
+        return result.Results;
+    }
+
+    /**
+     * Batch-loads active channels for many sessions at once and groups them by AgentSessionID
+     * (lowercased), so a sweep can disconnect a whole page of sessions with ONE query instead of
+     * one-per-session. Sessions with no active channels are absent from the map (callers default
+     * to []). Pass each session's slice to {@link CloseSession}'s `preloadedChannels`.
+     */
+    public async LoadActiveChannelsBySession(
+        sessionIDs: string[],
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<Map<string, MJAIAgentSessionChannelEntity[]>> {
+        const channels = await this.loadActiveChannels(sessionIDs, contextUser, provider);
+        const bySession = new Map<string, MJAIAgentSessionChannelEntity[]>();
+        for (const channel of channels) {
+            const key = String(channel.AgentSessionID).toLowerCase();
+            const list = bySession.get(key);
+            if (list) {
+                list.push(channel);
+            } else {
+                bySession.set(key, [channel]);
+            }
         }
+        return bySession;
     }
 
     /** True once the per-session coalescing window has elapsed since the last persisted write. */

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