@amalgm/browser 0.1.0

package/docs/SDK.md

@@ -0,0 +1,101 @@
+# TypeScript SDK
+
+The package is ESM-only and supports Node.js 20 or newer.
+
+```ts
+import { createBrowser, BrowserError } from '@amalgm/browser';
+```
+
+`createBrowser(options)` returns `BrowserProductService`. Defaults include a
+SQLite registry, local artifact store, encrypted cookie/auth files, headless
+driver, event bus, system clock, safe logger, and runtime selector. Injected
+ports can replace registry, drivers, selector, event sink, clock, ID generator,
+logger, authorization, profile directories, artifact store, process launcher,
+cookie jar/coordinator, auth vault, login secret store, and ffmpeg. Native
+ad-block construction separately accepts an injected fetch implementation.
+
+## Sessions and actions
+
+- `createSession({ id?, profileId?, profileKind?, context? })`
+- `getSession(id)` / `listSessions()`
+- `execute(sessionId, BrowserAction, context?)`
+- `cancel(sessionId)`
+- `closeSession(sessionId, context?)`
+- `pruneSessions(maxAgeMs?)`
+
+`BrowserAction` is a discriminated union for `open`, `snapshot`, `screenshot`,
+`click`, `fill`, `press`, `select`, `eval`, `wait`, `cli`, `dialog`, `tab`,
+`console`, `cua`, and `close`. See [ACTIONS.md](./ACTIONS.md). Blocking calls
+take `context.signal`; cancellation propagates to the driver, CDP, encoder, or
+child process.
+
+## Profiles
+
+- `createProfile({ id?, name, kind? })`
+- `listProfiles()` / `getProfile(id)` / `inspectProfile(id)`
+- `updateProfile(id, { name?, kind? })`
+- `deleteProfile(id)` / `pruneProfiles(maxAgeMs?)`
+
+Inspection returns `live`, `referenced`, and physical `locked` status. Delete
+and prune refuse live, referenced, or Chromium-locked profiles.
+
+## Authentication and login
+
+- `browser.auth.list()` / `get(id)` / `delete(id)`
+- `browser.auth.save({ sessionId, name, domains?, context? })`
+- `browser.auth.load({ sessionId, bundleId, context? })`
+- `browser.auth.exportEncrypted(id, portableKey, context?)`
+- `browser.auth.importEncrypted(resource, portableKey, context?)`
+- `browser.login.create(...)` / `list()` / `get(id)`
+- `browser.login.activate(id, token, context?)`
+- `browser.login.input(id, token, cuaOperation, context?)`
+- `browser.login.complete(...)` / `cancel(id, token)`
+
+The token and token-bearing URL exist only in the one-time login creation
+result. Stored login resources contain a hash and ordinary list/get projections
+never return the credential.
+
+## Cookies
+
+`browser.cookies` is the encrypted jar. `browser.cookieAdapters` registers and
+reconciles trusted physical-store adapters. This is an embedding API, not an
+ordinary automation API; raw cookie values must not be projected to users.
+See [COOKIES.md](./COOKIES.md).
+
+## Recordings
+
+- `browser.recordings.start({ sessionId, fps?, name?, context? })`
+- `stop(sessionId)` / `forceStop(sessionId)`
+- `list()` / `get(recordingId)` / `activeRecordings()`
+
+FPS is clamped to 1–30. Artifact placement uses `context.artifactDestination`
+before the standalone fallback.
+
+## Runtime context
+
+`BrowserRuntimeContext` accepts opaque `ownerId`, `callerId`, `clientKind`,
+`projectRef`, `cwdRef`, `artifactDestination`, authorization context, and
+`AbortSignal`. Browser does not discover these from Chat or a workspace
+registry.
+
+## Errors and capabilities
+
+Failures are `BrowserError` values with stable codes such as `INVALID_INPUT`,
+`NOT_FOUND`, `CONFLICT`, `CAPABILITY_UNSUPPORTED`, `AUTHORIZATION_DENIED`,
+`TIMEOUT`, `ABORTED`, `PROCESS_FAILED`, and `SURFACE_IDENTITY_MISMATCH`.
+Inspect `session.capabilities` before optional behavior. Unsupported behavior
+fails explicitly; it is not silently approximated.
+
+## Entry points
+
+- `@amalgm/browser` — service, ports, types, persistence, migration
+- `@amalgm/browser/headless` — headless driver and executable resolution
+- `@amalgm/browser/electron` — Electron-only host and native shell
+- `@amalgm/browser/cookies` — trusted cookie integration
+- `@amalgm/browser/recording` — recording components
+- `@amalgm/browser/toolbox`, `/mcp`, `/http` — adapters
+- `@amalgm/browser/testing` — deterministic test driver
+
+The [custom driver example](../examples/custom-driver.ts) implements the small
+`BrowserDriver` contract for a remote provider. A provider must advertise only
+capabilities it implements and must honor the runtime cancellation signal.

