types

type AddAllowRules struct {
	// Target is required and declares the full scope affected by the append.
	Target *L7RuleTarget
	// Rules are the allow rules to append.
	Rules []L7Rule
}

type AddDenyRules struct {
	// Target is required and declares the full scope affected by the append.
	Target *L7RuleTarget
	// DenyRules are the deny rules to append.
	DenyRules []L7DenyRule
}

type AddNetworkRule struct {
	// RuleName is the name key for the rule.
	RuleName string
	// Rule is the full network policy rule to add.
	Rule NetworkPolicyRule
}

type ApproveAllOption func(*approveAllConfig)

type ApproveAllResult struct {
	// PolicyVersion is the new policy version after merge.
	PolicyVersion uint32
	// PolicyHash is the SHA-256 hash of the new policy.
	PolicyHash string
	// ChunksApproved is the number of chunks approved.
	ChunksApproved uint32
	// ChunksSkipped is the number of chunks skipped (security-flagged).
	ChunksSkipped uint32
}

type ApproveResult struct {
	// PolicyVersion is the new policy version after merge.
	PolicyVersion uint32
	// PolicyHash is the SHA-256 hash of the new policy.
	PolicyHash string
}

type AttachProviderResult struct {
	Sandbox  *Sandbox
	Attached bool
}

type AuthProvider interface {
	GetRequestMetadata(ctx context.Context, uri ...string) (map[string]string, error)
	RequireTransportSecurity() bool
}

type ClearResult struct {
	// ChunksCleared is the number of chunks cleared.
	ChunksCleared uint32
}

type ComputeDriverInfo struct {
	Name          string
	DriverName    string
	DriverVersion string
}

type Config struct {
	Address     string
	TLS         *TLSConfig
	Auth        AuthProvider
	Timeout     time.Duration
	RetryPolicy *RetryPolicy
	Logger      Logger
}

type ConfigUpdate struct {
	// Name is the sandbox name (required for sandbox-scoped updates).
	Name string
	// Policy is the typed security policy for a full policy replacement. Nil means no policy change.
	Policy *SandboxPolicy
	// SettingKey is a single setting key to mutate.
	SettingKey string
	// SettingValue is the setting value for upsert. Nil means no value change.
	SettingValue *SettingValue
	// DeleteSetting deletes the setting key when true.
	DeleteSetting bool
	// Global applies the update at gateway-global scope when true.
	Global bool
	// MergeOperations is a list of typed policy merge operations.
	MergeOperations []PolicyMergeOperation
	// ExpectedResourceVersion is for optimistic concurrency (0 = skip check).
	ExpectedResourceVersion uint64
	// Annotations is caller-provided metadata for sandbox-scoped updates.
	Annotations map[string]string
}

type ConfigUpdateResult struct {
	// Version is the assigned policy version.
	Version uint32
	// PolicyHash is the SHA-256 of the serialized policy.
	PolicyHash string
	// SettingsRevision is the settings revision for the modified scope.
	SettingsRevision uint64
	// Deleted is true when a setting delete removed an existing key.
	Deleted bool
	// Annotations contains sandbox metadata annotations after the update.
	Annotations map[string]string
}

type ConfigurationAdmissionState string

type CreateOption func(*createConfig)

type CredentialHandle struct {
	Driver   string
	Handle   string
	Metadata map[string]string
}

type CredentialTokenGrant struct {
	TokenEndpoint   string
	Audience        string
	JWTSVIDAudience string
	Scopes          []string
	// CacheTTL retains the exact protobuf duration, including presence and nanoseconds.
	CacheTTL            *ProfileDuration
	AudienceOverrides   []TokenGrantAudienceOverride
	ClientAssertionType string
	GrantType           CredentialTokenGrantType
	SubjectToken        *TokenGrantSubjectToken
	RequestedTokenType  string
}

type CredentialTokenGrantType string

type CurrentUser struct {
	Subject          string
	DisplayName      string
	Roles            []string
	Scopes           []string
	IdentityProvider string
}

type DeleteOptions struct {
	AllowMissing bool
}

type DeletionOutcome int32

