opensteer 0.6.13 → 0.7.0

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

@@ -1,159 +1,115 @@
-# Opensteer CLI Command Reference
+# Opensteer CLI Reference
 
-All commands output JSON. Set session once per shell:
+Use the CLI when you need a fast, stateful loop against a live browser session.
 
-```bash
-export OPENSTEER_SESSION=my-session
-# Or for non-interactive runners:
-export OPENSTEER_CLIENT_ID=agent-1
-```
-
-Global flags: `--session <id>`, `--name <namespace>`, `--headless`, `--description <text>`.
-
-## Navigation
+## Session Loop
 
 ```bash
-opensteer open <url>                                # Open browser, navigate to URL
-opensteer open <url> --name "my-scraper"            # Set selector cache namespace
-opensteer open <url> --headless                     # Headless mode
-opensteer open --cdp-url http://localhost:9222        # Connect to running browser via CDP
-opensteer open <url> --browser real                   # Use real Chrome profile (headless)
-opensteer open <url> --browser real --headed           # Real Chrome, visible window
-opensteer open <url> --browser real --profile "Work"   # Specific Chrome profile
-opensteer navigate <url>                            # Navigate with visual stability wait
-opensteer navigate <url> --timeout 60000            # Custom timeout (default 30s)
-opensteer back                                      # Go back in history
-opensteer forward                                   # Go forward in history
-opensteer reload                                    # Reload page
-opensteer close                                     # Close browser and stop server
-opensteer close --all                               # Close all active sessions
-opensteer sessions                                  # List active sessions
-opensteer status                                    # Show resolved session/name state
+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 \
+  --description "page summary" \
+  --schema '{"title":{"selector":"title"},"url":{"source":"current_url"}}'
+opensteer close --name demo
 ```
 
-`open` performs a basic navigation (no stability wait). `navigate` includes `waitForVisualStability`. Use `open` once to start, then `navigate` for subsequent pages.
+## 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.
 
-## Observation
+## Navigation And Data
 
 ```bash
-opensteer snapshot action           # Same as above (explicit)
-opensteer snapshot extraction       # Flattened HTML for data scraping
-opensteer snapshot clickable        # Only clickable elements
-opensteer snapshot scrollable       # Only scrollable containers
-opensteer snapshot full             # Minimal cleaning, full HTML
-opensteer state                     # URL + title + cleaned HTML
-opensteer screenshot                # Save screenshot to screenshot.png
-opensteer screenshot output.png     # Save to specific file
-opensteer screenshot --fullPage     # Full page screenshot
+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"}}]}'
 ```
 
-## Actions
+## Browser Connection Modes
 
-First positional argument is element counter (`c="N"` from snapshot).
+Open a brand-new browser:
 
 ```bash
-opensteer click 5                                   # Click by counter
-opensteer click --description "the submit button"   # By cached description
-opensteer click 5 --button right                    # Right-click
-opensteer click 5 --clickCount 2                    # Double-click
-opensteer hover 4                                   # Hover over element
-opensteer hover --description "the user menu"       # Hover by description
+opensteer open https://example.com --name demo --headless true
 ```
 
-## Input
+Attach to a live Chromium instance:
 
 ```bash
-opensteer input 3 "Hello"                           # Type into element (clears first)
-opensteer input 3 "Hello" --clear false             # Append text
-opensteer input 3 "query" --pressEnter              # Type and press Enter
-opensteer input --description "the search input" --text "query" --pressEnter
+opensteer open https://example.com --name demo --browser attach-live --attach-endpoint 9222
+opensteer browser discover
+opensteer browser inspect --endpoint 9222
 ```
 
-## Select / Scroll
+Launch from a copied local profile:
 
 ```bash
-opensteer select 9 --label "Option A"              # Select by visible label
-opensteer select 9 --value "opt-a"                  # Select by value attribute
-opensteer select 9 --index 2                        # Select by index
-opensteer scroll                                    # Scroll page down (default)
-opensteer scroll --direction up                     # Scroll up
-opensteer scroll --direction down --amount 1000
-opensteer scroll 12                                 # Scroll within container element
+opensteer open https://example.com --name demo --browser snapshot-session \
+  --source-user-data-dir "~/Library/Application Support/Google/Chrome" \
+  --source-profile-directory Default
 ```
 
