opensteer 0.4.10 → 0.4.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +5 -0
- package/README.md +70 -141
- package/bin/opensteer.mjs +1 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -36,6 +36,11 @@
|
|
|
36
36
|
timeout/stale-target cases more accurately.
|
|
37
37
|
- Cloud action failures now accept optional structured failure details and map
|
|
38
38
|
them to `OpensteerActionError` when available.
|
|
39
|
+
- Docs: refreshed README and getting-started guidance to match current SDK/CLI
|
|
40
|
+
behavior and env vars.
|
|
41
|
+
- Docs: added CLI reference and docs index.
|
|
42
|
+
- OSS community docs: expanded `CONTRIBUTING.md` and added `SECURITY.md` +
|
|
43
|
+
`SUPPORT.md`.
|
|
39
44
|
|
|
40
45
|
## 0.1.0
|
|
41
46
|
|
package/README.md
CHANGED
|
@@ -1,186 +1,115 @@
|
|
|
1
1
|
# Opensteer
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Open-source browser automation SDK for coding agents and deterministic replay.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
`extractFromPlan`, `uploadFile`), observation (`snapshot`, `state`,
|
|
8
|
-
`screenshot`), navigation (`goto`), and convenience methods for tabs, cookies,
|
|
9
|
-
keyboard, element info, and wait.
|
|
5
|
+
Opensteer combines descriptor-aware actions, resilient selector persistence,
|
|
6
|
+
clean HTML snapshots, and first-class local or cloud runtime support.
|
|
10
7
|
|
|
11
|
-
|
|
12
|
-
|
|
8
|
+
## Requirements
|
|
9
|
+
|
|
10
|
+
- Node.js `>=20`
|
|
11
|
+
- A browser environment supported by Playwright
|
|
12
|
+
- API key for your selected model provider if you use LLM resolve/extract
|
|
13
13
|
|
|
14
14
|
## Install
|
|
15
15
|
|
|
16
16
|
```bash
|
|
17
17
|
# npm
|
|
18
|
-
npm install opensteer
|
|
18
|
+
npm install opensteer
|
|
19
19
|
# pnpm
|
|
20
|
-
pnpm add opensteer
|
|
20
|
+
pnpm add opensteer
|
|
21
21
|
```
|
|
22
22
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
OpenSteer CLI now separates runtime routing from selector caching:
|
|
26
|
-
|
|
27
|
-
- Runtime routing: `--session` or `OPENSTEER_SESSION`
|
|
28
|
-
- Selector cache namespace: `--name` or `OPENSTEER_NAME` (used on `open`)
|
|
29
|
-
|
|
30
|
-
If neither `--session` nor `OPENSTEER_SESSION` is set:
|
|
31
|
-
|
|
32
|
-
- In an interactive terminal, OpenSteer creates/reuses a terminal-scoped default session.
|
|
33
|
-
- In non-interactive environments (agents/CI), it fails fast unless you set
|
|
34
|
-
`OPENSTEER_SESSION` or `OPENSTEER_CLIENT_ID`.
|
|
35
|
-
|
|
36
|
-
Example:
|
|
23
|
+
If your environment skips Playwright browser downloads, run:
|
|
37
24
|
|
|
38
25
|
```bash
|
|
39
|
-
|
|
40
|
-
opensteer open https://example.com --name product-scraper
|
|
41
|
-
opensteer snapshot
|
|
42
|
-
opensteer click 3
|
|
43
|
-
opensteer status
|
|
26
|
+
npx playwright install chromium
|
|
44
27
|
```
|
|
45
28
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
## Quickstart
|
|
29
|
+
## Quickstart (SDK)
|
|
49
30
|
|
|
50
31
|
```ts
|
|
51
32
|
import { Opensteer } from "opensteer";
|
|
52
33
|
|
|
53
|
-
const opensteer = new Opensteer({ name: "my-scraper" });
|
|
34
|
+
const opensteer = new Opensteer({ name: "my-scraper" });
|
|
54
35
|
await opensteer.launch({ headless: false });
|
|
55
36
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
await opensteer.input({ description: "email", text: "user@example.com" });
|
|
61
|
-
await opensteer.page.keyboard.press("Enter");
|
|
62
|
-
|
|
63
|
-
await opensteer.close();
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
## Core Model
|
|
67
|
-
|
|
68
|
-
- `opensteer.page`: raw Playwright `Page`
|
|
69
|
-
- `opensteer.context`: raw Playwright `BrowserContext`
|
|
70
|
-
- Opensteer methods: descriptor-aware operations that can persist selectors
|
|
71
|
-
- Selector storage: `.opensteer/selectors/<namespace>`
|
|
72
|
-
|
|
73
|
-
## Resolution Chain
|
|
74
|
-
|
|
75
|
-
For actions like `click`/`input`/`hover`/`select`/`scroll`:
|
|
76
|
-
|
|
77
|
-
1. Use persisted path for `description` (if present)
|
|
78
|
-
2. Use `element` counter from snapshot
|
|
79
|
-
3. Use explicit CSS `selector`
|
|
80
|
-
4. Use built-in LLM resolution (`description` required)
|
|
81
|
-
5. Throw
|
|
82
|
-
|
|
83
|
-
When steps 2-4 resolve and `description` is provided, the path is persisted.
|
|
84
|
-
|
|
85
|
-
## Smart Post-Action Wait
|
|
86
|
-
|
|
87
|
-
Mutating actions (`click`, `input`, `select`, `scroll`, etc.) include a
|
|
88
|
-
best-effort post-action wait so delayed visual updates are usually settled
|
|
89
|
-
before the method resolves.
|
|
90
|
-
|
|
91
|
-
You can disable or tune this per call:
|
|
92
|
-
|
|
93
|
-
```ts
|
|
94
|
-
await opensteer.click({ description: "Save button", wait: false });
|
|
37
|
+
try {
|
|
38
|
+
await opensteer.goto("https://example.com");
|
|
39
|
+
const html = await opensteer.snapshot();
|
|
40
|
+
console.log(html.slice(0, 500));
|
|
95
41
|
|
|
96
|
-
await opensteer.click({
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
}
|
|
42
|
+
await opensteer.click({ description: "main call to action", element: 3 });
|
|
43
|
+
} finally {
|
|
44
|
+
await opensteer.close();
|
|
45
|
+
}
|
|
100
46
|
```
|
|
101
47
|
|
|
102
|
-
##
|
|
103
|
-
|
|
104
|
-
Descriptor-aware interaction methods (`click`, `dblclick`, `rightclick`,
|
|
105
|
-
`hover`, `input`, `select`, `scroll`, `uploadFile`) throw
|
|
106
|
-
`OpensteerActionError` when an interaction cannot be completed.
|
|
107
|
-
|
|
108
|
-
The error includes structured failure metadata for agent/tooling decisions:
|
|
48
|
+
## Quickstart (CLI)
|
|
109
49
|
|
|
110
|
-
|
|
111
|
-
- `error.failure.message`
|
|
112
|
-
- `error.failure.retryable`
|
|
113
|
-
- `error.failure.classificationSource`
|
|
114
|
-
- `error.failure.details` (for blocker and observation details when available)
|
|
115
|
-
|
|
116
|
-
```ts
|
|
117
|
-
import { Opensteer, OpensteerActionError } from "opensteer";
|
|
118
|
-
|
|
119
|
-
try {
|
|
120
|
-
await opensteer.click({ description: "Save button" });
|
|
121
|
-
} catch (err) {
|
|
122
|
-
if (err instanceof OpensteerActionError) {
|
|
123
|
-
console.error(err.failure.code); // e.g. BLOCKED_BY_INTERCEPTOR
|
|
124
|
-
console.error(err.failure.message);
|
|
125
|
-
console.error(err.failure.classificationSource);
|
|
126
|
-
}
|
|
127
|
-
throw err;
|
|
128
|
-
}
|
|
129
|
-
```
|
|
50
|
+
Opensteer CLI separates runtime routing from selector namespace routing.
|
|
130
51
|
|
|
131
|
-
|
|
52
|
+
- Runtime routing: `--session` or `OPENSTEER_SESSION`
|
|
53
|
+
- Selector namespace: `--name` or `OPENSTEER_NAME` (used by `open`)
|
|
132
54
|
|
|
133
|
-
```
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
55
|
+
```bash
|
|
56
|
+
opensteer open https://example.com --session agent-a --name product-scraper
|
|
57
|
+
opensteer snapshot --session agent-a
|
|
58
|
+
opensteer click 3 --session agent-a
|
|
59
|
+
opensteer status --session agent-a
|
|
60
|
+
opensteer close --session agent-a
|
|
139
61
|
```
|
|
140
62
|
|
|
141
|
-
|
|
63
|
+
In non-interactive environments, set `OPENSTEER_SESSION` or
|
|
64
|
+
`OPENSTEER_CLIENT_ID` explicitly.
|
|
142
65
|
|
|
143
|
-
|
|
66
|
+
## Resolution and Replay Model
|
|
144
67
|
|
|
145
|
-
|
|
146
|
-
stable descriptions for replay.
|
|
68
|
+
For descriptor-aware actions (`click`, `input`, `hover`, `select`, `scroll`):
|
|
147
69
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
70
|
+
1. Reuse persisted path for `description`
|
|
71
|
+
2. Use `element` counter from snapshot
|
|
72
|
+
3. Use explicit CSS `selector`
|
|
73
|
+
4. Use built-in LLM resolution (`description` required)
|
|
74
|
+
5. Throw actionable error
|
|
152
75
|
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
name: "run-mode",
|
|
156
|
-
model: "gpt-5-mini",
|
|
157
|
-
});
|
|
158
|
-
```
|
|
76
|
+
When steps 2-4 succeed and `description` is present, Opensteer persists the
|
|
77
|
+
path for deterministic replay in `.opensteer/selectors/<namespace>`.
|
|
159
78
|
|
|
160
|
-
## Mode
|
|
79
|
+
## Cloud Mode
|
|
161
80
|
|
|
162
81
|
Opensteer defaults to local mode.
|
|
163
82
|
|
|
164
|
-
- `OPENSTEER_MODE=local`
|
|
165
|
-
- `
|
|
166
|
-
- `
|
|
167
|
-
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
- Existing `process.env` values are never overwritten by `.env` values.
|
|
171
|
-
- Set `OPENSTEER_DISABLE_DOTENV_AUTOLOAD=true` to disable auto-loading.
|
|
83
|
+
- `OPENSTEER_MODE=local|cloud`
|
|
84
|
+
- `OPENSTEER_API_KEY` or `cloud.apiKey` required in cloud mode
|
|
85
|
+
- `OPENSTEER_BASE_URL` or `cloud.baseUrl` to override the default cloud host
|
|
86
|
+
- `OPENSTEER_AUTH_SCHEME` or `cloud.authScheme` for auth header mode
|
|
87
|
+
(`api-key` or `bearer`)
|
|
88
|
+
- `cloud: true` or a `cloud` options object overrides `OPENSTEER_MODE`
|
|
172
89
|
|
|
173
|
-
|
|
90
|
+
`.env` files are auto-loaded from `storage.rootDir` (default `process.cwd()`)
|
|
91
|
+
in this order: `.env.<NODE_ENV>.local`, `.env.local` (except in test),
|
|
92
|
+
`.env.<NODE_ENV>`, `.env`. Existing `process.env` values are not overwritten.
|
|
93
|
+
Set `OPENSTEER_DISABLE_DOTENV_AUTOLOAD=true` to disable.
|
|
174
94
|
|
|
175
95
|
## Docs
|
|
176
96
|
|
|
177
|
-
-
|
|
178
|
-
-
|
|
179
|
-
-
|
|
180
|
-
-
|
|
181
|
-
-
|
|
182
|
-
-
|
|
97
|
+
- [Getting Started](docs/getting-started.md)
|
|
98
|
+
- [API Reference](docs/api-reference.md)
|
|
99
|
+
- [CLI Reference](docs/cli-reference.md)
|
|
100
|
+
- [Cloud Integration](docs/cloud-integration.md)
|
|
101
|
+
- [Selectors and Storage](docs/selectors.md)
|
|
102
|
+
- [HTML Cleaning and Snapshot Modes](docs/html-cleaning.md)
|
|
103
|
+
- [Live Web Validation Suite](docs/live-web-tests.md)
|
|
104
|
+
|
|
105
|
+
## Community
|
|
106
|
+
|
|
107
|
+
- [Contributing Guide](CONTRIBUTING.md)
|
|
108
|
+
- [Code of Conduct](CODE_OF_CONDUCT.md)
|
|
109
|
+
- [Security Policy](SECURITY.md)
|
|
110
|
+
- [Support](SUPPORT.md)
|
|
111
|
+
- [Changelog](CHANGELOG.md)
|
|
183
112
|
|
|
184
113
|
## License
|
|
185
114
|
|
|
186
|
-
MIT
|
|
115
|
+
[MIT](LICENSE)
|
package/bin/opensteer.mjs
CHANGED
|
@@ -781,6 +781,7 @@ Environment:
|
|
|
781
781
|
OPENSTEER_MODE Runtime routing: "local" (default) or "cloud"
|
|
782
782
|
OPENSTEER_API_KEY Required when cloud mode is selected
|
|
783
783
|
OPENSTEER_BASE_URL Override cloud control-plane base URL
|
|
784
|
+
OPENSTEER_AUTH_SCHEME Cloud auth scheme: api-key (default) or bearer
|
|
784
785
|
OPENSTEER_REMOTE_ANNOUNCE Cloud session announcement policy: always (default), off, tty
|
|
785
786
|
`)
|
|
786
787
|
}
|