[Gastown] PR 3: Tool Plugin

[jrf0110]

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

• Plugin package with all 8 tools implemented
• HTTP client for Rig DO API with auth (JWT bearer token)
• Plugin event hooks for session lifecycle
• Tool input/output schemas defined
• Unit tests for tool logic