-## Keyboard
+Launch from a copied authenticated profile:
 
 ```bash
-opensteer press Enter
-opensteer press Tab
-opensteer press Escape
-opensteer press "Control+a"
-opensteer type "Hello World"                        # Type into focused element
+opensteer open https://example.com --name demo --browser snapshot-authenticated \
+  --source-user-data-dir "~/Library/Application Support/Google/Chrome" \
+  --source-profile-directory "Profile 1"
 ```
 
-## Element Info
+## Local Browser Profile Helpers
 
 ```bash
-opensteer get-text 5                                # Get element text content
-opensteer get-text --description "the heading"
-opensteer get-value 3                               # Get input/textarea value
-opensteer get-attrs 5                               # Get all HTML attributes
-opensteer get-html                                  # Full page HTML
-opensteer get-html "main"                           # HTML of element matching selector
+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"
 ```
 
-## Tabs
+## Cloud Profile Cookie Sync
 
 ```bash
-opensteer tabs                                      # List open tabs with indices
-opensteer tab-new                                   # Open new blank tab
-opensteer tab-new https://example.com               # Open URL in new tab
-opensteer tab-switch 0                              # Switch to tab by index
-opensteer tab-close                                 # Close current tab
-opensteer tab-close 2                               # Close specific tab
+opensteer profile sync \
+  --profile-id bp_123 \
+  --attach-endpoint 9222 \
+  --domain github.com
 ```
 
-## Cookies
+## Network Capture
 
-```bash
-opensteer cookies                                   # Get all cookies
-opensteer cookies --url https://example.com         # Cookies for specific URL
-opensteer cookie-set --name token --value abc123
-opensteer cookies-clear                             # Clear all cookies
-opensteer cookies-export /tmp/cookies.json          # Export to file
-opensteer cookies-import /tmp/cookies.json          # Import from file
-```
-
-## Utility
+Inspect the traffic triggered by a session:
 
 ```bash
-opensteer eval "document.title"                     # Execute JS in page
-opensteer wait-for "Success"                        # Wait for text to appear
-opensteer wait-for "Success" --timeout 5000
-opensteer wait-selector "h1"                        # Wait for selector to appear
+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
 ```
 
-## Data Extraction
+## Request Plans
 
-### Counter-based (preferred)
+Infer a plan from a captured record, then execute it:
 
 ```bash
-opensteer snapshot extraction
-# `schema-json` describes the output shape. It can use explicit bindings or semantic placeholders.
-
-# Explicit field bindings from observed counters/attributes:
-opensteer extract '{"title":{"element":3},"price":{"element":7}}'
-opensteer extract '{"url":{"element":5,"attribute":"href"}}'
-opensteer extract '{"pageUrl":{"source":"current_url"},"title":{"element":3}}'
-
-# Explicit array bindings: include multiple items to identify the repeating pattern
-opensteer extract '{"results":[{"title":{"element":11},"url":{"element":10,"attribute":"href"}},{"title":{"element":16},"url":{"element":15,"attribute":"href"}}]}'
-
-# Semantic extraction: use the output shape plus description/prompt
-opensteer extract '{"title":"string","price":"string"}' --description "product details"
-opensteer extract '{"images":[{"imageUrl":"string","alt":"string","caption":"string","credit":"string"}]}' \
-  --description "article images with captions and credits" \
-  --prompt "For each image, return the image URL, alt text, caption, and credit. Prefer caption and credit from the same figure. If missing, look at sibling text, then parent/container text, then nearby alt/data-* attributes."
+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
 ```
 
