@vybestack/llxprt-code-tools 0.10.0-nightly.260613.1adad3b34

package/dist/src/utils/tool-key-storage-facade.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @plan:PLAN-20260608-ISSUE1585.P11
+ * @requirement:REQ-API-001, REQ-TEMPORARY-INTERFACES
+ */
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IToolKeyStorage } from '../interfaces/IToolKeyStorage.js';
+import { type ToolKeyRegistryEntry } from './tool-key-storage-types.js';
+/**
+ * Tools-package facade over an injected tool-key storage implementation.
+ *
+ * The concrete persistence mechanism remains outside packages/tools. Core
+ * supplies SecureStore-backed persistence through CoreToolKeyStorageAdapter,
+ * while tools own registry metadata, display helpers, and this stable boundary.
+ */
+export declare class ToolKeyStorageFacade implements IToolKeyStorage {
+    private readonly storage;
+    constructor(storage: IToolKeyStorage);
+    saveKey(toolName: string, key: string): Promise<void>;
+    getKey(toolName: string): Promise<string | null>;
+    deleteKey(toolName: string): Promise<void>;
+    hasKey(toolName: string): Promise<boolean>;
+    resolveKey(toolName: string): Promise<string | null>;
+    maskKeyForDisplay(key: string): string;
+    getSupportedToolNames(): string[];
+    getToolKeyEntry(toolName: string): ToolKeyRegistryEntry | undefined;
+    isValidToolKeyName(toolName: string): boolean;
+    private assertSupportedTool;
+}

package/dist/src/utils/tool-key-storage-facade.js

@@ -0,0 +1,56 @@
+/**
+ * @plan:PLAN-20260608-ISSUE1585.P11
+ * @requirement:REQ-API-001, REQ-TEMPORARY-INTERFACES
+ */
+import { getSupportedToolNames, getToolKeyEntry, isValidToolKeyName, maskKeyForDisplay, } from './tool-key-storage-types.js';
+/**
+ * Tools-package facade over an injected tool-key storage implementation.
+ *
+ * The concrete persistence mechanism remains outside packages/tools. Core
+ * supplies SecureStore-backed persistence through CoreToolKeyStorageAdapter,
+ * while tools own registry metadata, display helpers, and this stable boundary.
+ */
+export class ToolKeyStorageFacade {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    async saveKey(toolName, key) {
+        this.assertSupportedTool(toolName);
+        await this.storage.saveKey(toolName, key);
+    }
+    async getKey(toolName) {
+        this.assertSupportedTool(toolName);
+        return this.storage.getKey(toolName);
+    }
+    async deleteKey(toolName) {
+        this.assertSupportedTool(toolName);
+        await this.storage.deleteKey(toolName);
+    }
+    async hasKey(toolName) {
+        this.assertSupportedTool(toolName);
+        return this.storage.hasKey(toolName);
+    }
+    async resolveKey(toolName) {
+        this.assertSupportedTool(toolName);
+        return this.storage.resolveKey(toolName);
+    }
+    maskKeyForDisplay(key) {
+        return maskKeyForDisplay(key);
+    }
+    getSupportedToolNames() {
+        return getSupportedToolNames();
+    }
+    getToolKeyEntry(toolName) {
+        return getToolKeyEntry(toolName);
+    }
+    isValidToolKeyName(toolName) {
+        return isValidToolKeyName(toolName);
+    }
+    assertSupportedTool(toolName) {
+        if (!isValidToolKeyName(toolName)) {
+            throw new Error(`Unsupported tool key storage name: ${toolName}`);
+        }
+    }
+}
+//# sourceMappingURL=tool-key-storage-facade.js.map

package/dist/src/utils/tool-key-storage-facade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-key-storage-facade.js","sourceRoot":"","sources":["../../../src/utils/tool-key-storage-facade.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,iBAAiB,GAElB,MAAM,6BAA6B,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,OAAO,oBAAoB;IACF;IAA7B,YAA6B,OAAwB;QAAxB,YAAO,GAAP,OAAO,CAAiB;IAAG,CAAC;IAEzD,KAAK,CAAC,OAAO,CAAC,QAAgB,EAAE,GAAW;QACzC,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;QACnC,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,QAAgB;QAC3B,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,QAAgB;QAC9B,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;QACnC,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,QAAgB;QAC3B,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,QAAgB;QAC/B,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED,iBAAiB,CAAC,GAAW;QAC3B,OAAO,iBAAiB,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAED,qBAAqB;QACnB,OAAO,qBAAqB,EAAE,CAAC;IACjC,CAAC;IAED,eAAe,CAAC,QAAgB;QAC9B,OAAO,eAAe,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IAED,kBAAkB,CAAC,QAAgB;QACjC,OAAO,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;IAEO,mBAAmB,CAAC,QAAgB;QAC1C,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,sCAAsC,QAAQ,EAAE,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;CACF"}

