Trinity Tool Contract

Language: English | ไทย

Stable ABI for Trinity-compatible CLI tools.

Trinity tools are not trusted because they print friendly messages. They are trusted because they speak a small, auditable contract:

input envelope -> tool execution -> output envelope -> artifacts -> audit

This repository freezes the public Tool Contract v1.0 surface for tools that want to plug into Trinity or any evidence-driven AI workflow.

---

What Is Frozen in v1.0?

Tool Contract v1.0 freezes the interoperability boundary:

• input envelope
• output envelope
• exit code meaning
• verdict schema
• artifact declaration
• error taxonomy
• retry semantics
• idempotency expectation
• audit log requirements
• security boundary

Future versions may add fields, but v1-compatible tools must keep this core surface stable.

---

Why It Exists

AI agents can claim work is done. Tools must prove what happened.

A Trinity-compatible tool must expose machine-checkable evidence:

• what command was requested
• what policy tier was used
• what the tool did
• what artifacts were created
• what hash proves those artifacts
• whether the result passed or failed
• whether retry is safe
• what audit events were emitted

---

Repository Layout

trinity-tool-contract/
├── spec/
│   ├── TOOL_CONTRACT_V1.md
│   └── TOOL_CONTRACT_V1_TH.md
├── schema/
│   ├── input-envelope.v1.schema.json
│   └── output-envelope.v1.schema.json
├── examples/
│   ├── input.browser.screenshot.json
│   ├── output.pass.artifact.json
│   ├── output.fail.policy.json
│   └── output.fail.element.json
├── docs/
│   ├── CONFORMANCE.md
│   └── conformance.checks.yaml
├── scripts/
│   └── trinity-contract-test.py
├── CHANGELOG.md
└── LICENSE

---

Minimal Tool Rule

A compatible tool must be runnable from shell and emit JSON on stdout:

tool-name --input request.json > response.json

stdout is machine output only. Human diagnostics go to stderr.

Validate an envelope with the bundled runner:

python scripts/trinity-contract-test.py --schema input examples/input.browser.screenshot.json
python scripts/trinity-contract-test.py --schema output examples/output.pass.artifact.json
python scripts/trinity-contract-test.py --schema output examples/output.fail.policy.json
python scripts/trinity-contract-test.py --schema output examples/output.fail.element.json

---

Default Flow

CLI tool
  -> Tool Contract input envelope
  -> Tool execution
  -> Tool Contract output envelope
  -> Declared artifacts with hashes
  -> Audit log / verifier / promotion gate

MCP can be used as an optional bridge, but it must enter through an adapter that emits the same Tool Contract envelope.

---

Version Line

v1.0.0 = first frozen public ABI
v1.0.1 = validation runner + CI
v1.0.2 = browser-cli v0.3.0 real output examples

Trinity Protocol may keep a newer draft spec internally, but external tools should target this repo when they need a stable public contract.

---

Related Projects

• Trinity Protocol: https://github.com/postmunnet/trinity-protocol
• browser-cli: https://github.com/postmunnet/browser-cli