Skip to content

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

fix(execd): report exit_code on command errors so start failures are distinguishable

BootstrapperSBL27f796dbbda6
diff --git a/components/execd/pkg/jupyter/execute/types.go b/components/execd/pkg/jupyter/execute/types.go
index c234ac22c..3550fce82 100644
--- a/components/execd/pkg/jupyter/execute/types.go
+++ b/components/execd/pkg/jupyter/execute/types.go
@@ -152,6 +152,13 @@ type ErrorOutput struct {
EValue string `json:"evalue"`
Traceback []string `json:"traceback"`
+
+ // ExitCode is the process exit status. It is set only when a command
+ // actually ran and finished with a non-zero status (-1 when it was
+ // terminated by a signal), so clients can tell an exit status apart from
+ // a failure to start the process, which shares the same ename. It is
+ // omitted for start failures and for non-command errors.
+ ExitCode *int `json:"exit_code,omitempty"`
}
func (e *ErrorOutput) String() string {
diff --git a/components/execd/pkg/jupyter/execute/zz_generated.deepcopy.go b/components/execd/pkg/jupyter/execute/zz_generated.deepcopy.go
index ad7552059..8910ba863 100644
--- a/components/execd/pkg/jupyter/execute/zz_generated.deepcopy.go
+++ b/components/execd/pkg/jupyter/execute/zz_generated.deepcopy.go
@@ -28,6 +28,11 @@ func (in *ErrorOutput) DeepCopyInto(out *ErrorOutput) {
*out = make([]string, len(*in))
copy(*out, *in)
}
+ if in.ExitCode != nil {
+ in, out := &in.ExitCode, &out.ExitCode
+ *out = new(int)
+ **out = **in
+ }
}
// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ErrorOutput.
diff --git a/components/execd/pkg/runtime/bash_session.go b/components/execd/pkg/runtime/bash_session.go
index fddf75f3e..eeaaef0f5 100644
--- a/components/execd/pkg/runtime/bash_session.go
+++ b/components/execd/pkg/runtime/bash_session.go
@@ -373,6 +373,7 @@ func (s *bashSession) run(ctx context.Context, request *ExecuteCodeRequest) erro
EName: "CommandExecError",
EValue: strconv.Itoa(userExitCode),
Traceback: []string{errMsg},
+ ExitCode: &userExitCode,
})
}
log.Error("bash session: command error: %s (command: %q)", errMsg, log.SanitizeCommand(request.Code))
diff --git a/components/execd/pkg/runtime/bash_session_test.go b/components/execd/pkg/runtime/bash_session_test.go
index 676e3ccb4..e5a9603a6 100644
--- a/components/execd/pkg/runtime/bash_session_test.go
+++ b/components/execd/pkg/runtime/bash_session_test.go
@@ -79,6 +79,8 @@ func TestBashSession_NonZeroExitEmitsError(t *testing.T) {
require.NotNil(t, gotErr, "expected non-nil error output")
require.Equal(t, "CommandExecError", gotErr.EName)
require.Equal(t, "7", gotErr.EValue)
+ require.NotNil(t, gotErr.ExitCode, "expected exit_code for a command that ran")
+ require.Equal(t, 7, *gotErr.ExitCode)
require.NotEmpty(t, sessionID, "expected session id to be set")
require.Equal(t, "before", stdoutLine)
diff --git a/components/execd/pkg/runtime/command.go b/components/execd/pkg/runtime/command.go
index 40054d43d..e1a787308 100644
--- a/components/execd/pkg/runtime/command.go
+++ b/components/execd/pkg/runtime/command.go
@@ -337,6 +337,7 @@ func (c *Controller) runCommand(ctx context.Context, request *ExecuteCodeRequest
if err != nil {
var eName, eValue string
var eCode int
+ var exitCodePtr *int
var traceback []string
var exitCodeErr exitCoder
@@ -345,6 +346,7 @@ func (c *Controller) runCommand(ctx context.Context, request *ExecuteCodeRequest
eName = "CommandExecError"
eValue = strconv.Itoa(exitCode)
eCode = exitCode
+ exitCodePtr = &exitCode
} else {
eName = "CommandExecError"
eValue = err.Error()
@@ -356,6 +358,7 @@ func (c *Controller) runCommand(ctx context.Context, request *ExecuteCodeRequest
EName: eName,
EValue: eValue,
Traceback: traceback,
+ ExitCode: exitCodePtr,
})
log.Error("command: run failed: %v", err)
diff --git a/components/execd/pkg/runtime/command_test.go b/components/execd/pkg/runtime/command_test.go
index 99beb5c12..f03c6bc66 100644
--- a/components/execd/pkg/runtime/command_test.go
+++ b/components/execd/pkg/runtime/command_test.go
@@ -335,6 +335,8 @@ func TestRunCommand_Error(t *testing.T) {
require.NotNil(t, gotErr, "expected error hook to be called")
require.Equal(t, "CommandExecError", gotErr.EName)
require.Equal(t, "3", gotErr.EValue)
+ require.NotNil(t, gotErr.ExitCode, "expected exit_code for a command that ran")
+ require.Equal(t, 3, *gotErr.ExitCode)
}
func TestRunCommand_ExpandsHomeInCwd(t *testing.T) {
@@ -493,6 +495,7 @@ func TestRunCommand_StartErrorIncludesTraceback(t *testing.T) {
require.Equal(t, "CommandExecError", gotErr.EName)
require.NotEmpty(t, gotErr.Traceback, "expected traceback to be populated")
require.Equal(t, gotErr.EValue, gotErr.Traceback[0])
+ require.Nil(t, gotErr.ExitCode, "start failure must not report an exit_code")
require.False(t, completeCalled, "did not expect completion hook on start failure")
}
diff --git a/components/execd/pkg/runtime/command_windows.go b/components/execd/pkg/runtime/command_windows.go
index 014a047e0..775f19940 100644
--- a/components/execd/pkg/runtime/command_windows.go
+++ b/components/execd/pkg/runtime/command_windows.go
@@ -97,6 +97,7 @@ func (c *Controller) runCommand(ctx context.Context, request *ExecuteCodeRequest
if err != nil {
var eName, eValue string
eCode := 1
+ var exitCodePtr *int
var traceback []string
var exitError *exec.ExitError
@@ -105,6 +106,7 @@ func (c *Controller) runCommand(ctx context.Context, request *ExecuteCodeRequest
eName = "CommandExecError"
eValue = strconv.Itoa(exitCode)
eCode = exitCode
+ exitCodePtr = &exitCode
} else {
eName = "CommandExecError"
eValue = err.Error()
@@ -115,6 +117,7 @@ func (c *Controller) runCommand(ctx context.Context, request *ExecuteCodeRequest
EName: eName,
EValue: eValue,
Traceback: traceback,
+ ExitCode: exitCodePtr,
})
log.Error("command: run failed: %v", err)
diff --git a/components/execd/pkg/web/model/codeinterpreting_test.go b/components/execd/pkg/web/model/codeinterpreting_test.go
index 615069501..c6b45429a 100644
--- a/components/execd/pkg/web/model/codeinterpreting_test.go
+++ b/components/execd/pkg/web/model/codeinterpreting_test.go
@@ -153,6 +153,36 @@ func TestServerStreamEventToJSON(t *testing.T) {
require.Equal(t, event.ExecutionCount, decoded.ExecutionCount)
}
+func TestServerStreamEventErrorExitCodeJSON(t *testing.T) {
+ exitCode := 3
+ exited := ServerStreamEvent{
+ Type: StreamEventTypeError,
+ Error: &execute.ErrorOutput{
+ EName: "CommandExecError",
+ EValue: "3",
+ Traceback: []string{"exit status 3"},
+ ExitCode: &exitCode,
+ },
+ }
+ require.Contains(t, string(exited.ToJSON()), `"exit_code":3`)
+
+ var decoded ServerStreamEvent
+ require.NoError(t, json.Unmarshal(exited.ToJSON(), &decoded))
+ require.NotNil(t, decoded.Error)
+ require.NotNil(t, decoded.Error.ExitCode)
+ require.Equal(t, 3, *decoded.Error.ExitCode)
+
+ startFailure := ServerStreamEvent{
+ Type: StreamEventTypeError,
+ Error: &execute.ErrorOutput{
+ EName: "CommandExecError",
+ EValue: "fork/exec /usr/bin/bash: argument list too long",
+ Traceback: []string{"fork/exec /usr/bin/bash: argument list too long"},
+ },
+ }
+ require.NotContains(t, string(startFailure.ToJSON()), "exit_code")
+}
+
func TestServerStreamEventSummary(t *testing.T) {
longText := strings.Repeat("a", 120)
tests := []struct {
diff --git a/sdks/sandbox/javascript/src/api/execd.ts b/sdks/sandbox/javascript/src/api/execd.ts
index decee1bb9..1861559be 100644
--- a/sdks/sandbox/javascript/src/api/execd.ts
+++ b/sdks/sandbox/javascript/src/api/execd.ts
@@ -1449,7 +1449,7 @@ export interface components {
*/
ename?: string;
/**
- * @description Error value/message
+ * @description Error value/message. For `CommandExecError` this is the stringified exit status when the command ran and exited non-zero, and a free-form message when the process could not be started; use `exit_code` to tell the two apart.
* @example name 'undefined_var' is not defined
*/
evalue?: string;
@@ -1462,6 +1462,11 @@ export interface components {
* ]
*/
traceback?: string[];
+ /**
+ * @description Exit status of a command that ran and finished with a non-zero status (-1 when it was terminated by a signal). Present only on `CommandExecError` events emitted after the process ran; omitted when the process failed to start and for non-command errors.
+ * @example 3
+ */
+ exit_code?: number;
};
};
/** @description File metadata including path and permissions */
diff --git a/sdks/sandbox/python/src/opensandbox/api/execd/models/server_stream_event_error.py b/sdks/sandbox/python/src/opensandbox/api/execd/models/server_stream_event_error.py
index 0f615e7fb..872827d75 100644
--- a/sdks/sandbox/python/src/opensandbox/api/execd/models/server_stream_event_error.py
+++ b/sdks/sandbox/python/src/opensandbox/api/execd/models/server_stream_event_error.py
@@ -33,14 +33,20 @@ class ServerStreamEventError:
Attributes:
ename (str | Unset): Error name/type Example: NameError.
- evalue (str | Unset): Error value/message Example: name 'undefined_var' is not defined.
+ evalue (str | Unset): Error value/message. For `CommandExecError` this is the stringified exit status when the
+ command ran and exited non-zero, and a free-form message when the process could not be started; use `exit_code`
+ to tell the two apart. Example: name 'undefined_var' is not defined.
traceback (list[str] | Unset): Stack trace lines Example: ['Traceback (most recent call last):', ' File
"<stdin>", line 1, in <module>', "NameError: name 'undefined_var' is not defined"].
+ exit_code (int | Unset): Exit status of a command that ran and finished with a non-zero status (-1 when it was
+ terminated by a signal). Present only on `CommandExecError` events emitted after the process ran; omitted when
+ the process failed to start and for non-command errors. Example: 3.
"""
ename: str | Unset = UNSET
evalue: str | Unset = UNSET
traceback: list[str] | Unset = UNSET
+ exit_code: int | Unset = UNSET
additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
def to_dict(self) -> dict[str, Any]:
@@ -52,6 +58,8 @@ class ServerStreamEventError:
if not isinstance(self.traceback, Unset):
traceback = self.traceback
+ exit_code = self.exit_code
+
field_dict: dict[str, Any] = {}
field_dict.update(self.additional_properties)
field_dict.update({})
@@ -61,6 +69,8 @@ class ServerStreamEventError:
field_dict["evalue"] = evalue
if traceback is not UNSET:
field_dict["traceback"] = traceback
+ if exit_code is not UNSET:
+ field_dict["exit_code"] = exit_code
return field_dict
@@ -73,10 +83,13 @@ class ServerStreamEventError:
traceback = cast(list[str], d.pop("traceback", UNSET))
+ exit_code = d.pop("exit_code", UNSET)
+
server_stream_event_error = cls(
ename=ename,
evalue=evalue,
traceback=traceback,
+ exit_code=exit_code,
)
server_stream_event_error.additional_properties = d
diff --git a/specs/execd-api.yaml b/specs/execd-api.yaml
index 8cd3a3ce6..8061e19fe 100644
--- a/specs/execd-api.yaml
+++ b/specs/execd-api.yaml
@@ -2759,7 +2759,7 @@ components:
example: "NameError"
evalue:
type: string
- description: Error value/message
+ description: "Error value/message. For `CommandExecError` this is the stringified exit status when the command ran and exited non-zero, and a free-form message when the process could not be started; use `exit_code` to tell the two apart."
example: "name 'undefined_var' is not defined"
traceback:
type: array
@@ -2770,6 +2770,10 @@ components:
- "Traceback (most recent call last):"
- ' File "<stdin>", line 1, in <module>'
- "NameError: name 'undefined_var' is not defined"
+ exit_code:
+ type: integer
+ description: "Exit status of a command that ran and finished with a non-zero status (-1 when it was terminated by a signal). Present only on `CommandExecError` events emitted after the process ran; omitted when the process failed to start and for non-command errors."
+ example: 3
FileInfo:
type: object