Skip to main content

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​

Checkpoint

The snapshot to persist.

Returns​

Promise<void>

Throws​

The store's error when it cannot persist the checkpoint.