sandbox

type BulkWrite struct {
	// Manifest names the file listing `tmp\0target\0` for every member, and
	// DirList the deduplicated parent directories. Both land in the workdir,
	// which exists, and both are the archive's first entries — so a delivery that
	// fails on a later one has still landed what the recovery pass needs. The
	// rename script removes them.
	Manifest string
	DirList  string
	// contains filtered or unexported fields
}

type ExecRequest struct {
	Command string
	Timeout time.Duration
}

type ExecResult struct {
	Stdout    string
	Stderr    string
	ExitCode  int
	TimedOut  bool
	Truncated bool
}

type FileWrite struct {
	Path string
	Data []byte
}

type GateSpec struct {
	Image           string // the gate container image (built with `docker build --target gate`)
	ControlplaneURL string // the gate fetches its per-session config from here
	// TokenMinter mints the gate's per-session token in two steps — generated in
	// memory before the create, persisted only once this provider has won it, so
	// an adoption never revokes the token a running gate is using (the full
	// argument is on GateTokenMinter). It must be non-nil wherever a GateSpec is:
	// both backends call it unconditionally on the create path.
	TokenMinter GateTokenMinter
	// OTelEndpoint and OTelInsecure carry the deployment's OTLP collector config
	// into the gate container so its egress_request spans export to the same
	// collector as the rest of the platform (observability is built in, not bolted
	// on). The gate is a separate process that does not inherit the executor's
	// environment, so its telemetry endpoint must be handed to it explicitly. Empty
	// OTelEndpoint means no collector configured — the gate runs without an
	// exporter, exactly as the executor does with an empty endpoint.
	OTelEndpoint string
	OTelInsecure bool
}

type GateTokenMinter interface {
	// Generate returns a fresh gate token in memory, with no durable effect.
	Generate() string
	// Persist records token as sessionID's live gate token (by hash). The provider
	// calls it only after creating the gate container with that token.
	Persist(ctx context.Context, sessionID domain.ID, token string) error
}

type GateTokenRevoker interface {
	Revoke(ctx context.Context, sessionID domain.ID) error
}

type Hardening struct {
	// PidsLimit caps the processes the sandbox may have alive at once. It is
	// the containment for a fork bomb and for the process pressure that would
	// stall the daemon probe the exec deadline uses to label an overrun. 0
	// leaves the runtime's default (unbounded).
	PidsLimit int64
	// CPUMillis caps CPU in thousandths of a core (2000 = two CPUs). A quota,
	// not a reservation: a backend that would otherwise turn a limit into a
	// scheduling reservation keeps the request small. 0 leaves it unbounded.
	CPUMillis int64
	// MemoryBytes caps the sandbox's memory. 0 leaves it unbounded — the
	// platform default, because an OOM kill in the middle of a task is a worse
	// failure than the throttling a CPU quota causes.
	MemoryBytes int64
	// EphemeralStorageBytes caps the sandbox's node-local disk — the container's
	// writable layer and every emptyDir the platform mounts over it. 0 leaves it
	// unbounded, the platform default.
	//
	// Kubernetes-only, the mirror image of PidsLimit: Docker's writable-layer
	// quota is only as good as the daemon's storage driver — some enforce it,
	// some refuse the option, and at least one accepts it and enforces nothing —
	// so that backend ignores this and says so once. The asymmetry is recorded
	// in docs/DIVERGENCES.md rather than faked.
	//
	// Its enforcement is unlike every other cap here, which is why it is opt-in
	// as MemoryBytes above is — a sharper version of that field's reason:
	// exceeding a memory limit kills the offending container, exceeding a CPU
	// limit throttles it, but exceeding this gets the whole pod **evicted** by
	// the kubelet. On this provider that surfaces mid-tool-call as a sandbox
	// that no longer exists. The limit makes the victim of node disk pressure
	// targeted and attributable instead of arbitrary; it does not make eviction
	// gentle.
	//
	// And it binds only where the kubelet can measure local ephemeral storage —
	// the node layouts Kubernetes supports for it. On any other layout the pod
	// takes the field and is never evicted for exceeding it, so this is a cap
	// whose effect is a property of the cluster's nodes as much as of the value.
	EphemeralStorageBytes int64
	// CapDrop names the Linux capabilities to drop, without the CAP_ prefix
	// ("NET_RAW"), or the single entry "ALL". Empty drops none. A gated
	// sandbox always drops NET_RAW/SETUID/SETGID on top of whatever this says:
	// those are what keep a tool from forging the gate's egress identity, so
	// they are not configurable away.
	CapDrop []string
	// ReadOnlyRootfs mounts the container's root filesystem read-only. The
	// provider mounts writable space over every path the platform itself writes
	// (WritablePaths) when it is set, so this is a provision-time choice rather
	// than a runtime-layer one — but it still needs an image that tolerates a
	// read-only root everywhere else. A session file resource created since #323
	// always resolves under the uploads root and so is covered; one stored before
	// it can still name a path outside the set and fail to materialize.
	ReadOnlyRootfs bool
	// RunAsUser overrides the image's default user with a numeric uid; nil
	// keeps the image's own USER. Numeric because that is what both backends
	// can express (a Kubernetes securityContext takes no user name).
	//
	// It does not make an image non-root-ready. ReadOnlyRootfs alongside it
	// makes the writable paths *exist* under a uid that could not create them
	// — which is what keeps the container's `mkdir -p <workdir>` entrypoint
	// alive — but only Kubernetes makes them *writable* by that uid (the
	// kubelet creates an emptyDir world-writable). On Docker a fresh anonymous
	// volume is root-owned 0755 unless the image ships the directory, so there
	// the image still decides. Shipping an image whose own USER is the uid
	// remains the reliable route; see docs/self-hosted-security.md §2.
	//
	// The one value both backends refuse is gaterun.DefaultGateUID for a gated
	// sandbox: a tool running as the gate's uid matches its owner-ACCEPT rule
	// and leaves the namespace unfiltered. Validate enforces it.
	RunAsUser *int64
}

