Agents & Sessions

What is a session?

A session is a durable, addressable unit of agent execution. It is not an in-memory object — it is a set of rows in the database that persist across server restarts, network interruptions, and module reloads.

Sessions give agents:

Resumability — pick up where they left off after failure
Observability — every state transition is a queryable row
Auditability — the event log records every tool call and message exchange

Session lifecycle

Created ──► Active ──► Suspended ──► Resumed ──► Completed
                          │
                          └──► Handed off to supervisor

State	Description
`created`	Session initialized, no messages yet
`active`	Agent is processing
`suspended`	Waiting for external input (human approval, tool result)
`completed`	Terminal state — session closed normally
`failed`	Terminal state — session closed with error

Tool authorization

Before an agent can invoke a tool, Cosmictron checks:

Tool is registered — the tool name exists in the module’s capability manifest
Agent has permission — row-level security on the tool_calls table
Not duplicate — the call_id idempotency key has not been used

The idempotency check is enforced at the database level, not in application code. This means:

Retries on network failure are safe
The same tool call cannot be double-executed even if the client sends it twice

Supervisor handoff

When an agent exceeds its capability (e.g., requires human approval or a higher-privileged agent), it writes a handoff record:

#[reducer]
pub fn request_supervisor_handoff(
    _ctx: &ReducerContext,
    session_id: String,
    reason: String,
    required_capability: String,
) {
    HandoffRequest::insert(HandoffRequest {
        session_id,
        reason,
        required_capability,
        status: "pending".to_string(),
        ..Default::default()
    }).unwrap();
}

The supervisor agent subscribes to SELECT * FROM handoff_requests WHERE status = 'pending' and receives real-time deltas as new requests arrive.

Voice provider support

Cosmictron includes lifecycle harnesses for voice/media workflows:

Provider-neutral telephony ingress
Room bridge and recording tables
Retention workflow reducers
Validation evidence tables (for compliance)

Voice sessions use the same session model: every turn is a row, every tool call is idempotent, and the full conversation is queryable.

MCP and A2A protocols

Cosmictron is the host that MCP (Model Context Protocol) and A2A (Agent-to-Agent) protocols run on top of:

MCP outward — agents call external tools via the MCP client built into the WASM host functions
A2A outward — agents communicate with foreign agents via the A2A protocol; Cosmictron maintains the shared event log

The unified event log means every MCP tool call, every A2A message, and every state write shares the same sequence number space — making cross-protocol replay deterministic.

Real-time subscriptions

Clients see agent state changes as they happen:

const sub = await client.subscribe(
  `SELECT * FROM agent_state
   WHERE session_id = :sid
   ORDER BY id`,
  { sid: 'session-abc' }
);

sub.on('update', ({ inserts, deletes }) => {
  // inserts: new rows added since last delta
  // deletes: rows removed since last delta
});

Subscriptions are compiled to DBSP circuits — incremental maintenance, not full re-scan on each write.