neuron-inspector 0.8.1 → 1.1.0

package/README.md

@@ -1,8 +1,8 @@
 # neuron-inspector
 
-**51 browser tools for AI agents.** Your AI can't see your browser. This fixes that.
+**177 browser tools for AI agents.** Your AI can't see your browser. This fixes that.
 
-Inspect DOM, automate clicks, run JavaScript, search network traffic, audit security, check accessibility, scan SEO, mock APIs, extract structured data, record demos — all from Claude Code, Cursor, Windsurf, or any MCP client.
+Inspect DOM, automate clicks, run JavaScript, search network traffic, audit security, check accessibility, scan SEO, mock APIs, extract structured data, record demos, scan profiles, score leads, track competitors, monitor mentions, build revenue pipelines — all from Claude Code, Cursor, Windsurf, or any MCP client.
 
 No API keys. No cloud. Runs on localhost.
 
@@ -63,9 +63,61 @@ Open any page in Chrome. Ask your AI agent to interact with it. Done.
 
 ---
 
+## Multi-Profile Setup
+
+Each Chrome profile can connect to a different bridge instance. This enables multi-account workflows where each profile is logged into different social media accounts.
+
+### 1. Set the bridge port per Chrome profile
+
+Open the extension popup > Settings (gear icon) > enable Developer Mode. Set a unique **Bridge Port** for each Chrome profile:
+
+- Profile A (personal): port `7377` (default)
+- Profile B (business): port `7378`
+- Profile C (client): port `7379`
+
+### 2. Start a bridge per profile
+
+Each bridge gets its own port (`NEURON_BRIDGE_PORT`) and its own data directory (`NEURON_DATA_DIR`) so leads, monitors, sessions, and recipes stay isolated.
+
+```bash
+# Terminal 1 — personal (default port + default data dir)
+npx neuron-inspector
+
+# Terminal 2 — business
+NEURON_BRIDGE_PORT=7378 NEURON_DATA_DIR=~/.neuron/letschop npx neuron-inspector
+
+# Terminal 3 — client
+NEURON_BRIDGE_PORT=7379 NEURON_DATA_DIR=~/.neuron/dlvh npx neuron-inspector
+```
+
+### 3. Register each bridge with your AI tool
+
+```bash
+claude mcp add rasheed-personal -- npx neuron-inspector
+claude mcp add letschop -- env NEURON_BRIDGE_PORT=7378 NEURON_DATA_DIR=~/.neuron/letschop npx neuron-inspector
+claude mcp add dlvh -- env NEURON_BRIDGE_PORT=7379 NEURON_DATA_DIR=~/.neuron/dlvh npx neuron-inspector
+```
+
+Each bridge logs its data directory on startup so you can confirm isolation:
+
+```
+[bridge] Data directory: /Users/you/.neuron/letschop
+[bridge] Primary mode — WebSocket server on 127.0.0.1:7378
+```
+
+Data layout:
+
+```
+~/.neuron/              ← rasheed-personal (default)
+~/.neuron/letschop/     ← letschop leads, monitors, recipes, collections
+~/.neuron/dlvh/         ← dlvh leads, monitors, recipes, collections
+```
+
+---
+
 ## What you can do
 
-### Ask your agent to debug a page
+### Debug a page
 
 > "Why is this page slow?"
 
@@ -79,55 +131,63 @@ The agent calls `neuron_perf_snapshot` and gets back Core Web Vitals, render-blo
 
 `neuron_a11y_audit` runs a WCAG audit — color contrast failures, missing alt text, broken heading hierarchy, unlabeled form fields.
 
-### Ask your agent to explore traffic
+### Explore traffic
 
 > "What APIs is this SPA calling?"
 
 `neuron_discover_apis` maps every endpoint from observed traffic — call counts, status codes, auth patterns, response shapes.
 
-> "Search all network responses for 'user_id'"
+> "Reverse-engineer this site's API into a collection"
+
+`neuron_api_blueprint` analyzes traffic, infers schemas, detects auth patterns, and creates a ready-to-use API collection.
 
-`neuron_search_traffic` does full-text search across every captured response body.
+### Prospect and generate leads
 
-> "Show me the network waterfall"
+> "Scan these 20 Instagram profiles and score them as leads"
 
