State

The state component lets you checkpoint execution state, branch to explore alternatives, and restore to roll back when things go wrong.

Checkpoint

Save a snapshot of execution state:

const cp = await harness.state().checkpoint({
  step: 1,
  label: "before-decision",
  metadata: { confidence: 0.7 },
})
// cp.id — unique checkpoint ID
// cp.createdAt — timestamp

Branch

Branch from any checkpoint to explore an alternative path:

const cp1 = await harness.state().checkpoint({
  step: 1,
  label: "before-decision",
})

// try path A
await harness.state().checkpoint({ step: 2, label: "path-a" })

// branch from cp1 to try path B
const branch = await harness.state().branch(cp1.id, {
  step: 2,
  label: "path-b",
})
// branch.parentCheckpointId === cp1.id

Branching creates a new checkpoint whose parentCheckpointId points to the branching point. This gives you a tree of execution paths you can navigate.

Restore

Roll back to a previous checkpoint:

await harness.state().restore(cp1.id)

List

const checkpoints = await harness.state().list()

Returns all checkpoints for the current agent + session, ordered by creation time.

Get a specific checkpoint

const cp = await harness.state().getCheckpoint(checkpointId)