package/dist/src/utils/tool-key-storage-types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @plan:PLAN-20260608-ISSUE1585.P05
+ * @requirement:REQ-API-001, REQ-TEMPORARY-INTERFACES
+ */
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Package-local tool key storage types and pure-utility helpers.
+ *
+ * Provides the registry metadata types and display helpers needed by
+ * tool-key-storage, codesearch, exa-web-search, and google-web-search.
+ * The actual ToolKeyStorage class with SecureStore integration remains
+ * in core. Self-contained with zero core imports.
+ */
+/** Metadata about a registered tool key. */
+export interface ToolKeyRegistryEntry {
+    /** The key used to reference the tool (e.g., 'exa'). */
+    toolKeyName: string;
+    /** Human-readable display name (e.g., 'Exa Search'). */
+    displayName: string;
+    /** URL parameter name for API key. */
+    urlParamName: string;
+    /** Description of the key's purpose. */
+    description: string;
+}
+/**
+ * Registry of supported tool keys and their metadata.
+ */
+export declare const TOOL_KEY_REGISTRY: Map<string, ToolKeyRegistryEntry>;
+/**
+ * Checks if a tool name is a valid key storage name.
+ * @param toolName - The tool name to check.
+ * @returns true if the tool name has a registered entry.
+ */
+export declare function isValidToolKeyName(toolName: string): boolean;
+/**
+ * Gets the registry entry for a tool key name.
+ * @param toolName - The tool name to look up.
+ * @returns The registry entry, or undefined if not found.
+ */
+export declare function getToolKeyEntry(toolName: string): ToolKeyRegistryEntry | undefined;
+/**
+ * Returns the list of all supported tool key names.
+ * @returns Array of supported tool key name strings.
+ */
+export declare function getSupportedToolNames(): string[];
+/**
+ * Masks an API key for safe display, showing only first 2 and last 2 characters.
+ * Keys of 8 characters or fewer are fully masked.
+ * @param key - The API key to mask.
+ * @returns The masked key string.
+ */
+export declare function maskKeyForDisplay(key: string): string;

package/dist/src/utils/tool-key-storage-types.js

@@ -0,0 +1,56 @@
+/**
+ * @plan:PLAN-20260608-ISSUE1585.P05
+ * @requirement:REQ-API-001, REQ-TEMPORARY-INTERFACES
+ */
+/**
+ * Registry of supported tool keys and their metadata.
+ */
+export const TOOL_KEY_REGISTRY = new Map([
+    [
+        'exa',
+        {
+            toolKeyName: 'exa',
+            displayName: 'Exa Search',
+            urlParamName: 'exaApiKey',
+            description: 'API key for Exa web and code search',
+        },
+    ],
+]);
+/**
+ * Checks if a tool name is a valid key storage name.
+ * @param toolName - The tool name to check.
+ * @returns true if the tool name has a registered entry.
+ */
+export function isValidToolKeyName(toolName) {
+    return TOOL_KEY_REGISTRY.has(toolName);
+}
+/**
+ * Gets the registry entry for a tool key name.
+ * @param toolName - The tool name to look up.
+ * @returns The registry entry, or undefined if not found.
+ */
+export function getToolKeyEntry(toolName) {
+    return TOOL_KEY_REGISTRY.get(toolName);
+}
+/**
+ * Returns the list of all supported tool key names.
+ * @returns Array of supported tool key name strings.
+ */
+export function getSupportedToolNames() {
+    return Array.from(TOOL_KEY_REGISTRY.keys());
+}
+/**
+ * Masks an API key for safe display, showing only first 2 and last 2 characters.
+ * Keys of 8 characters or fewer are fully masked.
+ * @param key - The API key to mask.
+ * @returns The masked key string.
+ */
+export function maskKeyForDisplay(key) {
+    if (key.length <= 8)
+        return '*'.repeat(key.length);
+    const first2 = key.substring(0, 2);
+    const last2 = key.substring(key.length - 2);
+    const middle = '*'.repeat(key.length - 4);
+    return `${first2}${middle}${last2}`;
+}
+//# sourceMappingURL=tool-key-storage-types.js.map