package/docs/TESTING.md

@@ -0,0 +1,57 @@
+# Testing
+
+Tests are organized by invariant rather than implementation file. The default
+suite is deterministic and uses injected drivers/stores; opt-in suites exercise
+real browser processes.
+
+```sh
+npm run check          # tree hygiene and strict TypeScript
+npm test               # unit and transport contracts
+npm run test:real      # real bundled headless Chromium
+npm run test:electron  # real Electron; macOS
+npm run verify         # check, build, test, package/install
+```
+
+## Contract coverage
+
+- immutable backend/profile binding, restart reopen, leases, cancellation
+- all 22 actions reachable through SDK, CLI, MCP, REST, and Toolbox
+- capability honesty and typed errors
+- two-surface identity, ambiguity, loss, and one verified reattach
+- isolated Electron partition and trusted cookie adapter
+- record-level cookie merges, tombstones, stale snapshots, retry, and feedback
+- protected hosts, partition keys, encryption integrity, wrong-key redaction
+- auth filtering, token TTL/hash, live login, portable import/export
+- profile locks, references, deletion refusal, and ephemeral pruning
+- CSS-pixel/DPR capture and page-scoped native input
+- recording viability, latest-frame buffer, backpressure, cancellation, ffmpeg
+- SQLite cross-process writes and encrypted legacy migration fixtures
+- REST auth/limits/SSE and MCP cancellation
+- argv process safety, bounded output/termination, asar resolution
+- native Electron URL/popup/download/permission/ad-block policies
+
+## Real boundaries
+
+The headless suite launches bundled Chromium and ffmpeg. The Electron harness
+launches the actual Electron binary with two `WebContentsView` surfaces and
+checks partition identity, isolation, capture, remount, and WebM recording.
+These tests exist because mocks cannot validate CDP target identity or physical
+partition behavior.
+
+## Package verification
+
+`verify:pack` runs `npm pack`, inspects contents for runtime data/secrets,
+checks the compiled CLI, installs the tarball into a temporary consumer without
+Electron, and imports the ESM core. Build output and temporary tarballs remain
+ignored.
+
+Production TypeScript in `src/` and `bin/` is limited to 220 lines per file.
+The tree check fails on generated-source evasions and tracked build/runtime
+artifacts.
+
+## Adding behavior
+
+Update purpose/axioms if the model changes, then the typed SDK, shared action
+descriptor, every transport projection, documentation, and an invariant test.
+A new action that is not reachable through all five public surfaces must fail
+the parity suite.

package/docs/TOOLBOX_INTEGRATION.md

