@memberjunction/server 5.40.2 → 5.42.0

package/dist/agentSessions/SessionManager.js

@@ -0,0 +1,308 @@
+import { LogError, RunView } from '@memberjunction/core';
+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';
+/**
+ * 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) {
+        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 {
+    constructor() {
+        /** session ID (lowercased) → epoch ms of its last persisted `LastActiveAt` write. */
+        this.heartbeatLastWrite = new Map();
+    }
+    /**
+     * 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.
+     */
+    async CreateSession(input, contextUser, provider) {
+        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.
+     */
+    async CloseSession(agentSessionID, contextUser, provider, closeReason = 'Explicit') {
+        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.
+     */
+    async notifyChannelPluginsSessionStarted(session, contextUser, provider) {
+        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.
+     */
+    async notifyChannelPluginsSessionClosed(agentSessionID, closeReason) {
+        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.
+     */
+    async finalizeObservabilityRuns(session, contextUser, provider) {
+        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. */
+    parseSessionRunConfig(raw) {
+        if (!raw) {
+            return {};
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            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`).
+     */
+    async Heartbeat(agentSessionID, contextUser, provider) {
+        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.
+     */
+    async MarkIdle(agentSessionID, contextUser, provider) {
+        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. */
+    async assertCanRun(agentID, contextUser) {
+        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. */
+    async createConversation(input, contextUser, provider) {
+        const conversation = await provider.GetEntityObject(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. */
+    async persistNewSession(input, conversationID, contextUser, provider) {
+        const session = await provider.GetEntityObject(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. */
+    async loadSession(agentSessionID, contextUser, provider) {
+        const session = await provider.GetEntityObject(SESSION_ENTITY, contextUser);
+        const loaded = await session.Load(agentSessionID);
+        return loaded ? session : null;
+    }
+    /** Sets `Closed` + `ClosedAt` + `CloseReason` and saves. Returns the save result. */
+    async markSessionClosed(session, closeReason) {
+        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. */
+    async disconnectChannels(agentSessionID, contextUser, provider) {
+        const rv = RunView.FromMetadataProvider(provider);
+        const result = await rv.RunView({
+            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. */
+    heartbeatWriteDue(key) {
+        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.
+     */
+    shouldForceWrite(key, _provider) {
+        return !this.heartbeatLastWrite.has(key);
+    }
+    /** Loads, bumps `LastActiveAt`, reactivates `Idle → Active`, saves, and records the write time. */
+    async persistHeartbeat(agentSessionID, contextUser, provider) {
+        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. */
+    async saveOrLog(entity, op) {
+        const saved = await entity.Save();
+        if (!saved) {
+            LogError(`SessionManager.${op} save failed: ${entity.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+        }
+        return saved;
+    }
+}
+//# sourceMappingURL=SessionManager.js.map

package/dist/agentSessions/SessionManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionManager.js","sourceRoot":"","sources":["../../src/agentSessions/SessionManager.ts"],"names":[],"mappings":"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"}

package/dist/agentSessions/index.d.ts

@@ -0,0 +1,5 @@
+export * from './remoteBrowserGoalEngine.js';
+export * from './HostInstance.js';
+export * from './SessionManager.js';
+export * from './SessionJanitor.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/agentSessions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agentSessions/index.ts"],"names":[],"mappings":"AA4BA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC"}

package/dist/agentSessions/index.js

@@ -0,0 +1,31 @@
+/**
+ * @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';
+//# sourceMappingURL=index.js.map

package/dist/agentSessions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agentSessions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,2BAA2B,EAAE,gCAAgC,EAAE,MAAM,2BAA2B,CAAC;AAC1G,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,MAAM,yCAAyC,CAAC;AACpF,OAAO,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAC;AAE3E,8EAA8E;AAC9E,gGAAgG;AAChG,6FAA6F;AAC7F,2BAA2B,EAAE,CAAC;AAC9B,gCAAgC,EAAE,CAAC;AACnC,gGAAgG;AAChG,iGAAiG;AACjG,gGAAgG;AAChG,wBAAwB,EAAE,CAAC;AAC3B,yBAAyB,EAAE,CAAC;AAC5B,wGAAwG;AACxG,wGAAwG;AACxG,2BAA2B,EAAE,CAAC;AAE9B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC"}

package/dist/agentSessions/remoteBrowserGoalEngine.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @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, IMetadataProvider } from '@memberjunction/core';
+import { MJAIAgentRunStepEntity } from '@memberjunction/core-entities';
+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 { 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 declare function buildMJGoalParams(params: RunComputerUseParams, contextUser?: UserInfo, agentRunID?: string, agentRunStepID?: string): MJRunComputerUseParams;
+/**
+ * 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 declare class MJProgressComputerUseEngine extends MJComputerUseEngine implements ComputerUseGoalRun {
+    /** Per-step progress hook the CDP session sets before {@link Run} (drives live narration). */
+    OnProgress?: (progress: ComputerUseGoalProgress) => void;
+    /** The MJ user the goal run executes as; the CDP session sets it from the session's context user. */
+    ContextUser?: UserInfo;
+    /** Parent agent-run id the CDP session sets before {@link Run} (links the goal's prompt runs to it). */
+    AgentRunID?: string;
+    /** Parent agent-run-step id the CDP session sets before {@link Run} (nests child prompt steps under it). */
+    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.
+     */
+    Run(params: RunComputerUseParams): Promise<ComputerUseResult>;
+    protected onStepComplete(step: StepRecord, params: MJRunComputerUseParams): void;
+}
+/**
+ * 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 declare function extractCoAgentRunID(configJson: string | null | undefined): string | undefined;
+/**
+ * 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 declare function beginBrowserGoalStep(provider: IMetadataProvider, contextUser: UserInfo | undefined, coAgentRunID: string | undefined, goal: string): Promise<MJAIAgentRunStepEntity | 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 declare function finalizeBrowserGoalStep(step: MJAIAgentRunStepEntity | null, result: RemoteBrowserGoalResult): Promise<void>;
+/**
+ * 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 declare function BindRemoteBrowserGoalEngine(): void;
+//# sourceMappingURL=remoteBrowserGoalEngine.d.ts.map

package/dist/agentSessions/remoteBrowserGoalEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remoteBrowserGoalEngine.d.ts","sourceRoot":"","sources":["../../src/agentSessions/remoteBrowserGoalEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,QAAQ,EAAY,iBAAiB,EAAW,MAAM,sBAAsB,CAAC;AACtF,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAEvE,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AACxG,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAClG,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AACnF,OAAO,EAA8C,KAAK,uBAAuB,EAAE,KAAK,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAEvJ;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,oBAAoB,EAAE,WAAW,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,sBAAsB,CAM5J;AAED;;;;;;;;;;GAUG;AACH,qBAAa,2BAA4B,SAAQ,mBAAoB,YAAW,kBAAkB;IAChG,8FAA8F;IACvF,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,uBAAuB,KAAK,IAAI,CAAC;IAEhE,qGAAqG;IAC9F,WAAW,CAAC,EAAE,QAAQ,CAAC;IAE9B,wGAAwG;IACjG,UAAU,CAAC,EAAE,MAAM,CAAC;IAE3B,4GAA4G;IACrG,cAAc,CAAC,EAAE,MAAM,CAAC;IAE/B;;;;;;;OAOG;IACmB,GAAG,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,iBAAiB,CAAC;cAIhE,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,sBAAsB,GAAG,IAAI;CAI1F;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAU7F;AAQD;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,iBAAiB,EAC3B,WAAW,EAAE,QAAQ,GAAG,SAAS,EACjC,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAuBxC;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,sBAAsB,GAAG,IAAI,EAAE,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBjI;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAMlD"}

package/dist/agentSessions/remoteBrowserGoalEngine.js

@@ -0,0 +1,164 @@
+/**
+ * @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 { LogError, RunView } from '@memberjunction/core';
+import { initAgentRunStep, finalizeAgentRunStep } from '@memberjunction/ai-core-plus';
+import { MJComputerUseEngine, MJRunComputerUseParams } from '@memberjunction/computer-use-engine';
+import { buildProgressNote, CdpRemoteBrowserSession } 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, contextUser, agentRunID, agentRunStepID) {
+    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 {
+    /**
+     * 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.
+     */
+    async Run(params) {
+        return super.Run(buildMJGoalParams(params, this.ContextUser, this.AgentRunID, this.AgentRunStepID));
+    }
+    onStepComplete(step, params) {
+        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) {
+    if (!configJson) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(configJson);
+        return typeof parsed.coAgentRunID === 'string' ? parsed.coAgentRunID : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Truncates a goal to a step-name-friendly length. */
+function goalStepName(goal) {
+    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, contextUser, coAgentRunID, goal) {
+    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('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, result) {
+    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() {
+    try {
+        CdpRemoteBrowserSession.SetGoalEngineFactory(() => new MJProgressComputerUseEngine());
+    }
+    catch (err) {
+        LogError(`[RemoteBrowserGoalEngine] Failed to bind MJ computer-use goal engine: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+//# sourceMappingURL=remoteBrowserGoalEngine.js.map