opensteer 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -36,6 +36,9 @@
   timeout/stale-target cases more accurately.
 - Cloud action failures now accept optional structured failure details and map
   them to `OpensteerActionError` when available.
+- Added native skills installer commands (`opensteer skills install` and
+  `opensteer skills add`) that wrap the upstream `skills` CLI to install the
+  first-party `opensteer` skill pack without requiring separate global setup.
 - Docs: refreshed README and getting-started guidance to match current SDK/CLI
   behavior and env vars.
 - Docs: added CLI reference and docs index.

package/README.md

@@ -1,128 +1,179 @@
 # Opensteer
 
-Open-source browser automation SDK for coding agents and deterministic replay.
+Browser automation framework for developers and AI agents with deterministic replay.
 
-Opensteer combines descriptor-aware actions, resilient selector persistence,
-clean HTML snapshots, and first-class local or cloud runtime support.
+Opensteer gives you one API for local and cloud runs, description-based actions,
+structured extraction, and CUA agent workflows.
 
-## Requirements
+## Install
 
-- Node.js `>=20`
-- A browser environment supported by Playwright
-- API key for your selected model provider if you use LLM resolve/extract
+Main setup (recommended):
 
-## Install
+```bash
+npm i -g opensteer
+opensteer skills install
+```
+
+SDK package (when importing `Opensteer` in app code):
 
 ```bash
 # npm
 npm install opensteer
+
 # pnpm
 pnpm add opensteer
+
 # bun
 bun add opensteer
 ```
 
-Repo maintenance defaults to `pnpm`, with compatibility checks for `npm` and
-`bun` in CI.
+## Requirements
+
+- Node.js `>=20`
+- Playwright-supported browser runtime
+- Model provider API key for LLM-powered resolution/extraction/CUA
 
-If your environment skips Playwright browser downloads, run:
+If browser binaries are missing:
 
 ```bash
 npx playwright install chromium
 ```
 
-## Quickstart (SDK)
+## What It Does
+
+- Unified local/cloud execution with the same API surface
+- Descriptor-aware actions with selector persistence for replay
+- Structured extraction with typed schemas
+- CUA agent support (`openai`, `anthropic`, `google`)
+
+## Quick Start: SDK
 
 ```ts
 import { Opensteer } from "opensteer";
 
-const opensteer = new Opensteer({ name: "my-scraper" });
-await opensteer.launch({ headless: false });
+const opensteer = new Opensteer({ name: "quickstart" });
 
 try {
+  await opensteer.launch();
   await opensteer.goto("https://example.com");
-  const html = await opensteer.snapshot();
-  console.log(html.slice(0, 500));
 
-  await opensteer.click({ description: "main call to action", element: 3 });
+  await opensteer.snapshot({ mode: "action" });
+  await opensteer.click({ description: "main call to action" });
+
+  await opensteer.snapshot({ mode: "extraction" });
+  const data = await opensteer.extract({
+    description: "hero section",
+    schema: { title: "string", href: "string" },
+  });
+
+  console.log(data);
 } finally {
   await opensteer.close();
 }
 ```
 
-## CUA Agent
+## Quick Start: CUA Agent
 
 ```ts
 import { Opensteer } from "opensteer";
 
-const opensteer = new Opensteer({
-  model: "openai/computer-use-preview",
-});
+const opensteer = new Opensteer({ model: "openai/computer-use-preview" });
 
-await opensteer.launch();
+try {
+  await opensteer.launch();
+  const agent = opensteer.agent({ mode: "cua" });
+  const result = await agent.execute({
+    instruction: "Go to Hacker News and open the top story.",
+    maxSteps: 20,
+  });
+  console.log(result.message);
+} finally {
+  await opensteer.close();
+}
+```
 
-const agent = opensteer.agent({
-  mode: "cua",
-});
+## Quick Start: CLI
 
