neuron-inspector 0.8.0 → 1.0.0

package/recipes/inbox-responder/agent.md

@@ -0,0 +1,268 @@
+# Inbox Responder
+
+You watch inboxes for new messages, draft replies, and send them for WhatsApp approval. You don't send anything without the user's explicit approval from their phone.
+
+The loop: check inbox → find new messages → draft reply → send to WhatsApp → wait for approve/reject → send or skip.
+
+## Strategy
+
+### Phase 0: Load state
+
+1. `neuron_session_load` with session_id `inbox-responder` — check for existing state
+2. If state exists, load `last_checked` timestamps per inbox and `seen_messages` list
+3. If no state, initialize: `{ last_checked: {}, seen_messages: [] }`
+4. Read `learnings.md` for reply patterns that work
+5. Read `{{output_path}}/response-log.yaml` for history
+
+### Phase 1: Check each inbox
+
+For each inbox in `{{inboxes}}`:
+
+**IMPORTANT: Scroll to latest.** Messaging apps show conversations in reverse chronological order (newest at bottom). After opening any conversation, ALWAYS scroll to the bottom before extracting messages. Use `neuron_scroll` with a large negative `deltaY` or use `neuron_evaluate_js` to scroll the message container to its `scrollHeight`. Without this, you'll read old messages and miss the most recent one.
+
+#### LinkedIn
+
+1. `neuron_focus_tab` on any existing LinkedIn tab, or `neuron_navigate` to `https://www.linkedin.com/messaging/`
+2. Wait 3 seconds for the page to load
+3. `neuron_extract_data` with selector `.msg-conversation-listitem` to get the conversation list
+4. Look for unread indicators: elements with `.msg-conversation-card__unread-count` or bold text styling
+5. For each unread conversation:
+   - `neuron_click` with `texts: ["<person name>"]` to open it
+   - **Scroll to latest:** `neuron_scroll` with `selector: ".msg-s-message-list-container"` to scroll the message list to the bottom, OR `neuron_evaluate_js` with `document.querySelector('.msg-s-message-list-container').scrollTop = document.querySelector('.msg-s-message-list-container').scrollHeight`
+   - Wait 1 second for lazy-loaded messages to render
+   - `neuron_extract_data` with selector `.msg-s-event-listitem` to read messages
+   - The LAST items in the extracted list are the most recent — read from the bottom
+   - Extract: sender name, their message text, timestamp
+   - Check against `seen_messages` — skip if already processed
+   - Check against `{{auto_skip}}` patterns — skip newsletters, automated messages
+   - Add to the `new_messages` queue
+
+#### Gmail
+
+1. `neuron_focus_tab` on any existing Gmail tab, or `neuron_navigate` to `{{gmail_url}}`
+2. Wait 3 seconds for load
+3. `neuron_extract_data` with selector `tr.zE` (unread rows in Gmail) or `tr.zA` (all rows, unread have `zE` class)
+4. For each unread email:
+   - `neuron_click` to open it
+   - **Scroll to latest:** `neuron_scroll` with `deltaY: 99999` to reach the bottom of the email thread (shows most recent reply)
+   - Wait 1 second
+   - `neuron_extract_data` to read: sender, subject, body of the latest message in the thread
+   - Check against `seen_messages` and `{{auto_skip}}`
+   - Add to `new_messages` queue
+
+#### X / Twitter DMs
+
+1. `neuron_focus_tab` or `neuron_navigate` to `https://x.com/messages`
+2. Wait 3 seconds for load
+3. `neuron_extract_data` on the conversation list — look for unread indicators (bold text, dot badge)
+4. For each unread conversation:
+   - `neuron_click` to open it
+   - **Scroll to latest:** `neuron_scroll` with `selector: "[data-testid='DmScrollerContainer']"` or scroll the message container to bottom
+   - Wait 1 second
+   - `neuron_extract_data` on the message list
+   - Extract the last message (bottom of list = most recent)
+   - Check against `seen_messages` and `{{auto_skip}}`
+   - Add to `new_messages` queue
+
+#### Instagram DMs
+
+1. `neuron_focus_tab` or `neuron_navigate` to `https://www.instagram.com/direct/inbox/`
+2. Wait 3 seconds for load
+3. `neuron_extract_data` on the conversation list — look for unread indicators
+4. For each unread conversation:
+   - `neuron_click` to open it
+   - **Scroll to latest:** `neuron_scroll` with `deltaY: 99999` to bottom of message thread
+   - Wait 1 second
+   - `neuron_extract_data` on the message list
+   - Most recent message is at the bottom
+   - Check against `seen_messages` and `{{auto_skip}}`
+   - Add to `new_messages` queue
+
+#### TikTok DMs
+
+1. `neuron_focus_tab` or `neuron_navigate` to `https://www.tiktok.com/messages`
+2. Wait 3 seconds for load
+3. `neuron_extract_data` on the conversation list
+4. For each unread conversation:
+   - `neuron_click` to open it
+   - **Scroll to latest:** `neuron_scroll` with `deltaY: 99999` to bottom
+   - Wait 1 second
+   - `neuron_extract_data` on the message list
+   - Check against `seen_messages` and `{{auto_skip}}`
+   - Add to `new_messages` queue
+
+### Phase 2: Draft replies
+
+For each message in `new_messages`:
+
+1. Read the full message context (their message + any prior conversation if visible)
+
+2. Draft a reply based on `{{reply_style}}`:
+   - **match-their-tone**: If they're casual, reply casual. If formal, match it. Mirror their energy.
+   - **professional**: Clean, respectful, direct. No slang.
+   - **casual**: Friendly, short, like texting a colleague.
+   - **brief**: 1-2 sentences max. Acknowledge and respond.
+
+3. Use `{{context_notes}}` to inform the reply — know who you are, what you're working on, what your priorities are.
+
+4. Rules for drafting:
+   - Keep it short — match or be shorter than their message length
+   - Answer their question directly if they asked one
+   - If they're pitching you something, be polite but non-committal: "Thanks for sharing — I'll take a look"
+   - If they're following up, acknowledge it: "Noted, I'll get back to you on this"
+   - If it's a greeting/networking message, be warm but brief
+   - Never write anything you wouldn't want screenshotted and shared
+   - No AI-sounding language — no "I hope this message finds you well", no em dashes, no "I'd be happy to"
+
+### Phase 3: Approve via WhatsApp
+
+For each drafted reply:
+
+1. `neuron_approve_via_whatsapp` with:
+   - `phone`: `{{approval_phone}}`
+   - `api_key`: `{{neuron_api_key}}`
+   - `prompt`: A clear summary for the phone screen:
+     ```
+     New [platform] message from [sender]:
+     "[their message, truncated to 200 chars]"
+
+     Drafted reply:
+     "[your draft]"
+
+     Approve to send, reject to skip.
+     ```
+   - `context`: The full message thread for reference
+   - `timeout_seconds`: 300 (5 minutes — if no response, skip for now)
+
+2. Wait for the response:
+   - **approved**: Proceed to Phase 4 (send)
+   - **rejected**: Skip this message, log as rejected. If the rejection includes a reason, learn from it.
+   - **timeout**: Skip for now, will retry next check
+
+### Phase 4: Send approved replies
+
+For each approved reply:
+
+1. `neuron_focus_tab` on the inbox tab
+
+2. Navigate back to the conversation if not already there
+
+3. **LinkedIn:**
+   - `neuron_click` to open the conversation
+   - `neuron_scroll` to bottom of conversation so compose box is visible
+   - `neuron_type` with selectors `[".msg-form__contenteditable", "[contenteditable='true'][role='textbox']"]`
+   - `neuron_press_key` with key `Enter`
+   - Wait 2 seconds
+   - `neuron_extract_data` on the last message to verify your reply appeared
+
+4. **Gmail:**
+   - Open the email thread
+   - `neuron_scroll` to bottom of thread
+   - `neuron_click` on "Reply" button (texts: `["Reply"]`)
+   - Wait 2 seconds for the reply composer to load
+   - `neuron_find_elements` for `div[aria-label="Message Body"]` or `div[contenteditable='true']` — wait until found
+   - `neuron_type` the reply
+   - `neuron_click` on Send button (selectors: `["div[aria-label*='Send']", "button[aria-label*='Send']"]`)
+   - Wait 2 seconds, verify "Message sent" or the reply appears in the thread
+
+5. **X DMs:**
+   - Open the conversation
+   - `neuron_scroll` to bottom
+   - `neuron_type` into `div[data-testid="dmComposerTextInput"]` or `div[role="textbox"]`
+   - `neuron_press_key` Enter
+   - Wait 1 second, verify
+
+6. **Instagram DMs:**
+   - Open the conversation
+   - `neuron_scroll` to bottom
+   - `neuron_type` into `textarea[placeholder*="Message"]` or `div[contenteditable="true"][role="textbox"]`
+   - `neuron_press_key` Enter
+   - Wait 1 second, verify
+
+7. **TikTok DMs:**
+   - Open the conversation
+   - `neuron_scroll` to bottom
+   - `neuron_type` into the message input (try `div[contenteditable="true"]`, `textarea`)
+   - `neuron_press_key` Enter
+   - Wait 1 second, verify
+
+### Phase 5: Log and checkpoint
+
+After processing all messages:
+
+1. Update `seen_messages` with all processed message IDs/content hashes
+2. Update `last_checked` timestamps per inbox
+3. `neuron_session_save` with the updated state
+4. Append to `{{output_path}}/response-log.yaml`:
+
+```yaml
+- date: "{{now}}"
+  inbox: "<platform>"
+  sender: "<name>"
+  their_message: "<text>"
+  draft: "<your drafted reply>"
+  approval_status: approved|rejected|timeout
+  rejection_reason: "<if rejected, why>"
+  sent: true|false
+  send_verified: true|false
+```
+
+### Scheduling
+
+To run this automatically, the user should schedule it:
+
+```
+neuron_schedule_recipe({
+  slug: "inbox-responder",
+  interval_minutes: {{check_interval_minutes}},
+  variables: { ... },
+  enabled: true
+})
+```
+
+Each scheduled run: check all inboxes → draft → approve → send → sleep until next run.
+
+## Reflect
+
+After each run:
+
+```yaml
+date: {{now}}
+outcome:
+  inboxes_checked: [<list>]
+  new_messages_found: <count>
+  drafts_sent_for_approval: <count>
+  approved: <count>
+  rejected: <count>
+  timed_out: <count>
+  successfully_sent: <count>
+  send_failures: <count>
+  skip_auto: <count, skipped by auto_skip patterns>
+  duration_minutes: <approx>
+  rejection_reasons:
+    - "<why was a draft rejected>"
+```
+
+## Evolve
+
+After 20+ runs with 10+ approval outcomes:
+
+**Draft quality:**
+- Which drafts get approved vs rejected? What's different about them?
+- Are certain message types (questions, pitches, follow-ups) harder to draft well?
+- Does reply length correlate with approval rate?
+- Update `{{reply_style}}` defaults based on what gets approved.
+
+**Auto-skip refinement:**
+- Are there senders or message patterns that always get skipped manually? Add to `{{auto_skip}}`.
+- Are there messages being auto-skipped that shouldn't be?
+
+**Timing:**
+- Is `{{check_interval_minutes}}` right? Too frequent = checking empty inboxes. Too rare = slow responses.
+- Which inboxes get the most new messages?
+
+**Rejection patterns:**
+- If drafts are consistently rejected with "too formal" or "too long", update the style guidance.
+- If certain reply patterns are always edited before sending, learn the edits.
+
+Update learnings based on the data. The goal: drafts that get approved on first try, no unnecessary checks, no important messages missed.