type PathNotWritableError struct {
	Path   string
	Reason string
}

type Provider interface {
	// Provision returns the session's sandbox, creating it only if none is
	// running. Concurrent executors provisioning the same session converge on
	// one sandbox rather than racing to create two.
	Provision(ctx context.Context, spec Spec) (Sandbox, error)
	// Attach returns a handle to the session's sandbox when this endpoint is
	// already running one, and ErrNotFound when it is not. It is Provision's
	// read-only half: it creates nothing, starts nothing, replaces nothing and
	// restores nothing, so a caller that wants the sandbox a session has —
	// rather than the sandbox it is about to use — cannot heal, reclaim or
	// rebuild one as a side effect. A sandbox that exists but is not running is
	// ErrNotFound: "running" is what a handle can be used against, and starting
	// it would be the healing this is here to avoid. A container or pod holding
	// the session's name without its ownership label is an error, not a miss —
	// the same refusal every adoption path makes.
	Attach(ctx context.Context, sessionID domain.ID) (Sandbox, error)
	// Owned lists the distinct session ids of every sandbox asset — sandbox
	// containers/pods and gate containers, running or stopped — this endpoint
	// currently holds, read from the ownership label. Endpoint-local by
	// design: each executor sees only its own daemon or namespace, which is
	// what shards the reaper across executors with no coordination (plan 24).
	Owned(ctx context.Context) ([]domain.ID, error)
	// Reap destroys everything the endpoint owns for the session — sandbox,
	// gate, anonymous volumes — revoking the session's gate token first when
	// the provider was built with a revoker (#197: a token must not outlive
	// its gate). It needs no live handle, waits out asynchronous deletion so
	// the assets are gone — at the orchestrator's level — when it returns: a
	// terminating pod or an in-progress removal is waited on, never reported
	// as success or as failure. The bound is the same one Destroy already
	// has: on K8s "gone" is the API object (a partitioned node's kubelet may
	// lag the force delete). Idempotent: reaping a session that owns nothing
	// is a no-op.
	Reap(ctx context.Context, sessionID domain.ID) error
	// Export streams one directory root out of the session's sandbox as an
	// uncompressed tar whose members all live under a single top-level
	// directory named after the root's base name (Docker's archive endpoint
	// shapes it so; the K8s backend matches it) — the checkpoint engine
	// strips that prefix and re-roots members itself (plan 24). It needs no
	// live handle; on Docker it works on a stopped container, on K8s the pod
	// must be running (a sandbox that cannot be read surfaces its error, and
	// the caller degrades to reap-without-checkpoint). A root that does not
	// exist answers ErrFileNotExist — a session that never used a root is
	// normal, not an error; a sandbox that does not exist answers
	// ErrNotFound. The caller owns the stream and must close it; a transfer
	// that dies mid-stream surfaces on Read, not here.
	Export(ctx context.Context, sessionID domain.ID, root string) (io.ReadCloser, error)
}

