opensteer 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -4,8 +4,23 @@
 
 - Breaking: removed legacy `ai` config from `OpensteerConfig`; use top-level `model` instead.
 - Breaking: `OPENSTEER_AI_MODEL` is no longer supported; use `OPENSTEER_MODEL`.
+- Breaking: `OPENSTEER_RUNTIME` is no longer supported; use `OPENSTEER_MODE`.
+- Breaking: mode selection now uses `mode: 'local' | 'remote'` and remote credentials use `remote.apiKey`.
 - Opensteer now enables built-in LLM resolve/extract by default with model `gpt-5.1`.
-- Cloud mode now falls back to `OPENSTEER_API_KEY` when `cloud.key` is omitted.
+- Remote mode now falls back to `OPENSTEER_API_KEY` when `remote.apiKey` is omitted.
+- Mutating actions now include smart best-effort post-action wait with per-action
+  profiles and optional per-call overrides via `wait`.
+- Added structured interaction diagnostics via `OpensteerActionError` for
+  descriptor-aware interaction methods (`click`, `dblclick`, `rightclick`,
+  `hover`, `input`, `select`, `scroll`, `uploadFile`).
+- Added `ActionFailure` types (`ActionFailureCode`, `retryable`,
+  `classificationSource`, optional `details`) to support programmatic handling
+  of action failures.
+- Added DOM actionability probe + Playwright call-log classification to report
+  reasons like `BLOCKED_BY_INTERCEPTOR`, `NOT_VISIBLE`, `NOT_EDITABLE`, and
+  timeout/stale-target cases more accurately.
+- Remote action failures now accept optional structured failure details and map
+  them to `OpensteerActionError` when available.
 
 ## 0.1.0
 

package/README.md

@@ -2,11 +2,14 @@
 
 Lean browser automation SDK for coding agents and script replay.
 
-`opensteer` wraps only operations that need descriptor resolution (`snapshot`,
-`click`, `dblclick`, `rightclick`, `hover`, `input`, `select`, `scroll`,
-`extract`, `extractFromPlan`, `state`).
+`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.
 
-Everything else is raw Playwright via `ov.page` and `ov.context`.
+For anything not covered, use raw Playwright via `opensteer.page` and
+`opensteer.context`.
 
 ## Install
 
@@ -22,23 +25,23 @@ pnpm add opensteer playwright
 ```ts
 import { Opensteer } from "opensteer";
 
-const ov = new Opensteer({ name: "my-scraper" }); // defaults to model: 'gpt-5.1'
-await ov.launch({ headless: false });
+const opensteer = new Opensteer({ name: "my-scraper" }); // defaults to model: 'gpt-5.1'
+await opensteer.launch({ headless: false });
 
-await ov.page.goto("https://example.com");
-const html = await ov.snapshot();
+await opensteer.goto("https://example.com");
+const html = await opensteer.snapshot();
 
-await ov.click({ description: "login-button" });
-await ov.input({ description: "email", text: "user@example.com" });
-await ov.page.keyboard.press("Enter");
+await opensteer.click({ description: "login-button" });
+await opensteer.input({ description: "email", text: "user@example.com" });
+await opensteer.page.keyboard.press("Enter");
 
