Gas City

Gas City is a platform for building software factories. Instead of using a single coding agent in an interactive session, Gas City allows you to define a formula (a description of how a job gets done) that an orchestrator executes across a fleet of agents.

Key benefits include:

• Parallelism: The orchestrator decomposes jobs into independent pieces and runs them in parallel across multiple agents.
• Durability: Work is broken into tracked units that survive crashes.
• Production Quality: The system includes automated review and gap-checking against the original plan.
• Portability: The engine is role-agnostic, allowing the same configuration to run locally, within a team, or via community packs.

The Gas City core pack includes a set of deterministic, mechanical housekeeping orders that run automatically in any city including the core pack. These orders do not use LLM context; instead, the controller executes them directly via exec using timer comparisons, dependency lookups, and event decoding.

Key categories of orders include:

• Cleanup: gate-sweep, orphan-sweep, prune-branches, wisp-compact, and order-tracking-sweep.
• Dependency Management: cross-rig-deps.
• Monitoring: spawn-storm-detect.
• Event-Driven Nudges: nudge-on-route, cascade-nudge-on-blocker-close, notify-on-human-gate-creation, and renudge-stale-human-gates.

No per-city configuration is required for these orders to function.

Gas City is a composable orchestration-builder SDK designed for multi-agent coding workflows. It provides a configurable toolkit that includes:

• Declarative Configuration: Managed via city.toml.
• Runtime Providers: Support for tmux, subprocess, exec, ACP, Kubernetes, herdr, and hybrid.
• Work Tracking: Uses 'Beads' for tracking work, formulas, molecules, waits, and mail.
• Controller/Supervisor Loop: A mechanism that reconciles the desired state defined in configuration to the actual running state.
• Orchestration Scopes: Supports Packs, overrides, and rig-scoped orchestration for managing multi-project setups.

The Supervisor API is organized into several functional surfaces:

• Cities: Lifecycle management (GET /v0/cities, POST /v0/city, GET /v0/city/{cityName}, etc.).
• Health & Readiness: System status (GET /health, GET /v0/readiness, GET /v0/provider-readiness).
• Agents: Agent management and output streaming (/v0/city/{cityName}/agents).
• Beads (work units): CRUD, queries, hooks, and dependencies.
• Sessions: Interaction management (submit, prompt, resume, transcript, and SSE streams).
• Connected-client external messaging: Registering LLM clients (POST /v0/extmsg/clients) and delivering inbound turns (POST /v0/extmsg/inbound).
• Events: Supervisor-wide or city-specific event streams (/v0/events/stream or /v0/city/{cityName}/events/stream).
• Config & Packs: Metadata and configuration for specific cities.

The Gas City Testing Policy is the canonical source for how tests are designed, placed, reviewed, and timed. It prioritizes fast, deterministic feedback and follows the principle of 'one risk, one smallest owning proof'.

Key principles include:

• Smallest Owning Proof: Every test should target the smallest layer that can fail for the intended reason. Avoid repeating lower-layer branch matrices at higher layers.
• Conformance over Duplication: Instead of creating new journeys for every implementation, use shared conformance suites that run against both production implementations and fast substitutes (fakes).
• Flakes are Defects: Non-deterministic tests are considered bugs and must be addressed.
• Fast Feedback: The target Service Level Objective (SLO) is for PR feedback to be available in under five minutes (p95).

The Gas City dashboard provides real-time monitoring via Server-Sent Events (SSE). Key features include:

• Convoys: Progress tracking, issue tracking, and convoy creation.
• Crew & Polecats: Named worker status, activity detection, and ephemeral worker status.
• Activity timeline: A categorized, filterable event feed.
• Mail: Inbox with threading, composing, and all-traffic views.
• Merge queue: Monitoring open PRs, CI status, and mergeability.
• Escalations & Issues: Priority-colored escalation lists and backlog management (priority, age, labels, assignment).
• Health: System heartbeats and agent counts.
• Ready work: Items available for assignment.
• Command palette: Press Cmd+K to execute gc commands directly from the browser.

The Testing Efficiency Operating Corpus is an operational playbook used to accelerate Gas City's test suite without reducing defect detection. It provides the methodology for finding test candidates, designing bounded slices of work, and delegating implementation.

Important Distinctions:

• TESTING.md: The canonical source for test design, placement, doubles, and resource policy. It takes precedence in all conflicts.
• testing-pyramid-hardening-plan.md: The historical audit and backlog of tasks.
• This Corpus: The operational guide for executing the policy and plan.

The Mission: Achieve developer-visible protected PR feedback at p95 under five minutes while preserving or improving defect detection. Speed is treated as an architectural constraint: a slow test indicates either a real boundary or production logic trapped behind an unnecessarily expensive boundary.

The Gas City controller implementation is primarily located in cmd/gc/. Key files and their responsibilities include:

• controller.go: Core loop management, config reloading, and socket startup.
• city_runtime.go: The CityRuntime shared per-city runtime.
• cmd_supervisor.go: Machine-wide supervisor lifecycle and API hosting.
• session_reconciler.go: The bead-driven state machine for desired/live convergence.
• pool.go: Pool evaluation and agent naming.
• providers.go: Session and bead provider initialization.
• formula_resolve.go: Layered symlink materialization via ResolveFormulas().
• wisp_gc.go: TTL-based purging of closed molecules.
• order_dispatch.go: Order triggering and execution.
• crash_tracker.go & idle_tracker.go: Tracking agent health and inactivity.

Gas City provides several conceptual frameworks to help you model agentic workflows and system behavior:

• Capabilities for Coding Agents: Maps single-agent coding tool concepts (context, state, skills, history, messaging, roles, and identity) onto Gas City's shared infrastructure.
• Packs: Understand how pack definitions function and how imports translate into city behavior.
• Formulas: Learn how to design formulas, select appropriate contracts, and apply common patterns to your workflows.