Checkpoint

When to useCopy Anchor Link

• The agent is partway through a long run that changed things, saved restore points along the way, and the user may want to go back before it continues.
• The user asks to undo part of the run, or questions a step the agent took a while ago.

When not to useCopy Anchor Link

• The agent can't actually roll back to the states it would list. Never offer a restore it can't perform.
• The user only wants to see what the agent did. Use the Activity Trail.
• One action is waiting for approval. Use the Approval Request.
• Something failed and the user needs a way forward. Use the Recovery Panel.

How the agent should use itCopy Anchor Link

• List only checkpoints it really saved, oldest first, each with the time it was saved.
• Write change as what that step did, in a few words with real counts: "14 closed with no reply in 30 days".
• Set currentId to where the run is now; it defaults to the last checkpoint.
• Use caveat for anything a restore can't undo (emails sent, payments made). Leave it out when everything is reversible.
• Pause the run while it's open. On restore, roll back to checkpointId, say what was undone and wait. On continue, carry on from the current state.

InteractionCopy Anchor Link

• Each checkpoint is a radio option on a rail, oldest at the top. The current one is selected at the start and tagged "Current".
• Selecting an earlier checkpoint dims the ones after it (read as "would be undone") and turns the button into "Restore…".
• "Restore…" opens an inline confirm step in the footer, not a modal: "Go back to “Tagged and routed”? This undoes 2 later checkpoints.", the caveat under it, then Back and Restore. Escape or Back returns to the list.
• After a restore, the later checkpoints collapse away, the target becomes current and the footer records "Restored to “…” · 2 checkpoints undone." After continue, it records "Continued from “…”."
• While streaming, checkpoints arrive one by one and the controls are disabled. Long lists scroll inside the card.

AccessibilityCopy Anchor Link

• The list is a radio group labelled by the card title; arrow keys move between checkpoints. Each option reads its label, time and change, plus "would be undone" when a restore would remove it.
• Selecting a checkpoint announces what restoring it would undo. The confirm step is a labelled group that takes focus when it opens; Back returns focus to the button.
• Buttons are at least 44px tall with visible focus rings. The record line is in a polite live region.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/checkpoint.json

UsageCopy Anchor Link

import { tool } from "ai"
import { checkpointTool } from "@/components/genui/checkpoint.schema"

const tools = {
  [checkpointTool.name]: tool({
    description: checkpointTool.description,
    inputSchema: checkpointTool.inputSchema,
  }),
}

import { Checkpoint } from "@/components/genui/checkpoint"

function ToolPart({ part, addToolResult }) {
  if (part.type !== "tool-show_checkpoints") return null

  return (
    <Checkpoint
      {...part.input}
      status={part.state === "input-streaming" ? "streaming" : undefined}
      result={part.state === "output-available" ? part.output : undefined}
      onResult={(result) =>
        addToolResult({
          tool: "show_checkpoints",
          toolCallId: part.toolCallId,
          output: result,
        })
      }
    />
  )
}

The result tells the agent what the user chose:

{ action: "restore", checkpointId: "ckpt-2" }
{ action: "continue" }

SchemaCopy Anchor Link

Host props: status (streaming, ready, submitting, restored, continued), onResult, result and className.

SourceCopy Anchor Link