@kkeve/suite 0.0.1

package/dist/llm/OpenAIClient.js

@@ -0,0 +1,455 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAIClient = void 0;
+/**
+ * OpenAI Client implementation
+
+不需要工具 → LLM.chat()        → 直接调 API，不带 tools
+需要工具循环 → LLM.chatWithTools() → 调 OpenAIClient.chat()，tool_choice: auto
+需要强制工具 → LLM.invoke()      → 调 OpenAIClient.invoke()，tool_choice: required
+
+ */
+const z = __importStar(require("zod/v4"));
+const errors_1 = require("./errors");
+const utils_1 = require("./utils");
+/**
+ * Client for OpenAI compatible APIs
+ */
+class OpenAIClient {
+    config;
+    fetch;
+    constructor(config) {
+        this.config = config;
+        this.fetch = config.customFetch;
+    }
+    async invoke(messages, tools, abortSignal, options) {
+        // 1. Convert tools to OpenAI format
+        // If a Tool has customJsonSchema, use it directly (detailed schema for LLM)
+        // Otherwise, convert from zod inputSchema via zodToOpenAITool
+        const openaiTools = Object.entries(tools).map(([name, t]) => {
+            if (t.customJsonSchema) {
+                return {
+                    type: 'function',
+                    function: {
+                        name,
+                        description: t.description,
+                        parameters: t.customJsonSchema,
+                    },
+                };
+            }
+            return (0, utils_1.zodToOpenAITool)(name, t);
+        });
+        // Build request body
+        let toolChoice = 'required';
+        if (options?.toolChoiceName && !this.config.disableNamedToolChoice) {
+            toolChoice = { type: 'function', function: { name: options.toolChoiceName } };
+        }
+        else if (this.config.disableNamedToolChoice) {
+            toolChoice = undefined;
+        }
+        const requestBody = {
+            model: this.config.model,
+            temperature: this.config.temperature,
+            messages,
+            tools: openaiTools,
+            parallel_tool_calls: false,
+            ...(toolChoice !== undefined && { tool_choice: toolChoice }),
+        };
+        (0, utils_1.modelPatch)(requestBody);
+        // 2. Call API
+        let response;
+        try {
+            response = await this.fetch(`${this.config.baseURL}/chat/completions`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...(this.config.apiKey && { Authorization: `Bearer ${this.config.apiKey}` }),
+                },
+                body: JSON.stringify(requestBody),
+                signal: abortSignal,
+            });
+        }
+        catch (error) {
+            const isAbortError = error?.name === 'AbortError';
+            const errorMessage = isAbortError ? 'Network request aborted' : 'Network request failed';
+            if (!isAbortError)
+                console.error(error);
+            throw new errors_1.InvokeError(errors_1.InvokeErrorType.NETWORK_ERROR, errorMessage, error);
+        }
+        // 3. Handle HTTP errors
+        if (!response.ok) {
+            const errorData = await response.json().catch();
+            const errorMessage = errorData.error?.message || response.statusText;
+            if (response.status === 401 || response.status === 403) {
+                throw new errors_1.InvokeError(errors_1.InvokeErrorType.AUTH_ERROR, `Authentication failed: ${errorMessage}`, errorData);
+            }
+            if (response.status === 429) {
+                throw new errors_1.InvokeError(errors_1.InvokeErrorType.RATE_LIMIT, `Rate limit exceeded: ${errorMessage}`, errorData);
+            }
+            if (response.status >= 500) {
+                throw new errors_1.InvokeError(errors_1.InvokeErrorType.SERVER_ERROR, `Server error: ${errorMessage}`, errorData);
+            }
+            throw new errors_1.InvokeError(errors_1.InvokeErrorType.UNKNOWN, `HTTP ${response.status}: ${errorMessage}`, errorData);
+        }
+        // 4. Parse and validate response
+        const data = await response.json();
+        const choice = data.choices?.[0];
+        if (!choice) {
+            throw new errors_1.InvokeError(errors_1.InvokeErrorType.UNKNOWN, 'No choices in response', data);
+        }
+        // Check finish_reason
+        switch (choice.finish_reason) {
+            case 'tool_calls':
+            case 'function_call':
+            case 'stop':
+                break;
+            case 'length':
+                throw new errors_1.InvokeError(errors_1.InvokeErrorType.CONTEXT_LENGTH, 'Response truncated: max tokens reached', undefined, data);
+            case 'content_filter':
+                throw new errors_1.InvokeError(errors_1.InvokeErrorType.CONTENT_FILTER, 'Content filtered by safety system', undefined, data);
+            default:
+                throw new errors_1.InvokeError(errors_1.InvokeErrorType.UNKNOWN, `Unexpected finish_reason: ${choice.finish_reason}`, undefined, data);
+        }
+        // Apply normalizeResponse if provided
+        const normalizedData = options?.normalizeResponse ? options.normalizeResponse(data) : data;
+        const normalizedChoice = normalizedData.choices?.[0];
+        // Get tool name from response
+        const toolCallName = normalizedChoice?.message?.tool_calls?.[0]?.function?.name;
+        if (!toolCallName) {
+            // When LLM returns no valid tool_call (finish_reason: 'stop', empty tool_calls, etc.),
+            // treat it as a graceful fallback rather than throwing an error.
+            const textContent = normalizedChoice?.message?.content;
+            // Try to find a suitable tool for synthetic call:
+            // 1. Prefer "done" or "AgentOutput" (main loop tools)
+            // 2. Fall back to the first available tool (sub-tool calls like VerifyResult)
+            const doneTool = tools['done'] || tools['AgentOutput'] || Object.values(tools)[0];
+            if (doneTool) {
+                // For "done"/"AgentOutput", wrap as { text, success }
+                // For other tools, try to parse textContent as JSON; fallback to minimal valid input
+                let syntheticArgs;
+                const toolName = doneTool === tools['done'] ? 'done'
+                    : doneTool === tools['AgentOutput'] ? 'AgentOutput'
+                        : Object.keys(tools)[0];
+                if (toolName === 'done' || toolName === 'AgentOutput') {
+                    syntheticArgs = { text: textContent || '', success: true };
+                }
+                else {
+                    // Try to extract JSON from the text content (LLM sometimes outputs JSON in text)
+                    if (textContent) {
+                        const jsonMatch = textContent.match(/\{[\s\S]*\}/);
+                        if (jsonMatch) {
+                            try {
+                                syntheticArgs = JSON.parse(jsonMatch[0]);
+                            }
+                            catch {
+                                syntheticArgs = {};
+                            }
+                        }
+                        else {
+                            syntheticArgs = {};
+                        }
+                    }
+                    else {
+                        syntheticArgs = {};
+                    }
+                }
+                const validation = doneTool.inputSchema.safeParse(syntheticArgs);
+                const toolInput = validation.success ? validation.data : syntheticArgs;
+                let toolResult;
+                try {
+                    toolResult = validation.success ? await doneTool.execute(toolInput) : toolInput;
+                }
+                catch {
+                    toolResult = toolInput;
+                }
+                return {
+                    toolCall: {
+                        name: toolName,
+                        args: toolInput,
+                    },
+                    toolResult,
+                    usage: {
+                        promptTokens: data.usage?.prompt_tokens ?? 0,
+                        completionTokens: data.usage?.completion_tokens ?? 0,
+                        totalTokens: data.usage?.total_tokens ?? 0,
+                        cachedTokens: data.usage?.prompt_tokens_details?.cached_tokens,
+                        reasoningTokens: data.usage?.completion_tokens_details?.reasoning_tokens,
+                    },
+                    rawResponse: data,
+                };
+            }
+            throw new errors_1.InvokeError(errors_1.InvokeErrorType.NO_TOOL_CALL, 'No tool call found in response', undefined, data);
+        }
+        const tool = tools[toolCallName];
+        if (!tool) {
+            throw new errors_1.InvokeError(errors_1.InvokeErrorType.UNKNOWN, `Tool "${toolCallName}" not found in tools`, undefined, data);
+        }
+        // Extract and parse tool arguments
+        const argString = normalizedChoice.message?.tool_calls?.[0]?.function?.arguments;
+        if (!argString) {
+            throw new errors_1.InvokeError(errors_1.InvokeErrorType.INVALID_TOOL_ARGS, 'No tool call arguments found', undefined, data);
+        }
+        let parsedArgs;
+        try {
+            parsedArgs = JSON.parse(argString);
+        }
+        catch (jsonError) {
+            // LLM sometimes generates slightly malformed JSON (e.g. trailing characters, 
+            // mismatched quotes, or extra text after the closing brace).
+            // Attempt to recover by extracting the first valid JSON object from the string.
+            const recovered = this.tryRecoverJSON(argString);
+            if (recovered !== undefined) {
+                parsedArgs = recovered;
+            }
+            else {
+                throw new errors_1.InvokeError(errors_1.InvokeErrorType.INVALID_TOOL_ARGS, 'Failed to parse tool arguments as JSON', jsonError, data);
+            }
+        }
+        // Validate with schema
+        const validation = tool.inputSchema.safeParse(parsedArgs);
+        if (!validation.success) {
+            console.error(z.prettifyError(validation.error));
+            throw new errors_1.InvokeError(errors_1.InvokeErrorType.INVALID_TOOL_ARGS, 'Tool arguments validation failed', validation.error, data);
+        }
+        const toolInput = validation.data;
+        // 5. Execute tool
+        let toolResult;
+        try {
+            toolResult = await tool.execute(toolInput);
+        }
+        catch (e) {
+            throw new errors_1.InvokeError(errors_1.InvokeErrorType.TOOL_EXECUTION_ERROR, `Tool execution failed: ${e.message}`, e, data);
+        }
+        // Return result
+        return {
+            toolCall: {
+                name: toolCallName,
+                args: toolInput,
+            },
+            toolResult,
+            usage: {
+                promptTokens: data.usage?.prompt_tokens ?? 0,
+                completionTokens: data.usage?.completion_tokens ?? 0,
+                totalTokens: data.usage?.total_tokens ?? 0,
+                cachedTokens: data.usage?.prompt_tokens_details?.cached_tokens,
+                reasoningTokens: data.usage?.completion_tokens_details?.reasoning_tokens,
+            },
+            rawResponse: data,
+            rawRequest: requestBody,
+        };
+    }
+    /**
+     * Attempt to recover a valid JSON object from a malformed LLM response.
+     * Handles common LLM JSON errors:
+     * 1. Extra text after closing brace (e.g. "...}{extra")
+     * 2. Trailing commas inside objects
+     * 3. Unbalanced braces — find the deepest matching pair
+     * 4. Mixed quote styles (single quotes instead of double quotes)
+     */
+    tryRecoverJSON(argString) {
+        // Strategy 1: Find the first complete JSON object using brace matching
+        const firstBrace = argString.indexOf('{');
+        if (firstBrace === -1)
+            return undefined;
+        let depth = 0;
+        let inString = false;
+        let escapeNext = false;
+        for (let i = firstBrace; i < argString.length; i++) {
+            const ch = argString[i];
+            if (escapeNext) {
+                escapeNext = false;
+                continue;
+            }
+            if (ch === '\\') {
+                escapeNext = true;
+                continue;
+            }
+            if (ch === '"' && !escapeNext) {
+                inString = !inString;
+                continue;
+            }
+            if (inString)
+                continue;
+            if (ch === '{')
+                depth++;
+            if (ch === '}') {
+                depth--;
+                if (depth === 0) {
+                    // Extract the matched JSON object
+                    const candidate = argString.substring(firstBrace, i + 1);
+                    try {
+                        return JSON.parse(candidate);
+                    }
+                    catch {
+                        // Strategy 2: Fix common issues
+                        let fixed = candidate;
+                        // Remove trailing commas before } or ]
+                        fixed = fixed.replace(/,\s*([}\]])/g, '$1');
+                        // Replace single-quoted property names with double quotes
+                        fixed = fixed.replace(/'([^']+)'\s*:/g, '"$1":');
+                        // Replace single-quoted string values with double quotes (careful with nested)
+                        fixed = fixed.replace(/:\s*'([^']*)'/g, ': "$1"');
+                        try {
+                            return JSON.parse(fixed);
+                        }
+                        catch {
+                            continue; // try deeper nesting
+                        }
+                    }
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Call the LLM and return the full assistant message without executing any tools.
+     * Used by the agent loop to get the LLM's response and process tool_calls separately.
+     *
+     * This method:
+     * 1. Sends messages + tools to the OpenAI-compatible API
+     * 2. Returns the full assistant Message (with content + tool_calls)
+     * 3. Does NOT execute any tools or validate tool args
+     *
+     * The agent loop handles tool execution via its own ToolRegistry.
+     */
+    async chat(messages, tools, abortSignal, options) {
+        // Convert tools to OpenAI format (same as invoke)
+        const openaiTools = Object.entries(tools).map(([name, t]) => {
+            if (t.customJsonSchema) {
+                return {
+                    type: 'function',
+                    function: {
+                        name,
+                        description: t.description,
+                        parameters: t.customJsonSchema,
+                    },
+                };
+            }
+            return (0, utils_1.zodToOpenAITool)(name, t);
+        });
+        // Build request body
+        let toolChoice = 'required';
+        if (options?.toolChoiceName && !this.config.disableNamedToolChoice) {
+            toolChoice = { type: 'function', function: { name: options.toolChoiceName } };
+        }
+        else if (this.config.disableNamedToolChoice) {
+            toolChoice = undefined;
+        }
+        // For agent loop, we want the LLM to have freedom to respond
+        // with text or tool_calls. Use 'auto' instead of 'required'.
+        if (!options?.toolChoiceName) {
+            toolChoice = 'auto';
+        }
+        const requestBody = {
+            model: this.config.model,
+            temperature: this.config.temperature,
+            messages,
+            tools: openaiTools,
+            parallel_tool_calls: false,
+            ...(toolChoice !== undefined && { tool_choice: toolChoice }),
+        };
+        (0, utils_1.modelPatch)(requestBody);
+        // Call API
+        let response;
+        try {
+            response = await this.fetch(`${this.config.baseURL}/chat/completions`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...(this.config.apiKey && { Authorization: `Bearer ${this.config.apiKey}` }),
+                },
+                body: JSON.stringify(requestBody),
+                signal: abortSignal,
+            });
+        }
+        catch (error) {
+            const isAbortError = error?.name === 'AbortError';
+            const errorMessage = isAbortError ? 'Network request aborted' : 'Network request failed';
+            if (!isAbortError)
+                console.error(error);
+            throw new errors_1.InvokeError(errors_1.InvokeErrorType.NETWORK_ERROR, errorMessage, error);
+        }
+        // Handle HTTP errors (same as invoke)
+        if (!response.ok) {
+            const errorData = await response.json().catch();
+            const errorMessage = errorData.error?.message || response.statusText;
+            if (response.status === 401 || response.status === 403) {
+                throw new errors_1.InvokeError(errors_1.InvokeErrorType.AUTH_ERROR, `Authentication failed: ${errorMessage}`, errorData);
+            }
+            if (response.status === 429) {
+                throw new errors_1.InvokeError(errors_1.InvokeErrorType.RATE_LIMIT, `Rate limit exceeded: ${errorMessage}`, errorData);
+            }
+            if (response.status >= 500) {
+                throw new errors_1.InvokeError(errors_1.InvokeErrorType.SERVER_ERROR, `Server error: ${errorMessage}`, errorData);
+            }
+            throw new errors_1.InvokeError(errors_1.InvokeErrorType.UNKNOWN, `HTTP ${response.status}: ${errorMessage}`, errorData);
+        }
+        // Parse response and extract full assistant message
+        const data = await response.json();
+        const choice = data.choices?.[0];
+        if (!choice) {
+            throw new errors_1.InvokeError(errors_1.InvokeErrorType.UNKNOWN, 'No choices in response', data);
+        }
+        // Build the assistant Message from the response
+        const assistantMessage = {
+            role: 'assistant',
+            content: choice.message?.content ?? null,
+        };
+        // Include tool_calls if present
+        if (choice.message?.tool_calls?.length) {
+            assistantMessage.tool_calls = choice.message.tool_calls.map((tc) => ({
+                id: tc.id,
+                type: 'function',
+                function: {
+                    name: tc.function.name,
+                    arguments: tc.function.arguments,
+                },
+            }));
+        }
+        return {
+            message: assistantMessage,
+            usage: {
+                promptTokens: data.usage?.prompt_tokens ?? 0,
+                completionTokens: data.usage?.completion_tokens ?? 0,
+                totalTokens: data.usage?.total_tokens ?? 0,
+                cachedTokens: data.usage?.prompt_tokens_details?.cached_tokens,
+                reasoningTokens: data.usage?.completion_tokens_details?.reasoning_tokens,
+            },
+            rawResponse: data,
+        };
+    }
+}
+exports.OpenAIClient = OpenAIClient;

