TBE

TBE is a deterministic execution engine for policy-gated, evidence-driven agent work.

What TBE is

TBE v1.0.0 is a standalone CLI product that runs bounded deterministic thread steps, enforces local policy gates before effectful operations, records content-addressed evidence, and supports replay to verify whether outcomes still match prior sessions.

Why TBE exists

Agent workflows need three things at the same time:

• deterministic step execution
• explicit policy controls for side effects
• durable evidence for audit and replay

TBE combines these into one local engine with stable v1 contracts.

Current command surface

The v1.0.0 surface is:

• tbe init
• tbe validate
• tbe status
• tbe export
• tbe replay
• tbe run
• tbe version
• tbe help

Run modes (run, --plan, --dry-run)

tbe run supports three modes:

• run (default): executes deterministic built-in steps and performs policy-allowed effects
• plan (--plan): emits a static execution plan artifact without executing steps
• dry-run (--dry-run): executes pure steps and simulates effect steps without performing IO

--plan and --dry-run are mutually exclusive.

Policy and profiles

Policy is loaded from .tbe/policy.json using schema id tbe-policy/v0.9.

• capabilities are fail-closed unless explicitly allowed
• built-in effect gates cover read_file, write_file, and exec
• named profiles are supported through active_profile
• built-in defaults include default and repo_writer

Evidence model

Each command run can write evidence under .tbe/ as content-addressed JSON artifacts plus session records.

Stable evidence schema identifiers in v1:

• cli-session/v0.2
• cli-artifact/v0.2
• cli-step-result/v0.4

Artifact registry

Run execution includes named artifacts and artifact:<name> references.

• steps can emit or register named artifacts
• later steps can resolve those names deterministically
• replay verifies current results against recorded evidence

Canonical workflows

Canonical v1 workflows are in examples/:

1. safe repo content generation
2. controlled exec with command rules
3. named artifact pipeline

Each workflow includes thread JSON, command sequence, and expected results for plan, dry-run, run, and replay.

Installation

See INSTALL.md for verified build/install paths.

Compatibility and stability

TBE v1.0.0 freezes the CLI JSON contract surface for:

• validate --json
• status --json
• export --json
• run --json (default/plan/dry-run)
• replay --json

See COMPATIBILITY.md for full guarantees and v1.x change policy.

Known non-goals

The following are intentionally out of scope for v1.0.0:

• branching or conditional execution semantics
• plugin systems
• network/remote execution steps
• UI/runtime orchestration service

The repository still includes supporting schemas/spec documents under schema/ and spec/; they support the engine and are not the primary product identity.

License

Apache License 2.0. See LICENSE.

Contributing

Contributions should preserve deterministic behavior and stable contracts.

When changing CLI behavior:

• update tests (including golden contract tests)
• update product docs (README.md, INSTALL.md, COMPATIBILITY.md, release docs)
• keep changes within the shipped v1.0.0 surface unless explicitly planned for a future major release