type DeletionResult struct {
	Outcome DeletionOutcome
	// SandboxID is empty for non-sandbox deletions and missing targets.
	SandboxID string
}

type DetachProviderResult struct {
	Sandbox  *Sandbox
	Detached bool
}

type DraftChunkApproval struct {
	ChunkID     string
	ReviewToken string
}

type DraftHistoryEntry struct {
	// Timestamp is when the event occurred.
	Timestamp time.Time
	// EventType is the event type (e.g., "approved", "rejected", "cleared").
	EventType string
	// Description is a human-readable description.
	Description string
	// ChunkID is the associated chunk ID (if applicable).
	ChunkID string
}

type DraftPolicy struct {
	// Chunks contains the draft policy chunks.
	Chunks []PolicyChunk
	// RollingSummary is an LLM-generated summary of all analysis.
	RollingSummary string
	// DraftVersion is the current draft version number.
	DraftVersion uint64
	// LastAnalyzedAt is when the last analysis completed.
	LastAnalyzedAt time.Time
}

type EffectiveSetting struct {
	Value SettingValue
	Scope SettingScope
}

type EndpointFailure struct {
	// Domain names the subsystem whose closed code set explains the failure.
	Domain EndpointFailureDomain
	// Code is a stable lower_snake_case code from the domain's closed set,
	// such as provider_authorization_required.
	Code string
	// RecoveryAction is the action documented for Code.
	RecoveryAction RefreshRecoveryAction
	// Provider is the configured provider whose credential failed. It is empty
	// when the failure happened before a credential was selected.
	Provider string
	// CredentialKey is the configured credential name within Provider, never a
	// credential value. It is empty when Provider is empty.
	CredentialKey string
	// Stage is the step that observed the failure, from the domain's closed
	// set, such as gateway_rpc.
	Stage string
	// UpstreamHTTPStatus is the HTTP status a token service returned. Nil means
	// no status was received.
	UpstreamHTTPStatus *uint32
	// RequestID is the supervisor-minted UUID of the refused exchange. The
	// workload receives the same value in the x-openshell-request-id response
	// header.
	RequestID string
}

type EndpointFailureDomain string

type EndpointResult string

type EndpointStatus struct {
	// EndpointID selects this endpoint without parsing its address or display text.
	EndpointID string
	Host       string
	Ports      []uint32
	Path       string
	LastResult EndpointResult
	// LastReportedAt is the RFC 3339 UTC rendering of the time when the gateway accepted the
	// observation, not the request time. Retained evidence can be accepted after
	// a reset. NoObservedExchange has no report timestamp.
	LastReportedAt string
	// LastFailure is the bounded cause of LastResult, when the supervisor
	// classified it. Each failure domain names the results it explains; token
	// grant failures accompany EndpointCredentialUnavailable. Each later
	// observation replaces or clears it, and the resets that clear LastResult
	// also clear it. Nil means no classified cause.
	LastFailure *EndpointFailure
}

type ErrorCode int

type ErrorInfo struct {
	Reason   string
	Domain   string
	Metadata map[string]string
}

type Event[T any] struct {
	Type   EventType
	Object T
	Err    error
}

type EventType string

type ExecChunk struct {
	Stream StreamType
	Data   []byte
}

type ExecOptions struct {
	Env     map[string]string
	WorkDir string
	// NoLoginShell skips sourcing shell login/profile startup files before the
	// command. The zero value (false) preserves login-shell behavior. Set it
	// for automation and managed checks that need predictable startup behavior.
	NoLoginShell bool
}

type ExecResult struct {
	ExitCode int
	Stdout   []byte
	Stderr   []byte
}

type ExtensionInfo struct {
	Kind                  ExtensionKind
	ConfiguredName        string
	ImplementationName    string
	ImplementationVersion string
	ProtocolMajor         uint32
	ProtocolMinor         uint32
	SupportedCapabilities []string
	RequiredCapabilities  []string
}

type ExtensionKind string

type FieldViolation struct {
	Field       string
	Description string
}

