@kkeve/suite 0.0.1 → 0.0.2

package/dist/llm/OpenAIClient.js

@@ -1,455 +0,0 @@
-"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

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

package/dist/llm/constants.js

@@ -1,6 +0,0 @@
-"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

@@ -1,25 +0,0 @@
-/**
- * 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

@@ -1,51 +0,0 @@
-"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

@@ -1,49 +0,0 @@
-/**
- * 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>;
-}