package/dist/src/utils/tool-key-storage-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-key-storage-types.js","sourceRoot":"","sources":["../../../src/utils/tool-key-storage-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA6BH;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAA+B;IACrE;QACE,KAAK;QACL;YACE,WAAW,EAAE,KAAK;YAClB,WAAW,EAAE,YAAY;YACzB,YAAY,EAAE,WAAW;YACzB,WAAW,EAAE,qCAAqC;SACnD;KACF;CACF,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,OAAO,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAgB;IAEhB,OAAO,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AACzC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC1C,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,EAAE,CAAC;AACtC,CAAC"}

package/dist/src/utils/toolOutputLimiter.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2025 Vybestack LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export interface ToolOutputSettingsProvider {
+    getEphemeralSettings(): Record<string, unknown>;
+}
+export declare const DEFAULT_MAX_TOKENS = 50000;
+export declare const DEFAULT_TRUNCATE_MODE = "warn";
+export declare const ESCAPE_BUFFER_PERCENTAGE = 0.8;
+export interface TruncatedOutput {
+    content: string;
+    wasTruncated: boolean;
+    originalTokens?: number;
+    message?: string;
+}
+export declare function estimateTokens(text: string): number;
+export declare function getEffectiveTokenLimit(maxTokens: number): number;
+export interface OutputLimitConfig {
+    maxTokens?: number;
+    truncateMode?: 'warn' | 'truncate' | 'sample';
+}
+export declare function getOutputLimits(config: ToolOutputSettingsProvider): OutputLimitConfig;
+export declare function limitOutputTokens(content: string, config: ToolOutputSettingsProvider, toolName: string): TruncatedOutput;
+export declare function formatLimitedOutput(result: TruncatedOutput): {
+    llmContent: string;
+    returnDisplay: string;
+};

package/dist/src/utils/toolOutputLimiter.js

