holo-desktop-cli 0.0.1__py3-none-any.whl

holo_desktop/__init__.py

@@ -0,0 +1,6 @@
+"""HoloDesktop CLI: thin client to the hai-agent-runtime desktop agent, powered by H Company's Holo3 VLM."""
+
+from importlib.metadata import version
+
+__version__ = version("holo-desktop-cli")
+__all__ = ["__version__"]

holo_desktop/__main__.py

@@ -0,0 +1,6 @@
+"""Make `python -m holo_desktop ...` work; real entry point is `holo_desktop.cli.main`."""
+
+from holo_desktop.cli import main
+
+if __name__ == "__main__":
+    main()

holo_desktop/agent_client/__init__.py

@@ -0,0 +1,20 @@
+"""Thin client to the hai-agent-runtime binary."""
+
+from holo_desktop.agent_client.client import AgentApiClient, SessionStream
+from holo_desktop.agent_client.launcher import (
+    AgentDaemon,
+    SpawnConfig,
+    ensure_running,
+    runtime_log_path,
+    runtime_log_tail,
+)
+
+__all__ = [
+    "AgentApiClient",
+    "AgentDaemon",
+    "SessionStream",
+    "SpawnConfig",
+    "ensure_running",
+    "runtime_log_path",
+    "runtime_log_tail",
+]

holo_desktop/agent_client/client.py

@@ -0,0 +1,155 @@
+"""Async HTTP client for the hai-agent-runtime agent-API surface."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+from types import TracebackType
+
+import httpx
+from agent_interface.definition import UserMessageEvent
+from agent_interface.specs.session import SessionRequest, SessionStatus
+from agp_types import TrajectoryChanges, TrajectoryEvent, TrajectoryStatus
+
+logger = logging.getLogger(__name__)
+
+API_PREFIX = "/api/v2"
+# Long-poll window per request; modest to stay under the server's cap and keep Ctrl+C responsive.
+POLL_WAIT_S = 10
+
+_KNOWN_STATUSES = frozenset(s.value for s in TrajectoryStatus)
+
+
+def _coerce_status(payload: object) -> object:
+    if isinstance(payload, dict):
+        status = payload.get("status")
+        if isinstance(status, str) and status not in _KNOWN_STATUSES:
+            # End the turn instead of mapping to a non-terminal status: an unknown *terminal* status
+            # would otherwise never trip end-of-turn and the stream would poll until external limits hit.
+            logger.warning("unrecognized session status %r from runtime; ending turn as failed", status)
+            patched = {**payload, "status": TrajectoryStatus.FAILED.value}
+            if not patched.get("error"):
+                patched["error"] = f"runtime reported unrecognized session status {status!r}"
+            return patched
+    return payload
+
+
+class AgentApiClient:
+    """Authenticated async client bound to one agent-API base URL."""
+
+    def __init__(self, base_url: str, token: str, *, timeout: float = 60.0) -> None:
+        self._http = httpx.AsyncClient(
+            base_url=f"{base_url}{API_PREFIX}",
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=httpx.Timeout(timeout, connect=5.0),
+        )
+
+    async def __aenter__(self) -> AgentApiClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def create_session(self, request: SessionRequest) -> str:
+        """Create a session and return its id."""
+        resp = await self._http.post("/sessions", json=request.model_dump(mode="json", exclude_none=True))
+        resp.raise_for_status()
+        return str(resp.json()["id"])
+
+    async def get_changes(
+        self, session_id: str, from_index: int, *, wait_for_seconds: int, include_events: bool
+    ) -> TrajectoryChanges | None:
+        """One long-poll for changes since ``from_index``; ``None`` when nothing arrived (204)."""
+        resp = await self._http.get(
+            f"/sessions/{session_id}/changes",
+            params={"from_index": from_index, "wait_for_seconds": wait_for_seconds, "include_events": include_events},
+        )
+        if resp.status_code == 204:
+            return None
+        resp.raise_for_status()
+        return TrajectoryChanges.model_validate(_coerce_status(resp.json()))
+
+    async def get_status(self, session_id: str) -> SessionStatus:
+        """Live session status; authoritative for terminal detection (``/changes`` 204s past the tail)."""
+        resp = await self._http.get(f"/sessions/{session_id}/status")
+        resp.raise_for_status()
+        return SessionStatus.model_validate(_coerce_status(resp.json()))
+
+    async def send_message(self, session_id: str, text: str) -> None:
+        # Body is a server-side tagged union, so the typed model's "type" discriminator is required.
+        body = UserMessageEvent(message=text).model_dump(mode="json")
+        resp = await self._http.post(f"/sessions/{session_id}/messages", json=body)
+        resp.raise_for_status()
+
+    async def pause(self, session_id: str) -> None:
+        """Freeze the agent after its current step; pairs with cancel for a responsive stop."""
+        resp = await self._http.post(f"/sessions/{session_id}/pause")
+        resp.raise_for_status()
+
+    async def cancel(self, session_id: str) -> None:
+        resp = await self._http.delete(f"/sessions/{session_id}")
+        if resp.status_code not in (200, 204):
+            resp.raise_for_status()
+
+    def stream(self, session_id: str, *, from_index: int = 0) -> SessionStream:
+        return SessionStream(self, session_id, from_index=from_index)
+
+
+def _is_end_of_turn(status: TrajectoryStatus) -> bool:
+    """Terminal, or IDLE (interactive session answered and awaits the next task)."""
+    return status.is_terminal or status == TrajectoryStatus.IDLE
+
+
+class SessionStream:
+    """Tails a session's events to end-of-turn, accumulating the final projection."""
+
+    def __init__(self, client: AgentApiClient, session_id: str, *, from_index: int = 0) -> None:
+        self._client = client
+        self._session_id = session_id
+        self.next_index = from_index
+        self.answer: str | dict[str, object] | None = None
+        self.status: TrajectoryStatus | None = None
+        self.error: str | None = None
+
+    async def events(self) -> AsyncIterator[TrajectoryEvent]:
+        """Yield each new ``TrajectoryEvent`` until the session reaches end-of-turn."""
+        while True:
+            changes = await self._client.get_changes(
+                self._session_id, self.next_index, wait_for_seconds=POLL_WAIT_S, include_events=True
+            )
+            if changes is not None:
+                self.next_index += len(changes.new_events)
+                if changes.answer is not None:
+                    self.answer = changes.answer
+                # status + error are one coherent snapshot: track the latest so a recovered
+                # session does not finish carrying a stale failure from an earlier batch.
+                self.status = changes.status
+                self.error = changes.error
+                for event in changes.new_events:
+                    yield event
+                if _is_end_of_turn(changes.status):
+                    return
+                continue
+            status = await self._client.get_status(self._session_id)
+            if _is_end_of_turn(status.status):
+                await self._finalize(status)
+                return
+
+    async def _finalize(self, status: SessionStatus) -> None:
+        """Adopt the authoritative status and pick up the final answer the 204 hid from us."""
+        self.status = status.status
+        self.error = status.error
+        if self.answer is not None:
+            return
+        final = await self._client.get_changes(self._session_id, 0, wait_for_seconds=0, include_events=False)
+        if final is not None:
+            self.answer = final.answer
+            self.error = self.error or final.error