-`neuron_waterfall` gives DNS, TCP, TLS, TTFB timing per resource — the same view as DevTools Network, but in your agent's context.
+`neuron_profile_scanner` visits each profile, extracts data. `neuron_lead_scorer` scores them by follower count, bio keywords, website presence.
 
-### Ask your agent to interact with the page
+> "Find people asking for delivery services in this hashtag feed"
 
-> "Click the Sign Up button"
+`neuron_demand_scanner` scrolls the feed, matches trigger phrases like "looking for", "need a", "who delivers", and enriches each poster's profile.
 
-`neuron_click` finds it by CSS selector or visible text and clicks it.
+> "Who are my competitor's most engaged followers?"
 
-> "Fill in the email field with test@example.com"
+`neuron_competitor_mapper` scans their recent posts, ranks commenters by frequency, and categorizes each as potential customer, fellow business, or influencer.
 
-`neuron_type` targets the input and types into it.
+### Monitor and track
 
-> "Scroll down and extract all the product listings"
+> "Watch this collection for new items matching 'logistics'"
 
-`neuron_scroll` + `neuron_extract_data` — scrolls the page and pulls structured data from repeating patterns (cards, tables, feeds).
+`neuron_collection_watch` creates a persistent monitor that alerts when matching content appears.
 
-### Ask your agent to test edge cases
+> "Show me all opportunities from the last 24 hours"
 
-> "Mock the payments API to return a 500 error"
+`neuron_opportunity_radar` aggregates alerts from all your monitors into one feed.
 
-`neuron_set_mock` intercepts matching requests and returns your custom response. Test error states without touching the real backend.
+> "Track who mentions our brand across platforms"
 
-> "Take a snapshot, click submit, then tell me what changed"
+`neuron_mention_tracker` scans feeds for your brand terms and saves matches to a searchable bank.
 
-`neuron_snapshot_state` before, action, `neuron_diff_states` after — detects DOM changes, added/removed elements, URL changes.
+### Automate social actions
 
-### Ask your agent to record and replay
+> "Like this post and leave a comment"
 
-> "Record what I'm doing as a workflow"
+`neuron_quick_action` handles per-platform DOM selectors — works across Instagram, X, LinkedIn, TikTok, Facebook.
 
-`neuron_start_recording` captures clicks, typing, and navigation. `neuron_start_demo` replays it as a polished video with chapter markers and cursor overlay.
+> "Send personalized DMs to this lead list"
+
+`neuron_dm_outreach` composes messages from a template with merge fields, paces them to avoid detection, and tracks status.
 
 ---
 
-## All 51 tools
+## All 177 tools
+
+### Browser Primitives (55 tools)
+
+Low-level extension commands forwarded over WebSocket.
 
-### Inspect & Debug
+#### Inspect & Debug
 | Tool | What it does |
 |------|-------------|
 | `neuron_query_dom` | DOM snapshot of the page or a subtree |
@@ -137,19 +197,24 @@ The agent calls `neuron_perf_snapshot` and gets back Core Web Vitals, render-blo
 | `neuron_screenshot` | PNG screenshot of the visible area |
 | `neuron_diagnose` | Connection health check |
 | `neuron_list_tabs` | Open tabs with platform detection |
+| `neuron_session_diagnostics` | Agent session health |
+| `neuron_action_space` | Snapshot all interactable controls on a page |
 
-### Browse & Automate
+#### Browse & Automate
 | Tool | What it does |
 |------|-------------|
 | `neuron_click` | Click by selector or text |
 | `neuron_type` | Type into inputs and contenteditable |
 | `neuron_scroll` | Scroll by pixels or into view |
 | `neuron_navigate` | Navigate to a URL |
+| `neuron_press_key` | Press keyboard key (Enter, Tab, Escape, etc.) |
+| `neuron_focus_tab` | Bring a tab to the foreground |
 | `neuron_open_tab` | Open a new tab |
 | `neuron_reload` | Reload a tab |
 | `neuron_run_sequence` | Multi-step automation (click, type, wait, eval) |
+| `neuron_trigger_post` | Trigger the IG post runner |
 
-### Network Intelligence
+#### Network Intelligence
 | Tool | What it does |
 |------|-------------|
 | `neuron_get_requests` | Query HTTP requests by tab, method, status, URL |
