Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

37.9 KB
Raw Blame
// Copyright 2026 The OpenSandbox Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// Package opensandbox provides Go client libraries for the OpenSandbox
// Lifecycle, Egress, and Execd APIs.
package opensandbox

import (
	"encoding/json"
	"fmt"
	"strings"
	"time"
	"unicode"
	"unicode/utf8"
)

// SandboxState represents the high-level lifecycle state of a sandbox.
type SandboxState string

const (
	StatePending    SandboxState = "Pending"
	StateRunning    SandboxState = "Running"
	StatePausing    SandboxState = "Pausing"
	StatePaused     SandboxState = "Paused"
	StateStopping   SandboxState = "Stopping"
	StateTerminated SandboxState = "Terminated"
	StateFailed     SandboxState = "Failed"
)

// SandboxStatus provides detailed status information with lifecycle state
// and transition details.
type SandboxStatus struct {
	State            SandboxState `json:"state"`
	Reason           string       `json:"reason,omitempty"`
	Message          string       `json:"message,omitempty"`
	LastTransitionAt *time.Time   `json:"lastTransitionAt,omitempty"`
}

// ImageSpec describes the container image used to provision a sandbox.
type ImageSpec struct {
	URI  string     `json:"uri"`
	Auth *ImageAuth `json:"auth,omitempty"`
}

// ImageAuth holds registry authentication credentials for private images.
type ImageAuth struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

// PlatformOS is the target operating system of a sandbox platform constraint.
// The wire-level enum is enforced server-side; the constants below mirror the
// spec so Go callers can avoid stringly-typed typos.
type PlatformOS string

const (
	OSLinux   PlatformOS = "linux"
	OSWindows PlatformOS = "windows"
)

// PlatformArch is the target CPU architecture of a sandbox platform
// constraint.
type PlatformArch string

const (
	ArchAMD64 PlatformArch = "amd64"
	ArchARM64 PlatformArch = "arm64"
)

// PlatformSpec is a runtime platform constraint used for scheduling and
// provisioning. It is independent from Image and expresses the expected
// target OS and CPU architecture for sandbox execution.
//
// When omitted, the server applies its own default platform selection
// behavior. When provided, the runtime must satisfy the constraint or the
// request fails.
//
// See specs/sandbox-lifecycle.yml#/components/schemas/PlatformSpec.
type PlatformSpec struct {
	OS   PlatformOS   `json:"os"`
	Arch PlatformArch `json:"arch"`
}

// ResourceLimits defines runtime resource constraints as key-value pairs.
// Common keys: "cpu" (e.g. "500m"), "memory" (e.g. "512Mi"), "gpu" (e.g. "1").
type ResourceLimits map[string]string

// Volume defines a storage mount for a sandbox.
type Volume struct {
	Name      string `json:"name"`
	Host      *Host  `json:"host,omitempty"`
	PVC       *PVC   `json:"pvc,omitempty"`
	OSSFS     *OSSFS `json:"ossfs,omitempty"`
	MountPath string `json:"mountPath"`
	ReadOnly  bool   `json:"readOnly,omitempty"`
	SubPath   string `json:"subPath,omitempty"`
}

// Host represents a host path bind mount backend.
type Host struct {
	Path string `json:"path"`
}

// PVC represents a platform-managed named volume backend.
type PVC struct {
	ClaimName                  string   `json:"claimName"`
	CreateIfNotExists          *bool    `json:"createIfNotExists,omitempty"`
	DeleteOnSandboxTermination *bool    `json:"deleteOnSandboxTermination,omitempty"`
	StorageClass               *string  `json:"storageClass,omitempty"`
	Storage                    *string  `json:"storage,omitempty"`
	AccessModes                []string `json:"accessModes,omitempty"`
}

// OSSFS represents an Alibaba Cloud OSS mount backend via ossfs.
type OSSFS struct {
	Bucket          string   `json:"bucket"`
	Endpoint        string   `json:"endpoint"`
	Version         string   `json:"version,omitempty"`
	Options         []string `json:"options,omitempty"`
	AccessKeyID     string   `json:"accessKeyId"`
	AccessKeySecret string   `json:"accessKeySecret"`
}

// NetworkPolicy defines the egress network policy for a sandbox.
type NetworkPolicy struct {
	DefaultAction string        `json:"defaultAction,omitempty"`
	Egress        []NetworkRule `json:"egress,omitempty"`
}

// NetworkRule defines a single egress allow/deny rule.
//
// Target may be a FQDN, wildcard domain ("*.example.com"), IP, or CIDR. It
// may be omitted when Ports is set: the rule then scopes by TCP destination
// port alone, across all IPv4/IPv6 destinations. A domain Target combined
// with Ports is rejected by the server/sidecar (domain rules have no port
// dimension). Port limits enforced server-side (this SDK does not
// pre-validate): each port 1-65535, at most 256 ports per rule, no
// duplicates.
type NetworkRule struct {
	Action string `json:"action"`
	Target string `json:"target,omitempty"`
	Ports  []int  `json:"ports,omitempty"`
}

