@memberjunction/server 5.40.2 → 5.42.0

package/src/agentSessions/SessionManager.ts

@@ -0,0 +1,446 @@
+import { IMetadataProvider, UserInfo, LogError, RunView } from '@memberjunction/core';
+import {
+    MJAIAgentSessionEntity,
+    MJAIAgentSessionChannelEntity,
+    MJConversationEntity,
+} from '@memberjunction/core-entities';
+import { AIAgentPermissionHelper } from '@memberjunction/ai-engine-base';
+import { RealtimeClientSessionService, RealtimeChannelServerHost } from '@memberjunction/ai-agents';
+import { GetHostInstanceID } from './HostInstance.js';
+
+/** Entity names — centralised so the `MJ:`-prefix convention is applied in exactly one place. */
+const SESSION_ENTITY = 'MJ: AI Agent Sessions';
+const SESSION_CHANNEL_ENTITY = 'MJ: AI Agent Session Channels';
+const CONVERSATION_ENTITY = 'MJ: Conversations';
+
+/**
+ * Shape of the observability run ids a realtime voice session persists in `AIAgentSession.Config_`.
+ * Read on {@link SessionManager.CloseSession} to finalize the co-agent runs. All fields optional —
+ * a non-voice session (or one whose run creation was skipped) carries none of them.
+ */
+interface SessionRunConfig {
+    coAgentRunID?: string;
+    promptRunID?: string;
+    /** The co-agent run's single system-prompt `MJ: AI Agent Run Steps` row id (its Timeline entry). */
+    coAgentRunStepID?: string;
+}
+
+/**
+ * Inputs for {@link SessionManager.CreateSession}. `conversationID`/`lastSessionID`/`config`
+ * are optional — when no `conversationID` is supplied a fresh Conversation is created and linked.
+ */
+export interface CreateSessionInput {
+    /** The agent the session will run. Authorized via `CanRun` before any row is written. */
+    agentID: string;
+    /** The owning user. Persisted as `AIAgentSession.UserID`; enforced on every inbound envelope. */
+    userID: string;
+    /** Existing conversation to attach to. If omitted, a new one is created and linked. */
+    conversationID?: string;
+    /** Prior (closed) session being resumed — chained via `LastSessionID`. */
+    lastSessionID?: string;
+    /** Free-form, low-traffic session state. Serialized verbatim into `AIAgentSession.Config`. */
+    config?: string;
+}
+
+/**
+ * Why a session was closed — persisted to `AIAgentSession.CloseReason` alongside the
+ * `Status = 'Closed'` transition so the admin dashboards can distinguish a user hanging up
+ * (`Explicit`) from janitor reconciliation (`Janitor`), a graceful host drain (`Shutdown`),
+ * or a failure-path teardown (`Error`). `NULL` in the column means "legacy/unknown" — rows
+ * closed before this column existed.
+ */
+export type SessionCloseReason = 'Explicit' | 'Janitor' | 'Shutdown' | 'Error';
+
+/**
+ * Thrown by {@link SessionManager.CreateSession} when the caller lacks `CanRun` on the target
+ * agent. No session row is created — denial happens before any write. Distinct error type so the
+ * resolver layer can map it to an authorization-shaped GraphQL error rather than a generic failure.
+ */
+export class SessionAuthorizationError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'SessionAuthorizationError';
+    }
+}
+
+/**
+ * Minimum interval between persisted `LastActiveAt` writes for a single session. A chatty channel
+ * (e.g. an audio heartbeat every ~200ms) must not turn into a DB write storm — heartbeats inside
+ * this window are coalesced in-memory and dropped. Mirrors the `SetSettingDebounced` philosophy.
+ */
+const HEARTBEAT_MIN_WRITE_INTERVAL_MS = 3_000;
+
+/**
+ * Server-side lifecycle manager for `AIAgentSession` **records** (not the media/socket transport —
+ * that arrives in P5). Stateless with respect to the caller: every method takes the request's
+ * `contextUser` and request-scoped `IMetadataProvider` so all entity operations run under the
+ * correct identity/provider and never pin the process-global provider.
+ *
+ * The only in-memory state it holds is a small per-session last-heartbeat-write timestamp map used
+ * purely to coalesce {@link Heartbeat} writes; it carries no user or provider state across calls.
+ *
+ * Responsibilities:
+ * - **Create** — authorize (`CanRun`), optionally mint a Conversation, persist an `Active` session.
+ * - **Close** — terminal transition; disconnect channels; idempotent.
+ * - **Heartbeat** — coalesced `LastActiveAt` bump; reactivates `Idle → Active`.
+ * - **MarkIdle** — `Active → Idle` transition when the last channel goes quiet.
+ *
+ * @remarks
+ * P5 will extend {@link CloseSession} to also abort any in-flight `AIAgentRun` (via its cancellation
+ * token) and call `ClientToolRequestManager.ClearSession(...)`; those resources don't exist yet at
+ * this layer, so close here only reconciles the durable record + channel rows.
+ */
+export class SessionManager {
+    /** session ID (lowercased) → epoch ms of its last persisted `LastActiveAt` write. */
+    private heartbeatLastWrite = new Map<string, number>();
+
+    /**
+     * Authorize and create a new session. Flow:
+     * 1. `CanRun` check on the agent — denied → {@link SessionAuthorizationError}, no row written.
+     * 2. Resolve the conversation (use the supplied one, or create+link a fresh Conversation).
+     * 3. Persist the `AIAgentSession` as `Active`, stamped with this host and `LastActiveAt = now`.
+     *
+     * @returns the saved {@link MJAIAgentSessionEntity}.
+     * @throws {SessionAuthorizationError} when the user may not run the agent.
+     * @throws {Error} when conversation creation or session save fails.
+     */
+    public async CreateSession(
+        input: CreateSessionInput,
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<MJAIAgentSessionEntity> {
+        await this.assertCanRun(input.agentID, contextUser);
+
+        const conversationID = input.conversationID
+            ?? await this.createConversation(input, contextUser, provider);
+
+        const session = await this.persistNewSession(input, conversationID, contextUser, provider);
+        await this.notifyChannelPluginsSessionStarted(session, contextUser, provider);
+        return session;
+    }
+
+    /**
+     * Close a session (terminal). Sets `Status = 'Closed'` + `ClosedAt = now` + `CloseReason`, then
+     * disconnects all of its channel rows. Idempotent: closing an already-`Closed` session is a
+     * no-op that returns `true` (and never overwrites the original `CloseReason`). A
+     * missing/unloadable session returns `false`.
+     *
+     * @param closeReason Why the session is being closed. **Defaults to `'Explicit'`** so existing
+     *   call sites (the user-initiated close mutations) stamp the common case without modification;
+     *   background callers (janitor sweeps, shutdown drain, error teardowns) must pass their reason
+     *   explicitly. `NULL` rows remain only for legacy data closed before the column existed.
+     *
+     * @remarks P5 adds in-flight-run abort + `ClientToolRequestManager.ClearSession` here.
+     */
+    public async CloseSession(
+        agentSessionID: string,
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+        closeReason: SessionCloseReason = 'Explicit',
+    ): Promise<boolean> {
+        const session = await this.loadSession(agentSessionID, contextUser, provider);
+        if (!session) {
+            return false;
+        }
+        this.heartbeatLastWrite.delete(agentSessionID.toLowerCase());
+
+        if (session.Status === 'Closed') {
+            // Idempotent — already terminal. Still notify the channel-plugin host so a session
+            // whose plugin instances live in THIS process is cleaned up even when another host
+            // instance won the close race (the host no-ops for sessions it doesn't hold).
+            await this.notifyChannelPluginsSessionClosed(agentSessionID, session.CloseReason ?? null);
+            return true;
+        }
+
+        const closed = await this.markSessionClosed(session, closeReason);
+        if (!closed) {
+            return false;
+        }
+        await this.disconnectChannels(agentSessionID, contextUser, provider);
+        await this.finalizeObservabilityRuns(session, contextUser, provider);
+        await this.notifyChannelPluginsSessionClosed(agentSessionID, closeReason);
+        return true;
+    }
+
+    /**
+     * Notifies the server-side channel-plugin host that a session started, so it can resolve the
+     * ACTIVE `MJ: AI Agent Channels` rows' `ServerPluginClass` plugins (one fresh instance per
+     * channel, per session) and fire their start hooks. Strictly best-effort: the host itself
+     * never throws, and this guard makes session creation immune to any plugin-layer surprise.
+     */
+    private async notifyChannelPluginsSessionStarted(
+        session: MJAIAgentSessionEntity,
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<void> {
+        try {
+            await RealtimeChannelServerHost.Instance.OnSessionStarted(
+                {
+                    AgentSessionID: session.ID,
+                    AgentID: session.AgentID,
+                    UserID: session.UserID,
+                    ConversationID: session.ConversationID ?? null,
+                },
+                contextUser,
+                provider,
+            );
+        } catch (e) {
+            LogError(`SessionManager.notifyChannelPluginsSessionStarted failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+
+    /**
+     * Notifies the server-side channel-plugin host that a session closed (fires each plugin's
+     * `OnSessionClosed` hook and schedules disposal). Invoked from EVERY close provenance —
+     * explicit hang-up, janitor sweeps, shutdown drain, and error teardowns all funnel through
+     * {@link CloseSession}. Strictly best-effort, same posture as the start notification.
+     */
+    private async notifyChannelPluginsSessionClosed(
+        agentSessionID: string,
+        closeReason: SessionCloseReason | null,
+    ): Promise<void> {
+        try {
+            await RealtimeChannelServerHost.Instance.OnSessionClosed(agentSessionID, closeReason);
+        } catch (e) {
+            LogError(`SessionManager.notifyChannelPluginsSessionClosed failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+
+    /**
+     * Finalizes the co-agent observability runs a realtime voice session stored in its `Config_`
+     * (see `RealtimeClientSessionResolver`). No-op when the config carries no run ids. Tolerant: a
+     * malformed config or a finalize failure is swallowed so it can never break session close.
+     */
+    private async finalizeObservabilityRuns(
+        session: MJAIAgentSessionEntity,
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<void> {
+        const config = this.parseSessionRunConfig(session.Config_);
+        if (!config.coAgentRunID && !config.promptRunID && !config.coAgentRunStepID) {
+            return;
+        }
+        try {
+            await new RealtimeClientSessionService().FinalizeCoAgentRun(
+                config.coAgentRunID ?? null,
+                config.promptRunID ?? null,
+                contextUser,
+                provider,
+                true,
+                config.coAgentRunStepID ?? null,
+            );
+        } catch (e) {
+            LogError(`SessionManager.finalizeObservabilityRuns failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+
+    /** Parses the session's `Config_` for observability run ids; returns an empty config on any error. */
+    private parseSessionRunConfig(raw: string | null): SessionRunConfig {
+        if (!raw) {
+            return {};
+        }
+        try {
+            const parsed = JSON.parse(raw) as Partial<SessionRunConfig>;
+            return {
+                coAgentRunID: typeof parsed.coAgentRunID === 'string' ? parsed.coAgentRunID : undefined,
+                promptRunID: typeof parsed.promptRunID === 'string' ? parsed.promptRunID : undefined,
+                coAgentRunStepID: typeof parsed.coAgentRunStepID === 'string' ? parsed.coAgentRunStepID : undefined,
+            };
+        } catch {
+            return {};
+        }
+    }
+
+    /**
+     * Record activity on a session. Coalesces persisted writes so at most one `LastActiveAt` update
+     * lands per session per {@link HEARTBEAT_MIN_WRITE_INTERVAL_MS}; intervening calls return `true`
+     * without touching the DB. Reactivates an `Idle` session to `Active`. A `Closed` session is not
+     * reactivated (returns `false`).
+     */
+    public async Heartbeat(
+        agentSessionID: string,
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<boolean> {
+        const key = agentSessionID.toLowerCase();
+        const reactivating = this.shouldForceWrite(key, provider);
+        if (!reactivating && !this.heartbeatWriteDue(key)) {
+            return true; // coalesced — skip the DB round-trip
+        }
+        return this.persistHeartbeat(agentSessionID, contextUser, provider);
+    }
+
+    /**
+     * Transition an `Active` session to `Idle` (e.g. when its last channel disconnects). No-op when
+     * the session is already `Idle` or `Closed`. Returns `true` on success / no-op-needed.
+     */
+    public async MarkIdle(
+        agentSessionID: string,
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<boolean> {
+        const session = await this.loadSession(agentSessionID, contextUser, provider);
+        if (!session) {
+            return false;
+        }
+        if (session.Status !== 'Active') {
+            return true; // only Active → Idle is meaningful
+        }
+        session.Status = 'Idle';
+        return this.saveOrLog(session, 'MarkIdle');
+    }
+
+    // ----- internals -------------------------------------------------------------------------
+
+    /** Throws {@link SessionAuthorizationError} unless the user has `CanRun` on the agent. */
+    private async assertCanRun(agentID: string, contextUser: UserInfo): Promise<void> {
+        const canRun = await AIAgentPermissionHelper.HasPermission(agentID, contextUser, 'run');
+        if (!canRun) {
+            throw new SessionAuthorizationError(
+                `User ${contextUser.Email} is not permitted to open a session for agent ${agentID}`,
+            );
+        }
+    }
+
+    /** Creates and links a new Conversation for the session, returning its ID. */
+    private async createConversation(
+        input: CreateSessionInput,
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<string> {
+        const conversation = await provider.GetEntityObject<MJConversationEntity>(CONVERSATION_ENTITY, contextUser);
+        conversation.NewRecord();
+        conversation.UserID = input.userID;
+        conversation.Name = 'Agent Session';
+
+        const saved = await conversation.Save();
+        if (!saved) {
+            throw new Error(
+                `Failed to create Conversation for agent session: ${conversation.LatestResult?.CompleteMessage ?? 'unknown error'}`,
+            );
+        }
+        return conversation.ID;
+    }
+
+    /** Persists the new session row as `Active` and returns the saved entity. */
+    private async persistNewSession(
+        input: CreateSessionInput,
+        conversationID: string,
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<MJAIAgentSessionEntity> {
+        const session = await provider.GetEntityObject<MJAIAgentSessionEntity>(SESSION_ENTITY, contextUser);
+        session.NewRecord();
+        session.AgentID = input.agentID;
+        session.UserID = input.userID;
+        session.Status = 'Active';
+        session.ConversationID = conversationID;
+        session.LastSessionID = input.lastSessionID ?? null;
+        session.HostInstanceID = GetHostInstanceID();
+        session.Config_ = input.config ?? null;
+        session.LastActiveAt = new Date();
+
+        const saved = await session.Save();
+        if (!saved) {
+            throw new Error(
+                `Failed to create agent session: ${session.LatestResult?.CompleteMessage ?? 'unknown error'}`,
+            );
+        }
+        return session;
+    }
+
+    /** Loads a session entity by ID, returning null when it cannot be loaded. */
+    private async loadSession(
+        agentSessionID: string,
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<MJAIAgentSessionEntity | null> {
+        const session = await provider.GetEntityObject<MJAIAgentSessionEntity>(SESSION_ENTITY, contextUser);
+        const loaded = await session.Load(agentSessionID);
+        return loaded ? session : null;
+    }
+
+    /** Sets `Closed` + `ClosedAt` + `CloseReason` and saves. Returns the save result. */
+    private async markSessionClosed(
+        session: MJAIAgentSessionEntity,
+        closeReason: SessionCloseReason,
+    ): Promise<boolean> {
+        session.Status = 'Closed';
+        session.ClosedAt = new Date();
+        session.CloseReason = closeReason;
+        return this.saveOrLog(session, 'CloseSession');
+    }
+
+    /** Marks every channel row of the session `Disconnected` (with `DisconnectedAt`), if not already. */
+    private async disconnectChannels(
+        agentSessionID: string,
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<void> {
+        const rv = RunView.FromMetadataProvider(provider);
+        const result = await rv.RunView<MJAIAgentSessionChannelEntity>({
+            EntityName: SESSION_CHANNEL_ENTITY,
+            ExtraFilter: `AgentSessionID='${agentSessionID}' AND Status <> 'Disconnected'`,
+            ResultType: 'entity_object',
+        }, contextUser);
+
+        if (!result.Success) {
+            LogError(`SessionManager.disconnectChannels 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');
+        }
+    }
+
+    /** True once the per-session coalescing window has elapsed since the last persisted write. */
+    private heartbeatWriteDue(key: string): boolean {
+        const last = this.heartbeatLastWrite.get(key);
+        return last == null || (Date.now() - last) >= HEARTBEAT_MIN_WRITE_INTERVAL_MS;
+    }
+
+    /**
+     * Whether this heartbeat must write regardless of the coalescing window. We force a write the
+     * first time we see a session (no cached timestamp) so an `Idle → Active` reactivation is never
+     * swallowed by coalescing.
+     */
+    private shouldForceWrite(key: string, _provider: IMetadataProvider): boolean {
+        return !this.heartbeatLastWrite.has(key);
+    }
+
+    /** Loads, bumps `LastActiveAt`, reactivates `Idle → Active`, saves, and records the write time. */
+    private async persistHeartbeat(
+        agentSessionID: string,
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<boolean> {
+        const session = await this.loadSession(agentSessionID, contextUser, provider);
+        if (!session || session.Status === 'Closed') {
+            return false;
+        }
+        session.LastActiveAt = new Date();
+        if (session.Status === 'Idle') {
+            session.Status = 'Active';
+        }
+        const saved = await this.saveOrLog(session, 'Heartbeat');
+        if (saved) {
+            this.heartbeatLastWrite.set(agentSessionID.toLowerCase(), Date.now());
+        }
+        return saved;
+    }
+
+    /** Saves an entity, logging `CompleteMessage` on failure. Returns the boolean save result. */
+    private async saveOrLog(
+        entity: MJAIAgentSessionEntity | MJAIAgentSessionChannelEntity,
+        op: string,
+    ): Promise<boolean> {
+        const saved = await entity.Save();
+        if (!saved) {
+            LogError(`SessionManager.${op} save failed: ${entity.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+        }
+        return saved;
+    }
+}

package/src/agentSessions/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview AI Agent Session lifecycle substrate (server-side, record + janitor layer).
+ *
+ * Exposes the session-record lifecycle manager, the orphan-reconciliation janitor, and the
+ * per-process host identity helpers. The audio/media (WebRTC) transport and the long-lived
+ * realtime agent run are deliberately **not** part of this layer — they arrive in P5.
+ *
+ * @module @memberjunction/server
+ */
+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
+// the session lifecycle — `SessionManager.CreateSession` resolves them via the ClassFactory.
+LoadWhiteboardChannelServer();
+LoadMeetingControlsChannelServer();
+// Remote Browser native channel (client-direct): the lifecycle-only server channel plugin + the
+// Self-Hosted Chrome backend driver (whose default runner launches a local headless Chromium via
+// 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)}`);
+  }
+}