opensteer 0.4.10 → 0.4.12

package/CHANGELOG.md

@@ -36,6 +36,11 @@
   timeout/stale-target cases more accurately.
 - Cloud action failures now accept optional structured failure details and map
   them to `OpensteerActionError` when available.
+- Docs: refreshed README and getting-started guidance to match current SDK/CLI
+  behavior and env vars.
+- Docs: added CLI reference and docs index.
+- OSS community docs: expanded `CONTRIBUTING.md` and added `SECURITY.md` +
+  `SUPPORT.md`.
 
 ## 0.1.0
 

package/README.md

@@ -1,186 +1,142 @@
 # Opensteer
 
-Lean browser automation SDK for coding agents and script replay.
+Open-source browser automation SDK for coding agents and deterministic replay.
 
-`opensteer` provides descriptor-aware actions (`click`, `dblclick`,
-`rightclick`, `hover`, `input`, `select`, `scroll`, `extract`,
-`extractFromPlan`, `uploadFile`), observation (`snapshot`, `state`,
-`screenshot`), navigation (`goto`), and convenience methods for tabs, cookies,
-keyboard, element info, and wait.
+Opensteer combines descriptor-aware actions, resilient selector persistence,
+clean HTML snapshots, and first-class local or cloud runtime support.
 
-For anything not covered, use raw Playwright via `opensteer.page` and
-`opensteer.context`.
+## Requirements
+
+- Node.js `>=20`
+- A browser environment supported by Playwright
+- API key for your selected model provider if you use LLM resolve/extract
 
 ## Install
 
 ```bash
 # npm
-npm install opensteer playwright
+npm install opensteer
 # pnpm
-pnpm add opensteer playwright
+pnpm add opensteer
 ```
 
-## CLI Session Routing
-
-OpenSteer CLI now separates runtime routing from selector caching:
-
-- Runtime routing: `--session` or `OPENSTEER_SESSION`
-- Selector cache namespace: `--name` or `OPENSTEER_NAME` (used on `open`)
-
-If neither `--session` nor `OPENSTEER_SESSION` is set:
-
-- In an interactive terminal, OpenSteer creates/reuses a terminal-scoped default session.
-- In non-interactive environments (agents/CI), it fails fast unless you set
-  `OPENSTEER_SESSION` or `OPENSTEER_CLIENT_ID`.
-
-Example:
+If your environment skips Playwright browser downloads, run:
 
 ```bash
-export OPENSTEER_SESSION=agent-a
-opensteer open https://example.com --name product-scraper
-opensteer snapshot
-opensteer click 3
-opensteer status
+npx playwright install chromium
 ```
 
-`opensteer status` reports `resolvedSession`, `sessionSource`, `resolvedName`, and `nameSource`.
-
-## Quickstart
+## Quickstart (SDK)
 
 ```ts
 import { Opensteer } from "opensteer";
 
-const opensteer = new Opensteer({ name: "my-scraper" }); // defaults to model: 'gpt-5.1'
+const opensteer = new Opensteer({ name: "my-scraper" });
 await opensteer.launch({ headless: false });
 
-await opensteer.goto("https://example.com");
-const html = await opensteer.snapshot();
-
-await opensteer.click({ description: "login-button" });
-await opensteer.input({ description: "email", text: "user@example.com" });
-await opensteer.page.keyboard.press("Enter");
+try {
+  await opensteer.goto("https://example.com");
+  const html = await opensteer.snapshot();
+  console.log(html.slice(0, 500));
 
-await opensteer.close();
+  await opensteer.click({ description: "main call to action", element: 3 });
+} finally {
+  await opensteer.close();
+}
 ```
 
-## Core Model
-
-- `opensteer.page`: raw Playwright `Page`
-- `opensteer.context`: raw Playwright `BrowserContext`
-- Opensteer methods: descriptor-aware operations that can persist selectors
-- Selector storage: `.opensteer/selectors/<namespace>`
-
-## Resolution Chain
-
-For actions like `click`/`input`/`hover`/`select`/`scroll`:
-
-1. Use persisted path for `description` (if present)
-2. Use `element` counter from snapshot
-3. Use explicit CSS `selector`
-4. Use built-in LLM resolution (`description` required)
-5. Throw
-
-When steps 2-4 resolve and `description` is provided, the path is persisted.
-
-## Smart Post-Action Wait
-
-Mutating actions (`click`, `input`, `select`, `scroll`, etc.) include a
-best-effort post-action wait so delayed visual updates are usually settled
-before the method resolves.
-
-You can disable or tune this per call:
+## CUA Agent
 
 ```ts
-await opensteer.click({ description: "Save button", wait: false });
+import { Opensteer } from "opensteer";
 
-await opensteer.click({
-  description: "Save button",
-  wait: { timeout: 9000, settleMs: 900, includeNetwork: true, networkQuietMs: 400 },
+const opensteer = new Opensteer({
+  model: "openai/computer-use-preview",
 });
-```
 
-## Action Failure Diagnostics
+await opensteer.launch();
 
-Descriptor-aware interaction methods (`click`, `dblclick`, `rightclick`,
-`hover`, `input`, `select`, `scroll`, `uploadFile`) throw
-`OpensteerActionError` when an interaction cannot be completed.
+const agent = opensteer.agent({
+  mode: "cua",
+});
 
-The error includes structured failure metadata for agent/tooling decisions:
+const result = await agent.execute({
+  instruction: "Go to Hacker News and open the top story.",
+  maxSteps: 20,
+  highlightCursor: true,
+});
 
