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

CMD file lands in agents/commands/active/
Agent picks it up, reads it
Agent executes, writes evidence to evidence/<CMD-ID>/
Agent writes audit record to audit/agent-runs/
Git commit locks the audit record
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:

{
  "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.

3.2 KiB Raw Blame History