Observation Logs

The observation log is a per-agent, hash-chained, append-only NDJSON log that records the agent's reasoning trace: what it did and what it learned. Unlike the audit trail (which records security events at the daemon level), observations are agent-authored records of intent and outcome.

What is an Observation?

An observation is a structured record written by the agent to document a step in its reasoning:

{
  "id": "<uuid>",
  "timestamp": "2026-02-22T12:34:56Z",
  "agent_id": "<uuid>",
  "action": "searched_web",
  "result": "Found 5 results about renewable energy",
  "tags": ["research", "web-search"],
  "prev_hash": "<sha256>",
  "hash": "<sha256>"
}

Like the audit trail, observations are hash-chained for tamper detection.

Writing an Observation

Via SDK:

#![allow(unused)]
fn main() {
agent.observe(
    "searched_web",
    "Found 5 results about renewable energy",
    vec!["research".to_string(), "web-search".to_string()],
).await?;
}

Via IPC directly:

{
  "ObservationAppend": {
    "agent_id": "<uuid>",
    "action": "completed_task",
    "result": "Summary written to /workspace/report.md",
    "tags": ["output", "success"],
    "metadata": null
  }
}

Querying Observations

# All observations for an agent
ash obs query <agent-id>

# With filters
ash obs query <agent-id> --keyword "error" --limit 10
ash obs query <agent-id> --since "2026-02-22T12:00:00Z"
ash obs query <agent-id> --until "2026-02-22T13:00:00Z"

# Query another agent's log (requires obs.query capability)
ash obs query <my-agent-id> --target <other-agent-id>

Capabilities Required

spec:
  capabilities:
    - obs.append    # Write observations
    - obs.query     # Read observations (own and others)

Storage

Observations are stored as NDJSON (newline-delimited JSON) files on disk, one file per agent. The hash chain links entries, making any post-hoc modification detectable.

Use Cases

Debugging - understand what the agent was doing before a failure
Replay - combined with workspace snapshots, reconstruct the agent's full reasoning trace
Audit - agent-authored record complementing the daemon-level audit trail
Training data - high-quality reasoning traces for fine-tuning

Scarab-Runtime Documentation