@memberjunction/remote-browser-base 0.0.1 → 5.42.0

package/README.md

@@ -1,45 +1,162 @@
 # @memberjunction/remote-browser-base
 
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@memberjunction/remote-browser-base`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+Universal (client **and** server), **metadata-only** base layer for the MemberJunction **Remote
+Browser channel** — the in-house channel where an agent **spins up a real Chromium browser, drives it
+over CDP while it talks, screen-shares it live, and can hand the wheel to a human** (a sales agent
+running an interactive product demo, a support agent walking a user through a UI, a trainer agent that
+demonstrates a task then watches you try).
+
+This package holds everything the Remote Browser channel needs that carries **no execution** — the
+backend-provider registry cache, the abstract `BaseRemoteBrowserProvider` driver contract, the live
+CDP-backed `IRemoteBrowserSession` interface plus its self-contained action / input / frame types, the
+control-mode/strategy helpers, and the capability-error type. It is the base half of the
+`RemoteBrowserEngineBase` / `RemoteBrowserEngine` pair, exactly mirroring how
+[`@memberjunction/ai-bridge-base`](../../RealtimeBridge/Base)'s `BaseRealtimeBridge` /
+`AIBridgeEngineBase` underpin the bridge server tier. The server tier that actually *runs* a
+remote-browser session (CDP-connect via `@memberjunction/computer-use`, the live sessions, control
+arbitration, the viewport→screen-track encode) lives in the Server package; the five backend drivers
+(Self-Hosted Chrome, Browserbase, Steel, Browserless, Hyperbrowser) live alongside it.
+
+> See the architecture plan at `/plans/realtime/realtime-bridges-architecture.md` §4d (the Remote
+> Browser channel) and §4d-i (the option-3 build decision: one CDP primitive, pluggable backends, the
+> MJ way) for the full design.
+
+## What's in the box
+
+| Export | Purpose |
+|---|---|
+| `BaseRemoteBrowserProvider` | The abstract driver. A concrete backend (`BrowserbaseRemoteBrowser`, `SelfHostedChromeRemoteBrowser`, …) implements only the irreducibly backend-specific primitives (`Connect` → returns a live `IRemoteBrowserSession`, `Disconnect`). Drivers self-register via `@RegisterClass(BaseRemoteBrowserProvider, '<X>RemoteBrowser')`. |
+| `RemoteBrowserEngineBase` | A `BaseEngine` singleton caching the backend registry (`MJ: AI Remote Browser Providers` + capability flags) with synchronous resolution helpers (`ProviderByName`, `ProviderByDriverClass`, `ActiveProviders`, `FeaturesFor`). No execution. |
+| `IRemoteBrowserSession` | The live-session contract — core CDP methods (`GetCdpEndpoint`, `Navigate`, `ExecuteAction`, `CaptureScreenshot`, `GetCurrentUrl`, `Close`), capability-gated ones (`GetLiveViewUrl`, `StartScreencast`/`StopScreencast`, `RouteHumanInput`, `InvokeNativeAIControl`), and the **goal-driven** `RunComputerUseGoal(goal, options)` (set a high-level goal; computer-use plans + executes it — see [§ Goal-driven control](#goal-driven-control-set-a-goal-not-clicks)). |
+| Action / input / frame types | `RemoteBrowserAction` (discriminated union: navigate / click / type / key / scroll / back / forward / wait), `RemoteBrowserActionResult`, `RemoteBrowserScreencastFrame`, `RemoteBrowserHumanInput` (pointer-move / pointer-click / key) — all strongly typed, **self-contained** (no Playwright / computer-use dependency). |
+| Goal types | `RunComputerUseGoalOptions` (transport-neutral: `StartUrl`, `MaxSteps`, model overrides, model-blind `Context`, `OnProgress`, `Signal`, `ContextUser`) + `RemoteBrowserGoalResult` (`Success` / `Strategy` / `Status` / `StepCount` / `Detail`) — carry **no** computer-use SDK types, so model selection stays in the CDP/engine tier. |
+| `RemoteBrowserControlMode` + `RemoteBrowserControlStrategy` + helpers | `isControlModeSupported(mode, features)`, `resolveControlStrategy(features, preferred?)` — pure, capability-aware helpers. |
+| `RemoteBrowserCapabilityNotSupportedError` | The defense-in-depth error thrown when a capability-gated method is called on a backend that doesn't support it (carries `FeatureName` + `ProviderName`). |
+| `IRemoteBrowserProviderFeatures` + `featuresOf` + `KNOWN_REMOTE_BROWSER_FEATURE_KEYS` | Typed alias of the generated `MJ: AI Remote Browser Providers.SupportedFeatures` shape, a null-safe reader, and the full key list for validators/iteration. |
+
+## Installation
+
+```bash
+npm install @memberjunction/remote-browser-base
+```
+
+## The universal CDP substrate
+
+Every backend — self-hosted headless Chrome **and** every browser-as-a-service (Browserbase, Steel,
+Browserless, Hyperbrowser) — exposes a **Chrome DevTools Protocol** endpoint. The Remote Browser
+subsystem standardizes on **CDP-connect** as its one primitive: the server engine connects over CDP
+(reusing `@memberjunction/computer-use`'s `PlaywrightBrowserAdapter`) and drives a clean
+click/type/scroll/screenshot vocabulary — no hand-rolled raw CDP. This Base package itself stays
+dependency-light and universal precisely because it only *declares* the `IRemoteBrowserSession`
+contract both sides agree on; the Playwright/CDP machinery lives in the server tier.
+
+## The driver contract
+
+`BaseRemoteBrowserProvider` is intentionally tiny — two abstract methods:
+
+- **`Connect(ctx)`** — open or attach a browser over CDP and return the live `IRemoteBrowserSession`.
+  Call `this.applyContext(ctx)` first to capture the backend's capability flags + name.
+- **`Disconnect()`** — release the driver's own backend resources (tear down the container, end the
+  service session).
+
+Protected helpers for driver authors: `applyContext(ctx)` (capture features + provider name — call it
+first in `Connect`), `RequireFeature(flag)` (re-assert a capability flag before gated work), and
+`notSupported(name)` (build the standard error).
+
+```typescript
+import { RegisterClass } from '@memberjunction/global';
+import {
+    BaseRemoteBrowserProvider,
+    IRemoteBrowserSession,
+    RemoteBrowserProviderContext,
+} from '@memberjunction/remote-browser-base';
+
+@RegisterClass(BaseRemoteBrowserProvider, 'BrowserbaseRemoteBrowser')
+export class BrowserbaseRemoteBrowser extends BaseRemoteBrowserProvider {
+    public async Connect(ctx: RemoteBrowserProviderContext): Promise<IRemoteBrowserSession> {
+        this.applyContext(ctx);                       // capture features + provider name (do this first)
+        // ...request a session from the backend, obtain its CDP endpoint, and return a session that
+        // implements IRemoteBrowserSession (the actual CDP wiring lives in the server tier).
+        throw new Error('implemented in the server / driver package');
+    }
+
+    public async Disconnect(): Promise<void> {
+        // ...release the backend session.
+    }
+}
+```
+
+A provider row whose `DriverClass = 'BrowserbaseRemoteBrowser'` resolves to this driver through the
+`ClassFactory`: `MJGlobal.ClassFactory.CreateInstance(BaseRemoteBrowserProvider, provider.DriverClass)`.
+
+## Capability gating (two layers, defense-in-depth)
+
+A backend's capabilities live in the `MJ: AI Remote Browser Providers.SupportedFeatures` JSON column,
+strongly typed via `IRemoteBrowserProviderFeatures`. It holds **control/transport** concerns only:
+
+- **Control substrate & strategies** — `RawCdpControl` (the universal substrate), `NativeAIControl` (a
+  backend's own AI-control harness, e.g. Stagehand).
+- **Viewing & collaboration** — `LiveView`, `HumanTakeover`, `ScreenStreaming`.
+- **Operational** — `Stealth`, `ProxyEgress`, `SessionRecording`, `PersistentContext`, `MultiTab`,
+  `FileDownloads`, `CaptchaSolving`.
+
+The engine checks the matching flag **first** and never calls a capability-gated session method whose
+feature is off; the capability-gated method's own throw is the **second**, defense-in-depth layer for
+when a metadata flag lies or a caller bypasses the gate. New backend features need no schema migration
+— extend the interface. Read flags via `provider.SupportedFeaturesObject` (or the null-safe
+`featuresOf(provider)`), never `JSON.parse(provider.SupportedFeatures)`.
+
+## Control modes vs. control strategies
+
+These are **orthogonal** axes — keep them straight:
+
+| Axis | Type | Meaning |
+|---|---|---|
+| **Control mode** | `RemoteBrowserControlMode` | *Who* drives: `AgentOnly` (no takeover) · `ViewOnly` (humans watch — needs `LiveView`) · `Collaborative` (a human can grab the wheel — needs `LiveView` + `HumanTakeover`). A per-provider `DefaultControlMode`, overridable per-channel and at runtime. |
+| **Control strategy** | `RemoteBrowserControlStrategy` | *How* the agent decides what to do: `ComputerUse` (MJ's perception→action loop over CDP — the universal default) · `NativeAI` (delegate intents to the backend's own harness — needs `NativeAIControl`). |
+
+```typescript
+import {
+    isControlModeSupported,
+    resolveControlStrategy,
+} from '@memberjunction/remote-browser-base';
+
+const features = provider.SupportedFeaturesObject ?? {};
+
+isControlModeSupported('Collaborative', features); // true only if LiveView && HumanTakeover
+resolveControlStrategy(features);                  // 'NativeAI' iff features.NativeAIControl, else 'ComputerUse'
+resolveControlStrategy(features, 'ComputerUse');   // always 'ComputerUse' — explicit ComputerUse pins the universal loop
+```
+
+## Goal-driven control (set a goal, not clicks)
+
+Beyond driving the page one action at a time, a caller can hand the session a **high-level goal** —
+*"log into this site and download the latest invoice"* — and let MJ's **computer-use** loop plan and
+execute it. `IRemoteBrowserSession.RunComputerUseGoal(goal, options)` is that contract; the
+`resolveControlStrategy` above decides whether the goal runs through the universal `ComputerUse` loop or
+is delegated to a backend's `NativeAI` harness. This Base package declares only the **transport-neutral**
+types (`RunComputerUseGoalOptions`, `RemoteBrowserGoalResult`) — the actual loop, model selection, and the
+**model-blind credential injection** (`{{label}}` references resolved at the keystroke boundary, never seen
+by any model) live in the CDP + server tiers. See the [Remote Browser Channel Guide §9](../../../../guides/REMOTE_BROWSER_GUIDE.md).
+
+## How it composes
+
+| Layer | Package | Role |
+|---|---|---|
+| **Registry cache + abstract driver + session contract + control helpers** | **`@memberjunction/remote-browser-base`** (this) | provider cache, `BaseRemoteBrowserProvider`, `IRemoteBrowserSession`, action/input types, control mode/strategy, capability types |
+| Coordination + execution (CDP-connect, control arbiter, screen-track encode) | server package | `RemoteBrowserEngine` (composes this base), live sessions, the `RemoteBrowserChannel` |
+| Browser control vocabulary | [`@memberjunction/computer-use`](../../ComputerUse) | the `PlaywrightBrowserAdapter` the server tier uses to drive CDP — **not** a dependency of this base |
+
+The server `RemoteBrowserEngine` **composes** (does not extend) `RemoteBrowserEngineBase`, so the
+startup manager warms exactly one `BaseEngine` cache — the same composition-over-inheritance pattern
+`AIBridgeEngine` uses over `AIBridgeEngineBase`.
+
+## Further reading
+
+- **Architecture plan:** `/plans/realtime/realtime-bridges-architecture.md` §4d / §4d-i.
+- **Sibling subsystem:** [`@memberjunction/ai-bridge-base`](../../RealtimeBridge/Base/README.md) — the
+  realtime media bridge this package mirrors in structure and style.
+
+## License
+
+ISC

package/dist/base-remote-browser-provider.d.ts

@@ -0,0 +1,149 @@
+import { UserInfo } from '@memberjunction/core';
+import { IRemoteBrowserProviderFeatures } from './remote-browser-features.js';
+import { RemoteBrowserControlMode } from './control.js';
+import { IRemoteBrowserSession } from './remote-browser-session.js';
+import { RemoteBrowserCapabilityNotSupportedError } from './capability-errors.js';
+/**
+ * The set of host services a remote-browser driver sees while running.
+ *
+ * The engine (`RemoteBrowserEngine`, server package) constructs this and hands it to {@link
+ * BaseRemoteBrowserProvider.Connect}. It is deliberately small: a driver should depend only on what it
+ * truly needs, and everything richer (the realtime session, the channel plane, the control arbiter)
+ * is wired by the engine AROUND the driver, not handed into it. This keeps drivers thin and
+ * backend-focused.
+ */
+export interface RemoteBrowserProviderContext {
+    /**
+     * The backend's `SupportedFeatures` — the capability flags the engine and the driver's
+     * `RequireFeature` guard gate on. Sourced from the provider metadata row's typed
+     * `SupportedFeaturesObject` accessor (never `JSON.parse`).
+     */
+    Features: IRemoteBrowserProviderFeatures;
+    /**
+     * The backend's display name (e.g. `'Browserbase'`, `'Self-Hosted Chrome'`), used in
+     * capability-error messages and logging.
+     */
+    ProviderName: string;
+    /**
+     * How the browser is hosted: `'SelfHost'` (MJ orchestrates a lightweight headless-Chrome
+     * container we connect to over CDP) or `'Service'` (a browser-as-a-service exposes a CDP connect
+     * endpoint). Mirrors `MJ: AI Remote Browser Providers.ProviderType`.
+     */
+    ProviderType: 'SelfHost' | 'Service';
+    /**
+     * The resolved control mode for this session (`AgentOnly` / `ViewOnly` / `Collaborative`) — the
+     * provider default overridden per-channel / at runtime. The driver uses it to decide whether to
+     * stand up live-view / takeover plumbing on connect.
+     */
+    ControlMode: RemoteBrowserControlMode;
+    /**
+     * Opaque, backend-specific connection configuration (resolved credential references, region,
+     * Chrome image, proxy settings, …) as a parsed JSON object. Typed as a record of unknown values
+     * rather than `any` so it stays inspectable without losing type-safety at the boundary; the
+     * driver narrows the fields it understands. Never carries inline secrets — credentials resolve
+     * through MJ's credential system upstream and arrive here already resolved or as references.
+     */
+    Configuration?: Record<string, unknown>;
+    /**
+     * The MJ user the remote-browser session runs as. Every session is owned by a user and fully
+     * audited; the driver uses this for any server-side operations that require a context user.
+     */
+    ContextUser?: UserInfo;
+}
+/**
+ * Abstract base class for a **Remote Browser** provider driver — a pluggable backend that opens (or
+ * attaches to) a real Chromium browser over the Chrome DevTools Protocol and returns a live
+ * {@link IRemoteBrowserSession} the agent drives.
+ *
+ * This is the sibling of `BaseRealtimeBridge`: the Remote Browser channel is built exactly like the
+ * bridge subsystem (registry table + base driver + EngineBase/Engine pair + pluggable backends). A
+ * concrete driver (`SelfHostedChromeRemoteBrowser`, `BrowserbaseRemoteBrowser`, …) implements only the
+ * irreducibly backend-specific primitives — everything generic (control arbitration, the
+ * viewport→screen-track encode, session bookkeeping) lives in the server engine above. Drivers
+ * self-register with the MemberJunction `ClassFactory` — e.g.
+ * `@RegisterClass(BaseRemoteBrowserProvider, 'BrowserbaseRemoteBrowser')`. The base class itself is
+ * abstract and unregistered; the engine resolves a driver via
+ * `MJGlobal.ClassFactory.CreateInstance(BaseRemoteBrowserProvider, provider.DriverClass)`.
+ *
+ * **Capability gating (two layers, defense-in-depth).** The engine FIRST checks a provider's
+ * `SupportedFeatures` flag and never calls a session method whose feature is off. The driver's own
+ * capability-gated work is the SECOND layer: it calls {@link BaseRemoteBrowserProvider.RequireFeature}
+ * (or builds an error via {@link BaseRemoteBrowserProvider.notSupported}) so a metadata flag that
+ * lied — or a caller that bypassed the gate — fails loudly rather than silently degrading.
+ *
+ * **Universal CDP substrate.** Every backend (self-hosted Chrome and every browser-as-a-service)
+ * exposes a CDP endpoint; the engine standardizes on CDP-connect (reusing `@memberjunction/computer-use`
+ * server-side) so this Base package itself stays dependency-light and universal.
+ *
+ * @see `/plans/realtime/realtime-bridges-architecture.md` §4d / §4d-i.
+ * @abstract
+ */
+export declare abstract class BaseRemoteBrowserProvider {
+    /**
+     * The capability flags for the backend this driver instance serves. Populated from the
+     * {@link RemoteBrowserProviderContext} at {@link BaseRemoteBrowserProvider.Connect} time (call
+     * `this.applyContext(ctx)` first). Drives {@link BaseRemoteBrowserProvider.RequireFeature}.
+     */
+    protected features: IRemoteBrowserProviderFeatures;
+    /**
+     * The backend's display name for this driver instance, used in capability-error messages.
+     * Populated from the {@link RemoteBrowserProviderContext}; falls back to the driver class name.
+     */
+    protected providerName: string;
+    /**
+     * The backend's supported-feature flags for this driver instance.
+     *
+     * Read-only accessor over the internally-held {@link BaseRemoteBrowserProvider.features}. The
+     * engine consults this (and the underlying provider metadata) to decide which capability-gated
+     * session methods are safe to call; a driver consults it via
+     * {@link BaseRemoteBrowserProvider.RequireFeature}.
+     */
+    get Features(): IRemoteBrowserProviderFeatures;
+    /**
+     * Opens or attaches a browser session on the backend over CDP and returns the live handle.
+     *
+     * Implementations must normalize the backend's capability flags + provider name into the
+     * instance (typically by calling `this.applyContext(ctx)` first), then establish the CDP-connected
+     * browser and return an {@link IRemoteBrowserSession} wrapping it.
+     *
+     * @param ctx The host services and connection parameters for this session.
+     * @returns A promise resolving to the live remote-browser session handle.
+     */
+    abstract Connect(ctx: RemoteBrowserProviderContext): Promise<IRemoteBrowserSession>;
+    /**
+     * Tears down / releases the backend session this driver opened (closes the container, ends the
+     * browser-as-a-service session, …). Distinct from {@link IRemoteBrowserSession.Close}, which the
+     * engine may call on the session handle; `Disconnect` releases the driver's own backend resources.
+     *
+     * @returns A promise that resolves once the backend session has been released.
+     */
+    abstract Disconnect(): Promise<void>;
+    /**
+     * Captures the connection context onto the instance so {@link BaseRemoteBrowserProvider.Features},
+     * {@link BaseRemoteBrowserProvider.RequireFeature}, and capability-error messages have the
+     * backend's flags and name. A concrete {@link BaseRemoteBrowserProvider.Connect} should call this
+     * first.
+     *
+     * @param ctx The provider context handed to `Connect`.
+     */
+    protected applyContext(ctx: RemoteBrowserProviderContext): void;
+    /**
+     * Defense-in-depth guard: asserts a `SupportedFeatures` flag is enabled before the driver performs
+     * a capability-gated action, throwing {@link RemoteBrowserCapabilityNotSupportedError} if it is
+     * false/omitted. A driver should call this at the top of any capability-gated work so that even a
+     * direct (engine-bypassing) caller cannot run an action the metadata says is off.
+     *
+     * @param featureName The `IRemoteBrowserProviderFeatures` flag to require.
+     * @throws {RemoteBrowserCapabilityNotSupportedError} when the flag is not enabled.
+     */
+    protected RequireFeature(featureName: keyof IRemoteBrowserProviderFeatures): void;
+    /**
+     * Builds the standard {@link RemoteBrowserCapabilityNotSupportedError} for an un-overridden
+     * capability or a failed feature requirement, stamped with this driver's backend name.
+     *
+     * @param featureName The feature / method name to report.
+     * @returns The error to throw or reject with.
+     */
+    protected notSupported(featureName: string): RemoteBrowserCapabilityNotSupportedError;
+}
+//# sourceMappingURL=base-remote-browser-provider.d.ts.map

package/dist/base-remote-browser-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-remote-browser-provider.d.ts","sourceRoot":"","sources":["../src/base-remote-browser-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,8BAA8B,EAAE,MAAM,2BAA2B,CAAC;AAC3E,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,wCAAwC,EAAE,MAAM,qBAAqB,CAAC;AAE/E;;;;;;;;GAQG;AACH,MAAM,WAAW,4BAA4B;IACzC;;;;OAIG;IACH,QAAQ,EAAE,8BAA8B,CAAC;IAEzC;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,YAAY,EAAE,UAAU,GAAG,SAAS,CAAC;IAErC;;;;OAIG;IACH,WAAW,EAAE,wBAAwB,CAAC;IAEtC;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAExC;;;OAGG;IACH,WAAW,CAAC,EAAE,QAAQ,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,8BAAsB,yBAAyB;IAC3C;;;;OAIG;IACH,SAAS,CAAC,QAAQ,EAAE,8BAA8B,CAAM;IAExD;;;OAGG;IACH,SAAS,CAAC,YAAY,EAAE,MAAM,CAAM;IAEpC;;;;;;;OAOG;IACH,IAAW,QAAQ,IAAI,8BAA8B,CAEpD;IAMD;;;;;;;;;OASG;aACa,OAAO,CAAC,GAAG,EAAE,4BAA4B,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAE1F;;;;;;OAMG;aACa,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3C;;;;;;;OAOG;IACH,SAAS,CAAC,YAAY,CAAC,GAAG,EAAE,4BAA4B,GAAG,IAAI;IAK/D;;;;;;;;OAQG;IACH,SAAS,CAAC,cAAc,CAAC,WAAW,EAAE,MAAM,8BAA8B,GAAG,IAAI;IASjF;;;;;;OAMG;IACH,SAAS,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,wCAAwC;CAMxF"}

package/dist/base-remote-browser-provider.js

@@ -0,0 +1,95 @@
+import { RemoteBrowserCapabilityNotSupportedError } from './capability-errors.js';
+/**
+ * Abstract base class for a **Remote Browser** provider driver — a pluggable backend that opens (or
+ * attaches to) a real Chromium browser over the Chrome DevTools Protocol and returns a live
+ * {@link IRemoteBrowserSession} the agent drives.
+ *
+ * This is the sibling of `BaseRealtimeBridge`: the Remote Browser channel is built exactly like the
+ * bridge subsystem (registry table + base driver + EngineBase/Engine pair + pluggable backends). A
+ * concrete driver (`SelfHostedChromeRemoteBrowser`, `BrowserbaseRemoteBrowser`, …) implements only the
+ * irreducibly backend-specific primitives — everything generic (control arbitration, the
+ * viewport→screen-track encode, session bookkeeping) lives in the server engine above. Drivers
+ * self-register with the MemberJunction `ClassFactory` — e.g.
+ * `@RegisterClass(BaseRemoteBrowserProvider, 'BrowserbaseRemoteBrowser')`. The base class itself is
+ * abstract and unregistered; the engine resolves a driver via
+ * `MJGlobal.ClassFactory.CreateInstance(BaseRemoteBrowserProvider, provider.DriverClass)`.
+ *
+ * **Capability gating (two layers, defense-in-depth).** The engine FIRST checks a provider's
+ * `SupportedFeatures` flag and never calls a session method whose feature is off. The driver's own
+ * capability-gated work is the SECOND layer: it calls {@link BaseRemoteBrowserProvider.RequireFeature}
+ * (or builds an error via {@link BaseRemoteBrowserProvider.notSupported}) so a metadata flag that
+ * lied — or a caller that bypassed the gate — fails loudly rather than silently degrading.
+ *
+ * **Universal CDP substrate.** Every backend (self-hosted Chrome and every browser-as-a-service)
+ * exposes a CDP endpoint; the engine standardizes on CDP-connect (reusing `@memberjunction/computer-use`
+ * server-side) so this Base package itself stays dependency-light and universal.
+ *
+ * @see `/plans/realtime/realtime-bridges-architecture.md` §4d / §4d-i.
+ * @abstract
+ */
+export class BaseRemoteBrowserProvider {
+    constructor() {
+        /**
+         * The capability flags for the backend this driver instance serves. Populated from the
+         * {@link RemoteBrowserProviderContext} at {@link BaseRemoteBrowserProvider.Connect} time (call
+         * `this.applyContext(ctx)` first). Drives {@link BaseRemoteBrowserProvider.RequireFeature}.
+         */
+        this.features = {};
+        /**
+         * The backend's display name for this driver instance, used in capability-error messages.
+         * Populated from the {@link RemoteBrowserProviderContext}; falls back to the driver class name.
+         */
+        this.providerName = '';
+    }
+    /**
+     * The backend's supported-feature flags for this driver instance.
+     *
+     * Read-only accessor over the internally-held {@link BaseRemoteBrowserProvider.features}. The
+     * engine consults this (and the underlying provider metadata) to decide which capability-gated
+     * session methods are safe to call; a driver consults it via
+     * {@link BaseRemoteBrowserProvider.RequireFeature}.
+     */
+    get Features() {
+        return this.features;
+    }
+    // ──────────────────────────────────────────────────────────────────────────────
+    // Protected helpers for driver authors.
+    // ──────────────────────────────────────────────────────────────────────────────
+    /**
+     * Captures the connection context onto the instance so {@link BaseRemoteBrowserProvider.Features},
+     * {@link BaseRemoteBrowserProvider.RequireFeature}, and capability-error messages have the
+     * backend's flags and name. A concrete {@link BaseRemoteBrowserProvider.Connect} should call this
+     * first.
+     *
+     * @param ctx The provider context handed to `Connect`.
+     */
+    applyContext(ctx) {
+        this.features = ctx.Features ?? {};
+        this.providerName = ctx.ProviderName || this.constructor.name;
+    }
+    /**
+     * Defense-in-depth guard: asserts a `SupportedFeatures` flag is enabled before the driver performs
+     * a capability-gated action, throwing {@link RemoteBrowserCapabilityNotSupportedError} if it is
+     * false/omitted. A driver should call this at the top of any capability-gated work so that even a
+     * direct (engine-bypassing) caller cannot run an action the metadata says is off.
+     *
+     * @param featureName The `IRemoteBrowserProviderFeatures` flag to require.
+     * @throws {RemoteBrowserCapabilityNotSupportedError} when the flag is not enabled.
+     */
+    RequireFeature(featureName) {
+        if (this.features[featureName] !== true) {
+            throw new RemoteBrowserCapabilityNotSupportedError(String(featureName), this.providerName || this.constructor.name);
+        }
+    }
+    /**
+     * Builds the standard {@link RemoteBrowserCapabilityNotSupportedError} for an un-overridden
+     * capability or a failed feature requirement, stamped with this driver's backend name.
+     *
+     * @param featureName The feature / method name to report.
+     * @returns The error to throw or reject with.
+     */
+    notSupported(featureName) {
+        return new RemoteBrowserCapabilityNotSupportedError(featureName, this.providerName || this.constructor.name);
+    }
+}
+//# sourceMappingURL=base-remote-browser-provider.js.map

package/dist/base-remote-browser-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-remote-browser-provider.js","sourceRoot":"","sources":["../src/base-remote-browser-provider.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,wCAAwC,EAAE,MAAM,qBAAqB,CAAC;AAuD/E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,OAAgB,yBAAyB;IAA/C;QACI;;;;WAIG;QACO,aAAQ,GAAmC,EAAE,CAAC;QAExD;;;WAGG;QACO,iBAAY,GAAW,EAAE,CAAC;IAuFxC,CAAC;IArFG;;;;;;;OAOG;IACH,IAAW,QAAQ;QACf,OAAO,IAAI,CAAC,QAAQ,CAAC;IACzB,CAAC;IA2BD,iFAAiF;IACjF,wCAAwC;IACxC,iFAAiF;IAEjF;;;;;;;OAOG;IACO,YAAY,CAAC,GAAiC;QACpD,IAAI,CAAC,QAAQ,GAAG,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC;QACnC,IAAI,CAAC,YAAY,GAAG,GAAG,CAAC,YAAY,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;IAClE,CAAC;IAED;;;;;;;;OAQG;IACO,cAAc,CAAC,WAAiD;QACtE,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,KAAK,IAAI,EAAE,CAAC;YACtC,MAAM,IAAI,wCAAwC,CAC9C,MAAM,CAAC,WAAW,CAAC,EACnB,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,CAC7C,CAAC;QACN,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACO,YAAY,CAAC,WAAmB;QACtC,OAAO,IAAI,wCAAwC,CAC/C,WAAW,EACX,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,CAC7C,CAAC;IACN,CAAC;CACJ"}

package/dist/capability-errors.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Error types for the remote-browser capability-gating flow.
+ *
+ * See `/plans/realtime/realtime-bridges-architecture.md` §4d-i — the Remote Browser channel is built
+ * exactly like the bridge subsystem (registry table + base driver + EngineBase/Engine pair +
+ * pluggable backends), with the same two-layer capability gating. The engine checks a provider's
+ * `SupportedFeatures` flag BEFORE calling an optional driver method; this error is the
+ * **defense-in-depth** layer that fires when a feature is claimed in metadata but the concrete driver
+ * never implemented it (or a caller skipped the metadata gate). Metadata says "don't call this"; the
+ * throw means the code refuses to pretend a capability exists.
+ */
+/**
+ * Thrown when a capability-gated remote-browser feature is invoked on a driver that does not support it.
+ *
+ * Two distinct failure modes both surface as this error:
+ * 1. A `BaseRemoteBrowserProvider` **virtual** method (e.g. `GetLiveViewUrl`, `StartScreencast`) was
+ *    called but the concrete driver did not override the base implementation — the base throws this.
+ * 2. The driver's `RequireFeature(...)` defense-in-depth guard found the matching
+ *    `IRemoteBrowserProviderFeatures` flag false/omitted — the metadata claims the feature is off, so
+ *    the call must not proceed.
+ *
+ * Carrying both the `FeatureName` and the `ProviderName` makes the loud failure actionable: it points
+ * at exactly which capability flag lied (or which driver method is missing) for which backend.
+ */
+export declare class RemoteBrowserCapabilityNotSupportedError extends Error {
+    /**
+     * The name of the unsupported feature — by convention an `IRemoteBrowserProviderFeatures` key
+     * (e.g. `'LiveView'`, `'HumanTakeover'`, `'NativeAIControl'`) or the virtual method name when the
+     * throw originates from an un-overridden base method.
+     */
+    readonly FeatureName: string;
+    /**
+     * The remote-browser backend the call targeted (e.g. `'Browserbase'`, `'Self-Hosted Chrome'`).
+     * Sourced from the provider metadata row's `Name`, or the driver's own identifier when the
+     * provider name is not available at the throw site.
+     */
+    readonly ProviderName: string;
+    /**
+     * Constructs a {@link RemoteBrowserCapabilityNotSupportedError}.
+     *
+     * @param featureName The unsupported feature / method name (an `IRemoteBrowserProviderFeatures` key by convention).
+     * @param providerName The backend the call targeted (e.g. `'Browserbase'`, `'Steel'`).
+     * @param message Optional override for the human-readable message; a sensible default is built from the two names.
+     */
+    constructor(featureName: string, providerName: string, message?: string);
+}
+//# sourceMappingURL=capability-errors.d.ts.map

package/dist/capability-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-errors.d.ts","sourceRoot":"","sources":["../src/capability-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;GAYG;AACH,qBAAa,wCAAyC,SAAQ,KAAK;IAC/D;;;;OAIG;IACH,SAAgB,WAAW,EAAE,MAAM,CAAC;IAEpC;;;;OAIG;IACH,SAAgB,YAAY,EAAE,MAAM,CAAC;IAErC;;;;;;OAMG;gBACS,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAY1E"}

package/dist/capability-errors.js

@@ -0,0 +1,44 @@
+/**
+ * Error types for the remote-browser capability-gating flow.
+ *
+ * See `/plans/realtime/realtime-bridges-architecture.md` §4d-i — the Remote Browser channel is built
+ * exactly like the bridge subsystem (registry table + base driver + EngineBase/Engine pair +
+ * pluggable backends), with the same two-layer capability gating. The engine checks a provider's
+ * `SupportedFeatures` flag BEFORE calling an optional driver method; this error is the
+ * **defense-in-depth** layer that fires when a feature is claimed in metadata but the concrete driver
+ * never implemented it (or a caller skipped the metadata gate). Metadata says "don't call this"; the
+ * throw means the code refuses to pretend a capability exists.
+ */
+/**
+ * Thrown when a capability-gated remote-browser feature is invoked on a driver that does not support it.
+ *
+ * Two distinct failure modes both surface as this error:
+ * 1. A `BaseRemoteBrowserProvider` **virtual** method (e.g. `GetLiveViewUrl`, `StartScreencast`) was
+ *    called but the concrete driver did not override the base implementation — the base throws this.
+ * 2. The driver's `RequireFeature(...)` defense-in-depth guard found the matching
+ *    `IRemoteBrowserProviderFeatures` flag false/omitted — the metadata claims the feature is off, so
+ *    the call must not proceed.
+ *
+ * Carrying both the `FeatureName` and the `ProviderName` makes the loud failure actionable: it points
+ * at exactly which capability flag lied (or which driver method is missing) for which backend.
+ */
+export class RemoteBrowserCapabilityNotSupportedError extends Error {
+    /**
+     * Constructs a {@link RemoteBrowserCapabilityNotSupportedError}.
+     *
+     * @param featureName The unsupported feature / method name (an `IRemoteBrowserProviderFeatures` key by convention).
+     * @param providerName The backend the call targeted (e.g. `'Browserbase'`, `'Steel'`).
+     * @param message Optional override for the human-readable message; a sensible default is built from the two names.
+     */
+    constructor(featureName, providerName, message) {
+        super(message ??
+            `Remote browser capability '${featureName}' is not supported by provider '${providerName}'. ` +
+                `Either the provider's SupportedFeatures does not enable it, or its driver does not implement it.`);
+        this.name = 'RemoteBrowserCapabilityNotSupportedError';
+        this.FeatureName = featureName;
+        this.ProviderName = providerName;
+        // Restore the prototype chain — required when extending built-ins under ES2015+ down-compilation.
+        Object.setPrototypeOf(this, RemoteBrowserCapabilityNotSupportedError.prototype);
+    }
+}
+//# sourceMappingURL=capability-errors.js.map

