aether-browser 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,124 @@
+# aether-browser
+
+Client and CLI for **[Agent Browser](https://github.com/AetherAI3/agent-browser) by Aether AI** —
+self-hosted Chrome for AI agents. Drive one browser session through a closed HTTP API, and watch or
+take over that exact same session through noVNC.
+
+```bash
+npm install aether-browser
+```
+
+Zero runtime dependencies. Ships TypeScript types. Node 18+.
+
+## Drive a session
+
+`withSession` always attempts to end the session, including when your callback throws, so a crash
+cannot leave the single session slot occupied.
+
+```ts
+import { AgentBrowser, withSession } from 'aether-browser'
+
+const browser = new AgentBrowser({
+  baseUrl: 'http://127.0.0.1:8092',
+  controllerToken: process.env.AGENT_BROWSER_CONTROLLER_TOKEN,
+})
+
+await withSession(browser, async (session) => {
+  console.log('watch it live at', session.viewUrl)
+
+  const page = await session.navigate('https://example.com')
+  console.log(page.title, page.readable_text.slice(0, 200))
+
+  await session.click({ selector: '#login' })
+  await session.type({ selector: '#user', text: 'ada' })
+  await session.press('Enter')
+
+  const shot = await session.snapshot()
+  console.log(`${shot.vision_steps_remaining} vision steps left`)
+})
+```
+
+Connection settings fall back to `AGENT_BROWSER_URL`, `AGENT_BROWSER_CONTROLLER_TOKEN`, and
+`AGENT_BROWSER_OBSERVER_TOKEN`, so `new AgentBrowser()` works with no arguments in a configured
+environment.
+
+## Two roles, kept separate
+
+The server splits authority, and this client keeps that split visible in your code. The observer
+token covers health and snapshot; the controller token is required to create, navigate, interact,
+and end. Give a read-only caller only the observer token:
+
+```ts
+const readOnly = new AgentBrowser({ observerToken: process.env.AGENT_BROWSER_OBSERVER_TOKEN })
+await readOnly.health()
+```
+
+## Errors
+
+Failures raise `AgentBrowserError` carrying the server's stable `code`:
+
+```ts
+import { AgentBrowserError } from 'aether-browser'
+
+try {
+  await browser.createSession()
+} catch (error) {
+  if (error instanceof AgentBrowserError && error.isCapacityReached) {
+    console.log(`busy; retry in ${error.retryAfterSeconds}s`)
+  }
+}
+```
+
+Codes are `AUTH_REQUIRED`, `AUTH_FORBIDDEN`, `SESSION_CAPACITY_REACHED`, `SESSION_NOT_FOUND`,
+`SESSION_EXPIRED`, `VISION_BUDGET_EXHAUSTED`, `INVALID_URL`, `DESTINATION_BLOCKED`,
+`INVALID_INTERACTION`, `BROWSER_NOT_READY`, and `INTERNAL_ERROR`. A transport failure raises the
+same class with `code` left `undefined`, so a refused connection is never mistaken for a refusal
+by the server.
+
+## CLI
+
+```bash
+npx aether-browser doctor   # check Docker, platform, and server health; say what is wrong
+npx aether-browser up       # build and start the runtime
+npx aether-browser status   # print the health document
+npx aether-browser open     # open the live noVNC view
+npx aether-browser down     # stop and clean up
+```
+
+Run `doctor` first. It checks the things that actually break a first run and tells you which one
+failed, instead of leaving you to read a build log.
+
+### What `up` really does, and its limits
+
+Agent Browser publishes **no Chrome-containing image** — distribution is source-only. So `up` builds
+the image locally from source, and **the first build takes several minutes** because it installs a
+hash-locked Python environment and the current Google Chrome Stable package. It uses the checkout
+you are standing in if there is one, and otherwise downloads the matching tagged source tarball from
+the official repository over HTTPS into your cache directory.
+
+`up` requires **Linux** with Docker Compose v2. The documented quickstart uses Docker host
+networking so both the API and the noVNC listeners stay bound to numeric loopback; Docker Desktop on
+macOS and Windows is outside that contract, and `doctor` will tell you so rather than half-working.
+
+**The library has no such limit.** It is plain HTTP and runs anywhere Node does — point it at a
+server on a Linux host and drive it from macOS, Windows, or CI.
+
+## Security
+
+The v0.1 noVNC surface is **unauthenticated** and intended for numeric loopback on a machine you
+control. Treat every process and user that can reach that loopback interface as trusted with the
+live browser view. Do not expose it through a tunnel, reverse proxy, or container bridge. See the
+[security model](https://github.com/AetherAI3/agent-browser/blob/main/docs/SECURITY-MODEL.md).
+
+The API is deliberately closed: `click`, `type`, `scroll`, and `press` are the only interactions,
+and there is no arbitrary JavaScript, CDP, upload, clipboard, download, extension, shell,
+filesystem, credential, or cookie field. This client cannot widen that surface, because the server
+rejects unknown fields.
+
+## Status
+
+`0.1.0-rc.1` tracks Agent Browser `v0.1.0-rc.1` and its `api_version: "v1"` contract. This is a
+release candidate: the API may change before `v0.1.0`. Issues and design discussion are welcome on
+[the repository](https://github.com/AetherAI3/agent-browser/issues).
+
+Apache-2.0 · [Aether AI](https://github.com/AetherAI3)

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "aether-browser",
+  "version": "0.1.0-rc.1",
+  "description": "Client and CLI for Agent Browser by Aether AI: drive one self-hosted Chrome session over a closed HTTP API and watch or take over that same session through noVNC.",
+  "license": "Apache-2.0",
+  "author": "Aether AI",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "aether-browser": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AetherAI3/agent-browser.git",
+    "directory": "clients/node"
+  },
+  "homepage": "https://github.com/AetherAI3/agent-browser#readme",
+  "bugs": {
+    "url": "https://github.com/AetherAI3/agent-browser/issues"
+  },
+  "keywords": [
+    "agent-browser",
+    "browser",
+    "automation",
+    "ai-agents",
+    "chrome",
+    "novnc",
+    "self-hosted",
+    "human-in-the-loop",
+    "computer-use"
+  ],
+  "scripts": {
+    "test": "node --test test/client.test.js",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/src/cli.js

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+/**
+ * aether-browser CLI.
+ *
+ * The runtime is a container you build from source: Agent Browser publishes no
+ * Chrome-containing image, so `up` builds one locally the first time and that build
+ * takes several minutes. This CLI never pretends otherwise.
+ */
+
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { homedir, platform } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { AgentBrowser, AgentBrowserError, DEFAULT_BASE_URL } from './index.js'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const PKG = JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf8'))
+const REPO = 'https://github.com/AetherAI3/agent-browser'
+const NOVNC_URL = 'http://127.0.0.1:6080/vnc.html'
+
+const styles = { on: process.stdout.isTTY && !process.env.NO_COLOR }
+const dim = (s) => (styles.on ? `\u001b[2m${s}\u001b[0m` : s)
+const bold = (s) => (styles.on ? `\u001b[1m${s}\u001b[0m` : s)
+const red = (s) => (styles.on ? `\u001b[31m${s}\u001b[0m` : s)
+const green = (s) => (styles.on ? `\u001b[32m${s}\u001b[0m` : s)
+const yellow = (s) => (styles.on ? `\u001b[33m${s}\u001b[0m` : s)
+
+const ok = (s) => console.log(`  ${green('ok')}    ${s}`)
+const warn = (s) => console.log(`  ${yellow('warn')}  ${s}`)
+const bad = (s) => console.log(`  ${red('fail')}  ${s}`)
+
+function run(cmd, args, options = {}) {
+  return spawnSync(cmd, args, { encoding: 'utf8', ...options })
+}
+
+function has(cmd) {
+  const probe = run(cmd, ['--version'])
+  return probe.status === 0 ? (probe.stdout || probe.stderr).trim().split('\n')[0] : undefined
+}
+
+function composeCommand() {
+  const v2 = run('docker', ['compose', 'version'])
+  if (v2.status === 0) return { cmd: 'docker', args: ['compose'], version: v2.stdout.trim() }
+  return undefined
+}
+
+/** Locate a checkout: the current tree if it is one, otherwise the cached release tarball. */
+function findComposeDir({ allowDownload }) {
+  let dir = process.cwd()
+  for (let depth = 0; depth < 6; depth++) {
+    if (existsSync(join(dir, 'docker-compose.yml')) && existsSync(join(dir, 'Dockerfile'))) {
+      return { dir, source: 'local checkout' }
+    }
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  if (!allowDownload) return undefined
+
+  const version = PKG.version
+  const cacheRoot = join(process.env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'aether-browser')
+  const target = join(cacheRoot, `agent-browser-${version}`)
+  if (existsSync(join(target, 'docker-compose.yml'))) {
+    return { dir: target, source: `cached source ${dim(target)}` }
+  }
+
+  const url = `${REPO}/archive/refs/tags/v${version}.tar.gz`
+  console.log(`  fetching source  ${dim(url)}`)
+  mkdirSync(target, { recursive: true })
+  const tarball = join(cacheRoot, `v${version}.tar.gz`)
+  const curl = run('curl', ['-fsSL', '--proto', '=https', '--tlsv1.2', '-o', tarball, url], {
+    stdio: 'inherit',
+  })
+  if (curl.status !== 0) {
+    rmSync(target, { recursive: true, force: true })
+    return undefined
+  }
+  const untar = run('tar', ['-xzf', tarball, '-C', target, '--strip-components=1'], {
+    stdio: 'inherit',
+  })
+  rmSync(tarball, { force: true })
+  if (untar.status !== 0) {
+    rmSync(target, { recursive: true, force: true })
+    return undefined
+  }
+  return { dir: target, source: `downloaded source ${dim(target)}` }
+}
+
+function preflight({ forUp }) {
+  const problems = []
+
+  console.log(bold('\nEnvironment'))
+  console.log(`  node    ${process.version}`)
+  console.log(`  client  aether-browser ${PKG.version}`)
+  console.log(`  os      ${platform()}`)
+
+  console.log(bold('\nRuntime prerequisites'))
+  if (platform() === 'linux') {
+    ok('Linux host')
+  } else {
+    bad(
+      `the documented quickstart is Linux only (found ${platform()}). It relies on Docker host ` +
+        `networking so both listeners stay on numeric loopback; Docker Desktop is outside that contract.`,
+    )
+    problems.push(
+      'Run the container on a Linux host. The client library itself works on any platform ' +
+        'against a server you can reach.',
+    )
+  }
+
+  const docker = has('docker')
+  if (docker) ok(docker)
+  else {
+    bad('docker not found on PATH')
+    problems.push('Install Docker Engine: https://docs.docker.com/engine/install/')
+  }
+
+  const compose = docker ? composeCommand() : undefined
+  if (compose) ok(compose.version)
+  else if (docker) {
+    bad('docker compose v2 not available')
+    problems.push('Install the Docker Compose v2 plugin.')
+  }
+
+  if (docker) {
+    const info = run('docker', ['info', '--format', '{{.ServerVersion}}'])
+    if (info.status === 0) ok(`docker daemon reachable (server ${info.stdout.trim()})`)
+    else {
+      bad('docker daemon is not reachable')
+      problems.push('Start Docker, or add your user to the docker group and re-login.')
+    }
+  }
+
+  if (forUp) {
+    console.log(bold('\nSource'))
+    const found = findComposeDir({ allowDownload: false })
+    if (found) ok(`docker-compose.yml found in ${found.source} ${dim(found.dir)}`)
+    else warn(`no checkout here; \`up\` will download ${REPO} at v${PKG.version}`)
+  }
+
+  return problems
+}
+
+async function probeHealth(baseUrl) {
+  const browser = new AgentBrowser({ baseUrl, timeoutMs: 4000 })
+  try {
+    return { health: await browser.health() }
+  } catch (error) {
+    return { error }
+  }
+}
+
+async function cmdDoctor() {
+  const problems = preflight({ forUp: true })
+
+  console.log(bold('\nServer'))
+  const baseUrl = process.env.AGENT_BROWSER_URL || DEFAULT_BASE_URL
+  const { health, error } = await probeHealth(baseUrl)
+  if (health) {
+    ok(`${baseUrl} responding (version ${health.version})`)
+    console.log(
+      `        browser_ready=${health.browser_ready} session_active=${health.session_active} ` +
+        `slots_available=${health.slots_available}`,
+    )
+  } else {
+    warn(`${baseUrl} not responding yet ${dim(`(${error?.message ?? 'unknown'})`)}`)
+    console.log(`        start it with ${bold('npx aether-browser up')}`)
+  }
+
+  console.log(bold('\nTokens'))
+  if (process.env.AGENT_BROWSER_CONTROLLER_TOKEN) ok('AGENT_BROWSER_CONTROLLER_TOKEN is set')
+  else warn('AGENT_BROWSER_CONTROLLER_TOKEN unset (fine for strict loopback local mode)')
+
+  if (problems.length) {
+    console.log(bold(red('\nBlocking problems')))
+    for (const problem of problems) console.log(`  - ${problem}`)
+    console.log()
+    return 1
+  }
+  console.log(green('\nReady.\n'))
+  return 0
+}
+
+function cmdUp(argv) {
+  const problems = preflight({ forUp: false })
+  if (problems.length) {
+    console.log(bold(red('\nCannot start')))
+    for (const problem of problems) console.log(`  - ${problem}`)
+    console.log()
+    return 1
+  }
+
+  console.log(bold('\nSource'))
+  const found = findComposeDir({ allowDownload: true })
+  if (!found) {
+    console.error(red('\nCould not obtain a source checkout to build from.\n'))
+    return 1
+  }
+  ok(found.source)
+
+  console.log(bold('\nBuilding and starting'))
+  console.log(
+    dim(
+      '  The first build installs a hash-locked Python environment and the current\n' +
+        '  Google Chrome Stable package, so it can take several minutes.\n',
+    ),
+  )
+  const detach = !argv.includes('--foreground')
+  const args = ['compose', 'up', '--build', ...(detach ? ['--detach'] : [])]
+  const result = run('docker', args, { cwd: found.dir, stdio: 'inherit' })
+  if (result.status !== 0) return result.status ?? 1
+
+  if (detach) {
+    console.log(`\n  API     ${DEFAULT_BASE_URL}/browser/health`)
+    console.log(`  noVNC   ${NOVNC_URL}`)
+    console.log(dim(`\n  Stop with: npx aether-browser down\n`))
+  }
+  return 0
+}
+
+function cmdDown() {
+  const found = findComposeDir({ allowDownload: false })
+  if (!found) {
+    console.error(red('No checkout found here. Run `down` from the directory you ran `up` in.'))
+    return 1
+  }
+  const result = run('docker', ['compose', 'down', '--volumes', '--remove-orphans'], {
+    cwd: found.dir,
+    stdio: 'inherit',
+  })
+  return result.status ?? 1
+}
+
+async function cmdStatus() {
+  const baseUrl = process.env.AGENT_BROWSER_URL || DEFAULT_BASE_URL
+  const { health, error } = await probeHealth(baseUrl)
+  if (!health) {
+    console.error(red(`Agent Browser is not responding at ${baseUrl}`))
+    if (error instanceof AgentBrowserError && error.code) console.error(dim(`  ${error.code}`))
+    return 1
+  }
+  console.log(JSON.stringify(health, null, 2))
+  return 0
+}
+
+function cmdOpen() {
+  const opener =
+    platform() === 'darwin' ? 'open' : platform() === 'win32' ? 'explorer' : 'xdg-open'
+  console.log(`Opening ${NOVNC_URL}`)
+  const result = run(opener, [NOVNC_URL], { stdio: 'ignore' })
+  if (result.status !== 0) console.log(`Open it manually: ${NOVNC_URL}`)
+  return 0
+}
+
+function usage() {
+  console.log(`
+${bold('aether-browser')} ${dim(PKG.version)}
+Client and CLI for Agent Browser by Aether AI.
+
+${bold('Usage')}
+  npx aether-browser <command>
+
+${bold('Commands')}
+  doctor    Check Docker, platform, ports, and server health, and say what is wrong
+  up        Build and start the runtime (Linux + Docker Compose v2; first build is slow)
+  down      Stop the runtime and remove its volumes
+  status    Print the server health document as JSON
+  open      Open the live noVNC view in a browser
+  help      Show this message
+
+${bold('Environment')}
+  AGENT_BROWSER_URL               Server base URL (default ${DEFAULT_BASE_URL})
+  AGENT_BROWSER_CONTROLLER_TOKEN  Controller token, if the server runs authenticated
+  AGENT_BROWSER_OBSERVER_TOKEN    Observer token
+
+${bold('Library')}
+  import { AgentBrowser, withSession } from 'aether-browser'
+
+${dim(REPO)}
+`)
+  return 0
+}
+
+const [, , command = 'help', ...rest] = process.argv
+const commands = {
+  doctor: cmdDoctor,
+  up: () => cmdUp(rest),
+  down: cmdDown,
+  status: cmdStatus,
+  open: cmdOpen,
+  help: usage,
+  '--help': usage,
+  '-h': usage,
+  '--version': () => (console.log(PKG.version), 0),
+  '-v': () => (console.log(PKG.version), 0),
+}
+
+const handler = commands[command]
+if (!handler) {
+  console.error(red(`Unknown command: ${command}`))
+  usage()
+  process.exit(1)
+}
+process.exit((await handler()) ?? 0)

package/src/index.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Types for the Agent Browser v1 API client.
+ *
+ * These mirror the closed server models in `src/agent_browser/models.py`. The server
+ * rejects unknown fields, so these types are deliberately exact rather than permissive.
+ */
+
+export declare const API_VERSION: 'v1'
+export declare const DEFAULT_BASE_URL: 'http://127.0.0.1:8092'
+
+export type AllowedKey =
+  | 'Enter'
+  | 'Escape'
+  | 'Tab'
+  | 'Backspace'
+  | 'Delete'
+  | 'Space'
+  | 'ArrowUp'
+  | 'ArrowDown'
+  | 'ArrowLeft'
+  | 'ArrowRight'
+  | 'Home'
+  | 'End'
+  | 'PageUp'
+  | 'PageDown'
+  | 'Control+A'
+  | 'Control+Z'
+  | 'Control+Shift+Z'
+  | 'Meta+A'
+  | 'Meta+Z'
+  | 'Meta+Shift+Z'
+
+export declare const ALLOWED_KEYS: readonly AllowedKey[]
+
+export type ErrorCode =
+  | 'AUTH_REQUIRED'
+  | 'AUTH_FORBIDDEN'
+  | 'SESSION_CAPACITY_REACHED'
+  | 'SESSION_NOT_FOUND'
+  | 'SESSION_EXPIRED'
+  | 'VISION_BUDGET_EXHAUSTED'
+  | 'INVALID_URL'
+  | 'DESTINATION_BLOCKED'
+  | 'INVALID_INTERACTION'
+  | 'BROWSER_NOT_READY'
+  | 'INTERNAL_ERROR'
+
+export type InteractionAction = 'click' | 'type' | 'scroll' | 'press'
+
+export interface AccessibilityNode {
+  role: string
+  name: string
+  value: string
+  focused: boolean
+  disabled: boolean
+}
+
+export interface AccessibilitySnapshot {
+  nodes: AccessibilityNode[]
+  truncated: boolean
+}
+
+export interface Viewport {
+  width: number
+  height: number
+  device_scale_factor: number
+}
+
+export interface HealthResponse {
+  api_version: 'v1'
+  status: 'ok'
+  version: string
+  browser_ready: boolean
+  session_active: boolean
+  slots_available: number
+  started_at: string
+}
+
+export interface CreateSessionResponse {
+  api_version: 'v1'
+  status: 'created'
+  session_id: string
+  state: 'active'
+  max_vision_steps: number
+  view_url: string
+  created_at: string
+  expires_at: string
+}
+
+export interface NavigateResponse {
+  api_version: 'v1'
+  status: 'navigated'
+  session_id: string
+  final_url: string
+  title: string
+  readable_text: string
+  accessibility: AccessibilitySnapshot
+  navigated_at: string
+}
+
+export interface SnapshotResponse {
+  api_version: 'v1'
+  status: 'snapshot'
+  session_id: string
+  url: string
+  title: string
+  readable_text: string
+  accessibility: AccessibilitySnapshot
+  screenshot_base64: string
+  viewport: Viewport
+  sequence: number
+  captured_at: string
+  vision_steps_used: number
+  vision_steps_remaining: number
+}
+
+export interface InteractResponse {
+  api_version: 'v1'
+  status: 'interacted'
+  session_id: string
+  action: InteractionAction
+  sequence: number
+  interacted_at: string
+}
+
+export interface EndSessionResponse {
+  api_version: 'v1'
+  status: 'ended' | 'already_ended'
+  session_id: string
+  ended_at: string
+}
+
+export interface RequestOptions {
+  /** Abort the request early. Composed with the client timeout. */
+  signal?: AbortSignal
+  /** Override the client timeout for this call. Pass 0 to disable. */
+  timeoutMs?: number
+}
+
+export interface AgentBrowserOptions {
+  /** Defaults to `AGENT_BROWSER_URL`, then `http://127.0.0.1:8092`. */
+  baseUrl?: string
+  /** Required for create, navigate, interact, and end. Defaults to `AGENT_BROWSER_CONTROLLER_TOKEN`. */
+  controllerToken?: string
+  /** Sufficient for health and snapshot. Defaults to `AGENT_BROWSER_OBSERVER_TOKEN`. */
+  observerToken?: string
+  /** Per-request timeout in milliseconds. Defaults to 30000. Pass 0 to disable. */
+  timeoutMs?: number
+  /** Injectable transport, for tests or a custom agent. Defaults to global fetch. */
+  fetch?: typeof globalThis.fetch
+  /** Injectable environment, for tests. Defaults to `process.env`. */
+  env?: Record<string, string | undefined>
+}
+
+export declare class AgentBrowserError extends Error {
+  name: 'AgentBrowserError'
+  /** The server's stable error code, or undefined for a transport failure. */
+  code?: ErrorCode
+  httpStatus?: number
+  retryAfterSeconds?: number
+  readonly isCapacityReached: boolean
+  readonly isDestinationBlocked: boolean
+  constructor(
+    message: string,
+    options?: {
+      code?: ErrorCode
+      httpStatus?: number
+      retryAfterSeconds?: number
+      cause?: unknown
+    },
+  )
+}
+
+export declare class Session {
+  readonly id: string
+  readonly viewUrl: string
+  readonly createdAt: string
+  readonly expiresAt: string
+  readonly maxVisionSteps: number
+  ended: boolean
+
+  navigate(url: string, options?: RequestOptions): Promise<NavigateResponse>
+  snapshot(options?: RequestOptions): Promise<SnapshotResponse>
+  click(
+    target: { selector: string; x?: never; y?: never } | { x: number; y: number; selector?: never },
+    options?: RequestOptions,
+  ): Promise<InteractResponse>
+  type(
+    input:
+      | { text: string; selector: string; x?: never; y?: never }
+      | { text: string; x: number; y: number; selector?: never },
+    options?: RequestOptions,
+  ): Promise<InteractResponse>
+  press(key: AllowedKey, options?: RequestOptions): Promise<InteractResponse>
+  scroll(
+    input: { deltaX?: number; deltaY?: number; selector?: string; x?: number; y?: number },
+    options?: RequestOptions,
+  ): Promise<InteractResponse>
+  end(options?: RequestOptions): Promise<EndSessionResponse>
+}
+
+export declare class AgentBrowser {
+  constructor(options?: AgentBrowserOptions)
+  readonly baseUrl: string
+  health(options?: RequestOptions): Promise<HealthResponse>
+  createSession(
+    input?: { maxVisionSteps?: number },
+    options?: RequestOptions,
+  ): Promise<Session>
+}
+
+/**
+ * Run `fn` against a fresh session and always attempt to end it, including when `fn`
+ * throws. A failure to end never masks the original error.
+ */
+export declare function withSession<T>(
+  browser: AgentBrowser,
+  fn: (session: Session) => Promise<T>,
+  input?: { maxVisionSteps?: number },
+): Promise<T>
+
+export default AgentBrowser

package/src/index.js

@@ -0,0 +1,316 @@
+/**
+ * Client for the Agent Browser v1 API.
+ *
+ * The server exposes one closed JSON API. Every request and response carries
+ * `api_version: "v1"` and unknown fields are rejected, so this client sends
+ * exactly the documented fields and omits anything left undefined.
+ *
+ * @see https://github.com/AetherAI3/agent-browser/blob/main/docs/API.md
+ */
+
+export const API_VERSION = 'v1'
+
+export const DEFAULT_BASE_URL = 'http://127.0.0.1:8092'
+
+/** Keys the server accepts for `press`. Anything else is refused server-side. */
+export const ALLOWED_KEYS = Object.freeze([
+  'Enter',
+  'Escape',
+  'Tab',
+  'Backspace',
+  'Delete',
+  'Space',
+  'ArrowUp',
+  'ArrowDown',
+  'ArrowLeft',
+  'ArrowRight',
+  'Home',
+  'End',
+  'PageUp',
+  'PageDown',
+  'Control+A',
+  'Control+Z',
+  'Control+Shift+Z',
+  'Meta+A',
+  'Meta+Z',
+  'Meta+Shift+Z',
+])
+
+/**
+ * An error returned by the Agent Browser API, or a transport failure reaching it.
+ *
+ * `code` is the server's stable error code when the response carried the documented
+ * error envelope, and `undefined` for transport-level failures.
+ */
+export class AgentBrowserError extends Error {
+  /**
+   * @param {string} message
+   * @param {{ code?: string, httpStatus?: number, retryAfterSeconds?: number, cause?: unknown }} [options]
+   */
+  constructor(message, options = {}) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause })
+    this.name = 'AgentBrowserError'
+    this.code = options.code
+    this.httpStatus = options.httpStatus
+    this.retryAfterSeconds = options.retryAfterSeconds
+  }
+
+  /** True when the server refused because a session is already active. */
+  get isCapacityReached() {
+    return this.code === 'SESSION_CAPACITY_REACHED'
+  }
+
+  /** True when the server refused the destination rather than failing to reach it. */
+  get isDestinationBlocked() {
+    return this.code === 'DESTINATION_BLOCKED' || this.code === 'INVALID_URL'
+  }
+}
+
+/** Strip undefined values so the closed server models never see unknown or null keys. */
+function compact(object) {
+  const out = {}
+  for (const [key, value] of Object.entries(object)) {
+    if (value !== undefined) out[key] = value
+  }
+  return out
+}
+
+function normalizeBaseUrl(value) {
+  return String(value).replace(/\/+$/, '')
+}
+
+/**
+ * A live session. Obtained from `AgentBrowser#createSession`; not constructed directly.
+ *
+ * Every method is a thin, typed call onto the documented routes. The session does not
+ * cache page state: `navigate` and `snapshot` each return the server's own bounded view.
+ */
+export class Session {
+  /**
+   * @param {AgentBrowser} browser
+   * @param {import('./index.d.ts').CreateSessionResponse} created
+   */
+  constructor(browser, created) {
+    this.browser = browser
+    this.id = created.session_id
+    this.viewUrl = created.view_url
+    this.createdAt = created.created_at
+    this.expiresAt = created.expires_at
+    this.maxVisionSteps = created.max_vision_steps
+    this.ended = false
+  }
+
+  /** Navigate to an HTTP(S) URL. The server evaluates its egress policy separately from schema validation. */
+  navigate(url, options = {}) {
+    return this.browser._post('/browser/navigate', { session_id: this.id, url }, 'controller', options)
+  }
+
+  /** Capture bounded page state plus a base64 PNG. Consumes exactly one vision step. */
+  snapshot(options = {}) {
+    return this.browser._post('/browser/snapshot', { session_id: this.id }, 'observer', options)
+  }
+
+  /**
+   * Click a selector or an x/y point. Exactly one of the two is allowed by the server.
+   * @param {{ selector?: string, x?: number, y?: number }} target
+   */
+  click(target, options = {}) {
+    return this._interact({ action: 'click', target: compact(target) }, options)
+  }
+
+  /**
+   * Type text into a selector or an x/y point. Text is preserved byte for byte,
+   * including leading and trailing whitespace.
+   * @param {{ selector?: string, x?: number, y?: number, text: string }} input
+   */
+  type({ text, ...target }, options = {}) {
+    return this._interact({ action: 'type', target: compact(target), text }, options)
+  }
+
+  /**
+   * Press one of the allowed keys or combinations. Clipboard shortcuts are not allowlisted.
+   * @param {import('./index.d.ts').AllowedKey} key
+   */
+  press(key, options = {}) {
+    return this._interact({ action: 'press', key }, options)
+  }
+
+  /**
+   * Scroll by a bounded, nonzero delta.
+   * @param {{ deltaX?: number, deltaY?: number, selector?: string, x?: number, y?: number }} input
+   */
+  scroll({ deltaX, deltaY, ...target } = {}, options = {}) {
+    const body = { action: 'scroll', delta_x: deltaX, delta_y: deltaY }
+    const where = compact(target)
+    if (Object.keys(where).length > 0) body.target = where
+    return this._interact(body, options)
+  }
+
+  _interact(body, options) {
+    return this.browser._post(
+      '/browser/interact',
+      { session_id: this.id, ...compact(body) },
+      'controller',
+      options,
+    )
+  }
+
+  /**
+   * End the session. Idempotent: a repeated call reports `already_ended` rather than
+   * resurrecting state, so calling this twice is safe.
+   */
+  async end(options = {}) {
+    const result = await this.browser._post(
+      '/browser/session/end',
+      { session_id: this.id },
+      'controller',
+      options,
+    )
+    this.ended = true
+    return result
+  }
+}
+
+/**
+ * A client bound to one Agent Browser server.
+ *
+ * Observer and controller tokens are kept separate so the server's role split is visible
+ * in your own code: reads may be given only the observer token, while anything that
+ * creates, navigates, interacts, or ends requires the controller token.
+ */
+export class AgentBrowser {
+  /**
+   * @param {import('./index.d.ts').AgentBrowserOptions} [options]
+   */
+  constructor(options = {}) {
+    const env = options.env ?? (typeof process !== 'undefined' ? process.env : {}) ?? {}
+    this.baseUrl = normalizeBaseUrl(options.baseUrl ?? env.AGENT_BROWSER_URL ?? DEFAULT_BASE_URL)
+    this.controllerToken = options.controllerToken ?? env.AGENT_BROWSER_CONTROLLER_TOKEN
+    this.observerToken = options.observerToken ?? env.AGENT_BROWSER_OBSERVER_TOKEN
+    this.timeoutMs = options.timeoutMs ?? 30_000
+    this._fetch = options.fetch ?? globalThis.fetch
+    if (typeof this._fetch !== 'function') {
+      throw new TypeError(
+        'No fetch implementation available. Use Node 18 or newer, or pass options.fetch.',
+      )
+    }
+  }
+
+  /** Liveness and readiness. Accepts the observer token. */
+  health(options = {}) {
+    return this._request('GET', '/browser/health', undefined, 'observer', options)
+  }
+
+  /**
+   * Create the one owned session. A second concurrent create is refused with
+   * `SESSION_CAPACITY_REACHED` rather than queued.
+   * @param {{ maxVisionSteps?: number }} [input]
+   */
+  async createSession(input = {}, options = {}) {
+    const created = await this._post(
+      '/browser/session/create',
+      compact({ max_vision_steps: input.maxVisionSteps }),
+      'controller',
+      options,
+    )
+    return new Session(this, created)
+  }
+
+  _post(path, body, role, options) {
+    return this._request('POST', path, body, role, options)
+  }
+
+  _tokenFor(role) {
+    if (role === 'observer') return this.observerToken ?? this.controllerToken
+    return this.controllerToken ?? this.observerToken
+  }
+
+  async _request(method, path, body, role, options = {}) {
+    const headers = { accept: 'application/json' }
+    const token = this._tokenFor(role)
+    if (token) headers.authorization = `Bearer ${token}`
+
+    let payload
+    if (body !== undefined) {
+      headers['content-type'] = 'application/json'
+      payload = JSON.stringify({ api_version: API_VERSION, ...body })
+    }
+
+    const timeoutMs = options.timeoutMs ?? this.timeoutMs
+    const controller = new AbortController()
+    const onAbort = () => controller.abort(options.signal?.reason)
+    if (options.signal) {
+      if (options.signal.aborted) onAbort()
+      else options.signal.addEventListener('abort', onAbort, { once: true })
+    }
+    const timer =
+      timeoutMs > 0
+        ? setTimeout(
+            () => controller.abort(new Error(`Agent Browser request timed out after ${timeoutMs}ms`)),
+            timeoutMs,
+          )
+        : undefined
+
+    let response
+    try {
+      response = await this._fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        body: payload,
+        signal: controller.signal,
+      })
+    } catch (cause) {
+      throw new AgentBrowserError(
+        `Could not reach Agent Browser at ${this.baseUrl}: ${cause?.message ?? cause}`,
+        { cause },
+      )
+    } finally {
+      if (timer !== undefined) clearTimeout(timer)
+      options.signal?.removeEventListener?.('abort', onAbort)
+    }
+
+    const text = await response.text()
+    let parsed
+    try {
+      parsed = text ? JSON.parse(text) : undefined
+    } catch {
+      parsed = undefined
+    }
+
+    if (!response.ok) {
+      const detail = parsed?.error
+      const retryAfter = Number(response.headers?.get?.('retry-after'))
+      throw new AgentBrowserError(detail?.message ?? `Agent Browser returned HTTP ${response.status}`, {
+        code: detail?.code,
+        httpStatus: response.status,
+        retryAfterSeconds: Number.isFinite(retryAfter) ? retryAfter : undefined,
+      })
+    }
+
+    return parsed
+  }
+}
+
+/**
+ * Run `fn` against a fresh session and always attempt to end it, including when `fn`
+ * throws. A failure to end never masks the original error.
+ *
+ * @template T
+ * @param {AgentBrowser} browser
+ * @param {(session: Session) => Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+export async function withSession(browser, fn, input = {}) {
+  const session = await browser.createSession(input)
+  try {
+    return await fn(session)
+  } finally {
+    try {
+      await session.end()
+    } catch {
+      // The caller's outcome is what matters; a cleanup failure must not replace it.
+    }
+  }
+}
+
+export default AgentBrowser