nexus-coding-agent 0.1.0__tar.gz

nexus_coding_agent-0.1.0/.gitattributes

@@ -0,0 +1,7 @@
+# 这样仓库里这些源码和文档会统一保存成 LF，Windows、Linux、Codex 之间协作会更稳定。
+* text=auto
+*.py text eol=lf
+*.md text eol=lf
+*.toml text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf

nexus_coding_agent-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,90 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: pgvector/pgvector:pg16-trixie
+        env:
+          POSTGRES_DB: nexus
+          POSTGRES_USER: nexus
+          POSTGRES_PASSWORD: nexus
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U nexus -d nexus"
+          --health-interval 2s
+          --health-timeout 5s
+          --health-retries 15
+
+    env:
+      NEXUS_DATABASE_URL: postgresql+asyncpg://nexus:nexus@localhost:5432/nexus
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+
+      - name: Bind gates to exact commit
+        shell: bash
+        run: |
+          expected="${{ github.event.pull_request.head.sha || github.sha }}"
+          actual="$(git rev-parse HEAD)"
+          test "$actual" = "$expected"
+          echo "Coverage commit: $actual"
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Install locked dependencies
+        run: uv sync --frozen --dev
+
+      - name: Ruff
+        run: uv run ruff check .
+
+      - name: Mypy
+        run: uv run mypy src tests
+
+      - name: Pytest with canonical coverage collection
+        run: >-
+          uv run pytest
+          --cov=nexus
+          --cov-report=term-missing
+          --cov-report=json:coverage.json
+
+      - name: Overall coverage gate
+        run: uv run coverage report --precision=2 --fail-under=70
+
+      - name: Runtime coverage gate
+        run: >-
+          uv run coverage report
+          --include="src/nexus/application/runtime.py"
+          --precision=2
+          --fail-under=80
+
+      - name: Permission and security coverage gate
+        run: >-
+          uv run coverage report
+          --include="src/nexus/security/*"
+          --precision=2
+          --fail-under=80
+
+      - name: Validation coverage gate
+        run: >-
+          uv run coverage report
+          --include="src/nexus/application/validation.py"
+          --precision=2
+          --fail-under=80

nexus_coding_agent-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,66 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: "3.12"
+
+      - name: Verify release tag matches package version
+        shell: bash
+        run: |
+          package_version="$(python - <<'PY'
+          import tomllib
+          with open('pyproject.toml', 'rb') as fh:
+              print(tomllib.load(fh)['project']['version'])
+          PY
+          )"
+          release_version="${GITHUB_REF_NAME#v}"
+          test "$package_version" = "$release_version"
+          echo "Publishing version $package_version"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish distribution to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/nexus-coding-agent
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

nexus_coding_agent-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+.env
+.nexus/config.toml
+.venv/
+.uv-cache/
+.tmp-docker-config/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.pytest-tmp/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.json
+htmlcov/
+dist/
+build/
+*.egg-info/

nexus_coding_agent-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

nexus_coding_agent-0.1.0/AGENTS.md

