sandbox

type AccessKind string

type ApprovalRequiredError struct {
	Reason string
}

type ApprovalScope string

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

type Context struct {
	WorkingDirectory string
	WorkspaceRoot    string
	AdditionalRoots  []string
	Environment      EnvironmentKind
	SandboxEnabled   bool
}

type Decision string

type DecisionResult struct {
	Decision Decision
	Reason   string
}

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

type DockerExecutorConfig struct {
	// BaseImage is the OCI image used for new environments.
	// Default: "ubuntu:24.04"
	BaseImage string

	// SetupCommands are shell commands run once when an environment's
	// container is first created.
	// Example: ["apt-get update -y", "apt-get install -y python3 nodejs"]
	SetupCommands []string

	// WorkDir is the working directory inside the container that
	// RunRequest.WorkDir (a host path) is bind-mounted to.
	// Default: "/workdir"
	WorkDir string

	// Env is a set of KEY=VALUE pairs always injected into the container.
	Env map[string]string

	// NetworkAccess controls whether the container can reach the network.
	// Default: true (default Docker bridge network).
	// Set to false to run with --network=none.
	NetworkAccess bool

	// MemoryLimitMB caps container memory (docker run --memory).
	// Default: 2048 (2 GiB). 0 means no additional default is applied
	// (Docker's own daemon-level default, if any, still applies).
	MemoryLimitMB int

	// CPULimit caps container CPU (docker run --cpus). Fractional values
	// are allowed (e.g. 1.5). Default: 2.0. 0 means no limit is passed.
	CPULimit float64

	// DockerBinary is the path to the docker CLI. Default: "docker"
	// (resolved via PATH).
	DockerBinary string

	// Runtime selects a non-default OCI runtime (docker run --runtime=…),
	// e.g. "runsc" for gVisor. Empty (default) uses Docker's own default
	// runtime — plain runc, which shares the host kernel with the
	// container. A stronger isolation runtime like gVisor must already be
	// installed and registered with the Docker daemon separately (this is
	// an operator/host setup step, not something DockerExecutor can do) —
	// if Runtime is set but not registered, Healthy(ctx) fails rather than
	// silently falling back to running without it, so an explicit request
	// for stronger isolation never gets silently downgraded.
	Runtime string

	// PublishPorts lists container ports to publish to random host ports
	// when an environment's container is created (docker run -p). Useful
	// for e.g. previewing a dev server an agent starts inside the sandbox.
	// Fixed for the lifetime of an environment — declared here rather than
	// per RunRequest because Docker only allows publishing ports at
	// container-creation time. The actual host-side ports are reported back
	// via RunResult.Endpoints on every call to that environment.
	PublishPorts []int

	// TrackFileChanges enables git-tracked snapshots of RunRequest.WorkDir
	// (the host directory bind-mounted into the environment) after every
	// Run call that actually changed something. Default: false — this is an
	// audit/undo convenience feature, not a security property, and requires
	// git on the HOST (not inside the container). If true and git isn't
	// found on the host, Healthy(ctx) fails rather than silently tracking
	// nothing — same "don't silently downgrade a requested capability"
	// contract as Runtime.
	//
	// Snapshots go into a separate, bare git repository — NOT the
	// project's own .git, if it has one — keyed by a hash of the absolute
	// WorkDir path (stable across environment/container restarts for the
	// same directory, see HistoryDir). The project's own .git, if present,
	// is excluded from what gets snapshotted.
	TrackFileChanges bool

	// HistoryDir is the base directory shadow tracking repos are stored
	// under when TrackFileChanges is true. Default (DefaultDockerConfig):
	// os.UserConfigDir()/seshat/sandbox-history.
	HistoryDir string

	// GitBinary is the path to the git CLI used for TrackFileChanges.
	// Default: "git" (resolved via PATH).
	GitBinary string
}

type DockerRunOptions struct {
	// EnvironmentID selects a named, persistent environment (one long-lived
	// container reused across calls via `docker exec`). Empty means the
	// default session environment.
	//
	// Port publishing is NOT a per-call option here — Docker only allows
	// publishing ports at container-creation time, not on an already-running
	// container, and an environment's container may already exist by the
	// time a given RunRequest is issued. See
	// DockerExecutorConfig.PublishPorts, which is declared once for the
	// environment instead.
	EnvironmentID string
}

type EnvironmentKind string

