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)
    |
    +---> 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

Audit Record Schema

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

Agent Command Plane
Baseline System =======

AIOS Agent Audit Plane

Purpose

Every agent action is recorded. All code changes are traceable to:

Who made the change
Why the change was made
When it was made
Which version introduced it
What test results showed

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

Agent Run Record

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

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 tracked via Git with signed commits where possible. Every commit message references the originating Command ID.

4d18ee0 (feat(cmd): enable Agent Command Plane, audit plane, and Web UI dashboard)

3.4 KiB Raw Blame History