@kkeve/suite 0.0.1 → 0.0.2

package/dist/context/truncation.d.ts

@@ -1,67 +0,0 @@
-/**
- * Truncation utilities — ported from gemini-cli (Apache-2.0), adapted for
- * our project's message format (OpenAI-compatible instead of Gemini Part).
- *
- * Key differences from the original:
- * - No `Part` type from `@google/genai` → use `TokenEstimationPart` from tokenCalculation
- * - `normalizeFunctionResponse` works on plain JSON objects instead of Gemini's Part structure
- */
-/** Minimum target tokens to preserve when truncating. */
-export declare const MIN_TARGET_TOKENS = 10;
-/** Minimum character count before truncation is applied. */
-export declare const MIN_CHARS_FOR_TRUNCATION = 100;
-/** Prefix marker for truncated text content. */
-export declare const TEXT_TRUNCATION_PREFIX = "[Message Normalized: Exceeded size limit]";
-/** Prefix marker for truncated tool output. */
-export declare const TOOL_TRUNCATION_PREFIX = "[Message Normalized: Tool output exceeded size limit]";
-/**
- * Estimates the character limit for a target token count, accounting for ASCII vs Non-ASCII.
- * Uses a weighted average based on the provided text to decide how many characters
- * fit into the target token budget.
- *
- * Ported from gemini-cli's `estimateCharsFromTokens`.
- */
-export declare function estimateCharsFromTokens(text: string, targetTokens: number): number;
-/**
- * Truncates a string to a target length, keeping a proportional amount of the head and tail,
- * and prepending a prefix marker.
- *
- * By default, 20% of the budget goes to the head (beginning) and 80% to the tail (end),
- * which preserves recent context while keeping some original context.
- *
- * Ported from gemini-cli's `truncateProportionally`.
- */
-export declare function truncateProportionally(str: string, targetChars: number, prefix?: string, headRatio?: number): string;
-/**
- * Safely normalizes a function/tool response by truncating large string values
- * within the response object while maintaining its JSON structure (preserving keys
- * like stdout, stderr, etc.).
- *
- * This is the OpenAI-compatible adaptation of gemini-cli's `normalizeFunctionResponse`.
- * Instead of operating on Gemini's `Part.functionResponse`, it operates on plain
- * JSON objects (the `result` field of OpenAI tool_call responses).
- *
- * @param responseObj - The tool response object (e.g., { stdout: "...", stderr: "..." })
- * @param ratio - Retention ratio (e.g., 0.3 means keep ~30% of tokens)
- * @param headRatio - Proportion of head content to keep (default 0.2)
- * @param savedPath - Optional path where full output was saved (added as footer)
- * @param intentSummary - Optional LLM-generated summary appended after truncation
- * @returns The normalized response object with large values truncated
- */
-export declare function normalizeFunctionResponse(responseObj: Record<string, unknown>, ratio: number, headRatio?: number, savedPath?: string, intentSummary?: string): Record<string, unknown>;
-/**
- * Truncate a text string to fit within a token budget.
- * Converts the token budget to a character budget using `estimateCharsFromTokens`,
- * then applies `truncateProportionally`.
- *
- * This is a convenience function combining token estimation + truncation,
- * useful for truncating LLM input (a11y tree snapshots, PRD content, etc.)
- * to fit within the model's token limit.
- *
- * @param text - The text to potentially truncate
- * @param maxTokens - Maximum token budget
- * @param prefix - Prefix marker for truncated text
- * @param headRatio - Proportion of head to keep
- * @returns Truncated text if exceeding budget, original text otherwise
- */
-export declare function truncateToTokenBudget(text: string, maxTokens: number, prefix?: string, headRatio?: number): string;

package/dist/context/truncation.js