@@ -0,0 +1,107 @@
+/**
+ * @license
+ * Copyright 2025 Vybestack LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export const DEFAULT_MAX_TOKENS = 50000;
+export const DEFAULT_TRUNCATE_MODE = 'warn';
+export const ESCAPE_BUFFER_PERCENTAGE = 0.8;
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 3);
+}
+export function getEffectiveTokenLimit(maxTokens) {
+    return Math.floor(maxTokens * ESCAPE_BUFFER_PERCENTAGE);
+}
+export function getOutputLimits(config) {
+    const ephemeralSettings = config.getEphemeralSettings();
+    return {
+        maxTokens: ephemeralSettings['tool-output-max-tokens'] ??
+            DEFAULT_MAX_TOKENS,
+        truncateMode: ephemeralSettings['tool-output-truncate-mode'] ?? DEFAULT_TRUNCATE_MODE,
+    };
+}
+function shouldSkipTruncation(rawMaxTokens, maxTokens, tokens, effectiveLimit) {
+    return (rawMaxTokens === false ||
+        rawMaxTokens === '' ||
+        maxTokens === 0 ||
+        Number.isNaN(maxTokens) ||
+        tokens <= effectiveLimit);
+}
+function truncateWarn(originalTokens, effectiveLimit, toolName) {
+    return {
+        content: '',
+        wasTruncated: true,
+        originalTokens,
+        message: `${toolName} output exceeded token limit (${originalTokens} > ${effectiveLimit}). The results were found but are too large to display. Please:\n1. Use more specific search patterns or file paths to narrow results\n2. Search for specific function/class names instead of generic terms\n3. Look in specific directories rather than the entire codebase\n4. Use exact match patterns when possible`,
+    };
+}
+function truncateHard(content, originalTokens, effectiveLimit) {
+    const approxChars = Math.floor(content.length * (effectiveLimit / originalTokens));
+    return {
+        content: `${content.slice(0, Math.max(0, approxChars))}\n\n[Output truncated due to token limit]`,
+        wasTruncated: true,
+        originalTokens,
+        message: `Output truncated from ${originalTokens} to ${effectiveLimit} tokens`,
+    };
+}
+function sampleLines(content, originalTokens, effectiveLimit, maxTokens) {
+    const lines = content.split('\n');
+    if (lines.length > 1) {
+        const targetLines = Math.max(1, Math.floor(effectiveLimit / 10));
+        const step = Math.ceil(lines.length / targetLines);
+        const sampledLines = [];
+        for (let i = 0; i < lines.length; i += step) {
+            const candidateLines = [...sampledLines, lines[i]];
+            if (estimateTokens(candidateLines.join('\n')) > effectiveLimit) {
+                break;
+            }
+            sampledLines.push(lines[i]);
+        }
+        if (sampledLines.length > 0) {
+            return {
+                content: sampledLines.join('\n') +
+                    `\n\n[Sampled ${sampledLines.length} of ${lines.length} lines due to token limit]`,
+                wasTruncated: true,
+                originalTokens,
+                message: `Output sampled to fit within ${maxTokens} token limit`,
+            };
+        }
+    }
+    return truncateHard(content, originalTokens, effectiveLimit);
+}
+export function limitOutputTokens(content, config, toolName) {
+    const limits = getOutputLimits(config);
+    const maxTokens = limits.maxTokens ?? DEFAULT_MAX_TOKENS;
+    const rawMaxTokens = limits.maxTokens;
+    const effectiveLimit = getEffectiveTokenLimit(maxTokens);
+    const tokens = estimateTokens(content);
+    if (shouldSkipTruncation(rawMaxTokens, maxTokens, tokens, effectiveLimit)) {
+        return { content, wasTruncated: false };
+    }
+    if (limits.truncateMode === 'warn') {
+        return truncateWarn(tokens, effectiveLimit, toolName);
+    }
+    if (limits.truncateMode === 'truncate') {
+        return truncateHard(content, tokens, effectiveLimit);
+    }
+    return sampleLines(content, tokens, effectiveLimit, limits.maxTokens);
+}
+export function formatLimitedOutput(result) {
+    if (!result.wasTruncated) {
+        return {
+            llmContent: result.content,
+            returnDisplay: result.content,
+        };
+    }
+    if (result.message && !result.content) {
+        return {
+            llmContent: result.message,
+            returnDisplay: `## Token Limit Exceeded\n\n${result.message}`,
+        };
+    }
+    return {
+        llmContent: result.content,
+        returnDisplay: result.content + (result.message ? `\n\n## Note\n${result.message}` : ''),
+    };
+}
+//# sourceMappingURL=toolOutputLimiter.js.map

package/dist/src/utils/toolOutputLimiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolOutputLimiter.js","sourceRoot":"","sources":["../../../src/utils/toolOutputLimiter.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/unicodeUtils.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * Copyright 2025 Vybestack LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Sanitizes Unicode strings by handling replacement characters and ensuring
+ * proper UTF-8 encoding for API transmission.
+ */
+/**
+ * Removes or replaces Unicode replacement characters (U+FFFD) from a string.
+ * These characters often appear when there are encoding/decoding errors.
+ *
+ * @param text The text to sanitize
+ * @param replacement What to replace U+FFFD with (default: '?')
+ * @returns The sanitized text
+ */
+export declare function sanitizeUnicodeReplacements(text: string, replacement?: string): string;
+/**
+ * Checks if a string contains Unicode replacement characters (U+FFFD).
+ *
+ * @param text The text to check
+ * @returns True if the text contains replacement characters
+ */
+export declare function hasUnicodeReplacements(text: string): boolean;
+/**
+ * Checks if a string contains characters that are unsafe for JSON serialization.
+ * This includes:
+ * - Unicode replacement characters (U+FFFD)
+ * - Unpaired surrogates (high surrogate without low, or low without high)
+ * - Control characters (except tab, newline, carriage return)
+ *
+ * @param text The text to check
+ * @returns True if the text contains JSON-unsafe characters
+ */
+export declare function hasJsonUnsafeCharacters(text: string): boolean;
+/**
+ * Ensures a string is safe for JSON serialization and API transmission.
+ * This handles various edge cases including:
+ * - Unicode replacement characters
+ * - Control characters
+ * - Invalid surrogate pairs
+ *
+ * @param text The text to make safe
+ * @returns The sanitized text
+ */
+export declare function ensureJsonSafe(text: string): string;
+/**
+ * Attempts to detect and fix common cp932 (Shift-JIS) decoding issues.
+ * This is specifically for Windows Japanese locale users.
+ *
+ * @param text The text that may have cp932 encoding issues
+ * @returns The cleaned text
+ */
+export declare function cleanCp932Artifacts(text: string): string;

