Session

A session is one conversation's state as one JSON blob. The host loads it, passes it to turn(), and saves what comes back with the version it loaded. The framework never saves anything; it returns the new blob on TurnResult.session. Everything the framework remembers between turns is in this blob: the live runs, the data collected so far, the claims that stop a flow from starting twice, and the last 50 message ids.

Signature

tsCopy
interface Session<D = unknown> {
  id: string;
  v: 4;
  version: number;
  data: Partial<D>;
  runs: Run[];
  claims: Record<string, { at: string }>;
  inputs: string[];
  lastUserAt?: string;
  lastAssistantAt?: string;
  history?: History;
  metadata: Record<string, unknown>;
}

interface Run {
  id: string;
  flowId: string;
  anchor: string;
  dedupeKey: string;
  stepId: string | null;
  status: RunStatus;
  trigger: { kind: TriggerKind; key: string; payload?: unknown };
  input?: unknown;
  hop: number;
  startedAt: string;
  suspendedAt?: string;
  staying?: true;
  waiting?: { kind: "timer" | "event"; key?: string; until?: string; setAt: string; event?: string };
  asked: Record<string, number>;
  visits: Record<string, number>;
  outcomes: StepOutcome[];
}

type RunStatus = "running" | "asking" | "waiting" | "suspended";
type TriggerKind = "message" | "mention" | "silence" | "event" | "start" | "flow";

interface Store<D = unknown> {
  load(id: string): Promise<Session<D> | null>;
  save(session: Session<D>, expectedVersion: number): Promise<Session<D>>;
}

From src/types/session.ts. Every date is ISO 8601 text, never a Date: the blob has to survive JSON.stringify and come back the same.

Session fields

Run fields

RunStatus

Run.waiting

StepOutcome

One line per step for the host's execution log: { runId?, flowId?, stepId?, key?, kind, status, code?, message?, detail?, next?, until?, at, llmCalls? }. kind is prompt | collect | say | do | wait | if | idle; status is ok | skipped | failed | waiting | deferred. code says why, and is what you switch on; message is its English sentence, filled by the framework from OUTCOME_MESSAGES; detail carries only what this one line is about (a field name, an action's own words, your silenced reason). Each run keeps its last 50; the turn returns all of this turn's lines on TurnResult.outcomes. The full code vocabulary is in Outcomes.

Store

Two methods, one rule. load(id) returns the session or null. save(session, expectedVersion):

• expectedVersion: 0 inserts, and fails if a row already exists.
• Any other value updates only when the stored version is exactly that number.
• A failed check throws SessionConflictError with expectedVersion and the version it found (undefined when the row is gone).
• Success stores expectedVersion + 1 and returns the session with that version.

The host loop is load → turn → if changed, save(result.session, loaded?.version ?? 0) → send messages[] → enqueue schedule[]. On a conflict, nothing has left the host's hands: load again and replay the same input (invariant I1, see Runs and waits). The seven stores are in Stores.

Keys

Every key is built from ids the host already has, so a replay mints the same keys and the host can dedupe sends and jobs on them. From src/core/Runner.ts.

The trigger key depends on what started the run:

Limits

All from src/core/Runner.ts.

Example

tsCopy
import { MemoryStore, SessionConflictError } from "@falai/agent";
import type { Session } from "@falai/agent";

type Data = { nome: string };

const store = new MemoryStore<Data>();
console.log(await store.load("s1")); // null: nothing saved yet

const fresh: Session<Data> = {
  id: "s1",
  v: 4,
  version: 0,
  data: { nome: "Ana" },
  runs: [],
  claims: {},
  inputs: [],
  metadata: {},
};

const v1 = await store.save(fresh, 0);
console.log(v1.version); // 1

const loaded = await store.load("s1");
console.log(loaded?.version); // 1

try {
  await store.save(fresh, 0); // a row exists: the insert loses
} catch (error) {
  if (error instanceof SessionConflictError) {
    console.log(error.expectedVersion, error.actualVersion); // 0 1
  }
}

See also

• Runs and waits: the floor, waits, wakes and the invariants.
• Stores: the seven Store classes and the schema each expects.
• Outcomes: every outcome code and when it is emitted.
• Persistence: the host loop, migrateSession and assertSession.
• Errors: SessionConflictError and InvalidSessionError.