operator

package
v1.55.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 20, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CleanupSession 

func CleanupSession(agentID string) error

CleanupSession cleans up a browser session

func ConnectCDP added in v1.39.0 

func ConnectCDP(parentCtx context.Context, session *BrowserSession) error

ConnectCDP establishes a CDP WebSocket connection for a session. Called after a provider returns a ConnectURL.

func ConnectToSession added in v1.51.0 

func ConnectToSession(agentID, sessionID string) error

ConnectToSession fetches session details from the provider and caches the session so HandleComputerToolWithContext can use it. For BrowserEngine: commands go via REST (POST /sessions/{id}/commands), no CDP. For CDP-native providers (Steel, Browserbase): establishes CDP WebSocket.

func CreateSessionWithData 

func CreateSessionWithData(agentID string, initialURL string, proxyEnabled bool, proxyCountry string) (string, map[string]interface{}, error)

CreateSessionWithData creates a new session and returns both the session ID and full response data

func EnsureBrowserSession 

func EnsureBrowserSession(operatorConfig *config.OperatorConfig) error

EnsureBrowserSession ensures browser session is active (no-op, sessions are on-demand)

func ExecuteCDPCommand added in v1.39.0 

func ExecuteCDPCommand(ctx context.Context, session *BrowserSession, cmdType string, params map[string]interface{}) (map[string]interface{}, error)

ExecuteCDPCommand runs a browser action via CDP WebSocket. Returns results in the same format as REST commands for transparent routing.

func ExecuteVirtualCommand 

func ExecuteVirtualCommand(sessionID string, cmdType string, params map[string]interface{}) (map[string]interface{}, error)

ExecuteVirtualCommand executes a command in a browser session (no cancellation)

func ExecuteVirtualCommandWithContext added in v1.34.0 

func ExecuteVirtualCommandWithContext(ctx context.Context, sessionID string, cmdType string, params map[string]interface{}) (map[string]interface{}, error)

ExecuteVirtualCommandWithContext executes a command with cancellation support. Routes to CDP or REST depending on session state.

func GetOrCreateSession 

func GetOrCreateSession(agentID string, initialURL string, proxyEnabled bool, proxyCountry string) (string, error)

GetOrCreateSession gets existing session or creates a new one

func GetPendingURL 

func GetPendingURL() string

GetPendingURL retrieves the pending URL for the current agent

func GetStatus added in v1.42.0 

func GetStatus() map[string]interface{}

GetStatus returns the current operator/browser provider status for the debug UI.

func HandleComputerTool 

func HandleComputerTool(input map[string]interface{}) (map[string]interface{}, error)

HandleComputerTool handles Claude's computer tool requests (no cancellation)

func HandleComputerToolWithContext added in v1.34.0 

func HandleComputerToolWithContext(ctx context.Context, input map[string]interface{}) (map[string]interface{}, error)

HandleComputerToolWithContext handles Claude's computer tool requests with cancellation support

func HandleHighQualityScreenshot 

func HandleHighQualityScreenshot(fullPage bool, quality int) (map[string]interface{}, error)

HandleHighQualityScreenshot captures a high-quality screenshot with full-page support

func InitBrowserSession 

func InitBrowserSession()

InitBrowserSession initializes browser session if operator mode is enabled

func InitBrowserSessionOnEnable 

func InitBrowserSessionOnEnable(operatorConfig *config.OperatorConfig)

InitBrowserSessionOnEnable initializes browser session when operator mode is enabled via config

func SetPendingURL 

func SetPendingURL(url string)

SetPendingURL stores a URL to be used when creating the next browser session

func SetSessionID 

func SetSessionID(agentID, sessionID string)

SetSessionID injects an existing session ID into the cache for reuse. Deprecated: Use ConnectToSession instead, which fetches session details and establishes CDP.

Types

type BrowserEngineProvider added in v1.39.0 

type BrowserEngineProvider struct {
	BaseURL string // e.g., "https://api.browserengine.co"
	APIKey  string // X-API-Key header value
}

BrowserEngineProvider implements BrowserProvider for the BrowserEngine cloud service. Routes through the API with authentication, billing, and usage tracking.

func NewBrowserEngineProvider added in v1.39.0 

func NewBrowserEngineProvider(baseURL, apiKey string) *BrowserEngineProvider

NewBrowserEngineProvider creates a new BrowserEngineProvider.

func (*BrowserEngineProvider) CreateSession added in v1.39.0 

