Checkpoints

A checkpoint is a structured progress report an agent submits during a mission. For enforced-mode agents, checkpoints are load-bearing - the passport TTL ties to the checkpoint interval, so each successful checkpoint extends the leash. For logged and standard modes, checkpoints are advisory but still written to the audit chain.

Checkpoints are not optional in enforced mode. A missed checkpoint triggers thecheckpoint_silence detector and the passport dies at its current expiry.

Shape

json
{
  "services_used":  ["slack", "github"],
  "actions_count":  3,
  "delegated_to":   ["agt_notion_writer"],
  "summary":        "Pulled ticket context; drafted reply"
}
  • services_used - every service hit since the last checkpoint
  • actions_count - integer, number of discrete operations
  • delegated_to - optional, agent IDs the parent delegated to in this window
  • summary - free text, max 1000 chars

Interval presets

Set at issue time via checkpoint_interval_seconds. Choose from presets or a custom value (60s min, 3600s max).

  • frequent - 2 minutes (high-risk, real-money paths)
  • standard - 5 minutes (default)
  • relaxed - 15 minutes (longer missions with lower stakes)
  • marathon - 60 minutes (batch jobs)

TTL tying in enforced mode

When an agent is in enforced mode, the passport's actual TTL is the minimum of the requested ttl_seconds and the interval. Every successful checkpoint bumps the passport's exp forward by one interval; miss one and the passport dies.

text
issue:     exp = now + interval
chk #1:    exp = chk_time + interval
chk #2:    exp = chk_time + interval
(miss):    exp unchanged  →  passport expires  →  checkpoint_silence signal

Catching undeclared services

When a checkpoint reports a service not listed in the passport'sintent_services, it surfaces immediately rather than waiting for checkout. In enforced mode this is recorded ascredential_outside_scope critical; in logged mode as warning; in standard mode the checkpoint is accepted without flagging.

Endpoint

bash
curl -X POST https://api.getstack.run/v1/passports/pp_8f3a/checkpoint \
  -H "Authorization: Bearer $STACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "services_used": ["slack", "github"],
    "actions_count": 3,
    "summary": "Pulled ticket context"
  }'

Related

  • /docs/guides/enforced-mode - full enforced-mode walkthrough
  • /docs/guides/passport-lifecycle - issue → checkpoint → checkout → review
  • /docs/concepts/detectors - checkpoint_silence and post-hoc review flag catalog
stack | docs