unkinben
8f48dd838b
Replace task statuses (pending/running/succeeded/failed/cancelled) with
a kanban workflow: todo → in_progress → in_review → done/wontdo.
When a non-review agent task completes, the API auto-creates a child
review task and moves the parent to in_review. Only humans can move
tasks from in_review to done/wontdo via the TUI.
New components:
- cmd/tui: bubbletea kanban board with $EDITOR integration
- POST /api/v1/tasks/{id}/complete: agent completion callback
- Operator --api-url flag for completion callbacks
- ProviderQueue sets tasks to in_progress on pickup
- AgentTask reconciler calls /complete on job finish
124 lines
3.6 KiB
Markdown
124 lines
3.6 KiB
Markdown
# forgebot
|
|
|
|
K8s operator + API for AI agent dispatch from git forges.
|
|
|
|
## Architecture
|
|
|
|
- **API server** (`cmd/api`) — REST API backed by PostgreSQL. Receives webhooks from Gitea, manages task lifecycle, and orchestrates the review workflow.
|
|
- **Operator** (`cmd/operator`) — Kubernetes controller that watches for pending tasks, creates Jobs via AgentPool/AgentTask CRDs, and reports completion back to the API.
|
|
- **TUI** (`cmd/tui`) — Terminal kanban board for viewing and managing tasks.
|
|
|
|
## Task Lifecycle
|
|
|
|
Tasks follow a kanban workflow with automated review:
|
|
|
|
```
|
|
+-----------+
|
|
| Todo |
|
|
+-----+-----+
|
|
|
|
|
agent picks up
|
|
|
|
|
+-----v-------+
|
|
| In Progress |
|
|
+-----+-------+
|
|
|
|
|
agent completes
|
|
|
|
|
+-----------+-----------+
|
|
| |
|
|
auto-create error?
|
|
review task back to Todo
|
|
|
|
|
+-----v------+
|
|
| In Review |<-----+
|
|
+-----+------+ |
|
|
| |
|
|
human decision reviewer
|
|
| suggests
|
|
+----+----+ changes
|
|
| | |
|
|
+----v--+ +---v----+ |
|
|
| Done | | Wontdo | |
|
|
+-------+ +--------+ |
|
|
|
|
|
(new fix task in Todo)
|
|
```
|
|
|
|
Only humans can move tasks from In Review to Done/Wontdo.
|
|
|
|
## Quick Start
|
|
|
|
### API Server
|
|
|
|
```bash
|
|
export DBHOST=localhost DBUSER=forgebot DBPASS=secret DBNAME=forgebot
|
|
export GITEA_URL=https://git.unkin.net GITEA_TOKEN=<token>
|
|
make build
|
|
./bin/forgebot-api
|
|
```
|
|
|
|
### Operator
|
|
|
|
```bash
|
|
./bin/forgebot-operator --api-url http://forgebot-api:8000
|
|
# or
|
|
FORGEBOT_API_URL=http://forgebot-api:8000 ./bin/forgebot-operator
|
|
```
|
|
|
|
### TUI
|
|
|
|
```bash
|
|
./bin/forgebot-tui -api http://localhost:8000
|
|
# or
|
|
FORGEBOT_API_URL=http://forgebot-api:8000 ./bin/forgebot-tui
|
|
```
|
|
|
|
#### TUI Key Bindings
|
|
|
|
| Key | Action |
|
|
|-----|--------|
|
|
| `h`/`l` or arrows | Move between columns |
|
|
| `j`/`k` or arrows | Move within column |
|
|
| `Enter` | Task detail view |
|
|
| `e` | Edit task in $EDITOR |
|
|
| `n` | Create new task |
|
|
| `d` | Mark done (in review only) |
|
|
| `w` | Mark wontdo (in review only) |
|
|
| `r` | Refresh |
|
|
| `/` | Filter by repository |
|
|
| `?` | Toggle help |
|
|
| `q` | Quit |
|
|
|
|
## API
|
|
|
|
| Method | Path | Description |
|
|
|--------|------|-------------|
|
|
| `GET` | `/health` | Health check |
|
|
| `GET` | `/api/v1/tasks` | List tasks (`?status=`, `?repository=`) |
|
|
| `POST` | `/api/v1/tasks` | Create task |
|
|
| `GET` | `/api/v1/tasks/{id}` | Get task |
|
|
| `PATCH` | `/api/v1/tasks/{id}` | Update task status |
|
|
| `POST` | `/api/v1/tasks/{id}/complete` | Agent completion callback (triggers review workflow) |
|
|
| `POST` | `/api/v1/tasks/{id}/comment` | Post comment to forge |
|
|
| `POST` | `/api/v1/webhook/gitea` | Gitea webhook receiver |
|
|
|
|
## CRDs
|
|
|
|
- **AgentPool** — Configuration for a pool of AI agents (model, concurrency, image, resources)
|
|
- **AgentTask** — A task dispatched to a pool for execution
|
|
- **ProviderQueue** — Polls the API for pending tasks and creates AgentTask CRs
|
|
- **RepositoryBinding** — Links a repository to a queue and pool with access controls
|
|
|
|
## Building
|
|
|
|
```bash
|
|
make build # all binaries to bin/
|
|
make test # run tests
|
|
make lint # go vet
|
|
make fmt # gofmt
|
|
make generate # regenerate CRDs and RBAC
|
|
make docker-api # build API container image
|
|
make docker-operator # build operator container image
|
|
```
|