pagent 0.3.2__tar.gz → 0.4.0__tar.gz

{pagent-0.3.2 → pagent-0.4.0}/PKG-INFO

@@ -1,21 +1,25 @@
 Metadata-Version: 2.3
 Name: pagent
-Version: 0.3.2
-Summary: Minimal OpenAI Chat Completions agent (session + tools).
+Version: 0.4.0
+Summary: Async Python agent library and terminal REPL (OpenAI-compatible Chat Completions + sandbox).
 Author: gongyulei
 Author-email: gongyulei <gongyulei@stu.xmu.edu.cn>
+Requires-Dist: asyncssh>=2.24.0
 Requires-Dist: docstring-parser>=0.18.0
 Requires-Dist: openai>=2.31.0
+Requires-Dist: prompt-toolkit>=3.0.52
 Requires-Dist: tiktoken>=0.7.0
 Requires-Dist: agent-client-protocol>=0.10 ; extra == 'acp'
 Requires-Dist: ddgs>=7 ; extra == 'acp'
 Requires-Dist: ddgs>=7 ; extra == 'search'
+Requires-Dist: asyncssh>=2.14 ; extra == 'ssh'
 Requires-Dist: transformers>=4.40 ; extra == 'tokens'
 Requires-Python: >=3.11
 Project-URL: Documentation, https://synclionpaw.github.io/pagent/
 Project-URL: Homepage, https://github.com/SyncLionPaw/pagent
 Provides-Extra: acp
 Provides-Extra: search
+Provides-Extra: ssh
 Provides-Extra: tokens
 Description-Content-Type: text/markdown
 
