directops-operator 0.1.9__py3-none-any.whl

agent/__init__.py

@@ -0,0 +1,6 @@
+"""Operator — DOPS client that connects to the Director and executes tasks."""
+
+from .client import OperatorClient
+from .executor import TaskExecutor
+
+__all__ = ["OperatorClient", "TaskExecutor"]

agent/cli.py

@@ -0,0 +1,146 @@
+"""Operator CLI entry point.
+
+Usage:
+    python -m agent.cli --host 65.108.215.205 --port 9000
+
+No API key required on the Operator machine — the Director handles all model
+calls (Claude for planning, Devstral for implementation). See DIRECTIVE.md AD-1.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import os
+import socket
+import sys
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="directops-operator",
+        description="DirectOps Operator — connects to the Director and executes tasks.",
+    )
+    parser.add_argument(
+        "--url",
+        default=os.environ.get("DIRECTOR_URL", ""),
+        help="Director WebSocket URL for production use, e.g. wss://director.directops.io/ws/operator "
+             "(default: $DIRECTOR_URL). When set, overrides --host/--port.",
+    )
+    parser.add_argument(
+        "--host",
+        default=os.environ.get("DIRECTOR_HOST", "127.0.0.1"),
+        help="Director host for TCP mode (default: $DIRECTOR_HOST or 127.0.0.1)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=int(os.environ.get("DIRECTOR_PORT", "9000")),
+        help="Director port for TCP mode (default: $DIRECTOR_PORT or 9000)",
+    )
+    parser.add_argument(
+        "--operator-id",
+        default="",
+        help="Stable operator ID (default: hostname-based)",
+    )
+    parser.add_argument(
+        "--name",
+        default="",
+        help="Display name for this machine in the dashboard (default: hostname)",
+    )
+    parser.add_argument(
+        "--model",
+        default="devstral-small-latest",
+        help="Model name to advertise on registration (informational only; no local API call)",
+    )
+    parser.add_argument(
+        "--capabilities",
+        nargs="+",
+        default=["code", "shell", "search"],
+        metavar="CAP",
+        help="Task types this operator handles (default: code shell search)",
+    )
+    parser.add_argument(
+        "--token",
+        default=os.environ.get("OPERATOR_TOKEN", ""),
+        help="Auth token issued by the Director (default: $OPERATOR_TOKEN)",
+    )
+    parser.add_argument(
+        "--workdir",
+        default=None,
+        help="Working directory for task execution (default: ~/directops-workspace)",
+    )
+    tls_grp = parser.add_argument_group("TLS")
+    tls_grp.add_argument(
+        "--no-tls",
+        action="store_true",
+        help="Disable TLS (insecure — for local testing only)",
+    )
+    tls_grp.add_argument(
+        "--ca-cert",
+        default=os.environ.get("DIRECTOR_CA_CERT"),
+        metavar="PATH",
+        help="Custom CA certificate for Director verification (default: system trust store)",
+    )
+    parser.add_argument(
+        "--log-level",
+        default="INFO",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+        help="Log verbosity (default: INFO)",
+    )
+    return parser.parse_args()
+
+
+async def _run(args: argparse.Namespace) -> None:
+    # Imports here so the module is importable without heavy deps at load time
+    from .client import OperatorClient
+    from .executor import TaskExecutor
+    from .discovery import load_or_run
+    from .updater import check_and_maybe_update
+
+    check_and_maybe_update()
+
+    system_context = load_or_run()
+
+    executor = TaskExecutor(workdir=args.workdir)
+    client = OperatorClient(
+        director_url=args.url,
+        director_host=args.host,
+        director_port=args.port,
+        operator_id=args.operator_id,
+        capabilities=args.capabilities,
+        executor=executor,
+        model=args.model,
+        auth_token=args.token,
+        tls=not args.no_tls,
+        ca_cert=args.ca_cert,
+        display_name=args.name,
+        system_context=system_context,
+    )
+
+    if args.url:
+        logging.info("Starting operator %s → %s (WebSocket)", client.operator_id, args.url)
+    else:
+        logging.info("Starting operator %s → %s:%d (TCP)", client.operator_id, args.host, args.port)
+
+    try:
+        await client.run()
+    except KeyboardInterrupt:
+        await client.stop()
+
+
+def main() -> None:
+    args = _parse_args()
+    logging.basicConfig(
+        level=getattr(logging, args.log_level),
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+    try:
+        asyncio.run(_run(args))
+    except KeyboardInterrupt:
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

agent/client.py

@@ -0,0 +1,423 @@
+"""OperatorClient — asyncio client implementing the DOPS protocol."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import platform
+import socket
+import ssl
+import time
+from typing import Any
+
+from protocol.constants import MessageType, OperatorState
+from protocol.messages import (
+    RegisterMessage,
+    TaskCompleteMessage,
+    TaskErrorMessage,
+    TaskUpdateMessage,
+    HeartbeatMessage,
+    AckMessage,
+    EventMessage,
+    TaskNeedsPasswordMessage,
+    deserialize,
+)
+from protocol.state import ConnectionStateMachine
+from protocol.transport import DopsTransport
+
+from .executor import TaskExecutor  # noqa: F401 (re-exported)
+
+logger = logging.getLogger(__name__)
+
+HEARTBEAT_INTERVAL = 15.0  # seconds between keep-alive pings
+RECONNECT_DELAY = 5.0      # seconds to wait before reconnecting
+
+
+class OperatorClient:
+    """Manages the connection from an Operator to the Director.
+
+    Supports two transport modes:
+    - WebSocket (production): pass director_url="wss://director.directops.io/ws/operator"
+    - TCP (local dev): pass director_host and director_port
+
+    Args:
+        director_url: WebSocket URL for production use (overrides host/port).
+        director_host: IP or hostname of the Director server (TCP mode).
+        director_port: TCP port the Director listens on (TCP mode).
+        operator_id: Stable identifier for this operator instance.
+        capabilities: List of task-type tags this operator handles.
+        executor: TaskExecutor instance for running assigned tasks.
+        model: Local model name to advertise on registration.
+    """
+
+    def __init__(
+        self,
+        director_host: str = "",
+        director_port: int = 9000,
+        director_url: str = "",
+        operator_id: str = "",
+        capabilities: list[str] | None = None,
+        executor: TaskExecutor | None = None,
+        model: str = "devstral-small-latest",
+        auth_token: str = "",
+        tls: bool = True,
+        ca_cert: str | None = None,
+        display_name: str = "",
+        system_context: dict | None = None,
+    ) -> None:
+        self.host = director_host
+        self.port = director_port
+        self.director_url = director_url
+        self.operator_id = operator_id or f"{socket.gethostname()}-{id(self) & 0xFFFF:04x}"
+        self.capabilities = capabilities or ["code", "shell", "search"]
+        self.executor = executor or TaskExecutor()
+        self.model = model
+        self.auth_token = auth_token
+        self.tls = tls
+        self.ca_cert = ca_cert
+        self.display_name = display_name
+        self.system_context = system_context or {}
+
+        self._state = ConnectionStateMachine(
+            on_transition=self._on_state_change
+        )
+        self._transport: DopsTransport | None = None
+        self._running = False
+        self._current_task_id: str | None = None
+        # Futures waiting for PROVIDE_PASSWORD frames, keyed by task_id
+        self._password_futures: dict[str, asyncio.Future] = {}
+        # Background task for the currently executing task (so the receive loop stays live)
+        self._active_task: asyncio.Task | None = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def run(self) -> None:
+        """Start the operator event loop. Reconnects on disconnect."""
+        self._running = True
+        while self._running:
+            try:
+                await self._connect_and_serve()
+            except asyncio.CancelledError:
+                break
+            except BaseException as exc:
+                if hasattr(exc, 'exceptions'):
+                    for sub in exc.exceptions:
+                        logger.error("Connection sub-error [%s]: %s", type(sub).__name__, sub, exc_info=sub)
+                else:
+                    logger.error("Connection error [%s]: %s", type(exc).__name__, exc)
+                self._state.force(OperatorState.DISCONNECTED)
+                await asyncio.sleep(RECONNECT_DELAY)
+
+    async def stop(self) -> None:
+        """Gracefully shut down the operator."""
+        self._running = False
+        if self._active_task and not self._active_task.done():
+            self._active_task.cancel()
+        if self._transport:
+            await self._transport.close()
+
+    # ------------------------------------------------------------------
+    # Internal: connection lifecycle
+    # ------------------------------------------------------------------
+
+    async def _connect_and_serve(self) -> None:
+        if self.director_url:
+            await self._connect_ws()
+        else:
+            await self._connect_tcp()
+
+    async def _connect_tcp(self) -> None:
+        """Open a raw TCP connection to the Director."""
+        from protocol.tcp_transport import TcpTransport
+
+        ssl_context: ssl.SSLContext | None = None
+        if self.tls:
+            ssl_context = ssl.create_default_context()
+            if self.ca_cert:
+                ssl_context.load_verify_locations(self.ca_cert)
+        else:
+            logger.warning("TLS disabled — connection to Director is unencrypted")
+
+        logger.info(
+            "Connecting to Director at %s:%d (%s)",
+            self.host, self.port, "TLS" if ssl_context else "plaintext",
+        )
+        reader, writer = await asyncio.open_connection(
+            self.host, self.port, ssl=ssl_context
+        )
+        self._transport = TcpTransport(reader, writer)
+        self._state.force(OperatorState.CONNECTED)
+        logger.info("Connected (TCP). Sending REGISTER…")
+        await self._serve()
+
+    async def _connect_ws(self) -> None:
+        """Connect to the Director via WebSocket (port 443 compatible)."""
+        import websockets
+        from .ws_transport import ClientWebSocketTransport
+
+        logger.info("Connecting to Director at %s (WebSocket)", self.director_url)
+        async with websockets.connect(self.director_url) as ws:
+            self._transport = ClientWebSocketTransport(ws)
+            self._state.force(OperatorState.CONNECTED)
+            logger.info("Connected (WebSocket). Sending REGISTER…")
+            await self._serve()
+
+    async def _serve(self) -> None:
+        """Common post-connect logic: register then run recv + heartbeat loops."""
+        await self._send_register()
+        async with asyncio.TaskGroup() as tg:
+            tg.create_task(self._receive_loop())
+            tg.create_task(self._heartbeat_loop())
+
+    async def _send_register(self) -> None:
+        hostname = socket.gethostname()
+        msg = RegisterMessage(
+            operator_id=self.operator_id,
+            capabilities=self.capabilities,
+            model=self.model,
+            hostname=hostname,
+            auth_token=self.auth_token,
+            os_info=f"{platform.system()} {platform.release()}",
+            display_name=self.display_name or hostname,
+            system_context=self.system_context,
+        )
+        await self._transport.send_frame(MessageType.REGISTER, msg.to_bytes())
+
+    # ------------------------------------------------------------------
+    # Internal: receive loop
+    # ------------------------------------------------------------------
+
+    async def _receive_loop(self) -> None:
+        """Read frames from the Director and dispatch them."""
+        while self._running:
+            frame = await self._transport.recv_frame()
+            await self._dispatch(frame.msg_type, frame.payload)
+
+    async def _dispatch(self, msg_type: MessageType, payload: bytes) -> None:
+        """Route an incoming frame to the appropriate handler."""
+        msg = deserialize(msg_type, payload)
+
+        match msg_type:
+            case MessageType.REGISTER_ACK:
+                self._state.transition(MessageType.REGISTER)
+                logger.info("Registered with Director. Operator ID: %s", self.operator_id)
+                await self._transport.send_frame(
+                    MessageType.ACK,
+                    AckMessage(ack_id=msg.message_id).to_bytes(),
+                )
+
+            case MessageType.TASK_ASSIGN:
+                # Spawn as a background task so the receive loop stays live.
+                # This is required for PROVIDE_PASSWORD frames to be processed
+                # while a task is blocked waiting for a credential.
+                self._active_task = asyncio.create_task(self._handle_task_assign(msg))
+
+            case MessageType.HEARTBEAT:
+                await self._transport.send_frame(
+                    MessageType.HEARTBEAT_ACK,
+                    HeartbeatMessage(timestamp=time.time()).to_bytes(),
+                )
+
+            case MessageType.HEARTBEAT_ACK:
+                pass  # pong received, nothing to do
+
+            case MessageType.ACK:
+                pass
+
+            case MessageType.NACK:
+                reason = getattr(msg, "reason", "")
+                logger.error("Director rejected registration: %s", reason)
+                self._running = False
+                raise ConnectionError(f"Registration rejected: {reason}")
+
+            case MessageType.PROVIDE_PASSWORD:
+                await self._handle_provide_password(msg)
+
+            case _:
+                logger.warning("Unhandled message type: %s", msg_type.name)
+
+    # ------------------------------------------------------------------
+    # Internal: task execution
+    # ------------------------------------------------------------------
+
+    async def _handle_task_assign(self, msg: Any) -> None:
+        """Execute an assigned task and report results back to the Director."""
+        self._state.transition(MessageType.TASK_ASSIGN)
+        self._current_task_id = msg.task_id
+        logger.info("Task assigned: %s (%s)", msg.task_id, msg.task_type)
+
+        # Acknowledge receipt
+        await self._transport.send_frame(
+            MessageType.ACK,
+            AckMessage(ack_id=msg.message_id).to_bytes(),
+        )
+
+        # Run with a timeout guard
+        try:
+            async with asyncio.timeout(msg.timeout_seconds):
+                result = await self._execute_with_updates(msg)
+        except TimeoutError:
+            await self._send_error(msg.task_id, "TIMEOUT", "Task exceeded timeout", retryable=True)
+            return
+        except Exception as exc:
+            await self._send_error(msg.task_id, "EXECUTOR_CRASH", str(exc), retryable=False)
+            return
+
+        if result.success:
+            await self._send_complete(msg.task_id, result)
+            self._state.transition(MessageType.TASK_COMPLETE)
+        else:
+            await self._send_error(
+                msg.task_id,
+                result.error_code,
+                result.error_detail,
+                retryable=True,
+            )
+
+        self._current_task_id = None
+
+    async def _execute_with_updates(self, msg: Any):
+        """Run the executor while sending a mid-task progress update."""
+        await self._send_update(msg.task_id, 0, "Starting…")
+
+        task_id = msg.task_id
+
+        async def event_fn(event_type: str, data: dict) -> None:
+            await self._emit_event(event_type, task_id, data)
+
+        async def password_fn(tid: str, prompt: str) -> str | None:
+            """Request a credential from the Director, return plaintext or None on timeout/deny."""
+            if not self._transport or self._transport.is_closing:
+                return None
+            needs_msg = TaskNeedsPasswordMessage(task_id=tid, prompt=prompt)
+            await self._transport.send_frame(MessageType.TASK_NEEDS_PASSWORD, needs_msg.to_bytes())
+            logger.info("Credential requested for task %s: %s", tid, prompt)
+
+            fut: asyncio.Future = asyncio.get_event_loop().create_future()
+            self._password_futures[tid] = fut
+            try:
+                # Wait slightly longer than the server's 120s timeout
+                return await asyncio.wait_for(fut, timeout=130.0)
+            except asyncio.TimeoutError:
+                logger.warning("Credential request timed out for task %s", tid)
+                return None
+            finally:
+                self._password_futures.pop(tid, None)
+
+        result = await self.executor.execute(
+            task_type=msg.task_type,
+            instruction=msg.instruction,
+            context=msg.context,
+            event_fn=event_fn,
+            password_fn=password_fn,
+            task_id=task_id,
+        )
+
+        await self._send_update(msg.task_id, 100, "Done")
+        return result
+
+    async def _handle_provide_password(self, msg: Any) -> None:
+        """Decrypt an incoming PROVIDE_PASSWORD frame and resolve the waiting future."""
+        from protocol.crypto import decrypt_password
+
+        encrypted = {"nonce": msg.nonce, "ciphertext": msg.ciphertext, "tag": msg.tag}
+        try:
+            password = decrypt_password(encrypted, self.auth_token)
+        except Exception as exc:
+            logger.error("Failed to decrypt credential for task %s: %s", msg.task_id, exc)
+            fut = self._password_futures.get(msg.task_id)
+            if fut and not fut.done():
+                fut.set_exception(exc)
+            return
+
+        fut = self._password_futures.get(msg.task_id)
+        if fut and not fut.done():
+            fut.set_result(password)
+            logger.info("Credential decrypted and delivered for task %s", msg.task_id)
+        else:
+            logger.warning("No pending credential future for task %s", msg.task_id)
+        # Don't hold the plaintext any longer than necessary
+        password = None  # noqa: F841
+
+    async def _send_update(self, task_id: str, progress: int, status: str) -> None:
+        self._state.transition(MessageType.TASK_UPDATE)
+        msg = TaskUpdateMessage(task_id=task_id, progress=progress, status_text=status)
+        await self._transport.send_frame(MessageType.TASK_UPDATE, msg.to_bytes())
+
+    async def _send_complete(self, task_id: str, result) -> None:
+        msg = TaskCompleteMessage(
+            task_id=task_id,
+            result=result.artifacts,
+            duration_seconds=result.duration_seconds,
+        )
+        await self._transport.send_frame(MessageType.TASK_COMPLETE, msg.to_bytes())
+        logger.info("Task %s completed in %.2fs", task_id, result.duration_seconds)
+        await self._emit_event("task_executed", task_id, {
+            "status": "success",
+            "duration_seconds": result.duration_seconds,
+            "output_preview": result.output[:200] if result.output else "",
+        })
+
+    async def _send_error(
+        self, task_id: str, error_code: str, detail: str, retryable: bool
+    ) -> None:
+        msg = TaskErrorMessage(
+            task_id=task_id,
+            error_code=error_code,
+            error_detail=detail,
+            retryable=retryable,
+        )
+        await self._transport.send_frame(MessageType.TASK_ERROR, msg.to_bytes())
+        logger.error("Task %s failed [%s]: %s", task_id, error_code, detail)
+        self._state.transition(MessageType.TASK_ERROR)
+        await self._emit_event("command_failed", task_id, {
+            "error_code": error_code,
+            "detail": detail[:200],
+            "retryable": retryable,
+        })
+
+    async def _emit_event(self, event_type: str, task_id: str, payload: dict) -> None:
+        import json
+        if not self._transport or self._transport.is_closing:
+            return
+        try:
+            ev = EventMessage(
+                event_type=event_type,
+                task_id=task_id,
+                payload=json.dumps(payload),
+                timestamp=time.time(),
+            )
+            await self._transport.send_frame(MessageType.EVENT, ev.to_bytes())
+        except Exception:
+            pass  # fire-and-forget: never let telemetry break task flow
+
+    # ------------------------------------------------------------------
+    # Internal: heartbeat loop
+    # ------------------------------------------------------------------
+
+    async def _heartbeat_loop(self) -> None:
+        """Send periodic HEARTBEAT frames to keep the connection alive."""
+        while self._running:
+            await asyncio.sleep(HEARTBEAT_INTERVAL)
+            try:
+                if self._transport and not self._transport.is_closing:
+                    await self._transport.send_frame(
+                        MessageType.HEARTBEAT,
+                        HeartbeatMessage(timestamp=time.time()).to_bytes(),
+                    )
+            except Exception as exc:
+                logger.error("Heartbeat failed [%s]: %s", type(exc).__name__, exc)
+                raise
+
+    # ------------------------------------------------------------------
+    # Internal: state change hook
+    # ------------------------------------------------------------------
+
+    def _on_state_change(
+        self, old: OperatorState, new: OperatorState, trigger: MessageType
+    ) -> None:
+        logger.debug(
+            "State: %s → %s (trigger: %s)", old.name, new.name, trigger.name
+        )