driver

type AgentNetworkPolicyReport struct {
	// Agent is the project-local agent name the declaration belongs to.
	Agent string
	// Driver is the resolved runtime driver the report was computed for.
	Driver string
	// Declared is false when neither the agent nor the daemon declared a network
	// policy. Undeclared is not deny (D3): egress stays unrestricted and there
	// is nothing to enforce. A daemon-wide policy sets it true for every agent,
	// including one that declared nothing itself.
	Declared bool
	// Restricts is false when the declaration cannot refuse anything: an allow
	// default with no denial. It is true for a deny default or any declared
	// denial, and false for an undeclared policy.
	Restricts bool
	// Default is the action applied to traffic no entry matches.
	Default egress.Action
	// Allow lists the declared allowances, including their address ranges.
	Allow []egress.DeclaredAllowance
	// Deny lists the declared refusals.
	Deny []egress.DeclaredDenial
	// Mediated reports whether the engine's own forward proxy will apply the
	// declaration rather than the driver.
	Mediated bool
	// Enforcement is the mechanism that will apply the declaration.
	Enforcement SandboxNetworkEnforcement
	// Enforced reports whether that mechanism applies the declaration.
	Enforced bool
	// Mechanisms lists every enforcement mechanism that will apply at least part
	// of this declaration, in driver-first order: for example
	// ["sdk_network_policy", "forward_proxy"]. Mechanism above remains the one
	// that determines the reported strength, so a consumer that only knows the
	// primary mechanism keeps its existing interpretation.
	Mechanisms []string
	// Limitations states material limits of the reported enforcement that do not
	// make it unenforced, such as traffic that bypasses the forward proxy. It is
	// empty when there is nothing beyond Mechanism to disclose.
	Limitations []string
	// DaemonPolicySource and DaemonPolicySHA256 identify the daemon-wide policy
	// the effective declaration was computed against. They are empty when no
	// daemon-wide policy was configured, or when this report was produced
	// outside project admission.
	DaemonPolicySource string
	DaemonPolicySHA256 string
	// Unapplied names the parts of the declaration the mechanism does not apply.
	// It is empty when the mechanism applies all of it.
	Unapplied []string
	// Warning states what the operator must know when the declaration will not be
	// enforced as written. It is empty when it will be.
	Warning string
}

type CredentialSurface struct {
	// Kind is the credential form the name belongs to.
	Kind credentials.Kind
	// Absorbable reports whether the daemon can already replace the declared
	// plaintext value with a short-lived, scoped handle on the way into a
	// sandbox. Only the LLM facade is absorbable today: the daemon holds the
	// upstream key and gives the guest a run-scoped facade token. Git, MCP, and
	// registry credentials are recognized, but still travel as plaintext
	// environment until the credential broker has a declared endpoint to scope
	// them to; they stay visible in views and are reported as not yet isolated
	// instead of being described as protected.
	Absorbable bool
}

type ExecChunk struct {
	// Text is valid UTF-8. Runtime byte streams must buffer incomplete rune
	// suffixes and replace irrecoverably invalid input before emitting a chunk.
	Text   string
	Stream StdioStream
}

type ExecResult struct {
	ExitCode int
	Stdout   string
	Stderr   string
	Output   string
	Success  bool
	// SecurityFacts carries the isolation failures the lower layer reported on
	// this exec's stderr. It is engine-measured evidence, not a driver
	// declaration, and is zero when the lower layer reported nothing.
	SecurityFacts ExecSecurityFacts
}

type ExecSecurityFacts struct {
	// SeccompUnavailable counts reports that seccomp privileges were not set.
	SeccompUnavailable int `json:"seccomp_unavailable,omitempty"`
	// NoNewPrivilegesUnavailable counts reports that no_new_privileges was not
	// enforced.
	NoNewPrivilegesUnavailable int `json:"no_new_privileges_unavailable,omitempty"`
}

