agent-cli-lib 0.1.0__py3-none-any.whl

agent_cli_lib/core/acp/client.py

@@ -0,0 +1,248 @@
+"""ACP stdio 连接（自管泵，v8 设计 §4.2.1 线程职责表）。
+
+连接层定案：SDK 连接层（asyncio-only、无进程组、env 裁剪、stderr 无 drain——四项实证
+冲突）不采用；本模块自管子进程与 stdio 泵，编解码用 SDK 的 pydantic 模型（driver 层）。
+
+线程模型（强制规格）：
+- reader 线程（唯一 stdout 消费者）：逐行读 → JSON 解析 → 按 id 分发响应 / 通知入队 /
+  server 请求入队；EOF/异常时向所有 pending future 广播失败并置 closed
+- sender 线程（唯一 stdin 写入者）：call/notify/权限应答/cancel 全走它的队列——
+  调用方线程绝不直接写 stdin（子进程卡死时写阻塞不会传染）
+- stderr drain 线程：持续读 stderr 到缓冲（无 drain 则 agent 日志写满管道即整链挂死；
+  缓冲同时是"进程级失败"报错的 stderr 来源）
+- 编码：binary 读写 + 手工 \\n 切帧 + utf-8 解码（对齐仓库 CLI 子进程编码惯例，
+  防 Windows locale 解码坑）
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import queue
+import subprocess
+import threading
+from collections.abc import Sequence
+from concurrent.futures import Future
+from concurrent.futures import TimeoutError as FutureTimeoutError
+
+from agent_cli_lib.core.proctree import kill_tree, terminate_tree
+from agent_cli_lib.errors import BackendRunError
+
+
+class AcpJsonRpcError(Exception):
+    """JSON-RPC 层错误（携带 code/message，由 driver 翻译为库异常家族）。"""
+
+    def __init__(self, code: int, message: str) -> None:
+        self.code = code
+        self.message = message
+        super().__init__(f"code={code}: {message}")
+
+
+class AcpConnection:
+    """一个 ACP agent 子进程连接（per-run 短生命周期，调用方负责 close）。"""
+
+    def __init__(self, command: Sequence[str], cwd: str | None = None) -> None:
+        self._closed = threading.Event()
+        # POSIX 独立进程组：cancel/清理整树杀（树杀前提）
+        self._proc = subprocess.Popen(
+            list(command),
+            cwd=cwd,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            start_new_session=(os.name != "nt"),
+        )
+        self._pending: dict[int, Future[dict]] = {}
+        self._pending_lock = threading.Lock()
+        self._notifications: queue.Queue[dict] = queue.Queue()
+        self._server_requests: queue.Queue[dict] = queue.Queue()
+        self._outbound: queue.Queue[str | None] = queue.Queue()
+        self._stderr_lines: list[str] = []
+        self._stderr_lock = threading.Lock()
+        self._next_id = 0
+
+        self._reader = threading.Thread(target=self._read_loop, daemon=True)
+        self._sender = threading.Thread(target=self._send_loop, daemon=True)
+        self._drain = threading.Thread(target=self._drain_loop, daemon=True)
+        self._reader.start()
+        self._sender.start()
+        self._drain.start()
+
+    # ── 对外 API ───────────────────────────────────────────────────────────
+
+    @property
+    def stderr_text(self) -> str:
+        """stderr 缓冲（进程级失败报错来源）。"""
+        with self._stderr_lock:
+            return "".join(self._stderr_lines)
+
+    @property
+    def closed(self) -> bool:
+        return self._closed.is_set()
+
+    def submit(self, method: str, params: dict | None = None) -> Future[dict]:
+        """发起 JSON-RPC 请求，返回 future（driver 的泵循环边等边处理事件）。"""
+        if self._closed.is_set():
+            raise BackendRunError("acp", -1, "连接已关闭")
+        with self._pending_lock:
+            self._next_id += 1
+            rid = self._next_id
+            fut: Future[dict] = Future()
+            self._pending[rid] = fut
+        self._outbound.put(
+            json.dumps(
+                {"jsonrpc": "2.0", "id": rid, "method": method, "params": params or {}},
+                ensure_ascii=False,
+            )
+        )
+        return fut
+
+    def request(self, method: str, params: dict | None = None, timeout: float = 30.0) -> dict:
+        """同步请求（initialize/new/resume 等阶段调用；超时抛内建 TimeoutError）。"""
+        fut = self.submit(method, params)
+        try:
+            return fut.result(timeout=timeout)
+        except FutureTimeoutError as e:
+            # py3.10 上 concurrent.futures.TimeoutError 与内建不同类，归一化
+            raise TimeoutError from e
+
+    def notify(self, method: str, params: dict | None = None) -> None:
+        """发通知（session/cancel 等），不期望响应。"""
+        self._outbound.put(
+            json.dumps(
+                {"jsonrpc": "2.0", "method": method, "params": params or {}}, ensure_ascii=False
+            )
+        )
+
+    def respond(self, request_id: int, result: dict) -> None:
+        """应答 server → client 请求（权限应答）。"""
+        self._outbound.put(
+            json.dumps({"jsonrpc": "2.0", "id": request_id, "result": result}, ensure_ascii=False)
+        )
+
+    def pop_notification(self, timeout: float = 0.0) -> dict | None:
+        """取一条通知 params（session/update）；无则 None。"""
+        try:
+            return self._notifications.get(timeout=timeout)
+        except queue.Empty:
+            return None
+
+    def pop_server_request(self, timeout: float = 0.0) -> dict | None:
+        """取一条 server → client 请求（session/request_permission）；无则 None。"""
+        try:
+            return self._server_requests.get(timeout=timeout)
+        except queue.Empty:
+            return None
+
+    def close(self, timeout: float = 5.0) -> None:
+        """清理矩阵：关 stdin → wait(5) → 超时树杀。幂等（EOF/写失败路径也要停 sender 收尸）。"""
+        first = not self._closed.is_set()
+        self._closed.set()
+        self._outbound.put(None)  # 停 sender（不论谁先置 closed）
+        if first:
+            try:
+                if self._proc.stdin is not None:
+                    self._proc.stdin.close()
+            except OSError:
+                pass
+        if self._proc.poll() is None:  # agent 仍存活：等待/树杀（写失败路径进程可能未死）
+            try:
+                self._proc.wait(timeout=timeout)
+            except subprocess.TimeoutExpired:
+                terminate_tree(self._proc)
+                try:
+                    self._proc.wait(timeout=2)
+                except subprocess.TimeoutExpired:
+                    kill_tree(self._proc)
+                    self._proc.wait()
+        else:
+            self._proc.wait()  # 已退出：回收僵尸
+        self._fail_pending("连接已关闭")
+
+    def kill(self) -> None:
+        """兜底强杀（cancel 超时路径）。幂等。"""
+        if self._proc.poll() is not None:
+            return
+        terminate_tree(self._proc)
+        try:
+            self._proc.wait(timeout=2)
+        except subprocess.TimeoutExpired:
+            kill_tree(self._proc)
+            self._proc.wait()
+        self._closed.set()
+
+    # ── 内部线程 ───────────────────────────────────────────────────────────
+
+    def _read_loop(self) -> None:
+        assert self._proc.stdout is not None
+        try:
+            for raw in self._proc.stdout:
+                line = raw.decode("utf-8", errors="replace").strip()
+                if not line:
+                    continue
+                try:
+                    msg = json.loads(line)
+                except json.JSONDecodeError:
+                    continue  # 半行/非 JSON 容错
+                if not isinstance(msg, dict):
+                    continue
+                self._dispatch(msg)
+        except OSError:
+            pass
+        finally:
+            self._closed.set()
+            self._fail_pending("agent 进程退出")
+
+    def _dispatch(self, msg: dict) -> None:
+        if "method" in msg:
+            if "id" in msg:  # server → client 请求（权限等）
+                self._server_requests.put(msg)
+            else:  # 通知（session/update 等）
+                self._notifications.put(msg.get("params") or {})
+            return
+        rid = msg.get("id")
+        fut: Future[dict] | None = None
+        if isinstance(rid, int):
+            with self._pending_lock:
+                fut = self._pending.pop(rid, None)
+        if fut is None or fut.done():
+            return
+        if "error" in msg:
+            err = msg["error"] or {}
+            fut.set_exception(
+                AcpJsonRpcError(int(err.get("code", -32000)), str(err.get("message", "")))
+            )
+        else:
+            fut.set_result(msg.get("result") or {})
+
+    def _send_loop(self) -> None:
+        assert self._proc.stdin is not None
+        while True:
+            item = self._outbound.get()
+            if item is None:
+                return
+            try:
+                self._proc.stdin.write((item + "\n").encode("utf-8"))
+                self._proc.stdin.flush()
+            except (OSError, ValueError):
+                self._closed.set()
+                self._fail_pending("stdin 写入失败（agent 进程异常）")
+                return
+
+    def _drain_loop(self) -> None:
+        assert self._proc.stderr is not None
+        try:
+            for raw in self._proc.stderr:
+                with self._stderr_lock:
+                    self._stderr_lines.append(raw.decode("utf-8", errors="replace"))
+        except OSError:
+            pass
+
+    def _fail_pending(self, reason: str) -> None:
+        with self._pending_lock:
+            futures = list(self._pending.values())
+            self._pending.clear()
+        for fut in futures:
+            if not fut.done():
+                stderr_head = self.stderr_text[:500]
+                fut.set_exception(BackendRunError("acp", -1, f"{reason}；stderr: {stderr_head}"))

agent_cli_lib/core/acp/driver.py

@@ -0,0 +1,344 @@
+"""AcpDriver：ACP 传输的会话编排（v8 设计 §4.4，本设计的核心新逻辑）。
+
+per-run 生命周期（短连接，跨进程 resume 已实测无损）：
+spawn <binary> acp → initialize → session/new | session/resume →（model 设置）
+→ session/prompt（任务线程泵循环：事件队列消费 + 权限应答 + cancel 监视）
+→ prompt 响应 → 清理矩阵退出 → RunOutput
+
+on_event 交付（v8 定字）：reader 线程把通知入队，**任务线程**在等待 prompt 响应的
+循环里边等边泵——回调永远不在 reader 线程执行，慢回调拖慢的只是事件消费，
+帧读取、权限应答、cancel 写入永不被用户回调阻塞。
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import threading
+import time
+from collections.abc import Callable
+from concurrent.futures import TimeoutError as FutureTimeoutError
+
+from acp import SessionNotification
+from acp.schema import PromptResponse
+
+from agent_cli_lib.backends.base import AcpSpec, RunOutput, RunRequest
+from agent_cli_lib.core.acp import wire
+from agent_cli_lib.core.acp.client import AcpConnection, AcpJsonRpcError
+from agent_cli_lib.errors import (
+    AcpProtocolError,
+    BackendLaunchError,
+    BackendRunError,
+    RunCancelledError,
+    SessionError,
+)
+
+# 超时矩阵（v8 设计 §4.4）：initialize/new/resume/set_config 30s；清理等待在 client.close
+_PHASE_TIMEOUT = 30.0
+# cancel 优雅层等待 prompt 返回 stopReason:"cancelled" 的兜底上限，超时进程组强杀
+_CANCEL_GRACE = 5.0
+# 泵循环的轮询间隔
+_PUMP_INTERVAL = 0.05
+
+OnEvent = Callable[[SessionNotification], None]
+
+# 初始化请求的固定参数（协议 v1；fs 能力按本库不提供声明）
+_INITIALIZE_PARAMS: dict = {
+    "protocolVersion": 1,
+    "clientCapabilities": {"fs": {"readTextFile": False, "writeTextFile": False}},
+}
+
+
+class AcpDriver:
+    """一次 run/resume 的 ACP 传输执行体（runner 按路由构造，per-run 生命周期）。"""
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        spec: AcpSpec,
+        on_event: OnEvent | None = None,
+    ) -> None:
+        self.name = name
+        self.spec = spec
+        self._on_event = on_event
+        self._conn: AcpConnection | None = None
+        self._prompt_session_id: str | None = None
+        self._cancel_sent = False
+        self._lock = threading.Lock()
+
+    # ── Driver 协议（runner 侧主动干预入口） ───────────────────────────────
+
+    def cancel(self) -> None:
+        """优雅取消：发 session/cancel（幂等，立即返回，不等待收尾）。"""
+        with self._lock:
+            if self._cancel_sent or self._conn is None or self._prompt_session_id is None:
+                return
+            self._cancel_sent = True
+            conn, sid = self._conn, self._prompt_session_id
+        # 发送失败由兜底强杀收尾（连接已死时）
+        with contextlib.suppress(Exception):
+            conn.notify("session/cancel", {"sessionId": sid})
+
+    def kill(self) -> None:
+        """兜底强杀（进程组）。幂等。"""
+        with self._lock:
+            conn = self._conn
+        if conn is not None:
+            conn.kill()
+
+    # ── 执行 ───────────────────────────────────────────────────────────────
+
+    def run(self, req: RunRequest, cancel_event: threading.Event) -> RunOutput:
+        cwd = os.path.abspath(req.workdir or os.getcwd())
+        self._check_request(req)
+        try:
+            conn = AcpConnection(self.spec.command, cwd=cwd)
+        except OSError as e:
+            raise BackendLaunchError(self.name, f"ACP agent 进程启动失败: {e}") from e
+        with self._lock:
+            self._conn = conn
+        try:
+            self._initialize(conn, cancel_event)
+            self._raise_if_cancelled(cancel_event, conn)
+            session_id = self._open_session(conn, req, cwd, cancel_event)
+            self._raise_if_cancelled(cancel_event, conn)
+            if req.model:
+                self._apply_model(conn, session_id, req.model, cancel_event)
+            return self._prompt(conn, session_id, req, cancel_event)
+        finally:
+            with self._lock:
+                self._conn = None
+                self._prompt_session_id = None
+            conn.close()
+
+    # ── 阶段实现 ───────────────────────────────────────────────────────────
+
+    def _check_request(self, req: RunRequest) -> None:
+        """调用期参数校验（与 CLI 兜底同语义的前置拒绝）。"""
+        if req.session and not req.session.strip():
+            raise SessionError("session 不能为空")
+        if req.session and not _looks_like_session_id(req.session):
+            raise SessionError(
+                f"{self.name} 恢复会话仅支持 session id（文件路径恢复见二期 session import）"
+            )
+        if req.session and not req.prompt.strip():
+            raise SessionError(f"{self.name} 恢复会话必须带 prompt（ACP 的 prompt 为必填）")
+
+    def _initialize(self, conn: AcpConnection, cancel_event: threading.Event) -> None:
+        try:
+            conn.request("initialize", _INITIALIZE_PARAMS, timeout=_PHASE_TIMEOUT)
+        except AcpJsonRpcError as e:
+            raise wire.translate_error(self.name, e.code, e.message) from e
+        except FutureTimeoutError as e:
+            self._raise_if_cancelled(cancel_event, conn)  # cancel 在飞优先报取消
+            raise BackendLaunchError(self.name, f"initialize 超时（{_PHASE_TIMEOUT}s）") from e
+        except BackendRunError as e:
+            raise BackendLaunchError(self.name, str(e)) from e
+
+    def _open_session(
+        self, conn: AcpConnection, req: RunRequest, cwd: str, cancel_event: threading.Event
+    ) -> str:
+        if req.session:
+            params = {"cwd": cwd, "mcpServers": [], "sessionId": req.session}
+            try:
+                conn.request("session/resume", params, timeout=_PHASE_TIMEOUT)
+            except AcpJsonRpcError as e:
+                raise wire.translate_error(self.name, e.code, e.message) from e
+            except FutureTimeoutError as e:
+                self._raise_if_cancelled(cancel_event, conn)
+                raise BackendRunError(
+                    self.name, 0, f"session/resume 超时（{_PHASE_TIMEOUT}s）"
+                ) from e
+            # opencode 的 resume 响应实测带 sessionId（hermes 0.19.0 才缺）；
+            # 沿用传入 id（协议语义：resume 即续用该会话）
+            return req.session
+        params = {"cwd": cwd, "mcpServers": []}
+        try:
+            result = conn.request("session/new", params, timeout=_PHASE_TIMEOUT)
+        except AcpJsonRpcError as e:
+            raise wire.translate_error(self.name, e.code, e.message) from e
+        except FutureTimeoutError as e:
+            self._raise_if_cancelled(cancel_event, conn)
+            raise BackendRunError(self.name, 0, f"session/new 超时（{_PHASE_TIMEOUT}s）") from e
+        session_id = str(result.get("sessionId") or "")
+        if not session_id:
+            raise AcpProtocolError(self.name, None, "session/new 未返回 sessionId")
+        return session_id
+
+    def _apply_model(
+        self,
+        conn: AcpConnection,
+        session_id: str,
+        model: str,
+        cancel_event: threading.Event,
+    ) -> None:
+        """model 的 ACP 映射：configOptions 找 id=="model" → set_config_option（v8 §4.4）。
+
+        无匹配 option → 显式报错，绝不静默用默认模型（错误发生在最贵的 token 上）。
+        """
+        try:
+            result = conn.request(
+                "session/set_config_option",
+                {"sessionId": session_id, "configId": "model", "value": model},
+                timeout=_PHASE_TIMEOUT,
+            )
+        except AcpJsonRpcError as e:
+            raise wire.translate_error(self.name, e.code, e.message) from e
+        except FutureTimeoutError as e:
+            self._raise_if_cancelled(cancel_event, conn)
+            raise BackendRunError(self.name, 0, "session/set_config_option 超时") from e
+        # 响应回带 config_options，确认 model 生效
+        options = _extract_config_options(result)
+        current = next(
+            (str(o.get("currentValue", "")) for o in options if o.get("id") == "model"), ""
+        )
+        if not current or model not in current:
+            raise BackendRunError(
+                self.name,
+                0,
+                f"模型设置未生效：期望 {model}，实际 {current or '（响应未回带 model 配置）'}",
+            )
+
+    def _prompt(
+        self,
+        conn: AcpConnection,
+        session_id: str,
+        req: RunRequest,
+        cancel_event: threading.Event,
+    ) -> RunOutput:
+        with self._lock:
+            self._prompt_session_id = session_id
+        params = {"sessionId": session_id, "prompt": [{"type": "text", "text": req.prompt}]}
+        fut = conn.submit("session/prompt", params)
+
+        text_parts: list[str] = []
+        saw_message = False
+        grace_deadline: float | None = None
+        pump_failure: BaseException | None = None
+        cancelled = False
+
+        while True:
+            if pump_failure is not None:
+                break
+            if cancel_event.is_set():
+                # 幂等：外部 cancel() 已发送过通知时为 no-op；兜底计时不论谁先触发都武装
+                # （否则 agent 无视 session/cancel 时 run 会永久挂起）
+                self.cancel()
+                if grace_deadline is None:
+                    grace_deadline = time.monotonic() + _CANCEL_GRACE
+            if grace_deadline is not None and time.monotonic() > grace_deadline:
+                conn.kill()
+                cancelled = True
+                break
+            # 泵通知（顺序保持；回调异常 → 任务失败上抛）
+            while (ev := conn.pop_notification()) is not None and pump_failure is None:
+                notification = _safe_parse(ev)
+                if notification is None:
+                    continue  # 未知变体/载荷不合法：跳过（宽容线格式演进），空响应守卫兜底
+                if self._on_event is not None:
+                    try:
+                        self._on_event(notification)
+                    except Exception as e:  # 回调异常视同任务失败（不静默吞错）
+                        pump_failure = e
+                        break
+                if wire.is_agent_message(notification):
+                    saw_message = True
+                    text_parts.append(wire.message_text(notification))
+            if pump_failure is not None:
+                break
+            # 泵 server 请求（权限默认应答 allow_once）
+            while (srv := conn.pop_server_request()) is not None:
+                self._answer_permission(conn, srv)
+            if fut.done():
+                break
+            if conn.closed:
+                # reader 已把 EOF 广播给 pending future，break 后从 fut 拿异常
+                break
+            time.sleep(_PUMP_INTERVAL)
+
+        if pump_failure is not None:
+            raise pump_failure
+        if cancelled:
+            raise RunCancelledError(self.name)
+
+        try:
+            result = fut.result(timeout=_PHASE_TIMEOUT)
+        except AcpJsonRpcError as e:
+            raise wire.translate_error(self.name, e.code, e.message) from e
+        except FutureTimeoutError as e:
+            raise BackendRunError(self.name, 0, "session/prompt 等待超时") from e
+
+        # 迟到事件 flush：reader 可能在响应行之后还有已入队的通知（含正文尾块），排空再返回
+        while (ev := conn.pop_notification(timeout=0.5)) is not None:
+            notification = _safe_parse(ev)
+            if notification is None:
+                continue
+            if self._on_event is not None:
+                self._on_event(notification)  # 回调异常在此阶段同样视同任务失败上抛
+            if wire.is_agent_message(notification):
+                saw_message = True
+                text_parts.append(wire.message_text(notification))
+
+        # Fix 5: 响应校验失败按协议错误翻译（不裸抛 pydantic ValidationError）
+        try:
+            response = PromptResponse.model_validate(result)
+        except Exception as e:
+            raise AcpProtocolError(self.name, None, f"session/prompt 响应不合法: {e}") from e
+        return self._finalize_response(response, text_parts, saw_message, session_id)
+
+    def _finalize_response(
+        self,
+        response: PromptResponse,
+        text_parts: list[str],
+        saw_message: bool,
+        session_id: str,
+    ) -> RunOutput:
+        stop = response.stop_reason
+        if stop == "cancelled":
+            raise RunCancelledError(self.name)
+        if stop == "refusal":
+            # hermes 实证的空成功轮：无文本无报错退出正常，不得静默当正常结果
+            raise AcpProtocolError(self.name, None, "agent 拒绝执行（stopReason=refusal）")
+        if stop == "end_turn" and not saw_message:
+            # 空响应守卫：provider 故障/配额可能不发 error 事件而以空 end_turn 收场
+            raise AcpProtocolError(self.name, None, "空响应（end_turn 且无 agent_message_chunk）")
+        return RunOutput(text="".join(text_parts), session_id=session_id)
+
+    def _answer_permission(self, conn: AcpConnection, srv: dict) -> None:
+        """权限默认应答：allow_once（deny/policy 由 agent 侧执行，客户端无需实现）。"""
+        if srv.get("method") != "session/request_permission":
+            return  # 未知 server 请求忽略（协议演进宽容），不阻塞
+        params = srv.get("params") or {}
+        options = params.get("options") or []
+        result = wire.permission_response(options)
+        rid = srv.get("id")
+        if isinstance(rid, int):
+            conn.respond(rid, result)
+
+    def _raise_if_cancelled(self, cancel_event: threading.Event, conn: AcpConnection) -> None:
+        """initialize/new/resume 阶段的 cancel 到达：直接走兜底强杀（无 prompt 可等）。"""
+        if cancel_event.is_set():
+            conn.kill()
+            raise RunCancelledError(self.name)
+
+
+def _looks_like_session_id(s: str) -> bool:
+    """session id / 文件路径粗判（镜像 core/session.py 启发式，避免 backends→core 反向依赖）。"""
+    return not (s.endswith((".json", ".jsonl", ".md", ".html")) or "/" in s or "\\" in s)
+
+
+def _safe_parse(params: dict) -> SessionNotification | None:
+    """解析通知；线格式漂移（未知变体）返回 None 跳过，不失败整个 run。"""
+    try:
+        return SessionNotification.model_validate(params)
+    except Exception:
+        return None
+
+
+def _extract_config_options(result: dict) -> list:
+    """从响应里取 configOptions（兼容 dict/模型两种形态）。"""
+    options = result.get("configOptions")
+    if isinstance(options, list):
+        return [o if isinstance(o, dict) else o.model_dump(by_alias=True) for o in options]
+    return []