@@ -161,28 +226,28 @@ The agent calls `neuron_perf_snapshot` and gets back Core Web Vitals, render-blo
 | `neuron_replay_request` | Re-fire a request with the browser's live session |
 | `neuron_waterfall` | DNS/TLS/TTFB timing per resource |
 
-### Security
+#### Security & Auth
 | Tool | What it does |
 |------|-------------|
 | `neuron_security_scan` | Leaked secrets, missing headers, CORS, mixed content |
 | `neuron_check_auth` | Verify platform credentials |
 | `neuron_detect_blocker` | Detect rate limits, captchas, login walls |
 
-### Quality
+#### Quality
 | Tool | What it does |
 |------|-------------|
 | `neuron_a11y_audit` | WCAG audit — contrast, labels, headings, tabindex |
 | `neuron_perf_snapshot` | Core Web Vitals, resource breakdown, memory |
 | `neuron_seo_audit` | Meta, OG, headings, structured data, links |
 
-### Network Mocking
+#### Network Mocking
 | Tool | What it does |
 |------|-------------|
 | `neuron_set_mock` | Intercept requests, return custom responses |
 | `neuron_get_mocks` | List active mock rules |
 | `neuron_clear_mocks` | Remove all mocks |
 
-### Cookies & Storage
+#### Cookies & Storage
 | Tool | What it does |
 |------|-------------|
 | `neuron_get_cookies` | Read cookies for a URL |
@@ -191,7 +256,7 @@ The agent calls `neuron_perf_snapshot` and gets back Core Web Vitals, render-blo
 | `neuron_get_storage` | Read localStorage / sessionStorage |
 | `neuron_clear_storage` | Clear storage |
 
-### Page Monitoring
+#### Page State
 | Tool | What it does |
 |------|-------------|
 | `neuron_snapshot_state` | Capture page state for later diff |
@@ -201,28 +266,213 @@ The agent calls `neuron_perf_snapshot` and gets back Core Web Vitals, render-blo
 | `neuron_stop_watch` | Stop watching |
 | `neuron_extract_data` | Extract structured data from feeds, tables, listings |
 
-### Demo Recording
+#### Demo Recording
 | Tool | What it does |
 |------|-------------|
 | `neuron_start_recording` | Record interactions as a workflow |
 | `neuron_stop_recording` | Save the recording |
 | `neuron_list_workflows` | List saved workflows |
+| `neuron_toggle_workflow` | Enable or disable a workflow |
 | `neuron_start_replay` | Replay a workflow |
 | `neuron_stop_replay` | Stop replay |
 | `neuron_start_demo` | Record a demo video with chapters + cursor |
 | `neuron_workflow_status` | Engine state |
 
-### Other
+### Compound Tools (15 tools)
+
+Bridge-side orchestration that chains multiple primitives in one call.
+
 | Tool | What it does |
 |------|-------------|