package/dist/capability-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-errors.js","sourceRoot":"","sources":["../src/capability-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,wCAAyC,SAAQ,KAAK;IAe/D;;;;;;OAMG;IACH,YAAY,WAAmB,EAAE,YAAoB,EAAE,OAAgB;QACnE,KAAK,CACD,OAAO;YACH,8BAA8B,WAAW,mCAAmC,YAAY,KAAK;gBACzF,kGAAkG,CAC7G,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,0CAA0C,CAAC;QACvD,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,kGAAkG;QAClG,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,wCAAwC,CAAC,SAAS,CAAC,CAAC;IACpF,CAAC;CACJ"}

package/dist/control.d.ts

@@ -0,0 +1,69 @@
+import { IRemoteBrowserProviderFeatures } from './remote-browser-features.js';
+/**
+ * How control of the remote browser is shared between the agent and humans — a per-provider default
+ * (`MJ: AI Remote Browser Providers.DefaultControlMode`) that the `RemoteBrowserChannel` config
+ * overrides per-channel and at runtime.
+ *
+ * This is **distinct from** {@link RemoteBrowserControlStrategy}: the *mode* is the human/agent
+ * sharing policy, the *strategy* is the mechanism by which the agent decides what to do.
+ *
+ * - `AgentOnly` — only the agent drives; no human takeover (e.g. a hands-off sales demo).
+ * - `ViewOnly` — the agent drives while humans **watch** the live view but cannot take the wheel.
+ *   Requires the backend's `LiveView` capability.
+ * - `Collaborative` — a human can **grab the wheel** (e.g. a trainer agent: demonstrate a task, then
+ *   "your turn, try X"). Requires both `LiveView` (to watch) and `HumanTakeover` (to drive).
+ *
+ * @see `/plans/realtime/realtime-bridges-architecture.md` §4d-i.
+ */
+export type RemoteBrowserControlMode = 'AgentOnly' | 'ViewOnly' | 'Collaborative';
+/**
+ * The mechanism by which the agent decides *what to click/type/navigate* — a pluggable strategy
+ * gated by capability, orthogonal to the {@link RemoteBrowserControlMode}.
+ *
+ * - `ComputerUse` — MJ's own perception→action loop over the universal CDP substrate
+ *   (`@memberjunction/computer-use`). The default; works on every backend that exposes
+ *   `RawCdpControl`. The right fit for a realtime co-agent that is already a powerful brain emitting
+ *   tool calls while it talks.
+ * - `NativeAI` — delegate high-level intents to the backend's own first-party AI-control harness
+ *   (e.g. Browserbase Stagehand, Hyperbrowser agent). An optional accelerator for heavy, robust
+ *   autonomous automation; it runs its own model loop, so it is offered, never the default. Requires
+ *   the backend's `NativeAIControl` capability.
+ *
+ * @see `/plans/realtime/realtime-bridges-architecture.md` §4d-i ("Control is a pluggable STRATEGY").
+ */
+export type RemoteBrowserControlStrategy = 'ComputerUse' | 'NativeAI';
+/**
+ * Determines whether a {@link RemoteBrowserControlMode} is valid given a backend's capabilities.
+ *
+ * A mode is only valid when the backend supports the capabilities it requires:
+ * - `AgentOnly` — always valid (the agent drives; no viewing/takeover prerequisite).
+ * - `ViewOnly` — requires `LiveView` (humans must be able to watch).
+ * - `Collaborative` — requires `LiveView` **and** `HumanTakeover` (humans watch *and* can take over).
+ *
+ * @param mode The control mode to validate.
+ * @param features The backend's capability flags.
+ * @returns `true` when the backend can support the mode, `false` otherwise.
+ */
+export declare function isControlModeSupported(mode: RemoteBrowserControlMode, features: IRemoteBrowserProviderFeatures): boolean;
+/**
+ * Resolves which {@link RemoteBrowserControlStrategy} the engine should use for a backend, honoring an
+ * optional caller preference.
+ *
+ * **Precedence (highest to lowest):**
+ * 1. **`NativeAI`** — chosen *only* when the backend advertises `NativeAIControl` **and** the caller
+ *    did not explicitly pin `ComputerUse`. (A caller preference of `'NativeAI'` is honored only if the
+ *    backend actually supports it; an explicit `'ComputerUse'` always suppresses native delegation.)
+ * 2. **`ComputerUse`** — the universal default, chosen whenever the backend exposes the
+ *    `RawCdpControl` substrate and native control was not selected above.
+ * 3. **`ComputerUse`** — also the fallback when neither flag is set, because CDP-connect is the one
+ *    primitive every backend is expected to provide; emitting `ComputerUse` lets the caller surface a
+ *    clear downstream error if the backend genuinely cannot be driven, rather than this helper
+ *    inventing an unsupported strategy.
+ *
+ * @param features The backend's capability flags.
+ * @param preferred An optional caller preference; `'ComputerUse'` pins the universal loop and
+ *  suppresses native delegation even when the backend supports it.
+ * @returns The resolved control strategy.
+ */
+export declare function resolveControlStrategy(features: IRemoteBrowserProviderFeatures, preferred?: RemoteBrowserControlStrategy): RemoteBrowserControlStrategy;
+//# sourceMappingURL=control.d.ts.map

package/dist/control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../src/control.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,8BAA8B,EAAE,MAAM,2BAA2B,CAAC;AAE3E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,wBAAwB,GAAG,WAAW,GAAG,UAAU,GAAG,eAAe,CAAC;AAElF;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,4BAA4B,GAAG,aAAa,GAAG,UAAU,CAAC;AAEtE;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAClC,IAAI,EAAE,wBAAwB,EAC9B,QAAQ,EAAE,8BAA8B,GACzC,OAAO,CAYT;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CAClC,QAAQ,EAAE,8BAA8B,EACxC,SAAS,CAAC,EAAE,4BAA4B,GACzC,4BAA4B,CAK9B"}