browser

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jul 14, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package browser provides the shared local browser runtime used by Seshat tools and sessions.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config 

type Config struct {
	Headless              bool
	ExecutablePath        string
	RemoteControlURL      string
	NavigationTimeout     time.Duration
	ActionTimeout         time.Duration
	MaxPagesPerSession    int
	MaxSnapshotText       int
	MaxSnapshotElements   int
	MaxActionsPerSession  int
	MaxRepeatedAction     int
	MaxSessionAge         time.Duration
	WaitAfterNavigation   time.Duration
	LauncherLeakless      bool
	DisableDefaultBrowser bool
	ScreenshotDir         string
	MaxIdleSession        time.Duration
	SessionReaperInterval time.Duration
	ArtifactStore         storage.ArtifactStore
	MaxNetworkEntries     int
	MaxDownloadEntries    int
	DownloadDir           string
}

Config controls the local browser runtime.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns a pragmatic V1 browser configuration.

type DownloadEntry 

type DownloadEntry struct {
	GUID              string    `json:"guid"`
	PageID            string    `json:"page_id,omitempty"`
	URL               string    `json:"url"`
	SuggestedFilename string    `json:"suggested_filename,omitempty"`
	State             string    `json:"state"`
	BytesReceived     int       `json:"bytes_received,omitempty"`
	TotalBytes        int       `json:"total_bytes,omitempty"`
	PersistedPath     string    `json:"persisted_path,omitempty"`
	PersistedSize     int       `json:"persisted_size,omitempty"`
	ErrorText         string    `json:"error_text,omitempty"`
	StartedAt         time.Time `json:"started_at"`
	UpdatedAt         time.Time `json:"updated_at"`
}

DownloadEntry is a compact browser download record retained per session.

type ElementInfo 

type ElementInfo struct {
	ID           string `json:"id"`
	Role         string `json:"role,omitempty"`
	Name         string `json:"name,omitempty"`
	Text         string `json:"text,omitempty"`
	SelectorHint string `json:"selector_hint,omitempty"`
	Editable     bool   `json:"editable,omitempty"`
	Disabled     bool   `json:"disabled,omitempty"`
}

ElementInfo is an actionable element extracted from the DOM.

type HeadingInfo 

type HeadingInfo struct {
	Level int    `json:"level"`
	Text  string `json:"text"`
}

HeadingInfo is a compact semantic heading extracted from the page.

type Manager 

type Manager interface {
	EnsureSession(ctx context.Context, sessionID types.SessionID) (SessionState, error)
	OpenPage(ctx context.Context, sessionID types.SessionID, url string) (PageInfo, error)
	Navigate(ctx context.Context, sessionID types.SessionID, pageID string, url string) (PageInfo, error)
	Snapshot(ctx context.Context, sessionID types.SessionID, pageID string, options SnapshotOptions) (Snapshot, error)
	Screenshot(ctx context.Context, sessionID types.SessionID, pageID string, options ScreenshotOptions) (Screenshot, error)
	Click(ctx context.Context, sessionID types.SessionID, pageID string, elementID string, revision string) (PageInfo, error)
	Type(ctx context.Context, sessionID types.SessionID, pageID string, elementID string, revision string, text string, clear bool) (PageInfo, error)
	Press(ctx context.Context, sessionID types.SessionID, pageID string, key string) (PageInfo, error)
	Scroll(ctx context.Context, sessionID types.SessionID, pageID string, options ScrollOptions) (PageInfo, error)
	Wait(ctx context.Context, sessionID types.SessionID, pageID string, options WaitOptions) (PageInfo, error)
	ListPages(ctx context.Context, sessionID types.SessionID) ([]PageInfo, error)
	ListNetwork(ctx context.Context, sessionID types.SessionID, pageID string, limit int) ([]NetworkEntry, error)
	ListDownloads(ctx context.Context, sessionID types.SessionID, pageID string, limit int) ([]DownloadEntry, error)
	SearchSnapshots(ctx context.Context, sessionID types.SessionID, query string, limit int) ([]SnapshotSearchHit, error)
	GetNetworkPolicy(ctx context.Context, sessionID types.SessionID) (NetworkPolicy, error)
	SetNetworkPolicy(ctx context.Context, sessionID types.SessionID, policy NetworkPolicy) (NetworkPolicy, error)
	SelectPage(ctx context.Context, sessionID types.SessionID, pageID string) (PageInfo, error)
	ClosePage(ctx context.Context, sessionID types.SessionID, pageID string) (SessionState, error)
	CloseSession(ctx context.Context, sessionID types.SessionID) error
	Close() error
}

