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

agent_cli_lib/core/driver_base.py

@@ -0,0 +1,35 @@
+"""Driver 协议：传输驱动（ACP / CLI）的公共接口。
+
+runner 按路由选择 Driver 并把可取消执行交给它；协议保持极简——
+run 是唯一必须成员，cancel/kill 是 runner 主动干预的入口。
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Protocol
+
+from agent_cli_lib.backends.base import RunOutput, RunRequest
+
+
+class Driver(Protocol):
+    """一次可取消执行的传输驱动。"""
+
+    def run(self, req: RunRequest, cancel_event: threading.Event) -> RunOutput:
+        """执行一次 run/resume 请求（阻塞至完成或被取消）。
+
+        - 取消经 cancel_event 传入（与 CLI 执行体同机制）；
+        - 取消完成时抛 RunCancelledError；失败抛 AgentCliError 家族异常。
+        """
+        ...
+
+    def cancel(self) -> None:
+        """优雅取消（ACP：发 session/cancel；CLI：无优雅层直接树杀）。
+
+        必须立即返回（不等待收尾）；等待在驱动后台完成。
+        """
+        ...
+
+    def kill(self) -> None:
+        """兜底强杀：进程组 SIGTERM→SIGKILL。幂等，已退出时静默。"""
+        ...

agent_cli_lib/core/proctree.py

@@ -0,0 +1,40 @@
+"""进程树终止工具（自 runner.py 迁入，CLI 执行体与 ACP 驱动共用）。
+
+agent CLI 会派生子进程（opencode acp 自带私有 server），只杀父进程会留孤儿握住管道，
+取消/清理必须整组杀。
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import sys
+
+
+def terminate_tree(proc: subprocess.Popen[bytes] | subprocess.Popen[str]) -> None:
+    """SIGTERM 进程及其整棵子进程树。
+
+    sys.platform 条件用于类型检查器平台收窄（ty 同样支持），与 os.name 在运行时等价。
+    """
+    if os.name == "nt" or sys.platform == "win32":
+        subprocess.run(
+            ["taskkill", "/F", "/T", "/PID", str(proc.pid)],
+            capture_output=True,
+            check=False,
+        )
+        return
+    try:
+        os.killpg(os.getpgid(proc.pid), signal.SIGTERM)
+    except (ProcessLookupError, PermissionError):
+        proc.terminate()
+
+
+def kill_tree(proc: subprocess.Popen[bytes] | subprocess.Popen[str]) -> None:
+    """SIGTERM 无效时的兜底：SIGKILL 整组（Windows 上 taskkill /F 已是强杀）。"""
+    if os.name == "nt" or sys.platform == "win32":
+        return
+    try:
+        os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+    except (ProcessLookupError, PermissionError):
+        proc.kill()

agent_cli_lib/core/prompt.py

