@ketd/gemini-cli-sdk 0.3.5 → 0.3.7

package/dist/index.d.cts

@@ -506,7 +506,7 @@ interface UserInputMessage {
 /**
  * Control subtypes for control messages
  */
-type ControlSubtype = 'interrupt' | 'cancel' | 'shutdown' | 'truncate_history' | 'resume_session';
+type ControlSubtype = 'interrupt' | 'cancel' | 'shutdown' | 'truncate_history' | 'resume_session' | 'replace_history';
 /**
  * Interrupt control - stop current processing
  */
@@ -514,13 +514,21 @@ interface InterruptControl {
     subtype: 'interrupt' | 'cancel' | 'shutdown';
 }
 /**
- * Truncate history control - remove messages from a specific index
+ * Truncate history control - remove messages from a specific index or by user turn count
  * Used for edit/retry functionality
+ *
+ * Two modes:
+ * - keepUserTurns: Semantic mode — keep N complete user turns (handles tool call Content items correctly)
+ * - fromIndex: Raw mode — truncate from a specific Content[] index (legacy, doesn't account for tool calls)
+ *
+ * When both are provided, keepUserTurns takes precedence.
  */
 interface TruncateHistoryControl {
     subtype: 'truncate_history';
-    /** Index from which to truncate (0-based, inclusive) */
-    fromIndex: number;
+    /** Index from which to truncate (0-based, inclusive). Used when keepUserTurns is not set. */
+    fromIndex?: number;
+    /** Number of complete user turns to keep. The CLI scans its history to find the correct Content[] split point. */
+    keepUserTurns?: number;
 }
 /**
  * Resume session control - load history from a session file
@@ -531,12 +539,24 @@ interface ResumeSessionControl {
     /** Path to the session file to resume from */
     sessionFilePath: string;
 }
+/**
+ * Replace history control - fully replace CLI in-memory history
+ * Used when messages are deleted from DB and CLI history needs to be rebuilt
+ */
+interface ReplaceHistoryControl {
+    subtype: 'replace_history';
+    /** Full replacement history as Gemini Content[] format */
+    contents: Array<{
+        role: string;
+        parts: unknown[];
+    }>;
+}
 /**
  * Control message sent to CLI
  */
 interface ControlInputMessage {
     type: JsonInputMessageType.CONTROL;
-    control: InterruptControl | TruncateHistoryControl | ResumeSessionControl;
+    control: InterruptControl | TruncateHistoryControl | ResumeSessionControl | ReplaceHistoryControl;
     session_id?: string;
 }
 /**
@@ -583,9 +603,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>;
@@ -602,6 +629,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
  */
@@ -694,12 +753,6 @@ interface GeminiStreamOptions {
      * ```
      */
     mcpServers?: MCPServersConfig;
-    /**
-     * Resume from a previous session file path
-     * If provided, Gemini CLI will load the session history using --resume flag
-     * @example '/path/to/session-2025-01-01T12-00-abc123.json'
-     */
-    resumeSessionFilePath?: string;
     /**
      * Custom logger implementation
      * If not provided, uses console with [GeminiStreamClient] prefix
@@ -715,6 +768,34 @@ interface GeminiStreamOptions {
      * ```
      */
     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;
 }
 
 /**
@@ -904,9 +985,13 @@ declare class GeminiStreamClient extends EventEmitter$1 {
      *
      * Used for edit/retry functionality where subsequent messages need to be discarded.
      *
-     * @param fromIndex - Index from which to truncate (0-based, inclusive)
+     * @param options - Truncation options: either keepUserTurns (preferred) or fromIndex (legacy)
      */
-    truncateHistory(fromIndex: number): Promise<void>;
+    truncateHistory(options: number | {
+        keepUserTurns: number;
+    } | {
+        fromIndex: number;
+    }): Promise<void>;
     /**
      * Resume session from a session file
      *
@@ -919,6 +1004,21 @@ declare class GeminiStreamClient extends EventEmitter$1 {
      * @param sessionFilePath - Path to the session file to resume from
      */
     resumeSession(sessionFilePath: string): Promise<void>;
+    /**
+     * Replace CLI in-memory history with provided contents
+     *
+     * This sends a control message to the CLI to:
+     * 1. Replace the entire in-memory history with the provided contents
+     * 2. Clear session.json (DB is the source of truth)
+     *
+     * Used when messages are deleted from DB and CLI history needs to be rebuilt.
+     *
+     * @param contents - Full replacement history in Gemini Content[] format
+     */
+    replaceHistory(contents: Array<{
+        role: string;
+        parts: unknown[];
+    }>): Promise<void>;
     /**
      * Stop the CLI process
      */
@@ -945,6 +1045,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;
     /**
@@ -1034,4 +1137,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, 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 };
+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

@@ -506,7 +506,7 @@ interface UserInputMessage {
 /**
  * Control subtypes for control messages
  */
