@agentrhq/webcmd 0.2.1 → 0.2.2

package/README.md

@@ -14,7 +14,7 @@
     <img alt="Join the community on Discord" src="https://img.shields.io/badge/Join%20the%20community-7C3AED.svg?style=for-the-badge&logo=discord&logoColor=white&labelColor=000000&logoWidth=20">
   </a>
   <a href="https://x.com/agentrhq">
-    <img alt="Follow AgentR on X" src="https://img.shields.io/badge/Follow%20%40agentrhq-000000.svg?style=for-the-badge&logo=x&logoColor=white&labelColor=000000&logoWidth=20">
+    <img alt="Follow AgentR on X" src="https://img.shields.io/badge/Built%20by%20%40agentrhq-000000.svg?style=for-the-badge&logo=x&logoColor=white&labelColor=000000&logoWidth=20">
   </a>
 </p>
 
@@ -24,14 +24,14 @@
 
 WebCMD learns the navigational context of websites as agents use them, then compiles that knowledge into deterministic commands for faster, cheaper, more reliable browser automation. The goal is simple: stop making agents rediscover the same sites on every run and cut browser-agent token spend by up to 90%.
 
-On top of vanilla browser interactions, WebCMD adds 3 layers of learnings. Each layer collapses cost and variance for the layer above it.
+On top of live browser control, WebCMD adds 3 layers of learnings. Each layer collapses cost and variance for the layer above it.
 
 | Layer | Scenario | What Webcmd Helps With |
 | --- | --- | --- |
 | 1. Live browser control | The site is unfamiliar. | Use `webcmd browser` to inspect, click, type, extract, capture network calls, and complete the task in a real browser. |
 | 2. Sitemap memory | The site is familiar, but the action space is not fully known. | Capture an agent-facing sitemap of observed pages, states, actions, workflows, APIs, pitfalls, and fallback paths. |
-| 3. CLI authoring | The action space is known, but the path is still too variable for one fixed sequence. | Explicitly author a reusable `webcmd <site> <command>` adapter with structured output, so future agents spend tokens on the task instead of navigation. |
-| 4. Custom CLI commands | The workflow is deterministic enough to stop browsing. | Extend the CLI with a tailored command so the workflow runs instantly with the least amount of tokens. |
+| 3. CLI authoring | The action space is known, but the path is still too variable for one fixed sequence. | Explicitly author a reusable `webcmd <site>` adapter with structured output, so future agents spend tokens on the task instead of navigation. |
+| 4. Extend existing CLIs | The workflow is deterministic enough to stop browsing. | Extend the `webcmd <site>` adapter with a tailored command so the workflow runs instantly with the least amount of tokens. |
 
 
 ## Quick Start
@@ -51,7 +51,7 @@ npm install -g @agentrhq/webcmd
 webcmd doctor
 ```
 
-`doctor` checks the Webcmd browser bridge: daemon status, runtime wiring, profile selection, and a live connectivity probe. Pure public adapters and local passthrough commands do not need a green browser check, but `COOKIE`, `INTERCEPT`, `UI`, and `webcmd browser` workflows do.
+`doctor` checks the Webcmd browser bridge: daemon status, browser runtime installation, profile selection, and a live connectivity probe. Pure public adapters and local passthrough commands do not need a green browser check, but `COOKIE`, `INTERCEPT`, `UI`, and `webcmd browser` workflows do.
 
 ### 3. Discover commands
 
@@ -64,7 +64,7 @@ webcmd reddit hot --help
 
 `webcmd list -f json` is the source of truth for agents. It emits one row per command with the site, command name, arguments, output columns, browser requirement, and strategy.
 
-### 4. Run your first adapters
+### 4. Run your first command
 
 ```bash
 webcmd hackernews top --limit 5
@@ -80,23 +80,20 @@ Use Webcmd directly when you want a reliable command instead of a live browser s
 webcmd list
 webcmd <site> --help
 webcmd <site> <command> --help
-webcmd <site> <command> -f json
+webcmd <site> <command> -f yaml
 ```
 
 The everyday surface is intentionally small:
 
 - `webcmd list` shows every registered adapter and external command.
 - `webcmd <site> <command> ...` runs a built-in, plugin, or private adapter.
-- `webcmd external register <name>` exposes a local CLI through the same discovery surface.
-- `webcmd doctor` diagnoses browser connectivity for authenticated or UI-driven commands.
 
 For example:
 
 ```bash
 webcmd hackernews top --limit 10
 webcmd reddit subreddit programming --limit 10
