Add configurable idle heartbeats to Code Mode gRPC streams (#61385)

## What changed

- Add `code_mode.heartbeat_interval_s` to configure heartbeats after inactivity on session-event and tool-call streams. The default value of `0` disables heartbeats.
- Pass the interval through session options and gRPC requests, preserving provider defaults when overriding it.
- Ignore heartbeat messages in the client without admitting tool callbacks, and reject tool-call heartbeats that carry invocation data.

## Testing

Add coverage for disabled heartbeats, repeated idle heartbeats and timer resets after traffic, callback handling, and configuration loading. Extend TCP integration tests to verify heartbeats on both streams and continued session operation after idle periods.

GitOrigin-RevId: bf0b6d3081b5541837d07f35931e0dd3e5472c3b

codex-rs/code-mode-protocol/src/grpc/codex.code_mode.v1.proto

@@ -64,6 +64,9 @@ message OpenSessionRequest {
   // Absent preserves the legacy 1,024 callback budget. Hosts may impose a lower
   // shared limit, and older hosts ignore this field and retain their own limit.
   optional uint32 max_pending_delegate_calls = 3;
+  reserved 4; // Boolean heartbeat opt-in used by earlier preview builds.
+  // Seconds of stream inactivity before a heartbeat. Zero disables heartbeats.
+  uint32 heartbeat_interval_s = 5;
 }
 
 enum OutputTruncation {
@@ -84,6 +87,7 @@ message SessionEvent {
     Notification notification = 3;
     NotificationCancelled notification_cancelled = 4;
     CellClosed cell_closed = 5;
+    StreamHeartbeat heartbeat = 6;
   }
 }
 
@@ -102,8 +106,13 @@ message CloseSessionResponse {}
 message SubscribeToToolCallsRequest {
   string session_id = 1;
   repeated ToolName tool_names = 2;
+  reserved 3; // Boolean heartbeat opt-in used by earlier preview builds.
+  // Seconds of stream inactivity before a heartbeat. Zero disables heartbeats.
+  uint32 heartbeat_interval_s = 4;
 }
 
+message StreamHeartbeat {}
+
 message ToolCall {
   string session_id = 1;
 
@@ -123,6 +132,9 @@ message ToolCall {
   // gRPC metadata is fixed when the subscription stream opens, so each call
   // carries its own context in the message.
   optional string traceparent = 10;
+
+  // A heartbeat carries only the session ID and must not be handled as a tool call.
+  optional StreamHeartbeat heartbeat = 11;
 }
 
 message CompleteToolCallRequest {

codex-rs/code-mode-protocol/src/session.rs

@@ -57,6 +57,8 @@ pub enum CodeModeOutputTruncation {
 pub struct CodeModeSessionOptions {
     pub cell_execution_limits: CodeModeSessionCellExecutionLimits,
     pub output_truncation: CodeModeOutputTruncation,
+    /// Interval for idle gRPC heartbeats. Zero disables them.
+    pub heartbeat_interval_s: u32,
 }
 
 #[derive(Clone, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
@@ -236,6 +238,11 @@ pub trait CodeModeSessionProvider: Send + Sync {
 
     fn create_session(&self) -> CodeModeSessionProviderFuture<'_>;
 
+    /// Returns the default options for callers that need to override one setting.
+    fn default_session_options(&self) -> CodeModeSessionOptions {
+        CodeModeSessionOptions::default()
+    }
+
     /// Creates a session whose cells share the supplied execution limits.
     ///
     /// Existing providers remain compatible with unlimited sessions, but must