type FilesystemPolicy struct {
	// IncludeWorkdir auto-includes the working directory as read-write.
	IncludeWorkdir bool
	// ReadOnly is the list of read-only directory paths.
	// Nil means no read-only directories; an empty slice is distinct from nil.
	ReadOnly []string
	// ReadWrite is the list of read-write directory paths.
	// Nil means no read-write directories; an empty slice is distinct from nil.
	ReadWrite []string
}

type GatewayConfig struct {
	// Settings is the global settings map.
	Settings map[string]SettingValue
	// SettingsRevision is a monotonically increasing revision for gateway-global settings.
	SettingsRevision uint64
}

type GatewayInfo struct {
	Status         ServiceStatus
	Version        string
	ComputeDrivers []ComputeDriverInfo
	Extensions     []ExtensionInfo
}

type GetDraftOption func(*getDraftConfig)

type GetStatusOption func(*getStatusConfig)

type GraphqlOperation struct {
	OperationType string
	OperationName string
	Fields        []string
}

type HealthResult struct {
	Healthy bool
	Version string
}

type ImportResult struct {
	Diagnostics []ProfileDiagnostic
	Profiles    []ProviderProfile
	Imported    bool
}

type L7Allow struct {
	Method        string
	Path          string
	Command       string
	Query         map[string]L7QueryMatcher
	OperationType string
	OperationName string
	Fields        []string
	Params        map[string]L7QueryMatcher
}

type L7DenyRule struct {
	Method        string
	Path          string
	Command       string
	Query         map[string]L7QueryMatcher
	OperationType string
	OperationName string
	Fields        []string
	Params        map[string]L7QueryMatcher
}

type L7QueryMatcher struct {
	Glob string
	Any  []string
}

type L7Rule struct {
	// Allow holds the layer-7 allow criteria.
	Allow *L7Allow
}

type L7RuleTarget struct {
	// RuleName names the base-policy rule containing the endpoint.
	RuleName string
	// Host is the endpoint host, matched case-insensitively.
	Host string
	// Ports lists every port affected by the append, not only a lookup port.
	Ports []uint32
	// Path selects the endpoint path, distinct from an appended request path.
	// Nil requires a unique endpoint; a pointer to "" selects an unscoped endpoint.
	Path *string
	// Binaries lists every binary governed by the containing rule.
	// Exactly one of a nonempty Binaries list or AnyBinary=true is required.
	Binaries []PolicyNetworkBinary
	// AnyBinary explicitly acknowledges a rule with unrestricted binary scope.
	AnyBinary bool
}

type LandlockPolicy struct {
	// Compatibility is the compatibility mode (e.g., "best_effort", "hard_requirement").
	Compatibility string
}

type LintResult struct {
	Diagnostics []ProfileDiagnostic
	Valid       bool
}

type ListOptions struct {
	// PageSize is the maximum number of resources requested per RPC.
	PageSize int
	// PageToken resumes after a page returned by the same list query.
	PageToken     string
	LabelSelector string
	// AllWorkspaces selects a platform-admin view across workspace boundaries.
	AllWorkspaces bool
}

type ListPolicyOption func(*listPolicyConfig)

type LogLine struct {
	// Timestamp is when the log entry was recorded.
	Timestamp time.Time
	// Level is the log severity level (e.g., "INFO", "WARN", "ERROR").
	Level string
	// Target is the log target/module.
	Target string
	// Message is the log message text.
	Message string
	// Source is the log source: "gateway" or "sandbox".
	Source string
	// Fields contains structured key-value fields from the tracing event.
	Fields map[string]string
}

type LogOption func(*logConfig)

type LogResult struct {
	// Lines contains the log entries in chronological order.
	Lines []LogLine
	// BufferTotal is the total number of lines in the server's buffer.
	BufferTotal uint32
}

type Logger interface {
	Debug(msg string, keysAndValues ...any)
	Info(msg string, keysAndValues ...any)
	Error(err error, msg string, keysAndValues ...any)
}

