feat(sdk): add sandbox lifecycle hook models

[jianpingpei]

Summary

• Add a standard, extensible CreateSandboxRequest.lifecycle model to the lifecycle API specification.
• Support the optional preStart and periodic hooks in this phase.
• Align the generated and handwritten Java/Kotlin, Python, and TypeScript SDK models and serialization behavior.
• Document the execd behavior for pre-start failures and overlapping periodic runs.

This is the SDK and API Spec part of OSEP-0020 (#1542) and complements the execd implementation in #1587. Server integration will be submitted separately. Docker, PATCH, and other lifecycle hooks are intentionally out of scope.

Testing

• Not run (explain why)
• Unit tests
• Integration tests
• e2e / manual verification

Validated:

• TypeScript lint, typecheck, build, and tests: 99 passed
• Python ruff, pyright, and tests: 513 passed
• Kotlin Spotless and SandboxLifecycleModelsTest: passed

Breaking Changes

• None
• Yes (describe impact and migration path)

Checklist

• Linked Issue or clearly described motivation
• Added/updated docs (if needed)
• Added/updated tests (if needed)
• Security impact considered
• Backward compatibility considered

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f7f216dff2

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Implement server handling before advertising lifecycle hooks

Any client that sends this newly documented field to the server in this commit gets a successful sandbox without the requested hooks: server/opensandbox_server/api/schema.py:391-493 has no lifecycle field, so Pydantic ignores it, and the create route proceeds with the stripped request. This can run the user entrypoint without the advertised restore hook and never schedule checkpoints while returning 202; add the server schema and runtime transport in the same change, or defer exposing the contract.

AGENTS.md reference: specs/AGENTS.md:L49-L52

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Plumb lifecycle hooks through the stable Python and Kotlin APIs

When callers use the normal Python Sandbox.create or Kotlin Sandbox/Sandboxes.createSandbox APIs, there is no lifecycle parameter, and their converters never populate this generated field (sandbox_model_converter.py:170-185,310-317 and SandboxModelConverter.kt:252-283). Consequently only direct construction of internal generated-client models can send hooks, unlike the JavaScript SDK's public create request; add stable lifecycle models, create parameters, converter mappings, and focused request tests for both SDKs.

AGENTS.md reference: sdks/AGENTS.md:L117-L123

Useful? React with 👍 / 👎.