browser4-cli 0.1.7 → 0.1.8

package/README.md

@@ -133,7 +133,6 @@ The tables below mirror the commands surfaced by the global `browser4-cli help`
 | Command | Description |
 |---|---|
 | `screenshot [ref]` | Take a screenshot |
-| `pdf` | Save page as PDF |
 
 #### Tabs
 
@@ -146,6 +145,28 @@ The tables below mirror the commands surfaced by the global `browser4-cli help`
 
 Use `tab-list` first to find the zero-based tab index you want to select or close.
 
+#### Browser storage
+
+| Command | Description |
+|---|---|
+| `state-save <path>` | Save cookies and localStorage to a JSON file |
+| `state-load <path>` | Restore cookies and localStorage from a saved state file |
+| `cookie-list` | List all cookies (optionally filtered by `--domain` / `--path`) |
+| `cookie-get <name>` | Get a cookie by name |
+| `cookie-set <name> <value>` | Set a cookie (optional `--path`, `--domain`) |
+| `cookie-delete <name>` | Delete a cookie by name |
+| `cookie-clear` | Clear all cookies for the current page |
+| `localstorage-list` | List all localStorage entries |
+| `localstorage-get <key>` | Get a localStorage value by key |
+| `localstorage-set <key> <value>` | Set a localStorage key-value pair |
+| `localstorage-delete <key>` | Delete a localStorage key |
+| `localstorage-clear` | Clear all localStorage entries |
+| `sessionstorage-list` | List all sessionStorage entries |
+| `sessionstorage-get <key>` | Get a sessionStorage value by key |
+| `sessionstorage-set <key> <value>` | Set a sessionStorage key-value pair |
+| `sessionstorage-delete <key>` | Delete a sessionStorage key |
+| `sessionstorage-clear` | Clear all sessionStorage entries |
+
 #### Browser sessions
 
 | Command | Description |
@@ -156,6 +177,17 @@ Use `tab-list` first to find the zero-based tab index you want to select or clos
 
 Use `close-all` for session cleanup when you want to keep the current Browser4 service running. Use `kill-all` only when you explicitly want to stop the backend and clean up tracked Browser4 processes.
 
+#### Server management
+
+| Command | Description |
+|---|---|
+| `install` | Download the self-contained Browser4 runtime bundle (JAR + bundled JRE) from GitHub Releases |
+| `upgrade` | Upgrade `browser4-cli` itself to the latest release (requires `cargo`) |
+| `stop` | Kill the Browser4 backend after closing all sessions |
+| `status` | Check whether the Browser4 backend is reachable and healthy |
+
+When a local Browser4 checkout is detected with the `browser4-bundle` module present,
+`install` auto-builds the runtime bundle from source instead of downloading.
 
 ### Advanced commands
 
@@ -164,18 +196,186 @@ Query `browser4-cli help <command>` for the exact syntax when you need them.
 
 | Command | Description |
 |---|---|
-| `batch [command...]` | Execute multiple commands in one invocation. Only DOM operations are supported (Core, Navigation, Keyboard, Mouse, Export, Tabs categories). Commands like `open`, `close`, `list`, `agent-run`, etc. are not allowed in batch mode. |
+| `batch [command...]` | Execute multiple commands in one invocation. Only DOM operations are supported (Core, Navigation, Keyboard, Mouse, Export, Tabs categories). Commands like `open`, `close`, `list`, `agent run`, etc. are not allowed in batch mode. |
 | `console [min-level]` | List console messages |
 | `extract <instruction>` | Extract structured data from the current page |
 | `summarize [instruction]` | Summarize page content using AI |