type McpOptions struct {
	StrictToolNames         *bool
	AllowAllKnownMcpMethods *bool
	// Versions lists the exact MCP protocol revisions accepted by the endpoint.
	// An empty list represents omission at the protobuf transport boundary; the
	// checked policy or server ingress materializes the pinned default
	// "2025-11-25" before storing canonical state. Nonempty lists remain exact
	// allowlists.
	Versions []string
}

type MiddlewareEndpointSelector struct {
	Include []string
	Exclude []string
}

type NetworkAccessPreset int32

type NetworkBinary struct {
	Path string
}

type NetworkCredentialBinding struct {
	Provider string
}

type NetworkEndpoint struct {
	Host     string
	Port     uint32
	Protocol string
}

type NetworkEnforcementMode int32

type NetworkMiddlewareConfig struct {
	Name       string
	Middleware string
	Config     map[string]any
	OnError    string
	Endpoints  *MiddlewareEndpointSelector
	Order      int32
}

type NetworkPolicyRule struct {
	// Name is the map key for this rule in the sandbox policy.
	Name string
	// Endpoints lists the network endpoints governed by this rule.
	Endpoints []PolicyNetworkEndpoint
	// Binaries lists the binaries governed by this rule.
	Binaries []PolicyNetworkBinary
}

type NetworkTLSMode int32

type PolicyChunk struct {
	// ID is the unique chunk identifier.
	ID string
	// Status is the approval status: "pending", "approved", "rejected".
	Status string
	// RuleName is the proposed network_policies map key.
	RuleName string
	// ProposedRule is the proposed network policy rule.
	ProposedRule *NetworkPolicyRule

	// Rationale is a human-readable explanation of why this rule is proposed.
	Rationale string
	// SecurityNotes contains security concerns flagged by analysis (empty if none).
	SecurityNotes string
	// Confidence is the analysis confidence score (0.0-1.0).
	Confidence float32
	// DenialSummaryIDs lists the IDs of denial summaries that led to this chunk.
	DenialSummaryIDs []string
	// CreatedAt is when the chunk was created.
	CreatedAt time.Time
	// DecidedAt is when the user approved/rejected (zero if undecided).
	DecidedAt time.Time
	// Stage is the recommendation stage: "initial" or "refined".
	Stage string
	// SupersedesChunkID is the initial chunk ID this refined chunk replaces.
	SupersedesChunkID string
	// HitCount is how many times this endpoint was seen across denial flush cycles.
	HitCount int32
	// FirstSeen is the first time this endpoint was proposed.
	FirstSeen time.Time
	// LastSeen is the most recent time this endpoint was re-proposed.
	LastSeen time.Time
	// Binary is the binary path that triggered the denial.
	Binary string
	// ValidationResult is the prover output from gateway-side static checks.
	ValidationResult string
	// RejectionReason is the operator-supplied text accompanying a rejection.
	RejectionReason string
	// ApplicationError is the complete-candidate preflight/application failure.
	ApplicationError string
	// ReviewToken binds an approval to the exact evaluated candidate.
	ReviewToken                  string
	CurrentEffectivePolicyHash   string
	CandidateEffectivePolicyHash string
	CurrentEffectivePolicy       *SandboxPolicy
	CandidateEffectivePolicy     *SandboxPolicy
}

type PolicyLoadStatus int

type PolicyMergeOperation struct {
	// AddRule adds a new named network policy rule.
	AddRule *AddNetworkRule
	// RemoveEndpoint removes a single endpoint from a rule.
	RemoveEndpoint *RemoveNetworkEndpoint
	// RemoveRule removes an entire named rule.
	RemoveRule *RemoveNetworkRule
	// AddDenyRules appends deny rules to an endpoint.
	AddDenyRules *AddDenyRules
	// AddAllowRules appends allow rules to an endpoint.
	AddAllowRules *AddAllowRules
	// RemoveBinary removes a binary from a rule.
	RemoveBinary *RemoveNetworkBinary
}

type PolicyNetworkBinary struct {
	// Path is the filesystem path to the binary.
	Path string
}

