Skip to content

Concepts ​

Bide is a Go framework for AI agents that move money: risky calls approved, every action recorded and verifiable. It rests on crash-safe execution (a side effect fires at most once), people in control (signed approvals, separation of duties, notifications), and proof of everything (a verifiable audit trail). The vocabulary, defined once. Terms are grouped by the layer they belong to. See the docs index for the guides that use them.

The durable core ​

  • Journal: the append-only log of a run. Every model turn, tool result, and durable step is a named record. Replaying the journal reconstructs the run's state, which is how resume works.
  • Step: one named, memoized unit of work (Step, or the internal tool-result record). A step runs at most once per run: on resume a recorded step returns its stored result without re-executing.
  • At-most-once: a non-idempotent side effect (a charge, an email, a physical actuation) fires at most once, even across crashes. On an unknown outcome the run halts rather than risk a repeat. Contrast at-least-once systems, which re-run and require idempotent steps.
  • Resume: re-invoking Run with the same run ID replays the journal and continues from where it stopped.
  • Pause: the sealed error a run returns when it stops durably and waits: *ApprovalPending, *InterruptPending, *SignalPending, *TimerPending, *Stopped (a kill switch holds the run) or *OutcomeUnknown. IsPause/AsPause detect one through wrapping; it is not a failure, and the run resumes when re-invoked with Paused().RootRunID once the condition is met.
  • OutcomeUnknown: returned when a non-retriable side effect was started but its outcome was never recorded. The run stops for confirmation instead of guessing. Its Cause is HaltCrashed (a marker with no live claimant known) or HaltContended (another driver won the claim and may be running the effect).
  • Reconciler: what clears an OutcomeUnknown without a human. Most non-idempotent effects still leave a queryable record (a sent-message id, a row); a reconciler queries it, decides, and calls ResolveHalt(ctx, journal, halt.Ref(), outcome). WithMinHaltAge(d) refuses to resolve a halt younger than d, measured from the live attempt (a provider's record can lag the send), returning HaltTooYoung so the caller waits, and a HaltContended halt is resolved only with it (where it stands in for the live-driver check, d must cover the tool's real worst-case run time, not its ToolSpec.Timeout: a late result is still recorded, and a tool that ignores cancellation runs past the timeout; the lease check is unaffected); it also refuses while a driver holds the run's lease (HaltInFlight), or, on a store that cannot lease runs, without WithMinHaltAge (unless WithoutLiveDriverCheck); WithEvidence(v) marks the injected result Reconciled and journals what was read to decide, so a reconciled outcome stays distinguishable from a clean one.
  • Safety: a tool's declaration of how it may be retried on an unknown-outcome resume, as plain data: ReadOnly (no side effects, always safe) and Idempotent (safe to repeat: the tool de-duplicates downstream itself, with a key it derives or NextOnceKey). The zero value is a side effect. Each call's result journals the Safety it ran under, and a saga rollback reads that record. Maps onto MCP tool annotations.
  • ToolSpec: everything the agent knows about a tool: name, title, description, input and output schemas, Safety, Approval (a human gate, set with WithApproval) and Timeout (WithTimeout). The agent reads a tool's spec once, when the tool is registered (its Spec()), and decides every call from that copy. Tool middleware sees it as ToolCall.Spec.
  • Retry-safe tool: a tool that may re-run from the top on an unknown-outcome resume: Safety.ReadOnly or Idempotent. Pausing primitives (Interrupt, Sleep, Await) require one.

High availability ​

  • Lease: a per-run lock so normally only one process drives a run at a time. A crashed holder's lease expires (by the store's clock) and another node takes over. A holder that stalls past its lease can wake still driving; its drive is cancelled with ErrLeaseLost, and the attempt claim, not the lease, keeps its side effects at most once.
  • Recover: after a restart, re-drive in-flight runs, in one pass. Lister enumerates a store's runs that hold no terminal marker (the store filters out finished ones), sub-agent runs (IsSubRun) and session runs (IsSessionRun) are left to the root run and the session that drive them, and the rest are handed, with their run:start, to a Resumer (ResumeAgent, ResumeTyped, ResumeAny), which drives each under the options its first drive journaled. A run with no run:start is skipped and reported once per process.
  • Cancel and Status: Cancel ends a run with run:cancelled (a saga is rolled back first, on a run:cancel-requested request its drive answers); Status reads a run's state (not started, started, completed, aborted, cancelled) from its journal, and RunStatus.EndedAt says when the end marker was written, if it records a time. The first end marker in journal order is a run's end.
  • RecoverLoop: Recover repeated for the life of a process, so a dead holder's run is taken over automatically once its lease expires.

