@ketd/gemini-cli-sdk 0.3.4 → 0.3.6

package/dist/index.d.cts

@@ -1,11 +1,118 @@
 import { EventEmitter } from 'events';
 import { EventEmitter as EventEmitter$1 } from 'node:events';
 
+/**
+ * Logger utility for Gemini CLI SDK
+ *
+ * Provides a configurable logging interface that can be customized by SDK consumers.
+ * By default, logs go to console. Users can provide their own logger implementation.
+ */
+/**
+ * Log level enumeration
+ */
+declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    SILENT = 4
+}
+/**
+ * Logger interface that SDK consumers can implement
+ */
+interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Logger configuration options
+ */
+interface LoggerOptions {
+    /** Custom logger implementation */
+    logger?: Logger;
+    /** Minimum log level to output (default: INFO, or DEBUG if debug=true) */
+    level?: LogLevel;
+    /** Prefix for all log messages (e.g., '[GeminiSDK]') */
+    prefix?: string;
+}
+/**
+ * Silent logger that outputs nothing
+ */
+declare const silentLogger: Logger;
+/**
+ * SDK Logger class
+ *
+ * Wraps a logger implementation with level filtering and prefix support.
+ *
+ * @example
+ * ```typescript
+ * // Use default console logger
+ * const logger = new SDKLogger({ level: LogLevel.DEBUG });
+ *
+ * // Use custom logger
+ * const logger = new SDKLogger({
+ *   logger: myCustomLogger,
+ *   prefix: '[MyApp]',
+ * });
+ *
+ * logger.debug('Debug message');
+ * logger.error('Error occurred', { details: '...' });
+ * ```
+ */
+declare class SDKLogger implements Logger {
+    private logger;
+    private level;
+    private prefix;
+    constructor(options?: LoggerOptions);
+    /**
+     * Update logger configuration
+     */
+    configure(options: Partial<LoggerOptions>): void;
+    /**
+     * Set log level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Set custom logger implementation
+     */
+    setLogger(logger: Logger): void;
+    private formatMessage;
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Global SDK logger instance
+ *
+ * Used internally by SDK components. Can be configured by SDK consumers.
+ *
+ * @example
+ * ```typescript
+ * import { sdkLogger, LogLevel } from '@google/gemini-cli-sdk';
+ *
+ * // Configure global logger
+ * sdkLogger.setLevel(LogLevel.DEBUG);
+ * sdkLogger.setLogger(myCustomLogger);
+ * ```
+ */
+declare const sdkLogger: SDKLogger;
+/**
+ * Create a component-specific logger
+ *
+ * @param component - Component name for the prefix (e.g., 'GeminiStreamClient')
+ * @param options - Logger options
+ */
+declare function createLogger(component: string, options?: LoggerOptions): SDKLogger;
+
 /**
  * Type definitions for Gemini CLI SDK
  *
  * Based on Gemini CLI v0.21.0+ interface specification
  */
+
 /**
  * Gemini CLI configuration options
  */
@@ -95,6 +202,21 @@ interface GeminiOptions {
      * If not provided, falls back to Gemini CLI's built-in approval mechanism
      */
     onPermissionRequest?: (request: ToolPermissionRequest) => Promise<ToolPermissionDecision>;
+    /**
+     * Custom logger implementation
+     * If not provided, uses console with [GeminiSDK] prefix
+     * Set to silentLogger to disable all logging
+     *
+     * @example
+     * ```typescript
+     * import { silentLogger } from '@google/gemini-cli-sdk';
+     *
+     * const stream = query('Hello', {
+     *   logger: silentLogger, // Disable all logging
+     * });
+     * ```
+     */
+    logger?: Logger;
 }
 /**
  * Tool permission request
@@ -461,9 +583,16 @@ interface MCPServerConfig {
     cwd?: string;
     /** Environment variables */
     env?: Record<string, string>;
-    /** URL for SSE transport */
+    /**
+     * Transport type for URL-based connections
+     * - 'http': Streamable HTTP transport (recommended for mcp-chrome)
+     * - 'sse': Server-Sent Events transport
+     * When not specified with url, defaults to 'http'
+     */
+    type?: 'http' | 'sse';
+    /** URL for the MCP server (used with type field) */
     url?: string;
-    /** URL for HTTP streaming transport */
+    /** URL for HTTP streaming transport (deprecated, use url with type: 'http') */
     httpUrl?: string;
     /** Custom headers for HTTP transports */
     headers?: Record<string, string>;
@@ -480,6 +609,38 @@ interface MCPServerConfig {
  * MCP Servers configuration map
  */
 type MCPServersConfig = Record<string, MCPServerConfig>;
+/**
+ * Tools configuration for Gemini CLI settings.json
+ * Used to configure custom tool discovery and execution commands
+ */
+interface ToolsConfig {
+    /**
+     * Command to discover available tools
+     * @example '"node" "/path/to/discover-tools.cjs"'
+     */
+    discoveryCommand?: string;
+    /**
+     * Command to call/execute a tool
+     * @example '"node" "/path/to/call-tool.cjs"'
+     */
+    callCommand?: string;
+    /**
+     * Enable hooks for tool execution
+     * Set to true when using hooks configuration
+     */
+    enableHooks?: boolean;
+}
+/**
+ * Context configuration for Gemini CLI settings.json
+ * Used to configure context file settings
+ */
+interface ContextConfig {
+    /**
+     * Name of the context file (e.g., 'AOE.md')
+     * Gemini CLI will look for this file in the working directory
+     */
+    fileName?: string;
+}
 /**
  * Options for GeminiStreamClient
  */
@@ -578,6 +739,49 @@ interface GeminiStreamOptions {
      * @example '/path/to/session-2025-01-01T12-00-abc123.json'
      */
     resumeSessionFilePath?: string;
+    /**
+     * Custom logger implementation
+     * If not provided, uses console with [GeminiStreamClient] prefix
+     * Set to silentLogger to disable all logging
+     *
+     * @example
+     * ```typescript
+     * import { silentLogger, GeminiStreamClient } from '@google/gemini-cli-sdk';
+     *
+     * const client = new GeminiStreamClient({
+     *   logger: silentLogger, // Disable all logging
+     * });
+     * ```
+     */
+    logger?: Logger;
+    /**
+     * Tools configuration for Gemini CLI
+     * Configures custom tool discovery and execution commands
+     * Written to settings.json tools field
+     *
+     * @example
+     * ```typescript
+     * tools: {
+     *   discoveryCommand: '"node" "/path/to/discover-tools.cjs"',
+     *   callCommand: '"node" "/path/to/call-tool.cjs"',
+     *   enableHooks: true,
+     * }
+     * ```
+     */
+    tools?: ToolsConfig;
+    /**
+     * Context configuration for Gemini CLI
+     * Configures context file settings
+     * Written to settings.json context field
+     *
+     * @example
+     * ```typescript
+     * context: {
+     *   fileName: 'AOE.md',
+     * }
+     * ```
+     */
+    context?: ContextConfig;
 }
 
 /**
@@ -742,6 +946,7 @@ declare class GeminiStreamClient extends EventEmitter$1 {
     private initEvent;
     private initTimeout;
     private tempSettingsPath;
+    private logger;
     constructor(options: GeminiStreamOptions);
     /**
      * Start the Gemini CLI process
@@ -807,6 +1012,9 @@ declare class GeminiStreamClient extends EventEmitter$1 {
      * Note: Gemini CLI does not support --settings-file parameter.
      * Instead, it loads settings from GEMINI_CONFIG_DIR/settings.json
      * where GEMINI_CONFIG_DIR is set via environment variable.
+     *
+     * This method merges with existing settings.json if present, preserving
+     * any configuration written by the host application (e.g., tools.discoveryCommand).
      */
     private createTempSettings;
     /**
@@ -896,4 +1104,4 @@ declare function formatDuration(ms: number): string;
  */
 declare function formatTokens(tokens: number): string;
 
-export { type ControlInputMessage, type ControlSubtype, type ErrorEvent, ExitCode, GeminiClient, type GeminiOptions, GeminiSDKError, GeminiStreamClient, type GeminiStreamOptions, type HooksConfiguration, type InitEvent, type InterruptControl, type JsonInputMessage, JsonInputMessageType, type JsonStreamEvent, JsonStreamEventType, type MCPServerConfig, type MCPServersConfig, type MessageEvent, ProcessStatus, type QueryResult, type ResultEvent, type ResumeSessionControl, type StreamStats, type ThoughtEvent, type ToolPermissionDecision, type ToolPermissionRequest, type ToolResultEvent, type ToolUseEvent, type TruncateHistoryControl, type UserInputMessage, findGeminiCLI, formatDuration, formatTokens, getApiKey, query, validateApiKey, validateModel };
+export { type ContextConfig, type ControlInputMessage, type ControlSubtype, type ErrorEvent, ExitCode, GeminiClient, type GeminiOptions, GeminiSDKError, GeminiStreamClient, type GeminiStreamOptions, type HooksConfiguration, type InitEvent, type InterruptControl, type JsonInputMessage, JsonInputMessageType, type JsonStreamEvent, JsonStreamEventType, LogLevel, type Logger, type LoggerOptions, type MCPServerConfig, type MCPServersConfig, type MessageEvent, ProcessStatus, type QueryResult, type ResultEvent, type ResumeSessionControl, SDKLogger, type StreamStats, type ThoughtEvent, type ToolPermissionDecision, type ToolPermissionRequest, type ToolResultEvent, type ToolUseEvent, type ToolsConfig, type TruncateHistoryControl, type UserInputMessage, createLogger, findGeminiCLI, formatDuration, formatTokens, getApiKey, query, sdkLogger, silentLogger, validateApiKey, validateModel };

package/dist/index.d.ts

@@ -1,11 +1,118 @@
 import { EventEmitter } from 'events';
 import { EventEmitter as EventEmitter$1 } from 'node:events';
 
+/**
+ * Logger utility for Gemini CLI SDK
+ *
+ * Provides a configurable logging interface that can be customized by SDK consumers.
+ * By default, logs go to console. Users can provide their own logger implementation.
+ */
+/**
+ * Log level enumeration
+ */
+declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    SILENT = 4
+}
+/**
+ * Logger interface that SDK consumers can implement
+ */
+interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Logger configuration options
+ */
+interface LoggerOptions {
+    /** Custom logger implementation */
+    logger?: Logger;
+    /** Minimum log level to output (default: INFO, or DEBUG if debug=true) */
+    level?: LogLevel;
+    /** Prefix for all log messages (e.g., '[GeminiSDK]') */
+    prefix?: string;
+}
+/**
+ * Silent logger that outputs nothing
+ */
+declare const silentLogger: Logger;
+/**
+ * SDK Logger class
+ *
+ * Wraps a logger implementation with level filtering and prefix support.
+ *
+ * @example
+ * ```typescript
+ * // Use default console logger
+ * const logger = new SDKLogger({ level: LogLevel.DEBUG });
+ *
+ * // Use custom logger
+ * const logger = new SDKLogger({
+ *   logger: myCustomLogger,
+ *   prefix: '[MyApp]',
+ * });
+ *
+ * logger.debug('Debug message');
+ * logger.error('Error occurred', { details: '...' });
+ * ```
+ */
+declare class SDKLogger implements Logger {
+    private logger;
+    private level;
+    private prefix;
+    constructor(options?: LoggerOptions);
+    /**
+     * Update logger configuration
+     */
+    configure(options: Partial<LoggerOptions>): void;
+    /**
+     * Set log level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Set custom logger implementation
+     */
+    setLogger(logger: Logger): void;
+    private formatMessage;
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Global SDK logger instance
+ *
+ * Used internally by SDK components. Can be configured by SDK consumers.
+ *
+ * @example
+ * ```typescript
+ * import { sdkLogger, LogLevel } from '@google/gemini-cli-sdk';
+ *
+ * // Configure global logger
+ * sdkLogger.setLevel(LogLevel.DEBUG);
+ * sdkLogger.setLogger(myCustomLogger);
+ * ```
+ */
+declare const sdkLogger: SDKLogger;
+/**
+ * Create a component-specific logger
+ *
+ * @param component - Component name for the prefix (e.g., 'GeminiStreamClient')
+ * @param options - Logger options
+ */
+declare function createLogger(component: string, options?: LoggerOptions): SDKLogger;
+
 /**
  * Type definitions for Gemini CLI SDK
  *
  * Based on Gemini CLI v0.21.0+ interface specification
  */
+
 /**
  * Gemini CLI configuration options
  */
@@ -95,6 +202,21 @@ interface GeminiOptions {
      * If not provided, falls back to Gemini CLI's built-in approval mechanism
      */
     onPermissionRequest?: (request: ToolPermissionRequest) => Promise<ToolPermissionDecision>;
+    /**
+     * Custom logger implementation
+     * If not provided, uses console with [GeminiSDK] prefix
+     * Set to silentLogger to disable all logging
+     *
+     * @example
+     * ```typescript
+     * import { silentLogger } from '@google/gemini-cli-sdk';
+     *
+     * const stream = query('Hello', {
+     *   logger: silentLogger, // Disable all logging
+     * });
+     * ```
+     */
+    logger?: Logger;
 }
 /**
  * Tool permission request
@@ -461,9 +583,16 @@ interface MCPServerConfig {
     cwd?: string;
     /** Environment variables */
     env?: Record<string, string>;
-    /** URL for SSE transport */
+    /**
+     * Transport type for URL-based connections
+     * - 'http': Streamable HTTP transport (recommended for mcp-chrome)
+     * - 'sse': Server-Sent Events transport
+     * When not specified with url, defaults to 'http'
+     */
+    type?: 'http' | 'sse';
+    /** URL for the MCP server (used with type field) */
     url?: string;
-    /** URL for HTTP streaming transport */
+    /** URL for HTTP streaming transport (deprecated, use url with type: 'http') */
     httpUrl?: string;
     /** Custom headers for HTTP transports */
     headers?: Record<string, string>;
@@ -480,6 +609,38 @@ interface MCPServerConfig {
  * MCP Servers configuration map
  */
 type MCPServersConfig = Record<string, MCPServerConfig>;
+/**
+ * Tools configuration for Gemini CLI settings.json
+ * Used to configure custom tool discovery and execution commands
+ */
+interface ToolsConfig {
+    /**
+     * Command to discover available tools
+     * @example '"node" "/path/to/discover-tools.cjs"'
+     */
+    discoveryCommand?: string;
+    /**
+     * Command to call/execute a tool
+     * @example '"node" "/path/to/call-tool.cjs"'
+     */
+    callCommand?: string;
+    /**
+     * Enable hooks for tool execution
+     * Set to true when using hooks configuration
+     */
+    enableHooks?: boolean;
+}
+/**
+ * Context configuration for Gemini CLI settings.json
+ * Used to configure context file settings
+ */
+interface ContextConfig {
+    /**
+     * Name of the context file (e.g., 'AOE.md')
+     * Gemini CLI will look for this file in the working directory
+     */
+    fileName?: string;
+}
 /**
  * Options for GeminiStreamClient
  */
@@ -578,6 +739,49 @@ interface GeminiStreamOptions {
      * @example '/path/to/session-2025-01-01T12-00-abc123.json'
      */
     resumeSessionFilePath?: string;
+    /**
+     * Custom logger implementation
+     * If not provided, uses console with [GeminiStreamClient] prefix
+     * Set to silentLogger to disable all logging
+     *
+     * @example
+     * ```typescript
+     * import { silentLogger, GeminiStreamClient } from '@google/gemini-cli-sdk';
+     *
+     * const client = new GeminiStreamClient({
+     *   logger: silentLogger, // Disable all logging
+     * });
+     * ```
+     */
+    logger?: Logger;
+    /**
+     * Tools configuration for Gemini CLI
+     * Configures custom tool discovery and execution commands
+     * Written to settings.json tools field
+     *
+     * @example
+     * ```typescript
+     * tools: {
+     *   discoveryCommand: '"node" "/path/to/discover-tools.cjs"',
+     *   callCommand: '"node" "/path/to/call-tool.cjs"',
+     *   enableHooks: true,
+     * }
+     * ```
+     */
+    tools?: ToolsConfig;
+    /**
+     * Context configuration for Gemini CLI
+     * Configures context file settings
+     * Written to settings.json context field
+     *
+     * @example
+     * ```typescript
+     * context: {
+     *   fileName: 'AOE.md',
+     * }
+     * ```
+     */
+    context?: ContextConfig;
 }
 
 /**
@@ -742,6 +946,7 @@ declare class GeminiStreamClient extends EventEmitter$1 {
     private initEvent;
     private initTimeout;
     private tempSettingsPath;
+    private logger;
     constructor(options: GeminiStreamOptions);
     /**
      * Start the Gemini CLI process
@@ -807,6 +1012,9 @@ declare class GeminiStreamClient extends EventEmitter$1 {
      * Note: Gemini CLI does not support --settings-file parameter.
      * Instead, it loads settings from GEMINI_CONFIG_DIR/settings.json
      * where GEMINI_CONFIG_DIR is set via environment variable.
+     *
+     * This method merges with existing settings.json if present, preserving
+     * any configuration written by the host application (e.g., tools.discoveryCommand).
      */
     private createTempSettings;
     /**
@@ -896,4 +1104,4 @@ declare function formatDuration(ms: number): string;
  */
 declare function formatTokens(tokens: number): string;
 
-export { type ControlInputMessage, type ControlSubtype, type ErrorEvent, ExitCode, GeminiClient, type GeminiOptions, GeminiSDKError, GeminiStreamClient, type GeminiStreamOptions, type HooksConfiguration, type InitEvent, type InterruptControl, type JsonInputMessage, JsonInputMessageType, type JsonStreamEvent, JsonStreamEventType, type MCPServerConfig, type MCPServersConfig, type MessageEvent, ProcessStatus, type QueryResult, type ResultEvent, type ResumeSessionControl, type StreamStats, type ThoughtEvent, type ToolPermissionDecision, type ToolPermissionRequest, type ToolResultEvent, type ToolUseEvent, type TruncateHistoryControl, type UserInputMessage, findGeminiCLI, formatDuration, formatTokens, getApiKey, query, validateApiKey, validateModel };
+export { type ContextConfig, type ControlInputMessage, type ControlSubtype, type ErrorEvent, ExitCode, GeminiClient, type GeminiOptions, GeminiSDKError, GeminiStreamClient, type GeminiStreamOptions, type HooksConfiguration, type InitEvent, type InterruptControl, type JsonInputMessage, JsonInputMessageType, type JsonStreamEvent, JsonStreamEventType, LogLevel, type Logger, type LoggerOptions, type MCPServerConfig, type MCPServersConfig, type MessageEvent, ProcessStatus, type QueryResult, type ResultEvent, type ResumeSessionControl, SDKLogger, type StreamStats, type ThoughtEvent, type ToolPermissionDecision, type ToolPermissionRequest, type ToolResultEvent, type ToolUseEvent, type ToolsConfig, type TruncateHistoryControl, type UserInputMessage, createLogger, findGeminiCLI, formatDuration, formatTokens, getApiKey, query, sdkLogger, silentLogger, validateApiKey, validateModel };