type ExecSpec struct {
	Command string            `json:"command"`
	Args    []string          `json:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty"`
	Cwd     string            `json:"cwd,omitempty"`
	// Marker, when set, tags the exec's process tree with this value instead
	// of a driver-generated one. The daemon uses a run's execution id as the
	// marker for a detached task so it can later terminate that exact tree via
	// ProcessTreeTerminator, independent of any exec handle.
	Marker string `json:"marker,omitempty"`
	// KillOnlyOnCancel reports that this exec is a single attach process whose
	// process tree is not the task's. On context cancellation the driver must
	// kill the exec directly and skip the whole-tree termination cleanup (which
	// otherwise adds a bounded SIGTERM→SIGKILL escalation on VM drivers).
	KillOnlyOnCancel bool `json:"kill_only_on_cancel,omitempty"`
}

type ExecStreamInteractionRequest struct {
	Session *Sandbox
	VMState VMState
	Spec    RuntimeStartSpec
}

type ExecStreamWriter func(ExecChunk)

type GuestDirectoryPublication struct {
	HostSource       string
	GuestDestination string
	ManagedMarker    string
}

type GuestSymlinkProjection struct {
	GuestPath      string
	RelativeTarget string
	ManagedMarkers []string
}

type ManagedRuntimeResource struct {
	Driver         string
	RuntimeID      string
	SandboxID      string
	UpdatedAt      time.Time
	OwnershipValid bool
	Removable      bool
	BlockedReasons []string
	OwnedPaths     []string
}

type MetricValue struct {
	Value   *float64
	Unit    string
	Status  string
	Message string
}

type ProcessTreeTerminator interface {
	TerminateProcessTree(context.Context, *Sandbox, VMState, string) error
}

type ProxyState struct {
	ProxyPath  string `json:"proxy_path"`
	GuestHost  string `json:"guest_host"`
	HostPort   int    `json:"host_port"`
	GuestPort  int    `json:"guest_port"`
	JupyterURL string `json:"jupyter_url,omitempty"`
	Token      string `json:"token,omitempty"`
	Enabled    bool   `json:"enabled,omitempty"`
	Exposed    bool   `json:"exposed,omitempty"`
}

type ProxyStateReader func(sandboxID string) (ProxyState, error)

type RuntimeAgentEvent struct {
	Type     string            `json:"type"`
	Message  string            `json:"message,omitempty"`
	Payload  []byte            `json:"payload,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

type RuntimeAgentSpec struct {
	Provider  string            `json:"provider,omitempty"`
	Model     string            `json:"model,omitempty"`
	Prompt    string            `json:"prompt,omitempty"`
	SessionID string            `json:"session_id,omitempty"`
	Metadata  map[string]string `json:"metadata,omitempty"`
}

type RuntimeCapabilityDimensionFacts struct {
	Dimension       string
	Enforced        bool
	Mechanism       string
	Preconditions   []string
	Observed        string
	DefaultBehavior string
	// State is the three-state answer ("enforced", "degraded", "unsupported").
	// Empty means the reader derives it from Enforced, which keeps an API-7
	// declaration valid unchanged.
	State string
	// Source is "declared", "measured", or "simulated". A driver declaration
	// itself is declared evidence: it states what the driver writes into its
	// runtime configuration, never what it observed. Empty defaults to
	// declared.
	Source string
}

type RuntimeCapabilityFacts struct {
	// Driver is the normalized runtime driver name.
	Driver string
	// Dimensions covers every dimension pkg/capmatrix requires, exactly once.
	Dimensions []RuntimeCapabilityDimensionFacts
}

type RuntimeCommandSpec struct {
	Command string            `json:"command"`
	Args    []string          `json:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty"`
	Cwd     string            `json:"cwd,omitempty"`
}

type RuntimeDriverNotCompiledError struct {
	Driver          string
	GOOS            string
	GOARCH          string
	CompiledDrivers []string
}

type RuntimeError struct {
	Code    string `json:"code,omitempty"`
	Message string `json:"message"`
}

