Add Phase 10-12 implementation: multi-tenant, marketplace, observability

Major additions: - marketplace/: Agent template registry with FTS5 search, ratings, versioning - observability/: Prometheus metrics, distributed tracing, structured logging - ledger/migrations/: Database migration scripts for multi-tenant support - tests/governance/: 15 new test files for phases 6-12 (295 total tests) - bin/validate-phases: Full 12-phase validation script New features: - Multi-tenant support with tenant isolation and quota enforcement - Agent marketplace with semantic versioning and search - Observability with metrics, tracing, and log correlation - Tier-1 agent bootstrap scripts Updated components: - ledger/api.py: Extended API for tenants, marketplace, observability - ledger/schema.sql: Added tenant, project, marketplace tables - testing/framework.ts: Enhanced test framework - checkpoint/checkpoint.py: Improved checkpoint management Archived: - External integrations (Slack/GitHub/PagerDuty) moved to .archive/ - Old checkpoint files cleaned up Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-24 18:39:47 -05:00
parent 4b5b3b0a2d
commit 8c6e7831e9
184 changed files with 16249 additions and 13673 deletions
@@ -1,34 +1,255 @@
-# Tier0 Agent
+# Tier 0 Observer Agent

-> Observer-tier agent (read-only)
+> Read-only agent for documentation, inventory, and plan generation

 ## Overview

-This directory contains observer-tier agent (read-only).
+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.

-## Key Files
+## Capabilities

-| File | Description |
-|------|-------------|
-| `agent.py` | Python module |
-| `run-agent.sh` | Shell script |
-| `bootstrap.sh` | Shell script |
+| 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** |

-## Interfaces / APIs
+## Quick Start

-*Document any APIs, CLI commands, or interfaces here.*
+```bash
+# Enter directory
+cd /opt/agent-governance/agents/tier0-agent

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

-** Not Started**
+# Check status
+./run-agent.sh status

-See [STATUS.md](./STATUS.md) for detailed progress tracking.
+# 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](/opt/agent-governance/docs/ARCHITECTURE.md).
+Part of the [Agent Governance System](../../docs/ARCHITECTURE.md).

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

 ---
-*Last updated: 2026-01-23 23:25:09 UTC*
+*Last updated: 2026-01-24*