@claude-flow/cli 3.0.0-alpha.142 → 3.0.0-alpha.144

package/.claude/agents/browser/browser-agent.yaml

@@ -0,0 +1,182 @@
+# Browser Agent Configuration
+# AI-powered web browser automation using agent-browser
+#
+# Capabilities:
+# - Web navigation and interaction
+# - AI-optimized snapshots with element refs
+# - Form filling and submission
+# - Screenshot capture
+# - Network interception
+# - Multi-session coordination
+
+name: browser-agent
+description: Web automation specialist using agent-browser with AI-optimized snapshots
+version: 1.0.0
+
+# Routing configuration
+routing:
+  complexity: medium
+  model: sonnet  # Good at visual reasoning and DOM interpretation
+  priority: normal
+  keywords:
+    - browser
+    - web
+    - scrape
+    - screenshot
+    - navigate
+    - login
+    - form
+    - click
+    - automate
+
+# Agent capabilities
+capabilities:
+  - web-navigation
+  - form-interaction
+  - screenshot-capture
+  - data-extraction
+  - network-interception
+  - session-management
+  - multi-tab-coordination
+
+# Available tools (MCP tools with browser/ prefix)
+tools:
+  navigation:
+    - browser/open
+    - browser/back
+    - browser/forward
+    - browser/reload
+    - browser/close
+  snapshot:
+    - browser/snapshot
+    - browser/screenshot
+    - browser/pdf
+  interaction:
+    - browser/click
+    - browser/fill
+    - browser/type
+    - browser/press
+    - browser/hover
+    - browser/select
+    - browser/check
+    - browser/uncheck
+    - browser/scroll
+    - browser/upload
+  info:
+    - browser/get-text
+    - browser/get-html
+    - browser/get-value
+    - browser/get-attr
+    - browser/get-title
+    - browser/get-url
+    - browser/get-count
+  state:
+    - browser/is-visible
+    - browser/is-enabled
+    - browser/is-checked
+  wait:
+    - browser/wait
+  eval:
+    - browser/eval
+  storage:
+    - browser/cookies-get
+    - browser/cookies-set
+    - browser/cookies-clear
+    - browser/localstorage-get
+    - browser/localstorage-set
+  network:
+    - browser/network-route
+    - browser/network-unroute
+    - browser/network-requests
+  tabs:
+    - browser/tab-list
+    - browser/tab-new
+    - browser/tab-switch
+    - browser/tab-close
+    - browser/session-list
+  settings:
+    - browser/set-viewport
+    - browser/set-device
+    - browser/set-geolocation
+    - browser/set-offline
+    - browser/set-media
+  debug:
+    - browser/trace-start
+    - browser/trace-stop
+    - browser/console
+    - browser/errors
+    - browser/highlight
+    - browser/state-save
+    - browser/state-load
+  find:
+    - browser/find-role
+    - browser/find-text
+    - browser/find-label
+    - browser/find-testid
+
+# Memory configuration
+memory:
+  namespace: browser-sessions
+  persist: true
+  patterns:
+    - login-flows
+    - form-submissions
+    - scraping-patterns
+    - navigation-sequences
+
+# Swarm integration
+swarm:
+  roles:
+    - navigator      # Handles authentication and navigation
+    - scraper        # Extracts data using snapshots
+    - validator      # Verifies extracted data
+    - tester         # Runs automated tests
+    - monitor        # Watches for errors and network issues
+  topology: hierarchical  # Coordinator manages browser agents
+  max_sessions: 5
+
+# Hooks integration
+hooks:
+  pre_task:
+    - route         # Get optimal routing
+    - memory_search # Check for similar patterns
+  post_task:
+    - memory_store  # Save successful patterns
+    - post_edit     # Train on outcomes
+
+# Default configuration
+defaults:
+  timeout: 30000
+  headless: true
+  viewport:
+    width: 1280
+    height: 720
+
+# Example workflows
+workflows:
+  login:
+    description: Authenticate to a website
+    steps:
+      - open: "{url}/login"
+      - snapshot: { interactive: true }
+      - fill: { target: "@e1", value: "{username}" }
+      - fill: { target: "@e2", value: "{password}" }
+      - click: "@e3"
+      - wait: { url: "**/dashboard" }
+      - state-save: "auth-state.json"
+
+  scrape_list:
+    description: Extract data from a list page
+    steps:
+      - open: "{url}"
+      - snapshot: { interactive: true, compact: true }
+      - eval: "Array.from(document.querySelectorAll('{selector}')).map(el => el.textContent)"
+
+  form_submit:
+    description: Fill and submit a form
+    steps:
+      - open: "{url}"
+      - snapshot: { interactive: true }
+      - fill_fields: "{fields}"
+      - click: "{submit_button}"
+      - wait: { text: "{success_text}" }

