@aimform/browser

Provider-neutral browser automation contracts for App Functions that need a web interface. The package owns deterministic browser primitives, domain and egress policy validation, persistent profile references, and the human takeover state model. Cloudflare Browser Run is one provider implementation; the service composition root supplies its binding.

The browser_use Agent tool is also exported from the core SDK. It accepts a bounded declarative BrowserFunctionPlan with an explicit domain allowlist; the model never supplies executable browser code.

import { Browser, type BrowserAdapter } from "@aimform/browser";

const browser = new Browser(adapter satisfies BrowserAdapter);
const session = await browser.newSession({
  organizationId: "org_123",
  profileId: "profile_123",
  plan: {
    policy: { allowedDomains: ["merchant.example"] },
    actions: [{ type: "goto", url: "https://merchant.example/orders" }],
  },
});

Browser policy is fail-closed: a plan must declare allowed domains, navigation must use HTTPS by default, downloads are disabled unless explicitly enabled, and action/page/time budgets are bounded. Browser profiles are opaque to Workflows; trusted services persist encrypted cookies and provider session references behind the BrowserProfileStore boundary.

BrowserTakeoverReason covers CAPTCHA, 2FA, payment challenges, and unexpected checkout screens. Providers report these as a durable human interaction requirement instead of attempting to bypass them.

Production browser hosts pass either { guard } or the explicit { delegatedGuard: true } mode to an adapter. The latter is used only when an outer service boundary has already admitted the operation; it is not a no-op Guard. The provider admits sessions and actions before the browser runtime is called and tracks page, step, duration, compute, and effect usage.

Residential egress is represented by a non-secret egressConnectionId and resolved through BrowserEgressProvider. Its short-lived lease may contain proxy credentials, but those credentials stay in the provider/runtime boundary; only browserEgressMetadata is safe for Agent View and telemetry. Browser Run is direct-egress only, so CloudflareBrowserAdapter rejects an egress request; BrowserUseCloudAdapter is the proxy-capable runtime for residential leases.

The package includes a shared residential proxy adapter system for DataImpulse, Decodo, IPRoyal, and Webshare. Each provider exposes the same BrowserEgressProvider contract, so Browser Use and other Apps/Tools can bind to the provider-neutral browser.egress.residential capability while the selected provider remains visible in safe runtime metadata. Legacy ResidentialProxyGatewayProvider and QuestingoResidentialProxyProvider adapters remain available for existing Connections during catalog migration. All adapters keep credentials runtime-only, reject private proxy endpoints, and expose a configuration health result that explicitly marks proxy reachability as not_tested; reachability testing remains an operational runtime check rather than a connection-health metadata check.

Detached jobs use task-scoped opaque browser session handles and isolated runtime contexts. They may seed an initial context from a connected profile, but never reuse or write back that profile's provider session or cookies.

BrowserUseCloudAdapter provisions a proxy-capable Browser Use Cloud session through the v3 REST API and connects over its CDP endpoint. A trusted service maps a runtime-only BrowserEgressLease to the API's customProxy fields. The adapter reuses active provider session IDs, emits bounded intermediate snapshots and pointer telemetry, and fails closed when a lease or Browser Use Cloud configuration is missing. The Browser Worker persists snapshots to R2 and returns opaque artifact references.

Browser providers return BrowserSessionUsage with runtime, page, action, session, provider API, and artifact measurements. proxyTrafficBytes is only populated when the runtime can prove provider-reported proxy traffic; callers must not derive it from screenshots or downloads. A browser egress request may also specify mode: "sticky" | "rotating" and, for rotating mode, rotation: "per-session" | "interval".

Providers may optionally implement guarded aggregate usage reporting for proxyTrafficBytes, proxySessions, and providerApiCalls. The reconciliation helper compares provider-reported usage with retry-safe internal receipts and returns only non-secret measurements; credentials, endpoints, provider session references, and full proxy addresses remain runtime-only.

Browser v2 compatibility

Browser v2 adds runtime-neutral observation, events, checkpoints, profile transfer policy, access challenges, and debug/network contracts. Existing v1 plans remain valid and can be compiled without execution:

import { compileBrowserV1Plan } from "@aimform/browser";

const v2 = compileBrowserV1Plan(v1Plan);
// v2.steps contains Interface Runtime actions, exact wait conditions, and
// browser artifact operations with the original policy preserved.

The compiler is deterministic and side-effect free. Providers still own browser sessions and must apply Identity, Execution Agreement, and Guard policy before consequence-bearing execution.

The cloud v2 runtime adapters are additive to the existing providers. They share one observable Puppeteer runtime that exposes bounded DOM observations, semantic, accessibility-labelled, and text-only observations, semantic and observed-reference actions, exact event-driven waits, network and console events, screenshots, and checkpoints. Events are ordered per runtime/session identity; stale, duplicate, or cross-runtime events cannot satisfy a wait. CloudflareBrowserAdapter continues to use Browser Run, while BrowserUseCloudAdapter continues to own the proxy-capable Browser Use Cloud connection path; neither provider is replaced or silently upgraded.

Every v2 open/attach request may carry a provider-neutral lineage context (traceId, runId, optional agreementId, and task id). The runtime copies that context to observations, checkpoints, events, and browser action access failures. An internal runtime request may keep a provider session alive after a checkpoint so a later, explicitly scoped attach can resume it; the caller must close the session and the service still applies the outer Guard admission.

Browser access failures are classified into authentication-required, connection-expired, permission-denied, challenge, drift, unavailable, and target-missing. Challenge and authentication failures become explicit human barriers; the runtime never attempts to bypass them.

The native desktop target includes a small Rust SystemWebView runtime. Its bridge accepts only a narrow, JSON-safe page-evaluation operation and action script compilation. Remote pages do not receive Tauri filesystem, shell, credential, or other privileged commands. Platform webview bindings remain behind the native host boundary, and navigation still passes the same allowlist/HTTPS policy before execution. Page automation is a separate explicit permission (allow_automation) and defaults to denied; screen capture has a separate reserved permission and is never inferred from automation.

Browser Profile v2 and existing-browser binding

Browser Profile v2 distinguishes native-aimform, external-binding, and ephemeral profiles. Transfer policy is explicit and fail-closed: the default is never, selected-origin transfer requires an allowlist, and profile state is represented by opaque state/Vault references rather than inline secrets.

ExistingBrowserRuntimeV2Adapter is an authorization-first provider. Its composition root must select an explicit browser and profile reference (and may select a tab/authorization reference); arbitrary process or profile attachment is not supported. Existing-browser sessions are local, live, and never silently transferred to cloud execution.