Skip to content
apomesh

Sessions, events & durability

A session is one run of a root agent toward a goal: the root spawns a tree of child agents, they do the work, and the session ends in a single terminal outcome — done, failed, or cancelled. apomesh never stores that run as a mutable record you overwrite. Instead it appends an event for every state change — an agent created, a token streamed, a cost incurred, a checkpoint written, a terminal outcome reached — to an ordered, append-only event log. The current state of a session is derived by folding its events. This is event-sourcing, and it is the single source of truth the entire platform reads from. For where sessions sit in the whole system, start at the architecture overview.

One log, everything derived

Section titled “One log, everything derived”

The log is authoritative for everything that happened in a session, and nothing observable is allowed to bypass it. Every state-bearing action emits; every consumer derives from that one stream — a driver’s live tail, the audit view, cost rollups, and full session reconstruction all read the same log. There is no parallel channel: no side table, no metrics write that skips the bus. A signal that isn’t on the log does not exist as far as audit or replay is concerned.

That single discipline is what buys the platform four distinct capabilities from one mechanism:

One append-only log, four capabilities: the orchestrator is the sole writer; every consumer derives its view by reading the same stream
  • Live observation. A driver subscribes to a session’s events and watches them arrive as they append — planning, dispatches, streamed tokens, verification, terminal state — over gRPC streaming or REST server-sent events.
  • Reconstruction. Because state is the fold of the log, apomesh rebuilds a session’s structure — the spawn tree, per-agent status and budgets — purely by replaying events. Historical sessions are browsable the same way live ones are.
  • Recovery. A session’s life can outlast the daemon process. A durable bootstrap event plus coordinator checkpoints make a non-terminal session rehydratable from the log alone, so a worker loss or a full restart resumes rather than restarts.
  • Replay. A run’s model calls can be captured once and replayed deterministically, so an experiment or an incident is re-runnable without hitting a live provider.

The sub-pages

Section titled “The sub-pages”

This group takes each capability to mechanism depth:

  • The event log — the envelope, the closed Payload vocabulary at reader altitude, who may emit, what deliberately never rides the log, and the surfaces that consume it.
  • Reconstruction & recovery — the fold that rebuilds session state, the two kinds of checkpoint, resume after a worker disconnect and after a daemon restart, and how a resumed session composes the same agent it started with.
  • Replay & history — the terminated-session index the console browses, deterministic replay via cassettes, and the open-stack reproducibility posture.

Guarantees

Section titled “Guarantees”
  • Reconstructible. A session’s structure is rebuildable from its events alone.
  • Single writer, no side channels. Only the orchestrator writes the log; every observable signal flows through it. See Control & execution.
  • Resumable. Non-terminal sessions survive a worker loss and a daemon restart; terminal sessions are never re-run.
  • Deterministic. What a session was built from is frozen at start and re-read on resume, so a restart reproduces the original agent exactly.

Where this shows up

Section titled “Where this shows up”