@steel-experiments/pi-steel 0.1.0 → 0.1.2
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/README.md +122 -73
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,45 +1,80 @@
|
|
|
1
|
-
# @steel-
|
|
1
|
+
# @steel-experiments/pi-steel
|
|
2
2
|
|
|
3
|
-
Steel
|
|
3
|
+
> **Steel Experiments** — This is where we ship early, break things, and explore what's next for browser agents. Experiments, prototypes, bleeding-edge demos, and community contributions that push the boundaries of what's possible with web automation. Not production-ready. Definitely interesting.
|
|
4
|
+
|
|
5
|
+
[Steel](https://steel.dev) browser automation tools for the [Pi](https://github.com/badlogic/pi-mono) coding agent.
|
|
4
6
|
|
|
5
7
|
This package publishes the Steel extension as a reusable Pi package so it can be installed directly into Pi or consumed by other runtimes such as Takopi-based wrappers.
|
|
6
8
|
|
|
7
|
-
##
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
9
|
+
## Quick start
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
pi install npm:@steel-experiments/pi-steel
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Then just ask Pi to browse:
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
> Go to hacker news and find the top story
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Pi will use `steel_navigate` to open the page, `steel_scrape` to read the content, and return what it finds. All session management happens automatically.
|
|
22
|
+
|
|
23
|
+
## Tools
|
|
24
|
+
|
|
25
|
+
### Navigation
|
|
26
|
+
|
|
27
|
+
| Tool | Description |
|
|
28
|
+
|------|-------------|
|
|
29
|
+
| `steel_navigate` | Open a URL with automatic scheme normalization and retry logic |
|
|
30
|
+
| `steel_go_back` | Navigate back in browser history |
|
|
31
|
+
| `steel_get_url` | Read the current page URL |
|
|
32
|
+
| `steel_get_title` | Read the current page title |
|
|
33
|
+
|
|
34
|
+
### Content extraction
|
|
35
|
+
|
|
36
|
+
| Tool | Description |
|
|
37
|
+
|------|-------------|
|
|
38
|
+
| `steel_scrape` | Extract page content as text, markdown, or html |
|
|
39
|
+
| `steel_screenshot` | Capture a screenshot artifact |
|
|
40
|
+
| `steel_pdf` | Generate a PDF artifact |
|
|
41
|
+
| `steel_extract` | Extract structured data using a JSON schema |
|
|
42
|
+
|
|
43
|
+
### Interaction
|
|
44
|
+
|
|
45
|
+
| Tool | Description |
|
|
46
|
+
|------|-------------|
|
|
47
|
+
| `steel_click` | Click an element with captcha recovery |
|
|
48
|
+
| `steel_type` | Type text into a field |
|
|
49
|
+
| `steel_fill_form` | Fill multiple form fields at once |
|
|
50
|
+
| `steel_scroll` | Scroll the page or a nested container |
|
|
51
|
+
| `steel_find_elements` | Find interactive elements by selector |
|
|
52
|
+
| `steel_wait` | Wait for an element to appear |
|
|
53
|
+
| `steel_computer` | Low-level computer action with screenshot |
|
|
54
|
+
|
|
55
|
+
### Session management
|
|
56
|
+
|
|
57
|
+
| Tool | Description |
|
|
58
|
+
|------|-------------|
|
|
59
|
+
| `steel_pin_session` | Keep the browser session alive across prompts |
|
|
60
|
+
| `steel_release_session` | Close the browser and reset to default session mode |
|
|
26
61
|
|
|
27
62
|
`steel_scrape` defaults to `text`. Ask for `markdown` when headings, lists, and links matter. Ask for `html` only when raw DOM markup is actually needed.
|
|
28
63
|
|
|
29
|
-
`steel_scroll` can scroll the page or a nested
|
|
64
|
+
`steel_scroll` can scroll the page or a nested container. For apps like Google Maps, pass a selector for the results pane instead of relying on window scrolling.
|
|
30
65
|
|
|
31
66
|
## Install
|
|
32
67
|
|
|
33
68
|
Install into Pi as a package:
|
|
34
69
|
|
|
35
70
|
```bash
|
|
36
|
-
pi install npm:@steel-
|
|
71
|
+
pi install npm:@steel-experiments/pi-steel
|
|
37
72
|
```
|
|
38
73
|
|
|
39
74
|
Or load it for a single run:
|
|
40
75
|
|
|
41
76
|
```bash
|
|
42
|
-
pi -e npm:@steel-
|
|
77
|
+
pi -e npm:@steel-experiments/pi-steel
|
|
43
78
|
```
|
|
44
79
|
|
|
45
80
|
For local development from this repo:
|
|
@@ -48,57 +83,83 @@ For local development from this repo:
|
|
|
48
83
|
pi -e .
|
|
49
84
|
```
|
|
50
85
|
|
|
51
|
-
|
|
86
|
+
## Session modes
|
|
87
|
+
|
|
88
|
+
Steel sessions have a lifecycle tied to how Pi uses them. The default works for most cases, but you can tune it:
|
|
89
|
+
|
|
90
|
+
| Mode | Behavior |
|
|
91
|
+
|------|----------|
|
|
92
|
+
| `agent` (default) | One session per Pi prompt, closed after `agent_end` |
|
|
93
|
+
| `session` | Session stays alive until Pi switches or shuts down |
|
|
94
|
+
| `turn` | Session closed after each Pi turn — aggressive, can break multi-step workflows |
|
|
95
|
+
|
|
96
|
+
Set the mode via environment variable:
|
|
52
97
|
|
|
53
98
|
```bash
|
|
54
|
-
STEEL_SESSION_MODE=session pi -e
|
|
99
|
+
STEEL_SESSION_MODE=session pi -e npm:@steel-experiments/pi-steel
|
|
55
100
|
```
|
|
56
101
|
|
|
57
|
-
|
|
102
|
+
You can also change session persistence at runtime with `steel_pin_session` and `steel_release_session`.
|
|
103
|
+
|
|
104
|
+
## Configuration
|
|
105
|
+
|
|
106
|
+
### Required
|
|
58
107
|
|
|
59
108
|
- Node.js 20+
|
|
60
109
|
- A Pi runtime that supports extensions
|
|
61
110
|
- Steel authentication via either:
|
|
62
111
|
- `STEEL_API_KEY`, or
|
|
63
112
|
- `steel login` config in `~/.config/steel/config.json`
|
|
64
|
-
- For self-hosted/local Steel, configure a custom base URL
|
|
65
|
-
|
|
66
|
-
Optional runtime configuration:
|
|
67
|
-
|
|
68
|
-
- `STEEL_BASE_URL`
|
|
69
|
-
- `STEEL_BROWSER_API_URL`
|
|
70
|
-
- `STEEL_LOCAL_API_URL`
|
|
71
|
-
- `STEEL_API_URL`
|
|
72
|
-
- `STEEL_CONFIG_DIR`
|
|
73
|
-
- `STEEL_SESSION_TIMEOUT_MS`
|
|
74
|
-
- `STEEL_TOOL_TIMEOUT_MS`
|
|
75
|
-
- `STEEL_SOLVE_CAPTCHA`
|
|
76
|
-
- `STEEL_USE_PROXY`
|
|
77
|
-
- `STEEL_PROXY_URL`
|
|
78
|
-
- `STEEL_SESSION_HEADLESS`
|
|
79
|
-
- `STEEL_SESSION_REGION`
|
|
80
|
-
- `STEEL_SESSION_PROFILE_ID`
|
|
81
|
-
- `STEEL_SESSION_PERSIST_PROFILE`
|
|
82
|
-
- `STEEL_SESSION_CREDENTIALS`
|
|
83
|
-
- `STEEL_SESSION_NAMESPACE`
|
|
84
|
-
- `STEEL_SESSION_MODE`
|
|
85
|
-
- `STEEL_CAPTCHA_MAX_RETRIES`
|
|
86
|
-
- `STEEL_CAPTCHA_WAIT_MS`
|
|
87
|
-
- `STEEL_CAPTCHA_POLL_INTERVAL_MS`
|
|
88
|
-
- `STEEL_NAVIGATE_RETRY_COUNT`
|
|
89
113
|
|
|
90
|
-
|
|
114
|
+
### Environment variables
|
|
115
|
+
|
|
116
|
+
**Connection**
|
|
117
|
+
|
|
118
|
+
| Variable | Purpose |
|
|
119
|
+
|----------|---------|
|
|
120
|
+
| `STEEL_BASE_URL` | Steel API base URL |
|
|
121
|
+
| `STEEL_BROWSER_API_URL` | Browser API endpoint |
|
|
122
|
+
| `STEEL_LOCAL_API_URL` | Local Steel instance URL |
|
|
123
|
+
| `STEEL_API_URL` | Alternative API URL |
|
|
124
|
+
| `STEEL_CONFIG_DIR` | Custom config directory |
|
|
125
|
+
|
|
126
|
+
**Session**
|
|
91
127
|
|
|
92
|
-
|
|
128
|
+
| Variable | Purpose |
|
|
129
|
+
|----------|---------|
|
|
130
|
+
| `STEEL_SESSION_MODE` | Lifecycle mode: `agent`, `session`, or `turn` |
|
|
131
|
+
| `STEEL_SESSION_TIMEOUT_MS` | Session timeout |
|
|
132
|
+
| `STEEL_SESSION_HEADLESS` | Run browser headless |
|
|
133
|
+
| `STEEL_SESSION_REGION` | Browser region |
|
|
134
|
+
| `STEEL_SESSION_PROFILE_ID` | Persistent browser profile |
|
|
135
|
+
| `STEEL_SESSION_PERSIST_PROFILE` | Save profile changes |
|
|
136
|
+
| `STEEL_SESSION_CREDENTIALS` | Session credentials |
|
|
137
|
+
| `STEEL_SESSION_NAMESPACE` | Session namespace |
|
|
93
138
|
|
|
94
|
-
|
|
95
|
-
- `STEEL_SESSION_MODE=session` keeps the same Steel session alive until Pi switches or shuts down the current session.
|
|
96
|
-
- `STEEL_SESSION_MODE=turn` closes the Steel session after each Pi turn. This is more aggressive and can break workflows that need multiple tool rounds inside one prompt.
|
|
139
|
+
**Proxy**
|
|
97
140
|
|
|
98
|
-
|
|
141
|
+
| Variable | Purpose |
|
|
142
|
+
|----------|---------|
|
|
143
|
+
| `STEEL_USE_PROXY` | Enable proxy |
|
|
144
|
+
| `STEEL_PROXY_URL` | Proxy URL |
|
|
99
145
|
|
|
100
|
-
|
|
101
|
-
|
|
146
|
+
**Captcha**
|
|
147
|
+
|
|
148
|
+
| Variable | Purpose |
|
|
149
|
+
|----------|---------|
|
|
150
|
+
| `STEEL_SOLVE_CAPTCHA` | Enable captcha solving |
|
|
151
|
+
| `STEEL_CAPTCHA_MAX_RETRIES` | Max captcha retry attempts |
|
|
152
|
+
| `STEEL_CAPTCHA_WAIT_MS` | Captcha solve wait time |
|
|
153
|
+
| `STEEL_CAPTCHA_POLL_INTERVAL_MS` | Captcha poll interval |
|
|
154
|
+
|
|
155
|
+
**Tools**
|
|
156
|
+
|
|
157
|
+
| Variable | Purpose |
|
|
158
|
+
|----------|---------|
|
|
159
|
+
| `STEEL_TOOL_TIMEOUT_MS` | Default tool timeout |
|
|
160
|
+
| `STEEL_NAVIGATE_RETRY_COUNT` | Navigation retry attempts |
|
|
161
|
+
|
|
162
|
+
`pi-steel` reads Steel CLI config for auth and local API resolution, and it normalizes CLI-style API URLs such as `http://localhost:3000/v1` to the SDK-compatible base URL form.
|
|
102
163
|
|
|
103
164
|
## Development
|
|
104
165
|
|
|
@@ -114,16 +175,4 @@ Publish preflight:
|
|
|
114
175
|
npm pack --dry-run
|
|
115
176
|
```
|
|
116
177
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
This repo is a Pi package. The package manifest in `package.json` exposes the compiled extension entrypoint:
|
|
120
|
-
|
|
121
|
-
```json
|
|
122
|
-
{
|
|
123
|
-
"pi": {
|
|
124
|
-
"extensions": ["./dist/index.js"]
|
|
125
|
-
}
|
|
126
|
-
}
|
|
127
|
-
```
|
|
128
|
-
|
|
129
|
-
That lets Pi load the package root directly after `pi install npm:@steel-dev/pi-steel`.
|
|
178
|
+
The package manifest in `package.json` exposes the compiled extension entrypoint via `pi.extensions`, which lets Pi load the package root directly after install.
|