-webcmd github whoami
-webcmd gh pr list --limit 5
+webcmd twitter whoami
 ```
 
 Adapter commands are tagged by strategy:
@@ -119,19 +116,23 @@ webcmd hackernews top -f md
 webcmd hackernews top -f csv
 ```
 
-Agents usually want `-f json`; humans usually want the default table.
+Agents usually want `-f json`; humans usually want table (default) or yaml.
 
 ## For AI Agents
 
 Webcmd is designed to be driven by coding agents such as Codex, Claude Code, Cursor, and similar tools.
 
-Install Webcmd skills into the agent environment with your agent's skill manager:
+## Install skills (also refreshes existing installs)
+
+Install Webcmd skills into your agent environment:
 
 ```bash
-npx skills add agentrhq/webcmd
+webcmd skills install
 ```
 
-Or install/copy only the skills you need from [`skills/`](./skills/) into your agent's skills root. These skills teach agents when to use adapters, when to drive the browser, how to author new adapters, and how to repair failing commands.
+The installer asks whether to install globally or locally, then asks for the coding agent (`agents`, `codex`, `claude`) or a custom skills path. For scripts, pass flags such as `--scope project --provider codex` or `--path ./my-skills`.
+
+### Which skill to use
 
 | Skill | When to use |
 |-------|-------------|
@@ -153,20 +154,34 @@ webcmd <site> <command> --trace retain-on-failure -f json
 
 Start with adapters. Fall back to `webcmd browser` only when no adapter covers the task or you are teaching Webcmd a new site flow.
 
-## Browser Automation
+## Live Browser Interaction
+
+`webcmd browser` gives agents a stable, structured interface to a real browser. Every command takes a session name immediately after `browser` — the session is required, so `webcmd browser tab list` without one is an error:
+
+```bash
+webcmd browser <session> open https://example.com
+```
+
+### Tabs and page IDs
 
-`webcmd browser` gives agents a stable, structured interface to a real browser. Commands use a session name immediately after `browser`:
+`webcmd browser work open <url>` and `webcmd browser work tab new [url]` both return a page ID in the `page` field:
 
 ```bash
-webcmd browser work open https://example.com
-webcmd browser work state
-webcmd browser work click --role link --name "Learn more"
-webcmd browser work type --role textbox --name Email "you@example.com"
-webcmd browser work keys Enter
-webcmd browser work extract
-webcmd browser work close
+$ webcmd browser work open https://reddit.com
+{
+  "url": "https://reddit.com",
+  "page": "page-1783484232033-8"
+}
 ```
 
+Use `webcmd browser work tab list` to inspect all tabs — each entry carries its page ID (`id`/`page`), the owning `session` (adapter sessions appear as `site:<name>`), and whether it is the currently `selected` tab. Pass `--tab <pageId>` to route a single command to a specific tab:
+
+```bash
+webcmd browser work open https://example.com --tab page-1783484232033-8
+```
+
+`tab new` creates a tab without changing the session's default tab; only `tab select <pageId>` promotes a tab to the default for later untargeted commands in the same session.
+
 Useful browser primitives include:
 
 | Area | Commands |

package/cli-manifest.json

@@ -6912,6 +6912,510 @@
     "sourceFile": "discord-app/threads.js",
     "navigateBefore": true
   },
