bide

README

English · 简体中文 · Русский · हिन्दी · العربية

Durable AI agents in Go, for agents that move money, change records, or act under audit.
Side effects fire at most once, even across a crash. Every action is provable afterwards.

  A pause you can clear beats a double-fire you can't.  

# Install (or: go install github.com/bide-ai/bide/cmd/bide@latest)
brew install bide-ai/tap/bide
# 1. See it: kill an agent mid-payment; it does not charge twice (no API key)
bide demo
# 2. Build: a plan flow with a 2-of-3 approval gate, on SQLite, no API key
bide init refund && cd refund && go mod tidy && go run .
# 3. Inspect: the runs in a local, read-only page (a run list, then each run; it prints the address to open)
bide view -db run.db
# 4. Prove: verify the run's evidence offline
bide audit verify-evidence -evidence evidence.json -pubkey keys/log.pub

One append-only journal, in a plain-Go library, gives four guarantees:

• Side effects fire at most once, even across a crash, so they need not be idempotent.
• Thousands of concurrent durable runs in one process. It is a library; there is no cluster to run.
• A cryptographically verifiable audit trail: RFC 6962 Merkle proofs, checkable offline without trusting the vendor.
• Provably convergent shared state: the convergence conditions are machine-checked.

Ambient agents. An ambient agent runs unattended: it sleeps until a trigger (a schedule or an event) wakes it, works over hours or days, and pauses to ask a human only when it needs judgment, with nobody watching each step. Such an agent has to be safe to crash, safe to re-trigger, and provable afterwards. Bide provides the durable lifecycle for this: durable Sleep/WaitUntil timers, a pluggable Waker for time- or event-driven wakeups, and durable Interrupt/AnswerInterrupt for typed human-in-the-loop, all on the same journal. You bring the trigger source and the oversight UI; the runtime keeps each run correct across sleeps, crashes and node handoffs.

Status: working v0, live-verified end to end. Requires Go 1.27.

One journal, four guarantees

The agent loop is about 40 lines. The four guarantees come from the durable, append-only journal underneath it.

1 · At most once (measured)

Temporal, DBOS, LangGraph, trpc-agent-go, ADK and eino resume by re-running: activities or steps must be idempotent, so a non-idempotent side effect (a charge, an email, a shipment) can fire twice across a crash. A crash-injection benchmark (chaos/, cross-SDK results in benchmarks/) drives a non-idempotent charge through every crash point:

Each framework either never repeated the charge or charged again; the worst-case count depends on how often a framework saves state, so it is not a ranking. Each competitor adapter passes a fairness test (a run with no crash charges exactly once, and where the framework has a resume, it works), and LangGraph runs in its most durable documented mode. What none of the benchmarked frameworks has: a durable attempt marker written before a non-idempotent write, and halt-on-unknown-outcome on resume: if a write's result was never journaled, the run stops for a human decision.

When the outcome is unknown, it stops

The hard case is a side effect whose call left the process but whose result never reached the journal. The attempt marker lets a resumed run tell "never started" from "started, outcome unknown", and the unknown case is resolved in a fixed order:

Which tier a tool lands in is set by its declared Safety: mark it read-only or idempotent and an unknown outcome auto-retries; declare none of those and it halts. Retry-safety is opt-in; without it, the default is to pause.

Most unknowns never reach a person: an idempotency key lets the provider dedupe a safe retry, and for systems without one (email, internal services) a reconciler resolves the step from the record it left (agent.ResolveHalt). A person is asked only when neither applies.

[!IMPORTANT] When an action moves money, changes a record, or happens under audit and its outcome cannot be known, the run stops. A human or a reconciler can clear a pause; a double charge cannot be taken back.

2 · Durable execution as a library

Temporal provides durable execution with a server and a worker fleet. Here it comes from a store adapter you already run (SQLite locally, Postgres in production). A hello-world imports only the standard library: no Temporal, gRPC or vector database dependency (enforced by architecture_test.go).

One process can keep many durable runs in flight at once. Agent work is I/O-bound (waiting on model and tool calls), which goroutines absorb without a cluster. The cmd/bench harness measures it: 20,000 runs, 5,000 in flight at a time, each blocking ~100ms on the model, finish in about half a second (~470ms) of wall-clock on a 10-core Apple silicon Mac (measured at v0.7.0), and about one second on a standard 4-vCPU CI runner, on a few thousand goroutines and tens of MB (go run ./cmd/bench -runs 20000 -concurrency 5000 -latency 50ms; reproducible with the Benchmark workflow). This measures throughput; per-call latency is the provider's. At high fan-out the limit is the durable store's write throughput. Every concurrent run keeps all four guarantees. For reliability under load there are per-attempt timeouts, retry with backoff that classifies transient and terminal errors, hedged model calls (race a backup, take the first, for tail latency and provider failover), and a rate limiter for model and tool calls (middleware, docs/guides/reliability.md).

