Agent Citizen Roles

Agent & Citizen Roles

Note

This page defines the role model for the Monkey-Head-Project (HueyOS): the bicameral core (Spark and Zap), the 256-member citizen populace, and the worker subsystems that execute real-world work. It’s offline-first and bound by the constitution (clauses and quorum) with unified memory.

Project · Monkey-Head-Project (HueyOS)
Status Date · 2025-10-25
Related · Governance-and-Constitution

---

1) Overview

HueyOS separates “thinking,” “checking,” and “doing”:

• Spark — creative planner. Generates proposals, plans, hypotheses.

• Zap — evaluator and safety core. Scores, constrains, and can veto.

• Citizens (up to 256) — narrow-scope agents (perception, navigation, dialogue, storage, etc.) that debate and vote.

• Workers — drivers and services (I/O, motion, audio, storage sync). No clause power; execute orders only.

flowchart TB
  S["Spark (plan and propose)"]
  Z["Zap (evaluate and enforce)"]
  C["Citizens (256 narrow-scope agents)"]
  W["Workers (I/O and motion subsystems)"]
  M["Unified Memory (SQLite + logs)"]
  S --> C
  C --> Z
  Z --> C
  C --> W
  S --> M
  Z --> M
  C --> M
  W --> M

Design goals:

• Decentralize decision-making, unify memory.

• Clear role contracts (inputs/outputs, capabilities, limits).

• Minimal external dependencies; run fully offline.

---

2) Role taxonomy

Layer	Authority	Typical capabilities	Examples
Spark	Drafts proposals; no direct act	Planning, multi-modal synthesis	Task planning, tool selection, dialogue intent
Zap	Scores, constrains, vetoes	Policy, safety, verification	Safety checks, cost bounds, ethics/clauses
Citizens	Debate & vote; propose & execute within scope	Domain decision-making	Perception, Navigation, Dialogue, Memory, Tooling
Workers	No vote; execute only	Hardware/IO, system services	Cameras, TTS, motor driver, storage sync

R = Responsible, C = Consulted, I = Informed.

---

13) Defaults and guardrails

• Max concurrent proposals in flight: 3 (drop oldest on overflow).

• Hard execution window: 30s unless extended by clause.

• Any class A step must include a Zap-approved risk note in the event payload.

• Workers must ignore orders missing an execution context (proposal_id, quorum result, clause hash).

---

14) Appendix — JSON Schema (fragment) for roles.yml

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["version", "spark", "zap", "citizens", "quorum"],
  "properties": {
    "version": {"type": "integer", "minimum": 1},
    "spark":  {"$ref": "#/$defs/role"},
    "zap":    {"$ref": "#/$defs/role"},
    "citizens": {"type": "array", "items": {"$ref": "#/$defs/role"}},
    "quorum": {
      "type": "object",
      "properties": {
        "weighting": {"type": "object", "additionalProperties": {"type": "integer"}},
        "rules": {"type": "array", "items": {"type": "object"}}
      }
    }
  },
  "$defs": {
    "role": {
      "type": "object",
      "required": ["id","name","scope","inputs","outputs","capabilities","safety_class"],
      "properties": {
        "id": {"type": "string"},
        "name": {"type": "string"},
        "version": {"type": "string"},
        "scope": {"type": "string"},
        "inputs": {"type": "array", "items": {"type": "string"}},
        "outputs": {"type": "array", "items": {"type": "string"}},
        "capabilities": {"type": "array", "items": {"type": "string"}},
        "constraints": {"type": "object"},
        "safety_class": {"enum": ["A","B","C"]},
        "resources": {"type": "object"},
        "logs": {"type": "object"}
      }
    }
  }
}

---

Next: wire this into your orchestrator’s bootstrap, add roles.yml to the repo under huey/config/, and run a quorum simulation to confirm ties, vetoes, and class-A paths behave as expected.