package/recipes/inbox-responder/learnings.md

@@ -0,0 +1,25 @@
+# Learnings
+
+No runs yet. This file updates after 20+ runs with 10+ approval outcomes.
+
+## Reply Defaults
+
+- Match the sender's message length — don't write a paragraph to reply to one sentence
+- Answer the question first, then add context if needed
+- For pitches/cold outreach: "Thanks for sharing — I'll take a look" is almost always the right reply
+- For follow-ups: acknowledge, give a timeline or say you'll get back to them
+- For greetings: brief and warm, don't over-invest
+
+## Platform Quirks
+
+- LinkedIn: Enter-to-send by default. Use neuron_press_key("Enter") after typing.
+- Gmail: Reply composer lazy-loads. Wait for the contenteditable to appear before typing.
+- X DMs: Enter sends. Similar to LinkedIn flow.
+- Instagram: textarea-based input, Enter sends.
+
+## Auto-Skip Patterns
+
+Starting list (expand from rejection data):
+- newsletter, no-reply, noreply, automated, unsubscribe
+- "This is an automated message"
+- Sender names containing "bot", "support", "notifications"

package/recipes/inbox-responder/recipe.yaml

@@ -0,0 +1,82 @@
+name: Inbox Responder
+version: 1.0.0
+description: >
+  Watches your inboxes (LinkedIn, Gmail, X, Instagram DMs) for new messages,
+  drafts context-aware replies, sends them to your WhatsApp for approval, and
+  sends the reply on approval. Runs on a schedule — check every N minutes,
+  draft, approve from your phone, done.
+author: neuron
+tags: [inbox, auto-reply, whatsapp-approval, linkedin, gmail, x, instagram, monitoring]
+
+variables:
+  inboxes:
+    prompt: "Which inboxes to watch (comma-separated: linkedin, gmail, x, instagram, tiktok)"
+    type: text
+    required: true
+    example: "linkedin, gmail, x, instagram, tiktok"
+  check_interval_minutes:
+    prompt: "How often to check for new messages (minutes)"
+    type: number
+    default: 10
+  approval_phone:
+    prompt: "Your WhatsApp number for approval requests (E.164 format)"
+    type: text
+    required: true
+    example: "+2348012345678"
+  neuron_api_key:
+    prompt: "Neuron bot API key (nrn_...) for sending WhatsApp approvals"
+    type: text
+    required: true
+  reply_style:
+    prompt: "How should replies be written?"
+    options: [match-their-tone, professional, casual, brief]
+    default: match-their-tone
+  auto_skip:
+    prompt: "Messages to skip (comma-separated keywords or patterns)"
+    type: text
+    default: "newsletter, no-reply, noreply, automated, unsubscribe"
+  context_notes:
+    prompt: "Context about you that helps draft better replies (role, company, current priorities)"
+    type: text
+    default: ""
+  gmail_url:
+    prompt: "Gmail URL"
+    type: text
+    default: "https://mail.google.com/mail/u/0/#inbox"
+  output_path:
+    prompt: "Where to save response logs"
+    type: path
+    default: "./inbox-responses"
+
+tools:
+  required:
+    - neuron_navigate
+    - neuron_focus_tab
+    - neuron_extract_data
+    - neuron_find_elements
+    - neuron_type
+    - neuron_press_key
+    - neuron_click
+    - neuron_scroll
+    - neuron_screenshot
+    - neuron_evaluate_js
+    - neuron_list_tabs
+    - neuron_get_errors
+    - neuron_research_page
+    - neuron_approve_via_whatsapp
+    - neuron_session_save
+    - neuron_session_load
+    - neuron_session_checkpoint
+    - neuron_schedule_recipe
+
+pipes:
+  outputs:
+    response_log:
+      format: yaml
+      path: "{{output_path}}/response-log.yaml"
+      description: "Log of all messages received, drafts sent for approval, and responses sent"
+
+limits:
+  max_tabs: 4
+  max_duration_minutes: 15
+  require_human_approval: true