For high availability, any node resumes any run from the shared store, and competing drivers coordinate through a per-run lease (agent.Lease): normally one process drives a run at a time, and a crashed holder's lease expires so another node's agent.RecoverLoop takes it over. A holder that stalls past its lease can wake still driving, but it cannot fire a side effect a second time: at-most-once rests on the attempt claim, not on the lease. Tests cover concurrent-worker mutual exclusion, crash-and-takeover, and at-most-once under concurrent drivers on the in-memory store (agent/ha_e2e_test.go), and on Postgres across real processes that the tests kill, stall past their lease and restart (store/postgres/ha_multiproc_test.go; the Postgres backend implements the lease with a DB-clock upsert).

3 · A verifiable audit trail from the same journal

The journal that makes resume safe is also the audit record, committed with the cryptography Certificate Transparency uses (RFC 6962, checked against the published reference vectors). A third party checks a proof without trusting you, your database or your logs:

• Inclusion proof: prove one specific action happened (this charge, this approval) in O(log n), revealing no other record (only its position and the run's size). Selective disclosure for an auditor.
• Consistency proof: prove the history was only ever appended to, never rewritten or reordered.
• Signed tree head + continuous anchoring: AuditedStore signs a commitment per step and publishes it out-of-band to an external transparency log, so tampering can be proven.
• Who acted, under what authority: the same leaf can commit to the acting identity (actor, on whose behalf, under which signed grant) and enforce delegated authority as a governed invariant, so a proof shows who was authorized for what happened. Bring your own IdP; this makes the authorized action provable, it does not replace authentication.

Produce a portable ProofBundle for one action (audit.ProveToolCall), or a whole-run EvidencePackage (audit.Evidence) bundling every material action's proof into one file, and hand it to an auditor who verifies it offline with bide audit verify / verify-evidence or a stdlib-only verifier that never imports the SDK. The same spine carries the rest of the accountability layer, all verifiable offline: proof-carrying runs (one RunCertificate attesting a whole run's policy compliance), signed capability grants with attenuating delegation, authority earned from a clean audit trail, and governed k-of-n quorum. → docs/guides/audit.md

4 · Provably convergent shared state (gsm)

Many agents can change shared state concurrently, even with events that conflict and break invariants, and every replica converges to the same valid state. The idea is convergence by compensation: repair always terminates and commutes with events, so the order events replay in cannot change the result. The theory, normalization confluence, is an exact regime map of governed concurrent state: in every regime, a machine-checked exact condition, a hardness result showing no efficient one exists, or a gap stated in the open. The proofs are axiom-free and CI-checked on Coq 8.18, 8.20 and Rocq 9.3 ().

• Checked at build time. Describe shared state as a registry of variables, invariants and events; gsm's Build checks the convergence conditions or refuses with a concrete counterexample.
• Re-checked by the proof itself. Every registry machine gsm returns is re-certified in-process by a checker generated from the Rocq proof; if it doesn't certify, there is no machine.
• Federations too. For registries linked across teams or organizations, repair composes into a unique normal form, and event order across registries is made safe by two local checks per edge (C1 and C2) that gsm runs at build time.
• Tested at scale. 10,000,000 governed agents driven through random, invariant-violating orders, all converging to the same valid state, each with an audit proof that verifies offline (a framework-level test: stub model, in-memory store; see docs/testing/testing.md).

The claim is precise: order-independent convergence of the replay for a machine that meets the conditions, on discrete, deterministic state, not "agents always agree". Details are in the governance guide; the exact scope (causal delivery and Independent pairs, delivery obligations, which checks are proof-generated versus Go, and gsm version history) is in known limitations.

vs. durable-execution and agent runtimes

	Bide	Temporal / DBOS	ADK · eino · trpc · langchaingo
Non-idempotent side effect on crash	At most once (halts on unknown outcome)	At least once; activities/steps must be idempotent	At least once; re-runs (measured 4–64×)
Deployment	Library + a DB you already run	Server + worker fleet	Library
Tamper-evident audit	RFC 6962 Merkle spine (same journal)	Not built in	None
Convergent shared state	Provable (gsm)[^gsm]	N/A	None