+  {
+    "site": "district",
+    "name": "checkout",
+    "description": "Select District movie seats and stop at the payment handoff page",
+    "access": "write",
+    "domain": "www.district.in",
+    "strategy": "cookie",
+    "browser": true,
+    "args": [
+      {
+        "name": "show",
+        "type": "str",
+        "required": true,
+        "positional": true,
+        "help": "District seat-layout URL or showId from district showtimes"
+      },
+      {
+        "name": "seats",
+        "type": "str",
+        "required": true,
+        "help": "Comma-separated seat labels to select, e.g. I22,I21"
+      },
+      {
+        "name": "format-id",
+        "type": "str",
+        "required": false,
+        "help": "District formatId from showtimes; required when show is a showId"
+      },
+      {
+        "name": "content-id",
+        "type": "str",
+        "required": false,
+        "help": "District content id; required when show is a showId"
+      },
+      {
+        "name": "timeout",
+        "type": "int",
+        "default": 45,
+        "required": false,
+        "help": "Maximum seconds to wait for selection and review page"
+      }
+    ],
+    "columns": [
+      "status",
+      "movie",
+      "cinema",
+      "date",
+      "time",
+      "seats",
+      "ticketCount",
+      "orderAmount",
+      "bookingCharge",
+      "total",
+      "paymentUrl",
+      "showId"
+    ],
+    "type": "js",
+    "modulePath": "district/checkout.js",
+    "sourceFile": "district/checkout.js",
+    "navigateBefore": false,
+    "siteSession": "persistent",
+    "freshPage": true,
+    "defaultWindowMode": "foreground"
+  },
+  {
+    "site": "district",
+    "name": "listings",
+    "aliases": [
+      "ls"
+    ],
+    "description": "List public District by Zomato movies, events, and nearby going-out cards",
+    "access": "read",
+    "domain": "www.district.in",
+    "strategy": "public",
+    "browser": false,
+    "args": [
+      {
+        "name": "input",
+        "type": "str",
+        "default": "home",
+        "required": false,
+        "positional": true,
+        "help": "home, movies, events, a district.in URL, or a District path"
+      },
+      {
+        "name": "limit",
+        "type": "int",
+        "default": 20,
+        "required": false,
+        "help": "Maximum rows to return (1-100)"
+      }
+    ],
+    "columns": [
+      "rank",
+      "title",
+      "category",
+      "date",
+      "venue",
+      "price",
+      "url"
+    ],
+    "type": "js",
+    "modulePath": "district/listings.js",
+    "sourceFile": "district/listings.js"
+  },
+  {
+    "site": "district",
+    "name": "locations",
+    "aliases": [
+      "location-search"
+    ],
+    "description": "Search District-supported cities, areas, malls, and places for booking filters",
+    "access": "read",
+    "domain": "www.district.in",
+    "strategy": "public",
+    "browser": false,
+    "args": [
+      {
+        "name": "query",
+        "type": "str",
+        "required": true,
+        "positional": true,
+        "help": "City, area, mall, or locality, for example \"bangalore\" or \"indiranagar\""
+      },
+      {
+        "name": "limit",
+        "type": "int",
+        "default": 10,
+        "required": false,
+        "help": "Maximum location rows to return (1-50)"
+      }
+    ],
+    "columns": [
+      "rank",
+      "name",
+      "kind",
+      "city",
+      "state",
+      "cityKey",
+      "cityId",
+      "placeId",
+      "lat",
+      "lng",
+      "distanceKm",
+      "source"
+    ],
+    "type": "js",
+    "modulePath": "district/locations.js",
+    "sourceFile": "district/locations.js"
+  },
+  {
+    "site": "district",
+    "name": "login",
+    "description": "Open district login and wait until the browser session is authenticated",
+    "access": "write",
+    "domain": "www.district.in",
+    "strategy": "cookie",
+    "browser": true,
+    "args": [
+      {
+        "name": "timeout",
+        "type": "int",
+        "default": 300,
+        "required": false,
+        "help": "Maximum seconds to wait for the user to finish login"
+      }
+    ],
+    "columns": [
+      "status",
+      "logged_in",
+      "site",
+      "user_id",
+      "name",
+      "phone_number",
+      "email"
+    ],
+    "type": "js",
+    "modulePath": "district/auth.js",
+    "sourceFile": "district/auth.js",
+    "navigateBefore": false,
+    "siteSession": "persistent",
+    "defaultWindowMode": "foreground"
+  },
+  {
+    "site": "district",
+    "name": "search",
+    "aliases": [
+      "s"
+    ],
+    "description": "Search District by Zomato across movies, events, dining, stores, activities, and play",
+    "access": "read",
+    "domain": "www.district.in",
+    "strategy": "public",
+    "browser": false,
+    "args": [
+      {
+        "name": "query",
+        "type": "str",
+        "required": true,
+        "positional": true,
+        "help": "Search query, for example \"hamlet\" or \"arijit\""
+      },
+      {
+        "name": "limit",
+        "type": "int",
+        "default": 20,
+        "required": false,
+        "help": "Maximum rows to return (1-100)"
+      },
+      {
+        "name": "tab",
+        "type": "str",
+        "default": "all",
+        "required": false,
+        "help": "Search tab: all, dining, events, movies, stores, activities, or play"
+      }
+    ],
+    "columns": [
+      "rank",
+      "title",
+      "category",
+      "date",
+      "venue",
+      "price",
+      "url"
+    ],
+    "type": "js",
+    "modulePath": "district/search.js",
+    "sourceFile": "district/search.js"
+  },
+  {
+    "site": "district",
+    "name": "seats",
+    "description": "List available seats for a District movie showtime",
+    "access": "read",
+    "domain": "www.district.in",
+    "strategy": "cookie",
+    "browser": true,
+    "args": [
+      {
+        "name": "show",
+        "type": "str",
+        "required": true,
+        "positional": true,
+        "help": "District seat-layout URL or showId from district showtimes"
+      },
+      {
+        "name": "format-id",
+        "type": "str",
+        "required": false,
+        "help": "District formatId from showtimes; required when show is a showId"
+      },
+      {
+        "name": "content-id",
+        "type": "str",
+        "required": false,
+        "help": "District content id; required when show is a showId"
+      },
+      {
+        "name": "class",
+        "type": "str",
+        "required": false,
+        "help": "Optional seat class filter, e.g. premium, premium xl, or recliner"
+      },
+      {
+        "name": "count",
+        "type": "int",
+        "required": false,
+        "help": "Number of seats to choose (1-10); without count, seats are listed normally"
+      },
+      {
+        "name": "together",
+        "type": "str",
+        "required": false,
+        "help": "Require selected seats to be adjacent when count is provided"
+      },
+      {
+        "name": "max-price",
+        "type": "float",
+        "required": false,
+        "help": "Maximum price per seat"
+      },
+      {
+        "name": "limit",
+        "type": "int",
+        "default": 100,
+        "required": false,
+        "help": "Maximum seats to return (1-300)"
+      },
+      {
+        "name": "timeout",
+        "type": "int",
+        "default": 30,
+        "required": false,
+        "help": "Maximum seconds to wait for the seat map to render"
+      }
+    ],
+    "columns": [
+      "rank",
+      "seat",
+      "row",
+      "number",
+      "column",
+      "seatClass",
+      "price",
+      "status",
+      "flags",
+      "showId",
+      "formatId",
+      "url"
+    ],
+    "type": "js",
+    "modulePath": "district/seats.js",
+    "sourceFile": "district/seats.js",
+    "navigateBefore": false,
+    "siteSession": "persistent",
+    "defaultWindowMode": "foreground"
+  },
+  {
+    "site": "district",
+    "name": "set-location",
+    "aliases": [
+      "setlocation"
+    ],
+    "description": "Set the District browser session location for movie booking filters",
+    "access": "write",
+    "domain": "www.district.in",
+    "strategy": "cookie",
+    "browser": true,
+    "args": [
+      {
+        "name": "location",
+        "type": "str",
+        "required": true,
+        "positional": true,
+        "help": "City, area, mall, or locality, for example \"Bangalore\" or \"Indiranagar\""
+      },
+      {
+        "name": "rank",
+        "type": "int",
+        "default": 1,
+        "required": false,
+        "help": "Pick the Nth District location result (1-20), default: 1"
+      },
+      {
+        "name": "timeout",
+        "type": "int",
+        "default": 45,
+        "required": false,
+        "help": "Maximum seconds to wait for the picker and location change"
+      }
+    ],
+    "columns": [
+      "status",
+      "name",
+      "city",
+      "state",
+      "cityKey",
+      "cityId",
+      "placeId",
+      "subzoneId",
+      "lat",
+      "lng",
+      "availableTabs",
+      "source"
+    ],
+    "type": "js",
+    "modulePath": "district/set-location.js",
+    "sourceFile": "district/set-location.js",
+    "navigateBefore": false,
+    "siteSession": "persistent",
+    "defaultWindowMode": "foreground"
+  },
+  {
+    "site": "district",
+    "name": "showtimes",
+    "aliases": [
+      "shows"
+    ],
+    "description": "List District movie showtimes with location, time, cinema, language, price, and format filters",
+    "access": "read",
+    "domain": "www.district.in",
+    "strategy": "cookie",
+    "browser": true,
+    "args": [
+      {
+        "name": "movie",
+        "type": "str",
+        "required": true,
+        "positional": true,
+        "help": "Movie name or District movie URL"
+      },
+      {
+        "name": "date",
+        "type": "str",
+        "required": false,
+        "help": "Show date in YYYY-MM-DD format; defaults to District selected date"
+      },
+      {
+        "name": "city",
+        "type": "str",
+        "required": false,
+        "help": "District city name/key, for example Bangalore or Bengaluru"
+      },
+      {
+        "name": "near",
+        "type": "str",
+        "required": false,
+        "help": "Area, mall, or locality to search near, for example Indiranagar"
+      },
+      {
+        "name": "city-key",
+        "type": "str",
+        "required": false,
+        "help": "Legacy District city key override, for example bengaluru"
+      },
+      {
+        "name": "after",
+        "type": "str",
+        "required": false,
+        "help": "Only shows at or after HH:MM, 24-hour time"
+      },
+      {
+        "name": "before",
+        "type": "str",
+        "required": false,
+        "help": "Only shows at or before HH:MM, 24-hour time"
+      },
+      {
+        "name": "cinema",
+        "type": "str",
+        "required": false,
+        "help": "Filter cinema/theatre name, for example PVR, INOX, Orion"
+      },
+      {
+        "name": "language",
+        "type": "str",
+        "required": false,
+        "help": "Filter movie language, for example English, Hindi, Kannada"
+      },
+      {
+        "name": "max-price",
+        "type": "float",
+        "required": false,
+        "help": "Only shows with at least one ticket class at or below this price"
+      },
+      {
+        "name": "quality",
+        "type": "str",
+        "required": false,
+        "help": "Generic format/quality filter, for example 2D, 3D, IMAX, IMAX 3D, 4DX"
+      },
+      {
+        "name": "limit",
+        "type": "int",
+        "default": 50,
+        "required": false,
+        "help": "Maximum showtime rows to return (1-200)"
+      }
+    ],
+    "columns": [
+      "rank",
+      "movie",
+      "language",
+      "date",
+      "time",
+      "cinema",
+      "format",
+      "priceRange",
+      "available",
+      "showId",
+      "formatId",
+      "url"
+    ],
+    "type": "js",
+    "modulePath": "district/showtimes.js",
+    "sourceFile": "district/showtimes.js",
+    "navigateBefore": false,
+    "siteSession": "persistent",
+    "defaultWindowMode": "foreground"
+  },
+  {
+    "site": "district",
+    "name": "whoami",
+    "description": "Show the current logged-in district account",
+    "access": "read",
+    "domain": "www.district.in",
+    "strategy": "cookie",
+    "browser": true,
+    "args": [],
+    "columns": [
+      "logged_in",
+      "site",
+      "user_id",
+      "name",
+      "phone_number",
+      "email"
+    ],
+    "type": "js",
+    "modulePath": "district/auth.js",
+    "sourceFile": "district/auth.js",
+    "navigateBefore": false,
+    "siteSession": "persistent"
+  },
   {
     "site": "dockerhub",
     "name": "image",

package/clis/_shared/site-auth.js

@@ -46,6 +46,11 @@ export function registerSiteAuthCommands(config) {
   if (!config?.site || !config?.domain || !config?.loginUrl || typeof config.verify !== 'function') {
     throw new Error('registerSiteAuthCommands requires site, domain, loginUrl, and verify(page)');
   }
+  // Sites whose login is a modal/flow rather than a page can pass
+  // openLogin(page) to bring the login UI up; default is a plain navigation.
+  const openLogin = typeof config.openLogin === 'function'
+    ? config.openLogin
+    : async (page) => { await page.goto(config.loginUrl); };
 
   cli({
     site: config.site,
@@ -92,7 +97,7 @@ export function registerSiteAuthCommands(config) {
         if (!isAuthRequired(error)) throw error;
       }
 
-      await page.goto(config.loginUrl);
+      await openLogin(page);
       const timeoutSeconds = Number(kwargs.timeout ?? DEFAULT_TIMEOUT_SECONDS);
       const deadline = Date.now() + timeoutSeconds * 1000;
       let lastAuthMessage = '';