@@ -0,0 +1,34 @@
+# Toolbox integration
+
+Browser projects into `@amalgm/tools` as one tool:
+
+- tool ID: `browser`
+- action IDs: `browser.<short-action>`
+- MCP names: `toolbox__browser_<short-action>`
+- capability sections: `core`, `computer-use`, `recording`, `auth`
+
+Import `browserToolboxManifest` and `createBrowserToolboxExecutor` from
+`@amalgm/browser/toolbox`. Tools owns registry presentation, enablement,
+loadouts, grants, and picker UI. Browser owns validation and execution.
+
+```ts
+import {
+  browserToolboxManifest,
+  createBrowserToolboxExecutor,
+} from '@amalgm/browser/toolbox';
+
+tools.register(browserToolboxManifest);
+const execute = createBrowserToolboxExecutor(browser, enabledActionIds);
+```
+
+The executor normalizes compatibility aliases once, verifies the action is
+granted, and dispatches the canonical action through the SDK. Disabled actions
+fail before session creation or browser execution.
+
+Legacy individual `cua_*` actions, old prefixed IDs, and historical aggregate
+grants are adapter aliases. They do not create new SDK action identities. In
+particular, never generate `toolbox__browser_browser_<action>`.
+
+The parity contract executes every canonical action through the Toolbox
+executor as well as SDK, CLI, MCP, and REST. Adding an action descriptor without
+a reachable Toolbox projection fails verification.

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,67 @@
+# Troubleshooting
+
+## A session unexpectedly uses headless
+
+Electron selection requires `clientKind: 'desktop'` and a live, loopback,
+protocol-5/6 host advertisement with a running PID. Check the advertisement
+path, CDP URL, protocol, and process. Backend selection cannot be changed after
+session creation; create a new session after fixing the host.
+
+## Surface identity mismatch
+
+Do not retry against an active tab or another target. Confirm the surface
+marker, stamp, ID, and protocol belong to the session. Browser permits one
+reattach only after a genuine target loss; mismatch is intentionally fail
+closed.
+
+## Headless executable is missing
+
+Run `amalgm-browser doctor`, reinstall production dependencies, or set
+`AMALGM_AGENT_BROWSER_BIN`. In packaged Electron builds, ensure native assets
+are unpacked from `app.asar`.
+
+## Recording cannot start
+
+Set `AMALGM_FFMPEG` to a working binary and run `<binary> -version`. Browser
+verifies ffmpeg first, then requires a page frame within five seconds. Open a
+navigable page and check that the assigned driver advertises `recording`.
+
+## A profile cannot be deleted
+
+Inspect it through SDK/CLI/REST. A live session, pending login, auth bundle, or
+Chromium process lock intentionally protects the directory. Close/cancel the
+owner or remove the explicit reference; never delete lock files from a running
+profile.
+
+## Cookie jar reports unhealthy
+
+Ordinary browsing should continue with the physical profile store. Do not print
+or hand-edit encrypted payloads. Restore a matching jar/key backup or clear the
+damaged automatic jar only after accepting that cross-backend cookie state is
+lost. Named auth bundles are separate.
+
+## REST returns 401/403
+
+Health is the only unauthenticated route. Supply the exact bearer token. Raw
+cookie routes additionally require `X-Browser-Adapter-Token`. Non-loopback
+listen also requires explicit remote authorization.
+
+## Login handoff fails
+
+Tokens are one-time credentials returned only at creation, TTL is at most one
+hour, and completed/cancelled/expired sessions reject reuse. For noVNC, set a
+valid HTTP(S) `AMALGM_BROWSER_NOVNC_PUBLIC_URL`.
+
+## SQLite is busy or a session conflicts
+
+Another process may hold the session lease. Do not run two active owners for
+one browser session. Let the operation finish or cancel it through the owning
+service; stale leases expire. Avoid placing the DB on filesystems with broken
+SQLite locking.
+
+## Migration fails
+
+Keep old writers stopped. Verify the legacy DB exists, the source auth blob
+hashes match, and the legacy 32-byte key is available. The importer is
+transactional and does not mark completion on failure; fix the violated
+invariant and rerun rather than editing the migration marker.

package/examples/basic.ts

@@ -0,0 +1,7 @@
+import { createBrowser } from '@amalgm/browser';
+
+const browser = createBrowser();
+const session = await browser.createSession({ id: 'example' });
+await browser.execute(session.id, { type: 'open', url: 'https://example.com' });
+console.log(await browser.execute(session.id, { type: 'snapshot' }));
+await browser.closeSession(session.id);

package/examples/custom-driver.ts

