SnapshotStorage

Defined in: src/session/storage.ts:47

Interface for snapshot persistence. Implementations provide storage backends (S3, filesystem, etc.).

File layout convention:

sessions/<session_id>/
  scopes/
    agent/<scope_id>/
      snapshots/
        snapshot_latest.json
        immutable_history/
          snapshot_<uuid>.json
          snapshot_<uuid>.json

Methods

saveSnapshot()

saveSnapshot(params): Promise<void>;

Defined in: src/session/storage.ts:51

Persists a snapshot to storage.

Parameters

| Parameter | Type | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | params | { location: SnapshotLocation; snapshotId: string; isLatest: boolean; snapshot: Snapshot; } | | params.location | SnapshotLocation | | params.snapshotId | string | | params.isLatest | boolean | | params.snapshot | Snapshot |

Returns

Promise<void>

---

loadSnapshot()

loadSnapshot(params): Promise<Snapshot>;

Defined in: src/session/storage.ts:61

Loads a snapshot from storage.

Parameters

| Parameter | Type | | -------------------- | ------------------------------------------------------------------------------------- | | params | { location: SnapshotLocation; snapshotId?: string; } | | params.location | SnapshotLocation | | params.snapshotId? | string |

Returns

Promise<Snapshot>

---

listSnapshotIds()

listSnapshotIds(params): Promise<string[]>;

Defined in: src/session/storage.ts:77

Lists all available immutable snapshot IDs for a session scope, sorted chronologically. Snapshot IDs are UUID v7 strings vended by the SDK — callers should treat them as opaque handles and never construct them manually.

Typical pagination pattern:

const page1 = await storage.listSnapshotIds({ location })
const page2 = await storage.listSnapshotIds({ location, startAfter: page1.at(-1) })

limit caps the number of returned IDs. startAfter is an exclusive cursor (the last ID from the previous page); it must be a UUID v7 obtained from a prior listSnapshotIds call.

Parameters

| Parameter | Type | | -------------------- | --------------------------------------------------------------------------------------------------------- | | params | { location: SnapshotLocation; limit?: number; startAfter?: string; } | | params.location | SnapshotLocation | | params.limit? | number | | params.startAfter? | string |

Returns

Promise<string[]>

---

deleteSession()

deleteSession(params): Promise<void>;

Defined in: src/session/storage.ts:82

Deletes all snapshots and directories belonging to the session ID.

Parameters

| Parameter | Type | | ------------------ | --------------------------- | | params | { sessionId: string; } | | params.sessionId | string |

Returns

Promise<void>

---

loadManifest()

loadManifest(params): Promise<SnapshotManifest>;

Defined in: src/session/storage.ts:87

Loads the snapshot manifest.

Parameters

| Parameter | Type | | ----------------- | ------------------------------------------------------------ | | params | { location: SnapshotLocation; } | | params.location | SnapshotLocation |

Returns

Promise<SnapshotManifest>

---

saveManifest()

saveManifest(params): Promise<void>;

Defined in: src/session/storage.ts:92

Saves the snapshot manifest.

Parameters

| Parameter | Type | | ----------------- | -------------------------------------------------------------------------------------------------------------------- | | params | { location: SnapshotLocation; manifest: SnapshotManifest; } | | params.location | SnapshotLocation | | params.manifest | SnapshotManifest |

Returns

Promise<void>