// CredentialProxyConfig enables Credential Vault transparent proxy support at
// sandbox startup.
type CredentialProxyConfig struct {
	Enabled bool `json:"enabled"`
}

// LifecycleHook is a command executed before the sandbox entrypoint starts.
type LifecycleHook struct {
	Command        []string `json:"command"`
	TimeoutSeconds *int     `json:"timeoutSeconds,omitempty"`
}

// PeriodicLifecycleHook is a named command scheduled while the sandbox is running.
type PeriodicLifecycleHook struct {
	Name           string   `json:"name"`
	Schedule       string   `json:"schedule"`
	Command        []string `json:"command"`
	TimeoutSeconds *int     `json:"timeoutSeconds,omitempty"`
}

// OnIdlePause is the only idle action supported today (OSEP-0024). The value
// exists as a named constant so future actions are additive.
const OnIdlePause = "pause"

const (
	// IdleTimeoutMinSeconds is the smallest accepted idle threshold X.
	IdleTimeoutMinSeconds = 30
	// IdleTimeoutMaxSeconds is the largest accepted idle threshold X.
	IdleTimeoutMaxSeconds = 86400
	// ProbeTimeoutMinSeconds is the smallest accepted activity probe timeout.
	ProbeTimeoutMinSeconds = 1
	// ProbeTimeoutMaxSeconds is the largest accepted activity probe timeout.
	ProbeTimeoutMaxSeconds = 10
	// RenewExtendMinSeconds is the smallest accepted renew-on-access
	// extension window (OSEP-0009).
	RenewExtendMinSeconds = 300
	// RenewExtendMaxSeconds is the largest accepted renew-on-access
	// extension window (OSEP-0009).
	RenewExtendMaxSeconds = 86400
)

// ActivityProbe is an application-declared activity probe (OSEP-0024).
//
// Endpoint inside the sandbox that answers {"active": bool, "message"?: string}
// with 200 while work is in progress. When the sandbox is otherwise idle, the
// server issues GET Path on Port; a busy answer counts as activity and resets
// the idle clock, while an explicit "not active", any failure, or a timeout
// records nothing.
type ActivityProbe struct {
	Port int `json:"port"`
	// Path is the absolute HTTP path of the probe endpoint. Must start with
	// "/" and must not contain whitespace or control characters.
	Path string `json:"path"`
	// TimeoutSeconds is the probe request budget in seconds (1-10). The
	// server defaults to 2 when omitted.
	TimeoutSeconds *int `json:"timeoutSeconds,omitempty"`
}

// IdlePolicy declares the idle behavior of a sandbox (OSEP-0024, fast-sandbox
// only).
//
// With IdleTimeoutSeconds, the sandbox is auto-paused after that many seconds
// without ingress-observed activity. Without it, the policy is wake-only: the
// sandbox is never auto-paused, but a (manually) paused sandbox wakes on
// access. Omitting the whole policy preserves non-automated behavior exactly.
type IdlePolicy struct {
	// IdleTimeoutSeconds is the idle threshold X in seconds (30-86400):
	// the sandbox is auto-paused after X continuously idle seconds.
	// Required together with OnIdle; absent together with it means a
	// wake-only policy.
	IdleTimeoutSeconds *int `json:"idleTimeoutSeconds,omitempty"`
	// OnIdle is the action taken at the idle threshold. Only OnIdlePause
	// exists today. Required with, and only valid with,
	// IdleTimeoutSeconds.
	OnIdle string `json:"onIdle,omitempty"`
	// WakeOnAccess controls whether incoming traffic may wake the sandbox
	// from Paused. Defaults to true when omitted.
	WakeOnAccess *bool `json:"wakeOnAccess,omitempty"`
	// ActiveProbe is the application-declared activity probe (relevant
	// only with auto-pause).
	ActiveProbe *ActivityProbe `json:"activeProbe,omitempty"`
}

