| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194 |
- // 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
- }
|