-const result = await agent.execute({
-  instruction: "Go to Hacker News and open the top story.",
-  maxSteps: 20,
-  highlightCursor: true,
-});
+```bash
+# Open a browser session and bind a selector namespace
+opensteer open https://example.com --session demo --name quickstart
 
-console.log(result.message);
-await opensteer.close();
+# Action snapshot + interaction
+opensteer snapshot action --session demo
+opensteer click --description "main call to action" --session demo
+
+# Extraction snapshot + structured extract
+opensteer snapshot extraction --session demo
+opensteer extract '{"title":"string","href":"string"}' --description "hero section" --session demo
+
+# Close session
+opensteer close --session demo
 ```
 
-Supported CUA providers in V1: `openai`, `anthropic`, `google`.
+For non-interactive runs, set `OPENSTEER_SESSION` or `OPENSTEER_CLIENT_ID`.
+
+## For AI Agents
 
-## Quickstart (CLI)
+Use this workflow to keep scripts replayable and maintainable:
 
-Opensteer CLI separates runtime routing from selector namespace routing.
+1. Use Opensteer APIs (`goto`, `snapshot`, `click`, `input`, `extract`) instead of raw Playwright calls.
+2. Keep namespace consistent: SDK `name` must match CLI `--name`.
+3. Take `snapshot({ mode: "action" })` before actions and `snapshot({ mode: "extraction" })` before extraction.
+4. Prefer `description` targeting for persistence and deterministic reruns.
+5. Always wrap runs in `try/finally` and call `close()`.
 
-- Runtime routing: `--session` or `OPENSTEER_SESSION`
-- Selector namespace: `--name` or `OPENSTEER_NAME` (used by `open`)
+First-party skills:
+
+- [skills/opensteer/SKILL.md](skills/opensteer/SKILL.md)
+- [skills/electron/SKILL.md](skills/electron/SKILL.md)
+- [skills/README.md](skills/README.md)
+
+Install the Opensteer skill pack:
 
 ```bash
-opensteer open https://example.com --session agent-a --name product-scraper
-opensteer snapshot --session agent-a
-opensteer click 3 --session agent-a
-opensteer status --session agent-a
-opensteer close --session agent-a
+opensteer skills install
 ```
 
-In non-interactive environments, set `OPENSTEER_SESSION` or
-`OPENSTEER_CLIENT_ID` explicitly.
-
-## Resolution and Replay Model
+Fallback (direct upstream `skills` CLI):
 
-For descriptor-aware actions (`click`, `input`, `hover`, `select`, `scroll`):
+```bash
+npx skills add https://github.com/steerlabs/opensteer-skills --skill opensteer
+```
 
-1. Reuse persisted path for `description`
-2. Use `element` counter from snapshot
-3. Use explicit CSS `selector`
-4. Use built-in LLM resolution (`description` required)
-5. Throw actionable error
+Claude Code marketplace plugin:
 
-When steps 2-4 succeed and `description` is present, Opensteer persists the
-path for deterministic replay in `.opensteer/selectors/<namespace>`.
+```text
+/plugin marketplace add steerlabs/opensteer
+/plugin install opensteer@opensteer-marketplace
+```
 
 ## Cloud Mode
 
-Opensteer defaults to local mode.
+Opensteer defaults to local mode. Enable cloud mode with env or constructor options:
 
-- `OPENSTEER_MODE=local|cloud`
-- `OPENSTEER_API_KEY` or `cloud.apiKey` required in cloud mode
-- `OPENSTEER_BASE_URL` or `cloud.baseUrl` to override the default cloud host
-- `OPENSTEER_AUTH_SCHEME` or `cloud.authScheme` for auth header mode
-  (`api-key` or `bearer`)
+```bash
+OPENSTEER_MODE=cloud
+OPENSTEER_API_KEY=<your_api_key>
+```
+
+- `OPENSTEER_BASE_URL` overrides the default cloud host
+- `OPENSTEER_AUTH_SCHEME` supports `api-key` (default) or `bearer`
 - `cloud: true` or a `cloud` options object overrides `OPENSTEER_MODE`
