Parent: #204 | Phase 1: Single Rig, Single Polecat
Goal
The opencode plugin that exposes Gastown tools to agents. This is the heart of the system — it is what agents actually interact with. Ships pre-installed in the Cloud Agent sandbox image, enabled via a server-side flag.
Location
cloud/cloudflare-gastown/plugin/
├── src/
│ ├── index.ts # Plugin entry point
│ ├── tools.ts # Tool definitions
│ ├── client.ts # HTTP client for Rig DO API
│ └── types.ts # Shared types
├── package.json
└── tsconfig.json
Tools (Phase 1 — minimum viable set)
| Tool |
Description |
Rig DO Method |
gt_prime |
Get full role context: identity, hooked work, instructions, pending mail |
prime(agentId) |
gt_bead_status |
Read the status of a bead |
getBead(beadId) |
gt_bead_close |
Close current bead or molecule step |
closeBead(beadId) |
gt_done |
Signal work complete — push branch, submit PR to review queue |
agentDone(agentId, ...) |
gt_mail_send |
Send a typed message to another agent |
sendMail(...) |
gt_mail_check |
Read and acknowledge pending mail |
checkMail(agentId) |
gt_escalate |
Escalate an issue with severity and category |
createBead(type: 'escalation') |
gt_checkpoint |
Write crash-recovery data |
writeCheckpoint(agentId, ...) |
Plugin Event Hooks
| Event |
Action |
session.created |
Auto-call gt_prime and inject result into session context |
session.compacted |
Re-call gt_prime to restore context after compaction |
session.deleted |
Notify Rig DO that the session has ended (for cleanup/cost tracking) |
Environment Variables (set by Cloud Agent session config)
| Var |
Value |
GASTOWN_API_URL |
Worker URL |
GASTOWN_SESSION_TOKEN |
Short-lived JWT for this agent session |
GASTOWN_AGENT_ID |
This agent's UUID |
GASTOWN_RIG_ID |
This rig's UUID |
KILO_API_URL |
Kilo gateway URL (for LLM calls) |
Dependencies
- PR 1 (Rig DO)
- PR 2 (HTTP API Layer)
Acceptance Criteria