type Sandbox interface {
	// ID identifies the sandbox to the backend (a container id, a pod name).
	ID() string
	// Exec runs one command to completion and reports what it did (ExecRequest,
	// ExecResult). A command that fails is not an error here: a non-zero exit,
	// output on stderr, and a command killed at its deadline are all a finished
	// ExecResult, because each is something the model reads and answers. The
	// error return is the sandbox failing the caller instead — gone
	// (ErrNotFound), unreachable, the context cancelled — which the toolset
	// carries up as a backend fault rather than folding into a tool result.
	Exec(ctx context.Context, req ExecRequest) (ExecResult, error)
	// ReadFile returns a file's bytes verbatim, binary included.
	ReadFile(ctx context.Context, path string) ([]byte, error)
	// ReadFileStream returns a regular file's bytes as a stream together with
	// their exact count, refusing a file larger than maxBytes with
	// ErrFileTooLarge and answering the same path sentinels as ReadFile. The
	// caller closes the reader.
	//
	// It exists for reads above the fixed ReadFile cap — the deliverables
	// harvest moves files up to its own per-file cap out of the sandbox — so
	// the ceiling is the caller's to name per read. The docker backend
	// streams the bytes through; the k8s backend buffers up to maxBytes
	// internally, because its exec transport frames stdout with a trailing
	// marker that can only be verified once the stream has ended.
	ReadFileStream(ctx context.Context, path string, maxBytes int64) (io.ReadCloser, int64, error)
	// WriteFile writes data, creating parent directories and overwriting any
	// existing file.
	//
	// The write is atomic: the bytes land under a temporary name in the target's
	// own directory (TempName) and are renamed into place, so a transfer that
	// fails part way through leaves the target holding what it held before — or
	// nothing, where there was nothing — never a truncated file. The path itself
	// is answered rather than the sandbox blamed: a path blocked by a
	// non-directory is ErrNotDirectory, a target that is a directory is
	// ErrIsDirectory (the directory is left intact, never replaced), and a
	// target a rename cannot replace — a device node, or a file bind-mounted
	// into the sandbox — is ErrNotReplaceable (the node or mount is left what
	// it was, neither supplanted nor written through; #205).
	//
	// Being a rename, it replaces the *name*, and four consequences follow that a
	// write-through would not have had:
	//   - A symlink at the target is supplanted by a regular file; what it pointed
	//     at is untouched. A symlink to a *directory* is a directory here, as it is
	//     to every other question asked of a path, and is refused as one.
	//   - The parent directory must be writable, even where the target itself
	//     already is.
	//   - The target's permission bits would go with the name, so they are put
	//     back first: the temporary file is chmod'd to the target's mode before the
	//     move, and a script made executable in bash survives being rewritten
	//     (#204). Only an existing *regular* target has bits worth carrying: one
	//     that does not exist lands 0644 on either backend, fixed by the platform
	//     rather than by the image (a tar header on docker; on k8s a `umask 022`
	//     the write script sets — #212 — and a `chmod 0644` beside it, because a
	//     parent directory's default POSIX ACL decides those bits over the umask,
	//     #213), and a symlink or FIFO lands 0644 too — what the rename
	//     replaces is the name, and a link's own mode is 0777.
	//     One case still differs between the backends: docker's temporary
	//     file is extracted by the daemon, so an image whose default user is not
	//     root cannot chmod it and the write lands 0644 where k8s preserves the
	//     mode (#209). (The Claude Code harness's atomic write does the same three
	//     steps — a harness-design observation, not a wire behavior of the
	//     managed-agents reference; the SDK's host-side agenttoolset writes a fixed
	//     0644 instead.)
	//   - A file bind-mounted into the sandbox cannot be renamed onto at all, and
	//     a device node could only be *supplanted*, never written through — so
	//     both are refused with ErrNotReplaceable before the move, identically on
	//     both backends, by the shared __map_unreplaceable probe (#205). A write
	//     to a bind-mounted file fails where the pre-#71 k8s backend used to
	//     write through it; the model is told why, and bash redirection still
	//     reaches it.
	WriteFile(ctx context.Context, path string, data []byte) error
	// WriteFileStream writes exactly size bytes read from src to path, creating
	// parent directories and overwriting any existing file, atomically and with
	// the same path sentinels as WriteFile. Unlike WriteFile it never buffers the
	// whole payload in the caller, so a large mounted file (up to the Files API's
	// 500 MB cap) streams straight through from object storage. size must equal
	// the number of bytes src yields: a short or long stream is an error, not a
	// silently truncated file. It must also be a length — a caller holding an
	// unknown count (a download with no Content-Length reads as -1) has to
	// measure the bytes before calling, because a negative size is refused
	// rather than read as "however many arrive" (#386). That refusal is
	// CheckWriteSize, taken before the target's directory is created and before
	// any byte is carried to the sandbox, so it costs nothing and leaves
	// nothing — not a stray parent directory, and not a 500 MB body pushed into
	// a container that was always going to reject it.
	WriteFileStream(ctx context.Context, path string, src io.Reader, size int64) error
	// WriteFiles writes a whole set of files, each exactly as WriteFile writes
	// one — creating parent directories, overwriting, landing under a temporary
	// name in the target's own directory and renaming into place, carrying an
	// existing target's mode over, and answering the same path sentinels — save
	// ErrNotReplaceable, which only the single writes answer: the bulk path
	// carries no unreplaceable probe, deliberately, because its one caller
	// (skill materialization) writes under the workdir, where a bind-mounted or
	// device target does not arise (#205). An empty batch writes nothing. A member's Path must be absolute and clean; a
	// batch naming the same target twice lands them in order, so the last wins.
	//
	// What it buys is round trips: the whole batch travels as an archive and costs
	// a fixed couple of execs — one on the k8s backend, two on docker — where the
	// same files written one at a time cost one exec each, about 14ms apiece
	// against a local daemon, which is most of what a small write costs (#206). A
	// skill of ten thousand files is the case that made it worth a method.
	//
	// The batch is NOT a transaction, and deliberately not: the first failure
	// stops the run, the members that already landed stay landed, and the rest
	// are never written. That is what a loop of WriteFile calls did, and the one
	// caller of either — materializing a skill — re-runs the whole skill next
	// time rather than reasoning about what got through. Every member is still
	// atomic on its own, so a failure leaves each target holding what it held,
	// never a truncated file. The single exception is a delivery that arrived
	// short, which lands nothing at all: every member is checked to be present
	// before any of them is moved.
	//
	// A batch that reached the sandbox and failed there sheds its temporary
	// files. One whose exec could not be run, or whose shell was killed before it
	// could clean up, leaves what it had delivered — as a single write in the
	// same position already does, at one file rather than N.
	//
	// The error names the member it stopped on, with two honest limits. Where
	// more than one member would have failed it names one of them, and a path
	// blocked by a non-directory is preferred over the delivery's own failure
	// because it is the one a caller can act on. And the naming rides a marker on
	// the sandbox's stderr, which the sandbox can flood or forge: it is a
	// diagnostic, not a guarantee, and it degrades to naming no member rather
	// than the wrong one where the marker is unusable. The error's *class* — the
	// sentinels below — does not depend on it.
	WriteFiles(ctx context.Context, files []FileWrite) error
	// Destroy removes the sandbox. It is idempotent: destroying an already
	// destroyed sandbox is not an error.
	Destroy(ctx context.Context) error
}

