@amalgm/browser 0.1.2-preview.35541635545 → 0.1.2-preview.37254096068

package/docs/TESTING.md

@@ -1,62 +1,78 @@
 # 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.
+suite is deterministic and uses injected drivers and stores; the real suite
+drives real Chrome.
 
 ```sh
 npm run check          # tree hygiene and strict TypeScript
 npm test               # unit and transport contracts
 npx --no-install agent-browser install # provision Chrome for Testing
-npm run test:real      # real headless Chromium
-npm run test:electron  # real Electron; macOS
+npm run test:real      # real Chrome and agent-browser
 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
-
-Source CI provisions Chrome for Testing through the locked `agent-browser`
-dependency before the headless suite, which launches that real browser and ffmpeg.
-The suite records command phases and the live CDP browser identity; it never logs
-page data, process output, or command arguments. Provisioning and browser action
-deadlines are separate, and the action deadlines remain unchanged. 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.
+- one browsing identity: every session browses as the account, and a root
+  cannot be reassigned to another account
+- restart reopen, cross-process leases, one action per session, cancellation
+- a session's own live view, and closing the runtime releases Chrome
+- all 22 actions reachable through SDK, CLI, MCP, REST, and Toolbox, from one
+  action manifest; an MCP call without a session uses its chat's session
+- two-way cookie sync: sign-ins and sign-outs reach the account, failed
+  applies retry without echo, partitioned cookies, protected hosts
+- record-level merges, tombstones, corrupt-jar health, wrong-key redaction
+- auth filtering, login token TTL and hashing, deprecated-input compatibility,
+  serialized live login transitions
+- recording frame pacing, backpressure, ffmpeg checks, viability deadline,
+  cancellation, and dead-owner recovery
+- SQLite cross-process writes and the encrypted legacy import
+- REST auth, loopback binding, SSE, redaction, and MCP cancellation
+- argv process safety, bounded output and termination, asar resolution
+- Electron URL, popup, permission, download, and ad-block policy, and the
+  Electron cookie adapter against an injected store
+
+## Real browser
+
+`npm run test:real` sets `AMALGM_BROWSER_REAL=1` and drives real Chrome
+through the MCP adapter against a public site. It checks that:
+
+- two chats browse side by side in one Chrome as one signed-in account;
+- a viewer watches and drives one chat's live view, only with the runtime
+  token;
+- the account stays signed in across restarts and follows sign-outs;
+- a chat keeps browsing, still signed in, after Chrome is killed;
+- loopback cookies never enter the account;
+- a competing owner cannot replace or stop the live Chrome;
+- captures and input follow the selected tab even with repeated URLs;
+- session and service shutdown drain work, HTTP requests, SSE and viewers;
+- raw CDP and advanced CLI calls cannot escape their session;
+- repeated login activation preserves the page, terminal states remain final,
+  and recorded imagery can be decoded.
+
+CI provisions Chrome for Testing through the locked `agent-browser`
+dependency before this suite. Mocks cannot validate these paths.
+
+UI's `test:browser` source examination additionally drives its canonical web
+and Electron browser surfaces through the actual UI routes and Shell gateway.
+It covers human input, companion ownership, login handoff, native cookie
+sharing and deletion, account switching, sign-out, and fractional native bounds.
 
 ## 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.
+`verify:pack` runs `npm pack`, checks the tarball for required files and for
+runtime data or secrets, checks the compiled CLIs, installs the tarball into a
+temporary consumer without Electron, imports the core entry points, and
+confirms the Electron entry resolves to its CommonJS build.
 
-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.
+TypeScript in `src/`, `bin/`, and `test/` is limited to 220 lines per file.
+The tree check also fails on empty or untracked source files, JavaScript
+source in `src/` or `bin/`, and tracked build or 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.
+Update the purpose and axioms if the model changes, then the typed SDK, the
+shared action descriptor, every transport projection, the documentation, and
+an invariant test. A new action that is not reachable through all five public
+surfaces fails the parity suite.

package/docs/TOOLBOX_INTEGRATION.md

@@ -18,12 +18,17 @@ import {
 } from '@amalgm/browser/toolbox';
 
 tools.register(browserToolboxManifest);
-const execute = createBrowserToolboxExecutor(browser, enabledActionIds);
+const execute = createBrowserToolboxExecutor(browser, {
+  canExecute: (actionId, context) => enabledActionIds.includes(actionId),
+});
+await execute('browser.open', { url: 'https://example.com' }, context);
 ```
 
