docs: clarify session destroy vs delete semantics (#599)

* docs: clarify session destroy vs delete semantics across all SDKs

Clarify the distinction between destroy() (closes session, releases
in-memory resources, preserves disk state for resumption) and
deleteSession() (permanently removes all data from disk).

Update doc comments across all four SDK languages (Go, Node.js, Python,
.NET) and the session persistence guide to make the behavioral
difference explicit and help users choose the right method.

Fixes #526

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* feat: add disconnect() method, deprecate destroy() across all SDKs

Add disconnect() as the preferred method for closing sessions across all
four SDK languages, marking destroy() as deprecated:

- Node.js: disconnect() + Symbol.asyncDispose support, destroy() delegates
- Python: disconnect() + __aenter__/__aexit__ context manager, destroy()
  emits DeprecationWarning
- Go: Disconnect() method, Destroy() marked with Deprecated godoc tag
- .NET: DisconnectAsync() method, DisposeAsync() delegates to it

Update all samples, READMEs, and documentation guides to use the new
disconnect() terminology. Internal stop() methods now call disconnect().

Resolves PR #599 comments:
- Rename destroy → disconnect for clarity
- Define IDisposable behavior in .NET (DisposeAsync delegates to
  DisconnectAsync)
- Add idiomatic cleanup patterns (async context managers, Symbol.asyncDispose)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* chore: update all tests, scenarios, and docs to use disconnect()

Migrate all test scenarios, e2e tests, READMEs, and documentation
references from destroy()/Destroy() to disconnect()/Disconnect().

- 90 test scenario files across Go/Python/TypeScript/C#
- 15 Node.js e2e test files
- 8 Python e2e test files
- 3 Go e2e test files
- 1 .NET test file
- READMEs and compatibility docs updated with new API reference
- Agent docs updated with new method names
- Reconnect scenario log messages updated to 'disconnected'

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: rename snapshot to match updated test name

The hooks_extended test 'should invoke onSessionEnd hook when session is
destroyed' was renamed to '...disconnected', but the snapshot YAML file
wasn't renamed to match, causing CI to fail with 'No cached response'.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* dotnet: remove DisconnectAsync, keep only DisposeAsync

Address review feedback from SteveSandersonMS: for .NET, the
standard IAsyncDisposable pattern (DisposeAsync) is sufficient
on its own without a duplicate DisconnectAsync method.

Moves the disconnect implementation directly into DisposeAsync
and removes the separate DisconnectAsync method. Updates all
references in Client.cs and README.md accordingly.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: patniko

.github/agents/docs-maintenance.agent.md

@@ -344,7 +344,7 @@ cat nodejs/src/types.ts | grep -A 10 "export interface ExportSessionOptions"
 **Must match:**
 - `CopilotClient` constructor options: `cliPath`, `cliUrl`, `useStdio`, `port`, `logLevel`, `autoStart`, `autoRestart`, `env`, `githubToken`, `useLoggedInUser`
 - `createSession()` config: `model`, `tools`, `hooks`, `systemMessage`, `mcpServers`, `availableTools`, `excludedTools`, `streaming`, `reasoningEffort`, `provider`, `infiniteSessions`, `customAgents`, `workingDirectory`
-- `CopilotSession` methods: `send()`, `sendAndWait()`, `getMessages()`, `destroy()`, `abort()`, `on()`, `once()`, `off()`
+- `CopilotSession` methods: `send()`, `sendAndWait()`, `getMessages()`, `disconnect()`, `abort()`, `on()`, `once()`, `off()`
 - Hook names: `onPreToolUse`, `onPostToolUse`, `onUserPromptSubmitted`, `onSessionStart`, `onSessionEnd`, `onErrorOccurred`
 
 #### Python Validation
@@ -362,7 +362,7 @@ cat python/copilot/types.py | grep -A 15 "class SessionHooks"
 **Must match (snake_case):**
 - `CopilotClient` options: `cli_path`, `cli_url`, `use_stdio`, `port`, `log_level`, `auto_start`, `auto_restart`, `env`, `github_token`, `use_logged_in_user`
 - `create_session()` config keys: `model`, `tools`, `hooks`, `system_message`, `mcp_servers`, `available_tools`, `excluded_tools`, `streaming`, `reasoning_effort`, `provider`, `infinite_sessions`, `custom_agents`, `working_directory`
-- `CopilotSession` methods: `send()`, `send_and_wait()`, `get_messages()`, `destroy()`, `abort()`, `export_session()`
+- `CopilotSession` methods: `send()`, `send_and_wait()`, `get_messages()`, `disconnect()`, `abort()`, `export_session()`
 - Hook names: `on_pre_tool_use`, `on_post_tool_use`, `on_user_prompt_submitted`, `on_session_start`, `on_session_end`, `on_error_occurred`
 
 #### Go Validation
@@ -380,7 +380,7 @@ cat go/types.go | grep -A 15 "type SessionHooks struct"
 **Must match (PascalCase for exported):**
 - `ClientOptions` fields: `CLIPath`, `CLIUrl`, `UseStdio`, `Port`, `LogLevel`, `AutoStart`, `AutoRestart`, `Env`, `GithubToken`, `UseLoggedInUser`
 - `SessionConfig` fields: `Model`, `Tools`, `Hooks`, `SystemMessage`, `MCPServers`, `AvailableTools`, `ExcludedTools`, `Streaming`, `ReasoningEffort`, `Provider`, `InfiniteSessions`, `CustomAgents`, `WorkingDirectory`
-- `Session` methods: `Send()`, `SendAndWait()`, `GetMessages()`, `Destroy()`, `Abort()`, `ExportSession()`
+- `Session` methods: `Send()`, `SendAndWait()`, `GetMessages()`, `Disconnect()`, `Abort()`, `ExportSession()`
 - Hook fields: `OnPreToolUse`, `OnPostToolUse`, `OnUserPromptSubmitted`, `OnSessionStart`, `OnSessionEnd`, `OnErrorOccurred`
 
 #### .NET Validation

docs/auth/byok.md

@@ -54,7 +54,7 @@ async def main():
     await session.send({"prompt": "What is 2+2?"})
     await done.wait()
 
-    await session.destroy()
+    await session.disconnect()
     await client.stop()
 
 asyncio.run(main())

docs/compatibility.md

@@ -15,7 +15,8 @@ The Copilot SDK communicates with the CLI via JSON-RPC protocol. Features must b
 | **Session Management** | | |
 | Create session | `createSession()` | Full config support |
 | Resume session | `resumeSession()` | With infinite session workspaces |
-| Destroy session | `destroy()` | Clean up resources |
+| Disconnect session | `disconnect()` | Release in-memory resources |
+| Destroy session *(deprecated)* | `destroy()` | Use `disconnect()` instead |
 | Delete session | `deleteSession()` | Remove from storage |
 | List sessions | `listSessions()` | All stored sessions |
 | Get last session | `getLastSessionId()` | For quick resume |

docs/debugging.md

@@ -248,9 +248,9 @@ var client = new CopilotClient(new CopilotClientOptions
 
 **Solution:**
 
-1. Ensure you're not calling methods after `destroy()`:
+1. Ensure you're not calling methods after `disconnect()`:
    ```typescript
-   await session.destroy();
+   await session.disconnect();
    // Don't use session after this!
    ```
 

docs/guides/session-persistence.md

@@ -325,24 +325,46 @@ async function cleanupExpiredSessions(maxAgeMs: number) {
 await cleanupExpiredSessions(24 * 60 * 60 * 1000);
 ```
 
-### Explicit Session Destruction
+### Disconnecting from a Session (`disconnect`)
 
-When a task completes, destroy the session explicitly rather than waiting for timeouts:
+When a task completes, disconnect from the session explicitly rather than waiting for timeouts. This releases in-memory resources but **preserves session data on disk**, so the session can still be resumed later:
 
 ```typescript
 try {
   // Do work...
   await session.sendAndWait({ prompt: "Complete the task" });
 
-  // Task complete - clean up
-  await session.destroy();
+  // Task complete — release in-memory resources (session can be resumed later)
+  await session.disconnect();
 } catch (error) {
   // Clean up even on error
-  await session.destroy();
+  await session.disconnect();
   throw error;
 }
 ```
 
+Each SDK also provides idiomatic automatic cleanup patterns:
+
+| Language | Pattern | Example |
+|----------|---------|---------|
+| **TypeScript** | `Symbol.asyncDispose` | `await using session = await client.createSession(config);` |
+| **Python** | `async with` context manager | `async with await client.create_session(config) as session:` |
+| **C#** | `IAsyncDisposable` | `await using var session = await client.CreateSessionAsync(config);` |
+| **Go** | `defer` | `defer session.Disconnect()` |
+
+> **Note:** `destroy()` is deprecated in favor of `disconnect()`. Existing code using `destroy()` will continue to work but should be migrated.
+
+### Permanently Deleting a Session (`deleteSession`)
+
+To permanently remove a session and all its data from disk (conversation history, planning state, artifacts), use `deleteSession`. This is irreversible — the session **cannot** be resumed after deletion:
+
+```typescript
+// Permanently remove session data
+await client.deleteSession("user-123-task-456");
+```
+
+> **`disconnect()` vs `deleteSession()`:** `disconnect()` releases in-memory resources but keeps session data on disk for later resumption. `deleteSession()` permanently removes everything, including files on disk.
+
 ## Automatic Cleanup: Idle Timeout
 
 The CLI has a built-in 30-minute idle timeout. Sessions without activity are automatically cleaned up:
@@ -526,8 +548,8 @@ await withSessionLock("user-123-task-456", async () => {
 | **Resume session** | `client.resumeSession(sessionId)` |
 | **BYOK resume** | Re-provide `provider` config |
 | **List sessions** | `client.listSessions(filter?)` |
-| **Delete session** | `client.deleteSession(sessionId)` |
-| **Destroy active session** | `session.destroy()` |
+| **Disconnect from active session** | `session.disconnect()` — releases in-memory resources; session data on disk is preserved for resumption |
+| **Delete session permanently** | `client.deleteSession(sessionId)` — permanently removes all session data from disk; cannot be resumed |
 | **Containerized deployment** | Mount `~/.copilot/session-state/` to persistent storage |
 
 ## Next Steps

docs/guides/setup/azure-managed-identity.md

@@ -118,7 +118,7 @@ class ManagedIdentityCopilotAgent:
         session = await self.client.create_session(config)
 
         response = await session.send_and_wait({"prompt": prompt})
-        await session.destroy()
+        await session.disconnect()
 
         return response.data.content if response else ""
 ```

docs/guides/setup/backend-services.md

@@ -319,7 +319,7 @@ async function processJob(job: Job) {
     });
 
     await saveResult(job.id, response?.data.content);
-    await session.destroy();  // Clean up after job completes
+    await session.disconnect();  // Clean up after job completes
 }
 ```
 

docs/guides/setup/scaling.md

@@ -412,8 +412,8 @@ class SessionManager {
     private async evictOldestSession(): Promise<void> {
         const [oldestId] = this.activeSessions.keys();
         const session = this.activeSessions.get(oldestId)!;
-        // Session state is persisted automatically — safe to destroy
-        await session.destroy();
+        // Session state is persisted automatically — safe to disconnect
+        await session.disconnect();
         this.activeSessions.delete(oldestId);
     }
 }
@@ -457,7 +457,7 @@ app.post("/api/analyze", async (req, res) => {
         });
         res.json({ result: response?.data.content });
     } finally {
-        await session.destroy();  // Clean up immediately
+        await session.disconnect();  // Clean up immediately
     }
 });
 ```

docs/mcp/overview.md

@@ -132,7 +132,7 @@ func main() {
     if err != nil {
         log.Fatal(err)
     }
-    defer session.Destroy()
+    defer session.Disconnect()
 
     // Use the session...
 }
@@ -191,7 +191,7 @@ async function main() {
 
     console.log("Response:", result?.data?.content);
 
-    await session.destroy();
+    await session.disconnect();
     await client.stop();
 }
 

dotnet/README.md

@@ -219,7 +219,17 @@ Get all events/messages from this session.
 
 ##### `DisposeAsync(): ValueTask`
 
-Dispose the session and free resources.
+Close the session and release in-memory resources. Session data on disk is preserved — the conversation can be resumed later via `ResumeSessionAsync()`. To permanently delete session data, use `client.DeleteSessionAsync()`.
+
+```csharp
+// Preferred: automatic cleanup via await using
+await using var session = await client.CreateSessionAsync(config);
+// session is automatically disposed when leaving scope
+
+// Alternative: explicit dispose
+var session2 = await client.CreateSessionAsync(config);
+await session2.DisposeAsync();
+```
 
 ---