Runs and audit packs

Chain an agent's receipts into a run and export the run as a signed pack.

Prove / runs-and-audit-packs

A run groups the receipts from one agent session. Each receipt in a run stores the SHA-256 of the previous receipt payload in prev, which turns the run into a hash chain. Drop or reorder a receipt and the chain no longer matches.

Start a run

bash

curl -X POST https://YOUR-PROVN-HOST/v1/runs \
  -H "Authorization: Bearer $PROVN_API_KEY"
# {"run_id":"run_9Kd2..."}

Tag calls

bash

curl https://YOUR-PROVN-HOST/v1/chat/completions \
  -H "Authorization: Bearer $PROVN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-provn-run: run_9Kd2..." \
  -d '{ "model": "provn", "messages": [{ "role": "user", "content": "Step one." }] }'

The first receipt in the run has prev: null. Each later receipt carries the hash of the payload before it.

Check the chain

import { createHash } from "node:crypto";

// Base64url receipts, in the order the gateway issued them.
export function chainIsIntact(receipts: string[]): boolean {
  let prev: string | null = null;
  for (const receipt of receipts) {
    const bytes = Buffer.from(receipt, "base64url");
    const payload = JSON.parse(bytes.toString("utf8"));
    if (payload.prev !== prev) return false;
    prev = createHash("sha256").update(bytes).digest("hex");
  }
  return true;
}

Verify each signature as well. The chain shows order and that nothing in the middle went missing; the signatures show who issued each link.

Read a run

bash

curl https://YOUR-PROVN-HOST/v1/runs/run_9Kd2... \
  -H "Authorization: Bearer $PROVN_API_KEY"

Audit packs

POST /v1/runs/:id/audit returns a signed audit pack for the run. Pro and Scale plans include audit packs, and you can also download them from the dashboard.

bash

curl -X POST https://YOUR-PROVN-HOST/v1/runs/run_9Kd2.../audit \
  -H "Authorization: Bearer $PROVN_API_KEY" \
  -o audit-pack.json

Each receipt in the run, with its signature.
The head hash of the chain.
The span the run covers.
A pack signature from the gateway signer.

An auditor with the pack can check each receipt signature, walk the prev links to the head hash and verify the pack signature against the published signer. They need no Provn account for any of it.