@octavus/agent 1.0.28 → 1.0.34

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -23,6 +23,7 @@ Usage mirrors the macOS driver exactly:
23
23
  linux-driver.py screenshot <path>
24
24
  linux-driver.py screenshot-grid <path> --region x y w h --grid <2|3>
25
25
  linux-driver.py activate <app-name>
26
+ linux-driver.py read-clipboard
26
27
  """
27
28
 
28
29
  import ctypes
@@ -669,8 +670,9 @@ _IGNORE_X_ERRORS = ctypes.CFUNCTYPE(ctypes.c_int, ctypes.c_void_p, ctypes.c_void
669
670
  def _load_xlib():
670
671
  """libX11 with the prototypes the driver uses, loaded once; None when unavailable.
671
672
 
672
- Window properties are read through libX11 directly because xprop is not
673
- installed on the cloud image.
673
+ Window properties and the clipboard are read through libX11 directly because
674
+ xprop and xclip are not installed on the cloud image (nor guaranteed on an
675
+ Agent CLI host).
674
676
  """
675
677
  try:
676
678
  xlib = ctypes.cdll.LoadLibrary(ctypes.util.find_library("X11") or "libX11.so.6")
@@ -698,6 +700,40 @@ def _load_xlib():
698
700
  ctypes.POINTER(ctypes.c_void_p),
699
701
  ]
700
702
  xlib.XFree.argtypes = [ctypes.c_void_p]
703
+ xlib.XCreateSimpleWindow.argtypes = [
704
+ ctypes.c_void_p,
705
+ ctypes.c_ulong,
706
+ ctypes.c_int,
707
+ ctypes.c_int,
708
+ ctypes.c_uint,
709
+ ctypes.c_uint,
710
+ ctypes.c_uint,
711
+ ctypes.c_ulong,
712
+ ctypes.c_ulong,
713
+ ]
714
+ xlib.XCreateSimpleWindow.restype = ctypes.c_ulong
715
+ xlib.XDestroyWindow.argtypes = [ctypes.c_void_p, ctypes.c_ulong]
716
+ xlib.XSelectInput.argtypes = [ctypes.c_void_p, ctypes.c_ulong, ctypes.c_long]
717
+ xlib.XGetSelectionOwner.argtypes = [ctypes.c_void_p, ctypes.c_ulong]
718
+ xlib.XGetSelectionOwner.restype = ctypes.c_ulong
719
+ xlib.XConvertSelection.argtypes = [
720
+ ctypes.c_void_p,
721
+ ctypes.c_ulong,
722
+ ctypes.c_ulong,
723
+ ctypes.c_ulong,
724
+ ctypes.c_ulong,
725
+ ctypes.c_ulong,
726
+ ]
727
+ xlib.XCheckTypedWindowEvent.argtypes = [
728
+ ctypes.c_void_p,
729
+ ctypes.c_ulong,
730
+ ctypes.c_int,
731
+ ctypes.c_void_p,
732
+ ]
733
+ xlib.XCheckTypedWindowEvent.restype = ctypes.c_int
734
+ xlib.XFlush.argtypes = [ctypes.c_void_p]
735
+ xlib.XGetAtomName.argtypes = [ctypes.c_void_p, ctypes.c_ulong]
736
+ xlib.XGetAtomName.restype = ctypes.c_void_p
701
737
  xlib.XSetErrorHandler.restype = ctypes.c_void_p
702
738
  xlib.XSetErrorHandler(_IGNORE_X_ERRORS)
703
739
  return xlib
@@ -706,26 +742,27 @@ def _load_xlib():
706
742
  class _X11:
707
743
  """One connection to the X display for a batch of reads.
708
744
 
