types.go 5.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194
  1. // Package api defines engine-neutral browser contracts.
  2. package api
  3. import (
  4. "context"
  5. "encoding/json"
  6. "fmt"
  7. "time"
  8. )
  9. // Owner is supplied by the trusted host, never by model arguments.
  10. type Owner struct {
  11. EnvironmentID string `json:"environmentId"`
  12. ThreadID string `json:"threadId"`
  13. RunID string `json:"runId"`
  14. SSHSessionID string `json:"sshSessionId,omitempty"`
  15. }
  16. func (o Owner) Valid() bool { return o.EnvironmentID != "" && o.ThreadID != "" && o.RunID != "" }
  17. type Capability struct {
  18. Status string `json:"status"`
  19. Reason string `json:"reason,omitempty"`
  20. }
  21. type Capabilities struct {
  22. Engine string `json:"engine"`
  23. Platform string `json:"platform"`
  24. Features map[string]Capability `json:"features"`
  25. }
  26. func (c Capabilities) Supports(name string) bool { return c.Features[name].Status == "supported" }
  27. // Error preserves a stable code without exposing native stack traces.
  28. type Error struct {
  29. Code string `json:"code"`
  30. Message string `json:"message"`
  31. Effect string `json:"effect,omitempty"`
  32. Cause error `json:"-"`
  33. }
  34. func (e *Error) Unwrap() error { return e.Cause }
  35. func (e *Error) Error() string { return e.Code + ": " + e.Message }
  36. func Err(code, message string) error { return &Error{Code: code, Message: message} }
  37. type EngineOptions struct {
  38. Headless bool
  39. Executable string
  40. NoSandbox bool
  41. DownloadDir string
  42. ViewportWidth int
  43. ViewportHeight int
  44. MaxDownloadBytes int64
  45. }
  46. // Driver starts a dedicated engine session with no access to host credentials.
  47. type Driver interface {
  48. Probe(context.Context) (Capabilities, error)
  49. Open(context.Context, EngineOptions) (EngineSession, error)
  50. }
  51. type Download struct {
  52. ID string `json:"id"`
  53. Name string `json:"name"`
  54. State string `json:"state"`
  55. Bytes int64 `json:"bytes"`
  56. // Path is trusted-host metadata and is removed from model-facing results.
  57. Path string `json:"-"`
  58. }
  59. type EngineSession interface {
  60. NewPage(context.Context) (EnginePage, error)
  61. Downloads() []Download
  62. Close() error
  63. }
  64. // EnginePage exposes trusted evaluation only to the SDK, not to agent tools.
  65. type EnginePage interface {
  66. Navigate(context.Context, string, string) (string, error)
  67. Evaluate(context.Context, string) (json.RawMessage, error)
  68. Input(context.Context, string, string, float64, float64) error
  69. Capture(context.Context) ([]byte, error)
  70. Close() error
  71. }
  72. // FullPageCapturer is optional so existing third-party drivers remain compatible.
  73. type FullPageCapturer interface {
  74. CaptureFullPage(context.Context) ([]byte, error)
  75. }
  76. type SessionInfo struct {
  77. ID string `json:"id"`
  78. Owner Owner `json:"owner"`
  79. Engine string `json:"engine"`
  80. Pages []string `json:"pages"`
  81. Created time.Time `json:"created"`
  82. }
  83. type PageInfo struct {
  84. SessionID string `json:"sessionId"`
  85. PageID string `json:"pageId"`
  86. URL string `json:"url,omitempty"`
  87. }
  88. type Element struct {
  89. Ref string `json:"ref"`
  90. Role string `json:"role"`
  91. Name string `json:"name"`
  92. Value string `json:"value,omitempty"`
  93. Disabled bool `json:"disabled,omitempty"`
  94. Checked bool `json:"checked,omitempty"`
  95. }
  96. type SnapshotRequest struct {
  97. Mode string `json:"mode,omitempty"`
  98. MaxBytes int `json:"maxBytes,omitempty"`
  99. MaxElements int `json:"maxElements,omitempty"`
  100. }
  101. type Snapshot struct {
  102. PageID string `json:"pageId"`
  103. SnapshotID string `json:"snapshotId"`
  104. DocumentID string `json:"documentId"`
  105. URL string `json:"url"`
  106. Title string `json:"title"`
  107. Kind string `json:"kind"`
  108. Text string `json:"text,omitempty"`
  109. Elements []Element `json:"elements"`
  110. Truncated bool `json:"truncated"`
  111. Scanned int `json:"scanned"`
  112. }
  113. type ActionRequest struct {
  114. SnapshotID string `json:"snapshotId"`
  115. Ref string `json:"ref"`
  116. Action string `json:"action"`
  117. Value string `json:"value,omitempty"`
  118. }
  119. type ActionResult struct {
  120. Effect string `json:"effect"`
  121. InputKind string `json:"inputKind"`
  122. }
  123. type ReadRequest struct {
  124. SnapshotID string `json:"snapshotId,omitempty"`
  125. Ref string `json:"ref,omitempty"`
  126. Mode string `json:"mode,omitempty"`
  127. MaxBytes int `json:"maxBytes,omitempty"`
  128. }
  129. type ReadResult struct {
  130. URL string `json:"url"`
  131. Text string `json:"text,omitempty"`
  132. Rows [][]string `json:"rows,omitempty"`
  133. Truncated bool `json:"truncated"`
  134. }
  135. type WaitRequest struct {
  136. Kind string `json:"kind"`
  137. Value string `json:"value,omitempty"`
  138. TimeoutMS int `json:"timeoutMs,omitempty"`
  139. }
  140. type FileInfo struct {
  141. ID string `json:"id"`
  142. Name string `json:"name"`
  143. MIME string `json:"mime"`
  144. Size int64 `json:"size"`
  145. SHA256 string `json:"sha256"`
  146. }
  147. func ValidateAction(r ActionRequest) error {
  148. if r.Ref == "" || r.SnapshotID == "" {
  149. return Err("BROWSER_INVALID_ARGUMENT", "snapshotId and ref are required")
  150. }
  151. switch r.Action {
  152. case "click", "hover", "fill", "type", "select", "check", "uncheck":
  153. case "press":
  154. switch r.Value {
  155. case "Enter", "Tab", "Escape", "ArrowDown", "ArrowUp", "Backspace":
  156. default:
  157. return Err("BROWSER_INVALID_ARGUMENT", "unsupported key")
  158. }
  159. case "scroll":
  160. if r.Value != "up" && r.Value != "down" {
  161. return Err("BROWSER_INVALID_ARGUMENT", "scroll value must be up or down")
  162. }
  163. default:
  164. return Err("BROWSER_INVALID_ARGUMENT", fmt.Sprintf("unsupported action %q", r.Action))
  165. }
  166. if len(r.Value) > 16384 {
  167. return Err("BROWSER_INVALID_ARGUMENT", "action value exceeds 16 KiB")
  168. }
  169. return nil
  170. }