@@ -0,0 +1,45 @@
+import {
+  createBrowser,
+  BrowserError,
+  type BrowserAction,
+  type BrowserActionResult,
+  type BrowserDriver,
+  type BrowserDriverSession,
+} from '@amalgm/browser';
+
+class RemoteBrowserDriver implements BrowserDriver {
+  readonly kind = 'headless' as const;
+  readonly capabilities = ['core', 'computer-use'] as const;
+
+  constructor(readonly endpoint: string, readonly token: string) {}
+
+  async open(input: BrowserDriverSession): Promise<void> {
+    await this.request('/sessions', { session: input.session });
+  }
+
+  async execute(input: BrowserDriverSession, action: BrowserAction): Promise<BrowserActionResult> {
+    return this.request(`/sessions/${encodeURIComponent(input.session.id)}/actions`, { action }, input.context.signal);
+  }
+
+  async close(input: BrowserDriverSession): Promise<void> {
+    await this.request(`/sessions/${encodeURIComponent(input.session.id)}/close`, {});
+  }
+
+  private async request<T>(path: string, body: unknown, signal?: AbortSignal): Promise<T> {
+    const response = await fetch(new URL(path, this.endpoint), {
+      method: 'POST',
+      headers: { authorization: `Bearer ${this.token}`, 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+      ...(signal ? { signal } : {}),
+    });
+    if (!response.ok) throw new BrowserError('PROCESS_FAILED', `Remote driver returned ${response.status}.`);
+    return response.json() as Promise<T>;
+  }
+}
+
+const browser = createBrowser({
+  headlessDriver: new RemoteBrowserDriver('https://browser-provider.example', 'token'),
+});
+
+const session = await browser.createSession({ id: 'remote-example' });
+await browser.execute(session.id, { type: 'open', url: 'https://example.com' });

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@amalgm/browser",
+  "version": "0.1.0",
+  "description": "Safe persistent browser automation across headless Chromium and visible Electron surfaces.",
+  "repository": { "type": "git", "url": "git+https://github.com/amalgm-inc/amalgm-browser.git" },
+  "bugs": { "url": "https://github.com/amalgm-inc/amalgm-browser/issues" },
+  "homepage": "https://github.com/amalgm-inc/amalgm-browser#readme",
+  "license": "UNLICENSED",
+  "type": "module",
+  "private": false,
+  "publishConfig": { "access": "public" },
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/src/index.d.ts", "import": "./dist/src/index.js" },
+    "./headless": { "types": "./dist/src/headless.d.ts", "import": "./dist/src/headless.js" },
+    "./electron": { "types": "./dist/src/electron.d.ts", "import": "./dist/src/electron.js" },
+    "./cookies": { "types": "./dist/src/cookies.d.ts", "import": "./dist/src/cookies.js" },
+    "./recording": { "types": "./dist/src/recording.d.ts", "import": "./dist/src/recording.js" },
+    "./toolbox": { "types": "./dist/src/toolbox.d.ts", "import": "./dist/src/toolbox.js" },
+    "./mcp": { "types": "./dist/src/mcp.d.ts", "import": "./dist/src/mcp.js" },
+    "./http": { "types": "./dist/src/http.d.ts", "import": "./dist/src/http.js" },
+    "./testing": { "types": "./dist/src/testing.d.ts", "import": "./dist/src/testing.js" }
+  },
+  "bin": {
+    "amalgm-browser": "./dist/bin/amalgm-browser.js",
+    "amalgm-browser-mcp": "./dist/bin/amalgm-browser-mcp.js",
+    "amalgm-browser-rest": "./dist/bin/amalgm-browser-rest.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "examples",
+    "skills",
+    "CHANGELOG.md",
+    "LICENSE",
+    "PURPOSE.md",
+    "README.md",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && tsx scripts/mark-executables.ts",
+    "check": "tsx scripts/check-tree.ts && tsc -p tsconfig.json && tsc -p tsconfig.test.json",
+    "test": "tsx --test --test-concurrency=1 --test-timeout=30000 test/*.test.ts",
+    "test:real": "cross-env AMALGM_BROWSER_REAL=1 tsx --test --test-timeout=60000 test/real-headless.test.ts",
+    "pretest:electron": "npm run build",
+    "test:electron": "tsx scripts/run-electron-test.ts",
+    "verify": "npm run check && npm run build && npm test && npm run verify:pack",
+    "verify:pack": "tsx scripts/verify-package.ts",
+    "prepack": "npm run build"
+  },
+  "engines": { "node": ">=20" },
+  "dependencies": {
+    "@amalgm/core": "^0.1.0",
+    "@ghostery/adblocker": "^2.18.1",
+    "agent-browser": "0.26.0",
+    "better-sqlite3": "^12.10.1",
+    "ffmpeg-static": "^5.3.0",
+    "tldts-experimental": "^7.4.9",
+    "ws": "^8.18.3"
+  },
+  "peerDependencies": {
+    "electron": ">=33"
+  },
+  "peerDependenciesMeta": {
+    "electron": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/ffmpeg-static": "^3.0.3",
+    "@types/node": "^20.19.43",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/ws": "^8.18.1",
+    "cross-env": "^7.0.3",
+    "electron": "41.7.1",
+    "tsx": "^4.23.1",
+    "typescript": "^5.9.3"
+  }
+}

