executor

type Config struct {
	Image        string
	Workdir      string
	LeaseTTL     time.Duration
	PollInterval time.Duration
	// StallTimeout bounds how long a claimed item may make no progress before
	// the lease keeper gives up on it — cancelling the work and leaving the
	// lease to lapse, so another executor reclaims it (#383). Progress is a
	// step finishing, not a byte moving, so it must clear the longest single
	// step a healthy run takes: toolset.MaxTimeout for one `bash`, a 500 MB
	// mount, a wait on the session lock behind another goroutine's checkpoint
	// capture, a cold image pull, or a CheckpointMaxBytes restore — provisioning
	// reports between those, so they are separate intervals rather than one sum.
	// The check rides the keeper's renewal tick, so detection lands somewhere in
	// [stall, stall+LeaseTTL/3]. Set it under the longest step and the item does
	// not merely retry: every reclaim re-runs that step and cancels at the same
	// point, so the session waits on a loop nothing breaks — which is why the
	// binary floors the configured value above toolset.MaxTimeout (a tool at its
	// cap is killed and answers *after* it) and a deployment whose object store
	// is far away should raise it well past that. It bounds
	// *silence*, never duration — an item that keeps finishing steps runs as
	// long as it likes. Not an off switch: a wedged sandbox call is what left
	// an executor stuck with no recovery at all, so 0 takes the default
	// (EXECUTOR_STALL_TIMEOUT).
	StallTimeout time.Duration
	// ReapInterval paces the sandbox reaper (reaper.go): one sweep of this
	// endpoint's owned sessions per interval (EXECUTOR_REAP_INTERVAL; 0 takes
	// the 60s default). Teardown latency is bounded by it, and nothing else
	// destroys sandboxes, so there is no off switch — a deployment that wants
	// slower reaping sets it longer.
	ReapInterval time.Duration
	// CheckpointMaxBytes budgets a workspace checkpoint (checkpoint.go): ONE
	// measure on both sides — the framed, uncompressed tar stream, metered as
	// capture writes it and again as restore decompresses it — so a capture
	// that fits is arithmetically guaranteed to restore
	// (EXECUTOR_CHECKPOINT_MAX_BYTES; 0 takes the 2 GiB default). Over
	// budget, the TTL tier reaps without a checkpoint — an agent must not
	// pin its sandbox immortal by filling the disk (plan 24 D8).
	CheckpointMaxBytes int64
	// SandboxIdleTTL arms the reaper's idle tier (plan 24 slice 5): an idle
	// cloud session whose last activity is older than this is checkpointed and
	// its sandbox reaped — unless it still owes work (a queued/starting/active
	// work item) or an unanswered confirmation ask (HITL-idle is mid-turn).
	// Zero disables the tier — deliberately, so a hand-built test Config never
	// reaps by surprise; cmd/executor resolves the unset env to the 24h
	// default (EXECUTOR_SANDBOX_IDLE_TTL; 0 there disables too). A blob-less
	// executor disables the tier at startup regardless: reaping without the
	// means to checkpoint would silently discard workspaces.
	SandboxIdleTTL time.Duration
	// Hardening is the containment every session's sandbox is created with —
	// cgroup limits, capability drops, optionally a uid and a read-only root
	// (#65). The zero value hardens nothing, which is what a test that builds a
	// Config by hand wants; cmd/executor resolves the platform's defaults from
	// the environment (sandbox.HardeningFromEnv), so every deployment gets them.
	Hardening sandbox.Hardening
	// ControlplaneURL and GateImage opt the deployment into the per-session egress
	// gate. A session wants a gate when its networking is `limited` or it has
	// vaults attached; its gate container (GateImage) fetches that session's egress
	// config from ControlplaneURL. When both are set, a gate-wanting session gets a
	// gate; when either is empty, no gate is requested and a gate-wanting session
	// keeps the backend's own fail-closed networking (Docker `limited` → no egress,
	// K8s → its init-container isolation, vault-attached → inert placeholders) — the
	// pre-gate behavior, so an un-opted-in deployment is unchanged rather than
	// faulted. An unrestricted, vault-less session never wanted a gate and networks
	// directly regardless. See gateSpec.
	ControlplaneURL string
	GateImage       string
	// OTelEndpoint and OTelInsecure are the deployment's OTLP collector config,
	// threaded into each session's gate container so its egress_request spans
	// export to the same collector as the executor (the gate is a separate process
	// that does not inherit this executor's environment). Empty OTelEndpoint =
	// no collector; the gate runs without an exporter.
	OTelEndpoint string
	OTelInsecure bool
	// The web tools' backends (docs/plan/15_web-tools.md). An unconfigured
	// tool answers with an is_error result naming what is missing, so the
	// misconfiguration surfaces to an operator instead of masking the tool.
	// web_search needs TavilyAPIKey; web_fetch needs JinaAPIKey OR an explicit
	// WebFetchBaseURL (the Reader protocol works keyless — a keyless proxy, or
	// the public free tier named deliberately — but with neither set, a bare
	// install must not silently egress model-chosen URLs to a public third
	// party). The base URLs point at Tavily-protocol / Jina-Reader-protocol
	// endpoints; empty resolves to the adapters' public defaults.
	TavilyAPIKey     string
	JinaAPIKey       string
	WebSearchBaseURL string
	WebFetchBaseURL  string
	// WebAllowedDomains, when non-empty, is the operator-side allowlist for
	// the web tools (#225): web_fetch may reach only these hosts, and a
	// search hit whose source is outside them is dropped. Entries use the
	// same grammar as the wire's allowed_hosts (a bare hostname, an IPv4
	// literal, or a "*."-prefixed wildcard that never matches the apex —
	// egress.HostSet, the one matcher). Empty means unrestricted: the
	// reference has per-tool allowed domains, but no wire field carries
	// them, so this knob is platform-native (docs/DIVERGENCES.md).
	WebAllowedDomains []string
	// The clone budgets for github_repository mounts (plan 25 decision 1).
	// The spool a clone lands in sits on executor-local disk, outside the
	// sandbox's own storage hardening, so one unbounded repository could
	// exhaust the executor and disrupt unrelated sessions. RepoCloneMaxBytes
	// is metered as bytes land — over the tree and its tar together — and
	// RepoCloneTimeout bounds one repository's clone; both surface as
	// tolerated clone failures (too_large / timeout), never as a failed run.
	RepoCloneTimeout  time.Duration
	RepoCloneMaxBytes int64
	// MCPPassTimeout bounds one mcp_exec pass — the discovery half across all of
	// the session's MCP servers, and the execution half across all of a turn's
	// outstanding calls — for the reason the clone budgets exist: both walk
	// third-party endpoints serially, so an unbounded pass would hold this
	// process's single work goroutine and disrupt unrelated sessions. Neither
	// half fails the run when it runs out: a server discovery does not reach is
	// a tolerated failed row, and a call execution does not make stays
	// outstanding and keeps the item, which comes back to finish it.
	MCPPassTimeout time.Duration
}

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