Add configurable session idle timeout option (#1093)

MackinnonBuck · Copilot · web-flow · commit b4ef955c54c8 · 2026-04-23T09:36:53.000Z
* Add sessionIdleTimeoutMs option to CopilotClientOptions Add a new optional sessionIdleTimeoutMs field to CopilotClientOptions that allows consumers to configure the server-wide session idle timeout. When set to a positive value, the SDK passes --session-idle-timeout to the CLI process. Sessions have no idle timeout by default (infinite lifetime). The minimum configurable value is 300000ms (5 minutes). Also updates the session persistence documentation to reflect the new default behavior and configuration option. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * refactor: rename sessionIdleTimeoutMs to sessionIdleTimeoutSeconds Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: correct @default tag for sessionIdleTimeoutSeconds Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: format client.ts with prettier Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * feat: add sessionIdleTimeoutSeconds to Go, Python, and .NET SDKs Add the session idle timeout option across all remaining SDK languages, consistent with the Node.js implementation and the runtime CLI's --session-idle-timeout flag. - Go: SessionIdleTimeoutSeconds int on ClientOptions - Python: session_idle_timeout_seconds on SubprocessConfig - .NET: SessionIdleTimeoutSeconds int? on CopilotClientOptions Each SDK passes --session-idle-timeout <seconds> to the CLI when the value is positive, and omits it otherwise (disabled by default). Includes unit tests for all three languages and updates the .NET clone test to cover the new property. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: add external-server caveat to Node.js and Python idle timeout docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * test: add Node.js unit tests for sessionIdleTimeoutSeconds Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: format test_client.py with ruff Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: remove incorrect minimum value from idle timeout docs The runtime does not enforce a minimum value for the session idle timeout - any positive value is accepted. Remove the 'Minimum value: 300 (5 minutes)' note from all SDK docstrings and docs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: copy SessionIdleTimeoutSeconds unconditionally in Go NewClient() The option was only copied when > 0, which silently normalized negative inputs. Other SDKs preserve the caller's value and gate only at spawn time. Align Go to match. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
diff --git a/docs/features/session-persistence.md b/docs/features/session-persistence.md
@@ -433,14 +433,26 @@ await client.deleteSession("user-123-task-456");
 
 ## Automatic Cleanup: Idle Timeout
 
-The CLI has a built-in 30-minute idle timeout. Sessions without activity are automatically cleaned up:
+By default, sessions have **no idle timeout** and live indefinitely until explicitly disconnected or deleted. You can optionally configure a server-wide idle timeout via `CopilotClientOptions.sessionIdleTimeoutSeconds`:
+
+```typescript
+const client = new CopilotClient({
+  sessionIdleTimeoutSeconds: 30 * 60, // 30 minutes
+});
+```
+
+When a timeout is configured, sessions without activity for that duration are automatically cleaned up. Set to `0` or omit to disable.
+
+> **Note:** This option only applies when the SDK spawns the runtime process. When connecting to an existing server via `cliUrl`, the server's own timeout configuration applies.
 
 ```mermaid
 flowchart LR
-    A["⚡ Last Activity"] --> B["⏳ 25 min<br/>timeout_warning"] --> C["🧹 30 min<br/>destroyed"]
+    A["⚡ Last Activity"] --> B["⏳ ~5 min before<br/>timeout_warning"] --> C["🧹 Timeout<br/>destroyed"]
 ```
 
-Listen for idle events to know when work completes:
+Sessions with active work (running commands, background agents) are always protected from idle cleanup, regardless of the timeout setting.
+
+Listen for idle events to react to session inactivity:
 
 ```typescript
 session.on("session.idle", (event) => {
diff --git a/dotnet/src/Client.cs b/dotnet/src/Client.cs
@@ -1190,6 +1190,11 @@ private async Task VerifyProtocolVersionAsync(Connection connection, Cancellatio
             args.Add("--no-auto-login");
         }
 
+        if (options.SessionIdleTimeoutSeconds is > 0)
+        {
+            args.AddRange(["--session-idle-timeout", options.SessionIdleTimeoutSeconds.Value.ToString(CultureInfo.InvariantCulture)]);
+        }
+
         var (fileName, processArgs) = ResolveCliCommand(cliPath, args);
 
         var startInfo = new ProcessStartInfo
diff --git a/dotnet/src/Types.cs b/dotnet/src/Types.cs
@@ -69,6 +69,7 @@ protected CopilotClientOptions(CopilotClientOptions? other)
         UseStdio = other.UseStdio;
         OnListModels = other.OnListModels;
         SessionFs = other.SessionFs;
+        SessionIdleTimeoutSeconds = other.SessionIdleTimeoutSeconds;
     }
 
     /// <summary>
@@ -165,6 +166,15 @@ public string? GithubToken
     /// </summary>
     public TelemetryConfig? Telemetry { get; set; }
 
+    /// <summary>
+    /// Server-wide idle timeout for sessions in seconds.
+    /// Sessions without activity for this duration are automatically cleaned up.
+    /// Set to <c>0</c> or leave as <see langword="null"/> to disable (sessions live indefinitely).
+    /// This option is only used when the SDK spawns the CLI process; it is ignored
+    /// when connecting to an external server via <see cref="CliUrl"/>.
+    /// </summary>
+    public int? SessionIdleTimeoutSeconds { get; set; }
+
     /// <summary>
     /// Creates a shallow clone of this <see cref="CopilotClientOptions"/> instance.
     /// </summary>
diff --git a/dotnet/test/ClientTests.cs b/dotnet/test/ClientTests.cs
@@ -216,6 +216,25 @@ public void Should_Throw_When_UseLoggedInUser_Used_With_CliUrl()
         });
     }
 
+    [Fact]
+    public void Should_Default_SessionIdleTimeoutSeconds_To_Null()
+    {
+        var options = new CopilotClientOptions();
+
+        Assert.Null(options.SessionIdleTimeoutSeconds);
+    }
+
+    [Fact]
+    public void Should_Accept_SessionIdleTimeoutSeconds_Option()
+    {
+        var options = new CopilotClientOptions
+        {
+            SessionIdleTimeoutSeconds = 600
+        };
+
+        Assert.Equal(600, options.SessionIdleTimeoutSeconds);
+    }
+
     [Fact]
     public async Task Should_Not_Throw_When_Disposing_Session_After_Stopping_Client()
     {
diff --git a/dotnet/test/CloneTests.cs b/dotnet/test/CloneTests.cs
@@ -26,6 +26,7 @@ public void CopilotClientOptions_Clone_CopiesAllProperties()
             Environment = new Dictionary<string, string> { ["KEY"] = "value" },
             GitHubToken = "ghp_test",
             UseLoggedInUser = false,
+            SessionIdleTimeoutSeconds = 600,
         };
 
         var clone = original.Clone();
@@ -42,6 +43,7 @@ public void CopilotClientOptions_Clone_CopiesAllProperties()
         Assert.Equal(original.Environment, clone.Environment);
         Assert.Equal(original.GitHubToken, clone.GitHubToken);
         Assert.Equal(original.UseLoggedInUser, clone.UseLoggedInUser);
+        Assert.Equal(original.SessionIdleTimeoutSeconds, clone.SessionIdleTimeoutSeconds);
     }
 
     [Fact]
diff --git a/go/client.go b/go/client.go
@@ -215,6 +215,10 @@ func NewClient(options *ClientOptions) *Client {
 			sessionFs := *options.SessionFs
 			opts.SessionFs = &sessionFs
 		}
+		if options.Telemetry != nil {
+			opts.Telemetry = options.Telemetry
+		}
+		opts.SessionIdleTimeoutSeconds = options.SessionIdleTimeoutSeconds
 	}
 
 	// Default Env to current environment if not set
@@ -1378,6 +1382,10 @@ func (c *Client) startCLIServer(ctx context.Context) error {
 		args = append(args, "--no-auto-login")
 	}
 
+	if c.options.SessionIdleTimeoutSeconds > 0 {
+		args = append(args, "--session-idle-timeout", strconv.Itoa(c.options.SessionIdleTimeoutSeconds))
+	}
+
 	// If CLIPath is a .js file, run it with node
 	// Note we can't rely on the shebang as Windows doesn't support it
 	command := cliPath
diff --git a/go/client_test.go b/go/client_test.go
@@ -391,6 +391,26 @@ func TestClient_EnvOptions(t *testing.T) {
 	})
 }
 
+func TestClient_SessionIdleTimeoutSeconds(t *testing.T) {
+	t.Run("should store SessionIdleTimeoutSeconds option", func(t *testing.T) {
+		client := NewClient(&ClientOptions{
+			SessionIdleTimeoutSeconds: 600,
+		})
+
+		if client.options.SessionIdleTimeoutSeconds != 600 {
+			t.Errorf("Expected SessionIdleTimeoutSeconds to be 600, got %d", client.options.SessionIdleTimeoutSeconds)
+		}
+	})
+
+	t.Run("should default SessionIdleTimeoutSeconds to zero", func(t *testing.T) {
+		client := NewClient(&ClientOptions{})
+
+		if client.options.SessionIdleTimeoutSeconds != 0 {
+			t.Errorf("Expected SessionIdleTimeoutSeconds to be 0, got %d", client.options.SessionIdleTimeoutSeconds)
+		}
+	})
+}
+
 func findCLIPathForTest() string {
 	abs, _ := filepath.Abs("../nodejs/node_modules/@github/copilot/index.js")
 	if fileExistsForTest(abs) {
diff --git a/go/types.go b/go/types.go
@@ -71,6 +71,12 @@ type ClientOptions struct {
 	// When non-nil, COPILOT_OTEL_ENABLED=true is set and any populated fields
 	// are mapped to the corresponding environment variables.
 	Telemetry *TelemetryConfig
+	// SessionIdleTimeoutSeconds configures the server-wide session idle timeout in seconds.
+	// Sessions without activity for this duration are automatically cleaned up.
+	// Set to 0 or leave unset to disable (sessions live indefinitely).
+	// This option is only used when the SDK spawns the CLI process; it is ignored
+	// when connecting to an external server via CLIUrl.
+	SessionIdleTimeoutSeconds int
 }
 
 // TelemetryConfig configures OpenTelemetry integration for the Copilot CLI process.
diff --git a/nodejs/src/client.ts b/nodejs/src/client.ts
@@ -340,6 +340,7 @@ export class CopilotClient {
             // Default useLoggedInUser to false when githubToken is provided, otherwise true
             useLoggedInUser: options.useLoggedInUser ?? (options.githubToken ? false : true),
             telemetry: options.telemetry,
+            sessionIdleTimeoutSeconds: options.sessionIdleTimeoutSeconds ?? 0,
         };
     }
 
@@ -1414,6 +1415,16 @@ export class CopilotClient {
                 args.push("--no-auto-login");
             }
 
+            if (
+                this.options.sessionIdleTimeoutSeconds !== undefined &&
+                this.options.sessionIdleTimeoutSeconds > 0
+            ) {
+                args.push(
+                    "--session-idle-timeout",
+                    this.options.sessionIdleTimeoutSeconds.toString()
+                );
+            }
+
             // Suppress debug/trace output that might pollute stdout
             const envWithoutNodeDebug = { ...this.options.env };
             delete envWithoutNodeDebug.NODE_DEBUG;
diff --git a/nodejs/src/types.ts b/nodejs/src/types.ts
@@ -184,6 +184,16 @@ export interface CopilotClientOptions {
      * instead of the server's default local filesystem storage.
      */
     sessionFs?: SessionFsConfig;
+
+    /**
+     * Server-wide idle timeout for sessions in seconds.
+     * Sessions without activity for this duration are automatically cleaned up.
+     * Set to 0 or omit to disable (sessions live indefinitely).
+     * This option is only used when the SDK spawns the CLI process; it is ignored
+     * when connecting to an external server via {@link cliUrl}.
+     * @default undefined (disabled)
+     */
+    sessionIdleTimeoutSeconds?: number;
 }
 
 /**
diff --git a/nodejs/test/client.test.ts b/nodejs/test/client.test.ts
@@ -1258,4 +1258,23 @@ describe("CopilotClient", () => {
             rpcSpy.mockRestore();
         });
     });
+
+    describe("sessionIdleTimeoutSeconds", () => {
+        it("should default to 0 when not specified", () => {
+            const client = new CopilotClient({
+                logLevel: "error",
+            });
+
+            expect((client as any).options.sessionIdleTimeoutSeconds).toBe(0);
+        });
+
+        it("should store a custom value", () => {
+            const client = new CopilotClient({
+                sessionIdleTimeoutSeconds: 600,
+                logLevel: "error",
+            });
+
+            expect((client as any).options.sessionIdleTimeoutSeconds).toBe(600);
+        });
+    });
 });
diff --git a/python/copilot/client.py b/python/copilot/client.py
@@ -150,6 +150,14 @@ class SubprocessConfig:
     session_fs: SessionFsConfig | None = None
     """Connection-level session filesystem provider configuration."""
 
+    session_idle_timeout_seconds: int | None = None
+    """Server-wide session idle timeout in seconds.
+
+    Sessions without activity for this duration are automatically cleaned up.
+    Set to ``None`` or ``0`` to disable (sessions live indefinitely).
+    This option is only used when the SDK spawns the CLI process.
+    """
+
 
 @dataclass
 class ExternalServerConfig:
@@ -2261,6 +2269,9 @@ async def _start_cli_server(self) -> None:
         if not cfg.use_logged_in_user:
             args.append("--no-auto-login")
 
+        if cfg.session_idle_timeout_seconds is not None and cfg.session_idle_timeout_seconds > 0:
+            args.extend(["--session-idle-timeout", str(cfg.session_idle_timeout_seconds)])
+
         # If cli_path is a .js file, run it with node
         # Note that we can't rely on the shebang as Windows doesn't support it
         if cli_path.endswith(".js"):
diff --git a/python/test_client.py b/python/test_client.py
@@ -204,6 +204,24 @@ def test_explicit_use_logged_in_user_false_without_token(self):
         assert client._config.use_logged_in_user is False
 
 
+class TestSessionIdleTimeoutSeconds:
+    def test_accepts_session_idle_timeout_seconds(self):
+        client = CopilotClient(
+            SubprocessConfig(
+                cli_path=CLI_PATH,
+                session_idle_timeout_seconds=600,
+                log_level="error",
+            )
+        )
+        assert isinstance(client._config, SubprocessConfig)
+        assert client._config.session_idle_timeout_seconds == 600
+
+    def test_default_session_idle_timeout_seconds_is_none(self):
+        client = CopilotClient(SubprocessConfig(cli_path=CLI_PATH, log_level="error"))
+        assert isinstance(client._config, SubprocessConfig)
+        assert client._config.session_idle_timeout_seconds is None
+
+
 class TestOverridesBuiltInTool:
     @pytest.mark.asyncio
     async def test_overrides_built_in_tool_sent_in_tool_definition(self):

Original file line number	Diff line number	Diff line change
`@@ -215,6 +215,10 @@ func NewClient(options ClientOptions) Client {`
`215`	`215`	`sessionFs := *options.SessionFs`
`216`	`216`	`opts.SessionFs = &sessionFs`
`217`	`217`	`}`
	`218`	`+ if options.Telemetry != nil {`
	`219`	`+ opts.Telemetry = options.Telemetry`
	`220`	`+ }`
	`221`	`+ opts.SessionIdleTimeoutSeconds = options.SessionIdleTimeoutSeconds`
`218`	`222`	`}`
`219`	`223`
`220`	`224`	`// Default Env to current environment if not set`
`@@ -1378,6 +1382,10 @@ func (c *Client) startCLIServer(ctx context.Context) error {`
`1378`	`1382`	`args = append(args, "--no-auto-login")`
`1379`	`1383`	`}`
`1380`	`1384`
	`1385`	`+ if c.options.SessionIdleTimeoutSeconds > 0 {`
	`1386`	`+ args = append(args, "--session-idle-timeout", strconv.Itoa(c.options.SessionIdleTimeoutSeconds))`
	`1387`	`+ }`
	`1388`	`+`
`1381`	`1389`	`// If CLIPath is a .js file, run it with node`
`1382`	`1390`	`// Note we can't rely on the shebang as Windows doesn't support it`
`1383`	`1391`	`command := cliPath`