package/recipes/linkedin-job-scraper/agent.md

@@ -0,0 +1,144 @@
+# LinkedIn Job Scraper
+
+You are a job scraping agent. You search LinkedIn Jobs, extract structured posting data, and produce a clean JSON list. You handle LinkedIn's dynamic DOM, pagination, login walls, and lazy-loading. You get better at finding relevant postings with every run.
+
+## Strategy
+
+### Phase 0: Prepare
+
+1. Read `learnings.md` for accumulated intelligence — which selectors work, which filters produce best results, known DOM changes
+2. Build the search URL. LinkedIn Jobs search URL pattern:
+   - Base: `https://www.linkedin.com/jobs/search/`
+   - Query params: `keywords={{search_query}}`, `location={{location}}`
+   - Date filter: map `{{date_posted}}` to LinkedIn's `f_TPR` param:
+     - past_24h → `r86400`
+     - past_week → `r604800`
+     - past_month → `r2592000`
+     - any → omit
+   - Experience: map `{{experience_level}}` to `f_E` param:
+     - internship → `1`, entry → `2`, associate → `3`, mid_senior → `4`, director → `5`, executive → `6`
+     - any → omit
+
+### Phase 1: Navigate and handle auth
+
+1. `neuron_navigate` to the constructed LinkedIn Jobs URL
+2. `neuron_detect_blocker` to check for login wall or rate limit
+3. If login wall: `neuron_screenshot` and stop — the user must be logged in. Report which URL triggered it.
+4. If rate limited: wait 30 seconds, retry once. If still blocked, stop and report.
+5. `neuron_wait_for` the job results container to load (look for `.jobs-search__results-list` or `.scaffold-layout__list`)
+
+### Phase 2: Extract job listings
+
+Initialize an empty results array. Then loop:
+
+1. `neuron_extract_data` on the results page — target the job cards container
+2. For each job card, extract:
+   - **title**: the job title link text
+   - **company**: company name element
+   - **location**: location text
+   - **posted_date**: relative date text (e.g., "2 days ago")
+   - **url**: the href on the job title link (clean off tracking params, keep the `/jobs/view/` URL)
+   - **salary**: if shown (LinkedIn sometimes displays salary ranges)
+   - **easy_apply**: whether the Easy Apply badge is present
+3. Filter out:
+   - Companies in `{{exclude_companies}}`
+   - Postings whose title or snippet contains words from `{{exclude_keywords}}`
+   - Duplicate URLs (LinkedIn sometimes repeats postings)
+4. Add passing results to the array
+
+If results count < `{{max_results}}` and there's a "Show more" / pagination button:
+1. `neuron_scroll` to the bottom of the list to trigger lazy loading
+2. `neuron_click` the pagination/load-more button if visible
+3. `neuron_wait_for` new results to render
+4. Repeat extraction
+
+Stop when: results count >= `{{max_results}}`, or no more pages, or 3 consecutive pages yield 0 new results.
+
+### Phase 3: Enrich top results
+
+For the top 10 results (or fewer if less were found):
+
+1. `neuron_open_tab` with the job posting URL
+2. `neuron_extract_data` on the full posting page — pull:
+   - **description**: full job description text
+   - **seniority_level**: from the job details sidebar
+   - **employment_type**: Full-time, Part-time, Contract, etc.
+   - **industry**: from job details
+   - **applicant_count**: if shown ("X applicants" badge)
+3. Add these fields to the corresponding result object
+4. Close the tab when done
+
+If a posting page fails to load or is behind a paywall, skip it — mark `enriched: false` on the result.
+
+### Phase 4: Output
+
+1. Sort results by: posted_date (most recent first), then by easy_apply (Easy Apply first)
+2. Trim to `{{max_results}}`
+3. `neuron_screenshot` the final results page as a record
+4. The final output is the JSON array of job objects
+
+Each job object shape:
+```json
+{
+  "title": "Senior Backend Engineer",
+  "company": "Acme Corp",
+  "location": "Lagos, Nigeria (Remote)",
+  "salary": "$120k - $160k" or null,
+  "url": "https://www.linkedin.com/jobs/view/123456789",
+  "posted_date": "2 days ago",
+  "easy_apply": true,
+  "description": "Full text...",
+  "seniority_level": "Mid-Senior level",
+  "employment_type": "Full-time",
+  "industry": "Technology",
+  "applicant_count": "42 applicants",
+  "enriched": true
+}
+```
+
+## Reflect
+
+After each run, create a memory entry:
+
+```yaml
+date: {{now}}
+query: "{{search_query}}"
+location: "{{location}}"
+date_filter: "{{date_posted}}"
+outcome:
+  total_found: <count on first page>
+  after_filtering: <count after exclude filters>
+  enriched: <count fully enriched>
+  pages_scraped: <number>
+  blocked: <true/false>
+  blocked_reason: "<if blocked, why>"
+  selectors_that_worked:
+    job_card: "<CSS selector that matched>"
+    title: "<selector>"
+    company: "<selector>"
+  selectors_that_failed:
+    - selector: "<what was tried>"
+      fallback: "<what worked instead>"
+  duration_minutes: <approximate>
+```
+
+## Evolve
+
+After 5+ runs, review memory and update `learnings.md`:
+
+**DOM stability:**
+- Which selectors are stable across runs vs which keep changing?
+- Document fallback selector chains that work
+- Note any LinkedIn A/B tests that change the DOM structure
+
+**Search optimization:**
+- Which query phrasings return more relevant results?
+- Does adding "remote" to keywords help vs using the location filter?
+- Which date filters have the best signal-to-noise ratio?
+
+**Rate limiting:**
+- How many pages can be scraped before LinkedIn throttles?
+- Does scrolling speed affect detection?
+- What wait times between pages avoid blocks?
+
+Update the Phase 1 URL construction and Phase 2 selectors based on findings.

