SnapshotStorage

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>