func (p *BrowserEngineProvider) CreateSession(ctx context.Context, opts SessionOptions) (*BrowserSession, error)

func (*BrowserEngineProvider) DestroySession added in v1.39.0 

func (p *BrowserEngineProvider) DestroySession(ctx context.Context, sessionID string) error

func (*BrowserEngineProvider) ExecuteCommand added in v1.42.0 

func (p *BrowserEngineProvider) ExecuteCommand(ctx context.Context, sessionID, cmdType string, params map[string]interface{}) (map[string]interface{}, error)

ExecuteCommand sends a command through the BrowserEngine API.

func (*BrowserEngineProvider) GetSession added in v1.51.0 

func (p *BrowserEngineProvider) GetSession(ctx context.Context, sessionID string) (*SessionInfo, error)

GetSession fetches a single session's details from the BrowserEngine API.

func (*BrowserEngineProvider) ListSessions added in v1.51.0 

func (p *BrowserEngineProvider) ListSessions(ctx context.Context) ([]SessionInfo, error)

ListSessions fetches active sessions from the BrowserEngine API.

func (*BrowserEngineProvider) Name added in v1.39.0 

func (p *BrowserEngineProvider) Name() string

func (*BrowserEngineProvider) ResumeSession added in v1.53.0 

func (p *BrowserEngineProvider) ResumeSession(ctx context.Context, sessionID string) (*SessionInfo, error)

ResumeSession resumes a closed/timed-out session via the BrowserEngine API. Creates a new browser instance, restores cookies/localStorage, and navigates to the stored URL. Returns the updated session info (now RUNNING with a new browser_session_id).

type BrowserProvider added in v1.39.0 

type BrowserProvider interface {
	// Name returns the provider identifier ("browserengine", "browserbase", "steel", "cdp")
	Name() string

	// CreateSession creates a browser session and returns connection metadata.
	// Sessions with a non-empty ConnectURL support direct CDP WebSocket control.
	CreateSession(ctx context.Context, opts SessionOptions) (*BrowserSession, error)

	// DestroySession terminates a browser session and cleans up resources.
	DestroySession(ctx context.Context, sessionID string) error
}

BrowserProvider abstracts browser session lifecycle. All providers create sessions (possibly via REST) and return connection info. Providers that support CDP return a ConnectURL for direct WebSocket control.

func InitProvider added in v1.39.0 

func InitProvider(operatorConfig *config.OperatorConfig) BrowserProvider

InitProvider initializes the browser provider based on config.

type BrowserSession added in v1.39.0 

type BrowserSession struct {
	ID         string                 // Provider-assigned session ID
	ConnectURL string                 // CDP WebSocket URL (empty for REST-only providers)
	StreamURL  string                 // Optional: live stream URL for viewing
	ViewURL    string                 // Optional: browser view URL
	TargetID   string                 // Optional: CDP target ID
	Provider   string                 // Provider name that created this session
	Metadata   map[string]interface{} // Extra provider-specific data
	// contains filtered or unexported fields
}

BrowserSession holds the state of a connected browser session.

func (*BrowserSession) Close added in v1.39.0 

func (s *BrowserSession) Close()

Close cleans up the CDP connection if active.

func (*BrowserSession) GetCDPContext added in v1.39.0 

func (s *BrowserSession) GetCDPContext() context.Context

GetCDPContext returns the CDP context for command execution.

func (*BrowserSession) IsConnectedCDP added in v1.39.0 

func (s *BrowserSession) IsConnectedCDP() bool

IsConnectedCDP returns true if this session has an active CDP WebSocket.

func (*BrowserSession) SetCDP added in v1.39.0 

func (s *BrowserSession) SetCDP(ctx context.Context, cancel context.CancelFunc)

SetCDP stores the CDP connection state.

type BrowserbaseProvider added in v1.39.0 

type BrowserbaseProvider struct {
	APIKey    string
	ProjectID string
	BaseURL   string // Default: "https://api.browserbase.com"
}

BrowserbaseProvider implements BrowserProvider for Browserbase (browserbase.com). Sessions are created via REST API and controlled via CDP WebSocket.

func NewBrowserbaseProvider added in v1.39.0 

func NewBrowserbaseProvider(apiKey, projectID string) *BrowserbaseProvider

NewBrowserbaseProvider creates a new BrowserbaseProvider.

func (*BrowserbaseProvider) CreateSession added in v1.39.0 

