#!/usr/bin/env python3 """AgentHub CLI bridge — 把一个无头 CLI Agent 挂成 hub 的 connector。 一个进程 = 一个 hub agent 身份 = 一个 CLI。思考是 CLI 的事,本进程只做三件事: 1. 把 hub 下发的一次 task.run 变成一次子进程调用(argv 由适配器给出); 2. 把 CLI 的 JSONL 事件翻译成 hub 事件(status/delta/reasoning/tool/log/completed); 3. 把 hub 的 session_key 映射成 CLI 的会话 id —— 于是 hub 上的第二个 task 会自动续上同一段对话,agent.command 也知道该把指令投递给哪个会话。 只依赖标准库 + SDK(websockets)。运行时需 Python >= 3.10。 bridge.py --hub http://127.0.0.1:8100 --token \\ --name codex --cli codex --workdir ~/code/x --mode readonly """ from __future__ import annotations import argparse import asyncio import contextlib import getpass import importlib import json import logging import os import sys import time from dataclasses import dataclass, field from pathlib import Path from typing import Any, Awaitable, Callable HERE = Path(__file__).resolve().parent sys.path.insert(0, str(HERE)) sys.path.insert(0, str(HERE.parent / "nanobot-gateway" / "channel")) from agenthub.agenthub_client import GatewayClient, GatewayConfig # noqa: E402 Emit = Callable[..., Awaitable[None]] BRIDGE_VERSION = "0.1.0" HOST_POLL_S = 10.0 # 宿主 App(WorkBuddy 桌面端)的探活间隔 log = logging.getLogger("cli-bridge") @dataclass class Run: """一次 task 的可变状态:适配器往里写,收尾时 hub 拿走。""" session_key: str session_id: str = "" resumed: bool = False parts: list[str] = field(default_factory=list) final_text: str = "" usage: dict[str, Any] = field(default_factory=dict) errors: list[str] = field(default_factory=list) stderr_tail: str = "" # 最后一行 stderr:退出码非 0 时它常是唯一的线索 extra: dict[str, Any] = field(default_factory=dict) class SessionStore: """session_key -> CLI 会话 id。落盘,桥重启后续话仍然接得上。""" def __init__(self, path: Path) -> None: self.path = path self.data: dict[str, Any] = {} if path.exists(): with contextlib.suppress(ValueError, OSError): loaded = json.loads(path.read_text("utf-8")) if isinstance(loaded, dict): self.data = loaded def get(self, key: str) -> str: return str((self.data.get(key) or {}).get("session_id") or "") def drop(self, key: str) -> None: if self.data.pop(key, None) is not None: self._save() def put(self, key: str, session_id: str) -> None: self.data[key] = {"session_id": session_id, "updated": time.time()} self._save() def all(self) -> dict[str, str]: return {key: str((row or {}).get("session_id") or "") for key, row in self.data.items()} def _save(self) -> None: with contextlib.suppress(OSError): self.path.parent.mkdir(parents=True, exist_ok=True) self.path.write_text(json.dumps(self.data, ensure_ascii=False, indent=2), "utf-8") class Bridge: """把 hub 的帧翻译成 CLI 动作。""" def __init__(self, args: argparse.Namespace) -> None: self.cli = importlib.import_module("adapters." + args.cli) self.workdir = str(Path(args.workdir).expanduser()) self.mode = args.mode self.sessions = SessionStore(Path(args.state).expanduser()) self.active: dict[str, Run] = {} # task_id -> Run self.host = getattr(self.cli, "host", None) # 可选:返回 (可用?, 原因) # -- task.run -------------------------------------------------------- async def on_task(self, task: dict[str, Any], emit: Emit) -> str: task_id = str(task.get("task_id") or "") key = str(task.get("session_key") or task_id or "default") session_id = self.sessions.get(key) run = Run(session_key=key, session_id=session_id, resumed=bool(session_id)) argv = self.cli.argv(prompt=str(task.get("prompt") or ""), run=run, workdir=self.workdir, mode=self.mode) await emit("status", message="resume " + run.session_id if run.session_id else "new session", session_id=run.session_id, argv=argv[:2]) proc = await asyncio.create_subprocess_exec( *argv, cwd=self.workdir, stdin=asyncio.subprocess.DEVNULL, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE, ) self.active[task_id] = run drain = asyncio.create_task(self._drain_stderr(proc, run, emit), name="bridge-stderr") code = -1 try: while True: line = await proc.stdout.readline() if not line: break raw = line.decode("utf-8", "replace").strip() if not raw: continue try: obj = json.loads(raw) except ValueError: await emit("log", text=raw[:2000]) # 不是 JSON 的行别吞掉,它是排障线索 continue if isinstance(obj, dict): await self.cli.feed(obj, run, emit) code = await proc.wait() finally: # hub 取消 → 这里收到 CancelledError → 子进程必须跟着死,不能留孤儿。 with contextlib.suppress(ProcessLookupError): if proc.returncode is None: proc.kill() drain.cancel() self.active.pop(task_id, None) if run.session_id and self.sessions.get(key) != run.session_id: self.sessions.put(key, run.session_id) # 失败的一轮也要记住会话,下一轮还能续 text = (run.final_text or "".join(run.parts)).strip() if code != 0 and not text: hint = "" if run.resumed: self.sessions.drop(key) # 坏掉的会话映射别一直抱着,否则这个 key 从此全废 hint = "(已丢弃会话映射,下一个 task 会新开会话)" detail = run.errors[-1] if run.errors else run.stderr_tail raise RuntimeError( f"{self.cli.name} 退出码 {code}{hint}" + (";" + detail if detail else ",且没有产出任何文本") ) await emit("completed", text=text, usage=run.usage, session_id=run.session_id, exit_code=code) return text async def _drain_stderr(self, proc: asyncio.subprocess.Process, run: Run, emit: Emit) -> None: while True: line = await proc.stderr.readline() if not line: return text = line.decode("utf-8", "replace").rstrip() if text: run.stderr_tail = text[:500] await emit("log", text=text[:2000]) # -- 宿主 App:适配器提供 host() 时才生效(workbuddy 有,codex/claude 没有)- async def wait_host(self) -> None: """宿主没起来就先别连 —— hub 上挂着一个假的在线,比干脆不在线更糟。""" if self.host is None: return warned = False while True: ok, why = await asyncio.to_thread(self.host) if ok: if warned: log.info("宿主已回来,接入 hub") return if not warned: log.warning("宿主不可用(%s):暂不接入,每 %.0fs 探一次", why, HOST_POLL_S) warned = True await asyncio.sleep(HOST_POLL_S) async def watch_host(self, gone: asyncio.Event) -> None: """宿主退出 → 桥接进程跟着退出 → hub 那边转 offline。 在跑的 task 不打断:CLI 子进程不依赖桌面端,让它把这一轮跑完再说。 """ if self.host is None: await asyncio.Event().wait() # 没有宿主可跟,一直睡着 while True: await asyncio.sleep(HOST_POLL_S) try: ok, why = await asyncio.to_thread(self.host) except Exception as exc: # noqa: BLE001 - 探测本身出错不该把在线的 agent 拽下线 log.warning("宿主探测失败(忽略,继续在线):%r", exc) continue if ok: continue while self.active: await asyncio.sleep(1.0) log.warning("宿主不可用(%s),桥接进程退出", why) gone.set() return # -- agent.describe(hub 显示的模型/能力只来自这里)------------------ async def describe(self) -> dict[str, Any]: info: dict[str, Any] = { "bridge": "cli-bridge " + BRIDGE_VERSION, # 这台 agent 物理上在哪台机器:hub 和 agent 分开部署时, # scripts/attach.sh 靠它决定是本机进会话还是 ssh 过去进。 "host": os.uname().nodename, "user": getpass.getuser(), "cli": self.cli.name, "cli_version": await self.cli.version(), "workdir": self.workdir, "mode": self.mode, "sessions": len(self.sessions.all()), } status = getattr(self.cli, "status", None) if status is not None: info.update(status()) # 各适配器把 CLI 自省里的键加了自己的前缀(wb_model / claude_model), # 而 hub 的 model 字段只从 capabilities.model 取 —— 这里统一一下, # 否则列表里 model 永远是“—”。 for key, value in info.items(): if key.endswith("_model") and value: info.setdefault("model", value) break return info # -- agent.command --------------------------------------------------- async def command(self, name: str, args: dict[str, Any]) -> dict[str, Any]: if name == "sessions": return {"sessions": self.sessions.all()} if name == "message": text = str(args.get("text") or args.get("message") or "").strip() if not text: raise ValueError("message 需要 args.text") key = str(args.get("session_key") or "default") session_id = self.sessions.get(key) if not session_id: raise ValueError(f"还没有名为 {key} 的会话;先发一个 session_key={key} 的 task") ok, detail = await self.cli.deliver(session_id, text) return {"delivered": ok, "session_key": key, "session_id": session_id, "detail": detail} raise ValueError(f"未知 command '{name}',可用:message, sessions") async def _run(client: GatewayClient, bridge: Bridge) -> None: """连着 hub 跑,同时盯着宿主:宿主一关就干净下线,宿主一开又自己接回去。 桥接进程不跟着桌面端一起退出 —— 否则用户每次重开 WorkBuddy 都得手动再拉一次进程。 """ while True: await bridge.wait_host() client.stop.clear() # 上一轮 request_stop() 置的位,不清第二轮根本起不来 gone = asyncio.Event() connector = asyncio.create_task(client.run(), name="connector") watcher = asyncio.create_task(bridge.watch_host(gone), name="host-watch") await asyncio.wait({connector, watcher}, return_when=asyncio.FIRST_COMPLETED) if gone.is_set(): await client.request_stop() # 跟 hub 道个别(agent.deregister),别等心跳超时才发现 # request_stop() 只置位不拆连接:_session() 还堵在 reader 里,心跳会继续把状态刷回 # online。所以给它 3s 好走,不走就直接掐 —— socket 真关了,hub 才会落 offline。 with contextlib.suppress(asyncio.TimeoutError): await asyncio.wait_for(connector, 3.0) connector.cancel() with contextlib.suppress(asyncio.CancelledError): await connector log.info("已下线,等宿主回来(WorkBuddy 重新打开后自动接入)") else: watcher.cancel() await connector # hub 侧出错照旧抛给 main with contextlib.suppress(asyncio.CancelledError): await watcher def main() -> int: clis = tuple(sorted(p.stem for p in (HERE / "adapters").glob("*.py") if not p.name.startswith("_"))) ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) ap.add_argument("--hub", default=os.environ.get("AGENTHUB_URL", "http://127.0.0.1:8100")) ap.add_argument("--token", default=os.environ.get("AGENTHUB_TOKEN", ""), help="agent_token(agenthub agent add --show-token 印出来的那一个)") ap.add_argument("--name", default=os.environ.get("AGENTHUB_AGENT", "codex"), help="hub 上的 agent 名字") ap.add_argument("--cli", default=os.environ.get("AGENTHUB_CLI", "codex"), choices=clis) ap.add_argument("--workdir", default=os.environ.get("AGENTHUB_WORKDIR", os.getcwd())) ap.add_argument("--mode", default=os.environ.get("AGENTHUB_MODE", "readonly"), choices=("readonly", "write"), help="readonly=只读沙箱/plan 档;write=允许改文件。默认 readonly") ap.add_argument("--state", default=os.environ.get("AGENTHUB_STATE", str(Path.home() / ".agenthub" / "cli-bridge-{name}.json"))) ap.add_argument("--max-concurrency", type=int, default=2) ap.add_argument("--verbose", action="store_true") args = ap.parse_args() logging.basicConfig(level=logging.DEBUG if args.verbose else logging.INFO, format="%(asctime)s %(levelname)-7s %(name)s: %(message)s") if not args.token: ap.error("需要 --token:这台 Agent 的凭证(控制台「接入」页签发的 ag_…)") args.state = Path(args.state.format(name=args.name)) if not Path(args.workdir).is_dir(): ap.error(f"--workdir 不存在:{args.workdir}") bridge = Bridge(args) config = GatewayConfig( hub_url=args.hub, name=args.name, agent_token=args.token, display_name=args.name, driver="connector", connection_mode="connector", deployment_ref=os.uname().nodename, labels={"cli": args.cli, "mode": args.mode}, max_concurrency=args.max_concurrency, client_version=BRIDGE_VERSION, emoji="🔌", ) client = GatewayClient(config, bridge.on_task, describe=bridge.describe, command=bridge.command) log.info("cli-bridge 启动:hub=%s agent=%s cli=%s workdir=%s mode=%s", args.hub, args.name, args.cli, args.workdir, args.mode) try: asyncio.run(_run(client, bridge)) except KeyboardInterrupt: log.info("bye") return 0 if __name__ == "__main__": sys.exit(main())