@@ -0,0 +1,32 @@
+"""prompt 处理：字符串 / 文件路径统一解析。
+
+resolve_prompt 接受任意字符串：
+- 若是已存在的文件路径 -> 读取文件内容返回
+- 否则 -> 原样作为 prompt 字符串返回
+
+判空、路径合法性等细节收纳在此，调用方只需传字符串。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from agent_cli_lib.errors import PromptError
+
+_MAX_PROMPT_BYTES = 10 * 1024 * 1024
+
+
+def resolve_prompt(prompt: str) -> str:
+    """若 prompt 是存在的文件路径则读取内容，否则按字符串原样返回。"""
+    if not prompt or not prompt.strip():
+        raise PromptError("prompt 不能为空")
+
+    candidate = Path(prompt)
+    if candidate.is_file():
+        if candidate.stat().st_size > _MAX_PROMPT_BYTES:
+            raise PromptError(f"prompt 文件过大: {candidate} (>10MB)")
+        try:
+            return candidate.read_text(encoding="utf-8")
+        except OSError as e:
+            raise PromptError(f"读取 prompt 文件失败: {candidate}: {e}") from e
+    return prompt

agent_cli_lib/core/runner.py

@@ -0,0 +1,305 @@
+"""统一运行入口（聚合层）。
+
+职责（只做聚合，不碰 backend 细节）：
+1. 选 backend（参数切换 opencode/opencode2/pi/hermes）与传输（transport=auto/acp/cli）
+2. 解析 prompt（字符串或文件路径）-> 委托 core.prompt
+3. 构造 RunRequest -> ACP 路径委托 core.acp.AcpDriver / CLI 路径委托 backend.build_argv
+4. 起进程、可取消 -> ACP：driver 双层 cancel；CLI：Popen + Event（run 与 resume 共用）
+5. 收集输出 -> ACP：driver 聚合事件；CLI：委托 backend.parse_output
+6. session 导出/恢复 -> 委托 core.session + backend.export_session_file（export 恒走 CLI 子进程）
+
+错误处理委托 errors 模块（ProcessResult.raise_for_status / which_or_raise）。
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import IO
+
+from acp import SessionNotification
+
+from agent_cli_lib.backends.base import AcpSpec, Backend, RunOutput, RunRequest
+from agent_cli_lib.backends.hermes.backend import HermesBackend
+from agent_cli_lib.backends.opencode.backend import Opencode2Backend, OpencodeBackend
+from agent_cli_lib.backends.pi.backend import PiBackend
+from agent_cli_lib.core.acp.driver import AcpDriver
+from agent_cli_lib.core.proctree import kill_tree, terminate_tree
+from agent_cli_lib.core.prompt import resolve_prompt
+from agent_cli_lib.core.session import SessionInfo, export_session, load_session
+from agent_cli_lib.errors import (
+    BackendLaunchError,
+    BackendNotFoundError,
+    ProcessResult,
+    RunCancelledError,
+    SessionError,
+    which_or_raise,
+)
+
+_BACKENDS: dict[str, Callable[[], Backend]] = {
+    "opencode": lambda: OpencodeBackend(),
+    "opencode2": lambda: Opencode2Backend(),
+    "pi": lambda: PiBackend(),
+    "hermes": lambda: HermesBackend(),
+}
+
+# 传输取值
+_TRANSPORTS = ("auto", "acp", "cli")
+
+
+def get_backend(name: str) -> Backend:
+    """按名称获取 backend 实例。"""
+    factory = _BACKENDS.get(name)
+    if factory is None:
+        raise BackendNotFoundError(name)
+    return factory()
+
+
+@dataclass
+class AgentResult:
+    """一次 agent 运行的结果。"""
+
+    session_id: str = ""
+    output: str = ""
+    # export_to 落盘结果：成功为绝对路径/None；失败时 export_error 给出原因（run 主结果不受影响）
+    export_path: str | None = None
+    export_error: str | None = None
+
+
+class AgentRunner:
+    """统一封装入口。所有后端通过该类以一致的方式调用。run 与 resume 均可被 cancel() 中断。"""
+
+    def __init__(
+        self,
+        backend: str = "opencode",
+        workdir: str | None = None,
+        transport: str = "auto",
+    ) -> None:
+        if transport not in _TRANSPORTS:
+            raise ValueError(f"transport 取值须为 {'/'.join(_TRANSPORTS)}，得到 {transport!r}")
+        self._backend = get_backend(backend)
+        self._workdir = workdir
+        self._transport = transport
+        self._lock = threading.Lock()
+        self._active_cancel: threading.Event | None = None
+        self._active_driver: AcpDriver | None = None
+
+    @property
+    def backend(self) -> str:
+        return self._backend.name
+
+    @property
+    def workdir(self) -> str | None:
+        return self._workdir
+
+    @property
+    def transport(self) -> str:
+        return self._transport
+
+    def run(
+        self,
+        prompt: str,
+        *,
+        model: str | None = None,
+        export_to: str | None = None,
+        on_event: Callable[[SessionNotification], None] | None = None,
+    ) -> AgentResult:
+        """执行一次任务；prompt 可为字符串或文件路径。可被 cancel() 中断。
+
+        - export_to：给出时，任务完成后把会话导出文件落到该路径（相对路径按调用方进程
+          cwd 解析，父目录自动创建）。导出失败不抛异常——对话已真实发生、结果不可重建，
+          降级为 AgentResult.export_error；成功时 export_path 为落盘绝对路径。
+        """
+        resolved = resolve_prompt(prompt)
+        req = RunRequest(prompt=resolved, workdir=self._workdir, model=model)
+        out = self._execute(req, on_event=on_event)
+        result = AgentResult(session_id=out.session_id, output=out.text)
+        if export_to is not None:
+            result.export_path, result.export_error = self._export_safely(out.session_id, export_to)
+        return result
+
+    def resume(
+        self,
+        session: str,
+        *,
+        model: str | None = None,
+        prompt: str = "",
+        on_event: Callable[[SessionNotification], None] | None = None,
+    ) -> AgentResult:
+        """用 session id 或 session 文件路径恢复会话。可被 cancel() 中断。
+
+        - session id -> 原样传给 CLI 的恢复 flag（opencode -s / pi --session / hermes --resume）
+        - 文件路径 -> 原样传给支持路径的 CLI（pi 原生支持；opencode/hermes 需传 id）
+        - prompt 可选，作为恢复后的续写输入
+        """
+        info: SessionInfo = load_session(session)
+        session_value = info.session_id or info.file_path
+        resolved_prompt = resolve_prompt(prompt) if prompt.strip() else ""
+        req = RunRequest(
+            prompt=resolved_prompt, workdir=self._workdir, model=model, session=session_value
+        )
+        # CLI 兜底路径的前置探测（ACP 路径协议错误自带语义，不需要）；
+        # 多数 backend 恒 True（CLI 自己报错），仅 opencode v2 兜底真实探测
+        if (
+            self._select_transport(on_event) == "cli"
+            and info.session_id
+            and not self._backend.session_exists(info.session_id)
+        ):
+            raise SessionError(f"会话不存在: {info.session_id}")
+        out = self._execute(req, on_event=on_event)
+        return AgentResult(session_id=out.session_id, output=out.text)
+
+    def cancel(self) -> None:
+        """终止当前正在运行的任务（并发安全：只作用于在飞的那一次）。
+
+        ACP 路径：先走协议级优雅取消（session/cancel），驱动内 5s 兜底强杀；
+        CLI 路径：直接进程组树杀（与既往行为一致）。
+        """
+        with self._lock:
+            event = self._active_cancel
+            driver = self._active_driver
+        if event is not None:
+            event.set()
+        if driver is not None:
+            driver.cancel()
+
+    def export_session(self, session_id: str, target: str) -> SessionInfo:
+        """调用 backend 的原生导出命令，把会话数据落到 target 文件（失败抛异常）。"""
+        info = export_session(session_id, target)
+        self._backend.export_session_file(session_id, self._resolve_export_target(target))
+        return info
+
+    def _resolve_export_target(self, target: str) -> str:
+        """导出目标统一处理：resolve 成绝对路径（按调用方进程 cwd）+ 建父目录。"""
+        path = Path(target).resolve()
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+        except OSError as e:
+            raise SessionError(f"创建导出目录失败: {path.parent}: {e}") from e
+        return str(path)
+
+    def _export_safely(self, session_id: str, target: str) -> tuple[str | None, str | None]:
+        """run(export_to=...) 的导出段：失败不抛，返回 (export_path, export_error)。
+
+        对话已真实发生（output/session_id 不可重建），导出作为次目标失败时信息
+        无损地留在 export_error，由调用方决策。契约是导出段的**任何**失败都不得
+        毁掉 run 结果，故不逐异常枚举（backend 内部如 Path.home() 等也可能抛
+        非 AgentCliError/OSError 的异常）。
+        """
+        try:
+            if not session_id:
+                raise SessionError("未获取到 session_id，无法导出")
+            path = self._resolve_export_target(target)
+            self._backend.export_session_file(session_id, path)
+            return path, None
+        except Exception as e:
+            return None, f"{type(e).__name__}: {e}"
+
+    def _execute(
+        self, req: RunRequest, *, on_event: Callable[[SessionNotification], None] | None = None
+    ) -> RunOutput:
+        """run/resume 共用的可取消执行路径：按传输路由到 AcpDriver 或 CLI 子进程。
+
+        每次执行用独立的取消事件并登记为 active，cancel() 只影响当前在飞的一次。
+        """
+        cancel_event = threading.Event()
+        driver: AcpDriver | None = None
+        if self._select_transport(on_event) == "acp":
+            spec = self._require_acp_spec()
+            driver = AcpDriver(name=self._backend.name, spec=spec, on_event=on_event)
+        with self._lock:
+            self._active_cancel = cancel_event
+            self._active_driver = driver
+        try:
+            if driver is not None:
+                return driver.run(req, cancel_event)
+            return self._execute_inner(req, cancel_event)
+        finally:
+            with self._lock:
+                self._active_cancel = None
+                self._active_driver = None
+
+    def _select_transport(self, on_event: Callable[[SessionNotification], None] | None) -> str:
+        """传输路由（v8 设计 §3.2）：auto 按 backend 的 ACP 声明；显式覆盖 + 防呆校验。"""
+        if self._transport == "cli":
+            if on_event is not None:
+                raise ValueError("on_event 需要 ACP 传输（当前 transport='cli' 不支持）")
+            return "cli"
+        spec = self._backend.acp
+        if self._transport == "acp":
+            if spec is None:
+                raise ValueError(
+                    f"backend '{self._backend.name}' 无 ACP 能力，transport='acp' 不可用"
+                )
+            return "acp"
+        if on_event is not None and spec is None:
+            # auto 下无 ACP 声明的 backend 传 on_event：显式报错，不静默无事件
+            raise ValueError(f"backend '{self._backend.name}' 无 ACP 能力，on_event 需要 ACP 传输")
+        return "acp" if spec is not None else "cli"
+
+    def _require_acp_spec(self) -> AcpSpec:
+        spec = self._backend.acp
+        if spec is None:  # 路由已保证非 None，防御性兜底
+            raise BackendLaunchError(self._backend.name, "ACP 能力声明缺失")
+        return spec
+
+    def _execute_inner(self, req: RunRequest, cancel_event: threading.Event) -> RunOutput:
+        binary = which_or_raise(self._backend.binary, self._backend.name)
+        argv = [binary, *self._backend.build_argv(req)]
+
+        # POSIX 下让子进程独立成组，取消时才能整组杀掉（Windows 上 False 是默认行为）
+        proc = subprocess.Popen(
+            argv,
+            cwd=self._workdir,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            start_new_session=(os.name != "nt"),
+        )
+
+        stdout_buf: list[str] = []
+        stderr_buf: list[str] = []
+
+        def _drain(stream: IO[str], buf: list[str]) -> None:
+            try:
+                for chunk in stream:
+                    if cancel_event.is_set():
+                        break
+                    buf.append(chunk)
+            finally:
+                stream.close()
+
+        t_out = threading.Thread(target=_drain, args=(proc.stdout, stdout_buf), daemon=True)
+        t_err = threading.Thread(target=_drain, args=(proc.stderr, stderr_buf), daemon=True)
+        t_out.start()
+        t_err.start()
+
+        cancelled = False
+        while proc.poll() is None:
+            if cancel_event.is_set():
+                cancelled = True
+                terminate_tree(proc)
+                try:
+                    proc.wait(timeout=5)
+                except subprocess.TimeoutExpired:
+                    kill_tree(proc)
+                    proc.wait()
+                break
+            time.sleep(0.2)
+
+        t_out.join(timeout=5)
+        t_err.join(timeout=5)
+        stdout = "".join(stdout_buf)
+        stderr = "".join(stderr_buf)
+
+        if cancelled:
+            raise RunCancelledError(self._backend.name)
+        ProcessResult(self._backend.name, proc.returncode, stdout, stderr).raise_for_status()
+        return self._backend.parse_output(stdout, stderr)