-- `error.failure.code` (`ActionFailureCode`)
-- `error.failure.message`
-- `error.failure.retryable`
-- `error.failure.classificationSource`
-- `error.failure.details` (for blocker and observation details when available)
+console.log(result.message);
+await opensteer.close();
+```
 
-```ts
-import { Opensteer, OpensteerActionError } from "opensteer";
+Supported CUA providers in V1: `openai`, `anthropic`, `google`.
 
-try {
-  await opensteer.click({ description: "Save button" });
-} catch (err) {
-  if (err instanceof OpensteerActionError) {
-    console.error(err.failure.code); // e.g. BLOCKED_BY_INTERCEPTOR
-    console.error(err.failure.message);
-    console.error(err.failure.classificationSource);
-  }
-  throw err;
-}
-```
+## Quickstart (CLI)
 
-## Snapshot Modes
+Opensteer CLI separates runtime routing from selector namespace routing.
 
-```ts
-await opensteer.snapshot(); // action mode (default)
-await opensteer.snapshot({ mode: "extraction" });
-await opensteer.snapshot({ mode: "clickable" });
-await opensteer.snapshot({ mode: "scrollable" });
-await opensteer.snapshot({ mode: "full" });
-```
+- Runtime routing: `--session` or `OPENSTEER_SESSION`
+- Selector namespace: `--name` or `OPENSTEER_NAME` (used by `open`)
 
-## Two Usage Patterns
+```bash
+opensteer open https://example.com --session agent-a --name product-scraper
+opensteer snapshot --session agent-a
+opensteer click 3 --session agent-a
+opensteer status --session agent-a
+opensteer close --session agent-a
+```
 
-### Explore (coding agent, no API key required)
+In non-interactive environments, set `OPENSTEER_SESSION` or
+`OPENSTEER_CLIENT_ID` explicitly.
 
-Use `snapshot()` + `element` counters while exploring in real time, then persist
-stable descriptions for replay.
+## Resolution and Replay Model
 
-### Run (script replay / built-in LLM)
+For descriptor-aware actions (`click`, `input`, `hover`, `select`, `scroll`):
 
-Opensteer uses built-in LLM resolve/extract by default. You can override the
-default model with top-level `model` or `OPENSTEER_MODEL`.
+1. Reuse persisted path for `description`
+2. Use `element` counter from snapshot
+3. Use explicit CSS `selector`
+4. Use built-in LLM resolution (`description` required)
+5. Throw actionable error
 
-```ts
-const opensteer = new Opensteer({
-  name: "run-mode",
-  model: "gpt-5-mini",
-});
-```
+When steps 2-4 succeed and `description` is present, Opensteer persists the
+path for deterministic replay in `.opensteer/selectors/<namespace>`.
 
-## Mode Selection
+## Cloud Mode
 
 Opensteer defaults to local mode.
 
-- `OPENSTEER_MODE=local` runs local Playwright.
-- `OPENSTEER_MODE=cloud` enables cloud mode (requires `OPENSTEER_API_KEY`).
-- `cloud: true` in constructor config always enables cloud mode.
-- Opensteer auto-loads `.env` files from your `storage.rootDir` (default:
-  `process.cwd()`) using this order: `.env.<NODE_ENV>.local`, `.env.local`
-  (skipped when `NODE_ENV=test`), `.env.<NODE_ENV>`, `.env`.
-- Existing `process.env` values are never overwritten by `.env` values.
-- Set `OPENSTEER_DISABLE_DOTENV_AUTOLOAD=true` to disable auto-loading.
+- `OPENSTEER_MODE=local|cloud`
+- `OPENSTEER_API_KEY` or `cloud.apiKey` required in cloud mode
+- `OPENSTEER_BASE_URL` or `cloud.baseUrl` to override the default cloud host
+- `OPENSTEER_AUTH_SCHEME` or `cloud.authScheme` for auth header mode
+  (`api-key` or `bearer`)
+- `cloud: true` or a `cloud` options object overrides `OPENSTEER_MODE`
 
-Cloud mode is fail-fast: it does not automatically fall back to local mode.
+`.env` files are auto-loaded from `storage.rootDir` (default `process.cwd()`)
+in this order: `.env.<NODE_ENV>.local`, `.env.local` (except in test),
+`.env.<NODE_ENV>`, `.env`. Existing `process.env` values are not overwritten.
+Set `OPENSTEER_DISABLE_DOTENV_AUTOLOAD=true` to disable.
 
 ## Docs
 
-- `docs/getting-started.md`
-- `docs/api-reference.md`
-- `docs/cloud-integration.md`
-- `docs/html-cleaning.md`
-- `docs/selectors.md`
-- `docs/live-web-tests.md`
+- [Getting Started](docs/getting-started.md)
+- [API Reference](docs/api-reference.md)
+- [CLI Reference](docs/cli-reference.md)
+- [Cloud Integration](docs/cloud-integration.md)
+- [Selectors and Storage](docs/selectors.md)
+- [HTML Cleaning and Snapshot Modes](docs/html-cleaning.md)
+- [Live Web Validation Suite](docs/live-web-tests.md)
+
+## Community
+
+- [Contributing Guide](CONTRIBUTING.md)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [Security Policy](SECURITY.md)
+- [Support](SUPPORT.md)
+- [Changelog](CHANGELOG.md)
 
 ## License
 
-MIT
+[MIT](LICENSE)

package/bin/opensteer.mjs

@@ -781,6 +781,7 @@ Environment:
   OPENSTEER_MODE            Runtime routing: "local" (default) or "cloud"
   OPENSTEER_API_KEY         Required when cloud mode is selected
   OPENSTEER_BASE_URL        Override cloud control-plane base URL
+  OPENSTEER_AUTH_SCHEME     Cloud auth scheme: api-key (default) or bearer
   OPENSTEER_REMOTE_ANNOUNCE Cloud session announcement policy: always (default), off, tty
 `)
 }