Feat/run in session sdks

[Pangjiping]

Summary

Bash session API (create_session, run_in_session, delete_session) is exposed on commands in all OpenSandbox SDKs. Sessions keep shell state (working directory, environment) across multiple runs. This PR adds or completes support in Python, JavaScript, Kotlin, and C# so that usage is consistent: users call sandbox.commands.createSession(...), sandbox.commands.runInSession(...), and sandbox.commands.deleteSession(...) (or the language-idiomatic equivalent). There is no separate “session” service; everything lives under commands.

---

How to use (by SDK)

Python

# Async
sandbox = await Sandbox.create(...)
session_id = await sandbox.commands.create_session(cwd="/tmp")
execution = await sandbox.commands.run_in_session(session_id, "pwd")
# execution.logs.stdout → "/tmp"
execution = await sandbox.commands.run_in_session(session_id, "pwd", cwd="/var")
await sandbox.commands.delete_session(session_id)

# Sync
session_id = sandbox.commands.create_session(cwd="/tmp")
execution = sandbox.commands.run_in_session(session_id, "pwd", cwd="/var")
sandbox.commands.delete_session(session_id)

JavaScript / TypeScript

const sandbox = await Sandbox.create({ ... });

const sessionId = await sandbox.commands.createSession({ cwd: "/tmp" });
const run = await sandbox.commands.runInSession(sessionId, "pwd");
// run.logs.stdout[0].text === "/tmp"
await sandbox.commands.runInSession(sessionId, "pwd", { cwd: "/var" });
await sandbox.commands.deleteSession(sessionId);

Optional options for runInSession: { cwd?: string; timeoutMs?: number }. Handlers can be passed as the fourth argument for streaming callbacks.

Kotlin / Java

// Kotlin
val sandbox = Sandbox.builder()...build()
val sessionId = sandbox.commands().createSession("/tmp")
val execution = sandbox.commands().runInSession(sessionId, "pwd")
// execution.logs.stdout → "/tmp"
sandbox.commands().runInSession(sessionId, RunInSessionRequest.builder().code("pwd").cwd("/var").build())
sandbox.commands().deleteSession(sessionId)

// Convenience overload
sandbox.commands().runInSession(sessionId, "pwd", cwd = "/var", timeoutMs = 5000L)

// Java
Sandbox sandbox = Sandbox.builder()...build();
String sessionId = sandbox.commands().createSession("/tmp");
Execution run = sandbox.commands().runInSession(sessionId,
    RunInSessionRequest.builder().code("pwd").cwd("/var").build());
sandbox.commands().deleteSession(sessionId);

C#

var sandbox = await Sandbox.CreateAsync(...);

string sessionId = await sandbox.Commands.CreateSessionAsync(new CreateSessionOptions { Cwd = "/tmp" });
Execution run = await sandbox.Commands.RunInSessionAsync(sessionId, "pwd");
// run.Logs.Stdout → "/tmp"
run = await sandbox.Commands.RunInSessionAsync(sessionId, "pwd",
    options: new RunInSessionOptions { Cwd = "/var", TimeoutMs = 5000 });
await sandbox.Commands.DeleteSessionAsync(sessionId);

---

Testing

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

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

[ninan-nn]

A small suggestion to keep future implementations consistent:

• For standard JSON request-response endpoints like create_session / delete_session, prefer using OpenAPI-generated code.
• For SSE endpoints like run_in_session (text/event-stream), keep the transport/event-stream handling handwritten.
• Even for handwritten SSE logic, reuse OpenAPI-generated models/field definitions whenever possible to stay aligned with the spec.

This keeps maintenance simple while preserving protocol correctness.
It may also help to add a short code comment clarifying that the generated run_in_session API file is not the recommended runtime entry point, to avoid accidental misuse.

I'll also add this guideline to AGENTS.md later as a default implementation convention.

[Pangjiping]

A small suggestion to keep future implementations consistent:

• For standard JSON request-response endpoints like create_session / delete_session, prefer using OpenAPI-generated code.
• For SSE endpoints like run_in_session (text/event-stream), keep the transport/event-stream handling handwritten.
• Even for handwritten SSE logic, reuse OpenAPI-generated models/field definitions whenever possible to stay aligned with the spec.

This keeps maintenance simple while preserving protocol correctness. It may also help to add a short code comment clarifying that the generated run_in_session API file is not the recommended runtime entry point, to avoid accidental misuse.

I'll also add this guideline to AGENTS.md later as a default implementation convention.

A small suggestion to keep future implementations consistent:

• For standard JSON request-response endpoints like create_session / delete_session, prefer using OpenAPI-generated code.
• For SSE endpoints like run_in_session (text/event-stream), keep the transport/event-stream handling handwritten.
• Even for handwritten SSE logic, reuse OpenAPI-generated models/field definitions whenever possible to stay aligned with the spec.

This keeps maintenance simple while preserving protocol correctness. It may also help to add a short code comment clarifying that the generated run_in_session API file is not the recommended runtime entry point, to avoid accidental misuse.

I'll also add this guideline to AGENTS.md later as a default implementation convention.

A small suggestion to keep future implementations consistent:

• For standard JSON request-response endpoints like create_session / delete_session, prefer using OpenAPI-generated code.
• For SSE endpoints like run_in_session (text/event-stream), keep the transport/event-stream handling handwritten.
• Even for handwritten SSE logic, reuse OpenAPI-generated models/field definitions whenever possible to stay aligned with the spec.

This keeps maintenance simple while preserving protocol correctness. It may also help to add a short code comment clarifying that the generated run_in_session API file is not the recommended runtime entry point, to avoid accidental misuse.

I'll also add this guideline to AGENTS.md later as a default implementation convention.

I’ve already added comments about run_in_session.

[hittyt]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d12e14fd8f

ℹ️ About Codex in GitHub

Your team has set up Codex to 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 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".