-| `agent-run <task>` | Run an autonomous agent task |
-| `agent-status <id>` | Check the status of a running agent task |
-| `agent-result <id>` | Get the result of a completed agent task |
-| `co-create` | Create a collective session with parallel browser contexts |
-| `co-submit [url]` | Submit URL(s) or tasks to the active collective session |
-| `co-scrape <url>` | Scrape data from a URL using CSS selectors |
-| `co-status <id>` | Check the status of a collective task |
-| `co-result <id>` | Get the result of a completed collective task |
+| `agent run <task>` | Run an autonomous agent task |
+| `agent status <id>` | Check the status of a running agent task |
+| `agent result <id>` | Get the result of a completed agent task |
+| `swarm create` | Create a swarm scrape session with parallel browser contexts |
+| `swarm submit [url]` | Submit URL(s) or X-SQL payloads as scrape jobs |
+| `swarm status <id>` | Check the status of a scrape job |
+| `swarm result <id>` | Get the result of a completed scrape job |
+
+## Agent task workflow (`agent <subcommand>`)
+
+The `agent-*` commands wrap the backend command agent's asynchronous task API.
+They are useful when you want Browser4 to plan and execute a natural-language
+task in the background instead of issuing one low-level browser action at a
+time.
+
+Like other advanced commands, they are intentionally omitted from the global
+`browser4-cli help` overview. Query `browser4-cli help agent run` (or
+`agent status` / `agent result`) when you need the exact syntax.
+
+Use the spaced `agent <subcommand>` form:
+
+```shell
+browser4-cli agent run "Open example.com and summarize the hero section"
+browser4-cli agent status agent-task-1
+browser4-cli agent result agent-task-1
+```
+
+### Command lifecycle
+
+| Step | Command | What it does |
+|---|---|---|
+| 1 | `agent run <task>` | Submits an asynchronous natural-language task through `command_run` and prints the returned task ID |
+| 2 | `agent status <id>` | Fetches the latest task status payload through `command_status` |
+| 3 | `agent result <id>` | Fetches the completed task result payload through `command_result` |
+
+### Notes
+
+- `agent run` is asynchronous: it returns immediately after the backend accepts
+  the task and prints a follow-up `agent status` command with the generated task
+  ID.
+- `agent status` prints the backend status payload as-is. In practice this is a
+  JSON object that commonly includes fields such as `id`, `status`,
+  `statusCode`, `processState`, `message`, `agentState`, `agentHistory`, and
+  `commandResult`.
+- `agent result` prints the backend result payload as-is. Depending on the task,
+  it may be plain text or structured JSON.
+- These commands are task-ID based and do not require an active CLI browser
+  session slot. The global `-s=<name>` option is therefore usually not relevant
+  for `agent-*` follow-up calls.
+- `agent` subcommands are not supported inside `batch` mode.
+- `agent run` performs a short post-submit status probe so obvious missing-LLM
+  configuration failures can be surfaced immediately instead of leaving you with
+  a task ID that will never succeed.
+
+### Use cases
+
+#### 1. Submit an autonomous agent task
+
+```shell
+browser4-cli agent run "Open example.com and summarize the hero section"
+```
+
+Typical output:
+
+```text
+Task submitted: agent-task-1
+Use 'browser4-cli agent status agent-task-1' to check progress.
+```
+
+#### 2. Poll task progress
+
+```shell
+browser4-cli agent status agent-task-1
+```
+
+Example status payload:
+
+```json
+{"id":"agent-task-1","status":"RUNNING"}
+```
+
+On a real Browser4 backend the payload can be richer and may include lifecycle
+details such as `processState`, agent history snapshots, or an embedded partial
+`commandResult`.
+
+#### 3. Read the final result
+
+```shell
+browser4-cli agent result agent-task-1
+```
+
+If the backend returns a structured `CommandResult`, expect fields such as
+`summary`, `pageSummary`, `fields`, `links`, or `xsqlResultSet`.
+
+## Swarm scrape workflow (`swarm <subcommand>`)
+
+The `swarm` subcommands support a swarm scrape workflow where one CLI session
+coordinates multiple browser contexts in the Browser4 backend.
+
+Use the spaced `swarm <subcommand>` form:
+
+```shell
+browser4-cli swarm create
+browser4-cli swarm submit https://example.com
+```
+
+### Command lifecycle
+
+| Step | Command | What it does |
+|---|---|---|
+| 1 | `swarm create` | Opens a swarm scrape session and persists the returned session ID in the current CLI slot |
+| 2 | `swarm submit [url]` | Submits one direct URL plus any URLs from `--seed-file` as scrape jobs through `ScrapeController.submit(payload)` |
+| 3 | `swarm status <id>` | Calls `ScrapeController.getStatus(id)` and prints the returned scrape job status JSON |
+| 4 | `swarm result <id>` | Calls `ScrapeController.getResult(id)` and prints the returned scrape job result JSON |
+
+### Notes
+
+- `swarm create` accepts backend capability hints such as `--profile-mode`,
+  `--max-open-tabs`, `--max-browser-contexts`, and `--display-mode`.
+- `swarm submit` accepts either a direct positional URL, `--seed-file`, or both.
+  Seed files are plain text files with one URL per line; blank lines and lines
+  starting with `#` are ignored.
+- `swarm submit` maps CLI flags like `--deadline`, `--expires`, `--refresh`,
+  `--parse`, and `--store-content` into the raw submission payload sent to the
+  scrape REST API.
+- `swarm status` and `swarm result` are read-only follow-up commands; keep the job ID
+  printed by `swarm submit`.
+
+### Use cases
+
+#### 1. Create a supervised swarm scrape session for manual monitoring
+
+```shell
+browser4-cli swarm create \
+  --profile-mode=TEMPORARY \
+  --max-open-tabs=12 \
+  --max-browser-contexts=3 \
+  --display-mode=HEADLESS
+```
+
+Use this when you want multiple isolated browser contexts and you still want to
+watch the run visually.
+
+#### 2. Submit a seed crawl as scrape jobs
+
+```shell
+browser4-cli swarm submit https://example.com/direct \
+  --seed-file=./swarm-seeds.txt \
+  --deadline=2026-03-30T00:00:00Z \
+  --expires=1d \
+  --refresh \
+  --parse \
+  --store-content
+```
+
+Example `swarm-seeds.txt`:
+
+```text
+# campaign landing pages
+https://example.com/seed-1
+https://example.com/seed-2
+```
+
+This pattern is useful for warming caches, refreshing a URL list, or launching
+parallel collection across a curated seed set.
+
+#### 3. Poll and fetch the result
+
+```shell
+browser4-cli swarm status scrape-task-4
+browser4-cli swarm result scrape-task-4
+```
+
+The status and result commands print the scrape job response payload as-is. In
+the current backend, `getResult(id)` returns the same response envelope type as
+`getStatus(id)`.
 
 ## Element References
 