709
- Opened on entry and closed on exit. Every read answers with a neutral value
710
- (0 for an atom, None for a property) instead of raising, so a window destroyed
711
- between the xdotool lookup and the read - or a box without libX11 or a display
712
- at all - degrades to "no property".
745
+ Opened on entry and closed on exit; ``display`` is None on a box without
746
+ libX11 or a display at all. Every read answers with a neutral value (0 for
747
+ an atom, None for a property) instead of raising, so a window destroyed
748
+ between the xdotool lookup and the read - or that missing display - degrades
749
+ to "no property".
713
750
  """
714
751
 
715
752
  def __enter__(self):
716
- self._xlib = _load_xlib()
717
- self._display = self._xlib.XOpenDisplay(None) if self._xlib else None
753
+ self.xlib = _load_xlib()
754
+ self.display = self.xlib.XOpenDisplay(None) if self.xlib else None
718
755
  return self
719
756
 
720
757
  def __exit__(self, *_exc):
721
- if self._display:
722
- self._xlib.XCloseDisplay(self._display)
758
+ if self.display:
759
+ self.xlib.XCloseDisplay(self.display)
723
760
 
724
761
  def atom(self, name):
725
762
  """The atom for ``name``, or 0 when it was never interned on this server."""
726
- if not self._display:
763
+ if not self.display:
727
764
  return 0
728
- return int(self._xlib.XInternAtom(self._display, name.encode(), True))
765
+ return int(self.xlib.XInternAtom(self.display, name.encode(), True))
729
766
 
730
767
  def window_property(self, window_id, name, max_items=1024):
731
768
  """A format-32 property of ``window_id`` (the root window when None) as a
@@ -734,19 +771,35 @@ class _X11:
734
771
  if not atom:
735
772
  return None
736
773
  if window_id is None:
737
- window_id = self._xlib.XDefaultRootWindow(self._display)
774
+ window_id = self.xlib.XDefaultRootWindow(self.display)
775
+ value = self.property_value(window_id, atom, max_length=max_items)
776
+ if value is None:
777
+ return None
778
+ _type, data_format, data = value
779
+ if data_format != 32 or not data:
780
+ return None
781
+ return _format32_items(data)
782
+
783
+ def property_value(self, window_id, atom, delete=False, max_length=1024):
784
+ """The raw value of ``atom`` on ``window_id``: ``(type atom, format, bytes)``,
785
+ or None when the window or the property does not exist.
786
+
787
+ ``max_length`` counts 32-bit units, as Xlib does. Format-16 and format-32
788
+ items come back as C shorts and longs, as Xlib returns them. Deleting the
789
+ property as it is read is how a selection requestor takes a value.
790
+ """
738
791
  actual_type = ctypes.c_ulong()
739
792
  actual_format = ctypes.c_int()
740
793
  n_items = ctypes.c_ulong()
741
794
  bytes_after = ctypes.c_ulong()
742
795
  data = ctypes.c_void_p()
