Secure, Fast, and Extensible Sandbox runtime for AI agents.
fix(execd,sdks): report signal-killed bash runs and surface error.exit_code in SDKs
BootstrapperSBL8a964b893a43
diff --git a/components/execd/pkg/runtime/bash_session.go b/components/execd/pkg/runtime/bash_session.goindex eeaaef0f5..3327f8a5d 100644--- a/components/execd/pkg/runtime/bash_session.go+++ b/components/execd/pkg/runtime/bash_session.go@@ -357,6 +357,14 @@ func (s *bashSession) run(ctx context.Context, request *ExecuteCodeRequest) errolog.Error("bash session: wait: %v (command: %q)", waitErr, log.SanitizeCommand(request.Code))return waitErr}+ // A shell terminated by a signal (e.g. `kill -TERM $$`) never prints the+ // exit marker and reports ExitCode() == -1, which the >= 0 check above+ // skips. Take the code from the wait error so the run is reported as a+ // failure (exit_code -1) rather than as a successful completion.+ if exitCode == nil && exitCodeErr != nil {+ code := exitCodeErr.ExitCode()+ exitCode = &code+ }userExitCode := 0if exitCode != nil {diff --git a/components/execd/pkg/runtime/bash_session_test.go b/components/execd/pkg/runtime/bash_session_test.goindex e5a9603a6..1bc558235 100644--- a/components/execd/pkg/runtime/bash_session_test.go+++ b/components/execd/pkg/runtime/bash_session_test.go@@ -898,3 +898,53 @@ func TestBashSession_NormalExitKeepsBackgroundJob(t *testing.T) {return err == nil}, 5*time.Second, 50*time.Millisecond, "background job was killed after a normal run")}++func TestBashSession_SignalKillEmitsError(t *testing.T) {+ requireBash(t)++ c := NewController("", "")++ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)+ defer cancel()++ var (+ errCh = make(chan *execute.ErrorOutput, 1)+ completeCh = make(chan struct{}, 1)+ )++ req := &ExecuteCodeRequest{+ Language: Bash,+ // The shell kills itself before the wrapper can print its exit marker.+ Code: `kill -TERM $$`,+ Cwd: t.TempDir(),+ Timeout: 5 * time.Second,+ Hooks: ExecuteResultHook{+ OnExecuteError: func(err *execute.ErrorOutput) { errCh <- err },+ OnExecuteComplete: func(_ time.Duration) {+ completeCh <- struct{}{}+ },+ },+ }++ session, err := c.createBashSession(&CreateContextRequest{})+ require.NoError(t, err)+ req.Context = session+ require.NoError(t, c.runBashSession(ctx, req))++ select {+ case <-completeCh:+ require.Fail(t, "did not expect completion hook when the shell was killed by a signal")+ default:+ }++ var gotErr *execute.ErrorOutput+ select {+ case gotErr = <-errCh:+ case <-time.After(2 * time.Second):+ require.Fail(t, "expected error hook to be called for a signal-killed shell")+ }+ require.Equal(t, "CommandExecError", gotErr.EName)+ require.Equal(t, "-1", gotErr.EValue)+ require.NotNil(t, gotErr.ExitCode, "expected exit_code for a signal-killed shell")+ require.Equal(t, -1, *gotErr.ExitCode)+}diff --git a/sdks/sandbox/go/execution.go b/sdks/sandbox/go/execution.goindex b1801217b..c7ea17448 100644--- a/sdks/sandbox/go/execution.go+++ b/sdks/sandbox/go/execution.go@@ -45,6 +45,11 @@ type ExecutionError struct {Value string `json:"value"`Timestamp int64 `json:"timestamp"`Traceback []string `json:"traceback"`+ // ExitCode is the exit status reported by execd for a CommandExecError+ // when the command ran and finished with a non-zero status (-1 when it was+ // terminated by a signal). Nil when the process failed to start, for+ // non-command errors, and on servers that predate error.exit_code.+ ExitCode *int `json:"exit_code,omitempty"`}// ExecutionComplete represents the completion event from the server.@@ -116,6 +121,7 @@ type sseErrorPayload struct {EName string `json:"ename,omitempty"`EValue string `json:"evalue,omitempty"`Traceback []string `json:"traceback,omitempty"`+ ExitCode *int `json:"exit_code,omitempty"`}// sseEvent is the raw JSON structure from execd SSE/NDJSON events.@@ -203,11 +209,13 @@ func processStreamEvent(exec *Execution, event StreamEvent, handlers *ExecutionHcase "error":var ename, evalue stringvar traceback []string+ var exitCode *int// Prefer nested error object per spec; fall back to flat fieldsif ev.Error != nil {ename = ev.Error.ENameevalue = ev.Error.EValuetraceback = ev.Error.Traceback+ exitCode = ev.Error.ExitCode} else {ename = ev.ENameevalue = ev.EValue@@ -218,10 +226,15 @@ func processStreamEvent(exec *Execution, event StreamEvent, handlers *ExecutionHValue: evalue,Timestamp: ev.Timestamp,Traceback: traceback,+ ExitCode: exitCode,}exec.Error = &execErr- // Try to parse exit code from error value- if code, err := strconv.Atoi(evalue); err == nil {+ // Prefer the authoritative error.exit_code; fall back to parsing the+ // error value for servers that predate it.+ if exitCode != nil {+ code := *exitCode+ exec.ExitCode = &code+ } else if code, err := strconv.Atoi(evalue); err == nil {exec.ExitCode = &code}if handlers != nil && handlers.OnError != nil {diff --git a/sdks/sandbox/go/opensandbox_test.go b/sdks/sandbox/go/opensandbox_test.goindex 1ab635a96..d1d9f985f 100644--- a/sdks/sandbox/go/opensandbox_test.go+++ b/sdks/sandbox/go/opensandbox_test.go@@ -2495,6 +2495,56 @@ func TestExecution_ErrorEvent(t *testing.T) {}}+func TestExecution_ErrorEventExitCode(t *testing.T) {+ intPtr := func(v int) *int { return &v }+ tests := []struct {+ name string+ data string+ wantErrorCode *int+ wantExitCode *int+ }{+ {+ name: "exit_code is authoritative",+ data: `{"type":"error","error":{"ename":"CommandExecError","evalue":"3","traceback":["exit status 3"],"exit_code":3}}`,+ wantErrorCode: intPtr(3),+ wantExitCode: intPtr(3),+ },+ {+ name: "signal kill reports -1",+ data: `{"type":"error","error":{"ename":"CommandExecError","evalue":"-1","traceback":["signal: terminated"],"exit_code":-1}}`,+ wantErrorCode: intPtr(-1),+ wantExitCode: intPtr(-1),+ },+ {+ name: "start failure has no exit code",+ data: `{"type":"error","error":{"ename":"CommandExecError","evalue":"fork/exec /bin/sh: argument list too long"}}`,+ },+ {+ name: "older server falls back to evalue",+ data: `{"type":"error","error":{"ename":"CommandExecError","evalue":"7"}}`,+ wantExitCode: intPtr(7),+ },+ }++ for _, tc := range tests {+ t.Run(tc.name, func(t *testing.T) {+ exec := &Execution{}+ var handled *ExecutionError+ handlers := &ExecutionHandlers{+ OnError: func(e ExecutionError) error { handled = &e; return nil },+ }+ require.NoError(t, processStreamEvent(exec, StreamEvent{Event: "error", Data: tc.data}, handlers))++ require.NotNil(t, exec.Error)+ require.NotNil(t, handled)+ require.Equal(t, tc.wantErrorCode, exec.Error.ExitCode)+ require.Equal(t, tc.wantErrorCode, handled.ExitCode)+ require.Equal(t, tc.wantExitCode, exec.ExitCode)+ require.True(t, exec.Complete == nil, "error event must not mark the execution complete")+ })+ }+}+func TestExecution_HandlersInvoked(t *testing.T) {exec := &Execution{}var initCalled, stdoutCalled, stderrCalled, resultCalled, completeCalled booldiff --git a/sdks/sandbox/javascript/src/adapters/commandsAdapter.ts b/sdks/sandbox/javascript/src/adapters/commandsAdapter.tsindex 64b81c035..477c19252 100644--- a/sdks/sandbox/javascript/src/adapters/commandsAdapter.ts+++ b/sdks/sandbox/javascript/src/adapters/commandsAdapter.ts@@ -93,6 +93,10 @@ function toRunInSessionRequest(}function inferForegroundExitCode(execution: CommandExecution): number | null {+ // Prefer the authoritative `error.exit_code`; fall back to parsing `evalue` for older servers.+ if (typeof execution.error?.exitCode === "number") {+ return execution.error.exitCode;+ }const errorValue = execution.error?.value?.trim();const parsedExitCode =errorValue && /^-?\d+$/.test(errorValue) ? Number(errorValue) : Number.NaN;diff --git a/sdks/sandbox/javascript/src/adapters/isolatedSessionsAdapter.ts b/sdks/sandbox/javascript/src/adapters/isolatedSessionsAdapter.tsindex ab968992b..9c7a5b0c4 100644--- a/sdks/sandbox/javascript/src/adapters/isolatedSessionsAdapter.ts+++ b/sdks/sandbox/javascript/src/adapters/isolatedSessionsAdapter.ts@@ -59,6 +59,10 @@ function utf8ByteLength(text: string): number {}function inferExitCode(execution: CommandExecution): number | null {+ // Prefer the authoritative `error.exit_code`; fall back to parsing `evalue` for older servers.+ if (typeof execution.error?.exitCode === "number") {+ return execution.error.exitCode;+ }const errorValue = execution.error?.value?.trim();const parsedExitCode =errorValue && /^-?\d+$/.test(errorValue) ? Number(errorValue) : Number.NaN;diff --git a/sdks/sandbox/javascript/src/models/execution.ts b/sdks/sandbox/javascript/src/models/execution.tsindex 35ca3b6d5..2a2d2455b 100644--- a/sdks/sandbox/javascript/src/models/execution.ts+++ b/sdks/sandbox/javascript/src/models/execution.ts@@ -32,6 +32,12 @@ export interface ExecutionError {value: string;timestamp: number;traceback: string[];+ /**+ * Exit status reported by execd for a `CommandExecError` when the command ran and finished+ * with a non-zero status (-1 when it was terminated by a signal). Absent when the process+ * failed to start, for non-command errors, and on servers that predate `error.exit_code`.+ */+ exitCode?: number;}export interface ExecutionComplete {diff --git a/sdks/sandbox/javascript/src/models/executionEventDispatcher.ts b/sdks/sandbox/javascript/src/models/executionEventDispatcher.tsindex 3eece585d..3686a1d5a 100644--- a/sdks/sandbox/javascript/src/models/executionEventDispatcher.ts+++ b/sdks/sandbox/javascript/src/models/executionEventDispatcher.ts@@ -89,6 +89,9 @@ export class ExecutionEventDispatcher {timestamp: ts,traceback: Array.isArray(e.traceback) ? e.traceback.map(String) : [],};+ if (typeof e.exit_code === "number" && Number.isInteger(e.exit_code)) {+ err.exitCode = e.exit_code;+ }this.execution.error = err;await this.handlers?.onError?.(err);}diff --git a/sdks/sandbox/javascript/tests/commands.run.test.mjs b/sdks/sandbox/javascript/tests/commands.run.test.mjsindex 0e0dc146b..447e79295 100644--- a/sdks/sandbox/javascript/tests/commands.run.test.mjs+++ b/sdks/sandbox/javascript/tests/commands.run.test.mjs@@ -245,6 +245,67 @@ test("CommandsAdapter.runInSession infers non-zero exitCode from final error staassert.equal(execution.exitCode, 7);});+test("CommandsAdapter.run propagates error.exit_code and prefers it over evalue", async () => {+ const adapter = createAdapter(+ [+ 'data: {"type":"init","text":"cmd-exit","timestamp":1}',+ 'data: {"type":"error","error":{"ename":"CommandExecError","evalue":"3","traceback":["exit status 3"],"exit_code":3},"timestamp":2}',+ "",+ ].join("\n"),+ );++ const execution = await adapter.run("exit 3");++ assert.equal(execution.error?.exitCode, 3);+ assert.equal(execution.exitCode, 3);+});++test("CommandsAdapter.run reports a signal kill (exit_code -1) as a failure", async () => {+ const adapter = createAdapter(+ [+ 'data: {"type":"init","text":"cmd-sig","timestamp":1}',+ 'data: {"type":"error","error":{"ename":"CommandExecError","evalue":"-1","traceback":["signal: terminated"],"exit_code":-1},"timestamp":2}',+ "",+ ].join("\n"),+ );++ const execution = await adapter.run("kill -TERM $$");++ assert.equal(execution.error?.exitCode, -1);+ assert.equal(execution.exitCode, -1);+ assert.equal(execution.complete, undefined);+});++test("CommandsAdapter.run leaves exitCode null for start failures without exit_code", async () => {+ const adapter = createAdapter(+ [+ 'data: {"type":"init","text":"cmd-start","timestamp":1}',+ 'data: {"type":"error","error":{"ename":"CommandExecError","evalue":"fork/exec /bin/sh: argument list too long","traceback":["fork/exec /bin/sh: argument list too long"]},"timestamp":2}',+ "",+ ].join("\n"),+ );++ const execution = await adapter.run("huge");++ assert.equal(execution.error?.exitCode, undefined);+ assert.equal(execution.exitCode, null);+});++test("CommandsAdapter.runInSession propagates error.exit_code", async () => {+ const adapter = createAdapter(+ [+ 'data: {"type":"init","text":"sess-exit","timestamp":1}',+ 'data: {"type":"error","error":{"ename":"CommandExecError","evalue":"-1","traceback":["signal: killed"],"exit_code":-1},"timestamp":2}',+ "",+ ].join("\n"),+ );++ const execution = await adapter.runInSession("sess-3", "kill -KILL $$");++ assert.equal(execution.error?.exitCode, -1);+ assert.equal(execution.exitCode, -1);+});+test("execd client error message carries unstructured JSON error body", async () => {const adapter = new CommandsAdapter(createExecdClient({diff --git a/sdks/sandbox/python/src/opensandbox/adapters/converter/command_execution.py b/sdks/sandbox/python/src/opensandbox/adapters/converter/command_execution.pyindex 60f0e2923..aa7abadc6 100644--- a/sdks/sandbox/python/src/opensandbox/adapters/converter/command_execution.py+++ b/sdks/sandbox/python/src/opensandbox/adapters/converter/command_execution.py@@ -40,6 +40,10 @@ def resolve_run_in_session_timeout(timeout: timedelta | None) -> int | None:def infer_foreground_exit_code(execution: Execution) -> int | None:if execution.error is not None:+ # Prefer the authoritative error.exit_code; fall back to parsing evalue+ # for servers that predate it.+ if execution.error.exit_code is not None:+ return execution.error.exit_codetry:return int(execution.error.value)except (TypeError, ValueError):diff --git a/sdks/sandbox/python/src/opensandbox/adapters/converter/event_node.py b/sdks/sandbox/python/src/opensandbox/adapters/converter/event_node.pyindex 26fb11fea..35ee49159 100644--- a/sdks/sandbox/python/src/opensandbox/adapters/converter/event_node.py+++ b/sdks/sandbox/python/src/opensandbox/adapters/converter/event_node.py@@ -28,6 +28,7 @@ class EventNodeError(BaseModel):name: str | None = Field(default=None, alias="ename")value: str | None = Field(default=None, alias="evalue")traceback: list[str] = Field(default_factory=list)+ exit_code: int | None = Field(default=None, alias="exit_code")@field_validator("traceback", mode="before")@classmethoddiff --git a/sdks/sandbox/python/src/opensandbox/adapters/converter/execution_event_dispatcher.py b/sdks/sandbox/python/src/opensandbox/adapters/converter/execution_event_dispatcher.pyindex b5116a2d3..f7829ae76 100644--- a/sdks/sandbox/python/src/opensandbox/adapters/converter/execution_event_dispatcher.py+++ b/sdks/sandbox/python/src/opensandbox/adapters/converter/execution_event_dispatcher.py@@ -117,6 +117,7 @@ class ExecutionEventDispatcher:value=error_data.value or "",timestamp=timestamp,traceback=error_data.traceback,+ exit_code=error_data.exit_code,)self.execution.error = errorif self.handlers and self.handlers.on_error:diff --git a/sdks/sandbox/python/src/opensandbox/adapters/isolated_adapter.py b/sdks/sandbox/python/src/opensandbox/adapters/isolated_adapter.pyindex 7c0095dec..55f37c5a6 100644--- a/sdks/sandbox/python/src/opensandbox/adapters/isolated_adapter.py+++ b/sdks/sandbox/python/src/opensandbox/adapters/isolated_adapter.py@@ -76,6 +76,10 @@ def _decode_sse_event_data(data: str) -> EventNode | None:def _infer_exit_code(execution: Execution) -> int | None:if execution.error is not None:+ # Prefer the authoritative error.exit_code; fall back to parsing evalue+ # for servers that predate it.+ if execution.error.exit_code is not None:+ return execution.error.exit_codetry:return int(execution.error.value)except (TypeError, ValueError):diff --git a/sdks/sandbox/python/src/opensandbox/models/execd.py b/sdks/sandbox/python/src/opensandbox/models/execd.pyindex 25456bb50..cc5c04d75 100644--- a/sdks/sandbox/python/src/opensandbox/models/execd.py+++ b/sdks/sandbox/python/src/opensandbox/models/execd.py@@ -82,6 +82,15 @@ class ExecutionError(BaseModel):description="Unix timestamp in milliseconds when error occurred")traceback: list[str] = Field(default_factory=list, description="Stack trace lines")+ exit_code: int | None = Field(+ default=None,+ description=(+ "Exit status reported by execd for a CommandExecError when the command ran "+ "and finished with a non-zero status (-1 when it was terminated by a signal). "+ "None when the process failed to start, for non-command errors, and on "+ "servers that predate error.exit_code."+ ),+ )model_config = ConfigDict(populate_by_name=True)diff --git a/sdks/sandbox/python/src/opensandbox/sync/adapters/converter/execution_event_dispatcher.py b/sdks/sandbox/python/src/opensandbox/sync/adapters/converter/execution_event_dispatcher.pyindex 90c257f72..4ee8af56a 100644--- a/sdks/sandbox/python/src/opensandbox/sync/adapters/converter/execution_event_dispatcher.py+++ b/sdks/sandbox/python/src/opensandbox/sync/adapters/converter/execution_event_dispatcher.py@@ -95,6 +95,7 @@ class ExecutionEventDispatcherSync:value=error_data.value or "",timestamp=timestamp,traceback=error_data.traceback,+ exit_code=error_data.exit_code,)self.execution.error = errorif self.handlers and self.handlers.on_error:diff --git a/sdks/sandbox/python/src/opensandbox/sync/adapters/isolated_adapter.py b/sdks/sandbox/python/src/opensandbox/sync/adapters/isolated_adapter.pyindex 7c5d47f7a..73e6ccf13 100644--- a/sdks/sandbox/python/src/opensandbox/sync/adapters/isolated_adapter.py+++ b/sdks/sandbox/python/src/opensandbox/sync/adapters/isolated_adapter.py@@ -76,6 +76,10 @@ def _decode_sse_event_data(data: str) -> EventNode | None:def _infer_exit_code(execution: Execution) -> int | None:if execution.error is not None:+ # Prefer the authoritative error.exit_code; fall back to parsing evalue+ # for servers that predate it.+ if execution.error.exit_code is not None:+ return execution.error.exit_codetry:return int(execution.error.value)except (TypeError, ValueError):diff --git a/sdks/sandbox/python/tests/test_command_service_adapter_streaming.py b/sdks/sandbox/python/tests/test_command_service_adapter_streaming.pyindex 2a51bb65f..8d63b2505 100644--- a/sdks/sandbox/python/tests/test_command_service_adapter_streaming.py+++ b/sdks/sandbox/python/tests/test_command_service_adapter_streaming.py@@ -486,3 +486,60 @@ async def test_foreground_drains_terminal_response_and_closes_stream(assert (execution.complete is None) == failureassert stream.exhaustedassert stream.closed+++class _ErrorEventTransport(httpx.AsyncBaseTransport):+ """Replies to any request with a single CommandExecError event."""++ def __init__(self, error: dict) -> None:+ self._error = error++ async def handle_async_request(self, request: httpx.Request) -> httpx.Response:+ sse = (+ b'data: {"type":"init","text":"exec-err","timestamp":1}\n\n'+ + b"data: "+ + json.dumps({"type": "error", "error": self._error, "timestamp": 2}).encode()+ + b"\n\n"+ )+ return httpx.Response(+ 200,+ headers={"Content-Type": "text/event-stream"},+ content=sse,+ request=request,+ )++[email protected]("in_session", [False, True])+ ("error", "expected_error_exit_code", "expected_exit_code"),+ [+ # exit_code is authoritative and wins over evalue.+ ({"ename": "CommandExecError", "evalue": "3", "exit_code": 3}, 3, 3),+ # A shell killed by a signal is a failure with exit_code -1.+ ({"ename": "CommandExecError", "evalue": "-1", "exit_code": -1}, -1, -1),+ # Start failure: no exit_code and a free-form evalue.+ ({"ename": "CommandExecError", "evalue": "fork/exec /bin/sh: argument list too long"}, None, None),+ # Older servers without exit_code: fall back to parsing evalue.+ ({"ename": "CommandExecError", "evalue": "7"}, None, 7),+ ],+)+async def test_error_exit_code_propagates_to_execution(+ error: dict,+ expected_error_exit_code: int | None,+ expected_exit_code: int | None,+ in_session: bool,+) -> None:+ cfg = ConnectionConfig(protocol="http", transport=_ErrorEventTransport(error))+ endpoint = SandboxEndpoint(endpoint="localhost:44772", port=44772)+ adapter = CommandsAdapter(cfg, endpoint)++ if in_session:+ execution = await adapter.run_in_session("sess-err", "cmd")+ else:+ execution = await adapter.run("cmd")++ assert execution.error is not None+ assert execution.error.exit_code == expected_error_exit_code+ assert execution.exit_code == expected_exit_code+ assert execution.complete is Nonediff --git a/sdks/sandbox/python/tests/test_sync_command_service_adapter_streaming.py b/sdks/sandbox/python/tests/test_sync_command_service_adapter_streaming.pyindex 596c66ecd..af25195df 100644--- a/sdks/sandbox/python/tests/test_sync_command_service_adapter_streaming.py+++ b/sdks/sandbox/python/tests/test_sync_command_service_adapter_streaming.py@@ -427,3 +427,55 @@ def test_foreground_drains_terminal_response_and_closes_stream(assert (execution.complete is None) == failureassert stream.exhaustedassert stream.closed+++class _ErrorEventTransport(httpx.BaseTransport):+ """Replies to any request with a single CommandExecError event."""++ def __init__(self, error: dict) -> None:+ self._error = error++ def handle_request(self, request: httpx.Request) -> httpx.Response:+ sse = (+ b'data: {"type":"init","text":"exec-err","timestamp":1}\n\n'+ + b"data: "+ + json.dumps({"type": "error", "error": self._error, "timestamp": 2}).encode()+ + b"\n\n"+ )+ return httpx.Response(+ 200,+ headers={"Content-Type": "text/event-stream"},+ content=sse,+ request=request,+ )++[email protected]("in_session", [False, True])+ ("error", "expected_error_exit_code", "expected_exit_code"),+ [+ ({"ename": "CommandExecError", "evalue": "3", "exit_code": 3}, 3, 3),+ ({"ename": "CommandExecError", "evalue": "-1", "exit_code": -1}, -1, -1),+ ({"ename": "CommandExecError", "evalue": "fork/exec /bin/sh: argument list too long"}, None, None),+ ({"ename": "CommandExecError", "evalue": "7"}, None, 7),+ ],+)+def test_error_exit_code_propagates_to_execution(+ error: dict,+ expected_error_exit_code: int | None,+ expected_exit_code: int | None,+ in_session: bool,+) -> None:+ cfg = ConnectionConfigSync(protocol="http", transport=_ErrorEventTransport(error))+ endpoint = SandboxEndpoint(endpoint="localhost:44772", port=44772)+ adapter = CommandsAdapterSync(cfg, endpoint)++ if in_session:+ execution = adapter.run_in_session("sess-err", "cmd")+ else:+ execution = adapter.run("cmd")++ assert execution.error is not None+ assert execution.error.exit_code == expected_error_exit_code+ assert execution.exit_code == expected_exit_code+ assert execution.complete is None