volcano-sh / volcano-sh/agentcube

Clarify session expiration behavior in API and Python SDK

Open
#459 1 comment 0 reactions 1 assignee View on GitHub

@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:

  • sessionTimeout controls idle expiration.
  • maxSessionDuration controls the hard lifetime limit.
  • The Python SDK exposes ttl, but the current create-session API does not apply it.
  • SDK timeout controls HTTP request timeout and is unrelated to session lifetime.

The expected behavior should be:

  1. Return a stable error such as SESSION_NOT_FOUND when the Router cannot resolve a supplied session ID.
  2. Keep this distinguishable from a 404 returned by the application inside the sandbox.
  3. Let the Python SDK expose a specific session-not-found error and stop treating the stale session ID as valid.
  4. Define whether request-level ttl is supported. If supported, enforce it under the CRD maximum lifetime policy; otherwise remove or reject it explicitly instead of silently ignoring it.
  5. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.