opensteer 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -4,23 +4,8 @@
 
 - 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`.
-- 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.
+- Cloud mode now falls back to `OPENSTEER_API_KEY` when `cloud.key` is omitted.
 
 ## 0.1.0
 

package/README.md

@@ -2,14 +2,11 @@
 
 Lean browser automation SDK for coding agents and script 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` wraps only operations that need descriptor resolution (`snapshot`,
+`click`, `dblclick`, `rightclick`, `hover`, `input`, `select`, `scroll`,
+`extract`, `extractFromPlan`, `state`).
 
-For anything not covered, use raw Playwright via `opensteer.page` and
-`opensteer.context`.
+Everything else is raw Playwright via `ov.page` and `ov.context`.
 
 ## Install
 
@@ -25,23 +22,23 @@ pnpm add opensteer playwright
 ```ts
 import { Opensteer } from "opensteer";
 
-const opensteer = new Opensteer({ name: "my-scraper" }); // defaults to model: 'gpt-5.1'
-await opensteer.launch({ headless: false });
+const ov = new Opensteer({ name: "my-scraper" }); // defaults to model: 'gpt-5.1'
+await ov.launch({ headless: false });
 
-await opensteer.goto("https://example.com");
-const html = await opensteer.snapshot();
+await ov.page.goto("https://example.com");
+const html = await ov.snapshot();
 
-await opensteer.click({ description: "login-button" });
-await opensteer.input({ description: "email", text: "user@example.com" });
-await opensteer.page.keyboard.press("Enter");
+await ov.click({ description: "login-button" });
+await ov.input({ description: "email", text: "user@example.com" });
+await ov.page.keyboard.press("Enter");
 
-await opensteer.close();
+await ov.close();
 ```
 
 ## Core Model
 
-- `opensteer.page`: raw Playwright `Page`
-- `opensteer.context`: raw Playwright `BrowserContext`
+- `ov.page`: raw Playwright `Page`
+- `ov.context`: raw Playwright `BrowserContext`
 - Opensteer methods: descriptor-aware operations that can persist selectors
 - Selector storage: `.opensteer/selectors/<namespace>`
 
@@ -57,60 +54,14 @@ 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 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" });
+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" });
 ```
 
 ## Two Usage Patterns
@@ -126,27 +77,16 @@ Opensteer uses built-in LLM resolve/extract by default. You can override the
 default model with top-level `model` or `OPENSTEER_MODEL`.
 
 ```ts
