@kaitranntt/ccs 7.31.1 → 7.32.0

package/dist/cliproxy/tool-name-sanitizer.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Tool Name Sanitizer
+ *
+ * Sanitizes MCP tool names to comply with Gemini API constraints:
+ * - Max 64 characters
+ * - Must start with letter or underscore
+ * - Only a-z A-Z 0-9 _ . : - / allowed
+ *
+ * Strategies:
+ * 1. Remove duplicate segments (e.g., gitmcp__foo__foo → gitmcp__foo)
+ * 2. Smart truncate with hash suffix if still >64 chars
+ *
+ * Note: Hash collision risk is ~1 in 16M with 6-char MD5 prefix.
+ * Acceptable for typical MCP tool counts (<1000 tools).
+ */
+/** Maximum tool name length allowed by Gemini API */
+export declare const GEMINI_MAX_TOOL_NAME_LENGTH = 64;
+/** Result of sanitization operation */
+export interface SanitizeResult {
+    /** The sanitized tool name */
+    sanitized: string;
+    /** Whether the name was changed */
+    changed: boolean;
+}
+/**
+ * Check if a tool name is valid for Gemini API.
+ *
+ * Requirements:
+ * - Length <= 64 characters
+ * - Starts with letter or underscore
+ * - Contains only valid characters: a-z A-Z 0-9 _ . : -
+ */
+export declare function isValidToolName(name: string): boolean;
+/**
+ * Remove consecutive duplicate segments separated by '__'.
+ *
+ * Examples:
+ * - 'gitmcp__foo__foo' → 'gitmcp__foo'
+ * - 'a__b__c__b__c' → 'a__b__c'
+ * - 'no_dupes' → 'no_dupes'
+ */
+export declare function removeDuplicateSegments(name: string): string;
+/**
+ * Smart truncate a name to fit within maxLen.
+ * Preserves start of name and appends hash suffix for uniqueness.
+ *
+ * Format: <prefix>_<6-char-hash>
+ *
+ * @param name The name to truncate
+ * @param maxLen Maximum allowed length (default: 64)
+ */
+export declare function smartTruncate(name: string, maxLen?: number): string;
+/**
+ * Sanitize a tool name to comply with Gemini API constraints.
+ *
+ * Process:
+ * 1. Remove duplicate segments (always, as duplicates are likely unintentional)
+ * 2. Truncate with hash if >64 chars
+ * 3. Return result with changed flag
+ *
+ * @param name The original tool name
+ * @returns Sanitization result with sanitized name and changed flag
+ */
+export declare function sanitizeToolName(name: string): SanitizeResult;
+//# sourceMappingURL=tool-name-sanitizer.d.ts.map

package/dist/cliproxy/tool-name-sanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-name-sanitizer.d.ts","sourceRoot":"","sources":["../../src/cliproxy/tool-name-sanitizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,qDAAqD;AACrD,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAK9C,uCAAuC;AACvC,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAQrD;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAY5D;AAUD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAoC,GAAG,MAAM,CAWhG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAmB7D"}

