[Gastown] PR 2: HTTP API Layer

[jrf0110]

Parent: #204 | Phase 1: Single Rig, Single Polecat

Goal

Hono router exposing the Rig DO's methods as HTTP endpoints, consumed by both the tool plugin and the Next.js backend.

Routes

POST   /api/rigs/:rigId/beads                    → createBead
GET    /api/rigs/:rigId/beads                     → listBeads
GET    /api/rigs/:rigId/beads/:beadId             → getBead
PATCH  /api/rigs/:rigId/beads/:beadId/status      → updateBeadStatus
POST   /api/rigs/:rigId/beads/:beadId/close       → closeBead

POST   /api/rigs/:rigId/agents                    → registerAgent
GET    /api/rigs/:rigId/agents                     → listAgents
GET    /api/rigs/:rigId/agents/:agentId            → getAgent

POST   /api/rigs/:rigId/agents/:agentId/hook      → hookBead
DELETE /api/rigs/:rigId/agents/:agentId/hook       → unhookBead
GET    /api/rigs/:rigId/agents/:agentId/prime      → prime
POST   /api/rigs/:rigId/agents/:agentId/done       → agentDone
POST   /api/rigs/:rigId/agents/:agentId/checkpoint → writeCheckpoint

POST   /api/rigs/:rigId/mail                       → sendMail
GET    /api/rigs/:rigId/agents/:agentId/mail        → checkMail

POST   /api/rigs/:rigId/review-queue               → submitToReviewQueue
POST   /api/rigs/:rigId/escalations                → createEscalation

GET    /api/rigs/:rigId/convoys                    → listConvoys (Phase 2)

Auth

Two auth modes (following KiloClaw pattern):

• Internal (x-internal-api-key): Next.js backend → worker
• Agent (Authorization: Bearer <session-token>): tool plugin → worker. Token is a short-lived JWT containing { agentId, rigId, townId, userId }, minted by Next.js when creating a Cloud Agent session.

Dependencies

• PR 1 (Rig DO)

Acceptance Criteria

• Hono router with all Phase 1 routes implemented
• Internal auth middleware (x-internal-api-key)
• Agent auth middleware (JWT validation)
• Request validation (zod or similar)
• Error handling with structured error responses
• Routes correctly resolve Rig DO by rigId and delegate to RPC methods