Unified Agent OS — Architecture Document

╔══════════════════════════════════════════════════════════════════════════════╗
║                           UNIFIED AGENT OS (UAOS)                          ║
╠══════════════════════════════════════════════════════════════════════════════╣
║                                                                            ║
║  ┌────────────────────────────────────────────────────────────────────┐    ║
║  │                     CADENCE ORCHESTRATION LAYER                    │    ║
║  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───────────────────┐ │    ║
║  │  │ Scheduler│  │ Router   │  │ Priority │  │ Agent Registry    │ │    ║
║  │  │          │  │          │  │ Queue    │  │ (roles, caps)     │ │    ║
║  │  └────┬─────┘  └────┬─────┘  └────┬─────┘  └───────────────────┘ │    ║
║  └───────┼──────────────┼──────────────┼────────────────────────────┘    ║
║          │              │              │                                   ║
║  ┌───────┼──────────────┼──────────────┼────────────────────────────┐    ║
║  │       ▼              ▼              ▼                             │    ║
║  │                 UNIFIED EVENT BUS                                 │    ║
║  │   ┌─────────────────────────────────────────────────────────┐    │    ║
║  │   │  Topics: dream.*, pulse.*, heartbeat.*, cadence.*       │    │    ║
║  │   │  Format: {type, source, payload, timestamp, trace_id}   │    │    ║
║  │   └─────────────────────────────────────────────────────────┘    │    ║
║  └──────────────────────────────────────────────────────────────────┘    ║
║          │              │              │              │                   ║
║  ┌───────▼──────┐ ┌─────▼──────┐ ┌────▼──────┐ ┌────▼──────────┐       ║
║  │   PULSE      │ │ HEARTBEAT  │ │  DREAM    │ │  CADENCE      │       ║
║  │   ENGINE     │ │ MONITOR    │ │  WEAVER   │ │  AGENTS       │       ║
║  │              │ │            │ │           │ │               │       ║
║  │ • Sessions   │ │ • Checks   │ │ • Seeds   │ │ • Higher-Level│       ║
║  │ • Iterations │ │ • Alerts   │ │ • Evolve  │ │ • Lower-Level │       ║
║  │ • Commits    │ │ • Proactive│ │ • Emerge  │ │ • INBOX/OUTBOX│       ║
║  │ • PRs        │ │ • Batch    │ │ • Morph   │ │ • Decisions   │       ║
║  └──────┬───────┘ └─────┬──────┘ └────┬──────┘ └──────┬────────┘       ║
║         │               │              │               │                 ║
║  ┌──────┴───────────────┴──────────────┴───────────────┴────────┐       ║
║  │                    UNIFIED STATE STORE                        │       ║
║  │                                                               │       ║
║  │  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐    │       ║
║  │  │ State DB    │  │ Event Log    │  │ Connection Graph │    │       ║
║  │  │ (SQLite)    │  │ (append-only)│  │ (Noosphere)      │    │       ║
║  │  │             │  │              │  │                  │    │       ║
║  │  │ • sessions  │  │ • all events │  │ • nodes          │    │       ║
║  │  │ • dreams    │  │ • decisions  │  │ • edges          │    │       ║
║  │  │ • checks    │  │ • handoffs   │  │ • weights        │    │       ║
║  │  │ • agents    │  │ • signals    │  │ • patterns       │    │       ║
║  │  └─────────────┘  └──────────────┘  └──────────────────┘    │       ║
║  └──────────────────────────────────────────────────────────────┘       ║
║                                                                          ║
╚══════════════════════════════════════════════════════════════════════════════╝

-- Core entity: anything the OS tracks
CREATE TABLE entities (
    id          TEXT PRIMARY KEY,
    type        TEXT NOT NULL,  -- 'session', 'dream', 'check', 'agent', 'decision'
    status      TEXT NOT NULL,
    created_at  TEXT NOT NULL DEFAULT (datetime('now')),
    updated_at  TEXT NOT NULL DEFAULT (datetime('now')),
    metadata    TEXT  -- JSON blob for subsystem-specific data
);

-- Pulse sessions
CREATE TABLE sessions (
    id              TEXT PRIMARY KEY REFERENCES entities(id),
    project_name    TEXT NOT NULL,
    project_path    TEXT NOT NULL,
    goal            TEXT,
    current_iteration INTEGER DEFAULT 0,
    max_iterations  INTEGER DEFAULT 10,
    active_account  TEXT,  -- dual-max tracking
    origin_dream_id TEXT REFERENCES entities(id)  -- if born from metamorphosis
);