type RuntimeInputFrame struct {
	Type    RuntimeInputFrameType `json:"type"`
	Data    []byte                `json:"data,omitempty"`
	Rows    uint32                `json:"rows,omitempty"`
	Cols    uint32                `json:"cols,omitempty"`
	Signal  RuntimeSignal         `json:"signal,omitempty"`
	Message string                `json:"message,omitempty"`
}

type RuntimeInputFrameType string

type RuntimeInteraction interface {
	Send(RuntimeInputFrame) error
	CloseSend() error
	Recv() (RuntimeOutputFrame, error)
	Wait() (RuntimeResult, error)
}

type RuntimeInteractionCapabilities struct {
	NativeExec    bool `json:"native_exec"`
	WrapperStream bool `json:"wrapper_stream"`
	Stdin         bool `json:"stdin"`
	StdinEOF      bool `json:"stdin_eof"`
	TTY           bool `json:"tty"`
	Resize        bool `json:"resize"`
	Signal        bool `json:"signal"`
	Artifacts     bool `json:"artifacts"`
	AgentTurns    bool `json:"agent_turns"`
}

type RuntimeInteractionCapability string

type RuntimeInteractionUnsupportedError struct {
	Driver     string
	Operation  RuntimeOperationKind
	Capability RuntimeInteractionCapability
	Reason     string
}

type RuntimeInteractor interface {
	InteractionCapabilities() RuntimeInteractionCapabilities
	OpenInteraction(context.Context, *Sandbox, VMState, RuntimeStartSpec) (RuntimeInteraction, error)
}

type RuntimeMount struct {
	HostPath  string `json:"hostPath"`
	GuestPath string `json:"guestPath"`
	Type      string `json:"type"`
	ReadOnly  bool   `json:"readOnly"`
}

type RuntimeMountManifest struct {
	Version int            `json:"version"`
	Driver  string         `json:"driver"`
	Mounts  []RuntimeMount `json:"mounts"`
}

type RuntimeOperationKind string

type RuntimeOutputFrame struct {
	Type RuntimeOutputFrameType `json:"type"`
	// Data in stdout and stderr frames is valid UTF-8 text. Runtime byte
	// streams must complete or replace invalid rune fragments before emitting.
	Data      []byte             `json:"data,omitempty"`
	Event     *RuntimeAgentEvent `json:"event,omitempty"`
	Result    *RuntimeResult     `json:"result,omitempty"`
	Error     *RuntimeError      `json:"error,omitempty"`
	StartedAt time.Time          `json:"started_at,omitempty"`
}

type RuntimeOutputFrameType string

type RuntimeResult struct {
	OperationID string            `json:"operation_id,omitempty"`
	ExitCode    int               `json:"exit_code"`
	Success     bool              `json:"success"`
	Error       string            `json:"error,omitempty"`
	StartedAt   time.Time         `json:"started_at,omitempty"`
	CompletedAt time.Time         `json:"completed_at,omitempty"`
	Artifacts   map[string]string `json:"artifacts,omitempty"`
	// SecurityFacts carries the lower-layer isolation failures observed during
	// this operation. It is nil when the lower layer reported nothing, so the
	// common case adds no payload.
	SecurityFacts *ExecSecurityFacts `json:"security_facts,omitempty"`
}

type RuntimeSignal string

type RuntimeStartSpec struct {
	OperationID string               `json:"operation_id,omitempty"`
	Kind        RuntimeOperationKind `json:"kind"`
	Origin      string               `json:"origin,omitempty"`
	Command     *RuntimeCommandSpec  `json:"command,omitempty"`
	Agent       *RuntimeAgentSpec    `json:"agent,omitempty"`
	Cwd         string               `json:"cwd,omitempty"`
	Env         map[string]string    `json:"env,omitempty"`
	AttachStdin bool                 `json:"attach_stdin,omitempty"`
	TTY         bool                 `json:"tty,omitempty"`
	Rows        uint32               `json:"rows,omitempty"`
	Cols        uint32               `json:"cols,omitempty"`
	TimeoutMs   int64                `json:"timeout_ms,omitempty"`
	ArtifactDir string               `json:"artifact_dir,omitempty"`
}