package/.claude/skills/browser/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: browser
+description: Web browser automation with AI-optimized snapshots for claude-flow agents
+version: 1.0.0
+triggers:
+  - /browser
+  - browse
+  - web automation
+  - scrape
+  - navigate
+  - screenshot
+tools:
+  - browser/open
+  - browser/snapshot
+  - browser/click
+  - browser/fill
+  - browser/screenshot
+  - browser/close
+---
+
+# Browser Automation Skill
+
+Web browser automation using agent-browser with AI-optimized snapshots. Reduces context by 93% using element refs (@e1, @e2) instead of full DOM.
+
+## Core Workflow
+
+```bash
+# 1. Navigate to page
+agent-browser open <url>
+
+# 2. Get accessibility tree with element refs
+agent-browser snapshot -i    # -i = interactive elements only
+
+# 3. Interact using refs from snapshot
+agent-browser click @e2
+agent-browser fill @e3 "text"
+
+# 4. Re-snapshot after page changes
+agent-browser snapshot -i
+```
+
+## Quick Reference
+
+### Navigation
+| Command | Description |
+|---------|-------------|
+| `open <url>` | Navigate to URL |
+| `back` | Go back |
+| `forward` | Go forward |
+| `reload` | Reload page |
+| `close` | Close browser |
+
+### Snapshots (AI-Optimized)
+| Command | Description |
+|---------|-------------|
+| `snapshot` | Full accessibility tree |
+| `snapshot -i` | Interactive elements only (buttons, links, inputs) |
+| `snapshot -c` | Compact (remove empty elements) |
+| `snapshot -d 3` | Limit depth to 3 levels |
+| `screenshot [path]` | Capture screenshot (base64 if no path) |
+
+### Interaction
+| Command | Description |
+|---------|-------------|
+| `click <sel>` | Click element |
+| `fill <sel> <text>` | Clear and fill input |
+| `type <sel> <text>` | Type with key events |
+| `press <key>` | Press key (Enter, Tab, etc.) |
+| `hover <sel>` | Hover element |
+| `select <sel> <val>` | Select dropdown option |
+| `check/uncheck <sel>` | Toggle checkbox |
+| `scroll <dir> [px]` | Scroll page |
+
+### Get Info
+| Command | Description |
+|---------|-------------|
+| `get text <sel>` | Get text content |
+| `get html <sel>` | Get innerHTML |
+| `get value <sel>` | Get input value |
+| `get attr <sel> <attr>` | Get attribute |
+| `get title` | Get page title |
+| `get url` | Get current URL |
+
+### Wait
+| Command | Description |
+|---------|-------------|
+| `wait <selector>` | Wait for element |
+| `wait <ms>` | Wait milliseconds |
+| `wait --text "text"` | Wait for text |
+| `wait --url "pattern"` | Wait for URL |
+| `wait --load networkidle` | Wait for load state |
+
+### Sessions
+| Command | Description |
+|---------|-------------|
+| `--session <name>` | Use isolated session |
+| `session list` | List active sessions |
+
+## Selectors
+
+### Element Refs (Recommended)
+```bash
+# Get refs from snapshot
+agent-browser snapshot -i
+# Output: button "Submit" [ref=e2]
+
+# Use ref to interact
+agent-browser click @e2
+```
+
+### CSS Selectors
+```bash
+agent-browser click "#submit"
+agent-browser fill ".email-input" "test@test.com"
+```
+
+### Semantic Locators
+```bash
+agent-browser find role button click --name "Submit"
+agent-browser find label "Email" fill "test@test.com"
+agent-browser find testid "login-btn" click
+```
+
+## Examples
+
+### Login Flow
+```bash
+agent-browser open https://example.com/login
+agent-browser snapshot -i
+agent-browser fill @e2 "user@example.com"
+agent-browser fill @e3 "password123"
+agent-browser click @e4
+agent-browser wait --url "**/dashboard"
+```
+
+### Form Submission
+```bash
+agent-browser open https://example.com/contact
+agent-browser snapshot -i
+agent-browser fill @e1 "John Doe"
+agent-browser fill @e2 "john@example.com"
+agent-browser fill @e3 "Hello, this is my message"
+agent-browser click @e4
+agent-browser wait --text "Thank you"
+```
+
+### Data Extraction
+```bash
+agent-browser open https://example.com/products
+agent-browser snapshot -i
+# Iterate through product refs
+agent-browser get text @e1  # Product name
+agent-browser get text @e2  # Price
+agent-browser get attr @e3 href  # Link
+```
+
+### Multi-Session (Swarm)
+```bash
+# Session 1: Navigator
+agent-browser --session nav open https://example.com
+agent-browser --session nav state save auth.json
+
+# Session 2: Scraper (uses same auth)
+agent-browser --session scrape state load auth.json
+agent-browser --session scrape open https://example.com/data
+agent-browser --session scrape snapshot -i
+```
+
+## Integration with Claude Flow
+
+### MCP Tools
+All browser operations are available as MCP tools with `browser/` prefix:
+- `browser/open`
+- `browser/snapshot`
+- `browser/click`
+- `browser/fill`
+- `browser/screenshot`
+- etc.
+
+### Memory Integration
+```bash
+# Store successful patterns
+npx @claude-flow/cli memory store --namespace browser-patterns --key "login-flow" --value "snapshot->fill->click->wait"
+
+# Retrieve before similar task
+npx @claude-flow/cli memory search --query "login automation"
+```
+
+### Hooks
+```bash
+# Pre-browse hook (get context)
+npx @claude-flow/cli hooks pre-edit --file "browser-task.ts"
+
+# Post-browse hook (record success)
+npx @claude-flow/cli hooks post-task --task-id "browse-1" --success true
+```
+
+## Tips
+
+1. **Always use snapshots** - They're optimized for AI with refs
+2. **Prefer `-i` flag** - Gets only interactive elements, smaller output
+3. **Use refs, not selectors** - More reliable, deterministic
+4. **Re-snapshot after navigation** - Page state changes
+5. **Use sessions for parallel work** - Each session is isolated