-- Dream Weaver dreams (unified noosphere + incubation)
CREATE TABLE dreams (
    id                  TEXT PRIMARY KEY REFERENCES entities(id),
    seed_idea           TEXT NOT NULL,
    keywords            TEXT,  -- JSON array
    connection_strength REAL DEFAULT 0.0,
    connections         TEXT,  -- JSON array
    synthesis           TEXT,  -- JSON blob
    approaches          TEXT,  -- JSON array
    pollinated_by       TEXT,  -- JSON array of dream IDs
    metamorphosis       TEXT,  -- JSON blob (pulse goal, confidence)
    phase               TEXT DEFAULT 'seed'  -- seed, germinating, growing, flowering, bloom
);

-- Heartbeat check records
CREATE TABLE checks (
    id          TEXT PRIMARY KEY,
    domain      TEXT NOT NULL,  -- 'dreamWeaver', 'projects', 'calendar', etc.
    checked_at  TEXT NOT NULL DEFAULT (datetime('now')),
    result      TEXT,  -- JSON blob
    alert_level INTEGER DEFAULT 0  -- 0=silent, 1-3=low, 4-6=medium, 7-9=high, 10=critical
);

-- Cadence agents
CREATE TABLE agents (
    id          TEXT PRIMARY KEY REFERENCES entities(id),
    role        TEXT NOT NULL,  -- 'higher_level', 'lower_level', 'pulse_worker', etc.
    inbox       TEXT,  -- JSON array of messages
    outbox      TEXT,  -- JSON array of messages
    capabilities TEXT  -- JSON array
);

-- Cross-system handoff log
CREATE TABLE handoffs (
    id              TEXT PRIMARY KEY,
    from_system     TEXT NOT NULL,  -- 'dream_weaver', 'pulse', 'heartbeat', 'cadence'
    to_system       TEXT NOT NULL,
    entity_id       TEXT REFERENCES entities(id),
    handoff_type    TEXT NOT NULL,  -- 'metamorphosis', 'alert', 'delegation', 'escalation'
    payload         TEXT,  -- JSON
    status          TEXT DEFAULT 'pending',  -- pending, accepted, rejected, completed
    created_at      TEXT NOT NULL DEFAULT (datetime('now')),
    completed_at    TEXT
);

-- Unified event log (append-only)
CREATE TABLE events (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    timestamp   TEXT NOT NULL DEFAULT (datetime('now')),
    topic       TEXT NOT NULL,  -- 'pulse.iteration.complete', 'dream.emerged', etc.
    source      TEXT NOT NULL,  -- which subsystem
    entity_id   TEXT,
    payload     TEXT,  -- JSON
    trace_id    TEXT   -- for correlating related events
);

CREATE INDEX idx_events_topic ON events(topic);
CREATE INDEX idx_events_entity ON events(entity_id);
CREATE INDEX idx_events_time ON events(timestamp DESC);
CREATE INDEX idx_handoffs_status ON handoffs(status);

class EventBus:
    """Unified event bus for inter-system communication."""

    def __init__(self, db: StateDB):
        self.db = db
        self._subscribers: Dict[str, List[Callable]] = defaultdict(list)

    def publish(self, topic: str, source: str, payload: dict, entity_id: str = None):
        """Publish an event. Persists to event log and notifies subscribers."""
        event = {
            'topic': topic,
            'source': source,
            'entity_id': entity_id,
            'payload': json.dumps(payload),
            'timestamp': datetime.now().isoformat(),
            'trace_id': current_trace_id()
        }
        self.db.insert_event(event)

        # Notify matching subscribers
        for pattern, handlers in self._subscribers.items():
            if topic_matches(pattern, topic):
                for handler in handlers:
                    handler(event)

    def subscribe(self, pattern: str, handler: Callable):
        """Subscribe to events matching a topic pattern (supports wildcards)."""
        self._subscribers[pattern].append(handler)

1. Dream Weaver detects dream.connection_strength ≥ 0.85
2. Publishes: dream.metamorphosis.ready {dream_id, confidence, pulse_goal}
3. Cadence Router evaluates priority vs. current Pulse load
4. If approved:
   a. Creates handoff record (from=dream_weaver, to=pulse, type=metamorphosis)
   b. Spawns Pulse session with:
      - goal = dream.metamorphosis.pulse_goal
      - origin_dream_id = dream.id
      - Context: dream synthesis, approaches, connections
   c. Publishes: dream.metamorphosis.triggered
   d. Updates dream status → metamorphosed
5. On Pulse session complete:
   a. Publishes: pulse.session.status_changed {status: complete}
   b. Dream Weaver updates handoff → completed
   c. Links implementation artifacts back to dream

1. Heartbeat detects critical issue (alert_level ≥ 9)
2. Publishes: heartbeat.alert {domain, level, details}
3. Cadence receives, creates INBOX message for higher-level agent
4. Higher-level agent decides:
   a. Self-resolve → Cadence publishes resolution
   b. Delegate → Creates cadence.handoff → Pulse session
   c. Escalate → Notify human via Discord/notification

