feat: implement stability fixes and enhance error handling

src/lib/antigravity/ClaudeResponseMapper.ts

@@ -7,6 +7,7 @@ import {
   Usage,
   GroundingMetadata,
 } from './types';
+import { decodeSignature } from './signature-utils';
 
 /**
  * Non-streaming response processor (Gemini -> Claude)
@@ -55,7 +56,7 @@ class NonStreamingProcessor {
   }
 
   private processPart(part: GeminiPart) {
-    const signature = part.thoughtSignature || null;
+    const signature = decodeSignature(part.thoughtSignature) || null;
 
     // 1. Handle FunctionCall
     if (part.functionCall) {

src/lib/antigravity/ClaudeStreamingMapper.ts

@@ -1,5 +1,6 @@
-import { GeminiPart, Usage, UsageMetadata, GroundingMetadata } from './types';
+import { GeminiPart, Usage, UsageMetadata } from './types';
 import { SignatureStore } from './SignatureStore';
+import { decodeSignature } from './signature-utils';
 
 type BlockType = 'None' | 'Text' | 'Thinking' | 'Function';
 
@@ -43,6 +44,8 @@ export class StreamingState {
   public webSearchQuery: string | null = null;
   public groundingChunks: any[] | null = null;
 
+  private parseErrorCount: number = 0;
+
   constructor() {}
 
   public emit(eventType: string, data: any): string {
@@ -242,6 +245,56 @@ export class StreamingState {
   public storeSignature(signature?: string) {
     this.signatures.store(signature);
   }
+  public handleParseError(rawData: string): string[] {
+    const chunks: string[] = [];
+    this.parseErrorCount++;
+
+    console.warn(
+      `[SSE-Parser] Parse error #${this.parseErrorCount}. Raw data length: ${rawData.length}`,
+    );
+
+    // Safely close current block
+    if (this.blockType !== 'None') {
+      chunks.push(...this.endBlock());
+    }
+
+    // Emit error event if too many errors
+    if (this.parseErrorCount > 3) {
+      console.error(
+        `[SSE-Parser] High error rate (${this.parseErrorCount} errors). Stream may be corrupted.`,
+      );
+      chunks.push(
+        this.emit('error', {
+          type: 'error',
+          error: {
+            type: 'network_error',
+            message: 'Unstable network connection. Please check your network or proxy settings.',
+            code: 'stream_decode_error',
+            details: {
+              error_count: this.parseErrorCount,
+              suggestion: 'Check network connection',
+            },
+          },
+        }),
+      );
+    }
+
+    return chunks;
+  }
+
+  /**
+   * Reset error state (call after recovery)
+   */
+  public resetErrorState(): void {
+    this.parseErrorCount = 0;
+  }
+
+  /**
+   * Get current error count (for monitoring)
+   */
+  public getErrorCount(): number {
+    return this.parseErrorCount;
+  }
 }
 
 /**
@@ -252,7 +305,7 @@ export class PartProcessor {
 
   public process(part: GeminiPart): string[] {
     const chunks: string[] = [];
-    const signature = part.thoughtSignature || undefined;
+    const signature = decodeSignature(part.thoughtSignature);
 
     // 1. Handle FunctionCall
     if (part.functionCall) {

src/lib/antigravity/retry-utils.ts

@@ -0,0 +1,49 @@
+/** Jitter factor: ±20% */
+const JITTER_FACTOR = 0.2;
+
+/** Maximum retry delay in milliseconds (30 seconds) */
+const MAX_DELAY_MS = 30000;
+
+/**
+ * Apply jitter to a delay value to prevent thundering herd
+ * Returns delay ± JITTER_FACTOR (e.g., 1000ms ± 20% = 800-1200ms)
+ *
+ * @param delayMs - Base delay in milliseconds
+ * @returns Jittered delay (minimum 1ms)
+ */
+export function applyJitter(delayMs: number): number {
+  if (delayMs <= 0) {
+    return 1;
+  }
+
+  const jitterRange = delayMs * JITTER_FACTOR;
+  const jitter = (Math.random() * 2 - 1) * jitterRange;
+  return Math.max(1, Math.round(delayMs + jitter));
+}
+
+/**
+ * Calculate retry delay with exponential backoff and jitter
+ *
+ * @param attempt - Current attempt number (0-indexed)
+ * @param baseMs - Base delay for first retry (default 1000ms)
+ * @returns Delay in milliseconds with jitter applied
+ */
+export function calculateRetryDelay(attempt: number, baseMs: number = 1000): number {
+  // Exponential backoff: 1s, 2s, 4s, 8s, ...
+  const exponentialDelay = baseMs * Math.pow(2, attempt);
+
+  // Cap at maximum delay
+  const cappedDelay = Math.min(exponentialDelay, MAX_DELAY_MS);
+
+  // Apply jitter
+  return applyJitter(cappedDelay);
+}
+
+/**
+ * Sleep for specified milliseconds
+ *
+ * @param ms - Milliseconds to sleep
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

src/lib/antigravity/signature-utils.ts

@@ -0,0 +1,32 @@
+import { isEmpty } from 'lodash-es';
+/**
+ * Decode Base64-encoded signature if present
+ * Gemini sends Base64, Claude expects raw string
+ *
+ * @param signature - The signature string (may be Base64 or raw)
+ * @returns Decoded signature or undefined if input is empty
+ */
+export function decodeSignature(signature: string | undefined | null): string | undefined {
+  if (isEmpty(signature)) {
+    return undefined;
+  }
+
+  try {
+    const decoded = Buffer.from(signature!, 'base64').toString('utf-8');
+
+    // Validate: Check if it looks like valid UTF-8 text
+    // If decoding produces replacement characters, it wasn't valid Base64
+    if (decoded && !decoded.includes('\ufffd') && decoded.length > 0) {
+      // Additional check: re-encode and compare to detect false positives
+      const reEncoded = Buffer.from(decoded).toString('base64');
+      if (reEncoded === signature) {
+        return decoded;
+      }
+    }
+  } catch {
+    // Not valid Base64, return as-is
+  }
+
+  // Return original if not Base64
+  return signature!;
+}

