hanzi-browse 2.2.0

package/dist/ipc/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * IPC Module - Communication with Chrome Extension
+ *
+ * WebSocketClient is the primary transport for MCP traffic.
+ * NativeHostConnection is retained only for legacy utility flows.
+ */
+export { WebSocketClient, type WebSocketClientOptions } from './websocket-client.js';
+export { NativeHostConnection, type NativeMessage, type MessageHandler, type ConnectionOptions, type OutgoingMessageType, type IncomingMessageType, } from './native-host.js';

package/dist/ipc/index.js

@@ -0,0 +1,8 @@
+/**
+ * IPC Module - Communication with Chrome Extension
+ *
+ * WebSocketClient is the primary transport for MCP traffic.
+ * NativeHostConnection is retained only for legacy utility flows.
+ */
+export { WebSocketClient } from './websocket-client.js';
+export { NativeHostConnection, } from './native-host.js';

package/dist/ipc/native-host.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Native Host IPC Module
+ *
+ * Handles communication with the installed native host via Chrome native
+ * messaging protocol.
+ *
+ * Protocol: Chrome Native Messaging (4-byte little-endian length prefix + JSON)
+ *
+ * This transport is no longer used for MCP task delivery. It remains for
+ * native-host-backed utilities such as credential reads, debug logging, and
+ * API proxy support.
+ */
+/** Message types sent TO the native host */
+export type OutgoingMessageType = 'ping' | 'debug_log' | 'agent_log' | 'check_file' | 'read_cli_credentials' | 'read_codex_credentials' | 'proxy_api_call';
+/** Message types received FROM the native host */
+export type IncomingMessageType = 'pong' | 'debug_logged' | 'file_check_result' | 'cli_credentials' | 'codex_credentials' | 'credentials_not_found' | 'api_response' | 'api_error' | 'error';
+/** Base message structure */
+export interface NativeMessage {
+    type: string;
+    sessionId?: string;
+    requestId?: string;
+    [key: string]: any;
+}
+/** Callback for handling incoming messages */
+export type MessageHandler = (message: NativeMessage) => void | Promise<void>;
+/** Connection options */
+export interface ConnectionOptions {
+    /** Custom path to native host executable */
+    hostPath?: string;
+    /** Callback when connection is lost */
+    onDisconnect?: (code: number | null) => void;
+    /** Callback for native host stderr output */
+    onStderr?: (data: string) => void;
+}
+/**
+ * Manages a connection to the native host process.
+ *
+ * Usage:
+ *   const conn = new NativeHostConnection();
+ *   conn.onMessage((msg) => console.log('Received:', msg));
+ *   await conn.connect();
+ *   await conn.send({ type: 'ping' });
+ */
+export declare class NativeHostConnection {
+    private process;
+    private messageBuffer;
+    private messageHandlers;
+    private options;
+    private connected;
+    constructor(options?: ConnectionOptions);
+    /**
+     * Find the native host executable path from the installed Chrome manifest
+     */
+    private findHostPath;
+    /**
+     * Register a handler for incoming messages
+     */
+    onMessage(handler: MessageHandler): void;
+    /**
+     * Remove a message handler
+     */
+    offMessage(handler: MessageHandler): void;
+    /**
+     * Connect to the native host process
+     */
+    connect(): Promise<void>;
+    /**
+     * Process buffered messages using the native messaging protocol
+     * (4-byte little-endian length prefix + JSON payload)
+     */
+    private processMessages;
+    /**
+     * Dispatch a message to all registered handlers
+     */
+    private dispatchMessage;
+    /**
+     * Send a message to the native host
+     */
+    send(message: NativeMessage): Promise<void>;
+    /**
+     * Check if connected to native host
+     */
+    isConnected(): boolean;
+    /**
+     * Disconnect from the native host
+     */
+    disconnect(): void;
+}
+/**
+ * Get the default native host connection (creates one if needed)
+ */
+export declare function getDefaultConnection(): NativeHostConnection;
+/**
+ * Reset the default connection (useful for testing)
+ */
+export declare function resetDefaultConnection(): void;

