@ketd/gemini-cli-sdk 0.3.6 → 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;
 }
 /**
@@ -733,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
@@ -971,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
      *
@@ -986,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
      */

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;
 }
 /**
@@ -733,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
@@ -971,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
      *
@@ -986,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
      */

package/dist/index.js

@@ -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
    */
@@ -768,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);
     }