@agentrhq/webcmd 0.3.3 → 0.3.4

package/README.md

@@ -9,13 +9,13 @@
     <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://docs.webcmd.dev">
-    <img alt="Documentation" src="https://img.shields.io/badge/docs-webcmd.dev-1E88E5.svg?style=for-the-badge&labelColor=000000">
+    <img alt="Documentation" src="https://img.shields.io/badge/docs-webcmd.dev-7C3AED.svg?style=for-the-badge&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://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">
+    <img alt="Join the community on Discord" src="https://img.shields.io/badge/Join%20the%20community-5865F2.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">
@@ -28,8 +28,6 @@
 
 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%.
 
-📖 **Full documentation: [docs.webcmd.dev](https://docs.webcmd.dev)**
-
 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 |

package/dist/src/browser/ax-snapshot.js

@@ -71,7 +71,7 @@ function renderAxTree(axTree, lines, refs, nextRef, opts) {
     const rawNodes = Array.isArray(axTree?.nodes)
         ? axTree.nodes
         : [];
-    const nodes = rawNodes.filter((node) => node && !node.ignored);
+    const nodes = rawNodes.filter((node) => node);
     const byId = new Map();
     const parentIds = new Set();
     for (const node of nodes) {
@@ -88,11 +88,21 @@ function renderAxTree(axTree, lines, refs, nextRef, opts) {
     });
     const root = roots[0] ?? nodes[0];
     const maxDepth = Math.max(1, Math.min(Number(opts.maxDepth) || 50, 200));
+    const maxTraversalHops = 200;
     const roleNameCounts = countRoleNames(nodes);
     const roleNameSeen = new Map();
-    function render(node, depth) {
-        if (!node || depth > maxDepth)
+    function render(node, depth, hops, path) {
+        if (!node || depth > maxDepth || hops > maxTraversalHops || path.has(node))
             return false;
+        const nextPath = new Set(path).add(node);
+        if (node.ignored) {
+            let hasVisibleChild = false;
+            for (const childId of node.childIds ?? []) {
+                if (render(byId.get(childId), depth, hops + 1, nextPath))
+                    hasVisibleChild = true;
+            }
+            return hasVisibleChild;
+        }
         const role = axString(node.role) || 'generic';
         const name = cleanText(axString(node.name));
         const value = cleanText(axString(node.value) || propertyValue(node, 'value'));
@@ -109,7 +119,7 @@ function renderAxTree(axTree, lines, refs, nextRef, opts) {
         const childStart = lines.length;
         let hasVisibleChild = false;
         for (const childId of node.childIds ?? []) {
-            if (render(byId.get(childId), depth + 1))
+            if (render(byId.get(childId), depth + 1, hops + 1, nextPath))
                 hasVisibleChild = true;
         }
         if (!shouldShowSelf && !hasVisibleChild) {
@@ -151,7 +161,7 @@ function renderAxTree(axTree, lines, refs, nextRef, opts) {
         }
         return true;
     }
-    render(root, opts.baseDepth);
+    render(root, opts.baseDepth, 0, new Set());
     return nextRef;
 }
 export function findAxRefReplacement(axTree, ref) {

package/dist/src/browser/ax-snapshot.test.js

@@ -1,6 +1,12 @@
+import { readFileSync } from 'node:fs';
 import { describe, expect, it } from 'vitest';
 import { buildAxSnapshot, buildAxSnapshotFromTrees, findAxRefReplacement } from './ax-snapshot.js';
 describe('AX snapshot prototype', () => {
+    it('publishes the AX snapshot builder as a package subpath', () => {
+        const packageJson = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+        expect(packageJson.exports?.['./browser/ax-snapshot'])
+            .toBe('./dist/src/browser/ax-snapshot.js');
+    });
     it('builds compact refs from Accessibility.getFullAXTree output', () => {
         const result = buildAxSnapshot({
             nodes: [
@@ -25,6 +31,49 @@ describe('AX snapshot prototype', () => {
             name: 'Category',
         });
     });
+    it('keeps actionable descendants of ignored AX nodes', () => {
+        const result = buildAxSnapshot({
+            nodes: [
+                { nodeId: '1', role: { value: 'RootWebArea' }, childIds: ['2'] },
+                { nodeId: '2', ignored: true, childIds: ['3', '4'] },
+                { nodeId: '3', role: { value: 'button' }, name: { value: 'First' }, backendDOMNodeId: 30 },
+                { nodeId: '4', role: { value: 'button' }, name: { value: 'Second' }, backendDOMNodeId: 40 },
+            ],
+        });
+        expect(result.text).toContain('  [1]button "First"\n  [2]button "Second"');
+        expect(result.text).not.toContain('ignored');
+        expect([...result.refs.values()]).toEqual([
+            { ref: '1', backendNodeId: 30, role: 'button', name: 'First' },
+            { ref: '2', backendNodeId: 40, role: 'button', name: 'Second' },
+        ]);
+    });
+    it('stops ignored-node cycles without changing promoted indentation', () => {
+        const result = buildAxSnapshot({
+            nodes: [
+                { nodeId: '1', role: { value: 'RootWebArea' }, childIds: ['2'] },
+                { nodeId: '2', ignored: true, childIds: ['2', '3'] },
+                { nodeId: '3', role: { value: 'button' }, name: { value: 'Save' }, backendDOMNodeId: 30 },
+            ],
+        });
+        expect(result.text).toContain('\n  [1]button "Save"\n');
+        expect(result.refs).toHaveLength(1);
+    });
+    it('bounds traversal through long ignored-node chains', () => {
+        const ignored = Array.from({ length: 201 }, (_, index) => ({
+            nodeId: String(index + 2),
+            ignored: true,
+            childIds: [String(index + 3)],
+        }));
+        const result = buildAxSnapshot({
+            nodes: [
+                { nodeId: '1', role: { value: 'RootWebArea' }, childIds: ['2'] },
+                ...ignored,
+                { nodeId: '203', role: { value: 'button' }, name: { value: 'Too deep' }, backendDOMNodeId: 203 },
+            ],
+        });
+        expect(result.text).not.toContain('Too deep');
+        expect(result.refs).toHaveLength(0);
+    });
     it('tracks nth only for duplicate role/name pairs', () => {
         const result = buildAxSnapshot({
             nodes: [

package/hosted-contract.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "webcmdVersion": "0.3.3",
+  "webcmdVersion": "0.3.4",
   "outputFormats": [
     "table",
     "plain",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentrhq/webcmd",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "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",
@@ -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-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>`.
@@ -433,6 +446,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
 
@@ -194,6 +208,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.