Interface: ICheckpointStore
Defined in: packages/agentos/src/orchestration/checkpoint/ICheckpointStore.ts:131
Persistence contract for checkpoint snapshots.
Implementations may back this with in-memory maps (for testing / ephemeral runs), SQLite / Postgres rows, object storage blobs, or any other durable medium.
All methods are async to accommodate I/O-bound backends without interface changes.
Methods
delete()
delete(
checkpointId):Promise<void>
Defined in: packages/agentos/src/orchestration/checkpoint/ICheckpointStore.ts:200
Permanently remove a checkpoint from the store.
Silently succeeds when checkpointId does not exist.
Parameters
checkpointId
string
The checkpoint to remove.
Returns
Promise<void>
fork()
fork(
checkpointId,patchState?):Promise<string>
Defined in: packages/agentos/src/orchestration/checkpoint/ICheckpointStore.ts:214
Create a new run branching from an existing checkpoint.
The operation deep-clones the source checkpoint, assigns a fresh runId and
checkpoint id, applies any patchState overrides, persists the new checkpoint,
and returns the new runId.
Parameters
checkpointId
string
The checkpoint to fork from.
patchState?
Partial<GraphState<unknown, unknown, unknown>>
Optional partial GraphState overrides applied after cloning.
Returns
Promise<string>
The new runId for the forked run.
Throws
When checkpointId does not exist.
get()
get(
checkpointId):Promise<Checkpoint|null>
Defined in: packages/agentos/src/orchestration/checkpoint/ICheckpointStore.ts:154
Load a checkpoint by its unique checkpoint identifier.
Parameters
checkpointId
string
The exact checkpoint id assigned at save-time.
Returns
Promise<Checkpoint | null>
The matching checkpoint, or null when none exists.
latest()
latest(
runId):Promise<Checkpoint|null>
Defined in: packages/agentos/src/orchestration/checkpoint/ICheckpointStore.ts:178
Return the most recently persisted checkpoint for a run, or null when the run
has no checkpoints. Of checkpoints with the same timestamp, the one saved last
is the most recent.
Parameters
runId
string
The graph run identifier.
Returns
Promise<Checkpoint | null>
list()
list(
graphId,options?):Promise<CheckpointMetadata[]>
Defined in: packages/agentos/src/orchestration/checkpoint/ICheckpointStore.ts:188
List lightweight metadata descriptors for all checkpoints belonging to a graph.
Parameters
graphId
string
The compiled graph identifier.
options?
limit?
number
Maximum number of entries to return (most-recent-first).
runId?
string
Optional filter to a single run within the graph.
Returns
Promise<CheckpointMetadata[]>
Array of CheckpointMetadata, sorted by timestamp descending.
load()
load(
runId,nodeId?):Promise<Checkpoint|null>
Defined in: packages/agentos/src/orchestration/checkpoint/ICheckpointStore.ts:169
Load a checkpoint for the given runId.
When nodeId is supplied, returns the most recent checkpoint for that specific
node within the run. When nodeId is omitted, returns the most recent checkpoint
for the run regardless of node (equivalent to latest(runId)). The most recent
checkpoint has the latest timestamp and, of checkpoints with the same
timestamp, was saved last: the runtime can save several in one millisecond.
Parameters
runId
string
The graph run identifier.
nodeId?
string
Optional node filter.
Returns
Promise<Checkpoint | null>
The matching checkpoint, or null when none exists.
save()
save(
checkpoint):Promise<void>
Defined in: packages/agentos/src/orchestration/checkpoint/ICheckpointStore.ts:146
Persist a checkpoint snapshot.
If a checkpoint with the same id already exists it is overwritten.
The runtime awaits each save and does not retry one that rejects: the run that
asked for the checkpoint ends with the store's error, which GraphRuntime.stream()
throws, and a resume by the run id continues from the last checkpoint the store
saved. When a save inside a parallel batch rejects, the run ends with the error
once the batch's other nodes have finished.
Parameters
checkpoint
The snapshot to persist.
Returns
Promise<void>
Throws
The store's error when it cannot persist the checkpoint.