@ketd/gemini-cli-sdk 0.3.3 → 0.3.5

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
@@ -384,7 +506,7 @@ interface UserInputMessage {
 /**
  * Control subtypes for control messages
  */
-type ControlSubtype = 'interrupt' | 'cancel' | 'shutdown' | 'truncate_history';
+type ControlSubtype = 'interrupt' | 'cancel' | 'shutdown' | 'truncate_history' | 'resume_session';
 /**
  * Interrupt control - stop current processing
  */
@@ -400,12 +522,21 @@ interface TruncateHistoryControl {
     /** Index from which to truncate (0-based, inclusive) */
     fromIndex: number;
 }
+/**
+ * Resume session control - load history from a session file
+ * Used when warm pool adapter is assigned to a real session
+ */
+interface ResumeSessionControl {
+    subtype: 'resume_session';
+    /** Path to the session file to resume from */
+    sessionFilePath: string;
+}
 /**
  * Control message sent to CLI
  */
 interface ControlInputMessage {
     type: JsonInputMessageType.CONTROL;
-    control: InterruptControl | TruncateHistoryControl;
+    control: InterruptControl | TruncateHistoryControl | ResumeSessionControl;
     session_id?: string;
 }
 /**
@@ -569,6 +700,21 @@ 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;
 }
 
 /**
@@ -733,6 +879,7 @@ declare class GeminiStreamClient extends EventEmitter$1 {
     private initEvent;
     private initTimeout;
     private tempSettingsPath;
+    private logger;
     constructor(options: GeminiStreamOptions);
     /**
      * Start the Gemini CLI process
@@ -760,6 +907,18 @@ declare class GeminiStreamClient extends EventEmitter$1 {
      * @param fromIndex - Index from which to truncate (0-based, inclusive)
      */
     truncateHistory(fromIndex: number): Promise<void>;
+    /**
+     * Resume session from a session file
+     *
+     * This sends a control message to the CLI to:
+     * 1. Load history from the specified session file
+     * 2. Update the ChatRecordingService to use the session file
+     *
+     * Used when a warm pool adapter is assigned to a real session that has history.
+     *
+     * @param sessionFilePath - Path to the session file to resume from
+     */
+    resumeSession(sessionFilePath: string): Promise<void>;
     /**
      * Stop the CLI process
      */
@@ -875,4 +1034,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 StreamStats, type ThoughtEvent, type ToolPermissionDecision, type ToolPermissionRequest, type ToolResultEvent, type ToolUseEvent, type TruncateHistoryControl, type UserInputMessage, findGeminiCLI, formatDuration, formatTokens, getApiKey, query, validateApiKey, validateModel };
+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, 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 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
@@ -384,7 +506,7 @@ interface UserInputMessage {
 /**
  * Control subtypes for control messages
  */
-type ControlSubtype = 'interrupt' | 'cancel' | 'shutdown' | 'truncate_history';
+type ControlSubtype = 'interrupt' | 'cancel' | 'shutdown' | 'truncate_history' | 'resume_session';
 /**
  * Interrupt control - stop current processing
  */
@@ -400,12 +522,21 @@ interface TruncateHistoryControl {
     /** Index from which to truncate (0-based, inclusive) */
     fromIndex: number;
 }
+/**
+ * Resume session control - load history from a session file
+ * Used when warm pool adapter is assigned to a real session
+ */
+interface ResumeSessionControl {
+    subtype: 'resume_session';
+    /** Path to the session file to resume from */
+    sessionFilePath: string;
+}
 /**
  * Control message sent to CLI
  */
 interface ControlInputMessage {
     type: JsonInputMessageType.CONTROL;
-    control: InterruptControl | TruncateHistoryControl;
+    control: InterruptControl | TruncateHistoryControl | ResumeSessionControl;
     session_id?: string;
 }
 /**
@@ -569,6 +700,21 @@ 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;
 }
 
 /**
@@ -733,6 +879,7 @@ declare class GeminiStreamClient extends EventEmitter$1 {
     private initEvent;
     private initTimeout;
     private tempSettingsPath;
+    private logger;
     constructor(options: GeminiStreamOptions);
     /**
      * Start the Gemini CLI process
@@ -760,6 +907,18 @@ declare class GeminiStreamClient extends EventEmitter$1 {
      * @param fromIndex - Index from which to truncate (0-based, inclusive)
      */
     truncateHistory(fromIndex: number): Promise<void>;
+    /**
+     * Resume session from a session file
+     *
+     * This sends a control message to the CLI to:
+     * 1. Load history from the specified session file
+     * 2. Update the ChatRecordingService to use the session file
+     *
+     * Used when a warm pool adapter is assigned to a real session that has history.
+     *
+     * @param sessionFilePath - Path to the session file to resume from
+     */
+    resumeSession(sessionFilePath: string): Promise<void>;
     /**
      * Stop the CLI process
      */
@@ -875,4 +1034,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 StreamStats, type ThoughtEvent, type ToolPermissionDecision, type ToolPermissionRequest, type ToolResultEvent, type ToolUseEvent, type TruncateHistoryControl, type UserInputMessage, findGeminiCLI, formatDuration, formatTokens, getApiKey, query, validateApiKey, validateModel };
+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, 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 TruncateHistoryControl, type UserInputMessage, createLogger, findGeminiCLI, formatDuration, formatTokens, getApiKey, query, sdkLogger, silentLogger, validateApiKey, validateModel };