Skip to content

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

fix(sdks): surface execution_complete.exit_code in Go and Kotlin SDKs

BootstrapperSBLf296a6e47d43
diff --git a/sdks/sandbox/go/execution.go b/sdks/sandbox/go/execution.go
index c7ea17448..f67206b5c 100644
--- a/sdks/sandbox/go/execution.go
+++ b/sdks/sandbox/go/execution.go
@@ -56,6 +56,12 @@ type ExecutionError struct {
type ExecutionComplete struct {
Timestamp int64 `json:"timestamp"`
ExecutionTime int64 `json:"execution_time"`
+ // ExitCode is the successful foreground POST /command process exit status
+ // (0), present only on its execution_complete event after the process has
+ // exited. Nil for background startup acknowledgements, code execution,
+ // other events, and servers that predate execution_complete.exit_code.
+ // Non-zero command exits use error.exit_code instead.
+ ExitCode *int `json:"exit_code,omitempty"`
}
// ExecutionInit represents the initialization event from the server.
@@ -245,12 +251,19 @@ func processStreamEvent(exec *Execution, event StreamEvent, handlers *ExecutionH
complete := ExecutionComplete{
Timestamp: ev.Timestamp,
ExecutionTime: ev.ExecutionTime,
+ ExitCode: ev.ExitCode,
}
exec.Complete = &complete
- // Foreground command exit code: 0 if no error
- if exec.ExitCode == nil && exec.Error == nil {
- zero := 0
- exec.ExitCode = &zero
+ // Prefer the wire execution_complete.exit_code when present; otherwise
+ // infer 0 for a successful foreground completion (older servers omit it).
+ if exec.ExitCode == nil {
+ if ev.ExitCode != nil {
+ code := *ev.ExitCode
+ exec.ExitCode = &code
+ } else if exec.Error == nil {
+ zero := 0
+ exec.ExitCode = &zero
+ }
}
if handlers != nil && handlers.OnComplete != nil {
return handlers.OnComplete(complete)
diff --git a/sdks/sandbox/go/opensandbox_test.go b/sdks/sandbox/go/opensandbox_test.go
index d1d9f985f..4c1cc439a 100644
--- a/sdks/sandbox/go/opensandbox_test.go
+++ b/sdks/sandbox/go/opensandbox_test.go
@@ -2545,6 +2545,46 @@ func TestExecution_ErrorEventExitCode(t *testing.T) {
}
}
+func TestExecution_CompleteEventExitCode(t *testing.T) {
+ intPtr := func(v int) *int { return &v }
+ tests := []struct {
+ name string
+ data string
+ wantCompleteCode *int
+ wantExecutionCode *int
+ }{
+ {
+ name: "wire exit_code is surfaced on complete and execution",
+ data: `{"type":"execution_complete","timestamp":10,"execution_time":5,"exit_code":0}`,
+ wantCompleteCode: intPtr(0),
+ wantExecutionCode: intPtr(0),
+ },
+ {
+ name: "older server without exit_code still infers zero",
+ data: `{"type":"execution_complete","timestamp":10,"execution_time":5}`,
+ wantCompleteCode: nil,
+ wantExecutionCode: intPtr(0),
+ },
+ }
+
+ for _, tc := range tests {
+ t.Run(tc.name, func(t *testing.T) {
+ exec := &Execution{}
+ var handled *ExecutionComplete
+ handlers := &ExecutionHandlers{
+ OnComplete: func(c ExecutionComplete) error { handled = &c; return nil },
+ }
+ require.NoError(t, processStreamEvent(exec, StreamEvent{Event: "execution_complete", Data: tc.data}, handlers))
+
+ require.NotNil(t, exec.Complete)
+ require.NotNil(t, handled)
+ require.Equal(t, tc.wantCompleteCode, exec.Complete.ExitCode)
+ require.Equal(t, tc.wantCompleteCode, handled.ExitCode)
+ require.Equal(t, tc.wantExecutionCode, exec.ExitCode)
+ })
+ }
+}
+
func TestExecution_HandlersInvoked(t *testing.T) {
exec := &Execution{}
var initCalled, stdoutCalled, stderrCalled, resultCalled, completeCalled bool
diff --git a/sdks/sandbox/kotlin/sandbox-api/src/main/kotlin/com/alibaba/opensandbox/sandbox/api/models/execd/ExecutionModels.kt b/sdks/sandbox/kotlin/sandbox-api/src/main/kotlin/com/alibaba/opensandbox/sandbox/api/models/execd/ExecutionModels.kt
index 0c125065a..d60881589 100644
--- a/sdks/sandbox/kotlin/sandbox-api/src/main/kotlin/com/alibaba/opensandbox/sandbox/api/models/execd/ExecutionModels.kt
+++ b/sdks/sandbox/kotlin/sandbox-api/src/main/kotlin/com/alibaba/opensandbox/sandbox/api/models/execd/ExecutionModels.kt
@@ -33,6 +33,11 @@ data class EventNode(
@SerialName("execution_count")
val executionCount: Long? = null,
val error: ErrorData? = null,
+ // Successful foreground POST /command exit status (0). Present only on
+ // execution_complete after the process has exited; omitted for background
+ // startup, code execution, and older servers. Non-zero exits use error.exit_code.
+ @SerialName("exit_code")
+ val exitCode: Long? = null,
)
@Serializable
@@ -53,4 +58,9 @@ data class ErrorData(
val value: String? = null,
@SerialName("traceback")
val traceback: List<String> = emptyList(),
+ // Exit status for CommandExecError when the command ran and finished
+ // non-zero (-1 when terminated by a signal). Null when the process failed
+ // to start, for non-command errors, and on servers that predate error.exit_code.
+ @SerialName("exit_code")
+ val exitCode: Long? = null,
)
diff --git a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/models/execd/executions/ExecutionModels.kt b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/models/execd/executions/ExecutionModels.kt
index 04bccb944..fd1a0cb10 100644
--- a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/models/execd/executions/ExecutionModels.kt
+++ b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/models/execd/executions/ExecutionModels.kt
@@ -148,6 +148,13 @@ class ExecutionError(
val value: String,
val timestamp: Long,
val traceback: List<String> = emptyList(),
+ /**
+ * Exit status reported by execd for a CommandExecError when the command ran
+ * and finished with a non-zero status (-1 when terminated by a signal).
+ * Null when the process failed to start, for non-command errors, and on
+ * servers that predate error.exit_code.
+ */
+ val exitCode: Int? = null,
)
/**
@@ -166,6 +173,12 @@ class ExecutionComplete(
* Execution time in mills
*/
val executionTimeInMillis: Long,
+ /**
+ * Successful foreground POST /command exit status (0), when present on the
+ * wire execution_complete event. Null for background startup, code
+ * execution, and servers that omit execution_complete.exit_code.
+ */
+ val exitCode: Int? = null,
)
/**
diff --git a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/converter/ExecutionEventDispatcher.kt b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/converter/ExecutionEventDispatcher.kt
index 2927f9d10..a6fae7b96 100644
--- a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/converter/ExecutionEventDispatcher.kt
+++ b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/converter/ExecutionEventDispatcher.kt
@@ -105,6 +105,7 @@ class ExecutionEventDispatcher(
value = errorData.value ?: "",
traceback = errorData.traceback,
timestamp = timestamp,
+ exitCode = errorData.exitCode?.toInt(),
)
execution.error = error
handlers?.onError?.handle(error)
@@ -118,6 +119,7 @@ class ExecutionEventDispatcher(
ExecutionComplete(
executionTimeInMillis = eventNode.executionTimeInMillis ?: 0L,
timestamp = timestamp,
+ exitCode = eventNode.exitCode?.toInt(),
)
execution.complete = complete
handlers?.onExecutionComplete?.handle(complete)
diff --git a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/ExecdEventSupport.kt b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/ExecdEventSupport.kt
index e2f908a04..4932f2a11 100644
--- a/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/ExecdEventSupport.kt
+++ b/sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/ExecdEventSupport.kt
@@ -59,12 +59,19 @@ public object ExecdEventSupport {
}
}
- /** Error payload carries the code on failure; completion implies success. */
+ /**
+ * Prefers the authoritative wire exit_code (error.exitCode /
+ * complete.exitCode) and falls back to parsing error.value for older
+ * servers. A completed execution without an error is 0 when the wire
+ * field is absent; unfinished executions stay null.
+ */
public fun inferForegroundExitCode(execution: Execution): Int? {
- return if (execution.error != null) {
- execution.error?.value?.toIntOrNull()
- } else {
- if (execution.complete != null) 0 else null
+ val error = execution.error
+ if (error != null) {
+ error.exitCode?.let { return it }
+ return error.value.toIntOrNull()
}
+ val complete = execution.complete ?: return null
+ return complete.exitCode ?: 0
}
}
diff --git a/sdks/sandbox/kotlin/sandbox/src/test/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/ExecdEventSupportTest.kt b/sdks/sandbox/kotlin/sandbox/src/test/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/ExecdEventSupportTest.kt
index dc73eab77..e301af161 100644
--- a/sdks/sandbox/kotlin/sandbox/src/test/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/ExecdEventSupportTest.kt
+++ b/sdks/sandbox/kotlin/sandbox/src/test/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/ExecdEventSupportTest.kt
@@ -115,4 +115,72 @@ class ExecdEventSupportTest {
}
assertNull(ExecdEventSupport.inferForegroundExitCode(nonNumeric))
}
+
+ @Test
+ fun `foreground exit code prefers authoritative error exitCode over evalue`() {
+ val mismatched =
+ Execution().apply {
+ error =
+ ExecutionError(
+ name = "CommandExecError",
+ value = "99",
+ timestamp = 1,
+ exitCode = 3,
+ )
+ }
+ assertEquals(3, ExecdEventSupport.inferForegroundExitCode(mismatched))
+
+ val signalKill =
+ Execution().apply {
+ error =
+ ExecutionError(
+ name = "CommandExecError",
+ value = "-1",
+ timestamp = 1,
+ exitCode = -1,
+ )
+ }
+ assertEquals(-1, ExecdEventSupport.inferForegroundExitCode(signalKill))
+
+ val startFailure =
+ Execution().apply {
+ error =
+ ExecutionError(
+ name = "CommandExecError",
+ value = "fork/exec /bin/sh: argument list too long",
+ timestamp = 1,
+ )
+ }
+ assertNull(ExecdEventSupport.inferForegroundExitCode(startFailure))
+ }
+
+ @Test
+ fun `foreground exit code prefers wire complete exitCode when present`() {
+ val withWire =
+ Execution().apply {
+ complete = ExecutionComplete(timestamp = 1, executionTimeInMillis = 1, exitCode = 0)
+ }
+ assertEquals(0, ExecdEventSupport.inferForegroundExitCode(withWire))
+ }
+
+ @Test
+ fun `decodes execution_complete and error exit_code wire fields`() {
+ val complete =
+ decode(
+ """{"type":"execution_complete","timestamp":10,"execution_time":5,"exit_code":0}""",
+ )
+ assertNotNull(complete)
+ assertEquals("execution_complete", complete!!.type)
+ assertEquals(0L, complete.exitCode)
+
+ val error =
+ decode(
+ """{"type":"error","timestamp":11,"error":{"ename":"CommandExecError","evalue":"3","traceback":["exit status 3"],"exit_code":3}}""",
+ )
+ assertNotNull(error)
+ assertEquals("error", error!!.type)
+ assertNotNull(error.error)
+ assertEquals(3L, error.error!!.exitCode)
+ assertTrue(reported.isEmpty())
+ }
}