nyanpasu 0.1.0__tar.gz

nyanpasu-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026-present, Nyakku Shigure
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

nyanpasu-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: nyanpasu
+Version: 0.1.0
+Summary: A plugin-oriented Codex-powered agent service.
+Keywords: 
+Author: Nyakku Shigure
+Author-email: Nyakku Shigure <sigure.qaq@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Dist: anyio>=4.12.0
+Requires-Dist: fastapi>=0.125.0
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pydantic>=2.12.0
+Requires-Dist: typer>=0.20.0
+Requires-Dist: uvicorn>=0.38.0
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/ShigureLab/nyanpasu
+Project-URL: Documentation, https://github.com/ShigureLab/nyanpasu
+Project-URL: Repository, https://github.com/ShigureLab/nyanpasu
+Project-URL: Issues, https://github.com/ShigureLab/nyanpasu/issues
+Description-Content-Type: text/markdown
+
+# Nyanpasu
+
+Nyanpasu is a plugin-oriented Codex agent service. The core runtime is deliberately generic: it accepts events from plugins, turns them into `AgentTask` objects, prepares one reusable workspace per context, reuses persistent Codex threads per context, records state in SQLite, and runs Codex under a constrained runtime policy.
+
+GitHub PR review is implemented by the `nyanpasu-github-reviewer` plugin, not by the core package.
+
+## Core Responsibilities
+
+- Async task execution with per-context serialization and bounded concurrency.
+- Context workspace management. By default, one `context_key` owns one reusable worktree that is reset to the task revision before each run.
+- Optional event snapshots for plugins that explicitly need per-event isolation.
+- Persistent task, thread, and context state.
+- Codex backend management through `codex app-server` or `codex exec`.
+- Plugin lifecycle hooks, HTTP router registration, and post-process hooks.
+- Runtime safety defaults: `sandbox = "workspace-write"` and `approval_policy = "never"`.
+
+Anything domain-specific belongs in a plugin. GitHub event parsing, polling, webhook signatures, `gh-llm` prompts, and review submission live in `packages/nyanpasu-github-reviewer`.
+
+## Configuration
+
+Nyanpasu uses TOML and Pydantic models. Core config lives at the top level; plugin config lives under `plugins.<plugin_id>`.
+
+Nyanpasu has one user-facing home directory. Set `NYANPASU_HOME` to choose it; otherwise it defaults to `~/.nyanpasu`. Config is always read from `$NYANPASU_HOME/config.toml`, and runtime state, logs, SQLite, and managed worktrees also live under `$NYANPASU_HOME`.
+
+`state_dir` is intentionally not a TOML option. To move both config and state, move `NYANPASU_HOME`.
+
+```toml
+enabled_plugins = ["github_reviewer"]
+
+[server]
+host = "127.0.0.1"
+port = 8765
+
+[codex]
+backend = "app-server"
+sandbox = "workspace-write"
+approval_policy = "never"
+command_timeout_seconds = 3600
+
+[runtime]
+concurrency = 4
+coalesce_window_seconds = 600
+clean_event_snapshots = true
+
+[plugins.github_reviewer]
+github_login = "your-github-login"
+poll_interval_seconds = 600
+poll_event_pages = 3
+poll_max_events_per_cycle = 0
+review_language = "Chinese"
+
+[[plugins.github_reviewer.instruction_docs]]
+name = "SOUL.md"
+path = "/path/to/SOUL.md"
+
+[plugins.github_reviewer.repos."owner/repo"]
+local_path = "/path/to/repo"
+github_remote = "https://github.com/owner/repo.git"
+base_branches = ["main"]
+
+[[plugins.github_reviewer.repos."owner/repo".instruction_docs]]
+name = "AGENTS.md"
+path = "/path/to/repo/AGENTS.md"
+required = false
+```
+
+Instruction documents are task-scoped. A plugin can attach files such as `SOUL.md`, `AGENTS.md`, or project policy notes to an `AgentTask`; the core runtime appends them only for that task before invoking Codex. They are not global Nyanpasu identity and are not hardcoded into the core or GitHub reviewer prompt.
+
+## Run
+
+Create `$NYANPASU_HOME/config.toml` from `examples/config.toml`, then start the agent service:
+
+```bash
+export NYANPASU_HOME="$HOME/.nyanpasu"
+uv run nyanpasu serve
+```
+
+Inspect runtime state:
+
+```bash
+uv run nyanpasu status
+curl http://127.0.0.1:8765/tasks
+curl http://127.0.0.1:8765/contexts
+```
+
+The GitHub reviewer plugin mounts its webhook at:
+
+```text
+POST /plugins/github-reviewer/webhook
+```
+
+The plugin can also start its poller during plugin setup. Events poll uses GitHub repository events as the source of truth: the first poll records the current repo event cursor without handling older events, later polls process matching events after that cursor, and already processed delivery ids are skipped. `poll_max_events_per_cycle = 0` means process every matching event in the poll window; set it to a positive number only when you intentionally want a per-cycle cap.
+
+## Plugin Contract
+
+A plugin exposes a `NyanpasuPlugin` through the `nyanpasu.plugins` entry point group.
+
+```python
+class MyPlugin:
+    id = "my_plugin"
+    config_model = MyPluginConfig
+
+    async def setup(self, runtime, config):
+        runtime.add_router(router, prefix="/plugins/my-plugin")
+        runtime.add_post_process_hook(self.id, self.after_task)
+        await runtime.submit(task)
+
+    async def shutdown(self):
+        ...
+```
+
+Plugins send work to the core by creating `AgentTask`:
+
+```python
+AgentTask(
+    task_id="event-123",
+    action=TaskAction.RUN,
+    context_key="my-domain:object-456",
+    prompt="Review or handle this event.",
+    instruction_docs=[
+        InstructionDocument(
+            name="AGENTS.md",
+            source="/path/to/repo/AGENTS.md",
+            content="Follow this repository's local conventions.",
+        ),
+    ],
+    workspace=WorkspaceRef(
+        key="owner/repo",
+        local_path=Path("/path/to/repo"),
+        remote="https://github.com/owner/repo.git",
+        ref="pull/123/head",
+        revision="abc123",
+    ),
+    dedupe_key="event-123",
+    metadata={"plugin_id": "my_plugin"},
+)
+```
+
+Core executes the task and calls post-process hooks registered for `metadata["plugin_id"]`.
+
+By default, the task uses `workspace_policy = "context"`: Nyanpasu resets the context worktree to `workspace.revision` or `workspace.ref`, runs Codex there, and keeps that workspace for the next event in the same context. Plugins can opt into `workspace_policy = "event_snapshot"` only when they need a disposable per-event worktree.