+- Cloud mode is fail-fast (no automatic fallback to local)
+- `Opensteer.from(page)`, `uploadFile`, `exportCookies`, and `importCookies` are local-only
+
+## Resolution and Replay
+
+For descriptor-aware actions (`click`, `input`, `hover`, `select`, `scroll`):
 
-`.env` files are auto-loaded from `storage.rootDir` (default `process.cwd()`)
-in this order: `.env.<NODE_ENV>.local`, `.env.local` (except in test),
-`.env.<NODE_ENV>`, `.env`. Existing `process.env` values are not overwritten.
-Set `OPENSTEER_DISABLE_DOTENV_AUTOLOAD=true` to disable.
+1. Reuse persisted selector path from `description`
+2. Try snapshot counter (`element`)
+3. Try explicit CSS selector (`selector`)
+4. Use LLM resolution (`description` required)
+5. Return actionable error
+
+When step 2-4 succeeds and `description` is present, selector paths are cached
+in `.opensteer/selectors/<namespace>` for deterministic replay.
 
 ## Docs
 
@@ -133,13 +184,23 @@ Set `OPENSTEER_DISABLE_DOTENV_AUTOLOAD=true` to disable.
 - [Selectors and Storage](docs/selectors.md)
 - [HTML Cleaning and Snapshot Modes](docs/html-cleaning.md)
 - [Live Web Validation Suite](docs/live-web-tests.md)
+- [Skills](docs/skills.md)
+
+## Development
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm test
+pnpm build
+```
 
 ## Community
 
-- [Contributing Guide](CONTRIBUTING.md)
+- [Contributing](CONTRIBUTING.md)
 - [Code of Conduct](CODE_OF_CONDUCT.md)
 - [Security Policy](SECURITY.md)
-- [Support](SUPPORT.md)
+- [Discussions](https://github.com/steerlabs/opensteer/discussions)
 - [Changelog](CHANGELOG.md)
 
 ## License

package/bin/opensteer.mjs

@@ -14,10 +14,38 @@ import {
 import { connect } from 'net'
 import { tmpdir } from 'os'
 import { dirname, join } from 'path'
-import { fileURLToPath } from 'url'
+import { fileURLToPath, pathToFileURL } from 'url'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const SERVER_SCRIPT = join(__dirname, '..', 'dist', 'cli', 'server.js')
+const SKILLS_INSTALLER_SCRIPT = join(
+    __dirname,
+    '..',
+    'dist',
+    'cli',
+    'skills-installer.js'
+)
+const SKILLS_HELP_TEXT = `Usage: opensteer skills <install|add> [options]
+
+Installs the first-party Opensteer skill using the upstream "skills" CLI.
+
+Commands:
+  install                  Install the opensteer skill
+  add                      Alias for install
+
+Supported Options:
+  -a, --agent <agents...>  Target specific agent(s)
+  -g, --global             Install globally
+  -y, --yes                Skip confirmations
+  --copy                   Copy files instead of symlinking
+  --all                    Install to all agents
+  -h, --help               Show this help
+
+Examples:
+  opensteer skills install
+  opensteer skills add --agent codex --global --yes
+  opensteer skills install --all --yes
+`
 
 const CONNECT_TIMEOUT = 15000
 const POLL_INTERVAL = 100
@@ -735,6 +763,46 @@ function toObject(value) {
     return value
 }
 
+function isSkillsHelpRequest(args) {
+    if (args.length === 0) return true
+
+    const [subcommand, ...rest] = args
+    if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
+        return true
+    }
+
+    if (subcommand !== 'install' && subcommand !== 'add') {
+        return false
+    }
+
+    return rest.includes('--help') || rest.includes('-h')
+}
+
+function printSkillsHelp() {
+    process.stdout.write(SKILLS_HELP_TEXT)
+}
+
+async function runSkillsSubcommand(args) {
+    if (isSkillsHelpRequest(args)) {
+        printSkillsHelp()
+        return
+    }
+
+    if (!existsSync(SKILLS_INSTALLER_SCRIPT)) {
+        throw new Error(
+            `Skills installer module not found: ${SKILLS_INSTALLER_SCRIPT}. Run the build script first.`
+        )
+    }
+
+    const moduleUrl = pathToFileURL(SKILLS_INSTALLER_SCRIPT).href
+    const { runOpensteerSkillsInstaller } = await import(moduleUrl)
+
+    const exitCode = await runOpensteerSkillsInstaller(args)
+    if (exitCode !== 0) {
+        process.exit(exitCode)
+    }
+}
+
 function printHelp() {
     console.log(`Usage: opensteer <command> [options]
 
