docs: clarify session destroy vs delete semantics

[patniko]

Summary

Clarifies the distinction between destroy() and deleteSession() across all four SDK languages and the session persistence guide.

Fixes #526

Problem

As reported in #526, the API documentation around session disposal is counterintuitive:

• destroy() says it "destroys this session and releases all associated resources" but then says the session can be resumed — contradicting what "destroy" implies
• deleteSession() is the truly permanent operation, but there's no clear guidance on when to use one vs the other
• stop() says it "destroys all active sessions" but actually leaves session data on disk, which isn't mentioned

Changes

All four SDK languages (Go, Node.js, Python, .NET) — updated doc comments for:

• destroy() / DisposeAsync(): Now explicitly states it releases in-memory resources only, preserves disk state, and points to deleteSession() for permanent removal
• stop() / StopAsync(): Clarifies it closes sessions (not "destroys") and notes that disk data is preserved — users wanting permanent removal must call deleteSession() first
• deleteSession() / DeleteSessionAsync(): Now explicitly contrasts with destroy() to make the difference clear

Session persistence guide (docs/guides/session-persistence.md):

• Renamed "Explicit Session Destruction" to "Closing a Session" and "Permanently Deleting a Session" — two separate subsections
• Added a callout box summarizing destroy() vs deleteSession()
• Updated the summary table with clarifying descriptions

[Copilot]

Pull request overview

This PR clarifies the semantic distinction between destroy() and deleteSession() methods across all four SDK languages (Go, Node.js, Python, .NET) and updates the session persistence guide. The changes address issue #526, which reported that the API documentation around session disposal was counterintuitive and contradictory.

Changes:

• Updated destroy() / DisposeAsync() documentation to explicitly state it releases in-memory resources only, preserves disk state, and can be resumed
• Updated stop() / StopAsync() documentation to clarify it closes (not "destroys") sessions and preserves disk data
• Updated deleteSession() / DeleteSessionAsync() documentation to explicitly contrast with destroy() and emphasize permanent deletion
• Restructured session persistence guide with separate sections for "Closing a Session" vs "Permanently Deleting a Session" and added a callout box

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
python/copilot/session.py	Updated destroy() docstring to clarify it closes session and releases in-memory resources while preserving disk state
python/copilot/client.py	Updated stop() to clarify it closes (not destroys) sessions; updated delete_session() to contrast with destroy()
nodejs/src/session.ts	Updated destroy() JSDoc to clarify it closes session and releases in-memory resources while preserving disk state
nodejs/src/client.ts	Updated stop() to clarify it closes sessions; updated deleteSession() to contrast with destroy()
go/session.go	Updated Destroy() doc comment to clarify it closes session and releases in-memory resources while preserving disk state
go/client.go	Updated Stop() to clarify it closes sessions; updated DeleteSession() to contrast with Destroy()
dotnet/src/Session.cs	Updated DisposeAsync() XML doc to clarify it closes session and releases in-memory resources while preserving disk state
dotnet/src/Client.cs	Updated StopAsync() to clarify it closes sessions; updated DeleteSessionAsync() to contrast with DisposeAsync()
docs/guides/session-persistence.md	Restructured with separate sections for closing vs deleting; added callout box and updated summary table

[patniko]

@SteveSandersonMS would be great to chat about this

[github-actions]

✅ Cross-SDK Consistency Review: APPROVED

This PR demonstrates excellent cross-language consistency in clarifying the destroy() vs deleteSession() semantics. All four SDK implementations have been updated with parallel documentation changes:

Consistent Changes Across All Languages

1. Session destroy() / DisposeAsync() method:

• ✅ Node.js, Python, Go, and .NET all now clearly state it "closes" (not "destroys") the session
• ✅ All specify that it releases "in-memory resources" only
• ✅ All mention that session data on disk is preserved
• ✅ All point to deleteSession() for permanent removal
• ✅ All note the session object cannot be reused after calling this method
• ✅ Examples updated to clarify "session can still be resumed later"

2. Client stop() / StopAsync() method:

• ✅ All four languages changed "destroys" to "closes" active sessions
• ✅ All clarify that in-memory resources are released
• ✅ All note that disk data is preserved
• ✅ All suggest calling deleteSession() first for permanent removal

3. Client deleteSession() / DeleteSessionAsync() method:

• ✅ All four languages now explicitly describe this as "permanently deletes"
• ✅ All mention it removes "conversation history, planning state, and artifacts"
• ✅ All contrast with destroy() to highlight the difference
• ✅ All state that deletion is "irreversible"

4. Documentation guide:

• ✅ docs/guides/session-persistence.md updated with new subsections
• ✅ Added callout box summarizing destroy() vs deleteSession()
• ✅ Summary table updated with clarifying descriptions

Language-Specific Adaptations (Appropriate)

The following differences respect language conventions and are not consistency issues:

• Documentation style:

  • TypeScript: JSDoc with {@link}
  • Python: reStructuredText with :meth:
  • Go: godoc with [Client.ResumeSession] reference style
  • .NET: XML doc comments with (see cref=""/)

• Method naming:

  • Node/Python: destroy(), deleteSession()
  • Go: Destroy(), DeleteSession() (exported functions use PascalCase)
  • .NET: DisposeAsync() (IAsyncDisposable pattern), DeleteSessionAsync()

These variations follow each language's idiomatic documentation and naming conventions.

Conclusion

This PR maintains complete feature parity and semantic consistency across all four SDK implementations. The documentation now provides clear, consistent guidance on session lifecycle management regardless of which SDK language developers are using.

Great work addressing issue #526! 🎉

AI generated by SDK Consistency Review Agent