Session lifecycle

The full path of a single conversation, from first prompt to deletion.

State machine

                     ┌──────────────┐
                     │  no session  │
                     └──────┬───────┘
                            │ first $prompt for (targetKey, profileKey)
                            ▼
                     ┌──────────────┐
       ┌─────────────│   created    │  row in `sessions`, turn_count=0
       │             └──────┬───────┘
       │                    │ $prompt arrives
       │                    ▼
       │             ┌──────────────┐
       │             │   running    │  AgentActor child mounted
       │             └──────┬───────┘
       │                    │ oracle loop completes
       │                    ▼
       │             ┌──────────────┐
       │             │     idle     │  child unmounts after TTL; row stays
       │             └──────┬───────┘
       │                    │ next $prompt → back to running
       │                    │
       │ $sessionDelete /   │
       │ $sessionClearAll  ▼
       │             ┌──────────────┐
       └────────────►│   deleted    │  rows removed, no resume possible
                     └──────────────┘

Persistence semantics

Session row. Persists in sessions until explicitly deleted. Survives Host restart.
Messages. Persist in session_messages. Append-only.
State (snapshot, REPL). Persists in session_state. Overwritten per turn.
Activity frames. Persist via the IAgentSessionStore backend (file or record store). Append-only per request.
The child AgentActor. Lives only while a request is in flight or resume window is open. Spawned on $prompt, unmounted via _pendingReapTimer on AgentsRoot (AgentsRoot.ts:151,188).

Idempotency

session.create is idempotent (INSERT OR IGNORE).
A $prompt with a requestId already in _processingRequestIds is dropped (the claimGlobalPromptRequest deduplication, AgentsRoot.ts:76-85, GLOBAL_PROMPT_DEDUP_TTL_MS = 5 * 60 * 1000).
$sessionDelete returns false if the session did not exist; that's the only time the call is non-destructive.

Bulk operations

Op	Effect
`$sessionList`	returns sessions for a `targetKey` (or all sessions)
`$sessionDelete`	drops one session and its messages/state
`$sessionClearAll`	drops every session, every message, every state row, and tears down active `AgentActor` children
`$sessionSeed`	writes a synthetic transcript; used by tests and tooling

$sessionClearAll is destructive — there is no soft-delete or trash. The op exists primarily for test fixtures and the "reset cognitive state" admin path.

Failure modes

Code	Meaning	Source
`AGENT_BUSY`	a request for the same session is already in flight	`AgentActor.MX_AGENT_ERRORS.BUSY`
`AGENT_TIMEOUT`	the prompt exceeded `promptTimeoutMs`	`AgentActor.MX_AGENT_ERRORS.TIMEOUT`
`LLM_API_FAILURE`	the inference call failed	`AgentActor.MX_AGENT_ERRORS.LLM_API_FAILURE`
`MAX_ITERATIONS`	the oracle loop hit `maxIterations` (default 25)	`AgentActor.MX_AGENT_ERRORS.MAX_ITERATIONS`
`TOOL_SCOPE_VIOLATION`	the model called a tool outside the allowed subtree	`AgentActor.MX_AGENT_ERRORS.TOOL_SCOPE_VIOLATION`
`TOOL_INVOKE_FAILED`	the underlying actor call failed	`AgentActor.MX_AGENT_ERRORS.TOOL_INVOKE_FAILED`

All error codes are defined in AgentActor.ts:101-112.

Session lifecycle ​

State machine ​

Persistence semantics ​

Idempotency ​

Bulk operations ​

Failure modes ​