Enable commitments
Commitments require PostgreSQL, an enabled agent, and the Mesh run worker (MESH_RUN_WORKER_ENABLED=true). New agents created through the dashboard or
operator API enable commitments automatically when the commitment service and
run worker are available. Existing agents keep their setting. Check the agent’s
Commitments page; if commitments are off, choose Enable commitments.
A failed automatic setup leaves them off without failing agent creation.
Turning commitments from off to on also enables Capture accepted tasks and
requester retraction. These settings can be adjusted afterward. Re-enabling
commitments applies those defaults again; review the settings after a pause.
Incoming task capture has three modes:
In capture mode, “Can you prepare a deployment checklist?” can create a task;
“What does this setting mean?” can remain an ordinary question. A possible task
or low-confidence classification also reaches the agent as an ordinary turn.
The agent can ask a question when it needs more context; classifier uncertainty
alone does not produce a clarification question.
Classification uses the configured Decision model,
or the classifier text model when no native Decision route is configured. An
unavailable classifier leaves intake pending for bounded recovery instead of
treating the request as unimportant.
The agent can also register work explicitly. A follow-up promise inferred only
from an agent’s reply becomes a proposal requiring human assent before it grants
autonomous work. Clear accepted assignments and explicit task registration use
their own authorization paths. Confirming a proposal with “yes” or “all of them”
starts eligible work in that same turn, within the turn’s allowance. Work already
owned by another run stays with that owner; Mesh reports work that can no longer
start.
What happens after a task is accepted
Mesh records the original request, its audience, the required outcomes, a deadline, and an execution allowance. Foreground turns and background attempts share one task owner. A compatible follow-up can attach to the existing task; uncertain matches can ask whether this updates existing work or creates a new task. That association question is separate from uncertain incoming-task classification, which leaves the message to the agent. The background reconciler checks for work that can proceed. New conversational input takes priority over the next background attempt. Unchanged external waits do not spend a working-model attempt. Restarts preserve the task record and its progress, subject to current authorization and execution limits. Completion depends on the requested outcome. Exact predicates can be checked against recorded query results. Semantic outcomes use independent verification of the actual reply or artifact; more complex evidence uses a separate richer verifier. The agent’s own claim that it finished is not sufficient. Changed criteria, stale evidence, or unread updates prevent an old verdict from closing the task. For example, “draft a release note” can finish with a verified draft. “Publish a release note” needs evidence of publication, within the permission originally granted. Creating a pull request does not by itself prove a request to merge or deploy is finished, and a commitment does not grant permission to merge or deploy.Waiting and operator actions
The Commitments page shows each task’s status, required outcomes, evidence, activity history, and next steps. Common states includeopen, in_progress,
waiting, and completed; closed work can be cancelled, failed, or
closed_incomplete. Older or stalled tasks can also show stalled or escalated.
A waiting task records why it cannot proceed: human input, external state,
access, execution allowance, deadline, or an uncertain external write. Human
questions identify the recipient and the answer or action needed. A reply can
unblock work without claiming the whole task is complete.
Some tasks use a human-attestation contract (operator_ack). Once the agent
finishes a turn with its final answer and allowance to spare, that task waits
for confirmation instead of repeating the work. This includes an answer that
reports a blocker. It appears as escalated while awaiting acknowledgment and
closes at its deadline if no one confirms it. A turn cut short by its execution
limits remains eligible for bounded retries.
Operators can:
- Resume bounded work when an existing allowance and deadline still permit it.
- Increase allowance or revise deadline for a nonterminal task with a criteria contract, with an attributed reason. Prior usage remains counted.
- Record a confirmed write result after checking an external operation whose outcome was uncertain. Mesh reconciles that result before another write.
- Close as incomplete or Cancel follow-up, keeping the task’s history.
- Attest completion only for a task whose evidence contract explicitly allows operator acknowledgment.
Clearing pending work
Disabling commitments pauses them and preserves open work, unsent notices, and unanswered proposals. If any are pending when you enable commitments again, the dashboard offers Resume existing work or Start fresh. Clear pending work cancels all nonterminal commitments, withdraws unsent notices, and discards unanswered proposals. Committed task records and activity history remain available, attributed to the operator who cleared them. Starting fresh performs this cleanup before enabling the feature. Clearing is also available while commitments are disabled. Requester retraction lets a person’s stop request cancel their own eligible idle follow-ups in that conversation. It does not withdraw other people’s requests or undo effects that have already happened.External assignment sources
Commitments can discover assigned work through approved, agent-owned MCP connections. Configure an assignment source on the Commitments page with its verified account and tenant, read queries, identity mappings, and a real delivery conversation. Saving or editing a source leaves it disabled. Run a complete preview before enabling its assignment policy. A partial scan is not evidence that no work exists. Discovered assignments that exceed the agent’s task capacity remain deferred and are retried when capacity is available. Source health reports this backlog separately from scan coverage. Disabling a source withdraws the authority that source granted. Independently authorized requests remain owned. Re-enabling a source does not silently revive cancelled or withdrawn tasks. Completed tasks do not become indefinite monitors.Privacy and notifications
Each request retains its own audience and permissions. Recognizing the same issue or artifact in two conversations does not grant either audience access to the other’s instructions or evidence. Shared-memory revocation also prevents reuse of dependent protected history. When you start a turn, you receive the agent’s answer even if the task is still unfinished. Delivering that answer does not mark the task complete: completion still requires its recorded evidence. Cancellation and audience permissions continue to apply. Background attempts stay quiet during routine work. They notify you of a verified result, delivered work awaiting confirmation, a concrete dependency, or work that has stopped without finishing. An uncertain external write asks for its outcome to be checked before another attempt. Retries, backoff, and other internal bookkeeping stay in the activity history. Mesh delivers verified results independently to each authorized origin. A failure to notify one recipient does not undo verified work or repeat notices to recipients already reached. Results and proof that cannot be disclosed to an origin are withheld. External writes still depend on tool authorization and recorded outcomes. Mesh cannot guarantee exactly-once arbitrary shell commands or remote operations; an unknown write result requires reconciliation before retry.Reconciler watchdog
The deployment needs a worker that runs between HTTP requests. Inspect the Commitments page for due work and heartbeat health. An independent monitor can useGET /api/commitments/health or the repository’s
scripts/check-commitments.sh with a read-only API token. The endpoint returns
503 if the enabled reconciler has no heartbeat within two minutes or dispatch is
over five minutes overdue.
See the operator API for settings, task
actions, source previews, and health responses. Maintainers can read the
completion runtime reference
and ownership reference
for execution and verification contracts.