-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.
+The executor normalizes compatibility aliases once, asks the optional policy
+whether the action is granted, and dispatches the canonical action through the
+SDK. Disabled actions fail with `AUTHORIZATION_DENIED` before session creation
+or browser execution. Session choice is the same as MCP: an explicit
+`session`, else `context.callerId`, else `default`.
 
 Legacy individual `cua_*` actions, old prefixed IDs, and historical aggregate
 grants are adapter aliases. They do not create new SDK action identities. In

package/docs/TROUBLESHOOTING.md

@@ -1,67 +1,95 @@
 # Troubleshooting
 
-## A session unexpectedly uses headless
+## Chrome was not found
 
-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.
+Install Google Chrome, run `npx agent-browser install` to download Chrome for
+Testing, or set `AMALGM_BROWSER_EXECUTABLE_PATH`. A configured path that does
+not exist fails with `PROCESS_FAILED` and is not replaced by a search. See
+[Chrome runtime](./CHROME.md) for the search order.
 
-## Surface identity mismatch
+## Chrome did not start
 
-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.
+Browser waits 20 seconds for Chrome's DevTools port and reports the end of
+Chrome's stderr. On Linux as root, Browser already adds `--no-sandbox` and
+`--disable-dev-shm-usage`; check the executable runs by hand.
 
-## Headless executable is missing
+## "This browser profile already has a live owner."
+
+Another live process holds this root's Chrome lease (`chrome.lease.sqlite`). This happens
+when a one-shot CLI command runs beside `mcp`, `serve`, or an embedding host on
+the same root. Send the work to that process, stop it, or use another root.
+Never delete the lease file or Chrome's lock files. An owner that has died
+releases its lease automatically; the next start retires its orphaned Chrome
+through the exact endpoint published by that profile.
+
+## Chrome crashed
+
+The runtime logs "Chrome exited; it restarts on next use." An action caught by
+the crash can fail; retry it. A later action starts a new Chrome filled with
+the account's cookies from the jar, and the session keeps browsing. Open pages
+are not restored.
+
+## SURFACE_IDENTITY_FAILED
+
+Screenshots, CUA double-clicks, and recording need one page for the session.
+Browser records the selected page's target identity through the session relay.
+Repeated URLs are safe. If the target has disappeared or selection cannot be
+proven, switch to the intended tab or open a page, then retry.
+
+## An element reference fails
+
+Refs such as `@e3` belong to the latest snapshot. After the page changes, an
+old ref fails with `PROCESS_FAILED`. Take a new snapshot.
+
+## agent-browser 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`.
+`AMALGM_AGENT_BROWSER_BIN`. In packaged Electron builds, make sure native
+assets are unpacked from `app.asar`.
 
-## Recording cannot start
+## "Browser IPC requires a private, user-owned temporary directory"
 
-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`.
+agent-browser's sockets live in `/tmp/amalgm-browser-<uid>`. It must be a
+directory owned by the current user with no group or other permissions. Fix or
+remove it.
 
-## A profile cannot be deleted
+## Recording cannot start
 
-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.
+Set `AMALGM_FFMPEG` to a working binary and run `<binary> -version`. Browser
+checks ffmpeg first, then needs a page frame within five seconds, so open a
+page before recording.
 
 ## 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.
+Browsing continues with the cookies Chrome already has, but sign-ins no longer
+sync with other browser stores. Do not print or hand-edit encrypted files. Restore a
+matching `cookie-jar.sqlite` and `browser.key` backup while the runtime is stopped,
+using the SQLite-safe backup procedure in [Operations](./OPERATIONS.md).
+Named auth bundles are separate.
 
-## REST returns 401/403
+## REST returns 401 or 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.
+Health is the only unauthenticated route. Send the exact runtime token.
+Internal cookie routes also need `X-Browser-Adapter-Token`. A live-view
+WebSocket closing with `4401` is the same token failure. Non-loopback binding
+requires explicit remote opt-in.
 
 ## 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`.