type PolicyNetworkEndpoint struct {
	Host                         string
	Port                         uint32
	Ports                        []uint32
	Protocol                     string
	TLS                          NetworkTLSMode
	Enforcement                  NetworkEnforcementMode
	Access                       NetworkAccessPreset
	Rules                        []L7Rule
	AllowedIPs                   []string
	DenyRules                    []L7DenyRule
	AllowEncodedSlash            bool
	PersistedQueries             string
	GraphqlPersistedQueries      map[string]GraphqlOperation
	GraphqlMaxBodyBytes          uint32
	Path                         string
	WebsocketCredentialRewrite   bool
	RequestBodyCredentialRewrite bool
	// AllowUninspectedCredentials explicitly permits credential-bearing traffic
	// on paths OpenShell cannot inspect or rewrite.
	AllowUninspectedCredentials bool
	// ProviderCredentialed is gateway-derived provenance indicating that the
	// endpoint belongs to an attached credentialed provider.
	ProviderCredentialed bool
	AdvisorProposed      bool
	CredentialSigning    string
	SigningService       string
	SigningRegion        string
	JSONRPCMaxBodyBytes  uint32
	Mcp                  *McpOptions
	CredentialBinding    *NetworkCredentialBinding
}

type PolicySource string

type PolicyStatusResult struct {
	// Revision is the queried policy revision.
	Revision SandboxPolicyRevision
	// ActiveVersion is the currently active (loaded) policy version.
	ActiveVersion uint32
}

type ProcessPolicy struct {
	// RunAsUser is the user name for sandboxed processes.
	RunAsUser string
	// RunAsGroup is the group name for sandboxed processes.
	RunAsGroup string
}

type ProfileCategory string

type ProfileCredential struct {
	Name        string
	Description string
	EnvVars     []string
	Required    bool
	// StablePlaceholder uses an opaque identity-bound resolver handle across
	// value-only external provider updates. It does not change secret
	// classification or bypass endpoint authorization.
	StablePlaceholder bool
	Secret            bool
	Refresh           *ProfileCredentialRefresh
	AuthStyle         string
	HeaderName        string
	QueryParam        string
	PathTemplate      string
	TokenGrant        *CredentialTokenGrant
}

type ProfileCredentialRefresh struct {
	Strategy RefreshStrategy
	TokenURL string
	Scopes   []string
	// RefreshBefore retains the exact protobuf duration, including presence and nanoseconds.
	RefreshBefore *ProfileDuration
	// MaxLifetime retains the exact protobuf duration, including presence and nanoseconds.
	MaxLifetime       *ProfileDuration
	Material          []ProfileCredentialRefreshMaterial
	AdditionalOutputs []ProfileCredentialRefreshOutput
}

type ProfileCredentialRefreshMaterial struct {
	Name        string
	Description string
	Required    bool
	Secret      bool
}

type ProfileCredentialRefreshOutput struct {
	Output     string
	Credential string
}

type ProfileDiagnostic struct {
	Source    string
	ProfileID string
	Field     string
	Message   string
	Severity  string
}

type ProfileDiscovery struct {
	Credentials []string
}

type ProfileDuration struct {
	Seconds int64
	Nanos   int32
}

type ProfileFile struct {
	Path    string
	Content string
	EnvVar  string
}

type ProfileImportItem struct {
	Profile ProviderProfile
	Source  string
}

type Provider struct {
	ID                string
	Name              string
	Type              string
	CreatedAt         time.Time
	Labels            map[string]string
	Annotations       map[string]string
	ResourceVersion   uint64
	Workspace         string
	DeletionTimestamp *time.Time
	Spec              ProviderSpec
}

type ProviderProfile struct {
	ID          string
	DisplayName string
	Description string
	Category    ProfileCategory
	Credentials []ProfileCredential
	// Files is EXPERIMENTAL. This API and its behavior may change or be removed.
	Files            []ProfileFile
	Endpoints        []NetworkEndpoint
	Binaries         []NetworkBinary
	InferenceCapable bool
	Discovery        ProfileDiscovery
	ResourceVersion  uint64
	Annotations      map[string]string
	Source           string
	Scope            string
}

