opensteer 0.4.1 → 0.4.3

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

@@ -1,22 +1,32 @@
 #!/usr/bin/env node
 
-import { connect } from 'net'
+import { createHash } from 'crypto'
 import { spawn } from 'child_process'
-import { existsSync, readFileSync, unlinkSync, mkdirSync } from 'fs'
-import { join, dirname } from 'path'
-import { homedir } from 'os'
+import { existsSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'fs'
+import { connect } from 'net'
+import { tmpdir } from 'os'
+import { basename, dirname, join } from 'path'
 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 getVersion() {
+    try {
+        const pkgPath = join(__dirname, '..', 'package.json')
+        return JSON.parse(readFileSync(pkgPath, 'utf-8')).version
+    } catch {
+        return 'unknown'
+    }
+}
 
 function parseArgs(argv) {
     const args = argv.slice(2)
@@ -25,6 +35,11 @@ function parseArgs(argv) {
         process.exit(0)
     }
 
+    if (args[0] === '--version' || args[0] === '-v') {
+        console.log(getVersion())
+        process.exit(0)
+    }
+
     const command = args[0]
     const flags = {}
     const positional = []
@@ -56,10 +71,78 @@ 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 getActiveNamespacePath() {
+    const hash = createHash('md5').update(process.cwd()).digest('hex').slice(0, 16)
+    return join(tmpdir(), `${RUNTIME_PREFIX}active-${hash}`)
+}
+
+function readActiveNamespace() {
+    try {
+        const filePath = getActiveNamespacePath()
+        if (!existsSync(filePath)) return null
+        const ns = readFileSync(filePath, 'utf-8').trim()
+        return ns || null
+    } catch {
+        return null
+    }
+}
+
+function writeActiveNamespace(namespace) {
+    try {
+        writeFileSync(getActiveNamespacePath(), namespace)
+    } catch { /* best-effort */ }
+}
+
+function resolveNamespace(flags) {
+    if (flags.name !== undefined && String(flags.name).trim().length > 0) {
+        return { namespace: sanitizeNamespace(String(flags.name)), source: 'flag' }
+    }
+
+    if (
+        typeof process.env.OPENSTEER_NAME === 'string' &&
+        process.env.OPENSTEER_NAME.trim().length > 0
+    ) {
+        return { namespace: sanitizeNamespace(process.env.OPENSTEER_NAME), source: 'env' }
+    }
+
+    const active = readActiveNamespace()
+    if (active && isServerRunning(active)) {
+        return { namespace: active, source: 'active' }
+    }
+
+    const cwdBase = basename(process.cwd())
+    if (cwdBase && cwdBase !== '.' && cwdBase !== '/') {
+        return { namespace: sanitizeNamespace(cwdBase), source: 'cwd' }
+    }
+
+    return { namespace: 'default', source: '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 ['name', 'headless', 'json', 'cdp-url', 'channel', 'user-data-dir']) {
+    for (const key of ['headless', 'json', 'connect-url', 'channel', 'profile-dir']) {
         if (key in flags) {
             globalFlags[key] = flags[key]
             delete flags[key]
@@ -165,38 +248,66 @@ function buildRequest(command, flags, positional) {
     return { id, command, args }
 }
 
-function isServerRunning() {
-    if (!existsSync(PID_PATH)) return false
+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) {
     try {
-        const pid = parseInt(readFileSync(PID_PATH, 'utf-8').trim(), 10)
         process.kill(pid, 0)
         return true
     } catch {
-        cleanStaleFiles()
         return false
     }
 }
 
-function cleanStaleFiles() {
+function cleanStaleFiles(namespace) {
     try {
-        unlinkSync(SOCKET_PATH)
-    } catch {}
+        unlinkSync(getSocketPath(namespace))
+    } catch { }
     try {
-        unlinkSync(PID_PATH)
-    } catch {}
+        unlinkSync(getPidPath(namespace))
+    } catch { }
 }
 
-function startServer() {
-    mkdirSync(RUNTIME_DIR, { recursive: true })
+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(namespace) {
     const child = spawn('node', [SERVER_SCRIPT], {
         detached: true,
         stdio: ['ignore', 'ignore', 'ignore'],
+        env: {
+            ...process.env,
+            OPENSTEER_NAME: namespace,
+        },
     })
     child.unref()
 }
 
-function waitForSocket(timeout) {
+function waitForSocket(socketPath, timeout) {
     return new Promise((resolve, reject) => {
         const start = Date.now()
 
@@ -206,7 +317,7 @@ function waitForSocket(timeout) {
                 return
             }
 
-            if (existsSync(SOCKET_PATH)) {
+            if (existsSync(socketPath)) {
                 resolve()
                 return
             }
@@ -218,9 +329,9 @@ function waitForSocket(timeout) {
     })
 }
 
-function sendCommand(request) {
+function sendCommand(socketPath, request) {
     return new Promise((resolve, reject) => {
-        const socket = connect(SOCKET_PATH)
+        const socket = connect(socketPath)
         let buffer = ''
         let settled = false
 
@@ -270,6 +381,71 @@ function sendCommand(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')
 }
@@ -289,6 +465,11 @@ 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
+  status                    Show resolved namespace and session state
 
 Observation:
   snapshot [--mode action]  Get page snapshot
@@ -334,40 +515,87 @@ Utility:
   extract <schema-json>     Extract structured data
 
 Global Flags:
-  --name <namespace>        Storage namespace (default: "cli")
+  --name <namespace>        Session namespace (default: CWD basename or OPENSTEER_NAME)
   --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
+  --version, -v             Show version
+
+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, source: namespaceSource } = resolveNamespace(flags)
+    const socketPath = getSocketPath(namespace)
+
+    if (command === 'sessions') {
+        output({ ok: true, sessions: listSessions() })
+        return
+    }
+
+    if (command === 'status') {
+        output({
+            ok: true,
+            namespace,
+            namespaceSource,
+            serverRunning: isServerRunning(namespace),
+            socketPath,
+            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()) {
+    if (!isServerRunning(namespace)) {
+        if (command !== 'open') {
+            error(
+                `No server running for namespace '${namespace}' (resolved from ${namespaceSource}). Run 'opensteer open' first or use 'opensteer sessions' to see active sessions.`
+            )
+        }
         if (!existsSync(SERVER_SCRIPT)) {
             error(
                 `Server script not found: ${SERVER_SCRIPT}. Run the build script first.`
             )
         }
-        startServer()
+        startServer(namespace)
         try {
-            await waitForSocket(CONNECT_TIMEOUT)
+            await waitForSocket(socketPath, CONNECT_TIMEOUT)
         } catch {
             error('Failed to start server. Check that the build is complete.')
         }
     }
 
     try {
-        const response = await sendCommand(request)
+        const response = await sendCommand(socketPath, request)
 
         if (response.ok) {
+            if (command === 'open') {
+                writeActiveNamespace(namespace)
+            }
             output({ ok: true, ...response.result })
         } else {
             process.stderr.write(
@@ -376,7 +604,7 @@ async function main() {
             process.exit(1)
         }
     } catch (err) {
-        error(err.message || 'Connection failed')
+        error(err instanceof Error ? err.message : 'Connection failed')
     }
 }