@memberjunction/server 5.40.2 → 5.42.0

package/dist/resolvers/RemoteBrowserActionResolver.js

@@ -0,0 +1,1108 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+/**
+ * @fileoverview GraphQL resolvers for the **Remote Browser** native realtime channel, CLIENT-DIRECT
+ * topology.
+ *
+ * Realtime sessions are client-direct: the model talks to the browser, and the agent's browser-driving
+ * tools execute CLIENT-side (like the live Whiteboard). Each client-executed browser tool relays its
+ * intent to the server through {@link RemoteBrowserActionResolver.ExecuteRemoteBrowserAction}, which drives
+ * the server-side {@link RemoteBrowserEngine}'s live browser. A second query,
+ * {@link RemoteBrowserActionResolver.RemoteBrowserSnapshot}, returns the current screenshot + URL for the
+ * client's live view.
+ *
+ * Both operations are **ownership-gated** exactly like {@link import('./RealtimeClientSessionResolver.js').RealtimeClientSessionResolver}:
+ * the `AIAgentSession.UserID` must equal the calling user. The mutation lazily starts the browser on first
+ * use — so a realtime session that never touches the browser never launches Chrome — resolving the backend
+ * from the agent's `TypeConfiguration` (`{ remoteBrowser: { provider } }`), else the single Active provider.
+ *
+ * @module @memberjunction/server
+ */
+import { Resolver, Mutation, Query, Arg, Ctx, Float, Int, ObjectType, Field, PubSub, PubSubEngine } from 'type-graphql';
+import { LogError } from '@memberjunction/core';
+import { UUIDsEqual } from '@memberjunction/global';
+import { RemoteBrowserEngine } from '@memberjunction/remote-browser-server';
+import { beginBrowserGoalStep, finalizeBrowserGoalStep, extractCoAgentRunID } from '../agentSessions/remoteBrowserGoalEngine.js';
+import { RemoteBrowserGoalRegistry } from '../agentSessions/remoteBrowserGoalRegistry.js';
+import { randomUUID } from 'node:crypto';
+import { RemoteBrowserCapabilityNotSupportedError, } from '@memberjunction/remote-browser-base';
+import { ResolverBase } from '../generic/ResolverBase.js';
+import { GetReadWriteProvider } from '../util.js';
+import { PUSH_STATUS_UPDATES_TOPIC } from '../generic/PushStatusResolver.js';
+import { AIEngine } from '@memberjunction/aiengine';
+import { AIPromptRunner } from '@memberjunction/ai-prompts';
+import { AIPromptParams } from '@memberjunction/ai-core-plus';
+/** Entity name — centralised so the `MJ:`-prefix convention is applied in exactly one place. */
+const SESSION_ENTITY = 'MJ: AI Agent Sessions';
+/** Entity name for the agent whose `TypeConfiguration` carries the remote-browser provider preference. */
+const AGENT_ENTITY = 'MJ: AI Agents';
+/**
+ * Name of the governable vision AI Prompt that interprets a browser screenshot for a non-vision voice agent.
+ * Seeded as metadata (`metadata/prompts/.remote-browser-visual-interpreter-prompt.json`) and pinned to the
+ * `Gemini 3.1 Flash-Lite` model via its `MJ: AI Prompt Models` association — so the model is chosen by the
+ * prompt's own configuration, not hard-coded here.
+ */
+const VISUAL_INTERPRETER_PROMPT_NAME = 'Remote Browser Visual Interpreter';
+/**
+ * Result of {@link RemoteBrowserActionResolver.ExecuteRemoteBrowserAction} — the outcome of one browser
+ * action plus the resulting URL the client narrates / displays.
+ */
+let RemoteBrowserActionResult = class RemoteBrowserActionResult {
+};
+__decorate([
+    Field(() => Boolean),
+    __metadata("design:type", Boolean)
+], RemoteBrowserActionResult.prototype, "Success", void 0);
+__decorate([
+    Field(() => String, { nullable: true }),
+    __metadata("design:type", String)
+], RemoteBrowserActionResult.prototype, "CurrentUrl", void 0);
+__decorate([
+    Field(() => String, { nullable: true }),
+    __metadata("design:type", String)
+], RemoteBrowserActionResult.prototype, "Detail", void 0);
+RemoteBrowserActionResult = __decorate([
+    ObjectType()
+], RemoteBrowserActionResult);
+export { RemoteBrowserActionResult };
+/**
+ * Result of {@link RemoteBrowserActionResolver.ExecuteRemoteBrowserGoal} — the outcome of an autonomous,
+ * goal-driven browser run (computer-use loop or backend native AI).
+ */
+let RemoteBrowserGoalResultType = class RemoteBrowserGoalResultType {
+};
+__decorate([
+    Field(() => Boolean),
+    __metadata("design:type", Boolean)
+], RemoteBrowserGoalResultType.prototype, "Success", void 0);
+__decorate([
+    Field(() => String, { nullable: true }),
+    __metadata("design:type", String)
+], RemoteBrowserGoalResultType.prototype, "GoalRunID", void 0);
+__decorate([
+    Field(() => String, { nullable: true }),
+    __metadata("design:type", String)
+], RemoteBrowserGoalResultType.prototype, "Strategy", void 0);
+__decorate([
+    Field(() => String, { nullable: true }),
+    __metadata("design:type", String)
+], RemoteBrowserGoalResultType.prototype, "CurrentUrl", void 0);
+__decorate([
+    Field(() => String, { nullable: true }),
+    __metadata("design:type", String)
+], RemoteBrowserGoalResultType.prototype, "Status", void 0);
+__decorate([
+    Field(() => Int, { nullable: true }),
+    __metadata("design:type", Number)
+], RemoteBrowserGoalResultType.prototype, "StepCount", void 0);
+__decorate([
+    Field(() => String, { nullable: true }),
+    __metadata("design:type", String)
+], RemoteBrowserGoalResultType.prototype, "Detail", void 0);
+RemoteBrowserGoalResultType = __decorate([
+    ObjectType()
+], RemoteBrowserGoalResultType);
+export { RemoteBrowserGoalResultType };
+/**
+ * Result of {@link RemoteBrowserActionResolver.RemoteBrowserSnapshot} — the current viewport screenshot +
+ * URL for the client's live view. Both fields are null when the session holds no live browser.
+ */
+let RemoteBrowserSnapshot = class RemoteBrowserSnapshot {
+};
+__decorate([
+    Field(() => String, { nullable: true }),
+    __metadata("design:type", String)
+], RemoteBrowserSnapshot.prototype, "ScreenshotBase64", void 0);
+__decorate([
+    Field(() => String, { nullable: true }),
+    __metadata("design:type", String)
+], RemoteBrowserSnapshot.prototype, "CurrentUrl", void 0);
+RemoteBrowserSnapshot = __decorate([
+    ObjectType()
+], RemoteBrowserSnapshot);
+export { RemoteBrowserSnapshot };
+/**
+ * Result of {@link RemoteBrowserActionResolver.StartRemoteBrowserScreencast} — whether the live CDP
+ * screencast started. When `false` the backend lacks the `ScreenStreaming` capability (or the start
+ * failed); the client keeps its 700ms snapshot poll as the fallback live view. When `true` the server
+ * is now PUSHING encoded frames on the user's push-status topic and the client paints them on a canvas.
+ */
+let RemoteBrowserScreencastResult = class RemoteBrowserScreencastResult {
+};
+__decorate([
+    Field(() => Boolean),
+    __metadata("design:type", Boolean)
+], RemoteBrowserScreencastResult.prototype, "Streaming", void 0);
+RemoteBrowserScreencastResult = __decorate([
+    ObjectType()
+], RemoteBrowserScreencastResult);
+export { RemoteBrowserScreencastResult };
+/**
+ * Result of {@link RemoteBrowserActionResolver.StartRemoteBrowserAudioStream} — whether the live tab-audio
+ * stream started. When `false` the backend lacks an audio-capture mechanism (v1 gates audio by backend
+ * implementation, not a metadata flag) or the start failed; the client simply plays no audio. When `true`
+ * the server is now PUSHING encoded audio chunks on the user's push-status topic and the client plays them.
+ */
+let RemoteBrowserAudioStreamResult = class RemoteBrowserAudioStreamResult {
+};
+__decorate([
+    Field(() => Boolean),
+    __metadata("design:type", Boolean)
+], RemoteBrowserAudioStreamResult.prototype, "Streaming", void 0);
+RemoteBrowserAudioStreamResult = __decorate([
+    ObjectType()
+], RemoteBrowserAudioStreamResult);
+export { RemoteBrowserAudioStreamResult };
+/**
+ * Result of {@link RemoteBrowserActionResolver.GetRemoteBrowserSelection} — the remote page's current text
+ * selection, the copy-out half of human clipboard support. `Text` is `''` when nothing is selected, no live
+ * browser exists, or the backend can't read the selection (the client then writes nothing to the clipboard).
+ */
+let RemoteBrowserSelection = class RemoteBrowserSelection {
+};
+__decorate([
+    Field(() => String),
+    __metadata("design:type", String)
+], RemoteBrowserSelection.prototype, "Text", void 0);
+RemoteBrowserSelection = __decorate([
+    ObjectType()
+], RemoteBrowserSelection);
+export { RemoteBrowserSelection };
+/**
+ * One UI element the visual interpreter localized in the screenshot — a label plus the pixel centroid the
+ * voice agent can feed straight into `browser_Click(x, y)`. Coordinates are in the SCREENSHOT's own pixel
+ * space (top-left origin), which equals the live browser viewport.
+ */
+let RemoteBrowserInterpretedElement = class RemoteBrowserInterpretedElement {
+};
+__decorate([
+    Field(),
+    __metadata("design:type", String)
+], RemoteBrowserInterpretedElement.prototype, "Label", void 0);
+__decorate([
+    Field(() => Float),
+    __metadata("design:type", Number)
+], RemoteBrowserInterpretedElement.prototype, "X", void 0);
+__decorate([
+    Field(() => Float),
+    __metadata("design:type", Number)
+], RemoteBrowserInterpretedElement.prototype, "Y", void 0);
+__decorate([
+    Field(() => Float),
+    __metadata("design:type", Number)
+], RemoteBrowserInterpretedElement.prototype, "Confidence", void 0);
+RemoteBrowserInterpretedElement = __decorate([
+    ObjectType()
+], RemoteBrowserInterpretedElement);
+export { RemoteBrowserInterpretedElement };
+/**
+ * Result of {@link RemoteBrowserActionResolver.InterpretRemoteBrowserPage} — how a fast vision model "sees"
+ * the current browser viewport on behalf of a voice agent that cannot view images. `Description` is a concise
+ * text summary; `Elements` localizes any UI elements the request asked for (empty for a plain describe).
+ * `Detail` carries a non-fatal note (e.g. `'no live browser'` or a vision-error message) — every path is
+ * best-effort and never throws.
+ */
+let RemoteBrowserInterpretation = class RemoteBrowserInterpretation {
+};
+__decorate([
+    Field(() => String, { nullable: true }),
+    __metadata("design:type", String)
+], RemoteBrowserInterpretation.prototype, "Description", void 0);
+__decorate([
+    Field(() => [RemoteBrowserInterpretedElement]),
+    __metadata("design:type", Array)
+], RemoteBrowserInterpretation.prototype, "Elements", void 0);
+__decorate([
+    Field(() => String, { nullable: true }),
+    __metadata("design:type", String)
+], RemoteBrowserInterpretation.prototype, "Detail", void 0);
+RemoteBrowserInterpretation = __decorate([
+    ObjectType()
+], RemoteBrowserInterpretation);
+export { RemoteBrowserInterpretation };
+/**
+ * Resolver for the Remote Browser native realtime channel. A single {@link RemoteBrowserEngine} instance
+ * (the process-wide singleton) backs every request; ownership is enforced per call against the session's
+ * `UserID`.
+ */
+let RemoteBrowserActionResolver = class RemoteBrowserActionResolver extends ResolverBase {
+    constructor() {
+        super(...arguments);
+        /**
+         * Agent-session ids whose live CDP screencast this resolver has already started. Keyed by
+         * `agentSessionID` so a re-issued {@link RemoteBrowserActionResolver.StartRemoteBrowserScreencast}
+         * (e.g. the surface re-binding after a tab collapse) is idempotent and never stacks two screencasts
+         * on the one session. Entries are removed by {@link RemoteBrowserActionResolver.StopRemoteBrowserScreencast}.
+         */
+        this.startedScreencasts = new Set();
+        /**
+         * Agent-session ids whose live tab-audio stream this resolver has already started. Keyed by
+         * `agentSessionID` so a re-issued {@link RemoteBrowserActionResolver.StartRemoteBrowserAudioStream}
+         * (the surface re-binding) is idempotent and never stacks two captures on the one session. Entries are
+         * removed by {@link RemoteBrowserActionResolver.StopRemoteBrowserAudioStream}.
+         */
+        this.startedAudioStreams = new Set();
+    }
+    /**
+     * Execute ONE browser action relayed from the client-direct realtime session, returning the outcome +
+     * resulting URL.
+     *
+     * Flow:
+     * 1. Ownership gate — the session's `UserID` must equal the caller's (throws otherwise).
+     * 2. Lazily start (or reuse) the session's browser via {@link RemoteBrowserEngine.StartSessionForAgentSession},
+     *    resolving the backend from the agent's `TypeConfiguration` (`{ remoteBrowser: { provider } }`), else
+     *    the single Active provider.
+     * 3. Build a strongly-typed {@link RemoteBrowserAction} from `kind` + the supplied fields.
+     * 4. Execute it against the live session and return the result.
+     *
+     * @param agentSessionID The `AIAgentSession` id the browser is bound to.
+     * @param kind The action kind (`'navigate' | 'click' | 'type' | 'key' | 'scroll' | 'back' | 'forward' | 'wait'`).
+     * @returns The action result (success + resulting URL + detail).
+     */
+    async ExecuteRemoteBrowserAction(agentSessionID, kind, { userPayload, providers }, url, selector, x, y, text, key, deltaX, deltaY, ms) {
+        const { contextUser, provider } = this.requireUserAndProvider(userPayload, providers);
+        const session = await this.loadOwnedSession(agentSessionID, contextUser, provider);
+        const action = this.buildAction({ kind, url, selector, x, y, text, key, deltaX, deltaY, ms });
+        if (!action) {
+            return { Success: false, Detail: `Unknown or incomplete remote-browser action '${kind}'.` };
+        }
+        const providerName = await this.resolveProviderName(session, contextUser, provider);
+        try {
+            const liveSession = await RemoteBrowserEngine.Instance.StartSessionForAgentSession(agentSessionID, contextUser, providerName);
+            const result = await liveSession.ExecuteAction(action);
+            return { Success: result.Success, CurrentUrl: result.CurrentUrl, Detail: result.Detail };
+        }
+        catch (err) {
+            // Surface the real failure to BOTH the MJAPI terminal (for diagnosis) and the model (so it
+            // narrates the actual cause instead of the opaque client-side "no response from the server").
+            const message = err instanceof Error ? err.message : String(err);
+            LogError(`ExecuteRemoteBrowserAction failed (provider='${providerName}', kind='${kind}'): ${message}`);
+            return { Success: false, Detail: `Remote browser error (${providerName}): ${message}` };
+        }
+    }
+    /**
+     * Execute a high-level GOAL against the session's browser — the agent sets an intent ("log in and open
+     * the latest invoice") and the resolved control strategy (computer-use loop or backend native AI) plans
+     * + executes it autonomously, instead of relaying granular actions. Ownership-gated; lazily starts the
+     * browser. Returns the terminal outcome (this is a request/response mutation — for live progress
+     * narration in a server-bridged realtime session the broker calls {@link RemoteBrowserEngine.AchieveGoal}
+     * in-process with an `OnProgress` callback).
+     *
+     * @param agentSessionID The `AIAgentSession` id the browser is bound to.
+     * @param goal The natural-language goal.
+     * @returns The goal outcome (success, strategy, status, step count, url, detail).
+     */
+    async ExecuteRemoteBrowserGoal(agentSessionID, goal, { userPayload, providers }, startUrl, maxSteps, preferredStrategy) {
+        const { contextUser, provider } = this.requireUserAndProvider(userPayload, providers);
+        const session = await this.loadOwnedSession(agentSessionID, contextUser, provider);
+        const providerName = await this.resolveProviderName(session, contextUser, provider);
+        // Observability: nest this goal's many prompt runs under ONE "Browser goal" step on the realtime
+        // co-agent run (when the session has one). Best-effort — a null step just means the goal runs unlinked.
+        const coAgentRunID = extractCoAgentRunID(session.Config_);
+        const goalStep = await beginBrowserGoalStep(provider, contextUser, coAgentRunID, goal);
+        // ASYNC START: a goal loop can run for minutes; do NOT hold this request open for it (browser
+        // fetch / proxy / janitor timeouts would kill the request while the loop runs on, and the agent
+        // would get "no response from the server" despite a successful run). Register the run, kick the
+        // loop off WITHOUT awaiting, and return a GoalRunID the client polls via GetRemoteBrowserGoalResult.
+        const goalRunID = randomUUID();
+        RemoteBrowserGoalRegistry.Instance.Begin(agentSessionID, goalRunID);
+        void RemoteBrowserEngine.Instance.AchieveGoal(agentSessionID, goal, {
+            ContextUser: contextUser,
+            ProviderName: providerName,
+            StartUrl: startUrl,
+            MaxSteps: maxSteps,
+            PreferredStrategy: preferredStrategy === 'NativeAI' || preferredStrategy === 'ComputerUse' ? preferredStrategy : undefined,
+            AgentRunID: coAgentRunID,
+            AgentRunStepID: goalStep?.ID,
+        })
+            .then(async (result) => {
+            await finalizeBrowserGoalStep(goalStep, result);
+            RemoteBrowserGoalRegistry.Instance.Complete(agentSessionID, goalRunID, result);
+        })
+            .catch(async (err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            LogError(`ExecuteRemoteBrowserGoal failed (provider='${providerName}'): ${message}`);
+            const failure = { Success: false, Status: 'Error', Detail: `Remote browser error (${providerName}): ${message}` };
+            await finalizeBrowserGoalStep(goalStep, failure);
+            RemoteBrowserGoalRegistry.Instance.Complete(agentSessionID, goalRunID, failure);
+        });
+        return { Success: true, Status: 'Running', GoalRunID: goalRunID, Detail: 'Goal started.' };
+    }
+    /**
+     * Poll the outcome of a goal STARTED by {@link RemoteBrowserActionResolver.ExecuteRemoteBrowserGoal}.
+     * Returns `Status: 'Running'` while the loop is in flight, then the terminal outcome (success,
+     * strategy, status, step count, url, detail) once it finishes. Ownership-gated. A `Status: 'Unknown'`
+     * result means the run id is unrecognized — it expired (results are retained briefly) or never existed.
+     *
+     * @param agentSessionID The `AIAgentSession` id the goal runs against.
+     * @param goalRunID The handle returned by `ExecuteRemoteBrowserGoal`.
+     * @returns The current/terminal goal outcome.
+     */
+    async GetRemoteBrowserGoalResult(agentSessionID, goalRunID, { userPayload, providers }) {
+        const { contextUser, provider } = this.requireUserAndProvider(userPayload, providers);
+        await this.loadOwnedSession(agentSessionID, contextUser, provider);
+        const record = RemoteBrowserGoalRegistry.Instance.Get(agentSessionID, goalRunID);
+        if (!record) {
+            return { Success: false, Status: 'Unknown', GoalRunID: goalRunID, Detail: 'No such goal run (it may have expired).' };
+        }
+        if (record.Status === 'Running' || !record.Outcome) {
+            return { Success: false, Status: 'Running', GoalRunID: goalRunID };
+        }
+        return { ...record.Outcome, GoalRunID: goalRunID };
+    }
+    /**
+     * Return the current viewport screenshot + URL for the session's live browser — the client's live view.
+     * Ownership-gated. When the session holds no live browser (never started, or already torn down), the
+     * result's fields are null rather than an error.
+     *
+     * @param agentSessionID The `AIAgentSession` id.
+     * @returns The current screenshot + URL, or an empty snapshot when no live browser exists.
+     */
+    async RemoteBrowserSnapshot(agentSessionID, { userPayload, providers }) {
+        const { contextUser, provider } = this.requireUserAndProvider(userPayload, providers);
+        await this.loadOwnedSession(agentSessionID, contextUser, provider);
+        const liveSession = RemoteBrowserEngine.Instance.GetSessionForAgentSession(agentSessionID);
+        if (!liveSession) {
+            return {};
+        }
+        const screenshot = await liveSession.CaptureScreenshot();
+        return { ScreenshotBase64: screenshot, CurrentUrl: liveSession.GetCurrentUrl() };
+    }
+    /**
+     * VISION-QUERY path (separate from the navigate/click {@link RemoteBrowserActionResolver.ExecuteRemoteBrowserAction}
+     * path — this OBSERVES the page, it never drives it). Captures the session's current screenshot and runs
+     * a fast vision AI Prompt over it so a non-omnimodal voice agent (audio/text-only) can effectively SEE the
+     * page: a concise text description ("kinda see") and, when `query` names a target, the pixel centroid(s) the
+     * agent can then feed to `browser_Click(x, y)`.
+     *
+     * Flow:
+     * 1. Ownership gate — the session's `UserID` must equal the caller's (throws otherwise).
+     * 2. Get the LIVE session and `CaptureScreenshot()`. No live session / no screenshot → `{ Description: null,
+     *    Elements: [], Detail: 'no live browser' }`.
+     * 3. Run the `Remote Browser Visual Interpreter` prompt with the screenshot as an `image_url` content block
+     *    plus an instruction derived from `query` (empty/"describe" → describe; a named target → locate it).
+     * 4. Parse the strict-JSON result tolerantly and map it to {@link RemoteBrowserInterpretation}.
+     *
+     * Best-effort + tolerant by contract: any vision/prompt/parse failure is logged and returned as
+     * `{ Description: null, Elements: [], Detail: <message> }`. This mutation NEVER throws past the ownership gate.
+     *
+     * @param agentSessionID The `AIAgentSession` id the browser is bound to.
+     * @param query Optional request — empty/"describe" for a page description, else a visual target to localize.
+     * @returns The interpretation (description + localized elements + optional detail note).
+     */
+    async InterpretRemoteBrowserPage(agentSessionID, { userPayload, providers }, query) {
+        const { contextUser, provider } = this.requireUserAndProvider(userPayload, providers);
+        await this.loadOwnedSession(agentSessionID, contextUser, provider);
+        const liveSession = RemoteBrowserEngine.Instance.GetSessionForAgentSession(agentSessionID);
+        if (!liveSession) {
+            return { Description: undefined, Elements: [], Detail: 'no live browser' };
+        }
+        try {
+            const screenshot = await liveSession.CaptureScreenshot();
+            if (!screenshot) {
+                return { Description: undefined, Elements: [], Detail: 'no live browser' };
+            }
+            return await this.runVisualInterpreter(screenshot, query, contextUser);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            LogError(`InterpretRemoteBrowserPage failed for session ${agentSessionID}: ${message}`);
+            return { Description: undefined, Elements: [], Detail: message };
+        }
+    }
+    /**
+     * Starts a live CDP screencast on the session's browser and PUSHES each encoded frame to the calling
+     * user's push-status topic — replacing the client's 700ms snapshot poll with low-latency pushed frames.
+     * Ownership-gated. Idempotent: a re-call for an already-streaming session is a no-op that reports
+     * `Streaming: true`.
+     *
+     * Capability gating: {@link IRemoteBrowserSession.StartScreencast} throws
+     * {@link RemoteBrowserCapabilityNotSupportedError} on a backend without `ScreenStreaming` — caught here
+     * and reported as `Streaming: false`, leaving the client on its polling fallback. Any other failure is
+     * logged and likewise reported as `Streaming: false` (the poll keeps the view alive).
+     *
+     * @param agentSessionID The `AIAgentSession` id the browser is bound to.
+     * @returns `{ Streaming: true }` when frames are now being pushed, else `{ Streaming: false }`.
+     */
+    async StartRemoteBrowserScreencast(agentSessionID, { userPayload, providers }, pubSub) {
+        const { contextUser, provider } = this.requireUserAndProvider(userPayload, providers);
+        const session = await this.loadOwnedSession(agentSessionID, contextUser, provider);
+        // Idempotent: a re-bind must not stack a second screencast on the one live browser.
+        if (this.startedScreencasts.has(agentSessionID)) {
+            return { Streaming: true };
+        }
+        const providerName = await this.resolveProviderName(session, contextUser, provider);
+        try {
+            const liveSession = await RemoteBrowserEngine.Instance.StartSessionForAgentSession(agentSessionID, contextUser, providerName);
+            await liveSession.StartScreencast((frame) => this.publishFrame(pubSub, userPayload, agentSessionID, frame));
+            this.startedScreencasts.add(agentSessionID);
+            return { Streaming: true };
+        }
+        catch (err) {
+            if (err instanceof RemoteBrowserCapabilityNotSupportedError) {
+                // Backend can't stream — the client keeps polling. Not an error condition.
+                return { Streaming: false };
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            LogError(`StartRemoteBrowserScreencast failed (provider='${providerName}'): ${message}`);
+            return { Streaming: false };
+        }
+    }
+    /**
+     * Stops a screencast previously started by {@link RemoteBrowserActionResolver.StartRemoteBrowserScreencast}.
+     * Ownership-gated and best-effort: when no live browser exists, or `StopScreencast` rejects, the call
+     * still resolves `true` (the client's teardown should never depend on this succeeding).
+     *
+     * @param agentSessionID The `AIAgentSession` id.
+     * @returns `true` (always) once the stop has been attempted.
+     */
+    async StopRemoteBrowserScreencast(agentSessionID, { userPayload, providers }) {
+        const { contextUser, provider } = this.requireUserAndProvider(userPayload, providers);
+        await this.loadOwnedSession(agentSessionID, contextUser, provider);
+        this.startedScreencasts.delete(agentSessionID);
+        const liveSession = RemoteBrowserEngine.Instance.GetSessionForAgentSession(agentSessionID);
+        if (liveSession) {
+            try {
+                await liveSession.StopScreencast();
+            }
+            catch (err) {
+                // Best-effort: a backend without ScreenStreaming throws here too; teardown ignores it.
+                const message = err instanceof Error ? err.message : String(err);
+                LogError(`StopRemoteBrowserScreencast (best-effort) for session ${agentSessionID}: ${message}`);
+            }
+        }
+        return true;
+    }
+    /**
+     * Starts streaming the session browser's TAB AUDIO and PUSHES each encoded chunk to the calling user's
+     * push-status topic — so a co-agent demoing a video/audio site is HEARD, not just seen. Ownership-gated.
+     * Idempotent: a re-call for an already-streaming session is a no-op that reports `Streaming: true`.
+     *
+     * Capability gating (v1 = by backend implementation): {@link IRemoteBrowserSession.StartAudioStream}
+     * throws {@link RemoteBrowserCapabilityNotSupportedError} on a backend with no audio-capture mechanism —
+     * caught here and reported as `Streaming: false` (the client simply plays no audio). Any other failure is
+     * logged and likewise reported as `Streaming: false`.
+     *
+     * @param agentSessionID The `AIAgentSession` id the browser is bound to.
+     * @returns `{ Streaming: true }` when audio chunks are now being pushed, else `{ Streaming: false }`.
+     */
+    async StartRemoteBrowserAudioStream(agentSessionID, { userPayload, providers }, pubSub) {
+        const { contextUser, provider } = this.requireUserAndProvider(userPayload, providers);
+        const session = await this.loadOwnedSession(agentSessionID, contextUser, provider);
+        // Idempotent: a re-bind must not stack a second audio capture on the one live browser.
+        if (this.startedAudioStreams.has(agentSessionID)) {
+            return { Streaming: true };
+        }
+        const providerName = await this.resolveProviderName(session, contextUser, provider);
+        try {
+            const liveSession = await RemoteBrowserEngine.Instance.StartSessionForAgentSession(agentSessionID, contextUser, providerName);
+            await liveSession.StartAudioStream((chunk) => this.publishAudioChunk(pubSub, userPayload, agentSessionID, chunk));
+            this.startedAudioStreams.add(agentSessionID);
+            return { Streaming: true };
+        }
+        catch (err) {
+            if (err instanceof RemoteBrowserCapabilityNotSupportedError) {
+                // Backend can't capture audio — the client plays no audio. Not an error condition.
+                return { Streaming: false };
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            LogError(`StartRemoteBrowserAudioStream failed (provider='${providerName}'): ${message}`);
+            return { Streaming: false };
+        }
+    }
+    /**
+     * Stops a tab-audio stream previously started by {@link RemoteBrowserActionResolver.StartRemoteBrowserAudioStream}.
+     * Ownership-gated and best-effort: when no live browser exists, or `StopAudioStream` rejects, the call
+     * still resolves `true` (the client's teardown should never depend on this succeeding).
+     *
+     * @param agentSessionID The `AIAgentSession` id.
+     * @returns `true` (always) once the stop has been attempted.
+     */
+    async StopRemoteBrowserAudioStream(agentSessionID, { userPayload, providers }) {
+        const { contextUser, provider } = this.requireUserAndProvider(userPayload, providers);
+        await this.loadOwnedSession(agentSessionID, contextUser, provider);
+        this.startedAudioStreams.delete(agentSessionID);
+        const liveSession = RemoteBrowserEngine.Instance.GetSessionForAgentSession(agentSessionID);
+        if (liveSession) {
+            try {
+                await liveSession.StopAudioStream();
+            }
+            catch (err) {
+                // Best-effort: a backend without audio capture throws here too; teardown ignores it.
+                const message = err instanceof Error ? err.message : String(err);
+                LogError(`StopRemoteBrowserAudioStream (best-effort) for session ${agentSessionID}: ${message}`);
+            }
+        }
+        return true;
+    }
+    /**
+     * Relays ONE human-takeover input (pointer move/click or key press) from the user watching the live
+     * screencast into the session's server-hosted browser — the "grab the wheel" path. Ownership-gated.
+     * The surface captures the event on the live-view canvas, maps display→viewport coordinates, and calls
+     * this; the resolver builds a strongly-typed {@link RemoteBrowserHumanInput} and routes it over CDP via
+     * {@link IRemoteBrowserSession.RouteHumanInput}.
+     *
+     * Gracefully best-effort, never throws past the ownership gate:
+     * - No live browser for the session → `false`.
+     * - Unknown/incomplete input (`buildHumanInput` returns null) → `false`.
+     * - Backend lacks `HumanTakeover` ({@link RemoteBrowserCapabilityNotSupportedError}) → `false` (the
+     *   live view stays view-only for that backend).
+     * - Any other failure → logged + `false`.
+     *
+     * NOTE: this prototype does NOT reject by control mode here — the engine's floor arbiter governs the
+     * agent⇄human floor, so we just relay. Finer floor / `AgentOnly` gating is a follow-up.
+     *
+     * @param agentSessionID The `AIAgentSession` id the browser is bound to.
+     * @param kind The input kind (`'pointer-move' | 'pointer-click' | 'pointer-down' | 'pointer-up' | 'key' | 'text' | 'scroll'`).
+     * @param text The pasted text (the `'text'` paste-in kind only) — inserted into the page's focused element.
+     * @param modifiers Optional comma-separated modifier keys held during the input (`'Shift'`, `'Control'`,
+     *   `'Alt'`, `'Meta'`) — carries Shift-click selection and Ctrl/Cmd+key chords faithfully.
+     * @returns `true` when the input was routed, else `false`.
+     */
+    async RelayRemoteBrowserHumanInput(agentSessionID, kind, { userPayload, providers }, x, y, button, key, text, deltaX, deltaY, modifiers) {
+        const { contextUser, provider } = this.requireUserAndProvider(userPayload, providers);
+        await this.loadOwnedSession(agentSessionID, contextUser, provider);
+        const liveSession = RemoteBrowserEngine.Instance.GetSessionForAgentSession(agentSessionID);
+        if (!liveSession) {
+            return false;
+        }
+        const input = this.buildHumanInput({ kind, x, y, button, key, text, deltaX, deltaY, modifiers });
+        if (!input) {
+            return false;
+        }
+        try {
+            liveSession.RouteHumanInput(input);
+            return true;
+        }
+        catch (err) {
+            if (err instanceof RemoteBrowserCapabilityNotSupportedError) {
+                // Backend can't take human input — the live view stays view-only. Not an error condition.
+                return false;
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            LogError(`RelayRemoteBrowserHumanInput failed (kind='${kind}'): ${message}`);
+            return false;
+        }
+    }
+    /**
+     * Returns the remote page's CURRENT text selection — the copy-out half of human clipboard support. The
+     * viewer captures a local `copy` / Cmd+C, calls this to read what the human selected on the live page, and
+     * writes the result to the LOCAL clipboard (sidestepping the isolated remote clipboard, the mirror of the
+     * `'text'` paste-in path). Ownership-gated.
+     *
+     * Gracefully best-effort, never throws past the ownership gate (mirrors {@link RemoteBrowserSnapshot}):
+     * - No live browser for the session → `{ Text: '' }`.
+     * - Backend lacks `HumanTakeover` ({@link RemoteBrowserCapabilityNotSupportedError}) → `{ Text: '' }`.
+     * - Nothing selected / any other read failure → `{ Text: '' }` (logged).
+     *
+     * @param agentSessionID The `AIAgentSession` id the browser is bound to.
+     * @returns The selection text, or `{ Text: '' }` when none is readable.
+     */
+    async GetRemoteBrowserSelection(agentSessionID, { userPayload, providers }) {
+        const { contextUser, provider } = this.requireUserAndProvider(userPayload, providers);
+        await this.loadOwnedSession(agentSessionID, contextUser, provider);
+        const liveSession = RemoteBrowserEngine.Instance.GetSessionForAgentSession(agentSessionID);
+        if (!liveSession) {
+            return { Text: '' };
+        }
+        try {
+            return { Text: await liveSession.GetSelectionText() };
+        }
+        catch (err) {
+            if (err instanceof RemoteBrowserCapabilityNotSupportedError) {
+                // Backend can't read the selection — copy-out is simply unavailable. Not an error condition.
+                return { Text: '' };
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            LogError(`GetRemoteBrowserSelection failed for session ${agentSessionID}: ${message}`);
+            return { Text: '' };
+        }
+    }
+    // ----- internals -------------------------------------------------------------------------
+    /**
+     * Publishes one encoded screencast frame to the calling user's push-status topic, in the same envelope
+     * shape the conversations client already routes (mirrors `RealtimeClientSessionResolver`'s delegation
+     * progress publish). The client matches on `resolver` + `type`, then on `agentSessionID`, and paints
+     * `dataBase64` onto its canvas.
+     *
+     * @param pubSub The resolver-injected pub/sub engine.
+     * @param userPayload The calling user's payload (its `sessionId` scopes the topic to this browser).
+     * @param agentSessionID The `AIAgentSession` id the frame belongs to.
+     * @param frame The encoded viewport frame.
+     */
+    publishFrame(pubSub, userPayload, agentSessionID, frame) {
+        pubSub.publish(PUSH_STATUS_UPDATES_TOPIC, {
+            message: JSON.stringify({
+                resolver: 'RemoteBrowserActionResolver',
+                type: 'RemoteBrowserScreencastFrame',
+                agentSessionID,
+                dataBase64: frame.DataBase64,
+                width: frame.Width,
+                height: frame.Height,
+                seq: frame.SequenceNumber,
+            }),
+            sessionId: userPayload.sessionId,
+        });
+    }
+    /**
+     * Publishes one encoded tab-audio chunk to the calling user's push-status topic, in the same envelope
+     * shape the conversations client routes for screencast frames (distinguished by `type`). The client
+     * matches on `resolver` + `type`, then on `agentSessionID`, and feeds `dataBase64` to its audio player.
+     *
+     * @param pubSub The resolver-injected pub/sub engine.
+     * @param userPayload The calling user's payload (its `sessionId` scopes the topic to this browser).
+     * @param agentSessionID The `AIAgentSession` id the chunk belongs to.
+     * @param chunk The encoded audio chunk.
+     */
+    publishAudioChunk(pubSub, userPayload, agentSessionID, chunk) {
+        pubSub.publish(PUSH_STATUS_UPDATES_TOPIC, {
+            message: JSON.stringify({
+                resolver: 'RemoteBrowserActionResolver',
+                type: 'RemoteBrowserAudioChunk',
+                agentSessionID,
+                dataBase64: chunk.DataBase64,
+                codec: chunk.Codec,
+                sampleRate: chunk.SampleRate,
+                channels: chunk.Channels,
+                seq: chunk.SequenceNumber,
+            }),
+            sessionId: userPayload.sessionId,
+        });
+    }
+    /**
+     * Runs the governable `Remote Browser Visual Interpreter` AI Prompt over a screenshot + request, and maps
+     * its strict-JSON output to {@link RemoteBrowserInterpretation}. The model is chosen by the PROMPT's own
+     * `MJ: AI Prompt Models` association (pinned to Gemini 3.1 Flash-Lite in metadata) — not hard-coded here.
+     * Tolerant: a missing prompt, a failed run, or unparseable output all degrade to a best-effort result.
+     *
+     * @param screenshotBase64 The raw Base64 viewport screenshot (no `data:` prefix).
+     * @param query The agent's request — empty/"describe" for a description, else a target to localize.
+     * @param contextUser The owning user (server-side multi-user safety).
+     * @returns The mapped interpretation.
+     */
+    async runVisualInterpreter(screenshotBase64, query, contextUser) {
+        await AIEngine.Instance.Config(false, contextUser);
+        const promptEntity = AIEngine.Instance.Prompts.find((p) => p.Name?.trim().toLowerCase() === VISUAL_INTERPRETER_PROMPT_NAME.toLowerCase());
+        if (!promptEntity) {
+            const detail = `Visual interpreter prompt '${VISUAL_INTERPRETER_PROMPT_NAME}' not found.`;
+            LogError(detail);
+            return { Description: undefined, Elements: [], Detail: detail };
+        }
+        const instruction = this.buildInterpreterInstruction(query);
+        const params = new AIPromptParams();
+        params.prompt = promptEntity;
+        params.contextUser = contextUser;
+        // The template surfaces the request via a {{ query }} variable; the screenshot rides as an image block.
+        params.data = { query: instruction };
+        params.conversationMessages = [
+            {
+                role: 'user',
+                content: [
+                    { type: 'text', content: instruction },
+                    // Declare the explicit MIME so the modality check matches a concrete
+                    // 'image/jpeg' driver capability (not just a wildcard probe).
+                    { type: 'image_url', content: `data:image/jpeg;base64,${screenshotBase64}`, mimeType: 'image/jpeg' },
+                ],
+            },
+        ];
+        const runner = new AIPromptRunner();
+        const result = await runner.ExecutePrompt(params);
+        if (!result.success) {
+            const detail = result.errorMessage ?? 'Visual interpreter prompt failed.';
+            LogError(`InterpretRemoteBrowserPage: vision prompt failed: ${detail}`);
+            return { Description: undefined, Elements: [], Detail: detail };
+        }
+        return this.mapInterpreterResult(result.rawResult);
+    }
+    /**
+     * Builds the natural-language instruction handed to the visual interpreter from the raw `query`. An empty
+     * / blank / "describe" request asks for a concise page description; anything else asks to locate that target
+     * and return its pixel centroid.
+     *
+     * @param query The raw request from the agent.
+     * @returns The instruction string.
+     */
+    buildInterpreterInstruction(query) {
+        const trimmed = query?.trim();
+        if (!trimmed || trimmed.toLowerCase() === 'describe') {
+            return 'Describe concisely what is visible and actionable on this page. Return an empty elements array.';
+        }
+        return (`Find this UI element and report its approximate pixel centroid: "${trimmed}". ` +
+            'Also give a one-sentence description of the page for context. ' +
+            'If the element is not present, return an empty elements array.');
+    }
+    /**
+     * Tolerantly parses the interpreter's raw text output into a {@link RemoteBrowserInterpretation}. Strips
+     * code fences before parsing; on parse failure returns the raw text as `Description` with no elements.
+     *
+     * @param raw The prompt's raw text output (may be null/undefined/fenced JSON).
+     * @returns The mapped interpretation.
+     */
+    mapInterpreterResult(raw) {
+        const text = (raw ?? '').trim();
+        if (text.length === 0) {
+            return { Description: undefined, Elements: [], Detail: 'Empty interpreter response.' };
+        }
+        const stripped = this.stripCodeFences(text);
+        let payload;
+        try {
+            const parsed = JSON.parse(stripped);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                return { Description: text, Elements: [], Detail: 'Interpreter output was not a JSON object.' };
+            }
+            payload = parsed;
+        }
+        catch {
+            // Not JSON — hand the raw text back as the description so the agent still gets something useful.
+            return { Description: text, Elements: [] };
+        }
+        const elements = Array.isArray(payload.elements)
+            ? payload.elements
+                .filter((e) => typeof e?.x === 'number' && typeof e?.y === 'number')
+                .map((e) => ({
+                Label: typeof e.label === 'string' ? e.label : '',
+                X: e.x,
+                Y: e.y,
+                Confidence: typeof e.confidence === 'number' ? e.confidence : 0,
+            }))
+            : [];
+        return {
+            Description: typeof payload.description === 'string' ? payload.description : undefined,
+            Elements: elements,
+        };
+    }
+    /**
+     * Strips a leading/trailing Markdown code fence (```json … ```) from a model response so the inner JSON can
+     * be parsed. Returns the input unchanged when no fence is present.
+     *
+     * @param text The possibly-fenced text.
+     * @returns The text with any surrounding fence removed.
+     */
+    stripCodeFences(text) {
+        const fence = /^```(?:json)?\s*([\s\S]*?)\s*```$/i;
+        const match = fence.exec(text.trim());
+        return match ? match[1].trim() : text;
+    }
+    /** Resolve the request user + read-write provider, throwing a clear error if unauthenticated. */
+    requireUserAndProvider(userPayload, providers) {
+        const contextUser = this.GetUserFromPayload(userPayload);
+        if (!contextUser) {
+            throw new Error('Not authenticated: no user context for remote-browser operation');
+        }
+        return { contextUser, provider: GetReadWriteProvider(providers) };
+    }
+    /**
+     * Loads the agent session and enforces inbound ownership: the session's `UserID` must equal the
+     * caller's. Throws when the session is missing or owned by another user.
+     *
+     * @param agentSessionID The `AIAgentSession` id.
+     * @returns The loaded, owned session entity.
+     */
+    async loadOwnedSession(agentSessionID, contextUser, provider) {
+        const session = await provider.GetEntityObject(SESSION_ENTITY, contextUser);
+        if (!(await session.Load(agentSessionID))) {
+            throw new Error(`Remote-browser session ${agentSessionID} not found.`);
+        }
+        if (!UUIDsEqual(session.UserID, contextUser.ID)) {
+            throw new Error(`Not authorized: remote-browser session ${agentSessionID} is not owned by you.`);
+        }
+        return session;
+    }
+    /**
+     * Resolves the remote-browser backend name for the session from the session's agent's
+     * `TypeConfiguration` JSON (`{ remoteBrowser: { provider } }`). Best-effort: a missing agent, absent
+     * config, or unparseable JSON all yield `undefined`, letting the engine fall back to the single Active
+     * provider.
+     *
+     * @param session The owned session entity (supplies the agent id).
+     * @returns The configured backend name, or `undefined` to let the engine auto-select.
+     */
+    async resolveProviderName(session, contextUser, provider) {
+        // The session's agent IS the co-agent (the realtime voice agent), and the interactive channels
+        // (Remote Browser, Whiteboard) are the CO-AGENT's abilities — so the remoteBrowser backend config
+        // lives on the co-agent's TypeConfiguration, not on the target agent it voices.
+        try {
+            const agent = await provider.GetEntityObject(AGENT_ENTITY, contextUser);
+            if (!(await agent.Load(session.AgentID))) {
+                return undefined;
+            }
+            const config = this.parseTypeConfiguration(agent.TypeConfiguration);
+            const name = config?.remoteBrowser?.provider?.trim();
+            return name && name.length > 0 ? name : undefined;
+        }
+        catch (error) {
+            LogError(`ExecuteRemoteBrowserAction: failed to read agent TypeConfiguration for session ${session.ID} — ` +
+                `falling back to the single Active provider: ${error instanceof Error ? error.message : String(error)}`);
+            return undefined;
+        }
+    }
+    /**
+     * Parses an agent's `TypeConfiguration` JSON into the {@link RemoteBrowserTypeConfiguration} slice this
+     * resolver reads. Returns `null` for null/blank/non-object/unparseable input.
+     *
+     * @param json The raw `TypeConfiguration` JSON, or null.
+     * @returns The parsed config slice, or `null`.
+     */
+    parseTypeConfiguration(json) {
+        if (!json || json.trim().length === 0) {
+            return null;
+        }
+        try {
+            const parsed = JSON.parse(json);
+            return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Builds a strongly-typed {@link RemoteBrowserAction} from the relayed `kind` + fields, validating the
+     * fields each kind requires. Returns `null` for an unknown kind or a kind missing its required field(s).
+     *
+     * @param input The relayed action kind + all optional fields.
+     * @returns The built action, or `null` when the kind is unknown / incomplete.
+     */
+    buildAction(input) {
+        switch (input.kind) {
+            case 'navigate':
+                return input.url ? { Kind: 'navigate', Url: input.url } : null;
+            case 'click':
+                if (input.selector || (typeof input.x === 'number' && typeof input.y === 'number')) {
+                    return { Kind: 'click', Selector: input.selector, X: input.x, Y: input.y };
+                }
+                return null;
+            case 'type':
+                return typeof input.text === 'string' ? { Kind: 'type', Text: input.text, Selector: input.selector } : null;
+            case 'key':
+                return input.key ? { Kind: 'key', Key: input.key } : null;
+            case 'scroll':
+                if (input.selector || typeof input.deltaX === 'number' || typeof input.deltaY === 'number') {
+                    return { Kind: 'scroll', DeltaX: input.deltaX, DeltaY: input.deltaY, Selector: input.selector };
+                }
+                return null;
+            case 'back':
+                return { Kind: 'back' };
+            case 'forward':
+                return { Kind: 'forward' };
+            case 'wait':
+                if (typeof input.ms === 'number' || input.selector) {
+                    return { Kind: 'wait', Ms: input.ms, Selector: input.selector };
+                }
+                return null;
+            default:
+                return null;
+        }
+    }
+    /**
+     * Builds a strongly-typed {@link RemoteBrowserHumanInput} from the relayed `kind` + fields, validating
+     * each kind's required field(s). Returns `null` for an unknown kind or a kind missing its required
+     * field(s): pointer-move/click/down/up need finite `x`,`y`; key needs a non-empty `key`; text needs a
+     * non-empty `text`; scroll needs finite `x`,`y`,`deltaX`,`deltaY`. The `button` is clamped to the allowed
+     * union (`'left' | 'middle' | 'right'`), defaulting unknown/absent values to `'left'`. Held `modifiers`
+     * (e.g. Shift-click, Ctrl/Cmd+key) ride on pointer clicks/presses and key presses.
+     *
+     * @param input The relayed input kind + all optional fields.
+     * @returns The built human input, or `null` when the kind is unknown / incomplete.
+     */
+    buildHumanInput(input) {
+        const modifiers = this.parseModifiers(input.modifiers);
+        const hasXy = Number.isFinite(input.x) && Number.isFinite(input.y);
+        switch (input.kind) {
+            case 'pointer-move':
+                return hasXy ? { Kind: 'pointer-move', X: input.x, Y: input.y } : null;
+            case 'pointer-click':
+                return hasXy
+                    ? {
+                        Kind: 'pointer-click',
+                        X: input.x,
+                        Y: input.y,
+                        Button: this.clampButton(input.button),
+                        ...(modifiers.length ? { Modifiers: modifiers } : {}),
+                    }
+                    : null;
+            case 'pointer-down':
+                return hasXy
+                    ? {
+                        Kind: 'pointer-down',
+                        X: input.x,
+                        Y: input.y,
+                        Button: this.clampButton(input.button),
+                        ...(modifiers.length ? { Modifiers: modifiers } : {}),
+                    }
+                    : null;
+            case 'pointer-up':
+                return hasXy
+                    ? {
+                        Kind: 'pointer-up',
+                        X: input.x,
+                        Y: input.y,
+                        Button: this.clampButton(input.button),
+                        ...(modifiers.length ? { Modifiers: modifiers } : {}),
+                    }
+                    : null;
+            case 'key':
+                return input.key && input.key.length > 0 ? { Kind: 'key', Key: input.key, ...(modifiers.length ? { Modifiers: modifiers } : {}) } : null;
+            case 'text':
+                // Human paste — insert the relayed clipboard text into the focused element. Empty text is a no-op.
+                return typeof input.text === 'string' && input.text.length > 0 ? { Kind: 'text', Text: input.text } : null;
+            case 'scroll':
+                return hasXy && Number.isFinite(input.deltaX) && Number.isFinite(input.deltaY)
+                    ? { Kind: 'scroll', X: input.x, Y: input.y, DeltaX: input.deltaX, DeltaY: input.deltaY }
+                    : null;
+            default:
+                return null;
+        }
+    }
+    /** Clamps a relayed mouse-button string to the allowed union, defaulting to `'left'`. */
+    clampButton(button) {
+        return button === 'middle' || button === 'right' ? button : 'left';
+    }
+    /**
+     * Parses the relayed comma-separated `modifiers` string into the validated
+     * {@link RemoteBrowserModifierKey} list, dropping any unrecognized token. Returns an empty array for a
+     * null/blank input.
+     *
+     * @param modifiers The raw `'Shift,Control'`-style CSV, or undefined.
+     * @returns The validated modifier list (possibly empty).
+     */
+    parseModifiers(modifiers) {
+        if (!modifiers) {
+            return [];
+        }
+        const allowed = ['Shift', 'Control', 'Alt', 'Meta'];
+        return modifiers
+            .split(',')
+            .map((m) => m.trim())
+            .filter((m) => allowed.includes(m));
+    }
+};
+__decorate([
+    Mutation(() => RemoteBrowserActionResult),
+    __param(0, Arg('agentSessionID', () => String)),
+    __param(1, Arg('kind', () => String)),
+    __param(2, Ctx()),
+    __param(3, Arg('url', () => String, { nullable: true })),
+    __param(4, Arg('selector', () => String, { nullable: true })),
+    __param(5, Arg('x', () => Float, { nullable: true })),
+    __param(6, Arg('y', () => Float, { nullable: true })),
+    __param(7, Arg('text', () => String, { nullable: true })),
+    __param(8, Arg('key', () => String, { nullable: true })),
+    __param(9, Arg('deltaX', () => Float, { nullable: true })),
+    __param(10, Arg('deltaY', () => Float, { nullable: true })),
+    __param(11, Arg('ms', () => Float, { nullable: true })),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, Object, String, String, Number, Number, String, String, Number, Number, Number]),
+    __metadata("design:returntype", Promise)
+], RemoteBrowserActionResolver.prototype, "ExecuteRemoteBrowserAction", null);
+__decorate([
+    Mutation(() => RemoteBrowserGoalResultType),
+    __param(0, Arg('agentSessionID', () => String)),
+    __param(1, Arg('goal', () => String)),
+    __param(2, Ctx()),
+    __param(3, Arg('startUrl', () => String, { nullable: true })),
+    __param(4, Arg('maxSteps', () => Int, { nullable: true })),
+    __param(5, Arg('preferredStrategy', () => String, { nullable: true })),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, Object, String, Number, String]),
+    __metadata("design:returntype", Promise)
+], RemoteBrowserActionResolver.prototype, "ExecuteRemoteBrowserGoal", null);
+__decorate([
+    Query(() => RemoteBrowserGoalResultType),
+    __param(0, Arg('agentSessionID', () => String)),
+    __param(1, Arg('goalRunID', () => String)),
+    __param(2, Ctx()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, Object]),
+    __metadata("design:returntype", Promise)
+], RemoteBrowserActionResolver.prototype, "GetRemoteBrowserGoalResult", null);
+__decorate([
+    Query(() => RemoteBrowserSnapshot),
+    __param(0, Arg('agentSessionID', () => String)),
+    __param(1, Ctx()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], RemoteBrowserActionResolver.prototype, "RemoteBrowserSnapshot", null);
+__decorate([
+    Mutation(() => RemoteBrowserInterpretation),
+    __param(0, Arg('agentSessionID', () => String)),
+    __param(1, Ctx()),
+    __param(2, Arg('query', () => String, { nullable: true })),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object, String]),
+    __metadata("design:returntype", Promise)
+], RemoteBrowserActionResolver.prototype, "InterpretRemoteBrowserPage", null);
+__decorate([
+    Mutation(() => RemoteBrowserScreencastResult),
+    __param(0, Arg('agentSessionID', () => String)),
+    __param(1, Ctx()),
+    __param(2, PubSub()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object, PubSubEngine]),
+    __metadata("design:returntype", Promise)
+], RemoteBrowserActionResolver.prototype, "StartRemoteBrowserScreencast", null);
+__decorate([
+    Mutation(() => Boolean),
+    __param(0, Arg('agentSessionID', () => String)),
+    __param(1, Ctx()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], RemoteBrowserActionResolver.prototype, "StopRemoteBrowserScreencast", null);
+__decorate([
+    Mutation(() => RemoteBrowserAudioStreamResult),
+    __param(0, Arg('agentSessionID', () => String)),
+    __param(1, Ctx()),
+    __param(2, PubSub()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object, PubSubEngine]),
+    __metadata("design:returntype", Promise)
+], RemoteBrowserActionResolver.prototype, "StartRemoteBrowserAudioStream", null);
+__decorate([
+    Mutation(() => Boolean),
+    __param(0, Arg('agentSessionID', () => String)),
+    __param(1, Ctx()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], RemoteBrowserActionResolver.prototype, "StopRemoteBrowserAudioStream", null);
+__decorate([
+    Mutation(() => Boolean),
+    __param(0, Arg('agentSessionID', () => String)),
+    __param(1, Arg('kind', () => String)),
+    __param(2, Ctx()),
+    __param(3, Arg('x', () => Float, { nullable: true })),
+    __param(4, Arg('y', () => Float, { nullable: true })),
+    __param(5, Arg('button', () => String, { nullable: true })),
+    __param(6, Arg('key', () => String, { nullable: true })),
+    __param(7, Arg('text', () => String, { nullable: true })),
+    __param(8, Arg('deltaX', () => Float, { nullable: true })),
+    __param(9, Arg('deltaY', () => Float, { nullable: true })),
+    __param(10, Arg('modifiers', () => String, { nullable: true })),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, Object, Number, Number, String, String, String, Number, Number, String]),
+    __metadata("design:returntype", Promise)
+], RemoteBrowserActionResolver.prototype, "RelayRemoteBrowserHumanInput", null);
+__decorate([
+    Query(() => RemoteBrowserSelection),
+    __param(0, Arg('agentSessionID', () => String)),
+    __param(1, Ctx()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], RemoteBrowserActionResolver.prototype, "GetRemoteBrowserSelection", null);
+RemoteBrowserActionResolver = __decorate([
+    Resolver()
+], RemoteBrowserActionResolver);
+export { RemoteBrowserActionResolver };
+//# sourceMappingURL=RemoteBrowserActionResolver.js.map