Documentation
¶
Overview ¶
Package session implements sandbox.Session — a stateful execution context in which successive Exec calls share working directory and environment — once, for ANY sandbox.Sandbox backend. The docker and local backends both construct one of these (differing only in the state-dir path), so the stateful-shell logic lives in exactly one place.
The mechanism (see ../../docs/specs/SESSION.md for the decided design): the underlying Exec is stateless — a fresh process at the default cwd with the base env every call. To carry cwd + env across calls WITHOUT a long-lived shell process (that is the ProcessHost slice, deliberately deferred), each shell command is wrapped:
restore source a per-session env file; cd to the saved cwd run eval the model's command IN this shell (so its cd/export take effect) capture write the new cwd and `export -p` back to the state file
The state file lives in a writable, container-lifetime directory the backend chooses (the docker /tmp tmpfs; the host temp dir for local). Only shell `-c` commands are wrapped — a raw process (rg, git) can't mutate session state, so it passes straight through.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is a stateful view over an underlying Sandbox. It is NOT safe for concurrent Exec calls (the agent loop is sequential); two independent Sessions over the same backend are isolated by their distinct state dirs.
func New ¶
New returns a Session that drives sb's Exec, persisting shell state under stateDir. stateDir must be a writable path that survives across Exec calls for the backend (e.g. the docker container's /tmp tmpfs); the backend owns choosing it and making it unique per Session. The dir is created lazily on first Exec.
func (*Session) Close ¶
Close removes the session's state files. Best-effort: the backend tears the whole container (and its /tmp) down on its own Close, so a failure here only leaks a few bytes for the rest of the run, not across runs.
func (*Session) Exec ¶
Exec runs cmd with the session's accumulated cwd + env. A shell `-c` command is wrapped so its `cd`/`export` persist to the next call; anything else passes through to the backend unchanged (a single process carries no session state). The contract otherwise matches sandbox.Exec exactly (non-zero exit is a Result, not an error).
Source Files