src/lib/antigravity/stream-error-utils.ts

@@ -0,0 +1,75 @@
+/**
+ * Stream Error Utilities
+ * Classifies network errors and formats user-friendly messages
+ *
+ * Problem: Technical error messages confuse users
+ * Solution: Classify errors and provide localized, actionable messages
+ */
+
+export interface ClassifiedError {
+  type: string;
+  message: string;
+}
+
+/**
+ * Classify a stream error and return user-friendly message
+ *
+ * @param error - The error object
+ * @returns Classified error with type and localized message
+ */
+export function classifyStreamError(error: Error): ClassifiedError {
+  const msg = error.message.toLowerCase();
+
+  if (msg.includes('timeout') || msg.includes('timedout')) {
+    return {
+      type: 'timeout_error',
+      message: 'Request timed out. Please check your network connection or try again later.',
+    };
+  }
+
+  if (msg.includes('econnrefused') || msg.includes('connect')) {
+    return {
+      type: 'connection_error',
+      message: 'Unable to connect to server. Please check your network.',
+    };
+  }
+
+  if (msg.includes('enotfound') || msg.includes('network') || msg.includes('dns')) {
+    return {
+      type: 'network_error',
+      message: 'Network connection failed. Please check your network settings.',
+    };
+  }
+
+  if (msg.includes('socket') || msg.includes('aborted') || msg.includes('reset')) {
+    return {
+      type: 'stream_error',
+      message: 'Data transfer interrupted. Please try again later.',
+    };
+  }
+
+  return {
+    type: 'unknown_error',
+    message: `Unknown error occurred: ${error.message.substring(0, 100)}`,
+  };
+}
+
+/**
+ * Format error as SSE event for Claude protocol
+ *
+ * @param errorType - Error type string
+ * @param message - User-friendly message
+ * @returns SSE-formatted error event string
+ */
+export function formatErrorForSSE(errorType: string, message: string): string {
+  const errorEvent = {
+    type: 'error',
+    error: {
+      type: errorType,
+      message: message,
+      code: 'stream_error',
+    },
+  };
+
+  return `event: error\ndata: ${JSON.stringify(errorEvent)}\n\n`;
+}

