hanzi-browse 2.2.0

package/dist/llm/client.d.ts

@@ -0,0 +1,72 @@
+/**
+ * LLM Client for MCP Server
+ *
+ * Routes between providers:
+ * - Vertex AI (Gemini) — managed mode, server-side agent loop
+ * - Anthropic — legacy local mode, Claude Code OAuth
+ *
+ * Canonical internal format is Anthropic content blocks.
+ * Vertex provider converts at the API boundary.
+ */
+export interface ContentBlockText {
+    type: "text";
+    text: string;
+}
+export interface ContentBlockImage {
+    type: "image";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    };
+}
+export interface ContentBlockToolUse {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, any>;
+}
+export interface ContentBlockToolResult {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string | Array<ContentBlockText | ContentBlockImage>;
+}
+export type ContentBlock = ContentBlockText | ContentBlockImage | ContentBlockToolUse | ContentBlockToolResult;
+export interface Message {
+    role: "user" | "assistant";
+    content: string | ContentBlock[];
+}
+export interface Tool {
+    name: string;
+    description: string;
+    input_schema: Record<string, any>;
+}
+export interface LLMResponse {
+    content: ContentBlock[];
+    stop_reason: string;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+    /** The model that produced this response (for billing attribution) */
+    model?: string;
+}
+export interface CallLLMParams {
+    messages: Message[];
+    system: ContentBlockText[];
+    tools: Tool[];
+    model?: string;
+    maxTokens?: number;
+    signal?: AbortSignal;
+    onText?: (chunk: string) => void;
+}
+/**
+ * Call the LLM. Routes to Vertex AI (Gemini) if configured, otherwise Anthropic.
+ *
+ * Handles streaming, auto-refresh on 401, and credential resolution.
+ */
+export declare function callLLM(params: CallLLMParams): Promise<LLMResponse>;
+/**
+ * Reset cached credentials (e.g., after manual credential update).
+ */
+export declare function resetCredentialCache(): void;

package/dist/llm/client.js

