# Tier 1 Agent

> Operator-tier agent with execution capabilities

## Overview

The Tier 1 Operator Agent is a governed agent that can execute approved plans, run infrastructure commands (Terraform, Ansible), and access sandbox environments. It is promoted from Tier 0 after demonstrating compliant behavior.

## Capabilities

| Capability | Tier 0 | Tier 1 |
|------------|--------|--------|
| Read files | Yes | Yes |
| List directories | Yes | Yes |
| Generate plans | Yes | Yes |
| Execute commands | No | **Yes** |
| Write files | No | **Yes** |
| Terraform plan/apply | No | **Yes** |
| Ansible check/run | No | **Yes** |
| Docker run | No | **Yes** |
| SSH access | No | **Yes** (sandbox only) |
| Access secrets | No | No |

## Constraints

### Allowed Targets
- `localhost`
- `sandbox-*`

### Forbidden Targets
- `prod-*`
- `staging-db-*`

### Forbidden Actions
- `delete_production` - Cannot delete production resources
- `access_vault_root` - Cannot access Vault root credentials
- `modify_governance` - Cannot modify governance rules

## Quick Start

```bash
# Bootstrap the agent
./bootstrap.sh

# Check status
./run-agent.sh status

# Execute a command
./run-agent.sh exec ls -la

# Read a file
./run-agent.sh read /opt/agent-governance/docs/README.md

# Write a file
./run-agent.sh write workspace/test.txt --content "Hello World"

# Generate and execute a plan
./run-agent.sh plan \
    --title "Test deployment" \
    --description "Deploy test service" \
    --target "sandbox-01" \
    --steps '["echo step1", "echo step2"]'

./run-agent.sh run-plan plan-XXXXXXXX-XXXXXX-XXXXXXXX
```

## Infrastructure Commands

### Terraform
```bash
# Plan
./run-agent.sh tf-plan /opt/agent-governance/sandbox/terraform

# Apply
./run-agent.sh tf-apply /opt/agent-governance/sandbox/terraform
```

### Ansible
```bash
# Check mode (dry-run)
./run-agent.sh ansible-check playbook.yml -i inventory.yml

# Run
./run-agent.sh ansible-run playbook.yml -i inventory.yml --limit sandbox-01
```

### Docker
```bash
./run-agent.sh docker alpine --cmd "echo hello"
./run-agent.sh docker nginx -v /data:/usr/share/nginx/html
```

## Governance Integration

All actions are logged to the governance ledger:
- `/opt/agent-governance/ledger/governance.db`

The agent:
- Checks revocation status before each action
- Updates heartbeat in DragonflyDB
- Logs all actions with decision (EXECUTE/BLOCKED/PLAN)
- Tracks compliant runs for promotion eligibility

## Promotion to Tier 2

Requirements (from config):
- Minimum 10 compliant runs
- Minimum 5 consecutive compliant runs
- Required actions: `ansible_run`, `terraform_apply`
- Maximum 0 violations in 30 days

## Directory Structure

```
tier1-agent/
├── agent.py          # Main agent implementation
├── run-agent.sh      # Runner script
├── bootstrap.sh      # Setup script
├── config/
│   └── agent.json    # Agent configuration
├── workspace/        # Working directory
├── plans/            # Generated plans
├── logs/             # Agent logs
└── credentials/      # Agent credentials (from Vault)
```

## Testing

```bash
# Test that forbidden actions are blocked
./run-agent.sh test-forbidden
```

## Architecture Reference

Part of the [Agent Governance System](../../docs/ARCHITECTURE.md).

---
*Last updated: 2026-01-24*