package/dist/llm/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const LLM_MAX_RETRIES = 2;
+export declare const DEFAULT_TEMPERATURE = 0.7;

package/dist/llm/constants.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TEMPERATURE = exports.LLM_MAX_RETRIES = void 0;
+// Internal constants
+exports.LLM_MAX_RETRIES = 2;
+exports.DEFAULT_TEMPERATURE = 0.7;

package/dist/llm/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Error types and error handling for LLM invocations
+ */
+export declare const InvokeErrorType: {
+    readonly NETWORK_ERROR: "network_error";
+    readonly RATE_LIMIT: "rate_limit";
+    readonly SERVER_ERROR: "server_error";
+    readonly NO_TOOL_CALL: "no_tool_call";
+    readonly INVALID_TOOL_ARGS: "invalid_tool_args";
+    readonly TOOL_EXECUTION_ERROR: "tool_execution_error";
+    readonly UNKNOWN: "unknown";
+    readonly AUTH_ERROR: "auth_error";
+    readonly CONTEXT_LENGTH: "context_length";
+    readonly CONTENT_FILTER: "content_filter";
+};
+export type InvokeErrorType = (typeof InvokeErrorType)[keyof typeof InvokeErrorType];
+export declare class InvokeError extends Error {
+    type: InvokeErrorType;
+    retryable: boolean;
+    statusCode?: number;
+    rawError?: unknown;
+    rawResponse?: unknown;
+    constructor(type: InvokeErrorType, message: string, rawError?: unknown, rawResponse?: unknown);
+    private isRetryable;
+}

