02 Execution

02 Execution

Source: docs/design/02-execution.md

Principles

• Reply turns talk and decide; tasks execute
• Turns never block on tasks
• Every finished task must be settled so a turn can consume the result (“must settle” invariant)
• Soft isolation + leases, not git worktrees for task isolation

Reply turn vs task (D75)

	Reply turn	Task
loop_type	turn	task
Latency	Seconds	Minutes–hours
Tools	Read-only core + routing + async managed actions	Full surface
Engine	Always built-in pi	Built-in or external ACP agent
Parallelism	Serial per (Bot, conversation)	Parallel within caps

Deep dive: 30-Supervisor-and-Tasks.

Routing tools

Turns use enumerated tools: start_task, inject_task, cancel_task, list_tasks, plus capability search/call (40-Capability-Mounting). Task cards leave a visible routing trail.

Mailbox and scheduling

Serialisation is on turns, not tasks. Incoming events queue in a mailbox until the next turn. Write mutual exclusion uses leases on workdir/workspace keys (one writer task per workdir). Scheduler enforces per-conversation and global task caps.

Task settlement

States include running → completed / failed / interrupted / cancelled, etc. Settlement writes a durable notify entry (main.db) then task terminal state (runs.db); wakeup is host-deterministic. Reaper repairs incomplete settlement after crashes.

Wake examples: task result, failure, interrupt; user cancel from task card wakes; Bot’s own cancel_task / delete-driven cancel / empty result may not.

Runs

Each loop produces a run with steps (assistant text, tool calls, progress). Continuation between tasks uses explicit continues_task_id replay (automatic loop continuation removed for turns).

Crash and recovery

Default ephemeral: mark interrupted, prompt on restart, no auto-resume (D49). Durable journal (24-Durable-Execution) not implemented. External side-effect ledger tool_effects (D78) is implemented — retry after interrupt may require “I verified” when prior effects completed/unknown.

How Bots send messages

Final assistant reply auto-posts; mid-turn send_message; skip_reply for silence; structured @ only. Interim narrations auto-post with caps (D54). Status line at stream end (D55).

Inline setup

Missing config → structured setup failure → inline card → retry (18-Inline-Setup, 38-Conversational-Settings).

Loop types

Includes turn, task, subagent, reflection/wiki maintenance, widget_authoring, etc. Context injection differs by type (conversation info, memories, schedules, tasks, capabilities, private timeline).

Project communication response (D92)

No @: previous speaker continue-check → lead gateway → guaranteed outcome. Collaboration episodes + circuit breakers replace token-budgeted chains. See 41-Project-Team.

Nested subagents (D66)

Inside a task: sync / parallel fan-out / collect results — not group members, no re-delegate. See 23-MCP-and-SubAgent.

Cross-Bot delegation (D71)

delegate_to_bot A→B with intents; not SubAgent. See 27-Butler-and-Delegation.

Proactive messages & watches

Schedules, offer_schedule nudges (D80), web watches (D79) wake turns with guardrails (daily caps, quiet hours). Watches use hidden browser pages and content-hash edge triggers.

Recall and edit

Supported for user/Bot messages within product rules (D6).