# sagarchhatrala/horizon-agent-containment architecture

> Architecture diagram of the GitHub repository sagarchhatrala/horizon-agent-containment, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sagarchhatrala/horizon-agent-containment
- Repository: https://github.com/sagarchhatrala/horizon-agent-containment

## Overview

HAC is a deterministic containment engine for long-horizon agent actions. An agent action enters through the engine directly or through the MCP adapter; HAC validates it, applies it to a hypothetical security state while preserving artifact provenance and graph relationships, derives capabilities, and evaluates invariants. The engine commits allowed state changes and blocks invalid or malformed actions. The optional ACB bridge adds action-level enforcement. The Streamlit demo and documented attack scenarios present the engine’s decisions and state. Core relationships are grounded in excerpts and README; links to unsampled demo/scenario implementations are documented rather than inferred.

Main entry points: [`src/hac/engine.py`](https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/engine.py) (HAC Engine), [`src/hac/state.py`](https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/state.py) (Security State), [`src/hac/transitions.py`](https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/transitions.py) (Action Validation and Transitions), [`adapters/acb.py`](https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/adapters/acb.py) (ACB Bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Action Interfaces"]
  node_mcp["MCP Adapter<br/>[mcp.py]"]
  node_acb["ACB Bridge<br/>[acb.py]"]
  node_simulator["Simulator Adapter<br/>[simulator.py]"]
end

subgraph group_engine["Containment Engine"]
  node_engine["HAC Engine<br/>[engine.py]"]
  node_decisions["Decision Model<br/>[decisions.py]"]
  node_transitions["Action Validation and Transitions<br/>[transitions.py]"]
  node_evaluator["Invariant Evaluation<br/>[evaluator.py]"]
  node_capabilities["Capability Derivation<br/>[capabilities.py]"]
  node_invariants["Security Invariants<br/>[invariants.py]"]
  node_authority["Authority Checks<br/>[authority.py]"]
end

subgraph group_state["Security State"]
  node_provenance["Provenance Lineage<br/>[provenance.py]"]
  node_state["Security State<br/>[state.py]"]
  node_graph["Capability Graph<br/>[graph.py]"]
  node_models["Domain Models<br/>[models.py]"]
end

subgraph group_demo["Scenarios and Demo"]
  node_scenario["Scenario Workflows"]
  node_demo["Streamlit Demo<br/>[app.py]"]
end

node_agent(("AI Agent"))
node_acb_service["ACB Enforcer"]
node_external["External Resources"]

node_agent -->|"sends tool request"| node_mcp
node_mcp -->|"evaluates action"| node_engine
node_agent -.->|"submits action"| node_acb
node_acb -->|"evaluates action"| node_engine
node_acb -->|"optionally enforces"| node_acb_service
node_simulator -->|"evaluates action"| node_engine
node_engine -->|"validates and applies"| node_transitions
node_engine -->|"evaluates resulting state"| node_evaluator
node_engine -->|"reads and commits"| node_state
node_engine -->|"returns decision"| node_decisions
node_transitions -->|"clones and updates"| node_state
node_transitions -->|"inherits lineage"| node_provenance
node_transitions -->|"records relationships"| node_graph
node_evaluator -->|"derives capabilities"| node_capabilities
node_evaluator -->|"checks invariants"| node_invariants
node_capabilities -->|"reads state and history"| node_state
node_authority -->|"checks delegations"| node_state
node_state -->|"stores graph"| node_graph
node_scenario -.->|"provides actions"| node_engine
node_demo -.->|"demonstrates decisions"| node_engine
node_external -.->|"modeled in actions"| node_engine

click node_mcp "https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/adapters/mcp.py"
click node_acb "https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/adapters/acb.py"
click node_engine "https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/engine.py"
click node_decisions "https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/decisions.py"
click node_transitions "https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/transitions.py"
click node_evaluator "https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/evaluator.py"
click node_capabilities "https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/capabilities.py"
click node_invariants "https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/invariants.py"
click node_authority "https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/authority.py"
click node_provenance "https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/provenance.py"
click node_state "https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/state.py"
click node_graph "https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/graph.py"
click node_models "https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/models.py"
click node_scenario "https://github.com/sagarchhatrala/horizon-agent-containment/tree/main/scenarios"
click node_demo "https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/demo/app.py"
click node_simulator "https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/adapters/simulator.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp,node_acb,node_simulator toneBlue
class node_engine,node_decisions,node_transitions,node_evaluator,node_capabilities,node_invariants,node_authority toneAmber
class node_provenance,node_state,node_graph,node_models toneMint
class node_scenario,node_demo toneRose
class node_agent,node_acb_service,node_external toneIndigo
```

## Components

### Action Interfaces

- [MCP Adapter](https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/adapters/mcp.py): `adapters/mcp.py`
- [ACB Bridge](https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/adapters/acb.py): `adapters/acb.py`
- [Simulator Adapter](https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/adapters/simulator.py): `adapters/simulator.py`

### Containment Engine

- [HAC Engine](https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/engine.py): `src/hac/engine.py`
- [Decision Model](https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/decisions.py): `src/hac/decisions.py`
- [Action Validation and Transitions](https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/transitions.py): `src/hac/transitions.py`
- [Invariant Evaluation](https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/evaluator.py): `src/hac/evaluator.py`
- [Capability Derivation](https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/capabilities.py): `src/hac/capabilities.py`
- [Security Invariants](https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/invariants.py): `src/hac/invariants.py`
- [Authority Checks](https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/authority.py): `src/hac/authority.py`

### Security State

- [Provenance Lineage](https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/provenance.py): `src/hac/provenance.py`
- [Security State](https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/state.py): `src/hac/state.py`
- [Capability Graph](https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/graph.py): `src/hac/graph.py`
- [Domain Models](https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/src/hac/models.py): `src/hac/models.py`

### Scenarios and Demo

- [Scenario Workflows](https://github.com/sagarchhatrala/horizon-agent-containment/tree/main/scenarios): `scenarios`
- [Streamlit Demo](https://github.com/sagarchhatrala/horizon-agent-containment/blob/main/demo/app.py): `demo/app.py`

### Other components

- **AI Agent**
- **ACB Enforcer**
- **External Resources**

## Connections

- AI Agent → MCP Adapter: sends tool request (evidence: `adapters/mcp.py`)
- MCP Adapter → HAC Engine: evaluates action (evidence: `adapters/mcp.py`)
- AI Agent → ACB Bridge: submits action (evidence: `README.md`)
- ACB Bridge → HAC Engine: evaluates action (evidence: `adapters/acb.py`)
- ACB Bridge → ACB Enforcer: optionally enforces (evidence: `adapters/acb.py`)
- Simulator Adapter → HAC Engine: evaluates action (evidence: `adapters/simulator.py`)
- HAC Engine → Action Validation and Transitions: validates and applies (evidence: `src/hac/engine.py`)
- HAC Engine → Invariant Evaluation: evaluates resulting state (evidence: `src/hac/engine.py`)
- HAC Engine → Security State: reads and commits (evidence: `src/hac/engine.py`)
- HAC Engine → Decision Model: returns decision (evidence: `src/hac/engine.py`)
- Action Validation and Transitions → Security State: clones and updates (evidence: `src/hac/transitions.py`)
- Action Validation and Transitions → Provenance Lineage: inherits lineage (evidence: `src/hac/transitions.py`)
- Action Validation and Transitions → Capability Graph: records relationships (evidence: `src/hac/transitions.py`)
- Invariant Evaluation → Capability Derivation: derives capabilities (evidence: `src/hac/evaluator.py`)
- Invariant Evaluation → Security Invariants: checks invariants (evidence: `src/hac/evaluator.py`)
- Capability Derivation → Security State: reads state and history (evidence: `src/hac/capabilities.py`)
- Authority Checks → Security State: checks delegations (evidence: `src/hac/authority.py`)
- Security State → Capability Graph: stores graph (evidence: `src/hac/state.py`)
- Scenario Workflows → HAC Engine: provides actions (evidence: `README.md`)
- Streamlit Demo → HAC Engine: demonstrates decisions (evidence: `README.md`)
- External Resources → HAC Engine: modeled in actions (evidence: `README.md`)
