agent-governance/agents/tier0-agent/README.md

# Tier 0 Observer Agent

> Read-only agent for documentation, inventory, and plan generation

## Overview

The Tier 0 Observer Agent is a governed agent that operates in read-only mode. It can view documentation, check inventory, and generate plans, but it CANNOT execute any commands or modify any files. This is the entry-level tier for all new agents.

## Capabilities

| Capability | Allowed |
|------------|---------|
| Read files | Yes (within allowed paths) |
| List directories | Yes (within allowed paths) |
| Generate plans | Yes (draft only) |
| View logs | Yes |
| Execute commands | **No** |
| Write files | **No** |
| Access secrets | **No** |
| SSH/API access | **No** |

## Quick Start

```bash
# Enter directory
cd /opt/agent-governance/agents/tier0-agent

# Bootstrap the agent (sets up credentials, workspace)
./bootstrap.sh

# Check status
./run-agent.sh status

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

# List a directory
./run-agent.sh list /opt/agent-governance/docs

# Generate a plan (draft - cannot execute)
./run-agent.sh plan --title "Deploy service" --description "Deploy web service" --target "sandbox-01"
```

## Directory Structure

```
tier0-agent/
├── agent.py          # Main agent implementation (603 lines)
├── bootstrap.sh      # Setup and credential retrieval
├── run-agent.sh      # CLI runner script
├── config/
│   └── agent.json    # Agent configuration
├── workspace/        # Working directory for agent
├── plans/            # Generated plans (draft only)
├── logs/             # Agent activity logs
└── credentials/      # Vault credentials (populated by bootstrap)
```

## Configuration

### agent.json

```json
{
  "agent_id": "tier0-observer-001",
  "tier": 0,
  "role": "observer",
  "constraints": {
    "allowed_paths": [
      "/opt/agent-governance/docs",
      "/opt/agent-governance/inventory",
      "/opt/agent-governance/agents/tier0-agent/workspace"
    ],
    "forbidden_paths": [
      "/opt/vault",
      "/etc/shadow",
      "/root/.ssh"
    ],
    "allowed_actions": [
      "read_file",
      "list_directory",
      "generate_plan",
      "view_logs"
    ],
    "forbidden_actions": [
      "execute_command",
      "write_file",
      "delete_file",
      "ssh",
      "access_secrets"
    ]
  }
}
```

## CLI Commands

### Status
```bash
./run-agent.sh status
```
Shows agent status including:
- Agent ID and tier
- Connection to governance ledger
- Heartbeat status
- Revocation status

### Read File
```bash
./run-agent.sh read <file_path>
```
Reads a file if within allowed paths. Blocked paths return an error.

### List Directory
```bash
./run-agent.sh list <directory_path>
```
Lists directory contents if within allowed paths.

### Generate Plan
```bash
./run-agent.sh plan \
    --title "Plan title" \
    --description "What this plan does" \
    --target "sandbox-01" \
    --steps '["step1", "step2"]'
```
Creates a draft plan. Plans are saved to `plans/` directory but cannot be executed by Tier 0.

## Governance Integration

### Ledger Logging

All actions are logged to SQLite:

```python
def log_action(action: str, success: bool, data: Any = None):
    conn = sqlite3.connect(LEDGER_DB)
    cursor = conn.cursor()
    cursor.execute("""
        INSERT INTO agent_actions
        (timestamp, agent_id, tier, action, decision, success)
        VALUES (?, ?, ?, ?, ?, ?)
    """, [
        datetime.now(timezone.utc).isoformat(),
        AGENT_ID,
        AGENT_TIER,
        action,
        "EXECUTE" if success else "BLOCKED",
        1 if success else 0
    ])
    conn.commit()
```

### Heartbeat

Agent sends heartbeat to DragonflyDB:

```python
def update_heartbeat():
    redis_client.setex(
        f"agent:heartbeat:{AGENT_ID}",
        30,  # 30 second TTL
        json.dumps({
            "timestamp": datetime.now(timezone.utc).isoformat(),
            "status": "active",
            "tier": AGENT_TIER
        })
    )
```

### Revocation Check

Before each action, agent checks if it has been revoked:

```python
def is_revoked() -> bool:
    return redis_client.exists(f"agent:revoked:{AGENT_ID}")
```

## Path Validation

```python
def is_path_allowed(path: Path) -> bool:
    """Check if path is within allowed paths and not forbidden"""
    # Check forbidden first
    for forbidden in FORBIDDEN_PATHS:
        if str(path).startswith(forbidden):
            return False

    # Check allowed
    for allowed in ALLOWED_PATHS:
        if path.is_relative_to(allowed):
            return True

    return False
```

## Promotion to Tier 1

To be promoted to Tier 1, this agent must demonstrate:

| Requirement | Threshold |
|-------------|-----------|
| Total actions | 100+ |
| Consecutive compliant runs | 10+ |
| Error rate | < 5% |
| Days active | 7+ |

Promotion is tracked in `agent_metrics` table:

```sql
SELECT compliant_runs, consecutive_compliant, current_tier
FROM agent_metrics
WHERE agent_id = 'tier0-observer-001';
```

## Testing

```bash
# Test bootstrap
./bootstrap.sh

# Test status
./run-agent.sh status

# Test read (should succeed)
./run-agent.sh read /opt/agent-governance/docs/README.md

# Test forbidden read (should fail)
./run-agent.sh read /etc/shadow

# Test that execution is blocked
./run-agent.sh exec ls  # Should fail - Tier 0 cannot execute
```

## Error Handling

| Error | Cause | Resolution |
|-------|-------|------------|
| `PATH_FORBIDDEN` | Attempted access to forbidden path | Use allowed paths only |
| `ACTION_FORBIDDEN` | Attempted forbidden action | Upgrade to higher tier |
| `REVOKED` | Agent has been revoked | Contact governance admin |
| `HEARTBEAT_TIMEOUT` | Lost connection to DragonflyDB | Check DragonflyDB status |

## Architecture Reference

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

See also:
- [Tier 1 Agent](../tier1-agent) - Execution-capable agent (next tier)
- [Agents Overview](../README.md) - All agents

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