Skip to content

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.go
index 2f049d276..87204a934 100644
--- a/components/execd/pkg/runtime/bash_session.go
+++ b/components/execd/pkg/runtime/bash_session.go
@@ -18,10 +18,10 @@
package runtime
import (
- "bufio"
"context"
"errors"
"fmt"
+ "io"
"os"
"os/exec"
"sort"
@@ -290,41 +290,74 @@ func (s *bashSession) run(ctx context.Context, request *ExecuteCodeRequest) erro
stopGroupKill := killProcessGroupOnDone(ctx, cmd.Process.Pid)
defer stopGroupKill()
- scanner := bufio.NewScanner(stdoutR)
- scanner.Buffer(make([]byte, 0, 64*1024), 16*1024*1024)
-
var (
envLines []string
pwdLine string
exitCode *int
inEnv 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) erro
return 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.go
index 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.md
index 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 execution
diff --git a/sdks/sandbox/javascript/src/api/execd.ts b/sdks/sandbox/javascript/src/api/execd.ts
index 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.py
index 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. 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.
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. 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.
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. 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.
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. 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.
Args:
session_id (str):
diff --git a/specs/execd-api.yaml b/specs/execd-api.yaml
index 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. 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.
operationId: runInSession
tags:
- Command
diff --git a/tests/python/tests/test_sandbox_e2e.py b/tests/python/tests/test_sandbox_e2e.py
index 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 None
logger.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 None
diff --git a/tests/python/tests/test_sandbox_e2e_sync.py b/tests/python/tests/test_sandbox_e2e_sync.py
index 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 None
logger.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