@amalgm/browser 0.1.0

package/dist/src/types.d.ts

@@ -0,0 +1,273 @@
+export type BrowserBackendKind = 'electron' | 'headless';
+export type BrowserCapability = 'core' | 'computer-use' | 'recording' | 'auth' | 'full-page-capture' | 'ad-blocking' | 'visible-surface' | 'live-login';
+export type BrowserSessionStatus = 'creating' | 'ready' | 'closing' | 'closed' | 'failed';
+export type BrowserProfileKind = 'durable' | 'ephemeral';
+export interface BrowserRuntimeContext {
+    ownerId?: string;
+    callerId?: string;
+    clientKind?: 'desktop' | 'web' | 'cli' | 'mcp' | 'rest' | 'automation' | 'agent';
+    projectRef?: string;
+    cwdRef?: string;
+    artifactDestination?: string;
+    authorization?: unknown;
+    signal?: AbortSignal;
+}
+export interface BrowserProfile {
+    id: string;
+    name: string;
+    kind: BrowserProfileKind;
+    createdAt: string;
+    updatedAt: string;
+    lastUsedAt: string;
+}
+export interface BrowserProfileStatus {
+    profile: BrowserProfile;
+    live: boolean;
+    referenced: boolean;
+    locked: boolean;
+}
+export interface BrowserSession {
+    id: string;
+    ownerId?: string;
+    profileId: string;
+    backend: BrowserBackendKind;
+    status: BrowserSessionStatus;
+    capabilities: BrowserCapability[];
+    createdAt: string;
+    updatedAt: string;
+    lastActiveAt: string;
+    url?: string;
+    title?: string;
+    error?: string;
+}
+export interface BrowserCapture {
+    mimeType: 'image/png' | 'image/jpeg';
+    base64: string;
+    bytes: number;
+    width?: number;
+    height?: number;
+    coordinateSpace: 'css-pixel';
+}
+export interface BrowserArtifact {
+    id: string;
+    kind: 'capture' | 'recording' | 'download' | 'trace';
+    path: string;
+    mimeType: string;
+    bytes: number;
+    createdAt: string;
+}
+export interface BrowserRecording {
+    id: string;
+    sessionId: string;
+    ownerPid?: number;
+    status: 'active' | 'stopped' | 'failed';
+    fps: number;
+    createdAt: string;
+    stoppedAt?: string;
+    wallSeconds?: number;
+    videoSeconds?: number;
+    frames?: number;
+    framesReceived?: number;
+    skippedTicks?: number;
+    artifact?: BrowserArtifact;
+    warning?: string;
+}
+export type CuaOperation = {
+    kind: 'screenshot';
+    fullPage?: boolean;
+} | {
+    kind: 'click' | 'double_click' | 'move';
+    x: number;
+    y: number;
+    button?: 'left' | 'middle' | 'right';
+} | {
+    kind: 'scroll';
+    scrollX?: number;
+    scrollY?: number;
+} | {
+    kind: 'type';
+    text: string;
+} | {
+    kind: 'keypress';
+    keys: string[];
+} | {
+    kind: 'drag';
+    path: Array<{
+        x: number;
+        y: number;
+    }>;
+};
+export type BrowserAction = {
+    type: 'open';
+    url: string;
+} | {
+    type: 'snapshot';
+} | {
+    type: 'screenshot';
+    fullPage?: boolean;
+} | {
+    type: 'click';
+    target: string;
+} | {
+    type: 'fill';
+    target: string;
+    text: string;
+    submit?: boolean;
+} | {
+    type: 'press';
+    key: string;
+} | {
+    type: 'select';
+    target: string;
+    value: string;
+} | {
+    type: 'eval';
+    script: string;
+} | {
+    type: 'wait';
+    selector?: string;
+    url?: string;
+    ms?: number;
+    timeoutMs?: number;
+} | {
+    type: 'cli';
+    args: string[];
+    timeoutMs?: number;
+} | {
+    type: 'dialog';
+    action: 'accept' | 'dismiss';
+    text?: string;
+} | {
+    type: 'tab';
+    action: 'list' | 'switch' | 'new' | 'close';
+    id?: string;
+} | {
+    type: 'console';
+    clear?: boolean;
+} | {
+    type: 'cua';
+    operation: CuaOperation;
+} | {
+    type: 'close';
+};
+export type BrowserActionName = BrowserAction['type'];
+export type BrowserActionResult = {
+    type: 'page';
+    url: string;
+    title: string;
+    text?: string;
+} | {
+    type: 'capture';
+    capture: BrowserCapture;
+} | {
+    type: 'value';
+    value: unknown;
+} | {
+    type: 'tabs';
+    tabs: unknown[];
+} | {
+    type: 'console';
+    logs: unknown;
+    errors: unknown;
+} | {
+    type: 'ok';
+    message?: string;
+    evidence?: BrowserActionEvidence;
+};
+export interface BrowserActionEvidence {
+    targetEnabled?: boolean;
+    value?: {
+        before?: string;
+        after: string;
+        changed?: boolean;
+    };
+    keys?: {
+        dispatched: number;
+        flood?: boolean;
+    };
+    page?: {
+        url?: string;
+        title?: string;
+        urlChanged?: boolean;
+        dialog?: string;
+    };
+    warnings: string[];
+}
+export type BrowserEvent = {
+    version: 1;
+    id: string;
+    at: string;
+    sessionId?: string;
+    profileId?: string;
+} & ({
+    type: 'session.created' | 'session.ready' | 'session.closed';
+    backend: BrowserBackendKind;
+} | {
+    type: 'session.failed';
+    error: string;
+} | {
+    type: 'page.navigated';
+    origin: string;
+} | {
+    type: 'page.failed';
+    origin: string;
+    errorCode: number;
+} | {
+    type: 'profile.updated';
+} | {
+    type: 'recording.started' | 'recording.stopped';
+    recordingId: string;
+} | {
+    type: 'login.updated';
+    loginSessionId: string;
+    status: BrowserLoginSession['status'];
+} | {
+    type: 'cookie-jar.changed';
+    versionToken: string;
+} | {
+    type: 'surface.requested' | 'surface.bound' | 'surface.updated' | 'surface.lost';
+    surfaceId?: string;
+} | {
+    type: 'download.updated';
+    downloadId: string;
+    state: string;
+    receivedBytes: number;
+    totalBytes: number;
+} | {
+    type: 'permission.requested';
+    permission: string;
+    origin: string;
+});
+export type BrowserEventInput = BrowserEvent extends infer Event ? Event extends BrowserEvent ? Omit<Event, 'version' | 'id' | 'at'> : never : never;
+export interface BrowserAuthBundle {
+    id: string;
+    name: string;
+    profileId: string;
+    domains: string[];
+    storageKinds: Array<'cookies' | 'localStorage' | 'sessionStorage'>;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface BrowserLoginSession {
+    id: string;
+    profileId: string;
+    targetUrl: string;
+    domains: string[];
+    status: 'pending' | 'active' | 'completed' | 'cancelled' | 'expired';
+    transport: 'electron-surface' | 'novnc' | 'external';
+    liveUrl?: string;
+    setupStatus?: 'ready' | 'missing_novnc_url' | 'manual';
+    expiresAt: string;
+    createdAt: string;
+    updatedAt: string;
+    authBundleId?: string;
+}
+export interface BrowserHostAdvertisement {
+    protocol: number;
+    backend: 'electron';
+    pid: number;
+    cdpUrl: string;
+    targetTypes: Array<'page' | 'webview'>;
+    createdAt?: string;
+    file?: string;
+}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/docs/ACTIONS.md

@@ -0,0 +1,27 @@
+# Action surface
+
+The descriptor array in `src/adapters/actions.ts` is the source of truth for
+all public actions. SDK adapters must project every descriptor exactly once.
+
+Core actions are `open`, `snapshot`, `screenshot`, `click`, `fill`, `press`,
+`select`, `eval`, `wait`, `cli`, `dialog`, `tab`, `console`, and `close`.
+Browser-scoped computer use is `cua`. Recording adds `record_start`,
+`record_stop`, and `record_list`. Authentication adds `auth_list`,
+`auth_link_create`, `auth_save`, and `auth_load`.
+
+CLI resource commands are ergonomic spellings over these actions. MCP uses
+`browser_<action>`. Toolbox uses `browser.<action>` with
+`toolbox__browser_<action>` as its transport name. REST uses resource paths
+and posts canonical action inputs. No adapter assigns different semantics.
+
+Targets use one stable grammar: accessibility snapshot references such as
+`@e12`, CSS selectors, or `text=Visible label`. Prefer snapshot references;
+use browser-scoped CUA for canvas, WebGL, image-only, or hostile custom UI.
+
+`cua.operation.kind` is one of `screenshot`, `click`, `double_click`, `move`,
+`scroll`, `type`, `keypress`, or `drag`. Coordinates are CSS pixels and map
+1:1 to returned viewport screenshots.
+
+Backends advertise capability groups. Core semantics are never approximated
+when a backend lacks `computer-use`, `recording`, `auth`, full-page capture,
+visible surfaces, live login, or native ad blocking.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,71 @@
+# Architecture
+
+`BrowserProductService` is the product boundary. It composes session and
+profile policy, encrypted cookie coordination, auth bundles, login handoffs,
+and recording lifecycles. Drivers operate physical browsers. Transport
+adapters translate their inputs into this service and do not own browser
+policy.
+
+## Derivation
+
+The purpose requires one meaning for every browser action across desktop and
+server environments. Therefore:
+
+1. A typed action enters `BrowserService`.
+2. The service authorizes it, checks session state and capabilities, and
+   acquires the session lease.
+3. The session's immutable backend selects exactly one driver.
+4. The driver acts on the session's exact page or verified visible surface.
+5. The service persists the transition and emits a sanitized event.
+
+CLI, MCP, REST, and Toolbox all dispatch through the same canonical action
+descriptor array. The generated reachability test calls all 22 actions through
+all five surfaces.
+
+## Ownership map
+
+- `service.ts`, `product-service.ts` — mutation boundary and product services
+- `sessions/`, `profiles/` — leases and lifecycle policy
+- `drivers/headless/` — `agent-browser`, CDP, profiles, and physical cookies
+- `drivers/electron/` — verified visible driver and host advertisement
+- `drivers/electron/native/` — `WebContentsView` shell, surfaces, policy,
+  downloads, permissions, menus, and native ad blocking
+- `drivers/cdp/` — exact-target capture, input, and cancellable protocol client
+- `cookies/` — encrypted logical authority and adapter reconciliation
+- `auth/` — explicit bundles and TTL-bound human login
+- `recording/` — page screencast, latest-frame sampler, and bounded encoder
+- `persistence/`, `migration/` — SQLite state and idempotent legacy import
+- `adapters/` — CLI, MCP, REST/SSE, and Toolbox projections
+
+## Runtime selection
+
+Selection happens once before open. A forced backend or explicit CDP endpoint
+wins. A fresh, compatible, loopback Electron host advertisement selects
+Electron only for a desktop owner. Everything else selects headless. A visible
+session never falls back to headless after identity loss.
+
+## Persistence and concurrency
+
+SQLite stores each metadata entity independently, uses WAL and a busy timeout,
+and holds cross-process session leases. Encrypted cookie/auth payloads use
+atomic private files because their security and integrity envelope is a better
+fit than ordinary database rows. Registry and migration writes are
+transactional. A restarted service reopens a persisted ready session through
+its assigned driver before acting.
+
+## Visible surfaces
+
+The Electron host creates native `WebContentsView` pages in the isolated
+Browser partition. Protocol-6 identity combines a session stamp, surface ID,
+marker URL, and declared target type. The driver verifies that identity before
+every action. It may reattach once only when the original surface is genuinely
+gone; ambiguity or mismatch fails before page input.
+
+## Data movement
+
+Physical Chromium stores remain isolated. Cookie adapters exchange normalized
+records with the encrypted logical jar, never with each other. Deletion is a
+tombstone and timestamp/source ordering makes merges deterministic. Named auth
+bundles are explicit filtered snapshots and can additionally contain supported
+origin storage. Events and ordinary resource projections contain metadata
+only.

package/docs/AUTHENTICATION.md

@@ -0,0 +1,56 @@
+# Authentication and login handoff
+
+Browser separates working profiles, automatic cookies, named auth bundles,
+and human login sessions. None is an alias for another.
+
+## Named auth bundles
+
+`browser.auth.save` asks the assigned driver for state, filters it to explicit
+domains, encrypts the payload, and stores only metadata in SQLite. Supported
+payloads can include cookies, localStorage, and sessionStorage. List/get return
+ID, name, profile, domains, storage kinds, and timestamps—never values.
+
+Loading is explicit and requires a capable session. Deleting removes both the
+encrypted payload and metadata. A bundle's profile reference protects that
+profile from pruning.
+
+Portable export/import re-encrypts a bundle with an explicitly authorized
+32-byte portable key and verifies metadata integrity on import. The portable
+resource is still ciphertext and should be handled as a credential.
+
+## Human login
+
+`browser.login.create` returns a session plus one random token and a
+token-bearing handoff URL. The credential is delivered only in that creation
+result. Browser stores a SHA-256 hash and compares verification values in
+constant time. Ordinary list/get never returns the token.
+
+TTL defaults to 15 minutes and is clamped from one minute to one hour. A handoff
+uses a durable profile while pending or active:
+
+1. Create the handoff for a target URL and filtered domains.
+2. Activate it after validating the token; Browser opens the owned profile.
+3. Forward browser-scoped CUA screenshot/input while the human signs in.
+4. Complete to save an encrypted named bundle and close the live session, or
+   cancel to close it without saving.
+
+Expired active sessions are closed. Completed, cancelled, and expired tokens
+cannot be reused.
+
+## Transports
+
+- `electron-surface` presents the verified page in the desktop app.
+- `novnc` uses `AMALGM_BROWSER_NOVNC_PUBLIC_URL` or
+  `AMALGM_BROWSER_NOVNC_URL` when configured.
+- `external` provides a host-integrated handoff.
+
+Transport selection is presentation; the auth lifecycle and profile ownership
+remain Browser rules.
+
+## Security boundary
+
+Device-local AES-GCM encryption protects against accidental plaintext
+exposure, not an attacker who can read both encrypted files and the local key.
+Treat token-bearing handoff URLs, portable resources, captures, and origin
+storage as credentials. They must not enter logs, events, chat history, or
+ordinary resource projections.

package/docs/AXIOMS.md

@@ -0,0 +1,20 @@
+# Axiom map
+
+[PURPOSE.md](../PURPOSE.md) is the authoritative list of primitives and 18
+product axioms. This document maps them to observable boundaries.
+
+| Axioms | Consequence | Evidence |
+| --- | --- | --- |
+| 1–3 | Browser owns state; sessions bind one profile and immutable backend | service and restart contracts |
+| 4–5 | Electron identity is verified; ordinary fallback is headless | identity and advertisement tests |
+| 6–8 | Capabilities are honest; work is cancellable and bounded | driver, CDP, process, and parity tests |
+| 9–13 | Cookie stores are isolated and secrets remain encrypted | cookie, auth, partition, and migration tests |
+| 14 | Capture and recording address the actual page | DPR, target, sampler, and real-runtime tests |
+| 15 | Context enters through ports; events are sanitized | artifact and SSE contracts |
+| 16 | Existing state is imported safely | transactional legacy fixture test |
+| 17–18 | One TypeScript implementation works without Engine/Electron | package install and adapter parity tests |
+
+When behavior fails, classify it against this map. If code drifted, restore the
+axiom everywhere it applies. If the axiom is incomplete, update
+`PURPOSE.md`, implementation, documentation, and invariant tests together. A
+transport-specific exception is not an acceptable fix for a domain rule.

package/docs/CLI.md

@@ -0,0 +1,61 @@
+# CLI
+
+`amalgm-browser` prints stable JSON to stdout and sanitized diagnostics to
+stderr. It never constructs a shell command.
+
+## Actions
+
+```text
+open <url>                     snapshot
+screenshot [--full-page]      click <target>
+fill <target> <text>           press <key>
+select <target> <value>        eval <script>
+wait [--selector|--url|--ms]   dialog|tab|console|cua --input <json>
+close                          action <name> --input <json>
+```
+
+Use one `--session` value across related invocations. The generic `action`
+form reaches every canonical action, including recording and auth actions.
+
+## Resources
+
+```text
+sessions list|get|close|cancel|prune [id]
+profiles list|get|create|update|delete|prune [id]
+auth list|link|save|load|delete [id]
+recordings start|stop|cancel|list|get [id]
+capabilities
+doctor
+serve
+mcp
+```
+
+Common options are `--session`, `--profile`, `--root`, `--cwd`, `--timeout`,
+`--headless`, `--headed`, and `--cdp`. `--cwd` supplies opaque cwd context and
+a local artifact destination; it does not create a Browser workspace model.
+
+`--headed` is an explicit debug choice. Ordinary standalone and background use
+stays headless. `--cdp` attaches to an operator-provided endpoint.
+
+## REST and MCP modes
+
+```sh
+amalgm-browser mcp
+amalgm-browser serve --token "$AMALGM_BROWSER_TOKEN" --port 8787
+```
+
+`serve` binds `127.0.0.1` unless `--host` is supplied. A non-loopback host also
+requires `--allow-remote`; bearer authentication remains mandatory.
+
+## Exit codes
+
+- `0` success
+- `2` invalid input
+- `3` authorization denied
+- `4` resource not found
+- `5` timeout or cancellation
+- `1` other typed failure
+
+Use `--timeout <ms>` to abort a blocking operation. Recording start without a
+duration remains active until SIGINT or SIGTERM, then stops and flushes within
+the encoder deadline.

package/docs/COMPATIBILITY.md

@@ -0,0 +1,45 @@
+# Compatibility
+
+## Runtime and package
+
+- Node.js: 20 or newer
+- modules: ESM import only
+- Electron: optional peer, version 33 or newer
+- Electron surface protocols: writes protocol 6; reads protocols 5 and 6
+- Browser partition: exactly `persist:amalgm-browser`
+
+Core and headless imports do not load Electron. The Electron native code is
+available only from `@amalgm/browser/electron`.
+
+## Action identities
+
+Canonical SDK actions are the 22 names in [ACTIONS.md](./ACTIONS.md). MCP uses
+`browser_<action>`. Toolbox uses `browser.<action>` and
+`toolbox__browser_<action>`.
+
+Historical aggregate Browser grants, older prefixed IDs, and individual
+`cua_*` names are normalized in the Toolbox compatibility adapter. They are
+not core action aliases and never create doubled Browser prefixes.
+
+## Engine routes and data
+
+Engine can keep its previous HTTP/IPC route shapes during rolling integration
+by delegating into this SDK. Raw cookie bootstrap and merge must use the
+restricted adapter transport, not public OpenAPI.
+
+Legacy Engine profiles, encrypted auth/cookie-source bundles, cookie
+tombstones, and login sessions are supported by the versioned importer. Paths
+and the Electron partition are reused to avoid forced sign-in.
+
+## Backend differences
+
+Capabilities make differences explicit. Electron advertises visible-surface,
+live-login, and ad-blocking behavior. Headless advertises full-page capture and
+does not claim native Electron ad blocking. Unsupported operations return
+`CAPABILITY_UNSUPPORTED`; adapters must not synthesize a substitute.
+
+## Agent-browser envelopes
+
+The headless adapter accepts supported historical JSON result envelopes and
+normalizes them at its boundary. The SDK result union is stable and does not
+expose agent-browser's transport format.

package/docs/COOKIES.md

@@ -0,0 +1,61 @@
+# Cookies
+
+Browser has three separate security domains:
+
+1. the Amalgm application renderer and account session;
+2. the visible Electron `persist:amalgm-browser` partition;
+3. each headless Chromium profile store.
+
+The application renderer is outside Browser. Electron and headless stores are
+physically isolated and never read one another.
+
+## Logical jar
+
+Cross-backend portability occurs through one encrypted Browser cookie jar.
+Each trusted `BrowserCookieAdapter` reports a normalized snapshot or mutation;
+the coordinator merges records and applies changes back to other adapters.
+
+The record identity includes domain, path, name, and partition key. Merges use
+timestamp then source ID for deterministic last-writer-wins ordering. Deletes
+are durable tombstones, so a stale physical snapshot cannot resurrect a logged
+out cookie. One adapter update cannot replace unrelated records.
+
+Adapter baselines suppress feedback generated while applying jar changes.
+Failed application is retried. Partitioned identity is preserved; an adapter
+that cannot represent partitioned cookies skips them rather than flattening
+them.
+
+## Filtering
+
+The central boundary rejects application/authentication hosts, Amalgm API
+hosts, Supabase hosts, loopback, and configured exclusions. Filtering happens
+before secret persistence or propagation. Automatic synchronization moves
+cookies only; it never copies localStorage or sessionStorage.
+
+## Encryption and failure behavior
+
+The jar uses AES-256-GCM with an integrity tag, atomic replacement, private
+directories, and mode `0600`. The local key is stored separately but on the
+same device. This prevents accidental plaintext exposure; it does not defend
+against an attacker able to read both ciphertext and key.
+
+A missing or corrupt jar reports value-free health metadata and ordinary
+browsing continues with backend-local state. An incorrect key never causes
+cookie values to enter an error.
+
+## Public versus trusted APIs
+
+Ordinary SDK, CLI, MCP, REST, events, and Toolbox projections return only
+sanitized metadata such as domains, names, expiry, partition presence, count,
+and version. Raw values are available only to trusted in-process adapters or
+the separately credentialed loopback internal REST transport.
+
+Named auth bundles are a separate explicit snapshot mechanism. They may carry
+filtered origin storage and do not become the automatic jar.
+
+## Reconciliation lifecycle
+
+Register physical adapters with `browser.cookieAdapters`, then initialize the
+coordinator. The first available physical store may seed an absent logical jar
+exactly once. Thereafter the jar is authoritative. Subscribe to sanitized
+`cookie-jar.changed` events or version tokens rather than secret data.