feat(runtime-api): add PUT /v1/sessions endpoint for engine-based session save

[gaord]

Focused slice from #2808: add a PUT /v1/sessions endpoint that saves a thread's current engine state as a session. This is the session-save slice that @Hmbown identified as the next harvest target.

New endpoint: PUT /v1/sessions saves a thread live engine state as a session via a oneshot channel, so token counts and message ordering are authoritative. Unlike POST /v1/sessions (which reconstructs from turn items), this matches TUI build_session_snapshot behavior. Backward compatible: existing POST endpoint is preserved.

Implementation: SessionSnapshot struct + Op::GetSessionSnapshot variant (ops.rs), engine loop handler (engine.rs), get_session_snapshot method (handle.rs), get_engine public wrapper (runtime_threads.rs), PUT /v1/sessions route + save_current_session handler (runtime_api.rs).

Bug fix: load_session errors were silently swallowed by Err(_) wildcard. Only io::ErrorKind::NotFound now falls back to creating a new session; other I/O errors (e.g. PermissionDenied) are propagated.

Not included (need atomicity tests): undo, patch-undo, retry, restore-snapshot, ToolCall/FileChange reconstruction.

Ref: #2808

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[gemini-code-assist]

Code Review

This pull request introduces a new PUT /v1/sessions endpoint to save a thread's current engine state as a session by requesting a live snapshot directly from the engine. Key changes include adding the GetSessionSnapshot operation to the engine, exposing get_engine in RuntimeThreadManager, and implementing the save_current_session handler. Feedback focuses on casting token counts to u64 to prevent overflow, optimizing the retrieval of the most recent thread by using threads.first() instead of max_by_key, and using the map_session_err helper to ensure consistent and accurate API error responses when loading or saving sessions.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

To prevent potential overflow and ensure type compatibility with SessionSnapshot::total_tokens (which is u64), cast the input_tokens and output_tokens to u64 before performing the addition.

Suggested change

	let total_tokens = self.session.total_usage.input_tokens
	+ self.session.total_usage.output_tokens;
	let total_tokens = u64::from(self.session.total_usage.input_tokens)
	+ u64::from(self.session.total_usage.output_tokens);

[gemini-code-assist]

Since list_threads already returns threads sorted descending by updated_at (most recent first), finding the maximum via max_by_key is redundant and runs in $O(N)$ time. Using threads.first() is cleaner, runs in $O(1)$ time, and avoids consuming the iterator.

Suggested change

	threads
	.into_iter()
	.max_by_key(|t| t.updated_at)
	.map(|t| t.id)
	.ok_or_else(|| ApiError::bad_request("No threads to save"))?
	threads
	.first()
	.map(|t| t.id.clone())
	.ok_or_else(|| ApiError::bad_request("No threads to save"))?

[gemini-code-assist]

Use the existing map_session_err helper function to map the error. This ensures that client-side errors (like InvalidInput for malformed session IDs) are correctly translated to 400 Bad Request instead of generic 500 Internal Server Error responses.

                    return Err(map_session_err(existing_id, e, "load"));

[gemini-code-assist]

Use the existing map_session_err helper function to map the error when saving the session. This ensures that any validation or I/O errors are mapped consistently and client-side errors are correctly surfaced as 400 Bad Request instead of 500 Internal Server Error.

Suggested change

	manager
	.save_session(&session)
	.map_err(|e| ApiError::internal(format!("Failed to save session: {e}")))?;
	manager
	.save_session(&session)
	.map_err(|e| map_session_err(&session.metadata.id, e, "save"))?;

[Hmbown]

Thank you @gaord! The PUT /v1/sessions snapshot path — using a oneshot so it does not contend with the SSE stream — is a nice design. Landed in the v0.8.61 release prep with your authorship after a tiny rustfmt pass. Appreciated.

[Hmbown]

Thank you @gaord — the runtime-api session-save (PUT /v1/sessions) shipped in v0.8.61. Closing as resolved; credited. 🐳