// Validate checks the idle policy against the server's create-time rules so
// invalid policies fail fast client-side.
func (p *IdlePolicy) Validate() error {
	if p == nil {
		return nil
	}
	hasTimeout := p.IdleTimeoutSeconds != nil
	if hasTimeout {
		t := *p.IdleTimeoutSeconds
		if t < IdleTimeoutMinSeconds || t > IdleTimeoutMaxSeconds {
			return &InvalidArgumentError{
				Field:   "IdleTimeoutSeconds",
				Message: fmt.Sprintf("must be an integer between %d and %d, got %d", IdleTimeoutMinSeconds, IdleTimeoutMaxSeconds, t),
			}
		}
	}
	if p.OnIdle != "" {
		if !hasTimeout {
			return &InvalidArgumentError{
				Field:   "OnIdle",
				Message: "must be omitted when IdleTimeoutSeconds is omitted (a policy without a timeout is wake-only)",
			}
		}
		if p.OnIdle != OnIdlePause {
			return &InvalidArgumentError{Field: "OnIdle", Message: fmt.Sprintf("must be %q, got %q", OnIdlePause, p.OnIdle)}
		}
	} else if hasTimeout {
		return &InvalidArgumentError{Field: "OnIdle", Message: "is required when IdleTimeoutSeconds is set"}
	}
	if p.ActiveProbe != nil {
		if !hasTimeout {
			return &InvalidArgumentError{
				Field:   "ActiveProbe",
				Message: "requires IdleTimeoutSeconds; the probe is relevant only with auto-pause",
			}
		}
		if p.ActiveProbe.Port < 1 || p.ActiveProbe.Port > 65535 {
			return &InvalidArgumentError{
				Field:   "ActiveProbe.Port",
				Message: fmt.Sprintf("must be an integer between 1 and 65535, got %d", p.ActiveProbe.Port),
			}
		}
		path := p.ActiveProbe.Path
		if path == "" {
			return &InvalidArgumentError{Field: "ActiveProbe.Path", Message: "must be a non-empty absolute HTTP path"}
		}
		if utf8.RuneCountInString(path) > 512 {
			return &InvalidArgumentError{Field: "ActiveProbe.Path", Message: "must not exceed 512 characters"}
		}
		if !strings.HasPrefix(path, "/") {
			return &InvalidArgumentError{Field: "ActiveProbe.Path", Message: "must be an absolute HTTP path starting with '/'"}
		}
		if strings.IndexFunc(path, func(r rune) bool {
			return unicode.IsSpace(r) || r < 0x20 || r == 0x7f
		}) >= 0 {
			return &InvalidArgumentError{Field: "ActiveProbe.Path", Message: "must not contain whitespace or control characters"}
		}
		if t := p.ActiveProbe.TimeoutSeconds; t != nil && (*t < ProbeTimeoutMinSeconds || *t > ProbeTimeoutMaxSeconds) {
			return &InvalidArgumentError{
				Field:   "ActiveProbe.TimeoutSeconds",
				Message: fmt.Sprintf("must be an integer between %d and %d, got %d", ProbeTimeoutMinSeconds, ProbeTimeoutMaxSeconds, *t),
			}
		}
	}
	return nil
}

// RenewalPolicy declares the renew-on-access behavior of a sandbox
// (OSEP-0009): observed access moves the expiration to
// max(now + ExtendSeconds, current). Control-plane policy; supersedes the
// deprecated extensions["access.renew.extend.seconds"] key.
type RenewalPolicy struct {
	// ExtendSeconds is the extension window X in seconds (300-86400) for
	// each access-driven renewal.
	ExtendSeconds int `json:"extendSeconds"`
}

// Validate checks the renewal policy against the server's create-time rules
// so invalid policies fail fast client-side.
func (p *RenewalPolicy) Validate() error {
	if p == nil {
		return nil
	}
	if p.ExtendSeconds < RenewExtendMinSeconds || p.ExtendSeconds > RenewExtendMaxSeconds {
		return &InvalidArgumentError{
			Field:   "ExtendSeconds",
			Message: fmt.Sprintf("must be an integer between %d and %d, got %d", RenewExtendMinSeconds, RenewExtendMaxSeconds, p.ExtendSeconds),
		}
	}
	return nil
}

// SandboxLifecycle contains optional lifecycle configuration applied during
// sandbox creation.
type SandboxLifecycle struct {
	PreStart *LifecycleHook          `json:"preStart,omitempty"`
	Periodic []PeriodicLifecycleHook `json:"periodic,omitempty"`
	// IdlePolicy is the auto-pause and wake-on-access behavior (OSEP-0024).
	// Supported only by the fast-sandbox backend; other backends reject the
	// field. Control-plane policy: it never reaches the guest.
	IdlePolicy *IdlePolicy `json:"idlePolicy,omitempty"`
	// RenewalPolicy is the renew-on-access behavior (OSEP-0009).
	// Control-plane policy; supersedes the deprecated
	// extensions["access.renew.extend.seconds"] key.
	RenewalPolicy *RenewalPolicy `json:"renewalPolicy,omitempty"`
}

// CreateSandboxRequest is the request body for creating a new sandbox.
type CreateSandboxRequest struct {
	Image      *ImageSpec `json:"image,omitempty"`
	SnapshotID string     `json:"snapshotId,omitempty"`
	// TemplateID creates the sandbox from a Succeeded fsb template. It is
	// mutually exclusive with Image and SnapshotID; in template mode the
	// workload shape is fixed by the template's golden image, so only
	// Metadata, NetworkPolicy and Extensions may accompany it, and Timeout
	// is required.
	TemplateID       string                 `json:"templateId,omitempty"`
	Timeout          *int                   `json:"timeout,omitempty"`
	ResourceLimits   ResourceLimits         `json:"resourceLimits"`
	ResourceRequests ResourceLimits         `json:"resourceRequests,omitempty"`
	Env              map[string]string      `json:"env,omitempty"`
	SecureAccess     bool                   `json:"secureAccess,omitempty"`
	Metadata         map[string]string      `json:"metadata,omitempty"`
	Lifecycle        *SandboxLifecycle      `json:"lifecycle,omitempty"`
	Entrypoint       []string               `json:"entrypoint,omitempty"`
	NetworkPolicy    *NetworkPolicy         `json:"networkPolicy,omitempty"`
	CredentialProxy  *CredentialProxyConfig `json:"credentialProxy,omitempty"`
	Volumes          []Volume               `json:"volumes,omitempty"`
	Extensions       map[string]string      `json:"extensions,omitempty"`
	Platform         *PlatformSpec          `json:"platform,omitempty"`
}