-Use explicit bindings when you need deterministic element-to-field mappings. Use semantic extraction when the fields require relationship inference or fallback rules. `--prompt` is the place to describe those rules.
+## Execution Modes
+
+- `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.
+
+Use `--engine abp` on `open` only when the optional `@opensteer/engine-abp` package is installed.

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

@@ -0,0 +1,81 @@
+# Opensteer Request Workflow
+
+Use this workflow when the deliverable is a custom API, a replayable request plan, or a lower-overhead path than full browser automation.
+
+## Transport Selection
+
+- `direct-http`: the request is replayable without a browser.
+- `context-http`: browser session state matters, but the request does not need to execute inside page JavaScript.
+- `page-http`: the request must execute inside the live page JavaScript world.
+- `session-http`: use a stored request plan that still depends on a live browser session.
+
+When in doubt, start with browser-backed capture first. Opensteer treats browser-backed replay as a first-class path, not a fallback.
+
+## SDK Flow
+
+1. Trigger the request from a real page.
+
+```ts
+await opensteer.open("https://example.com/app");
+await opensteer.click({
+  description: "load products",
+  networkTag: "products-load",
+});
+```
+
+2. Inspect the captured traffic.
+
+```ts
+const records = await opensteer.queryNetwork({
+  tag: "products-load",
+  includeBodies: true,
+  limit: 20,
+});
+```
+
+3. Test the request directly.
+
+```ts
+const response = await opensteer.rawRequest({
+  transport: "context-http",
+  url: "https://example.com/api/products",
+  method: "POST",
+  body: {
+    json: { page: 1 },
+  },
+});
+```
+
+4. Promote a captured record into a request plan.
+
+```ts
+await opensteer.inferRequestPlan({
+  recordId: records.records[0]!.id,
+  key: "products.search",
+  version: "v1",
+});
+```
+
+5. Replay the plan from code.
+
+```ts
+const result = await opensteer.request("products.search", {
+  query: { q: "laptop" },
+});
+```
+
+## 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
+```
+
+## Practical 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.

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

@@ -1,174 +1,121 @@
-# Opensteer SDK API Reference
+# Opensteer SDK Reference
 
-The SDK is the `Opensteer` class imported from `'opensteer'`. **Only the methods listed below exist.** Do NOT call CLI command names as SDK methods.
+Use the SDK when the workflow should become reusable TypeScript code in the repository.
 
-## Construction and Lifecycle
+## Session Ownership
 
-```typescript
-const opensteer = new Opensteer({
-  name: "my-scraper",
-  storage: { rootDir: process.cwd() },
-});
-await opensteer.launch({ headless: false });
-await opensteer.close();
+Owned session:
 
-// Use the user's local Chrome profile state:
-const opensteer = new Opensteer({
-  name: "my-scraper",
-  browser: {
-    mode: "real",
-    profileDirectory: "Default",
-    headless: false,
-  },
-});
-await opensteer.launch();
+```ts
+import { Opensteer } from "opensteer";
 