package/dist/src/utils/unicodeUtils.js

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * Copyright 2025 Vybestack LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Sanitizes Unicode strings by handling replacement characters and ensuring
+ * proper UTF-8 encoding for API transmission.
+ */
+/**
+ * Removes or replaces Unicode replacement characters (U+FFFD) from a string.
+ * These characters often appear when there are encoding/decoding errors.
+ *
+ * @param text The text to sanitize
+ * @param replacement What to replace U+FFFD with (default: '?')
+ * @returns The sanitized text
+ */
+export function sanitizeUnicodeReplacements(text, replacement = '?') {
+    // U+FFFD is the Unicode replacement character
+    return text.replace(/\uFFFD/g, replacement);
+}
+/**
+ * Checks if a string contains Unicode replacement characters (U+FFFD).
+ *
+ * @param text The text to check
+ * @returns True if the text contains replacement characters
+ */
+export function hasUnicodeReplacements(text) {
+    return /\uFFFD/.test(text);
+}
+/**
+ * Checks if a string contains characters that are unsafe for JSON serialization.
+ * This includes:
+ * - Unicode replacement characters (U+FFFD)
+ * - Unpaired surrogates (high surrogate without low, or low without high)
+ * - Control characters (except tab, newline, carriage return)
+ *
+ * @param text The text to check
+ * @returns True if the text contains JSON-unsafe characters
+ */
+export function hasJsonUnsafeCharacters(text) {
+    // Check for replacement chars, unpaired surrogates, and control chars in one pass
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        // U+FFFD replacement character
+        if (code === 0xfffd)
+            return true;
+        // Control characters (except tab, newline, carriage return)
+        if (code <= 0x1f && code !== 0x09 && code !== 0x0a && code !== 0x0d)
+            return true;
+        if (code === 0x7f)
+            return true;
+        // High surrogate without matching low surrogate
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = i + 1 < text.length ? text.charCodeAt(i + 1) : 0;
+            if (next < 0xdc00 || next > 0xdfff)
+                return true;
+            i++; // skip the valid low surrogate
+        }
+        // Low surrogate without preceding high surrogate
+        else if (code >= 0xdc00 && code <= 0xdfff) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Ensures a string is safe for JSON serialization and API transmission.
+ * This handles various edge cases including:
+ * - Unicode replacement characters
+ * - Control characters
+ * - Invalid surrogate pairs
+ *
+ * @param text The text to make safe
+ * @returns The sanitized text
+ */
+export function ensureJsonSafe(text) {
+    // First, handle replacement characters
+    let safe = sanitizeUnicodeReplacements(text);
+    // Remove control characters except common ones (tab, newline, carriage return)
+    let result = '';
+    for (let i = 0; i < safe.length; i++) {
+        const char = safe[i];
+        const code = safe.charCodeAt(i);
+        // Keep tab (0x09), newline (0x0A), and carriage return (0x0D)
+        if (code === 0x09 || code === 0x0a || code === 0x0d) {
+            result += char;
+        }
+        // Skip other control characters
+        else if ((code >= 0x00 && code <= 0x1f) || code === 0x7f) {
+            continue;
+        }
+        // Keep all other characters
+        else {
+            result += char;
+        }
+    }
+    safe = result;
+    // Ensure valid UTF-16 surrogate pairs
+    // This regex matches unpaired surrogates
+    safe = safe.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, '?');
+    return safe;
+}
+/**
+ * Attempts to detect and fix common cp932 (Shift-JIS) decoding issues.
+ * This is specifically for Windows Japanese locale users.
+ *
+ * @param text The text that may have cp932 encoding issues
+ * @returns The cleaned text
+ */
+export function cleanCp932Artifacts(text) {
+    // Common cp932 decoding artifacts when incorrectly decoded as UTF-8
+    const commonArtifacts = {
+        '髮｢': '陰',
+        邨ｱ: '結',
+        繧ｳ: 'コ',
+        繝ｼ: 'ー',
+        '繝｡': 'メ',
+        繝ｳ: 'ン',
+        繝医: 'ト',
+        // Add more common patterns as discovered
+    };
+    let cleaned = text;
+    for (const [artifact, replacement] of Object.entries(commonArtifacts)) {
+        cleaned = cleaned.replace(new RegExp(artifact, 'g'), replacement);
+    }
+    return cleaned;
+}
+//# sourceMappingURL=unicodeUtils.js.map