// AllocationMode identifies how the runtime allocated a sandbox.
type AllocationMode string

const (
	// AllocationModePool indicates that the sandbox was allocated from a pool.
	AllocationModePool AllocationMode = "pool"
)

// AllocationState describes the confirmed allocation state of a sandbox.
type AllocationState string

const (
	// AllocationStateAllocated indicates that the pool allocation is active.
	AllocationStateAllocated AllocationState = "allocated"
)

// AllocationSummary is the public summary of a confirmed active pool
// allocation. It is present only when the runtime confirms an active pool
// allocation.
type AllocationSummary struct {
	Mode    AllocationMode  `json:"mode"`
	PoolRef string          `json:"poolRef"`
	State   AllocationState `json:"state"`
}

// SandboxInfo represents a runtime execution environment provisioned from a
// container image, as returned by the lifecycle API.
type SandboxInfo struct {
	ID         string             `json:"id"`
	Image      *ImageSpec         `json:"image,omitempty"`
	SnapshotID string             `json:"snapshotId,omitempty"`
	Status     SandboxStatus      `json:"status"`
	Metadata   map[string]string  `json:"metadata,omitempty"`
	Extensions map[string]string  `json:"extensions,omitempty"`
	Entrypoint []string           `json:"entrypoint"`
	ExpiresAt  *time.Time         `json:"expiresAt,omitempty"`
	CreatedAt  time.Time          `json:"createdAt"`
	Platform   *PlatformSpec      `json:"platform,omitempty"`
	Allocation *AllocationSummary `json:"allocation,omitempty"`
}

type SnapshotState string

const (
	SnapshotStateCreating SnapshotState = "Creating"
	SnapshotStateDeleting SnapshotState = "Deleting"
	SnapshotStateReady    SnapshotState = "Ready"
	SnapshotStateFailed   SnapshotState = "Failed"
)

type SnapshotStatus struct {
	State            SnapshotState `json:"state"`
	Reason           string        `json:"reason,omitempty"`
	Message          string        `json:"message,omitempty"`
	LastTransitionAt *time.Time    `json:"lastTransitionAt,omitempty"`
}

type SnapshotInfo struct {
	ID        string         `json:"id"`
	SandboxID string         `json:"sandboxId"`
	Name      string         `json:"name,omitempty"`
	Status    SnapshotStatus `json:"status"`
	CreatedAt time.Time      `json:"createdAt"`
}

type CreateSnapshotRequest struct {
	Name string `json:"name,omitempty"`
}

// PaginationInfo contains pagination metadata for list responses.
type PaginationInfo struct {
	Page        int  `json:"page"`
	PageSize    int  `json:"pageSize"`
	TotalItems  int  `json:"totalItems"`
	TotalPages  int  `json:"totalPages"`
	HasNextPage bool `json:"hasNextPage"`
}

// ListSandboxesResponse is the paginated response from listing sandboxes.
type ListSandboxesResponse struct {
	Items      []SandboxInfo  `json:"items"`
	Pagination PaginationInfo `json:"pagination"`
}

// MetadataPatch is the request body for patching sandbox metadata.
// Non-nil values add or replace keys. Nil values delete keys.
type MetadataPatch map[string]*string

type ListSnapshotsResponse struct {
	Items      []SnapshotInfo `json:"items"`
	Pagination PaginationInfo `json:"pagination"`
}

type ListSnapshotsOptions struct {
	SandboxID string
	Name      string
	States    []SnapshotState
	Page      int
	PageSize  int
}

// Endpoint describes a public access endpoint for a service running inside
// a sandbox.
type Endpoint struct {
	Endpoint string            `json:"endpoint"`
	Headers  map[string]string `json:"headers,omitempty"`
	// Origin is the sandbox origin reported by the server's
	// OPEN-SANDBOX-ORIGIN response header (see SandboxOrigin). Empty when
	// the server does not send it.
	Origin SandboxOrigin `json:"-"`
}

// SandboxOrigin describes what backs a sandbox.
//
// The protocol currently defines a single meaningful value:
// SandboxOriginTemplate, reported by the server via the
// OPEN-SANDBOX-ORIGIN response header on endpoint lookups and set locally
// when the sandbox was explicitly created from a template. Template-backed
// sandboxes have no sandbox-side egress sidecar: egress policy operations
// go through the lifecycle control plane. Anything else means the sandbox
// is not template-backed.
//
// The set of origin values may grow in future versions; treat a missing or
// unknown origin as "not template-backed".
//
// See specs/sandbox-lifecycle.yml#/components/headers/SandboxOrigin.
type SandboxOrigin string

