Skip to main content
Every turn runs a deterministic-first loop:
  1. Apply inbound set: button taps (when the user text is a valid payload from the latest agent message). The engine writes that memory field and runs its memory validation tool before any LLM call. Stale or non-writable taps utter utter_set_memory_button_skipped and skip the rest of this loop. See Set-memory payloads.
  2. Execute deterministic steps first: ordered-block steps that need no model call (execute_tool:, noop:, set_memory:, utter:, and collect: steps whose value is already known, including a field just written by a set: tap). The framework also narrows what the LLM may do next, omitting hidden / disabled / engine-managed skills and hiding gated tools, though the routing choice itself is made by the LLM in step 4.
  3. Build a scoped prompt from live state: the active skill’s instructions filtered by if: markers, the tools whose requires: conditions currently hold, and the memory values readable in scope. A set: payload is omitted. A successful tap shows the button label instead, and that turn adds a system instruction that the field is already stored.
  4. Call the LLM.
  5. If the LLM returns a tool call: dispatch it, apply any memory writes the tool makes as it runs, check for newly-available deterministic steps, and loop back to step 2.
  6. Otherwise: send any text. Then either wait for the user or loop from step 2. See When the engine waits.
One user message can go around this loop several times.

Start a skill from a message

A typed user message whose whole text is / plus one skill folder name, such as /refund, starts that skill before step 2, with no routing turn. The folder name has to be a skill the router may already start. Hidden, disabled, and engine-managed skills stay unstarted, and so does an ordered-block id. The match is case-sensitive: /Refund is ordinary text. Voice turns never use the command. The command is left out of the skill prompt. The stored user message is unchanged. When another skill is already running, the command interrupts it the same way activate does. While the agent is declining an unsupported request, activate is refused, and so is this command: the message stays ordinary text. Sending it for a routable skill that is already running continues that skill, including while one of its ordered blocks is open. If that block is still waiting on a collect field, this turn’s prompt names the field instead of the command. A hidden, disabled, or engine-managed skill stays ordinary text even when that skill is already running. A skill with an unmet precondition starts its resolver instead. /refund please is not a command, and neither is /skill refund. Both stay as typed and are routed normally. A command that names a skill the router cannot start is left as typed and routed normally. /session_start, /session_end, and /silence_timeout are engine messages, not skill commands. Validation rejects a skill folder with one of those names.

When the engine waits

The engine waits for the next user message when:
  • The stack is empty after a delivered response (the skill or block finished).
  • An engaged collect: needs the user’s answer.
  • An ordered-block execute_tool: listen step runs.
  • The LLM calls listen() alone (not mixed with text or other tools).
After a canned ordered-block utter_*, leftover hybrid prose or further deterministic steps can still run in the same turn. On that follow-up LLM call, a canned-response reminder tells the model not to repeat or paraphrase the canned reply. See listen.

When the engine ends the conversation

Hangup is destructive and is not offered as an LLM tool. A skill must explicitly execute execute_tool: hangup in an ordered block to end the conversation. Place an utter_* goodbye before that step when a farewell is needed.

State tracked per control level

These coexist. A hybrid skill, meaning prose with if: markers that also references an ordered block, tracks both a step pointer and memory state at once.

Tool execution

A tool may be invoked by the LLM (a tool call) or by the framework (an execute_tool: step). The function does not know or care which. tool_constraints are checked in both cases, and in two places:
  • when the tool schema is built, deciding whether the LLM sees the tool at all
  • again at dispatch, before the function runs
Both fail closed. A requires: condition that cannot be evaluated hides and blocks the tool rather than allowing it. When the LLM issues a local or MCP tool call, Mantle validates the arguments against the JSON schema offered to the model before confirmation or execution. Missing, extra, or mistyped arguments are returned as a retryable error so the model can correct the call in the same turn. Because the tool did not run, this does not trigger its on_failure response. An imported MCP tool without a usable object schema is treated the same way: the remote tool is not called. Ordered execute_tool steps use the same check after memory fill. Those arguments come from the step’s parameters:, not from the model, so the LLM cannot repair a schema-invalid payload. The engine stays on the step, does not run the tool or on_failure, and yields so a later deterministic pass can retry if missing memory has been filled. If the parameters themselves stay invalid, the tool cannot run.

Knowledge search changes the loop

When search_knowledge runs during a turn, the tool list for the remainder of that turn collapses to activate, search_knowledge, and cannot_help, plus resolve_tool_confirmation when a confirmation is pending so the pending gate is never stranded. The active skill’s lifecycle, collect, builder, and listen tools are dropped so a grounded answer neither re-drives the skill nor ends silently before presenting the retrieved information. They return on the next turn. Relatedly, cannot_help is withheld until a search has run whenever a knowledge base is configured, so the model cannot decline before retrieval could have answered. If the model still mixes listen with a user-facing answer after a search, the engine ignores listen and treats the text as the grounded reply: the post-search trim ends so the skill can be parked and resume offered.

Where conditions are evaluated

See Conditions for expression grammar, and skill.md complete_when for the skill-level mapping.

Tracker events

Mantle appends these events to the conversation tracker. They are what Inspector and Copilot read; you do not author them in YAML. These are the only lifecycle, tool, and memory events Mantle writes. Skill lifecycle is skill_*, block lifecycle is ordered_block_*, tool runs are tool_executed, and memory writes are memory_set / memory_cleared. block_id is the authored id (submit, start), not the compiled target id {skill_id}__{block_id}. Inspector shows each ordered_block_* as a Block row. is_hint on tool_executed classifies the result for later prompts. false is a clean success. true is guidance, a partial apply, an error that a result hook cleared, or a success that a result hook changed. It is unset for a run that did not come from an LLM tool call, such as a confirmed tool run. On later turns, a clean success from the built-in tools set_memory, activate, enter, complete, and cancel is left out of the prompt once the agent has replied to that turn. The event stays on the tracker. Errors, guidance, and tools you define are always kept. Session-start channel metadata is recorded as memory_set (key system.session_started_metadata, after the session starts). A later session start without channel metadata does not reuse the previous session’s value. A conversation that was started under CALM is not continued. Start it on a new tracker. The turn is skipped and nothing is sent back. Operators see an error log event named mantle.turn.session_refused.

See also