Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
"""Shared Runtime contract for the desktop-owned Computer Use daemon.
The desktop shell is the only process allowed to start the Cua daemon and the
only writer of ``computer-use.json``. Runtime processes use this module to:
* derive the effective user-facing status,
* derive the status consumed by the Workbench and the Controller-owned CLI, and
* keep the daemon state contract independent from backend launch configuration.
Computer Use requests enter through ``vibe computer`` and the Controller's
internal IPC. Backend processes do not receive a Computer Use MCP server.
The state directory intentionally does not use ``AVIBE_HOME``. It belongs to
the operating-system desktop application and must be shared by every Runtime
that the shell can adopt.
"""
from __future__ import annotations
from dataclasses import dataclass
import hashlib
import json
import logging
import os
from pathlib import Path
import socket
import sys
from typing import Any, Callable, Mapping
logger = logging.getLogger(__name__)
COMPUTER_USE_SCHEMA_VERSION = 1
COMPUTER_USE_STATE_DIR_ENV = "AVIBE_COMPUTER_USE_STATE_DIR"
COMPUTER_USE_STATE_FILE = "computer-use.json"
COMPUTER_USE_LOCK_FILE = "computer-use.lock"
COMPUTER_USE_TOOL_SNAPSHOT_SHA256 = (
"d46448a2f8a03c7be23d52c8089f5a86b3abb61add102b950170d89cc238a944"
)
COMPUTER_USE_TOOL_NAMES = (
"list_apps",
"list_windows",
"get_window_state",
"verify_state",
"get_accessibility_tree",
"get_screen_size",
"get_desktop_state",
"get_cursor_position",
"zoom",
"launch_app",
"kill_app",
"bring_to_front",
"set_window_frame",
"click",
"double_click",
"right_click",
"drag",
"scroll",
"type_text",
"press_key",
"hotkey",
"set_value",
"clipboard_read",
"clipboard_write",
"start_session",
"end_session",
"get_session",
"list_sessions",
"health_report",
)
# Each approved snapshot digest and the exact tool set it advertises. Desktop
# shells released before window activation still bundle the previous snapshot;
# a newer Runtime they adopt keeps Computer Use available without activation.
COMPUTER_USE_APPROVED_TOOL_SNAPSHOTS: Mapping[str, frozenset[str]] = {
COMPUTER_USE_TOOL_SNAPSHOT_SHA256: frozenset(COMPUTER_USE_TOOL_NAMES),
"f446154884a6ac3e3126c1d6ca4a886c8d1caea7f41449124a9ad5ca47e9c7fe": frozenset(
COMPUTER_USE_TOOL_NAMES
),
"1614e37e369df122b2bb74be4d1c790f304c9325d3b57b301deb62f8c11e8fd6": frozenset(
COMPUTER_USE_TOOL_NAMES
),
"37b99238c5f59a64ddece25467aa51148ac6267baa928cbb5d3404196d9d4c71": frozenset(
COMPUTER_USE_TOOL_NAMES
),
"0af1e40dbf8d48303c25d969fa54b54ccff5d0c36f2f7966b4f04964c13e5ba0": frozenset(
COMPUTER_USE_TOOL_NAMES
),
"edf496838092b2fa21807724b30308c4e9a90a404c9a9b7783a299b71e427144": frozenset(
COMPUTER_USE_TOOL_NAMES
)
- {"bring_to_front"},
}
_STATE_VALUES = frozenset(
{
"off",
"needs_permission",
"starting",
"ready",
"error",
"stopped",
"needs_runtime",
}
)
_SHA256_HEX_LENGTH = 64
class ComputerUseStateError(ValueError):
"""The desktop state file does not satisfy the versioned contract."""
@dataclass(frozen=True)
class ToolSnapshot:
path: Path
sha256: str
@dataclass(frozen=True)
class ComputerUseState:
schema_version: int
enabled: bool
state: str
reason: str | None
shell_pid: int
instance_id: str
generation: int
driver_version: str
tool_snapshot: ToolSnapshot
socket_path: str | None = None
proxy_executable: str | None = None
host_bundle_id: str | None = None
@property
def daemon_key(self) -> tuple[str, int]:
return (self.instance_id, self.generation)
@dataclass(frozen=True)
class ComputerUseStatus:
status: str
reason: str | None
state: ComputerUseState | None = None
def as_dict(self) -> dict[str, Any]:
payload: dict[str, Any] = {"status": self.status, "reason": self.reason}
if self.state is not None:
payload.update(
{
"enabled": self.state.enabled,
"state": self.state.state,
"instance_id": self.state.instance_id,
"generation": self.state.generation,
"driver_version": self.state.driver_version,
}
)
return payload
@dataclass
class _SnapshotCacheEntry:
size: int
mtime_ns: int
digest: str
class SnapshotVerifier:
"""Hash snapshots only when their filesystem identity changes."""
def __init__(self) -> None:
self._cache: dict[Path, _SnapshotCacheEntry] = {}
def digest(self, path: Path) -> str | None:
try:
stat_result = path.stat()
except OSError:
self._cache.pop(path, None)
return None
cached = self._cache.get(path)
if (
cached is not None
and cached.size == stat_result.st_size
and cached.mtime_ns == stat_result.st_mtime_ns
):
return cached.digest
try:
digest = hashlib.sha256(path.read_bytes()).hexdigest()
except OSError:
self._cache.pop(path, None)
return None
self._cache[path] = _SnapshotCacheEntry(
size=stat_result.st_size,
mtime_ns=stat_result.st_mtime_ns,
digest=digest,
)
return digest
def verifies(self, snapshot: ToolSnapshot) -> bool:
return self.digest(snapshot.path) == snapshot.sha256
_snapshot_verifier = SnapshotVerifier()
_warned_snapshot_failures: set[tuple[str, str]] = set()
def desktop_computer_use_dir(
*,
environ: Mapping[str, str] | None = None,
home: Path | None = None,
platform: str | None = None,
) -> Path:
"""Resolve the desktop app-data directory independently of ``AVIBE_HOME``."""
env = os.environ if environ is None else environ
override = str(env.get(COMPUTER_USE_STATE_DIR_ENV) or "").strip()
if override:
return Path(override).expanduser()
platform_name = platform or sys.platform
user_home = Path.home() if home is None else home
if platform_name == "darwin":
return user_home / "Library" / "Application Support" / "bot.avibe.desktop"
if platform_name == "win32":
appdata = str(env.get("APPDATA") or "").strip()
if appdata:
return Path(appdata) / "bot.avibe.desktop"
return user_home / "AppData" / "Roaming" / "bot.avibe.desktop"
xdg_data_home = str(env.get("XDG_DATA_HOME") or "").strip()
base = Path(xdg_data_home).expanduser() if xdg_data_home else user_home / ".local" / "share"
return base / "bot.avibe.desktop"
def computer_use_state_path(**kwargs: Any) -> Path:
return desktop_computer_use_dir(**kwargs) / COMPUTER_USE_STATE_FILE
def computer_use_lock_path(**kwargs: Any) -> Path:
return desktop_computer_use_dir(**kwargs) / COMPUTER_USE_LOCK_FILE
def _required_bool(payload: Mapping[str, Any], key: str) -> bool:
value = payload.get(key)
if not isinstance(value, bool):
raise ComputerUseStateError(f"{key} must be a boolean")
return value
def _required_int(payload: Mapping[str, Any], key: str, *, minimum: int = 0) -> int:
value = payload.get(key)
if isinstance(value, bool) or not isinstance(value, int) or value < minimum:
raise ComputerUseStateError(f"{key} must be an integer >= {minimum}")
return value
def _required_string(payload: Mapping[str, Any], key: str) -> str:
value = payload.get(key)
if not isinstance(value, str) or not value.strip():
raise ComputerUseStateError(f"{key} must be a non-empty string")
return value
def _optional_reason(payload: Mapping[str, Any]) -> str | None:
value = payload.get("reason")
if value is None:
return None
if not isinstance(value, str) or not value.strip():
raise ComputerUseStateError("reason must be null or a non-empty string")
return value
def _absolute_path(payload: Mapping[str, Any], key: str) -> str:
value = _required_string(payload, key)
if not Path(value).is_absolute():
raise ComputerUseStateError(f"{key} must be an absolute path")
return value
def parse_computer_use_state(payload: Any) -> ComputerUseState:
if not isinstance(payload, dict):
raise ComputerUseStateError("state file must contain a JSON object")
schema_version = _required_int(payload, "schema_version", minimum=1)
if schema_version != COMPUTER_USE_SCHEMA_VERSION:
raise ComputerUseStateError(f"unsupported schema_version: {schema_version}")
state_name = _required_string(payload, "state")
if state_name not in _STATE_VALUES:
raise ComputerUseStateError(f"unknown state: {state_name}")
raw_snapshot = payload.get("tool_snapshot")
if not isinstance(raw_snapshot, dict):
raise ComputerUseStateError("tool_snapshot must be an object")
snapshot_path = Path(_absolute_path(raw_snapshot, "path"))
snapshot_sha256 = _required_string(raw_snapshot, "sha256").lower()
if len(snapshot_sha256) != _SHA256_HEX_LENGTH or any(
character not in "0123456789abcdef" for character in snapshot_sha256
):
raise ComputerUseStateError("tool_snapshot.sha256 must be a SHA-256 hex digest")
socket_path: str | None = None
proxy_executable: str | None = None
host_bundle_id: str | None = None
if state_name == "ready":
socket_path = _absolute_path(payload, "socket_path")
proxy_executable = _absolute_path(payload, "proxy_executable")
host_bundle_id = _required_string(payload, "host_bundle_id")
return ComputerUseState(
schema_version=schema_version,
enabled=_required_bool(payload, "enabled"),
state=state_name,
reason=_optional_reason(payload),
shell_pid=_required_int(payload, "shell_pid", minimum=1),
instance_id=_required_string(payload, "instance_id"),
generation=_required_int(payload, "generation", minimum=0),
driver_version=_required_string(payload, "driver_version"),
tool_snapshot=ToolSnapshot(snapshot_path, snapshot_sha256),
socket_path=socket_path,
proxy_executable=proxy_executable,
host_bundle_id=host_bundle_id,
)
def read_computer_use_state(path: Path | None = None) -> ComputerUseState | None:
target = path or computer_use_state_path()
try:
raw = target.read_text(encoding="utf-8")
except FileNotFoundError:
return None
except (OSError, UnicodeError) as exc:
raise ComputerUseStateError(f"state file is unreadable: {exc}") from exc
try:
payload = json.loads(raw)
except (json.JSONDecodeError, RecursionError) as exc:
raise ComputerUseStateError("state file is malformed JSON") from exc
return parse_computer_use_state(payload)
def _snapshot_valid(state: ComputerUseState, verifier: SnapshotVerifier) -> bool:
valid = verifier.verifies(state.tool_snapshot)
if not valid:
warning_key = (str(state.tool_snapshot.path), state.tool_snapshot.sha256)
if warning_key not in _warned_snapshot_failures:
_warned_snapshot_failures.add(warning_key)
logger.warning(
"Computer-use tool snapshot failed verification: path=%s expected_sha256=%s",
state.tool_snapshot.path,
state.tool_snapshot.sha256,
)
return valid
def _shell_lock_is_held(lock_path: Path) -> bool:
if os.name == "nt":
# Phase 1 is macOS-only. A Windows state file cannot claim a live shell
# until the deferred Windows lock implementation is added.
return False
import fcntl
try:
lock_path.parent.mkdir(parents=True, exist_ok=True)
with lock_path.open("a+b") as handle:
try:
fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
except BlockingIOError:
return True
fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
return False
except OSError:
return False
def desktop_computer_use_shell_is_live(
*,
state_path: Path | None = None,
lock_path: Path | None = None,
shell_lock_held: Callable[[Path], bool] = _shell_lock_is_held,
) -> bool:
"""Whether the native shell owns the Computer Use lock.
Missing or damaged optional state does not mean that the native shell is
absent: the shell acquires the lock before it reads or repairs that state.
The lock is therefore the support signal, while a valid state record
remains the source for the feature's effective status.
"""
target = state_path or computer_use_state_path()
try:
state = read_computer_use_state(target)
except ComputerUseStateError:
state = None
resolved_lock_path = lock_path or target.with_name(COMPUTER_USE_LOCK_FILE)
if not shell_lock_held(resolved_lock_path):
return False
return state is None or state.state != "stopped"
def _unix_socket_accepts(path: str, *, timeout: float = 0.1) -> bool:
if os.name == "nt":
return False
client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
client.settimeout(timeout)
try:
client.connect(path)
except OSError:
return False
finally:
client.close()
return True
def effective_computer_use_status(
*,
state_path: Path | None = None,
lock_path: Path | None = None,
verifier: SnapshotVerifier | None = None,
shell_lock_held: Callable[[Path], bool] = _shell_lock_is_held,
socket_accepts: Callable[[str], bool] = _unix_socket_accepts,
) -> ComputerUseStatus:
target = state_path or computer_use_state_path()
checker = verifier or _snapshot_verifier
try:
state = read_computer_use_state(target)
except ComputerUseStateError:
return ComputerUseStatus("unavailable", "invalid_state_file")
if state is None:
return ComputerUseStatus("off", "never_enabled")
if not state.enabled:
return ComputerUseStatus("off", "toggle_off", state)
if not _snapshot_valid(state, checker):
return ComputerUseStatus("unavailable", "snapshot_invalid", state)
resolved_lock_path = lock_path or target.with_name(COMPUTER_USE_LOCK_FILE)
if not shell_lock_held(resolved_lock_path) or state.state == "stopped":
return ComputerUseStatus("unavailable", "shell_not_running", state)
if state.state != "ready":
return ComputerUseStatus(state.state, state.reason, state)
assert state.socket_path is not None
if not socket_accepts(state.socket_path):
return ComputerUseStatus("unavailable", "daemon_unreachable", state)
return ComputerUseStatus("ready", None, state)