window.api.sessions — Chat Session Persistence API

window.api.sessions persists chat sessions to disk as individual JSON files — not in the SQLite database. Each session is stored at sessions/<projectId>/<sessionId>.json under the app data directory, alongside a small sessions/manifest.json that restores the user’s last-open project and session after an app restart. Conversations are never lost across restarts: interrupted sessions are restored with an error status so the user can retry.

The session persistence layer queues writes internally to avoid race conditions between rapid message saves and concurrent session updates. You do not need to serialise calls yourself — fire-and-forget saves are safe.

Methods

`loadAll()`

Loads every per-session file from disk plus the last-open manifest, applies sanitization and interrupted-session normalization, and returns the full set in one call. Call this once at app startup to restore the previous conversation state. Returns: Promise<LoadAllSessionsResult>

sessions

PersistedChatSession[]

required

All persisted sessions across all projects, with interrupted runtime state normalized to status: 'error'.

manifest

PersistedSessionManifest

required

The last-open project and session pointer. Fields are undefined when no manifest exists yet.

`saveSession(session)`

Persists a single chat session to its per-file path (upsert semantics). The session is serialized and queued for writing; oversized text fields are bounded automatically by the persistence layer.

session

PersistedChatSession

required

The full session record to persist. See the PersistedChatSession type reference below.

Returns: Promise<void>

`deleteSession(request)`

Removes a single session file from disk.

request

DeleteSessionRequest

required

Show DeleteSessionRequest fields

projectId

string

required

ID of the project that owns the session.

sessionId

string

required

ID of the session to delete.

Returns: Promise<void>

`deleteProjectSessions(request)`

Removes every session file under a project directory. Use this before deleting the project itself to clean up all associated conversation history.

request

DeleteProjectSessionsRequest

required

Show DeleteProjectSessionsRequest fields

projectId

string

required

ID of the project whose sessions should be deleted.

Returns: Promise<void>

`saveManifest(request)`

Persists the last-open project and session pointer so the app can restore the user’s view on next launch.

request

SaveSessionManifestRequest

required

Show SaveSessionManifestRequest fields

lastProjectId

string

ID of the most recently active project.

lastSessionId

string

ID of the most recently active session.

Returns: Promise<void>

Type reference

`PersistedChatSession`

The full durable record for a single conversation session. This is the value you pass to saveSession and receive back from loadAll.

Field	Type	Description
`id`	`string`	Unique session identifier
`projectId`	`string`	Owning project ID (authoritative from the file’s directory path on load)
`title`	`string`	Session display title
`cwd`	`string`	Working directory for the session
`status`	`PersistedSessionStatus`	`'idle' \| 'running' \| 'waiting-permission' \| 'error'`
`messages`	`PersistedChatMessage[]`	Ordered conversation messages
`activities`	`PersistedToolActivity[]`	Tool call activity records
`activeRun`	`PersistedActiveRun \| undefined`	Pointer to the in-flight prompt (cleared after restart)
`error`	`string \| undefined`	Error message when `status` is `'error'`
`artifacts`	`PersistedArtifact[]`	Artifact references associated with the session
`createdAt`	`number`	Creation timestamp (epoch milliseconds)
`updatedAt`	`number`	Last-updated timestamp (epoch milliseconds)

On loadAll, sessions that were 'running' or 'waiting-permission' when the app closed are automatically restored with status: 'error' and activeRun cleared, because the agent runtime state cannot survive a process restart. The error message is set to "Session was interrupted before the app closed." unless a prior error was already recorded.

`PersistedChatMessage`

Field	Type	Description
`id`	`string`	Unique message identifier
`role`	`'user' \| 'agent'`	Who sent the message
`content`	`string`	Message text
`status`	`'complete' \| 'streaming' \| 'error'`	Delivery status (`'streaming'` becomes `'error'` after restart)
`streamId`	`string \| undefined`	Live stream correlation ID
`responseToMessageId`	`string \| undefined`	ID of the user message this reply responds to
`eventIds`	`string[]`	ACP event IDs associated with this message
`artifactIds`	`string[]`	IDs of artifacts produced by this message
`uploads`	`PersistedUploadedAttachment[]`	File attachments sent with this message
`createdAt`	`number`	Creation timestamp (epoch milliseconds)
`updatedAt`	`number`	Last-updated timestamp (epoch milliseconds)

`PersistedSessionManifest`

The small pointer file that restores the user’s last-open view.

Field	Type	Description
`version`	`1`	File format version
`lastProjectId`	`string \| undefined`	Last-open project ID
`lastSessionId`	`string \| undefined`	Last-open session ID

`PersistedSessionStatus` values

Value	Description
`'idle'`	No active run; ready for a new prompt
`'running'`	Agent is processing a prompt
`'waiting-permission'`	Agent is blocked on a permission approval
`'error'`	Last run ended in an error or was interrupted

Usage example

import type {
  LoadAllSessionsResult,
  PersistedChatSession,
  PersistedSessionManifest
} from '../../../../shared/session-persistence'

// On app startup: restore all sessions and the last-open pointer
async function initializeSessions() {
  const { sessions, manifest }: LoadAllSessionsResult =
    await window.api.sessions.loadAll()

  console.log(`Loaded ${sessions.length} session(s)`)

  const lastSessionId = manifest.lastSessionId
  const lastProjectId = manifest.lastProjectId

  if (lastSessionId && lastProjectId) {
    console.log(`Restoring last session: ${lastSessionId} in project: ${lastProjectId}`)
  }

  return { sessions, manifest }
}

// Save a session after each message update
async function persistSession(session: PersistedChatSession) {
  await window.api.sessions.saveSession(session)
}

// Update the manifest when the user switches sessions
async function updateLastOpen(projectId: string, sessionId: string) {
  await window.api.sessions.saveManifest({
    lastProjectId: projectId,
    lastSessionId: sessionId
  })
}

// Delete a session
async function removeSession(projectId: string, sessionId: string) {
  await window.api.sessions.deleteSession({ projectId, sessionId })
}

// Delete all sessions for a project before deleting the project
async function removeProject(projectId: string) {
  await window.api.sessions.deleteProjectSessions({ projectId })
  await window.api.projects.delete({ id: projectId })
}

IPC API

Configuration

window.api.sessions — Chat Session Persistence API

Methods

`loadAll()`

`saveSession(session)`

`deleteSession(request)`

`deleteProjectSessions(request)`

`saveManifest(request)`

Type reference

`PersistedChatSession`

`PersistedChatMessage`

`PersistedSessionManifest`

`PersistedSessionStatus` values

Usage example

Build docs developers (and LLMs) love

IPC API

Configuration

Documentation Index

​Methods

​loadAll()

​saveSession(session)

​deleteSession(request)

​deleteProjectSessions(request)

​saveManifest(request)

​Type reference

​PersistedChatSession

​PersistedChatMessage

​PersistedSessionManifest

​PersistedSessionStatus values

​Usage example

Build docs developers (and LLMs) love

Methods

`loadAll()`

`saveSession(session)`

`deleteSession(request)`

`deleteProjectSessions(request)`

`saveManifest(request)`

Type reference

`PersistedChatSession`

`PersistedChatMessage`

`PersistedSessionManifest`

`PersistedSessionStatus` values

Usage example