-type ControlSubtype = 'interrupt' | 'cancel' | 'shutdown' | 'truncate_history' | 'resume_session';
+type ControlSubtype = 'interrupt' | 'cancel' | 'shutdown' | 'truncate_history' | 'resume_session' | 'replace_history';
 /**
  * Interrupt control - stop current processing
  */
@@ -514,13 +514,21 @@ interface InterruptControl {
     subtype: 'interrupt' | 'cancel' | 'shutdown';
 }
 /**
- * Truncate history control - remove messages from a specific index
+ * Truncate history control - remove messages from a specific index or by user turn count
  * Used for edit/retry functionality
+ *
+ * Two modes:
+ * - keepUserTurns: Semantic mode — keep N complete user turns (handles tool call Content items correctly)
+ * - fromIndex: Raw mode — truncate from a specific Content[] index (legacy, doesn't account for tool calls)
+ *
+ * When both are provided, keepUserTurns takes precedence.
  */
 interface TruncateHistoryControl {
     subtype: 'truncate_history';
-    /** Index from which to truncate (0-based, inclusive) */
-    fromIndex: number;
+    /** Index from which to truncate (0-based, inclusive). Used when keepUserTurns is not set. */
+    fromIndex?: number;
+    /** Number of complete user turns to keep. The CLI scans its history to find the correct Content[] split point. */
+    keepUserTurns?: number;
 }
 /**
  * Resume session control - load history from a session file
@@ -531,12 +539,24 @@ interface ResumeSessionControl {
     /** Path to the session file to resume from */
     sessionFilePath: string;
 }
+/**
+ * Replace history control - fully replace CLI in-memory history
+ * Used when messages are deleted from DB and CLI history needs to be rebuilt
+ */
+interface ReplaceHistoryControl {
+    subtype: 'replace_history';
+    /** Full replacement history as Gemini Content[] format */
+    contents: Array<{
+        role: string;
+        parts: unknown[];
+    }>;
+}
 /**
  * Control message sent to CLI
  */
 interface ControlInputMessage {
     type: JsonInputMessageType.CONTROL;
-    control: InterruptControl | TruncateHistoryControl | ResumeSessionControl;
+    control: InterruptControl | TruncateHistoryControl | ResumeSessionControl | ReplaceHistoryControl;
     session_id?: string;
 }
 /**
@@ -583,9 +603,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>;
@@ -602,6 +629,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
  */
@@ -694,12 +753,6 @@ interface GeminiStreamOptions {
      * ```
      */
     mcpServers?: MCPServersConfig;
-    /**
-     * Resume from a previous session file path
-     * If provided, Gemini CLI will load the session history using --resume flag
-     * @example '/path/to/session-2025-01-01T12-00-abc123.json'
-     */
-    resumeSessionFilePath?: string;
     /**
      * Custom logger implementation
      * If not provided, uses console with [GeminiStreamClient] prefix
@@ -715,6 +768,34 @@ interface GeminiStreamOptions {
      * ```
      */
     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;
 }
 
 /**
@@ -904,9 +985,13 @@ declare class GeminiStreamClient extends EventEmitter$1 {
      *
      * Used for edit/retry functionality where subsequent messages need to be discarded.
      *
-     * @param fromIndex - Index from which to truncate (0-based, inclusive)
+     * @param options - Truncation options: either keepUserTurns (preferred) or fromIndex (legacy)
      */
-    truncateHistory(fromIndex: number): Promise<void>;
+    truncateHistory(options: number | {
+        keepUserTurns: number;
+    } | {
+        fromIndex: number;
+    }): Promise<void>;
     /**
      * Resume session from a session file
      *
@@ -919,6 +1004,21 @@ declare class GeminiStreamClient extends EventEmitter$1 {
      * @param sessionFilePath - Path to the session file to resume from
      */
     resumeSession(sessionFilePath: string): Promise<void>;
+    /**
+     * Replace CLI in-memory history with provided contents
+     *
+     * This sends a control message to the CLI to:
+     * 1. Replace the entire in-memory history with the provided contents
+     * 2. Clear session.json (DB is the source of truth)
+     *
+     * Used when messages are deleted from DB and CLI history needs to be rebuilt.
+     *
+     * @param contents - Full replacement history in Gemini Content[] format
+     */
+    replaceHistory(contents: Array<{
+        role: string;
+        parts: unknown[];
+    }>): Promise<void>;
     /**
      * Stop the CLI process
      */
@@ -945,6 +1045,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;
     /**
@@ -1034,4 +1137,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, 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 };
+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.js

@@ -492,7 +492,7 @@ var GeminiStreamClient = class extends EventEmitter {
       throw new GeminiSDKError("Process already started");
     }
     this.status = "running" /* RUNNING */;