@@ -1,142 +0,0 @@
-"use strict";
-/**
- * Truncation utilities — ported from gemini-cli (Apache-2.0), adapted for
- * our project's message format (OpenAI-compatible instead of Gemini Part).
- *
- * Key differences from the original:
- * - No `Part` type from `@google/genai` → use `TokenEstimationPart` from tokenCalculation
- * - `normalizeFunctionResponse` works on plain JSON objects instead of Gemini's Part structure
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TOOL_TRUNCATION_PREFIX = exports.TEXT_TRUNCATION_PREFIX = exports.MIN_CHARS_FOR_TRUNCATION = exports.MIN_TARGET_TOKENS = void 0;
-exports.estimateCharsFromTokens = estimateCharsFromTokens;
-exports.truncateProportionally = truncateProportionally;
-exports.normalizeFunctionResponse = normalizeFunctionResponse;
-exports.truncateToTokenBudget = truncateToTokenBudget;
-const tokenCalculation_1 = require("./tokenCalculation");
-/** Minimum target tokens to preserve when truncating. */
-exports.MIN_TARGET_TOKENS = 10;
-/** Minimum character count before truncation is applied. */
-exports.MIN_CHARS_FOR_TRUNCATION = 100;
-/** Prefix marker for truncated text content. */
-exports.TEXT_TRUNCATION_PREFIX = '[Message Normalized: Exceeded size limit]';
-/** Prefix marker for truncated tool output. */
-exports.TOOL_TRUNCATION_PREFIX = '[Message Normalized: Tool output exceeded size limit]';
-/**
- * Estimates the character limit for a target token count, accounting for ASCII vs Non-ASCII.
- * Uses a weighted average based on the provided text to decide how many characters
- * fit into the target token budget.
- *
- * Ported from gemini-cli's `estimateCharsFromTokens`.
- */
-function estimateCharsFromTokens(text, targetTokens) {
-    if (text.length === 0)
-        return 0;
-    // Count ASCII vs Non-ASCII in a sample of the text.
-    let asciiCount = 0;
-    const sampleLen = Math.min(text.length, 1000);
-    for (let i = 0; i < sampleLen; i++) {
-        if (text.charCodeAt(i) <= 127) {
-            asciiCount++;
-        }
-    }
-    const asciiRatio = asciiCount / sampleLen;
-    // Weighted tokens per character:
-    const avgTokensPerChar = asciiRatio * 0.33 + (1 - asciiRatio) * 1.5; // ASCII_TOKENS_PER_CHAR + NON_ASCII_TOKENS_PER_CHAR
-    // Characters = Tokens / (Tokens per Character)
-    return Math.floor(targetTokens / avgTokensPerChar);
-}
-/**
- * Truncates a string to a target length, keeping a proportional amount of the head and tail,
- * and prepending a prefix marker.
- *
- * By default, 20% of the budget goes to the head (beginning) and 80% to the tail (end),
- * which preserves recent context while keeping some original context.
- *
- * Ported from gemini-cli's `truncateProportionally`.
- */
-function truncateProportionally(str, targetChars, prefix = exports.TEXT_TRUNCATION_PREFIX, headRatio = 0.2) {
-    if (str.length <= targetChars)
-        return str;
-    const ellipsis = '\n...\n';
-    const overhead = prefix.length + ellipsis.length + 1; // +1 for newline after prefix
-    const availableChars = Math.max(0, targetChars - overhead);
-    if (availableChars <= 0) {
-        return prefix; // Safe fallback if target is extremely small
-    }
-    const headChars = Math.floor(availableChars * headRatio);
-    const tailChars = availableChars - headChars;
-    return `${prefix}\n${str.substring(0, headChars)}${ellipsis}${str.substring(str.length - tailChars)}`;
-}
-/**
- * Safely normalizes a function/tool response by truncating large string values
- * within the response object while maintaining its JSON structure (preserving keys
- * like stdout, stderr, etc.).
- *
- * This is the OpenAI-compatible adaptation of gemini-cli's `normalizeFunctionResponse`.
- * Instead of operating on Gemini's `Part.functionResponse`, it operates on plain
- * JSON objects (the `result` field of OpenAI tool_call responses).
- *
- * @param responseObj - The tool response object (e.g., { stdout: "...", stderr: "..." })
- * @param ratio - Retention ratio (e.g., 0.3 means keep ~30% of tokens)
- * @param headRatio - Proportion of head content to keep (default 0.2)
- * @param savedPath - Optional path where full output was saved (added as footer)
- * @param intentSummary - Optional LLM-generated summary appended after truncation
- * @returns The normalized response object with large values truncated
- */
-function normalizeFunctionResponse(responseObj, ratio, headRatio = 0.2, savedPath, intentSummary) {
-    if (typeof responseObj !== 'object' || responseObj === null) {
-        return responseObj;
-    }
-    let hasChanges = false;
-    const newResponse = {};
-    for (const [key, value] of Object.entries(responseObj)) {
-        if (typeof value === 'string' && value.length > exports.MIN_CHARS_FOR_TRUNCATION) {
-            const valueTokens = (0, tokenCalculation_1.estimateTokenCountSync)([{ text: value }]);
-            const targetValueTokens = Math.max(exports.MIN_TARGET_TOKENS, Math.floor(valueTokens * ratio));
-            const targetChars = estimateCharsFromTokens(value, targetValueTokens);
-            if (value.length > targetChars) {
-                let truncated = truncateProportionally(value, targetChars, exports.TOOL_TRUNCATION_PREFIX, headRatio);
-                if (savedPath) {
-                    truncated += `\n\nFull output saved to: ${savedPath}`;
-                }
-                if (intentSummary) {
-                    truncated += intentSummary;
-                }
-                newResponse[key] = truncated;
-                hasChanges = true;
-            }
-            else {
-                newResponse[key] = value;
-            }
-        }
-        else {
-            newResponse[key] = value;
-        }
-    }
-    return hasChanges ? newResponse : responseObj;
-}
-/**
- * Truncate a text string to fit within a token budget.
- * Converts the token budget to a character budget using `estimateCharsFromTokens`,
- * then applies `truncateProportionally`.
- *
- * This is a convenience function combining token estimation + truncation,
- * useful for truncating LLM input (a11y tree snapshots, PRD content, etc.)
- * to fit within the model's token limit.
- *
- * @param text - The text to potentially truncate
- * @param maxTokens - Maximum token budget
- * @param prefix - Prefix marker for truncated text
- * @param headRatio - Proportion of head to keep
- * @returns Truncated text if exceeding budget, original text otherwise
- */
-function truncateToTokenBudget(text, maxTokens, prefix = exports.TEXT_TRUNCATION_PREFIX, headRatio = 0.2) {
-    if (text.length <= exports.MIN_CHARS_FOR_TRUNCATION)
-        return text;
-    const estimatedTokens = (0, tokenCalculation_1.estimateTokenCountSync)([{ text }]);
-    if (estimatedTokens <= maxTokens)
-        return text;
-    const targetChars = estimateCharsFromTokens(text, maxTokens);
-    return truncateProportionally(text, targetChars, prefix, headRatio);
-}

