From e6784d43407d6c36ec40fcb8067d44b46349efbb Mon Sep 17 00:00:00 2001
From: Copilot <copilot@github.com>
Date: Fri, 6 Mar 2026 13:53:32 +0000
Subject: [PATCH] feat: add disconnect! as preferred session close method,
 deprecate destroy!

Port upstream PR #599: add disconnect() as the preferred method for
closing sessions across all SDKs, with destroy() deprecated to delegate
to disconnect().

Changes:
- Add session/disconnect! with same semantics as destroy! (sends
  session.destroy RPC, clears handlers, closes event channel)
- Deprecate session/destroy! to delegate to disconnect!
- Add disconnect! to github.copilot-sdk top-level namespace
- Update with-session and with-client-session macros to use disconnect!
- Update client stop! to call session/disconnect! internally
- Add disconnect! to both instrument-all! and unstrument-all! lists
- Document disconnect! in API reference, mark destroy! as deprecated

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 CHANGELOG.md                          |  8 ++++++++
 doc/reference/API.md                  | 10 ++++++++++
 doc/style.md                          |  2 +-
 src/github/copilot_sdk.clj            | 22 +++++++++++++++++-----
 src/github/copilot_sdk/client.clj     |  6 +++---
 src/github/copilot_sdk/instrument.clj |  8 ++++++++
 src/github/copilot_sdk/session.clj    | 27 +++++++++++++++++++++------
 7 files changed, 68 insertions(+), 15 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 588363d..26c9c8d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,14 @@ All notable changes to this project will be documented in this file. This change
 
 ## [Unreleased]
 
