volcano-sh / volcano-sh/agentcube
Clarify session expiration behavior in API and Python SDK
@acsoto is already working on this.
Since Aug 21, 2026.
- Dominant language
- Go
- Stars
- 167
- Forks
- 88
- Avg merge
- 44m
- Merged PRs (30d)
- 1
Description
What would you like to be added:
Clarify and align session expiration behavior across the Router, Workload Manager API, CRDs, and Python SDK.
A client may continue using x-agentcube-session-id after the corresponding sandbox has been reclaimed. The Router then returns HTTP 404, but the response does not provide a stable machine-readable error code. The Python SDK also propagates it as a generic HTTP exception without invalidating the stale session ID.
As a result, clients may repeatedly send an expired session ID and remain in a permanent 404 loop.
Session lifetime configuration is also inconsistent:
sessionTimeoutcontrols idle expiration.maxSessionDurationcontrols the hard lifetime limit.- The Python SDK exposes
ttl, but the current create-session API does not apply it. - SDK
timeoutcontrols HTTP request timeout and is unrelated to session lifetime.
The expected behavior should be:
- Return a stable error such as
SESSION_NOT_FOUNDwhen the Router cannot resolve a supplied session ID. - Keep this distinguishable from a 404 returned by the application inside the sandbox.
- Let the Python SDK expose a specific session-not-found error and stop treating the stale session ID as valid.
- Define whether request-level
ttlis supported. If supported, enforce it under the CRD maximum lifetime policy; otherwise remove or reject it explicitly instead of silently ignoring it. - Document that clients must discard an expired session ID and explicitly create a new session if their application wants to continue.
Why is this needed:
Session reuse is part of the public AgentCube API, but expiration behavior is not currently defined well enough for official or third-party SDKs.
A consistent error and lifetime contract prevents clients from repeatedly using stale session IDs and makes session behavior predictable.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.