const (
	// SandboxOriginTemplate indicates the sandbox runs on a fsb
	// golden-image template.
	SandboxOriginTemplate SandboxOrigin = "template"

	// SandboxOriginUnknown indicates the origin could not be determined
	// (created from an image or snapshot, or an older server that does not
	// send the origin header).
	SandboxOriginUnknown SandboxOrigin = "unknown"
)

// SandboxOriginHeader is the lifecycle response header that reports a
// sandbox's origin on endpoint lookups.
const SandboxOriginHeader = "Open-Sandbox-Origin"

// TemplatePhase is the high-level lifecycle phase of a fsb template build.
// The server may introduce new phases in future versions; handle unknown
// values gracefully.
type TemplatePhase string

const (
	// TemplatePhasePending indicates the build was accepted but not started.
	TemplatePhasePending TemplatePhase = "Pending"
	// TemplatePhaseBuilding indicates the golden-image build is in progress.
	TemplatePhaseBuilding TemplatePhase = "Building"
	// TemplatePhaseSucceeded indicates the build finished; the template can
	// back sandbox creation.
	TemplatePhaseSucceeded TemplatePhase = "Succeeded"
	// TemplatePhaseFailed indicates the build failed; see
	// TemplateStatus.Message.
	TemplatePhaseFailed TemplatePhase = "Failed"
)

// TemplateFormat is the storage encoding of a template's produced snapshot
// set.
type TemplateFormat string

const (
	// TemplateFormatNative stores raw snapshots.
	TemplateFormatNative TemplateFormat = "native"
	// TemplateFormatOverlayBD stores overlaybd snapshots (server default).
	TemplateFormatOverlayBD TemplateFormat = "overlaybd"
)

// TemplateReadiness is the build-side readiness gate for a fsb template.
type TemplateReadiness struct {
	// Probe is checked first during the golden-image build;
	// e.g. "tcp://127.0.0.1:44772" or "cmd://<command>".
	Probe string `json:"probe,omitempty"`
	// WarmupSeconds is the fallback warmup window in seconds (default 60).
	WarmupSeconds *int `json:"warmupSeconds,omitempty"`
}

// TemplateStatus is the build status of a fsb template.
type TemplateStatus struct {
	Phase TemplatePhase `json:"phase"`
	// ManifestRef is the published S3 manifest reference or immutable OCI reference;
	// present when the phase is Succeeded.
	ManifestRef string `json:"manifestRef,omitempty"`
	// Message is the failure reason when the phase is Failed.
	Message string `json:"message,omitempty"`
}

// CreateTemplateRequest is the request body for creating a fsb (fast-sandbox)
// template: a golden-image build.
//
// The build runs asynchronously: the response starts at
// TemplatePhasePending; poll GetTemplate until the phase is Succeeded (or
// Failed). Kernel, execd and guest init are server-side build inputs, not
// client fields.
type CreateTemplateRequest struct {
	// Image is the source OCI image reference the golden image is built from.
	Image string `json:"image"`
	// Publish is s3://bucket/publish (native) or oci://registry/repository
	// (overlaybd, without a tag or digest).
	Publish string `json:"publish"`
	// ResourceLimits is the guest machine sizing, e.g.
	// {"cpu": "1", "memory": "512Mi", "disk": "2Gi"}. Server defaults when
	// omitted: cpu "1", memory "512Mi", disk "2Gi".
	ResourceLimits ResourceLimits `json:"resourceLimits,omitempty"`
	// Entrypoint is the guest business command (argv); empty defaults to
	// ["tail", "-f", "/dev/null"].
	Entrypoint []string `json:"entrypoint,omitempty"`
	// Env is the environment variables baked into the golden image (injected
	// as /etc/sandbox-init.env in the guest; literal values only). The source
	// image's own OCI Config.Env is inherited; an env with the same name
	// overrides the inherited value. Names must be valid shell variable names.
	Env map[string]string `json:"env,omitempty"`
	// Metadata is custom key-value metadata for management, filtering, and
	// tagging.
	Metadata map[string]string `json:"metadata,omitempty"`
	// Readiness is the build-side readiness gate.
	Readiness *TemplateReadiness `json:"readiness,omitempty"`
	// Format is the storage encoding of the produced snapshot set. Defaults
	// to overlaybd.
	Format TemplateFormat `json:"format,omitempty"`
}

// TemplateInfo is a fsb template: a golden image whose build is declared and
// executed by fast-sandbox.
type TemplateInfo struct {
	TemplateID string         `json:"templateId"`
	Image      string         `json:"image"`
	Publish    string         `json:"publish"`
	Format     TemplateFormat `json:"format"`
	Status     TemplateStatus `json:"status"`
	CreatedAt  time.Time      `json:"createdAt"`
	UpdatedAt  time.Time      `json:"updatedAt"`

	ResourceLimits ResourceLimits     `json:"resourceLimits,omitempty"`
	Entrypoint     []string           `json:"entrypoint,omitempty"`
	Env            map[string]string  `json:"env,omitempty"`
	Metadata       map[string]string  `json:"metadata,omitempty"`
	Readiness      *TemplateReadiness `json:"readiness,omitempty"`
}

