gemini_cli_sdk 4.0.6

gemini_cli_sdk: ^4.0.6 copied to clipboard

Dependencies #

• Updated programming_cli_core_sdk to 2.1.1: Inherits critical bug fix that resolves "No pubspec.yaml file found" error during schema validation. The core SDK now automatically creates and cleans up a minimal pubspec.yaml when running schema tests, enabling successful validation in isolated/scoped directories.

Improvements #

• Enhanced MCP Compatibility: Expanded the isolated environment to include additional essential environment variables (USER, TMPDIR, TEMP, TMP, SHELL, NODE_PATH) when an API key is provided. This ensures MCP servers (which run as Node.js processes via npx) have sufficient context to function properly while maintaining security isolation.

Technical Details #

• Modified _buildEnvironment() in gemini_chat.dart to conditionally include essential system environment variables that MCP servers need to operate
• Maintains security: still uses includeParentEnvironment: false and only includes whitelisted essential variables
• Backward compatible: when no API key is provided, behavior remains unchanged

Context #

This change fixes issues where Gemini CLI with API key isolation couldn't access MCP servers because npm/node processes lacked necessary environment context. Now MCP tools work correctly even with API key isolation enabled.

Security #

• Isolated API Key Environment: When an API key is provided via the SDK, the chat process now runs in a completely isolated environment. Only essential variables (PATH, HOME, GEMINI_API_KEY) are passed to the CLI, preventing any parent environment credentials from leaking through.
• Enhanced Process Security: All processes spawned with an API key now use includeParentEnvironment: false and runInShell: false for maximum security isolation.

Technical Details #

• Modified _buildEnvironment() to create minimal isolated environments when apiKey is provided
• Updated Process.start() in createProcess() to explicitly disable parent environment inheritance when using API keys
• Backward compatible: when no API key is provided, the SDK continues to use the full parent environment

Dependencies #

• Updated programming_cli_core_sdk to 2.1.0: Inherits improvements including public chatNanoId, updateOptions method, and optimized directory-level cleanup.

Improvements #

• File operation scoping: Now properly scopes all CLI file operations to ai_generated_files/$chatNanoId/ by updating the cwd option after chat creation. This prevents the Gemini CLI from creating files at the root directory.

Dependencies #

• Updated programming_cli_core_sdk to 2.0.1: Inherits critical file cleanup fix that guarantees temporary files and schema test files are always deleted, even when errors occur.

Bug Fixes #

• Fixed stream subscription error: Changed _decorateStream to use StreamController<String>.broadcast() instead of StreamController<String>(). This fixes the "Stream has already been listened to" error when the stream is consumed by multiple listeners (e.g., when both forwarding chunks and collecting all messages).

Breaking Changes #

• API Key Management Refactor: Gemini class now manages its own apiKey field directly instead of inheriting from base class.
• Method Renamed: exportApiKeyToEnvironment() has been replaced with addApiKeyToEnvironment(String apiKey) to match the new abstract interface signature.

Added #

• Implements new addApiKeyToEnvironment(String apiKey) method: Sets the GEMINI_API_KEY environment variable to allow CLI authentication without login.
• Explicit API Key Field: The apiKey is now a final field in the Gemini class for better clarity.

Migration Guide #

• No changes needed for SDK instantiation: Gemini(apiKey: 'your-key') remains the same.
• Call await gemini.addApiKeyToEnvironment(apiKey) after creating the instance to ensure CLI authentication works.
• If you were using exportApiKeyToEnvironment(), rename it to addApiKeyToEnvironment(apiKey).

Breaking Changes #

• Rebuilt the SDK on top of programming_cli_core_sdk, aligning the Gemini, Codex, and Claude packages.
• Replaced GeminiSdkContent with the shared PromptContent abstractions for text and file prompts.
• Removed package-specific exceptions in favour of the shared CliException hierarchy.
• Simplified the public API to mirror other CLI SDKs; previous MCP helper models have been replaced with shared types.

Added #

• New Gemini/GeminiSDK class implementing CodingCliInterface with consistent session management.
• Dedicated GeminiChatOptions that map directly to Gemini CLI flags and shared schema tooling.
• Enhanced MCP management using the shared McpConfig, including popular server templates and scope-aware helpers.

Improved #

• Streaming now normalises Gemini CLI output and strips metadata automatically.
• Environment handling ensures GEMINI_API_KEY is injected for every process and can export to the shell on demand.
• Package layout now mirrors the other CLI SDKs with a flat lib/src structure.

Breaking Changes #

• GeminiSdkContent.bytes() now requires a fileName parameter for proper file identification
• Files passed via GeminiSdkContent.file() are now cloned to the working directory to ensure CLI access
• Temporary files are automatically cleaned up in dispose() method

Added #

• File Management Improvements:
  • Automatic file cloning to working directory for CLI accessibility
  • Unique file naming using nanoid2 to prevent conflicts
  • Guaranteed cleanup of temporary files in dispose()
• New Parameters:
  • fileName parameter (required) for GeminiSdkContent.bytes()
  • fileDescription parameter (optional) for both bytes() and file() methods
• CLI-specific formatting: Added toCliString() method for proper file references

Fixed #

• CLI tools can now access files from any location by cloning them to the working directory
• Prevents file access errors when files are outside the CLI's scope
• Ensures consistent file handling across different operating systems

Breaking #

• sendMessageWithSchema() now returns a record ({String llmMessage, Map<String, dynamic> structuredSchemaData})
• Schema responses are generated via a temporary JSON file with validation and retry logic

Added #

• streamResponseWithSchema() companion API that streams Gemini output while structured data is produced
• Strong schema validation with descriptive error messages when required fields are missing or types mismatch

Improved #

• File-system workflow now leverages the write_file tool and guarantees cleanup of temporary schema files
• Better diagnostics when JSON parsing fails

New Features #

• Auto-Update Functionality: Added updateToNewestVersionIfNeeded() method
  • Automatically checks for CLI updates
  • Compares installed version with latest npm version
  • Updates to newest version if available
  • Falls back to reinstall if update fails

Improvements #

• Better version management for Gemini CLI
• Automatic handling of outdated installations
• Improved error handling during updates
• Fixed README documentation to use correct method names (isGeminiCLIInstalled() and installGeminiCLI())

Initial Release #

• Core Features

  • Simple API for creating chat sessions with Google Gemini
  • Support for multiple authentication methods (API Key, OAuth, Vertex AI)
  • Session management with conversation continuity
  • Resource cleanup and disposal management

• Content Types

  • Text content support
  • File attachment support
  • Bytes content support with automatic temporary file creation
  • Automatic cleanup of temporary files on disposal

• Schema Support

  • JSON schema-based structured responses
  • Type-safe schema builders with nullable control
  • Automatic required field detection
  • Support for nested objects and arrays

• Streaming

  • Real-time streaming response support
  • Chunk-by-chunk processing
  • Process management for streaming sessions

• MCP (Model Context Protocol)

  • Full MCP server management
  • Popular MCP server installation support (filesystem, GitHub, PostgreSQL, etc.)
  • Custom MCP server configuration
  • Environment variable management for MCP servers

• CLI Management

  • Built-in Gemini CLI installation checker
  • Automatic CLI installation support
  • SDK information retrieval
  • Cross-platform support (Windows, macOS, Linux)

• Developer Experience

  • Comprehensive error handling with custom exceptions
  • Type-safe API with Dart's strong typing
  • Extensive documentation and examples
  • Unit test coverage

• Examples Included

  • Basic usage and conversation management
  • File analysis
  • Schema-based structured extraction
  • Streaming responses
  • MCP server management
  • Bytes content handling
  • Installation checking