package/dist/llm/errors.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Error types and error handling for LLM invocations
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvokeError = exports.InvokeErrorType = void 0;
+exports.InvokeErrorType = {
+    // Retryable
+    NETWORK_ERROR: 'network_error',
+    RATE_LIMIT: 'rate_limit',
+    SERVER_ERROR: 'server_error',
+    NO_TOOL_CALL: 'no_tool_call',
+    INVALID_TOOL_ARGS: 'invalid_tool_args',
+    TOOL_EXECUTION_ERROR: 'tool_execution_error',
+    UNKNOWN: 'unknown',
+    // Non-retryable
+    AUTH_ERROR: 'auth_error',
+    CONTEXT_LENGTH: 'context_length',
+    CONTENT_FILTER: 'content_filter',
+};
+class InvokeError extends Error {
+    type;
+    retryable;
+    statusCode;
+    rawError;
+    rawResponse;
+    constructor(type, message, rawError, rawResponse) {
+        super(message);
+        this.name = 'InvokeError';
+        this.type = type;
+        this.retryable = this.isRetryable(type, rawError);
+        this.rawError = rawError;
+        this.rawResponse = rawResponse;
+    }
+    isRetryable(type, rawError) {
+        const isAbortError = rawError?.name === 'AbortError';
+        if (isAbortError)
+            return false;
+        const retryableTypes = [
+            exports.InvokeErrorType.NETWORK_ERROR,
+            exports.InvokeErrorType.RATE_LIMIT,
+            exports.InvokeErrorType.SERVER_ERROR,
+            exports.InvokeErrorType.NO_TOOL_CALL,
+            exports.InvokeErrorType.INVALID_TOOL_ARGS,
+            exports.InvokeErrorType.TOOL_EXECUTION_ERROR,
+            exports.InvokeErrorType.UNKNOWN,
+        ];
+        return retryableTypes.includes(type);
+    }
+}
+exports.InvokeError = InvokeError;