// ListTemplatesOptions configures filtering and pagination for ListTemplates.
type ListTemplatesOptions struct {
	// Metadata filters by key-value metadata (AND logic).
	Metadata map[string]string
	// Page number (1-based). Defaults to 1.
	Page int
	// PageSize is the number of items per page (1-200). Defaults to 20.
	PageSize int
}

// ListTemplatesResponse is the paginated response from listing templates.
type ListTemplatesResponse struct {
	Items      []TemplateInfo `json:"items"`
	Pagination PaginationInfo `json:"pagination"`
}

// RenewExpirationRequest is the request body for renewing sandbox expiration.
type RenewExpirationRequest struct {
	ExpiresAt time.Time `json:"expiresAt"`
}

// RenewExpirationResponse is the response from renewing sandbox expiration.
type RenewExpirationResponse struct {
	ExpiresAt time.Time `json:"expiresAt"`
}

// PolicyStatusResponse is the response from the egress policy endpoints.
type PolicyStatusResponse struct {
	Status          string         `json:"status,omitempty"`
	Mode            string         `json:"mode,omitempty"`
	EnforcementMode string         `json:"enforcementMode,omitempty"`
	Reason          string         `json:"reason,omitempty"`
	Policy          *NetworkPolicy `json:"policy,omitempty"`
}

// CredentialSourceType is the credential source discriminator.
type CredentialSourceType string

const (
	// CredentialSourceInline carries write-only inline credential material.
	CredentialSourceInline CredentialSourceType = "inline"
	// CredentialSourceExchange resolves headers per request from a resolver endpoint; no local material.
	CredentialSourceExchange CredentialSourceType = "exchange"
)

// CredentialSource is a Credential Vault credential source: inline material
// (Value) or a resolver endpoint (Endpoint), never both.
type CredentialSource struct {
	Type     CredentialSourceType `json:"type,omitempty"`
	Value    string               `json:"value,omitempty"`
	Endpoint string               `json:"endpoint,omitempty"`
}

// InlineCredentialSource is an alias of CredentialSource for inline-only callers.
type InlineCredentialSource = CredentialSource

// MarshalJSON defaults the type for the zero-value forms: Value only →
// inline, Endpoint only → exchange.
func (s CredentialSource) MarshalJSON() ([]byte, error) {
	type credentialSource CredentialSource
	source := credentialSource(s)
	if source.Type == "" {
		if source.Endpoint != "" && source.Value == "" {
			source.Type = CredentialSourceExchange
		} else {
			source.Type = CredentialSourceInline
		}
	}
	return json.Marshal(source)
}

// Credential is a sandbox-local Credential Vault credential create/update
// model.
type Credential struct {
	Name   string           `json:"name"`
	Source CredentialSource `json:"source"`
}

// CredentialScheme is a request scheme matched by a Credential Vault binding.
type CredentialScheme string

const (
	CredentialSchemeHTTPS CredentialScheme = "https"
	CredentialSchemeHTTP  CredentialScheme = "http"
)

// CredentialMatch selects outbound requests where a Credential Vault binding
// applies.
type CredentialMatch struct {
	Schemes []CredentialScheme `json:"schemes,omitempty"`
	// Deprecated: Ports is ignored; port is derived from Schemes (https→443, http→80).
	Ports   []int    `json:"ports,omitempty"`
	Hosts   []string `json:"hosts"`
	Methods []string `json:"methods,omitempty"`
	Paths   []string `json:"paths,omitempty"`
}

// CustomHeaderEntry describes one custom header injection rule.
type CustomHeaderEntry struct {
	Name       string `json:"name"`
	Credential string `json:"credential"`
}

// CredentialSubstitutionSurface is a request surface where a Credential Vault
// placeholder may be replaced.
type CredentialSubstitutionSurface string

const (
	CredentialSubstitutionPath   CredentialSubstitutionSurface = "path"
	CredentialSubstitutionQuery  CredentialSubstitutionSurface = "query"
	CredentialSubstitutionHeader CredentialSubstitutionSurface = "header"
	CredentialSubstitutionBody   CredentialSubstitutionSurface = "body"
)

// CredentialSubstitution describes one scoped literal placeholder replacement.
type CredentialSubstitution struct {
	Credential  string                          `json:"credential"`
	Placeholder string                          `json:"placeholder"`
	In          []CredentialSubstitutionSurface `json:"in"`
}

// CredentialAuthType is the Credential Vault auth discriminator.
type CredentialAuthType string

const (
	CredentialAuthBearer        CredentialAuthType = "bearer"
	CredentialAuthBasic         CredentialAuthType = "basic"
	CredentialAuthAPIKey        CredentialAuthType = "apiKey"
	CredentialAuthCustomHeaders CredentialAuthType = "customHeaders"
	CredentialAuthPassthrough   CredentialAuthType = "passthrough"
)

