nexor-agora 0.1.0__tar.gz

nexor_agora-0.1.0/.env.example

@@ -0,0 +1,27 @@
+# Copy to .env and edit. Only the hub host needs these.
+
+# Public URL of the hub (used in notification deep links).
+NEXOR_AGORA_PUBLIC_URL=http://localhost:8400
+NEXOR_AGORA_PORT=8400
+
+# Database password for the dedicated nexor_agora Postgres role.
+NEXOR_AGORA_DB_PASSWORD=change-me
+
+# LAN trust: true lets anyone register. Set false + an admin key to gate it.
+NEXOR_AGORA_OPEN_REGISTRATION=true
+NEXOR_AGORA_ADMIN_KEY=
+# Reject any message whose body looks like it contains a secret/credential.
+NEXOR_AGORA_BLOCK_SECRETS=true
+
+# --- Notifications (optional, outbound only) ------------------------------
+# Telegram bot token (from @BotFather) used to deliver escalations/mentions.
+NEXOR_AGORA_TELEGRAM_BOT_TOKEN=
+# Slack incoming webhook for the shared team channel.
+NEXOR_AGORA_SLACK_WEBHOOK_URL=
+
+# CORS origins for the web UI (comma-separated, or * on a trusted LAN).
+NEXOR_AGORA_CORS_ORIGINS=*
+
+# NOTE: agent-runner settings (MCP isolation, per-conversation budget, turn caps)
+# are NOT hub config — the hub never runs an agent. They belong to the external
+# runner that connects to this hub over its public API.

nexor_agora-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,23 @@
+---
+name: Bug report
+about: Something isn't working as expected
+title: "[bug] "
+labels: bug
+---
+
+**What happened**
+A clear description of the bug.
+
+**To reproduce**
+Steps / commands. Include relevant config (redact secrets).
+
+**Expected behavior**
+
+**Environment**
+- nexor-agora version / commit:
+- How you run it (Docker / pip):
+- Python version:
+- Postgres version:
+
+**Logs**
+Relevant hub / `nexor-agora agent` logs (redact secrets).

nexor_agora-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an idea or improvement
+title: "[feat] "
+labels: enhancement
+---
+
+**Problem / motivation**
+What are you trying to do? What's painful today?
+
+**Proposed solution**
+What would you like to happen?
+
+**Alternatives considered**
+
+**Additional context**
+Notes, mockups, links. Does it affect the privacy/isolation model?

nexor_agora-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,12 @@
+## What & why
+
+<!-- What does this change and why? Link any related issue. -->
+
+## Checklist
+
+- [ ] `ruff check src tests` passes
+- [ ] `pytest` passes
+- [ ] Updated `CHANGELOG.md`
+- [ ] Preserves isolation/privacy invariants (no external reads; outbound-only
+      notifications; agent output still passes the secret backstop)
+- [ ] Docs updated if behavior/config changed

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

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  leak-gate:
+    # Generic OSS: fail if any org-specific identifier leaks in.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Org-leak gate
+        run: bash scripts/check_no_org_leak.sh
+
+  lint-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: nexor_agora
+          POSTGRES_PASSWORD: nexor-agora
+          POSTGRES_DB: nexor_agora
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U nexor_agora -d nexor_agora"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      NEXOR_AGORA_DATABASE_URL: postgresql://nexor_agora:nexor-agora@localhost:5432/nexor_agora
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src tests
+
+      - name: Test
+        run: pytest -q
+
+  docker-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build image
+        run: docker build -t nexor-agora:ci .

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

@@ -0,0 +1,47 @@
+name: Release
+
+# Publishes nexor-agora to PyPI via Trusted Publishing (OIDC) — no API tokens.
+# PyPI mints short-lived credentials from the GitHub OIDC identity.
+# Trigger by pushing a version tag, e.g. `git tag v0.1.0 && git push origin v0.1.0`.
+#
+# One-time PyPI setup (pending publisher, before the first release):
+#   PyPI → project nexor-agora → Publishing → add a GitHub publisher:
+#     owner=nexorhq · repo=nexor-agora · workflow=release.yml · environment=pypi
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Org-leak gate (block publish on any org identifier)
+        run: bash scripts/check_no_org_leak.sh
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Build sdist + wheel
+        run: uv build --out-dir dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

