Portable, hash-verifiable intermediate representation for agent execution trajectories.
A flight recorder for agent runs: typed nodes, a sealed model plan, fail-closed effect classes, and a runtime-independent .tir package anyone can verify by content hash.
It sits on top of durable execution engines (Temporal, DBOS, Restate). It does not replace them, and it is not another agent framework. It does not freeze AWS, auctions, or users while you are crashed, and a client-side gate is not exactly-once at Stripe.
Agent host / framework (LangGraph, custom loops, MCP hosts, ...)
│
▼
┌─────────────────────────────┐
│ Trajectory IR │ seals · effect classes · .tir · sandbox
└─────────────────────────────┘
│
▼
Durable backend (Temporal · DBOS · Restate)
Production agent stacks keep failing the same way. Crash replay is already Temporal/DBOS/Restate's job. The hole they do not fill is a portable, hash-verifiable record of what the agent actually decided and invoked, plus agent-shaped policy on top of that record.
| Failure | Who actually solves it | What Trajectory IR adds |
|---|---|---|
| Crash mid-tool | Durable backend memoization. Exactly-once still needs a server-side idempotency key the remote API honors. | Block-and-gate: at most one automatic attempt from this client. Unknown in-flight calls go to BLOCKED_NEEDS_GATE for a human, not a second LLM turn. The seal-derived key is recorded on TOOL_CALL so you can forward it. |
| Naive resume | Do not re-call the model for a sealed step (backend replay + IR seal). | Honest resume of the sealed plan (R01). That freezes the plan, not the world. If the cluster changed while you were dead, re-observe (READ_ONLY) or abort and start a new step. Do not silently re-infer the sealed one. |
| Locked history | Nobody else ships a runtime-independent unit. | Portable thin/fat .tir with hash-checked node IDs |
| Unsafe demos | Host policy. | Sandbox mode is a demo/CI effect-class gate before the tool body (R06). It is not a process sandbox, not an AST of bash, and not a security boundary for arbitrary code. |
One-line pitch: portable semantics for what the agent actually did, on top of engines that already solve crash safety.
This is a runtime trajectory IR, not LLVM. You do not compile a prompt into .tir ahead of time. Hosts lower a live agent step into typed, content-addressed nodes; you can project, redact, graft, verify, and export that trace onto more than one backend. If you wanted a compiler, this is the wrong repo. If you wanted a vendor-neutral flight recorder for agent steps, this is the product.
Full normative contract: docs/MASTER_SPECIFICATION.md (
spec-v0.2-draft).
Short scope card: docs/SCOPE_AND_NON_GOALS.md.
- Sealed decisions — freeze the model's plan (
DECISION) before world-changing tools run. The world is not frozen with it. - Effect classes — fail-closed mapping from MCP tool hints, plus
AGENT_SPAWNandSENSITIVE. Open-world primitives (bash,python,sql, browser) stayNON_IDEMPOTENT_WRITEunless an operator sets the class on the tool. No command parser. - Honest resume — a sealed step does not re-infer (R01). Re-observe is allowed; re-plan is a new step.
- Block-and-gate — non-idempotent tools are not blindly retried after interruption (R02). At-most-one automatic attempt, not exactly-once in the world.
- Seal-derived idempotency keys —
trajectory_id:step_n:seqon everyTOOL_CALL. Hosts must forward that string to the remote API. .tirpackages — thin or fat export/import with content-addressed identity; optionaltrajir-pkg-sig-v1signatures- Sandbox mode — demo/CI gate that rejects dangerous effect classes before the tool body. Not a security sandbox.
- Dual SDK — Go primary (Temporal production backend), Python reference (DBOS local profile)
- Conformance suite — R01–R11 runnable across languages
- OpenSSF Best Practices — project badge and continuous hardening
Prerequisites: Go 1.25.x, Git
git clone https://github.com/Coder-s-OG-s/Trajectory-IR.git
cd Trajectory-IR/go
go test ./...Minimal client step:
tr, err := client.OpenTrajectory("demo", "qs-1", client.Options{WorkDir: dir})
// ...
tr.Project(1, map[string]any{"goal": "hello"})
tr.SealDecision(1, map[string]any{
"tool_calls": []any{
map[string]any{"name": "echo", "args": map[string]any{"msg": "hi"}},
},
})
res, err := tr.ExecTool(1, 2, tool, map[string]any{"msg": "hi"})
fmt.Println(res.Result) // hi
tr.CommitStep(1, 4)Full walkthrough, Temporal notes, and demos: go/QUICKSTART.md
cd Trajectory-IR
python -m venv .venv
# Windows: .\.venv\Scripts\activate
# Unix: source .venv/bin/activate
pip install -U pip
pip install -e ".[dev]"
pytest conformance/ -qMore: QUICKSTART.md · kill-mid-deploy demo: examples/kill_mid_deploy/
| Audience | Start here |
|---|---|
| Students / newcomers | This README → go/QUICKSTART.md → try sandbox + kill-mid-deploy demos |
| Agent / platform engineers | docs/SCOPE_AND_NON_GOALS.md → docs/INTEGRATIONS.md → wire seals into your host loop |
| Security / compliance | Seals + .tir (hash-verifiable export); report issues via SECURITY.md. Sandbox is a demo gate, not a security boundary. |
| Contributors | CONTRIBUTING.md (DCO required) → Phase 1B/1C: Go first |
| AI coding agents | docs/MASTER_SPECIFICATION.md + AI_POLICY.md — implement the spec, do not invent behavior |
| Talks / demos | website/ MkDocs site and speaker runbook |
flowchart LR
A[PROJECT_CONTEXT] --> B[DECISION seal]
B --> C[TOOL_CALL]
C --> D[TOOL_RESULT]
D --> E[COMMIT_STEP]
- Host projects context for the step
- Model plan is sealed before tools with side effects
- Tools execute under an effect class (fail closed if unknown)
- Step commits; trajectory can be exported as
.tir
Same agent, two modes: live does the job; sandbox refuses dangerous classified effects and still keeps the sealed plan. Classify bash as read-only and sandbox will believe you. Don't.
| Trajectory IR is | Trajectory IR is not |
|---|---|
A portable runtime IR + .tir package for agent trajectories |
LLVM, bytecode, or a compiler for prompts |
| Seals, effect classes, resume semantics, hash-verifiable export | A replacement for Temporal / DBOS / Restate (adapters only) |
| A thin layer over pluggable durable backends | An agent orchestration framework (not LangGraph) |
| At-most-one automatic retry policy + a key you can forward | Exactly-once remote writes (that is the server's idempotency key) |
| A demo/CI effect-class gate (R06) | A process sandbox or bash AST analyzer |
| Open source libraries (Apache-2.0) | A hosted multi-tenant SaaS control plane, or a long-term memory product |
| Item | Status |
|---|---|
| Spec | spec-v0.2-draft — master specification |
| Phase | 1C harden and adopt (Go primary; Python parity) — see docs/ROADMAP.md |
| OpenSSF Best Practices | Project 14075 |
| CNCF Sandbox | Preparing — outline. Not claiming CNCF membership until TOC approval |
| Adopters | Honest empty list — ADOPTERS.md (add yourself via PR when you consent) |
| Doc | Purpose |
|---|---|
| docs/MASTER_SPECIFICATION.md | Normative architecture, data model, protocols |
| go/QUICKSTART.md | Fastest path to a working Go client |
| QUICKSTART.md | Repo-wide quickstart (Go + Python) |
| docs/SCOPE_AND_NON_GOALS.md | In / out of scope |
| docs/ROADMAP.md | Public roadmap |
| docs/INTEGRATIONS.md | Host and backend integration notes |
| docs/RELEASE.md | Release process |
| website/README.md | Demo / docs site (MkDocs) |
| CHANGELOG.md | What shipped |
We welcome students, first-time OSS contributors, and experienced systems engineers.
- Read CONTRIBUTING.md — every commit needs
Signed-off-by(DCO) - Follow CODE_OF_CONDUCT.md
- Prefer Go for new Phase 1B/1C features (
go/trajir); keep Python green for parity - Do not reimplement durable execution (retry / lease / crash engines) — adapters only
- Spec questions → open a Spec question issue; do not invent undefined behavior
git commit -s -m "feat: short description"Governance: GOVERNANCE.md · Maintainers: MAINTAINERS.md · AI-assisted work: AI_POLICY.md
- Improve docs and quickstarts for newcomers
- Add or harden conformance / unit tests
- Fix sandbox, redaction, or packaging edge cases
- Dual-language parity when an issue asks for it
- Real adopter stories in ADOPTERS.md (with consent only)
Please report vulnerabilities privately per SECURITY.md.
Do not open public issues for undisclosed security bugs.
Apache License 2.0 — see LICENSE.
Third-party notices: docs/THIRD_PARTY_LICENSES.md
Trajectory IR builds on ideas and prior art from durable execution (Temporal, DBOS, Restate), MCP tool annotations, and the CNCF TAG Infrastructure discussion of agentic AI storage needs. See §3.1 and §18 of the master specification.
Questions? Open a GitHub Discussion or Issue. Spec wins over chat — when in doubt, read docs/MASTER_SPECIFICATION.md.