Ambient and pauses ​

  • Sleep / WaitUntil: durable timers. A run pauses until a wall-clock deadline, journaled so the pause survives a restart. They run inside an agent's tools; a plan flow node cannot call them yet (known limitations).
  • Waker: the pluggable trigger that re-invokes a sleeping run when its timer is due (or when an event is delivered). Schedule(ctx, Wake) returns an error; a failed schedule fails the run with an error wrapping ErrStorage and records nothing, so a re-drive (RecoverLoop) schedules again. MemWaker is the in-process reference.
  • Interrupt / Resume: durable human-in-the-loop. A tool pauses the run to request a typed decision; recording the answer and re-running continues.
  • Approval: a durable pre-execution gate. A tool built with WithApproval(SingleApproval()) (or an m-of-n ApprovalPolicy) halts the run as *ApprovalPending before it executes; recording agent.Approve and re-running lets it proceed or skips it. Distinct from Interrupt, which pauses inside a running tool to collect a typed value. See the approval guide; an approver decides from a terminal with bide approve (guide).
  • m-of-n approval: an approval gate that needs k signed decisions from a bounded, named set of n approvers (ToolSpec.Approval, set with agent.WithApproval and an ApprovalPolicy). Each approver signs ApprovalDecisionBytes over the exact call (run, call id, tool, canonical arguments) and the time they decided (decided_at, their clock, signed), and records it with SubmitDecision, which adds when bide recorded it (recorded_at); neither time affects the count. Each distinct decision is its own record, and an approver's first valid one counts (TallyApprovals, the rule shared by the gate and the auditor), so a forged or mistaken record never locks an approver out. A seat is a key: the gate refuses, with ErrConfig, a policy two of whose approvers' verifiers report one key identity (ApproverVerifier.KeyIDs). With ExcludePrincipal (separation of duties) no requester fills a seat: the run's journaled principal (OnBehalfOf, in its run:principal) or that of any run above it. The gate proceeds at k approvals, denies once k is unreachable, and otherwise pauses with the running ApprovalTally; at the outcome it records the tally, including the policy it enforced and every decision it read. audit.ApprovalEvidence exports the request, decisions, tally, and result, and audit.VerifyApprovals (or bide audit verify-approvals) checks offline that k named approvers approved this call before it ran, detecting an omitted decision, a recount mismatch, or a different enforced policy.
  • Separation of duties: ApprovalPolicy.ExcludePrincipal makes an m-of-n gate never count a decision by a requester of the run (its journaled principal, or that of any run above it, compared ignoring ASCII case). The excluded decision is recorded and marked ReasonRequester; it fills no seat. Bide compares ids; it cannot see that one person holds two of them. See the approval guide.
  • Approval deadline: ApprovalPolicy.Timeout (timeout: in a plan config's approval block) gives a gate a deadline, measured from its recorded request and recorded once (approval-deadline:<call>), so a redeploy that changes the timeout does not move a gate already waiting. A gate past its deadline with no terminal count records its expiry as its outcome, insert-once like a pass, so whichever outcome is recorded first stands and an expiry and a pass cannot both be recorded. The call never runs (the model reads agent.ExpiredResult; a plan flow returns plan.ErrApprovalExpired), a decision recorded after the deadline is shown as not counted and never counts, and SubmitDecision, Approve, the approvals endpoint and bide approve refuse one (agent.ErrApprovalExpired). The notifier sends approval_expired. See deadlines.
  • Approval intake: approvals.Handler, an http.Handler an application mounts so approvers can fetch a gated call and post a signed decision (bide approve -to <url>, or a browser page the organization hosts that signs with a non-extractable key). The handler verifies the decision against the recorded call and the approver's enrolled key and records it through the application's own journal; who may reach it is the deployment's job (WithAuth). See the approval guide.
  • Decision receipt: audit.DecisionReceipt (format bide.audit.decision-receipt.v1), the signed decision an approver keeps: the run, call, tool, arguments, approver, verdict and time, the signature, and where the journal holds the record (its name, position and when it was written), with no key material. Verify checks it on its own; audit.CheckReceipt (bide audit verify-receipts) decides whether the signed tree heads of the journal commit to the decision, so a decision deleted before it was anchored is noticed. The intake returns one with each decision it records, and bide approve writes one. See Audit.
  • Notifier: what tells a person that a run halted on an unknown outcome or waits at an approval gate (agent.WithNotifier). The shipped delivery is a signed HTTPS webhook (notify.NewWebhook); events can be routed by kind or approver, escalated when not acknowledged by a deadline, and closed by a resolved all-clear; an audited trail records each attempt and whether the sink acknowledged it, where an acknowledgement means the endpoint answered 2xx, not that a person read it. See notifications.
  • Kill switch: a durable emergency stop (agent.StopControl, agent.StopSwitch, agent.WithStopSwitch). A stop covers every run, one tool or one agent; covered runs return *Stopped before any side effect begins and resume when it is lifted. A call that has begun finishes; a held call writes no attempt marker (or records its claim as not started). Basic mode trusts store access; audited mode signs and needs a lift quorum. Operators set, list and lift stops with bide stop. See the kill switch guide.
  • Signal / Await: an external event delivered into a run, journaled at most once. AwaitFor races a signal against a durable deadline. Ordered channels (Enqueue / Receive / Ack) give exactly-once streaming consumption. The guarantee: at-least-once transport in, exactly-once application.
  • Saga: a sequence of steps with compensations that run in reverse order on failure.

Governed state (Tier-2, gsm) ​

  • gsm: the convergence engine underneath governed state. At build time it checks that concurrent agents applying the same events converge to the same valid state, against the conditions of a machine-checked convergence theorem. Build returns a machine only after the table oracle, Go generated from gsm's machine-checked Rocq proof, re-checks it in-process, and 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 event guards and effects that read variables another event writes. Exact scope: known limitations.
  • Governed state: shared state described as a registry of variables, invariants, and events. The governor prevents, repairs, or halts on invariant violations.
  • Convergence: order-independent agreement on the replayed state, certified at build time, not assumed. CertifyConvergence emits a portable ConfluenceCertificate, re-checkable offline, which also records the delivery obligations gsm reports (undeclared pairs that need causal order, events that need deduplication).
  • Federation: multiple governed registries connected by morphisms, converging across boundaries (trees, multi-source DAGs, monotone cycles). A source is authoritative over its targets' shared components, which makes the federated repair terminate in a unique valid normal form; event order across registries is safe because Federation.Build checks cross-registry CC (C1) and repaired CC (C2) and rejects a federation that fails either.

Accountability ​

  • Threat model: what bide prevents, detects and does not address, by actor (threat model); key custody and retention are in the operations guidance.
  • Merkle tree / STH: the audit spine. Records hash into a tree; a signed tree head (STH) commits to the whole log. Inclusion and consistency proofs are checkable offline.
  • Signature scheme: what signs an STH, an evidence seal, a grant or an approver's decision, named by its Alg: ed25519, ecdsa-p256 (what most HSMs and cloud KMS can sign), ml-dsa-65, or the ed25519+ml-dsa-65 hybrid. Every artifact names its scheme and a verifier refuses a signature of another scheme.
  • Anchoring: publishing an STH to an independent log, which upgrades integrity to tamper-evidence against the operator. The shipped production anchor writes each head to an S3 bucket under Object Lock (anchoring), or to a Google Cloud Storage bucket with a locked retention policy (anchoring).
  • ProofBundle: a portable proof that a specific record is included under a signed tree head. It carries the record as the bytes the journal stores for it (record_bytes), which the verifier hashes without re-encoding.
  • Absence proof: a checkable proof that no record with a given key exists in the log (ProveAbsent / VerifyAbsence), so "this never happened" is provable, not just unlogged. Completes the trio with inclusion and consistency proofs.
  • EvidencePackage: a whole run's evidence in one portable file: a signed tree head plus an inclusion proof per material action, and optionally the run certificate, grant chain, and consistency proof. Built with audit.Evidence and checkable offline with bide audit verify-evidence. The package is sealed by signing a fixed-size digest of itself (format bide.audit.evidence.v6), so a signer with a message size limit, such as AWS KMS, can seal a package of any size; v5 packages still verify.
  • RunCertificate: a proof-carrying attestation of behavioral-property compliance over a whole run, checkable offline.
  • Grant / delegation: a signed capability a sub-agent can only narrow (attenuate). VerifyDelegationChain checks the chain offline; EarnedAuthority widens scope from a clean trail.
  • Quorum: governed k-of-n agreement among voters, with the tally anchored and re-checkable offline.
  • Key custody: where a signing key lives. An audit.Signer signs without exposing its key, so the key can sit in a PKCS#11 token (an HSM), AWS KMS, Google Cloud KMS or Azure Key Vault and never in the application's memory or on its disk; verifiers hold only the public key. Ed25519 or ECDSA P-256 (Azure Key Vault has only P-256). An approver decides from a terminal with an HSM, AWS KMS, Google Cloud KMS or Azure Key Vault key through bide-hsm approve, and gets its certificate request from bide-hsm csr. See key custody.
  • Selective disclosure: revealing some records while proving the rest exist, without showing their content. It limits what you reveal; it does not encrypt. See the security model.
  • Flow / conformance: the plan package is an optional builder of plan flows over the same durable core. A Flow is a reified topology of durable steps, authored in typed Go or loaded from declarative config (plan.Load); Topology and RenderMermaid expose its shape, and Conform checks a run's journal against it, proving the run followed the declared topology or flagging where it diverged. See the plan flows guide.

Structure ​

  • Footprint: the set of invariants (or variables) a tool or event can affect. Disjoint footprints commute, which is what lets governance verification stay local.
  • Port and adapter: the core defines interfaces (Model, Store, Tool, Anchor, ...); adapters plug in at the edges. The core carries no provider or infrastructure dependency. See extension points.
  • Tool-result codec: provider.ToolResultCodec (package model/provider, the kit adapters are built from) controls how a tool result is rendered for the model. The default (provider.JSONToolResultCodec) passes canonical JSON; codec/gcf encodes GCF (Graph Compact Format), a more token-efficient encoding for structured data, wired per adapter with WithToolResultCodec. It changes only what the model reads: the journal and audit trail keep the canonical JSON.

Apache-2.0 licensed.