hanzi-browse 2.3.1 → 2.3.3

package/README.md

@@ -1,45 +1,51 @@
-# Hanzi Browse — MCP Server
+# Hanzi Browse
 
-The MCP server exposes browser tools to MCP clients and forwards browser work to
-the Chrome extension over the local WebSocket relay.
+Give your AI agent a real browser — with your existing logins, cookies, and sessions.
 
-## Setup
+**Two ways to use it:**
+- **Use locally** — MCP server for Claude Code, Cursor, Codex, and other AI coding agents
+- **Build with it** — REST API + TypeScript SDK for embedding browser automation in your product
+
+## Quick Start (MCP)
 
 ```bash
-cd mcp-server
-npm install
-npm run build
+npx hanzi-browse setup
 ```
 
-Add to your MCP config (e.g., `~/.claude/claude_desktop_config.json`):
+This installs the Chrome extension and configures your AI agent. One command, done.
 
-```json
-{
-  "mcpServers": {
-    "browser": {
-      "command": "node",
-      "args": ["/path/to/hanzi-browse/mcp-server/dist/index.js"]
-    }
-  }
-}
+**Prerequisites:** Chrome must be open with the [Hanzi extension](https://chromewebstore.google.com/detail/hanzi-browse/iklpkemlmbhemkiojndpbhoakgikpmcd) installed.
+
+## Quick Start (API)
+
+```bash
+npm install @hanzi-browse/sdk
 ```
 
-**Prerequisites:** The Chrome extension must be installed and running. See the [main README](../README.md) for full setup.
+```typescript
+import { HanziClient } from '@hanzi-browse/sdk';
 
-## How It Works
+const client = new HanziClient({ apiKey: 'hic_live_...' });
 
-```text
-MCP client
-  -> mcp-server (stdio)
-  -> relay (WebSocket)
-  -> Chrome extension
-  -> browser agent
+// 1. Pair a browser — give the URL to your user
+const { pairingToken } = await client.createPairingToken();
+// User visits: https://api.hanzilla.co/pair/{pairingToken}
+
+// 2. Find their connected session
+const sessions = await client.listSessions();
+const browser = sessions.find(s => s.status === 'connected');
+
+// 3. Run a task (polls until complete)
+const result = await client.runTask({
+  browserSessionId: browser.id,
+  task: 'Go to example.com and read the page title',
+});
+console.log(result.answer);
 ```
 
