hanzi-browse 2.3.0 → 2.3.2

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/browser-agent
 ```
 
-**Prerequisites:** The Chrome extension must be installed and running. See the [main README](../README.md) for full setup.
+```typescript
+import { HanziClient } from '@hanzi/browser-agent';
 
-## 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,63 @@ 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 |
 
-## 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

@@ -0,0 +1,20 @@
+/**
+ * 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;
+}
+/**
+ * Look up domain knowledge for a URL.
+ * 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

@@ -0,0 +1,33 @@
+/**
+ * Domain-specific knowledge for the agent loop.
+ * Single source of truth — shared between server (managed API, MCP)
+ * and extension (via import at build time).
+ */
+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.
+ */
+export function getDomainSkill(url) {
+    try {
+        const hostname = new URL(url).hostname.toLowerCase();
+        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_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,66 @@
+[
+  {
+    "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 best practices:\n- Use the search bar at the top for product search\n- Filter results using the left sidebar (price, ratings, Prime, etc.)\n- Click 'Add to Cart' or 'Buy Now' to purchase\n- Product details and reviews are on the product page\n- Check seller information and shipping times before purchasing"
+  }
+]

package/dist/agent/loop.d.ts

@@ -48,6 +48,16 @@ export interface StepUpdate {
     toolInput?: Record<string, any>;
     text?: string;
 }
+export interface TurnLog {
+    step: number;
+    tools: Array<{
+        name: string;
+        input: Record<string, any>;
+        result: string;
+        durationMs: number;
+    }>;
+    ai_response: string | null;
+}
 export interface AgentLoopResult {
     status: "complete" | "error" | "max_steps";
     answer: string;
@@ -59,5 +69,7 @@ export interface AgentLoopResult {
     };
     /** The model used for the last LLM call (for billing attribution) */
     model?: string;
+    /** Structured turn-by-turn log of the agent's actions */
+    turns?: TurnLog[];
 }
 export declare function runAgentLoop(params: AgentLoopParams): Promise<AgentLoopResult>;

package/dist/agent/loop.js

@@ -19,9 +19,12 @@ import { buildSystemPrompt } from "./system-prompt.js";
 // --- Agent Loop ---
 export async function runAgentLoop(params) {
     const { task, url, context, executeTool, onStep, onText, maxSteps = 50, signal, } = params;
-    const system = buildSystemPrompt();
+    // Detect target URL for domain knowledge — from explicit url param or from task text
+    const targetUrl = url || task.match(/https?:\/\/[^\s"')]+/)?.[0];
+    const system = buildSystemPrompt(targetUrl);
     const tools = AGENT_TOOLS;
     const messages = [];
+    const turns = [];
     let totalUsage = { inputTokens: 0, outputTokens: 0, apiCalls: 0 };
     let lastModel;
     // Build initial user message
@@ -41,6 +44,7 @@ export async function runAgentLoop(params) {
                 steps: step - 1,
                 usage: totalUsage,
                 model: lastModel,
+                turns,
             };
         }
         onStep?.({ step, status: "thinking" });
@@ -63,6 +67,7 @@ export async function runAgentLoop(params) {
                 steps: step,
                 usage: totalUsage,
                 model: lastModel,
+                turns,
             };
         }
         totalUsage.apiCalls++;
@@ -79,9 +84,17 @@ export async function runAgentLoop(params) {
         // Extract text and tool calls
         const textBlocks = response.content.filter((b) => b.type === "text");
         const toolUseBlocks = response.content.filter((b) => b.type === "tool_use");
+        // Start building the turn log for this step
+        const currentTurn = {
+            step,
+            tools: [],
+            ai_response: textBlocks.map((b) => b.text).join("\n").trim() || null,
+        };
         // If no tool calls, we're done
         if (response.stop_reason === "end_turn" || toolUseBlocks.length === 0) {
             const answer = textBlocks.map((b) => b.text).join("\n").trim();
+            turns.push(currentTurn);
+            console.error(`[AgentLoop] Complete at step ${step} (${totalUsage.apiCalls} API calls, ${totalUsage.inputTokens} input tokens)`);
             onStep?.({ step, status: "complete", text: answer });
             return {
                 status: "complete",
@@ -89,6 +102,7 @@ export async function runAgentLoop(params) {
                 steps: step,
                 usage: totalUsage,
                 model: lastModel,
+                turns,
             };
         }
         // Execute each tool call
@@ -105,6 +119,12 @@ export async function runAgentLoop(params) {
                 });
                 continue;
             }
+            // Log tool call
+            const inputSummary = toolUse.name === "navigate" ? toolUse.input.url
+                : toolUse.name === "computer" ? `${toolUse.input.action}${toolUse.input.ref ? ` ref=${toolUse.input.ref}` : ""}${toolUse.input.coordinate ? ` @${toolUse.input.coordinate}` : ""}`
+                    : toolUse.name === "javascript_tool" ? toolUse.input.text?.slice(0, 80)
+                        : JSON.stringify(toolUse.input).slice(0, 80);
+            console.error(`[AgentLoop] Step ${step}: ${toolUse.name}(${inputSummary})`);
             onStep?.({
                 step,
                 status: "tool_use",
@@ -112,6 +132,7 @@ export async function runAgentLoop(params) {
                 toolInput: toolUse.input,
             });
             let result;
+            const toolStartMs = Date.now();
             try {
                 result = await executeTool(toolUse.name, toolUse.input);
             }
@@ -133,15 +154,32 @@ export async function runAgentLoop(params) {
                     result = { success: false, error: err.message };
                 }
             }
+            // Log result summary
+            const toolDurationMs = Date.now() - toolStartMs;
+            const resultText = result.error ? `Error: ${result.error}`
+                : typeof result.output === "string" ? result.output
+                    : JSON.stringify(result.output);
+            const resultSummary = resultText.length > 120 ? resultText.slice(0, 120) + "..." : resultText;
+            console.error(`[AgentLoop] Step ${step}: ${toolUse.name} → ${resultSummary}`);
+            // Add to structured turn log (truncate large results to keep log manageable)
+            currentTurn.tools.push({
+                name: toolUse.name,
+                input: toolUse.input,
+                result: (resultText.length > 5000 ? resultText.slice(0, 5000) + "... [truncated]" : resultText)
+                    + (result.screenshot ? " [+screenshot]" : ""),
+                durationMs: toolDurationMs,
+            });
             onStep?.({ step, status: "tool_result", toolName: toolUse.name });
             // Check abort after each tool — don't feed results back to LLM if cancelled
             if (signal?.aborted) {
+                turns.push(currentTurn);
                 return {
                     status: "error",
                     answer: "Task was cancelled.",
                     steps: step,
                     usage: totalUsage,
                     model: lastModel,
+                    turns,
                 };
             }
             // Build tool result content block
@@ -172,6 +210,7 @@ export async function runAgentLoop(params) {
         }
         // Add tool results as user message
         messages.push({ role: "user", content: toolResults });
+        turns.push(currentTurn);
     }
     // Exceeded max steps
     const lastText = messages
@@ -186,5 +225,6 @@ export async function runAgentLoop(params) {
         steps: maxSteps,
         usage: totalUsage,
         model: lastModel,
+        turns,
     };
 }

package/dist/agent/system-prompt.d.ts

@@ -1,7 +1,7 @@
 /**
  * System prompt for server-side managed agent loop.
  */
-export declare function buildSystemPrompt(): Array<{
+export declare function buildSystemPrompt(taskUrl?: string): Array<{
     type: "text";
     text: string;
 }>;

package/dist/agent/system-prompt.js

@@ -1,7 +1,8 @@
 /**
  * System prompt for server-side managed agent loop.
  */
-export function buildSystemPrompt() {
+import { getDomainSkill } from "./domain-knowledge.js";
+export function buildSystemPrompt(taskUrl) {
     const now = new Date();
     const dateStr = now.toLocaleDateString("en-US", {
         month: "numeric",
@@ -9,7 +10,7 @@ export function buildSystemPrompt() {
         year: "numeric",
     });
     const timeStr = now.toLocaleTimeString("en-US");
-    return [
+    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.
@@ -38,4 +39,13 @@ When a page shows only a loading spinner, use the computer tool with action "wai
 </tool_usage_requirements>`,
         },
     ];
+    // Inject domain-specific knowledge if the task targets a known site
+    const domainSkill = taskUrl ? getDomainSkill(taskUrl) : null;
+    if (domainSkill) {
+        blocks.push({
+            type: "text",
+            text: `<domain_knowledge domain="${domainSkill.domain}">\n${domainSkill.skill}\n</domain_knowledge>`,
+        });
+    }
+    return blocks;
 }

package/dist/cli/json-output.d.ts

@@ -0,0 +1,21 @@
+import type { SessionFileStatus } from './session-files.js';
+export declare function buildTaskCompletePayload(sessionId: string, result: unknown): {
+    session_id: string;
+    status: string;
+    result: unknown;
+};
+export declare function buildTaskErrorPayload(sessionId: string, error: string): {
+    session_id: string;
+    status: string;
+    error: string;
+};
+export declare function buildStatusPayload(status: SessionFileStatus | SessionFileStatus[]): SessionFileStatus | SessionFileStatus[];
+export declare function buildStopPayload(sessionId: string, remove?: boolean): {
+    session_id: string;
+    status: string;
+    removed: boolean;
+};
+export declare function buildScreenshotPayload(sessionId: string, screenshotPath: string): {
+    session_id: string;
+    screenshot_path: string;
+};

package/dist/cli/json-output.js

@@ -0,0 +1,30 @@
+export function buildTaskCompletePayload(sessionId, result) {
+    return {
+        session_id: sessionId,
+        status: 'completed',
+        result,
+    };
+}
+export function buildTaskErrorPayload(sessionId, error) {
+    return {
+        session_id: sessionId,
+        status: 'error',
+        error,
+    };
+}
+export function buildStatusPayload(status) {
+    return status;
+}
+export function buildStopPayload(sessionId, remove = false) {
+    return {
+        session_id: sessionId,
+        status: 'stopped',
+        removed: remove,
+    };
+}
+export function buildScreenshotPayload(sessionId, screenshotPath) {
+    return {
+        session_id: sessionId,
+        screenshot_path: screenshotPath,
+    };
+}

package/dist/cli/setup.d.ts

@@ -4,7 +4,58 @@
  * Scans the machine for Claude Code, Cursor, Windsurf, and Claude Desktop,
  * then merges the Hanzi MCP server entry into each agent's config file.
  */
+interface AgentConfig {
+    name: string;
+    slug: string;
+    method: 'json-merge' | 'cli-command';
+    detect: () => boolean;
+    configPath?: () => string;
+    cliCommand?: string;
+    skillsDir?: () => string;
+}
+interface SetupResult {
+    agent: string;
+    status: 'configured' | 'already-configured' | 'skipped' | 'error';
+    detail: string;
+}
+interface AgentRegistryDeps {
+    home?: string;
+    plat?: NodeJS.Platform;
+    appData?: string;
+    pathExists?: (path: string) => boolean;
+    runCommand?: (command: string, options?: any) => Buffer | string;
+}
+interface JsonConfigDeps {
+    pathExists?: (path: string) => boolean;
+    readTextFile?: (path: string, encoding: BufferEncoding) => string;
+    writeTextFile?: (path: string, contents: string) => void;
+    ensureDir?: (path: string, options: {
+        recursive: boolean;
+    }) => void;
+    copyFile?: (source: string, destination: string) => void;
+}
+interface BrowserDetectionDeps {
+    plat?: NodeJS.Platform;
+    pathExists?: (path: string) => boolean;
+    runCommand?: (command: string, options?: any) => Buffer | string;
+}
+export declare function getAgentRegistry(deps?: AgentRegistryDeps): AgentConfig[];
+export declare function mergeJsonConfig(configPath: string, deps?: JsonConfigDeps): SetupResult;
+interface BrowserInfo {
+    name: string;
+    slug: string;
+    macApp: string;
+    linuxBin: string;
+    winPaths: string[];
+}
+export declare function detectBrowsers(deps?: BrowserDetectionDeps): BrowserInfo[];
+export declare function resolveInteractiveMode(options?: {
+    yes?: boolean;
+}, stdinIsTTY?: boolean): boolean;
+export declare function buildBrowserOpenCommand(browser: BrowserInfo, url: string, plat: NodeJS.Platform): string;
+export declare function buildSystemOpenCommand(url: string, plat: NodeJS.Platform): string;
 export declare function runSetup(options?: {
     only?: string;
     yes?: boolean;
 }): Promise<void>;
+export {};