@@ -0,0 +1,227 @@
+/**
+ * LLM Client for MCP Server
+ *
+ * Routes between providers:
+ * - Vertex AI (Gemini) — managed mode, server-side agent loop
+ * - Anthropic — legacy local mode, Claude Code OAuth
+ *
+ * Canonical internal format is Anthropic content blocks.
+ * Vertex provider converts at the API boundary.
+ */
+import { resolveCredentials, refreshClaudeToken, saveClaudeCredentials, } from "./credentials.js";
+import { callVertexLLM, isVertexConfigured } from "./vertex.js";
+const ANTHROPIC_API_URL = "https://api.anthropic.com/v1/messages";
+const DEFAULT_MODEL = "claude-haiku-4-5-20251001";
+const DEFAULT_MAX_TOKENS = 16384;
+// Cached credential source — refreshed on 401
+let cachedSource = null;
+function getSource() {
+    if (!cachedSource) {
+        cachedSource = resolveCredentials();
+    }
+    if (!cachedSource) {
+        throw new Error("No credentials found. Set ANTHROPIC_API_KEY or run `claude login`");
+    }
+    return cachedSource;
+}
+/**
+ * Build request headers based on credential type.
+ */
+function buildHeaders(source) {
+    if (source.type === "api_key") {
+        return {
+            "Content-Type": "application/json",
+            "x-api-key": source.apiKey,
+            "anthropic-version": "2023-06-01",
+        };
+    }
+    if (source.type === "claude_oauth") {
+        return {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${source.credentials.accessToken}`,
+            "anthropic-version": "2023-06-01",
+            "anthropic-dangerous-direct-browser-access": "true",
+            "anthropic-beta": "claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14",
+            "x-app": "cli",
+            "user-agent": "claude-code/2.1.29 (Darwin; arm64)",
+        };
+    }
+    throw new Error("Codex credentials are not supported for direct LLM calls from MCP server");
+}
+/**
+ * Parse SSE stream and extract the final response.
+ */
+async function parseSSEStream(response, onText, signal) {
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    // Accumulate content blocks from streaming events
+    const contentBlocks = [];
+    let currentBlockIndex = -1;
+    let stopReason = "";
+    let usage = { input_tokens: 0, output_tokens: 0 };
+    try {
+        while (true) {
+            if (signal?.aborted) {
+                reader.cancel();
+                throw new DOMException("Aborted", "AbortError");
+            }
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split("\n");
+            buffer = lines.pop();
+            for (const line of lines) {
+                if (!line.startsWith("data: "))
+                    continue;
+                const data = line.slice(6);
+                if (data === "[DONE]")
+                    continue;
+                let event;
+                try {
+                    event = JSON.parse(data);
+                }
+                catch {
+                    continue;
+                }
+                switch (event.type) {
+                    case "content_block_start":
+                        currentBlockIndex = event.index;
+                        if (event.content_block.type === "tool_use") {
+                            contentBlocks[currentBlockIndex] = {
+                                type: "tool_use",
+                                id: event.content_block.id,
+                                name: event.content_block.name,
+                                input: {},
+                            };
+                        }
+                        else if (event.content_block.type === "text") {
+                            contentBlocks[currentBlockIndex] = {
+                                type: "text",
+                                text: "",
+                            };
+                        }
+                        break;
+                    case "content_block_delta":
+                        if (event.delta.type === "text_delta") {
+                            const block = contentBlocks[event.index];
+                            if (block) {
+                                block.text += event.delta.text;
+                                onText?.(event.delta.text);
+                            }
+                        }
+                        else if (event.delta.type === "input_json_delta") {
+                            // Accumulate JSON string for tool input — parse on content_block_stop
+                            const block = contentBlocks[event.index];
+                            if (block) {
+                                block._rawInput = (block._rawInput || "") + event.delta.partial_json;
+                            }
+                        }
+                        break;
+                    case "content_block_stop": {
+                        const block = contentBlocks[event.index];
+                        if (block?.type === "tool_use") {
+                            if (block._rawInput) {
+                                try {
+                                    block.input = JSON.parse(block._rawInput);
+                                }
+                                catch {
+                                    block.input = {};
+                                }
+                            }
+                            delete block._rawInput;
+                        }
+                        break;
+                    }
+                    case "message_delta":
+                        if (event.delta.stop_reason) {
+                            stopReason = event.delta.stop_reason;
+                        }
+                        if (event.usage) {
+                            usage.output_tokens = event.usage.output_tokens || usage.output_tokens;
+                        }
+                        break;
+                    case "message_start":
+                        if (event.message?.usage) {
+                            usage.input_tokens = event.message.usage.input_tokens || 0;
+                        }
+                        break;
+                }
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    // Safety: strip any leftover _rawInput from tool_use blocks
+    for (const block of contentBlocks) {
+        if (block._rawInput !== undefined) {
+            delete block._rawInput;
+        }
+    }
+    return { content: contentBlocks, stop_reason: stopReason, usage };
+}
+/**
+ * Call the LLM. Routes to Vertex AI (Gemini) if configured, otherwise Anthropic.
+ *
+ * Handles streaming, auto-refresh on 401, and credential resolution.
+ */
+export async function callLLM(params) {
+    // Route to Vertex AI if configured
+    if (isVertexConfigured()) {
+        return callVertexLLM(params);
+    }
+    const { messages, system, tools, model = DEFAULT_MODEL, maxTokens = DEFAULT_MAX_TOKENS, signal, onText, } = params;
+    const source = getSource();
+    const headers = buildHeaders(source);
+    const body = JSON.stringify({
+        model,
+        max_tokens: maxTokens,
+        system,
+        messages,
+        tools: tools.length > 0 ? tools : undefined,
+        stream: true,
+    });
+    let response = await fetch(ANTHROPIC_API_URL, {
+        method: "POST",
+        headers,
+        body,
+        signal,
+    });
+    // Auto-refresh on 401/403 for OAuth credentials
+    if ((response.status === 401 || response.status === 403) &&
+        source.type === "claude_oauth" &&
+        source.credentials.refreshToken) {
+        console.error("[LLM] Got 401/403, refreshing OAuth token...");
+        try {
+            const newCreds = await refreshClaudeToken(source.credentials.refreshToken);
+            saveClaudeCredentials(newCreds);
+            // Update cached source
+            cachedSource = { type: "claude_oauth", credentials: newCreds };
+            const newHeaders = buildHeaders(cachedSource);
+            response = await fetch(ANTHROPIC_API_URL, {
+                method: "POST",
+                headers: newHeaders,
+                body,
+                signal,
+            });
+        }
+        catch (refreshErr) {
+            throw new Error(`Token refresh failed: ${refreshErr.message}`);
+        }
+    }
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => "");
+        throw new Error(`Anthropic API error ${response.status}: ${errorText.slice(0, 300)}`);
+    }
+    const result = await parseSSEStream(response, onText, signal);
+    result.model = model;
+    return result;
+}
+/**
+ * Reset cached credentials (e.g., after manual credential update).
+ */
+export function resetCredentialCache() {
+    cachedSource = null;
+}

package/dist/llm/credentials.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Credential Reader for MCP Server
+ *
+ * Reads Claude/Codex credentials directly from the user's machine,
+ * eliminating the need for the native host bridge in MCP mode.
+ *
+ * Resolution order:
+ * 1. ANTHROPIC_API_KEY env var → direct API key auth
+ * 2. ~/.claude/.credentials.json → Claude Code OAuth tokens
+ * 3. macOS Keychain "Claude Code-credentials" → Claude Code OAuth tokens
+ * 4. ~/.codex/auth.json → Codex/OpenAI tokens
+ */
+export interface ClaudeCredentials {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+}
+export interface CodexCredentials {
+    accessToken: string;
+    refreshToken: string;
+    accountId: string;
+}
+export type CredentialSource = {
+    type: "api_key";
+    apiKey: string;
+} | {
+    type: "claude_oauth";
+    credentials: ClaudeCredentials;
+} | {
+    type: "codex_oauth";
+    credentials: CodexCredentials;
+};
+/**
+ * Read Claude Code OAuth credentials from ~/.claude/.credentials.json
+ */
+export declare function getClaudeCredentials(): ClaudeCredentials | null;
+/**
+ * Read Claude Code credentials from macOS Keychain
+ */
+export declare function getClaudeKeychainCredentials(): ClaudeCredentials | null;
+/**
+ * Read Codex CLI credentials from ~/.codex/auth.json
+ */
+export declare function getCodexCredentials(): CodexCredentials | null;
+/**
+ * Save refreshed Claude credentials back to ~/.claude/.credentials.json
+ */
+export declare function saveClaudeCredentials(newCreds: ClaudeCredentials): boolean;
+/**
+ * Refresh Claude OAuth token using refresh token
+ */
+export declare function refreshClaudeToken(refreshToken: string): Promise<ClaudeCredentials>;
+/**
+ * Resolve credentials in priority order.
+ * Returns the first valid credential source found.
+ */
+export declare function resolveCredentials(): CredentialSource | null;
+/**
+ * Get a human-readable description of the credential source found.
+ */
+export declare function describeCredentials(): string;

package/dist/llm/credentials.js

@@ -0,0 +1,200 @@
+/**
+ * Credential Reader for MCP Server
+ *
+ * Reads Claude/Codex credentials directly from the user's machine,
+ * eliminating the need for the native host bridge in MCP mode.
+ *
+ * Resolution order:
+ * 1. ANTHROPIC_API_KEY env var → direct API key auth
+ * 2. ~/.claude/.credentials.json → Claude Code OAuth tokens
+ * 3. macOS Keychain "Claude Code-credentials" → Claude Code OAuth tokens
+ * 4. ~/.codex/auth.json → Codex/OpenAI tokens
+ */
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { execSync } from "child_process";
+// OAuth configuration (same as native-bridge.cjs)
+const OAUTH_CONFIG = {
+    tokenUrl: "https://console.anthropic.com/v1/oauth/token",
+    clientId: "9d1c250a-e61b-44d9-88ed-5944d1962f5e",
+};
+/**
+ * Read Claude Code OAuth credentials from ~/.claude/.credentials.json
+ */
+export function getClaudeCredentials() {
+    const credPath = path.join(os.homedir(), ".claude", ".credentials.json");
+    if (!fs.existsSync(credPath))
+        return null;
+    try {
+        const content = fs.readFileSync(credPath, "utf8");
+        const creds = JSON.parse(content);
+        if (creds.claudeAiOauth?.accessToken) {
+            return creds.claudeAiOauth;
+        }
+    }
+    catch {
+        // File unreadable or invalid JSON
+    }
+    return null;
+}
+/**
+ * Read Claude Code credentials from macOS Keychain
+ */
+export function getClaudeKeychainCredentials() {
+    if (process.platform !== "darwin")
+        return null;
+    try {
+        const result = execSync('security find-generic-password -s "Claude Code-credentials" -w', { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+        if (result?.trim()) {
+            const creds = JSON.parse(result.trim());
+            if (creds.claudeAiOauth?.accessToken) {
+                return creds.claudeAiOauth;
+            }
+        }
+    }
+    catch {
+        // Keychain entry not found or not on macOS
+    }
+    return null;
+}
+/**
+ * Read Codex CLI credentials from ~/.codex/auth.json
+ */
+export function getCodexCredentials() {
+    const credPath = path.join(os.homedir(), ".codex", "auth.json");
+    if (!fs.existsSync(credPath))
+        return null;
+    try {
+        const content = fs.readFileSync(credPath, "utf8");
+        const creds = JSON.parse(content);
+        if (creds.tokens?.access_token) {
+            return {
+                accessToken: creds.tokens.access_token,
+                refreshToken: creds.tokens.refresh_token,
+                accountId: creds.tokens.account_id,
+            };
+        }
+    }
+    catch {
+        // File unreadable or invalid JSON
+    }
+    return null;
+}
+/**
+ * Save refreshed Claude credentials back to ~/.claude/.credentials.json
+ */
+export function saveClaudeCredentials(newCreds) {
+    const credPath = path.join(os.homedir(), ".claude", ".credentials.json");
+    try {
+        let existingData = {};
+        if (fs.existsSync(credPath)) {
+            existingData = JSON.parse(fs.readFileSync(credPath, "utf8"));
+        }
+        existingData.claudeAiOauth = {
+            ...existingData.claudeAiOauth,
+            accessToken: newCreds.accessToken,
+            refreshToken: newCreds.refreshToken || existingData.claudeAiOauth?.refreshToken,
+            expiresAt: newCreds.expiresAt,
+        };
+        fs.writeFileSync(credPath, JSON.stringify(existingData, null, 2));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Refresh Claude OAuth token using refresh token
+ */
+export async function refreshClaudeToken(refreshToken) {
+    const body = JSON.stringify({
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+        client_id: OAUTH_CONFIG.clientId,
+    });
+    const response = await fetch(OAUTH_CONFIG.tokenUrl, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Content-Length": String(Buffer.byteLength(body)),
+        },
+        body,
+    });
+    if (response.ok) {
+        const data = await response.json();
+        const expiresAt = Date.now() + data.expires_in * 1000;
+        return {
+            accessToken: data.access_token,
+            refreshToken: data.refresh_token || refreshToken,
+            expiresAt,
+        };
+    }
+    // Parse error for actionable message
+    let errorMessage = `Token refresh failed (${response.status})`;
+    try {
+        const errorData = await response.json();
+        const oauthError = errorData.error || errorData.error_code;
+        switch (oauthError) {
+            case "invalid_grant":
+                errorMessage = "Refresh token expired or revoked. Run: claude login";
+                break;
+            case "invalid_client":
+                errorMessage = "OAuth client configuration error.";
+                break;
+            default:
+                errorMessage = errorData.error_description || `OAuth error: ${oauthError || response.status}`;
+        }
+    }
+    catch {
+        if (response.status === 400)
+            errorMessage = "Refresh token invalid. Run: claude login";
+        else if (response.status >= 500)
+            errorMessage = "Anthropic API error. Try again later.";
+    }
+    throw new Error(errorMessage);
+}
+/**
+ * Resolve credentials in priority order.
+ * Returns the first valid credential source found.
+ */
+export function resolveCredentials() {
+    // 1. ANTHROPIC_API_KEY env var
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (apiKey) {
+        return { type: "api_key", apiKey };
+    }
+    // 2. Claude Code credentials file
+    const fileCreds = getClaudeCredentials();
+    if (fileCreds) {
+        return { type: "claude_oauth", credentials: fileCreds };
+    }
+    // 3. macOS Keychain
+    const keychainCreds = getClaudeKeychainCredentials();
+    if (keychainCreds) {
+        return { type: "claude_oauth", credentials: keychainCreds };
+    }
+    // 4. Codex credentials
+    const codexCreds = getCodexCredentials();
+    if (codexCreds) {
+        return { type: "codex_oauth", credentials: codexCreds };
+    }
+    return null;
+}
+/**
+ * Get a human-readable description of the credential source found.
+ */
+export function describeCredentials() {
+    const source = resolveCredentials();
+    if (!source) {
+        return "No credentials found. Set ANTHROPIC_API_KEY or run `claude login`";
+    }
+    switch (source.type) {
+        case "api_key":
+            return "Found ANTHROPIC_API_KEY";
+        case "claude_oauth":
+            return "Found Claude Code credentials";
+        case "codex_oauth":
+            return "Found Codex credentials";
+    }
+}

package/dist/llm/vertex.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Vertex AI Gemini Provider for Server-Side LLM Client
+ *
+ * Handles:
+ * - Service account JWT → OAuth token exchange
+ * - Gemini API request/response format
+ * - Streaming SSE parsing
+ * - Anthropic ↔ Gemini format conversion (canonical internal format is Anthropic)
+ *
+ * The server uses Anthropic's content block format internally.
+ * This module converts to/from Gemini's format at the API boundary.
+ */
+import type { CallLLMParams, LLMResponse } from "./client.js";
+/**
+ * Initialize Vertex AI with a service account JSON file path or object.
+ */
+export declare function initVertex(serviceAccountPathOrJson: string | object, region?: string): void;
+/**
+ * Check if Vertex AI is configured.
+ */
+export declare function isVertexConfigured(): boolean;
+export declare function callVertexLLM(params: CallLLMParams): Promise<LLMResponse>;