@jsonstudio/rcc 0.89.1189 → 0.89.1348

package/docs/debugging/gemini-sse-root-cause.md

@@ -0,0 +1,52 @@
+# Gemini SSE Stream Processing Issue - Root Cause & Solution
+
+## Current Status
+- ✅ `GeminiSseNormalizer` correctly sends 15 events with raw `part` objects
+- ❌ Only 8 events reach the client (7 events dropped)
+
+## Architecture Flow
+```
+Gemini CLI (upstream)
+  ↓ SSE stream
+GeminiCLIHttpProvider.GeminiSseNormalizer
+  ↓ parse SSE → emit `gemini.data` events with raw `part`
+llmswitch-core: GeminiSseToJsonConverter  
+  ↓ collect parts → build GeminiResponse
+llmswitch-core: Response transformation layer
+  ↓ Gemini parts → Responses/OpenAI format
+Client (receives final SSE)
+```
+
+## Root Cause
+**Gemini parts with `functionCall`, `thought`, `executableCode` are未被正确转换为 Responses 格式**
+
+`GeminiSseToJsonConverter` 正确收集所有 parts（包括 tool calls），但后续转换层（可能在 `codecs/gemini-openai-codec.ts` 或 Responses 转换器中）不认识这些 part 类型，导致它们被过滤掉。
+
+## Files Need Investigation
+1. `/sharedmodule/llmswitch-core/src/codecs/gemini-openai-codec.ts`  
+   - Gemini → OpenAI 格式转换
+   - 需要添加 `functionCall` → `tool_calls` 映射
+   - 需要添加 `thought` → `reasoning_content` 映射
+
+2. `/sharedmodule/llmswitch-core/src/sse/json-to-sse/gemini-json-to-sse-converter.ts`
+   - 如果是逆向流程（JSON → SSE），也需要处理这些类型
+
+3. 参考实现：  
+   - `~/Documents/github/gcli2api` (user 提到的参考项目，目前无法访问)
+   - 需要 user 提供关键的转换逻辑
+
+## Next Steps
+1. 查看 `gemini-openai-codec.ts` 的 part 转换逻辑
+2. 添加对以下 Gemini part 类型的支持：
+   - `functionCall` →  OpenAI `tool_calls`
+   - `functionResponse` → tool result
+   - `thought` → `reasoning_content` (extended thinking)
+   - `executableCode` → code_interpreter
+   - `codeExecutionResult` → execution output
+
+3. 或者，user 提供 gcli2api 的实现参考
+
+## Current State
+- v0.89.376 deployed
+- Provider layer correctly sends raw parts
+- Waiting for llmswitch-core response inbound layer fixes

package/docs/debugging/sse_encoding_failure_analysis.md

@@ -0,0 +1,53 @@
+# Analysis of Incomplete Response / SSE Encoding Issues
+
+## Incident Summary
+The user reported that requests are "stopping halfway" or having encoding issues, suspecting that SSE is being treated as JSON or that Double Encoding is occurring.
+Logs indicate:
+- `reason=thinking:last-tool-read` (Complex flow with tool outputs)
+- `[response.sse.stream] ... end {"events":8,"status":200}` (Stream started but ended potentially prematurely)
+
+## Root Cause Analysis
+
+### Primary Cause: Unsafe Buffer Handling in `GeminiSseNormalizer`
+The `GeminiSseNormalizer` class in `src/providers/core/runtime/gemini-cli-http-provider.ts` has a critical flaw in how it processes incoming data chunks from the Gemini CLI process.
+
+**The Code:**
+```typescript
+override _transform(chunk: unknown, ...): void {
+  if (chunk) {
+    // FLAW: Converting a Buffer chunk directly to string can split multi-byte characters
+    const text = chunk instanceof Buffer ? chunk.toString('utf8') : String(chunk);
+    this.buffer += text.replace(/\r\n/g, '\n');
+    this.processBuffered();
+  }
+}
+```
+
+**The Mechanism of Failure:**
+1.  **Multi-byte Characters**: Output containing Chinese characters or other multi-byte Unicode sequences (common in "thinking" traces or translated tool outputs) takes up 3-4 bytes per character.
+2.  **Chunk Splitting**: A network or process stream chunk boundary can land *in the middle* of a character's byte sequence (e.g., getting the first 2 bytes of a 3-byte character).
+3.  **Corruption**: `chunk.toString('utf8')` replaces the incomplete byte sequence with a replacement character ().
+4.  **JSON Validation**: The `GeminiSseNormalizer` attempts to parse the accumulated text as JSON (`JSON.parse(payloadText)`).
+5.  **Silent Failure**: Because the JSON string now contains corrupted characters (or the structure is broken due to the character being part of a syntax element), `JSON.parse` throws an error.
+6.  **Data Loss**: The code explicitly ignores these errors:
+    ```typescript
+    try {
+      const parsed = JSON.parse(payloadText);
+      // ...
+    } catch {
+      // ignore malformed chunks
+    }
+    ```
+    This causes the entire chunk (which might contain the rest of the response or a crucial tool output) to be **silently discarded**.
+
+### Secondary Symptoms
+*   **"Stopped Halfway"**: The client receives the initial events (e.g., 8 events) but once a large chunk with a split character arrives, it is dropped, and the stream ends or hangs, making it look like it stopped.
+*   **"Encoding Issues"**: If any corrupt text *does* make it through (unlikely with JSON.parse failing), it would look like mojibake.
+
+## Conclusion
+The issue is definitively an **encoding handling bug** in the streaming pipeline. The server is not handling binary stream usage correctly for multi-byte content.
+
+## Recommended Fix
+Use the `Utf8ChunkBuffer` utility (which correctly buffers incomplete byte sequences across chunks) in `GeminiSseNormalizer` instead of direct `toString()`.
+
+*Note: I attempted to apply this fix in the previous step but the file update was incomplete/broken. The file currently needs repair to function.*