1. Pulse iteration completes
2. Publishes: pulse.iteration.completed {summary, files_modified, signal}
3. Dream Weaver Mycelium senses keywords from summary
4. If patterns align with gestating dreams → strengthens connections
5. If novel patterns → creates sensing entries for future dream seeds

                    ┌─────────────────────────────────────────┐
                    │         UNIFIED ENTITY LIFECYCLE         │
                    ├─────────────────────────────────────────┤
                    │                                         │
                    │  INCEPTION ─── born/planted/triggered   │
                    │      │                                  │
                    │      ▼                                  │
                    │  ACTIVE ───── running/incubating/live   │
                    │      │                                  │
                    │      ├──▶ SUSPENDED (paused/dormant)    │
                    │      │       │                          │
                    │      │       └──▶ ACTIVE (resumed)      │
                    │      │                                  │
                    │      ├──▶ BLOCKED (needs intervention)  │
                    │      │       │                          │
                    │      │       ├──▶ ACTIVE (unblocked)    │
                    │      │       └──▶ TERMINATED (failed)   │
                    │      │                                  │
                    │      ├──▶ TRANSFORMED (metamorphosis)   │
                    │      │       └──▶ new entity created    │
                    │      │                                  │
                    │      └──▶ COMPLETED (goal achieved)     │
                    │                                         │
                    └─────────────────────────────────────────┘

  Pulse iterations ───▶ summaries ───▶ Mycelium sensing
                                              │
                                              ▼
  Heartbeat alerts ───▶ patterns ───▶ Connection Graph
                                              │
                                              ▼
  Cadence decisions ──▶ motifs ────▶ Dream seed suggestions
                                              │
                                              ▼
                                      Enriched Pulse prompts
                                      (via enriched_spawn.py)

@dataclass
class SharedContext:
    """Cross-system context available to all subsystems."""

    # Recent activity
    active_pulse_sessions: List[SessionSummary]
    gestating_dreams: List[DreamSummary]
    recent_alerts: List[AlertSummary]
    pending_cadence_messages: List[CadenceMessage]

    # Patterns
    hot_keywords: List[str]      # from Mycelium
    recurring_issues: List[str]  # from Heartbeat
    active_themes: List[str]     # from Connection Graph

    # Resource state
    account_usage: DualMaxState   # from Pulse
    quiet_hours: bool             # from Heartbeat
    active_agents: List[str]      # from Cadence

    # Lineage
    recent_handoffs: List[Handoff]
    metamorphosis_chain: List[MetamorphosisLink]

uaos.pulse.*        — All Pulse tools (start, status, iterate, etc.)
uaos.dream.*        — All Dream Weaver tools (incubate, evolve, view, etc.)
uaos.heartbeat.*    — Heartbeat control (check, status, configure)
uaos.cadence.*      — Cadence tools (message, delegate, escalate)
uaos.context        — Get shared context
uaos.handoff        — Create/query handoffs
uaos.events         — Query event log

UAOS Daemon
├── Dream Evolution Loop (every 1h) — existing daemon logic
├── Heartbeat Check Loop (every 30m) — existing heartbeat logic
├── Event Processing Loop (continuous) — new
├── Handoff Monitor (every 5m) — new
├── Noosphere Sync (every 15m) — replaces noosphere_bridge.py
└── Account Usage Reset (daily) — from dual_runner.py

┌──────────────────────────────────────────────────────┐
│  UAOS Dashboard                                      │
├──────────────────────────────────────────────────────┤
│                                                      │
│  🟢 Pulse:  2 active sessions (14/20 iterations)    │
│  🌱 Dreams: 5 gestating, 1 emerging, 12 bloomed     │
│  💓 Beats:  Last check 12m ago, all green            │
│  🤝 Cadence: 0 pending messages                      │
│                                                      │
│  Recent Events:                                      │
│  14:23  pulse.iteration.completed  spore-app #7     │
│  14:15  dream.evolved              config-genome     │
│  14:00  heartbeat.check.completed  projects          │
│  13:45  pulse.commit               motion-to-music   │
│                                                      │
│  Active Handoffs: 1                                  │
│  🦋 dream_20250209_abc123 → pulse_session_xyz       │
│     Status: in_progress (iteration 3/10)             │
│                                                      │
│  Hot Patterns: agent, orchestration, unified, pulse  │
│                                                      │
└──────────────────────────────────────────────────────┘

[home-path]
├── state.db           # Unified SQLite database
├── graph.json         # Connection graph (Noosphere)
├── config.yaml        # Unified configuration
├── daemon.pid         # Single daemon PID
├── daemon.log         # Unified daemon log
├── events/            # Event log overflow (when DB gets large)
└── backups/           # Daily state.db snapshots

# Legacy paths (symlinked during migration):
[home-path]     → reads from state.db
[home-path] → reads from state.db
[home-path] → reads from state.db
[home-path] → reads from state.db