feat: provisioned hermes agent orchestration

Author: jahilldev

.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: api
+    env:
+      # Tests/build use an ephemeral SQLite file — no external services needed.
+      DATABASE_URL: file:./ci.db
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: api/package-lock.json
+
+      - run: npm ci
+
+      - name: Generate Prisma client
+        run: npx prisma generate
+
+      - name: Apply migrations
+        run: npx prisma migrate deploy
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Build
+        run: npm run build
+
+      - name: Unit tests
+        run: npm test
+
+      - name: E2E tests
+        run: npm run test:e2e

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "prisma.pinToPrisma6": true
+}

README.md

@@ -0,0 +1,154 @@
+# Hermes Agent Orchestration Service ("Olympian")
+
+An **AI dark factory**: label a GitHub issue and the service drives the
+[Hermes Agent](https://github.com/nousresearch/hermes-agent) CLI through the entire
+delivery lifecycle — planning, implementation, self-review, and a draft PR — with a
+human only ever approving the plan and the final PR. No human writes code.
+
+```
+issue labeled ──▶ PLAN ──▶ (human approves plan) ──▶ IMPLEMENT ──▶ SELF-REVIEW ⇄ REVISE
+                    ▲             │                                        │
+                    └─ feedback ──┘                          (confidence ≥ threshold)
+                                                                          │
+                                                                          ▼
+                              (human approves PR) ◀── AWAIT PR REVIEW ◀── OPEN DRAFT PR
+                                      │                     ▲                 
+                                      ▼                     └── changes requested ──▶ IMPLEMENT
+                                    DONE
+```
+
+## How it works
+
+1. **Trigger.** An issue is labeled with the trigger label (default `hermes`). A `Job` is created.
+2. **Plan.** Hermes reads the issue (in a clone of the repo) and posts an implementation
+   plan as an issue comment.
+3. **Plan approval loop.** A maintainer replies `/hermes approve` to proceed, or leaves a
+   comment with corrections — each comment re-plans until approved (capped by `MAX_PLAN_REVISIONS`).
+4. **Implement.** Hermes writes the code on a branch (`hermes/issue-<n>`). An optional
+   `VERIFY_COMMAND` (tests/build) gates the work, iterating up to `MAX_IMPLEMENTATION_ITERATIONS`.
+5. **Self-review.** Hermes reviews its own diff and returns a JSON verdict
+   `{confidence, verdict, issues[]}`. Below `REVIEW_CONFIDENCE_THRESHOLD` it revises and
+   re-reviews, up to `MAX_REVIEW_PASSES`.
+6. **Draft PR.** The branch is pushed and a **draft** PR is opened, linking the issue.
+7. **PR approval loop.** Approve the PR review → the job is `DONE`. Request changes → the
+   implementation loop runs again and pushes an update.
+
+The orchestrator owns git; Hermes only edits files. **Prisma (SQLite) is the source of
+truth** for every job's state, plan revisions, agent runs, reviews, and the work queue —
+each Hermes prompt is rebuilt deterministically from the database.
+
+## Tech stack
+
+- **NestJS** (ESM, `"type": "module"`, NodeNext) — modular service.
+- **Prisma + SQLite** — file-based; no DB server to provision.
+- **DB-backed queue** — a polling worker claims tasks with an atomic `UPDATE ... RETURNING`
+  (SQLite-safe), with exponential backoff/retry and per-job concurrency isolation.
+- **GitHub App** — webhooks, scoped installation tokens, comments, draft PRs, reviews.
+- **Hermes Agent CLI** — invoked headless: `hermes -z --yolo --source tool --max-turns N`.
+
+Module layout (one service per module): `config`, `prisma`, `metrics`, `health`,
+`github-app`, `github-api`, `webhook`, `job`, `queue`, `worker`, `agent`, `workspace`,
+`review`, `orchestrator`.
+
+## Quick start (local)
+
+```bash
+cd api
+cp .env.example .env            # fill in GitHub App + Hermes values
+npm install
+npx prisma migrate dev          # creates prisma/dev.db
+npm run start:dev
+```
+
+Probe it:
+
+```bash
+curl localhost:3000/health        # liveness
+curl localhost:3000/health/ready  # readiness (DB)
+curl localhost:3000/metrics       # Prometheus metrics
+```
+
+## Required external setup
+
+These can't be scripted for you and gate the live run (not the build or tests):
+
+### 1. Register a GitHub App
+- **Permissions:** Issues *Read & write*, Pull requests *Read & write*, Contents *Read &
+  write*, Metadata *Read-only*.
+- **Subscribe to events:** Issues, Issue comment, Pull request review, Installation.
+- **Webhook URL:** `https://<your-host>/webhooks/github` and a **webhook secret**.
+- Generate a **private key** (PEM). Install the App on the target repos.
+- Put the values in `.env`: `GITHUB_APP_ID`, `GITHUB_WEBHOOK_SECRET`, and either
+  `GITHUB_APP_PRIVATE_KEY` (inline, `\n`-escaped) or `GITHUB_APP_PRIVATE_KEY_PATH`.
+
+For local dev, tunnel webhooks with [smee.io](https://smee.io) or ngrok to
+`localhost:3000/webhooks/github`.
+
+### 2. Provision Hermes
+- Install the `hermes` CLI (set `HERMES_BIN`) **or** build the sandbox image
+  (`docker build -f Dockerfile.agent -t hermes-agent .`) and set `SANDBOX_MODE=docker`.
+- Configure provider credentials/model under `HERMES_HOME` (`~/.hermes`), or set
+  `HERMES_MODEL`/`HERMES_PROVIDER`.
+
+## Using it
+
+1. Label an issue `hermes` (or your `TRIGGER_LABEL`).
+2. Hermes posts a plan. Reply with comments to iterate, or `/hermes approve` to build.
+3. A draft PR appears. **Approve** the PR review to finish, or **request changes** to loop.
+
+Issue-comment commands (maintainers only — write access required):
+- `/hermes approve` — approve the plan and start implementation
+- `/hermes cancel` — stop the job
+- `/hermes status` — report current state
+
+## Sandboxing
+
+- `SANDBOX_MODE=none` (default) runs `hermes` as a subprocess in the job's worktree.
+- `SANDBOX_MODE=docker` runs each agent invocation inside `DOCKER_AGENT_IMAGE`, mounting
+  **only** that job's directory and the read-only Hermes config. Each job lives in its own
+  directory keyed by job id, so raising `WORKER_CONCURRENCY` runs N isolated jobs in parallel.
+
+## Configuration
+
+All config is validated at boot (see `src/config/config.model.ts`). Full reference and
+defaults live in [`api/.env.example`](api/.env.example). Key knobs:
+
+| Variable | Purpose |
+| --- | --- |
+| `TRIGGER_LABEL` | Label that starts a job (default `hermes`). |
+| `REVIEW_CONFIDENCE_THRESHOLD` | Min self-review confidence to open a PR (default 85). |
+| `MAX_PLAN_REVISIONS` / `MAX_IMPLEMENTATION_ITERATIONS` / `MAX_REVIEW_PASSES` | Loop caps. |
+| `WORKER_CONCURRENCY` | Parallel jobs (default 2). |
+| `VERIFY_COMMAND` | Optional tests/build command used as an acceptance gate. |
+| `SANDBOX_MODE` | `none` or `docker`. |
+| `HERMES_BIN` / `HERMES_HOME` / `HERMES_MODEL` / `HERMES_MAX_TURNS` | Hermes invocation. |
+
+## Docker
+
+```bash
+cd api && cp .env.example .env   # fill in values
+docker compose up --build        # from repo root: builds the api image
+```
+
+SQLite lives on a named volume; there is no separate database container.
+
+## Operations
+
+- **Health:** `/health` (liveness), `/health/ready` (DB).
+- **Metrics:** `/metrics` — job counts by state, queue depth, agent run durations, webhook
+  counts, last review confidence.
+- **Audit trail:** every state transition (`JobStateTransition`) and every Hermes
+  invocation (`AgentRun`) is persisted; inspect with `npx prisma studio`.
+- **Retries:** failed tasks back off exponentially up to `QUEUE_MAX_ATTEMPTS`; exhausted
+  jobs are failed and a comment is posted. Orphaned tasks are reclaimed after `QUEUE_LOCK_TTL_MS`.
+
+## Tests
+
+```bash
+cd api
+npm test        # unit
+npm run test:e2e  # full webhook→plan→approve→implement→review→PR loop with a stub Hermes
+```
+
+The e2e suite stubs the Hermes agent and fakes the GitHub API, so the entire pipeline runs
+in CI without real LLM or GitHub credentials.

api/.dockerignore

@@ -0,0 +1,11 @@
+node_modules
+dist
+coverage
+.workspaces
+*.log
+.env
+.env.*
+!.env.example
+prisma/dev.db*
+*.pem
+.git

api/.env.example

@@ -0,0 +1,65 @@
+# ── Server ────────────────────────────────────────────────────────────────
+PORT=3000
+NODE_ENV=development
+LOG_LEVEL=info
+
+# ── Database (SQLite, file-based — no server to provision) ──────────────────
+# Path is relative to the prisma/ directory (so this resolves to api/prisma/dev.db).
+DATABASE_URL=file:./dev.db
+
+# ── GitHub App ───────────────────────────────────────────────────────────────
+# From the GitHub App settings page.
+GITHUB_APP_ID=000000
+# The webhook secret you configured on the App.
+GITHUB_WEBHOOK_SECRET=replace-me
+# The App private key (PEM). Either inline (with literal \n) or a file path via GITHUB_APP_PRIVATE_KEY_PATH.
+GITHUB_APP_PRIVATE_KEY=
+GITHUB_APP_PRIVATE_KEY_PATH=./github-app.pem
+
+# ── Hermes Agent CLI ─────────────────────────────────────────────────────────
+HERMES_BIN=hermes
+# HERMES_HOME holds Hermes config + provider credentials (~/.hermes by default).
+HERMES_HOME=
+# Model/provider overrides (optional). Falls back to Hermes config when unset.
+HERMES_MODEL=
+HERMES_PROVIDER=
+# Max tool-calling iterations per Hermes turn.
+HERMES_MAX_TURNS=90
+# Hard wall-clock timeout (ms) for a single Hermes invocation.
+HERMES_TIMEOUT_MS=1800000
+
+# ── Orchestration policy ─────────────────────────────────────────────────────
+# Only issues with this label are picked up.
+TRIGGER_LABEL=hermes
+# Review confidence (0-100) required before opening a PR.
+REVIEW_CONFIDENCE_THRESHOLD=85
+MAX_PLAN_REVISIONS=10
+MAX_IMPLEMENTATION_ITERATIONS=5
+MAX_REVIEW_PASSES=5
+# Slash-command prefix used in issue comments (e.g. "/hermes approve").
+COMMAND_PREFIX=/hermes
+
+# ── Queue / worker ───────────────────────────────────────────────────────────
+WORKER_ENABLED=true
+WORKER_CONCURRENCY=2
+# How often the worker polls for due tasks (ms).
+WORKER_POLL_INTERVAL_MS=2000
+QUEUE_MAX_ATTEMPTS=3
+# Backoff base (ms); delay = base * 2^(attempt-1).
+QUEUE_BACKOFF_BASE_MS=15000
+# A task RUNNING longer than this (ms) is considered orphaned and reclaimable.
+QUEUE_LOCK_TTL_MS=3600000
+
+# ── Workspace / git ──────────────────────────────────────────────────────────
+WORKSPACE_ROOT=./.workspaces
+GIT_AUTHOR_NAME=Hermes Agent
+GIT_AUTHOR_EMAIL=hermes@users.noreply.github.com
+# Branch name template; {issue} is replaced with the issue number.
+BRANCH_PREFIX=hermes/issue-
+
+# ── Sandbox ──────────────────────────────────────────────────────────────────
+# none = run hermes as a local subprocess; docker = run hermes inside a container.
+SANDBOX_MODE=none
+DOCKER_AGENT_IMAGE=hermes-agent:latest
+# Optional: command the agent should run to verify acceptance criteria (tests/build).
+VERIFY_COMMAND=

api/.gitignore

@@ -0,0 +1,31 @@
+# dependencies
+node_modules/
+
+# build
+dist/
+*.tsbuildinfo
+
+# test
+coverage/
+
+# env & secrets
+.env
+.env.*
+!.env.example
+*.pem
+
+# logs
+*.log
+logs/
+
+# runtime
+.DS_Store
+
+# agent workspaces (cloned repos / worktrees)
+.workspaces/
+
+# sqlite database files (migrations are tracked; the .db files are not)
+prisma/*.db
+prisma/*.db-journal
+prisma/*.db-wal
+prisma/*.db-shm

api/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "semi": true
+}

api/Dockerfile

@@ -0,0 +1,30 @@
+# ── Build stage ──────────────────────────────────────────────────────────────
+FROM node:20-alpine AS builder
+WORKDIR /app
+RUN apk add --no-cache openssl
+COPY package*.json ./
+RUN npm ci
+COPY prisma ./prisma
+RUN npx prisma generate
+COPY tsconfig*.json nest-cli.json ./
+COPY src ./src
+RUN npm run build
+
+# ── Runtime stage ────────────────────────────────────────────────────────────
+FROM node:20-alpine AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+# git: required by the workspace module (clone/commit/push).
+# openssl + ca-certificates: Prisma engine + HTTPS git remotes.
+# NOTE: with SANDBOX_MODE=none the `hermes` binary must also be on PATH in this
+# image; with SANDBOX_MODE=docker the agent runs in DOCKER_AGENT_IMAGE instead
+# (mount the Docker socket and set the image).
+RUN apk add --no-cache git openssh-client ca-certificates openssl
+COPY package*.json ./
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/prisma ./prisma
+COPY docker-entrypoint.sh ./
+RUN chmod +x docker-entrypoint.sh
+EXPOSE 3000
+ENTRYPOINT ["./docker-entrypoint.sh"]

api/Dockerfile.agent

@@ -0,0 +1,30 @@
+# Sandbox image for running the Hermes Agent (used when SANDBOX_MODE=docker).
+# The orchestrator runs:  docker run --rm -i -v <job-dir>:/workspace -w /workspace \
+#     [-v <HERMES_HOME>:/root/.hermes:ro] <DOCKER_AGENT_IMAGE> hermes -z --yolo ...
+#
+# This image must contain the `hermes` executable plus a toolchain rich enough for
+# the repos you target (git, node, python, build tools, etc.). Add languages/SDKs
+# your repositories need.
+
+FROM python:3.12-slim
+
+# Base toolchain. Extend per your repos' needs.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      git curl ca-certificates build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Node 20 (many target repos need it; harmless otherwise).
+RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y --no-install-recommends nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# ── Install Hermes Agent ──────────────────────────────────────────────────────
+# IMPORTANT: confirm the install command against the current Hermes docs
+# (https://github.com/nousresearch/hermes-agent). The line below uses the Python
+# package install path; switch to the official installer script if that's preferred.
+RUN pip install --no-cache-dir hermes-agent || \
+    echo "WARNING: adjust this line to the current Hermes install method"
+
+# Provider credentials/config are mounted at runtime via HERMES_HOME -> /root/.hermes.
+WORKDIR /workspace
+ENTRYPOINT []

api/docker-entrypoint.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+set -e
+
+# Apply any pending migrations against the configured DATABASE_URL before boot.
+npx prisma migrate deploy
+
+exec node --enable-source-maps dist/main.js