Upstream Architecture Model (Living Document v0.1)

(Evidence-Backed Canonical Baseline)

Authority note (2026-09-09): current docs.gascity.com is primary for Gas City semantics. This catalog is a dated snapshot. If this file disagrees with current docs.gascity.com, the online docs win. Do not treat Order, Session, Supervisor, Mayor, or Molecule as additional primitives — the six primitives are Agent, Bead, Formula, Rig, Pack, Event. Bluefly policy: factory-operating-contract.md.

This document establishes the evidence-backed architectural model of the platform's upstream dependencies, capturing their primitives, boundaries, and extension surfaces. This fulfills Phase 0 of the platform cataloging implementation plan by documenting the true upstream authorities.

Upstream Version Record

• Gas City Docs:
  • Documentation index: llms.txt
  • Last documentation crawl: 2026-09-09
  • Primary authority: current docs.gascity.com
  • Documentation revision: main (gascityhall/gascity)
• OpenClaw:
  • Repository / documentation revision: main (openclaw.ai)
• KAgent:
  • Repository snapshot: main (kagent-dev/kagent)
  • Organization repositories enumerated: kagent, kmcp, khook, OpenShell, substrate, a2a-go, tools
• Generated: 2026-07-15
• Gas City semantics last reconciled: 2026-09-09 against current docs.gascity.com

---

1. Gas City Core (Orchestrator, Packs, Rigs)

Authority: Gas City Core Orchestration Primitives: * Agent: The configured WHO of the system. An identity bound to a harness (provider), prompt templates, and options (min_active_sessions, max_active_sessions), executing within a session. * Bead: The universal WHAT. An immutable unit of work or state (task, comment, convoy, control) stored in the Dolt database. * Formula: The HOW. A declarative set of steps and dependencies (e.g. v2 formula compiler) that decomposes into a graph of beads run by the orchestrator. * Rig: The WHERE. A registered workspace (git repository) mapped into a city scope with its own prefix namespace. * Pack: The configuration boundary. A portable directory with pack.toml defining imported packs, agent prompts, formulas, and orders. * Event: The OBSERVE mechanism. Immutable append-only events published to the system-wide event bus for logging, state transitions, and coordination. Configuration Boundary: * pack.toml (portable capabilities, imported packs, and named session templates). * city.toml (city deployment/runtime: provider, daemon flags, portable rig identity/declaration — not machine-local path=). Deployment Boundary: The City root directory containing city.toml and managing the local .gc/ runtime state directory. Rig directories are registered locally in .gc/site.toml. Runtime Boundary: The supervisor daemon (gc supervisor start), the orchestrator tick loop (reconciliation loop executing ticks, scaling sessions, gating work), and individual isolated provider shells (e.g. tmux via RPP). Persistence Boundary: Beads store (Dolt sql-server) scoped by issue_prefix (e.g. mc for city-level, rig basenames for rigs), isolated at the query layer via bd filters. Machine-local site state is stored in .gc/site.toml. Extension Boundary: Reusable packs, custom formulas (v2 compiler), command directories, custom doctor checks, overlay contexts, and MCP integrations. Migration Boundary: gc doctor --fix automatically repairs legacy configuration, missing system templates, or version bumps. Compatibility Boundary: RPP (Runtime Provider Protocol) connecting standard providers (claude, codex, gemini, groq, opencode, cerebras). Observed Runtime: Orchestration loop evaluates ready beads, scales pools, and processes mail asynchronously from active operator sessions. Evidence: * Source: getting-started/how-gas-city-works.md, tutorials/01-cities-and-rigs.md, getting-started/coming-from-gascity.md, reference/internal/beads-topology.md * Confidence: Documented

---

2. Gas City: Dashboard

Authority: Gas City Built-in Dashboard Primitives: * Single-page app: Built-in SPA precompiled directly into the gc binary. * Supervisor HTTP Listener: API listener hosted by the supervisor daemon (default port 8372). Configuration Boundary: * GC_SUPERVISOR_DASHBOARD=0 environment variable (disables dashboard compiling/serving). * Bind settings (bind = "0.0.0.0") and write authorization/mutations knobs (allow_mutations = true) in city.toml. Deployment Boundary: Embedded within the gc binary; served directly by the supervisor process on the API bind address. Runtime Boundary: Same-origin API requests carrying X-GC-Request CSRF headers. Disables mutating controls and falls back to read-only if binding a non-localhost address without allow_mutations. Persistence Boundary: Stateless. Directly queries the supervisor's REST API. Extension Boundary: None documented. Migration Boundary: N/A. Compatibility Boundary: X-GC-Request CSRF headers. Observed Runtime: Serves on loopback (127.0.0.1:8372) reflecting live agent, bead, and mail state. Evidence: * Source: getting-started/dashboard.md * Confidence: Documented