type Sandbox struct {
	Summary         SandboxSummary       `json:"summary"`
	Workspace       *SandboxWorkspace    `json:"workspace,omitempty"`
	EnvItems        []SandboxEnvVar      `json:"env_items,omitempty"`
	VolumeMounts    []SandboxVolumeMount `json:"volume_mounts,omitempty"`
	RuntimeEnvItems []SandboxEnvVar      `json:"-"`
	// NetworkPolicy is the driver-boundary egress policy the caller populated
	// from the compose declaration. A nil policy means the sandbox declared no
	// network policy, which keeps today's unrestricted behavior (D3).
	NetworkPolicy *SandboxNetworkPolicy `json:"network_policy,omitempty"`
	// ProxyEnv, when set, is invoked by a driver at the moment it builds the
	// environment of a runtime it is creating, and never when it reuses one.
	//
	// A guest reads its proxy environment once, when its runtime is created; a
	// later ensure of that same runtime cannot change it. Resolving the proxy
	// credential here, rather than when the sandbox is handed to the driver, is
	// what keeps issuance to one credential per runtime: eager resolution mints
	// a live credential on every ensure, every scheduler tick and every
	// guest-file operation, and no extra can ever be presented by a guest.
	ProxyEnv func(context.Context) ([]SandboxEnvVar, error) `json:"-"`
}

type SandboxEgressStrength string

type SandboxEnvVar struct {
	Name   string `json:"name"`
	Value  string `json:"value,omitempty"`
	Secret bool   `json:"secret,omitempty"`
}

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

type SandboxHostMode string

type SandboxNeedsCreate interface {
	NeedsCreate(context.Context, *Sandbox, VMState) (bool, error)
}

type SandboxNetworkEnforcement struct {
	Driver    string
	Strength  SandboxEgressStrength
	Mechanism string
	// AppliesAllowEntries reports whether declared allowances reach the driver.
	AppliesAllowEntries bool
	// AppliesDenyEntries reports whether declared denials reach the driver.
	AppliesDenyEntries bool
	// AppliesEngineEndpoints reports whether the engine-owned endpoints stay
	// reachable when the policy restricts.
	AppliesEngineEndpoints bool
	// AppliesDenyDomains reports whether the declared deny domains reach the
	// driver's DNS resolution path.
	AppliesDenyDomains bool
	// AppliesAllowedAddresses reports whether this mechanism can constrain which
	// addresses a declared name may resolve to. Only a mediator that resolves the
	// destination itself can, so a driver that pushes host patterns to a runtime
	// leaves that part of a declaration unapplied rather than applying it
	// partially without saying so.
	AppliesAllowedAddresses bool
	// Notes is the human-readable limit of what the driver applies, so a report
	// never presents a partial mechanism as complete.
	Notes string
}

type SandboxNetworkPolicy struct {
	Default egress.Action
	// Allow is the declared allowance list in declaration order. Order does not
	// change the outcome because every entry allows, but it is preserved so a
	// report can echo the declaration. It is the declaration layer's own entry
	// type rather than a narrowed endpoint so an entry's allowed address range
	// survives the seam: a boundary policy that quietly dropped a constraint
	// would let a driver enforce less than the project declared.
	Allow []egress.AllowEntry
	// Deny is the declared refusal list in declaration order. A denial wins over
	// an allowance that matches the same destination.
	Deny []egress.DenyEntry
	// EngineEndpoints are the engine-owned endpoints that must stay reachable
	// whenever the policy restricts.
	EngineEndpoints []egress.EngineEndpoint
	// DenyDomains are exact domain names the driver refuses to resolve. The
	// compose declaration does not carry them yet, so they are engine-supplied.
	DenyDomains []string
	// MediatedByForwardProxy reports that the engine, not the driver, decides
	// this sandbox's egress: the guest was given the engine's forward proxy as
	// its egress path, so the declaration is enforced on a driver that has no
	// enforcement surface of its own.
	//
	// It is set by the caller that actually routed the guest through the proxy,
	// in the same step that added the proxy environment, so a driver can never
	// believe in a mediation the engine did not wire. A driver reads it only to
	// report enforcement honestly and to skip the unenforced-declaration gate.
	MediatedByForwardProxy bool
}