src/lib/antigravity/thinking-utils.ts

@@ -0,0 +1,116 @@
+/**
+ * Thinking Block Utilities
+ * Handles validation and graceful degradation of thinking blocks
+ *
+ * Problem: Invalid signatures cause thinking blocks to be dropped, losing content
+ * Solution: Validate and convert invalid blocks to text instead of dropping
+ */
+
+/** Minimum length for a valid thought signature */
+const MIN_SIGNATURE_LENGTH = 10;
+
+export interface ThinkingBlock {
+  type: 'thinking';
+  thinking: string;
+  signature?: string;
+}
+
+export interface TextBlock {
+  type: 'text';
+  text: string;
+}
+
+export type ContentBlock = ThinkingBlock | TextBlock | { type: string; [key: string]: any };
+
+/**
+ * Check if a thinking block has a valid signature
+ *
+ * Rules:
+ * - Empty thinking + any signature = valid (trailing signature case)
+ * - Non-empty thinking + signature >= MIN_SIGNATURE_LENGTH = valid
+ * - Non-empty thinking + no/short signature = invalid
+ * - Non-thinking blocks = always valid
+ *
+ * @param block - Content block to validate
+ * @returns true if block is valid or not a thinking block
+ */
+export function hasValidSignature(block: ContentBlock): boolean {
+  if (block.type !== 'thinking') {
+    return true; // Non-thinking blocks are always valid
+  }
+
+  const thinkingBlock = block as ThinkingBlock;
+
+  // Empty thinking + any signature = valid (trailing signature)
+  if (!thinkingBlock.thinking || thinkingBlock.thinking.length === 0) {
+    return (
+      thinkingBlock.signature !== undefined &&
+      thinkingBlock.signature !== null &&
+      thinkingBlock.signature.length >= MIN_SIGNATURE_LENGTH
+    );
+  }
+
+  // Non-empty thinking needs a long enough signature
+  return (
+    thinkingBlock.signature !== undefined &&
+    thinkingBlock.signature !== null &&
+    thinkingBlock.signature.length >= MIN_SIGNATURE_LENGTH
+  );
+}
+
+/**
+ * Gracefully degrade an invalid thinking block
+ *
+ * - Valid blocks: return as-is
+ * - Invalid with content: convert to text block
+ * - Invalid without content: return null (should be dropped)
+ *
+ * @param block - Content block to process
+ * @returns Processed block or null if should be dropped
+ */
+export function gracefulDegradeThinking(block: ContentBlock): ContentBlock | null {
+  if (block.type !== 'thinking') {
+    return block;
+  }
+
+  const thinkingBlock = block as ThinkingBlock;
+
+  if (hasValidSignature(block)) {
+    return block;
+  }
+
+  // Invalid signature - check if we have content to preserve
+  if (thinkingBlock.thinking && thinkingBlock.thinking.length > 0) {
+    // Convert to text block to preserve content
+    console.info(
+      `[Thinking-Utils] Converting invalid thinking block to text. Content length: ${thinkingBlock.thinking.length}`,
+    );
+    return {
+      type: 'text',
+      text: thinkingBlock.thinking,
+    };
+  }
+
+  // Empty content + invalid signature = drop
+  console.debug('[Thinking-Utils] Dropping empty thinking block with invalid signature');
+  return null;
+}
+
+/**
+ * Process an array of content blocks, applying graceful degradation
+ *
+ * @param blocks - Array of content blocks
+ * @returns Processed array with invalid thinking blocks handled
+ */
+export function processThinkingBlocks(blocks: ContentBlock[]): ContentBlock[] {
+  const result: ContentBlock[] = [];
+
+  for (const block of blocks) {
+    const processed = gracefulDegradeThinking(block);
+    if (processed !== null) {
+      result.push(processed);
+    }
+  }
+
+  return result;
+}