Secure, Fast, and Extensible Sandbox runtime for AI agents.
fix(execd): preserve bash session output line endings (#2318)
ephaa869b33d3242
diff --git a/components/execd/pkg/runtime/bash_session.go b/components/execd/pkg/runtime/bash_session.goindex 2f049d276..87204a934 100644--- a/components/execd/pkg/runtime/bash_session.go+++ b/components/execd/pkg/runtime/bash_session.go@@ -18,10 +18,10 @@package runtimeimport (- "bufio""context""errors""fmt"+ "io""os""os/exec""sort"@@ -290,41 +290,74 @@ func (s *bashSession) run(ctx context.Context, request *ExecuteCodeRequest) errostopGroupKill := killProcessGroupOnDone(ctx, cmd.Process.Pid)defer stopGroupKill()- scanner := bufio.NewScanner(stdoutR)- scanner.Buffer(make([]byte, 0, 64*1024), 16*1024*1024)-var (envLines []stringpwdLine stringexitCode *intinEnv bool)+ // Env-dump records are reassembled from raw fragment bytes and only+ // finalized on LF: values may contain literal CR bytes (dash quotes them+ // verbatim), so CR-split fragments must be joined before parseExportLine+ // sees a record.+ var envRecord strings.Builder+ flushEnvRecord := func() {+ if envRecord.Len() == 0 {+ return+ }+ envLines = append(envLines, strings.TrimSuffix(envRecord.String(), "\n"))+ envRecord.Reset()+ }- for scanner.Scan() {- line := scanner.Text()+ emit := func(fragment string) {+ if request.Hooks.OnExecuteStdout != nil {+ request.Hooks.OnExecuteStdout(fragment)+ }+ }++ // handleFragment forwards user output while intercepting the wrapper's+ // protocol lines. The wrapper prints the env-dump marker on its own line,+ // so user output that lacks a trailing newline merges with the marker+ // line; stripping the marker suffix keeps that output byte-exact.+ handleFragment := func(fragment string) {+ content := lineContent(fragment)switch {- case line == envDumpStartMarker:+ case content == envDumpStartMarker:+ inEnv = true+ return+ case strings.HasSuffix(content, envDumpStartMarker):inEnv = true- case line == envDumpEndMarker:+ if prefix := strings.TrimSuffix(content, envDumpStartMarker); prefix != "" {+ emit(prefix)+ }+ return+ case content == envDumpEndMarker:inEnv = false- case strings.HasPrefix(line, exitMarkerPrefix):- if code, err := strconv.Atoi(strings.TrimPrefix(line, exitMarkerPrefix)); err == nil {+ return+ case strings.HasPrefix(content, exitMarkerPrefix):+ if code, err := strconv.Atoi(strings.TrimPrefix(content, exitMarkerPrefix)); err == nil {exitCode = &code //nolint:ineffassign}- case strings.HasPrefix(line, pwdMarkerPrefix):- pwdLine = strings.TrimPrefix(line, pwdMarkerPrefix)- default:- if inEnv {- envLines = append(envLines, line)- continue- }- if request.Hooks.OnExecuteStdout != nil {- request.Hooks.OnExecuteStdout(line)+ return+ case strings.HasPrefix(content, pwdMarkerPrefix):+ pwdLine = strings.TrimPrefix(content, pwdMarkerPrefix)+ return+ }+ if inEnv {+ envRecord.WriteString(fragment)+ if strings.HasSuffix(fragment, "\n") {+ flushEnvRecord()}+ return}+ emit(fragment)+ }++ scanErr := scanLineFragments(stdoutR, handleFragment)+ if inEnv {+ flushEnvRecord()}- scanErr := scanner.Err()waitErr := mp.Wait()if scanErr != nil {@@ -355,6 +388,54 @@ func (s *bashSession) run(ctx context.Context, request *ExecuteCodeRequest) erroreturn reportRunResult(request, waitErr, exitCode, startAt)}+// maxScanLineBytes bounds the buffer for a single output fragment without a+// line ending, matching the former bufio.Scanner cap; exceeding it fails the+// run instead of buffering without limit.+const maxScanLineBytes = 16 * 1024 * 1024++// scanLineFragments reads r and calls onFragment for each fragment terminated+// by \n or \r, passing the terminator through; a final unterminated fragment+// is flushed at EOF. Concatenating the fragments reproduces the exact byte+// stream, including blank lines and \r-only progress output.+func scanLineFragments(r io.Reader, onFragment func(string)) error {+ buf := make([]byte, 64*1024)+ var pending []byte+ for {+ n, readErr := r.Read(buf)+ for i := range n {+ b := buf[i]+ pending = append(pending, b)+ if b == '\n' || b == '\r' {+ onFragment(string(pending))+ pending = pending[:0]+ } else if len(pending) >= maxScanLineBytes {+ return fmt.Errorf("output line exceeds %d bytes", maxScanLineBytes)+ }+ }+ if readErr != nil {+ if len(pending) > 0 {+ onFragment(string(pending))+ }+ if errors.Is(readErr, io.EOF) {+ return nil+ }+ return readErr+ }+ }+}++// lineContent strips the single line-ending byte from a fragment produced by+// scanLineFragments; unterminated fragments are returned unchanged.+func lineContent(fragment string) string {+ if fragment == "" {+ return ""+ }+ if c := fragment[len(fragment)-1]; c == '\n' || c == '\r' {+ return fragment[:len(fragment)-1]+ }+ return fragment+}+// reportRunResult maps the shell's wait result and parsed exit code onto the// request hooks: a non-exit wait error is returned, a non-zero exit code is// reported via OnExecuteError, and a clean run via OnExecuteComplete.@@ -455,7 +536,7 @@ func buildWrappedScript(command string, env map[string]string, cwd string) strin}b.WriteString("__USER_EXIT_CODE__=$?\n")- b.WriteString("printf \"\\n%s\\n\" \"" + envDumpStartMarker + "\"\n")+ b.WriteString("printf \"%s\\n\" \"" + envDumpStartMarker + "\"\n")b.WriteString("export -p\n")b.WriteString("printf \"%s\\n\" \"" + envDumpEndMarker + "\"\n")b.WriteString("printf \"" + pwdMarkerPrefix + "%s\\n\" \"$(pwd)\"\n")diff --git a/components/execd/pkg/runtime/bash_session_test.go b/components/execd/pkg/runtime/bash_session_test.goindex 1bc558235..17486f4c2 100644--- a/components/execd/pkg/runtime/bash_session_test.go+++ b/components/execd/pkg/runtime/bash_session_test.go@@ -82,7 +82,7 @@ func TestBashSession_NonZeroExitEmitsError(t *testing.T) {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)+ require.Equal(t, "before\n", stdoutLine)select {case <-completeCh:@@ -140,7 +140,7 @@ func TestBashSession_FallsBackToSh(t *testing.T) {OnExecuteStdout: func(line string) { stdoutLines = append(stdoutLines, line) },},}))- require.Contains(t, stdoutLines, "hello world")+ require.Contains(t, stdoutLines, "hello world\n")}// Round-trip a value containing a single quote under sh to guard against@@ -166,7 +166,7 @@ func TestBashSession_FallsBackToSh_PersistsSingleQuotedValue(t *testing.T) {OnExecuteStdout: func(line string) { stdoutLines = append(stdoutLines, line) },},}))- require.Contains(t, stdoutLines, want)+ require.Contains(t, stdoutLines, want+"\n")}func TestParseExportLine_BashAndShFormats(t *testing.T) {@@ -817,7 +817,7 @@ func TestBashSession_ExecdEnvsFileAppliedToSession(t *testing.T) {OnExecuteStdout: func(line string) { stdoutLines = append(stdoutLines, line) },},}))- require.Contains(t, stdoutLines, "bar")+ require.Contains(t, stdoutLines, "bar\n")}func TestBashSession_ExecdEnvsFileExpandsSessionCwd(t *testing.T) {@@ -841,7 +841,153 @@ func TestBashSession_ExecdEnvsFileExpandsSessionCwd(t *testing.T) {OnExecuteStdout: func(line string) { stdoutLines = append(stdoutLines, line) },},}))- require.Contains(t, stdoutLines, workspace)+ require.Contains(t, stdoutLines, workspace+"\n")+}++// Session stdout events must carry their original line endings so that+// concatenating event text per run reconstructs the exact output bytes,+// matching the foreground command stream contract. Unterminated output ends+// without a terminator, and the wrapper's protocol lines never leak into it.+func TestBashSession_PreservesLineEndings(t *testing.T) {+ requireBash(t)++ tests := []struct {+ name string+ code string+ want []string+ }{+ {+ name: "plain lines",+ code: `echo hi`,+ want: []string{"hi\n"},+ },+ {+ name: "blank lines",+ code: `printf 'a\n\nb\n'`,+ want: []string{"a\n", "\n", "b\n"},+ },+ {+ name: "carriage returns",+ code: `printf 'x\r\ny\rz\n'`,+ want: []string{"x\r", "\n", "y\r", "z\n"},+ },+ {+ name: "unterminated output",+ code: `printf 'partial'`,+ want: []string{"partial"},+ },+ {+ name: "unterminated output ending before carriage return",+ code: `printf 'a\rb'`,+ want: []string{"a\r", "b"},+ },+ {+ name: "bare blank line",+ code: `echo`,+ want: []string{"\n"},+ },+ {+ name: "no output",+ code: `true`,+ want: nil,+ },+ }++ for _, tt := range tests {+ t.Run(tt.name, func(t *testing.T) {+ session := newBashSession("", nil)+ t.Cleanup(func() { _ = session.close() })+ require.NoError(t, session.start())++ var got []string+ require.NoError(t, session.run(context.Background(), &ExecuteCodeRequest{+ Code: tt.code,+ Timeout: 5 * time.Second,+ Hooks: ExecuteResultHook{+ OnExecuteStdout: func(fragment string) { got = append(got, fragment) },+ },+ }))++ require.Equal(t, tt.want, got)+ for _, fragment := range got {+ require.NotContains(t, fragment, envDumpStartMarker)+ require.NotContains(t, fragment, exitMarkerPrefix)+ require.NotContains(t, fragment, pwdMarkerPrefix)+ require.NotContains(t, fragment, "declare -x")+ }+ })+ }+}++// A blank line must be delivered immediately, not held back until the next+// fragment or process exit.+func TestBashSession_FlushesBlankLineImmediately(t *testing.T) {+ requireBash(t)++ session := newBashSession("", nil)+ t.Cleanup(func() { _ = session.close() })+ require.NoError(t, session.start())++ var blankAt time.Duration+ gotBlank := false+ start := time.Now()+ require.NoError(t, session.run(context.Background(), &ExecuteCodeRequest{+ Code: `echo; sleep 2`,+ Timeout: 10 * time.Second,+ Hooks: ExecuteResultHook{+ OnExecuteStdout: func(fragment string) {+ if fragment == "\n" && !gotBlank {+ gotBlank = true+ blankAt = time.Since(start)+ }+ },+ },+ }))++ require.True(t, gotBlank, "blank line event was never delivered")+ require.Less(t, blankAt, 1500*time.Millisecond, "blank line was held back until the run finished")+}++// Output without any line ending must fail the run at the fragment cap+// instead of buffering without limit, mirroring the former 16 MiB scanner cap.+func TestBashSession_OutputLineCapErrors(t *testing.T) {+ requireBash(t)++ session := newBashSession("", nil)+ t.Cleanup(func() { _ = session.close() })+ require.NoError(t, session.start())++ err := session.run(context.Background(), &ExecuteCodeRequest{+ Code: `head -c 17000000 /dev/zero | tr '\0' 'x'`,+ Timeout: 30 * time.Second,+ })+ require.ErrorContains(t, err, "output line exceeds")+}++// Env values may carry a literal CR byte (dash quotes export -p values+// verbatim); the record must survive session persistence byte-exact.+func TestBashSession_EnvValueWithCRPersists(t *testing.T) {+ requireBash(t)+ useShOnlyPath(t)++ session := newBashSession("", nil)+ t.Cleanup(func() { _ = session.close() })+ require.NoError(t, session.start())++ require.NoError(t, session.run(context.Background(), &ExecuteCodeRequest{+ Code: `export CR_VALUE="$(printf 'a\rb')"`,+ Timeout: 5 * time.Second,+ }))++ var got []string+ require.NoError(t, session.run(context.Background(), &ExecuteCodeRequest{+ Code: `printf '%s' "$CR_VALUE"`,+ Timeout: 5 * time.Second,+ Hooks: ExecuteResultHook{+ OnExecuteStdout: func(fragment string) { got = append(got, fragment) },+ },+ }))+ require.Equal(t, []string{"a\r", "b"}, got, "CR inside the persisted env value was lost")}func TestNewBashSessionEnvOverlaysFileAndKeepsBlacklist(t *testing.T) {diff --git a/docs/architecture/data-plane/execd.md b/docs/architecture/data-plane/execd.mdindex 7ae988c1a..85cf948d0 100644--- a/docs/architecture/data-plane/execd.md+++ b/docs/architecture/data-plane/execd.md@@ -58,6 +58,8 @@ Execution modes:Foreground `stdout` and `stderr` event text preserves the command's line endings (`\n`, `\r`, or `\r\n`). Concatenate event text for each stream to reconstruct its output; the last event may be an unterminated fragment.+Bash-session runs stream one merged `stdout` event stream (session stderr is merged into it) with the same line-ending contract: event text preserves `\n`, `\r`, or `\r\n`, and concatenating event text reconstructs the run's output. Blank lines are preserved as events containing only the line ending, and the final event may be an unterminated fragment.+Sessions use Bash when the image provides it and fall back to POSIX `sh` on minimal images — commands sent to a fallback session must be `sh`-compatible. Windows sandboxes are supported (environment names are case-insensitive; batch files require shell syntax).## Code executiondiff --git a/sdks/sandbox/javascript/src/api/execd.ts b/sdks/sandbox/javascript/src/api/execd.tsindex 91624b768..53f9d3df7 100644--- a/sdks/sandbox/javascript/src/api/execd.ts+++ b/sdks/sandbox/javascript/src/api/execd.ts@@ -186,6 +186,10 @@ export interface paths {* @description Executes a shell command in an existing bash session and streams the output in real-time via SSE* (Server-Sent Events). The session must have been created by create_session. Supports* optional working directory override and timeout (milliseconds).+ * The run streams a single merged `stdout` event stream (session stderr is merged into it).+ * Stdout event text preserves the original line endings (`\n`, `\r`, or `\r\n`). Concatenate+ * text from the stdout events to recover the run's output; blank lines appear as events+ * containing only the line ending, and the final event may be an unterminated fragment.*/post: operations["runInSession"];delete?: never;diff --git a/sdks/sandbox/python/src/opensandbox/api/execd/api/command/run_in_session.py b/sdks/sandbox/python/src/opensandbox/api/execd/api/command/run_in_session.pyindex 8f3223775..ff29d2d07 100644--- a/sdks/sandbox/python/src/opensandbox/api/execd/api/command/run_in_session.py+++ b/sdks/sandbox/python/src/opensandbox/api/execd/api/command/run_in_session.py@@ -91,11 +91,15 @@ def sync_detailed(client: AuthenticatedClient | Client,body: RunInSessionRequest,) -> Response[ErrorResponse | ServerStreamEvent]:- """Run command in bash session (run_in_session)+ r"""Run command in bash session (run_in_session)Executes a shell command in an existing bash session and streams the output in real-time via SSE(Server-Sent Events). The session must have been created by create_session. Supportsoptional working directory override and timeout (milliseconds).+ The run streams a single merged `stdout` event stream (session stderr is merged into it).+ Stdout event text preserves the original line endings (`\n`, `\r`, or `\r\n`). Concatenate+ text from the stdout events to recover the run's output; blank lines appear as events+ containing only the line ending, and the final event may be an unterminated fragment.Args:session_id (str):@@ -127,11 +131,15 @@ def sync(client: AuthenticatedClient | Client,body: RunInSessionRequest,) -> ErrorResponse | ServerStreamEvent | None:- """Run command in bash session (run_in_session)+ r"""Run command in bash session (run_in_session)Executes a shell command in an existing bash session and streams the output in real-time via SSE(Server-Sent Events). The session must have been created by create_session. Supportsoptional working directory override and timeout (milliseconds).+ The run streams a single merged `stdout` event stream (session stderr is merged into it).+ Stdout event text preserves the original line endings (`\n`, `\r`, or `\r\n`). Concatenate+ text from the stdout events to recover the run's output; blank lines appear as events+ containing only the line ending, and the final event may be an unterminated fragment.Args:session_id (str):@@ -158,11 +166,15 @@ async def asyncio_detailed(client: AuthenticatedClient | Client,body: RunInSessionRequest,) -> Response[ErrorResponse | ServerStreamEvent]:- """Run command in bash session (run_in_session)+ r"""Run command in bash session (run_in_session)Executes a shell command in an existing bash session and streams the output in real-time via SSE(Server-Sent Events). The session must have been created by create_session. Supportsoptional working directory override and timeout (milliseconds).+ The run streams a single merged `stdout` event stream (session stderr is merged into it).+ Stdout event text preserves the original line endings (`\n`, `\r`, or `\r\n`). Concatenate+ text from the stdout events to recover the run's output; blank lines appear as events+ containing only the line ending, and the final event may be an unterminated fragment.Args:session_id (str):@@ -192,11 +204,15 @@ async def asyncio(client: AuthenticatedClient | Client,body: RunInSessionRequest,) -> ErrorResponse | ServerStreamEvent | None:- """Run command in bash session (run_in_session)+ r"""Run command in bash session (run_in_session)Executes a shell command in an existing bash session and streams the output in real-time via SSE(Server-Sent Events). The session must have been created by create_session. Supportsoptional working directory override and timeout (milliseconds).+ The run streams a single merged `stdout` event stream (session stderr is merged into it).+ Stdout event text preserves the original line endings (`\n`, `\r`, or `\r\n`). Concatenate+ text from the stdout events to recover the run's output; blank lines appear as events+ containing only the line ending, and the final event may be an unterminated fragment.Args:session_id (str):diff --git a/specs/execd-api.yaml b/specs/execd-api.yamlindex 493710fa3..8c4215d76 100644--- a/specs/execd-api.yaml+++ b/specs/execd-api.yaml@@ -333,6 +333,10 @@ paths:Executes a shell command in an existing bash session and streams the output in real-time via SSE(Server-Sent Events). The session must have been created by create_session. Supportsoptional working directory override and timeout (milliseconds).+ The run streams a single merged `stdout` event stream (session stderr is merged into it).+ Stdout event text preserves the original line endings (`\n`, `\r`, or `\r\n`). Concatenate+ text from the stdout events to recover the run's output; blank lines appear as events+ containing only the line ending, and the final event may be an unterminated fragment.operationId: runInSessiontags:- Commanddiff --git a/tests/python/tests/test_sandbox_e2e.py b/tests/python/tests/test_sandbox_e2e.pyindex 334bb9c7e..08ed81341 100644--- a/tests/python/tests/test_sandbox_e2e.py+++ b/tests/python/tests/test_sandbox_e2e.py@@ -1351,6 +1351,14 @@ class TestSandboxE2E:assert fail.complete is Nonelogger.info("✓ run_in_session failure propagated exit_code=7")+ logger.info("Step 3d: Session stdout events preserve line endings (incl. blank lines)")+ out_lines = await sandbox.commands.run_in_session(sid, "printf 'a\\n\\nb\\n'")+ assert out_lines.error is None+ assert out_lines.exit_code == 0+ joined = "".join(m.text for m in out_lines.logs.stdout)+ assert joined == "a\n\nb\n", f"session stdout should reconstruct exactly, got: {joined!r}"+ logger.info("✓ session stdout line endings preserved: %r", joined)+logger.info("Step 4: New session with working_directory=/var — verify create_session working directory again")sid2 = await sandbox.commands.create_session(working_directory="/var")assert sid2 is not Nonediff --git a/tests/python/tests/test_sandbox_e2e_sync.py b/tests/python/tests/test_sandbox_e2e_sync.pyindex 63812b5b4..3e956b151 100644--- a/tests/python/tests/test_sandbox_e2e_sync.py+++ b/tests/python/tests/test_sandbox_e2e_sync.py@@ -1075,6 +1075,14 @@ class TestSandboxE2ESync:assert fail.complete is Nonelogger.info("✓ run_in_session failure propagated exit_code=7")+ logger.info("Step 3d: Session stdout events preserve line endings (incl. blank lines)")+ out_lines = sandbox.commands.run_in_session(sid, "printf 'a\\n\\nb\\n'")+ assert out_lines.error is None+ assert out_lines.exit_code == 0+ joined = "".join(m.text for m in out_lines.logs.stdout)+ assert joined == "a\n\nb\n", f"session stdout should reconstruct exactly, got: {joined!r}"+ logger.info("✓ session stdout line endings preserved: %r", joined)+logger.info("Step 4: New session with working_directory=/var — verify create_session working directory again")sid2 = sandbox.commands.create_session(working_directory="/var")assert sid2 is not None