-// Or pass real-browser mode at launch time:
-await opensteer.launch({
-  mode: "real",
-  profileDirectory: "Default",
-  headless: false,
+const opensteer = new Opensteer({
+  name: "demo",
+  rootDir: process.cwd(),
+  browser: { headless: true },
 });
-
-// Wrap an existing page instance:
-const opensteer = Opensteer.from(existingPage, { name: "my-scraper" });
 ```
 
-## Properties
-
-```typescript
-opensteer.page;    // Low-level page handle (see "Advanced: Direct Page Access" in SKILL.md)
-opensteer.context; // Low-level browser context handle
-```
-
-## Navigation
-
-```typescript
-await opensteer.goto(url);                      // Navigate + waitForVisualStability
-await opensteer.goto(url, { timeout: 60000 });  // Custom timeout
-```
+Attached session:
 
-## Observation
+```ts
+import { Opensteer } from "opensteer";
 
-```typescript
-const html = await opensteer.snapshot();                          // Action mode (default)
-const html = await opensteer.snapshot({ mode: "extraction" });    // Extraction mode
-const state = await opensteer.state();                            // { url, title, html }
-const buffer = await opensteer.screenshot();                      // PNG buffer
-const jpeg = await opensteer.screenshot({ type: "jpeg", fullPage: true });
+const opensteer = Opensteer.attach({
+  name: "demo",
+  rootDir: process.cwd(),
+});
 ```
 
-## Interactions
-
-```typescript
-await opensteer.click({ element: 5 });
-await opensteer.click({ description: "the submit button" });
-await opensteer.click({ selector: "#btn" });
-await opensteer.dblclick({ element: 7 });
-await opensteer.rightclick({ element: 7 });
-await opensteer.hover({ element: 4 });
-await opensteer.input({ element: 3, text: "Hello" });
-await opensteer.input({ description: "search", text: "q", pressEnter: true });
-await opensteer.select({ element: 9, label: "Option A" });
-await opensteer.scroll();
-await opensteer.scroll({ direction: "up", amount: 500 });
-```
+Use `close()` for owned sessions. Use `disconnect()` for attached sessions.
 
-## Data Extraction
+## Core Browser Flow
 
-```typescript
-// Replay from cached descriptions (preferred in scraper scripts)
+```ts
+await opensteer.open("https://example.com");
+await opensteer.goto("https://example.com/products");
+await opensteer.snapshot("action");
+await opensteer.click({ description: "primary button" });
+await opensteer.input({ description: "search input", text: "laptop", pressEnter: true });
+await opensteer.hover({ description: "price filter" });
+await opensteer.scroll({ direction: "down", amount: 600 });
 const data = await opensteer.extract({
-  description: "product details",
-});
-
-// Semantic extraction: schema is the output shape
-const images = await opensteer.extract({
-  description: "article images with captions and credits",
-  prompt: "For each image, return the image URL, alt text, caption, and credit. Prefer caption and credit from the same figure. If missing, look at sibling text, then parent/container text, then nearby alt/data-* attributes.",
+  description: "page summary",
   schema: {
-    images: [{ imageUrl: "string", alt: "string", caption: "string", credit: "string" }],
+    title: { selector: "title" },
+    url: { source: "current_url" },
   },
 });
-
-// Explicit bindings (during exploration or when no cache exists)
-const data = await opensteer.extract({
-  schema: { title: { element: 3 }, price: { element: 7 } },
-  description: "product details",
-});
 ```
 
-`schema` describes the output shape, not just selector config. It can use semantic placeholders like `"string"` and arrays of objects, or explicit field bindings such as `{ element: N }`, `{ element: N, attribute: "href" }`, `{ selector: ".price" }`, and `{ source: "current_url" }`.
-
-Use `prompt` to describe relationship/fallback rules, such as matching each image to its caption and credit.
-
-For explicit array bindings, include multiple items in the schema so Opensteer can infer the repeating pattern. For semantic extraction, a single representative object shape is enough.
-
-## Keyboard
-
-```typescript
-await opensteer.pressKey("Enter");
-await opensteer.pressKey("Control+a");
-await opensteer.type("Hello World");
-```
-
-## Element Info
-
-```typescript
-const text = await opensteer.getElementText({ element: 5 });
-const value = await opensteer.getElementValue({ element: 3 });
-const attrs = await opensteer.getElementAttributes({ element: 5 });
-const box = await opensteer.getElementBoundingBox({ element: 5 });
-const html = await opensteer.getHtml();
-const html = await opensteer.getHtml("main");
-const title = await opensteer.getTitle();
-```
-
-## Wait
-
-**Do NOT use wait calls before SDK actions** — each action handles waiting internally. Only use explicit waits for page transitions or confirming SPA content loaded.
-
-```typescript
-await opensteer.waitForText("Success");                              // Literal text on page
-await opensteer.waitForText("Success", { timeout: 5000 });
-// For CSS selector waits, see "Advanced: Direct Page Access" in SKILL.md
-```
-
-## Tabs
-
-```typescript
-const tabs = await opensteer.tabs();
-await opensteer.newTab("https://example.com");
-await opensteer.switchTab(0);
-await opensteer.closeTab(1);
-```
-
-## Cookies
-
-```typescript
-const cookies = await opensteer.getCookies();
-await opensteer.setCookie({ name: "token", value: "abc" });
-await opensteer.clearCookies();
-await opensteer.exportCookies("/tmp/cookies.json");
-await opensteer.importCookies("/tmp/cookies.json");
-```
-
-## File Upload
-
-```typescript
-await opensteer.uploadFile({ element: 5, paths: ["/path/to/file.pdf"] });
-```
-
-## Common Mistakes
-
-| If you want to...        | Use this                          |
-| ------------------------ | --------------------------------- |
-| Navigate to a URL        | `opensteer.goto(url)`             |
-| Launch the browser       | `opensteer.launch()`              |
-| Close the browser        | `opensteer.close()`               |
-| Get page text content    | `opensteer.getElementText()`      |
-| Get page HTML            | `opensteer.getHtml()`             |
-| Extract structured data  | `opensteer.extract()`             |
-| Wait for content         | `opensteer.waitForText()`         |
-
-> **SDK Rule**: Every browser action in a script MUST use an `opensteer.*` method.
+## Common Methods
+
+Session and page control:
+
+- `Opensteer.attach({ name?, rootDir? })`
+- `open(url | { url?, name?, browser?, context? })`
+- `goto(url | { url, networkTag? })`
+- `listPages()`
+- `newPage({ url?, openerPageRef? })`
+- `activatePage({ pageRef })`
+- `closePage({ pageRef })`
+- `waitForPage({ openerPageRef?, urlIncludes?, timeoutMs? })`
+
+Interaction and extraction:
+
+- `snapshot("action" | "extraction")`
+- `click({ element | selector | description, networkTag? })`
+- `hover({ element | selector | description, networkTag? })`
+- `input({ element | selector | description, text, pressEnter?, networkTag? })`
+- `scroll({ element | selector | description, direction, amount, networkTag? })`
+- `extract({ description, schema? })`
+
+Inspection and evaluation:
+
+- `evaluate(script | { script, pageRef?, args? })`
+- `evaluateJson({ script, pageRef?, args? })`
+- `waitForNetwork({ ...filters, pageRef?, includeBodies?, timeoutMs? })`
+- `waitForResponse({ ...filters, pageRef?, includeBodies?, timeoutMs? })`
+- `queryNetwork({ ...filters, includeBodies?, limit? })`
+- `saveNetwork({ tag, ...filters })`
+- `clearNetwork({ tag? })`
+
+Request capture and replay:
+
+- `rawRequest({ transport?, pageRef?, url, method?, headers?, body?, followRedirects? })`
+- `inferRequestPlan({ recordId, key, version, lifecycle? })`
+- `writeRequestPlan({ key, version, payload, lifecycle?, tags?, provenance?, freshness? })`
+- `getRequestPlan({ key, version? })`
+- `listRequestPlans({ key? })`
+- `request(key, { path?, query?, headers?, body? })`
+- `writeRecipe({ key, version, payload, tags?, provenance? })`
+- `getRecipe({ key, version? })`
+- `listRecipes({ key? })`
+- `runRecipe({ key, version?, input? })`
+
+Instrumentation:
+
+- `captureScripts({ pageRef?, includeInline?, includeExternal?, includeDynamic?, includeWorkers?, urlFilter?, persist? })`
+- `addInitScript({ script, args?, pageRef? })`
+- `route({ urlPattern, resourceTypes?, times?, handler })`
+- `interceptScript({ urlPattern, handler, times? })`
+
+Browser and profile helpers:
+
+- `discoverLocalCdpBrowsers({ timeoutMs? })`
+- `inspectCdpEndpoint({ endpoint, headers?, timeoutMs? })`
+- `inspectLocalBrowserProfile({ userDataDir? })`
+- `unlockLocalBrowserProfile({ userDataDir })`
+
+Lifecycle:
+
+- `disconnect()`
+- `close()`
+
+## Rules
+
+- Wrap owned sessions in `try/finally` and call `close()`.
+- Use `networkTag` on actions that trigger requests you may inspect later.
+- Use `description` when the interaction should be replayable across sessions.
+- Use `element` targets only with a fresh snapshot from the same live session.
+- Prefer Opensteer methods over raw Playwright so browser, extraction, and replay semantics stay consistent.