coding-bridge-agent 2026.6.8.0__py3-none-any.whl

coding_bridge_agent/__init__.py

@@ -0,0 +1,8 @@
+"""Coding Bridge Agent — node daemon for AceDataCloud Coding Bridge.
+
+Runs on a developer's own machine, connects out to the coding-bridge relay, and
+drives local Claude Code sessions on behalf of an authenticated browser. All
+code execution stays local; the bridge only relays messages.
+"""
+
+__version__ = "0.1.0"

coding_bridge_agent/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m coding_bridge_agent`` entry point."""
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

coding_bridge_agent/cli.py

@@ -0,0 +1,185 @@
+"""Command-line interface: ``pair``, ``run``, ``up``, ``status``, ``logout``."""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import sys
+from pathlib import Path
+
+from . import store
+from .config import Settings
+from .connection import BridgeConnection
+from .pairing import PairingError, poll_for_token, start_pairing
+
+
+def _build_settings(args: argparse.Namespace) -> Settings:
+    settings = Settings.from_env()
+    if getattr(args, "bridge_url", None):
+        settings.bridge_url = args.bridge_url
+    if getattr(args, "name", None):
+        settings.node_name = args.name
+    if getattr(args, "config_dir", None):
+        settings.config_dir = Path(args.config_dir).expanduser()
+    if getattr(args, "model", None):
+        settings.default_model = args.model
+    if getattr(args, "cwd", None):
+        settings.default_cwd = args.cwd
+    if getattr(args, "permission_timeout", None) is not None:
+        settings.permission_timeout = args.permission_timeout
+    return settings
+
+
+def _print_pairing(settings: Settings, pair_code: str) -> None:
+    claim_base = settings.claim_url_template.split("?", 1)[0]
+    claim_url = settings.claim_url_template.format(code=pair_code)
+    print()
+    print("  Pair this machine with your Ace account:")
+    print(f"    1. Open {claim_base}")
+    print(f"    2. Enter pair code:  {pair_code}")
+    print(f"    or open directly:    {claim_url}")
+    _print_qr(claim_url)
+    print()
+
+
+def _print_qr(data: str) -> None:
+    try:
+        import qrcode
+    except ImportError:
+        return
+    qr = qrcode.QRCode(border=1)
+    qr.add_data(data)
+    qr.make(fit=True)
+    qr.print_ascii(invert=True)
+
+
+async def _do_pair(settings: Settings) -> str:
+    pair_code, expires_in = await start_pairing(settings)
+    _print_pairing(settings, pair_code)
+    print(f"  Waiting for confirmation (expires in {expires_in}s)...")
+    deadline = asyncio.get_running_loop().time() + expires_in
+    token = await poll_for_token(settings, pair_code, deadline=deadline)
+    store.save(
+        settings.credentials_path,
+        {"node_token": token, "node_name": settings.node_name, "bridge_url": settings.bridge_url},
+    )
+    print(f"  Paired. Credentials saved to {settings.credentials_path}")
+    return token
+
+
+async def _run_connection(settings: Settings, token: str) -> None:
+    connection = BridgeConnection(settings, token)
+    print(f"  Coding Bridge agent running. Node: {settings.node_name}. Press Ctrl-C to stop.")
+    try:
+        await connection.run()
+    finally:
+        await connection.aclose()
+
+
+def cmd_pair(args: argparse.Namespace) -> None:
+    settings = _build_settings(args)
+    try:
+        asyncio.run(_do_pair(settings))
+    except PairingError as exc:
+        print(f"Pairing failed: {exc}", file=sys.stderr)
+        raise SystemExit(1) from exc
+
+
+def cmd_run(args: argparse.Namespace) -> None:
+    settings = _build_settings(args)
+    creds = store.load(settings.credentials_path)
+    if not creds or not creds.get("node_token"):
+        print("Not paired. Run `coding-bridge-agent pair` first.", file=sys.stderr)
+        raise SystemExit(1)
+    asyncio.run(_run_connection(settings, creds["node_token"]))
+
+
+def cmd_up(args: argparse.Namespace) -> None:
+    settings = _build_settings(args)
+    creds = store.load(settings.credentials_path)
+    token = creds.get("node_token") if creds else None
+
+    async def _go() -> None:
+        nonlocal token
+        if not token:
+            token = await _do_pair(settings)
+        await _run_connection(settings, token)
+
+    try:
+        asyncio.run(_go())
+    except PairingError as exc:
+        print(f"Pairing failed: {exc}", file=sys.stderr)
+        raise SystemExit(1) from exc
+
+
+def cmd_logout(args: argparse.Namespace) -> None:
+    settings = _build_settings(args)
+    removed = store.clear(settings.credentials_path)
+    print("Credentials removed." if removed else "No credentials found.")
+
+
+def cmd_status(args: argparse.Namespace) -> None:
+    settings = _build_settings(args)
+    creds = store.load(settings.credentials_path)
+    paired = bool(creds and creds.get("node_token"))
+    print(f"Bridge URL : {settings.bridge_url}")
+    print(f"Node name  : {settings.node_name}")
+    print(f"Config dir : {settings.config_dir}")
+    print(f"Paired     : {'yes' if paired else 'no'}")
+
+
+def _add_run_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--model", help="Default Claude model for new sessions")
+    parser.add_argument("--cwd", help="Default working directory for new sessions")
+    parser.add_argument(
+        "--permission-timeout",
+        type=float,
+        dest="permission_timeout",
+        help="Seconds to wait for a permission decision (0 = forever)",
+    )
+
+
+def main(argv: list[str] | None = None) -> None:
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--bridge-url", default=argparse.SUPPRESS, help="coding-bridge base URL")
+    common.add_argument("--name", default=argparse.SUPPRESS, help="Display name for this node")
+    common.add_argument(
+        "--config-dir", default=argparse.SUPPRESS, help="Where credentials are stored"
+    )
+
+    parser = argparse.ArgumentParser(
+        prog="coding-bridge-agent",
+        description="Run Claude Code on this machine, driven from the AceDataCloud web app.",
+        parents=[common],
+    )
+    parser.set_defaults(func=cmd_up)
+
+    sub = parser.add_subparsers(dest="command")
+
+    p_up = sub.add_parser("up", help="Pair if needed, then run (default)", parents=[common])
+    _add_run_args(p_up)
+    p_up.set_defaults(func=cmd_up)
+
+    sub.add_parser("pair", help="Pair this machine and exit", parents=[common]).set_defaults(
+        func=cmd_pair
+    )
+
+    p_run = sub.add_parser("run", help="Run using stored credentials", parents=[common])
+    _add_run_args(p_run)
+    p_run.set_defaults(func=cmd_run)
+
+    sub.add_parser(
+        "status", help="Show configuration and pairing state", parents=[common]
+    ).set_defaults(func=cmd_status)
+    sub.add_parser("logout", help="Remove stored credentials", parents=[common]).set_defaults(
+        func=cmd_logout
+    )
+
+    args = parser.parse_args(argv)
+    logging.basicConfig(
+        level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s"
+    )
+    try:
+        args.func(args)
+    except KeyboardInterrupt:
+        print("\nStopped.")

coding_bridge_agent/config.py

@@ -0,0 +1,82 @@
+"""Runtime configuration for the node daemon."""
+from __future__ import annotations
+
+import os
+import socket
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_BRIDGE_URL = "https://coding-bridge.acedata.cloud"
+DEFAULT_CONFIG_DIR = "~/.ace-bridge"
+DEFAULT_CLAIM_URL = "https://nexior.acedata.cloud/bridge?code={code}"
+
+
+def _default_node_name() -> str:
+    try:
+        return socket.gethostname() or "node"
+    except OSError:
+        return "node"
+
+
+@dataclass
+class Settings:
+    """All tunables, sourced from env or CLI flags."""
+
+    bridge_url: str = DEFAULT_BRIDGE_URL
+    node_name: str = ""
+    config_dir: Path = Path(DEFAULT_CONFIG_DIR)
+    heartbeat_interval: float = 15.0
+    reconnect_min: float = 1.0
+    reconnect_max: float = 30.0
+    permission_timeout: float = 300.0  # 0 → wait indefinitely for the user
+    default_cwd: str = ""
+    default_model: str | None = None
+    claim_url_template: str = DEFAULT_CLAIM_URL
+
+    def __post_init__(self) -> None:
+        if not self.node_name:
+            self.node_name = _default_node_name()
+        if not self.default_cwd:
+            self.default_cwd = os.getcwd()
+        self.config_dir = Path(self.config_dir).expanduser()
+
+    @property
+    def _base(self) -> str:
+        return self.bridge_url.rstrip("/")
+
+    @property
+    def ws_node_url(self) -> str:
+        base = self._base
+        if base.startswith("https://"):
+            return "wss://" + base[len("https://") :] + "/ws/node"
+        if base.startswith("http://"):
+            return "ws://" + base[len("http://") :] + "/ws/node"
+        return base + "/ws/node"
+
+    @property
+    def pair_start_url(self) -> str:
+        return f"{self._base}/pair/start"
+
+    @property
+    def pair_poll_url(self) -> str:
+        return f"{self._base}/pair/poll"
+
+    @property
+    def credentials_path(self) -> Path:
+        return self.config_dir / "credentials.json"
+
+    @classmethod
+    def from_env(cls) -> Settings:
+        def _f(name: str, default: float) -> float:
+            raw = os.environ.get(name)
+            return float(raw) if raw else default
+
+        return cls(
+            bridge_url=os.environ.get("CODING_BRIDGE_URL", DEFAULT_BRIDGE_URL),
+            node_name=os.environ.get("CODING_BRIDGE_NODE_NAME", ""),
+            config_dir=Path(os.environ.get("CODING_BRIDGE_CONFIG_DIR", DEFAULT_CONFIG_DIR)),
+            heartbeat_interval=_f("CODING_BRIDGE_HEARTBEAT_INTERVAL", 15.0),
+            permission_timeout=_f("CODING_BRIDGE_PERMISSION_TIMEOUT", 300.0),
+            default_model=os.environ.get("CODING_BRIDGE_MODEL") or None,
+            claim_url_template=os.environ.get("CODING_BRIDGE_CLAIM_URL", DEFAULT_CLAIM_URL),
+        )

coding_bridge_agent/connection.py

@@ -0,0 +1,227 @@
+"""WebSocket client toward the coding-bridge relay.
+
+Maintains a single outbound connection (``/ws/node?token=...``), heartbeats every
+``heartbeat_interval`` seconds, reconnects with backoff, and dispatches browser
+commands to local sessions. The node never accepts inbound connections.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+
+import websockets
+
+from . import protocol
+from .config import Settings
+from .protocol import Action, Event, event_payload
+from .providers import default_provider_factory
+from .providers.base import ProviderFactory
+from .session import Session
+
+logger = logging.getLogger("coding-bridge-agent.connection")
+
+
+class AuthFailed(Exception):
+    """The bridge rejected the node token; the user must re-pair."""
+
+
+class BridgeConnection:
+    def __init__(
+        self,
+        settings: Settings,
+        node_token: str,
+        *,
+        provider_factory: ProviderFactory | None = None,
+    ) -> None:
+        self.settings = settings
+        self.node_token = node_token
+        self.provider_factory = provider_factory or default_provider_factory(settings)
+        self.sessions: dict[str, Session] = {}
+        self._ws: websockets.WebSocketClientProtocol | None = None
+        self._stop = asyncio.Event()
+
+    def capabilities(self) -> list[str]:
+        return ["claude"]
+
+    def stop(self) -> None:
+        self._stop.set()
+
+    async def run(self) -> None:
+        delay = self.settings.reconnect_min
+        while not self._stop.is_set():
+            try:
+                await self._connect_once()
+                delay = self.settings.reconnect_min
+            except AuthFailed:
+                logger.error("node token rejected by bridge; re-run `coding-bridge-agent pair`")
+                return
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:  # noqa: BLE001 - keep retrying on transient errors
+                logger.warning("bridge connection error: %s", exc)
+            if self._stop.is_set():
+                break
+            await asyncio.sleep(delay)
+            delay = min(delay * 2, self.settings.reconnect_max)
+
+    async def _connect_once(self) -> None:
+        url = f"{self.settings.ws_node_url}?token={self.node_token}"
+        try:
+            async with websockets.connect(
+                url, max_size=None, ping_interval=20, ping_timeout=20
+            ) as ws:
+                self._ws = ws
+                logger.info("connected to bridge as node %s", self.node_token[:12])
+                heartbeat = asyncio.create_task(self._heartbeat())
+                try:
+                    async for raw in ws:
+                        await self._on_raw(raw)
+                finally:
+                    heartbeat.cancel()
+                    self._ws = None
+        except websockets.exceptions.ConnectionClosed as exc:
+            if getattr(exc, "code", None) == 4401:
+                raise AuthFailed() from exc
+            raise
+        except Exception as exc:  # noqa: BLE001 - classify handshake auth failures
+            if _is_auth_error(exc):
+                raise AuthFailed() from exc
+            raise
+
+    async def _heartbeat(self) -> None:
+        try:
+            while True:
+                await asyncio.sleep(self.settings.heartbeat_interval)
+                await self._send_envelope(
+                    protocol.envelope(
+                        protocol.NODE_HEARTBEAT, {"capabilities": self.capabilities()}
+                    )
+                )
+        except (asyncio.CancelledError, websockets.exceptions.ConnectionClosed):
+            return
+
+    async def _send_envelope(self, env: dict) -> None:
+        ws = self._ws
+        if ws is None:
+            return
+        await ws.send(json.dumps(env))
+
+    async def send_payload(self, payload: dict) -> None:
+        """Send an inner event payload toward the owner's browsers."""
+        await self._send_envelope(
+            protocol.envelope(protocol.NODE_TO_BROWSER, payload, from_node=self.node_token)
+        )
+
+    async def _on_raw(self, raw: str | bytes) -> None:
+        try:
+            message = json.loads(raw)
+        except (json.JSONDecodeError, TypeError):
+            return
+        msg_type = message.get("type")
+        if msg_type == protocol.BROWSER_TO_NODE:
+            await self._dispatch(message.get("payload") or {})
+        elif msg_type == protocol.NODE_REGISTERED:
+            logger.info("registered with bridge")
+
+    async def _dispatch(self, payload: dict) -> None:
+        action = payload.get("action")
+        session_id = payload.get("session_id")
+        try:
+            if action == Action.SESSION_START:
+                await self._start_session(payload)
+            elif action == Action.SESSION_SEND:
+                await self._send_to_session(session_id, payload.get("prompt", ""))
+            elif action == Action.SESSION_INTERRUPT:
+                await self._interrupt_session(session_id)
+            elif action == Action.SESSION_CLOSE:
+                await self._close_session(session_id)
+            elif action == Action.PERMISSION_RESOLVE:
+                self._resolve_permission(payload)
+            elif action == Action.SESSIONS_LIST:
+                await self._send_snapshot()
+            elif action == Action.PING:
+                await self.send_payload(event_payload(Event.PONG))
+            else:
+                await self.send_payload(
+                    event_payload(
+                        Event.SESSION_ERROR, session_id, message=f"unknown action: {action}"
+                    )
+                )
+        except Exception as exc:  # noqa: BLE001 - report, never crash the node
+            logger.warning("dispatch error (%s): %s", action, exc)
+            await self.send_payload(
+                event_payload(Event.SESSION_ERROR, session_id, message=str(exc))
+            )
+
+    async def _start_session(self, payload: dict) -> None:
+        session_id = payload.get("session_id")
+        if not session_id:
+            await self.send_payload(
+                event_payload(Event.SESSION_ERROR, None, message="session_id required")
+            )
+            return
+        existing = self.sessions.get(session_id)
+        if existing is not None:
+            await existing.send(payload.get("prompt", ""))
+            return
+        session = Session(
+            session_id,
+            self.provider_factory,
+            self.send_payload,
+            self.settings,
+            cwd=payload.get("cwd") or self.settings.default_cwd,
+            model=payload.get("model") or self.settings.default_model,
+            permission_mode=payload.get("permission_mode") or "default",
+        )
+        self.sessions[session_id] = session
+        await session.start(payload.get("prompt", ""))
+
+    async def _send_to_session(self, session_id: str | None, prompt: str) -> None:
+        session = self.sessions.get(session_id) if session_id else None
+        if session is None:
+            await self.send_payload(
+                event_payload(Event.SESSION_ERROR, session_id, message="unknown session")
+            )
+            return
+        await session.send(prompt)
+
+    async def _interrupt_session(self, session_id: str | None) -> None:
+        session = self.sessions.get(session_id) if session_id else None
+        if session is not None:
+            await session.interrupt()
+
+    async def _close_session(self, session_id: str | None) -> None:
+        session = self.sessions.pop(session_id, None) if session_id else None
+        if session is not None:
+            await session.close()
+
+    def _resolve_permission(self, payload: dict) -> None:
+        request_id = payload.get("request_id")
+        decision = "allow" if payload.get("decision") == "allow" else "deny"
+        if not request_id:
+            return
+        for session in self.sessions.values():
+            if session.resolve_permission(request_id, decision):
+                break
+
+    async def _send_snapshot(self) -> None:
+        await self.send_payload(
+            event_payload(
+                Event.SESSIONS_SNAPSHOT,
+                sessions=[s.info() for s in self.sessions.values()],
+            )
+        )
+
+    async def aclose(self) -> None:
+        for session in list(self.sessions.values()):
+            await session.close()
+        self.sessions.clear()
+
+
+def _is_auth_error(exc: Exception) -> bool:
+    code = getattr(exc, "status_code", None) or getattr(exc, "status", None)
+    if code in (401, 403):
+        return True
+    response = getattr(exc, "response", None)
+    return response is not None and getattr(response, "status_code", None) in (401, 403)

