@agentrhq/webcmd 0.3.3 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentrhq/webcmd",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Turn websites, browser sessions, desktop apps, and local tools into deterministic CLI surfaces for humans and AI agents.",
   "engines": {
     "node": ">=20.0.0"
@@ -18,6 +18,7 @@
     "./utils": "./dist/src/utils.js",
     "./logger": "./dist/src/logger.js",
     "./launcher": "./dist/src/launcher.js",
+    "./browser/ax-snapshot": "./dist/src/browser/ax-snapshot.js",
     "./browser/cdp": "./dist/src/browser/cdp.js",
     "./browser/page": "./dist/src/browser/page.js",
     "./browser/utils": "./dist/src/browser/utils.js",
@@ -77,7 +78,7 @@
   ],
   "author": "AgentR",
   "license": "Apache-2.0",
-  "homepage": "https://docs.webcmd.dev",
+  "homepage": "https://webcmd.dev/docs",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/agentrhq/webcmd.git"
@@ -90,7 +91,7 @@
     "cli-table3": "^0.6.5",
     "cloakbrowser": "0.4.5",
     "commander": "^14.0.3",
-    "js-yaml": "^4.1.0",
+    "js-yaml": "^4.3.0",
     "playwright-core": "1.61.1",
     "turndown": "^7.2.2",
     "turndown-plugin-gfm": "^1.0.2",
@@ -113,4 +114,4 @@
   "overrides": {
     "postcss": "^8.5.10"
   }
-}
+}

package/skills/smart-search/SKILL.md

@@ -11,10 +11,24 @@ Route a query to the best webcmd search source based on the topic and context. T
 
 Before every use, do both of these steps:
 
-- Run `webcmd list -f json`
-- Use the live registry to confirm that candidate sites exist, and inspect `strategy`, `browser`, and `domain`
+- Derive literal workflow terms from the requested action, entity, output fields, and any explicitly named site, then filter the live registry before it reaches bounded agent output:
 