// CredentialAuth configures how a binding injects credential material.
// Static kinds set Type; the typeless exchange form sets only Credential.
type CredentialAuth struct {
	Type          CredentialAuthType       `json:"type,omitempty"`
	Credential    string                   `json:"credential,omitempty"`
	Name          string                   `json:"name,omitempty"`
	Headers       []CustomHeaderEntry      `json:"headers,omitempty"`
	Substitutions []CredentialSubstitution `json:"substitutions,omitempty"`
}

// CredentialBinding is a sandbox-local Credential Vault binding create/update
// model.
type CredentialBinding struct {
	Name  string          `json:"name"`
	Match CredentialMatch `json:"match"`
	Auth  CredentialAuth  `json:"auth"`
}

// CredentialVaultCreateRequest creates the initial sandbox-local Credential
// Vault revision.
type CredentialVaultCreateRequest struct {
	Credentials []Credential        `json:"credentials"`
	Bindings    []CredentialBinding `json:"bindings"`
}

// CredentialMutationSet describes atomic credential changes for a vault patch.
type CredentialMutationSet struct {
	Add     []Credential `json:"add,omitempty"`
	Replace []Credential `json:"replace,omitempty"`
	Delete  []string     `json:"delete,omitempty"`
}

// CredentialBindingMutationSet describes atomic binding changes for a vault
// patch.
type CredentialBindingMutationSet struct {
	Add     []CredentialBinding `json:"add,omitempty"`
	Replace []CredentialBinding `json:"replace,omitempty"`
	Delete  []string            `json:"delete,omitempty"`
}

// CredentialVaultPatchRequest atomically mutates credentials and bindings. If
// ExpectedRevision is set, the sidecar applies it as an optimistic concurrency
// guard.
type CredentialVaultPatchRequest struct {
	ExpectedRevision *int                          `json:"expectedRevision,omitempty"`
	Credentials      *CredentialMutationSet        `json:"credentials,omitempty"`
	Bindings         *CredentialBindingMutationSet `json:"bindings,omitempty"`
}

// CredentialMetadata is sanitized credential metadata returned by Credential
// Vault. It intentionally does not include source values; SourceType is
// `inline` or `exchange`.
type CredentialMetadata struct {
	Name       string `json:"name"`
	SourceType string `json:"sourceType"`
	Revision   int    `json:"revision"`
}

// CredentialAuthMetadata is sanitized auth metadata. Static kinds carry
// Type (Name for apiKey); the typeless form carries only Credential.
type CredentialAuthMetadata struct {
	Type       string `json:"type,omitempty"`
	Name       string `json:"name,omitempty"`
	Credential string `json:"credential,omitempty"`
}

// MarshalJSON enforces the sanitized shape symmetrically: credential only
// when typeless, name only when typed.
func (m CredentialAuthMetadata) MarshalJSON() ([]byte, error) {
	type credentialAuthMetadata CredentialAuthMetadata
	out := credentialAuthMetadata(m)
	if out.Type != "" {
		out.Credential = ""
	} else {
		out.Name = ""
	}
	return json.Marshal(out)
}

// CredentialBindingMetadata is sanitized binding metadata returned by
// Credential Vault.
type CredentialBindingMetadata struct {
	Name     string                  `json:"name"`
	Revision int                     `json:"revision"`
	Match    *CredentialMatch        `json:"match,omitempty"`
	Auth     *CredentialAuthMetadata `json:"auth,omitempty"`
}

// CredentialVaultState is sanitized Credential Vault state.
type CredentialVaultState struct {
	Revision    int                         `json:"revision"`
	Credentials []CredentialMetadata        `json:"credentials"`
	Bindings    []CredentialBindingMetadata `json:"bindings"`
}

// CredentialListResponse is the credential metadata list response.
type CredentialListResponse struct {
	Revision    int                  `json:"revision"`
	Credentials []CredentialMetadata `json:"credentials"`
}

// CredentialBindingListResponse is the binding metadata list response.
type CredentialBindingListResponse struct {
	Revision int                         `json:"revision"`
	Bindings []CredentialBindingMetadata `json:"bindings"`
}

// ErrorResponse is the standard error response for non-2xx HTTP responses.
type ErrorResponse struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

// APIError wraps an ErrorResponse with the HTTP status code and retry metadata.
type APIError struct {
	StatusCode int
	RequestID  string
	Response   ErrorResponse

	// RetryAfter is the server-suggested wait duration from the Retry-After
	// header. Zero means no suggestion was provided.
	RetryAfter time.Duration

	// WakeExpired reports whether this 503 carried the gateway-owned
	// "OpenSandbox-Wake: expired" marker (OSEP-0024): the request was parked
	// pre-forward and is safe to retry for any method.
	WakeExpired bool

	// RetryAfterPresent reports whether a parseable Retry-After header was
	// on the response; when false, RetryAfter is zero and consumers apply
	// their own default wait.
	RetryAfterPresent bool
}

// Error implements the error interface.
func (e *APIError) Error() string {
	msg := fmt.Sprintf("%s: %s", e.Response.Code, e.Response.Message)
	if e.RequestID != "" {
		msg += fmt.Sprintf(" (request_id: %s)", e.RequestID)
	}
	return msg
}