---

3. Gas City: Orders

Authority: Gas City Automation (Orders) Orders are not a seventh primitive. They are Pack/City configuration that fires a Formula. The six primitives remain Agent, Bead, Formula, Rig, Pack, Event. Mechanisms: * Exec Order: Runs a POSIX shell command directly on the orchestrator environment. Does not spawn an agent session. * Formula Order: Dispatches a v2 formula as a bead graph to a targeted worker pool. * Triggers: cooldown (waits for interval duration since last run), cron (5-field schedule expression), condition (runs check command, exits 0, bounded by check_timeout), event (tracks cursor on named event bus event, e.g., bead.closed), manual (only fires via gc order run). Configuration Boundary: * TOML files in orders/ directory of a Pack or City. Local orders/ override pack-provided orders of the same name. * Managed by city.toml overrides ([[orders.overrides]]) and general [orders] keys (e.g., skip list, max_timeout). Deployment Boundary: Scoped city-wide (scope = "city") or instantiates per rig (scope = "rig", default). Rig-scoped orders qualify the pool target (e.g. gc.routed_to=rig-name/worker). Runtime Boundary: Ticked by the orchestrator loop. Enforces command execution timeout (check_timeout defaults to 10s, order execution defaults to 30s for formula and 300s for exec). Persistence Boundary: Synchronous creation of a tracking bead on Dolt before dispatch. Open-work check skips if prior run is still open (preventing duplicates), unless idempotent = true. Extension Boundary: Declarative TOML order files replacing legacy Gas City plugins. Supports executing arbitrary binaries via Exec orders. Migration Boundary: Replacing Gas City "plugins" with declarative Orders. Compatibility Boundary: 5-field cron parser, Go duration string parser ("5m", "30s"), and standard POSIX shell. Observed Runtime: Evaluates on supervisor tick; executes automatically without human interaction. Manageable via gc order list, gc order show <name>, gc order check, gc order run <name>, and gc order history. Evidence: * Source: getting-started/how-gas-city-works.md, tutorials/07-orders.md * Confidence: Documented

---

4. Gas City: Managed & Remote Cities

Authority: Gas City Distributed Deployment Primitives: * Managed City: The default local setup where the city owns the Dolt SQL server lifecycle (gc start launches it, gc stop shuts it down). Rigs inherit this server's port. * Remote Hardened City: A self-hosted city binding to 0.0.0.0 that accepts mutations over an HTTP+SSE control plane. * Endpoint Origins: * managed_city: City owns the Dolt SQL server lifecycle; port is read from .beads/dolt-server.port. * city_canonical: City declares an externally managed Dolt server. * inherited_city: Rig has no endpoint of its own; inherits from city. * explicit: Rig has a pinned, externally managed Dolt endpoint. Configuration Boundary: * Server-side city.toml under [api] (port, bind, allow_mutations, write_auth_verify_key, write_auth_allow_unverified). * Client-side $GC_HOME/contexts.toml (0600 file) defining context settings: --url, --city, --grant-command, --ca-file. Deployment Boundary: Single-tenant controller node (single replica only to prevent grant replay and double-clones) fronted by a mandatory network/TLS proxy (the read plane is fully unauthenticated). Runtime Boundary: Server-side allowed_hosts verification (421 check). Every client mutation must include a signed X-GC-City-Write grant token signed by client keypair (ed25519) within a 2-minute TTL. Persistence Boundary: Remote Dolt databases. Client-side contexts mapped in $GC_HOME/contexts.toml. Extension Boundary: Distributed event bus routing. Migration Boundary: Upgrading local standalone cities to managed network hubs. Compatibility Boundary: Supervisor API backward compatibility. Observed Runtime: Client operations use gc --context <ctx>. Remote slings are restricted to 2-arg explicit bead formats. Provisioning errors can be resumed idempotently using the exact same --request-id. Evidence: * Source: runbooks/managed-city-endpoints.md, runbooks/remote-hardened-city.md * Confidence: Documented

---

5. Gas City: Commands

Authority: Gas City CLI Extensibility Primitives: CLI subcommands, Command execution wrapper, CLI command parser. Configuration Boundary: Declared in the commands/ directory of a Pack. Deployment Boundary: Pack distribution. Runtime Boundary: CLI calls (gc <subcommand>) dynamically register and execute scripts or binaries. Persistence Boundary: Stateless execution. Extension Boundary: Custom subcommands exposed through the gc executable. Migration Boundary: Migration of gt script tooling into Pack-specific commands. Compatibility Boundary: POSIX exit codes, standard streams, and injected environment variables (PACK_DIR, ORDER_DIR). Observed Runtime: Native integration into gc --help. Evidence: * Source: PackV2 Layout guidelines, getting-started/coming-from-gascity.md * Confidence: Documented

---