nyanpasu-0.1.0/README.md

@@ -0,0 +1,141 @@
+# Nyanpasu
+
+Nyanpasu is a plugin-oriented Codex agent service. The core runtime is deliberately generic: it accepts events from plugins, turns them into `AgentTask` objects, prepares one reusable workspace per context, reuses persistent Codex threads per context, records state in SQLite, and runs Codex under a constrained runtime policy.
+
+GitHub PR review is implemented by the `nyanpasu-github-reviewer` plugin, not by the core package.
+
+## Core Responsibilities
+
+- Async task execution with per-context serialization and bounded concurrency.
+- Context workspace management. By default, one `context_key` owns one reusable worktree that is reset to the task revision before each run.
+- Optional event snapshots for plugins that explicitly need per-event isolation.
+- Persistent task, thread, and context state.
+- Codex backend management through `codex app-server` or `codex exec`.
+- Plugin lifecycle hooks, HTTP router registration, and post-process hooks.
+- Runtime safety defaults: `sandbox = "workspace-write"` and `approval_policy = "never"`.
+
+Anything domain-specific belongs in a plugin. GitHub event parsing, polling, webhook signatures, `gh-llm` prompts, and review submission live in `packages/nyanpasu-github-reviewer`.
+
+## Configuration
+
+Nyanpasu uses TOML and Pydantic models. Core config lives at the top level; plugin config lives under `plugins.<plugin_id>`.
+
+Nyanpasu has one user-facing home directory. Set `NYANPASU_HOME` to choose it; otherwise it defaults to `~/.nyanpasu`. Config is always read from `$NYANPASU_HOME/config.toml`, and runtime state, logs, SQLite, and managed worktrees also live under `$NYANPASU_HOME`.
+
+`state_dir` is intentionally not a TOML option. To move both config and state, move `NYANPASU_HOME`.
+
+```toml
+enabled_plugins = ["github_reviewer"]
+
+[server]
+host = "127.0.0.1"
+port = 8765
+
+[codex]
+backend = "app-server"
+sandbox = "workspace-write"
+approval_policy = "never"
+command_timeout_seconds = 3600
+
+[runtime]
+concurrency = 4
+coalesce_window_seconds = 600
+clean_event_snapshots = true
+
+[plugins.github_reviewer]
+github_login = "your-github-login"
+poll_interval_seconds = 600
+poll_event_pages = 3
+poll_max_events_per_cycle = 0
+review_language = "Chinese"
+
+[[plugins.github_reviewer.instruction_docs]]
+name = "SOUL.md"
+path = "/path/to/SOUL.md"
+
+[plugins.github_reviewer.repos."owner/repo"]
+local_path = "/path/to/repo"
+github_remote = "https://github.com/owner/repo.git"
+base_branches = ["main"]
+
+[[plugins.github_reviewer.repos."owner/repo".instruction_docs]]
+name = "AGENTS.md"
+path = "/path/to/repo/AGENTS.md"
+required = false
+```
+
+Instruction documents are task-scoped. A plugin can attach files such as `SOUL.md`, `AGENTS.md`, or project policy notes to an `AgentTask`; the core runtime appends them only for that task before invoking Codex. They are not global Nyanpasu identity and are not hardcoded into the core or GitHub reviewer prompt.
+
+## Run
+
+Create `$NYANPASU_HOME/config.toml` from `examples/config.toml`, then start the agent service:
+
+```bash
+export NYANPASU_HOME="$HOME/.nyanpasu"
+uv run nyanpasu serve
+```
+
+Inspect runtime state:
+
+```bash
+uv run nyanpasu status
+curl http://127.0.0.1:8765/tasks
+curl http://127.0.0.1:8765/contexts
+```
+
+The GitHub reviewer plugin mounts its webhook at:
+
+```text
+POST /plugins/github-reviewer/webhook
+```
+
+The plugin can also start its poller during plugin setup. Events poll uses GitHub repository events as the source of truth: the first poll records the current repo event cursor without handling older events, later polls process matching events after that cursor, and already processed delivery ids are skipped. `poll_max_events_per_cycle = 0` means process every matching event in the poll window; set it to a positive number only when you intentionally want a per-cycle cap.
+
+## Plugin Contract
+
+A plugin exposes a `NyanpasuPlugin` through the `nyanpasu.plugins` entry point group.
+
+```python
+class MyPlugin:
+    id = "my_plugin"
+    config_model = MyPluginConfig
+
+    async def setup(self, runtime, config):
+        runtime.add_router(router, prefix="/plugins/my-plugin")
+        runtime.add_post_process_hook(self.id, self.after_task)
+        await runtime.submit(task)
+
+    async def shutdown(self):
+        ...
+```
+
+Plugins send work to the core by creating `AgentTask`:
+
+```python
+AgentTask(
+    task_id="event-123",
+    action=TaskAction.RUN,
+    context_key="my-domain:object-456",
+    prompt="Review or handle this event.",
+    instruction_docs=[
+        InstructionDocument(
+            name="AGENTS.md",
+            source="/path/to/repo/AGENTS.md",
+            content="Follow this repository's local conventions.",
+        ),
+    ],
+    workspace=WorkspaceRef(
+        key="owner/repo",
+        local_path=Path("/path/to/repo"),
+        remote="https://github.com/owner/repo.git",
+        ref="pull/123/head",
+        revision="abc123",
+    ),
+    dedupe_key="event-123",
+    metadata={"plugin_id": "my_plugin"},
+)
+```
+
+Core executes the task and calls post-process hooks registered for `metadata["plugin_id"]`.
+
+By default, the task uses `workspace_policy = "context"`: Nyanpasu resets the context worktree to `workspace.revision` or `workspace.ref`, runs Codex there, and keeps that workspace for the next event in the same context. Plugins can opt into `workspace_policy = "event_snapshot"` only when they need a disposable per-event worktree.