coding_bridge_agent/pairing.py

@@ -0,0 +1,52 @@
+"""Device-flow pairing client.
+
+The node calls ``POST /pair/start`` to obtain a short pair code, shows it to the
+user, then polls ``POST /pair/poll`` until the user claims it from Nexior (which
+calls ``/pair/claim`` with their Ace JWT). The poll then returns the node_token.
+"""
+from __future__ import annotations
+
+import asyncio
+
+import httpx
+
+from .config import Settings
+
+
+class PairingError(Exception):
+    pass
+
+
+async def start_pairing(settings: Settings) -> tuple[str, int]:
+    async with httpx.AsyncClient(timeout=15) as client:
+        response = await client.post(
+            settings.pair_start_url, json={"node_name": settings.node_name}
+        )
+    if response.status_code != 200:
+        raise PairingError(f"pair/start failed: HTTP {response.status_code}")
+    data = response.json()
+    return data["pair_code"], int(data.get("expires_in", 600))
+
+
+async def poll_for_token(
+    settings: Settings,
+    pair_code: str,
+    *,
+    interval: float = 2.0,
+    deadline: float | None = None,
+) -> str:
+    async with httpx.AsyncClient(timeout=15) as client:
+        while True:
+            response = await client.post(settings.pair_poll_url, json={"pair_code": pair_code})
+            if response.status_code == 200:
+                data = response.json()
+                status = data.get("status")
+                if status == "ready" and data.get("node_token"):
+                    return data["node_token"]
+                if status in {"expired", "consumed"}:
+                    raise PairingError(f"pairing {status}")
+            elif response.status_code == 404:
+                raise PairingError("pairing expired")
+            if deadline is not None and asyncio.get_running_loop().time() > deadline:
+                raise PairingError("pairing timed out")
+            await asyncio.sleep(interval)