package/dist/src/utils/unicodeUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unicodeUtils.js","sourceRoot":"","sources":["../../../src/utils/unicodeUtils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,2BAA2B,CACzC,IAAY,EACZ,cAAsB,GAAG;IAEzB,8CAA8C;IAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAY;IAClD,kFAAkF;IAClF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAEhC,+BAA+B;QAC/B,IAAI,IAAI,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC;QAEjC,4DAA4D;QAC5D,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI;YACjE,OAAO,IAAI,CAAC;QACd,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAE/B,gDAAgD;QAChD,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,EAAE,CAAC;YACrC,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC9D,IAAI,IAAI,GAAG,MAAM,IAAI,IAAI,GAAG,MAAM;gBAAE,OAAO,IAAI,CAAC;YAChD,CAAC,EAAE,CAAC,CAAC,+BAA+B;QACtC,CAAC;QACD,iDAAiD;aAC5C,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,EAAE,CAAC;YAC1C,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,uCAAuC;IACvC,IAAI,IAAI,GAAG,2BAA2B,CAAC,IAAI,CAAC,CAAC;IAE7C,+EAA+E;IAC/E,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACrB,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAEhC,8DAA8D;QAC9D,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YACpD,MAAM,IAAI,IAAI,CAAC;QACjB,CAAC;QACD,gCAAgC;aAC3B,IAAI,CAAC,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YACzD,SAAS;QACX,CAAC;QACD,4BAA4B;aACvB,CAAC;YACJ,MAAM,IAAI,IAAI,CAAC;QACjB,CAAC;IACH,CAAC;IACD,IAAI,GAAG,MAAM,CAAC;IAEd,sCAAsC;IACtC,yCAAyC;IACzC,IAAI,GAAG,IAAI,CAAC,OAAO,CACjB,yEAAyE,EACzE,GAAG,CACJ,CAAC;IAEF,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,oEAAoE;IACpE,MAAM,eAAe,GAA8B;QACjD,IAAI,EAAE,GAAG;QACT,EAAE,EAAE,GAAG;QACP,EAAE,EAAE,GAAG;QACP,EAAE,EAAE,GAAG;QACP,IAAI,EAAE,GAAG;QACT,EAAE,EAAE,GAAG;QACP,EAAE,EAAE,GAAG;QACP,yCAAyC;KAC1C,CAAC;IAEF,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,KAAK,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,CAAC;QACtE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,WAAW,CAAC,CAAC;IACpE,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@vybestack/llxprt-code-tools",
+  "version": "0.10.0-nightly.260613.1adad3b34",
+  "description": "LLxprt Code Tools — built-in tool implementations, contracts, formatters, and registry",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vybestack/llxprt-code.git"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./IToolFormatter.js": "./dist/src/formatters/IToolFormatter.js",
+    "./ToolFormatter.js": "./dist/src/formatters/ToolFormatter.js",
+    "./ToolIdStrategy.js": "./dist/src/formatters/ToolIdStrategy.js",
+    "./toolIdNormalization.js": "./dist/src/formatters/toolIdNormalization.js",
+    "./doubleEscapeUtils.js": "./dist/src/formatters/doubleEscapeUtils.js",
+    "./toolNameUtils.js": "./dist/src/formatters/toolNameUtils.js",
+    "./utils/fetch.js": {
+      "types": "./dist/src/utils/fetch.d.ts",
+      "import": "./dist/src/utils/fetch.js"
+    }
+  },
+  "scripts": {
+    "build": "node ../../scripts/build_package.js",
+    "lint": "eslint . --ext .ts,.tsx",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:ci": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@ast-grep/napi": "^0.40.5",
+    "ajv": "^8.17.1",
+    "@google/genai": "1.30.0",
+    "cheerio": "^1.1.2",
+    "diff": "^8.0.3",
+    "fast-glob": "^3.3.3",
+    "glob": "^12.0.0",
+    "html-to-text": "^9.0.5",
+    "node-fetch": "^3.3.2",
+    "shell-quote": "^1.8.3",
+    "turndown": "^7.2.2",
+    "zod": "^3.25.76",
+    "zod-to-json-schema": "^3.25.1",
+    "@ast-grep/lang-c": "^0.0.5",
+    "@ast-grep/lang-cpp": "^0.0.5",
+    "@ast-grep/lang-go": "^0.0.5",
+    "@ast-grep/lang-java": "^0.0.6",
+    "@ast-grep/lang-json": "^0.0.6",
+    "@ast-grep/lang-python": "^0.0.5",
+    "@ast-grep/lang-ruby": "^0.0.6",
+    "@ast-grep/lang-rust": "^0.0.6",
+    "@lvce-editor/ripgrep": "^1.6.0",
+    "mime-types": "^2.1.35"
+  },
+  "devDependencies": {
+    "@types/node": "^24.2.1",
+    "@vybestack/llxprt-code-test-utils": "file:../test-utils",
+    "typescript": "^5.3.3",
+    "vitest": "^3.2.4",
+    "@types/mime-types": "^3.0.1"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}