func (p *BrowserbaseProvider) CreateSession(ctx context.Context, opts SessionOptions) (*BrowserSession, error)

func (*BrowserbaseProvider) DestroySession added in v1.39.0 

func (p *BrowserbaseProvider) DestroySession(ctx context.Context, sessionID string) error

func (*BrowserbaseProvider) Name added in v1.39.0 

func (p *BrowserbaseProvider) Name() string

type CDPProvider added in v1.42.0 

type CDPProvider struct {
	URL string // e.g., "ws://localhost:9222" or "http://localhost:9222"
}

CDPProvider implements BrowserProvider for direct CDP WebSocket connections. Use this to connect to any browser exposing a Chrome DevTools Protocol endpoint.

func NewCDPProvider added in v1.42.0 

func NewCDPProvider(url string) *CDPProvider

NewCDPProvider creates a new CDPProvider.

func (*CDPProvider) CreateSession added in v1.42.0 

func (p *CDPProvider) CreateSession(ctx context.Context, opts SessionOptions) (*BrowserSession, error)

func (*CDPProvider) DestroySession added in v1.42.0 

func (p *CDPProvider) DestroySession(ctx context.Context, sessionID string) error

func (*CDPProvider) Name added in v1.42.0 

func (p *CDPProvider) Name() string

type KeyDef added in v1.39.0 

type KeyDef struct {
	Key                   string // DOM key value (e.g., "Enter", "ArrowUp", "a")
	Code                  string // DOM code value (e.g., "Enter", "ArrowUp", "KeyA")
	KeyCode               int    // Legacy keyCode
	Text                  string // Character to insert (empty for non-printable keys)
	WindowsVirtualKeyCode int    // Windows virtual key code
}

KeyDef defines a CDP key with all fields needed for DispatchKeyEvent

func ParseKeyCombo added in v1.39.0 

func ParseKeyCombo(keyStr string) (input.Modifier, KeyDef, bool)

ParseKeyCombo parses a key string like "ctrl+a", "Return", or "shift+Tab" into CDP modifier flags and a key definition.

type SessionInfo added in v1.51.0 

type SessionInfo struct {
	ID         string `json:"id"`
	Status     string `json:"status"`
	URL        string `json:"url"`
	ConnectURL string `json:"connect_url"`
	StreamURL  string `json:"stream_url"`
	DebugURL   string `json:"debug_url"`
	CreatedAt  string `json:"created_at"`
	UpdatedAt  string `json:"updated_at"`
}

SessionInfo represents a session returned by the provider's list/get API.

func ListProviderSessions added in v1.51.0 

func ListProviderSessions() ([]SessionInfo, error)

ListProviderSessions lists sessions from the active provider (if supported).

type SessionLister added in v1.51.0 

type SessionLister interface {
	ListSessions(ctx context.Context) ([]SessionInfo, error)
	GetSession(ctx context.Context, sessionID string) (*SessionInfo, error)
}

SessionLister is an optional interface for providers that support listing and fetching sessions.

type SessionOptions added in v1.39.0 

type SessionOptions struct {
	InitialURL     string
	ViewportWidth  int
	ViewportHeight int
	Proxy          bool
	ProxyCountry   string // ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "DE")
	TestMode       bool
}

SessionOptions contains parameters for session creation.

type SessionResumer added in v1.53.0 

type SessionResumer interface {
	ResumeSession(ctx context.Context, sessionID string) (*SessionInfo, error)
}

SessionResumer is an optional interface for providers that support resuming closed sessions.

type SteelProvider added in v1.39.0 

type SteelProvider struct {
	APIKey  string
	BaseURL string // Default: "https://api.steel.dev"
}

SteelProvider implements BrowserProvider for Steel.dev. Sessions are created via REST API and controlled via CDP WebSocket.

func NewSteelProvider added in v1.39.0 

func NewSteelProvider(apiKey, baseURL string) *SteelProvider

NewSteelProvider creates a new SteelProvider.

func (*SteelProvider) CreateSession added in v1.39.0 

func (p *SteelProvider) CreateSession(ctx context.Context, opts SessionOptions) (*BrowserSession, error)

func (*SteelProvider) DestroySession added in v1.39.0 

func (p *SteelProvider) DestroySession(ctx context.Context, sessionID string) error

func (*SteelProvider) Name added in v1.39.0 

func (p *SteelProvider) Name() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.