refactor(sdk): introduce session-based architecture by mbleigh · Pull Request #19180 · google-gemini/gemini-cli

mbleigh · 2026-02-16T00:57:53Z

This change introduces the GeminiCliSession class to manage conversation state, separating it from the main GeminiCliAgent. This allows for cleaner session management and enables session resumption.

BREAKING CHANGE: The sendStream method on GeminiCliAgent has been removed. Use agent.session().sendStream() instead.

This change introduces the GeminiCliSession class to manage conversation state, separating it from the main GeminiCliAgent. This allows for cleaner session management and enables session resumption. BREAKING CHANGE: The `sendStream` method on `GeminiCliAgent` has been removed. Use `agent.session().sendStream()` instead.

gemini-cli · 2026-02-16T00:58:03Z

Hi there! Thank you for your contribution to Gemini CLI.

To improve our contribution process and better track changes, we now require all pull requests to be associated with an existing issue, as announced in our recent discussion and as detailed in our CONTRIBUTING.md.

This pull request is being closed because it is not currently linked to an issue. Once you have updated the description of this PR to link an issue (e.g., by adding Fixes #123 or Related to #123), it will be automatically reopened.

How to link an issue:
Add a keyword followed by the issue number (e.g., Fixes #123) in the description of your pull request. For more details on supported keywords and how linking works, please refer to the GitHub Documentation on linking pull requests to issues.

Thank you for your understanding and for being a part of our community!

gemini-cli · 2026-02-16T00:58:05Z

Hi @mbleigh, thank you so much for your contribution to Gemini CLI! We really appreciate the time and effort you've put into this.

We're making some updates to our contribution process to improve how we track and review changes. Please take a moment to review our recent discussion post: Improving Our Contribution Process & Introducing New Guidelines.

Key Update: Starting January 26, 2026, the Gemini CLI project will require all pull requests to be associated with an existing issue. Any pull requests not linked to an issue by that date will be automatically closed.

Thank you for your understanding and for being a part of our community!

gemini-code-assist · 2026-02-16T00:58:18Z

Summary of Changes

Hello @mbleigh, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant architectural refactor to the SDK by implementing a session-based approach for managing conversations. The core GeminiCliAgent now focuses on creating and resuming conversation sessions, delegating the actual conversation logic and state management to a new GeminiCliSession class. This change improves modularity, clarifies responsibilities, and lays the groundwork for robust session persistence and resumption features, enhancing the overall developer experience and flexibility of the SDK.

Highlights

Introduced GeminiCliSession class: A new GeminiCliSession class has been introduced to encapsulate conversation state, tool/skill management, and the sendStream method, separating these concerns from the main GeminiCliAgent.
Refactored GeminiCliAgent: The GeminiCliAgent has been refactored to act as a factory for GeminiCliSession instances, providing session() and resumeSession() methods. It no longer directly handles conversation streaming or internal configuration management.
Session Resumption Capability: The new architecture enables session resumption, allowing users to pick up previous conversations. The GeminiCliAgent now includes a resumeSession() method to facilitate this.
Breaking Change: sendStream method moved: The sendStream method has been removed from GeminiCliAgent. Consumers must now call agent.session().sendStream() or (await agent.resumeSession()).sendStream().
Updated Documentation and Tests: The SDK_DESIGN.md documentation and all relevant integration tests have been updated to reflect the new session-based API and usage patterns.

Changelog

packages/core/src/index.ts
- Exported createSessionId function.
packages/core/src/utils/session.ts
- Added createSessionId function to generate new UUIDs for sessions.
packages/sdk/SDK_DESIGN.md
- Updated documentation to reflect the new session() and resumeSession() methods on GeminiCliAgent.
- Removed sendStream from GeminiCliAgent examples.
- Added session: GeminiCliSession to the SessionContext interface.
packages/sdk/src/agent.integration.test.ts
- Updated integration tests to use the new agent.session().sendStream() pattern.
- Added a new integration test for resumeSession functionality.
- Removed previous tests related to dynamic instructions directly on the agent.
packages/sdk/src/agent.ts
- Refactored GeminiCliAgent to remove direct sendStream implementation.
- Introduced session() method to create new GeminiCliSession instances.
- Added resumeSession() method to load and resume existing conversation sessions from storage.
- Removed internal Config initialization and tool/skill loading logic, delegating it to GeminiCliSession.
packages/sdk/src/index.ts
- Exported the new session.js module.
packages/sdk/src/session.ts
- Added new file defining the GeminiCliSession class.
- Implemented GeminiCliSession to manage individual conversation state, including Config initialization, tool/skill loading, dynamic instruction handling, and the sendStream method.
- Included logic for resuming conversations from stored data within the session.
packages/sdk/src/skills.integration.test.ts
- Updated skill integration tests to use agent.session().sendStream().
packages/sdk/src/tool.integration.test.ts
- Updated tool integration tests to use agent.session().sendStream().
packages/sdk/src/types.ts
- Moved SystemInstructions and GeminiCliAgentOptions interfaces from agent.ts.
- Added GeminiCliSession type import.
- Added an optional session?: GeminiCliSession property to the SessionContext interface.
packages/sdk/test-data/agent-dynamic-instructions.json
- Updated test data to reflect changes in dynamic instruction handling.
packages/sdk/test-data/agent-resume-session.json
- Added new test data for session resumption scenarios.
packages/sdk/test-data/agent-static-instructions.json
- Updated test data.
packages/sdk/test-data/skill-dir-success.json
- Updated test data.
packages/sdk/test-data/skill-root-success.json
- Updated test data.
packages/sdk/test-data/tool-catchall-error.json
- Updated test data.
packages/sdk/test-data/tool-error-recovery.json
- Updated test data.
packages/sdk/test-data/tool-success.json
- Updated test data.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces a session-based architecture, separating conversation state from the main GeminiCliAgent into a new GeminiCliSession class, which improves modularity and enables session resumption. A critical security concern has been identified: the default configuration of the policy engine within the new GeminiCliSession class defaults to allowing all tool calls. This could lead to Remote Code Execution (RCE) if an agent is compromised via prompt injection, and it is recommended to change this default to a more secure 'deny-by-default' stance. Additionally, errors in dynamic instruction loading are silently ignored, and there is an inconsistent type definition for SessionContext in the public API.

github-actions · 2026-02-16T22:15:29Z

Size Change: +1.69 kB (+0.01%)

Total Size: 24.6 MB

Filename	Size	Change
`./bundle/gemini.js`	24.5 MB	+1.69 kB (+0.01%)

ℹ️ View Unchanged

Filename	Size
`./bundle/sandbox-macos-permissive-open.sb`	890 B
`./bundle/sandbox-macos-permissive-proxied.sb`	1.31 kB
`./bundle/sandbox-macos-restrictive-open.sb`	3.36 kB
`./bundle/sandbox-macos-restrictive-proxied.sb`	3.56 kB
`./bundle/sandbox-macos-strict-open.sb`	4.82 kB
`./bundle/sandbox-macos-strict-proxied.sb`	5.02 kB

_{compressed-size-action}

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

…mini-cli into sdk-05-refactor-session

gemini-cli · 2026-02-17T02:59:54Z

Hi there! Thank you for your contribution to Gemini CLI.

To improve our contribution process and better track changes, we now require all pull requests to be associated with an existing issue, as announced in our recent discussion and as detailed in our CONTRIBUTING.md.

This pull request is being closed because it is not currently linked to an issue. Once you have updated the description of this PR to link an issue (e.g., by adding Fixes #123 or Related to #123), it will be automatically reopened.

How to link an issue:
Add a keyword followed by the issue number (e.g., Fixes #123) in the description of your pull request. For more details on supported keywords and how linking works, please refer to the GitHub Documentation on linking pull requests to issues.

Thank you for your understanding and for being a part of our community!

NTaylorMullen · 2026-02-17T18:49:26Z

-      const registry = this.config.getToolRegistry();
-      const messageBus = this.config.getMessageBus();
+  async resumeSession(sessionId?: string): Promise<GeminiCliSession> {
+    const cwd = this.options.cwd || process.cwd();


It'd be interesting to try and bind a session to a specific file path. Otherwise resuming from a different one would be a bit odd

The sessions are essentially bound to a specific file path, because they are loaded from the project temp dir. So it can only resume a session for the same cwd path as implemented now.

NTaylorMullen · 2026-02-17T18:50:15Z

-        registry.registerTool(sdkTool);
-      }
-    }
+    const chatsDir = path.join(storage.getProjectTempDir(), 'chats');


There should be options for this BUT I'd imagine we'd want to utilize the storage object directly. Does it make sense to surface the normal dir that's used by the CLI?

Yeah, good callout. Added some new methods to storage to do this more directly.

NTaylorMullen · 2026-02-17T18:52:05Z

+    // Sort by mtime desc
+    fileStats.sort((a, b) => b.mtime - a.mtime);
+
+    let targetFile: { filePath: string } | undefined;


Feels odd to surface target file as a json array. After sorting above might just be worth mapping the file paths down to their final file path for readability

NTaylorMullen · 2026-02-17T18:53:05Z

-            prompt_id: sessionId,
-          });
+        } catch (_e) {
+          // Ignore parse errors


Hmm, feels like a debug log should be here. I'd imagine not finding your chat history would be super frustrating otherwise

Adding a TODO for this to come back to when I do logging.

NTaylorMullen · 2026-02-17T18:54:37Z

+      targetFile = fileStats[0];
    }
