feat(core): migrate chat recording to JSONL streaming

[spencer426]

Summary

Migrates ChatRecordingService from rewriting entire large JSON session files to an efficient, append-only JSON Lines (.jsonl) streaming log.

Details

• JSON Lines Format: Session storage now uses .jsonl. The initial session metadata is written as the first line, followed by individual message objects appended via fs.appendFileSync as they are created or updated.
• Efficient Loading: initialize() and loadConversationRecord() reconstruct the conversation strictly from the .jsonl log, preserving insertion and update order, without ever holding the full file in memory simultaneously.
• Memory-Safe List Rendering: Loading operations like sessionUtils.ts (used for rendering the UI's session browser) now utilize a metadataOnly: true option inside loadConversationRecord. This bypasses allocating massive arrays into active RAM entirely, extracting only scalar bounds and string IDs directly from the stream.
• OOM Resilient File Deletions: deleteSessionAndArtifacts() has been rewritten to open an async fs.promises.FileHandle and read only the first 4KB chunk of the .jsonl file. This safely extracts the metadata sessionId without attempting to load potentially gigabyte-sized files synchronously into Node.js memory.
• Legacy Compatibility: Added a robust fallback to loadConversationRecord to gracefully read, parse, and process monolithic .json sessions from prior versions of the CLI. This includes correctly computing hasUserOrAssistantMessage, messageCount, and firstUserMessage from legacy payloads when run in metadataOnly mode, ensuring users do not lose their history or break the session UI upon upgrading.

Related Issues

Resolves #23740

How to Validate

1. Run npm run test or npm run preflight.
2. Start the CLI (npm start) and run a few prompts.
3. Observe session-*.jsonl files generated in the .gemini/tmp/chats directory.
4. Exit the CLI and resume the session (npm start -- --resume). The history should load smoothly.
5. Ensure old .json sessions are still visible when running npm start -- --resume.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[gemini-code-assist]

Summary of Changes

Hello, 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 significantly refactors the chat recording mechanism to improve performance and memory efficiency. By transitioning from a monolithic JSON file to a JSON Lines streaming log, the system avoids expensive full-file parsing and unbounded memory consumption, particularly with large conversations or tool outputs. This change ensures that chat history is managed more robustly, allowing for efficient loading and storage while maintaining data integrity.

Highlights

• JSON Lines (JSONL) Format Adoption: Session storage has been migrated from a single JSON file to an append-only JSON Lines (.jsonl) streaming log. Initial session metadata is written as the first line, with subsequent message objects appended individually.
• Bounded Memory for Conversations: The active in-memory conversation array (cachedConversation.messages) is now strictly bounded to the last 50 messages to prevent unbounded memory growth.
• Aggressive Tool Output Truncation: Tool output payloads exceeding 50KB are aggressively truncated in the active memory array, replaced with a placeholder message, while the full content is safely persisted in the JSONL log.
• Efficient Conversation Loading: The initialize() and loadConversationRecord() functions now reconstruct conversations directly from the .jsonl log, preserving insertion and update order without loading the entire file into memory simultaneously.
• Refactored Session Utilities: Key utilities in sessionUtils.ts and the SDK's agent.ts have been updated to leverage the new loadConversationRecord() function for reading session logs, eliminating full JSON parsing.

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.

Footnotes

1. 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. ↩

[github-actions]

Size Change: +4.41 kB (+0.01%)

Total Size: 34 MB

Filename	Size	Change
./bundle/chunk-566LYU6X.js	0 B	-3.47 kB (removed)	🏆
./bundle/chunk-ETSDHTGW.js	0 B	-1.96 MB (removed)	🏆
./bundle/chunk-JDSH6FD2.js	0 B	-14.8 MB (removed)	🏆
./bundle/chunk-LONHTAXY.js	0 B	-3.16 MB (removed)	🏆
./bundle/core-D7E3UXGF.js	0 B	-45.6 kB (removed)	🏆
./bundle/devtoolsService-OCOUXNDV.js	0 B	-28.4 kB (removed)	🏆
./bundle/gemini-ABXPZJXL.js	0 B	-552 kB (removed)	🏆
./bundle/interactiveCli-XBPYDL2C.js	0 B	-1.64 MB (removed)	🏆
./bundle/oauth2-provider-OFYK3K5G.js	0 B	-9.16 kB (removed)	🏆
./bundle/chunk-5NENR2YT.js	1.96 MB	+1.96 MB (new file)	🆕
./bundle/chunk-USMR747Z.js	3.47 kB	+3.47 kB (new file)	🆕
./bundle/chunk-W5YS77RC.js	14.8 MB	+14.8 MB (new file)	🆕
./bundle/chunk-Z5E5G2OS.js	3.16 MB	+3.16 MB (new file)	🆕
./bundle/core-R3B5MHPN.js	45.7 kB	+45.7 kB (new file)	🆕
./bundle/devtoolsService-RPTRHL2H.js	28.4 kB	+28.4 kB (new file)	🆕
./bundle/gemini-IINMSRZX.js	552 kB	+552 kB (new file)	🆕
./bundle/interactiveCli-ILWVHRV7.js	1.64 MB	+1.64 MB (new file)	🆕
./bundle/oauth2-provider-UJFIMEVP.js	9.16 kB	+9.16 kB (new file)	🆕

ℹ️ View Unchanged

Filename	Size	Change
./bundle/bundled/third_party/index.js	8 MB	0 B
./bundle/chunk-34MYV7JD.js	2.45 kB	0 B
./bundle/chunk-5AUYMPVF.js	858 B	0 B
./bundle/chunk-5PS3AYFU.js	1.18 kB	0 B
./bundle/chunk-664ZODQF.js	124 kB	0 B
./bundle/chunk-DAHVX5MI.js	206 kB	0 B
./bundle/chunk-IUUIT4SU.js	56.5 kB	0 B
./bundle/chunk-RJTRUG2J.js	39.8 kB	0 B
./bundle/cleanup-ACZHUEBX.js	0 B	-856 B (removed)	🏆
./bundle/devtools-36NN55EP.js	696 kB	0 B
./bundle/dist-T73EYRDX.js	356 B	0 B
./bundle/events-XB7DADIJ.js	418 B	0 B
./bundle/gemini.js	4.97 kB	0 B
./bundle/getMachineId-bsd-TXG52NKR.js	1.55 kB	0 B
./bundle/getMachineId-darwin-7OE4DDZ6.js	1.55 kB	0 B
./bundle/getMachineId-linux-SHIFKOOX.js	1.34 kB	0 B
./bundle/getMachineId-unsupported-5U5DOEYY.js	1.06 kB	0 B
./bundle/getMachineId-win-6KLLGOI4.js	1.72 kB	0 B
./bundle/memoryDiscovery-YL35JRSL.js	0 B	-980 B (removed)	🏆
./bundle/multipart-parser-KPBZEGQU.js	11.7 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	222 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	229 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	13.4 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B	0 B
./bundle/sandbox-macos-permissive-open.sb	890 B	0 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB	0 B
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB	0 B
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB	0 B
./bundle/sandbox-macos-strict-open.sb	4.82 kB	0 B
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB	0 B
./bundle/src-QVCVGIUX.js	47 kB	0 B
./bundle/tree-sitter-7U6MW5PS.js	274 kB	0 B
./bundle/tree-sitter-bash-34ZGLXVX.js	1.84 MB	0 B
./bundle/cleanup-HJGAC7DN.js	856 B	+856 B (new file)	🆕
./bundle/memoryDiscovery-GD6P6WBI.js	980 B	+980 B (new file)	🆕

_{compressed-size-action}

[gemini-code-assist]

Code Review

This pull request refactors the chat session recording mechanism to use a JSON Lines (JSONL) format, enabling append-only writes and introducing bounded memory management for in-memory conversation history. Key changes include the introduction of an asynchronous loadConversationRecord function, updates to ChatRecordingService for JSONL handling, and corresponding modifications across the CLI and SDK for session loading and management. However, two high-severity issues were identified: a Denial of Service (DoS) vulnerability in deleteSessionAndArtifacts due to reading entire large files into memory, and another DoS vulnerability in loadConversationRecord where all messages are loaded into memory before truncation, potentially leading to Out-Of-Memory errors.

[gemini-cli]

Hi there! Thank you for your interest in contributing to Gemini CLI.

To ensure we maintain high code quality and focus on our prioritized roadmap, we have updated our contribution policy (see Discussion #17383).

We only guarantee review and consideration of pull requests for issues that are explicitly labeled as 'help wanted'. All other community pull requests are subject to closure after 14 days if they do not align with our current focus areas. For this reason, we strongly recommend that contributors only submit pull requests against issues explicitly labeled as 'help-wanted'.

This pull request is being closed as it has been open for 14 days without a 'help wanted' designation. We encourage you to find and contribute to existing 'help wanted' issues in our backlog! Thank you for your understanding and for being part of our community!

[abhipatel12]

Left a few comments, lmk what you think

[abhipatel12]

What happens if a user on a new version (i.e. preview channel) starts a session, decides they want to move back to a stable version.

In that case, the user's client will only look for json trajectories right? In that case, are we ack'ing that we wont support that edge case?

[spencer426]

This implementation will not support forward-compatibility for this specific downgrade edge case. If a user on a newer version tarts a session, that session will be saved as a .jsonl file. If they then downgrade their CLI back to an older, stable version that predates this feature, their client will only know how to look for and read .json files.

[abhipatel12]

Just a couple more questions!

[abhipatel12]

lgtm thanks!