shellsession

type Chunk struct {
	Offset int64
	Data   string
	Reset  bool
}

type Config struct {
	// CwdResolver returns the workspace root a new shell should be rooted at,
	// given the tool/request context (which carries the session id). Required.
	CwdResolver func(ctx context.Context) string
	// Workspace is the operator's workspace-root allowlist, enforced against
	// whatever CwdResolver returns; the only source of the default root.
	// Nil means no allowlist, and an absolute cwd is taken as given.
	Workspace *vfs.Factory
	// Shell overrides the shell executable; empty picks a platform default.
	Shell string
	// ScrollbackBytes bounds retained output per shell (default 64 KiB).
	ScrollbackBytes int
	// IdleTimeout kills inactive shells (default 15m; <=0 disables reaping).
	IdleTimeout time.Duration
	// ScrubEnv, when set, maps the parent environment to the one a spawned
	// shell inherits, so serve's own secrets never reach an agent-reachable
	// PTY. Nil inherits the full environment.
	ScrubEnv func([]string) []string
	// Interactive spawns shells for a HUMAN at a real terminal: ECHO stays on
	// and the shell draws its own prompt, because the operator must see what
	// they type. The default (false) is the agent-facing posture — echo off,
	// prompt suppressed — where output is scrollback for a model to read and a
	// prompt is noise plus a login/host/cwd leak.
	Interactive bool
	// OnExit, when set, is invoked once per shell when it terminates, from a
	// dedicated goroutine. Fires for every cause — process exit, Kill, idle
	// reap, Shutdown — so a client can report the terminal as gone exactly
	// once. Total: never called twice for the same shell.
	OnExit func(sessionID string)
}

type Manager interface {
	// Run ensures a shell exists for sessionID (rooted via the cwd resolver
	// against ctx) and submits one line to it. ctx is used only for cwd
	// resolution at creation time.
	Run(ctx context.Context, sessionID, line string) (RunResult, error)
	// Open ensures a shell exists for sessionID without submitting anything,
	// so an interactive client can attach before the first keystroke.
	// Idempotent: an already-live shell is returned as-is.
	Open(ctx context.Context, sessionID string) error
	// Write feeds raw bytes to sessionID's shell stdin VERBATIM — unlike Run
	// it appends no newline and imposes no line discipline, because the bytes
	// are a human's keystrokes (arrow keys, ^C, partial lines). Never creates
	// a shell: an unknown session is ErrNoSession.
	Write(sessionID string, data []byte) error
	// Read returns scrollback for sessionID: bytes since `since` when since >= 0,
	// otherwise the last `tailBytes`. Never creates a shell.
	Read(sessionID string, since int64, tailBytes int) ReadResult
	// Resize records the terminal geometry for sessionID and applies it to
	// the live shell when there is one. Total: an unknown session, a reaped
	// shell, or a non-positive dimension are no-ops, not errors. The size is
	// remembered even with no live shell, so the next one is born at it.
	Resize(sessionID string, rows, cols int)
	// Subscribe registers fn for live output of sessionID, invoked from a
	// dedicated goroutine so a slow consumer cannot stall the PTY. The
	// current scrollback is delivered immediately as a Reset chunk.
	Subscribe(sessionID string, fn func(Chunk)) (cancel func())
	// Kill terminates and forgets sessionID's shell (session close/delete).
	Kill(sessionID string)
	// Shutdown kills every shell and stops the reaper.
	Shutdown()
}

type ReadResult struct {
	Content    string
	FromOffset int64
	NextOffset int64
	Exists     bool
}

type ReadResultJSON struct {
	Content    string `json:"content"`
	FromOffset int64  `json:"from_offset"`
	NextOffset int64  `json:"next_offset"`
	Exists     bool   `json:"exists"`
	Note       string `json:"note,omitempty"`
}

type RunResult struct {
	Offset   int64
	Snapshot string
	Started  bool // a new shell was created for this run
}

type RunResultJSON struct {
	Offset  int64  `json:"offset"`
	Output  string `json:"output"`
	Started bool   `json:"started_new_shell,omitempty"`
	Note    string `json:"note,omitempty"`
}