@@ -0,0 +1,110 @@
+# AGENTS.md
+
+## Project
+
+This repository contains **Nexus**, a transparent and extensible coding-agent runtime.
+
+The authoritative product and engineering specification is:
+
+`docs/Nexus_V1_Product_Requirements_and_10-Day_Engineering_Specification_v1.1.1_中文.md`
+
+That specification is the frozen implementation baseline for Nexus V1.
+
+## Authority and Scope
+
+1. Treat the Nexus V1.1.1 specification as the authoritative product and architecture contract.
+2. Implement only the currently assigned Day Specification.
+3. Future Day sections are architecture context only and MUST NOT be implemented early.
+4. Do not silently reinterpret, weaken, redesign, or replace frozen decisions.
+5. If the current task conflicts with the frozen specification, STOP implementation and report:
+   - the conflict,
+   - supporting evidence,
+   - implementation impact,
+   - available options.
+6. Await an approved specification or ADR change before proceeding with any change that crosses the Codex decision boundary.
+
+## Frozen Architecture Constraints
+
+Preserve these principles unless the specification is explicitly amended:
+
+- CLI-first, runtime-independent architecture.
+- Async-first core.
+- LangGraph implementation behind Nexus-owned runtime/domain boundaries.
+- Domain must not depend on LangGraph, SQLAlchemy, MCP, Typer, or concrete model vendors.
+- All side effects must pass through Tool Runtime, policy, approval, and sandbox boundaries as applicable.
+- Context must be selected and bounded; never dump the entire repository or full session history into the model.
+- Code modifications require validation.
+- Runtime behavior must be observable through safe structured events without exposing private chain-of-thought.
+- Concrete dependency assembly belongs only in `src/nexus/infrastructure/bootstrap/`.
+- Provider boundaries must use dependency inversion where required by the specification.
+- V1 tool execution is sequential by default.
+- Existing files should normally be modified with `apply_patch`; `write_file` is for new files.
+- Do not implement prohibited Git operations such as `git commit`, `git push`, or `git reset --hard` as Nexus Agent capabilities.
+
+## Codex Implementation Decision Boundary
+
+Codex MAY decide:
+
+- private helper structure,
+- local variable names,
+- small refactors within the current module,
+- test fixture details,
+- error wording,
+- standard-library usage,
+- clearly equivalent low-level implementation details.
+
+Codex MUST NOT independently change or invent:
+
+- domain models,
+- graph node responsibilities or edges,
+- public/provider/tool contracts,
+- database schema,
+- security policy or risk classification,
+- retrieval/chunking/ranking algorithms,
+- evaluation success criteria,
+- CLI public contract,
+- persistence ownership boundaries,
+- major/new dependencies,
+- future features.
+
+For any decision in the MUST NOT category:
+
+`STOP → Report conflict → Explain options → Await approved specification change`
+
+## Daily Workflow
+
+For each Day task:
+
+1. Read the relevant global constraints in the authoritative specification.
+2. Read the complete 18-item specification for the assigned Day.
+3. Inspect the current repository state before editing.
+4. Produce a concise implementation plan mapped to the current Day.
+5. Implement only the current Day scope.
+6. Do not perform unrelated refactors or future-scope work.
+7. Run all checks required by the current Day specification.
+8. Report:
+   - changed files,
+   - tests/lint/type-check results,
+   - acceptance-criteria mapping,
+   - unresolved issues,
+   - intentionally deferred future-Day work.
+
+## Quality Gates
+
+Before a Day is considered complete, preserve the project governance defined in the specification:
+
+1. Acceptance Criteria
+2. Code & Architecture Review
+3. Tests / CI / Evaluation as applicable
+4. Product Owner Knowledge Review
+
+A Day is not complete merely because the code runs.
+
+## General Safety
+
+- Never log or commit secrets.
+- Never bypass workspace containment, approval policy, command policy, or sandbox restrictions.
+- Do not introduce raw `subprocess` usage in agent orchestration.
+- Do not scatter raw SQL through services or agent nodes.
+- Do not expose private chain-of-thought in events, logs, traces, or user output.
+- Prefer minimal, specification-aligned changes over speculative abstraction.

