session

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

• type Session
  • func New(sb sandbox.Sandbox, stateDir string) *Session
  • func (s *Session) Close() error
  • func (s *Session) Exec(ctx context.Context, cmd sandbox.Command) (*sandbox.Result, error)

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

func New(sb sandbox.Sandbox, stateDir string) *Session

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

func (s *Session) Close() error

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

func (s *Session) Exec(ctx context.Context, cmd sandbox.Command) (*sandbox.Result, error)

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).