package/dist/ipc/native-host.js

@@ -0,0 +1,223 @@
+/**
+ * Native Host IPC Module
+ *
+ * Handles communication with the installed native host via Chrome native
+ * messaging protocol.
+ *
+ * Protocol: Chrome Native Messaging (4-byte little-endian length prefix + JSON)
+ *
+ * This transport is no longer used for MCP task delivery. It remains for
+ * native-host-backed utilities such as credential reads, debug logging, and
+ * API proxy support.
+ */
+import { spawn } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+// ============================================================================
+// Native Host Connection Class
+// ============================================================================
+/**
+ * Manages a connection to the native host process.
+ *
+ * Usage:
+ *   const conn = new NativeHostConnection();
+ *   conn.onMessage((msg) => console.log('Received:', msg));
+ *   await conn.connect();
+ *   await conn.send({ type: 'ping' });
+ */
+export class NativeHostConnection {
+    process = null;
+    messageBuffer = Buffer.alloc(0);
+    messageHandlers = [];
+    options;
+    connected = false;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /**
+     * Find the native host executable path from the installed Chrome manifest
+     */
+    findHostPath() {
+        // Check user-provided path first
+        if (this.options.hostPath && existsSync(this.options.hostPath)) {
+            return this.options.hostPath;
+        }
+        // Look for Chrome native messaging manifest
+        const manifestPath = join(homedir(), 'Library', 'Application Support', 'Google', 'Chrome', 'NativeMessagingHosts', 'com.hanzi_browse.oauth_host.json');
+        if (existsSync(manifestPath)) {
+            try {
+                const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+                if (manifest.path && existsSync(manifest.path)) {
+                    return manifest.path;
+                }
+            }
+            catch {
+                // Fall through to error
+            }
+        }
+        throw new Error('Native host not found. Please install the Chrome extension first.\n' +
+            'Expected manifest at: ' + manifestPath);
+    }
+    /**
+     * Register a handler for incoming messages
+     */
+    onMessage(handler) {
+        this.messageHandlers.push(handler);
+    }
+    /**
+     * Remove a message handler
+     */
+    offMessage(handler) {
+        const index = this.messageHandlers.indexOf(handler);
+        if (index !== -1) {
+            this.messageHandlers.splice(index, 1);
+        }
+    }
+    /**
+     * Connect to the native host process
+     */
+    async connect() {
+        if (this.connected && this.process?.stdin?.writable) {
+            return; // Already connected
+        }
+        const hostPath = this.findHostPath();
+        console.error(`[NativeHost] Connecting to: ${hostPath}`);
+        return new Promise((resolve, reject) => {
+            try {
+                this.process = spawn(hostPath, [], {
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+                this.process.stdout?.on('data', (chunk) => {
+                    this.messageBuffer = Buffer.concat([this.messageBuffer, chunk]);
+                    this.processMessages();
+                });
+                this.process.stderr?.on('data', (data) => {
+                    const text = data.toString().trim();
+                    if (this.options.onStderr) {
+                        this.options.onStderr(text);
+                    }
+                    else {
+                        console.error(`[NativeHost] ${text}`);
+                    }
+                });
+                this.process.on('error', (err) => {
+                    console.error('[NativeHost] Process error:', err.message);
+                    this.connected = false;
+                    reject(err);
+                });
+                this.process.on('close', (code) => {
+                    console.error(`[NativeHost] Process exited with code: ${code}`);
+                    this.connected = false;
+                    this.process = null;
+                    if (this.options.onDisconnect) {
+                        this.options.onDisconnect(code);
+                    }
+                });
+                this.connected = true;
+                // Give the process a moment to initialize
+                setTimeout(() => resolve(), 100);
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+    }
+    /**
+     * Process buffered messages using the native messaging protocol
+     * (4-byte little-endian length prefix + JSON payload)
+     */
+    processMessages() {
+        while (this.messageBuffer.length >= 4) {
+            const msgLen = this.messageBuffer.readUInt32LE(0);
+            if (this.messageBuffer.length < 4 + msgLen) {
+                break; // Wait for more data
+            }
+            const msgStr = this.messageBuffer.subarray(4, 4 + msgLen).toString();
+            this.messageBuffer = this.messageBuffer.subarray(4 + msgLen);
+            try {
+                const message = JSON.parse(msgStr);
+                this.dispatchMessage(message);
+            }
+            catch (e) {
+                console.error('[NativeHost] Failed to parse message:', e);
+                console.error('[NativeHost] Raw message (first 200 chars):', msgStr.substring(0, 200));
+            }
+        }
+    }
+    /**
+     * Dispatch a message to all registered handlers
+     */
+    async dispatchMessage(message) {
+        for (const handler of this.messageHandlers) {
+            try {
+                await handler(message);
+            }
+            catch (err) {
+                console.error('[NativeHost] Handler error:', err);
+            }
+        }
+    }
+    /**
+     * Send a message to the native host
+     */
+    async send(message) {
+        if (!this.process?.stdin?.writable) {
+            await this.connect();
+        }
+        const json = JSON.stringify(message);
+        const buffer = Buffer.from(json);
+        const len = Buffer.alloc(4);
+        len.writeUInt32LE(buffer.length, 0);
+        try {
+            this.process.stdin.write(len);
+            this.process.stdin.write(buffer);
+        }
+        catch (err) {
+            console.error('[NativeHost] Send failed:', err.message);
+            this.connected = false;
+            this.process = null;
+            throw new Error(`Failed to send message: ${err.message}`);
+        }
+    }
+    /**
+     * Check if connected to native host
+     */
+    isConnected() {
+        return this.connected && !!this.process?.stdin?.writable;
+    }
+    /**
+     * Disconnect from the native host
+     */
+    disconnect() {
+        if (this.process) {
+            this.process.kill();
+            this.process = null;
+        }
+        this.connected = false;
+        this.messageBuffer = Buffer.alloc(0);
+    }
+}
+// ============================================================================
+// Convenience Functions
+// ============================================================================
+/** Singleton instance for simple usage */
+let defaultConnection = null;
+/**
+ * Get the default native host connection (creates one if needed)
+ */
+export function getDefaultConnection() {
+    if (!defaultConnection) {
+        defaultConnection = new NativeHostConnection();
+    }
+    return defaultConnection;
+}
+/**
+ * Reset the default connection (useful for testing)
+ */
+export function resetDefaultConnection() {
+    if (defaultConnection) {
+        defaultConnection.disconnect();
+        defaultConnection = null;
+    }
+}

package/dist/ipc/websocket-client.d.ts

@@ -0,0 +1,73 @@
+/**
+ * WebSocket Client for Relay Communication
+ *
+ * Drop-in replacement for NativeHostConnection that communicates
+ * via the WebSocket relay server instead of native messaging.
+ *
+ * Same interface: connect(), send(), onMessage(), isConnected(), disconnect()
+ */
+import type { NativeMessage, MessageHandler, ConnectionOptions } from './native-host.js';
+type ClientRole = 'mcp' | 'cli';
+export interface WebSocketClientOptions extends ConnectionOptions {
+    /** Role to register as with the relay */
+    role: ClientRole;
+    /** Custom relay URL (defaults to ws://localhost:7862) */
+    relayUrl?: string;
+    /** Auto-start relay server if not running (default: true) */
+    autoStartRelay?: boolean;
+    /** Extra fields to include in the register message (e.g., relay_secret) */
+    registerExtra?: Record<string, string>;
+}
+/**
+ * WebSocket-based connection to the Chrome extension via relay server.
+ *
+ * Usage:
+ *   const client = new WebSocketClient({ role: 'mcp' });
+ *   client.onMessage((msg) => console.log('Received:', msg));
+ *   await client.connect();
+ *   await client.send({ type: 'mcp_start_task', sessionId: 'abc', task: '...' });
+ */
+export declare class WebSocketClient {
+    private ws;
+    private messageHandlers;
+    private options;
+    private connected;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private maxReconnectDelay;
+    constructor(options: WebSocketClientOptions);
+    /**
+     * Register a handler for incoming messages
+     */
+    onMessage(handler: MessageHandler): void;
+    /**
+     * Remove a message handler
+     */
+    offMessage(handler: MessageHandler): void;
+    /**
+     * Connect to the relay server.
+     * Auto-starts the relay if needed.
+     */
+    connect(): Promise<void>;
+    /**
+     * Dispatch a message to all registered handlers
+     */
+    private dispatchMessage;
+    /**
+     * Send a message to the extension via relay
+     */
+    send(message: NativeMessage): Promise<void>;
+    /**
+     * Check if connected to relay
+     */
+    isConnected(): boolean;
+    /**
+     * Disconnect from relay
+     */
+    disconnect(): void;
+    /**
+     * Schedule a reconnection attempt with exponential backoff
+     */
+    private scheduleReconnect;
+}
+export {};

package/dist/ipc/websocket-client.js

@@ -0,0 +1,199 @@
+/**
+ * WebSocket Client for Relay Communication
+ *
+ * Drop-in replacement for NativeHostConnection that communicates
+ * via the WebSocket relay server instead of native messaging.
+ *
+ * Same interface: connect(), send(), onMessage(), isConnected(), disconnect()
+ */
+import WebSocket from 'ws';
+import { ensureRelayRunning, getRelayUrl } from '../relay/auto-start.js';
+/**
+ * WebSocket-based connection to the Chrome extension via relay server.
+ *
+ * Usage:
+ *   const client = new WebSocketClient({ role: 'mcp' });
+ *   client.onMessage((msg) => console.log('Received:', msg));
+ *   await client.connect();
+ *   await client.send({ type: 'mcp_start_task', sessionId: 'abc', task: '...' });
+ */
+export class WebSocketClient {
+    ws = null;
+    messageHandlers = [];
+    options;
+    connected = false;
+    reconnectTimer = null;
+    reconnectAttempts = 0;
+    maxReconnectDelay = 30000; // Max 30 second backoff
+    constructor(options) {
+        this.options = {
+            autoStartRelay: true,
+            ...options,
+        };
+    }
+    /**
+     * Register a handler for incoming messages
+     */
+    onMessage(handler) {
+        this.messageHandlers.push(handler);
+    }
+    /**
+     * Remove a message handler
+     */
+    offMessage(handler) {
+        const index = this.messageHandlers.indexOf(handler);
+        if (index !== -1) {
+            this.messageHandlers.splice(index, 1);
+        }
+    }
+    /**
+     * Connect to the relay server.
+     * Auto-starts the relay if needed.
+     */
+    async connect() {
+        if (this.connected && this.ws?.readyState === WebSocket.OPEN) {
+            return; // Already connected
+        }
+        const relayUrl = this.options.relayUrl || getRelayUrl();
+        // Auto-start relay if configured
+        if (this.options.autoStartRelay) {
+            try {
+                await ensureRelayRunning(relayUrl);
+            }
+            catch (err) {
+                console.error(`[WSClient] Failed to start relay: ${err.message}`);
+                throw err;
+            }
+        }
+        return new Promise((resolve, reject) => {
+            try {
+                console.error(`[WSClient] Connecting to relay: ${relayUrl}`);
+                this.ws = new WebSocket(relayUrl);
+                const connectTimeout = setTimeout(() => {
+                    if (!this.connected) {
+                        this.ws?.terminate();
+                        reject(new Error('WebSocket connection timed out'));
+                    }
+                }, 5000);
+                this.ws.on('open', () => {
+                    clearTimeout(connectTimeout);
+                    this.connected = true;
+                    this.reconnectAttempts = 0;
+                    // Register with relay
+                    this.ws.send(JSON.stringify({
+                        type: 'register',
+                        role: this.options.role,
+                        ...this.options.registerExtra,
+                    }));
+                    console.error(`[WSClient] Connected as ${this.options.role}`);
+                    resolve();
+                });
+                this.ws.on('message', (data) => {
+                    try {
+                        const message = JSON.parse(data.toString());
+                        // Skip relay protocol messages
+                        if (message.type === 'registered')
+                            return;
+                        if (message.type === 'error') {
+                            console.error(`[WSClient] Relay error: ${message.error}`);
+                            return;
+                        }
+                        this.dispatchMessage(message);
+                    }
+                    catch (e) {
+                        console.error('[WSClient] Failed to parse message:', e);
+                    }
+                });
+                this.ws.on('close', () => {
+                    console.error('[WSClient] Disconnected from relay');
+                    this.connected = false;
+                    this.ws = null;
+                    if (this.options.onDisconnect) {
+                        this.options.onDisconnect(null);
+                    }
+                    // Schedule reconnect with exponential backoff
+                    this.scheduleReconnect();
+                });
+                this.ws.on('error', (err) => {
+                    clearTimeout(connectTimeout);
+                    console.error(`[WSClient] WebSocket error: ${err.message}`);
+                    if (!this.connected) {
+                        reject(err);
+                    }
+                });
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+    }
+    /**
+     * Dispatch a message to all registered handlers
+     */
+    async dispatchMessage(message) {
+        for (const handler of this.messageHandlers) {
+            try {
+                await handler(message);
+            }
+            catch (err) {
+                console.error('[WSClient] Handler error:', err);
+            }
+        }
+    }
+    /**
+     * Send a message to the extension via relay
+     */
+    async send(message) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            // Try to reconnect
+            try {
+                await this.connect();
+            }
+            catch {
+                throw new Error('Not connected to relay and reconnection failed');
+            }
+        }
+        this.ws.send(JSON.stringify(message));
+    }
+    /**
+     * Check if connected to relay
+     */
+    isConnected() {
+        return this.connected && this.ws?.readyState === WebSocket.OPEN;
+    }
+    /**
+     * Disconnect from relay
+     */
+    disconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+        this.connected = false;
+    }
+    /**
+     * Schedule a reconnection attempt with exponential backoff
+     */
+    scheduleReconnect() {
+        if (this.reconnectTimer)
+            return;
+        const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), this.maxReconnectDelay);
+        this.reconnectAttempts++;
+        console.error(`[WSClient] Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})`);
+        this.reconnectTimer = setTimeout(async () => {
+            this.reconnectTimer = null;
+            try {
+                await this.connect();
+                console.error('[WSClient] Reconnected successfully');
+            }
+            catch (err) {
+                console.error(`[WSClient] Reconnection failed: ${err.message}`);
+                // onclose handler will schedule next attempt
+            }
+        }, delay);
+    }
+}

package/dist/license/manager.d.ts

@@ -0,0 +1,20 @@
+/**
+ * License Manager for MCP Server (BYOM mode)
+ *
+ * BYOM is free and unlimited — no license check needed.
+ * Managed mode uses the per-task credit system in api.ts instead.
+ *
+ * This file is kept for backwards compatibility (index.ts imports it)
+ * but always returns "allowed".
+ */
+export declare function checkAndIncrementUsage(): Promise<{
+    allowed: boolean;
+    remaining: number | null;
+    message: string;
+}>;
+export declare function getLicenseStatus(): {
+    isPro: boolean;
+    tasksUsed: number;
+    taskLimit: number | null;
+    message: string;
+};

package/dist/license/manager.js

@@ -0,0 +1,15 @@
+/**
+ * License Manager for MCP Server (BYOM mode)
+ *
+ * BYOM is free and unlimited — no license check needed.
+ * Managed mode uses the per-task credit system in api.ts instead.
+ *
+ * This file is kept for backwards compatibility (index.ts imports it)
+ * but always returns "allowed".
+ */
+export async function checkAndIncrementUsage() {
+    return { allowed: true, remaining: null, message: "BYOM — unlimited tasks" };
+}
+export function getLicenseStatus() {
+    return { isPro: true, tasksUsed: 0, taskLimit: null, message: "BYOM — Free, unlimited" };
+}