[^gsm]: The convergence theorem is machine-checked. gsm's Build checks each machine against its conditions and returns it only after the table oracle, Go generated from the proof, re-checks it in-process; for combinator rules inside its fragment and within a cost cap, the rules oracle re-checks it from the rules as well. A federation's own conditions, including the event-order checks C1 and C2, are checked by gsm's Go code. bide requires gsm v0.14.0; v0.13.0 added the C1 and C2 checks (v0.12.0 had neither), and v0.12.0 fixed the Build gap of v0.11.0 for guards and effects that read variables another event writes. Exact scope: known limitations.

Other details

• The graph is optional. Write plain Go (if, for, functions); RenderMermaid and Topology derive the graph. If you prefer authoring topology, the plan builder does that and runs on the same runtime. See Graphs.
• Claude's extended thinking works with tools. Thinking signatures are kept across turns, which the API requires when thinking and tool use are combined.
• Tool schemas per provider. A tool's schema is generated once from its Go type and emitted in each provider's dialect, including OpenAI strict mode and Gemini's subset.
• Model adapters. Native Claude and Gemini, plus any OpenAI-compatible endpoint (OpenAI, Ollama, DeepSeek, Groq, OpenRouter, vLLM, Azure, xAI) via WithBaseURL.
• Failover across nodes. With Postgres, any node can resume any run. A per-run lease stops two nodes driving the same run, and agent.RecoverLoop picks up a crashed node's runs when its lease expires.

Builders add the library to their own module: go get github.com/bide-ai/bide/agent. Then read Getting started, take the tour of the API, and see the docs index.

Documentation

Start here

• Getting started: install, bide demo, bide init, your first agent, and the examples.
• A tour of bide: the API section by section: graphs, ambient runs, the agent loop, streaming, typed output, sessions, the audit trail, human approval, errors, middleware and governance.
• The guarantee and known limitations: the precise durability guarantee and its bounds.

Concepts

• Concepts: the vocabulary (journal, at-most-once, lease, Waker, gsm, ProofBundle) in one place.
• Design: how the runtime is put together.

Guides: build

• Plan flows: the plan package. Author topology (Step/Tool/Model/Switch/Join/LoopBack) that lowers to the same journal, gate a node on m-of-n human approval, then prove a run followed it (Conform). Runnable: examples/plan.
• Durable steps: Step, Parallel/Task fan-in, sagas (WithSaga), and durable timers (Sleep/WaitUntil). Runnable: examples/parallel.
• Reliability: per-attempt timeouts, classified retry, hedged model calls, rate limiting and cost tracking. Runnable: examples/hedge.
• Signals and ambient: durable timers and the Waker, Interrupt/AnswerInterrupt, and durable signals (at-least-once in, exactly-once applied). Runnable: examples/signals, examples/interrupt.
• Models: the Anthropic, OpenAI-compatible and Gemini adapters, sampling, prompt caching, typed errors and multimodal input.
• MCP, Messaging, RAG and memory, Observability: MCP servers as tool sources, redelivery-safe webhooks, bring-your-own retrieval, and OTel spans in one line.

Guides: inspect

• Run viewer: bide view, a read-only local page for a journal's runs (a run list filtered by state, kind and ID) and for one run (the timeline, a flow's path, halts, approval gates and the audit verdict, following a run in progress), and bide check for flow configs in CI (a risk map of each node's crash behavior, and policy assertions such as every path to charge passes approval >= 2 of 3, a violation shown as a counterexample path), with -diff to compare two versions of a flow and flag a weakened approval gate.
• Debugging and recovery: Replay, ReplayEvents, Mermaid run diagrams, and Recover.

Guides: prove and govern

• Audit: the tamper-evident trail and proof-carrying runs, checkable offline with bide audit. Runnable: examples/govern/proof-carrying-run.
• Human approval: sign-off before a tool runs, 1-of-1 to signed m-of-n, with offline proof that k named approvers approved first. Runnable: examples/approval.
• Security model: the exact scope of the cryptographic guarantees, and the audit-only build of bide. Read before relying on the trail.
• Delegation, Governance, Quorum: signed grants a sub-agent can only narrow, convergent governed state (gsm), and governed k-of-n agreement.

Reference

• CLI reference: every bide command, flag and exit status.
• Extension points and module structure: the ports and adapters, and the multi-module layout.
• API: pkg.go.dev/github.com/bide-ai/bide.

Proofs

• Formal verification: the TLA+ models of the coordination protocols, what TLC and Apalache check, every bug they found, and what they do not cover.
• How bide is verified and testing: no fix without a failing test, mutation checks, crash sweeps, and the chaos benchmark.

The full map is the docs index.

Contact

Questions, feedback, or interest in using bide: dayna@blackwell-systems.com. Security issues go through SECURITY.md (private reporting).