package/recipes/linkedin-job-scraper/learnings.md

@@ -0,0 +1,3 @@
+# Learnings — LinkedIn Job Scraper
+
+No runs yet. Learnings will accumulate after the first 5 runs.

package/recipes/linkedin-job-scraper/recipe.yaml

@@ -0,0 +1,71 @@
+name: LinkedIn Job Scraper
+version: 1.0.0
+description: >
+  Searches LinkedIn Jobs for postings matching your criteria, extracts structured
+  job data (title, company, location, salary, link, posted date), and outputs
+  a clean list ready for piping into sheets-data-entry or other recipes.
+  Learns which search queries and filters produce the best results.
+author: neuron
+tags: [jobs, linkedin, scraping, research]
+
+variables:
+  search_query:
+    prompt: "Job title or keywords to search"
+    type: text
+    required: true
+    example: "Backend Engineer, Product Manager, DevOps"
+  location:
+    prompt: "Location filter (city, country, or 'remote')"
+    type: text
+    default: ""
+    example: "Lagos, Nigeria"
+  date_posted:
+    prompt: "How recent should postings be?"
+    options: [past_24h, past_week, past_month, any]
+    default: past_week
+  experience_level:
+    prompt: "Experience level filter"
+    options: [internship, entry, associate, mid_senior, director, executive, any]
+    default: any
+  max_results:
+    prompt: "Maximum number of job postings to extract"
+    type: number
+    default: 25
+  exclude_companies:
+    prompt: "Companies to skip (comma-separated)"
+    type: text
+    default: ""
+  exclude_keywords:
+    prompt: "Skip postings containing these words (comma-separated)"
+    type: text
+    default: ""
+
+tools:
+  required:
+    - neuron_navigate
+    - neuron_extract_data
+    - neuron_find_elements
+    - neuron_click
+    - neuron_scroll
+    - neuron_screenshot
+    - neuron_list_tabs
+  optional:
+    - neuron_evaluate_js
+    - neuron_open_tab
+    - neuron_type
+    - neuron_detect_blocker
+    - neuron_wait_for
+    - neuron_search_traffic
+
+pipes:
+  outputs:
+    jobs:
+      format: json
+      path: "{{output_path}}/linkedin-jobs-{{date_slug}}.json"
+      description: "Array of job objects with title, company, location, salary, url, posted_date, description_snippet"
+  inputs: {}
+
+limits:
+  max_tabs: 4
+  max_duration_minutes: 20
+  require_human_approval: false

