Background jobs

This page will cover running turns in the background. Ziro has two queue levels. The interactive inflight buffer is always available: it captures input typed mid-turn and drains one line per turn at a clean boundary, so what you type is never lost and never jumps an open approval prompt. Separately, an opt-in worker queue runs whole turns off-session on namespaced job threads, driving the same graph as an interactive turn. Submitting and polling go through the headless CLI:

python -m app.cli.chat_once --user <USER_ID> --agent <AGENT_ID> --message "<MSG>" --submit
python -m app.cli.chat_once --user <USER_ID> --status <JOB_ID>
python -m app.cli.chat_once --user <USER_ID> --status all

The page will cover the per-agent queue section of settings.yaml (was queue_policy.yaml), which gates only the cross-thread worker queue, not the inflight buffer, plus recovery of orphaned jobs after a crash. The worker queue is off by default; researcher ships with it enabled as the reference opt-in. The job pool itself (workers count, max_depth and inflight_max_depth backpressure, job_recursion_limit, and result_ttl_days) is a host resource, so it now lives in resources.jobs of a layer-root settings.yaml (~/.ziro/settings.yaml or <project>/.ziro/settings.yaml), not on any one agent. Where a knob is unset there it falls back to the agent’s queue section, so existing configs keep working.

# <layer>/settings.yaml
resources:
  jobs:
    workers: 2
    max_depth: 32
    inflight_max_depth: 16

This page is in progress. The shipped researcher queue section is fully commented and is the best reference until it lands. Legacy split queue_policy.yaml files still resolve.

See Headless usage for the full one-shot CLI, chat_once reference for the JSON contract, and Configuration for how the queue section and resources.jobs resolve.

Getting started

Concepts

Interfaces

Guides

Background jobs