Agent Blackbox

Runtime blackbox recorder for agent workflows using JEP events, HJS evidence references, and JAC declared dependency chains.

Experimental implementation seed.

Agent Blackbox supports incident review and chain reconstruction. It does not determine legal liability, factual truth, regulatory compliance, or moral responsibility.

---

What This Is

Agent Blackbox records structured execution traces for agent workflows.

For each traced operation it can record:

• who executed the operation;
• when it happened;
• input/output/error digests;
• a JEP v0.6-style event;
• a JAC v0.5-style dependency edge;
• optional HJS-style evidence references;
• a local JSONL blackbox log;
• an incident review report.

It is designed to help operators answer:

What happened?
Which event failed?
Which prior event was this based on?
Which declared dependency path led here?
Which evidence references are available for review?

It is not designed to answer:

Who is legally liable?
Who is morally at fault?
Was the system compliant?
Was the model correct?
Was the log complete?

---

Relationship to JEP / HJS / JAC

JEP = atomic signed judgment events
HJS = accountability receipts, archive/privacy/evidence lifecycle
JAC = declared dependency and accountability chains
Agent Blackbox = runtime trace recorder and incident review utility

Aligned with:

• JEP v0.6: https://github.com/hjs-spec/jep-v06
• JEP API v0.6: https://github.com/hjs-spec/jep-api
• HJS v0.5: https://github.com/hjs-spec/hjs-05
• JAC v0.5: https://github.com/hjs-spec/jac-agent-02

Public drafts:

• JEP-Core: https://datatracker.ietf.org/doc/draft-wang-jep-judgment-event-protocol/
• HJS: https://datatracker.ietf.org/doc/draft-wang-hjs-accountability/
• JAC: https://datatracker.ietf.org/doc/draft-wang-jac/

---

Core Features

Feature	Description
Trace decorator	Wrap agent functions and record runtime events
JEP-style event	Emits JEP v0.6-style J/D/T/V event objects
JAC chain extension	Uses ext["https://jac.org/chain"] instead of deprecated task_based_on
HJS evidence refs	Records input/output/error digests as evidence references
Local blackbox log	Stores JSONL event records for later review
Incident review	Reconstructs declared chain fragments around an incident
Integrity check	Verifies event hashes and Ed25519 signatures generated by this library

---

Installation

Install the published distribution:

pip install agent-blackbox-jep==0.2.0a2

The PyPI distribution is named agent-blackbox-jep because agent-blackbox is unavailable on PyPI. Python imports remain agent_blackbox, and the CLI commands remain agent-blackbox and blame-finder.

For local development:

pip install -e .

---

Basic Usage

from agent_blackbox import AgentBlackbox

blackbox = AgentBlackbox(storage="./blackbox_logs")

@blackbox.trace(agent_name="CoderAgent")
def write_code(requirement: str) -> str:
    return "print('hello world')"

result = write_code("write a hello world")

# Review the latest event
event_hash = list(blackbox.events.keys())[-1]
report = blackbox.review_incident(event_hash)

print(report["candidate_failure_node"])
print(report["chain"])

---

JAC v0.5 Chain Extension

Agent Blackbox does not use the deprecated top-level task_based_on field.

It uses:

{
  "ext": {
    "https://jac.org/chain": {
      "based_on": "sha256:...",
      "based_on_type": "jep-event",
      "relation": "derived-from",
      "observed_log_assumption": "partial"
    }
  },
  "ext_crit": ["https://jac.org/chain"]
}

---

Incident Review Output

Example:

{
  "incident": "sha256:...",
  "candidate_failure_node": "CoderAgent",
  "diagnostic_summary": "The selected event has status failed. Review declared parents and evidence references.",
  "review_score": 0.72,
  "chain": [
    {
      "event_hash": "sha256:...",
      "agent": "PlannerAgent",
      "status": "success"
    },
    {
      "event_hash": "sha256:...",
      "agent": "CoderAgent",
      "status": "failed"
    }
  ],
  "boundary": {
    "not_legal_liability": true,
    "not_factual_causality_proof": true,
    "not_compliance_determination": true
  }
}

---

CLI

Review an incident:

agent-blackbox review sha256:...

Show a chain tree:

agent-blackbox tree sha256:...

Verify an event:

agent-blackbox verify sha256:...

---

Boundary Statement

A valid Agent Blackbox trace means a local runtime event was recorded and structurally linked.

It does not prove:

• legal liability;
• factual causality;
• regulatory compliance;
• complete-log availability;
• model correctness;
• moral responsibility.

A valid signature proves integrity of the event under the local key used by this library.

It does not prove the underlying claim is true.

---

Status

Version: 0.2.0a2
Status: experimental implementation seed

---

License

MIT

Runtime and verification notes

See HARDENING.md for supported behavior, regression checks, and compatibility boundaries.