Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

fix(sdk-python): round sub-millisecond command timeouts up to 1 ms

Jackmeson135b98441197a
diff --git a/docs/sdks/python.md b/docs/sdks/python.md
index 21e5c2c3e..1ff3d3bcb 100644
--- a/docs/sdks/python.md
+++ b/docs/sdks/python.md
@@ -317,6 +317,8 @@ result = await sandbox.commands.run(["printf", "%s\n", "$HOME", "hello world"])
Native argv execution requires an updated execd. See [command execution modes](/architecture/data-plane/execd#command-execution) for executable lookup and platform behavior.
+`RunCommandOpts.timeout` and the `timeout` of `commands.run_in_session` take a `timedelta` and are sent in whole milliseconds, rounded up: 500 microseconds is sent as 1 ms and 1.5 ms as 2 ms. An omitted timeout is left out of the request and `timedelta(0)` is sent as 0; ordinary commands then run without a deadline, and bash-session commands use their 24-hour default.
+
#### Background commands
Start a bounded command, read incremental logs, and check its exit status. Command timeout and sandbox TTL are separate settings.
diff --git a/sdks/sandbox/python/src/opensandbox/adapters/converter/command_execution.py b/sdks/sandbox/python/src/opensandbox/adapters/converter/command_execution.py
index aa7abadc6..b4fac8e7e 100644
--- a/sdks/sandbox/python/src/opensandbox/adapters/converter/command_execution.py
+++ b/sdks/sandbox/python/src/opensandbox/adapters/converter/command_execution.py
@@ -34,7 +34,8 @@ def resolve_run_in_session_timeout(timeout: timedelta | None) -> int | None:
# The execd API validates this timeout with `gte=0`.
if timeout < timedelta(0):
raise InvalidArgumentException("timeout must not be negative")
- return int(timeout.total_seconds() * 1000)
+ # Round up using integer microseconds to preserve whole milliseconds exactly.
+ return (timeout // timedelta(microseconds=1) + 999) // 1000
raise InvalidArgumentException("timeout must be a datetime.timedelta or None")
diff --git a/sdks/sandbox/python/src/opensandbox/adapters/converter/execution_converter.py b/sdks/sandbox/python/src/opensandbox/adapters/converter/execution_converter.py
index c26dd5e86..cd54b76c8 100644
--- a/sdks/sandbox/python/src/opensandbox/adapters/converter/execution_converter.py
+++ b/sdks/sandbox/python/src/opensandbox/adapters/converter/execution_converter.py
@@ -63,7 +63,8 @@ class ExecutionConverter:
if opts.timeout is not None:
if opts.timeout < timedelta(0):
raise InvalidArgumentException("timeout must be positive")
- timeout_milliseconds = int(opts.timeout.total_seconds() * 1000)
+ # Round up using integer microseconds to preserve whole milliseconds exactly.
+ timeout_milliseconds = (opts.timeout // timedelta(microseconds=1) + 999) // 1000
uid = UNSET
if opts.uid is not None:
diff --git a/sdks/sandbox/python/tests/test_converters_and_error_handling.py b/sdks/sandbox/python/tests/test_converters_and_error_handling.py
index cf4ab38bb..3fc7dbfd3 100644
--- a/sdks/sandbox/python/tests/test_converters_and_error_handling.py
+++ b/sdks/sandbox/python/tests/test_converters_and_error_handling.py
@@ -21,6 +21,10 @@ import pytest
from httpx import HTTPStatusError, Request, Response
from pydantic import ValidationError
+from opensandbox.adapters.converter.command_execution import (
+ build_run_in_session_request_body,
+ resolve_run_in_session_timeout,
+)
from opensandbox.adapters.converter.exception_converter import (
ExceptionConverter,
parse_sandbox_error,
@@ -529,6 +533,82 @@ def test_execution_converter_to_api_run_command_request() -> None:
assert literal_request == {"argv": literal_argv}
+ ("microseconds", "expected"),
+ [
+ (None, None),
+ (0, 0),
+ (1, 1),
+ (500, 1),
+ (900, 1),
+ (999, 1),
+ (1000, 1),
+ (1001, 2),
+ (1200, 2),
+ (1_001_000, 1001),
+ (2_007_000, 2007),
+ (60_000_000, 60_000),
+ ],
+)
+def test_execution_converter_rounds_timeout_up_to_milliseconds(
+ microseconds: int | None, expected: int | None
+) -> None:
+ timeout = timedelta(microseconds=microseconds) if microseconds is not None else None
+ request = ExecutionConverter.to_api_run_command_request(
+ "sleep 10", RunCommandOpts(timeout=timeout)
+ ).to_dict()
+
+ if expected is None:
+ assert "timeout" not in request
+ else:
+ assert request["timeout"] == expected
+
+
+ ("microseconds", "expected"),
+ [
+ (None, None),
+ (0, 0),
+ (1, 1),
+ (500, 1),
+ (900, 1),
+ (999, 1),
+ (1000, 1),
+ (1001, 2),
+ (1200, 2),
+ (1_001_000, 1001),
+ (2_007_000, 2007),
+ (60_000_000, 60_000),
+ ],
+)
+def test_run_in_session_converter_rounds_timeout_up_to_milliseconds(
+ microseconds: int | None, expected: int | None
+) -> None:
+ timeout = timedelta(microseconds=microseconds) if microseconds is not None else None
+ timeout_ms = resolve_run_in_session_timeout(timeout)
+ assert timeout_ms == expected
+ request = build_run_in_session_request_body("sleep 10", None, timeout_ms).to_dict()
+
+ if expected is None:
+ assert "timeout" not in request
+ else:
+ assert request["timeout"] == expected
+
+
[email protected]("microseconds", [-1, -999, -1000])
+def test_execution_converter_rejects_negative_timeout(microseconds: int) -> None:
+ with pytest.raises(InvalidArgumentException, match="^timeout must be positive"):
+ ExecutionConverter.to_api_run_command_request(
+ "sleep 10", RunCommandOpts(timeout=timedelta(microseconds=microseconds))
+ )
+
+
[email protected]("microseconds", [-1, -999, -1000])
+def test_run_in_session_converter_rejects_negative_timeout(microseconds: int) -> None:
+ with pytest.raises(InvalidArgumentException, match="^timeout must not be negative"):
+ resolve_run_in_session_timeout(timedelta(microseconds=microseconds))
+
+
def test_run_command_opts_validates_gid_requires_uid() -> None:
with pytest.raises(ValueError, match="uid is required when gid is provided"):
RunCommandOpts(gid=1000)