package/dist/context/types.d.ts

@@ -1,7 +0,0 @@
-/**
- * Core context module types — shared between truncation, token calculation,
- * and future context manager/compression modules.
- */
-export type { TokenEstimationPart, } from './tokenCalculation';
-export { ASCII_TOKENS_PER_CHAR, NON_ASCII_TOKENS_PER_CHAR, MSG_OVERHEAD_TOKENS, DEFAULT_CHARS_PER_TOKEN, estimateTextTokens, estimateTokenCountSync, estimateTokenCountForText, calculateTokenCount, } from './tokenCalculation';
-export { MIN_TARGET_TOKENS, MIN_CHARS_FOR_TRUNCATION, TEXT_TRUNCATION_PREFIX, TOOL_TRUNCATION_PREFIX, estimateCharsFromTokens, truncateProportionally, normalizeFunctionResponse, truncateToTokenBudget, } from './truncation';

package/dist/context/types.js

@@ -1,27 +0,0 @@
-"use strict";
-/**
- * Core context module types — shared between truncation, token calculation,
- * and future context manager/compression modules.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.truncateToTokenBudget = exports.normalizeFunctionResponse = exports.truncateProportionally = exports.estimateCharsFromTokens = exports.TOOL_TRUNCATION_PREFIX = exports.TEXT_TRUNCATION_PREFIX = exports.MIN_CHARS_FOR_TRUNCATION = exports.MIN_TARGET_TOKENS = exports.calculateTokenCount = exports.estimateTokenCountForText = exports.estimateTokenCountSync = exports.estimateTextTokens = exports.DEFAULT_CHARS_PER_TOKEN = exports.MSG_OVERHEAD_TOKENS = exports.NON_ASCII_TOKENS_PER_CHAR = exports.ASCII_TOKENS_PER_CHAR = void 0;
-var tokenCalculation_1 = require("./tokenCalculation");
-// Token calculation
-Object.defineProperty(exports, "ASCII_TOKENS_PER_CHAR", { enumerable: true, get: function () { return tokenCalculation_1.ASCII_TOKENS_PER_CHAR; } });
-Object.defineProperty(exports, "NON_ASCII_TOKENS_PER_CHAR", { enumerable: true, get: function () { return tokenCalculation_1.NON_ASCII_TOKENS_PER_CHAR; } });
-Object.defineProperty(exports, "MSG_OVERHEAD_TOKENS", { enumerable: true, get: function () { return tokenCalculation_1.MSG_OVERHEAD_TOKENS; } });
-Object.defineProperty(exports, "DEFAULT_CHARS_PER_TOKEN", { enumerable: true, get: function () { return tokenCalculation_1.DEFAULT_CHARS_PER_TOKEN; } });
-Object.defineProperty(exports, "estimateTextTokens", { enumerable: true, get: function () { return tokenCalculation_1.estimateTextTokens; } });
-Object.defineProperty(exports, "estimateTokenCountSync", { enumerable: true, get: function () { return tokenCalculation_1.estimateTokenCountSync; } });
-Object.defineProperty(exports, "estimateTokenCountForText", { enumerable: true, get: function () { return tokenCalculation_1.estimateTokenCountForText; } });
-Object.defineProperty(exports, "calculateTokenCount", { enumerable: true, get: function () { return tokenCalculation_1.calculateTokenCount; } });
-var truncation_1 = require("./truncation");
-// Truncation
-Object.defineProperty(exports, "MIN_TARGET_TOKENS", { enumerable: true, get: function () { return truncation_1.MIN_TARGET_TOKENS; } });
-Object.defineProperty(exports, "MIN_CHARS_FOR_TRUNCATION", { enumerable: true, get: function () { return truncation_1.MIN_CHARS_FOR_TRUNCATION; } });
-Object.defineProperty(exports, "TEXT_TRUNCATION_PREFIX", { enumerable: true, get: function () { return truncation_1.TEXT_TRUNCATION_PREFIX; } });
-Object.defineProperty(exports, "TOOL_TRUNCATION_PREFIX", { enumerable: true, get: function () { return truncation_1.TOOL_TRUNCATION_PREFIX; } });
-Object.defineProperty(exports, "estimateCharsFromTokens", { enumerable: true, get: function () { return truncation_1.estimateCharsFromTokens; } });
-Object.defineProperty(exports, "truncateProportionally", { enumerable: true, get: function () { return truncation_1.truncateProportionally; } });
-Object.defineProperty(exports, "normalizeFunctionResponse", { enumerable: true, get: function () { return truncation_1.normalizeFunctionResponse; } });
-Object.defineProperty(exports, "truncateToTokenBudget", { enumerable: true, get: function () { return truncation_1.truncateToTokenBudget; } });

package/dist/llm/OpenAIClient.d.ts

@@ -1,31 +0,0 @@
-import type { ChatResult, InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types';
-/**
- * Client for OpenAI compatible APIs
- */
-export declare class OpenAIClient implements LLMClient {
-    config: Required<LLMConfig>;
-    private fetch;
-    constructor(config: Required<LLMConfig>);
-    invoke(messages: Message[], tools: Record<string, Tool>, abortSignal?: AbortSignal, options?: InvokeOptions): Promise<InvokeResult>;
-    /**
-     * 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)
-     */
-    private tryRecoverJSON;
-    /**
-     * 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.
-     */
-    chat(messages: Message[], tools: Record<string, Tool>, abortSignal?: AbortSignal, options?: InvokeOptions): Promise<ChatResult>;
-}