+### Added (v0.1.30 sync)
+- `disconnect!` function as the preferred way to close a session. Same semantics as `destroy!` — sends `session.destroy` RPC and releases in-memory resources while preserving disk state for resumption (upstream PR #599).
+
+### Changed (v0.1.30 sync)
+- `destroy!` is now deprecated and delegates to `disconnect!`. Matches upstream Node.js SDK where `destroy()` was deprecated in favor of `disconnect()` (upstream PR #599).
+- `with-session` and `with-client-session` macros now call `disconnect!` instead of `destroy!` in their cleanup forms.
+- `stop!` in client now internally calls `session/disconnect!` instead of `session/destroy!`.
+
 ## [0.1.30.0] - 2026-03-04
 ### Added (v0.1.30 sync)
 
diff --git a/doc/reference/API.md b/doc/reference/API.md
index 1b92942..7a93b60 100644
--- a/doc/reference/API.md
+++ b/doc/reference/API.md
@@ -780,12 +780,22 @@ Alias for `switch-model!`, matching the upstream SDK's `setModel()` API.
 ;; After: claude-sonnet-4.5
 ```
 
+#### `disconnect!`
+
+```clojure
+(copilot/disconnect! session)
+```
+
+Disconnect the session and free resources. Session data on disk is preserved for later resumption via `resume-session`. Use `delete-session!` to permanently remove session data from disk.
+
 #### `destroy!`
 
 ```clojure
 (copilot/destroy! session)
 ```
 
+**Deprecated**: Use `disconnect!` instead.
+
 Destroy the session and free resources.
 
 #### `session-id`
diff --git a/doc/style.md b/doc/style.md
index f5884e9..5c1603a 100644
--- a/doc/style.md
+++ b/doc/style.md
@@ -50,7 +50,7 @@ Short paragraphs (1–3 sentences). Use code blocks liberally.
 - Use `h` as the alias for `github.copilot-sdk.helpers`
 - Use `session` as the alias for `github.copilot-sdk.session`
 - Prefer `def` over `let` in top-level examples for clarity
-- Include cleanup (`stop!`, `destroy!`) in lifecycle examples
+- Include cleanup (`stop!`, `disconnect!`) in lifecycle examples
 
 ### What to Avoid
 
diff --git a/src/github/copilot_sdk.clj b/src/github/copilot_sdk.clj
index 457aea0..04d3671 100644
--- a/src/github/copilot_sdk.clj
+++ b/src/github/copilot_sdk.clj
@@ -409,7 +409,7 @@
   (client/<create-session client config))
 
 (defmacro with-session
-  "Create a session and ensure destroy! on exit.
+  "Create a session and ensure disconnect! on exit.
 
    Usage:
    (with-session [s client {:on-permission-request copilot/approve-all
@@ -420,11 +420,11 @@
      (try
        ~@body
        (finally
-         (destroy! ~session-sym)))))
+         (disconnect! ~session-sym)))))
 
 (defmacro with-client-session
   "Create a client + session and ensure cleanup on exit.
-   Automatically calls destroy! on session and stop! on client.
+   Automatically calls disconnect! on session and stop! on client.
 
    Four forms are supported:
 
@@ -666,10 +666,22 @@
   [session]
   (session/get-messages session))
 
+(defn disconnect!
+  "Disconnect the session and free resources.
+   Session data on disk is preserved for later resumption via resume-session.
+
+   This is the preferred way to close a session. Use delete-session! to
+   permanently remove session data from disk."
+  [session]
+  (session/disconnect! session))
+
 (defn destroy!
-  "Destroy the session and free resources."
+  "Destroy the session and free resources.
+
+   Deprecated: Use disconnect! instead. This function will be removed in a
+   future release."
   [session]
-  (session/destroy! session))
+  (session/disconnect! session))
 
 (defn events
   "Get the event mult for this session. Use tap/untap to subscribe:
diff --git a/src/github/copilot_sdk/client.clj b/src/github/copilot_sdk/client.clj
index 8a57159..38300c1 100644
--- a/src/github/copilot_sdk/client.clj
+++ b/src/github/copilot_sdk/client.clj
@@ -605,13 +605,13 @@
         (close! router-ch))
       (swap! (:state client) assoc :router-ch nil :router-queue nil :router-thread nil)
 
-      ;; 1. Destroy all sessions
+      ;; 1. Disconnect all sessions
       (doseq [[session-id _] sessions]
         (try
-          (session/destroy! client session-id)
+          (session/disconnect! client session-id)
           (catch Exception e
             (swap! errors conj
-                   (ex-info (str "Failed to destroy session " session-id)
+                   (ex-info (str "Failed to disconnect session " session-id)
                             {:session-id session-id} e)))))
       (swap! (:state client) assoc :sessions {} :session-io {})
 
diff --git a/src/github/copilot_sdk/instrument.clj b/src/github/copilot_sdk/instrument.clj
index b3a8b79..0cc3683 100644
--- a/src/github/copilot_sdk/instrument.clj
+++ b/src/github/copilot_sdk/instrument.clj
@@ -169,6 +169,12 @@
   :args (s/cat :session ::specs/session)
   :ret (s/coll-of map?))
 
+(s/fdef github.copilot-sdk.session/disconnect!
+  :args (s/alt :handle (s/cat :session ::specs/session)
+               :explicit (s/cat :client ::specs/client
+                                :session-id ::specs/session-id))
+  :ret nil?)
+
 (s/fdef github.copilot-sdk.session/destroy!
   :args (s/alt :handle (s/cat :session ::specs/session)
                :explicit (s/cat :client ::specs/client
@@ -275,6 +281,7 @@
                       github.copilot-sdk.session/<send!
                       github.copilot-sdk.session/abort!
                       github.copilot-sdk.session/get-messages
+                      github.copilot-sdk.session/disconnect!
                       github.copilot-sdk.session/destroy!
                       github.copilot-sdk.session/session-id
                       github.copilot-sdk.session/workspace-path
@@ -323,6 +330,7 @@
                       github.copilot-sdk.session/<send!
                       github.copilot-sdk.session/abort!
                       github.copilot-sdk.session/get-messages
+                      github.copilot-sdk.session/disconnect!
                       github.copilot-sdk.session/destroy!
                       github.copilot-sdk.session/session-id
                       github.copilot-sdk.session/workspace-path
diff --git a/src/github/copilot_sdk/session.clj b/src/github/copilot_sdk/session.clj
index 7d6181a..67684c5 100644
--- a/src/github/copilot_sdk/session.clj
+++ b/src/github/copilot_sdk/session.clj
@@ -598,13 +598,17 @@
           result (proto/send-request! conn "session.getMessages" {:session-id session-id})]
       (mapv #(update % :type util/event-type->keyword) (:events result)))))
 
-(defn destroy!
-  "Destroy the session and free resources.
-   Can be called with either a CopilotSession handle or (client, session-id)."
+(defn disconnect!
+  "Disconnect the session and free resources.
+   Session data on disk is preserved for later resumption via resume-session.
+   Can be called with either a CopilotSession handle or (client, session-id).
+
+   This is the preferred way to close a session. Use delete-session! in
+   client to permanently remove session data from disk."
   ([session]
-   (destroy! (:client session) (:session-id session)))
+   (disconnect! (:client session) (:session-id session)))
   ([client session-id]
-   (log/debug "Destroying session: " session-id)
+   (log/debug "Disconnecting session: " session-id)
    (when-not (:destroyed? (session-state client session-id))
      (let [conn (connection-io client)]
        ;; Try to notify server, but don't block forever if connection is broken
@@ -621,9 +625,20 @@
        ;; Close the event source channel - this propagates to all tapped channels
        (when-let [{:keys [event-chan]} (session-io client session-id)]
          (close! event-chan))
-       (log/debug "Session destroyed: " session-id)
+       (log/debug "Session disconnected: " session-id)
        nil))))
 
+(defn destroy!
+  "Destroy the session and free resources.
+   Can be called with either a CopilotSession handle or (client, session-id).
+
+   Deprecated: Use disconnect! instead. This function will be removed in a
+   future release. disconnect! is the preferred method for closing sessions."
+  ([session]
+   (disconnect! session))
+  ([client session-id]
+   (disconnect! client session-id)))
+
 (defn events
   "Get the event mult for this session. Use tap to subscribe: