@kkeve/suite 0.0.1

package/dist/agent-loop/types.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Agent Loop Core Types
+ *
+ * Reference: gemini-cli LocalAgentExecutor + AgentProtocol
+ * Adapted for OpenAI-compatible API (internal proxy at xxx)
+ *
+ * Key differences from gemini-cli:
+ * - LLM calls use OpenAIClient instead of GeminiChat
+ * - Tool definitions reuse core/llm/types.ts Tool interface
+ * - No Gemini-specific Content/Part types — use OpenAI Message format
+ * - Simplified timeout (no DeadlineTimer pause/resume — we don't wait for user confirmation)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolRegistry = exports.TM_ERROR_NO_COMPLETE_TASK = exports.TM_ERROR = exports.TM_ABORTED = exports.TM_MAX_TURNS = exports.TM_TIMEOUT = exports.TM_GOAL = exports.COMPLETE_TASK_TOOL_NAME = exports.DEFAULT_MAX_TIME_MINUTES = exports.DEFAULT_MAX_TURNS = void 0;
+// ===== Constants (reference: gemini-cli DEFAULT_MAX_TURNS/DEFAULT_MAX_TIME_MINUTES) =====
+/** Default maximum number of conversational turns for an agent. */
+exports.DEFAULT_MAX_TURNS = 30;
+/** Default maximum execution time for an agent in minutes. */
+exports.DEFAULT_MAX_TIME_MINUTES = 10;
+/** Tool name for signaling task completion (reference: gemini-cli CompleteTaskTool) */
+exports.COMPLETE_TASK_TOOL_NAME = 'complete_task';
+// ===== Termination Modes =====
+/**
+ * Describes how an agent's execution ended.
+ * Reference: gemini-cli AgentTerminateMode (agents/types.ts L24-31)
+ */
+// Inline termination mode constants (vite tree-shaking removes cross-module const objects)
+exports.TM_GOAL = 'GOAL';
+exports.TM_TIMEOUT = 'TIMEOUT';
+exports.TM_MAX_TURNS = 'MAX_TURNS';
+exports.TM_ABORTED = 'ABORTED';
+exports.TM_ERROR = 'ERROR';
+exports.TM_ERROR_NO_COMPLETE_TASK = 'ERROR_NO_COMPLETE_TASK';
+/**
+ * Tool registry for managing and executing tools during agent execution.
+ * Reference: gemini-cli ToolRegistry (tools/tool-registry.ts)
+ *
+ * Simplified: no message bus, no confirmation policy, no sort, no MCP integration.
+ * These can be added incrementally.
+ */
+class ToolRegistry {
+    tools = new Map();
+    /** Register a tool definition. */
+    register(tool) {
+        this.tools.set(tool.name, tool);
+    }
+    /** Unregister a tool by name. */
+    unregister(name) {
+        this.tools.delete(name);
+    }
+    /** Get all registered tool names. */
+    getAllToolNames() {
+        return Array.from(this.tools.keys());
+    }
+    /** Convert registered tools to the core/llm/types.ts Tool map format for LLM calls. */
+    getToolsMap() {
+        const result = {};
+        for (const [name, def] of this.tools) {
+            result[name] = {
+                description: def.description,
+                inputSchema: def.inputSchema,
+                execute: def.execute,
+                customJsonSchema: def.customJsonSchema,
+            };
+        }
+        return result;
+    }
+    /** Get a subset of tools by name (for agent's toolNames restriction). */
+    getToolsMapSubset(names) {
+        const result = {};
+        for (const name of names) {
+            const def = this.tools.get(name);
+            if (def) {
+                result[name] = {
+                    description: def.description,
+                    inputSchema: def.inputSchema,
+                    execute: def.execute,
+                    customJsonSchema: def.customJsonSchema,
+                };
+            }
+        }
+        return result;
+    }
+    /** Execute a registered tool by name with the given arguments and optional context. */
+    async execute(name, args, context) {
+        const tool = this.tools.get(name);
+        if (!tool) {
+            throw new Error(`Tool not found: ${name}`);
+        }
+        // Validate args with zod schema
+        const validation = tool.inputSchema.safeParse(args);
+        const validatedArgs = validation.success ? validation.data : args;
+        return tool.execute(validatedArgs, context);
+    }
+    /** Check if a tool is registered. */
+    has(name) {
+        return this.tools.has(name);
+    }
+    /** Get a tool definition by name. */
+    get(name) {
+        return this.tools.get(name);
+    }
+}
+exports.ToolRegistry = ToolRegistry;

package/dist/context/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @ks-data/agent-core — context module entry point.
+ *
+ * Provides truncation and token estimation utilities for managing
+ * LLM input size within token budgets.
+ */
+export { ASCII_TOKENS_PER_CHAR, NON_ASCII_TOKENS_PER_CHAR, MSG_OVERHEAD_TOKENS, DEFAULT_CHARS_PER_TOKEN, estimateTextTokens, estimateTokenCountSync, estimateTokenCountForText, calculateTokenCount, type TokenEstimationPart, } 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/index.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * @ks-data/agent-core — context module entry point.
+ *
+ * Provides truncation and token estimation utilities for managing
+ * LLM input size within token budgets.
+ */
+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/context/tokenCalculation.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Token estimation constants — ported from gemini-cli (Apache-2.0).
+ *
+ * ASCII characters (0-127) are roughly 3-4 chars per token.
+ * We use 0.33 (~3 chars/token) as a conservative baseline for mixed text and code.
+ */
+export declare const ASCII_TOKENS_PER_CHAR = 0.33;
+/**
+ * Non-ASCII characters (including CJK) are often 1-2 tokens per char.
+ * We use 1.5 as a conservative estimate to avoid underestimation.
+ */
+export declare const NON_ASCII_TOKENS_PER_CHAR = 1.5;
+/** Structural overhead per message turn (role prefixes, separators). */
+export declare const MSG_OVERHEAD_TOKENS = 5;
+/** Default chars-per-token ratio used as fallback. */
+export declare const DEFAULT_CHARS_PER_TOKEN = 4;
+/**
+ * Heuristic estimation of tokens for a text string.
+ * Uses char-by-char scan for strings ≤ 100K chars, length/charsPerToken for larger strings.
+ */
+export declare function estimateTextTokens(text: string, charsPerToken?: number): number;
+/**
+ * Synchronous token-count estimation for an array of message-like parts.
+ * Adapted from gemini-cli's `estimateTokenCountSync`, but uses our own
+ * message-part representation instead of Gemini's `Part` type.
+ *
+ * Each "part" can be:
+ *   - `{ text: string }`          → text token estimation
+ *   - `{ functionResponse: ... }` → tool response estimation
+ *   - other objects               → JSON string length / charsPerToken fallback
+ */
+export interface TokenEstimationPart {
+    text?: string;
+    functionResponse?: {
+        name?: string;
+        response?: unknown;
+    };
+    [key: string]: unknown;
+}
+export declare function estimateTokenCountSync(parts: TokenEstimationPart[], charsPerToken?: number): number;
+/**
+ * Asynchronous token count calculation for a text string or message array.
+ * For text-only content, this simply delegates to `estimateTokenCountSync`.
+ * For content with media references (future: image/PDF), we would call
+ * an external tokenizer — but for now, everything is text-only estimation.
+ *
+ * This replaces gemini-cli's `calculateRequestTokenCount` which uses
+ * the Gemini `countTokens` API. We don't have an equivalent API for
+ * our internal OpenAI-compatible proxy, so we rely on heuristic estimation.
+ */
+export declare function calculateTokenCount(content: string | TokenEstimationPart[], charsPerToken?: number): Promise<number>;
+/**
+ * Convenience: estimate token count for a single text string.
+ */
+export declare function estimateTokenCountForText(text: string, charsPerToken?: number): number;

package/dist/context/tokenCalculation.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CHARS_PER_TOKEN = exports.MSG_OVERHEAD_TOKENS = exports.NON_ASCII_TOKENS_PER_CHAR = exports.ASCII_TOKENS_PER_CHAR = void 0;
+exports.estimateTextTokens = estimateTextTokens;
+exports.estimateTokenCountSync = estimateTokenCountSync;
+exports.calculateTokenCount = calculateTokenCount;
+exports.estimateTokenCountForText = estimateTokenCountForText;
+/**
+ * Token estimation constants — ported from gemini-cli (Apache-2.0).
+ *
+ * ASCII characters (0-127) are roughly 3-4 chars per token.
+ * We use 0.33 (~3 chars/token) as a conservative baseline for mixed text and code.
+ */
+exports.ASCII_TOKENS_PER_CHAR = 0.33;
+/**
+ * Non-ASCII characters (including CJK) are often 1-2 tokens per char.
+ * We use 1.5 as a conservative estimate to avoid underestimation.
+ */
+exports.NON_ASCII_TOKENS_PER_CHAR = 1.5;
+/** Structural overhead per message turn (role prefixes, separators). */
+exports.MSG_OVERHEAD_TOKENS = 5;
+/** Default chars-per-token ratio used as fallback. */
+exports.DEFAULT_CHARS_PER_TOKEN = 4;
+/**
+ * Maximum number of characters to process with the full character-by-character heuristic.
+ * Above this, we use a faster approximation to avoid performance bottlenecks.
+ */
+const MAX_CHARS_FOR_FULL_HEURISTIC = 100_000;
+/**
+ * Heuristic estimation of tokens for a text string.
+ * Uses char-by-char scan for strings ≤ 100K chars, length/charsPerToken for larger strings.
+ */
+function estimateTextTokens(text, charsPerToken = exports.DEFAULT_CHARS_PER_TOKEN) {
+    if (text.length > MAX_CHARS_FOR_FULL_HEURISTIC) {
+        return text.length / charsPerToken;
+    }
+    let tokens = 0;
+    const asciiTokensPerChar = 1 / charsPerToken;
+    for (let i = 0; i < text.length; i++) {
+        if (text.charCodeAt(i) <= 127) {
+            tokens += asciiTokensPerChar;
+        }
+        else {
+            tokens += exports.NON_ASCII_TOKENS_PER_CHAR;
+        }
+    }
+    return tokens;
+}
+function estimateTokenCountSync(parts, charsPerToken = exports.DEFAULT_CHARS_PER_TOKEN) {
+    let totalTokens = 0;
+    for (const part of parts) {
+        if (typeof part.text === 'string') {
+            totalTokens += estimateTextTokens(part.text, charsPerToken);
+        }
+        else if (part.functionResponse) {
+            const fr = part.functionResponse;
+            let frTokens = (fr.name?.length ?? 0) / charsPerToken;
+            const response = fr.response;
+            if (typeof response === 'string') {
+                frTokens += response.length / charsPerToken;
+            }
+            else if (response !== undefined && response !== null) {
+                frTokens += JSON.stringify(response).length / charsPerToken;
+            }
+            totalTokens += frTokens;
+        }
+        else {
+            // Fallback: JSON-serialize the whole part and estimate by length.
+            totalTokens += JSON.stringify(part).length / charsPerToken;
+        }
+    }
+    return Math.floor(totalTokens);
+}
+/**
+ * Asynchronous token count calculation for a text string or message array.
+ * For text-only content, this simply delegates to `estimateTokenCountSync`.
+ * For content with media references (future: image/PDF), we would call
+ * an external tokenizer — but for now, everything is text-only estimation.
+ *
+ * This replaces gemini-cli's `calculateRequestTokenCount` which uses
+ * the Gemini `countTokens` API. We don't have an equivalent API for
+ * our internal OpenAI-compatible proxy, so we rely on heuristic estimation.
+ */
+async function calculateTokenCount(content, charsPerToken = exports.DEFAULT_CHARS_PER_TOKEN) {
+    if (typeof content === 'string') {
+        return estimateTokenCountSync([{ text: content }], charsPerToken);
+    }
+    return estimateTokenCountSync(content, charsPerToken);
+}
+/**
+ * Convenience: estimate token count for a single text string.
+ */
+function estimateTokenCountForText(text, charsPerToken = exports.DEFAULT_CHARS_PER_TOKEN) {
+    return Math.floor(estimateTextTokens(text, charsPerToken));
+}

package/dist/context/truncation.d.ts

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

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

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

@@ -0,0 +1,27 @@
+"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/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Core module — runtime infrastructure for the agent
+ *
+ * Layers:
+ * - llm/     — OpenAI-compatible LLM client (invoke + chat)
+ * - context/ — Token calculation + truncation (from gemini-cli)
+ * - agent-loop/ — Universal agent execution engine (while loop + LLM + tools)
+ * - skill/   — SKILL.md discovery, loading, and execution (Progressive Disclosure)
+ * - tools/   — Built-in tool library (bash, codegraph, git, keve-read-doc, etc.)
+ */
+export { LLM, InvokeError, InvokeErrorType } from './llm/index';
+export type { ChatResult, ContentItem, InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool, } from './llm/index';
+export { estimateCharsFromTokens, truncateProportionally, normalizeFunctionResponse, estimateTokenCountSync, } from './context/index';
+export type { TokenEstimationPart } from './context/index';
+export { AgentLoop } from './agent-loop/index';
+export type { AgentDefinition, AgentEvent, AgentEventCallback, AgentLoopContext, AgentResult, AgentTerminateMode, ToolDefinition, } from './agent-loop/index';
+export { COMPLETE_TASK_TOOL_NAME, DEFAULT_MAX_TURNS, DEFAULT_MAX_TIME_MINUTES, createCompleteTaskTool, ToolRegistry, detectRuntimeEnvironment, } from './agent-loop/index';
+export type { RuntimeEnvironment, ToolExecutionContext, CompleteTaskToolOptions } from './agent-loop/index';
+export { AgentLoader, AgentFactory } from './agent/index';
+export type { AgentRegistryDefinition } from './agent/index';
+export { SkillLoader } from './skill/index';
+export type { SkillDefinition } from './skill/index';
+export { createDefaultToolRegistry, getBuiltinToolNames } from './tools/index';

package/dist/index.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Core module — runtime infrastructure for the agent
+ *
+ * Layers:
+ * - llm/     — OpenAI-compatible LLM client (invoke + chat)
+ * - context/ — Token calculation + truncation (from gemini-cli)
+ * - agent-loop/ — Universal agent execution engine (while loop + LLM + tools)
+ * - skill/   — SKILL.md discovery, loading, and execution (Progressive Disclosure)
+ * - tools/   — Built-in tool library (bash, codegraph, git, keve-read-doc, etc.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBuiltinToolNames = exports.createDefaultToolRegistry = exports.SkillLoader = exports.AgentFactory = exports.AgentLoader = exports.detectRuntimeEnvironment = exports.ToolRegistry = exports.createCompleteTaskTool = exports.DEFAULT_MAX_TIME_MINUTES = exports.DEFAULT_MAX_TURNS = exports.COMPLETE_TASK_TOOL_NAME = exports.AgentLoop = exports.estimateTokenCountSync = exports.normalizeFunctionResponse = exports.truncateProportionally = exports.estimateCharsFromTokens = exports.InvokeErrorType = exports.InvokeError = exports.LLM = void 0;
+// LLM
+var index_1 = require("./llm/index");
+Object.defineProperty(exports, "LLM", { enumerable: true, get: function () { return index_1.LLM; } });
+Object.defineProperty(exports, "InvokeError", { enumerable: true, get: function () { return index_1.InvokeError; } });
+Object.defineProperty(exports, "InvokeErrorType", { enumerable: true, get: function () { return index_1.InvokeErrorType; } });
+// Context
+var index_2 = require("./context/index");
+Object.defineProperty(exports, "estimateCharsFromTokens", { enumerable: true, get: function () { return index_2.estimateCharsFromTokens; } });
+Object.defineProperty(exports, "truncateProportionally", { enumerable: true, get: function () { return index_2.truncateProportionally; } });
+Object.defineProperty(exports, "normalizeFunctionResponse", { enumerable: true, get: function () { return index_2.normalizeFunctionResponse; } });
+Object.defineProperty(exports, "estimateTokenCountSync", { enumerable: true, get: function () { return index_2.estimateTokenCountSync; } });
+// Agent Loop
+var index_3 = require("./agent-loop/index");
+Object.defineProperty(exports, "AgentLoop", { enumerable: true, get: function () { return index_3.AgentLoop; } });
+var index_4 = require("./agent-loop/index");
+Object.defineProperty(exports, "COMPLETE_TASK_TOOL_NAME", { enumerable: true, get: function () { return index_4.COMPLETE_TASK_TOOL_NAME; } });
+Object.defineProperty(exports, "DEFAULT_MAX_TURNS", { enumerable: true, get: function () { return index_4.DEFAULT_MAX_TURNS; } });
+Object.defineProperty(exports, "DEFAULT_MAX_TIME_MINUTES", { enumerable: true, get: function () { return index_4.DEFAULT_MAX_TIME_MINUTES; } });
+Object.defineProperty(exports, "createCompleteTaskTool", { enumerable: true, get: function () { return index_4.createCompleteTaskTool; } });
+Object.defineProperty(exports, "ToolRegistry", { enumerable: true, get: function () { return index_4.ToolRegistry; } });
+Object.defineProperty(exports, "detectRuntimeEnvironment", { enumerable: true, get: function () { return index_4.detectRuntimeEnvironment; } });
+// Agent
+var index_5 = require("./agent/index");
+Object.defineProperty(exports, "AgentLoader", { enumerable: true, get: function () { return index_5.AgentLoader; } });
+Object.defineProperty(exports, "AgentFactory", { enumerable: true, get: function () { return index_5.AgentFactory; } });
+// Skill
+var index_6 = require("./skill/index");
+Object.defineProperty(exports, "SkillLoader", { enumerable: true, get: function () { return index_6.SkillLoader; } });
+// Tools (general tools, aligned with gemini-cli)
+var index_7 = require("./tools/index");
+Object.defineProperty(exports, "createDefaultToolRegistry", { enumerable: true, get: function () { return index_7.createDefaultToolRegistry; } });
+Object.defineProperty(exports, "getBuiltinToolNames", { enumerable: true, get: function () { return index_7.getBuiltinToolNames; } });

package/dist/llm/OpenAIClient.d.ts

@@ -0,0 +1,31 @@
+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>;
+}