-The extension is the browser executor. The MCP server should only manage MCP
-tool calls, local session bookkeeping, and blocking waits for completion.
+Full API docs: [browse.hanzilla.co/docs.html](https://browse.hanzilla.co/docs.html)
 
-## Tools
+## MCP Tools
 
 ### `browser_start`
 
@@ -55,7 +61,6 @@ browser_start(
 → {
   "session_id": "abc123",
   "status": "complete",
-  "task": "Search for flights to Tokyo...",
   "answer": "Found 3 flights: JAL $850, ANA $920, United $780",
   "total_steps": 8,
   "recent_steps": ["Opened Google Flights", "Set destination to Tokyo", ...]
@@ -64,7 +69,7 @@ browser_start(
 
 ### `browser_message`
 
-Send follow-up instructions to an existing session. Also blocks until the agent finishes.
+Send follow-up instructions to an existing session.
 
 ```
 browser_message(session_id: "abc123", message: "Book the cheapest one")
@@ -75,7 +80,7 @@ browser_message(session_id: "abc123", message: "Book the cheapest one")
 Check known sessions and their latest status.
 
 ```
-browser_status()                    // all active sessions
+browser_status()                     // all active sessions
 browser_status(session_id: "abc123") // specific session
 ```
 
@@ -85,7 +90,7 @@ Stop a task.
 
 ```
 browser_stop(session_id: "abc123")
-browser_stop(session_id: "abc123", remove: true)  // also delete session
+browser_stop(session_id: "abc123", remove: true)  // also close window
 ```
 
 ### `browser_screenshot`
@@ -98,84 +103,65 @@ browser_screenshot(session_id: "abc123")
 
 ## Examples
 
-**Research:**
-```
-browser_start("Find the top 3 competitors for Acme Corp and summarize their pricing")
-```
-
 **Logged-in workflows:**
 ```
-browser_start("Go to Jira, find my open tickets, and summarize what needs attention this week")
+browser_start("Go to Jira, find my open tickets, and summarize what needs attention")
 ```
 
 **Multi-turn:**
 ```
 s = browser_start("Go to LinkedIn and find AI Engineer jobs in Montreal")
-→ { session_id: "x1", answer: "Found: Applied AI Engineer at Cohere" }
-
-browser_message("x1", "Click into that job and tell me the requirements")
-→ { answer: "Requirements: 3+ years Python, ML experience..." }
-
-browser_message("x1", "Apply to this job using my profile")
-→ { answer: "Application submitted successfully" }
+browser_message(s.session_id, "Click into the Cohere job and tell me the requirements")
+browser_message(s.session_id, "Apply to this job using my profile")
 ```
 
 **Parallel execution:**
 ```
 browser_start("Check flight prices to Tokyo")
 browser_start("Check hotel prices in Shibuya")
-browser_start("Look up train pass costs")
-// All three run simultaneously
+// Both run simultaneously in separate windows
 ```
 
 ## Configuration
 
 | Environment Variable | Default | Description |
 |---|---|---|
-| `HANZI_IN_CHROME_MAX_SESSIONS` | `5` | Max concurrent browser tasks |
+| `HANZI_BROWSE_MAX_SESSIONS` | `5` | Max concurrent browser tasks |
+| `HANZI_BROWSE_TIMEOUT_MS` | `300000` | Task timeout (ms) |
 | `WS_RELAY_PORT` | `7862` | WebSocket relay port |
+| `POSTHOG_API_KEY` | unset | Enables PostHog analytics for local CLI telemetry, the dashboard build, the managed backend, and example apps |
+| `POSTHOG_HOST` | `https://us.i.posthog.com` | Override the PostHog host for all server-side capture calls and dashboard initialization |
 
-## Architecture
+## Skills
 
-```
-AI Tool (Claude Code, Cursor, etc.)
-    ↓ MCP Protocol (stdio)
-MCP Server
-    ↓ WebSocket
-Relay Server
-    ↓ WebSocket
-Chrome Extension
-    ↓ Extension agent loop
-Target Website
-```
-
-The relay server starts automatically when the MCP server connects. It routes
-messages between the MCP server and the Chrome extension and briefly queues
-messages while the extension service worker is asleep.
-
-> **Principle**: Hanzi is for real browser work in your signed-in Chrome.
-> Agents should prefer code, logs, APIs, and existing tools first. Use Hanzi when the job needs a real browser session.
-
-## Prompts
-
-The server exposes MCP prompts that clients auto-discover as slash commands:
+The server exposes MCP prompts that clients auto-discover:
 
 | Prompt | Description |
 |--------|-------------|
-| `linkedin-prospector` | Goal-driven LinkedIn outreach — networking, sales, partnerships, or hiring |
-| `e2e-tester` | Test your app in a real browser — reports bugs with screenshots and code references |
-| `social-poster` | Post across LinkedIn, Twitter, Reddit, HN — drafts per-platform, posts from your browser |
-
-In Claude Code, use the built-in `linkedin-prospector` prompt from the MCP prompt list.
-
-## Skills CLI
+| `linkedin-prospector` | Goal-driven LinkedIn outreach |
+| `e2e-tester` | Test your app in a real browser with screenshots |
+| `social-poster` | Post across LinkedIn, Twitter, Reddit from your browser |
+| `x-marketer` | Find X/Twitter conversations and draft voice-matched replies |
 
 ```bash
 hanzi-browser skills                              # list available skills
 hanzi-browser skills install linkedin-prospector   # install SKILL.md to your project
 ```
 
-Skills are portable SKILL.md files for agents that don't support MCP prompts (Cline, Codex). Each skill follows the same principle: use existing tools first, Hanzi only for real browser steps.
+## Architecture
+
+```
+AI Agent (Claude Code, Cursor, etc.)
+    ↓ MCP Protocol (stdio)
+MCP Server (this package)
+    ↓ WebSocket
+Chrome Extension
+    ↓ Chrome DevTools Protocol
+User's Real Browser
+```
+
+> **Principle**: Hanzi is for real browser work in your signed-in Chrome.
+> Agents should prefer code, logs, APIs, and existing tools first. Use Hanzi when the job needs a real browser session.
 
 ## License
 

package/dist/agent/domain-knowledge.d.ts

@@ -1,10 +1,11 @@
 /**
- * Domain-specific knowledge for the server-side agent loop.
- * Matches the extension's domain-skills.js but only includes domains
- * relevant to managed/API tasks.
+ * Domain-specific knowledge for the agent loop.
+ * Single source of truth — shared between server (managed API, MCP)
+ * and extension (via import at build time).
  */
 interface DomainEntry {
     domain: string;
+    antiBot?: boolean;
     skill: string;
 }
 /**
@@ -12,4 +13,8 @@ interface DomainEntry {
  * Returns the first matching entry, or null.
  */
 export declare function getDomainSkill(url: string): DomainEntry | null;
+/**
+ * Get all domain skills. Used by extension to import the full list.
+ */
+export declare function getAllDomainSkills(): DomainEntry[];
 export {};

package/dist/agent/domain-knowledge.js

@@ -1,51 +1,15 @@
 /**
- * Domain-specific knowledge for the server-side agent loop.
- * Matches the extension's domain-skills.js but only includes domains
- * relevant to managed/API tasks.
+ * Domain-specific knowledge for the agent loop.
+ * Single source of truth — shared between server (managed API, MCP)
+ * and extension (via import at build time).
  */
-const DOMAIN_KNOWLEDGE = [
-    {
-        domain: "x.com",
-        skill: `X/Twitter — verified patterns (updated 2026-03-30)
-
-## Reading pages (CRITICAL)
-- X loads content asynchronously — page looks empty for 3-5 seconds after navigation.
-- read_page often returns ONLY "To view keyboard shortcuts" — tweets haven't loaded yet.
-- DO NOT re-navigate to the same URL. That resets loading and makes it worse.
-- Instead: wait 5 seconds, then use get_page_text — it reads visible text and is more reliable.
-- If get_page_text returns nothing, scroll down once and try again.
-
-## Search
-- URL: x.com/search?q={encoded_query}&src=typed_query&f=live
-- After navigating, wait 5 seconds, then get_page_text (NOT read_page).
-- Scroll down once to load more tweets, then get_page_text again.
-- Tweet URLs in page text follow pattern: /status/{id}
-
-## Text input (CRITICAL — Draft.js)
-- form_input DOES NOT WORK — Draft.js ignores programmatic input.
-- computer type action GARBLES TEXT.
-- ONLY RELIABLE METHOD — use javascript_tool:
-  document.querySelector('[data-testid="tweetTextarea_0"]').focus();
-  document.execCommand('insertText', false, 'your reply text here');
-- Always verify text appeared by reading after insertion.
-
-## Replying to a tweet
-1. Navigate to tweet URL (x.com/{handle}/status/{id})
-2. Wait 3 seconds, read the page
-3. Click the reply/comment icon (speech bubble) in the action bar
-4. Use javascript_tool to insert text (see above)
-5. Verify text appeared, then click blue "Reply" button
-6. Wait 2 seconds to confirm reply posted
-
-## Known traps
-- DO NOT scroll looking for "Post your reply" — reply box appears after clicking comment icon
-- x.com/compose/post may open — that's fine, type and click Reply there
-- "Leave site?" dialog — ALWAYS click Cancel, finish posting first
-- Reply button is disabled until text is entered — verify first
-- Space replies 15+ seconds apart (rate limiting)
-- NEVER navigate to the same URL you're already on`,
-    },
-];
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+// Load from shared JSON file
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const DOMAIN_SKILLS = JSON.parse(readFileSync(join(__dirname, "domain-skills.json"), "utf-8"));
 /**
  * Look up domain knowledge for a URL.
  * Returns the first matching entry, or null.
@@ -53,11 +17,17 @@ const DOMAIN_KNOWLEDGE = [
 export function getDomainSkill(url) {
     try {
         const hostname = new URL(url).hostname.toLowerCase();
-        return DOMAIN_KNOWLEDGE.find((d) => hostname === d.domain || hostname.endsWith("." + d.domain)) || null;
+        return DOMAIN_SKILLS.find((d) => hostname === d.domain || hostname.endsWith("." + d.domain)) || null;
     }
     catch {
         // URL might not be a full URL — try matching as a bare domain
         const lower = url.toLowerCase();
-        return DOMAIN_KNOWLEDGE.find((d) => lower.includes(d.domain)) || null;
+        return DOMAIN_SKILLS.find((d) => lower.includes(d.domain)) || null;
     }
 }
+/**
+ * Get all domain skills. Used by extension to import the full list.
+ */
+export function getAllDomainSkills() {
+    return DOMAIN_SKILLS;
+}

package/dist/agent/domain-skills.json

@@ -0,0 +1,92 @@
+[
+  {
+    "domain": "mail.google.com",
+    "skill": "Gmail best practices:\n- To open an email, click directly on the email subject/preview text, NOT the checkbox or star\n- Use keyboard shortcuts: 'c' to compose, 'r' to reply, 'a' to reply all, 'f' to forward, 'e' to archive\n- To search, use the search bar at the top with operators like 'from:', 'to:', 'subject:', 'is:unread'\n- Reading pane may be on the right or below depending on user settings - check which layout is active\n- Verification codes are often in emails from 'noreply@' addresses with subjects containing 'verification', 'code', or 'confirm'"
+  },
+  {
+    "domain": "docs.google.com",
+    "skill": "Google Docs best practices:\n- This is a canvas-based application - use screenshots to see content, read_page may not capture all text\n- Use keyboard shortcuts: Cmd/Ctrl+B for bold, Cmd/Ctrl+I for italic, Cmd/Ctrl+K for links\n- To navigate, use Cmd/Ctrl+F to find text, then click on the result\n- For editing, click to place cursor then type - triple-click to select a paragraph\n- Access menus via the menu bar at the top (File, Edit, View, Insert, Format, etc.)"
+  },
+  {
+    "domain": "sheets.google.com",
+    "skill": "Google Sheets best practices:\n- Click on cells to select them, double-click to edit cell content\n- Use Tab to move right, Enter to move down, arrow keys to navigate\n- Formulas start with '=' - e.g., =SUM(A1:A10), =VLOOKUP(), =IF()\n- Use Cmd/Ctrl+C and Cmd/Ctrl+V for copy/paste\n- Select ranges by clicking and dragging, or Shift+click for range selection"
+  },
+  {
+    "domain": "github.com",
+    "skill": "GitHub best practices:\n- Repository navigation: Code tab for files, Issues for bug tracking, Pull requests for code review\n- To view a file, click on the filename in the file tree\n- Use 't' to open file finder, 'l' to jump to a line\n- In PRs: 'Files changed' tab shows diffs, 'Conversation' tab shows comments\n- Use the search bar with qualifiers: 'is:open is:pr', 'is:issue label:bug'"
+  },
+  {
+    "domain": "reddit.com",
+    "antiBot": true,
+    "skill": "Reddit UI patterns:\n- Posts are listed in a feed - click on post title to view full post and comments\n- Comments are nested/threaded - each comment has its own reply button underneath\n- Upvote (up arrow) and downvote (down arrow) buttons are to the left of each post/comment\n- To comment, scroll to comment box at top of comments section, or click reply under a specific comment\n- Use the search bar at top to find subreddits or posts\n- r/subredditname format for community names"
+  },
+  {
+    "domain": "linkedin.com",
+    "antiBot": true,
+    "skill": "LinkedIn UI patterns:\n\n## Messaging & Connections\n- To message someone: first check if you're connected (1st degree) - if not, send a connection request first\n- Connection request: go to their profile, click 'Connect' button, optionally add a note\n- Once connected, use the 'Message' button on their profile or go to Messaging tab\n- InMail (messaging non-connections) requires Premium subscription\n\n## Easy Apply Forms\n- Contact Info page is pre-filled from LinkedIn profile - don't try to modify, just click Next\n- Modal forms may need scrolling to see all content and buttons\n- Use screenshots over read_page for modals - accessibility tree often misses modal content\n\n## Navigation\n- Main tabs: Home (feed), My Network, Jobs, Messaging, Notifications\n- Job search: Jobs tab → filter by location, experience level, date posted\n- 'Easy Apply' = apply within LinkedIn; 'Apply' = external site\n- Profile sections are collapsible - click 'Show all' to expand"
+  },
+  {
+    "domain": "indeed.com",
+    "skill": "Indeed best practices:\n- Search for jobs using the 'What' and 'Where' fields at the top\n- Filter results by date posted, salary, job type, experience level\n- Click job title to view full description\n- 'Apply now' or 'Apply on company site' buttons are typically on the right panel\n- Sign in to save jobs and track applications"
+  },
+  {
+    "domain": "calendar.google.com",
+    "skill": "Google Calendar best practices:\n- Click on a time slot to create a new event\n- Drag events to reschedule them\n- Click on an event to view details, edit, or delete\n- Use the mini calendar on the left to navigate to different dates\n- Keyboard: 'c' to create event, 't' to go to today, arrow keys to navigate"
+  },
+  {
+    "domain": "drive.google.com",
+    "skill": "Google Drive best practices:\n- Double-click files to open them, single-click to select\n- Right-click for context menu (download, share, rename, etc.)\n- Use the search bar to find files by name or content\n- Create new items with the '+ New' button on the left\n- Drag and drop to move files between folders"
+  },
+  {
+    "domain": "notion.so",
+    "skill": "Notion best practices:\n- Click to place cursor, type '/' to open command menu\n- Drag blocks using the ⋮⋮ handle on the left\n- Use sidebar for navigation between pages\n- Toggle blocks expand/collapse on click\n- Databases can be viewed as table, board, calendar, etc."
+  },
+  {
+    "domain": "figma.com",
+    "skill": "Figma best practices:\n- This is a canvas-based design tool - always use screenshots to see content\n- Use 'V' for select tool, 'R' for rectangle, 'T' for text\n- Zoom with Cmd/Ctrl+scroll or Cmd/Ctrl++ and Cmd/Ctrl+-\n- Navigate frames in the left sidebar\n- Right-click for context menus and additional options"
+  },
+  {
+    "domain": "slack.com",
+    "skill": "Slack best practices:\n- Channels listed in left sidebar - click to switch\n- Cmd/Ctrl+K to quickly switch channels/DMs\n- @ mentions notify users, # references channels\n- Thread replies keep conversations organized\n- Use the search bar to find messages, files, and people"
+  },
+  {
+    "domain": "twitter.com",
+    "antiBot": true,
+    "skill": "See x.com — twitter.com redirects to x.com."
+  },
+  {
+    "domain": "x.com",
+    "antiBot": true,
+    "skill": "X/Twitter — verified patterns (updated 2026-03-30)\n\n## Reading pages (CRITICAL)\n- X loads content asynchronously — page looks empty for 3-5 seconds after navigation.\n- read_page often returns ONLY \"To view keyboard shortcuts\" — tweets haven't loaded yet.\n- DO NOT re-navigate to the same URL. That resets loading and makes it worse.\n- Instead: wait 5 seconds, then use get_page_text — it reads visible text and is more reliable.\n- If get_page_text returns nothing, scroll down once and try again.\n\n## Search\n- URL: x.com/search?q={encoded_query}&src=typed_query&f=live\n- After navigating, wait 5 seconds, then get_page_text (NOT read_page).\n- Scroll down once to load more tweets, then get_page_text again.\n- Tweet URLs in page text follow pattern: /status/{id}\n\n## Text input (CRITICAL — Draft.js)\n- form_input DOES NOT WORK — Draft.js ignores programmatic input.\n- computer type action GARBLES TEXT.\n- ONLY RELIABLE METHOD — use javascript_tool:\n  document.querySelector('[data-testid=\"tweetTextarea_0\"]').focus();\n  document.execCommand('insertText', false, 'your reply text here');\n- Always verify text appeared by reading after insertion.\n\n## Replying to a tweet\n1. Navigate to tweet URL (x.com/{handle}/status/{id})\n2. Wait 3 seconds, read the page\n3. Click the reply/comment icon (speech bubble) in the action bar\n4. Use javascript_tool to insert text (see above)\n5. Verify text appeared, then click blue \"Reply\" button\n6. Wait 2 seconds to confirm reply posted\n\n## Known traps\n- DO NOT scroll looking for \"Post your reply\" — reply box appears after clicking comment icon\n- x.com/compose/post may open — that's fine, type and click Reply there\n- \"Leave site?\" dialog — ALWAYS click Cancel, finish posting first\n- Reply button is disabled until text is entered — verify first\n- Space replies 15+ seconds apart (rate limiting)\n- NEVER navigate to the same URL you're already on"
+  },
+  {
+    "domain": "amazon.com",
+    "skill": "Amazon UI patterns:\n- Prefer the top search bar or a direct search URL for product discovery\n- The first fold may be dominated by sponsored modules or Amazon brand carousels before standard results\n- Result cards can show total price, unit price, ratings, delivery promises, variation links, and inline Add to Cart buttons all at once\n- Watch carefully for subtle labels such as 'Sponsored' or 'Featured from Amazon brands'\n- Location/shipping prompts can change delivery wording and result context, so verify destination-sensitive text before extracting prices"
+  },
+  {
+    "domain": "ebay.com",
+    "skill": "eBay UI patterns:\n- Search results usually show title, condition, price, shipping, and location directly on the card\n- Headline price is often incomplete until you also check shipping cost, coupon text, and 'Best Offer' language\n- Sponsored placements and featured carousels can interrupt the organic result list\n- Use condition and shipping origin early to filter out weak matches\n- Be cautious with range prices and urgency labels like 'Last one' or watcher counts; they do not guarantee a clean fixed-price purchase path"
+  },
+  {
+    "domain": "walmart.ca",
+    "antiBot": true,
+    "skill": "Walmart.ca UI patterns:\n- Search results often expose enough information to compare products before opening a product page\n- Cards commonly include brand, title, price, ratings, fulfillment messaging, and promo details such as Subscribe to Save or pickup thresholds\n- Walmart.com may first present a storefront or region-selection step and later a human-verification blocker ('Press & Hold' challenge); validation was more reliable on Walmart.ca\n- On Walmart.ca product pages, verify one-time price separately from Subscribe to Save pricing and check pickup, express delivery, and standard delivery messages individually\n- Treat promo labels, fulfillment thresholds, and returns messaging as separate signals and verify them individually\n- If you hit a 'Press & Hold' or 'verify you are human' challenge, STOP and tell the user — never attempt to bypass"
+  },
+  {
+    "domain": "target.com",
+    "skill": "Target UI patterns:\n- Result cards usually include title, review count, price, promo messaging, and a persistent Add to Cart button\n- Price formatting can mix ranges, sale pricing, regular pricing, and per-unit math, so read the full price block carefully\n- Promo text such as Target gift card offers or 'Highly rated' badges appears frequently and can distract from the base price\n- Fulfillment filters are easy to see near the top, but card-level availability may still need a deeper click\n- Search results can include adjacent-category items, so confirm the exact product type from the title before acting"
+  },
+  {
+    "domain": "zillow.com",
+    "antiBot": true,
+    "skill": "Zillow UI patterns (rentals):\n- Sign in first for full contact info and saved searches; anonymous users see degraded data\n- Use 'For Rent' in the top nav, then refine by price, beds, and 'Move-in Date'\n- Results have a split map + list view — switch to list view for cleaner data extraction\n- Listing cards include price, beds/baths, address, and 'Apply' or 'Request a tour' buttons\n- 'Request a tour' and 'Contact' buttons submit forms — draft the message and wait for explicit user approval before clicking submit\n- Never enter SSN, payment info, or background check data without confirming the user is on an official Zillow Application flow\n- Zillow frequently serves a CAPTCHA / 'Press & Hold' challenge for automated traffic — if you hit one, STOP and tell the user, do not bypass"
+  },
+  {
+    "domain": "apartments.com",
+    "skill": "Apartments.com UI patterns:\n- Top filter bar: location, price, beds, move-in date, amenities — apply them before reading results\n- Listing cards include price range, beds/baths, address, and a 'Send Message' or 'Contact' button\n- Many listings have a built-in multi-step application flow — each step is clearly labeled; stop before 'Submit Application' and confirm with the user\n- 'Send Message' opens an inline form — draft the message, show it to the user, wait for approval before submitting\n- Pricing is often shown as a range ($X-$Y) because individual units vary; click into the listing for per-unit prices\n- Response times for large property managers are usually fast (hours); individual landlords slower\n- Do not enter SSN, credit-card, or bank info without explicit user confirmation that they want to proceed with a real application"
+  },
+  {
+    "domain": "craigslist.org",
+    "skill": "Craigslist UI patterns (apartments / housing):\n- URL pattern: https://[city].craigslist.org/search/apa?minAsk={min}&maxAsk={max}&bedrooms={n}\n- Sort by 'newest' to avoid stale listings — older listings are frequently scams or already rented\n- Listings may or may not have photos; listings without photos are higher risk, flag them\n- Contact is always via an anonymized email relay — no built-in application flow\n- Scam flags to warn the user about: price >25% below market, 'owner overseas', 'send deposit to hold', asks to text/WhatsApp before viewing, generic stock photos\n- Never follow links off craigslist for a 'verified listings site' — those are almost always phishing\n- Show the user any inquiry message before sending, and wait for explicit approval"
+  }
+]

package/dist/agent/system-prompt.js

@@ -13,9 +13,13 @@ export function buildSystemPrompt(taskUrl) {
     const blocks = [
         {
             type: "text",
-            text: `You are a web automation assistant with browser tools. Your priority is to complete the user's request efficiently and autonomously.
+            text: `You are Hanzi Browse, a browsing sub-agent driving the user's own Chrome browser — with all their logins, cookies, and sessions already in place. A host agent (Claude Code, Cursor, Codex, etc.) has delegated a task to you. Your job is to complete that task autonomously using the browser tools below, and return a concise answer.
 
-Browser tasks often require long-running, agentic capabilities. When you encounter a user request that feels time-consuming or extensive in scope, you should be persistent and use all available context needed to accomplish the task. The user expects you to work autonomously until the task is complete. Do not ask for permission - just do it.
+You are NOT a step-by-step executor reading a script. You are an agent. You decide what to click, what to type, what to wait for, and when you're done. The host agent gave you a goal in natural language; figure out the steps yourself and complete the goal.
+
+When the host agent sends you a follow-up via browser_message, it's course-correcting or refining the task — treat it as the latest instruction from the user and continue from the current browser state.
+
+You are persistent. Long or multi-step tasks are expected. The host agent expects you to work until the task is complete. Do not ask for permission — just do it.
 
 <behavior_instructions>
 The current date is ${dateStr}, ${timeStr}.

package/dist/cli/setup.d.ts

@@ -10,6 +10,8 @@ interface AgentConfig {
     method: 'json-merge' | 'cli-command';
     detect: () => boolean;
     configPath?: () => string;
+    configSection?: 'mcpServers' | 'servers' | 'context_servers';
+    legacyConfigSections?: ('mcpServers' | 'servers' | 'context_servers')[];
     cliCommand?: string;
     skillsDir?: () => string;
 }
@@ -22,6 +24,7 @@ interface AgentRegistryDeps {
     home?: string;
     plat?: NodeJS.Platform;
     appData?: string;
+    xdgConfigHome?: string;
     pathExists?: (path: string) => boolean;
     runCommand?: (command: string, options?: any) => Buffer | string;
 }
@@ -41,6 +44,7 @@ interface BrowserDetectionDeps {
 }
 export declare function getAgentRegistry(deps?: AgentRegistryDeps): AgentConfig[];
 export declare function mergeJsonConfig(configPath: string, deps?: JsonConfigDeps): SetupResult;
+export declare function mergeJsonConfigAtKey(configPath: string, configSection: 'mcpServers' | 'servers' | 'context_servers', deps?: JsonConfigDeps, legacyConfigSections?: ('mcpServers' | 'servers' | 'context_servers')[]): SetupResult;
 interface BrowserInfo {
     name: string;
     slug: string;
@@ -57,5 +61,7 @@ export declare function buildSystemOpenCommand(url: string, plat: NodeJS.Platfor
 export declare function runSetup(options?: {
     only?: string;
     yes?: boolean;
+    all?: boolean;
+    skills?: string[];
 }): Promise<void>;
 export {};