type ProviderSpec struct {
	Credentials         map[string]string
	Config              map[string]string
	CredentialExpiresAt map[string]time.Time
	ProfileWorkspace    string
	CredentialHandles   map[string]CredentialHandle
}

type RefreshConfig struct {
	Provider           string
	CredentialKey      string
	Strategy           RefreshStrategy
	Material           map[string]string
	SecretMaterialKeys []string
	ExpiresAt          *time.Time
}

type RefreshRecoveryAction int

type RefreshStatus struct {
	Provider      string
	ProviderID    string
	CredentialKey string
	Strategy      RefreshStrategy
	Status        string
	ExpiresAt     time.Time
	// NextRefreshAt is zero when no automatic refresh is scheduled. Use
	// RecoveryAction to distinguish a parked refresh from an unset timestamp.
	NextRefreshAt        time.Time
	LastRefreshAt        time.Time
	LastError            string
	RecoveryAction       RefreshRecoveryAction
	FailureCode          string
	ProviderErrorSubtype string
	LastErrorAt          time.Time
}

type RefreshStrategy string

type RemoveNetworkBinary struct {
	// RuleName is the name of the rule containing the binary.
	RuleName string
	// BinaryPath is the filesystem path of the binary to remove.
	BinaryPath string
}

type RemoveNetworkEndpoint struct {
	// RuleName is the name of the rule containing the endpoint.
	RuleName string
	// Host is the endpoint host to remove.
	Host string
	// Port is the endpoint port to remove.
	Port uint32
}

type RemoveNetworkRule struct {
	// RuleName is the name of the rule to remove.
	RuleName string
}

type ResumeOptions struct {
	// RestartIfRestoreFails lets the isolation backend boot the workload
	// cleanly when it cannot restore the retained memory state. When false,
	// resume fails instead.
	RestartIfRestoreFails bool
}

type RetryPolicy struct {
	MaxRetries  int
	InitialWait time.Duration
	MaxWait     time.Duration
}

type SSHSession struct {
	// SandboxID is the sandbox this session connects to.
	SandboxID string
	// Token is the session token for gateway tunnel authentication.
	// This is a sensitive credential — treat it like an API key.
	Token string
	// GatewayHost is the host for SSH proxy connection.
	GatewayHost string
	// GatewayPort is the gateway port (1-65535).
	GatewayPort uint32
	// GatewayScheme is the gateway protocol scheme ("http" or "https").
	GatewayScheme string
	// HostKeyFingerprint is the optional host key fingerprint.
	HostKeyFingerprint string
	// ExpiresAtMs is the session expiry in milliseconds since epoch.
	// Zero means no expiry.
	ExpiresAtMs int64
}

type Sandbox struct {
	// HostKeyFingerprint is the stable SSH identity; empty on older runtimes.
	HostKeyFingerprint          string
	ID                          string
	Name                        string
	CreatedAt                   time.Time
	Labels                      map[string]string
	Annotations                 map[string]string
	ResourceVersion             uint64
	Workspace                   string
	DeletionTimestamp           *time.Time
	CreatedFromWorkloadTemplate *SandboxWorkloadTemplateProvenance
	Spec                        SandboxSpec
	Status                      SandboxStatus
	// ServiceURLs is populated by create operations and keyed by service name.
	// The empty key identifies the unnamed service.
	ServiceURLs map[string]string
}

type SandboxCondition struct {
	Type               string
	Status             string
	Reason             string
	Message            string
	LastTransitionTime string
}

type SandboxConfig struct {
	// Policy is the typed security policy for this sandbox. Nil means no policy in the response.
	Policy *SandboxPolicy
	// PolicyVersion is monotonically increasing per sandbox.
	PolicyVersion uint32
	// PolicyHash is the SHA-256 of the serialized policy payload.
	PolicyHash string
	// Settings is the effective settings resolved for this sandbox.
	Settings map[string]EffectiveSetting
	// ConfigRevision is the fingerprint for effective config (policy + settings).
	ConfigRevision uint64
	// PolicySource indicates where the policy came from (sandbox or global).
	PolicySource PolicySource
	// GlobalPolicyVersion is the global policy version (0 if not applicable).
	GlobalPolicyVersion uint32
	// ProviderEnvRevision is the fingerprint for provider credential inputs.
	ProviderEnvRevision uint64
	// PolicyValidationFailureMode is the gateway-configured posture for rejected
	// policy generations ("fail_closed" or "retain_last_valid").
	PolicyValidationFailureMode string
}