coding_bridge_agent/permissions.py

@@ -0,0 +1,47 @@
+"""Pending tool-approval registry.
+
+Each in-flight ``can_use_tool`` call parks on a future keyed by request id. The
+browser's ``permission.resolve`` (or a timeout) settles it. This is the seam
+that turns a local agent prompt into a remote approval.
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Literal
+
+Decision = Literal["allow", "deny"]
+
+
+class PermissionBroker:
+    def __init__(self) -> None:
+        self._pending: dict[str, asyncio.Future[Decision]] = {}
+
+    def pending_ids(self) -> list[str]:
+        return list(self._pending)
+
+    async def request(self, request_id: str, timeout: float | None = None) -> Decision:
+        """Block until the request is resolved; deny on timeout."""
+        loop = asyncio.get_running_loop()
+        future: asyncio.Future[Decision] = loop.create_future()
+        self._pending[request_id] = future
+        try:
+            if timeout and timeout > 0:
+                return await asyncio.wait_for(future, timeout)
+            return await future
+        except (TimeoutError, asyncio.TimeoutError):
+            return "deny"
+        finally:
+            self._pending.pop(request_id, None)
+
+    def resolve(self, request_id: str, decision: Decision) -> bool:
+        future = self._pending.get(request_id)
+        if future is None or future.done():
+            return False
+        future.set_result("allow" if decision == "allow" else "deny")
+        return True
+
+    def cancel_all(self, decision: Decision = "deny") -> None:
+        for future in list(self._pending.values()):
+            if not future.done():
+                future.set_result(decision)
+        self._pending.clear()

coding_bridge_agent/protocol.py

@@ -0,0 +1,78 @@
+"""WebSocket protocol shared with the coding-bridge relay.
+
+The outer envelope and its ``type`` constants mirror coding-bridge's
+``worker/app/protocol.py`` exactly — the bridge routes on ``type`` and forwards
+``payload`` verbatim. The inner ``Action`` / ``Event`` sub-protocol is opaque to
+the bridge and is carried inside ``payload`` between browser and node.
+"""
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any
+
+PROTOCOL_VERSION = 1
+
+# --- Outer envelope types (must match coding-bridge) -----------------------
+BROWSER_TO_NODE = "browser.to_node"
+BROWSER_LIST_NODES = "browser.list_nodes"
+NODE_TO_BROWSER = "node.to_browser"
+NODES_SNAPSHOT = "nodes.snapshot"
+NODE_STATUS = "node.status"
+ERROR = "error"
+NODE_REGISTERED = "node.registered"
+NODE_HEARTBEAT = "node.heartbeat"
+NODE_HEARTBEAT_ACK = "node.heartbeat_ack"
+
+
+def envelope(
+    message_type: str, payload: dict[str, Any] | None = None, **extra: Any
+) -> dict[str, Any]:
+    """Build a protocol envelope with an id and millisecond timestamp."""
+    message: dict[str, Any] = {
+        "v": PROTOCOL_VERSION,
+        "id": uuid.uuid4().hex,
+        "ts": int(time.time() * 1000),
+        "type": message_type,
+        "payload": payload or {},
+    }
+    message.update(extra)
+    return message
+
+
+class Action:
+    """Browser → node commands (inside ``payload``)."""
+
+    SESSION_START = "session.start"
+    SESSION_SEND = "session.send"
+    SESSION_INTERRUPT = "session.interrupt"
+    SESSION_CLOSE = "session.close"
+    PERMISSION_RESOLVE = "permission.resolve"
+    SESSIONS_LIST = "sessions.list"
+    PING = "ping"
+
+
+class Event:
+    """Node → browser events (inside ``payload``)."""
+
+    SESSION_STARTED = "session.started"
+    SESSION_TEXT = "session.text"
+    SESSION_THINKING = "session.thinking"
+    SESSION_TOOL_USE = "session.tool_use"
+    SESSION_TOOL_RESULT = "session.tool_result"
+    PERMISSION_REQUEST = "permission.request"
+    PERMISSION_RESOLVED = "permission.resolved"
+    SESSION_RESULT = "session.result"
+    SESSION_ERROR = "session.error"
+    SESSION_CLOSED = "session.closed"
+    SESSIONS_SNAPSHOT = "sessions.snapshot"
+    PONG = "pong"
+
+
+def event_payload(event: str, session_id: str | None = None, **fields: Any) -> dict[str, Any]:
+    """Build an inner event payload for node → browser traffic."""
+    payload: dict[str, Any] = {"event": event}
+    if session_id is not None:
+        payload["session_id"] = session_id
+    payload.update(fields)
+    return payload