diff --git a/docs/UPGRADE_SPLIT.md b/docs/UPGRADE_SPLIT.md new file mode 100644 index 0000000..0222890 --- /dev/null +++ b/docs/UPGRADE_SPLIT.md @@ -0,0 +1,61 @@ +# 升级方案:拆分为 agenthub-gateway / acpclient 两个包 + +## 目标 + +把现有单体 `agenthub` 升级为两个独立发布的 Python 包: + +1. **acpclient**(新独立包,零 gateway 依赖) + - 迁入:`framing.py`(ndjson / lsp-frame 分帧)+ `acp_client.py`(ACPClient、 + ACPError、ACPProcessDead、handler 协议) + - 新增(M-w1 需要的远程传输):`RemoteACPClient`——与 ACPClient 同一接口 + (request/notify/register_*/initialize/session_*),transport 不是子进程 + stdin/stdout,而是 HTTP POST(指令)+ WS(事件回流),帧仍是 ACP JSON-RPC 原样。 + - 传输层抽象:`start()/close()/is_alive()/_send()/读循环` 收敛为 Transport 协议, + StdioTransport(现有逻辑原样)与 RemoteTransport(新)两个实现。上层 + (session.py 的 pending/permission/relay 逻辑)完全不感知差别。 + - 发布名:`acpclient`(PyPI 空闲已确认过 agenthub 被占但 acpclient 待查), + 单独 repo `vxquant/acpclient`,CI 同 agenthub(Gitea 先行→GitHub)。 + +2. **agenthub-gateway**(原 agenthub 改名重发布) + - 目录 `src/agenthub/` 不动(import 名保留 `agenthub`,避免大改 140 个测试与 + 三台部署脚本),只改发行元数据: + - `name = "agenthub-gateway"`,`[project.scripts] agenthub-gateway = "agenthub.__main__:main"` + - 依赖加 `acpclient`(本地 path/内网 PyPI),删除内部 framing/acp_client 模块, + `from acpclient import ...` 兼容 shim:`agenthub/acp_client.py` 留 3 行 re-export, + 老测试/老 import 不破坏。 + - gateway 侧后续新增(本升级不实现,仅留口):`worker:` agent 类型 + (cmd 字段换 url 字段)、deepagents orchestrator 段。 + +## 为什么保留 import 名 `agenthub` + +- 140 tests + 三台部署(zd git pull、api rsync、proxy git)+ supervisor unit 文件 + 都引用 `agenthub` 包与 `agenthub` 命令;改名 import 是纯机械风险零收益。 +- 发行名与 import 名不一致是 Python 常态(`pip install agent-client-protocol` + → `import acp`)。 + +## 实施清单(一次升级,向后兼容) + +| # | 事项 | 验证 | +|---|---|---| +| 1 | 新 repo `vxquant/acpclient`:src/acpclient/{framing,client,transports}.py(代码从 agenthub 平移) | uv run pytest(迁过去的老测试 + RemoteTransport 单测 mock HTTP/WS) | +| 2 | acpclient pyproject:独立版本 0.1.0,零依赖(stdlib only,WS 用 websockets optional extra) | uv build + 安装冒烟 | +| 3 | agenthub pyproject:rename `agenthub-gateway`,deps + acpclient,scripts 改名,旧脚本 `agenthub` 保留别名 | 全量 140 tests 过(import 不变) | +| 4 | agenthub/acp_client.py 与 agenthub/framing.py 变 re-export shim | 老测试不动全绿 | +| 5 | Gitea 建 vxquant/acpclient、推送;agenthub-gateway 版本 bump 0.2.0 | push 成功 | +| 6 | 三台部署:zd/proxy git pull(requirements 解析 acpclient 需内网可装——Gitea 直装 `agenthub-gateway @ gitea+https` 或 vendor);api rsync | 目标机 pytest + 重启 + status | +| 7 | CHANGELOG + DESIGN_GATEWAY_WORKER.md 更新实施状态 | — | + +## RemoteACPClient 接口草案 + +```python +class RemoteACPClient: + """ACPClient 兼容接口,帧走 HTTP/WS 到 worker-agentd。""" + def __init__(self, base_url: str, worker_token: str | None = None): ... + # 与 ACPClient 相同:request/notify/register_notification_handler/ + # register_request_handler/initialize/session_new/session_prompt/session_cancel + # start() = 打开 WS 事件流 + POST initialize;close() = POST /close + # is_alive() = WS 连接健康 + 心跳未超时 +``` + +worker-agentd(后续 M-w1 实现,不在本升级)作为 acpclient 的姊妹服务, +复用 acpclient 的 framing/handler 协议。 diff --git a/pyproject.toml b/pyproject.toml index dfe6e7a..0d9e1ea 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,7 +1,7 @@ [project] -name = "agenthub" -version = "0.1.0" -description = "IM/NATS to local ACP (Agent Client Protocol) bridge - drive Claude Code, Codex, Gemini CLI, OpenCode from messaging front-ends" +name = "agenthub-gateway" +version = "0.2.0" +description = "IM/NATS to ACP (Agent Client Protocol) gateway - drive Claude Code, Codex, Gemini CLI, OpenCode from messaging front-ends; orchestrates remote workers via acpclient" readme = "README.md" license = { text = "MIT" } authors = [{ name = "OpenBot", email = "openbot@vxquant.com" }] @@ -20,6 +20,7 @@ classifiers = [ dependencies = [ "cryptography>=42", "websockets>=12", + "acpclient>=0.1.0", ] [project.optional-dependencies] @@ -32,6 +33,7 @@ Documentation = "https://gitea.vxquant.com/vxquant/agenthub/src/branch/main/docs [project.scripts] agenthub = "agenthub.__main__:main" +agenthub-gateway = "agenthub.__main__:main" [build-system] requires = ["hatchling"] diff --git a/src/agenthub/acp_client.py b/src/agenthub/acp_client.py index d294f08..cf1e261 100644 --- a/src/agenthub/acp_client.py +++ b/src/agenthub/acp_client.py @@ -1,355 +1,5 @@ -"""ACP client: JSON-RPC 2.0 over stdio to an agent subprocess. +"""Backward-compat shim: ACP client moved to the acpclient package.""" -M0 scope: -- launch agent subprocess, talk ACP frames over stdin/stdout -- initialize / session/new / session/prompt -- dispatch server->client notifications (session/update) and requests - (fs/*, terminal/*, session/request_permission) to registered handlers -- thread-safe request/response correlation by id -""" +from acpclient.client import ACPClient, ACPError, ACPProcessDead # noqa: F401 -from __future__ import annotations - -import json -import shlex -import subprocess -import threading -from dataclasses import dataclass, field -from typing import Any, Callable - -from .framing import FrameError, decode_frames, decode_ndjson_lines, encode_frame, encode_ndjson - -# --------------------------------------------------------------------------- -# JSON-RPC error codes -# --------------------------------------------------------------------------- -PARSE_ERROR = -32700 -INVALID_REQUEST = -32600 -METHOD_NOT_FOUND = -32601 -INVALID_PARAMS = -32602 -INTERNAL_ERROR = -32603 - - -class ACPError(Exception): - """An error returned by the agent for a client request.""" - - def __init__(self, code: int, message: str, data: Any = None): - super().__init__(f"ACP error {code}: {message}") - self.code = code - self.message = message - self.data = data - - -class ACPProcessDead(ACPError): - def __init__(self, detail: str = ""): - super().__init__(INTERNAL_ERROR, f"agent process is not running: {detail}") - - -# --------------------------------------------------------------------------- -# handler signatures -# --------------------------------------------------------------------------- -NotificationHandler = Callable[[str, dict[str, Any]], None] -RequestHandler = Callable[[str, dict[str, Any]], Any] # returns result, raises ACPError - - -@dataclass -class ACPClient: - """A single ACP connection to one agent subprocess.""" - - cmd: list[str] - cwd: str | None = None - env: dict[str, str] | None = None - transport: str = "ndjson" # "ndjson" (current ACP SDK agents) | "lsp-frame" - - _proc: subprocess.Popen | None = field(default=None, init=False, repr=False) - _lock: threading.Lock = field(default_factory=threading.Lock, init=False, repr=False) - _write_lock: threading.Lock = field(default_factory=threading.Lock, init=False, repr=False) - _next_id: int = field(default=0, init=False, repr=False) - _pending: dict[int, tuple[threading.Event, list]] = field( - default_factory=dict, init=False, repr=False - ) - _notif_handlers: list[NotificationHandler] = field(default_factory=list, init=False, repr=False) - _req_handlers: list[RequestHandler] = field(default_factory=list, init=False, repr=False) - _buf: bytearray = field(default_factory=bytearray, init=False, repr=False) - _closed: bool = field(default=False, init=False, repr=False) - _stderr_lines: list[str] = field(default_factory=list, init=False, repr=False) - _last_error: str = field(default="", init=False) - - # -- lifecycle --------------------------------------------------------- - def start(self) -> None: - flat: list[str] = [] - for c in self.cmd: - flat.extend(shlex.split(c) if isinstance(c, str) else list(c)) - self._proc = subprocess.Popen( - flat, - cwd=self.cwd, - env=self.env, - stdin=subprocess.PIPE, - stdout=subprocess.PIPE, - stderr=subprocess.PIPE, - bufsize=0, - ) - threading.Thread(target=self._read_loop, name="acp-reader", daemon=True).start() - threading.Thread(target=self._stderr_loop, name="acp-stderr", daemon=True).start() - - def close(self, timeout: float = 5.0) -> None: - self._closed = True - proc = self._proc - if proc is None: - return - try: - if proc.stdin: - proc.stdin.close() - except OSError: - pass - try: - proc.wait(timeout=timeout) - except subprocess.TimeoutExpired: - proc.kill() - proc.wait(timeout=timeout) - - def is_alive(self) -> bool: - return self._proc is not None and self._proc.poll() is None - - @property - def stderr_tail(self) -> list[str]: - return list(self._stderr_lines[-50:]) - - # -- low level io ------------------------------------------------------ - def _send(self, obj: dict[str, Any]) -> None: - if not self.is_alive(): - raise ACPProcessDead(self._last_error or "process exited") - assert self._proc and self._proc.stdin - data = encode_ndjson(obj) if self.transport == "ndjson" else encode_frame(obj) - with self._write_lock: - try: - self._proc.stdin.write(data) - self._proc.stdin.flush() - except (BrokenPipeError, OSError) as e: - raise ACPProcessDead(str(e)) from e - - def _stderr_loop(self) -> None: - assert self._proc and self._proc.stderr - for raw in iter(self._proc.stderr.readline, b""): - line = raw.decode("utf-8", "replace").rstrip() - if line: - self._stderr_lines.append(line) - - def _read_loop(self) -> None: - assert self._proc and self._proc.stdout - try: - while not self._closed: - chunk = self._proc.stdout.read(65536) - if not chunk: - break - self._buf.extend(chunk) - if self.transport == "ndjson": - self._drain_ndjson() - else: - self._drain() - except (OSError, ValueError): - pass - finally: - detail = self._last_error - if not detail and self._proc: - detail = f"exit={self._proc.poll()}" - self._fail_all(f"reader stopped ({detail})") - - def _drain(self) -> None: - """Parse complete frames out of the buffer, keeping partial tails. - - decode_frames raises FrameError for both 'need more bytes' and - 'corrupt stream'; we distinguish by scanning incrementally: - try to parse with a shrinking window until only an incomplete - tail remains. - """ - while True: - if not self._buf: - return - try: - msgs = list(decode_frames(self._buf)) - except FrameError as e: - msg = str(e) - if "incomplete frame" in msg or "no header terminator" in msg: - return # partial tail: wait for more bytes - # corrupt stream: record and drop - self._last_error = f"framing error: {e}" - self._buf.clear() - return - if not msgs: - return - # decode_frames consumed the whole buffer by definition - # (it only yields complete frames and the buffer holds only - # whole frames here, else it would have raised 'incomplete') - self._buf.clear() - for m in msgs: - self._dispatch(m) - return - - def _drain_ndjson(self) -> None: - try: - msgs, consumed = decode_ndjson_lines(self._buf) - except (UnicodeDecodeError, json.JSONDecodeError) as e: - self._last_error = f"ndjson parse error: {e}" - self._buf.clear() - return - if consumed: - del self._buf[:consumed] - for m in msgs: - self._dispatch(m) - - def _fail_all(self, detail: str) -> None: - self._last_error = detail - with self._lock: - pending = list(self._pending.items()) - self._pending.clear() - for _rid, (ev, slot) in pending: - slot.append(ACPProcessDead(detail)) - ev.set() - - # -- dispatch ---------------------------------------------------------- - def _dispatch(self, msg: dict[str, Any]) -> None: - if not isinstance(msg, dict): - return - has_id = "id" in msg - method = msg.get("method") - if method is not None and not has_id: - for h in self._notif_handlers: - try: - h(method, msg.get("params") or {}) - except Exception: # noqa: BLE001 - handler errors must not kill the reader - pass - return - if method is not None and has_id: - self._handle_server_request(msg) - return - if has_id: - self._resolve_response(msg) - - def _handle_server_request(self, msg: dict[str, Any]) -> None: - # Handlers may BLOCK (e.g. session/request_permission waits minutes for - # the user's IM reply). Run them on a worker thread: blocking here would - # stall the reader loop, and every pending request would time out. - threading.Thread( - target=self._run_server_request, args=(msg,), daemon=True, - name=f"acp-srvreq-{msg.get('method')}-{msg.get('id')}", - ).start() - - def _run_server_request(self, msg: dict[str, Any]) -> None: - rid = msg["id"] - method = msg["method"] - params = msg.get("params") or {} - result: Any = None - error: dict[str, Any] | None = None - handled = False - for h in self._req_handlers: - try: - result = h(method, params) - handled = True - break - except ACPError as e: - error = {"code": e.code, "message": e.message, "data": e.data} - handled = True - break - except NotImplementedError: - continue - except Exception as e: # noqa: BLE001 - error = {"code": INTERNAL_ERROR, "message": str(e)} - handled = True - break - if not handled: - error = {"code": METHOD_NOT_FOUND, "message": f"unsupported: {method}"} - - reply: dict[str, Any] = {"jsonrpc": "2.0", "id": rid} - if error: - reply["error"] = error - else: - reply["result"] = result - try: - self._send(reply) - except ACPProcessDead: - pass - - def _resolve_response(self, msg: dict[str, Any]) -> None: - rid = msg["id"] - with self._lock: - slot = self._pending.pop(rid, None) - if slot is None: - return - ev, out = slot - if "error" in msg: - err = msg["error"] or {} - out.append( - ACPError(err.get("code", INTERNAL_ERROR), err.get("message", "unknown"), err.get("data")) - ) - else: - out.append(msg.get("result")) - ev.set() - - # -- public API -------------------------------------------------------- - def register_notification_handler(self, h: NotificationHandler) -> None: - self._notif_handlers.append(h) - - def register_request_handler(self, h: RequestHandler) -> None: - self._req_handlers.append(h) - - def request( - self, method: str, params: dict[str, Any] | None = None, timeout: float | None = 60.0 - ) -> Any: - if not self.is_alive(): - raise ACPProcessDead(self._last_error or "not started") - with self._lock: - self._next_id += 1 - rid = self._next_id - ev = threading.Event() - slot: list = [] - self._pending[rid] = (ev, slot) - try: - self._send({"jsonrpc": "2.0", "id": rid, "method": method, "params": params or {}}) - except ACPProcessDead: - with self._lock: - self._pending.pop(rid, None) - raise - if not ev.wait(timeout): - with self._lock: - self._pending.pop(rid, None) - raise ACPError(INTERNAL_ERROR, f"timeout waiting for {method} ({timeout}s)") - out = slot[0] - if isinstance(out, Exception): - raise out - return out - - def notify(self, method: str, params: dict[str, Any] | None = None) -> None: - self._send({"jsonrpc": "2.0", "method": method, "params": params or {}}) - - # -- ACP convenience --------------------------------------------------- - def initialize( - self, client_capabilities: dict[str, Any] | None = None, protocol_version: int = 1 - ) -> dict[str, Any]: - return self.request( - "initialize", - { - "protocolVersion": protocol_version, - "clientCapabilities": client_capabilities - or { - "fs": {"readTextFile": True, "writeTextFile": True}, - "terminal": True, - }, - }, - ) - - def session_new(self, cwd: str, mcp_servers: list[dict[str, Any]] | None = None) -> str: - res = self.request("session/new", {"cwd": cwd, "mcpServers": mcp_servers or []}) - sid = (res or {}).get("sessionId") - if not sid: - raise ACPError(INTERNAL_ERROR, f"session/new returned no sessionId: {res!r}") - return sid - - def session_prompt( - self, session_id: str, blocks: list[dict[str, Any]], timeout: float | None = None - ) -> dict[str, Any]: - return self.request( - "session/prompt", {"sessionId": session_id, "prompt": blocks}, timeout=timeout - ) - - def session_cancel(self, session_id: str) -> None: - self.notify("session/cancel", {"sessionId": session_id}) +__all__ = ["ACPClient", "ACPError", "ACPProcessDead"] diff --git a/src/agenthub/framing.py b/src/agenthub/framing.py index c557a37..2733e81 100644 --- a/src/agenthub/framing.py +++ b/src/agenthub/framing.py @@ -1,100 +1,17 @@ -"""ACP JSON-RPC over stdio: Content-Length framing (LSP style). +"""Backward-compat shim: framing codecs moved to the acpclient package.""" -Frame format used by ACP (same as LSP): - Content-Length: \r\n - \r\n - -""" +from acpclient.framing import ( # noqa: F401 + FrameError, + decode_frames, + decode_ndjson_lines, + encode_frame, + encode_ndjson, +) -from __future__ import annotations - -import json -from typing import Any, Iterator - -_HEADER_SEP = b"\r\n\r\n" -_HEADER_END = b"\r\n" - - -class FrameError(Exception): - """Raised when the byte stream cannot be parsed as a valid frame.""" - - -def encode_frame(payload: dict[str, Any]) -> bytes: - """Serialize a JSON-RPC message to one ACP frame.""" - body = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8") - header = b"Content-Length: " + str(len(body)).encode() + _HEADER_END * 2 - return header + body - - -def _read_exact(buf: memoryview, pos: int, n: int) -> tuple[memoryview, int]: - if pos + n > len(buf): - raise FrameError(f"incomplete frame: need {n} bytes at pos {pos}, have {len(buf) - pos}") - return buf[pos : pos + n], pos + n - - -def decode_frames(buf: bytes | bytearray | memoryview) -> Iterator[dict[str, Any]]: - """Parse all complete frames from a buffer. - - Raises FrameError on malformed headers or truncated frames; - returns an iterator of decoded JSON objects. - """ - view = memoryview(bytes(buf)) - pos = 0 - while pos < len(view): - # find header terminator - idx = bytes(view[pos:]).find(_HEADER_SEP) - if idx == -1: - raise FrameError(f"no header terminator after pos {pos}") - header_blob = bytes(view[pos : pos + idx]) - pos += idx + len(_HEADER_SEP) - - length: int | None = None - content_type: str | None = None - for line in header_blob.split(_HEADER_END): - if not line: - continue - name, _, value = line.partition(b":") - name = name.strip().lower() - if name == b"content-length": - try: - length = int(value.strip()) - except ValueError as e: - raise FrameError(f"bad Content-Length: {value!r}") from e - elif name == b"content-type": - content_type = value.strip().decode("ascii", "replace") - if length is None: - raise FrameError(f"missing Content-Length header: {header_blob!r}") - if length < 0: - raise FrameError(f"negative Content-Length: {length}") - - body_view, pos = _read_exact(view, pos, length) - try: - yield json.loads(bytes(body_view).decode("utf-8")) - except (UnicodeDecodeError, json.JSONDecodeError) as e: - raise FrameError(f"bad JSON body ({length} bytes): {e}") from e - - -# --------------------------------------------------------------------------- -# newline-delimited JSON (ndjson) transport — used by current ACP SDK agents -# (e.g. @zed-industries/claude-code-acp via @agentclientprotocol/sdk). -# LSP-style Content-Length frames are kept in encode_frame/decode_frames for -# agents that use them; transport is auto-detected by ACPClient. -# --------------------------------------------------------------------------- - -def encode_ndjson(payload: dict) -> bytes: - return json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8") + b"\n" - - -def decode_ndjson_lines(buf: bytes | bytearray): - """Yield (messages, consumed_bytes) for complete newline-terminated lines.""" - view = bytes(buf) - idx = view.rfind(b"\n") - if idx == -1: - return [], 0 - out = [] - for line in view[:idx].split(b"\n"): - line = line.strip() - if not line: - continue - out.append(json.loads(line.decode("utf-8"))) - return out, idx + 1 +__all__ = [ + "FrameError", + "decode_frames", + "decode_ndjson_lines", + "encode_frame", + "encode_ndjson", +]