package/dist/cliproxy/tool-name-sanitizer.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * Tool Name Sanitizer
+ *
+ * Sanitizes MCP tool names to comply with Gemini API constraints:
+ * - Max 64 characters
+ * - Must start with letter or underscore
+ * - Only a-z A-Z 0-9 _ . : - / allowed
+ *
+ * Strategies:
+ * 1. Remove duplicate segments (e.g., gitmcp__foo__foo → gitmcp__foo)
+ * 2. Smart truncate with hash suffix if still >64 chars
+ *
+ * Note: Hash collision risk is ~1 in 16M with 6-char MD5 prefix.
+ * Acceptable for typical MCP tool counts (<1000 tools).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeToolName = exports.smartTruncate = exports.removeDuplicateSegments = exports.isValidToolName = exports.GEMINI_MAX_TOOL_NAME_LENGTH = void 0;
+const crypto_1 = require("crypto");
+/** Maximum tool name length allowed by Gemini API */
+exports.GEMINI_MAX_TOOL_NAME_LENGTH = 64;
+/** Valid characters pattern for Gemini tool names */
+const VALID_CHARS_REGEX = /^[a-zA-Z_][a-zA-Z0-9_.:/-]*$/;
+/**
+ * Check if a tool name is valid for Gemini API.
+ *
+ * Requirements:
+ * - Length <= 64 characters
+ * - Starts with letter or underscore
+ * - Contains only valid characters: a-z A-Z 0-9 _ . : -
+ */
+function isValidToolName(name) {
+    if (!name || name.length === 0) {
+        return false;
+    }
+    if (name.length > exports.GEMINI_MAX_TOOL_NAME_LENGTH) {
+        return false;
+    }
+    return VALID_CHARS_REGEX.test(name);
+}
+exports.isValidToolName = isValidToolName;
+/**
+ * Remove consecutive duplicate segments separated by '__'.
+ *
+ * Examples:
+ * - 'gitmcp__foo__foo' → 'gitmcp__foo'
+ * - 'a__b__c__b__c' → 'a__b__c'
+ * - 'no_dupes' → 'no_dupes'
+ */
+function removeDuplicateSegments(name) {
+    const segments = name.split('__');
+    const deduped = [];
+    for (const segment of segments) {
+        // Only add if different from previous segment
+        if (deduped.length === 0 || deduped[deduped.length - 1] !== segment) {
+            deduped.push(segment);
+        }
+    }
+    return deduped.join('__');
+}
+exports.removeDuplicateSegments = removeDuplicateSegments;
+/**
+ * Generate a short hash from a string for truncation suffix.
+ * Uses first 6 characters of MD5 hash (16M combinations).
+ */
+function generateShortHash(input) {
+    return (0, crypto_1.createHash)('md5').update(input).digest('hex').slice(0, 6);
+}
+/**
+ * Smart truncate a name to fit within maxLen.
+ * Preserves start of name and appends hash suffix for uniqueness.
+ *
+ * Format: <prefix>_<6-char-hash>
+ *
+ * @param name The name to truncate
+ * @param maxLen Maximum allowed length (default: 64)
+ */
+function smartTruncate(name, maxLen = exports.GEMINI_MAX_TOOL_NAME_LENGTH) {
+    if (name.length <= maxLen) {
+        return name;
+    }
+    // Format: prefix + '_' + 6-char hash = 7 chars for suffix
+    const hash = generateShortHash(name);
+    const prefixLen = maxLen - 7; // 7 = '_' (1) + hash (6)
+    const prefix = name.slice(0, prefixLen);
+    return `${prefix}_${hash}`;
+}
+exports.smartTruncate = smartTruncate;
+/**
+ * Sanitize a tool name to comply with Gemini API constraints.
+ *
+ * Process:
+ * 1. Remove duplicate segments (always, as duplicates are likely unintentional)
+ * 2. Truncate with hash if >64 chars
+ * 3. Return result with changed flag
+ *
+ * @param name The original tool name
+ * @returns Sanitization result with sanitized name and changed flag
+ */
+function sanitizeToolName(name) {
+    // Step 1: Always try to remove duplicate segments
+    // Duplicates like gitmcp__foo__foo are likely unintentional from MCP naming
+    let sanitized = removeDuplicateSegments(name);
+    // Step 2: Truncate if still too long
+    if (sanitized.length > exports.GEMINI_MAX_TOOL_NAME_LENGTH) {
+        sanitized = smartTruncate(sanitized);
+    }
+    // Step 3: If still invalid after sanitization, apply truncation to original
+    if (!isValidToolName(sanitized)) {
+        sanitized = smartTruncate(name);
+    }
+    return {
+        sanitized,
+        changed: sanitized !== name,
+    };
+}
+exports.sanitizeToolName = sanitizeToolName;
+//# sourceMappingURL=tool-name-sanitizer.js.map