@@ -794,6 +862,11 @@ Utility:
   wait-selector <selector>  Wait for selector
   extract <schema-json>     Extract structured data
 
+Skills:
+  skills install [options]  Install Opensteer skill pack for supported agents
+  skills add [options]      Alias for "skills install"
+  skills --help             Show skills installer help
+
 Global Flags:
   --session <id>            Runtime session id for daemon/browser routing
   --name <namespace>        Selector namespace for cache storage on 'open'
@@ -820,6 +893,19 @@ Environment:
 }
 
 async function main() {
+    const rawArgs = process.argv.slice(2)
+    if (rawArgs[0] === 'skills') {
+        try {
+            await runSkillsSubcommand(rawArgs.slice(1))
+        } catch (err) {
+            const message =
+                err instanceof Error ? err.message : 'Failed to run skills command'
+            process.stderr.write(`${message}\n`)
+            process.exit(1)
+        }
+        return
+    }
+
     const { command, flags, positional } = parseArgs(process.argv)
 
     if (command === 'sessions') {

package/dist/cli/skills-installer.cjs

@@ -0,0 +1,230 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/cli/skills-installer.ts
+var skills_installer_exports = {};
+__export(skills_installer_exports, {
+  createSkillsInstallInvocation: () => createSkillsInstallInvocation,
+  parseOpensteerSkillsArgs: () => parseOpensteerSkillsArgs,
+  resolveLocalSkillSourcePath: () => resolveLocalSkillSourcePath,
+  resolveSkillsCliPath: () => resolveSkillsCliPath,
+  runOpensteerSkillsInstaller: () => runOpensteerSkillsInstaller
+});
+module.exports = __toCommonJS(skills_installer_exports);
+var import_node_child_process = require("child_process");
+var import_node_module = require("module");
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var HELP_TEXT = `Usage: opensteer skills <install|add> [options]
+
+Installs the first-party Opensteer skill using the upstream "skills" CLI.
+
+Commands:
+  install                  Install the opensteer skill
+  add                      Alias for install
+
+Supported Options:
+  -a, --agent <agents...>  Target specific agent(s)
+  -g, --global             Install globally
+  -y, --yes                Skip confirmations
+  --copy                   Copy files instead of symlinking
+  --all                    Install to all agents
+  -h, --help               Show this help
+
+Examples:
+  opensteer skills install
+  opensteer skills add --agent codex --global --yes
+  opensteer skills install --all --yes
+`;
+function parseOpensteerSkillsArgs(rawArgs) {
+  if (rawArgs.length === 0) {
+    return { mode: "help", passthroughArgs: [] };
+  }
+  const [subcommand, ...rest] = rawArgs;
+  if (subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+    return { mode: "help", passthroughArgs: [] };
+  }
+  if (subcommand !== "install" && subcommand !== "add") {
+    return {
+      mode: "error",
+      passthroughArgs: [],
+      error: `Unsupported skills subcommand "${subcommand}". Use "install" or "add".`
+    };
+  }
+  const passthroughArgs = [];
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === "--help" || arg === "-h") {
+      return { mode: "help", passthroughArgs: [] };
+    }
+    if (arg === "--global" || arg === "-g") {
+      passthroughArgs.push(arg);
+      continue;
+    }
+    if (arg === "--yes" || arg === "-y") {
+      passthroughArgs.push(arg);
+      continue;
+    }
+    if (arg === "--copy" || arg === "--all") {
+      passthroughArgs.push(arg);
+      continue;
+    }
+    if (arg === "--agent" || arg === "-a") {
+      passthroughArgs.push(arg);
+      if (i + 1 >= rest.length || rest[i + 1]?.startsWith("-")) {
+        return {
+          mode: "error",
+          passthroughArgs: [],
+          error: `${arg} requires at least one value.`
+        };
+      }
+      while (i + 1 < rest.length && !rest[i + 1]?.startsWith("-")) {
+        i += 1;
+        const agent = rest[i];
+        if (agent) {
+          passthroughArgs.push(agent);
+        }
+      }
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      return {
+        mode: "error",
+        passthroughArgs: [],
+        error: `Unsupported option "${arg}" for "opensteer skills".`
+      };
+    }
+    return {
+      mode: "error",
+      passthroughArgs: [],
+      error: `Unexpected argument "${arg}".`
+    };
+  }
+  return {
+    mode: "install",
+    passthroughArgs
+  };
+}
+function resolveLocalSkillSourcePath() {
+  const packageRoot = resolvePackageRoot();
+  const sourcePath = (0, import_node_path.join)(packageRoot, "skills");
+  if (!(0, import_node_fs.existsSync)(sourcePath)) {
+    throw new Error(
+      `Opensteer skill source was not found at "${sourcePath}".`
+    );
+  }
+  return sourcePath;
+}
+function resolveSkillsCliPath() {
+  const require2 = (0, import_node_module.createRequire)(resolveCliEntrypointPath());
+  const skillsPackagePath = require2.resolve("skills/package.json");
+  const skillsPackageDir = (0, import_node_path.dirname)(skillsPackagePath);
+  const cliPath = (0, import_node_path.join)(skillsPackageDir, "bin", "cli.mjs");
+  if (!(0, import_node_fs.existsSync)(cliPath)) {
+    throw new Error(`skills CLI entrypoint was not found at "${cliPath}".`);
+  }
+  return cliPath;
+}
+function resolveCliEntrypointPath() {
+  const cliEntrypoint = process.argv[1];
+  if (!cliEntrypoint) {
+    throw new Error("Unable to resolve CLI entrypoint path for skills installer.");
+  }
+  return (0, import_node_fs.realpathSync)(cliEntrypoint);
+}
+function resolvePackageRoot() {
+  const cliEntrypointPath = resolveCliEntrypointPath();
+  const binDir = (0, import_node_path.dirname)(cliEntrypointPath);
+  return (0, import_node_path.resolve)(binDir, "..");
+}
+function createSkillsInstallInvocation(args) {
+  return {
+    cliPath: args.skillsCliPath,
+    cliArgs: [
+      "add",
+      args.localSkillSourcePath,
+      "--skill",
+      "opensteer",
+      ...args.passthroughArgs
+    ]
+  };
+}
+async function spawnInvocation(invocation) {
+  return await new Promise((resolvePromise, rejectPromise) => {
+    const child = (0, import_node_child_process.spawn)(process.execPath, [invocation.cliPath, ...invocation.cliArgs], {
+      stdio: "inherit",
+      env: process.env,
+      cwd: process.cwd()
+    });
+    child.once("error", (error) => {
+      rejectPromise(error);
+    });
+    child.once("exit", (code) => {
+      if (typeof code === "number") {
+        resolvePromise(code);
+        return;
+      }
+      resolvePromise(1);
+    });
+  });
+}
+function createDefaultDeps() {
+  return {
+    resolveSkillsCliPath,
+    resolveLocalSkillSourcePath,
+    spawnInvocation,
+    writeStdout(message) {
+      process.stdout.write(message);
+    },
+    writeStderr(message) {
+      process.stderr.write(message);
+    }
+  };
+}
+async function runOpensteerSkillsInstaller(rawArgs, overrideDeps = {}) {
+  const deps = {
+    ...createDefaultDeps(),
+    ...overrideDeps
+  };
+  const parsed = parseOpensteerSkillsArgs(rawArgs);
+  if (parsed.mode === "help") {
+    deps.writeStdout(HELP_TEXT);
+    return 0;
+  }
+  if (parsed.mode === "error") {
+    deps.writeStderr(`${parsed.error}
+`);
+    deps.writeStderr('Run "opensteer skills --help" for usage.\n');
+    return 1;
+  }
+  const invocation = createSkillsInstallInvocation({
+    localSkillSourcePath: deps.resolveLocalSkillSourcePath(),
+    passthroughArgs: parsed.passthroughArgs,
+    skillsCliPath: deps.resolveSkillsCliPath()
+  });
+  return await deps.spawnInvocation(invocation);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createSkillsInstallInvocation,
+  parseOpensteerSkillsArgs,
+  resolveLocalSkillSourcePath,
+  resolveSkillsCliPath,
+  runOpensteerSkillsInstaller
+});