type SandboxRuntime interface {
	EnsureSandbox(context.Context, *Sandbox, VMState, ProxyState) (SandboxVMInfo, error)
	StopSandbox(context.Context, *Sandbox, VMState) (bool, error)
	RemoveSandbox(context.Context, *Sandbox, VMState) error
	Exec(context.Context, *Sandbox, VMState, ExecSpec) (ExecResult, error)
	ExecStream(context.Context, *Sandbox, VMState, ExecSpec, ExecStreamWriter) (ExecResult, error)
}

type SandboxStartTarget struct {
	Driver  string
	Session *Sandbox
	VMState VMState
}

type SandboxStats struct {
	SandboxID        string
	Driver           string
	SampledAt        time.Time
	CPUPercent       MetricValue
	MemoryUsageBytes MetricValue
	MemoryLimitBytes MetricValue
	MemoryPercent    MetricValue
	NetworkRxBytes   MetricValue
	NetworkTxBytes   MetricValue
	BlockReadBytes   MetricValue
	BlockWriteBytes  MetricValue
	UptimeSeconds    MetricValue
}

type SandboxSummary struct {
	ID            string    `json:"id"`
	Driver        string    `json:"driver"`
	GuestImage    string    `json:"guest_image,omitempty"`
	PullPolicy    string    `json:"pull_policy,omitempty"`
	RuntimeRef    string    `json:"runtime_ref,omitempty"`
	WorkspacePath string    `json:"workspace_path"`
	CreatedAt     time.Time `json:"created_at"`
	UpdatedAt     time.Time `json:"updated_at"`
}

type SandboxVMInfo struct {
	BoxID      string
	JupyterURL string
	ProxyState *ProxyState
	// RuntimeCreated reports that this call created the runtime rather than
	// reusing one that already existed. The engine asks a start to *ensure* a
	// runtime, so this is the only fact that distinguishes "built under the
	// configuration resolved now" from "started again with the one it already
	// had". A driver that does not report it leaves the engine unable to tell,
	// and callers must treat false as unknown rather than as reuse.
	RuntimeCreated bool
}

type SandboxVolumeMount struct {
	ID       string `json:"id,omitempty"`
	Type     string `json:"type"`
	Source   string `json:"source"`
	Target   string `json:"target"`
	ReadOnly bool   `json:"read_only,omitempty"`
	VolumeID string `json:"volume_id,omitempty"`
	Driver   string `json:"driver,omitempty"`
	HostPath string `json:"host_path"`
}

type SandboxWorkspace struct {
	Type       string `json:"type"`
	ConfigJSON string `json:"config_json"`
}

type StdioStream string

type VMState struct {
	Driver           string    `json:"driver"`
	Mode             string    `json:"mode,omitempty"`
	BoxName          string    `json:"box_name,omitempty"`
	BoxID            string    `json:"box_id,omitempty"`
	Image            string    `json:"image,omitempty"`
	Registry         string    `json:"registry,omitempty"`
	RuntimeHome      string    `json:"runtime_home,omitempty"`
	StartedAt        time.Time `json:"started_at,omitempty"`
	StartAttemptedAt time.Time `json:"start_attempted_at,omitempty"`
	StoppedAt        time.Time `json:"stopped_at,omitempty"`
	LastError        string    `json:"last_error,omitempty"`
	BootstrapRef     string    `json:"bootstrap_ref,omitempty"`
	// K8sContext and K8sNamespace override which cluster/namespace the k8s
	// driver targets for this sandbox. Empty means "use the daemon's
	// K8S_KUBECONFIG current-context / K8S_NAMESPACE default" (see
	// k8sRuntime.client and k8sRuntime.namespaceFor). Other drivers ignore
	// these fields.
	K8sContext   string `json:"k8s_context,omitempty"`
	K8sNamespace string `json:"k8s_namespace,omitempty"`
}