// Execd types are hand-written: execd uses SSE streaming, multipart upload, and
// text responses that do not fit this SDK's higher-level API ergonomics.

// CodeContext represents a code execution context identifier and language.
type CodeContext struct {
	ID       string `json:"id,omitempty"`
	Language string `json:"language"`
}

// CreateContextRequest is the request body for creating a code execution context.
type CreateContextRequest struct {
	Language string `json:"language"`
}

// RunCodeRequest is the request body for executing code in a context.
type RunCodeRequest struct {
	Context *CodeContext `json:"context,omitempty"`
	Code    string       `json:"code"`
}

// Session represents a bash session with a unique identifier.
type Session struct {
	ID string `json:"session_id"`
}

// CreateSessionRequest is the optional request body for creating a bash session.
type CreateSessionRequest struct {
	Cwd string `json:"cwd,omitempty"`
}

// RunCommandRequest executes exactly one of Command (shell text) or Argv (literal arguments).
type RunCommandRequest struct {
	Command string `json:"command,omitempty"`
	// Argv must contain a non-empty executable at index 0; no element may contain NUL.
	// These constraints are validated by the server.
	Argv []string `json:"argv,omitempty"`
	Cwd  string   `json:"cwd,omitempty"`
	// Background runs the command asynchronously when true.
	Background bool `json:"background,omitempty"`
	// Timeout is the maximum command duration in milliseconds. Zero omits the
	// field and the server enforces no timeout (see execd-api.yaml). Note this
	// differs from the second-based TimeoutSeconds fields elsewhere in the SDK.
	Timeout int64             `json:"timeout,omitempty"`
	UID     *int32            `json:"uid,omitempty"`
	GID     *int32            `json:"gid,omitempty"`
	Envs    map[string]string `json:"envs,omitempty"`
}

// RunInSessionRequest is the request body for running a command in an existing bash session.
type RunInSessionRequest struct {
	Command string `json:"command"`
	Cwd     string `json:"cwd,omitempty"`
	// Timeout is the maximum command duration in milliseconds. Zero omits the
	// field and the server may not enforce any timeout (see execd-api.yaml).
	Timeout int64 `json:"timeout,omitempty"`
}

// CommandStatusResponse contains the status of a command execution.
type CommandStatusResponse struct {
	ID         string     `json:"id"`
	Content    string     `json:"content"`
	Running    bool       `json:"running"`
	ExitCode   *int32     `json:"exit_code,omitempty"`
	Error      string     `json:"error,omitempty"`
	StartedAt  time.Time  `json:"started_at"`
	FinishedAt *time.Time `json:"finished_at,omitempty"`
}

// CommandLogsResponse contains the stdout/stderr output and cursor for
// incremental log polling.
type CommandLogsResponse struct {
	Output string
	Cursor int64
}

// FileInfo contains file metadata including path and permissions.
type FileInfo struct {
	Path       string    `json:"path"`
	Type       string    `json:"type,omitempty"`
	Size       int64     `json:"size"`
	ModifiedAt time.Time `json:"modified_at"`
	CreatedAt  time.Time `json:"created_at"`
	Owner      string    `json:"owner"`
	Group      string    `json:"group"`
	Mode       int       `json:"mode"`
}

// Permission defines file ownership and mode settings.
type Permission struct {
	Owner string `json:"owner,omitempty"`
	Group string `json:"group,omitempty"`
	Mode  int    `json:"mode"`
}

// PermissionsRequest maps file paths to their desired permission settings.
type PermissionsRequest map[string]Permission

// MoveItem defines a single file move/rename operation.
type MoveItem struct {
	Src  string `json:"src"`
	Dest string `json:"dest"`
}

// MoveRequest is a list of file move/rename operations.
type MoveRequest []MoveItem

// ReplaceItem defines a text replacement operation for a single file.
type ReplaceItem struct {
	Old string `json:"old"`
	New string `json:"new"`
}

// ReplaceRequest maps file paths to their replacement operations.
type ReplaceRequest map[string]ReplaceItem

// ReplaceResult holds the result of a content replacement for a single file.
type ReplaceResult struct {
	ReplacedCount int `json:"replacedCount"`
}

// ReplaceResponse maps file paths to their replacement results.
type ReplaceResponse map[string]ReplaceResult

// FileMetadata is the metadata sent alongside file uploads.
type FileMetadata struct {
	Path  string `json:"path"`
	Owner string `json:"owner,omitempty"`
	Group string `json:"group,omitempty"`
	Mode  int    `json:"mode,omitempty"`
}

// Metrics contains system resource usage metrics.
type Metrics struct {
	CPUCount   float64 `json:"cpu_count"`
	CPUUsedPct float64 `json:"cpu_used_pct"`
	MemTotalMB float64 `json:"mem_total_mib"`
	MemUsedMB  float64 `json:"mem_used_mib"`
	Timestamp  int64   `json:"timestamp"`
}