nexus_coding_agent-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: nexus-coding-agent
+Version: 0.1.0
+Summary: A transparent and extensible coding-agent runtime.
+Project-URL: Homepage, https://github.com/K529529/Nexus
+Project-URL: Repository, https://github.com/K529529/Nexus
+Project-URL: Issues, https://github.com/K529529/Nexus/issues
+Author: Archer
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: alembic<2,>=1.16
+Requires-Dist: asyncpg<1,>=0.30
+Requires-Dist: langchain-openai<2,>=1.0
+Requires-Dist: langgraph-checkpoint-postgres<4,>=3.1
+Requires-Dist: langgraph<2,>=1.0
+Requires-Dist: langsmith<0.12,>=0.11.1
+Requires-Dist: mcp<3,>=2
+Requires-Dist: pathspec<2,>=0.12
+Requires-Dist: pgvector<1,>=0.4
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: sqlalchemy[asyncio]<3,>=2.0
+Requires-Dist: typer<1,>=0.16
+Description-Content-Type: text/markdown
+
+# Nexus
+
+English | [简体中文](README.zh-CN.md)
+
+Nexus is a transparent, async-first coding-agent runtime with a CLI adapter, durable PostgreSQL
+sessions/checkpoints, policy-governed native and MCP tools, bounded repository context, validated
+code editing, repository/user Skills, safe structured telemetry, and a deterministic evaluation
+harness. LangGraph and concrete providers remain behind Nexus-owned boundaries.
+
+This branch prepares the `Nexus v0.1.0 Release Candidate`. It does not create the final Git tag;
+tagging remains a Product Owner action after review and merge to `main`.
+
+## Requirements
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/)
+- Git
+- PostgreSQL 16 with the `vector` extension
+- an OpenAI-compatible model deployment for live coding tasks
+- Docker with Compose when using the included development database
+
+## Install
+
+```powershell
+uv sync --locked --dev
+docker compose up -d postgres
+uv run alembic upgrade head
+uv run nexus --help
+```
+
+The Compose development URL is
+`postgresql+asyncpg://nexus:nexus@localhost:5432/nexus`. Override it with
+`NEXUS_DATABASE_URL` when necessary. Credentials in `compose.yaml` are development-only.
+
+Configure secrets through environment variables, never CLI arguments or repository TOML:
+
+```powershell
+$env:NEXUS_MODEL_NAME = "your-model"
+$env:NEXUS_MODEL_API_KEY = "your-api-key"
+$env:NEXUS_MODEL_BASE_URL = "https://your-compatible-endpoint.example/v1" # optional
+```
+
+Non-secret repository configuration can be stored at `.nexus/config.toml`:
+
+```toml
+[model]
+provider = "openai_compatible"
+name = "your-model"
+base_url = "https://your-compatible-endpoint.example/v1"
+
+[database]
+url = "postgresql+asyncpg://nexus:nexus@localhost:5432/nexus"
+
+[runtime]
+approval_mode = "approval"
+max_steps = 20
+max_repair_attempts = 3
+max_replans = 2
+```
+
+Configuration precedence is resolved per field:
+
+```text
+CLI > repository TOML > user ~/.nexus/config.toml > NEXUS_* environment > defaults
+```
+
+MCP process configuration and LangSmith configuration are trusted only from user-level TOML or
+approved environment variables; API keys are environment-only.
+
+## Quick start
+
+Run Nexus from the repository that it is allowed to inspect and change:
+
+```powershell
+uv run nexus chat "Find the smallest cause of the failing test and fix it."
+```
+
+Nexus explores bounded context, proposes a Plan, asks for approval when required, performs
+policy-governed sequential Tool calls, validates changes, and renders a final result or a truthful
+failure/limit stop. Useful commands are:
+
+```powershell
+uv run nexus --help
+uv run nexus chat --help
+uv run nexus index --help
+uv run nexus session list --help
+uv run nexus session resume --help
+uv run nexus eval --help
+```
+
+## Release documentation
+
+The [Nexus V1 release guide](docs/nexus-v1-release-guide.md) is the authoritative Day 10 guide. It
+contains the architecture overview and diagram, complete CLI/configuration reference, validation,
+observability and evaluation procedures, canonical FastAPI walkthrough, known limitations,
+post-V1 roadmap, release checklist, and `v0.1.0` release notes.
+
+Focused subsystem guides remain available for [MCP](docs/mcp-guide.md),
+[Skills](docs/skill-guide.md), [observability](docs/day8-observability-guide.md), and the
+[architecture decisions](docs/adr/).
+
+## Development and release gates
+
+```powershell
+uv run ruff check .
+uv run mypy src tests
+uv run pytest --cov=nexus --cov-report=term-missing --cov-report=json:coverage.json
+uv run coverage report --precision=2 --fail-under=70
+uv run coverage report --include="src/nexus/application/runtime.py" --precision=2 --fail-under=80
+uv run coverage report --include="src/nexus/security/*" --precision=2 --fail-under=80
+uv run coverage report --include="src/nexus/application/validation.py" --precision=2 --fail-under=80
+uv lock --check
+uv build
+```
+
+Live provider, LangSmith, evaluation, fresh-install, fixture, and real-repository results are kept
+separate from deterministic regression evidence in the
+[Day 10 release evidence](docs/day10-release-evidence.md).

nexus_coding_agent-0.1.0/README.md