-If the user explicitly names a site/source and it is missing from `webcmd list` or when none of the sites cover the query, check installable plugins before marking it unavailable:
+  ```bash
+  WORKFLOW_TERMS='["requested action", "output field", "named site"]'
+  webcmd list -f json | jq --argjson terms "$WORKFLOW_TERMS" '
+    [.[] | select(
+      ([.site, .name, .description, ((.columns // []) | join(" "))]
+        | map(. // "") | join(" ") | ascii_downcase) as $text
+      | any($terms[]; . as $term | $text | contains($term | ascii_downcase))
+    )]
+  '
+  ```
+
+- Use the complete, non-truncated filtered registry to confirm that candidate sites exist, and inspect `strategy`, `browser`, and `domain`
+
+Any truncation warning from registry or plugin output means the inspection is incomplete. Narrow the filter or query and inspect again; absence from truncated output never proves a site, command, or plugin is unavailable. Do not search plugins until a complete filtered registry result for the missing capability is exactly `[]`, and do not use raw browser fallback until plugin output is also complete and non-truncated.
+
+If the user explicitly names a site/source, or no installed command covers the query, refine the filter for that missing site or capability. Only when the complete filtered result is `[]`, check installable plugins before marking it unavailable:
 
 ```bash
 webcmd plugin search <site-or-source-or-capability> -f json
@@ -22,7 +36,7 @@ webcmd plugin search <site-or-source-or-capability> -f json
 
 Derive a short plugin query from the missing site or capability. Preserve the user's term when practical: `find flights` becomes `flight`.
 
-If plugin search finds a match, tell the user it is available as a plugin and offer `webcmd plugin install <source>`. If plugin search fails because catalog sources cannot be fetched, report that catalog/search error separately from no plugin match.
+If a complete, non-truncated plugin search finds a match, tell the user it is available as a plugin and offer `webcmd plugin install <source>`. If plugin search is truncated, refine it before fallback. If it fails because catalog sources cannot be fetched, report that catalog/search error separately from no plugin match.
 
 After choosing a site, do both of these steps:
 
@@ -144,12 +158,12 @@ Keep a typical query to 1 AI source plus 1-2 specialized sources to avoid result
 When a site is unavailable:
 
 - Do not stop the whole search because one source failed
-- For a missing site or capability, run `webcmd plugin search <query> -f json` before recording unavailable
+- For a missing site or capability, first require a complete filtered registry result of `[]`, then run `webcmd plugin search <query> -f json` before recording unavailable
 - Record: `Skipped: <site> unavailable`
 - Fall back to another site of the same type, or to one AI source
 - Always trust the actual output of `webcmd list -f json`, `webcmd plugin search -f json`, and `webcmd <site> -h`
 
-Do not assume any site is always available. Even for public sites, trust live help and execution results in the current environment.
+Do not assume any site is always available. Even for public sites, trust complete, non-truncated live registry and plugin output, live help, and execution results in the current environment. Raw browser fallback requires both the complete `[]` registry result and a complete, non-truncated plugin search that returned no match and no error.
 
 ## Reference Files
 

package/skills/webcmd-adapter-author/SKILL.md

@@ -10,6 +10,8 @@ You are an agent writing an adapter for a site. The goal of this skill is a 30-m
 
 Use the existing tools throughout: `webcmd browser *`, `webcmd doctor`, `webcmd browser init`, and `webcmd browser verify`. This skill does not introduce new commands.
 
+Browser-profile auth commands must reuse `registerSiteAuthCommands`. Keep only site-specific `verify` and `openLogin` logic in the adapter. The login row must return `action_required` and `verify_command` (normally `webcmd <site> whoami`); after the user reports done, agents run that returned command and verification must succeed before retrying the original workflow. Credentials, MFA, and CAPTCHA always use human handoff: CAPTCHA stops automation until the user reports done and verification succeeds, and adapter code must not collect or type passwords or secrets.
+
 When debugging browser-backed adapters, start with `--trace on --keep-tab true --window foreground`. `--trace on` writes a trace artifact every round, and `summary.md` is the entry point for reviewing both failures and successes. `--keep-tab true --window foreground` keeps the tab lease alive and puts the browser window in front so you can inspect the final page state.
 
 ---

package/skills/webcmd-autofix/SKILL.md

@@ -12,9 +12,11 @@ When a `webcmd` command fails because a website changed its DOM, API, or respons
 
 Hard stops before any code change:
 
-- **`AUTH_REQUIRED`** (exit code 77): stop. Tell the user to log into the site in Chrome or the webcmd-managed browser profile.
+- **Human-action handoff:** if a failure returns `handoff.status === action_required`, stop before trace collection or AutoFix. Give the user `handoff.action` and any `Webcmd browser:` or `handoff.viewUrl` link, then wait. Never request or enter credentials, passwords, or CAPTCHA answers. After the user reports done, run `handoff.verifyCommand` when present; verification must succeed before retrying. Without a verifier, inspect fresh browser state and verify the intended post-action state before any retry, especially for write commands.
+- **`AUTH_REQUIRED`** (exit code 77): if a site login command exists, run `webcmd <site> login`, give its `action_required` instructions and any returned `action_url` or `view_url` to the user, and wait. Run the returned `verify_command` (normally `webcmd <site> whoami`); verification must succeed before retrying the original command. If no site login command exists, stop browser writes, hand the visible browser to the user, and wait. After they report done, take fresh browser state and use an available identity check or verify the intended post-action state before retrying. Their report alone is not verification. Never request, type, echo, store, or automate passwords, OTPs, recovery codes, cookies, or session secrets.
 - **`BROWSER_CONNECT`** (exit code 69): stop. Tell the user to run `webcmd doctor`.
-- **CAPTCHA / rate limiting / IP block:** stop. This is not an adapter issue.
+- **CAPTCHA / raw-browser user takeover:** stop automation. Follow the human-action handoff above when one is returned; otherwise let the user act in the visible browser. Verification must succeed before retrying. With no verifier, take fresh browser state and verify the intended post-action state before any retry. The user's report alone is not verification. CAPTCHA is not an adapter issue.
+- **Rate limiting / IP block:** stop. This is not an adapter issue.
 
 Scope constraint:
 
@@ -124,7 +126,7 @@ Read the trace summary and adapter source. Classify root cause:
 | SELECTOR | DOM restructured or class/id changed | Explore current DOM and find a stable selector |
 | EMPTY_RESULT | API response schema changed, data moved, or real empty result | Check network and visible page before patching |
 | API_ERROR | Endpoint URL changed or new params required | Discover current API through network evidence |
-| AUTH_REQUIRED | Login flow changed or cookies expired | Stop; ask user to log in |
+| AUTH_REQUIRED | Login flow changed or cookies expired | Follow the conditional AUTH_REQUIRED policy in Safety Boundaries: use the site login command and its returned verifier when available; otherwise use human handoff plus fresh-state supported verification. |
 | TIMEOUT | Page loads differently or lazy-load signal changed | Update wait conditions |
 | PAGE_CHANGED | Major redesign | May need full adapter rewrite through `webcmd-adapter-author` |
 

package/skills/webcmd-browser/SKILL.md

@@ -12,13 +12,26 @@ This skill is for **driving a live browser** to accomplish an agent task. If you
 
 ---
 
+## Adapter fallback gate
+
+Before starting a raw browser session, filter `webcmd list -f json` at the source using request-derived terms across `site`, `name`, `description`, and `columns`; follow `webcmd-usage` for the command shape. Any truncation warning means adapter discovery is incomplete: narrow the filter and inspect again. Absence from truncated output never proves that no adapter exists.
+
+Raw `webcmd browser` use is allowed only after both conditions hold:
+
+1. The complete, non-truncated filtered registry result for the missing capability is exactly `[]`.
+2. A complete, non-truncated `webcmd plugin search <capability> -f json` result returns no match and no error.
+
+If plugin search returns a match, offer installation. If its output is truncated, refine the query or output and inspect again. If it errors, report the error and stop instead of opening the browser.
+
+---
+
 ## Prerequisites
 
 ```bash
 webcmd doctor
 ```
 
-Until `doctor` is green, nothing else will work. Typical failures: Chrome not running, extension not installed, debug port blocked by 1Password / other extensions. The doctor output tells you which.
+Until `doctor` is green, browser commands will not work. Registry and plugin discovery do not require `doctor`. Typical failures: Chrome not running, extension not installed, debug port blocked by 1Password / other extensions. The doctor output tells you which.
 
 ---
 
@@ -61,7 +74,7 @@ Bound sessions use the normal Webcmd session lifecycle; `unbind` releases the Cl
 ## Critical rules
 
 1. **Always inspect before you act.** Run `state` or `find` first. Never hard-code a ref or selector from memory across sessions — indices are per-snapshot.
-2. **Prefer site adapters before raw browser driving.** If `webcmd <site> <command>` already covers the task, use that adapter command first (`webcmd facebook notifications`, `webcmd reddit read`, `webcmd chatgpt model <level>`, etc.). Use `webcmd browser ...` only for gaps, debugging, or one-off UI flows the adapter does not expose.
+2. **Prefer site adapters before raw browser driving.** Complete the adapter fallback gate above. If `webcmd <site> <command>` already covers the task, use that adapter command first (`webcmd facebook notifications`, `webcmd reddit read`, `webcmd chatgpt model <level>`, etc.). Use `webcmd browser ...` only for gaps, debugging, or one-off UI flows the adapter does not expose.
 3. **Prefer numeric ref over CSS once you have it.** Numeric refs survive mild DOM shifts because the CLI fingerprints each tagged element. A CSS selector written by hand will break the first time the site re-renders.
 4. **Read `match_level` after every write.** `exact` = all good. `stable` = the element is the same but some soft attrs drifted — your action still applied. `reidentified` = the original ref was gone and the CLI found a unique replacement; double-check you hit the right element.
 5. **Use the `compound` field for form controls.** Do not regex-guess a date format, do not `state` twice to get the full `<select>` options list. The compound envelope has the format string, full option list up to 50, `options_total` for overflow, and `accept`/`multiple` for `<input type=file>`.
@@ -322,18 +335,19 @@ webcmd browser hn open "https://news.ycombinator.com" \
 
 ## Recipes
 
-### Fill a login form
+### Authentication and human handoff
 
-```bash
-webcmd browser login open "https://example.com/login"
-webcmd browser login state                          # find [N] for email, password, submit
-webcmd browser login type 4 "me@example.com"
-webcmd browser login type 5 "hunter2"
-webcmd browser login get value 4                    # verify (autocomplete can eat chars)
-webcmd browser login click 6                        # submit
-webcmd browser login wait selector "[data-testid=account-menu]" --timeout 15000
-webcmd browser login state                          # fresh refs on the logged-in page
-```
+If a failure returns `handoff.status === action_required`, stop browser writes and AutoFix. Give the user `handoff.action` and any `Webcmd browser:` or `handoff.viewUrl` link, then wait. After the user reports done, run `handoff.verifyCommand` when present; verification must succeed before retrying.
+
+1. On a clear login redirect or auth wall, stop browser writes.
+2. If the site exposes a login command, run `webcmd <site> login`. `already_logged_in` is verified; `in_progress` means no current user action, so do not ask the user or wait for confirmation, and do not poll; `action_required` is a hard stop.
+3. For `action_required`, give the user its instructions and any returned `action_url` or `view_url`. If Webcmd returned no URL, use the current visible browser.
+4. Never ask for or type passwords, OTPs, recovery codes, cookies, or session secrets.
+5. Run the returned `verify_command` (normally `webcmd <site> whoami`) or `handoff.verifyCommand` only after the user reports done; verification must succeed before retrying.
+6. Without a verifier, take fresh browser state and verify the intended post-action state before any retry, especially for write commands. The user's report alone is not verification.
+7. If login remains `in_progress`, perform a later explicit `whoami` or task retry when work next needs auth state. Use `webcmd auth refresh` only when an explicit auth-state refresh is needed.
+
+For a CAPTCHA or user takeover, stop automation, give the user any viewer URL Webcmd returned, and apply the same verification policy above. Keep CAPTCHA outside automated retries.
 
 ### Pick from a long dropdown
 
@@ -433,6 +447,7 @@ normal DOM `state`, or navigate/bind directly to the iframe URL when possible.
 | `stale_ref` across every command | You are reusing refs from a prior page. Re-`state`. |
 | `click` succeeds but nothing happens | The element is probably a decorative wrapper stealing clicks from the real target. `find --css "..."` with a narrower selector and retry on the inner element. |
 | `type` appears to finish but value is wrong | Autocomplete, masked input, or React controlled re-render. Verify with `get value`. Add `keys Enter` or re-type. |
+| `webcmd list -f json` output is truncated | Adapter discovery is incomplete. Filter at the source with request-derived terms and narrow until the complete result is `[]`; do not start browser fallback yet. |
 | Giant `get html` output | Pass `--selector` + `--as json --depth 3 --children-max 20 --text-max 200`. |
 | Network cache seems stale | Bump `--ttl` down, or let it expire. The cache lives at `~/.webcmd/cache/browser-network/`. |
 

package/skills/webcmd-usage/SKILL.md

@@ -50,19 +50,33 @@ Run commands instead of reading static docs:
 
 ```bash
 webcmd
