01What it is
@hazeljs/agent-vm lets tools declare an effect class so the runtime can journal reversible work, block irreversible side effects inside losing speculative branches, and undo runs. Key decorators: @Pure, @Read, @Reversible, @Irreversible, @Compensate, @Atomic, @Speculate. Attach with attachAgentVm(runtime) or AGENT_OS_AGENT_VM=1.
02Problem it solves
- Agent holds a seat/lock then loses — @Reversible + journal auto-compensates losers
- Wrong branch charged a card — @Irreversible acts as a speculation barrier
- Need to undo an entire run — @Atomic + coordinator.undoRun(runId)
- Explore K plans in parallel — @Speculate commits the winner, rolls back losers
03How you use it today
Install @hazeljs/agent-vm, call attachAgentVm(runtime), then annotate tools. Tools without effect decorators default to irreversible — existing agents behave the same until you opt in. Prefer attachAgentVm over wiring setEffectGate by hand.
04Where it sits in the stack
Optional effect layer on top of Agent Runtime. Gatekeeper still authorizes whether a tool may run; Agent VM types what kind of world-change that tool is allowed to make during speculation.
05Boundaries
- Not a process hypervisor over hazeld — Local Agent OS does not treat VM that way
- Not required for every agent — opt-in package
- Forgetting @Compensate on @Reversible tools is a common mistake
06FAQ
- Is Agent VM a virtual machine?
- No. It is an effect lattice for tool side effects — not a guest OS or container runtime.
- Will attaching Agent VM change my existing tools?
- Not until you annotate them. Unannotated tools stay irreversible.
- Does it replace Gatekeeper?
- No. Gatekeeper decides allow / deny / require-approval. Agent VM classifies effect types after authorization.
07Attach Agent VM
import { attachAgentVm } from '@hazeljs/agent-vm';
// Opt-in — tools without effect decorators stay irreversible (unchanged).
const vm = attachAgentVm(runtime, { barrierMode: 'converge' });
// Or: AGENT_OS_AGENT_VM=1 + attachAgentVmFromEnv(runtime)