nyanpasu-0.1.0/pyproject.toml

@@ -0,0 +1,115 @@
+[project]
+name = "nyanpasu"
+version = "0.1.0"
+description = "A plugin-oriented Codex-powered agent service."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "anyio>=4.12.0",
+  "fastapi>=0.125.0",
+  "loguru>=0.7.3",
+  "pydantic>=2.12.0",
+  "typer>=0.20.0",
+  "uvicorn>=0.38.0",
+]
+authors = [{ name = "Nyakku Shigure", email = "sigure.qaq@gmail.com" }]
+keywords = []
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+  "Operating System :: OS Independent",
+  "Typing :: Typed",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: Implementation :: CPython",
+]
+
+[project.urls]
+Homepage = "https://github.com/ShigureLab/nyanpasu"
+Documentation = "https://github.com/ShigureLab/nyanpasu"
+Repository = "https://github.com/ShigureLab/nyanpasu"
+Issues = "https://github.com/ShigureLab/nyanpasu/issues"
+
+[project.scripts]
+nyanpasu = "nyanpasu.__main__:app"
+
+[dependency-groups]
+dev = [
+  "httpx>=0.28.0",
+  "nyanpasu-github-reviewer",
+  "ty>=0.0.39",
+  "ruff>=0.15.14",
+  "pytest>=9.0.3",
+  "pytest-rerunfailures>=16.3",
+]
+
+[tool.uv.workspace]
+members = ["packages/nyanpasu-github-reviewer"]
+
+[tool.uv.sources]
+nyanpasu = { workspace = true }
+nyanpasu-github-reviewer = { workspace = true }
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+  # Pyflakes
+  "F",
+  # Pycodestyle
+  "E",
+  "W",
+  # Isort
+  "I",
+  # Comprehensions
+  "C4",
+  # Debugger
+  "T100",
+  # Pyupgrade
+  "UP",
+  # Flake8-pyi
+  "PYI",
+  # Bugbear
+  "B",
+  # Pylint
+  "PLE",
+  # Flake8-simplify
+  "SIM101",
+  # Flake8-use-pathlib
+  "PTH",
+  # Pygrep-hooks
+  "PGH004",
+  # Flake8-type-checking
+  "TC",
+  # Flake8-raise
+  "RSE",
+  # Refurb
+  "FURB",
+  # Flake8-future-annotations
+  "FA",
+  # Yesqa
+  "RUF100",
+]
+ignore = [
+  "E501", # line too long, duplicate with ruff fmt
+]
+future-annotations = true
+
+[tool.ruff.lint.isort]
+required-imports = ["from __future__ import annotations"]
+known-first-party = ["nyanpasu", "nyanpasu_github_reviewer"]
+combine-as-imports = true
+
+[tool.ruff.lint.flake8-type-checking]
+runtime-evaluated-decorators = ["typing.runtime_checkable", "runtime_checkable"]
+runtime-evaluated-base-classes = ["pydantic.BaseModel"]
+
+[build-system]
+requires = ["uv_build>=0.11.2,<0.12.0"]
+build-backend = "uv_build"

