Agent Interaction Logger

README

# Agent Interaction Logger (AIL)

**Goal**: Log and monitor real-time agent communications in OpenClaw.

## 🎯 Quick Answer

**Question**: Is skills better or plugins better for this?  
**Answer**: **PLUGIN** (see [COMPARISON.md](COMPARISON.md) for full analysis)

## 📚 Documentation Index

### 🚀 Getting Started
- **[QUICK-START.md](docs/QUICK-START.md)** ⭐ **START HERE** - Step-by-step setup and testing guide
- **[SUMMARY.txt](SUMMARY.txt)** - TL;DR of everything

### 📖 Understanding the Options
- **[COMPARISON.md](docs/COMPARISON.md)** - Plugins vs Skills vs Internal Hooks comparison table
- **[ARCHITECTURE-DIAGRAM.md](docs/ARCHITECTURE-DIAGRAM.md)** - Visual diagrams of how it all works
- **[ALTERNATIVE-APPROACHES.md](docs/ALTERNATIVE-APPROACHES.md)** - Code examples for each approach

### 🧪 Testing
- **[test-scenario.md](docs/test-scenario.md)** - Test scenarios to validate functionality

## 📁 Implementation Files

### Main Plugin (USE THIS)
- **[plugin.ts](plugin.ts)** - Complete implementation with all 9 hooks
- **[openclaw.plugin.json](openclaw.plugin.json)** - Plugin manifest
- **[package.json](package.json)** - Package metadata

## ⚡ Quick Start (3 Steps)

```bash
# 1. Register plugin in config
echo '{
  "plugins": { "dirs": ["/home/ubuntu/openclaw/experiment-mitm-agent"] }
}' >> ~/.openclaw/config.json

# 2. Start gateway
openclaw gateway run

# 3. Test (in another terminal)
openclaw agent --message "Create a team with 2 agents to research OpenClaw"
```

**Expected**: You'll see `[AIL] Plugin loaded!` and real-time event logs!

## ✅ What This Plugin Does

- ✅ **Monitors** all agent lifecycle events (spawn → execute → end)
- ✅ **Monitors** LLM input/output in real-time
- ✅ **Injects** messages into running agents via API
- ✅ **Intercepts** and can replace agent replies before they're sent
- ✅ **Reads** full conversation history from any agent
- ✅ **Tracks** active agents and their status

## 🔧 Current Status

Feature | Status
--------|--------
Basic monitoring | ✅ Implemented
Message injection | ⚠️ Code ready (commented out)
Reply interception | ⚠️ Code ready (commented out)
Cross-agent context sharing | 📝 See QUICK-START.md Advanced section

## 🏗️ Architecture

```
Your Plugin (all hooks)
    ↓ ↑
OpenClaw Gateway
    ↓ ↑
Agent A ←→ Agent B ←→ Agent C
```

The plugin sits between the gateway and agents, seeing and controlling all communication.

## 📊 Available Hooks (All 28)

The plugin uses 9 key hooks:

1. `subagent_spawning` - Detect agent spawn
2. `subagent_spawned` - Agent ready (has runId)
3. `llm_input` - See prompts going to LLM
4. `llm_output` - See LLM responses
5. `before_agent_reply` - Intercept replies (can short-circuit!)
6. `message_sending` - Before external send
7. `message_sent` - After send confirmed
8. `message_received` - Inbound messages
9. `subagent_ended` - Agent finished (read full history)

## 🆘 Help

- **Setup issues?** See [QUICK-START.md](docs/QUICK-START.md) debugging section
- **Understanding approaches?** See [COMPARISON.md](docs/COMPARISON.md)
- **Need examples?** See [ALTERNATIVE-APPROACHES.md](docs/ALTERNATIVE-APPROACHES.md)
- **Architecture questions?** See [ARCHITECTURE-DIAGRAM.md](docs/ARCHITECTURE-DIAGRAM.md)

## 🎓 Key Takeaways

1. **Plugins** = Full logging capability (28 hooks, runtime API)
2. **Skills** = User-invoked only (no auto-intercept)
3. **Internal Hooks** = Limited events (12 vs 28, missing subagent hooks)

**For logging agent interactions: Use the Plugin approach** (already implemented in `plugin.ts`)