Joltrin

Documentation

Joltrin checks an AI agent's action against the recorded trace before it commits, independent of what the agent claims. This page is a path from the idea to a working integration.

1. What it protects against

An agent can propose a destructive action and report success from its own context. If the same agent also decides the action is safe, both judgments can fail for the same reason. The danger in production is that correlated failure.

2. The independent verifier model

The agent emits intent. The verifier checks that intent against the steps the server has recorded and the runbook's preconditions and safety rules. It does not use the agent's claims, prompt context, self-evaluation or confidence. The check and the commit are one call, so a step is recorded only if it passed, and a step whose required state is missing is refused. A claim that something happened is not evidence that it happened.

3. The blocked-result payload

A blocked call returns a normal result with fields the agent can act on:

{
  "blocked_by": "precondition",
  "missing_state": "backup_validated",
  "established_by_steps": ["validate_backup"]
}

Treat it as a replan signal, not a reason to retry. For a production database drop, the safe order is:

drop_prod_db      blocked, backup_validated is missing
validate_backup   blocked, backup_taken is missing
take_backup       allowed
validate_backup   allowed
drop_prod_db      allowed

Repeated blocks add attempts and next, which says whether to run the establishing steps or stop and ask. With memory turned on, the server also counts which rules block runs and how often agents recover.

4. Five-minute local demo

go run github.com/sharedcode/joltrin/v5/examples/verify_barrier@latest

That needs Go and no clone. Or try the barrier in your browser. It runs the same checks compiled to WebAssembly.

5. MCP integration

One command installs the server, checks its checksum, and registers it with the agents on your machine. No Go needed:

curl -fsSL https://raw.githubusercontent.com/SharedCode/joltrin/master/scripts/install.sh | sh

Building with Go, Windows, your own runbooks, and memory are covered in the README and Agent protocols.

6. A2A integration

The same check gates an A2A agent. A blocked step moves the task to input-required with the same fields. See Agent protocols.

Limits

The barrier only answers, so whatever performs the action must wait for it. It cannot see facts the trace does not contain. A backup in another cloud account has to be represented by a step you trust, such as one that checks that account and records the result. The browser demos run the real checks against stub tools. No production deployments, customers or third-party benchmarks are claimed.

Reference