opensteer 0.9.2 → 0.9.4

package/README.md

@@ -1,211 +1,204 @@
-# Opensteer
+<!-- This file is generated from the repository README. Run `node scripts/sync-package-readme.mjs`. -->
 
-`opensteer` is a browser-backed toolkit for agents exploring websites.
+<p align="center">
+  <strong>Opensteer</strong><br/>
+  <em>AI Browser Automation Framework</em>
+</p>
 
-It focuses on the parts normal code cannot do reliably on its own:
+<p align="center">
+  <a href="https://www.npmjs.com/package/opensteer"><img src="https://img.shields.io/npm/v/opensteer.svg" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/opensteer"><img src="https://img.shields.io/npm/dm/opensteer.svg" alt="npm downloads" /></a>
+  <a href="https://github.com/steerlabs/opensteer/blob/main/LICENSE"><img src="https://img.shields.io/github/license/steerlabs/opensteer.svg" alt="license" /></a>
+  <a href="https://github.com/steerlabs/opensteer/stargazers"><img src="https://img.shields.io/github/stars/steerlabs/opensteer.svg" alt="stars" /></a>
+</p>
 
-- capture real browser traffic from real browser actions
-- inspect captured requests without dumping huge raw payloads
-- replay requests with browser-grade transports
-- read browser cookies, storage, and page state
-- turn discoveries into plain TypeScript with `session.fetch()`
+<p align="center">
+  <a href="https://opensteer.com">Website</a> &middot;
+  <a href="https://docs.opensteer.com">Docs</a> &middot;
+  <a href="https://github.com/steerlabs/opensteer">GitHub</a> &middot;
+  <a href="https://discord.gg/opensteer">Discord</a>
+</p>
 
-The goal is discovery first, code second. The artifact should usually be working code, not a custom registry abstraction.
+---
+
+Open-source browser automation framework for AI agents. CLI and TypeScript SDK that give coding agents a real Chromium browser with persistent sessions, network capture, and stealth -- so they can browse, inspect, and generate scrapers directly in your codebase.
 
 ## Install
 
 ```bash
-pnpm add opensteer
-pnpm exec playwright install chromium
+npm i -g opensteer
+```
 
-# npm
-npm install opensteer
+Then install Chromium for Playwright:
+
+```bash
 npx playwright install chromium
 ```
 
-The package uses the Playwright-backed local engine by default.
+## Agent Quickstart
 
-## CLI Quickstart
+> **Using Claude Code, Codex, or Cursor?** Point your agent at Opensteer with a single command -- no manual setup needed.
 
 ```bash
-opensteer open https://example.com --workspace demo
-opensteer goto https://example.com/search --workspace demo --capture-network search
-opensteer network query --workspace demo --capture search
-opensteer network detail rec_123 --workspace demo
-opensteer replay rec_123 --workspace demo
-opensteer cookies example.com --workspace demo
-opensteer storage example.com --workspace demo
-opensteer state example.com --workspace demo
-opensteer close --workspace demo
+opensteer skills install
 ```
 
-For DOM exploration:
+This installs first-party skills that teach your AI agent how to use the Opensteer CLI and SDK. The agent can then open browsers, capture network traffic, extract structured data, and generate scrapers autonomously.
+
+Target specific agents:
 
 ```bash
+opensteer skills install --agent codex --agent cursor --agent claude-code
+```
+
+## Quickstart
+
+### CLI
+
+```bash
+# Open a page in a persistent workspace
+opensteer open https://example.com --workspace demo
+
+# Take a snapshot and list interactive elements
 opensteer snapshot action --workspace demo
-opensteer input 5 laptop --workspace demo --persist "search input" --capture-network search
-opensteer click 7 --workspace demo --persist "search button" --capture-network search
-opensteer snapshot extraction --workspace demo
-opensteer extract '{"title":{"element":3}}' --workspace demo --persist "page summary"
+
+# Click an element by its annotated index
+opensteer click 3 --workspace demo --persist "cta"
+
+# Extract structured data from the page
+opensteer extract '{"title":{"element":3}}' --workspace demo
+
+# Close the workspace
+opensteer close --workspace demo
 ```
 
-## SDK Quickstart
+### SDK
 
 ```ts
 import { Opensteer } from "opensteer";
 
-const opensteer = new Opensteer({
-  workspace: "demo",
-  rootDir: process.cwd(),
-});
+const opensteer = new Opensteer({ workspace: "demo", rootDir: process.cwd() });
 
 await opensteer.open("https://example.com");
-await opensteer.goto("https://example.com/search", {
-  captureNetwork: "search",
-});
+await opensteer.click({ persist: "cta" });
+const data = await opensteer.extract({ persist: "page summary" });
+await opensteer.close();
+```
 