package/skills/use-amalgm-browser/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: use-amalgm-browser
+description: Operate web pages through the standalone Amalgm Browser MCP or CLI using persistent sessions, accessibility snapshots, screenshots, browser-scoped computer use, recordings, and human login handoff. Use for web navigation, form interaction, page inspection, visual verification, canvas or image-only controls, authenticated browsing, or browser recordings.
+---
+
+# Use Amalgm Browser
+
+Use Browser as one persistent page session. Let the host select visible Electron
+or headless Chromium; do not ask users to choose a backend during normal work.
+
+## Work in this order
+
+1. Call `browser_open` once with the target URL.
+2. Call `browser_snapshot` to read the page and obtain stable `@eN` references.
+3. Prefer `browser_click`, `browser_fill`, `browser_select`, and `browser_press`
+   with snapshot references.
+4. Re-run `browser_snapshot` after navigation or material page changes.
+5. Use `browser_screenshot` only when pixels matter.
+6. Use `browser_cua` for canvas, WebGL, image-only, or hostile custom controls.
+7. Keep the same `session` value throughout one task. Close it when finished.
+
+Use `text=Visible label` or CSS only when a snapshot reference is unavailable.
+Use `browser_cli` only for an operation absent from the canonical actions.
+
+## Safety and identity
+
+- Treat screenshot and computer-use coordinates as CSS pixels with a 1:1 map.
+- Never try to switch an Electron session onto another visible surface.
+- Let surface verification fail closed; retry once only when Browser reports a
+  genuine surface reconnection.
+- Never request or print raw cookies, tokens, auth payloads, or storage values.
+- Use `browser_auth_link_create` when a human must complete authentication.
+- Use named auth bundles explicitly; do not treat a profile as an auth bundle.
+
+## Specialized operations
+
+- For action inputs and CUA variants, read
+  [references/actions.md](references/actions.md).
+- For recordings, start only after the page is open and stop before closing the
+  session. Report `videoSeconds` and `wallSeconds` by their actual names.
+- For visual verification, use the returned screenshot image rather than
+  inferring appearance from the accessibility snapshot.

package/skills/use-amalgm-browser/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Use Amalgm Browser"
+  short_description: "Browse and operate pages through Amalgm Browser"
+  default_prompt: "Use $use-amalgm-browser to inspect and operate the requested web page safely."

package/skills/use-amalgm-browser/references/actions.md

@@ -0,0 +1,40 @@
+# Browser actions
+
+## Targets
+
+- `@e12`: preferred stable reference from the latest snapshot.
+- `text=Sign in`: visible-text fallback.
+- `#submit` or another CSS selector: structural fallback.
+
+## Computer use
+
+Call `browser_cua` with one `operation`:
+
+```json
+{ "kind": "screenshot" }
+{ "kind": "click", "x": 320, "y": 240, "button": "left" }
+{ "kind": "double_click", "x": 320, "y": 240 }
+{ "kind": "move", "x": 320, "y": 240 }
+{ "kind": "scroll", "scrollY": 600, "scrollX": 0 }
+{ "kind": "type", "text": "hello" }
+{ "kind": "keypress", "keys": ["Control", "a"] }
+{ "kind": "drag", "path": [{ "x": 10, "y": 10 }, { "x": 80, "y": 90 }] }
+```
+
+Normal DOM work should use snapshot refs. Computer use is the fallback for
+interfaces without usable DOM semantics.
+
+## Tabs and dialogs
+
+Use `browser_tab` with `list`, `new`, `switch`, or `close`. Visible Electron
+sessions are bound to one verified surface and may reject switching.
+
+Use `browser_dialog` with `accept` or `dismiss`; add `text` only for prompts.
+
+## Authentication and recording
+
+- `browser_auth_link_create`: mint a human login handoff.
+- `browser_auth_save`: explicitly save named encrypted browser state.
+- `browser_auth_load`: explicitly load a named bundle into a session.
+- `browser_record_start`, `browser_record_stop`, `browser_record_list`: manage
+  page-only WebM recordings.