From 7e794c4cf1e451cd0c366a9291f51e4c91d3c414 Mon Sep 17 00:00:00 2001 From: Mackinnon Buck Date: Thu, 16 Apr 2026 11:24:10 -0700 Subject: [PATCH 1/4] 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> --- docs/features/session-persistence.md | 18 +++++++++++++++--- nodejs/src/client.ts | 5 +++++ nodejs/src/types.ts | 9 +++++++++ 3 files changed, 29 insertions(+), 3 deletions(-) diff --git a/docs/features/session-persistence.md b/docs/features/session-persistence.md index 19e53c385..2576ea50a 100644 --- 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.sessionIdleTimeoutMs`: + +```typescript +const client = new CopilotClient({ + sessionIdleTimeoutMs: 30 * 60 * 1000, // 30 minutes +}); +``` + +When a timeout is configured, sessions without activity for that duration are automatically cleaned up. The minimum value is 5 minutes (300,000ms). 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
timeout_warning"] --> C["🧹 30 min
destroyed"] + A["⚡ Last Activity"] --> B["⏳ ~5 min before
timeout_warning"] --> C["🧹 Timeout
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/nodejs/src/client.ts b/nodejs/src/client.ts index c5b84a6d4..7ff77a930 100644 --- a/nodejs/src/client.ts +++ b/nodejs/src/client.ts @@ -339,6 +339,7 @@ export class CopilotClient { // Default useLoggedInUser to false when githubToken is provided, otherwise true useLoggedInUser: options.useLoggedInUser ?? (options.githubToken ? false : true), telemetry: options.telemetry, + sessionIdleTimeoutMs: options.sessionIdleTimeoutMs ?? 0, }; } @@ -1385,6 +1386,10 @@ export class CopilotClient { args.push("--no-auto-login"); } + if (this.options.sessionIdleTimeoutMs !== undefined && this.options.sessionIdleTimeoutMs > 0) { + args.push("--session-idle-timeout", this.options.sessionIdleTimeoutMs.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 index 0c901f989..150cb2457 100644 --- a/nodejs/src/types.ts +++ b/nodejs/src/types.ts @@ -182,6 +182,15 @@ export interface CopilotClientOptions { * instead of the server's default local filesystem storage. */ sessionFs?: SessionFsConfig; + + /** + * Server-wide idle timeout for sessions in milliseconds. + * Sessions without activity for this duration are automatically cleaned up. + * Set to 0 or omit to disable (sessions live indefinitely). + * Minimum value: 300000 (5 minutes). + * @default 0 (disabled) + */ + sessionIdleTimeoutMs?: number; } /** From 02d0ca246e722938188aab1aba8aa1a346ecdd02 Mon Sep 17 00:00:00 2001 From: Mackinnon Buck Date: Thu, 16 Apr 2026 13:47:12 -0700 Subject: [PATCH 2/4] refactor: rename sessionIdleTimeoutMs to sessionIdleTimeoutSeconds Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/features/session-persistence.md | 6 +++--- nodejs/src/client.ts | 6 +++--- nodejs/src/types.ts | 6 +++--- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/features/session-persistence.md b/docs/features/session-persistence.md index 2576ea50a..a790a117a 100644 --- a/docs/features/session-persistence.md +++ b/docs/features/session-persistence.md @@ -433,15 +433,15 @@ await client.deleteSession("user-123-task-456"); ## Automatic Cleanup: Idle Timeout -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.sessionIdleTimeoutMs`: +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({ - sessionIdleTimeoutMs: 30 * 60 * 1000, // 30 minutes + sessionIdleTimeoutSeconds: 30 * 60, // 30 minutes }); ``` -When a timeout is configured, sessions without activity for that duration are automatically cleaned up. The minimum value is 5 minutes (300,000ms). Set to `0` or omit to disable. +When a timeout is configured, sessions without activity for that duration are automatically cleaned up. The minimum value is 300 seconds (5 minutes). 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. diff --git a/nodejs/src/client.ts b/nodejs/src/client.ts index 7ff77a930..c58ea1c66 100644 --- a/nodejs/src/client.ts +++ b/nodejs/src/client.ts @@ -339,7 +339,7 @@ export class CopilotClient { // Default useLoggedInUser to false when githubToken is provided, otherwise true useLoggedInUser: options.useLoggedInUser ?? (options.githubToken ? false : true), telemetry: options.telemetry, - sessionIdleTimeoutMs: options.sessionIdleTimeoutMs ?? 0, + sessionIdleTimeoutSeconds: options.sessionIdleTimeoutSeconds ?? 0, }; } @@ -1386,8 +1386,8 @@ export class CopilotClient { args.push("--no-auto-login"); } - if (this.options.sessionIdleTimeoutMs !== undefined && this.options.sessionIdleTimeoutMs > 0) { - args.push("--session-idle-timeout", this.options.sessionIdleTimeoutMs.toString()); + 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 diff --git a/nodejs/src/types.ts b/nodejs/src/types.ts index 150cb2457..4c715d221 100644 --- a/nodejs/src/types.ts +++ b/nodejs/src/types.ts @@ -184,13 +184,13 @@ export interface CopilotClientOptions { sessionFs?: SessionFsConfig; /** - * Server-wide idle timeout for sessions in milliseconds. + * 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). - * Minimum value: 300000 (5 minutes). + * Minimum value: 300 (5 minutes). * @default 0 (disabled) */ - sessionIdleTimeoutMs?: number; + sessionIdleTimeoutSeconds?: number; } /** From 282f1a49eab2c0a5dc47bdf553ed1da47eb41e37 Mon Sep 17 00:00:00 2001 From: Mackinnon Buck Date: Thu, 16 Apr 2026 16:00:10 -0700 Subject: [PATCH 3/4] fix: correct @default tag for sessionIdleTimeoutSeconds Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- nodejs/src/types.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/nodejs/src/types.ts b/nodejs/src/types.ts index 4c715d221..59cbffac9 100644 --- a/nodejs/src/types.ts +++ b/nodejs/src/types.ts @@ -188,7 +188,7 @@ export interface CopilotClientOptions { * Sessions without activity for this duration are automatically cleaned up. * Set to 0 or omit to disable (sessions live indefinitely). * Minimum value: 300 (5 minutes). - * @default 0 (disabled) + * @default undefined (disabled) */ sessionIdleTimeoutSeconds?: number; } From ede32da58537e9ab7b63ac25d284dc738a444bb3 Mon Sep 17 00:00:00 2001 From: Mackinnon Buck Date: Thu, 16 Apr 2026 16:34:23 -0700 Subject: [PATCH 4/4] fix: format client.ts with prettier Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- nodejs/src/client.ts | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/nodejs/src/client.ts b/nodejs/src/client.ts index c58ea1c66..fad4e7054 100644 --- a/nodejs/src/client.ts +++ b/nodejs/src/client.ts @@ -1386,8 +1386,14 @@ 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()); + 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