agent_cli_lib/core/session.py

@@ -0,0 +1,57 @@
+"""session 管理：统一抽象 session id 与 session 文件路径。
+
+三 CLI 的 session 机制差异较大（opencode/hermes 有 export 子命令，pi 的 session 即 jsonl 文件），
+这里统一为 SessionInfo(session_id, file_path)：
+- run 之后从 RunOutput.session_id 拿到 id
+- export_session 把会话数据落到指定文件
+- load_session 接受 id 或文件路径，返回 SessionInfo 供 runner 恢复
+
+backend 各自的导出/解析细节收纳在 backend 内，本模块只做路径判别与编排。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from agent_cli_lib.errors import SessionError
+
+
+@dataclass
+class SessionInfo:
+    """会话元信息：id 与可选的导出文件路径。"""
+
+    session_id: str = ""
+    file_path: str = ""
+
+
+def looks_like_session_id(s: str) -> bool:
+    """粗判字符串是 session id 还是文件路径。"""
+    return not (s.endswith((".json", ".jsonl", ".md", ".html")) or "/" in s or "\\" in s)
+
+
+def load_session(session: str) -> SessionInfo:
+    """按 session id 或 session 文件路径加载会话。
+
+    - 文件路径 -> 校验存在性，返回 file_path
+    - 否则当作 session id
+    """
+    if not session or not session.strip():
+        raise SessionError("session 不能为空")
+
+    if looks_like_session_id(session):
+        return SessionInfo(session_id=session.strip())
+
+    p = Path(session)
+    if not p.is_file():
+        raise SessionError(f"session 文件不存在: {session}")
+    return SessionInfo(file_path=str(p.resolve()))
+
+
+def export_session(session_id: str, target: str) -> SessionInfo:
+    """导出会话到文件（target 路径）。具体落盘动作由 runner 调 backend 完成。"""
+    if not session_id:
+        raise SessionError("导出需要有效的 session_id")
+    if not target:
+        raise SessionError("导出目标路径不能为空")
+    return SessionInfo(session_id=session_id, file_path=str(Path(target).resolve()))

agent_cli_lib/errors.py

@@ -0,0 +1,105 @@
+"""统一异常体系 + 进程错误自处理。
+
+所有 agent-cli-lib 抛出的异常都继承 AgentCliError。
+进程级错误（非零退出、文件未找到、被取消）由 ProcessResult.raise_for_status 统一翻译，
+避免调用方到处写 if rc != 0。
+"""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+
+
+class AgentCliError(Exception):
+    """所有 agent-cli-lib 异常的基类."""
+
+
+class BackendNotFoundError(AgentCliError):
+    """指定的 agent CLI 基座不存在或未安装."""
+
+    def __init__(self, backend: str) -> None:
+        self.backend = backend
+        super().__init__(f"backend '{backend}' 未安装或不可用")
+
+
+class BackendLaunchError(AgentCliError):
+    """启动 agent 进程失败（二进制缺失、权限等）."""
+
+    def __init__(self, backend: str, reason: str) -> None:
+        self.backend = backend
+        self.reason = reason
+        super().__init__(f"启动 {backend} 失败: {reason}")
+
+
+class BackendRunError(AgentCliError):
+    """agent 进程以非零状态退出."""
+
+    def __init__(self, backend: str, returncode: int, stderr: str) -> None:
+        self.backend = backend
+        self.returncode = returncode
+        self.stderr = stderr
+        super().__init__(f"{backend} 退出码 {returncode}: {stderr.strip()[:500] or '(无 stderr)'}")
+
+
+class PromptError(AgentCliError):
+    """prompt 字符串或 prompt 文件不合法."""
+
+
+class SessionError(AgentCliError):
+    """session 导出 / 恢复失败."""
+
+
+class RunCancelledError(AgentCliError):
+    """运行被主动终止（并发场景）."""
+
+    def __init__(self, backend: str) -> None:
+        self.backend = backend
+        super().__init__(f"{backend} 运行已被取消")
+
+
+class AcpProtocolError(AgentCliError):
+    """ACP 传输的协议级失败（JSON-RPC error / refusal / 空响应）。
+
+    与 BackendRunError（进程退出语义）区分：协议错误没有进程退出码与 stderr 载荷，
+    硬塞进 returncode 会产出"退出码 -32602"的误导消息。
+    """
+
+    def __init__(self, backend: str, code: int | None, message: str) -> None:
+        self.backend = backend
+        self.code = code
+        self.message = message
+        prefix = f"ACP 协议错误 code={code}" if code is not None else "ACP 协议错误"
+        super().__init__(f"{backend} {prefix}: {message}")
+
+
+class RemovedAPIError(AgentCliError):
+    """调用了已被移除的 API（由 api 层 removed 装饰器抛出）."""
+
+    def __init__(self, func: str, hint: str) -> None:
+        self.func = func
+        self.hint = hint
+        super().__init__(f"'{func}' 已移除：{hint}")
+
+
+@dataclass
+class ProcessResult:
+    """subprocess.run 结果的结构化包装（充血模型：翻译自己的错误）."""
+
+    backend: str
+    returncode: int
+    stdout: str
+    stderr: str
+
+    def raise_for_status(self) -> None:
+        """非零退出码翻译为具体异常。被取消的情况由调用方先行判断。"""
+        if self.returncode != 0:
+            raise BackendRunError(self.backend, self.returncode, self.stderr)
+
+
+def which_or_raise(binary: str, backend: str) -> str:
+    """查找 CLI 二进制路径，找不到抛 BackendLaunchError。"""
+    found = shutil.which(binary)
+    if not found:
+        raise BackendLaunchError(backend, f"未找到可执行文件 '{binary}'，请先安装")
+    return found