fix(sandbox-kubernetes): support claim lifecycle retention

[guslegend0510]

AgentScope-Java Version

2.0.3-SNAPSHOT

Description

Fixes #2979.

Kubernetes sandbox claims were always treated as client-owned. Releasing a sandbox therefore deleted its SandboxClaim, while the persisted agent state still referenced that claim. The next call attempted to resume the deleted claim and waited for the watch timeout before creating a replacement.

This PR:

• Exposes claimOwned(boolean) for explicitly controlling deletion on release.
• Adds shutdownAfterSeconds(long) as a hard controller-managed expiry.
• Adds ttlSecondsAfterFinished(int) and serializes it to SandboxClaim.spec.lifecycle.
• Keeps the compatibility default for claims without a hard shutdown deadline.
• Avoids retaining TTL-only claims implicitly because long-running runtimes may never reach Finished.
• Fails immediately when a persisted claim no longer exists instead of waiting for the 30-second watch timeout.
• Preserves the existing public createSandboxClaim overload for source and binary compatibility.
• Adds unit tests and English/Chinese documentation.

Lifecycle behavior

• Default: the client deletes the claim on release.
• With shutdownAfterSeconds: release only disconnects; the controller deletes the claim at the configured deadline.
• With ttlSecondsAfterFinished only: client ownership remains enabled by default.
• claimOwned(false) can explicitly retain a claim when the runtime is guaranteed to reach Finished.

Verification

• Kubernetes module test suite: 44 tests passed.
• Final focused lifecycle tests: 31 tests passed, 0 failures.
• Spotless check passed.
• git diff --check passed.

Checklist

• Code has been formatted with Spotless
• All affected-module tests are passing
• Javadoc comments follow project conventions
• Related English and Chinese documentation has been updated
• Code is ready for review

[codecov]

Codecov Report

❌ Patch coverage is 56.57895% with 33 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../sandbox/kubernetes/client/internal/K8sHelper.java	27.27%	13 Missing and 3 partials ⚠️
...ns/sandbox/kubernetes/KubernetesSandboxClient.java	57.89%	5 Missing and 3 partials ⚠️
...box/kubernetes/KubernetesSandboxClientOptions.java	69.23%	2 Missing and 2 partials ⚠️
...andbox/kubernetes/client/crd/SandboxClaimSpec.java	42.85%	4 Missing ⚠️
...sions/sandbox/kubernetes/client/SandboxClient.java	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[CryoThrust]

I traced the lifecycle paths against the reported resume failure. The ownership resolution and the preserved seven-argument createSandboxClaim overload look consistent with the compatibility goal.

Two points that may be worth making explicit before merge:

1. For an already-persisted KubernetesSandboxState, claimOwned remains whatever was serialized previously unless the caller supplies an explicit claimOwned option. That is a reasonable migration choice, but it means an existing state created with the old default still deletes its claim on release. Could the documentation or a regression test state this migration behavior explicitly?
2. ttlSecondsAfterFinished is serialized into spec.lifecycle alongside shutdownTime and shutdownPolicy. Please confirm that the deployed agent-sandbox CRD/controller version accepts this field and ignores it safely when unsupported; a small serialization assertion or compatibility note would make the rollout contract clearer.

The immediate missing-claim failure is a useful improvement for this issue because it removes the 30-second watch wait. I did not find a competing change in the open PR list beyond this PR, so I am leaving this as review feedback rather than opening a duplicate implementation.