opensteer 0.7.1 → 0.8.2

package/skills/opensteer/SKILL.md

@@ -1,90 +1,51 @@
 ---
 name: opensteer
-description: "Browser automation, scraping, structured extraction, and browser-backed API reverse engineering with the Opensteer CLI and SDK. Use when a task needs to open pages, interact with elements, capture network traffic, write request plans, or turn a browser workflow into reusable code."
+description: "Handles Opensteer browser automation, structured DOM extraction, and browser-backed request replay with the Opensteer CLI and SDK. Use when the user mentions Opensteer, browser automation, real Chromium sessions, persistent workspace browser state, descriptor-backed DOM actions or extraction, request plans, recipes, or browser-backed API replay."
+argument-hint: "[goal]"
 ---
 
 # Opensteer
 
-Use this skill when a task needs a real browser workflow, structured extraction, or browser-backed replay.
+If invoked directly, treat `$ARGUMENTS` as the concrete browser or replay goal. First decide whether the task is primarily DOM automation, request capture/replay, or workspace browser administration.
 
-Choose the reference that matches the job:
-
-- CLI exploration: [references/cli-reference.md](references/cli-reference.md)
-- SDK automation: [references/sdk-reference.md](references/sdk-reference.md)
-- Request capture and replay: [references/request-workflow.md](references/request-workflow.md)
-
-## Default Workflow
-
-1. Start with the CLI when you need to explore a site, inspect state, or prove the workflow on a real page.
-2. Re-snapshot after each meaningful page or DOM change before reusing counters.
-3. Add `--description` when you want selector persistence and later replay.
-4. Move to the SDK when the workflow should become reusable code in the repository.
-5. Move to request capture and request plans when the real target is a browser-backed API.
-
-## CLI Exploration
-
-```bash
-opensteer open https://example.com --name my-workflow
-opensteer snapshot action --name my-workflow
-opensteer click 3 --name my-workflow --description "primary button"
-opensteer snapshot extraction --name my-workflow
-opensteer extract --name my-workflow \
-  --description "page summary" \
-  --schema '{"title":{"selector":"title"},"url":{"source":"current_url"}}'
-opensteer close --name my-workflow
-```
+Use this skill when a task needs a real browser workflow, persistent workspace browser state, structured DOM extraction, or browser-backed request replay.
 
-Rules:
-
-- Use `opensteer open` once to create the session, then use `goto`, actions, snapshots, and extraction against the same `--name`.
-- Treat counter targets as snapshot-local. Always take a fresh `snapshot action` before reusing counters after the page changes.
-- Use `snapshot extraction` plus `extract` for structured data. Do not treat snapshot HTML as the final data source.
-- Use `--description` whenever the action or extraction should be replayable later.
-
-## SDK Automation
-
-```ts
-import { Opensteer } from "opensteer";
-
-const opensteer = new Opensteer({
-  name: "my-workflow",
-  rootDir: process.cwd(),
-  browser: { headless: true },
-});
+Choose the reference that matches the job:
 
-try {
-  await opensteer.open("https://example.com");
-  await opensteer.snapshot("action");
+- CLI exploration and browser admin: [references/cli-reference.md](references/cli-reference.md)
+- SDK automation and reusable code: [references/sdk-reference.md](references/sdk-reference.md)
+- Request capture, plans, and recipes: [references/request-workflow.md](references/request-workflow.md)
 
-  const data = await opensteer.extract({
-    description: "page summary",
-    schema: {
-      title: { selector: "title" },
-      url: { source: "current_url" },
-    },
-  });
+## Startup Checks
 
-  console.log(data);
-} finally {
-  await opensteer.close();
-}
-```
+- Verify `opensteer` is available in the repo or on `PATH` before planning the workflow.
+- If Chromium binaries are missing, install them through Playwright before debugging page behavior.
+- Reuse an existing workspace id for the same site or feature when one already exists.
 
-Rules:
+## Mental Model
 