nexor_agora-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.env
+.venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/

nexor_agora-0.1.0/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Changed — hub is now a pure, vendor-neutral coordination plane
+- **Extracted the agent runner.** Removed `autoreply.py` and the `nexor-agora
+  agent` CLI subcommand. Driving an agent (auto-reply, task execution) couples to
+  a specific agent runtime, a license/API key, billing and personal risk
+  appetite — none of which belong in an OSS team hub. That logic now lives in an
+  **external runner** that connects over the public API (reference
+  implementation: `nexor/services/agora-runner`).
+- The hub keeps everything an external runner needs: the `auto_reply` flag,
+  `chat_set_auto_reply`, `chat_wait`, `/tasks/mine`, escalation, and the
+  **server-side** secret backstop + audit trail. No agent-runtime dependency
+  remains. README/SETUP/.env reframed accordingly.
+
+### Plans & tasks (RFC-001)
+- Conversations can optionally **follow a plan** (`conversations.plan_ref`,
+  nullable): free/exploratory by default, bindable to an existing repo plan, or
+  crystallized from the discussion. The hub never reads/writes repos.
+- **Task coordination**: import a Spec-Kit `tasks.md` (or any markdown
+  checklist) deterministically (no LLM); per-step status, atomic self-claim
+  (Postgres row-lock), and lead assignment that **wakes the assignee via an
+  @mention**. Done by a non-lead lands in `review` for lead confirmation (guards
+  against stale "done" state). New `chat_bind_plan`, `chat_promote_plan`,
+  `chat_list_tasks`, `chat_my_tasks`, `chat_claim_task`, `chat_assign_task`,
+  `chat_task_status` MCP tools (+ REST under `/conversations/{id}/tasks`).
+- **Decisions / variations** as a first-class artifact for discoveries that
+  change a plan — `chat_record_decision` / `chat_resolve_decision`. Resolution
+  records a downstream-propagation proposal; the hub never applies it.
+- Design doc: `docs/rfc-001-plans-and-tasks.md`.
+
+### Security & usability (latest)
+- API keys are now stored **hashed** (SHA-256); plaintext shown once at
+  registration, with `POST /me/rotate-key` to rotate. **Breaking** (pre-1.0):
+  existing plaintext keys are invalidated on upgrade.
+- **Lead-only** management: roles, invites, membership and repos require a lead.
+- **Server-side secret backstop** rejects messages that look like credentials
+  (`NEXOR_AGORA_BLOCK_SECRETS`), plus an **audit trail** of agent actions
+  (`GET /conversations/{id}/audit`).
+- Web UI: Markdown/code-block rendering, @mention autocomplete, a profile panel
+  (display name, Telegram/Slack ids, key rotation), and "load earlier" pagination.
+- Message history pagination via `before=`.
+
+### Added
+- Shared conversations where humans and Claude Code agents are participants.
+- Per-user API keys, conversations (1:1 and group channels), messages, inbox,
+  unread tracking, read receipts.
+- `@mention` parsing with forced notifications: mentioned humans are pinged on
+  Slack (and Telegram for escalations); mentioned agents are woken.
+- `chat_wait` blocking long-poll — the reliable way to wake a waiting agent
+  session (plus SSE for the live web UI).
+- Optional `nexor-agora agent` runner: role-aware auto-reply (member vs **lead**),
+  with anti-loop safety (mention-gating, no unsolicited bot-to-bot, turn caps,
+  cooldown, repetition guard) and **per-conversation budget** enforcement.
+- Roles (`lead`/`member`, multiple leads) and **working-repo** metadata.
+- Invite links + `chat_join` so teammates (and their agents) join from a Slack link.
+- Outbound Telegram (escalation DMs) and Slack (channel) notifications.
+- Privacy guardrails: isolated MCP config, strict prompt clause, and an outgoing
+  secret backstop.
+- Zero-build static web UI; single-file stdlib-only MCP server; Docker Compose
+  stack with a dedicated Postgres; `nexor-agora` CLI (`serve` / `agent` / `mcp`).
+
+[Unreleased]: https://github.com/nexorhq/nexor-agora/commits/main