-const records = await opensteer.network.query({
-  capture: "search",
-  json: true,
-});
+## Features
 
-const detail = await opensteer.network.detail(records.records[0]!.recordId, {
-  probe: true,
-});
+<table>
+<tr>
+<td width="50%">
 
-console.log(detail.summary.url);
-console.log(detail.transportProbe?.recommended);
-```
+### Persistent Sessions
 
-## `session.fetch()`
+Logins, cookies, and browser state survive across restarts. Each workspace is a full Chrome user-data directory.
 
-After discovery, write ordinary TypeScript using `fetch()` on the session.
+### Profile Cloning
 
-```ts
-import { Opensteer } from "opensteer";
+Clone a real Chrome profile to start a workspace already logged in. Source browser doesn't need to close.
 
-const opensteer = new Opensteer({
-  workspace: "target",
-  rootDir: process.cwd(),
-});
-
-async function ensureTargetSession() {
-  const cookies = await opensteer.cookies(".target.com");
-  if (cookies.has("visitorId")) {
-    return;
-  }
-  await opensteer.goto("https://target.com");
-}
-
-export async function searchTarget(keyword: string, count = 24) {
-  await ensureTargetSession();
-
-  const response = await opensteer.fetch(
-    "https://redsky.target.com/redsky_aggregations/v1/web/plp_search_v2",
-    {
-      query: {
-        keyword,
-        count,
-        offset: 0,
-        channel: "WEB",
-        platform: "desktop",
-      },
-    },
-  );
-
-  return response.json();
-}
-```
+### Network Capture
 
-Transport is selected automatically by default. Force it only when discovery showed a specific requirement:
+Record traffic during any action, inspect requests, and replay APIs with browser-backed `fetch()`.
 
-```ts
-const response = await opensteer.fetch("https://api.example.com/search", {
-  query: { keyword: "laptop" },
-  transport: "matched-tls",
-});
-```
+### Script Analysis
 
-## Browser State
+Capture, beautify, deobfuscate, and sandbox page JavaScript.
 
-Opensteer exposes the browser state agents need for request tracing:
+</td>
+<td width="50%">
 
-```ts
-const cookies = await opensteer.cookies("example.com");
-const localStorage = await opensteer.storage("example.com", "local");
-const sessionStorage = await opensteer.storage("example.com", "session");
-const state = await opensteer.state("example.com");
-```
+### Computer Use
 
-`cookies()` returns a lightweight cookie jar:
+Coordinate-based mouse and keyboard when DOM targeting isn't enough.
 
-```ts
-cookies.has("session");
-cookies.get("session");
-cookies.getAll();
-cookies.serialize();
-```
+### Stealth
 
-## DOM Automation
+Anti-detection defaults: UA spoofing, fingerprint management, automation signal removal.
 
-```ts
-await opensteer.click({ persist: "search button", captureNetwork: "search" });
-await opensteer.input({
-  persist: "search input",
-  text: "laptop",
-  pressEnter: true,
-  captureNetwork: "search",
-});
-
-const data = await opensteer.extract({
-  persist: "page summary",
-  schema: {
-    title: { selector: "title" },
-    url: { source: "current_url" },
-  },
-});
+### Local View
+
+Stream live screenshots from headless sessions to a browser-based viewer.
+
+### Local or Cloud
+
+Run browsers locally or on [Opensteer Cloud](https://opensteer.com). Same CLI, same SDK.
+
+</td>
+</tr>
+</table>
+
+## How It Works
+
+Opensteer follows a **discover-then-codify** workflow:
+
+1. **Capture** -- Open a real page, trigger actions, and record network traffic.
+2. **Inspect** -- Query captured traffic, check cookies/storage/state for auth context.
+3. **Probe** -- Test transport viability for captured requests before writing code.
+4. **Codify** -- Write plain TypeScript with `session.fetch()`. The code is the durable artifact.
+
+See the full [Workflow Guide](https://github.com/steerlabs/opensteer/blob/main/docs/workflows.md) for details.
+
+## Documentation
+
+| Resource                                           | Description                            |
+| -------------------------------------------------- | -------------------------------------- |
+| [Package Guide](https://github.com/steerlabs/opensteer/blob/main/packages/opensteer/README.md)    | Full CLI and SDK reference             |
+| [Workflow Guide](https://github.com/steerlabs/opensteer/blob/main/docs/workflows.md)              | Discover-then-codify methodology       |
+| [Instrumentation Guide](https://github.com/steerlabs/opensteer/blob/main/docs/instrumentation.md) | Tracing and observability              |
+| [Skills Guide](https://github.com/steerlabs/opensteer/blob/main/skills/README.md)                 | Agent skill installation and authoring |
+
+## FAQ
+
+<details>
+<summary><strong>Which AI agents are supported?</strong></summary>
+
+Opensteer ships first-party skills for [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview), [Codex](https://openai.com/index/introducing-codex/), [Cursor](https://www.cursor.com/), and any agent compatible with the [skills.sh](https://skills.sh) standard.
+
+</details>
+
+<details>
+<summary><strong>Do I need to install a browser separately?</strong></summary>
+
+Yes. After installing Opensteer, run `npx playwright install chromium` to download a compatible Chromium build. This is a one-time step.
+
+</details>
+
+<details>
+<summary><strong>Can I use my existing Chrome login sessions?</strong></summary>
+
+Yes. Use profile cloning to copy your real Chrome profile into an Opensteer workspace. Your logins, cookies, and extensions carry over without closing your main browser.
+
+</details>
+
+<details>
+<summary><strong>Does it work in headless mode?</strong></summary>
+
+Yes. Opensteer runs headless by default. Use the Local View feature to stream live screenshots from headless sessions to a browser-based viewer for debugging.
+
+</details>
+
+<details>
+<summary><strong>What Node.js version is required?</strong></summary>
+
+Node.js 22 or later.
+
+</details>
+
+## Development
+
+```bash
+pnpm install
+pnpm run build
+pnpm run typecheck
+pnpm run test
 ```
 
-Use `snapshot("action")` or `snapshot("extraction")` during exploration. The snapshot result is the filtered HTML string, not a huge raw DOM object.
-
-## Public SDK Surface
-
-- `new Opensteer({ workspace?, rootDir?, browser?, provider? })`
-- `open(url | input?)`
-- `info()`
-- `listPages()`
-- `newPage()`
-- `activatePage()`
-- `closePage()`
-- `goto(url, { captureNetwork? })`
-- `evaluate(script | input)`
-- `addInitScript(input)`
-- `snapshot("action" | "extraction")`
-- `click({ element? | selector? | persist?, captureNetwork? })`
-- `hover({ element? | selector? | persist?, captureNetwork? })`
-- `input({ text, element? | selector? | persist?, captureNetwork? })`
-- `scroll({ direction, amount, element? | selector? | persist?, captureNetwork? })`
-- `extract({ schema } | { persist, schema? })`
-- `network.query(input?)`
-- `network.detail(recordId, { probe?: boolean })`
-- `waitForPage(input?)`
-- `cookies(domain?)`
-- `storage(domain?, "local" | "session")`
-- `state(domain?)`
-- `fetch(url, options?)`
-- `computerExecute(input)`
-- `route(input)`
-- `interceptScript(input)`
-- `browser.status()`
-- `browser.clone(input)`
-- `browser.reset()`
-- `browser.delete()`
-- `close()`
-- `disconnect()`
-
-## Design Notes
-
-- `network query` is intentionally summary-oriented. Use `network detail` for deep inspection.
-- `replay` is transport-aware and should usually replace manual probe logic.
-- `browser status` intentionally does not leak the raw browser websocket endpoint.
-- The package also exports advanced cloud and browser-management utilities, but the core agent workflow is the local discovery-first SDK and CLI shown above.
+## Community
+
+- [Contributing](https://github.com/steerlabs/opensteer/blob/main/CONTRIBUTING.md)
+- [Code of Conduct](https://github.com/steerlabs/opensteer/blob/main/CODE_OF_CONDUCT.md)
+- [Security Policy](https://github.com/steerlabs/opensteer/blob/main/SECURITY.md)
+- [License](https://github.com/steerlabs/opensteer/blob/main/LICENSE) (MIT)

package/dist/{chunk-HD6KVZ42.js → chunk-GEUHKPC2.js}

@@ -1,5 +1,5 @@
-import { resolveFilesystemWorkspacePath, createFilesystemOpensteerWorkspace, DEFAULT_OPENSTEER_ENGINE, assertSupportedEngineOptions, OpensteerBrowserManager, normalizeObservabilityConfig, manifestToExternalBinaryLocation, normalizeObservationContext } from './chunk-2TIVULZY.js';
-import { canonicalJsonString, toCanonicalJsonValue, readPersistedCloudSessionRecord, writePersistedSessionRecord, clearPersistedSessionRecord, sha256Hex, resolveBrandUserDataDir, getBrowserBrand, detectInstalledBrowserBrands, __require } from './chunk-BMPUL66S.js';
+import { resolveFilesystemWorkspacePath, createFilesystemOpensteerWorkspace, DEFAULT_OPENSTEER_ENGINE, assertSupportedEngineOptions, OpensteerBrowserManager, normalizeObservabilityConfig, manifestToExternalBinaryLocation, normalizeObservationContext } from './chunk-GSCQQKZZ.js';
+import { canonicalJsonString, toCanonicalJsonValue, readPersistedCloudSessionRecord, writePersistedSessionRecord, clearPersistedSessionRecord, sha256Hex, resolveBrandUserDataDir, getBrowserBrand, detectInstalledBrowserBrands, __require } from './chunk-T5P2QGZ3.js';
 import { selectAll } from 'css-select';
 import { createHash, randomUUID, pbkdf2Sync, createDecipheriv } from 'crypto';
 import { existsSync, readFileSync } from 'fs';
@@ -3743,6 +3743,20 @@ var opensteerBrowserContextOptionsSchema = objectSchema(
       {
         title: "OpensteerStealthProfileInput"
       }
+    ),
+    humanize: oneOfSchema(
+      [
+        { type: "boolean" },
+        objectSchema(
+          {
+            mouse: { type: "boolean" },
+            keyboard: { type: "boolean" },
+            scroll: { type: "boolean" }
+          },
+          { title: "OpensteerHumanizeOptions" }
+        )
+      ],
+      { title: "OpensteerHumanize" }
     )
   },
   {
@@ -10594,7 +10608,7 @@ async function dispatchSemanticOperation(runtime, operation, input, options = {}
 
 // ../runtime-core/package.json
 var package_default = {
-  version: "0.2.2"};
+  version: "0.2.3"};
 
 // ../runtime-core/src/version.ts
 var OPENSTEER_RUNTIME_CORE_VERSION = package_default.version;
@@ -14410,6 +14424,7 @@ function diffInteractionTraces(left, right) {
 // ../runtime-core/src/sdk/runtime.ts
 var MUTATION_CAPTURE_FINALIZE_TIMEOUT_MS = 5e3;
 var PERSISTED_NETWORK_FLUSH_TIMEOUT_MS = 5e3;
+var PERSISTED_NETWORK_SETTLE_POLL_MS = 25;
 var PENDING_OPERATION_EVENT_CAPTURE_LIMIT = 64;
 var PENDING_OPERATION_EVENT_CAPTURE_SKEW_MS = 1e3;
 var REPLAY_PROBE_MIN_ATTEMPT_TIMEOUT_MS = 3e3;
@@ -17184,15 +17199,22 @@ var OpensteerSessionRuntime = class {
       return [];
     }
     const root = await this.ensureRoot();
-    const browserRecords = await this.readBrowserNetworkRecords(
-      {
-        includeBodies: true,
-        includeCurrentPageOnly: options.includeCurrentPageOnly,
-        ...options.pageRef === void 0 ? {} : { pageRef: options.pageRef },
-        requestIds
-      },
-      signal
-    );
+    let browserRecords = [];
+    for (; ; ) {
+      browserRecords = await this.readBrowserNetworkRecords(
+        {
+          includeBodies: true,
+          includeCurrentPageOnly: options.includeCurrentPageOnly,
+          ...options.pageRef === void 0 ? {} : { pageRef: options.pageRef },
+          requestIds
+        },
+        signal
+      );
+      if (browserRecords.length === requestIds.length && browserRecords.every((record) => record.captureState !== "pending")) {
+        break;
+      }
+      await delayWithSignal(PERSISTED_NETWORK_SETTLE_POLL_MS, signal);
+    }
     return this.networkHistory.persist(browserRecords, root.registry.savedNetwork, {
       bodyWriteMode: "authoritative",
       redactSecretHeaders: false
@@ -22300,8 +22322,10 @@ var OpensteerRuntime = class extends OpensteerSessionRuntime {
     super(
       buildSharedRuntimeOptions({
         name: publicWorkspace ?? "default",
+        ...options.rootDir === void 0 ? {} : { rootDir: options.rootDir },
         rootPath,
         ...publicWorkspace === void 0 ? {} : { workspaceName: publicWorkspace },
+        ...options.environment === void 0 ? {} : { environment: options.environment },
         ...options.browser === void 0 ? {} : { browser: options.browser },
         ...options.launch === void 0 ? {} : { launch: options.launch },
         ...options.context === void 0 ? {} : { context: options.context },
@@ -22332,7 +22356,9 @@ var OpensteerSessionRuntime2 = class extends OpensteerSessionRuntime {
     super(
       buildSharedRuntimeOptions({
         name: options.name,
+        ...options.rootDir === void 0 ? {} : { rootDir: options.rootDir },
         rootPath,
+        ...options.environment === void 0 ? {} : { environment: options.environment },
         ...options.browser === void 0 ? {} : { browser: options.browser },
         ...options.launch === void 0 ? {} : { launch: options.launch },
         ...options.context === void 0 ? {} : { context: options.context },
@@ -22353,9 +22379,11 @@ var OpensteerSessionRuntime2 = class extends OpensteerSessionRuntime {
 function buildSharedRuntimeOptions(input) {
   const ownership = resolveOwnership(input.browser);
   const engineFactory = input.engineFactory ?? ((factoryOptions) => new OpensteerBrowserManager({
+    ...input.rootDir === void 0 ? {} : { rootDir: input.rootDir },
     rootPath: input.rootPath,
     ...input.workspaceName === void 0 ? {} : { workspace: input.workspaceName },
     engineName: input.engineName,
+    ...input.environment === void 0 ? {} : { environment: input.environment },
     ...(factoryOptions.browser ?? input.browser) === void 0 ? {} : { browser: factoryOptions.browser ?? input.browser },
     ...(factoryOptions.launch ?? input.launch) === void 0 ? {} : { launch: factoryOptions.launch ?? input.launch },
     ...(factoryOptions.context ?? input.context) === void 0 ? {} : { context: factoryOptions.context ?? input.context }
@@ -22416,9 +22444,10 @@ function resolveOpensteerRuntimeConfig(input = {}) {
 function createOpensteerSemanticRuntime(input = {}) {
   const runtimeOptions = input.runtimeOptions ?? {};
   const engine = input.engine ?? runtimeOptions.engineName ?? DEFAULT_OPENSTEER_ENGINE;
+  const environment = input.environment ?? process.env;
   const config = resolveOpensteerRuntimeConfig({
     ...input.provider === void 0 ? {} : { provider: input.provider },
-    ...input.environment === void 0 ? {} : { environment: input.environment }
+    environment
   });
   assertProviderSupportsEngine(config.provider.mode, engine);
   if (config.provider.mode === "cloud") {
@@ -22433,10 +22462,11 @@ function createOpensteerSemanticRuntime(input = {}) {
   }
   return new OpensteerRuntime({
     ...runtimeOptions,
-    engineName: engine
+    engineName: engine,
+    environment
   });
 }
 
 export { CloudSessionProxy, DEFERRED_MATCH_ATTR_KEYS, ElementPathError, FlowRecorderCollector, MATCH_ATTRIBUTE_PRIORITY, OPENSTEER_DOM_ACTION_BRIDGE_SYMBOL, OpensteerCloudClient, OpensteerRuntime, OpensteerSessionRuntime2 as OpensteerSessionRuntime, STABLE_PRIMARY_ATTR_KEYS, assertProviderSupportsEngine, buildArrayFieldPathCandidates, buildDomDescriptorKey, buildDomDescriptorPayload, buildDomDescriptorVersion, buildPathCandidates, buildPathSelectorHint, buildSegmentSelector, cloneElementPath, cloneReplayElementPath, cloneStructuralElementAnchor, createDomDescriptorStore, createDomRuntime, createOpensteerExtractionDescriptorStore, createOpensteerSemanticRuntime, defaultFallbackPolicy, defaultPolicy, defaultRetryPolicy, defaultSettlePolicy, defaultTimeoutPolicy, delayWithSignal, dispatchSemanticOperation, generateReplayScript, hashDomDescriptorPersist, isCurrentUrlField, isValidCssAttributeKey, loadEnvironment, normalizeExtractedValue, normalizeOpensteerProviderMode, parseDomDescriptorRecord, parseExtractionDescriptorRecord, requireCloudAppBaseUrl, resolveCloudConfig, resolveDomActionBridge, resolveExtractedValueInContext, resolveOpensteerEnvironment, resolveOpensteerProvider, resolveOpensteerRuntimeConfig, runWithPolicyTimeout, sanitizeElementPath, sanitizeReplayElementPath, sanitizeStructuralElementAnchor, settleWithPolicy, shouldKeepAttributeForPath };
-//# sourceMappingURL=chunk-HD6KVZ42.js.map
-//# sourceMappingURL=chunk-HD6KVZ42.js.map
+//# sourceMappingURL=chunk-GEUHKPC2.js.map
+//# sourceMappingURL=chunk-GEUHKPC2.js.map