prose-contracts/infrastructure-control.prose.md

kind, name, description

kind	name	description
pattern	infrastructure-control	Architectural pattern showing how OpenProse contracts connect to Gitea, containers, and remote agents to enforce conditions across all environments. Not an executable contract — a reference model.

The Full Control Stack

                    ┌─────────────────────────┐
                    │   OpenProse Contract    │
                    │  (declares what's true) │
                    └──────────┬──────────────┘
                               │
          ┌────────────────────┼────────────────────┐
          ▼                    ▼                    ▼
   ┌─────────────┐    ┌──────────────┐    ┌──────────────┐
   │   Agent     │    │   Agent      │    │   Agent      │
   │   (pi)      │    │   (Tanko)    │    │   (Mumuni)   │
   │   CT 100    │    │   CT 112     │    │   CT 114     │
   └──────┬──────┘    └──────┬───────┘    └──────┬───────┘
          │                  │                    │
          └──────────────────┼────────────────────┘
                             ▼
                    ┌─────────────────┐
                    │   Gitea Repos   │
                    │  (source of     │
                    │   truth for     │
                    │   code +        │
                    │   contracts)    │
                    └────────┬────────┘
                             │
          ┌──────────────────┼────────────────────┐
          ▼                  ▼                    ▼
   ┌─────────────┐    ┌──────────────┐    ┌──────────────┐
   │ CT 116      │    │ Authentik    │    │ Zulip        │
   │ (LiteLLM,   │    │ CT .11       │    │ CT .117      │
   │  nginx,     │    │ (OIDC auth)  │    │ (messaging)  │
   │  router)    │    │              │    │              │
   └─────────────┘    └──────────────┘    └──────────────┘

How Each Layer Connects

1. Code → Gitea

The contract enforces code state via git operations:

## Enforce
- git pull origin main on CT 116 — ensures latest config is deployed
- git diff HEAD...origin/main — warns if drift is detected
- git commit + push after auto-fix — changes are versioned

What the agent does: Runs git commands via SSH to check and update repos. What enforces it: Agent has SSH keys and Gitea credentials.

2. Contracts → Agents

Each agent runs OpenProse contracts in its own environment:

Agent	Runs contracts via	Can reach
Abiba (pi)	prose run in-session	CT 116 (SSH), Zulip API, Gitea API
Tanko (Hermes)	Hermes Gateway with OpenProse skill	CT 112, Zulip API, Gitea API
Mumuni (Hermes)	Hermes Gateway with OpenProse skill	CT 114, Zulip API, Gitea API

What enforces it: Each agent has SSH keys to the environments it manages.

3. Contracts → Containers

The contract enforces container state via Docker commands:

## Maintains
- harness-litellm.status == "healthy"
- harness-nginx.status == "healthy"

## Enforce
- If container unhealthy → `docker compose up -d <name>`
  - Requires: SSH access to host
  - Verifies: `docker ps` after restart

What the agent does: SSH to the host, run Docker commands. What enforces it: SSH key + Docker socket access on the target CT.

4. Contracts → Remote Agents (Tanko, Mumuni)

When a contract needs another agent to act:

## If out of scope
- If Authentik server down → relay to Mumuni (has access)
  - Creates relay message with diagnostic data
  - Mumuni's contract picks it up and acts

What the agent does: Creates a relay message via RA-H OS. What enforces it: Mumuni's own contracts check relays on wake.

Access Matrix

Each agent needs explicit credentials to each environment:

Environment	Abiba (pi)	Tanko (Hermes)	Mumuni (Hermes)
Gitea	✅ API token	Need to add	Need to add
CT 116 (LiteLLM)	✅ SSH key	Need to add	❌ (has own CTs)
Zulip API	✅ Bot token	✅ Bot token	✅ Bot token
RA-H OS	✅ MCP bridge	✅ MCP bridge	✅ MCP bridge
Authentik	❌ No SSH	❌ No SSH	❌ No SSH

The Gap (What's Missing)

Currently, the contracts CAN:

Capability	Works?	How
Read container state	✅ SSH to CT 116
Restart containers	✅ SSH + docker compose
Commit to Gitea	✅ API token
Alert via Zulip	✅ Bot API
Log to KG	✅ MCP bridge

But they CANNOT yet:

Gap	Why	Fix
Push code to Tanko's CT	No SSH key for CT 112	Add Abiba's key to CT 112
Restart Hermes gateway	No remote command	Add hermes gateway restart via SSH
Auto-merge PRs	Needs Gitea write token	Already have it, need to wire

Reference Implementation

The litellm-self-heal contract already implements most of this pattern:

1. It checks conditions (container health, endpoints)
2. It enforces fixes (docker compose up)
3. It logs results (knowledge graph)
4. It alerts via Zulip DM

The same pattern extends to any environment where the agent has credentials.