Clarify session disposal

[chlowell]

The API and documentation around session disposal are counterintuitive and contradictory such that it isn't clear how to go about this:

• Session.Destroy() docs say it "destroys this session and releases all associated resources" and that the session can no longer be used after calling this method. So far so good: "destroy" implies an irreversible operation leaving nothing behind. However, the docs go on to contradict this by saying that the conversation can be resumed by calling Client.ResumeSession(). Maybe "destroy" is the wrong verb here; how about "suspend" or "close"?
• Client.DeleteSession() naively appears equivalent to Session.Destroy() but apparently it's a superset: it does everything Destroy does plus it deletes files. It isn't clear how I should decide whether to "delete" or "destroy" a session.
• Client.Stop() is documented as both "closing" and "destroying" all active sessions. This is confusing because "destroy" implies an irreversible operation leaving nothing behind while "close" is ambiguous (what happens to session resources on closure?). Because this method calls Session.Destroy() on each active session, it apparently leaves their files behind. Maybe this is again suggesting "close" as a better verb than "destroy". In any case, the docs should at least call out that Client.Stop() leaves session artifacts behind and SDK users who want to remove them must explicitly delete sessions.

[github-actions]

Thanks for opening this issue! You've identified some important inconsistencies in our API naming and documentation around session lifecycle management.

I've labeled this as:

• sdk/go — The examples are Go-specific
• documentation — Clearer docs are definitely needed
• enhancement — This may also warrant API naming improvements

The confusion around Destroy() (which allows resumption) vs DeleteSession() (which removes files) vs Stop() (which destroys but leaves artifacts) is a valid UX concern. The team will review whether we should:

1. Update documentation to clarify the current behavior
2. Consider renaming methods for better clarity (e.g., Close() or Suspend() instead of Destroy())

This likely applies to other SDK implementations as well, so we'll check consistency across languages.

AI generated by Issue Triage Agent