package/README.md

@@ -301,6 +301,18 @@ npx claude-flow@v3alpha --agent coder --task "Implement user authentication"
 npx claude-flow@v3alpha --list
 ```
 
+### Upgrading
+
+```bash
+# Update helpers and statusline (preserves your data)
+npx claude-flow@v3alpha init upgrade
+
+# Update AND add any missing skills/agents/commands
+npx claude-flow@v3alpha init upgrade --add-missing
+```
+
+The `--add-missing` flag automatically detects and installs new skills, agents, and commands that were added in newer versions, without overwriting your existing customizations.
+
 ### Claude Code MCP Integration
 
 Add claude-flow as an MCP server for seamless integration:
@@ -4494,6 +4506,7 @@ Domain-Driven Design with bounded contexts, clean architecture, and measured per
 | `@claude-flow/testing` | Quality assurance | London School TDD, Vitest, fixtures, mocks |
 | `@claude-flow/deployment` | Release automation | Versioning, changelogs, NPM publishing |
 | `@claude-flow/shared` | Common utilities | Types, validation schemas, constants |
+| `@claude-flow/browser` | Browser automation | 59 MCP tools, element refs, trajectory learning |
 
 ### Architecture Principles
 
@@ -4533,6 +4546,93 @@ Domain-Driven Design with bounded contexts, clean architecture, and measured per
 
 ---
 
+<details>
+<summary><strong>🌐 Browser Automation — @claude-flow/browser</strong></summary>
+
+[![npm version](https://img.shields.io/npm/v/@claude-flow/browser?color=blue&label=npm)](https://www.npmjs.com/package/@claude-flow/browser)
+
+AI-optimized browser automation integrating [agent-browser](https://github.com/AugmentCode/agent-browser) with claude-flow for intelligent web automation, trajectory learning, and multi-agent browser coordination.
+
+### Installation
+
+```bash
+npm install @claude-flow/browser
+
+# agent-browser CLI (auto-suggested on install, or install manually)
+npm install -g agent-browser@latest
+```
+
+### Quick Start
+
+```typescript
+import { createBrowserService } from '@claude-flow/browser';
+
+const browser = createBrowserService({
+  sessionId: 'my-session',
+  enableSecurity: true,  // URL/PII scanning
+  enableMemory: true,    // Trajectory learning
+});
+
+// Track actions for ReasoningBank/SONA learning
+browser.startTrajectory('Login to dashboard');
+
+await browser.open('https://example.com/login');
+
+// Use element refs (93% context reduction vs CSS selectors)
+const snapshot = await browser.snapshot({ interactive: true });
+await browser.fill('@e1', 'user@example.com');
+await browser.fill('@e2', 'password');
+await browser.click('@e3');
+
+await browser.endTrajectory(true, 'Login successful');
+await browser.close();
+```
+
+### Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **59 MCP Tools** | Complete browser automation via MCP protocol |
+| **Element Refs** | 93% context reduction with `@e1`, `@e2` refs |
+| **Trajectory Learning** | Records actions for ReasoningBank/SONA |
+| **Security Scanning** | URL validation, PII detection, XSS/SQL injection prevention |
+| **9 Workflow Templates** | Login, OAuth, scraping, testing, monitoring |
+| **Swarm Coordination** | Multi-session parallel browser automation |
+
+### Security Integration
+
+```typescript
+import { getSecurityScanner, isUrlSafe, containsPII } from '@claude-flow/browser';
+
+// URL threat detection
+const scanner = getSecurityScanner({ requireHttps: true });
+const result = await scanner.scanUrl('https://example.com');
+// { safe: true, threats: [], score: 1.0 }
+
+// PII detection
+containsPII('SSN: 123-45-6789'); // true
+
+// Input validation (XSS, SQL injection)
+scanner.validateInput('<script>alert(1)</script>', 'comment');
+// { safe: false, threats: [{type: 'xss', ...}] }
+```
+
+### Workflow Templates
+
+```typescript
+import { listWorkflows, getWorkflow } from '@claude-flow/browser';
+
+listWorkflows(); // ['login-basic', 'login-oauth', 'scrape-table', ...]
+const template = getWorkflow('login-basic');
+// { steps: [{action: 'open'}, {action: 'fill'}, ...], variables: [...] }
+```
+
+📖 [Full Documentation](./v3/@claude-flow/browser/README.md)
+
+</details>
+
+---
+
 <details>
 <summary><h2>📦 Release Management — @claude-flow/deployment</h2></summary>
 
@@ -5784,6 +5884,7 @@ cp -r ./data-backup-v2 ./data
 | `@claude-flow/performance` | Benchmarking & optimization | [Source](./v3/@claude-flow/performance/) |
 | `@claude-flow/deployment` | Release & CI/CD | [Source](./v3/@claude-flow/deployment/) |
 | `@claude-flow/shared` | Shared utilities, types & V3ProgressService | [Source](./v3/@claude-flow/shared/) |
+| `@claude-flow/browser` | AI-optimized browser automation with agent-browser | [README](./v3/@claude-flow/browser/README.md) |
 
 ### Additional Resources
 

package/dist/src/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/commands/init.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAiC,MAAM,aAAa,CAAC;AAwuB1E,eAAO,MAAM,WAAW,EAAE,OAiFzB,CAAC;AAEF,eAAe,WAAW,CAAC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/commands/init.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAiC,MAAM,aAAa,CAAC;AA4xB1E,eAAO,MAAM,WAAW,EAAE,OAiFzB,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/src/commands/init.js

@@ -6,7 +6,7 @@ import { output } from '../output.js';
 import { confirm, select, multiSelect, input } from '../prompt.js';
 import * as fs from 'fs';
 import * as path from 'path';
-import { executeInit, executeUpgrade, DEFAULT_INIT_OPTIONS, MINIMAL_INIT_OPTIONS, FULL_INIT_OPTIONS, } from '../init/index.js';
+import { executeInit, executeUpgrade, executeUpgradeWithMissing, DEFAULT_INIT_OPTIONS, MINIMAL_INIT_OPTIONS, FULL_INIT_OPTIONS, } from '../init/index.js';
 // Check if project is already initialized
 function isInitialized(cwd) {
     const claudePath = path.join(cwd, '.claude', 'settings.json');
@@ -517,6 +517,7 @@ const skillsCommand = {
                 agentdb: ctx.flags.agentdb,
                 github: ctx.flags.github,
                 flowNexus: false,
+                browser: false,
                 v3: ctx.flags.v3,
             },
         };
@@ -600,16 +601,31 @@ const upgradeCommand = {
             type: 'boolean',
             default: false,
         },
+        {
+            name: 'add-missing',
+            short: 'a',
+            description: 'Add any new skills, agents, and commands that are missing',
+            type: 'boolean',
+            default: false,
+        },
     ],
     action: async (ctx) => {
+        const addMissing = ctx.flags['add-missing'];
         output.writeln();
         output.writeln(output.bold('Upgrading Claude Flow'));
-        output.writeln(output.dim('Updates helpers while preserving your existing data'));
+        if (addMissing) {
+            output.writeln(output.dim('Updates helpers and adds any missing skills/agents/commands'));
+        }
+        else {
+            output.writeln(output.dim('Updates helpers while preserving your existing data'));
+        }
         output.writeln();
-        const spinner = output.createSpinner({ text: 'Upgrading...' });
+        const spinner = output.createSpinner({ text: addMissing ? 'Upgrading and adding missing assets...' : 'Upgrading...' });
         spinner.start();
         try {
-            const result = await executeUpgrade(ctx.cwd);
+            const result = addMissing
+                ? await executeUpgradeWithMissing(ctx.cwd)
+                : await executeUpgrade(ctx.cwd);
             if (!result.success) {
                 spinner.fail('Upgrade failed');
                 for (const error of result.errors) {
@@ -638,8 +654,31 @@ const upgradeCommand = {
                 output.printInfo(`Preserved ${result.preserved.length} existing data files`);
                 output.writeln();
             }
+            // Show added assets (when --add-missing flag is used)
+            if (result.addedSkills && result.addedSkills.length > 0) {
+                output.printBox(result.addedSkills.map(s => `+ ${s}`).join('\n'), `Added Skills (${result.addedSkills.length} new)`);
+                output.writeln();
+            }
+            if (result.addedAgents && result.addedAgents.length > 0) {
+                output.printBox(result.addedAgents.map(a => `+ ${a}`).join('\n'), `Added Agents (${result.addedAgents.length} new)`);
+                output.writeln();
+            }
+            if (result.addedCommands && result.addedCommands.length > 0) {
+                output.printBox(result.addedCommands.map(c => `+ ${c}`).join('\n'), `Added Commands (${result.addedCommands.length} new)`);
+                output.writeln();
+            }
             output.printSuccess('Your statusline helper has been updated to the latest version');
             output.printInfo('Existing metrics and learning data were preserved');
+            // Show summary for --add-missing
+            if (addMissing) {
+                const totalAdded = (result.addedSkills?.length || 0) + (result.addedAgents?.length || 0) + (result.addedCommands?.length || 0);
+                if (totalAdded > 0) {
+                    output.printSuccess(`Added ${totalAdded} missing assets to your project`);
+                }
+                else {
+                    output.printInfo('All skills, agents, and commands are already up to date');
+                }
+            }
             if (ctx.flags.format === 'json') {
                 output.printJson(result);
             }