session-execution
Use when working on or reviewing session execution, command handling, shell state, FIFO-based streaming, or stdout/stderr separation. Relevant for session.ts, command handlers, exec/execStream, or anything involving shell process management. (project)
How do I install this agent skill?
npx skills add https://github.com/cloudflare/sandbox-sdk --skill session-executionIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides technical documentation and architectural guidelines for developers working on shell process management and session execution within a sandbox. It describes standard engineering practices for stream multiplexing and concurrency control, and no security issues were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
1/1 file flagged
What does this agent skill do?
Session Execution
Read docs/SESSION_EXECUTION.md before working in this area. It explains the architecture for reliable command execution with stdout/stderr separation.
Key Concepts
Two execution modes:
- Foreground (exec): Runs in main shell, state persists. Uses temp files for output capture.
- Background (execStream/startProcess): Runs in subshell via FIFOs. Labelers prefix output in background.
Binary prefix contract:
- Stdout:
\x01\x01\x01prefix per line - Stderr:
\x02\x02\x02prefix per line - Log parser reconstructs streams from these prefixes
Completion signaling:
- Exit code written to
<id>.exitfile via atomictmp+mv - Hybrid fs.watch + polling detects completion (robust on tmpfs/overlayfs)
- Background mode uses
labelers.donemarker to ensure output is fully captured
When Developing
- Understand why foreground uses temp files (bash waits for redirects to complete)
- Understand why background uses FIFOs (concurrent streaming without blocking shell)
- Test silent commands (cd, variable assignment) - these historically caused hangs
- Test large output - buffering issues can cause incomplete logs
When Reviewing
Correctness checks:
- Verify exit code handling is atomic (write to .tmp then mv)
- Check FIFO cleanup in error paths
- Ensure labelers.done is awaited before reading final output (background mode)
Race condition analysis:
Session execution has a mutex that serializes command execution per session. Before flagging race conditions:
- Check if operations happen within the same session (mutex protects)
- Check if operations are per-session vs cross-session (cross-session races are real)
- Refer to
docs/CONCURRENCY.mdfor the full concurrency model
Common false positives:
- "Concurrent reads/writes to session state" - mutex serializes these
- "FIFO operations might race" - labelers are per-command, not shared
Actual concerns to watch for:
- Cross-session operations without proper isolation
- Cleanup operations that might affect still-running commands
- File operations outside the mutex-protected section
Key Files
packages/sandbox-container/src/session.ts- Session class with exec/execStreampackages/sandbox-container/src/managers/SessionManager.ts- Mutex and lifecyclepackages/sandbox/src/clients/CommandClient.ts- SDK interface to session commands
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/cloudflare/sandbox-sdk/session-execution">View session-execution on skillZs</a>