@agentrhq/webcmd 0.2.0 → 0.2.2

package/README.md

@@ -1,26 +1,38 @@
 <img width="2054" height="766" alt="Webcmd banner" src="https://github.com/user-attachments/assets/3e5b9702-5ffd-43bd-ab1b-2319a8cc0e2a" />
 
-# Webcmd
-
 <p align="center">
   <a href="https://www.npmjs.com/package/@agentrhq/webcmd">
     <img alt="NPM version" src="https://img.shields.io/npm/v/@agentrhq/webcmd.svg?style=for-the-badge&color=1E88E5&labelColor=000000">
   </a>
+  <a href="https://www.npmjs.com/package/@agentrhq/webcmd">
+    <img alt="NPM downloads" src="https://img.shields.io/npm/dt/@agentrhq/webcmd.svg?style=for-the-badge&color=1E88E5&labelColor=000000">
+  </a>
   <a href="https://github.com/agentrhq/webcmd/blob/main/LICENSE">
     <img alt="License" src="https://img.shields.io/badge/license-Apache%202.0-1E88E5.svg?style=for-the-badge&labelColor=000000">
   </a>
-  <a href="https://github.com/agentrhq/webcmd/discussions">
-    <img alt="Join the community on GitHub" src="https://img.shields.io/badge/Join%20the%20community-1E88E5.svg?style=for-the-badge&logo=github&labelColor=000000&logoWidth=20">
+  <a href="https://discord.gg/9YP2C9tvMp">
+    <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/Built%20by%20%40agentrhq-000000.svg?style=for-the-badge&logo=x&logoColor=white&labelColor=000000&logoWidth=20">
   </a>
 </p>
 
-**Turn websites, browser sessions, desktop apps, and local tools into deterministic command-line surfaces for people and AI agents.**
+# Webcmd
+
+**Self-learning browser infra for AI agents.**
+
+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 live browser control, WebCMD adds 3 layers of learnings. Each layer collapses cost and variance for the layer above it.
 
-Webcmd gives you one command surface for three kinds of automation:
+| 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>` 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. |
 
-- **Use built-in adapters** for sites like Reddit, Hacker News, LinkedIn, Twitter/X, TikTok, Amazon, PubMed, ChatGPT, Claude, Gemini, NotebookLM, and many more.
-- **Let AI agents operate a real browser** with `webcmd browser <session> ...` primitives: open pages, inspect DOM snapshots, click, type, select, extract, capture network calls, and verify flows.
-- **Wrap local tools and desktop apps** so agents can discover and invoke `gh`, `docker`, `vercel`, Electron apps, and other command surfaces through the same `webcmd ...` entrypoint.
 
 ## Quick Start
 
@@ -39,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
 
@@ -52,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
@@ -68,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:
@@ -107,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 |
 |-------|-------------|
@@ -139,22 +152,36 @@ webcmd <site> <command> -f json
 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 debugging/building one.
+Start with adapters. Fall back to `webcmd browser` only when no adapter covers the task or you are teaching Webcmd a new site flow.
+
+## 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
+```
 
-## Browser Automation
+### 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 |
@@ -235,7 +262,7 @@ Use plugins for private company workflows, community adapters, or experiments th
 
 ## Writing Adapters
 
-When a site is not covered yet, author a reusable adapter instead of leaving an agent to click through the same browser flow every time.
+When a site is not covered yet, author a reusable adapter instead of leaving an agent to spend tokens clicking through the same browser flow every time.
 
 ```bash
 webcmd browser init <site>/<command>

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",
@@ -23638,6 +24142,8 @@
       "likes",
       "retweets",
       "replies",
+      "quotes",
+      "bookmarks",
       "views",
       "created_at",
       "url",