-- Wrap owned sessions in `try/finally` and call `close()`.
-- Use `Opensteer.attach(...)` plus `disconnect()` when you are attaching to an existing CLI-owned session.
-- Prefer Opensteer methods over raw Playwright calls so actions, extraction, and replay semantics stay inside the product surface.
-- Use `networkTag` on actions when you intend to inspect or promote the network traffic they trigger.
+- `workspace` / `--workspace` is the durable unit of state. Persistent workspaces live under `.opensteer/workspaces/<id>`.
+- A workspace stores the browser profile, live browser metadata, artifacts, traces, saved network, DOM descriptors, extraction descriptors, request plans, recipes, auth recipes, and reverse-analysis records.
+- In the SDK, omitting `workspace` creates a temporary root. In the CLI, stateful commands currently require `--workspace <id>`.
+- With a workspace, browser mode defaults to `persistent`. `temporary` creates an isolated browser for the current run. `attach` connects to an already-running Chromium browser.
+- `opensteer browser ...` manages the workspace browser itself. `opensteer close` stops the active session/browser without deleting the workspace. `browser reset` clears cloned browser state. `browser delete` removes workspace browser files.
+- The short CLI only has special parsing for a few common commands. For advanced semantic operations or fields like `persistAsDescription`, use `opensteer run <semantic-operation> --workspace <id> --input-json <json>`.
+- Prefer Opensteer surfaces over raw Playwright so descriptors, extraction payloads, saved network, request plans, recipes, traces, and artifacts stay in the workspace.
 
-## Request Capture And Replay
+## Workflow Selection
 
-Use Opensteer's reverse-engineering flow when the deliverable is a custom API or a replayable request plan:
+- Choose the DOM workflow when the answer must come from the rendered page or a real browser interaction.
+- Choose the request workflow when the durable artifact is an HTTP path, request plan, recipe, or reverse-analysis package.
+- Many tasks use both: prove the browser flow first, then capture and promote the underlying request path.
 
-1. Perform the browser action that triggers the request.
-2. Inspect traffic with `queryNetwork()` or `opensteer network query`.
-3. Retry the request with `rawRequest()` or `opensteer request raw`.
-4. Promote the captured request with `inferRequestPlan()` or `opensteer plan infer`.
-5. Replay it with `request()` or `opensteer request execute`.
+## Shared Rules
 
-Read [references/request-workflow.md](references/request-workflow.md) before implementing request-plan work.
+- Use `snapshot("action")` or `snapshot action` before counter-based `element` targets.
+- Re-snapshot after navigation or DOM-changing actions before reusing element counters.
+- In the SDK, `selector + description` or `element + description` persists a DOM action descriptor. `description` alone reuses it later.
+- In the CLI, the short `click` / `hover` / `input` / `scroll` forms accept exactly one target. Use `opensteer run dom.* --input-json` when you need `persistAsDescription`.
+- For extraction, `description + schema` authors or updates a persisted extraction descriptor. `description` alone replays the stored extraction payload.
+- Extraction schemas are explicit JSON objects and arrays. Each leaf must be `{ element: N }`, `{ selector: "..." }`, optional `attribute`, or `{ source: "current_url" }`.
+- Persisted extraction replay is deterministic and snapshot-backed. Do not replace `extract()` with `evaluate()` or custom DOM parsing when the desired output fits the extraction schema.
+- Use recipes for deterministic setup work. Use auth recipes for auth refresh/setup specifically. They live in separate registries.
+- Do not reach for removed surfaces such as `--name`, `Opensteer.attach()`, cloud/profile-sync helpers, `local-profile`, legacy snapshot browser modes, or `@opensteer/engine-abp`.

package/skills/opensteer/references/cli-reference.md

@@ -1,115 +1,133 @@
 # Opensteer CLI Reference
 
-Use the CLI when you need a fast, stateful loop against a live browser session.
+Use the CLI when you need a fast JSON-first loop against a repo-local workspace browser.
 
