gdmcode 0.1.0__py3-none-any.whl

src/server/protocol_version.py

@@ -0,0 +1,103 @@
+"""WebSocket protocol version constants and compatibility checks.
+
+Every WebSocket connection (bridge, remote, IDE, Chrome extension) must begin
+with a 'hello' handshake. The server sends its version and capability set;
+the client checks compatibility before sending commands.
+
+Versioning policy:
+  - Major version bump = breaking change; both sides must update
+  - Minor version bump = additive only; backward-compatible
+  - Client major != server major → close with code 4000 + error message
+  - Client minor > server minor → log warning, continue (server may lack new features)
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = [
+    "PROTOCOL_VERSION",
+    "PROTOCOL_MAJOR",
+    "PROTOCOL_MINOR",
+    "CapabilitySet",
+    "is_compatible",
+    "make_hello_message",
+    "make_version_mismatch_error",
+]
+
+PROTOCOL_VERSION: str = "1.0"
+PROTOCOL_MAJOR: int = 1
+PROTOCOL_MINOR: int = 0
+
+
+@dataclass
+class CapabilitySet:
+    """Server capability advertisement sent in the hello message."""
+
+    dom_actions: bool = True
+    screenshot: bool = True
+    navigation: bool = True
+    mobile: bool = False
+    voice: bool = False
+    remote: bool = False
+
+    def to_dict(self) -> dict[str, bool]:
+        return {
+            "dom_actions": self.dom_actions,
+            "screenshot": self.screenshot,
+            "navigation": self.navigation,
+            "mobile": self.mobile,
+            "voice": self.voice,
+            "remote": self.remote,
+        }
+
+
+def is_compatible(client_version: str) -> tuple[bool, str]:
+    """Check if client_version is compatible with this server.
+
+    Returns (compatible: bool, reason: str).
+    - compatible=True, reason="" if versions match exactly
+    - compatible=True, reason=warning if minor version mismatch (client ahead)
+    - compatible=False, reason=error if major version mismatch or invalid format
+    """
+    try:
+        parts = client_version.split(".")
+        client_major = int(parts[0])
+        client_minor = int(parts[1]) if len(parts) > 1 else 0
+    except (ValueError, IndexError):
+        return False, f"Invalid version format: {client_version!r}"
+
+    if client_major != PROTOCOL_MAJOR:
+        return False, (
+            f"Client v{client_version} required, got server v{PROTOCOL_VERSION}. "
+            "Please update the gdm extension."
+        )
+    if client_minor > PROTOCOL_MINOR:
+        return True, (
+            f"Client v{client_version} is ahead of server v{PROTOCOL_VERSION}"
+            " — some client features may not be supported"
+        )
+    return True, ""
+
+
+def make_hello_message(
+    server_name: str = "gdm-bridge",
+    capabilities: CapabilitySet | None = None,
+) -> dict:
+    """Build the hello message the server sends on WebSocket open."""
+    caps = capabilities or CapabilitySet()
+    return {
+        "type": "hello",
+        "protocol_version": PROTOCOL_VERSION,
+        "capabilities": caps.to_dict(),
+        "server": server_name,
+    }
+
+
+def make_version_mismatch_error(client_version: str) -> dict:
+    """Build the error message sent before closing on major version mismatch."""
+    _, reason = is_compatible(client_version)
+    return {
+        "type": "error",
+        "code": "version_mismatch",
+        "message": reason,
+    }

src/session/__init__.py

@@ -0,0 +1,10 @@
+"""Session management — multiplexed I/O and permission bridge."""
+from src.session.input_broker import InputBroker, InputMessage
+from src.session.event_fanout import EventFanout, SessionEvent
+from src.session.permission_bridge import PermissionBridge
+
+__all__ = [
+    "InputBroker", "InputMessage",
+    "EventFanout", "SessionEvent",
+    "PermissionBridge",
+]

src/session/event_fanout.py

@@ -0,0 +1,46 @@
+"""EventFanout — bounded pub/sub event distribution."""
+from __future__ import annotations
+import logging
+import queue
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+__all__ = ["EventFanout", "SessionEvent"]
+
+log = logging.getLogger(__name__)
+
+@dataclass
+class SessionEvent:
+    type: str
+    payload: Any = None
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+class EventFanout:
+    """Bounded per-subscriber queues with put_nowait drop (no blocking)."""
+
+    def __init__(self) -> None:
+        self._subscribers: dict[str, queue.Queue[SessionEvent]] = {}
+
+    def subscribe(self, name: str, maxsize: int = 100) -> queue.Queue[SessionEvent]:
+        """Register a subscriber. Returns the queue to read from."""
+        q: queue.Queue[SessionEvent] = queue.Queue(maxsize=maxsize)
+        self._subscribers[name] = q
+        log.debug("EventFanout: subscribed %s", name)
+        return q
+
+    def publish(self, event: SessionEvent) -> None:
+        """Publish event to all subscribers. put_nowait — drops on full queue."""
+        for name, q in list(self._subscribers.items()):
+            try:
+                q.put_nowait(event)
+            except queue.Full:
+                log.warning("EventFanout: subscriber %s queue full — event dropped", name)
+
+    def unsubscribe(self, name: str) -> None:
+        """Remove subscriber."""
+        self._subscribers.pop(name, None)
+        log.debug("EventFanout: unsubscribed %s", name)
+
+    def subscriber_count(self) -> int:
+        return len(self._subscribers)

src/session/input_broker.py

@@ -0,0 +1,38 @@
+"""InputBroker — thread-safe multiplexed input queue."""
+from __future__ import annotations
+import logging
+import queue
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Optional
+
+__all__ = ["InputBroker", "InputMessage"]
+
+log = logging.getLogger(__name__)
+
+@dataclass
+class InputMessage:
+    source: str       # "terminal" | "remote" | "voice"
+    text: str
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+class InputBroker:
+    """Thread-safe queue that multiplexes terminal + remote + voice input."""
+
+    def __init__(self, maxsize: int = 0) -> None:
+        self._queue: queue.Queue[InputMessage] = queue.Queue(maxsize=maxsize)
+
+    def put(self, source: str, message: str) -> None:
+        """Enqueue input from any source. Non-blocking."""
+        self._queue.put(InputMessage(source=source, text=message))
+        log.debug("InputBroker.put source=%s len=%d", source, len(message))
+
+    def get(self, timeout: float | None = None) -> InputMessage | None:
+        """Blocking dequeue. Returns None on timeout."""
+        try:
+            return self._queue.get(timeout=timeout)
+        except queue.Empty:
+            return None
+
+    def qsize(self) -> int:
+        return self._queue.qsize()

src/session/permission_bridge.py

@@ -0,0 +1,100 @@
+"""PermissionBridge — sync↔async permission request gateway with UUID tracking."""
+from __future__ import annotations
+import logging
+import threading
+import uuid
+from dataclasses import dataclass
+
+__all__ = ["PermissionBridge", "PermissionBridgeConflict"]
+
+log = logging.getLogger(__name__)
+
+
+class PermissionBridgeConflict(Exception):
+    """Raised when a second request arrives while one is already pending."""
+
+
+@dataclass
+class _PendingRequest:
+    request_id: str
+    prompt: str
+    event: threading.Event
+    result: bool = False
+
+
+class PermissionBridge:
+    """Bridges sync PermissionContext._prompt_user() to async remote/voice handlers.
+
+    v1 constraint: only ONE outstanding permission request per bridge instance.
+    Concurrent requests raise PermissionBridgeConflict.
+
+    Usage::
+        bridge = PermissionBridge()
+
+        # In sync caller thread:
+        approved = bridge.request("Delete /etc/hosts?", timeout=60.0)
+
+        # In async handler thread:
+        bridge.respond(request_id, True)
+    """
+
+    def __init__(self, fanout: "EventFanout | None" = None) -> None:
+        self._fanout = fanout
+        self._lock = threading.Lock()
+        self._pending: _PendingRequest | None = None
+
+    def request(self, prompt: str, timeout: float = 60.0) -> bool:
+        """Block until approved/denied or timeout.
+
+        Returns True if approved, False on denial or timeout.
+        Raises PermissionBridgeConflict if a request is already pending.
+        """
+        request_id = str(uuid.uuid4())
+        with self._lock:
+            if self._pending is not None:
+                raise PermissionBridgeConflict(
+                    f"Permission request already pending: {self._pending.prompt!r}"
+                )
+            event = threading.Event()
+            self._pending = _PendingRequest(
+                request_id=request_id, prompt=prompt, event=event
+            )
+
+        # Publish event so remote/voice handlers see it
+        if self._fanout is not None:
+            from src.session.event_fanout import SessionEvent
+            self._fanout.publish(SessionEvent(
+                type="permission_request",
+                payload={"request_id": request_id, "prompt": prompt},
+            ))
+
+        log.info("PermissionBridge: awaiting decision for request_id=%s", request_id)
+        approved = event.wait(timeout=timeout)
+
+        with self._lock:
+            result = self._pending.result if approved else False
+            self._pending = None
+
+        if not approved:
+            log.warning("PermissionBridge: request %s timed out → DENY", request_id)
+        return result
+
+    def respond(self, request_id: str, approved: bool) -> bool:
+        """Called from async handler. Returns False if request_id not found."""
+        with self._lock:
+            if self._pending is None or self._pending.request_id != request_id:
+                log.warning(
+                    "PermissionBridge.respond: unknown request_id=%s (pending=%s)",
+                    request_id,
+                    self._pending.request_id if self._pending else None,
+                )
+                return False
+            self._pending.result = approved
+            self._pending.event.set()
+        log.info("PermissionBridge: responded request_id=%s approved=%s", request_id, approved)
+        return True
+
+    def pending_request_id(self) -> str | None:
+        """Returns the current pending request_id, or None."""
+        with self._lock:
+            return self._pending.request_id if self._pending else None

src/tools/__init__.py

@@ -0,0 +1,160 @@
+"""Tool registry and base class for all gdm tools.
+
+Every concrete tool:
+  1. Subclasses ToolBase
+  2. Declares `name`, `description`, `input_schema`
+  3. Implements `execute(params) -> ToolResult`
+  4. Calls ToolRegistry.register(cls) at module level
+
+The registry is a module-level singleton — import the module, tools are registered.
+"""
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, ClassVar
+
+__all__ = [
+    "ToolBase",
+    "ToolResult",
+    "ToolRegistry",
+    "REGISTRY",
+    "BrowserTools",
+    "BrowserToolResult",
+]
+
+log = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# ToolResult
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ToolResult:
+    """Structured output from a tool invocation."""
+
+    output: str
+    """Human-readable output shown to the model and user."""
+
+    error: str | None = None
+    """If set, the tool failed. The agent will decide whether to retry."""
+
+    exit_code: int | None = None
+    """For shell tools — the process exit code."""
+
+    truncated: bool = False
+    """True when output was truncated to fit the context window."""
+
+    metadata: dict[str, Any] = field(default_factory=dict)
+    """Optional extra data (file paths modified, bytes read, etc.)."""
+
+    @property
+    def ok(self) -> bool:
+        """True when the tool succeeded (error is None or empty string)."""
+        return not self.error
+
+    def as_message_content(self) -> str:
+        """Render for inclusion in an LLM tool-result message."""
+        if self.error:
+            lines = [f"ERROR: {self.error}"]
+            if self.exit_code is not None:
+                lines.append(f"Exit code: {self.exit_code}")
+            return "\n".join(lines)
+        parts = [self.output]
+        if self.truncated:
+            parts.append("\n[Output truncated — request the next chunk if needed]")
+        return "\n".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# ToolBase
+# ---------------------------------------------------------------------------
+
+class ToolBase(ABC):
+    """Abstract base for every gdm tool."""
+
+    name: ClassVar[str]
+    """Unique snake_case identifier. Sent verbatim to the model."""
+
+    description: ClassVar[str]
+    """One- or two-sentence description the model uses to decide when to call this tool."""
+
+    input_schema: ClassVar[dict[str, Any]]
+    """JSON Schema object for the tool's parameters."""
+
+    @abstractmethod
+    def execute(self, params: dict[str, Any]) -> ToolResult:
+        """Run the tool and return a result.
+
+        Must never raise — catch all exceptions and return ToolResult(error=...).
+        """
+
+    def to_openai_spec(self) -> dict[str, Any]:
+        """Return the tool definition dict for the OpenAI tools array."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.input_schema,
+            },
+        }
+
+
+# ---------------------------------------------------------------------------
+# ToolRegistry
+# ---------------------------------------------------------------------------
+
+class ToolRegistry:
+    """Global registry of all available tool instances.
+
+    Usage::
+
+        from src.tools import REGISTRY
+        spec_list = REGISTRY.openai_specs()   # pass to client.chat.completions
+        result = REGISTRY.call("bash", {"command": "ls"})
+    """
+
+    def __init__(self) -> None:
+        self._tools: dict[str, ToolBase] = {}
+
+    def register(self, tool: ToolBase) -> None:
+        """Register a tool instance. Called once per tool at import time."""
+        if tool.name in self._tools:
+            log.warning("Tool %r already registered — overwriting", tool.name)
+        self._tools[tool.name] = tool
+
+    def get(self, name: str) -> ToolBase | None:
+        """Return a tool by name, or None if not found."""
+        return self._tools.get(name)
+
+    def all_tools(self) -> list[ToolBase]:
+        """Return all registered tools."""
+        return list(self._tools.values())
+
+    def openai_specs(self, exclude: frozenset[str] | None = None) -> list[dict[str, Any]]:
+        """Return OpenAI tool-spec dicts, optionally excluding denied tools."""
+        if exclude is None:
+            exclude = frozenset()
+        return [t.to_openai_spec() for t in self._tools.values() if t.name not in exclude]
+
+    def call(self, name: str, params: dict[str, Any]) -> ToolResult:
+        """Dispatch a tool call by name. Returns an error result if not found."""
+        tool = self._tools.get(name)
+        if tool is None:
+            return ToolResult(output="", error=f"Unknown tool: {name!r}")
+        try:
+            return tool.execute(params)
+        except Exception as exc:  # noqa: BLE001
+            log.exception("Tool %r raised unexpectedly", name)
+            return ToolResult(output="", error=f"Tool raised: {exc}")
+
+
+# Module-level singleton — all concrete tool modules import and extend this.
+REGISTRY: ToolRegistry = ToolRegistry()
+
+# Re-export browser tools so callers can do `from src.tools import BrowserTools`.
+# Import after REGISTRY is defined to avoid circular imports.
+from src.tools.browser_tools import BrowserToolResult, BrowserTools, BrowserToolsSync  # noqa: E402, F401

src/tools/_atomic.py

@@ -0,0 +1,72 @@
+"""Atomic file-write helpers for gdm tools.
+
+Uses write-to-temp + fsync + os.replace() to ensure a SIGTERM or power failure
+during a write never leaves a half-written (corrupted) file.
+
+Each temp file has a UUID component so concurrent writes to the same path
+(from multiple ThreadPoolExecutor workers) cannot collide.
+"""
+from __future__ import annotations
+
+import os
+import uuid
+from pathlib import Path
+
+__all__ = ["_atomic_write", "sweep_orphans"]
+
+_TMP_SUFFIX = ".gdm_tmp"
+
+
+def _atomic_write(path: str | Path, content: str | bytes, *, encoding: str = "utf-8") -> None:
+    """Write content to path atomically via a uniquely-named temp file.
+
+    Steps: open unique temp → write → fsync → os.replace() → fsync parent dir.
+    On any failure the temp file is deleted and the original is untouched.
+
+    Raises:
+        ValueError: if path is a symlink (refusing to replace a symlink target).
+    """
+    path = Path(path)
+    if path.is_symlink():
+        raise ValueError(f"Refusing to atomically replace symlink: {path}")
+    tmp = path.with_name(path.name + f".{uuid.uuid4().hex}{_TMP_SUFFIX}")
+    try:
+        mode = "wb" if isinstance(content, bytes) else "w"
+        kwargs: dict = {} if isinstance(content, bytes) else {"encoding": encoding}
+        with open(tmp, mode, **kwargs) as fh:
+            fh.write(content)
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.replace(tmp, path)
+        # fsync parent directory so the directory entry is durable (POSIX only)
+        try:
+            dir_fd = os.open(str(path.parent), os.O_RDONLY)
+            try:
+                os.fsync(dir_fd)
+            finally:
+                os.close(dir_fd)
+        except (AttributeError, OSError):
+            pass  # Windows does not support O_RDONLY on directories — best-effort
+    except BaseException:
+        try:
+            tmp.unlink(missing_ok=True)
+        except OSError:
+            pass
+        raise
+
+
+def sweep_orphans(root: str | Path) -> int:
+    """Delete any leftover *.gdm_tmp files under root. Returns count deleted.
+
+    Called once at startup (background thread) to clean up temp files left by
+    previous crashes.
+    """
+    root = Path(root)
+    count = 0
+    for p in root.rglob(f"*{_TMP_SUFFIX}"):
+        try:
+            p.unlink()
+            count += 1
+        except OSError:
+            pass
+    return count