holo_desktop/agent_client/desktop_lock.py

@@ -0,0 +1,69 @@
+"""Machine-wide advisory lock: at most one desktop turn runs at a time across all holo processes."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import os
+import sys
+from collections.abc import AsyncIterator
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+LOCK_PATH = Path.home() / ".holo" / "desktop.lock"
+# Poll cadence while another process or turn holds the lock; keeps the wait cancellable on Ctrl+C.
+_POLL_S = 0.25
+
+if sys.platform == "win32":
+    import msvcrt
+
+    def _try_acquire(fd: int) -> bool:
+        try:
+            msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+            return True
+        except OSError:
+            return False
+
+    def _release(fd: int) -> None:
+        with contextlib.suppress(OSError):
+            msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+else:
+    import fcntl
+
+    def _try_acquire(fd: int) -> bool:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            return True
+        except OSError:
+            return False
+
+    def _release(fd: int) -> None:
+        with contextlib.suppress(OSError):
+            fcntl.flock(fd, fcntl.LOCK_UN)
+
+
+@contextlib.asynccontextmanager
+async def desktop_turn() -> AsyncIterator[None]:
+    """Hold the machine-wide desktop lock for one turn, polling until it is free.
+
+    Not reentrant: each ``desktop_turn`` opens its own fd and the lock contends across fds even in
+    one process, so a second ``desktop_turn`` entered while the first is held waits forever. One turn
+    driver owns the lock at a time.
+    """
+    LOCK_PATH.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(LOCK_PATH, os.O_RDWR | os.O_CREAT, 0o600)
+    try:
+        waited = False
+        while not _try_acquire(fd):
+            if not waited:
+                logger.info("another desktop turn is in progress; waiting for the machine-wide lock")
+                waited = True
+            await asyncio.sleep(_POLL_S)
+        try:
+            yield
+        finally:
+            _release(fd)
+    finally:
+        os.close(fd)

holo_desktop/agent_client/event_timings.py

@@ -0,0 +1,251 @@
+"""Derive profile timing summaries from runtime ``events.jsonl`` traces."""
+
+from __future__ import annotations
+
+import json
+import statistics
+from collections.abc import Iterable
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from pathlib import Path
+
+from agent_interface.agent_events import (
+    AgentEventData,
+    ErrorEvent,
+    ObservationEvent,
+    PolicyEvent,
+    ToolResultEvent,
+)
+from pydantic import BaseModel, ConfigDict
+from rich.console import Console
+from rich.table import Table
+
+from holo_desktop.agent_client.events import parse_agent_event_data
+
+DEFAULT_RUNS_DIR = Path("~/.holo/runs").expanduser()
+# Error origins that close a step as a failed tool execution.
+_TOOL_ERROR_ORIGINS = frozenset({"tool", "tool_validation"})
+
+
+@dataclass
+class _StepTiming:
+    """Mutable accumulator for one step's phase durations while walking the trace."""
+
+    step_idx: int
+    tool_name: str | None = None
+    observe_s: float | None = None
+    llm_s: float | None = None
+    tool_s: float | None = None
+    failed: bool = False
+
+    @property
+    def total_s(self) -> float:
+        return sum(value for value in (self.observe_s, self.llm_s, self.tool_s) if value is not None)
+
+
+class StepTiming(BaseModel):
+    """Per-step phase durations (seconds); ``None`` where a phase was not observed."""
+
+    model_config = ConfigDict(frozen=True)
+    step_idx: int
+    tool_name: str | None
+    observe_s: float | None
+    llm_s: float | None
+    tool_s: float | None
+    failed: bool
+
+
+class StepTimingsSummary(BaseModel):
+    """Per-step timings plus phase averages across one session's trace."""
+
+    model_config = ConfigDict(frozen=True)
+    steps: tuple[StepTiming, ...]
+    avg_observe_s: float | None
+    avg_llm_s: float | None
+    avg_tool_s: float | None
+    avg_step_s: float | None
+    steps_timed: int
+
+
+def find_session_event_log(runs_dir: Path | None, session_id: str) -> Path | None:
+    """``events.jsonl`` for ``session_id``; only falls back to the sole log when attribution is unambiguous."""
+    root = DEFAULT_RUNS_DIR if runs_dir is None else runs_dir.expanduser()
+    if not root.exists():
+        return None
+    candidates = [path for path in root.rglob("events.jsonl") if path.is_file()]
+    if not candidates:
+        return None
+    if session_id:
+        matches = [path for path in candidates if session_id in str(path)]
+        if matches:
+            return max(matches, key=lambda path: path.stat().st_mtime)
+        # Multiple runs and none attributable to this session: refuse to show another run's timings.
+        if len(candidates) > 1:
+            return None
+    return max(candidates, key=lambda path: path.stat().st_mtime)
+
+
+def extract_step_timings(event_log: Path | None) -> StepTimingsSummary | None:
+    """Compute per-step profile timings from raw agent-event timestamp deltas."""
+    steps = _derive_steps(_load_records(event_log))
+    if not steps:
+        return None
+    return StepTimingsSummary(
+        steps=tuple(
+            StepTiming(
+                step_idx=step.step_idx,
+                tool_name=step.tool_name,
+                observe_s=step.observe_s,
+                llm_s=step.llm_s,
+                tool_s=step.tool_s,
+                failed=step.failed,
+            )
+            for step in steps
+        ),
+        avg_observe_s=_mean(step.observe_s for step in steps),
+        avg_llm_s=_mean(step.llm_s for step in steps),
+        avg_tool_s=_mean(step.tool_s for step in steps),
+        avg_step_s=_mean(step.total_s for step in steps),
+        steps_timed=len(steps),
+    )
+
+
+def render_step_timings(summary: StepTimingsSummary, console: Console) -> None:
+    """Render a timing summary as a per-step phase table plus averages."""
+    table = Table(title="step timings (s)", title_justify="left", header_style="bold")
+    for column in ("step", "tool", "observe", "llm", "tool exec", "total"):
+        table.add_column(column, justify="right" if column != "tool" else "left")
+    for step in summary.steps:
+        total = sum(value or 0.0 for value in (step.observe_s, step.llm_s, step.tool_s))
+        table.add_row(
+            str(step.step_idx),
+            step.tool_name or "--",
+            _fmt_s(step.observe_s),
+            _fmt_s(step.llm_s),
+            _fmt_s(step.tool_s),
+            f"{total:.2f}",
+        )
+    table.add_section()
+    table.add_row(
+        "avg",
+        "",
+        _fmt_s(summary.avg_observe_s),
+        _fmt_s(summary.avg_llm_s),
+        _fmt_s(summary.avg_tool_s),
+        _fmt_s(summary.avg_step_s),
+        style="bold",
+    )
+    console.print(table)
+
+
+def _load_records(event_log: Path | None) -> list[tuple[datetime, AgentEventData]]:
+    if event_log is None or not event_log.exists():
+        return []
+    records: list[tuple[datetime, AgentEventData]] = []
+    for line in event_log.read_text(encoding="utf-8").splitlines():
+        try:
+            record = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(record, dict):
+            continue
+        raw_event = record.get("event")
+        if not isinstance(raw_event, dict):
+            continue
+        ts = _parse_ts(record.get("ts"))
+        if ts is None:
+            continue
+        parsed = parse_agent_event_data(raw_event)
+        if parsed is None:
+            continue
+        records.append((ts, parsed))
+    return records
+
+
+def _derive_steps(records: list[tuple[datetime, AgentEventData]]) -> list[_StepTiming]:
+    steps: list[_StepTiming] = []
+    first_event_at: datetime | None = None
+    prev_step_end_at: datetime | None = None
+    observe_at: datetime | None = None
+    llm_at: datetime | None = None
+    pending: _StepTiming | None = None
+
+    for ts, event in records:
+        if first_event_at is None:
+            first_event_at = ts
+        match event:
+            case ObservationEvent():
+                if pending is not None:
+                    steps.append(pending)
+                baseline = prev_step_end_at or first_event_at or ts
+                pending = _StepTiming(step_idx=len(steps) + 1, observe_s=_seconds(ts - baseline))
+                observe_at = ts
+                llm_at = None
+            case PolicyEvent():
+                if pending is None:
+                    pending = _StepTiming(step_idx=len(steps) + 1, observe_s=None)
+                    observe_at = None
+                    llm_at = None
+                boundary = observe_at or prev_step_end_at or first_event_at
+                if boundary is not None:
+                    pending.llm_s = _seconds(ts - boundary)
+                pending.tool_name = _first_tool_name(event)
+                llm_at = ts
+            case ToolResultEvent() if pending is not None:
+                _close_step(steps, pending, ts=ts, llm_at=llm_at, failed=False)
+                pending = None
+                prev_step_end_at = ts
+                observe_at = None
+                llm_at = None
+            case ErrorEvent() if pending is not None and event.origin in _TOOL_ERROR_ORIGINS:
+                _close_step(steps, pending, ts=ts, llm_at=llm_at, failed=True)
+                pending = None
+                prev_step_end_at = ts
+                observe_at = None
+                llm_at = None
+    if pending is not None:
+        steps.append(pending)
+    return steps
+
+
+def _close_step(
+    steps: list[_StepTiming],
+    pending: _StepTiming,
+    *,
+    ts: datetime,
+    llm_at: datetime | None,
+    failed: bool,
+) -> None:
+    if llm_at is not None:
+        pending.tool_s = _seconds(ts - llm_at)
+    pending.failed = failed
+    steps.append(pending)
+
+
+def _first_tool_name(event: PolicyEvent) -> str | None:
+    return event.tool_reqs[0].tool_name if event.tool_reqs else None
+
+
+def _parse_ts(raw: object) -> datetime | None:
+    if not isinstance(raw, str):
+        return None
+    try:
+        return datetime.fromisoformat(raw.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def _mean(values: Iterable[float | None]) -> float | None:
+    present = [value for value in values if value is not None]
+    if not present:
+        return None
+    return round(statistics.fmean(present), 3)
+
+
+def _seconds(delta: timedelta) -> float:
+    # Clamp: out-of-order or clock-skewed timestamps must not yield a negative phase duration.
+    return round(max(0.0, delta.total_seconds()), 3)
+
+
+def _fmt_s(value: float | None) -> str:
+    return f"{value:.2f}" if value is not None else "--"