opensteer 0.8.9 → 0.8.11

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

@@ -177,6 +177,12 @@ if (!status.live) {
 
 ## Request Capture, Plans, And Recipes
 
+For the complete pipeline with mandatory phases, see [Request Plan Pipeline](request-workflow.md). This section covers SDK method signatures and examples for reusable scripts.
+
+The deliverable of a request capture workflow is a persisted request plan tested via `request()`. `rawRequest()` is a diagnostic probe — not the deliverable.
+
+### Capture, Probe, and Infer
+
 ```ts
 await opensteer.open();
 await opensteer.goto({
@@ -196,8 +202,10 @@ const records = await opensteer.queryNetwork({
   limit: 20,
 });
 
+// DIAGNOSTIC ONLY — probe transport to determine portability.
+// Do NOT return this data as the final answer. Proceed to inferRequestPlan.
 const response = await opensteer.rawRequest({
-  transport: "context-http",
+  transport: "direct-http",
   url: "https://example.com/api/products",
   method: "POST",
   body: {
@@ -205,43 +213,123 @@ const response = await opensteer.rawRequest({
   },
 });
 
+// Infer plan with the transport you proved works
 await opensteer.inferRequestPlan({
   recordId: records.records[0]!.recordId,
   key: "products.search",
   version: "v1",
+  transport: "direct-http",
 });
 
-await opensteer.inferRequestPlan({
-  recordId: records.records[0]!.recordId,
-  key: "products.search.portable",
+// Replay the plan — this is the deliverable
+await opensteer.request("products.search", {
+  query: { q: "laptop" },
+});
+```
+
+### Read and Fix Plans
+
+After inferring a plan, read it to validate auth and annotate parameters:
+
+```ts
+// Read the inferred plan
+const plan = await opensteer.getRequestPlan({
+  key: "products.search",
   version: "v1",
-  transport: "direct-http",
 });
 
-await opensteer.tagNetwork({
-  tag: "products-load",
+// Inspect plan.payload.auth — if auth.strategy is set but the API is public,
+// rewrite the plan with auth removed
+await opensteer.writeRequestPlan({
+  key: "products.search",
+  version: "v1",
+  tags: ["products", "search"],
+  provenance: {
+    source: "manual",
+    notes: "Auth removed — API is public. Parameters annotated.",
+  },
+  payload: {
+    ...plan.payload,
+    auth: undefined, // Remove spurious auth classification
+    parameters: [
+      { name: "q", in: "query", required: true, description: "Search keyword" },
+      { name: "count", in: "query", defaultValue: "24", description: "Results per page" },
+      { name: "offset", in: "query", defaultValue: "0", description: "Pagination offset" },
+    ],
+  },
+});
+```
+
+### Auth Recipes
+
+When an API genuinely requires auth, create an auth recipe that acquires tokens automatically:
+
+```ts
+// Write an auth recipe that acquires a bearer token
+await opensteer.writeAuthRecipe({
+  key: "example.auth",
+  version: "v1",
+  payload: {
+    description: "Acquire guest bearer token for example.com API",
+    steps: [
+      {
+        kind: "directRequest",
+        request: {
+          url: "https://example.com/api/oauth/token",
+          transport: "direct-http",
+          method: "POST",
+          body: { json: { grant_type: "client_credentials" } },
+        },
+        capture: {
+          bodyJsonPointer: { pointer: "/access_token", saveAs: "token" },
+        },
+      },
+    ],
+    outputs: {
+      headers: { Authorization: "Bearer {{token}}" },
+    },
+  },
 });
 
-await opensteer.request("products.search", {
+// Bind the auth recipe to a plan by rewriting the plan with auth.recipe
+const plan = await opensteer.getRequestPlan({ key: "products.search" });
+await opensteer.writeRequestPlan({
+  key: "products.search",
+  version: "v1",
+  payload: {
+    ...plan.payload,
+    auth: {
+      strategy: "bearer-token",
+      recipe: { key: "example.auth", version: "v1" },
+      failurePolicy: { on: "status", status: "401", action: "recover" },
+    },
+  },
+});
+
+// Now request.execute automatically runs the auth recipe on 401
+const result = await opensteer.request("products.search", {
   query: { q: "laptop" },
 });
 ```
 
-Rules:
+**Recipe step types:** `directRequest`, `sessionRequest`, `request`, `readCookie`, `readStorage`, `evaluate`, `waitForNetwork`, `waitForCookie`, `goto`, `solveCaptcha`, `hook`. Each step can `capture` values; `outputs` maps captured variables to `headers`, `query`, `params`, or `body` overrides.
+
+### Rules
 
 - `captureNetwork` is supported on `goto()`, `click()`, `scroll()`, `input()`, and `hover()`. It is NOT supported on `open()`. Use `open()` then `goto({ url, captureNetwork })` to name initial navigation capture.
 - Query by capture first, then query all traffic to catch async requests that fire after page load.
-- Probe discovered APIs with `rawRequest()` using `direct-http` first, then `context-http`.
+- Probe discovered APIs with `rawRequest()` using `direct-http` first, then `context-http`. `rawRequest()` is diagnostic — always proceed to `inferRequestPlan`.
 - Persistence is automatic; use `tagNetwork()` when you want to label a slice of already-persisted history for later lookup.
 - Use recipes when replay needs deterministic setup work. Use auth recipes when the setup is specifically auth-related. They live in separate registries.
 
-`rawRequest` input shapes:
+### Input Shapes
 
-- `headers` MUST be an array: `[{ name: "Authorization", value: "Bearer ..." }]`. NOT `{ Authorization: "Bearer ..." }`.
-- `body` MUST be one of: `{ json: { ... } }`, `{ text: "..." }`, or `{ base64: "..." }`. NOT a raw string or object.
+- `rawRequest` `headers` MUST be an array: `[{ name: "Authorization", value: "Bearer ..." }]`. NOT `{ Authorization: "Bearer ..." }`.
+- `rawRequest` `body` MUST be one of: `{ json: { ... } }`, `{ text: "..." }`, or `{ base64: "..." }`. NOT a raw string or object.
 - `rawRequest()` may populate parsed JSON on `data`. If it does not, decode `response.body.data` with `Buffer.from(..., "base64").toString("utf8")`.
+- Recipe step `request` fields accept `{ key: value }` objects for headers (unlike `rawRequest`).
 
-Common errors and fixes:
+### Common Errors
 
 | Error                                                        | Cause                                                 | Fix                                                               |
 | ------------------------------------------------------------ | ----------------------------------------------------- | ----------------------------------------------------------------- |

package/skills/recorder/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: recorder
+description: "Use when the user wants to record a live browser workflow and turn it into a deterministic Opensteer replay script. Prefer this for manual browser capture, multi-tab flow recording, and agent-guided record-and-replay setup with the Opensteer CLI."
+argument-hint: "[url]"
+---
+
+# Recorder
+
+Use the Opensteer recorder to open a headed local Playwright browser, capture DOM-level actions, and write a replayable TypeScript script.
+
+## When to use
+
+- Record a real browser flow for later replay.
+- Turn a manual QA walkthrough into Opensteer SDK code.
+- Capture a multi-tab browsing session as a starting point for automation.
+
+## Quick start
+
+```bash
+opensteer record --workspace <id> --url <url>
+opensteer record --workspace <id> --url <url> --output <path>
+```
+
+1. Start recording with `opensteer record --workspace <id> --url <url>`.
+2. Perform the workflow in the headed browser.
+3. Stop recording with the injected `Stop recording` button in the browser.
+4. Wait for the CLI to write the script path and close the browser session.
+5. Inspect the generated file before replaying or editing it.
+
+## Guardrails
+
+- Recording requires `provider=local`.
+- Recording requires `engine=playwright`.
+- Recording always uses a headed persistent browser for the target workspace.
+- Stopping is browser-driven. Do not rely on `Ctrl+C` or removed timeout flags.
+- If a launch argument value starts with `--`, pass it as `--arg=...`, not `--arg ...`.
+
+## Output
+
+- Default output path: `.opensteer/workspaces/<id>/recorded-flow.ts`
+- The generated script imports `Opensteer` from `opensteer`.
+- Replay uses public SDK methods such as `open`, `goto`, `click`, `input`, `scroll`, `newPage`, `closePage`, `activatePage`, and `evaluate`.
+
+## Agent workflow
+
+- Use the browser stop button as the primary stop path.
+- After recording, read the generated script and summarize what was captured before changing it.
+- If the user asks for replay verification, run the generated script instead of only inspecting the file.
+- If the flow depends on recorder limits such as iframes or file upload, read the reference file before promising support.
+
+## References
+
+- [Recorder Reference](references/recorder-reference.md)
+- [Opensteer SDK Reference](../opensteer/references/sdk-reference.md)

package/skills/recorder/references/recorder-reference.md

@@ -0,0 +1,71 @@
+# Recorder Reference
+
+Read this file when you need recorder constraints, replay details, or non-default invocation patterns.
+
+## Command
+
+```bash
+opensteer record --workspace <id> --url <url> [--output <path>]
+```
+
+Useful launch-arg pattern when the value begins with dashes:
+
+```bash
+opensteer record --workspace <id> --url <url> --arg=--remote-debugging-port=9333
+```
+
+## Stop behavior
+
+- The recorder stops when the user clicks the injected `Stop recording` button in the browser.
+- After stop, the CLI writes the replay script and closes the owned browser session.
+- Do not use removed timeout flags such as `--record-timeout-ms`.
+
+## What Gets Recorded
+
+- Clicks and double-clicks
+- Text entry with idle-based coalescing
+- Special key presses such as `Enter`, `Tab`, `Escape`, `Backspace`, `Delete`, and arrow keys
+- Scroll gestures
+- `<select>` value changes
+- Same-document navigation via `pushState`, `replaceState`, `popstate`, and `hashchange`
+- Full-page navigations, reloads, and back/forward traversal when they can be inferred
+- New tabs, closed tabs, and tab switches
+
+## Selector Strategy
+
+- Prefer stable single-attribute selectors such as `data-testid`, `data-test`, `data-qa`, `data-cy`, `id`, `name`, `role`, and `aria-label`
+- Reuse the same attribute-priority ordering as Opensteer DOM match policy
+- Fall back to short ancestor paths with attribute hints and `:nth-of-type()` when needed
+- Require selector uniqueness at capture time
+
+## Generated Replay
+
+- Opens the recorded start URL in the target workspace
+- Keeps stable page variables such as `page0`, `page1`, and `page2`
+- Activates the correct page before page-scoped SDK actions
+- Merges `Enter` into the preceding `input()` call when the capture sequence allows it
+- Uses `evaluate()` helpers when replay needs behavior that is not yet exposed as a first-class SDK helper
+
+## Replay verification
+
+- Default generated path: `.opensteer/workspaces/<id>/recorded-flow.ts`
+- Typical replay command: `pnpm exec tsx <path-to-recorded-flow.ts>`
+- Review the script before replay if the user performed unsupported or approximate browser actions
+
+## Limitations
+
+- v1 records only the top frame
+- Cross-origin iframes are not recorded
+- Shadow DOM selectors are best effort
+- File uploads, drag-and-drop, and canvas interactions are not fully modeled
+- Some browser-native key and pointer modifiers are approximated in replay because the public SDK surface is narrower than the raw browser event stream
+- Back and forward detection is best effort and may fall back to direct navigation replay in ambiguous cases
+
+## Workflow
+
+1. Start recording with `opensteer record`.
+2. Perform the workflow manually in the headed browser.
+3. Click the `Stop recording` button in the browser.
+4. Wait for the recorder to write `recorded-flow.ts` and close the browser session.
+5. Review the generated `recorded-flow.ts`.
+6. Run the script with `tsx` or integrate it into a larger automation.