How usertools-ai/usertrust works
usertrust is a financial-governance SDK for AI-agent LLM calls: it applies policy and budget controls, meters usage, settles spend, and returns an auditable receipt. Its central flow is a wrapped provider request through governance and a two-phase ledger lifecycle, followed by audit recording. The repository also includes policy and safety controls, external verification and anchoring, integrations, an operator UI, and a tenant server. Some subsystem links are based on README descriptions because their implementation files were not sampled.
Main entry points: govern.ts Governed SDK · main.ts Operator CLI · engine.ts Two-phase ledger · server.ts Dashboard server
Components 23
Governance runtime
- Governed SDK
packages/core/src/govern.ts - Policy engine
packages/core/src/policy/gate.ts - PII detection
packages/core/src/policy/pii.ts - Provider breakers
packages/core/src/resilience/circuit.ts - Routing proxy
packages/core/src/proxy.ts - Pattern memory
packages/core/src/memory/patterns.ts
Spend and audit
- Budget context
packages/core/src/budget/context.ts - Two-phase ledger
packages/core/src/ledger/engine.ts - Ledger client
packages/core/src/ledger/client.ts - Usage pricing
packages/core/src/ledger/pricing.ts - Audit chain
packages/core/src/audit/chain.ts - External anchoring
packages/core/src/audit/anchor.ts
Integrations and tools
- Provider adapters
packages/acs-adapter/src/composite.ts - OpenClaw governor
packages/openclaw/src/stream-governor.ts - Tenant API
packages/server/src/server.ts - Operator CLI
packages/core/src/cli/main.ts
Verification and visibility
- Receipt verifier
packages/verify/src/receipt-verify.ts - Ledger dashboard
packages/ui/src/app/app.tsx - Dashboard server
packages/ui/src/server/server.ts - Receipt pages
site/app/r/[receiptId]/receipt.json/route.ts
Other components
- Agent developer
- LLM provider
- TigerBeetle
Connections 27
- Agent developer → Governed SDK: wraps client
README.md - Governed SDK → Policy engine: checks policy
README.md - Governed SDK → PII detection: screens prompts
README.md - Governed SDK → Budget context: enforces budget
README.md - Governed SDK → LLM provider: calls provider
README.md - Governed SDK → Provider breakers: guards requests
README.md - Governed SDK → Two-phase ledger: records spend
README.md - Two-phase ledger → Ledger client: creates transfers
packages/core/src/ledger/engine.ts - Ledger client → TigerBeetle: submits transfers
packages/core/src/ledger/client.ts - Governed SDK → Usage pricing: prices usage
- Two-phase ledger → Audit chain: records events
- Governed SDK → Pattern memory: learns routing
README.md - Routing proxy → Pattern memory: uses learned routing
README.md - LLM provider → Governed SDK: returns response
README.md - Governed SDK → Agent developer: returns receipt
README.md - Operator CLI → Audit chain: verifies chain
README.md - Operator CLI → External anchoring: manages anchors
README.md - External anchoring → TigerBeetle: anchors externally
- Provider adapters → Governed SDK: adapts provider
- OpenClaw governor → Governed SDK: governs streams
- Agent developer → Tenant API: sends API requests
- Tenant API → Governed SDK: authorizes and settles
packages/server/src/server.ts - Dashboard server → Audit chain: reads vault
packages/ui/src/server/server.ts - Dashboard server → Ledger dashboard: serves dashboard data
- Operator CLI → Dashboard server: opens dashboard
- Receipt pages → Receipt verifier: resolves verification
site/app/r/[receiptId]/receipt.json/route.ts - Agent developer → Receipt verifier: submits receipt
README.md