-| `neuron_trigger_post` | Trigger the post runner |
-| `neuron_session_diagnostics` | Agent session health |
+| `neuron_research_page` | Deep-read a URL: navigate, scroll, extract, screenshot |
+| `neuron_research_profiles` | Research multiple URLs in parallel (max 8) |
+| `neuron_search_and_collect` | Search a site and collect results across pages |
+| `neuron_fill_and_submit` | Fill a form and optionally submit it |
+| `neuron_audit_page` | Run all quality audits in one call |
+| `neuron_monitor_action` | Snapshot, act, diff to verify changes |
+| `neuron_wait_for` | Wait for element, text, or URL condition |
+| `neuron_smart_click` | Click with retry, fallback chain, verification |
+| `neuron_smart_type` | Type with retry and value verification |
+| `neuron_health_check` | Check tab readiness (no blockers, no captcha) |
+| `neuron_vision_act` | Screenshot + describe + act (no selectors needed) |
+| `neuron_approve_via_whatsapp` | Send approval request to WhatsApp, wait for reply |
+| `neuron_extract_to_json` | Extract data as clean JSON/CSV/YAML |
+| `neuron_grab_media` | Extract and download video/audio from any page |
+| `neuron_grab_media_batch` | Download videos from multiple URLs (max 5) |
+
+### Business Intelligence Tools (29 tools)
+
+High-level tools for prospecting, lead generation, competitive intelligence, and social automation. All compound tools — they chain extension primitives with no new extension code.
+
+#### Prospecting
+| Tool | What it does |
+|------|-------------|
+| `neuron_profile_scanner` | Batch-scan profile URLs with session resume support |
+| `neuron_hashtag_scout` | Scout hashtag feeds, extract posts and authors |
+| `neuron_local_scout` | Search location/explore feeds with profile enrichment and filters |
+| `neuron_bio_harvester` | Extract all links from profile bios (websites, WhatsApp, Linktree, email) |
+| `neuron_cross_platform_finder` | Find a handle across platforms with confidence scores |
+
+#### Lead Generation
+| Tool | What it does |
+|------|-------------|
+| `neuron_demand_scanner` | Find demand signals via trigger phrases, optional recurring monitor |
+| `neuron_post_to_lead` | Monitor post comments for trigger keywords, extract leads |
+| `neuron_comment_miner` | Extract commenters from a post as a lead list |
+| `neuron_lead_scorer` | Score leads by follower count, bio keywords, website, location |
+| `neuron_revenue_tracker` | CRM-lite funnel: discovered to closed-won with revenue attribution |
+
+#### Competitive Intelligence
+| Tool | What it does |
+|------|-------------|
+| `neuron_competitor_mapper` | Map a competitor's engaged audience, categorize commenters |
+| `neuron_influencer_vetter` | Trust score (0-100) with red flag detection |
+| `neuron_engagement_analyzer` | Analyze your own posting performance with recommendations |
+
+#### Brand & Content
+| Tool | What it does |
+|------|-------------|
+| `neuron_mention_tracker` | Track brand mentions across platforms, optional recurring monitor |
+| `neuron_social_proof` | Collect testimonials and positive mentions |
+| `neuron_post_analyzer` | Extract metrics and classify posts (single or batch) |
+| `neuron_content_pipeline` | Repurpose content across platform formats |
+
+#### Collections & Monitoring
+| Tool | What it does |
+|------|-------------|
+| `neuron_collection_harvest` | One-shot deep-scroll + extract + keyword filter on any feed |
+| `neuron_collection_watch` | Persistent monitor for new items in a collection |
+| `neuron_opportunity_radar` | Aggregated alert feed from all monitors |
+| `neuron_page_watch` | Semantic page change monitor with structured diffs |
+
+#### Social Automation
+| Tool | What it does |
+|------|-------------|
+| `neuron_quick_action` | Platform-aware like/comment/follow/DM (per-platform selectors) |
+| `neuron_dm_outreach` | Paced DM campaigns with merge templates |
+| `neuron_group_link_scanner` | Extract WhatsApp/Telegram group invite links |
+
+#### Data Extraction
+| Tool | What it does |
+|------|-------------|
+| `neuron_pattern_learner` | Learn CSS selectors from example text, store for reuse |
+
+#### Network Analysis
+| Tool | What it does |
+|------|-------------|
+| `neuron_site_xray` | Full network analysis (requests, perf, security, APIs in parallel) |
+| `neuron_traffic_replay` | Capture/replay/list HAR traffic with mock rules |
+| `neuron_api_blueprint` | Reverse-engineer APIs from traffic into a collection |
+| `neuron_page_weight` | Asset breakdown by category with budget violation detection |
+
+### Recipe Tools (17 tools)
+
+Manage and run recipe workflows — purpose-built agents that get better with every run.
+
+| Tool | What it does |
+|------|-------------|
+| `neuron_recipe_run` | Start a recipe with variables and rules |
+| `neuron_recipe_complete` | End a recipe run and log the outcome |
+| `neuron_recipe_list` | List available recipes |
+| `neuron_recipe_get` | Get a recipe's full contents |
+| `neuron_recipe_create` | Create a new recipe |
+| `neuron_recipe_update` | Update a recipe |
+| `neuron_recipe_delete` | Delete a recipe |
+| `neuron_recipe_log` | Log a run outcome to memory |
+| `neuron_recipe_memory` | Read run history |
+| `neuron_recipe_import` | Import from GitHub or local path |
+| `neuron_recipe_export` | Export a recipe for sharing |
+| `neuron_profile_get` | Read user profile |
+| `neuron_profile_save` | Save user profile |
+| `neuron_rules_get` | Read active rules |
+| `neuron_rules_set` | Set or update rules |
+| `neuron_quickstart` | First-run onboarding |
+
+### Scheduler Tools (4 tools)
+
+| Tool | What it does |
+|------|-------------|
+| `neuron_schedule_recipe` | Schedule a recipe on interval or cron |
+| `neuron_schedule_list` | List all scheduled recipes |
+| `neuron_schedule_remove` | Remove a schedule |
+| `neuron_schedule_toggle` | Enable or disable a schedule |
+
+### Session State Tools (5 tools)
+
+| Tool | What it does |
+|------|-------------|
+| `neuron_session_save` | Save session state for resumption |
+| `neuron_session_load` | Load session state |
+| `neuron_session_list` | List active sessions |
+| `neuron_session_delete` | Delete a session |
+| `neuron_session_checkpoint` | Quick progress update |
+
+### Monitor Tools (8 tools)
+
+| Tool | What it does |
+|------|-------------|
+| `neuron_monitor_create` | Create a page monitor |
+| `neuron_monitor_list` | List all monitors |
+| `neuron_monitor_get` | Get monitor details |
+| `neuron_monitor_update` | Update monitor config |
+| `neuron_monitor_remove` | Remove a monitor |
+| `neuron_monitor_toggle` | Enable/disable a monitor |
+| `neuron_monitor_check` | Force an immediate check |
+| `neuron_monitor_alerts` | Get recent alerts |
+
+### Control Tools (4 tools)
+
+| Tool | What it does |
+|------|-------------|
+| `neuron_stop` | Emergency stop all autonomous operations |
+| `neuron_status` | Show what's currently running |
+| `neuron_pause_all` | Pause all monitors and schedules |
+| `neuron_resume_all` | Resume all paused operations |
+
+### API Collection Tools (28 tools)
+
+Full Postman-like API collection management persisted to `~/.neuron/collections/`.
+
+| Tool | What it does |
+|------|-------------|
+| `neuron_api_list_collections` | List all collections |
+| `neuron_api_get_collection` | Get collection structure |
+| `neuron_api_create_collection` | Create a collection |
+| `neuron_api_delete_collection` | Delete a collection |
+| `neuron_api_update_collection` | Update name/description |
+| `neuron_api_set_defaults` | Set collection-level defaults |
+| `neuron_api_upsert_endpoint` | Add or update an endpoint |
+| `neuron_api_remove_endpoint` | Remove an endpoint |
+| `neuron_api_move_endpoint` | Move endpoint between folders |
+| `neuron_api_create_folder` | Create a folder |
+| `neuron_api_update_folder` | Update folder config |
+| `neuron_api_delete_folder` | Delete a folder |
+| `neuron_api_list_folders` | List folders |
+| `neuron_api_set_env` | Create/update an environment |
+| `neuron_api_remove_env` | Remove an environment |
+| `neuron_api_list_envs` | List environments |
+| `neuron_api_switch_env` | Set active environment |
+| `neuron_api_create_scenario` | Create a test scenario |
+| `neuron_api_update_scenario` | Update a scenario |
+| `neuron_api_delete_scenario` | Delete a scenario |
+| `neuron_api_list_scenarios` | List scenarios |
+| `neuron_api_run` | Run endpoints against an environment |
+| `neuron_api_run_scenario` | Run a scenario with variable chaining |
+| `neuron_api_query` | Search endpoints across collections |
+| `neuron_api_generate_tests` | Suggest test assertions |
+| `neuron_api_export_collection` | Export as YAML or Postman JSON |
+| `neuron_api_import_collection` | Import from YAML or Postman JSON |
+| `neuron_api_import_file` | Import from a file path |
+
+### Automation Tools (12 tools)
+
+Browser automation workflows with scheduling and persistence.
 
 ---
 
 ## Recipes — purpose-built agents
 