type SandboxConfigurationAdmission struct {
	State               ConfigurationAdmissionState
	PolicyVersion       uint32
	PolicyHash          string
	ConfigRevision      uint64
	ProviderEnvRevision uint64
	Error               string
}

type SandboxGPURequirements struct {
	Count *uint32
}

type SandboxPhase string

type SandboxPolicy struct {
	// Version is the policy version number. The server may override this on write.
	Version uint32
	// Filesystem controls which directories the sandbox can access.
	// Nil means no filesystem policy is specified.
	Filesystem *FilesystemPolicy
	// Landlock configures the Linux Landlock LSM.
	// Nil means no landlock policy is specified.
	Landlock *LandlockPolicy
	// Process controls the user and group identity for sandboxed processes.
	// Nil means no process policy is specified.
	Process *ProcessPolicy
	// NetworkPolicies contains named network access rules.
	// Nil means no network policies are specified; an empty map is distinct from nil.
	NetworkPolicies map[string]NetworkPolicyRule
	// NetworkMiddlewares contains named middleware pipeline configurations for
	// network egress. Nil means no middleware is specified; an empty map is distinct from nil.
	NetworkMiddlewares map[string]NetworkMiddlewareConfig
}

type SandboxPolicyRevision struct {
	// Version is the policy version (monotonically increasing per sandbox).
	Version uint32
	// PolicyHash is the SHA-256 hash of the serialized policy payload.
	PolicyHash string
	// Status is the load status of this revision.
	Status PolicyLoadStatus
	// LoadError is the error message if status is Failed.
	LoadError string
	// CreatedAt is when this revision was created.
	CreatedAt time.Time
	// LoadedAt is when this revision was loaded by the sandbox.
	LoadedAt time.Time
	// Policy is the typed security policy for this revision. Nil when not requested or absent.
	Policy *SandboxPolicy
	// Provenance is immutable metadata supplied with this policy revision.
	Provenance map[string]string
}

type SandboxResources struct {
	CPU    string
	Memory string
	// GPU requests GPU resources for template-backed sandboxes. A non-nil GPU
	// with nil Count requests the active driver's default GPU assignment.
	GPU *SandboxGPURequirements
}

type SandboxRestartPolicy string

type SandboxServiceLevel struct {
	Startup *SandboxStartup
}

type SandboxSpec struct {
	LogLevel    string
	Environment map[string]string
	Template    *SandboxTemplate
	Providers   []string
	// GPU requests GPU resources using the active driver's default GPU assignment
	// when GPUCount is nil. GPUCount implies GPU for backward compatibility.
	GPU      bool
	GPUCount *uint32
	// Policy is the security policy for the sandbox. Nil means no policy specified.
	Policy        *SandboxPolicy
	Command       []string
	TTY           bool
	RestartPolicy SandboxRestartPolicy
}

type SandboxStartup struct {
	ReadyWithin time.Duration
	MaxBurst    uint32
}

type SandboxStatus struct {
	AgentPod             string
	AgentFd              string
	SandboxFd            string
	Phase                SandboxPhase
	Conditions           []SandboxCondition
	CurrentPolicyVersion uint32
	ExitCode             *int32
	// EndpointStatuses describes configured external tool endpoints and their
	// last accepted network results, independently of sandbox readiness.
	EndpointStatuses []EndpointStatus
	// LastTokenGrantFailure is the latest classified grant refusal for any
	// destination, including requests outside the MCP endpoint inventory.
	// A successful grant for the same destination and provider/credential clears
	// it. Before credential selection, any successful grant to that destination
	// clears it. Policy, provider, and session resets also clear it.
	// Nil means no retained cause.
	LastTokenGrantFailure  *TokenGrantFailureObservation
	ConfigurationAdmission *SandboxConfigurationAdmission
	RestartCount           uint32
	NextRestartAtMs        int64
	MainProcessStartedAtMs int64
}