agent_cli_lib/core/acp/wire.py

@@ -0,0 +1,73 @@
+"""ACP 线格式薄适配（SDK 类型之上的提取与翻译，v8 设计 §4.2）。
+
+变体判别由 SDK pydantic discriminator（session_update 字段）自动完成，本模块只做：
+- SessionNotification 的解析（wire → SDK 类型）
+- 文本块提取（AgentMessageChunk 的拼接即最终文本）
+- JSON-RPC error → 异常翻译（SessionError / AcpProtocolError）
+- 权限应答 payload 构造
+"""
+
+from __future__ import annotations
+
+from acp import SessionNotification
+from acp.schema import (
+    AgentMessageChunk,
+    AgentThoughtChunk,
+    TextContentBlock,
+)
+
+from agent_cli_lib.errors import AcpProtocolError, SessionError
+
+# JSON-RPC error code（协议级）
+_INVALID_PARAMS = -32602
+
+
+def parse_notification(params: dict) -> SessionNotification:
+    """把 session/update 通知的 params 解析为官方 SDK 类型（校验失败按协议错误处理）。"""
+    try:
+        return SessionNotification.model_validate(params)
+    except Exception as e:  # pydantic ValidationError：线格式漂移按协议错误上报
+        raise AcpProtocolError("acp", None, f"session/update 载荷不合法: {e}") from e
+
+
+def message_text(notification: SessionNotification) -> str:
+    """提取文本块的文本（thought 与 message 的 content 同型，由 is_agent_message 区分正文）。"""
+    update = notification.update
+    if isinstance(update, AgentMessageChunk | AgentThoughtChunk):
+        content = update.content
+        if isinstance(content, TextContentBlock):
+            return content.text
+    return ""
+
+
+def is_agent_message(notification: SessionNotification) -> bool:
+    return isinstance(notification.update, AgentMessageChunk)
+
+
+def translate_error(backend: str, code: int | None, message: str) -> Exception:
+    """JSON-RPC error → 异常（v8 设计 §4.4 错误翻译）。
+
+    - session not found → SessionError（-32602 且消息明示）
+    - does not belong to cwd → 可读 cwd 错误（含 transport="cli" 逃生提示）
+    - 其余 → AcpProtocolError
+    """
+    msg = str(message)
+    if "session not found" in msg.lower():
+        return SessionError(msg)
+    if code == _INVALID_PARAMS and "does not belong to cwd" in msg.lower():
+        return SessionError(
+            f"{msg}（opencode v2 的 ACP resume 绑定会话原目录；"
+            f'如需跨目录恢复可显式 transport="cli"，CLI 的 -s 为全局查找）'
+        )
+    return AcpProtocolError(backend, code, msg)
+
+
+def permission_response(options: list) -> dict:
+    """构造默认应答：挑 allow_once 选中；无匹配选项则拒绝（不猜测）。
+
+    options 为线上的原始 dict 列表（optionId/kind），避免在 client 层二次建模。
+    """
+    for opt in options or []:
+        if isinstance(opt, dict) and opt.get("kind") == "allow_once":
+            return {"outcome": {"outcome": "selected", "optionId": opt.get("optionId", "")}}
+    return {"outcome": {"outcome": "rejected"}}