From 6c993aacc8fd27536131506475c5c3311189dba7 Mon Sep 17 00:00:00 2001 From: syf2211 Date: Mon, 29 Jun 2026 10:04:06 +0000 Subject: [PATCH] docs: document EnableSessionStore and one-shot session guidance Add EnableSessionStore to SessionConfig documentation and a new One-shot / Hosted Environments section across all language READMEs. Explains when to disable infinite sessions and the session store in ephemeral containers to avoid unnecessary SQLite persistence. Related to #1814 --- dotnet/README.md | 22 ++++++++++++++++++++++ go/README.md | 24 ++++++++++++++++++++++++ java/README.md | 24 ++++++++++++++++++++++++ nodejs/README.md | 21 +++++++++++++++++++++ python/README.md | 22 ++++++++++++++++++++++ rust/README.md | 22 ++++++++++++++++++++++ 6 files changed, 135 insertions(+) diff --git a/dotnet/README.md b/dotnet/README.md index 796ef2254..bdeb92ba8 100644 --- a/dotnet/README.md +++ b/dotnet/README.md @@ -125,6 +125,7 @@ Create a new conversation session. - `Provider` - Custom API provider configuration (BYOK) - `Streaming` - Enable streaming of response chunks (default: false) - `InfiniteSessions` - Configure automatic context compaction (see below) +- `EnableSessionStore` - Enables the cross-session store for search and retrieval across sessions. When unset in `CopilotCli` mode, the runtime default applies (enabled). In `Empty` mode, defaults to disabled. See [One-shot / Hosted Environments](#one-shot--hosted-environments). - `OnPermissionRequest` - Optional handler called before each tool execution to approve or deny it. When omitted, permission requests are emitted as events and left pending for manual resolution. Use `PermissionHandler.ApproveAll` to allow everything, or provide a custom function for fine-grained control. See [Permission Handling](#permission-handling) section. - `OnUserInputRequest` - Handler for user input requests from the agent (enables ask_user tool). See [User Input Requests](#user-input-requests) section. - `Hooks` - Hook handlers for session lifecycle events. See [Session Hooks](#session-hooks) section. @@ -416,6 +417,27 @@ When enabled, sessions emit compaction events: - `SessionCompactionStartEvent` - Background compaction started - `SessionCompactionCompleteEvent` - Compaction finished (includes token counts) +## One-shot / Hosted Environments + +When running the SDK in ephemeral containers or other one-shot environments (one request per container), the default session configuration enables SQLite-backed persistence features that you typically do not need: + +- **Infinite sessions** — background compaction and workspace persistence (enabled by default) +- **Session store** — cross-session search and retrieval via a shared SQLite store (enabled by default in `CopilotCli` mode when `EnableSessionStore` is unset) + +In restricted or short-lived environments, explicitly disable both to avoid unnecessary disk I/O and transient SQLite lock errors: + +```csharp +var session = await client.CreateSessionAsync(new SessionConfig +{ + Model = "gpt-5", + EnableSessionStore = false, + InfiniteSessions = new InfiniteSessionConfig { Enabled = false }, + OnPermissionRequest = PermissionHandler.ApproveAll, +}); +``` + +In `CopilotClientMode.Empty`, the SDK already defaults `EnableSessionStore` to `false`; in the default `CopilotCli` mode, you must set it explicitly. + ## Memory Sessions can opt into persistent memory, allowing the agent to read and write memory across turns. Memory is configured per session and applies to both `CreateSessionAsync` and `ResumeSessionAsync`. diff --git a/go/README.md b/go/README.md index 5787e5a53..3fea1be97 100644 --- a/go/README.md +++ b/go/README.md @@ -169,6 +169,7 @@ Event types: `SessionLifecycleCreated`, `SessionLifecycleDeleted`, `SessionLifec - `Provider` (\*ProviderConfig): Custom API provider configuration (BYOK). See [Custom Providers](#custom-providers) section. - `Streaming` (*bool): Enable streaming delta events (nil = runtime default) - `InfiniteSessions` (\*InfiniteSessionConfig): Automatic context compaction configuration +- `EnableSessionStore` (\*bool): Enables the cross-session store for search and retrieval across sessions. When unset in `ModeCopilotCli`, the runtime default applies (enabled). In `ModeEmpty`, defaults to disabled. See [One-shot / Hosted Environments](#one-shot--hosted-environments). - `OnPermissionRequest` (PermissionHandlerFunc): Optional handler called before each tool execution to approve or deny it. When nil, permission requests are emitted as events and left pending for manual resolution. Use `copilot.PermissionHandler.ApproveAll` to allow everything, or provide a custom function for fine-grained control. See [Permission Handling](#permission-handling) section. - `OnUserInputRequest` (UserInputHandler): Handler for user input requests from the agent (enables ask_user tool). See [User Input Requests](#user-input-requests) section. - `Hooks` (\*SessionHooks): Hook handlers for session lifecycle events. See [Session Hooks](#session-hooks) section. @@ -507,6 +508,29 @@ When enabled, sessions emit compaction events: - `session.compaction_start` - Background compaction started - `session.compaction_complete` - Compaction finished (includes token counts) +## One-shot / Hosted Environments + +When running the SDK in ephemeral containers or other one-shot environments (one request per container), the default session configuration enables SQLite-backed persistence features that you typically do not need: + +- **Infinite sessions** — background compaction and workspace persistence (enabled by default) +- **Session store** — cross-session search and retrieval via a shared SQLite store (enabled by default in `ModeCopilotCli` when `EnableSessionStore` is unset) + +In restricted or short-lived environments, explicitly disable both to avoid unnecessary disk I/O and transient SQLite lock errors: + +```go +falseVal := false +session, _ := client.CreateSession(context.Background(), &copilot.SessionConfig{ + Model: "gpt-5", + EnableSessionStore: &falseVal, + InfiniteSessions: &copilot.InfiniteSessionConfig{ + Enabled: copilot.Bool(false), + }, + OnPermissionRequest: copilot.PermissionHandler.ApproveAll, +}) +``` + +In `ModeEmpty`, the SDK already defaults `EnableSessionStore` to `false`; in the default `ModeCopilotCli` mode, you must set it explicitly. + ## Memory Sessions can opt in to the memory feature, which lets the agent persist and recall diff --git a/java/README.md b/java/README.md index 28544b014..cb9c58ea0 100644 --- a/java/README.md +++ b/java/README.md @@ -132,6 +132,30 @@ Or run it directly from the repository: jbang https://github.com/github/copilot-sdk/blob/main/java/jbang-example.java ``` +## One-shot / Hosted Environments + +When running the SDK in ephemeral containers or other one-shot environments (one request per container), the default session configuration enables SQLite-backed persistence features that you typically do not need: + +- **Infinite sessions** — background compaction and workspace persistence (enabled by default) +- **Session store** — cross-session search and retrieval via a shared SQLite store (enabled by default in `CopilotClientMode.COPILOT_CLI` when `enableSessionStore` is unset) + +In restricted or short-lived environments, explicitly disable both to avoid unnecessary disk I/O and transient SQLite lock errors: + +```java +import com.github.copilot.rpc.InfiniteSessionConfig; +import com.github.copilot.rpc.PermissionHandler; +import com.github.copilot.rpc.SessionConfig; + +var session = client.createSession(new SessionConfig() + .setOnPermissionRequest(PermissionHandler.APPROVE_ALL) + .setModel("gpt-5") + .setEnableSessionStore(false) + .setInfiniteSessions(new InfiniteSessionConfig().setEnabled(false)) +).get(); +``` + +In `CopilotClientMode.EMPTY`, the SDK already defaults `enableSessionStore` to `false`; in the default `CopilotClientMode.COPILOT_CLI` mode, you must set it explicitly. + ## Memory Sessions can opt into persistent memory, allowing the agent to read and write memory across turns. Memory is configured per session and applies to both `createSession` and `resumeSession`. diff --git a/nodejs/README.md b/nodejs/README.md index e9d83c6df..b5cc8e7c5 100644 --- a/nodejs/README.md +++ b/nodejs/README.md @@ -127,6 +127,7 @@ Create a new conversation session. - `tools?: Tool[]` - Custom tools exposed to the CLI. Tools without `handler` are declaration-only and must be resolved via pending tool-call RPCs. - `systemMessage?: SystemMessageConfig` - System message customization (see below) - `infiniteSessions?: InfiniteSessionConfig` - Configure automatic context compaction (see below) +- `enableSessionStore?: boolean` - Enables the cross-session store for search and retrieval across sessions. When unset in `"copilot-cli"` mode, the runtime default applies (enabled). In `"empty"` mode, defaults to disabled. See [One-shot / Hosted Environments](#one-shot--hosted-environments). - `provider?: ProviderConfig` - Custom API provider configuration (BYOK - Bring Your Own Key). See [Custom Providers](#custom-providers) section. - `onPermissionRequest?: PermissionHandler` - Optional handler called before each tool execution to approve or deny it. When omitted, permission requests are emitted as events and left pending for manual resolution. Use `approveAll` to allow everything, or provide a custom function for fine-grained control. See [Permission Handling](#permission-handling) section. - `onUserInputRequest?: UserInputHandler` - Handler for user input requests from the agent. Enables the `ask_user` tool. See [User Input Requests](#user-input-requests) section. @@ -680,6 +681,26 @@ When enabled, sessions emit compaction events: - `session.compaction_start` - Background compaction started - `session.compaction_complete` - Compaction finished (includes token counts) +### One-shot / Hosted Environments + +When running the SDK in ephemeral containers or other one-shot environments (one request per container), the default session configuration enables SQLite-backed persistence features that you typically do not need: + +- **Infinite sessions** — background compaction and workspace persistence (enabled by default) +- **Session store** — cross-session search and retrieval via a shared SQLite store (enabled by default in `"copilot-cli"` mode when `enableSessionStore` is unset) + +In restricted or short-lived environments, explicitly disable both to avoid unnecessary disk I/O and transient SQLite lock errors: + +```typescript +const session = await client.createSession({ + model: "gpt-5", + enableSessionStore: false, + infiniteSessions: { enabled: false }, + onPermissionRequest: approveAll, +}); +``` + +In `"empty"` mode, the SDK already defaults `enableSessionStore` to `false`; in the default `"copilot-cli"` mode, you must set it explicitly. + ### Memory Sessions can opt in to the memory feature, which lets the agent persist and recall diff --git a/python/README.md b/python/README.md index 86f568bd7..96a1b1a23 100644 --- a/python/README.md +++ b/python/README.md @@ -217,6 +217,7 @@ These are passed as keyword arguments to `create_session()`: - `streaming` (bool): Enable streaming delta events - `provider` (ProviderConfig): Custom API provider configuration (BYOK). See [Custom Providers](#custom-providers) section. - `infinite_sessions` (InfiniteSessionConfig): Automatic context compaction configuration +- `enable_session_store` (bool): Enables the cross-session store for search and retrieval across sessions. When unset in `"copilot-cli"` mode, the runtime default applies (enabled). In `"empty"` mode, defaults to disabled. See [One-shot / Hosted Environments](#one-shot--hosted-environments). - `on_permission_request` (callable): Optional handler called before each tool execution to approve or deny it. When omitted, permission requests are emitted as events and left pending for manual resolution. Use `PermissionHandler.approve_all` to allow everything, or provide a custom function for fine-grained control. See [Permission Handling](#permission-handling) section. - `on_user_input_request` (callable): Handler for user input requests from the agent (enables ask_user tool). See [User Input Requests](#user-input-requests) section. - `hooks` (SessionHooks): Hook handlers for session lifecycle events. See [Session Hooks](#session-hooks) section. @@ -502,6 +503,27 @@ When enabled, sessions emit compaction events: - `session.compaction_start` - Background compaction started - `session.compaction_complete` - Compaction finished (includes token counts) +## One-shot / Hosted Environments + +When running the SDK in ephemeral containers or other one-shot environments (one request per container), the default session configuration enables SQLite-backed persistence features that you typically do not need: + +- **Infinite sessions** — background compaction and workspace persistence (enabled by default) +- **Session store** — cross-session search and retrieval via a shared SQLite store (enabled by default in `"copilot-cli"` mode when `enable_session_store` is unset) + +In restricted or short-lived environments, explicitly disable both to avoid unnecessary disk I/O and transient SQLite lock errors: + +```python +async with await client.create_session( + on_permission_request=PermissionHandler.approve_all, + model="gpt-5", + enable_session_store=False, + infinite_sessions={"enabled": False}, +) as session: + ... +``` + +In `"empty"` mode, the SDK already defaults `enable_session_store` to `False`; in the default `"copilot-cli"` mode, you must set it explicitly. + ## Memory Sessions can opt into persistent memory, allowing the agent to read and write memory across turns. Memory is configured per session and applies to both `create_session` and `resume_session`. diff --git a/rust/README.md b/rust/README.md index 6d9222408..991ec8716 100644 --- a/rust/README.md +++ b/rust/README.md @@ -571,6 +571,28 @@ config.infinite_sessions = Some(infinite); The CLI emits `session.compaction_start` / `session.compaction_complete` events around each compaction. The session id remains stable across compactions; resume with `Client::resume_session` to pick up a prior conversation. Workspace state lives under `~/.copilot/session-state/{sessionId}` by default — override with `workspace_path` to relocate. +`enable_session_store` on `SessionConfig` controls the cross-session store for search and retrieval across sessions. When unset in the default client mode, the runtime default applies (enabled). In empty mode, the SDK defaults it to disabled. + +### One-shot / Hosted Environments + +When running the SDK in ephemeral containers or other one-shot environments (one request per container), the default session configuration enables SQLite-backed persistence features that you typically do not need: + +- **Infinite sessions** — background compaction and workspace persistence (enabled by default) +- **Session store** — cross-session search and retrieval via a shared SQLite store (enabled by default when `enable_session_store` is unset) + +In restricted or short-lived environments, explicitly disable both to avoid unnecessary disk I/O and transient SQLite lock errors: + +```rust,ignore +let config = SessionConfig::default() + .with_enable_session_store(false) + .with_infinite_sessions(InfiniteSessionConfig { + enabled: Some(false), + ..Default::default() + }); +``` + +In empty mode, the SDK already defaults `enable_session_store` to `false`; in the default client mode, you must set it explicitly. + ### Memory Configure the runtime memory feature for a session: