hanzi-browse 2.3.0 → 2.3.1

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

@@ -0,0 +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.
+ */
+interface DomainEntry {
+    domain: string;
+    skill: string;
+}
+/**
+ * Look up domain knowledge for a URL.
+ * Returns the first matching entry, or null.
+ */
+export declare function getDomainSkill(url: string): DomainEntry | null;
+export {};

package/dist/agent/domain-knowledge.js

@@ -0,0 +1,63 @@
+/**
+ * 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.
+ */
+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`,
+    },
+];
+/**
+ * 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_KNOWLEDGE.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;
+    }
+}

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 {};

package/dist/cli/setup.js

@@ -65,12 +65,15 @@ const MCP_ENTRY = {
     args: ['-y', 'hanzi-browse'],
 };
 // ── Agent registry ─────────────────────────────────────────────────────
-function getAgentRegistry() {
-    const home = homedir();
-    const plat = platform();
+export function getAgentRegistry(deps = {}) {
+    const home = deps.home ?? homedir();
+    const plat = deps.plat ?? platform();
+    const appData = deps.appData ?? process.env.APPDATA ?? join(home, 'AppData', 'Roaming');
+    const pathExists = deps.pathExists ?? existsSync;
+    const runCommand = deps.runCommand ?? execSync;
     const hasCli = (bin) => {
         try {
-            execSync(`which ${bin}`, { stdio: 'ignore' });
+            runCommand(`which ${bin}`, { stdio: 'ignore' });
             return true;
         }
         catch {
@@ -94,7 +97,7 @@ function getAgentRegistry() {
             method: 'json-merge',
             configPath: () => join(home, '.cursor', 'mcp.json'),
             skillsDir: () => join(home, '.cursor', 'skills'),
-            detect: () => existsSync(join(home, '.cursor')),
+            detect: () => pathExists(join(home, '.cursor')),
         },
         {
             name: 'Windsurf',
@@ -102,7 +105,7 @@ function getAgentRegistry() {
             method: 'json-merge',
             configPath: () => join(home, '.codeium', 'windsurf', 'mcp_config.json'),
             skillsDir: () => join(home, '.codeium', 'windsurf', 'skills'),
-            detect: () => existsSync(join(home, '.codeium', 'windsurf')),
+            detect: () => pathExists(join(home, '.codeium', 'windsurf')),
         },
         {
             name: 'VS Code',
@@ -110,7 +113,7 @@ function getAgentRegistry() {
             method: 'json-merge',
             configPath: () => join(home, '.vscode', 'mcp.json'),
             skillsDir: () => join(home, '.vscode', 'skills'),
-            detect: () => existsSync(join(home, '.vscode')),
+            detect: () => pathExists(join(home, '.vscode')),
         },
         {
             name: 'Codex',
@@ -118,7 +121,7 @@ function getAgentRegistry() {
             method: 'json-merge',
             configPath: () => join(home, '.codex', 'mcp.json'),
             skillsDir: () => join(home, '.agents', 'skills'),
-            detect: () => existsSync(join(home, '.codex')) || hasCli('codex'),
+            detect: () => pathExists(join(home, '.codex')) || hasCli('codex'),
         },
         {
             name: 'Claude Desktop',
@@ -128,15 +131,15 @@ function getAgentRegistry() {
                 if (plat === 'darwin')
                     return join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
                 if (plat === 'win32')
-                    return join(process.env.APPDATA || join(home, 'AppData', 'Roaming'), 'Claude', 'claude_desktop_config.json');
+                    return join(appData, 'Claude', 'claude_desktop_config.json');
                 return join(home, '.config', 'Claude', 'claude_desktop_config.json');
             },
             detect: () => {
                 if (plat === 'darwin')
-                    return existsSync(join(home, 'Library', 'Application Support', 'Claude'));
+                    return pathExists(join(home, 'Library', 'Application Support', 'Claude'));
                 if (plat === 'win32')
-                    return existsSync(join(process.env.APPDATA || join(home, 'AppData', 'Roaming'), 'Claude'));
-                return existsSync(join(home, '.config', 'Claude'));
+                    return pathExists(join(appData, 'Claude'));
+                return pathExists(join(home, '.config', 'Claude'));
             },
         },
         {
@@ -145,7 +148,7 @@ function getAgentRegistry() {
             method: 'json-merge',
             configPath: () => join(home, '.gemini', 'settings.json'),
             skillsDir: () => join(home, '.gemini', 'skills'),
-            detect: () => existsSync(join(home, '.gemini')) || hasCli('gemini'),
+            detect: () => pathExists(join(home, '.gemini')) || hasCli('gemini'),
         },
         {
             name: 'Amp',
@@ -153,21 +156,21 @@ function getAgentRegistry() {
             method: 'json-merge',
             configPath: () => join(home, '.amp', 'mcp.json'),
             skillsDir: () => join(home, '.amp', 'skills'),
-            detect: () => existsSync(join(home, '.amp')),
+            detect: () => pathExists(join(home, '.amp')),
         },
         {
             name: 'Cline',
             slug: 'cline',
             method: 'json-merge',
             configPath: () => join(home, '.cline', 'mcp_settings.json'),
-            detect: () => existsSync(join(home, '.cline')),
+            detect: () => pathExists(join(home, '.cline')),
         },
         {
             name: 'Roo Code',
             slug: 'roo-code',
             method: 'json-merge',
             configPath: () => join(home, '.roo-code', 'mcp_settings.json'),
-            detect: () => existsSync(join(home, '.roo-code')),
+            detect: () => pathExists(join(home, '.roo-code')),
         },
     ];
 }
@@ -177,16 +180,21 @@ function stripJsonComments(text) {
         .replace(/\/\/.*$/gm, '')
         .replace(/\/\*[\s\S]*?\*\//g, '');
 }
-function mergeJsonConfig(configPath) {
+export function mergeJsonConfig(configPath, deps = {}) {
     const agentName = configPath;
+    const pathExists = deps.pathExists ?? existsSync;
+    const readTextFile = deps.readTextFile ?? readFileSync;
+    const writeTextFile = deps.writeTextFile ?? writeFileSync;
+    const ensureDir = deps.ensureDir ?? mkdirSync;
+    const copyFile = deps.copyFile ?? copyFileSync;
     try {
-        if (!existsSync(configPath)) {
-            mkdirSync(join(configPath, '..'), { recursive: true });
+        if (!pathExists(configPath)) {
+            ensureDir(join(configPath, '..'), { recursive: true });
             const config = { mcpServers: { "hanzi-browser": MCP_ENTRY } };
-            writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+            writeTextFile(configPath, JSON.stringify(config, null, 2) + '\n');
             return { agent: agentName, status: 'configured', detail: `created ${configPath}` };
         }
-        const raw = readFileSync(configPath, 'utf-8');
+        const raw = readTextFile(configPath, 'utf-8');
         let config;
         try {
             config = JSON.parse(raw);
@@ -197,9 +205,9 @@ function mergeJsonConfig(configPath) {
             }
             catch {
                 const bakPath = configPath + '.bak';
-                copyFileSync(configPath, bakPath);
+                copyFile(configPath, bakPath);
                 config = { mcpServers: { "hanzi-browser": MCP_ENTRY } };
-                writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+                writeTextFile(configPath, JSON.stringify(config, null, 2) + '\n');
                 return { agent: agentName, status: 'configured', detail: `backed up malformed config to ${bakPath}` };
             }
         }
@@ -212,7 +220,7 @@ function mergeJsonConfig(configPath) {
         if (!config.mcpServers)
             config.mcpServers = {};
         config.mcpServers["hanzi-browser"] = MCP_ENTRY;
-        writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+        writeTextFile(configPath, JSON.stringify(config, null, 2) + '\n');
         return { agent: agentName, status: 'configured', detail: `merged into ${configPath}` };
     }
     catch (err) {
@@ -245,20 +253,67 @@ function runClaudeCodeSetup() {
 // ── Browser detection ──────────────────────────────────────────────────
 const EXTENSION_URL = 'https://chromewebstore.google.com/detail/hanzi-browse/iklpkemlmbhemkiojndpbhoakgikpmcd';
 const BROWSERS = [
-    { name: 'Google Chrome', slug: 'chrome', macApp: 'Google Chrome', linuxBin: 'google-chrome' },
-    { name: 'Brave', slug: 'brave', macApp: 'Brave Browser', linuxBin: 'brave-browser' },
-    { name: 'Microsoft Edge', slug: 'edge', macApp: 'Microsoft Edge', linuxBin: 'microsoft-edge' },
-    { name: 'Arc', slug: 'arc', macApp: 'Arc', linuxBin: 'arc' },
-    { name: 'Chromium', slug: 'chromium', macApp: 'Chromium', linuxBin: 'chromium-browser' },
+    {
+        name: 'Google Chrome',
+        slug: 'chrome',
+        macApp: 'Google Chrome',
+        linuxBin: 'google-chrome',
+        winPaths: [
+            'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+            'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+        ],
+    },
+    {
+        name: 'Brave',
+        slug: 'brave',
+        macApp: 'Brave Browser',
+        linuxBin: 'brave-browser',
+        winPaths: [
+            'C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe',
+            'C:\\Program Files (x86)\\BraveSoftware\\Brave-Browser\\Application\\brave.exe',
+        ],
+    },
+    {
+        name: 'Microsoft Edge',
+        slug: 'edge',
+        macApp: 'Microsoft Edge',
+        linuxBin: 'microsoft-edge',
+        winPaths: [
+            'C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe',
+            'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+        ],
+    },
+    {
+        name: 'Arc',
+        slug: 'arc',
+        macApp: 'Arc',
+        linuxBin: 'arc',
+        winPaths: [],
+    },
+    {
+        name: 'Chromium',
+        slug: 'chromium',
+        macApp: 'Chromium',
+        linuxBin: 'chromium-browser',
+        winPaths: [
+            'C:\\Program Files\\Chromium\\Application\\chrome.exe',
+            'C:\\Program Files (x86)\\Chromium\\Application\\chrome.exe',
+        ],
+    },
 ];
-function detectBrowsers() {
-    const plat = platform();
+export function detectBrowsers(deps = {}) {
+    const plat = deps.plat ?? platform();
+    const pathExists = deps.pathExists ?? existsSync;
+    const runCommand = deps.runCommand ?? execSync;
     return BROWSERS.filter(b => {
         if (plat === 'darwin') {
-            return existsSync(`/Applications/${b.macApp}.app`);
+            return pathExists(`/Applications/${b.macApp}.app`);
+        }
+        if (plat === 'win32') {
+            return b.winPaths.some(path => pathExists(path));
         }
         try {
-            execSync(`which ${b.linuxBin}`, { stdio: 'ignore' });
+            runCommand(`which ${b.linuxBin}`, { stdio: 'ignore' });
             return true;
         }
         catch {
@@ -266,19 +321,36 @@ function detectBrowsers() {
         }
     });
 }
+export function resolveInteractiveMode(options = {}, stdinIsTTY = process.stdin.isTTY ?? false) {
+    return options.yes ? false : stdinIsTTY;
+}
+export function buildBrowserOpenCommand(browser, url, plat) {
+    if (plat === 'darwin') {
+        return `open -a "${browser.macApp}" "${url}"`;
+    }
+    if (plat === 'win32') {
+        const exePath = browser.winPaths.find(path => existsSync(path)) ?? browser.winPaths[0];
+        if (!exePath)
+            return `cmd /c start "" "${url}"`;
+        return `cmd /c start "" "${exePath}" "${url}"`;
+    }
+    return `${browser.linuxBin} "${url}" &`;
+}
+export function buildSystemOpenCommand(url, plat) {
+    if (plat === 'darwin')
+        return `open "${url}"`;
+    if (plat === 'win32')
+        return `cmd /c start "" "${url}"`;
+    return `xdg-open "${url}"`;
+}
 function openInBrowser(browser, url) {
     const plat = platform();
     try {
-        if (plat === 'darwin') {
-            execSync(`open -a "${browser.macApp}" "${url}"`, { stdio: 'ignore' });
-        }
-        else {
-            execSync(`${browser.linuxBin} "${url}" &`, { stdio: 'ignore' });
-        }
+        execSync(buildBrowserOpenCommand(browser, url, plat), { stdio: 'ignore' });
     }
     catch {
         // Fallback: system default
-        execSync(`open "${url}" 2>/dev/null || xdg-open "${url}" 2>/dev/null`, { stdio: 'ignore' });
+        execSync(buildSystemOpenCommand(url, plat), { stdio: 'ignore' });
     }
 }
 async function ensureExtension(isInteractive) {
@@ -700,7 +772,7 @@ export async function runSetup(options = {}) {
     trackEvent("setup_started");
     const registry = getAgentRegistry();
     const only = options.only;
-    const interactive = options.yes ? false : (process.stdin.isTTY ?? false);
+    const interactive = resolveInteractiveMode(options);
     // ── Banner ──
     if (interactive) {
         console.log(BANNER);