6. Gas City: Doctor

Authority: Gas City Configuration Repair Primitives: Repair Rule, Diagnostic Check. Configuration Boundary: Declared in the doctor/ directory of a Pack. Deployment Boundary: Pack distribution. Runtime Boundary: Plain gc doctor (no flags) is documented at docs.gascity.com/reference/cli as diagnostic-only; --fix is what applies repairs. Do not read "on demand" as meaning every invocation mutates — see the empirical conflict recorded in gas-city-master-spec.md §3a: a plain, flagless gc doctor run was traced (RETRIEVED 2026-09-09) to starting a managed Dolt server, contradicting the "read-only by default" doc claim. Persistence Boundary: --fix may modify city.toml, .gc/, and .beads/ configurations; plain gc doctor is documented as not doing so (see conflict above — not confirmed in practice). Extension Boundary: Custom packs adding domain-specific repair checks. Migration Boundary: Essential for config updates, path normalization, and legacy migrations. RETRIEVED 2026-09-09 (engdocs/design/packv2/doc-rig-binding-phases.md, Pack v2 design track, not confirmed shipped): also documented to detect and report rig-path binding/name mismatches — keyed (cityPath, rigName) — without silently repairing them; an explicit gc rig bindings import is required to change a binding. Compatibility Boundary: Safely handles malformed state without data loss. Observed Runtime: Includes the dolt-drift check to detect PID/port mismatches, automatically resolving missing core system templates/imports. Related, distinct mechanism: gc doctor (config diagnostics/repair) is not the same subsystem as Health Patrol — the controller's Layer 2-4 agent-supervision mechanism (liveness monitoring, crash-loop quarantine, idle-kill, periodic order dispatch). See github.com/gascityhall/gascity/blob/main/engdocs/architecture/health-patrol.md (last verified against code 2026-05-29). Not expanded here; named to prevent conflating config-repair with agent-supervision when reasoning about doctor/runtime behavior. Evidence: * Source: tutorials/01-cities-and-rigs.md, runbooks/managed-city-endpoints.md * Confidence: Documented

---

7. Gas City: Overlays

Authority: Gas City Context Injection Primitives: Overlay template, prompt fragment. Configuration Boundary: Declared in the overlays/ directory of a Pack. Deployment Boundary: Pack distribution. Runtime Boundary: Appended to targeted agent prompt templates during session boot. Persistence Boundary: None. Extension Boundary: Reusable system context across multiple agents. Migration Boundary: N/A. Compatibility Boundary: Template syntax compatibility. Observed Runtime: Shapes the system instructions dynamically at runtime. Evidence: * Source: PackV2 Layout guidelines * Confidence: Architectural interpretation

---

8. Gas City: Skills

Authority: Gas City Capability Extensions Primitives: Skill configurations, tool execution paths, Tool schema. Configuration Boundary: Declared in the skills/ directory of a Pack. Deployment Boundary: Pack distribution. Runtime Boundary: Loaded by agent runtimes as callable tools. Persistence Boundary: Stateless tool execution. Extension Boundary: Provides agent functions (e.g., file read/write, search). Migration Boundary: N/A. Compatibility Boundary: Tool calling schema (OpenAI/Anthropic compatible). Observed Runtime: Session provider exposes tools directly to the LLM agent. Evidence: * Source: Local pack directories and PackV2 Layout guidelines * Confidence: Corroborated

---

9. Gas City: MCP Directory

Authority: Gas City Standardized Tooling Primitives: MCP Servers. Configuration Boundary: Declared in the mcp/ directory of a Pack. Deployment Boundary: Pack distribution. Runtime Boundary: Subprocess executed by session providers. Persistence Boundary: N/A. Extension Boundary: Standardized Model Context Protocol servers. Migration Boundary: Upgrading proprietary tools to standard MCP servers. Compatibility Boundary: Model Context Protocol (stdio/SSE). Observed Runtime: Integrates external tool/resource interfaces cleanly. Evidence: * Source: PackV2 Layout guidelines * Confidence: Architectural interpretation

---

10. Gas City: Runtime Provider Interfaces

Authority: Gas City Execution Isolation Primitives: RPP (Runtime Provider Protocol), Provider harness. Configuration Boundary: Defined under [providers] and [workspace] keys in city.toml. Deployment Boundary: Local CLI or container environments. Runtime Boundary: Session lifecycle (awake, active, stopped) managed via process spawning (e.g. tmux via GC_AGENT_SLICE). Persistence Boundary: Provider-specific state (e.g. tmux sockets). Extension Boundary: Custom providers for Docker, Kubernetes, SSH. Migration Boundary: Moving agents from local tmux to remote execution. Compatibility Boundary: RPP contract (stdin/stdout, exit codes). Observed Runtime: Automatically boots named agents and housekeepers (dolt.dog) as background tasks. Evidence: * Source: tutorials/01-cities-and-rigs.md, getting-started/coming-from-gascity.md * Confidence: Documented

