agentdesktop

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

type Desktop interface {
	// Start launches the desktop session. It is idempotent — calling
	// Start on an already-running session returns the existing
	// config. The returned DisplayConfig describes the running
	// session.
	Start(ctx context.Context) (DisplayConfig, error)

	// VNCConn dials the desktop's VNC server and returns a raw
	// net.Conn carrying RFB binary frames. Each call returns a new
	// connection; multiple clients can connect simultaneously.
	// Start must be called before VNCConn.
	VNCConn(ctx context.Context) (net.Conn, error)

	// Screenshot captures the current framebuffer as a PNG and
	// returns it base64-encoded. TargetWidth/TargetHeight in opts
	// are the desired output dimensions (the implementation
	// rescales); pass 0 to use native resolution.
	Screenshot(ctx context.Context, opts ScreenshotOptions) (ScreenshotResult, error)

	// Move moves the mouse cursor to absolute coordinates.
	Move(ctx context.Context, x, y int) error
	// Click performs a mouse button click at the given coordinates.
	Click(ctx context.Context, x, y int, button MouseButton) error
	// DoubleClick performs a double-click at the given coordinates.
	DoubleClick(ctx context.Context, x, y int, button MouseButton) error
	// ButtonDown presses and holds a mouse button.
	ButtonDown(ctx context.Context, button MouseButton) error
	// ButtonUp releases a mouse button.
	ButtonUp(ctx context.Context, button MouseButton) error
	// Scroll scrolls by (dx, dy) clicks at the given coordinates.
	Scroll(ctx context.Context, x, y, dx, dy int) error
	// Drag moves from (startX,startY) to (endX,endY) while holding
	// the left mouse button.
	Drag(ctx context.Context, startX, startY, endX, endY int) error

	// KeyPress sends a key-down then key-up for a key combo string
	// (e.g. "Return", "ctrl+c").
	KeyPress(ctx context.Context, keys string) error
	// KeyDown presses and holds a key.
	KeyDown(ctx context.Context, key string) error
	// KeyUp releases a key.
	KeyUp(ctx context.Context, key string) error
	// Type types a string of text character-by-character.
	Type(ctx context.Context, text string) error

	// CursorPosition returns the current cursor coordinates.
	CursorPosition(ctx context.Context) (x, y int, err error)

	// RecordActivity marks the desktop as having received user
	// interaction, resetting the idle-recording timer.
	RecordActivity()

	// StartRecording begins recording the desktop to an MP4 file
	// using the caller-provided recording ID. Safe to call
	// repeatedly - active recordings continue unchanged, stopped
	// recordings are discarded and restarted. Concurrent recordings
	// are supported.
	StartRecording(ctx context.Context, recordingID string) error

	// StopRecording finalizes the recording identified by the given
	// ID. Idempotent - safe to call on an already-stopped recording.
	// Returns a RecordingArtifact that the caller can stream. The
	// caller must close the artifact when done. Returns an error if
	// the recording ID is unknown.
	StopRecording(ctx context.Context, recordingID string) (*RecordingArtifact, error)

	// Close shuts down the desktop session and cleans up resources.
	Close() error
}

type DesktopAction struct {
	Action          string  `json:"action"`
	Coordinate      *[2]int `json:"coordinate,omitempty"`
	StartCoordinate *[2]int `json:"start_coordinate,omitempty"`
	Text            *string `json:"text,omitempty"`
	Duration        *int    `json:"duration,omitempty"`
	ScrollAmount    *int    `json:"scroll_amount,omitempty"`
	ScrollDirection *string `json:"scroll_direction,omitempty"`
	// ScaledWidth and ScaledHeight describe the declared model-facing desktop
	// geometry. When provided, input coordinates are mapped from declared space
	// to native desktop pixels before dispatching.
	ScaledWidth  *int `json:"scaled_width,omitempty"`
	ScaledHeight *int `json:"scaled_height,omitempty"`
}

type DesktopActionResponse struct {
	Output           string `json:"output,omitempty"`
	ScreenshotData   string `json:"screenshot_data,omitempty"`
	ScreenshotWidth  int    `json:"screenshot_width,omitempty"`
	ScreenshotHeight int    `json:"screenshot_height,omitempty"`
}

type DisplayConfig struct {
	Width   int // native width in pixels
	Height  int // native height in pixels
	VNCPort int // local TCP port for the VNC server
	Display int // X11 display number (e.g. 1 for :1), -1 if N/A
}

type MouseButton string

type RecordingArtifact struct {
	// Reader is the MP4 content. Callers must close it when done.
	Reader io.ReadCloser
	// Size is the byte length of the MP4 content.
	Size int64
	// ThumbnailReader is the JPEG thumbnail. May be nil if no
	// thumbnail was produced. Callers must close it when done.
	ThumbnailReader io.ReadCloser
	// ThumbnailSize is the byte length of the thumbnail.
	ThumbnailSize int64
}

type ScreenshotOptions struct {
	TargetWidth  int // 0 = native
	TargetHeight int // 0 = native
}

type ScreenshotResult struct {
	Data string // base64-encoded PNG
}