diff --git a/infrastructure-control.prose.md b/infrastructure-control.prose.md new file mode 100644 index 0000000..9da55d3 --- /dev/null +++ b/infrastructure-control.prose.md @@ -0,0 +1,142 @@ +--- +kind: pattern +name: infrastructure-control +description: > + 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: + +```yaml +## 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: + +```yaml +## Maintains +- harness-litellm.status == "healthy" +- harness-nginx.status == "healthy" + +## Enforce +- If container unhealthy → `docker compose up -d ` + - 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: + +```yaml +## 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.