> ## Documentation Index
> Fetch the complete documentation index at: https://familyco.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Runtime and queue

> How agent runs, tool calls, and tasks flow through the in-process queue.

FamilyCo's runtime is in-process by default. The server schedules work across three queue lanes and exposes engine endpoints for inspection and recovery.

## Lanes

| Lane           | Purpose                                                                                 |
| -------------- | --------------------------------------------------------------------------------------- |
| `agent.run`    | Executes agent workflows and updates run lifecycle state.                               |
| `tool.execute` | Executes tool calls through runtime policy and audit pipeline.                          |
| `task.execute` | Executes ready tasks (single task or agent batch) with heartbeat and audit integration. |

## Concurrency

By default the server auto-scales by CPU cores:

* Agent concurrency: `max(2, floor(cpu/2))`
* Tool concurrency: `max(4, cpu)`

Override with environment variables:

```bash theme={null}
FAMILYCO_QUEUE_AGENT_CONCURRENCY=4
FAMILYCO_QUEUE_TOOL_CONCURRENCY=8
```

The queue driver is selected via `FAMILYCO_QUEUE_DRIVER`. The default `memory` driver is in-process and loses pending jobs on restart.

## Guards before enqueue

Two guards run before any agent or tool execution is enqueued:

1. **Daily quota guard** — consumes daily usage; rejects if over the cap.
2. **Approval guard** — may return `approvalRequired` instead of enqueuing, in which case an `ApprovalRequest` is created and the run pauses.

## Heartbeat runtime

The heartbeat scheduler periodically polls agents and enqueues heartbeat runs. It:

* skips paused or terminated agents,
* enforces in-flight and cooldown protections,
* can be force-triggered via the engine endpoint for recovery and debugging.

## Cron runtime

The cron scheduler polls due jobs, executes them, and records per-run success/failure into `CronRunRecord`. Each job persists `lastRunAt` and `nextRunAt` markers.

See [Automation](/modules/automation) for the UI and contract.

## Health and read-only mode

* The health endpoint reports queue stats, migration status, and read-only mode.
* If startup migration safety fails, the server enters **read-only mode**: mutation routes return `503 READ_ONLY_MODE` until the database is recoverable.

## Engine endpoints

The engine module exposes routes for:

* enqueueing agent runs,
* enqueueing tool executions,
* inspecting queued jobs,
* listing agent run history with filters (state, trigger type, root agent),
* fetching agent run detail,
* force-triggering heartbeat polling.

All non-token routes require API key or JWT authentication. Route access enforces a minimum agent level (`L0`, `L1`, `L2`).