Metadata-Version: 2.4
Name: transient-trace
Version: 0.2.0a3
Summary: Governance for autonomous agents. Intercepts every action, enforces policy, writes tamper-evident receipts.
Author: Transient Intelligence
Keywords: atp,trace,ed25519,rfc8785,governance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: PyNaCl>=1.5.0
Requires-Dist: rfc8785>=0.1.2
Requires-Dist: typing_extensions>=4.6.0
Requires-Dist: python-ulid>=3.0.0
Requires-Dist: textual>=0.70.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# transient-trace

Governance for AI agents. Every action an agent takes — subprocess calls, tool use, network requests — is evaluated against a policy and recorded as a tamper-evident, cryptographically signed receipt before it executes.

Part of [Transient](https://github.com/james-transient/transient), the trust infrastructure for autonomous agents.

## Install

```bash
pipx install transient-trace
```

`pipx` installs into an isolated environment and puts the `transient-trace` binary on PATH permanently. If you don't have pipx: `brew install pipx && pipx ensurepath`.

## Upgrade

```bash
pipx upgrade transient-trace
```

## Quickstart

The fastest path to governed agents is the `wrap` command. It installs a persistent shim so every invocation of the binary goes through governance automatically, with no prefix required.

```bash
transient-trace wrap install claude --auto-rc

source ~/.zshrc
```

Every `claude` invocation is now governed with a full receipt trail.

```bash
transient-trace wrap status

transient-trace receipts list --since 30m

transient-trace receipts summary --since 1h
```

## How it works

transient-trace sits between your agent and the operating system. Every action passes through the governance layer before it executes — including calls that use absolute binary paths or run inside nested subprocesses.

No changes to your agent framework required. Works inside Claude Code, LangChain, custom harnesses, and raw Python out of the box.

## Enforce a policy

By default, transient-trace runs in audit mode — records everything, blocks nothing. To enforce a policy, switch to strict mode:

```bash
cat > my-policy.json << 'EOF'
{
  "version": 1,
  "defaultAction": "deny",
  "rules": [
    { "id": "allow-git",       "action": "allow", "actionClasses": ["read", "write_low"] },
    { "id": "allow-anthropic", "action": "allow", "actionClasses": ["network"],
      "hosts": ["api.anthropic.com"] }
  ]
}
EOF

transient-trace run --mode strict --policy "$(cat my-policy.json)" claude -p "..."
```

Or set strict mode as the permanent default:

```bash
transient-trace config set mode strict
```

## Python SDK

For direct integration into Python agents:

```python
from transient_trace import Client

client = Client({
    "agentId": "my-agent",
    "mode": "permissive",
    "packages": ["shell"],
})

result = client.executeActionWithReceipt(
    lambda: {"ok": True},
    {"target": "resource-1", "action_class": "write_low"}
)

print(result["receipt"]["receipt_id"])       # TR-...
print(result["receipt"]["signature"]["alg"]) # Ed25519
print(result["decision"]["outcome"])         # allow
```

If policy returns `deny`, raises `RuntimeError: Denied: <reason_code>`.

## Receipts

Every governed action produces a signed receipt:

```json
{
  "receipt_id": "TR-01KPHGWX7C7A2BQYJKX93YP59Q",
  "execution_status": "executed",
  "event_snapshot": {
    "action_class": "x.read",
    "matched_rule_id": "x-read-allow",
    "matched_rule_reason": "x-governance/social-listening: read allowed."
  },
  "signature": {
    "alg": "Ed25519",
    "sig": "xRVLkN4r1hNy..."
  }
}
```

Receipts are tamper-evident. The event snapshot is hashed with SHA-256 and signed with Ed25519 before write. Signatures are cross-verifiable between the Python and TypeScript SDKs.

## Governance packages

Governance packages are pre-built rule sets you can drop into any project:

```python
client = Client({
    "agentId": "my-agent",
    "packages": ["shell", "filesystem", "web"],
})
```

Available packages map to [OWASP Agentic Security Initiative](https://genai.owasp.org) threat categories:

| Package | Covers |
|---|---|
| `shell` | Inline interpreter execution |
| `filesystem` | Destructive file operations |
| `web` | Outbound HTTP and SSRF |
| `code` | Git push, package installs, supply chain |
| `privilege` | sudo, su, chmod escalation |
| `messaging` | Outbound message delivery |

## Further reading

[Transient](https://github.com/james-transient/transient) — full product docs, Recall, Intelligence, receipt bus

[ATP 1.0](https://github.com/james-transient/transient-atp) — the open protocol specification underlying every receipt