-    if (this.options.hooks || this.options.mcpServers) {
+    if (this.options.hooks || this.options.mcpServers || this.options.tools || this.options.context) {
       await this.createTempSettings();
     }
     const args = this.buildCommand();
@@ -579,21 +579,32 @@ var GeminiStreamClient = class extends EventEmitter {
    *
    * Used for edit/retry functionality where subsequent messages need to be discarded.
    *
-   * @param fromIndex - Index from which to truncate (0-based, inclusive)
+   * @param options - Truncation options: either keepUserTurns (preferred) or fromIndex (legacy)
    */
-  async truncateHistory(fromIndex) {
+  async truncateHistory(options) {
     if (!this.isReady()) {
       throw new GeminiSDKError("Client not ready. Call start() first.");
     }
-    if (fromIndex < 0) {
-      throw new GeminiSDKError("fromIndex must be non-negative");
+    let control;
+    if (typeof options === "number") {
+      if (options < 0) {
+        throw new GeminiSDKError("fromIndex must be non-negative");
+      }
+      control = { subtype: "truncate_history", fromIndex: options };
+    } else if ("keepUserTurns" in options) {
+      if (options.keepUserTurns < 0) {
+        throw new GeminiSDKError("keepUserTurns must be non-negative");
+      }
+      control = { subtype: "truncate_history", keepUserTurns: options.keepUserTurns };
+    } else {
+      if (options.fromIndex < 0) {
+        throw new GeminiSDKError("fromIndex must be non-negative");
+      }
+      control = { subtype: "truncate_history", fromIndex: options.fromIndex };
     }
     const message = {
       type: "control" /* CONTROL */,
-      control: {
-        subtype: "truncate_history",
-        fromIndex
-      },
+      control,
       session_id: this.options.sessionId
     };
     this.writeMessage(message);
@@ -626,6 +637,31 @@ var GeminiStreamClient = class extends EventEmitter {
     };
     this.writeMessage(message);
   }
+  /**
+   * Replace CLI in-memory history with provided contents
+   *
+   * This sends a control message to the CLI to:
+   * 1. Replace the entire in-memory history with the provided contents
+   * 2. Clear session.json (DB is the source of truth)
+   *
+   * Used when messages are deleted from DB and CLI history needs to be rebuilt.
+   *
+   * @param contents - Full replacement history in Gemini Content[] format
+   */
+  async replaceHistory(contents) {
+    if (!this.isReady()) {
+      throw new GeminiSDKError("Client not ready. Call start() first.");
+    }
+    const message = {
+      type: "control" /* CONTROL */,
+      control: {
+        subtype: "replace_history",
+        contents
+      },
+      session_id: this.options.sessionId
+    };
+    this.writeMessage(message);
+  }
   /**
    * Stop the CLI process
    */
@@ -704,12 +740,15 @@ var GeminiStreamClient = class extends EventEmitter {
    * 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).
    */
   async createTempSettings() {
     const geminiConfigDir = this.options.env?.GEMINI_CONFIG_DIR;
     if (!geminiConfigDir) {
       throw new GeminiSDKError(
-        "GEMINI_CONFIG_DIR is required in options.env when using hooks or mcpServers. Please set options.env.GEMINI_CONFIG_DIR to a directory path."
+        "GEMINI_CONFIG_DIR is required in options.env when using hooks, mcpServers, tools, or context. Please set options.env.GEMINI_CONFIG_DIR to a directory path."
       );
     }
     if (!fs.existsSync(geminiConfigDir)) {
@@ -717,13 +756,32 @@ var GeminiStreamClient = class extends EventEmitter {
       this.logger.debug("Created config directory:", geminiConfigDir);
     }
     this.tempSettingsPath = path2.join(geminiConfigDir, "settings.json");
-    const settings = {};
-    if (this.options.hooks) {
+    let existingSettings = {};
+    if (fs.existsSync(this.tempSettingsPath)) {
+      try {
+        const content = fs.readFileSync(this.tempSettingsPath, "utf-8");
+        existingSettings = JSON.parse(content);
+        this.logger.debug("Read existing settings:", JSON.stringify(existingSettings, null, 2));
+      } catch (error) {
+        this.logger.warn("Failed to read existing settings.json, will overwrite:", error);
+      }
+    }
+    const settings = { ...existingSettings };
+    if (this.options.tools || this.options.hooks) {
+      const existingTools = settings.tools || {};
       settings.tools = {
-        enableHooks: true
+        ...existingTools,
+        ...this.options.tools,
+        // enableHooks is set to true if hooks are configured
+        ...this.options.hooks ? { enableHooks: true } : {}
       };
+    }
+    if (this.options.hooks) {
       settings.hooks = this.options.hooks;
     }
+    if (this.options.context) {
+      settings.context = this.options.context;
+    }
     if (this.options.mcpServers) {
       settings.mcpServers = this.options.mcpServers;
     }
@@ -746,10 +804,6 @@ var GeminiStreamClient = class extends EventEmitter {
       "--output-format",
       "stream-json"
     ];
-    if (this.options.resumeSessionFilePath) {
-      args.push("--resume-from-file", this.options.resumeSessionFilePath);
-      this.logger.debug("Resuming from session file:", this.options.resumeSessionFilePath);
-    }
     if (this.options.model) {
       args.push("--model", this.options.model);
     }