Data model¶

The Task payload is fully relational: every routing field plus the message body lives in its own typed column. The only JSON TEXT blob is agents.agent_card_json, which stores an AgentCard-shaped document.

The model is predominantly relational: every queried field on tasks is a typed column, and the only opaque payload is the agent_card_json document on agents.

Schema management is handled by Alembic; the runtime engine is SQLAlchemy 2.x with the synchronous pysqlite driver. The schema is created by a single initial migration; operators apply it once via cafleet db init before starting the server.

SQL Schema¶

All tables key on INTEGER columns. The three minted-id tables (fleets, agents, tasks) use INTEGER PRIMARY KEY AUTOINCREMENT. AUTOINCREMENT creates a per-table sqlite_sequence row that tracks the high-water mark, so ids are never reused — even after the highest row is deleted. The first AUTOINCREMENT value is 1, so real ids are always >= 1; this leaves 0 free as a sentinel (see tasks.to_agent_id). The other tables — agent_placements, monitor_config, and monitor_runtime — are the integer PKs without AUTOINCREMENT: each reuses a parent id (agents.agent_id for the first two, fleets.fleet_id for monitor_runtime) as a 1:1 PK rather than minting a fresh sequence.

fleets¶

Fleet deletion is a soft-delete keyed on deleted_at. See cli-options.md fleet delete for the observable delete behavior.

Root Director bootstrap¶

cafleet fleet create writes the fleet row, the root Director (and its placement), the director_agent_id back-reference, and the built-in Administrator in one all-or-nothing transaction. See cli-options.md fleet create for the observable bootstrap behavior.

agents¶

Indexes:

Deregistration is a soft-delete: status='deregistered' plus deregistered_at is set in a single statement. There is no row delete and no background cleanup loop. Active query paths filter status='active' so dead rows are invisible to normal traffic.

Built-in Administrator agent¶

Each fleet owns exactly one built-in Administrator agent, distinguished by a flag inside agent_card_json (cafleet.kind == "builtin-administrator") rather than a separate table or column:

{
  "name": "Administrator",
  "description": "Built-in administrator agent for fleet <fleet_id>",
  "skills": [],
  "cafleet": {
    "kind": "builtin-administrator"
  }
}

The cafleet.* namespace inside agent_card_json is reserved for broker-owned flags; callers cannot set cafleet.kind through any public path. The Administrator row is written as the final operation of the fleet-create bootstrap transaction, and its registered_at matches fleets.created_at. No migration seeds it — the single initial migration is schema-only.

Invariant: Every fleet has exactly one active Administrator agent. The WebUI surfaces a derived kind field ("builtin-administrator" | "user") so it can locate the Administrator without matching on the name.

Protection: The Administrator is a write-only identity — it is used as the WebUI's implicit sender but never receives messages or a tmux pane. It cannot be deregistered (Administrator cannot be deregistered) and cannot be made a Director (Administrator cannot be a director). It is excluded from broadcast recipients, though it may itself be the broadcast sender.

tasks¶

Indexes:

agent_placements¶

Indexes:

Placement rows are hard-deleted (not soft-deleted) when the agent is deregistered through any path. They have no historical value and must not outlive the agent they describe.

If a user kills a pane manually without going through cafleet member delete, the placement row stays until the next member delete resolves it; the "pane already gone" case is handled gracefully.

monitor_config¶

Per-agent monitoring schedule, one row per pane-bound agent. The cafleet monitor process reads this table each tick to decide which agents are due (see Monitoring).

A row is inserted automatically at registration for every agent that has a tmux pane — the root Director and every member. The write-only Administrator and card-only agent register calls (no placement) are not enrolled: only an agent with a pane can be pinged. There is no fleet_id column — fleet scoping is reached through the monitor_config.agent_id → agents.agent_id → agents.fleet_id join (the same pattern agent_placements uses), and director-vs-member is derived at scan time (agent_id == fleets.director_agent_id), never denormalized.

The row is hard-deleted (not soft-deleted) when the agent is deregistered, alongside its agent_placements row — runtime config with no historical value, on the same lifecycle as the placement.

monitor_runtime¶

Per-fleet process and heartbeat state, one row per fleet. A dedicated single-row-per-fleet table (rather than columns on fleets) keeps high-write heartbeat telemetry off the slow-changing fleet identity row, models "no monitor" cleanly as "no row", and lets single-instance claims and teardown operate independently of the fleets lifecycle.

The monitor_runtime row is deleted explicitly inside the fleet delete transaction (along with the fleet's monitor_config rows). Because agents are soft-deregistered and fleets soft-deleted, neither the CASCADE off agents nor the RESTRICT off fleets fires on the normal delete paths — the rows are cleaned explicitly, mirroring how agent_placements is explicitly deleted today.

Foreign key enforcement¶

SQLite ignores foreign key declarations unless PRAGMA foreign_keys=ON is issued on every connection. A SQLAlchemy engine connect event listener runs the PRAGMA on every new connection.

The foreign keys on agents.fleet_id, tasks.context_id, fleets.director_agent_id, agent_placements.director_agent_id, and monitor_runtime.fleet_id all use ON DELETE RESTRICT (agents are only soft-deregistered today, so RESTRICT is the safest default). agent_placements.agent_id → agents.agent_id and monitor_config.agent_id → agents.agent_id both use ON DELETE CASCADE so a hard-deleted agent (if any future path adds one) cannot leave a dangling placement or config row. Fleet deletion uses a soft-delete (deleted_at) — it never physically removes rows, so the RESTRICTs are not triggered by the normal delete path; the monitor_config and monitor_runtime rows are instead removed explicitly inside the fleet delete transaction.

Task Visibility Rules¶

Read access is fleet-scoped; per-agent identity is enforced only on state transitions:

The only cross-fleet boundary is fleet membership; within a fleet, reads are not partitioned per agent. Recipient/sender identity is enforced only when transitioning a task's state (ack / cancel).

Broadcast Grouping¶

A broadcast produces N+1 rows — one delivery task per active recipient plus one broadcast_summary task — and the admin WebUI timeline presents all of them as a single entry. The tasks.origin_task_id column is the grouping link:

Because ids are DB-assigned, the summary row is inserted first with origin_task_id temporarily NULL; the broker reads back its DB-assigned task_id, updates that row's origin_task_id to itself (self-reference), then inserts each delivery row with origin_task_id = summary_task_id. Unicast deliveries are inserted with origin_task_id left NULL.

The grouping predicate on the wire is origin_task_id IS NOT NULL, which cleanly partitions the timeline into "standalone unicast entry" vs "part of a broadcast group".

ACK timestamp inference¶

The timeline reads each broadcast's per-recipient ACK time from the status_timestamp of the matching completed delivery row, which is valid because a delivery task makes exactly one state transition over its lifetime (input_required → completed on ACK). If a future change adds a second transition that rewrites status_timestamp, a dedicated acknowledged_at column must be added.

Deregistered Agents¶

Deregistration is a soft-delete only. There is no background cleanup loop and no physical removal of agent or task rows. Deregistered agents continue to exist as rows with status='deregistered' indefinitely; their inbox tasks remain readable by the WebUI (the only consumer that surfaces deregistered agents). Active query paths filter status='active' so dead rows are invisible to normal traffic.