@@ -218,16 +418,16 @@ gate for commands that require an active Browser4 session.
 | `open -s=<name>` | Reads/writes the named session state file | Opens, reuses, or refreshes the named session for that slot; subsequent `-s=<name>` commands use the same slot |
 | Command succeeds through `with_session()` | `sessionId` stays unchanged | The command uses the persisted session normally |
 | Command fails because the server reports a stale / expired session and `recover_stale = false` | `invalidate_session()` clears `sessionId`, `activeSelector`, and `lastMousePosition`, while keeping `baseUrl` | The command fails with `Saved session expired. Run "browser4-cli open" first.` |
-| `goto` is invoked but the saved session is missing or no longer `active` in the backend | `invalidate_session()` clears the saved `sessionId`, `activeSelector`, and `lastMousePosition` | The command fails with `No active session for "goto". Run "browser4-cli open" to create or refresh the session first.` |
+| `goto` is invoked but the saved session is missing or no longer `active` in the backend | `invalidate_session()` clears any stale saved `sessionId`, then `create_session()` writes a fresh session before navigation continues | `goto` automatically refreshes the session and proceeds to the requested URL |
 | `close` with an active session | `clear_state()` removes only the current session state file after best-effort remote close | The selected default or named session is fully cleared |
 | `close` with no persisted `sessionId` | `clear_state()` best-effort removes the current session slot | Prints `No active session. Run "browser4-cli open" first.` and exits successfully as a no-op |
 | `close-all` / `kill-all` | `clear_all_state()` removes the default state file and all named session files | All persisted CLI session files are cleared |
 
 Notes:
 
-- `goto` reuses only the current backend-`active` session. It does not create a
-  new session automatically; run `browser4-cli open` first if the saved session
-  is missing or stale.
+- `goto` first tries to reuse the current backend-`active` session. If the saved
+  session is missing, stale, or the backend had been stopped, it automatically
+  opens a fresh session for the current slot before navigating.
 - `open` first checks whether the saved session for the current slot is still
   backend-`active`. It reuses active sessions and refreshes stale ones by
   creating a new session for the same slot.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser4-cli",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Browser automation CLI for AI agents",
   "type": "module",
   "files": [
@@ -15,7 +15,7 @@
   },
   "scripts": {
     "version:sync": "node scripts/sync-version.js",
-    "version": "npm run version:sync && git add browser4-cli/Cargo.toml",
+    "version": "npm run version:sync && git add browser4-cli/Cargo.toml browser4-cli/Cargo.lock",
     "build:native": "npm run version:sync && cargo build --release --manifest-path browser4-cli/Cargo.toml && node scripts/copy-native.js",
     "build:linux": "npm run version:sync && docker compose -f docker/docker-compose.yml run --rm build-linux",
     "build:macos": "npm run version:sync && (cargo build --release --manifest-path browser4-cli/Cargo.toml --target aarch64-apple-darwin & cargo build --release --manifest-path browser4-cli/Cargo.toml --target x86_64-apple-darwin & wait) && cp cli/target/aarch64-apple-darwin/release/browser4 bin/browser4-darwin-arm64 && cp cli/target/x86_64-apple-darwin/release/browser4 bin/browser4-darwin-x64",

package/scripts/sync-version.js

@@ -5,10 +5,10 @@
  * Run this script before building or releasing.
  */
 
-import { execSync } from "child_process";
-import { readFileSync, writeFileSync } from "fs";
-import { dirname, join } from "path";
-import { fileURLToPath } from "url";
+import {execSync} from "child_process";
+import {readFileSync, writeFileSync} from "fs";
+import {dirname, join} from "path";
+import {fileURLToPath} from "url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const rootDir = join(__dirname, "..");
@@ -47,7 +47,7 @@ if (cargoVersionRegex.test(cargoToml)) {
 // Update Cargo.lock to match Cargo.toml
 if (cargoTomlUpdated) {
   try {
-    execSync("cargo update -p browser4 --offline", {
+    execSync("cargo update -p browser4-cli --offline", {
       cwd: cliDir,
       stdio: "pipe",
     });
@@ -55,7 +55,7 @@ if (cargoTomlUpdated) {
   } catch {
     // --offline may fail if package not in cache, try without it
     try {
-      execSync("cargo update -p browser4", {
+      execSync("cargo update -p browser4-cli", {
         cwd: cliDir,
         stdio: "pipe",
       });