122 lines
3.2 KiB
Markdown
122 lines
3.2 KiB
Markdown
# AIOS Agent Audit Plane Architecture
|
|
|
|
## Overview
|
|
|
|
The AIOS Agent Audit Plane provides a complete traceability framework for all autonomous agent operations on the AIOS GitOps repository. Every agent action — from command discovery to execution to version promotion — is recorded, versioned, and auditable.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Git Repository
|
|
|
|
|
v
|
|
Agent Command Plane (agents/commands/)
|
|
| active/ running/ completed/ failed/
|
|
| + registry.yaml
|
|
v
|
|
[OpenClaw | Hermes | Codex]
|
|
|
|
|
+---> Execution
|
|
| |
|
|
| v
|
|
| evidence/<CMD-ID>/ (detection, execution, test, final)
|
|
|
|
|
+---> Audit
|
|
| |
|
|
| v
|
|
| audit/agent-runs/ (per-agent log)
|
|
| audit/command-history/ (per-command log)
|
|
| audit/version-history/ (per-baseline log)
|
|
| audit/interaction-history/ (agent conversation traces)
|
|
|
|
|
+---> Git Commit
|
|
|
|
|
v
|
|
Web UI Timeline
|
|
/admin/ai-history
|
|
```
|
|
|
|
## Data Flow
|
|
|
|
1. CMD file lands in `agents/commands/active/`
|
|
2. Agent picks it up, reads it
|
|
3. Agent executes, writes evidence to `evidence/<CMD-ID>/`
|
|
4. Agent writes audit record to `audit/agent-runs/`
|
|
5. Git commit locks the audit record
|
|
6. Web UI displays timeline from git history
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
audit/
|
|
├── agent-runs/ # Per-execution records (JSON)
|
|
├── command-history/ # Command lifecycle history
|
|
├── version-history/ # Version/baseline change log
|
|
└── interaction-history/ # Agent conversation traces
|
|
```
|
|
|
|
## Audit Record Schema
|
|
|
|
Current agent-run records use the following fields:
|
|
|
|
| Field | Description |
|
|
|-------|-------------|
|
|
| agent_run_id | Unique execution ID |
|
|
| command | Command file name |
|
|
| agent | Executing agent name |
|
|
| version | Baseline version at execution time |
|
|
| objective | Human-readable goal |
|
|
| start_time | ISO-8601 start timestamp |
|
|
| end_time | ISO-8601 completion timestamp |
|
|
| interaction_count | Agent-owner interaction turns |
|
|
| tool_call_count | Tool invocations during execution |
|
|
| changed_files | Files modified in this run |
|
|
| commit_sha | Git commit hash |
|
|
| test_result | Test verification outcome |
|
|
| final_result | SUCCESS / FAILED / PARTIAL |
|
|
| evidence_path | Link to evidence directory |
|
|
|
|
Legacy records remain valid and may use the following compatibility shape:
|
|
|
|
```json
|
|
{
|
|
"id": "",
|
|
"command": "CMD-20260708-...",
|
|
"agent": "openclaw",
|
|
"version": "V1R3C1",
|
|
"start_time": "",
|
|
"end_time": "",
|
|
"interaction_count": 0,
|
|
"objective": "",
|
|
"input_source": "git",
|
|
"actions": [],
|
|
"result": "",
|
|
"evidence": "",
|
|
"commit": "",
|
|
"approval": ""
|
|
}
|
|
```
|
|
|
|
## Ownership
|
|
|
|
- All agent modifications must be bound to a version (e.g., V1R3C1)
|
|
- Every code change must be traceable to who/what agent created it
|
|
- No agent-created changes without audit trail
|
|
|
|
## Version History
|
|
|
|
Records baseline promotions, rollbacks, and version changes.
|
|
|
|
## Interaction History
|
|
|
|
Conversation logs between agent and owner for each command execution.
|
|
|
|
## Audit Trail Requirement
|
|
|
|
All changes are tracked via Git with signed commits where possible. Every commit references the originating Command ID.
|
|
|
|
## Related
|
|
|
|
- [Agent Command Plane](../agents/README.md)
|
|
- [Baseline System](baseline-system.md)
|