@@ -0,0 +1,118 @@
+# Nexus
+
+English | [简体中文](README.zh-CN.md)
+
+Nexus is a transparent, async-first coding-agent runtime with a CLI adapter, durable PostgreSQL
+sessions/checkpoints, policy-governed native and MCP tools, bounded repository context, validated
+code editing, repository/user Skills, safe structured telemetry, and a deterministic evaluation
+harness. LangGraph and concrete providers remain behind Nexus-owned boundaries.
+
+This branch prepares the `Nexus v0.1.0 Release Candidate`. It does not create the final Git tag;
+tagging remains a Product Owner action after review and merge to `main`.
+
+## Requirements
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/)
+- Git
+- PostgreSQL 16 with the `vector` extension
+- an OpenAI-compatible model deployment for live coding tasks
+- Docker with Compose when using the included development database
+
+## Install
+
+```powershell
+uv sync --locked --dev
+docker compose up -d postgres
+uv run alembic upgrade head
+uv run nexus --help
+```
+
+The Compose development URL is
+`postgresql+asyncpg://nexus:nexus@localhost:5432/nexus`. Override it with
+`NEXUS_DATABASE_URL` when necessary. Credentials in `compose.yaml` are development-only.
+
+Configure secrets through environment variables, never CLI arguments or repository TOML:
+
+```powershell
+$env:NEXUS_MODEL_NAME = "your-model"
+$env:NEXUS_MODEL_API_KEY = "your-api-key"
+$env:NEXUS_MODEL_BASE_URL = "https://your-compatible-endpoint.example/v1" # optional
+```
+
+Non-secret repository configuration can be stored at `.nexus/config.toml`:
+
+```toml
+[model]
+provider = "openai_compatible"
+name = "your-model"
+base_url = "https://your-compatible-endpoint.example/v1"
+
+[database]
+url = "postgresql+asyncpg://nexus:nexus@localhost:5432/nexus"
+
+[runtime]
+approval_mode = "approval"
+max_steps = 20
+max_repair_attempts = 3
+max_replans = 2
+```
+
+Configuration precedence is resolved per field:
+
+```text
+CLI > repository TOML > user ~/.nexus/config.toml > NEXUS_* environment > defaults
+```
+
+MCP process configuration and LangSmith configuration are trusted only from user-level TOML or
+approved environment variables; API keys are environment-only.
+
+## Quick start
+
+Run Nexus from the repository that it is allowed to inspect and change:
+
+```powershell
+uv run nexus chat "Find the smallest cause of the failing test and fix it."
+```
+
+Nexus explores bounded context, proposes a Plan, asks for approval when required, performs
+policy-governed sequential Tool calls, validates changes, and renders a final result or a truthful
+failure/limit stop. Useful commands are:
+
+```powershell
+uv run nexus --help
+uv run nexus chat --help
+uv run nexus index --help
+uv run nexus session list --help
+uv run nexus session resume --help
+uv run nexus eval --help
+```
+
+## Release documentation
+
+The [Nexus V1 release guide](docs/nexus-v1-release-guide.md) is the authoritative Day 10 guide. It
+contains the architecture overview and diagram, complete CLI/configuration reference, validation,
+observability and evaluation procedures, canonical FastAPI walkthrough, known limitations,
+post-V1 roadmap, release checklist, and `v0.1.0` release notes.
+
+Focused subsystem guides remain available for [MCP](docs/mcp-guide.md),
+[Skills](docs/skill-guide.md), [observability](docs/day8-observability-guide.md), and the
+[architecture decisions](docs/adr/).
+
+## Development and release gates
+
+```powershell
+uv run ruff check .
+uv run mypy src tests
+uv run pytest --cov=nexus --cov-report=term-missing --cov-report=json:coverage.json
+uv run coverage report --precision=2 --fail-under=70
+uv run coverage report --include="src/nexus/application/runtime.py" --precision=2 --fail-under=80
+uv run coverage report --include="src/nexus/security/*" --precision=2 --fail-under=80
+uv run coverage report --include="src/nexus/application/validation.py" --precision=2 --fail-under=80
+uv lock --check
+uv build
+```
+
+Live provider, LangSmith, evaluation, fresh-install, fixture, and real-repository results are kept
+separate from deterministic regression evidence in the
+[Day 10 release evidence](docs/day10-release-evidence.md).

nexus_coding_agent-0.1.0/README.zh-CN.md