package/dist/llm/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * LLM client with MacroTool support
+ *
+ * Key features:
+ * - Direct fetch to OpenAI API (no LangChain dependency)
+ * - Zod schema for tool definitions
+ * - toolChoiceName support (force specific tool call)
+ * - parallel_tool_calls: false (one tool per step)
+ * - Retry with error classification
+ * - Model-specific patches (Claude, Qwen, GPT, etc.)
+ */
+import { InvokeError, InvokeErrorType } from './errors';
+import type { ChatResult, ContentItem, InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types';
+import { parseXMLExtractionResponse, extractXMLTag } from './utils';
+export { InvokeError, InvokeErrorType };
+export { parseXMLExtractionResponse, extractXMLTag };
+export type { ChatResult, ContentItem, InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool };
+export declare function parseLLMConfig(config: LLMConfig): Required<LLMConfig>;
+export declare class LLM extends EventTarget {
+    config: Required<LLMConfig>;
+    client: LLMClient;
+    constructor(config: LLMConfig);
+    /**
+     * Call LLM API once, invoke tool call once, return the result.
+     * This is the core method used by gui-agent's MacroTool loop.
+     */
+    invoke(messages: Message[], tools: Record<string, Tool>, abortSignal?: AbortSignal, options?: InvokeOptions): Promise<InvokeResult>;
+    /**
+     * Simple chat call — no tools, just text generation.
+     * Used for validation and other non-tool-call LLM tasks.
+     */
+    chat(messages: Message[], abortSignal?: AbortSignal): Promise<{
+        content: string;
+        usage: {
+            prompt_tokens: number;
+            completion_tokens: number;
+            total_tokens: number;
+        };
+    }>;
+    /**
+     * Agent loop chat — call LLM with tools and return the full assistant message.
+     * Unlike invoke(), this does NOT execute tools. The agent loop handles tool
+     * execution via its own ToolRegistry after getting the response.
+     *
+     * Uses tool_choice: 'auto' by default (LLM can choose text or tool_calls).
+     * Includes retry logic with exponential backoff.
+     */
+    chatWithTools(messages: Message[], tools: Record<string, Tool>, abortSignal?: AbortSignal, options?: InvokeOptions): Promise<ChatResult>;
+}