-## Session Loop
+## Sections
+
+- [Quickstart](#quickstart)
+- [Browser Lifecycle And Profile Cloning](#browser-lifecycle-and-profile-cloning)
+- [Browser Modes](#browser-modes)
+- [Advanced Semantic Operations](#advanced-semantic-operations)
+- [Extraction Schema Examples](#extraction-schema-examples)
+
+## Quickstart
 
 ```bash
-opensteer open https://example.com --name demo
-opensteer snapshot action --name demo
-opensteer click 3 --name demo --description "primary button"
-opensteer input 7 "search term" --name demo --press-enter --description "search input"
-opensteer snapshot extraction --name demo
-opensteer extract --name demo \
+opensteer browser status --workspace demo
+opensteer open https://example.com --workspace demo
+opensteer snapshot action --workspace demo
+opensteer click --workspace demo --element 3
+opensteer input --workspace demo --selector "input[type=search]" --text "search term" --press-enter true
+opensteer snapshot extraction --workspace demo
+opensteer extract --workspace demo \
   --description "page summary" \
-  --schema '{"title":{"selector":"title"},"url":{"source":"current_url"}}'
-opensteer close --name demo
+  --schema-json '{"title":{"selector":"title"},"url":{"source":"current_url"}}'
+opensteer extract --workspace demo --description "page summary"
+opensteer close --workspace demo
 ```
 
-## Core Rules
-
-- Keep `--name` stable for the whole workflow.
-- Use `snapshot action` before counter-based interactions.
-- Re-snapshot after any navigation or DOM-changing action before reusing counters.
-- Use `--description` when the interaction or extraction should become replayable later.
-- CLI commands return JSON for machine-readable actions and data commands.
+- Stateful CLI commands currently require `--workspace <id>`.
+- With a workspace, browser mode defaults to `persistent`.
+- Use `snapshot action` before `--element <n>` targets.
+- `extract --description --schema-json ...` writes or updates a persisted extraction descriptor.
+- `extract --description ...` replays the stored extraction payload with no schema.
 
-## Navigation And Data
+## Browser Lifecycle And Profile Cloning
 
 ```bash
-opensteer goto https://example.com/products --name demo
-opensteer snapshot action --name demo
-opensteer snapshot extraction --name demo
-opensteer extract --name demo --schema '{"items":[{"title":{"selector":"h2"}}]}'
+opensteer browser clone --workspace github-sync \
+  --source-user-data-dir "$HOME/Library/Application Support/Google/Chrome" \
+  --source-profile-directory Default
+opensteer open https://github.com --workspace github-sync
+opensteer browser status --workspace github-sync
+opensteer close --workspace github-sync
+opensteer browser reset --workspace github-sync
+opensteer browser delete --workspace github-sync
 ```
 
-## Browser Connection Modes
-
-Open a brand-new browser:
+- `browser clone`, `browser reset`, and `browser delete` require a persistent workspace browser.
+- `browser clone` copies a local Chromium profile into `.opensteer/workspaces/<id>/browser/user-data`.
+- `close` stops the active session/browser but keeps the workspace registry, traces, artifacts, and cloned browser data.
 
-```bash
-opensteer open https://example.com --name demo --headless true
-```
+## Browser Modes
 
-Attach to a live Chromium instance:
+- `persistent`: default with `--workspace`. Browser state lives in the workspace.
+- `temporary`: isolated browser state for the current run.
+- `attach`: connect to a running Chromium browser.
 
 ```bash
-opensteer open https://example.com --name demo --browser attach-live --attach-endpoint 9222
+opensteer open https://example.com --workspace demo --browser temporary
 opensteer browser discover
-opensteer browser inspect --endpoint 9222
+opensteer browser inspect --attach-endpoint ws://127.0.0.1:9222/devtools/browser/abc
+opensteer open https://example.com --workspace demo --browser attach --attach-endpoint ws://127.0.0.1:9222/devtools/browser/abc
 ```
 
-Launch from a copied local profile:
+Common options:
 
-```bash
-opensteer open https://example.com --name demo --browser snapshot-session \
-  --source-user-data-dir "~/Library/Application Support/Google/Chrome" \
-  --source-profile-directory Default
-```
+- `--headless true|false`
+- `--executable-path <path>`
+- `--arg <value>` repeatable
+- `--timeout-ms <ms>`
+- `--context-json <json>`
+- `--fresh-tab true|false` for `--browser attach`
 
-Launch from a copied authenticated profile:
+## Advanced Semantic Operations
+
+The short CLI only special-cases a small set of commands. For advanced operations and fields not exposed by shorthand parsing, use:
 
 ```bash
-opensteer open https://example.com --name demo --browser snapshot-authenticated \
-  --source-user-data-dir "~/Library/Application Support/Google/Chrome" \
-  --source-profile-directory "Profile 1"
+opensteer run <semantic-operation> --workspace <id> --input-json <json>
 ```
 
-## Local Browser Profile Helpers
+Examples:
 
 ```bash
-opensteer local-profile list
-opensteer local-profile inspect --user-data-dir "~/Library/Application Support/Opensteer Chrome"
-opensteer local-profile unlock --user-data-dir "~/Library/Application Support/Opensteer Chrome"
-```
+opensteer run dom.click --workspace demo \
+  --input-json '{"target":{"kind":"selector","selector":"button.primary"},"persistAsDescription":"primary button","networkTag":"load-products"}'
 
-## Cloud Profile Cookie Sync
+opensteer run page.goto --workspace demo \
+  --input-json '{"url":"https://example.com/products","networkTag":"page-load"}'
 
-```bash
-opensteer profile sync \
-  --profile-id bp_123 \
-  --attach-endpoint 9222 \
-  --domain github.com
+opensteer run network.query --workspace demo \
+  --input-json '{"tag":"load-products","includeBodies":true,"limit":20}'
+
+opensteer run request-plan.infer --workspace demo \
+  --input-json '{"recordId":"rec_123","key":"products.search","version":"v1"}'
+
+opensteer run request.execute --workspace demo \
+  --input-json '{"key":"products.search","query":{"q":"laptop"}}'
 ```
 
-## Network Capture
+- Command aliases such as `network query` and `request-plan infer` still exist, but they usually depend on `--input-json` for nontrivial inputs.
+- Use `run page.goto` when you need `networkTag` on navigation. The short `goto` form only parses the URL positional.
+- Use `run dom.click` / `run dom.input` / `run dom.hover` / `run dom.scroll` when you need `persistAsDescription`.
 
-Inspect the traffic triggered by a session:
+## Extraction Schema Examples
 
 ```bash
-opensteer network query --name demo --include-bodies --limit 20
-opensteer network save --name demo --tag login-flow
-opensteer network diff --name demo --left rec_a --right rec_b
-opensteer network probe --name demo --record-id rec_123
-opensteer network minimize --name demo --record-id rec_123 --transport context-http
+opensteer snapshot extraction --workspace demo
 ```
 
-## Request Plans
-
-Infer a plan from a captured record, then execute it:
+Explicit field bindings:
 
 ```bash
-opensteer plan infer --name demo --record-id rec_123 --key products.search --version v1
-opensteer plan get --name demo products.search
-opensteer request execute --name demo products.search --query q=laptop
-opensteer request raw --name demo https://example.com/api/search --transport context-http
+opensteer extract --workspace demo \
+  --description "page summary" \
+  --schema-json '{"title":{"element":3},"price":{"element":7}}'
+
+opensteer extract --workspace demo \
+  --description "links" \
+  --schema-json '{"url":{"selector":"a.primary","attribute":"href"},"pageUrl":{"source":"current_url"}}'
 ```
 
-## Execution Modes
+Arrays with representative rows:
 
-- `managed`: Opensteer launches and owns a fresh browser.
-- `attach-live`: Opensteer attaches to an already running Chromium browser.
-- `snapshot-session`: Opensteer copies an existing profile into an isolated owned session.
-- `snapshot-authenticated`: Opensteer copies a profile while preserving harder authenticated state.
+```bash
+opensteer extract --workspace demo \
+  --description "items" \
+  --schema-json '{"items":[{"title":{"selector":"#products li:nth-child(1) .title"},"price":{"selector":"#products li:nth-child(1) .price"}},{"title":{"selector":"#products li:nth-child(2) .title"},"price":{"selector":"#products li:nth-child(2) .price"}}]}'
+```
 
-Use `--engine abp` on `open` only when the optional `@opensteer/engine-abp` package is installed.
+- Build the exact JSON object you want. The extractor does not accept semantic placeholders like `"string"` or prompt-style schemas.
+- Use `element` fields only with counters from a fresh snapshot in the same live session.
+- For arrays, include one or more representative objects. Add multiple examples when repeated rows have structural variants.

package/skills/opensteer/references/request-workflow.md

@@ -2,6 +2,30 @@
 
 Use this workflow when the deliverable is a custom API, a replayable request plan, or a lower-overhead path than full browser automation.
 
+## Sections
+
+- [Standard Loop](#standard-loop)
+- [Transport Selection](#transport-selection)
+- [SDK Flow](#sdk-flow)
+- [CLI Equivalents](#cli-equivalents)
+- [Transport Probing](#transport-probing)
+- [Auth Token Acquisition](#auth-token-acquisition)
+- [Input Formats](#input-formats)
+- [Practical Guidance](#practical-guidance)
+
+## Standard Loop
+
+1. Trigger the real browser action that causes the request inside a stable workspace.
+2. Tag the important navigation or interactions with `networkTag`.
+3. Inspect the captured traffic and isolate the relevant records.
+4. Save useful captures to the workspace if they need to survive later analysis.
+5. Prove the request with `rawRequest()`.
+6. Promote the winning record into a request plan.
+7. Add recipes or auth recipes if replay needs deterministic setup.
+8. Replay the plan from code.
+
+This workflow should carry equal weight with DOM automation. Use it whenever the browser page is only the launcher for the real target request.
+
 ## Transport Selection
 
 - `direct-http`: the request is replayable without a browser.
@@ -13,11 +37,17 @@ When in doubt, start with browser-backed capture first. Opensteer treats browser
 
 ## SDK Flow
 
-1. Trigger the request from a real page.
+1. Start a workspace-backed browser flow and tag navigation.
 
 ```ts
-await opensteer.open("https://example.com/app");
+await opensteer.open();
+await opensteer.goto({
+  url: "https://example.com/app",
+  networkTag: "page-load",
+});
+
 await opensteer.click({
+  selector: "button.load-products",
   description: "load products",
   networkTag: "products-load",
 });
@@ -56,7 +86,15 @@ await opensteer.inferRequestPlan({
 });
 ```
 
-5. Replay the plan from code.
+5. Save the captured traffic if you want it in the workspace registry.
+
+```ts
+await opensteer.saveNetwork({
+  tag: "products-load",
+});
+```
+
+6. Replay the plan from code.
 
 ```ts
 const result = await opensteer.request("products.search", {
@@ -64,18 +102,116 @@ const result = await opensteer.request("products.search", {
 });
 ```
 
+7. Add a recipe or auth recipe if replay needs deterministic setup.
+
+```ts
+await opensteer.runRecipe({
+  key: "products.setup",
+});
+
+await opensteer.runAuthRecipe({
+  key: "products.auth",
+});
+```
+
 ## CLI Equivalents
 
 ```bash
-opensteer network query --name demo --tag products-load --include-bodies --limit 20
-opensteer request raw --name demo https://example.com/api/products --transport context-http
-opensteer plan infer --name demo --record-id rec_123 --key products.search --version v1
-opensteer request execute --name demo products.search --query q=laptop
+opensteer open --workspace demo
+opensteer run page.goto --workspace demo \
+  --input-json '{"url":"https://example.com/app","networkTag":"page-load"}'
+opensteer run dom.click --workspace demo \
+  --input-json '{"target":{"kind":"selector","selector":"button.load-products"},"persistAsDescription":"load products","networkTag":"products-load"}'
+opensteer run network.query --workspace demo \
+  --input-json '{"tag":"products-load","includeBodies":true,"limit":20}'
+opensteer run request.raw --workspace demo \
+  --input-json '{"transport":"context-http","url":"https://example.com/api/products","method":"POST","body":{"json":{"page":1}}}'
+opensteer run request-plan.infer --workspace demo \
+  --input-json '{"recordId":"rec_123","key":"products.search","version":"v1"}'
+opensteer run request.execute --workspace demo \
+  --input-json '{"key":"products.search","query":{"q":"laptop"}}'
+```
+
+## Transport Probing
+
+Test each discovered API with multiple transports to determine portability:
+
+```ts
+const direct = await opensteer.rawRequest({
+  transport: "direct-http",
+  url: discoveredUrl,
+  method: "GET",
+});
+
+const context = await opensteer.rawRequest({
+  transport: "context-http",
+  url: discoveredUrl,
+  method: "GET",
+});
 ```
 
+If `direct-http` returns 200, the API is portable and does not need a browser for future calls. If only `context-http` works, the API depends on browser session state.
+
+## Auth Token Acquisition
+
+When you discover an auth endpoint, acquire a token and use it to probe for data APIs that may be behind auth:
+
+```ts
+const tokenResp = await opensteer.rawRequest({
+  transport: "direct-http",
+  url: "https://example.com/api/oauth/token?scope=guest",
+  method: "POST",
+});
+
+let parsed = tokenResp.data;
+if (parsed === undefined) {
+  const body = tokenResp.response.body;
+  if (!body) {
+    throw new Error("Token response had no body");
+  }
+  parsed = JSON.parse(Buffer.from(body.data, "base64").toString("utf8"));
+}
+
+const token = String((parsed as { access_token: unknown }).access_token);
+
+const authed = await opensteer.rawRequest({
+  transport: "direct-http",
+  url: "https://example.com/api/products",
+  method: "GET",
+  headers: [{ name: "Authorization", value: `Bearer ${token}` }],
+});
+```
+
+## Input Formats
+
+`rawRequest` expects specific shapes:
+
+- `headers`: array of `[{ name, value }]`, not `{ key: value }`.
+- `body`: one of `{ json: { ... } }`, `{ text: "..." }`, or `{ base64: "..." }`. Not raw strings.
+- `request.execute` semantic input includes `key` inside the JSON object. The SDK convenience wrapper `opensteer.request(key, input)` adds that for you.
+
 ## Practical Guidance
 
+Mandatory steps:
+
+- MUST use `goto({ url, networkTag })` to tag navigation. `networkTag` is NOT supported on `open()`. In the CLI, this means `opensteer run page.goto --input-json ...`.
+- MUST query by tag first (`queryNetwork({ tag })`), then query all traffic to catch async requests.
+- MUST probe every discovered first-party API with transport tests. Do NOT just log URLs.
+- MUST call `saveNetwork({ tag })` before closing the session.
+- Use `queryNetwork({ source: "saved" })` when you want to read previously persisted captures after the live session is gone.
+
+Common mistakes:
+
+- Do NOT pass headers as `{key: value}`. MUST use `[{name, value}]` arrays.
+- Do NOT pass body as a raw string. MUST wrap it in `{json: {...}}`, `{text: "..."}`, or `{base64: "..."}`.
+- Do NOT skip auth probing. If you find an OAuth endpoint, get a token and re-probe with it.
+- Do NOT treat "no data API found" as failure. It is a valid reverse-engineering conclusion that justifies DOM fallback.
+- Do NOT mix up recipes and auth recipes. They are separate registries and can reuse the same key/version independently.
+
+Additional guidance:
+
 - Capture the browser action first if authentication, cookies, or minted tokens may matter.
-- Save or tag the useful traffic before minimizing or diffing it.
 - Prefer `direct-http` only after proving the request no longer depends on live browser state.
-- Use recipes when the request plan needs deterministic auth refresh or setup work.
+- `inferRequestPlan()` throws if the key+version already exists. Catch the error or bump the version.
+- Use recipes when the request plan needs deterministic setup work. Use auth recipes when the setup is specifically auth refresh or login state.
+- Stay in the DOM workflow only when the rendered page itself is the deliverable. Move here when the request is the durable artifact.