-await ov.close();
+await opensteer.close();
 ```
 
 ## Core Model
 
-- `ov.page`: raw Playwright `Page`
-- `ov.context`: raw Playwright `BrowserContext`
+- `opensteer.page`: raw Playwright `Page`
+- `opensteer.context`: raw Playwright `BrowserContext`
 - Opensteer methods: descriptor-aware operations that can persist selectors
 - Selector storage: `.opensteer/selectors/<namespace>`
 
@@ -54,14 +57,60 @@ For actions like `click`/`input`/`hover`/`select`/`scroll`:
 
 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:
+
+```ts
+await opensteer.click({ description: "Save button", wait: false });
+
+await opensteer.click({
+  description: "Save button",
+  wait: { timeout: 9000, settleMs: 900, includeNetwork: true, networkQuietMs: 400 },
+});
+```
+
+## Action Failure Diagnostics
+
+Descriptor-aware interaction methods (`click`, `dblclick`, `rightclick`,
+`hover`, `input`, `select`, `scroll`, `uploadFile`) throw
+`OpensteerActionError` when an interaction cannot be completed.
+
+The error includes structured failure metadata for agent/tooling decisions:
+
+- `error.failure.code` (`ActionFailureCode`)
+- `error.failure.message`
+- `error.failure.retryable`
+- `error.failure.classificationSource`
+- `error.failure.details` (for blocker and observation details when available)
+
+```ts
+import { Opensteer, OpensteerActionError } from "opensteer";
+
+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;
+}
+```
+
 ## Snapshot Modes
 
 ```ts
-await ov.snapshot(); // action mode (default)
-await ov.snapshot({ mode: "extraction" });
-await ov.snapshot({ mode: "clickable" });
-await ov.snapshot({ mode: "scrollable" });
-await ov.snapshot({ mode: "full" });
+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" });
 ```
 
 ## Two Usage Patterns
@@ -77,16 +126,27 @@ Opensteer uses built-in LLM resolve/extract by default. You can override the
 default model with top-level `model` or `OPENSTEER_MODEL`.
 
 ```ts
-const ov = new Opensteer({
+const opensteer = new Opensteer({
   name: "run-mode",
   model: "gpt-5-mini",
 });
 ```
 
+## Mode Selection
+
+Opensteer defaults to local mode.
+
+- `OPENSTEER_MODE=local` runs local Playwright.
+- `OPENSTEER_MODE=remote` runs remote mode (requires `OPENSTEER_API_KEY`).
+- `mode: "remote"` in constructor config always forces remote mode.
+
+Remote mode is fail-fast: it does not automatically fall back to local mode.
+
 ## Docs
 
 - `docs/getting-started.md`
 - `docs/api-reference.md`
+- `docs/remote-integration.md`
 - `docs/html-cleaning.md`
 - `docs/selectors.md`
 - `docs/live-web-tests.md`

package/bin/opensteer.mjs

@@ -59,7 +59,7 @@ function parseValue(str) {
 function buildRequest(command, flags, positional) {
     const id = 1
     const globalFlags = {}
-    for (const key of ['name', 'headless', 'json', 'cdp-url', 'channel', 'user-data-dir']) {
+    for (const key of ['name', 'headless', 'json', 'connect-url', 'channel', 'profile-dir']) {
         if (key in flags) {
             globalFlags[key] = flags[key]
             delete flags[key]
@@ -180,10 +180,10 @@ function isServerRunning() {
 function cleanStaleFiles() {
     try {
         unlinkSync(SOCKET_PATH)
-    } catch {}
+    } catch { }
     try {
         unlinkSync(PID_PATH)
-    } catch {}
+    } catch { }
 }
 
 function startServer() {
@@ -336,13 +336,18 @@ Utility:
 Global Flags:
   --name <namespace>        Storage namespace (default: "cli")
   --headless                Launch browser in headless mode
-  --cdp-url <url>           Connect to running Chrome via CDP (e.g. http://localhost:9222)
+  --connect-url <url>       Connect to a running browser (e.g. http://localhost:9222)
   --channel <browser>       Use installed browser (chrome, chrome-beta, msedge)
-  --user-data-dir <path>    Chrome profile directory for logged-in sessions
+  --profile-dir <path>      Browser profile directory for logged-in sessions
   --element <N>             Target element by counter
   --selector <css>          Target element by CSS selector
   --description <text>      Description for selector persistence
   --help                    Show this help
+
+Environment:
+  OPENSTEER_MODE            Runtime mode: "local" (default) or "remote"
+  OPENSTEER_API_KEY         Required when remote mode is selected
+  OPENSTEER_BASE_URL        Override remote control-plane base URL
 `)
 }