-webcmd list -f json
 webcmd <site> --help
 webcmd <site> <command> --help
 ```
 
 Run `webcmd` with no arguments to see all available functions and installed site adapters. Do not hard-code adapter lists: `webcmd list -f json` is the source of truth for installed commands and emits one entry per command with fields such as `{site, name, aliases, description, strategy, browser, args, columns}`.
 
+Large registries can exceed an agent or tool output budget. Filter the JSON stream before it is emitted, using broad literal terms derived from the whole requested workflow:
+
+```bash
+WORKFLOW_TERMS='["requested action", "output field", "named site"]'
+webcmd list -f json | jq --argjson terms "$WORKFLOW_TERMS" '
+  [.[] | select(
+    ([.site, .name, .description, ((.columns // []) | join(" "))]
+      | map(. // "") | join(" ") | ascii_downcase) as $text
+    | any($terms[]; . as $term | $text | contains($term | ascii_downcase))
+  )]
+'
+```
+
+Replace `WORKFLOW_TERMS` with terms from the current request: the requested action, entity, output fields, and any explicitly named site. Literal matching avoids regex errors from terms such as `C++` or `[foo]`. Do not maintain a site or category allowlist. Match across `site`, `name`, `description`, and `columns`. If any layer reports truncated output, the inspection is incomplete. Narrow the filter and inspect again. Never treat absence from truncated output as proof that an adapter or plugin is missing, and do not proceed to the next fallback stage from that evidence.
+
 Use this fallback order:
 
-1. Run `webcmd list -f json` once.
-2. Check that result against the whole requested workflow, not only a named site. If one installed command covers it, use that command and stop discovery.
-3. If none covers it, derive a short plugin query from the missing site or capability and run `webcmd plugin search <query> -f json`. Preserve the user's term when practical: `find flights` becomes `flight`.
-4. If plugin search returns a match, offer `webcmd plugin install <installSource>`. If it returns no match and no error, raw `webcmd browser` is allowed. If it errors, report plugin discovery as unavailable and stop. If `fetch failed` appears in `errors[].message`, report plugin discovery as unavailable due to network/reachability and ask the user whether to rerun with network/escalated permissions. Do not retry unless they approve.
+1. Run `webcmd list -f json` through a workflow-derived filter before returning its output to the agent.
+2. Check the complete, non-truncated filtered result against the whole requested workflow. If one installed command covers it, use that command and stop discovery. If candidates do not cover the missing capability, refine the capability filter until its complete result is exactly `[]`.
+3. Only after that complete filtered result is `[]`, derive a short plugin query from the missing site or capability and run `webcmd plugin search <query> -f json`. Preserve the user's term when practical: `find flights` becomes `flight`.
+4. If the complete, non-truncated plugin search returns a match, offer `webcmd plugin install <installSource>`. Only if that complete result returns no match and no error is raw `webcmd browser` allowed. Both plugin search and raw browser fallback require the prior complete filtered registry result to be `[]`. A truncated plugin result is incomplete evidence: refine the query or output before fallback. If plugin search errors, report plugin discovery as unavailable and stop. If `fetch failed` appears in `errors[].message`, report plugin discovery as unavailable due to network/reachability and ask the user whether to rerun with network/escalated permissions. Do not retry unless they approve.
 
 ## Universal Flags
 
@@ -104,6 +118,14 @@ webcmd <site> <command> [args...] --trace retain-on-failure
 
 The error envelope includes a `trace` block pointing at `summary.md`. Patch only `adapterSourcePath` from that summary and retry. Maximum 3 repair rounds. See `webcmd-autofix`.
 
+## Authentication and Human Handoff
+
+If a failure returns `handoff.status === action_required`, stop before AutoFix. Give the user `handoff.action` and any `Webcmd browser:` or `handoff.viewUrl` link, then wait. After the user reports done, run `handoff.verifyCommand` when present; verification must succeed before retrying.
+
+`AUTH_REQUIRED` is not an adapter failure. Run `webcmd <site> login`: `already_logged_in` is verified; `in_progress` means no current user action, so do not ask the user or wait for confirmation, and do not poll; `action_required` is a hard stop. For `action_required`, give the user its instructions and any returned `action_url` or `view_url`, then wait. If Webcmd returned no URL, use the current visible browser.
+
+Run the returned `verify_command` (normally `webcmd <site> whoami`) or `handoff.verifyCommand` only after the user reports done; verification must succeed before retrying. Without a verifier, take fresh browser state and verify the intended post-action state before any retry, especially for write commands. Use `webcmd auth refresh` only when an explicit auth-state refresh is needed. Their report alone is not verification. Never request, type, echo, store, or automate passwords, OTPs, recovery codes, cookies, session secrets, or CAPTCHA answers; CAPTCHA stops automation and follows the same verification rule.
+
 ## Report A Webcmd Defect
 
 After a reproducible Webcmd failure has been diagnosed or the `webcmd-autofix`
@@ -194,6 +216,7 @@ Do not invoke these removed commands:
 
 ## Do Not
 
-- Do not paste static command lists into plans; call `webcmd list -f json`.
+- Do not paste static command lists into plans; query `webcmd list -f json` through a workflow-derived filter.
+- Do not emit a large unfiltered registry into a bounded output or infer absence from a truncation warning; filter at the source and narrow until the result is complete.
 - Do not assume every adapter needs a browser; check `strategy`.
 - Do not silently fall back from a failing adapter to hand-rolled `fetch`; use `--trace retain-on-failure` first.

package/clis/practo/whoami.js

@@ -1,28 +0,0 @@
-import { cli, Strategy } from '@agentrhq/webcmd/registry';
-import { probeIdentity } from './utils.js';
-
-cli({
-  site: 'practo',
-  name: 'whoami',
-  aliases: ['auth-status'],
-  access: 'read',
-  description: 'Show whether the current browser session is logged into Practo',
-  domain: 'www.practo.com',
-  strategy: Strategy.COOKIE,
-  browser: true,
-  navigateBefore: false,
-  siteSession: 'persistent',
-  args: [],
-  columns: ['logged_in', 'site', 'name'],
-  authStatus: {
-    quickCheck: async (page) => {
-      try {
-        const rows = await probeIdentity(page);
-        return { logged_in: true, name: rows[0].name };
-      } catch {
-        return { logged_in: false };
-      }
-    },
-  },
-  func: probeIdentity,
-});