docs

src/gemini_cli_adapter.py

@@ -1,3 +1,38 @@
+"""
+Gemini CLI Adapter - Subprocess wrapper for the `gemini` CLI tool.
+
+This module provides an adapter for running the Google Gemini CLI as a subprocess,
+parsing its streaming JSON output, and handling session management.
+
+Key Features:
+ - Streaming JSON output parsing (init, message, chunk, tool_use, result)
+ - Session persistence via --resume flag
+ - Non-blocking line-by-line reading with stream_callback
+ - Token estimation via character count heuristic (4 chars/token)
+ - CLI call logging via session_logger
+
+Integration:
+ - Used by ai_client.py as the 'gemini_cli' provider
+ - Enables synchronous HITL bridge via GEMINI_CLI_HOOK_CONTEXT env var
+
+Thread Safety:
+ - Each GeminiCliAdapter instance maintains its own session_id
+ - Not thread-safe. Use separate instances per thread.
+
+Configuration:
+ - binary_path: Path to the `gemini` CLI (from project config [gemini_cli].binary_path)
+
+Output Protocol:
+ The CLI emits JSON-L lines:
+ {"type": "init", "session_id": "..."}
+ {"type": "message", "content": "...", "role": "assistant"}
+ {"type": "tool_use", "name": "...", "parameters": {...}}
+ {"type": "result", "status": "success", "stats": {"total_tokens": N}}
+
+See Also:
+ - docs/guide_architecture.md for CLI adapter integration
+ - src/ai_client.py for provider dispatch
+"""
 import subprocess
 import json
 import os
@@ -6,6 +41,7 @@ import sys
 from src import session_logger
 from typing import Optional, Callable, Any
 
+
 class GeminiCliAdapter:
  """
     Adapter for the Gemini CLI that parses streaming JSON output.