Agent-turn runner
The Gateway claims backgroundagent.turn work, runs the model, and acks the
result. Cron, isolated heartbeat ticks, and nudge are peer producers on this
seam. Live chat stays a direct in-process call with token streaming.
Contract
openclaw/plugin-sdk specifier still loads (ADR 2057).
- Topic:
agent.turn. Class:work. Source / consumer:core:agent-turn-runner. - Idempotency id:
agent-turn:<kind>:<jobId>:<runId>. AgentTurnKindis"cron" | "work" | "heartbeat" | "nudge".- Optional
busy?: "skip" | "delay" | "run"on the payload (defaultskip), consulted only when the main lane is busy at enqueue time (an idle lane publishes immediately). Skip returnsid:skippedand nothing is published. Delay persists the turn inbus_work_itemswithacceptedBusyDelay: truebefore returning acceptance (per-session cap 32 vialistPending; a 33rd returnsid:rejected-overflowand is not accepted), then arms a one-shot waiter that releases parked turns FIFO once the lane goes idle; after 10 minutes (AGENT_TURN_DELAY_MAX_WAIT_MS) it logs a warning and releases anyway. On Gateway start,recoverAcceptedAgentTurnsre-arms idle waiters for producer-accepted pending ids only. Recovery never executes at boot and never touches a pending row that lacks the accepted marker. Claims always pass an explicitworkId(never a FIFO scan). Run publishes and claims immediately even while the lane is busy — without preemption: the turn’s model work serializes behind the in-flight command on the session’s serial lane (the main lane itself runsagents.defaults.maxConcurrentturns in parallel; only same-session turns serialize) and starts as soon as the lane permits. - The runner stamps a
session-runsrow frompayload.kind(cronviainferSessionRunKind({ trigger: "cron" }),heartbeatandnudgesame-name, elsework) beforeexecuteruns, then updates that row throughack/nack. A mid-turn crash therefore leaves a durable in-progress record. Recovery uses the session-run classifier, neverclassifyTaskRecovery. Operators read the terminal rows (kindcron/heartbeat/nudge, status completed/failed) via thesessions.runs.listGateway RPC. jobIdandrunIdmust be non-empty after trim or enqueue throws.
Producers
Nudge payloads carry
busy: "delay", so a nudge sent while a main turn is in
flight persists, then delivers once that turn completes rather than being dropped.
Operator, plugin, and agent producers all go through the authorized coordination
seam (requestAuthorizedNudge): the caller’s grant is checked before anything is
enqueued, a denial throws AuthorizationError and emits the backbone.authz.rejected
diagnostic, and an allowed row records the requester as payload.coordination.requestedBy.
See Agent coordination.
Agent-turn mode delivers through the shared post-model finalizer. Heartbeat-only
pruning, dedupe, sent-state, and events stay mode-gated. runMainAgentTurn
resolves the merged per-agent heartbeat config (resolveHeartbeatConfig) before
execution. Isolated heartbeats resolve the final run session before any event
peek or consume; only contextKey=signal:* may transfer from the bound base
key. System-event agent turns (cron --system-event, ACP nudges) whose external
send fails still complete: the reply lands in the session chat instead of the
turn failing and rolling back.
Do not route main cron or the four cron outcomes through runHeartbeatOnce.
heartbeat.wakeGate gates the heartbeat producer only. There is no autonomous
agent.turn consumer.
What not to do
TaskRunStore from agent-turn modules. Do not enqueue agent.turn
from a plugin unless the manifest grants that produce topic. Do not add a
background consumer that claims agent.turn by FIFO scan. Do not execute
pending work inside recovery — re-arm waiters only.
Administrators
Cron, isolated heartbeat, and nudge need no new config keys. Restart the Gateway after upgrade (Linux:systemctl --user restart openclaw-gateway;
macOS: wednesdayai gateway restart --deep) so enqueueAgentTurn is wired
on CronService and the runner boots next to the task pipeline. A drain
restart waits for in-flight claimed turns and pending nudge chains
(admission + claim) within the shutdown budget; a chain that misses the
budget fails fast on the stopped runner and leaves its durable agent.turn
row for boot recovery.