-const opensteer = new Opensteer({
+const ov = 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

@@ -1,22 +1,22 @@
 #!/usr/bin/env node
 
-import { spawn } from 'child_process'
-import { existsSync, readFileSync, readdirSync, unlinkSync } from 'fs'
 import { connect } from 'net'
-import { tmpdir } from 'os'
-import { basename, dirname, join } from 'path'
+import { spawn } from 'child_process'
+import { existsSync, readFileSync, unlinkSync, mkdirSync } from 'fs'
+import { join, dirname } from 'path'
+import { homedir } from 'os'
 import { fileURLToPath } from 'url'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
+
+const RUNTIME_DIR = join(homedir(), '.opensteer')
+const SOCKET_PATH = join(RUNTIME_DIR, 'opensteer.sock')
+const PID_PATH = join(RUNTIME_DIR, 'opensteer.pid')
 const SERVER_SCRIPT = join(__dirname, '..', 'dist', 'cli', 'server.js')
 
 const CONNECT_TIMEOUT = 15000
 const POLL_INTERVAL = 100
 const RESPONSE_TIMEOUT = 120000
-const RUNTIME_PREFIX = 'opensteer-'
-const SOCKET_SUFFIX = '.sock'
-const PID_SUFFIX = '.pid'
-const CLOSE_ALL_REQUEST = { id: 1, command: 'close', args: {} }
 
 function parseArgs(argv) {
     const args = argv.slice(2)
@@ -56,51 +56,10 @@ function parseValue(str) {
     return str
 }
 
-function sanitizeNamespace(value) {
-    const trimmed = String(value || '').trim()
-    if (!trimmed || trimmed === '.' || trimmed === '..') {
-        return 'default'
-    }
-
-    const replaced = trimmed.replace(/[^a-zA-Z0-9_-]+/g, '_')
-    const collapsed = replaced.replace(/_+/g, '_')
-    const bounded = collapsed.replace(/^_+|_+$/g, '')
-
-    return bounded || 'default'
-}
-
-function resolveNamespace(flags) {
-    if (flags.name !== undefined && String(flags.name).trim().length > 0) {
-        return sanitizeNamespace(String(flags.name))
-    }
-
-    if (
-        typeof process.env.OPENSTEER_NAME === 'string' &&
-        process.env.OPENSTEER_NAME.trim().length > 0
-    ) {
-        return sanitizeNamespace(process.env.OPENSTEER_NAME)
-    }
-
-    const cwdBase = basename(process.cwd())
-    if (cwdBase && cwdBase !== '.' && cwdBase !== '/') {
-        return sanitizeNamespace(cwdBase)
-    }
-
-    return 'default'
-}
-
-function getSocketPath(namespace) {
-    return join(tmpdir(), `${RUNTIME_PREFIX}${namespace}${SOCKET_SUFFIX}`)
-}
-
-function getPidPath(namespace) {
-    return join(tmpdir(), `${RUNTIME_PREFIX}${namespace}${PID_SUFFIX}`)
-}
-
 function buildRequest(command, flags, positional) {
     const id = 1
     const globalFlags = {}
-    for (const key of ['headless', 'json', 'connect-url', 'channel', 'profile-dir']) {
+    for (const key of ['name', 'headless', 'json', 'cdp-url', 'channel', 'user-data-dir']) {
         if (key in flags) {
             globalFlags[key] = flags[key]
             delete flags[key]
@@ -206,66 +165,38 @@ function buildRequest(command, flags, positional) {
     return { id, command, args }
 }
 
-function readPid(pidPath) {
-    if (!existsSync(pidPath)) {
-        return null
-    }
-
-    const parsed = Number.parseInt(readFileSync(pidPath, 'utf-8').trim(), 10)
-    if (!Number.isInteger(parsed) || parsed <= 0) {
-        return null
-    }
-
-    return parsed
-}
-
-function isPidAlive(pid) {
+function isServerRunning() {
+    if (!existsSync(PID_PATH)) return false
     try {
+        const pid = parseInt(readFileSync(PID_PATH, 'utf-8').trim(), 10)
         process.kill(pid, 0)
         return true
     } catch {
+        cleanStaleFiles()
         return false
     }
 }
 
-function cleanStaleFiles(namespace) {
+function cleanStaleFiles() {
     try {
-        unlinkSync(getSocketPath(namespace))
-    } catch { }
+        unlinkSync(SOCKET_PATH)
+    } catch {}
     try {
-        unlinkSync(getPidPath(namespace))
-    } catch { }
+        unlinkSync(PID_PATH)
+    } catch {}
 }
 
-function isServerRunning(namespace) {
-    const pidPath = getPidPath(namespace)
-    const pid = readPid(pidPath)
-    if (!pid) {
-        cleanStaleFiles(namespace)
-        return false
-    }
-
-    if (!isPidAlive(pid)) {
-        cleanStaleFiles(namespace)
-        return false
-    }
-
-    return existsSync(getSocketPath(namespace))
-}
+function startServer() {
+    mkdirSync(RUNTIME_DIR, { recursive: true })
 
-function startServer(namespace) {
     const child = spawn('node', [SERVER_SCRIPT], {
         detached: true,
         stdio: ['ignore', 'ignore', 'ignore'],
-        env: {
-            ...process.env,
-            OPENSTEER_NAME: namespace,
-        },
     })
     child.unref()
 }
 
-function waitForSocket(socketPath, timeout) {
+function waitForSocket(timeout) {
     return new Promise((resolve, reject) => {
         const start = Date.now()
 
@@ -275,7 +206,7 @@ function waitForSocket(socketPath, timeout) {
                 return
             }
 
-            if (existsSync(socketPath)) {
+            if (existsSync(SOCKET_PATH)) {
                 resolve()
                 return
             }
@@ -287,9 +218,9 @@ function waitForSocket(socketPath, timeout) {
     })
 }
 
-function sendCommand(socketPath, request) {
+function sendCommand(request) {
     return new Promise((resolve, reject) => {
-        const socket = connect(socketPath)
+        const socket = connect(SOCKET_PATH)
         let buffer = ''
         let settled = false
 
@@ -339,71 +270,6 @@ function sendCommand(socketPath, request) {
     })
 }
 
-function listSessions() {
-    const sessions = []
-    const entries = readdirSync(tmpdir())
-
-    for (const entry of entries) {
-        if (!entry.startsWith(RUNTIME_PREFIX) || !entry.endsWith(PID_SUFFIX)) {
-            continue
-        }
-
-        const name = entry.slice(
-            RUNTIME_PREFIX.length,
-            entry.length - PID_SUFFIX.length
-        )
-        if (!name) {
-            continue
-        }
-
-        const pid = readPid(join(tmpdir(), entry))
-        if (!pid || !isPidAlive(pid)) {
-            cleanStaleFiles(name)
-            continue
-        }
-
-        sessions.push({ name, pid })
-    }
-
-    sessions.sort((a, b) => a.name.localeCompare(b.name))
-    return sessions
-}
-
-async function closeAllSessions() {
-    const sessions = listSessions()
-    const closed = []
-    const failures = []
-
-    for (const session of sessions) {
-        const socketPath = getSocketPath(session.name)
-        if (!existsSync(socketPath)) {
-            cleanStaleFiles(session.name)
-            continue
-        }
-
-        try {
-            const response = await sendCommand(socketPath, CLOSE_ALL_REQUEST)
-            if (response && response.ok === true) {
-                closed.push(session)
-            } else {
-                failures.push(
-                    `${session.name}: ${response?.error || 'unknown close error'}`
-                )
-            }
-        } catch (err) {
-            failures.push(
-                `${session.name}: ${err instanceof Error ? err.message : String(err)}`
-            )
-        }
-    }
-
-    if (failures.length > 0) {
-        throw new Error(`Failed to close sessions: ${failures.join('; ')}`)
-    }
-
-    return closed
-}
-
 function output(data) {
     process.stdout.write(JSON.stringify(data) + '\n')
 }
@@ -423,10 +289,6 @@ Navigation:
   forward                   Go forward
   reload                    Reload page
   close                     Close browser and server
-  close --all               Close all active namespace-scoped servers
-
-Sessions:
-  sessions                  List active namespace-scoped sessions
 
 Observation:
   snapshot [--mode action]  Get page snapshot
@@ -472,64 +334,38 @@ Utility:
   extract <schema-json>     Extract structured data
 
 Global Flags:
-  --name <namespace>        Session namespace (default: CWD basename or OPENSTEER_NAME)
+  --name <namespace>        Storage namespace (default: "cli")
   --headless                Launch browser in headless mode
-  --connect-url <url>       Connect to a running browser (e.g. http://localhost:9222)
+  --cdp-url <url>           Connect to running Chrome via CDP (e.g. http://localhost:9222)
   --channel <browser>       Use installed browser (chrome, chrome-beta, msedge)
-  --profile-dir <path>      Browser profile directory for logged-in sessions
+  --user-data-dir <path>    Chrome 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_NAME            Default session namespace when --name is omitted
-  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
 `)
 }
 
 async function main() {
     const { command, flags, positional } = parseArgs(process.argv)
-    const namespace = resolveNamespace(flags)
-    const socketPath = getSocketPath(namespace)
-
-    if (command === 'sessions') {
-        output({ ok: true, sessions: listSessions() })
-        return
-    }
-
-    if (command === 'close' && flags.all === true) {
-        try {
-            const closed = await closeAllSessions()
-            output({ ok: true, closed })
-        } catch (err) {
-            error(err instanceof Error ? err.message : 'Failed to close sessions')
-        }
-        return
-    }
-
-    delete flags.name
-    delete flags.all
     const request = buildRequest(command, flags, positional)
 
-    if (!isServerRunning(namespace)) {
+    if (!isServerRunning()) {
         if (!existsSync(SERVER_SCRIPT)) {
             error(
                 `Server script not found: ${SERVER_SCRIPT}. Run the build script first.`
             )
         }
-        startServer(namespace)
+        startServer()
         try {
-            await waitForSocket(socketPath, CONNECT_TIMEOUT)
+            await waitForSocket(CONNECT_TIMEOUT)
         } catch {
             error('Failed to start server. Check that the build is complete.')
         }
     }
 
     try {
-        const response = await sendCommand(socketPath, request)
+        const response = await sendCommand(request)
 
         if (response.ok) {
             output({ ok: true, ...response.result })
@@ -540,7 +376,7 @@ async function main() {
             process.exit(1)
         }
     } catch (err) {
-        error(err instanceof Error ? err.message : 'Connection failed')
+        error(err.message || 'Connection failed')
     }
 }