Revisit single-use semantics of StreamableHTTPSessionManager.run()

[dgenio]

Description

Summary

StreamableHTTPSessionManager currently enforces that run() can only be called once per instance. This is documented but not explained, and it complicates:

• testing (each test must construct a new manager), and
• any scenario that might want to reuse the manager for restarts.

It would be useful to either:

• make run() safely reusable, or
• codify and enforce single-use semantics in a clearer way.

Problems

• Testing: Requiring a new manager instance for each run increases boilerplate and can hide lifecycle issues.
• Unclear constraints: Users have to discover via runtime errors that run() is single-use, without an obvious reason.
• Lifecycle complexity: The single-use constraint is a hint that some internal state (task groups, resource stacks) is not being fully reset.

Proposal

1. Investigate why single-use is required

   • Document what internal state is left behind after run() completes (e.g., background tasks, queues).
   • Determine whether these can be safely reset at the start of the next run().

2. Either: make run() reusable...

   • Reset internal state (task groups, lists of tasks, queues) before each run().
   • Ensure proper cleanup in finally blocks so the manager returns to a clean state.

3. ...or explicitly codify single-use semantics

   • If reuse is fundamentally unsafe, consider:
     • modelling the manager as a consumable object (e.g., via documentation and type hints),
     • or returning a token/handle that marks the manager as “exhausted” after run().

Why this matters

• Developer experience: Easier to write tests that exercise multiple lifecycles.
• Robustness: Cleaning up state between runs reduces the risk of hidden leaks or race conditions.
• Clarity: Either outcome (reusable or explicitly consumable) is better than a hidden constraint.

Acceptance criteria

• [ ] The rationale for single-use semantics is documented (if they remain).
• [ ] Either:
  • [ ] run() can be safely called multiple times on the same instance, or
  • [ ] Single-use semantics are enforced and clearly documented.
• [ ] Tests cover repeated calls to run() and confirm expected behavior.

References

No response