package/dist/cli/skills-installer.d.cts

@@ -0,0 +1,28 @@
+type ParseMode = 'help' | 'install' | 'error';
+interface ParsedSkillsArgs {
+    mode: ParseMode;
+    passthroughArgs: string[];
+    error?: string;
+}
+interface SkillsInstallInvocation {
+    cliPath: string;
+    cliArgs: string[];
+}
+interface SkillsInstallerDeps {
+    resolveSkillsCliPath: () => string;
+    resolveLocalSkillSourcePath: () => string;
+    spawnInvocation: (invocation: SkillsInstallInvocation) => Promise<number>;
+    writeStdout: (message: string) => void;
+    writeStderr: (message: string) => void;
+}
+declare function parseOpensteerSkillsArgs(rawArgs: string[]): ParsedSkillsArgs;
+declare function resolveLocalSkillSourcePath(): string;
+declare function resolveSkillsCliPath(): string;
+declare function createSkillsInstallInvocation(args: {
+    localSkillSourcePath: string;
+    passthroughArgs: string[];
+    skillsCliPath: string;
+}): SkillsInstallInvocation;
+declare function runOpensteerSkillsInstaller(rawArgs: string[], overrideDeps?: Partial<SkillsInstallerDeps>): Promise<number>;
+
+export { createSkillsInstallInvocation, parseOpensteerSkillsArgs, resolveLocalSkillSourcePath, resolveSkillsCliPath, runOpensteerSkillsInstaller };

