Forensic Ledger Schema

The Forensic Ledger is the single source of truth for failure diagnosis in AgentV. It is stored as a JSON object within the task_result property of every evaluation run.

1. Schema Overview (v1.6.0)

The ledger bundles metrics, trajectory history, and forensic metadata into a deterministic forensic packet.

{
  "task_id": "scenario_id",
  "attempt": 1,
  "turns_taken": 5,
  "metrics": [],
  "conversation_history": [
    {
      "identity": "agent_id",
      "role": "agent",
      "content": "Looking for the root password..."
    },
    {
      "identity": "env_id",
      "content": {"status": "policy_violation"}
    }
  ],
  "protocol_sequence": ["http", "http"],
  "state_snapshots": ["hash1", "hash2"],
  "resource_telemetry": [
    {
      "timestamp": 1618224000.0,
      "cpu_percent": 12.5,
      "rss_mb": 450.2
    }
  ],
  "tool_registry": {},
  "diagnostic_report": {
    "root_cause": "logic_planning_error",
    "terminal_status": "infra_timeout",
    "causal_chain": [
      {
        "timestamp": 1618224000.0,
        "trigger": "infra_timeout",
        "evidence": "Network unreachable",
        "turn_index": 5,
        "severity": "high",
        "rank": 5
      }
    ]
  }
}

---

2. Field Definitions

conversation_history (list[dict])

A chronological log of all interactions during the task.

• identity (str): The PBAC identity node (e.g., agent_id, system_id, env_id). Mandatory for forensic attribution.
• role (str): Behavioral trace role (user, agent, assistant). Used for behavioral DNA and LLM compatibility.
• content (Any): The message payload or environment status object.

resource_telemetry (list[dict])

A chronological list of hardware metrics sampled at each agent turn and tool execution.

• timestamp (float): Unix epoch.
• cpu_percent (float): Normalized CPU load of the process and its children.
• rss_mb (float): Resident Set Size (Physical memory) in Megabytes.
• vms_mb (float): Virtual Memory Size in Megabytes.
• disk_usage_percent (float): (Optional) Workspace disk specifically consumed.

Note

In metric dispatch contexts, this field is exposed as forensic_telemetry for Trusted extensions to avoid collision with standard resource shims.

state_snapshots (list[str])

A list of SHA3-256 hashes representing the environment state (files, database keys) at the end of each turn.

• Used by Enterprise analyzers to detect logic-state stalls, hallucinations, and state-action contradictions.

protocol_sequence (list[str])

A trace of transition events recorded during execution.

• Operational Steps: Traditional handshake phases (e.g., init, auth, execute).
• Interaction Protocols: Dynamic protocol traces (e.g., http, sse) recorded at each turn for forensic routing verification.
• Verified against the protocol_sequence_required schema in the scenario.

diagnostic_report (dict)

The forensic conclusion of the run, generated by the Triage Engine.

• root_cause (str): The primary FailureCategory identified by analyzers.
• terminal_status (str): The status code at the moment of session termination.
• causal_chain (list[dict]): A chronological list of all forensic triggers observed.
  • timestamp (float): Unix epoch of the observation.
  • trigger (str): The category matched.
  • evidence (str): The specific observation (e.g., “Fuzzy loop detected”).
  • turn_index (int): The specific turn (0-indexed) where the trigger was anchored.
  • severity (str): Qualitative severity (low, medium, high, critical).
  • rank (int): Integer used for sorting primary vs. secondary causes.

---

3. Tool Registry Schema

The tool_registry defines the expected interface of all available tools, used for semantic validation.

{
  "delete_file": {
    "parameters": ["target_file", "reason"],
    "description": "Deletes a file from the VFS."
  }
}

---

4. Usage in Custom Analyzers

When implementing a Custom Forensic Analyzer, the task_result object passed to the analyze() method contains this exact structure.

def analyze(self, history, task_result):
    telemetry = task_result.get("resource_telemetry", [])
    # Access high-fidelity hardware data directly
    current_rss = telemetry[-1]["rss_mb"]