+hour, and completed, cancelled, and expired logins reject reuse. The login page
+uses the login session’s normal runtime stream; check that the selected runtime
+is available.
 
 ## 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.
+Each session allows one action at a time, and another process may hold the
+session's lease. Let the operation finish or cancel it through the owning
+process; stale leases expire. Avoid 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.
+Keep old writers stopped. Check that the legacy database 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 problem and
+rerun rather than editing the migration marker.

package/examples/basic.ts

@@ -5,3 +5,4 @@ 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);
+await browser.close();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@amalgm/browser",
-  "version": "0.1.2-preview.35541635545",
-  "description": "Safe persistent browser automation across headless Chromium and visible Electron surfaces.",
+  "version": "0.1.2-preview.37254096068",
+  "description": "The amalgm runtime's browser: one Chrome, a session per chat, and the account's cookies in every view.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/amalgm-inc/amalgm-browser.git"
@@ -23,10 +23,6 @@
       "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js"
     },
-    "./headless": {
-      "types": "./dist/src/headless.d.ts",
-      "import": "./dist/src/headless.js"
-    },
     "./electron": {
       "import": {
         "types": "./dist/src/electron.d.ts",
@@ -80,12 +76,10 @@
   ],
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && npm run build:electron-cjs && tsx scripts/finalize-build.ts",
-    "build:electron-cjs": "esbuild src/electron.ts --bundle --platform=node --format=cjs --target=node20 --define:import.meta.dirname=__dirname --define:__AMALGM_BROWSER_ADBLOCK_PRELOAD__=\\\"electron-preload.cjs\\\" --outfile=dist/src/electron.cjs --external:electron && esbuild src/drivers/electron/native/adblock/preload.ts --bundle --platform=node --format=cjs --target=node20 --outfile=dist/src/electron-preload.cjs --external:electron",
+    "build:electron-cjs": "esbuild src/electron.ts --bundle --platform=node --format=cjs --target=node20 --define:import.meta.dirname=__dirname --define:__AMALGM_BROWSER_ADBLOCK_PRELOAD__=\\\"electron-preload.cjs\\\" --outfile=dist/src/electron.cjs --external:electron && esbuild src/electron/adblock/preload.ts --bundle --platform=node --format=cjs --target=node20 --outfile=dist/src/electron-preload.cjs --external:electron",
     "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",
+    "test:real": "cross-env AMALGM_BROWSER_REAL=1 tsx --test --test-concurrency=1 --test-timeout=120000 test/real-*.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",
@@ -132,8 +126,7 @@
     "workflow": "verify.yml",
     "jobs": [
       "verify",
-      "real-headless",
-      "real-electron"
+      "real-browser"
     ],
     "verify": "verify",
     "cli": [
@@ -157,11 +150,11 @@
       "@amalgm/core"
     ]
   },
-  "gitHead": "f3c17f14ffd07ac7e89f57698f611b07db17545a",
+  "gitHead": "9a5d40729134e87c55fdbb7a52ad42711eef7163",
   "amalgmSource": {
     "repository": "amalgm-inc/amalgm-browser",
     "branch": "preview",
-    "commit": "f3c17f14ffd07ac7e89f57698f611b07db17545a",
-    "occurrence": "35541635545"
+    "commit": "9a5d40729134e87c55fdbb7a52ad42711eef7163",
+    "occurrence": "37254096068"
   }
 }

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

@@ -22,7 +22,7 @@ The package installs three executables alongside the SDK:
 - `amalgm-browser-mcp` — the MCP server (also reachable as `amalgm-browser mcp`).
 - `amalgm-browser-rest` — the authenticated loopback REST API (also `amalgm-browser serve --token <token>`).
 