nexor_agora-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,16 @@
+# Code of Conduct
+
+This project adopts the [Contributor Covenant](https://www.contributor-covenant.org/),
+version 2.1.
+
+In short: be respectful, welcoming, and constructive. Harassment and
+discrimination of any kind are not tolerated. Maintainers may remove,
+edit, or reject contributions and comments that violate this code, and may
+ban contributors for inappropriate behavior.
+
+To report unacceptable behavior, contact the maintainer privately (see
+[SECURITY.md](./SECURITY.md) for contact options). Reports will be handled
+confidentially.
+
+The full text is available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct/.

nexor_agora-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing to nexor-agora
+
+Thanks for your interest! nexor-agora is a small, self-hostable project and
+contributions are very welcome.
+
+## Development setup
+
+```bash
+git clone <repo> && cd nexor-agora
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Lint + tests
+ruff check src tests
+pytest
+```
+
+The hub needs a Postgres to run end to end. The quickest way:
+
+```bash
+docker compose up -d db        # just the database
+export NEXOR_AGORA_DATABASE_URL=postgresql://nexor_agora:nexor-agora@localhost:5432/nexor_agora
+nexor-agora serve
+```
+
+## Project layout
+
+```
+src/nexor-agora/
+  app.py          FastAPI app (routes, SSE, static UI)
+  store.py        all SQL / data access
+  db.py           asyncpg pool + idempotent schema
+  models.py       pydantic request/response models
+  notify.py       outbound Telegram/Slack
+  autoreply.py    the `nexor-agora agent` runner (role-aware, budgeted, privacy-guarded)
+  mcp_server.py   the `nexor-agora mcp` stdio server (stdlib-only)
+  cli.py          `nexor-agora serve|agent|mcp`
+  static/index.html   zero-build web UI
+tests/            unit tests (mentions, privacy) + optional integration
+```
+
+## Guidelines
+
+- Keep the **isolation/privacy** invariants: the hub must never read from external
+  systems; notifications are outbound only; agent output passes the secret backstop.
+- Run `ruff check` (config in `pyproject.toml`) and `pytest` before opening a PR.
+- Keep `mcp_server.py` **standard-library only** so it stays copy-paste portable.
+- Small, focused PRs with a clear description. Add a `CHANGELOG.md` entry.
+
+## Reporting bugs / ideas
+
+Open an issue using the templates. For security issues, see [SECURITY.md](./SECURITY.md).

nexor_agora-0.1.0/Dockerfile

@@ -0,0 +1,20 @@
+# nexor-agora hub — FastAPI + static UI. Self-contained (pip, no workspace).
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY pyproject.toml README.md ./
+COPY src/ ./src/
+
+RUN pip install --no-cache-dir .
+
+ENV NEXOR_AGORA_HOST=0.0.0.0 \
+    NEXOR_AGORA_PORT=8400 \
+    NEXOR_AGORA_LOG_LEVEL=INFO
+
+EXPOSE 8400
+
+HEALTHCHECK --interval=15s --timeout=5s --retries=5 --start-period=15s \
+    CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:8400/api/v1/health').status==200 else 1)" || exit 1
+
+CMD ["python", "-m", "nexor_agora", "serve"]

nexor_agora-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Giovanni Consiglio and nexor-agora contributors
+
+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.

nexor_agora-0.1.0/Makefile

@@ -0,0 +1,40 @@
+.PHONY: help install dev lint test serve agent db up down fmt
+
+help:
+	@echo "install   Install the package"
+	@echo "dev       Install with dev extras (ruff, pytest)"
+	@echo "lint      Run ruff"
+	@echo "test      Run pytest"
+	@echo "db        Start only the Postgres container"
+	@echo "serve     Run the hub locally"
+	@echo "up/down   docker compose up -d / down"
+
+install:
+	pip install .
+
+dev:
+	pip install -e ".[dev]"
+
+lint:
+	ruff check src tests
+
+fmt:
+	ruff check --fix src tests
+
+test:
+	pytest
+
+db:
+	docker compose up -d db
+
+serve:
+	nexor-agora serve
+
+agent:
+	nexor-agora agent
+
+up:
+	docker compose up -d
+
+down:
+	docker compose down