package/dist/cliproxy/tool-name-sanitizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-name-sanitizer.js","sourceRoot":"","sources":["../../src/cliproxy/tool-name-sanitizer.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAEH,mCAAoC;AAEpC,qDAAqD;AACxC,QAAA,2BAA2B,GAAG,EAAE,CAAC;AAE9C,qDAAqD;AACrD,MAAM,iBAAiB,GAAG,8BAA8B,CAAC;AAUzD;;;;;;;GAOG;AACH,SAAgB,eAAe,CAAC,IAAY;IAC1C,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,GAAG,mCAA2B,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACtC,CAAC;AARD,0CAQC;AAED;;;;;;;GAOG;AACH,SAAgB,uBAAuB,CAAC,IAAY;IAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,8CAA8C;QAC9C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,OAAO,EAAE,CAAC;YACpE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAZD,0DAYC;AAED;;;GAGG;AACH,SAAS,iBAAiB,CAAC,KAAa;IACtC,OAAO,IAAA,mBAAU,EAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,aAAa,CAAC,IAAY,EAAE,SAAiB,mCAA2B;IACtF,IAAI,IAAI,CAAC,MAAM,IAAI,MAAM,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,0DAA0D;IAC1D,MAAM,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,SAAS,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,yBAAyB;IACvD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IAExC,OAAO,GAAG,MAAM,IAAI,IAAI,EAAE,CAAC;AAC7B,CAAC;AAXD,sCAWC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,gBAAgB,CAAC,IAAY;IAC3C,kDAAkD;IAClD,4EAA4E;IAC5E,IAAI,SAAS,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAC;IAE9C,qCAAqC;IACrC,IAAI,SAAS,CAAC,MAAM,GAAG,mCAA2B,EAAE,CAAC;QACnD,SAAS,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;IAED,4EAA4E;IAC5E,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC,EAAE,CAAC;QAChC,SAAS,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,OAAO;QACL,SAAS;QACT,OAAO,EAAE,SAAS,KAAK,IAAI;KAC5B,CAAC;AACJ,CAAC;AAnBD,4CAmBC"}

package/dist/cliproxy/tool-sanitization-proxy.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Tool Sanitization Proxy
+ *
+ * HTTP proxy that intercepts Claude CLI → CLIProxy requests to:
+ * 1. Sanitize MCP tool names exceeding Gemini's 64-char limit
+ * 2. Forward sanitized requests to upstream
+ * 3. Restore original names in responses
+ *
+ * Follows CodexReasoningProxy pattern for consistency.
+ */
+export interface ToolSanitizationProxyConfig {
+    /** Upstream CLIProxy URL */
+    upstreamBaseUrl: string;
+    /** Enable verbose logging */
+    verbose?: boolean;
+    /** Log warnings when sanitization occurs */
+    warnOnSanitize?: boolean;
+    /** Request timeout in milliseconds */
+    timeoutMs?: number;
+}
+export declare class ToolSanitizationProxy {
+    private server;
+    private port;
+    private readonly config;
+    private readonly logFilePath;
+    private readonly debugMode;
+    constructor(config: ToolSanitizationProxyConfig);
+    /**
+     * Initialize log file path and ensure directory exists.
+     */
+    private initLogFile;
+    /**
+     * Write log entry to file (always) and console (if CCS_DEBUG=1).
+     */
+    private writeLog;
+    private log;
+    private warn;
+    /**
+     * Start the proxy server on an ephemeral port.
+     * @returns The assigned port number
+     */
+    start(): Promise<number>;
+    /**
+     * Stop the proxy server.
+     */
+    stop(): void;
+    /**
+     * Get the port the proxy is listening on.
+     */
+    getPort(): number | null;
+    private readBody;
+    private handleRequest;
+    private buildForwardHeaders;
+    private getRequestFn;
+    private forwardRaw;
+    /**
+     * Forward JSON request and buffer response for tool name restoration.
+     */
+    private forwardJsonBuffered;
+    /**
+     * Forward JSON request and stream response with tool name restoration.
+     * Handles SSE (Server-Sent Events) format.
+     */
+    private forwardJsonStreaming;
+    /**
+     * Process a single SSE event, restoring tool names if present.
+     */
+    private processSSEEvent;
+}
+//# sourceMappingURL=tool-sanitization-proxy.d.ts.map

package/dist/cliproxy/tool-sanitization-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-sanitization-proxy.d.ts","sourceRoot":"","sources":["../../src/cliproxy/tool-sanitization-proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH,MAAM,WAAW,2BAA2B;IAC1C,4BAA4B;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,6BAA6B;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4CAA4C;IAC5C,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAUD,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,IAAI,CAAuB;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAC/D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;gBAExB,MAAM,EAAE,2BAA2B;IAW/C;;OAEG;IACH,OAAO,CAAC,WAAW;IAoBnB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAkBhB,OAAO,CAAC,GAAG;IAMX,OAAO,CAAC,IAAI;IAMZ;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAmB9B;;OAEG;IACH,IAAI,IAAI,IAAI;IAOZ;;OAEG;IACH,OAAO,IAAI,MAAM,GAAG,IAAI;IAIxB,OAAO,CAAC,QAAQ;YAqBF,aAAa;IA6E3B,OAAO,CAAC,mBAAmB;IAmC3B,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,UAAU;IA+BlB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAsE3B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAsE5B;;OAEG;IACH,OAAO,CAAC,eAAe;CAqDxB"}