package/dist/cli/skills-installer.d.ts

@@ -0,0 +1,28 @@
+type ParseMode = 'help' | 'install' | 'error';
+interface ParsedSkillsArgs {
+    mode: ParseMode;
+    passthroughArgs: string[];
+    error?: string;
+}
+interface SkillsInstallInvocation {
+    cliPath: string;
+    cliArgs: string[];
+}
+interface SkillsInstallerDeps {
+    resolveSkillsCliPath: () => string;
+    resolveLocalSkillSourcePath: () => string;
+    spawnInvocation: (invocation: SkillsInstallInvocation) => Promise<number>;
+    writeStdout: (message: string) => void;
+    writeStderr: (message: string) => void;
+}
+declare function parseOpensteerSkillsArgs(rawArgs: string[]): ParsedSkillsArgs;
+declare function resolveLocalSkillSourcePath(): string;
+declare function resolveSkillsCliPath(): string;
+declare function createSkillsInstallInvocation(args: {
+    localSkillSourcePath: string;
+    passthroughArgs: string[];
+    skillsCliPath: string;
+}): SkillsInstallInvocation;
+declare function runOpensteerSkillsInstaller(rawArgs: string[], overrideDeps?: Partial<SkillsInstallerDeps>): Promise<number>;
+
+export { createSkillsInstallInvocation, parseOpensteerSkillsArgs, resolveLocalSkillSourcePath, resolveSkillsCliPath, runOpensteerSkillsInstaller };