runtime

type ContainerID string

type ContainerInfo struct {
	// ID is the Docker container ID.
	ID string
	// Name is the Docker container name.
	Name string
	// Status is the current lifecycle status of the container.
	Status ContainerStatus
	// Labels are the Docker labels attached to the container.
	Labels map[string]string
	// RunID is the AgentPaaS run identifier extracted from labels.
	RunID string
	// ResourceType is the AgentPaaS resource type (agent, gateway, etc.).
	ResourceType string
}

type ContainerNetworkInfo struct {
	// ID is the Docker network ID.
	ID string
	// Name is the Docker network name.
	Name string
	// IPAddress is the container's IP on this network.
	IPAddress string
	// Aliases are network-scoped DNS aliases for the container.
	Aliases []string
}

type ContainerSpec struct {
	// Image is the container image reference (e.g., "nginx:latest").
	Image string

	// Command is the entrypoint command override for the container.
	Command []string

	// Env is a list of environment variable assignments (KEY=VALUE format).
	Env []string

	// Labels are Docker labels to apply to the container for ownership
	// tracking and reconciliation.
	Labels map[string]string

	// NetworkIDs is a list of Docker network IDs to attach the container to.
	// Multiple network IDs enable dual-homing (e.g., gateway sidecar on
	// both internal and egress networks). For single-network containers
	// (e.g., agent), pass exactly one ID.
	NetworkIDs []string

	// User is the container-internal user to run as. When empty, the runtime
	// enforces a non-root default (uid 64000). Callers may override for
	// gateway containers that need privileged operations.
	User string

	// MemoryLimitBytes is the maximum memory the container may consume, in
	// bytes. 0 means no limit (gateway containers may need more). Populated
	// from agent.yaml by the upper orchestrator.
	MemoryLimitBytes int64

	// NanoCPUs is the CPU quota in nanoseconds of CPU time per period.
	// 0 means no limit. Populated from agent.yaml by the upper orchestrator.
	NanoCPUs int64

	// Binds is a list of host-path:container-path bind mounts. Each entry
	// follows the Docker --volume format: "host_path:container_path" or
	// "host_path:container_path:ro" for read-only. Used to mount audit
	// volumes and other host directories into the container.
	Binds []string

	// CapAdd lists Linux capabilities to add after the runtime's CapDrop ALL
	// baseline. Used by the orchestrator for agent egress firewall (NET_ADMIN).
	CapAdd []string
}

type ContainerStats struct {
	// CPUPercent is the CPU usage percentage (0.0-100.0).
	CPUPercent float64

	// MemoryMB is the current memory usage in megabytes.
	MemoryMB float64

	// PIDs is the number of processes running inside the container.
	PIDs int
}

type ContainerStatus int

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

type LogOptions struct {
	// Tail is the number of recent log lines to return. 0 means all.
	Tail int

	// Follow streams log output as the container produces it.
	Follow bool

	// Since returns logs only after this timestamp.
	Since *time.Time
}

type MCPContainerInfo struct {
	ContainerID ContainerID
	ServerID    string
	RunID       string
}

type NetworkID string

type NetworkInfo struct {
	// ID is the Docker network ID.
	ID string
	// Name is the Docker network name.
	Name string
	// Internal indicates whether the network is an internal bridge (no
	// external access).
	Internal bool
	// Labels are the Docker labels attached to the network.
	Labels map[string]string
}

type NetworkSpec struct {
	// Name is the Docker network name.
	Name string

	// Internal, when true, creates an internal bridge network that has no
	// external access. The agent's internal bridge uses this to prevent
	// direct egress.
	Internal bool

	// Labels are Docker labels to apply to the network for ownership
	// tracking and reconciliation.
	Labels map[string]string
}

type RuntimeDriver interface {
	// Create provisions a new container from the given spec and returns
	// its ContainerID. The container is created but not started; call
	// Start to begin execution.
	Create(ctx context.Context, spec ContainerSpec) (ContainerID, error)

	// Start begins execution of a previously created container.
	Start(ctx context.Context, id ContainerID) error

	// Stop halts a running container. If timeout is non-nil, the runtime
	// waits at most that long for graceful shutdown before force-killing.
	Stop(ctx context.Context, id ContainerID, timeout *time.Duration) error

	// Remove deletes a container. If force is true, the container is
	// killed first if running.
	Remove(ctx context.Context, id ContainerID, force bool) error

	// Status returns the current lifecycle status of the container.
	Status(ctx context.Context, id ContainerID) (ContainerStatus, error)

	// Stats returns a snapshot of the container's resource usage.
	Stats(ctx context.Context, id ContainerID) (ContainerStats, error)

	// Logs returns a reader for the container's stdout/stderr output.
	// The caller MUST close the returned reader when done.
	Logs(ctx context.Context, id ContainerID, opts LogOptions) (io.ReadCloser, error)

	// Exec runs a command inside a running container and returns stdout, stderr,
	// and exit code. Used by the daemon to invoke the harness /invoke endpoint
	// from inside the container (the harness binds to 127.0.0.1 only).
	Exec(ctx context.Context, id ContainerID, cmd []string) (stdout, stderr string, exitCode int, err error)

	// CreateNetwork provisions a new Docker network from the given spec and
	// returns its NetworkID. An internal:true network restricts external
	// access (used for the per-agent internal bridge).
	CreateNetwork(ctx context.Context, spec NetworkSpec) (NetworkID, error)

	// RemoveNetwork deletes a Docker network. Returns ErrNetworkNotFound
	// if the network does not exist.
	RemoveNetwork(ctx context.Context, id NetworkID) error

	// InspectNetwork returns detailed information about a Docker network,
	// including its Internal flag and labels.
	InspectNetwork(ctx context.Context, id NetworkID) (NetworkInfo, error)

	// InspectContainerNetworks returns the list of networks a container is
	// attached to, with network names and IDs. Used for topology assertions.
	InspectContainerNetworks(ctx context.Context, id ContainerID) ([]ContainerNetworkInfo, error)

	// InspectContainerIP returns the IP address of a container on a specific
	// network. Returns empty string if the container is not attached to the
	// network.
	InspectContainerIP(ctx context.Context, id ContainerID, networkID string) (string, error)

	// ListContainers returns all containers matching the given label filters.
	// Each filter is a "key=value" pair. Results are returned as a slice of
	// ContainerInfo structs containing ID, name, status, and labels.
	ListContainers(ctx context.Context, labelFilters ...string) ([]ContainerInfo, error)

	// ListNetworks returns all Docker networks matching the given label filters.
	// Each filter is a "key=value" pair.
	ListNetworks(ctx context.Context, labelFilters ...string) ([]NetworkInfo, error)
}