sandbox

type DirEntry struct {
	Name  string
	IsDir bool
	Size  int64
}

type ExecOptions struct {
	Cwd     string
	Env     map[string]string
	Timeout time.Duration
}

type ExecResult struct {
	Stdout   string
	Stderr   string
	ExitCode int
}

type Factory interface {
	CreateSession(ctx context.Context, policy Policy) (Session, error)
	Supported(policy Policy) error
	Name() string
	Available() bool
}

type FilesystemPolicy struct {
	// WorkspaceRoot is the host path mounted as the sandbox root. When empty,
	// WorkingDir is used for backwards compatibility.
	WorkspaceRoot string

	// WorkingDir is the logical working directory inside the sandbox root.
	WorkingDir string

	// ExtraReadOnlyMounts is a list of host paths to mount read-only inside the
	// sandbox at their exact host path (same-path strategy). Used for skill dirs
	// that live outside the workspace root but must be accessible for script execution.
	ExtraReadOnlyMounts []string

	// TempDirHost is the host directory mounted as /tmp inside the sandbox.
	// Empty means the backend chooses a session-local temp directory. Non-empty
	// directories are guaranteed to exist with 0700 permissions before the
	// backend sees the policy; they may be shared across sessions.
	TempDirHost string
}

type Host = Session

type NetworkMode string

type NetworkPolicy struct {
	// Mode is the network access mode: disabled | allow_all.
	Mode NetworkMode

	// Timeout for network operations. Zero means no timeout.
	Timeout time.Duration
}

type Policy struct {
	// Filesystem policy
	Filesystem FilesystemPolicy

	// Network policy
	Network NetworkPolicy

	// Env holds environment variables injected into sandboxed processes.
	Env map[string]string

	// InheritEnv includes system environment variables when true.
	InheritEnv bool

	// Timeout for process execution. Zero means no timeout.
	Timeout time.Duration
}

type PolicyCompatibilityError struct {
	Backend string
	Policy  Policy
	Reason  string
}

type ProcessHandle interface {
	PID() int
	Wait(ctx context.Context) (ExecResult, error)
	Stdin() io.WriteCloser
	Stdout() io.ReadCloser
	Stderr() io.ReadCloser
	Close() error
}

type ProcessRequest struct {
	Path    string
	Args    []string
	Cwd     string
	Env     map[string]string
	Timeout time.Duration
}

type ResilientSession struct {
	// contains filtered or unexported fields
}

type Session interface {
	// Lifecycle
	Policy() Policy
	Close() error
	Alive() bool
	Done() <-chan struct{}

	// Host process surface
	Exec(ctx context.Context, command string, opts ExecOptions) (ExecResult, error)
	StartProcess(ctx context.Context, req ProcessRequest) (ProcessHandle, error)

	// Path resolution — use os.* with the resolved path for file I/O.
	// ResolvePath validates read access; use ResolveWritePath for write operations.
	ResolvePath(path string) (string, error)
	// ResolveWritePath is like ResolvePath but additionally rejects paths in
	// read-only mounts (e.g. ExtraReadOnlyMounts / skill directories).
	ResolveWritePath(path string) (string, error)
	WorkingDir() string
}

type SessionCreator func(ctx context.Context) (Session, error)