-The 51 tools are primitives. A **recipe** turns them into a purpose-built agent — a QA engineer, a job applicant, a web researcher. Recipes are shareable, and they get better with every run.
+The 177 tools are primitives. A **recipe** turns them into a purpose-built agent — a QA engineer, a job applicant, a web researcher. Recipes are shareable, and they get better with every run.
 
 ### Built-in recipes
 
@@ -238,15 +488,68 @@ A recipe is a folder with instructions (`agent.md`) and config (`recipe.yaml`).
 
 **Recipes are alive.** Each run captures outcomes to `memory/`. After enough runs, the agent reviews what worked and updates its own strategy in `learnings.md`. A job applicant that discovers technical-tone cover letters get 3x more responses will start writing technical-tone cover letters by default.
 
-**Recipes feed each other.** The web researcher produces reports that the job applicant reads to tailor cover letters. The QA engineer reads its own previous reports to re-check if old bugs are fixed. Output from one recipe is input to another.
+### Build your own
 
-### Use a recipe
+See [RECIPE-SPEC.md](RECIPE-SPEC.md) for the full format.
 
-Copy a recipe's `agent.md` into your project as a CLAUDE.md (or append it), fill in the `{{variables}}` from `recipe.yaml`, and run. The recipe tells your AI agent exactly how to use the 51 tools for that purpose.
+---
 