nyanpasu-0.1.0/src/nyanpasu/__init__.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+__version__ = "0.1.0"

nyanpasu-0.1.0/src/nyanpasu/__main__.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import json
+import sys
+from typing import TYPE_CHECKING, Annotated, Any
+
+import anyio
+import typer
+import uvicorn
+from loguru import logger
+
+from nyanpasu.agent import AgentService
+from nyanpasu.config import ensure_state_dirs, load_config
+from nyanpasu.models import AgentTask
+from nyanpasu.store import StateStore
+from nyanpasu.web import create_app
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+app = typer.Typer(no_args_is_help=True)
+LOG_FORMAT = (
+    "<green>{time:YYYY-MM-DD HH:mm:ss.SSS Z}</green> | "
+    "<level>{level: <8}</level> | "
+    "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - "
+    "<level>{message}</level>"
+)
+
+
+def configure_logging() -> None:
+    logger.remove()
+    logger.add(sys.stderr, level="INFO", format=LOG_FORMAT, backtrace=False, diagnose=False)
+
+
+@app.command()
+def serve() -> None:
+    configure_logging()
+    resolved = load_config()
+    ensure_state_dirs(resolved)
+    uvicorn.run(create_app(resolved), host=resolved.server.host, port=resolved.server.port, log_level="info")
+
+
+@app.command()
+def run_task(path: Annotated[Path, typer.Argument(help="Path to a JSON task file.")]) -> None:
+    configure_logging()
+    resolved = load_config()
+    ensure_state_dirs(resolved)
+    task = _task_from_json(json.loads(path.read_text(encoding="utf-8")))
+
+    async def run() -> None:
+        agent = AgentService(resolved)
+        try:
+            result = await agent.run_now(task)
+            typer.echo(
+                json.dumps(
+                    {
+                        "task_id": result.task_id,
+                        "status": result.status.value,
+                        "thread_id": result.thread_id,
+                        "turn_id": result.turn_id,
+                    },
+                    ensure_ascii=False,
+                )
+            )
+        finally:
+            await agent.shutdown()
+
+    anyio.run(run)
+
+
+@app.command()
+def status(limit: int = 20) -> None:
+    resolved = load_config()
+    store = StateStore(resolved.db_path)
+    typer.echo(
+        json.dumps(
+            {
+                "contexts": [
+                    {
+                        "context_key": context.context_key,
+                        "thread_id": context.thread_id,
+                        "session_worktree": str(context.session_worktree) if context.session_worktree else None,
+                        "workspace_key": context.workspace_key,
+                        "revision": context.revision,
+                    }
+                    for context in store.list_contexts()
+                ],
+                "tasks": [task.model_dump(mode="json") for task in store.recent_tasks(limit)],
+            },
+            indent=2,
+            ensure_ascii=False,
+        )
+    )
+
+
+def _task_from_json(data: dict[str, Any]) -> AgentTask:
+    return AgentTask.model_validate(data)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()