type Executor interface {
	// Run executes a command inside the sandbox and streams its output.
	// Implementations must respect ctx cancellation and RunRequest.Timeout.
	Run(ctx context.Context, req RunRequest) (RunResult, error)

	// Kind identifies which backend this is.
	Kind() EnvironmentKind

	// Healthy returns nil when the executor is ready to accept work.
	// A non-nil error means the backend is unavailable (Dagger engine down,
	// Docker socket missing, etc). The engine calls this once at startup.
	Healthy(ctx context.Context) error
}

type ExecutorConfig struct {
	// Kind selects the backend. Defaults to EnvironmentLocal (noop).
	Kind EnvironmentKind

	// Docker holds Docker-specific configuration.
	// Only used when Kind == EnvironmentDocker.
	Docker DockerExecutorConfig
}

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

type NoopExecutor struct{}

type PathDecision struct {
	DecisionResult
	ResolvedPath string
}

type PermissionDecision struct {
	Decision      Decision
	Reason        string
	Scope         ApprovalScope
	ApprovedPaths []string
	Metadata      map[string]any
}

type PermissionDeniedError struct {
	Reason string
}

type PermissionRequest struct {
	ToolName       string
	Description    string
	Environment    EnvironmentKind
	Access         AccessKind
	Command        string
	Paths          []string
	NetworkTargets []string
	Justification  string
	Scope          ApprovalScope
	Metadata       map[string]any
}

type RunRequest struct {
	// Command is the shell command string to execute.
	// Passed as-is to the interpreter defined by Shell.
	Command string

	// Shell specifies the interpreter (default: /bin/sh -c).
	// Ignored by DockerExecutor which always uses sh inside the container.
	Shell []string

	// Env is a set of KEY=VALUE pairs injected into the command environment
	// on top of the executor's base environment.
	Env map[string]string

	// WorkDir is the host working directory for the command. NoopExecutor
	// and RemoteExecutor use it directly as the process's cwd. DockerExecutor
	// additionally treats it as the bind-mount source for the environment's
	// container-side working directory (see DockerExecutorConfig.WorkDir) —
	// fixed at the environment's first Run call and reused on every
	// subsequent call to the same Docker.EnvironmentID.
	WorkDir string

	// Stdin is connected to the command's standard input (may be nil).
	Stdin io.Reader

	// Timeout is the maximum duration for the command.
	// Zero means no timeout beyond the parent context deadline.
	Timeout time.Duration

	// Background requests a fire-and-forget execution (no output captured).
	// Used for long-running processes (servers, watchers).
	Background bool

	// Docker-specific extensions — ignored by NoopExecutor.
	Docker *DockerRunOptions
}

type RunResult struct {
	// Stdout and Stderr capture the command output.
	// Empty when Background=true.
	Stdout string
	Stderr string

	// ExitCode is the process exit code. Non-zero indicates failure.
	ExitCode int

	// Duration is the wall-clock time the command took.
	Duration time.Duration

	// Cwd is the working directory the command left the environment in.
	// Only populated by executors backed by a persistent shell (e.g.
	// RemoteExecutor) where a `cd` genuinely changes state for the next
	// command; empty for one-shot-per-call executors like NoopExecutor/
	// DockerExecutor where WorkDir never changes out from under the caller.
	Cwd string

	// Endpoints maps container port numbers to "host:port" strings — where
	// on the host a service listening on that container port is reachable.
	// Populated on every call by DockerExecutor when
	// DockerExecutorConfig.PublishPorts is non-empty (the mapping is fixed
	// at environment creation, so it's the same on every call for a given
	// environment, not something a specific RunRequest controls).
	Endpoints map[int]string
}

type ToolAccessPreview struct {
	ToolName       string   `json:"tool_name"`
	Environment    string   `json:"environment,omitempty"`
	Access         string   `json:"access,omitempty"`
	Command        string   `json:"command,omitempty"`
	Paths          []string `json:"paths,omitempty"`
	NetworkTargets []string `json:"network_targets,omitempty"`
	Justification  string   `json:"justification,omitempty"`
}

type ToolPermissionOptions struct {
	ToolInput              map[string]any
	ToolUseID              string
	SessionID              types.SessionID
	TurnID                 types.TurnID
	PermissionMode         types.PermissionMode
	WorkingDirectory       string
	IsToolRunningInSandbox bool
	Stage                  types.ToolPermissionStage
	Intent                 types.ToolPermissionIntent
	Metadata               map[string]any
}