From 688ce0c9e118577ad20318e00b5a544c8e4f922d Mon Sep 17 00:00:00 2001 From: fschrhunt <264049687+fschrhunt@users.noreply.github.com> Date: Tue, 28 Apr 2026 15:39:23 -0500 Subject: [PATCH] docs(router): polish public setup --- .github/workflows/ci.yml | 25 ++++++++ README.md | 61 +++++++++++++++++- .../plans/2026-04-28-agent-router-mvp.md | 63 ------------------- 3 files changed, 83 insertions(+), 66 deletions(-) create mode 100644 .github/workflows/ci.yml delete mode 100644 docs/superpowers/plans/2026-04-28-agent-router-mvp.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..37a94cd --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,25 @@ +name: CI + +on: + pull_request: + push: + branches: + - main + - codex/workspace + - claude/workspace + - huma/workspace + +jobs: + verify: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + with: + version: 10.25.0 + - uses: actions/setup-node@v4 + with: + node-version: 24 + cache: pnpm + - run: pnpm install --frozen-lockfile + - run: pnpm verify diff --git a/README.md b/README.md index 61e60be..3cb973c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # AgentRouter -AgentRouter is a GitHub App router for explicit agent mentions across personal and organization repositories. +AgentRouter is a GitHub App router for explicit agent mentions across personal and organization repositories. It lets one installed app listen across selected repos and queue work only when someone deliberately calls an agent. It listens for GitHub comments and reviews, validates that the sender is allowed to dispatch work, and creates jobs for: @@ -8,14 +8,25 @@ It listens for GitHub comments and reviews, validates that the sender is allowed - `@claude` - `@huma` -The first version is intentionally conservative: it stores jobs locally, exposes a small runner API, and only dispatches when an exact mention is present. +The first version is intentionally conservative: it stores jobs locally, exposes a small runner API, and only dispatches when an exact mention is present. No ambient code review, no surprise bot activity, no repo-by-repo workflow file required. -## Commands +## Quick Start ```bash pnpm install pnpm verify +cp .env.example .env +``` + +Set the required values in `.env`, then start the router: + +```bash pnpm dev +``` + +In another terminal, run a local worker lane: + +```bash pnpm runner -- --agent codex ``` @@ -43,6 +54,16 @@ pnpm setup:url HuntDynamics org 4. GitHub will redirect back to `/setup/callback`. AgentRouter exchanges the temporary manifest code and writes generated credentials to `.state/github-app.env` with file mode `0600`. 5. Copy those values into your runtime `.env`, restart the server, then install the app on the repos/accounts it should watch. +## Commands + +```bash +pnpm dev # start the webhook server +pnpm runner -- --agent codex # claim queued Codex jobs +pnpm setup:url fschrhunt user # generate a GitHub App manifest URL +pnpm test # run tests +pnpm verify # typecheck and test +``` + ## Configuration Copy `.env.example` to `.env` and set: @@ -55,6 +76,12 @@ Copy `.env.example` to `.env` and set: `GITHUB_PRIVATE_KEY_B64` should be the GitHub App private key PEM encoded as base64. +Use `agent-router.config.json` to restrict which repositories can dispatch jobs. Start from: + +```bash +cp agent-router.config.example.json agent-router.config.json +``` + ## Safety Rules - No agent runs unless a comment or review contains `@codex`, `@claude`, or `@huma`. @@ -62,3 +89,31 @@ Copy `.env.example` to `.env` and set: - Senders must have `write`, `maintain`, or `admin` repository permission. - Repositories can be allowlisted in `agent-router.config.json`. - The runner claims jobs over an authenticated local API. + +## Webhook Events + +AgentRouter currently understands: + +- issue comments +- issue bodies +- pull request review comments +- pull request review bodies + +When a valid mention is accepted, AgentRouter stores a queued job. Runners claim jobs per lane and report completion back to the local API. + +## Development + +```bash +pnpm install +pnpm verify +``` + +Runtime state is intentionally local and ignored by git: + +- `.env` +- `.state/` +- SQLite files + +## License + +MIT diff --git a/docs/superpowers/plans/2026-04-28-agent-router-mvp.md b/docs/superpowers/plans/2026-04-28-agent-router-mvp.md deleted file mode 100644 index 5285708..0000000 --- a/docs/superpowers/plans/2026-04-28-agent-router-mvp.md +++ /dev/null @@ -1,63 +0,0 @@ -# AgentRouter MVP Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Build a private GitHub App router that turns explicit `@codex`, `@claude`, and `@huma` mentions into authenticated local runner jobs. - -**Architecture:** A Node/TypeScript HTTP service verifies GitHub webhook signatures, parses supported comment/review events, checks sender permissions with a GitHub App installation token, and stores jobs in SQLite. A local runner authenticates with a shared runner token, claims pending jobs for one agent lane, and reports completion. - -**Tech Stack:** Node 24, TypeScript, Octokit, SQLite via `node:sqlite`, Vitest. - ---- - -### Task 1: Router Skeleton - -**Files:** -- Create `package.json`, `tsconfig.json`, `.env.example`, `README.md`, `AGENTS.md` -- Create `src/config.ts`, `src/types.ts` - -- [x] Define package scripts for `dev`, `runner`, `typecheck`, `test`, and `verify`. -- [x] Define strict TypeScript config for NodeNext modules. -- [x] Document first-run commands and required secrets. -- [x] Define environment parsing with safe defaults for local development. - -### Task 2: Event Parsing - -**Files:** -- Create `src/github/events.ts` -- Test `test/events.test.ts` - -- [x] Parse `issue_comment`, `pull_request_review_comment`, `pull_request_review`, and `issues`. -- [x] Extract exact agent mentions. -- [x] Ignore bot actors. -- [x] Return a normalized trigger request. - -### Task 3: Job Store - -**Files:** -- Create `src/store/job-store.ts` -- Test `test/job-store.test.ts` - -- [x] Create SQLite schema on startup. -- [x] Insert queued jobs. -- [x] Claim the oldest pending job for an agent. -- [x] Mark jobs complete or failed. - -### Task 4: GitHub Webhook Server - -**Files:** -- Create `src/server/main.ts`, `src/server/router.ts`, `src/github/client.ts` - -- [x] Verify webhook signatures. -- [x] Reject unknown methods and invalid payloads. -- [x] Check collaborator permission before queueing. -- [x] Comment back when a job is queued or rejected. - -### Task 5: Local Runner - -**Files:** -- Create `src/runner/main.ts` - -- [x] Claim jobs with `AGENT_ROUTER_RUNNER_TOKEN`. -- [x] Print claimed job details for the selected agent. -- [x] Report completion without running a real agent yet.