type SandboxTemplate struct {
	Image            string
	RuntimeClassName string
	AgentSocket      string
	Labels           map[string]string
	Annotations      map[string]string
	Environment      map[string]string
	UserNamespaces   *bool
	Resources        map[string]any
	DriverConfig     map[string]any
}

type SandboxWorkloadConfig struct {
	Image       string
	Environment map[string]string
	Resources   *SandboxResources
}

type SandboxWorkloadTemplate struct {
	ID                string
	Name              string
	CreatedAt         time.Time
	Labels            map[string]string
	Annotations       map[string]string
	ResourceVersion   uint64
	Workspace         string
	DeletionTimestamp *time.Time
	Spec              SandboxWorkloadTemplateSpec
}

type SandboxWorkloadTemplateProvenance struct {
	Name            string
	ResourceVersion string
}

type SandboxWorkloadTemplateSpec struct {
	Workload            *SandboxWorkloadConfig
	DriverConfig        map[string]any
	DesiredServiceLevel *SandboxServiceLevel
}

type ServiceAuthorizationMode int32

type ServiceEndpoint struct {
	ID                string
	SandboxID         string
	Sandbox           string
	Name              string
	TargetPort        uint32
	Domain            bool
	URL               string
	Workspace         string
	AuthorizationMode ServiceAuthorizationMode
}

type ServiceExposure struct {
	Service           string
	TargetPort        uint32
	AuthorizationMode ServiceAuthorizationMode
}

type ServiceStatus string

type SettingScope string

type SettingValue struct {
	Type      SettingValueType
	StringVal string
	BoolVal   bool
	IntVal    int64
	BytesVal  []byte
}

type SettingValueType string

type StatusError struct {
	Code    ErrorCode
	Message string
	Cause   error
	// GRPCCode retains the exact transport code before SDK classification.
	GRPCCode int32
	// FieldViolations identifies invalid request fields without parsing Message.
	FieldViolations []FieldViolation
	// ErrorInfo is the server's machine-readable reason, domain, and metadata.
	ErrorInfo *ErrorInfo
	// RetryDelay is a suggested minimum delay, not proof a mutation is safe to repeat.
	RetryDelay *time.Duration
}

type StreamType string

type TLSConfig struct {
	CertFile string
	KeyFile  string
	CAFile   string
	Insecure bool
}

type TokenGrantAudienceOverride struct {
	Host     string
	Port     uint32
	Path     string
	Audience string
	Scopes   []string
}

type TokenGrantFailureObservation struct {
	DestinationHost string
	DestinationPort uint32
	Failure         *EndpointFailure
}

type TokenGrantSubjectToken struct {
	Source           string
	Credential       string
	SubjectTokenType string
}

type UndoResult struct {
	// PolicyVersion is the new policy version after removal.
	PolicyVersion uint32
	// PolicyHash is the SHA-256 hash of the updated policy.
	PolicyHash string
}

type UpdateResult struct {
	Diagnostics []ProfileDiagnostic
	Profile     *ProviderProfile
	Updated     bool
}

type WaitOptions struct {
	PollInterval time.Duration
}

type WatchInterface[T any] interface {
	ResultChan() <-chan Event[T]
	Stop()
}

type WatchOptions struct {
	// StopOnTerminal causes the watch to close automatically when the sandbox
	// reaches a terminal phase (Ready or Error).
	StopOnTerminal bool
}

type Workspace struct {
	ID                string
	Name              string
	CreatedAt         time.Time
	Labels            map[string]string
	Annotations       map[string]string
	ResourceVersion   uint64
	Workspace         string
	DeletionTimestamp *time.Time
	Phase             WorkspacePhase
}

type WorkspaceMember struct {
	ID               string
	Name             string
	CreatedAt        time.Time
	Labels           map[string]string
	Annotations      map[string]string
	ResourceVersion  uint64
	PrincipalSubject string
	Role             WorkspaceRole
}

type WorkspacePhase string

type WorkspaceRole string