+
+    const content = await fs.promises.readFile(targetFile.filePath, 'utf8');


Instead of re-reading the file path (since we already did) it might be worth eagerly returning above instead of breaking

NTaylorMullen · 2026-02-17T18:55:18Z

+  private readonly tools: Array<Tool<any>>;
+  private readonly skillRefs: SkillReference[];
+  private readonly instructions: SystemInstructions | undefined;
+  private client: GeminiClient | undefined;


What is a session without a client?

Client is initialized async based on the config, so it can't be required. But it's effectively required.

NTaylorMullen · 2026-02-17T18:56:11Z

+    this.tools = options.tools || [];
+    this.skillRefs = options.skills || [];
+
+    const initialMemory =


Should we be throwing if the instructions aren't a string? Feels like falling back to empty string will bite a lot of people

NTaylorMullen · 2026-02-17T18:56:48Z

+
+      const loadPromises = this.skillRefs.map(async (ref) => {
+        try {
+          if (ref.type === 'dir' || ref.type === 'root') {


Left a comment in another PR around using "user" and "workspace" to align with existing CLI verbiage

I actually cleaned this up there but this is a straggler - the type here is not 'user' or 'workspace' since it's allowing passing in arbitrary directories. But the 'dir' and 'root' distinction doesn't matter because the loader will automatically detect and handle nested directories. Once we have in-memory skills we'll add a second, non-"dir" type here.

NTaylorMullen · 2026-02-17T18:57:04Z

+          }
+        } catch (e) {
+          // eslint-disable-next-line no-console
+          console.error(`Failed to load skills from ${ref.path}:`, e);


For SDK's we should probably have a dedicated logger stack instead of relying on console

Will do this in a followup as it's a bit of a big change to tack in here.

NTaylorMullen · 2026-02-17T18:57:38Z

+    }
+
+    // Re-register ActivateSkillTool if we have skills
+    const skillManager = this.config.getSkillManager();


I'll stop reviewing this bit, had a few other comments in other PRs about surfacing a lot of these bits in the core CLI instead of re-implementing

mbleigh · 2026-02-17T22:20:50Z

+
+      const loadPromises = this.skillRefs.map(async (ref) => {
+        try {
+          if (ref.type === 'dir' || ref.type === 'root') {


I actually cleaned this up there but this is a straggler - the type here is not 'user' or 'workspace' since it's allowing passing in arbitrary directories. But the 'dir' and 'root' distinction doesn't matter because the loader will automatically detect and handle nested directories. Once we have in-memory skills we'll add a second, non-"dir" type here.

mbleigh · 2026-02-17T22:31:08Z

-            prompt_id: sessionId,
-          });
+        } catch (_e) {
+          // Ignore parse errors


Adding a TODO for this to come back to when I do logging.

mbleigh · 2026-02-17T22:37:54Z

-        registry.registerTool(sdkTool);
-      }
-    }
+    const chatsDir = path.join(storage.getProjectTempDir(), 'chats');


Yeah, good callout. Added some new methods to storage to do this more directly.

mbleigh · 2026-02-18T01:27:47Z

-      const registry = this.config.getToolRegistry();
-      const messageBus = this.config.getMessageBus();
+  async resumeSession(sessionId?: string): Promise<GeminiCliSession> {
+    const cwd = this.options.cwd || process.cwd();


The sessions are essentially bound to a specific file path, because they are loaded from the project temp dir. So it can only resume a session for the same cwd path as implemented now.

mbleigh · 2026-02-18T01:28:22Z

+  private readonly tools: Array<Tool<any>>;
+  private readonly skillRefs: SkillReference[];
+  private readonly instructions: SystemInstructions | undefined;
+  private client: GeminiClient | undefined;


Client is initialized async based on the config, so it can't be required. But it's effectively required.

mbleigh · 2026-02-18T01:29:37Z

+            return await loadSkillsFromDir(ref.path);
+          }
+        } catch (e) {
+          // eslint-disable-next-line no-console


Suggested change

// eslint-disable-next-line no-console

// TODO: refactor this to use a proper logger interface

// eslint-disable-next-line no-console

mbleigh · 2026-02-18T01:29:52Z

+          }
+        } catch (e) {
+          // eslint-disable-next-line no-console
+          console.error(`Failed to load skills from ${ref.path}:`, e);


Will do this in a followup as it's a bit of a big change to tack in here.

gemini-cli · 2026-02-18T03:01:04Z

Hi there! Thank you for your contribution to Gemini CLI.

To improve our contribution process and better track changes, we now require all pull requests to be associated with an existing issue, as announced in our recent discussion and as detailed in our CONTRIBUTING.md.

This pull request is being closed because it is not currently linked to an issue. Once you have updated the description of this PR to link an issue (e.g., by adding Fixes #123 or Related to #123), it will be automatically reopened.

How to link an issue:
Add a keyword followed by the issue number (e.g., Fixes #123) in the description of your pull request. For more details on supported keywords and how linking works, please refer to the GitHub Documentation on linking pull requests to issues.

Thank you for your understanding and for being a part of our community!

…mini-cli into sdk-05-refactor-session

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

) Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

) Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

mbleigh requested a review from NTaylorMullen February 16, 2026 00:57

mbleigh requested a review from a team as a code owner February 16, 2026 00:57

gemini-cli Bot closed this Feb 16, 2026

gemini-code-assist Bot reviewed Feb 16, 2026

View reviewed changes

Comment thread packages/sdk/src/session.ts Outdated

Comment thread packages/sdk/src/session.ts

Comment thread packages/sdk/src/types.ts Outdated

mbleigh reopened this Feb 16, 2026

Update packages/sdk/src/types.ts

7e39654

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

gemini-cli Bot added the status/need-issue Pull requests that need to have an associated issue. label Feb 16, 2026

mbleigh and others added 3 commits February 16, 2026 15:34

fix(sdk): address code review comments

a0d90c1

Merge branch 'sdk-05-refactor-session' of github.com:google-gemini/ge…

4785999

…mini-cli into sdk-05-refactor-session

Merge branch 'main' into sdk-05-refactor-session

525f7c8

gemini-cli Bot closed this Feb 17, 2026

mbleigh reopened this Feb 17, 2026

Merge branch 'main' into sdk-05-refactor-session

fe24839

NTaylorMullen reviewed Feb 17, 2026

View reviewed changes

mbleigh added 2 commits February 17, 2026 14:22

fix(sdk): align skill types with CLI verbiage

4a3fae7

fix(sdk): throw error if instructions are missing or invalid

d757fd3

mbleigh force-pushed the sdk-05-refactor-session branch from 766b2cf to 2118700 Compare February 18, 2026 01:14

fix(sdk): refactor session loading to use optimized Storage methods

33e4c12

mbleigh force-pushed the sdk-05-refactor-session branch from 2118700 to 33e4c12 Compare February 18, 2026 01:25

mbleigh commented Feb 18, 2026

View reviewed changes

mbleigh added 2 commits February 17, 2026 17:34

fix(sdk): add TODO to refactor console.error to a proper logger

6a60754

fix(sdk): make sessionId required for resumeSession to improve security

f90b057

mbleigh requested a review from NTaylorMullen February 18, 2026 01:40

Merge branch 'main' into sdk-05-refactor-session

8be3078

gemini-cli Bot closed this Feb 18, 2026

mbleigh reopened this Feb 19, 2026

mbleigh and others added 3 commits February 19, 2026 09:46

Merge branch 'main' into sdk-05-refactor-session

4103ed8

fix: lint

51456c7

Merge branch 'sdk-05-refactor-session' of github.com:google-gemini/ge…

f6ce492

…mini-cli into sdk-05-refactor-session

NTaylorMullen approved these changes Feb 19, 2026

View reviewed changes

mbleigh and others added 2 commits February 19, 2026 16:16

Merge conflict resolved in packages/core/src/config/storage.test.ts

ecbd3f9

Merge branch 'main' into sdk-05-refactor-session

6339286

mbleigh enabled auto-merge February 20, 2026 00:38

mbleigh added this pull request to the merge queue Feb 20, 2026

Merged via the queue into main with commit f1c0a69 Feb 20, 2026
27 checks passed

mbleigh deleted the sdk-05-refactor-session branch February 20, 2026 00:57

spencer426 pushed a commit that referenced this pull request Feb 20, 2026

refactor(sdk): introduce session-based architecture (#19180)

2b9da3b

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

spencer426 pushed a commit that referenced this pull request Feb 20, 2026

refactor(sdk): introduce session-based architecture (#19180)

78e2ddc

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

gemini-code-assist Bot mentioned this pull request Feb 23, 2026

Changelog for v0.30.0-nightly.20260223.c537fd5ae #19981

Closed

JagjeevanAK mentioned this pull request Mar 6, 2026

voice personal assistant layer JagjeevanAK/gemini-cli#1

Open

cocosheng-g pushed a commit that referenced this pull request May 6, 2026

refactor(sdk): introduce session-based architecture (#19180)

bc21c39

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

sripasg added the size/l A large sized PR label Jun 2, 2026

	// eslint-disable-next-line no-console
	// TODO: refactor this to use a proper logger interface
	// eslint-disable-next-line no-console

Uh oh!

Conversation

mbleigh commented Feb 16, 2026

Uh oh!

gemini-cli Bot commented Feb 16, 2026

Uh oh!

gemini-cli Bot commented Feb 16, 2026

Uh oh!

gemini-code-assist Bot commented Feb 16, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-cli Bot commented Feb 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-cli Bot commented Feb 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

github-actions Bot commented Feb 16, 2026 •

edited

Loading