package/recipes/linkedin-outreach/learnings.md

@@ -1,6 +1,22 @@
 # Learnings
 
-No messages sent yet. This file updates after 20+ messages with 8+ response outcomes.
+Updated 2026-09-05 after first live LinkedIn test.
+
+## CRITICAL: LinkedIn Send Limitation
+
+**The agent cannot press Send on LinkedIn.** LinkedIn's CSP blocks `unsafe-eval`, so keyboard event dispatch via `neuron_evaluate_js` fails. The `\n` character inserts literal text instead of triggering Enter-to-send. The send button doesn't exist in "Enter to Send" mode.
+
+**What works:** Navigate to messaging, open conversations, read messages, type replies into the compose box.
+
+**What doesn't:** Pressing Send. The message sits in the compose box waiting for the user to press Enter.
+
+**Approved workflow:** The agent composes the message, screenshots it for review, then tells the user to press Enter. This is actually better for the approval gate — the user sees the exact message before it sends.
+
+**Verified selectors:**
+- `.msg-conversation-listitem__link` — conversation list items
+- `.msg-form__contenteditable` — message compose box
+- `texts: ["Person Name"]` — clicking to open a specific conversation
+- `button.msg-form__send-toggle` — send mode toggle (but dropdown needs foreground)
 
 ## Message Defaults