@agentrhq/webcmd 0.3.4 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentrhq/webcmd",
-  "version": "0.3.4",
+  "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"
@@ -78,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"
@@ -91,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",

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

@@ -335,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
 

package/skills/webcmd-usage/SKILL.md

@@ -118,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`

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,
-});