Manager owns browser lifecycle, per-session isolation, and page operations.

func DefaultManager 

func DefaultManager() Manager

DefaultManager returns the process-wide lazy browser manager.

type NetworkEntry 

type NetworkEntry struct {
	Seq          int64     `json:"seq"`
	PageID       string    `json:"page_id,omitempty"`
	URL          string    `json:"url"`
	Method       string    `json:"method,omitempty"`
	ResourceType string    `json:"resource_type,omitempty"`
	StatusCode   int       `json:"status_code,omitempty"`
	MimeType     string    `json:"mime_type,omitempty"`
	Stage        string    `json:"stage"`
	ErrorText    string    `json:"error_text,omitempty"`
	Timestamp    time.Time `json:"timestamp"`
}

NetworkEntry is a compact browser network activity record retained per session.

type NetworkPolicy 

type NetworkPolicy struct {
	BlockedURLs    []string `json:"blocked_urls,omitempty"`
	ResourcePolicy string   `json:"resource_policy,omitempty"`
}

NetworkPolicy is a session-scoped browser request policy. V2 intentionally uses URL blocking heuristics instead of full request rewriting so it stays lightweight and safe inside the mono-runtime.

type PageInfo 

type PageInfo struct {
	ID        string    `json:"id"`
	URL       string    `json:"url"`
	Title     string    `json:"title,omitempty"`
	Active    bool      `json:"active"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

PageInfo is browser-visible page metadata.

type RodManager 

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

RodManager manages a shared Chrome instance with per-session incognito contexts.

func NewManager 

func NewManager(config *Config) *RodManager

NewManager creates a new Rod-backed browser manager.

func (*RodManager) Click 

func (m *RodManager) Click(ctx context.Context, sessionID types.SessionID, pageID string, elementID string, revision string) (PageInfo, error)

Click activates a snapshot-backed interactive element on the page.

func (*RodManager) Close 

func (m *RodManager) Close() error

Close releases all browser resources owned by this manager.

func (*RodManager) ClosePage 

func (m *RodManager) ClosePage(ctx context.Context, sessionID types.SessionID, pageID string) (SessionState, error)

ClosePage closes a page and updates the session active page pointer.

func (*RodManager) CloseSession 

func (m *RodManager) CloseSession(ctx context.Context, sessionID types.SessionID) error

CloseSession tears down the isolated session browser context.

func (*RodManager) EnsureSession 

func (m *RodManager) EnsureSession(ctx context.Context, sessionID types.SessionID) (SessionState, error)

EnsureSession creates browser state for a Seshat session when needed.

func (*RodManager) GetNetworkPolicy 

func (m *RodManager) GetNetworkPolicy(ctx context.Context, sessionID types.SessionID) (NetworkPolicy, error)

GetNetworkPolicy returns the current session-scoped request policy.

func (*RodManager) ListDownloads 

func (m *RodManager) ListDownloads(ctx context.Context, sessionID types.SessionID, pageID string, limit int) ([]DownloadEntry, error)

ListDownloads returns recent download activity for the selected page or whole session.

func (*RodManager) ListNetwork 

func (m *RodManager) ListNetwork(ctx context.Context, sessionID types.SessionID, pageID string, limit int) ([]NetworkEntry, error)

ListNetwork returns recent network activity for the selected page or whole session.

func (*RodManager) ListPages 

func (m *RodManager) ListPages(ctx context.Context, sessionID types.SessionID) ([]PageInfo, error)

ListPages returns metadata for pages in the session context.

func (*RodManager) Navigate 

func (m *RodManager) Navigate(ctx context.Context, sessionID types.SessionID, pageID string, target string) (PageInfo, error)

Navigate loads the provided URL into an existing page.

func (*RodManager) OpenPage 

func (m *RodManager) OpenPage(ctx context.Context, sessionID types.SessionID, target string) (PageInfo, error)

OpenPage opens a new page within the session's isolated browser context.

func (*RodManager) Press 

func (m *RodManager) Press(ctx context.Context, sessionID types.SessionID, pageID string, key string) (PageInfo, error)

Press sends a keyboard key to the page.

func (*RodManager) Screenshot 

func (m *RodManager) Screenshot(ctx context.Context, sessionID types.SessionID, pageID string, options ScreenshotOptions) (Screenshot, error)

Screenshot captures the selected page as a base64-encoded PNG payload.

func (*RodManager) Scroll 

func (m *RodManager) Scroll(ctx context.Context, sessionID types.SessionID, pageID string, options ScrollOptions) (PageInfo, error)

Scroll moves the page viewport by a directional amount.

func (*RodManager) SearchSnapshots 

func (m *RodManager) SearchSnapshots(ctx context.Context, sessionID types.SessionID, query string, limit int) ([]SnapshotSearchHit, error)

SearchSnapshots searches previously captured snapshot content across pages in one session. This is a lightweight V3 primitive for agentic cross-tab recall without adding a vector store.

func (*RodManager) SelectPage 

func (m *RodManager) SelectPage(ctx context.Context, sessionID types.SessionID, pageID string) (PageInfo, error)

SelectPage marks an existing page as active for subsequent page-less operations.

func (*RodManager) SetNetworkPolicy 

func (m *RodManager) SetNetworkPolicy(ctx context.Context, sessionID types.SessionID, policy NetworkPolicy) (NetworkPolicy, error)

SetNetworkPolicy updates the current session-scoped request policy and applies it to every existing page immediately so future navigations follow the same rules.

func (*RodManager) Snapshot 

func (m *RodManager) Snapshot(ctx context.Context, sessionID types.SessionID, pageID string, options SnapshotOptions) (Snapshot, error)

Snapshot returns a compact text + element snapshot of the selected page.

func (*RodManager) Type 

func (m *RodManager) Type(ctx context.Context, sessionID types.SessionID, pageID string, elementID string, revision string, text string, clear bool) (PageInfo, error)

Type writes text into a snapshot-backed editable element.

func (*RodManager) Wait 

func (m *RodManager) Wait(ctx context.Context, sessionID types.SessionID, pageID string, options WaitOptions) (PageInfo, error)

Wait blocks until the page stabilizes and optionally contains text.

type Screenshot 

type Screenshot struct {
	Page          PageInfo  `json:"page"`
	MimeType      string    `json:"mime_type"`
	DataBase64    string    `json:"data_base64"`
	Bytes         int       `json:"bytes"`
	PersistedPath string    `json:"persisted_path,omitempty"`
	PersistedSize int       `json:"persisted_size,omitempty"`
	FullPage      bool      `json:"full_page"`
	TakenAt       time.Time `json:"taken_at"`
}

Screenshot is a compact image capture payload for the current page.

type ScreenshotOptions 

type ScreenshotOptions struct {
	FullPage bool `json:"full_page,omitempty"`
}

ScreenshotOptions controls page screenshot capture.

type ScrollOptions 

type ScrollOptions struct {
	Direction string `json:"direction,omitempty"`
	Amount    int    `json:"amount,omitempty"`
}

ScrollOptions controls page scrolling interactions.

type SessionState 

type SessionState struct {
	SessionID    types.SessionID `json:"session_id"`
	ActivePageID string          `json:"active_page_id,omitempty"`
	PageCount    int             `json:"page_count"`
	ActionCount  int             `json:"action_count"`
	CreatedAt    time.Time       `json:"created_at"`
	LastActivity time.Time       `json:"last_activity,omitempty"`
}

SessionState describes the browser state attached to one Seshat session.

type Snapshot 

type Snapshot struct {
	Page      PageInfo      `json:"page"`
	Revision  string        `json:"revision,omitempty"`
	Text      string        `json:"text"`
	Elements  []ElementInfo `json:"elements,omitempty"`
	Headings  []HeadingInfo `json:"headings,omitempty"`
	TakenAt   time.Time     `json:"taken_at"`
	Truncated bool          `json:"truncated,omitempty"`
}

Snapshot is a compact agent-facing view of a page.

type SnapshotOptions 

type SnapshotOptions struct {
	MaxText     int `json:"max_text,omitempty"`
	MaxElements int `json:"max_elements,omitempty"`
}

SnapshotOptions controls browser snapshot extraction.

type SnapshotSearchHit 

type SnapshotSearchHit struct {
	PageID            string    `json:"page_id"`
	URL               string    `json:"url"`
	Title             string    `json:"title,omitempty"`
	Revision          string    `json:"revision,omitempty"`
	Score             int       `json:"score"`
	Snippet           string    `json:"snippet,omitempty"`
	LastSnapshottedAt time.Time `json:"last_snapshotted_at,omitempty"`
}

SnapshotSearchHit represents a lightweight cross-page search result over previously captured browser snapshots inside one session.

type WaitOptions 

type WaitOptions struct {
	TimeoutMs int    `json:"timeout_ms,omitempty"`
	Text      string `json:"text,omitempty"`
}

WaitOptions controls page stabilization and content waits.

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.