743
- status = self._xlib.XGetWindowProperty(
744
- self._display,
796
+ status = self.xlib.XGetWindowProperty(
797
+ self.display,
745
798
  window_id,
746
799
  atom,
747
800
  0,
748
- max_items,
749
- False,
801
+ max_length,
802
+ delete,
750
803
  0, # AnyPropertyType
751
804
  ctypes.byref(actual_type),
752
805
  ctypes.byref(actual_format),
@@ -757,12 +810,22 @@ class _X11:
757
810
  if status != 0 or not data.value:
758
811
  return None
759
812
  try:
760
- if actual_format.value != 32 or n_items.value == 0:
761
- return None
762
- # Xlib hands format-32 property items back as C longs.
763
- return [int(v) for v in ctypes.cast(data, ctypes.POINTER(ctypes.c_long))[: n_items.value]]
813
+ item_size = {
814
+ 8: 1,
815
+ 16: ctypes.sizeof(ctypes.c_short),
816
+ 32: ctypes.sizeof(ctypes.c_long),
817
+ }.get(actual_format.value, 0)
818
+ raw = ctypes.string_at(data, n_items.value * item_size)
819
+ return actual_type.value, actual_format.value, raw
764
820
  finally:
765
- self._xlib.XFree(data)
821
+ self.xlib.XFree(data)
822
+
823
+
824
+ def _format32_items(data):
825
+ """The items of a format-32 property value, which Xlib hands back as C longs."""
826
+ item_size = ctypes.sizeof(ctypes.c_ulong)
827
+ count = len(data) // item_size
828
+ return list((ctypes.c_ulong * count).from_buffer_copy(data[: count * item_size]))
766
829
 
767
830
 
768
831
  def _x11_window_property(window_id, name, max_items=1024):
@@ -1768,6 +1831,233 @@ def activate_app(name):
1768
1831
  return False
1769
1832
 
1770
1833
 
1834
+ # ---------------------------------------------------------------------------
1835
+ # Clipboard (the X11 CLIPBOARD selection, read through libX11)
1836
+ # ---------------------------------------------------------------------------
1837
+
1838
+ _SELECTION_NOTIFY = 31
1839
+ _PROPERTY_NOTIFY = 28
1840
+ _PROPERTY_NEW_VALUE = 0
1841
+ _PROPERTY_CHANGE_MASK = 1 << 22
1842
+
1843
+ # How long the app holding the clipboard gets to answer one request: the target
1844
+ # list, the text, or one chunk of an INCR transfer.
1845
+ _CLIPBOARD_REPLY_TIMEOUT = 5.0
1846
+
1847
+ # The most bytes one read collects, so a huge copy cannot balloon the driver.
1848
+ _CLIPBOARD_MAX_BYTES = 8 * 1024 * 1024
1849
+
1850
+ # Text targets in preference order, each with the encoding its data arrives in.
1851
+ _CLIPBOARD_TEXT_TARGETS = [
1852
+ ("UTF8_STRING", "utf-8"),
1853
+ ("text/plain;charset=utf-8", "utf-8"),
1854
+ ("STRING", "latin-1"),
1855
+ ("TEXT", "utf-8"),
1856
+ ("text/plain", "utf-8"),
1857
+ ]
1858
+
1859
+ _CLIPBOARD_FILE_TARGETS = {"text/uri-list", "x-special/gnome-copied-files"}
1860
+
1861
+ # Targets every owner advertises that carry no clipboard content of their own.
1862
+ _CLIPBOARD_META_TARGETS = {"TARGETS", "TIMESTAMP", "MULTIPLE", "SAVE_TARGETS"}
1863
+
1864
+
1865
+ class _XSelectionEvent(ctypes.Structure):
1866
+ _fields_ = [
1867
+ ("type", ctypes.c_int),
1868
+ ("serial", ctypes.c_ulong),
1869
+ ("send_event", ctypes.c_int),
1870
+ ("display", ctypes.c_void_p),
1871
+ ("requestor", ctypes.c_ulong),
1872
+ ("selection", ctypes.c_ulong),
1873
+ ("target", ctypes.c_ulong),
1874
+ ("property", ctypes.c_ulong),
1875
+ ("time", ctypes.c_ulong),
1876
+ ]
1877
+
1878
+
1879
+ class _XPropertyEvent(ctypes.Structure):
1880
+ _fields_ = [
1881
+ ("type", ctypes.c_int),
1882
+ ("serial", ctypes.c_ulong),
1883
+ ("send_event", ctypes.c_int),
1884
+ ("display", ctypes.c_void_p),
1885
+ ("window", ctypes.c_ulong),
1886
+ ("atom", ctypes.c_ulong),
1887
+ ("time", ctypes.c_ulong),
1888
+ ("state", ctypes.c_int),
1889
+ ]
1890
+
1891
+
1892
+ class _XEvent(ctypes.Union):
1893
+ # Xlib's XEvent is a union padded to 24 longs; only these members are read.
1894
+ _fields_ = [
1895
+ ("type", ctypes.c_int),
1896
+ ("xselection", _XSelectionEvent),
1897
+ ("xproperty", _XPropertyEvent),
1898
+ ("pad", ctypes.c_long * 24),
1899
+ ]
1900
+
1901
+
1902
+ def read_clipboard():
1903
+ """The CLIPBOARD selection as ``{"content": kind, "text": str | None}``.
1904
+
1905
+ ``kind`` is text, image, files, empty, or other; text wins whenever the owner
1906
+ offers it alongside other kinds. Reading never changes the clipboard.
1907
+ """
1908
+ with _X11() as x11:
1909
+ if not x11.display:
1910
+ exit_with_error("Cannot read the clipboard: no X display is available ($DISPLAY).")
1911
+ return _ClipboardReader(x11).read()
1912
+
1913
+
1914
+ def _non_text_clipboard_kind(targets):
1915
+ """Classify an owner that offers no text by the targets it does offer.
1916
+
1917
+ ``targets`` is None for an owner that would not even list them; it holds
1918
+ something, so that is "other", never "empty".
1919
+ """
1920
+ if targets is None:
1921
+ return "other"
1922
+ if any(target.startswith("image/") for target in targets):
1923
+ return "image"
1924
+ if targets & _CLIPBOARD_FILE_TARGETS:
1925
+ return "files"
1926
+ return "empty" if targets <= _CLIPBOARD_META_TARGETS else "other"
1927
+
1928
+
1929
+ class _ClipboardReader:
1930
+ """One CLIPBOARD read on an open display, acting as the selection requestor.
1931
+
1932
+ Each request asks the owner to convert the selection into a property on a
1933
+ private unmapped window and waits for its SelectionNotify. Data larger than
1934
+ the owner's request size arrives through the ICCCM INCR protocol, as
1935
+ successive values of that property.
1936
+ """
1937
+
1938
+ def __init__(self, x11):
1939
+ self._x11 = x11
1940
+ self._xlib = x11.xlib
1941
+ self._display = x11.display
1942
+ self._clipboard = self._intern("CLIPBOARD")
1943
+ self._property = self._intern("OCTAVUS_CLIPBOARD")
1944
+ self._incr = self._intern("INCR")
1945
+ self._window = 0
1946
+
1947
+ def read(self):
1948
+ if not self._xlib.XGetSelectionOwner(self._display, self._clipboard):
1949
+ return {"content": "empty", "text": None}
1950
+ root = self._xlib.XDefaultRootWindow(self._display)
1951
+ self._window = self._xlib.XCreateSimpleWindow(self._display, root, 0, 0, 1, 1, 0, 0, 0)
1952
+ self._xlib.XSelectInput(self._display, self._window, _PROPERTY_CHANGE_MASK)
1953
+ try:
1954
+ targets = self._targets()
1955
+ for name, encoding in _CLIPBOARD_TEXT_TARGETS:
1956
+ if targets is not None and name not in targets:
1957
+ continue
1958
+ reply = self._convert(self._intern(name))
1959
+ if reply is not None:
1960
+ _format, data = reply
1961
+ return {"content": "text", "text": data.decode(encoding, errors="replace")}
1962
+ return {"content": _non_text_clipboard_kind(targets), "text": None}
1963
+ finally:
1964
+ self._xlib.XDestroyWindow(self._display, self._window)
1965
+
1966
+ def _targets(self):
1967
+ """Names of the targets the owner offers, or None when it will not list them."""
1968
+ reply = self._convert(self._intern("TARGETS"))
1969
+ if reply is None:
1970
+ return None
1971
+ data_format, data = reply
1972
+ if data_format != 32:
1973
+ return None
1974
+ atoms = _format32_items(data)
1975
+ return {name for name in (self._atom_name(atom) for atom in atoms) if name}
1976
+
1977
+ def _convert(self, target):
1978
+ """The owner's ``(format, data)`` for ``target``, or None when it refuses the target."""
1979
+ self._xlib.XConvertSelection(
1980
+ self._display, self._clipboard, target, self._property, self._window, 0
1981
+ )
1982
+ self._xlib.XFlush(self._display)
1983
+ event = self._wait_for(
1984
+ _SELECTION_NOTIFY, lambda e: e.xselection.selection == self._clipboard
1985
+ )
1986
+ if not event.xselection.property:
1987
+ return None
1988
+ # The owner set the property before it notified, so every PropertyNotify
1989
+ # queued so far is stale; dropping them keeps an INCR transfer from
1990
+ # mistaking the initial INCR marker for its first chunk.
1991
+ self._discard(_PROPERTY_NOTIFY)
1992
+ value_type, data_format, data = self._take_property()
1993
+ if value_type == self._incr:
1994
+ return 8, self._read_incr()
1995
+ return data_format, data
1996
+
1997
+ def _read_incr(self):
1998
+ """The data an INCR owner sends as successive property values, ended by an empty one.
1999
+
2000
+ Deleting the INCR marker (``_take_property``) is what starts the transfer;
2001
+ each chunk is taken the same way, which asks the owner for the next.
2002
+ """
2003
+ chunks = []
2004
+ total = 0
2005
+ while total < _CLIPBOARD_MAX_BYTES:
2006
+ self._wait_for(
2007
+ _PROPERTY_NOTIFY,
2008
+ lambda e: e.xproperty.atom == self._property
2009
+ and e.xproperty.state == _PROPERTY_NEW_VALUE,
2010
+ )
2011
+ _type, _format, chunk = self._take_property()
2012
+ if not chunk:
2013
+ break
2014
+ chunks.append(chunk)
2015
+ total += len(chunk)
2016
+ return b"".join(chunks)
2017
+
2018
+ def _take_property(self):
2019
+ """Read and delete our property: ``(type atom, format, raw bytes)``, empty
2020
+ when the owner set none."""
2021
+ value = self._x11.property_value(
2022
+ self._window, self._property, delete=True, max_length=_CLIPBOARD_MAX_BYTES // 4
2023
+ )
2024
+ return value if value is not None else (0, 0, b"")
2025
+
2026
+ def _wait_for(self, event_type, matches):
2027
+ """The next ``event_type`` event on our window that ``matches``; exits when the owner never answers."""
2028
+ event = _XEvent()
2029
+ deadline = time.monotonic() + _CLIPBOARD_REPLY_TIMEOUT
2030
+ while time.monotonic() < deadline:
2031
+ while self._xlib.XCheckTypedWindowEvent(
2032
+ self._display, self._window, event_type, ctypes.byref(event)
2033
+ ):
2034
+ if matches(event):
2035
+ return event
2036
+ time.sleep(0.01)
2037
+ exit_with_error(
2038
+ "The app holding the clipboard did not respond. Copy the value again and retry."
2039
+ )
2040
+
2041
+ def _discard(self, event_type):
2042
+ event = _XEvent()
2043
+ while self._xlib.XCheckTypedWindowEvent(
2044
+ self._display, self._window, event_type, ctypes.byref(event)
2045
+ ):
2046
+ pass
2047
+
2048
+ def _intern(self, name):
2049
+ return int(self._xlib.XInternAtom(self._display, name.encode(), False))
2050
+
2051
+ def _atom_name(self, atom):
2052
+ pointer = self._xlib.XGetAtomName(self._display, atom)
2053
+ if not pointer:
2054
+ return None
2055
+ try:
2056
+ return ctypes.string_at(pointer).decode("latin-1")
2057
+ finally:
2058
+ self._xlib.XFree(pointer)
2059
+
2060
+
1771
2061
  # ---------------------------------------------------------------------------
1772
2062
  # Main CLI
1773
2063
  # ---------------------------------------------------------------------------
@@ -1973,6 +2263,9 @@ def main():
1973
2263
  # a window yet, so the caller waits instead of launching it again.
1974
2264
  print_success(windowVisible=window_visible)
1975
2265
 
2266
+ elif command == "read-clipboard":
2267
+ print(json.dumps(read_clipboard()))
2268
+
1976
2269
  else:
1977
2270
  exit_with_error(f"Unknown command: '{command}'")
1978
2271