- 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 utterutter_set_memory_button_skippedand skip the rest of this loop. See Set-memory payloads. - Execute deterministic steps first: ordered-block steps that need no
model call (
execute_tool:,noop:,set_memory:,utter:, andcollect:steps whose value is already known, including a field just written by aset:tap). The framework also narrows what the LLM may do next, omittinghidden/disabled/ engine-managed skills and hiding gated tools, though the routing choice itself is made by the LLM in step 4. - Build a scoped prompt from live state: the active skill’s instructions
filtered by
if:markers, the tools whoserequires:conditions currently hold, and the memory values readable in scope. Aset:payload is omitted. A successful tap shows the button label instead, and that turn adds a system instruction that the field is already stored. - Call the LLM.
- 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.
- Otherwise: send any text. Then either wait for the user or loop from step 2. See When the engine waits.
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: listenstep runs. - The LLM calls
listen()alone (not mixed with text or other tools).
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 executeexecute_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 (anexecute_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
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
Whensearch_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
- The Runtime Loop: the same loop, explained
- Skills & Routing: how Inspector shows these events
- Constraint Table: framework vs. LLM at each level
- Tools reference: the built-in framework tools