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 Core 0.7-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 Core 0.7: https://github.com/hjs-spec/jep-core
• JEP API: https://github.com/hjs-spec/jep-api
• HJS archive/evidence companion: https://datatracker.ietf.org/doc/draft-wang-hjs-accountability/
• 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

JEP Core 0.7 boundary

Fresh Agent Blackbox events use stable id and Event Identity (who,id) and do not add a mandatory Core nonce. Event Hash remains the key used by this local blackbox store because it identifies the exact signed artifact.

When a recorded parent is available locally, the JEP ref uses a typed jep:event reference with Event Identity plus an optional exact-artifact hash. JAC extension metadata continues to carry runtime dependency-chain semantics. Chain reconstruction, causality, authority, and termination cascade are not JEP Core semantics.

Historical pre-0.7 imported events preserve their original signed members, including a historical nonce when present; they are not silently rewritten into 0.7.

Installation

Install the published distribution:

pip install --pre agent-blackbox-jep

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: see [current releases](https://github.com/hjs-spec/Agent-Blackbox/releases) (alpha).
Status: experimental implementation seed

License

MIT

Runtime and verification notes

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