-The `agent-browser` dependency supplies the launcher; its `install` command downloads Chrome for Testing. An existing Chrome installation can also supply the standalone headless browser. Setting `AMALGM_BROWSER_CDP_URL` attaches to a Chromium endpoint you already run instead.
+Browser runs one headless Chrome per runtime and drives it through the bundled `agent-browser`. It uses an installed Chrome, Chromium, or Brave, or the Chrome for Testing that `agent-browser install` downloads; `AMALGM_BROWSER_EXECUTABLE_PATH` picks a specific executable.
 
 ### MCP setup
 
@@ -59,26 +59,18 @@ const snapshot = await browser.execute(session.id, { type: 'snapshot' });
 await browser.execute(session.id, { type: 'click', target: '@e3' });
 
 await browser.closeSession(session.id);
+await browser.close(); // stops Chrome
 ```
 
-The same flow on the CLI — note that every invocation reuses one `--session` value:
+Through MCP the identical sequence is `browser_open`, `browser_snapshot`, `browser_click`, `browser_close`, each taking an optional `session` field. Without it, a call uses the calling chat's session when the host names the chat, and `default` otherwise.
 
-```bash
-amalgm-browser open https://example.com --session research
-amalgm-browser snapshot --session research
-amalgm-browser click @e3 --session research
-amalgm-browser close --session research
-```
-
-Through MCP the identical sequence is `browser_open`, `browser_snapshot`, `browser_click`, `browser_close`, each taking an optional `session` field (defaulting to `default`).
+Each CLI command is its own process: it starts Chrome, runs one step, and stops Chrome, so the next command starts on a new blank tab. Use the CLI for single steps such as `amalgm-browser open https://example.com`, and MCP, REST (`amalgm-browser serve`), or the SDK for multi-step flows.
 
 ## Core concepts
 
 ### Sessions
 
-A session is a persistent page context: one live browser state that survives across commands. Create it once at the start of a task, pass the same session id to every subsequent action, and close it when the task ends. Sessions are cheap to keep open and expensive to churn — reopening a page resets navigation state, cookies-in-flight, and every element reference you have collected.
-
-Backend selection (headless Chromium, an operator-supplied CDP endpoint, or a visible desktop surface when Browser is embedded in a host app) happens once, before session creation, and never changes during a session's lifetime. You do not choose a backend per command and should not ask users to.
+A session is a persistent page context: its own tabs in the runtime's one Chrome. Every session browses as the same signed-in account and shares its cookies, so a sign-in in one session is visible in all of them. Create or name a session once at the start of a task, pass the same session id to every subsequent action, and close it when the task ends. Sessions are cheap to keep open and expensive to churn — reopening a page resets navigation state and every element reference you have collected.
 
 ### Tabs
 
@@ -100,8 +92,8 @@ Browser actions are individual commands over one shared session, and the orderin
 1. Call `open` once per page, not once per command. The session holds the page.
 2. Call `snapshot` to get refs, then act with those refs. Do not re-issue `tab` or `open` before each action — that resets the page context and every `@ref` you hold goes stale.
 3. Re-snapshot only when the page has actually changed: after navigation, after a tab switch, after a click that triggered new content.