@@ -0,0 +1,114 @@
+# Nexus
+
+[English](README.md) | 简体中文
+
+Nexus 是一个透明、async-first 的 coding-agent runtime，提供 CLI adapter、持久化 PostgreSQL
+session/checkpoint、受策略治理的原生与 MCP 工具、有界仓库上下文、经过 Validation 的代码编辑、
+仓库级/用户级 Skills、安全的结构化 telemetry，以及确定性的 Evaluation harness。LangGraph
+和具体 provider 均封装在 Nexus 自有边界之后。
+
+此分支用于准备 `Nexus v0.1.0 Release Candidate`，不会创建最终 Git tag；tag 操作仍由
+Product Owner 在审查并 merge 到 `main` 后执行。
+
+## 环境要求
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/)
+- Git
+- 安装了 `vector` 扩展的 PostgreSQL 16
+- 用于真实 coding task 的 OpenAI-compatible model deployment
+- 使用仓库内置开发数据库时，需要 Docker 和 Compose
+
+## 安装
+
+```powershell
+uv sync --locked --dev
+docker compose up -d postgres
+uv run alembic upgrade head
+uv run nexus --help
+```
+
+Compose 开发环境的 URL 为
+`postgresql+asyncpg://nexus:nexus@localhost:5432/nexus`。必要时可通过
+`NEXUS_DATABASE_URL` 覆盖。`compose.yaml` 中的凭据仅供开发使用。
+
+请通过环境变量配置 secret，切勿通过 CLI 参数或仓库 TOML 配置：
+
+```powershell
+$env:NEXUS_MODEL_NAME = "your-model"
+$env:NEXUS_MODEL_API_KEY = "your-api-key"
+$env:NEXUS_MODEL_BASE_URL = "https://your-compatible-endpoint.example/v1" # optional
+```
+
+非敏感的仓库配置可保存在 `.nexus/config.toml`：
+
+```toml
+[model]
+provider = "openai_compatible"
+name = "your-model"
+base_url = "https://your-compatible-endpoint.example/v1"
+
+[database]
+url = "postgresql+asyncpg://nexus:nexus@localhost:5432/nexus"
+
+[runtime]
+approval_mode = "approval"
+max_steps = 20
+max_repair_attempts = 3
+max_replans = 2
+```
+
+配置优先级按字段解析：
+
+```text
+CLI > repository TOML > user ~/.nexus/config.toml > NEXUS_* environment > defaults
+```
+
+MCP 进程配置和 LangSmith 配置仅信任用户级 TOML 或已批准的环境变量；API key 只能通过环境变量提供。
+
+## 快速开始
+
+请在允许 Nexus 检查和修改的仓库中运行：
+
+```powershell
+uv run nexus chat "Find the smallest cause of the failing test and fix it."
+```
+
+Nexus 会探索有界上下文、提出 Plan、在需要时请求 approval、依次执行受策略治理的 Tool call、
+对变更执行 Validation，并呈现最终结果或如实报告失败/达到限制。常用命令如下：
+
+```powershell
+uv run nexus --help
+uv run nexus chat --help
+uv run nexus index --help
+uv run nexus session list --help
+uv run nexus session resume --help
+uv run nexus eval --help
+```
+
+## 发布文档
+
+[Nexus V1 发布指南](docs/nexus-v1-release-guide.md)是权威的 Day 10 指南，其中包含架构概览与
+架构图、完整的 CLI/配置参考、Validation、Observability 与 Evaluation 流程、标准 FastAPI
+walkthrough、已知限制、V1 后续 roadmap、release checklist，以及 `v0.1.0` release notes。
+
+此外还提供面向具体子系统的 [MCP](docs/mcp-guide.md)、[Skills](docs/skill-guide.md)、
+[Observability](docs/day8-observability-guide.md) 和[架构决策](docs/adr/)指南。
+
+## 开发与发布门禁
+
+```powershell
+uv run ruff check .
+uv run mypy src tests
+uv run pytest --cov=nexus --cov-report=term-missing --cov-report=json:coverage.json
+uv run coverage report --precision=2 --fail-under=70
+uv run coverage report --include="src/nexus/application/runtime.py" --precision=2 --fail-under=80
+uv run coverage report --include="src/nexus/security/*" --precision=2 --fail-under=80
+uv run coverage report --include="src/nexus/application/validation.py" --precision=2 --fail-under=80
+uv lock --check
+uv build
+```
+
+真实 provider、LangSmith、Evaluation、fresh install、fixture 和真实仓库的结果，与确定性
+regression evidence 分开记录在
+[Day 10 发布证据](docs/day10-release-evidence.md)中。