---

11. Gas City: Config Schema & Repository Map

Authority: Gas City Internal Registry Primitives: Configuration Parser, Path Resolver. Configuration Boundary: * pack.toml: Schema version, imports, and named session templates. * city.toml: Workspace defaults, portable rig identity ([[rigs]] name, not path=), provider presets, and order overrides. * .gc/: Directory for supervisor logs, PID files, and unix sockets. * .gc/site.toml: Machine-local city identity and rig path bindings. * .beads/: Local beads tracking setup containing config.yaml (issue_prefix, gc.endpoint_origin) and dolt-server.port compatibility mirror. Deployment Boundary: Local workspace. Runtime Boundary: Schema validation on gc start. Persistence Boundary: Cached schemas and repository paths. Extension Boundary: Registry syncing. Migration Boundary: PackV1 to PackV2 schema translation. Compatibility Boundary: TOML parser constraints. Observed Runtime: Validates config schemas dynamically. Evidence: * Source: PackV2 guide, beads storage topology documentation * Confidence: Architectural interpretation

---

12. KAgent (kagent.dev)

Authority: Kubernetes-native AI Framework Primitives: Agent, ModelConfig, RemoteMCPServer, MCPServer (CRDs), Task, Message (A2A), Hooks. Configuration Boundary: Kubernetes CRDs (Declarative state) and ConfigMaps (System Prompts). Deployment Boundary: Helm charts deploying controller, kmcp, khook, and agent Pods. Runtime Boundary: Standalone Agent Pods (LLM loop) and Substrate/OpenShell sandboxes. Persistence Boundary: Kubernetes ETCD (CRDs) and Controller Local DB (SQLite/Pg). Extension Boundary: Model Context Protocol (MCP) and Agent-to-Agent (A2A) HTTP/SSE. Migration Boundary: GitOps declarative state syncing. Compatibility Boundary: ACP shim for third-party harnesses (OpenClaw). Observed Runtime: Controller reconciles CRDs into Deployments/Services/Secrets dynamically. Unknowns: Specific execution limits inside OpenShell sandboxes. Evidence: * Source: agent-configuration.md, kagent.dev upstream * Confidence: Documented

---

13. OpenClaw (openclaw.ai)

Authority: Autonomous Agent Gateway Primitives: Gateway Process, Agent Engine, Lane Queue, Skills, Tools. Configuration Boundary: "Skills-as-markdown" and Gateway token configs. Deployment Boundary: Headless Node.js process. Runtime Boundary: Gateway orchestrates execution; ACP Bridge provides protocol translation (stdio to WS). Persistence Boundary: Local storage/DB managed by the Gateway. Extension Boundary: Agent Client Protocol (ACP) JSON-RPC 2.0. Migration Boundary: Markdown-based skills. Compatibility Boundary: ACP and MCP tool support. Observed Runtime: Gateway operates as a long-lived hub for agent sessions. Unknowns: Exact dispatch logic of the Lane Queue. Evidence: * Source: docs.openclaw.ai/cli/acp, openclaw.ai * Confidence: Documented

---

14. OpenCode (opencode.ai)

Authority: Open-source AI Agent Framework & CLI Execution Surface Primitives: CLI Runner (opencode), Agent Profiles (~/.config/opencode/agents/*.md), Model Providers (opencode.jsonc), Plugins / Hooks (plugins/*.js), MCP Tool Servers. Configuration Boundary: User configuration (~/.config/opencode/opencode.jsonc), Project overrides (.opencode/opencode.jsonc), Agent system prompt profiles. Deployment Boundary: Local CLI binary / headless task executor (opencode run). Runtime Boundary: Node.js/TypeScript execution runtime with native plugin hook lifecycle (session.created, session.compacted, experimental.chat.system.transform). Persistence Boundary: Session state in local SQLite/JSON (~/.local/share/opencode), project-scoped cache. Extension Boundary: OpenCode Plugin Architecture (JavaScript hook scripts) and Model Context Protocol (MCP) stdio/SSE servers. Migration Boundary: Agent role Markdown definition format with YAML frontmatter. Compatibility Boundary: OpenAI-compatible API providers (LiteLLM, Ollama, LM Studio), Gas City Tier 2 provider registration (builtin:opencode via city.toml and gascity.js plugin). Observed Runtime: Tier 2 governed Polecat worker integrated with Gas City lifecycle; injects gc prime and task context on session turns. Unknowns: Long-term upstream plugin API stability for experimental lifecycle hooks. Evidence: * Source: opencode.ai documentation, BluCity/city.toml, ~/.config/opencode/plugins/gascity.js * Confidence: Documented & verified runtime