// Package api defines engine-neutral browser contracts. package api import ( "context" "encoding/json" "fmt" "time" ) // Owner is supplied by the trusted host, never by model arguments. type Owner struct { EnvironmentID string `json:"environmentId"` ThreadID string `json:"threadId"` RunID string `json:"runId"` SSHSessionID string `json:"sshSessionId,omitempty"` } func (o Owner) Valid() bool { return o.EnvironmentID != "" && o.ThreadID != "" && o.RunID != "" } type Capability struct { Status string `json:"status"` Reason string `json:"reason,omitempty"` } type Capabilities struct { Engine string `json:"engine"` Platform string `json:"platform"` Features map[string]Capability `json:"features"` } func (c Capabilities) Supports(name string) bool { return c.Features[name].Status == "supported" } // Error preserves a stable code without exposing native stack traces. type Error struct { Code string `json:"code"` Message string `json:"message"` Effect string `json:"effect,omitempty"` Cause error `json:"-"` } func (e *Error) Unwrap() error { return e.Cause } func (e *Error) Error() string { return e.Code + ": " + e.Message } func Err(code, message string) error { return &Error{Code: code, Message: message} } type EngineOptions struct { Headless bool Executable string NoSandbox bool DownloadDir string ViewportWidth int ViewportHeight int MaxDownloadBytes int64 } // Driver starts a dedicated engine session with no access to host credentials. type Driver interface { Probe(context.Context) (Capabilities, error) Open(context.Context, EngineOptions) (EngineSession, error) } type Download struct { ID string `json:"id"` Name string `json:"name"` State string `json:"state"` Bytes int64 `json:"bytes"` // Path is trusted-host metadata and is removed from model-facing results. Path string `json:"-"` } type EngineSession interface { NewPage(context.Context) (EnginePage, error) Downloads() []Download Close() error } // EnginePage exposes trusted evaluation only to the SDK, not to agent tools. type EnginePage interface { Navigate(context.Context, string, string) (string, error) Evaluate(context.Context, string) (json.RawMessage, error) Input(context.Context, string, string, float64, float64) error Capture(context.Context) ([]byte, error) Close() error } // FullPageCapturer is optional so existing third-party drivers remain compatible. type FullPageCapturer interface { CaptureFullPage(context.Context) ([]byte, error) } type SessionInfo struct { ID string `json:"id"` Owner Owner `json:"owner"` Engine string `json:"engine"` Pages []string `json:"pages"` Created time.Time `json:"created"` } type PageInfo struct { SessionID string `json:"sessionId"` PageID string `json:"pageId"` URL string `json:"url,omitempty"` } type Element struct { Ref string `json:"ref"` Role string `json:"role"` Name string `json:"name"` Value string `json:"value,omitempty"` Disabled bool `json:"disabled,omitempty"` Checked bool `json:"checked,omitempty"` } type SnapshotRequest struct { Mode string `json:"mode,omitempty"` MaxBytes int `json:"maxBytes,omitempty"` MaxElements int `json:"maxElements,omitempty"` } type Snapshot struct { PageID string `json:"pageId"` SnapshotID string `json:"snapshotId"` DocumentID string `json:"documentId"` URL string `json:"url"` Title string `json:"title"` Kind string `json:"kind"` Text string `json:"text,omitempty"` Elements []Element `json:"elements"` Truncated bool `json:"truncated"` Scanned int `json:"scanned"` } type ActionRequest struct { SnapshotID string `json:"snapshotId"` Ref string `json:"ref"` Action string `json:"action"` Value string `json:"value,omitempty"` } type ActionResult struct { Effect string `json:"effect"` InputKind string `json:"inputKind"` } type ReadRequest struct { SnapshotID string `json:"snapshotId,omitempty"` Ref string `json:"ref,omitempty"` Mode string `json:"mode,omitempty"` MaxBytes int `json:"maxBytes,omitempty"` } type ReadResult struct { URL string `json:"url"` Text string `json:"text,omitempty"` Rows [][]string `json:"rows,omitempty"` Truncated bool `json:"truncated"` } type WaitRequest struct { Kind string `json:"kind"` Value string `json:"value,omitempty"` TimeoutMS int `json:"timeoutMs,omitempty"` } type FileInfo struct { ID string `json:"id"` Name string `json:"name"` MIME string `json:"mime"` Size int64 `json:"size"` SHA256 string `json:"sha256"` } func ValidateAction(r ActionRequest) error { if r.Ref == "" || r.SnapshotID == "" { return Err("BROWSER_INVALID_ARGUMENT", "snapshotId and ref are required") } switch r.Action { case "click", "hover", "fill", "type", "select", "check", "uncheck": case "press": switch r.Value { case "Enter", "Tab", "Escape", "ArrowDown", "ArrowUp", "Backspace": default: return Err("BROWSER_INVALID_ARGUMENT", "unsupported key") } case "scroll": if r.Value != "up" && r.Value != "down" { return Err("BROWSER_INVALID_ARGUMENT", "scroll value must be up or down") } default: return Err("BROWSER_INVALID_ARGUMENT", fmt.Sprintf("unsupported action %q", r.Action)) } if len(r.Value) > 16384 { return Err("BROWSER_INVALID_ARGUMENT", "action value exceeds 16 KiB") } return nil }