-4. When a multi-step sequence fails, classify the failure by the specific command that failed, not by the sequence as a whole. Every action returns a typed error with a stable code (see [Error handling](#error-handling)); a `NOT_FOUND` on step four means a stale ref or changed page at step four, not a broken session. Usually the fix is a fresh `snapshot` and a retry of that one step.
-5. Keep one owner per session. Two processes driving the same session id conflict; the second gets a lease conflict rather than silently interleaving.
+4. When a multi-step sequence fails, classify the failure by the specific command that failed, not by the sequence as a whole. Every action returns a typed error with a stable code (see [Error handling](#error-handling)); a stale ref at step four fails step four with `PROCESS_FAILED`, not the session. Usually the fix is a fresh `snapshot` and a retry of that one step.
+5. Keep one owner per session. A session runs one action at a time, and two processes driving the same session id get `CONFLICT` rather than silently interleaving. Only one process can run a state root's Chrome; another process on the same root gets `CONFLICT` ("This browser profile already has a live owner.").
 
 ## Reading pages: snapshots vs screenshots
 
@@ -117,12 +109,10 @@ Screenshot and computer-use coordinates are CSS pixels with a 1:1 mapping betwee
 
 ## Forms and input
 
-The core input actions cover ordinary DOM forms:
+The core input actions cover ordinary DOM forms. A `fill` input:
 
-```bash
-amalgm-browser fill @e7 "jane@example.com" --session research
-amalgm-browser select @e9 "US" --session research
-amalgm-browser press Enter --session research
+```json
+{ "target": "@e7", "text": "jane@example.com", "submit": true }
 ```
 
 - `fill` sets a target's text; pass `submit: true` to submit the surrounding form in the same action.
@@ -151,7 +141,7 @@ When a task needs a human to log in, let the host provide the login interface. `
 
 ## MCP tools
 
-The MCP server exposes twenty-two tools — the canonical action names prefixed with `browser_`. Session actions accept an optional `session` string and default to `default`. `browser_record_list` and `browser_auth_list` list service-wide metadata, while `browser_auth_link_create` creates a separate login session; these three tools do not accept `session`.
+The MCP server exposes twenty-two tools — the canonical action names prefixed with `browser_`. Session actions accept an optional `session` string; without it they use the calling chat's session when the host names the chat, and `default` otherwise. `browser_record_list` and `browser_auth_list` list service-wide metadata, while `browser_auth_link_create` creates a separate login session; these three tools do not accept `session`.
 
 | Group | Tools |
 | --- | --- |
@@ -164,7 +154,7 @@ The MCP server exposes twenty-two tools — the canonical action names prefixed
 
 `browser_cli` is the escape hatch: it runs an advanced `agent-browser` argv action for operations outside the canonical set. Prefer the named tools whenever one exists.
 
-The CLI provides direct commands for the fifteen core browsing and computer-use actions, such as `amalgm-browser open` and `amalgm-browser snapshot`. Use `amalgm-browser action <name> --input <json>` for any of the twenty-two product actions, including authentication and recording, or use the resource commands (`sessions`, `profiles`, `auth`, `recordings`, `capabilities`, `doctor`).
+The CLI provides direct commands for the fifteen core browsing and computer-use actions, such as `amalgm-browser open` and `amalgm-browser snapshot`. Use `amalgm-browser action <name> --input <json>` for any of the twenty-two product actions, including authentication and recording, or use the resource commands (`sessions`, `auth`, `recordings`, `doctor`).
 
 ## Error handling
 
@@ -173,15 +163,12 @@ Failures are typed `BrowserError` values with stable codes:
 | Code | Meaning |
 | --- | --- |
 | `INVALID_INPUT` | Malformed action input; fix the call, do not retry as-is. |
-| `NOT_FOUND` | Target, session, or resource does not exist — often a stale `@ref`; re-snapshot. |
-| `CONFLICT` | Another owner holds the session or resource. |
-| `CAPABILITY_UNSUPPORTED` | The active backend does not implement this action group; nothing is silently approximated. |
+| `NOT_FOUND` | The session, bundle, recording, or login does not exist. |
+| `CONFLICT` | The session is busy or owned by another process, or another process runs this root's Chrome. |
 | `AUTHORIZATION_DENIED` | The caller is not permitted to perform the action. |
 | `TIMEOUT` / `ABORTED` | The operation ran out of time or was cancelled. |
-| `PROCESS_FAILED` | The underlying browser process failed. |
-| `SURFACE_IDENTITY_FAILED` | A visible desktop surface no longer matches the session; this fails closed. Retry once only after a genuine reconnection, never against a different surface. |
-
-Check `session.capabilities` before relying on optional groups (computer use, recording, auth, full-page capture) — a backend that lacks a capability refuses it explicitly rather than faking it.
+| `PROCESS_FAILED` | agent-browser, Chrome, or ffmpeg failed — including a stale `@ref` or missing target; re-snapshot and retry that step. |
+| `SURFACE_IDENTITY_FAILED` | A screenshot, computer-use double-click, or recording could not tell which of the session's tabs is its page; this fails closed. Switch to or close tabs, then retry. |
 
 CLI exit codes map the same taxonomy: `0` success, `2` invalid input, `3` authorization denied, `4` not found, `5` timeout or cancellation, `1` any other typed failure. Pass `--timeout <ms>` to bound any blocking CLI operation.
 

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

@@ -31,7 +31,7 @@ Use computer use for canvas, WebGL, image-only, or custom controls without DOM s
 
 ## Tabs and dialogs
 
-`tab` takes `action: "list" | "new" | "switch" | "close"`, with `id` identifying the tab for `switch` and `close`. Switching tabs invalidates snapshot refs; re-snapshot after switching. Sessions bound to a visible desktop surface may reject switching to a surface they do not own.
+`tab` takes `action: "list" | "new" | "switch" | "close"`, with `id` identifying the tab for `switch` and `close`. Switching tabs invalidates snapshot refs; re-snapshot after switching.
 
 `dialog` takes `action: "accept" | "dismiss"`, with optional `text` supplied only for prompt dialogs.
 
@@ -46,7 +46,7 @@ Use computer use for canvas, WebGL, image-only, or custom controls without DOM s
 - `auth_load` — load a bundle into the session by `bundleId`.
 - `auth_list` — list sanitized profiles, bundles, and login sessions. Never returns raw cookie or token values.
 
-A profile is a browser state directory; an auth bundle is an explicitly saved, named credential snapshot. They are separate — loading a profile does not load a bundle.
+Every session browses as the signed-in amalgm account, so it already carries that account's cookies. An auth bundle is an explicitly saved, named credential snapshot; loading one adds its state to the session.
 
 ## Recording
 

package/dist/src/adapters/http/profile-routes.d.ts

@@ -1,2 +0,0 @@
-import type { RouteContext } from './types.js';
-export declare function routeProfiles(context: RouteContext): Promise<boolean>;

package/dist/src/adapters/http/profile-routes.js

@@ -1,42 +0,0 @@
-export async function routeProfiles(context) {
-    const [resource, id] = context.path;
-    if (resource !== 'profiles')
-        return false;
-    if (!id && context.method === 'GET') {
-        context.json(200, { profiles: context.browser.listProfiles() });
-        return true;
-    }
-    if (!id && context.method === 'POST') {
-        const body = await context.body();
-        context.json(201, { profile: context.browser.createProfile({
-                ...(typeof body.id === 'string' ? { id: body.id } : {}),
-                name: typeof body.name === 'string' ? body.name : String(body.id || 'profile'),
-                kind: 'durable',
-            }) });
-        return true;
-    }
-    if (id === 'prune' && context.method === 'POST') {
-        const body = await context.body();
-        context.json(200, { removed: context.browser.pruneProfiles(Number(body.maxAgeMs) || undefined) });
-        return true;
-    }
-    if (id && context.method === 'GET') {
-        context.json(200, { status: context.browser.inspectProfile(id) });
-        return true;
-    }
-    if (id && context.method === 'PATCH') {
-        const body = await context.body();
-        context.json(200, { profile: context.browser.updateProfile(id, {
-                ...(typeof body.name === 'string' ? { name: body.name } : {}),
-                ...(body.kind === 'durable' || body.kind === 'ephemeral' ? { kind: body.kind } : {}),
-            }) });
-        return true;
-    }
-    if (id && context.method === 'DELETE') {
-        context.browser.deleteProfile(id);
-        context.json(200, { deleted: id });
-        return true;
-    }
-    return false;
-}
-//# sourceMappingURL=profile-routes.js.map

package/dist/src/adapters/http/profile-routes.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"profile-routes.js","sourceRoot":"","sources":["../../../../src/adapters/http/profile-routes.ts"],"names":[],"mappings":"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"}

package/dist/src/auth/transport.d.ts

@@ -1,8 +0,0 @@
-import type { BrowserLoginSession, BrowserRuntimeContext } from '../types.js';
-export interface LoginTransportInput {
-    transport?: string;
-    liveUrl?: string;
-    context?: BrowserRuntimeContext;
-}
-export declare function resolveLoginTransport(input: LoginTransportInput, env?: NodeJS.ProcessEnv): Pick<BrowserLoginSession, 'transport' | 'liveUrl' | 'setupStatus'>;
-export declare function noVncUrl(value: string | undefined): string | undefined;

package/dist/src/auth/transport.js

@@ -1,45 +0,0 @@
-export function resolveLoginTransport(input, env = process.env) {
-    const requested = normalizeTransport(input.transport || env.AMALGM_BROWSER_LOGIN_TRANSPORT);
-    const liveUrl = noVncUrl(input.liveUrl || env.AMALGM_BROWSER_NOVNC_PUBLIC_URL || env.AMALGM_BROWSER_NOVNC_URL);
-    if (requested === 'electron-surface' || (!requested && input.context?.clientKind === 'desktop')) {
-        return { transport: 'electron-surface', setupStatus: 'ready' };
-    }
-    if (requested === 'novnc' || liveUrl) {
-        return {
-            transport: 'novnc',
-            ...(liveUrl ? { liveUrl } : {}),
-            setupStatus: liveUrl ? 'ready' : 'missing_novnc_url',
-        };
-    }
-    return { transport: 'external', setupStatus: requested === 'manual' ? 'manual' : 'ready' };
-}
-export function noVncUrl(value) {
-    if (!value)
-        return undefined;
-    try {
-        const url = new URL(value);
-        if (!['http:', 'https:'].includes(url.protocol))
-            return undefined;
-        if (!url.searchParams.has('autoconnect'))
-            url.searchParams.set('autoconnect', '1');
-        if (!url.searchParams.has('resize'))
-            url.searchParams.set('resize', 'scale');
-        return url.toString();
-    }
-    catch {
-        return undefined;
-    }
-}
-function normalizeTransport(value) {
-    const clean = String(value || '').trim().toLowerCase();
-    if (['electron', 'electron-splitview', 'desktop', 'electron-surface'].includes(clean))
-        return 'electron-surface';
-    if (['novnc', 'vnc', 'remote', 'remote-live-view'].includes(clean))
-        return 'novnc';
-    if (['none', 'manual'].includes(clean))
-        return 'manual';
-    if (['external', 'amalgm-live', 'live', 'browser-auth-live', 'cdp-live'].includes(clean))
-        return 'external';
-    return undefined;
-}
-//# sourceMappingURL=transport.js.map

package/dist/src/auth/transport.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../../src/auth/transport.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,qBAAqB,CACnC,KAA0B,EAC1B,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,SAAS,GAAG,kBAAkB,CAAC,KAAK,CAAC,SAAS,IAAI,GAAG,CAAC,8BAA8B,CAAC,CAAC;IAC5F,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,IAAI,GAAG,CAAC,+BAA+B,IAAI,GAAG,CAAC,wBAAwB,CAAC,CAAC;IAC/G,IAAI,SAAS,KAAK,kBAAkB,IAAI,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC,OAAO,EAAE,UAAU,KAAK,SAAS,CAAC,EAAE,CAAC;QAChG,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;IACjE,CAAC;IACD,IAAI,SAAS,KAAK,OAAO,IAAI,OAAO,EAAE,CAAC;QACrC,OAAO;YACL,SAAS,EAAE,OAAO;YAClB,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/B,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,mBAAmB;SACrD,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;AAC7F,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAyB;IAChD,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC3B,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,OAAO,SAAS,CAAC;QAClE,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,aAAa,CAAC;YAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;QACnF,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC7E,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,SAAS,CAAC;IAAC,CAAC;AAC/B,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAyB;IACnD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACvD,IAAI,CAAC,UAAU,EAAE,oBAAoB,EAAE,SAAS,EAAE,kBAAkB,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,kBAAkB,CAAC;IACjH,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,kBAAkB,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IACnF,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACxD,IAAI,CAAC,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,mBAAmB,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC;IAC5G,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/src/drivers/cdp/capture.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"capture.js","sourceRoot":"","sources":["../../../../src/drivers/cdp/capture.ts"],"names":[],"mappings":"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"}