type Spec struct {
	// SessionID is the sandbox's whole identity: both backends derive the
	// container or pod name from it, which is why no sandbox id is ever
	// persisted and any executor can find a session's sandbox again from the
	// session alone. Provision refuses a zero id.
	SessionID domain.ID
	// Image is what the sandbox is created from; Provision refuses an empty
	// one. It and Workdir are what every adoption compares, joined by
	// Networking only when the sandbox has no gate — a gated one's egress path
	// is already pinned by the pairing, so both backends skip that leg. What
	// selects this set is not that it is fixed at create (Env and Hardening are
	// too, and are deliberately adopted as created) but what a mismatch would
	// mean: a different image or workdir is a different sandbox rather than
	// this one found again, and a different network mode is a route out the
	// session never asked for. A mismatch is refused with ErrSpecMismatch
	// rather than served as if it matched — the one path that refuses for a
	// different reason being a gated K8s pod that never turns ready, whose
	// readiness error and reclaim deliberately precede the comparison so a pod
	// both wedged and mismatched is removed rather than stranded (k8s.go).
	Image string
	// Workdir is where commands run and where the toolset's relative paths
	// resolve. Empty means DefaultWorkdir, resolved by the provider before the
	// adoption comparison, so an empty spec and an explicit "/workspace" are
	// the same sandbox rather than a mismatch.
	Workdir string
	// Networking is the session's egress policy. What a backend does with it
	// depends on Gate: with a gate the gate enforces it and the backend leaves
	// the sandbox's own networking to the pairing, without one the backend
	// applies its own fail-closed containment (Docker's NetworkMode, the K8s
	// route-flush init container) — which is what the adoption compares in that
	// ungated case, each backend reading back its own expression of it.
	Networking domain.Networking
	// Env is injected at provision time and visible to every tool exec (nil =
	// none). What the executor puts here is the vault env-var placeholders and
	// only those (sandboxEnv, internal/executor) — the egress-proxy variables
	// are the gate's, injected by whichever backend runs it and reserved
	// against callers below, so a sandbox's secrets and its route out arrive by
	// different doors. Both backends thread Env in the same way, so the
	// behavior is identical across Docker and Kubernetes.
	//
	// Keys must be valid environment-variable names (ValidateEnv); an invalid
	// key fails provisioning on both backends rather than diverging (Docker
	// would fold a '=' into the value, Kubernetes would reject the pod). Values
	// are unconstrained opaque strings.
	//
	// That check is the grammar and nothing else. A name the platform reserves
	// passes it — PATH, the loader and shell hooks, the proxy variables the
	// sandbox's route to its gate depends on (ReservedEnvName) — because being
	// reserved is not a grammar rule and the platform's own trusted injections
	// go through the same check. A caller filling Env from an untrusted source
	// (a vault credential's secret_name is the one that exists) therefore drops
	// those keys itself rather than letting them reach ValidateEnv: a rejected
	// map fails the whole provision, so one bad credential would reclaim-loop
	// the session.
	//
	// Env is bound when the sandbox is first created. Provision is idempotent
	// and adopts a session's existing sandbox without re-applying a changed Env
	// — fixed at create, as Networking is, though the two part ways on a
	// mismatch: a changed Networking is refused at adoption (ErrSpecMismatch,
	// #29/#296) where a changed Env is silently kept. A caller
	// that re-provisions a session must therefore keep its Env stable; the
	// egress gate relies on this by minting stable per-session placeholders and
	// resolving their live values at egress rather than re-injecting them.
	Env map[string]string
	// Hardening is the containment the provider applies when it creates the
	// sandbox — cgroup limits, capability drops, a non-root uid, a read-only
	// root filesystem. The zero value applies none of it, which is what a
	// provider did before the field existed; the platform's own defaults are
	// resolved by HardeningFromEnv in the binaries that provision sandboxes.
	// Like Env it is bound at create and not re-applied to an adopted sandbox.
	// See Hardening for what each backend can express.
	Hardening Hardening
	// Gate, when non-nil, tells the provider to run a per-session egress gate
	// sidecar: a gate container (Gate.Image, on the deploy network, holding
	// CAP_NET_ADMIN) that owns the network namespace and installs owner-match
	// iptables, with the sandbox joining that namespace and reaching the network
	// only through the gate's loopback proxy (the provider points the sandbox's
	// HTTP_PROXY there — a deployment detail it owns, not the caller's env). nil =
	// the sandbox networks directly (unrestricted, no vault
	// credentials). The executor sets it for sessions that are `limited` or
	// vault-attached; both backends consume it — Docker as a gate-pair the
	// sandbox joins, K8s as a native sidecar in the sandbox's pod.
	Gate *GateSpec
	// GateTokenRevoker revokes the session's persisted gate token when a
	// provision dismantles its gate without replacing it — the gated→ungated
	// reshape, the one transition where no re-mint (whose revoke-on-re-mint
	// covers every other path) will ever run, so the token would otherwise
	// stay live until the session archives. It cannot live on GateSpec the way
	// TokenMinter does: the provision that needs it is precisely the one with
	// Gate == nil. The executor sets it on every spec (the transition is only
	// discoverable inside the provider, which inspects the previous shape);
	// nil skips revocation.
	GateTokenRevoker GateTokenRevoker
}