@@ -26,6 +30,7 @@ Description-Content-Type: text/markdown
 # pagent (English)
 
 [![CI](https://github.com/SyncLionPaw/pagent/actions/workflows/ruff.yml/badge.svg)](https://github.com/SyncLionPaw/pagent/actions/workflows/ruff.yml)
+[![Coverage](https://codecov.io/gh/SyncLionPaw/pagent/graph/badge.svg)](https://app.codecov.io/gh/SyncLionPaw/pagent)
 
 Language: [中文](./README.zh-CN.md) | [English](./README.en.md) · [Docs](https://synclionpaw.github.io/pagent/) · [For agents](./AGENTS.md) · [llms.txt](./llms.txt)
 
@@ -59,6 +64,14 @@ uv add pagent
 uv add "pagent[search]"
 ```
 
+### uvx (terminal REPL)
+
+```bash
+export DEEPSEEK_API_KEY="your-key"
+uvx pagent
+uvx pagent --thread-id demo
+```
+
 ### conda
 
 ```bash

{pagent-0.3.2 → pagent-0.4.0}/README.md

@@ -5,6 +5,7 @@
 # pagent (English)
 
 [![CI](https://github.com/SyncLionPaw/pagent/actions/workflows/ruff.yml/badge.svg)](https://github.com/SyncLionPaw/pagent/actions/workflows/ruff.yml)
+[![Coverage](https://codecov.io/gh/SyncLionPaw/pagent/graph/badge.svg)](https://app.codecov.io/gh/SyncLionPaw/pagent)
 
 Language: [中文](./README.zh-CN.md) | [English](./README.en.md) · [Docs](https://synclionpaw.github.io/pagent/) · [For agents](./AGENTS.md) · [llms.txt](./llms.txt)
 
@@ -38,6 +39,14 @@ uv add pagent
 uv add "pagent[search]"
 ```
 
+### uvx (terminal REPL)
+
+```bash
+export DEEPSEEK_API_KEY="your-key"
+uvx pagent
+uvx pagent --thread-id demo
+```
+
 ### conda
 
 ```bash

pagent-0.4.0/pyproject.toml

@@ -0,0 +1,101 @@
+[project]
+name = "pagent"
+version = "0.4.0"
+description = "Async Python agent library and terminal REPL (OpenAI-compatible Chat Completions + sandbox)."
+readme = "README.md"
+authors = [
+    { name = "gongyulei", email = "gongyulei@stu.xmu.edu.cn" },
+]
+requires-python = ">=3.11"
+dependencies = [
+    "asyncssh>=2.24.0",
+    "docstring-parser>=0.18.0",
+    "openai>=2.31.0",
+    "prompt-toolkit>=3.0.52",
+    "tiktoken>=0.7.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/SyncLionPaw/pagent"
+Documentation = "https://synclionpaw.github.io/pagent/"
+
+[project.optional-dependencies]
+search = ["ddgs>=7"]
+tokens = ["transformers>=4.40"]
+acp = ["agent-client-protocol>=0.10", "ddgs>=7"]
+ssh = ["asyncssh>=2.14"]
+
+[project.scripts]
+pagent = "app.repl:main"
+
+[build-system]
+requires = ["uv_build>=0.8.20,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = ["pagent", "pagentv4", "app"]
+
+[dependency-groups]
+dev = [
+    "agent-client-protocol>=0.10",
+    "asyncssh>=2.14",
+    "coverage[toml]>=7.15.0",
+    "ddgs>=7",
+    "pre-commit>=4",
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.9",
+]
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[tool.coverage.run]
+# 只统计业务代码，排除测试、示例、文档
+source = ["src"]
+branch = true                  # 分支覆盖（if/else 两条腿都算），比行覆盖更严格
+omit = [
+    "*/tests/*",
+    "*/examples/*",
+    "*/docs/*",
+    "*/__main__.py",
+    # 故意的非法语法 demo，无法被 import
+    "src/pagentv4/core/hacked_agent.py",
+    # v3 准备淘汰，整体不计入覆盖率（保留测试直到彻底移除）
+    "src/pagentv3/*",
+    # 故意不测的旧 Agent 实现（已被 core/agent.py 取代）
+    "src/pagentv4/core/agent_restored.py",
+    # 需要真实环境（docker / ssh / ACP server）才能测，纯单测覆盖不到
+    "src/pagentv4/sandbox/backends/container.py",
+    "src/pagentv4/sandbox/backends/ssh.py",
+    "src/pagentv4/adapters/acp.py",
+]
+
+[tool.coverage.report]
+# 终端报告里按行列出未覆盖的代码行
+show_missing = true
+skip_covered = false
+# 排除琐碎的、不算真正逻辑的行
+exclude_lines = [
+    "pragma: no cover",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "@(abc\\.)?abstractmethod",
+]
+
+[tool.ruff]
+target-version = "py311"
+src = ["src"]
+extend-exclude = ["src/pagentv4/core/hacked_agent.py"]  # intentional invalid syntax demo
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]
+
+[tool.ruff.lint.per-file-ignores]
+"examples/demo2/*.py" = ["E402"]  # sys.path adjusted before local / sibling imports
+"examples/acp_agent/main.py" = ["E402"]
+"tests/test_acp_tools.py" = ["E402"]
+
+[tool.ruff.format]
+quote-style = "double"

pagent-0.4.0/src/app/Dockerfile

@@ -0,0 +1,45 @@
+# pagent app 默认 agent 镜像 —— Alpine + uv(Python) + Node。
+#
+# 不用 python:* 基础镜像，避免系统 Python 与 uv 重复；Python 由 uv 安装。
+# Alpine 比 Debian slim 小很多；Node 走 apk（比 nvm 更瘦，无版本切换）。
+# 预装：curl、jq、git、uv、node/npm。
+#
+# 注意：musl 环境，少数带 glibc 二进制的 wheel 可能不兼容。
+#
+# 用法：
+#     docker build -t pagent:latest -f src/app/Dockerfile src/app
+#     # 或
+#     cd src/app && docker build -t pagent:latest .
+#
+# bundled pagent.toml 默认 backend=docker, image=pagent:latest
+
+FROM alpine:3.21
+
+ARG PYTHON_VERSION=3.12
+
+RUN apk add --no-cache \
+        bash \
+        ca-certificates \
+        curl \
+        git \
+        jq \
+        nodejs \
+        npm \
+        tar \
+        xz
+
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh \
+    && mv /root/.local/bin/uv /usr/local/bin/uv \
+    && mv /root/.local/bin/uvx /usr/local/bin/uvx
+
+ENV UV_PYTHON_PREFERENCE=only-managed
+RUN uv python install "$PYTHON_VERSION" \
+    && ln -sf "$(uv python find "$PYTHON_VERSION")" /usr/local/bin/python3 \
+    && ln -sf python3 /usr/local/bin/python \
+    && uv cache clean \
+    && rm -rf /root/.cache
+
+RUN mkdir -p /home/agent
+WORKDIR /home/agent
+
+CMD ["sleep", "infinity"]

pagent-0.4.0/src/app/Dockerfile.browser

@@ -0,0 +1,51 @@
+# pagent browser 镜像 —— 在默认 agent 镜像基础上加 headless Chromium。
+#
+# 预装：curl、jq、git、uv、node/npm、Chromium、Noto CJK 字体。
+# 渲染 HTML、导出 PDF 时用；日常开发继续用 Dockerfile。
+#
+# 用法：
+#     docker build -t pagent:browser -f src/app/Dockerfile.browser src/app
+#     # pagent.toml: image = "pagent:browser"
+#
+# 容器内 headless 示例：
+#     chromium-browser --headless --disable-gpu --no-sandbox --disable-dev-shm-usage \
+#         --screenshot=/home/agent/out.png https://example.com
+
+FROM alpine:3.21
+
+ARG PYTHON_VERSION=3.12
+
+RUN apk add --no-cache \
+        bash \
+        ca-certificates \
+        chromium \
+        curl \
+        font-noto-cjk \
+        git \
+        jq \
+        nodejs \
+        npm \
+        tar \
+        xz
+
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh \
+    && mv /root/.local/bin/uv /usr/local/bin/uv \
+    && mv /root/.local/bin/uvx /usr/local/bin/uvx
+
+ENV UV_PYTHON_PREFERENCE=only-managed
+RUN uv python install "$PYTHON_VERSION" \
+    && ln -sf "$(uv python find "$PYTHON_VERSION")" /usr/local/bin/python3 \
+    && ln -sf python3 /usr/local/bin/python \
+    && uv cache clean \
+    && rm -rf /root/.cache
+
+# Alpine 的 chromium 包；Puppeteer/Playwright 可指向这个二进制。
+ENV CHROME_BIN=/usr/bin/chromium-browser \
+    CHROMIUM_PATH=/usr/bin/chromium-browser \
+    PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser \
+    CHROMIUM_FLAGS="--headless --disable-gpu --no-sandbox --disable-dev-shm-usage"
+
+RUN mkdir -p /home/agent
+WORKDIR /home/agent
+
+CMD ["sleep", "infinity"]

pagent-0.4.0/src/app/__init__.py

@@ -0,0 +1,15 @@
+"""pagent — terminal REPL on pagentv4."""
+
+from .config import ReplConfig, build_parser, config_from_args, load_config
+from .repl import format_banner, main, open_runner, run_repl
+
+__all__ = [
+    "ReplConfig",
+    "build_parser",
+    "config_from_args",
+    "format_banner",
+    "load_config",
+    "main",
+    "open_runner",
+    "run_repl",
+]

pagent-0.4.0/src/app/__main__.py

@@ -0,0 +1,3 @@
+from .repl import main
+
+main()

pagent-0.4.0/src/app/clean.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from pagentv4.core.message import Messages
+from pagentv4.runtime.conversation import (
+    JsonlConversationStore,
+    default_conversations_root,
+)
+from pagentv4.runtime.thread import (
+    MESSAGES_CONVERSATION_ID,
+    SPEC_FILENAME,
+    WORKSPACE_DIRNAME,
+    default_threads_root,
+)
+
+MESSAGES_FILENAME = "messages.jsonl"
+
+
+@dataclass(slots=True)
+class CleanReport:
+    removed_threads: list[str] = field(default_factory=list)
+    removed_conversations: list[str] = field(default_factory=list)
+
+
+def user_message_count(path: Path) -> int:
+    if not path.is_file():
+        return 0
+    messages = Messages.load_from_jsonl(path)
+    return sum(1 for message in messages.data if message.role == "user")
+
+
+def workspace_is_empty(workspace: Path) -> bool:
+    if not workspace.is_dir():
+        return True
+    return not any(workspace.iterdir())
+
+
+def thread_is_useless(thread_dir: Path) -> bool:
+    if not (thread_dir / SPEC_FILENAME).is_file():
+        return False
+    if user_message_count(thread_dir / MESSAGES_FILENAME) > 0:
+        return False
+    return workspace_is_empty(thread_dir / WORKSPACE_DIRNAME)
+
+
+def conversation_is_useless(path: Path) -> bool:
+    if not path.is_file():
+        return False
+    if path.stat().st_size == 0:
+        return True
+    return user_message_count(path) == 0
+
+
+def iter_thread_dirs(root: Path) -> list[Path]:
+    if not root.is_dir():
+        return []
+    return [
+        child
+        for child in root.iterdir()
+        if child.is_dir() and (child / SPEC_FILENAME).is_file()
+    ]
+
+
+def clean_pagent(
+    *,
+    threads_root: Path | str | None = None,
+    conversations_root: Path | str | None = None,
+    keep_thread_ids: set[str] | frozenset[str] = frozenset(),
+    remove: bool = True,
+) -> CleanReport:
+    """Remove empty threads and orphan conversations under `.pagent/`.
+
+    A thread is useless when it has no user messages and an empty workspace.
+    A standalone conversation file is useless when empty or has no user messages.
+    """
+    report = CleanReport()
+    threads_base = (
+        Path(threads_root) if threads_root is not None else default_threads_root()
+    )
+    conversations_base = (
+        Path(conversations_root)
+        if conversations_root is not None
+        else Path(default_conversations_root())
+    )
+
+    for thread_dir in iter_thread_dirs(threads_base):
+        thread_id = thread_dir.name
+        if thread_id in keep_thread_ids:
+            continue
+        if not thread_is_useless(thread_dir):
+            continue
+        report.removed_threads.append(thread_id)
+        if remove:
+            shutil.rmtree(thread_dir)
+
+    if conversations_base.is_dir():
+        store = JsonlConversationStore(root=conversations_base)
+        for conversation_id in store.list():
+            path = store.path_for(conversation_id)
+            if conversation_id == MESSAGES_CONVERSATION_ID:
+                continue
+            if not conversation_is_useless(path):
+                continue
+            report.removed_conversations.append(conversation_id)
+            if remove:
+                path.unlink()
+
+    return report
+
+
+def format_clean_report(report: CleanReport) -> str | None:
+    parts: list[str] = []
+    if report.removed_threads:
+        names = ", ".join(report.removed_threads)
+        parts.append(f"清理 {len(report.removed_threads)} 条空 thread: {names}")
+    if report.removed_conversations:
+        names = ", ".join(report.removed_conversations)
+        parts.append(
+            f"清理 {len(report.removed_conversations)} 个空 conversation: {names}"
+        )
+    if not parts:
+        return None
+    return " · ".join(parts)

pagent-0.4.0/src/app/concurrent_repl.py

@@ -0,0 +1,250 @@
+"""底栏固定输入 REPL — 全屏布局，输入行钉在终端视口最底。"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+
+from pagentv4 import Runner
+
+from .config import ReplConfig
+from .layout_terminal import LayoutTerminal
+from .render import (
+    DIM,
+    RED,
+    YELLOW,
+    RenderState,
+    c,
+    consume_run,
+    emit_user_line,
+    format_banner,
+)
+from .repl import (
+    format_fatal_error,
+    handle_command,
+    handle_prefixed_command,
+    open_runner,
+    say_goodbye,
+)
+from .terminal import emit, layout_terminal
+from .tool_permit import apply_permit_answer, parse_permit_answer
+
+
+async def dispatch_user_line(
+    line: str,
+    *,
+    runner: Runner,
+    run_task: asyncio.Task | None,
+    color: bool,
+) -> tuple[str, asyncio.Task | None]:
+    """单元测试用：steer 分支。"""
+    text = line.strip()
+    if not text:
+        return "continue", run_task
+    if run_task is not None and not run_task.done():
+        runner.steer(text)
+        emit(c(f"↳ steer: {text}", DIM, on=color))
+        return "continue", run_task
+    return "start_run", run_task
+
+
+async def run_layout_loop(
+    runner: Runner,
+    terminal: LayoutTerminal,
+    run_state: dict,
+    *,
+    color: bool,
+    user_label: str,
+    assistant_label: str,
+    permit_auto: bool = False,
+) -> bool:
+    run_task: asyncio.Task | None = None
+    had_user_turn = False
+    input_task = asyncio.create_task(terminal.input_queue.get())
+    terminal.set_prefix(f"{user_label}> ")
+
+    while True:
+        run_state["active"] = run_task is not None and not run_task.done()
+        idle_prefix = f"{user_label}> "
+        if run_state.get("permit") is not None:
+            terminal.set_prefix("permit> ")
+        elif run_state["active"]:
+            terminal.set_prefix("steer> ")
+        else:
+            terminal.set_prefix(idle_prefix)
+
+        wait_set: set[asyncio.Task] = {input_task}
+        if run_state["active"] and run_task is not None:
+            wait_set.add(run_task)
+
+        done, _ = await asyncio.wait(
+            wait_set,
+            return_when=asyncio.FIRST_COMPLETED,
+        )
+
+        if run_task is not None and run_task in done:
+            run_task.result()
+            run_task = None
+            had_user_turn = True
+            if input_task.done():
+                input_task = asyncio.create_task(terminal.input_queue.get())
+            continue
+
+        if input_task not in done:
+            continue
+
+        try:
+            line = input_task.result()
+        except asyncio.CancelledError:
+            break
+
+        input_task = asyncio.create_task(terminal.input_queue.get())
+
+        if line is None:
+            terminal.write()
+            say_goodbye(color=color)
+            break
+
+        text = line.strip()
+        if not text:
+            continue
+
+        if await handle_prefixed_command(text, runner, color=color):
+            continue
+
+        if text.startswith("/"):
+            if run_task is not None and not run_task.done():
+                emit(c("run 进行中，/ 命令请等结束后再用", YELLOW, on=color))
+                continue
+            if await handle_command(text, runner, color=color):
+                say_goodbye(color=color)
+                break
+            continue
+
+        permit_event = run_state.get("permit")
+        if permit_event is not None:
+            answer = parse_permit_answer(text)
+            if answer is None:
+                emit(c("输入 y 批准 / n 拒绝", DIM, on=color))
+                continue
+            apply_permit_answer(runner, permit_event.tool_call_id, answer)
+            label = "已批准" if answer else "已拒绝"
+            emit(c(label, DIM, on=color))
+            wait = run_state.get("permit_wait")
+            if wait is not None:
+                wait.set()
+            continue
+
+        if run_task is not None and not run_task.done():
+            runner.steer(text)
+            emit(c(f"↳ steer: {text}", DIM, on=color))
+            continue
+
+        emit_user_line(text, color=color, user_label=user_label)
+        state = RenderState(
+            color=color,
+            user_label=user_label,
+            assistant_label=assistant_label,
+        )
+        run_task = asyncio.create_task(
+            consume_run(
+                runner,
+                text,
+                state,
+                run_state=run_state,
+                permit_auto=permit_auto,
+            )
+        )
+        had_user_turn = True
+
+    return had_user_turn
+
+
+async def run_concurrent_repl(config: ReplConfig, *, color: bool | None = None) -> int:
+    use_color = sys.stdout.isatty() if color is None else color
+    if not sys.stdout.isatty():
+        from .repl import run_blocking_repl
+
+        return await run_blocking_repl(config, color=use_color)
+
+    from .clean import clean_pagent, format_clean_report
+
+    runner: Runner | None = None
+    exit_code = 0
+    had_user_turn = False
+    try:
+        runner = await open_runner(config)
+        run_state: dict = {"active": False, "permit": None}
+        terminal = LayoutTerminal(color=use_color)
+        app = terminal.build_application(run_state=run_state, runner=runner)
+
+        token = layout_terminal.set(terminal)
+        try:
+            terminal.write(format_banner(runner, color=use_color))
+            terminal.write(
+                c(
+                    "输入行固定在最底；run 中 Enter=steer"
+                    + ("" if config.permission_auto() else "，危险工具需 permit> 审批")
+                    + "，Esc/Ctrl+C=cancel",
+                    DIM,
+                    on=use_color,
+                )
+            )
+
+            loop_task = asyncio.create_task(
+                run_layout_loop(
+                    runner,
+                    terminal,
+                    run_state,
+                    color=use_color,
+                    user_label=config.resolved_user_label(),
+                    assistant_label=config.resolved_assistant_label(),
+                    permit_auto=config.permission_auto(),
+                )
+            )
+            app_task = asyncio.create_task(app.run_async())
+            had_user_turn = await loop_task
+            app.exit()
+            await app_task
+        finally:
+            layout_terminal.reset(token)
+    except BaseException as exc:
+        if isinstance(exc, SystemExit):
+            raise
+        if isinstance(exc, KeyboardInterrupt):
+            emit()
+            say_goodbye(color=use_color)
+        else:
+            message = format_fatal_error(exc, phase="start")
+            emit(c(message, RED, on=use_color), file=sys.stderr, flush=True)
+            exit_code = 1
+    finally:
+        if runner is not None:
+            try:
+                await runner.close()
+            except BaseException as exc:
+                if isinstance(exc, SystemExit):
+                    raise
+                if exit_code == 0:
+                    message = format_fatal_error(exc, phase="close")
+                    emit(c(message, RED, on=use_color), file=sys.stderr, flush=True)
+                    exit_code = 1
+            keep = {runner.thread.id} if had_user_turn else set()
+            report = clean_pagent(keep_thread_ids=keep)
+            clean_message = format_clean_report(report)
+            if clean_message:
+                emit(c(clean_message, DIM, on=use_color), flush=True)
+    return exit_code
+
+
+def main(argv: list[str] | None = None) -> None:
+    from .repl import build_parser, config_from_args
+
+    parser = build_parser()
+    config = config_from_args(parser.parse_args(argv))
+    try:
+        code = asyncio.run(run_concurrent_repl(config))
+    except KeyboardInterrupt:
+        emit()
+        raise SystemExit(0) from None
+    raise SystemExit(code)