-### Build your own
+## Data storage
+
+All persistent data lives in `~/.neuron/`:
+
+```
+~/.neuron/
+  pipeline.yaml            # Revenue tracker leads
+  testimonials.yaml        # Social proof bank
+  mentions.yaml            # Brand mention history
+  extractors.yaml          # Learned extraction patterns
+  group-links.yaml         # WhatsApp/Telegram links
+  outreach-campaigns.yaml  # DM outreach campaigns
+  monitors.yaml            # Monitor configurations
+  monitor-alerts.yaml      # Monitor alert history
+  collections/             # API collections (YAML)
+  sessions/                # Session state files
+  replays/                 # HAR traffic captures
+  recipes/                 # Recipe definitions
+  rules.yaml               # Global rules
+  profile.yaml             # User profile
+```
+
+---
+
+## Development
+
+```bash
+# Build the bridge
+cd packages/extension/bridge
+npx tsc
+
+# Build the full extension
+cd packages/extension
+node build.js
+
+# Type-check without emitting
+npx tsc --noEmit
+```
 
-See [RECIPE-SPEC.md](RECIPE-SPEC.md) for the full format. The core idea: write the instructions you'd give a skilled human, reference the tools by name, add reflect/evolve sections so the agent improves itself, and declare your variables so others can import and customize.
+### Source files
+
+| File | Purpose |
+|------|---------|
+| `server.ts` | MCP server, WebSocket bridge, tool registration |
+| `tools.ts` | Browser primitive definitions + name mapping |
+| `compound-tools.ts` | Compound tools (research, search, fill, audit, media) |
+| `business-tools.ts` | 29 business intelligence and developer tools |
+| `recipe-tools.ts` | Recipe management + rules + profile |
+| `scheduler.ts` | Cron-like recipe scheduling |
+| `session-state.ts` | Session state persistence |
+| `monitor.ts` | Page monitoring with alerts |
+| `killswitch.ts` | Emergency stop, pause, resume |
+| `resilience.ts` | Retry, wait, health check helpers |
+| `correlation.ts` | WebSocket request/response correlation |
+| `collections/` | API collection CRUD + runner |
+| `automations/` | Browser automation workflows |
 
 ---
 

package/dist/automations/executor.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Step Execution Engine — Browser Automation
+ *
+ * Dispatches automation steps to bridge primitives via WebSocket.
+ * Handles variable substitution, tab tracking, assertions, extraction,
+ * retry logic, and error handling.
+ */
+import type { WebSocket } from "ws";
+import type { PendingCalls } from "../correlation.js";
+import type { Suite, Step, StepResult, RunResult } from "./types.js";
+interface BridgeContext {
+    ws: WebSocket;
+    pending: PendingCalls;
+}
+export declare function executeStep(ctx: BridgeContext, step: Step, variables: Record<string, string>, tabId: number | null, suiteDefaults?: Suite["defaults"]): Promise<{
+    result: StepResult;
+    tabId: number | null;
+    variables: Record<string, string>;
+}>;
+export declare function executeSuite(ctx: BridgeContext, suiteId: string, suite: Suite): Promise<RunResult>;
+export {};