The runtime coordinates a Metnos turn. It interprets the request, selects admitted capabilities, builds or reuses a plan, checks its shape and permissions, and delegates each step to the appropriate executor. A language model may propose the plan and compose an explanation; this does not give it direct access to files, mail, browsers, devices, or credentials.

1. Responsibilities and boundaries

At the start of a turn, the runtime binds the request to four coordinates: the owning user, technical actor, channel, and conversation. Preferences, language, credentials, devices, suspended dialogs, and history are resolved within this context. One user's turn does not authorize access to another user's resources.

The runtime is not a general-purpose shell. Its operational surface is the set of capabilities in the live catalog and admitted by policy. To inspect what an instance can currently do, ask the Tutor or open Settings › System › Services in the web chat.

2. A turn from request to answer

Ask Metnos with a request like this example: “Search the web for the latest European guidance on digital product passports, read the three most authoritative sources, and create a summary document in the Reports folder.”

1. The channel identifies the user, conversation, language, attachments, and any named target device.
2. The intent extractor obtains an ordered set of intents: find URLs, read the sources, and create a document.
3. Routing builds a relevant pool from the catalog. A proposer formulates a framework using available executors only.
4. The validator and guards check names, arguments, dependencies, order, and policy. If saving requires a missing choice, Metnos presents a localized form instead of inventing it.
5. Executors search, read, and write. Each step's structured result feeds the next step.
6. The terminal composes an answer grounded in actual outcomes, records the turn trace, and exposes the resulting document as an attachment or link.

The same sentence can be sent through Telegram. If a setting is available only in the web chat, Metnos must name that channel and provide the navigation path, rather than returning only a technical route or page name.

3. Execution paths

Not every request needs a new model proposal. The runtime tries paths with different responsibilities in a fixed order:

1. Narrow deterministic routes. These cover closed cases such as undoing the last turn, selected service answers, uploads without text, and recurrences recognized by the scheduler grammar.
2. L0, fast path. Reuses the framework of a cacheable request that previously completed with an effective result.
3. L1, autopath. Reuses a generalized framework for a semantic cluster. Positive feedback can confirm a champion; repeated expensive runs may create a shadow champion, which is explicitly distinct from user approval.
4. Full engine. Extracts or completes intent, reduces the catalog, asks the proposer for a framework, validates and runs it, and—when safe— attempts one recovery path.

Attached images and resumed dialogs carry turn-specific state and therefore do not blindly reuse a generic cached plan. A remote destination is resolved before routing: if a named device is ambiguous or unreachable, the turn stops or offers explicit deferral.

4. Model roles and language

The names fast, middle, wise, creative, and frontier denote configurable roles, not fixed products:

• fast handles short tasks such as intent extraction, fillers, and selected summaries;
• middle performs deterministic intermediate transformations and judgments;
• wise proposes frameworks and handles more complex composition;
• creative formulates divergent proposals and editorial text with a distinct policy;
• frontier is optional and used only by paths that request it explicitly.

Language is resolved per user and propagated through the entire turn. Prompts, runtime messages, confirmation forms, and the final answer must use that language. Prompt wording must not accidentally impose another language: each prompt family has localized resources, and a missing resource for a new language must be caught at compilation time or produce an explicit fallback rather than silent mixing.

5. Catalog, routing pool, and plan reuse

The catalog combines signed-manifest executors, builtin capabilities, and operations added by admitted skills. Before planning, routing creates a smaller pool using intents, canonical objects, named providers, producer–consumer relations, and availability. When the signal is insufficient, the proposer can be given a broader catalog.

An L0 or L1 plan is not valid forever. At registration it stores two signatures: one for the executors it uses and one for the relevant candidate families. On each hit, the runtime compares them with the current catalog. A changed or removed executor, a newly relevant alternative, or a routing-epoch change turns the entry into a miss and forces a new decision.

Reuse concerns the operational framework, not a personal profile injected into the planner. Closed preferences and user context are applied at the runtime points that own them and during final generation; biographical prose does not contaminate a shared cache key.

6. Frameworks and executors

The proposer returns a Framework: a finite list of steps, optional fillers, and a terminal. Each step names an executor in the catalog and supplies arguments conforming to its schema. A framework does not contain arbitrary code to execute.

{
  "steps": [
    {"tool": "find_urls", "args": {"query": "..."}},
    {"tool": "read_urls_html", "args": {"from_step": 1}},
    {"tool": "create_files_doc", "args": {"from_step": 2, "path": "Reports/..."}},
    {"tool": "final_answer", "args": {}}
  ]
}

Before execution, the validator checks tools, types, required fields, requires_one_of alternatives, references to earlier steps, and placeholders. Structural guards realign order and may request one new proposal if an explicitly requested action is missing. The shared executor then resolves arguments and applies the same sequence to fresh and reused plans.

7. Passing data between steps

Data need not be copied into a prompt as free-form text when a structured reference is available:

• from_step: N passes the collection produced by step N to a consumer;
• ${stepN.field} passes one field;
• ${RUNTIME:key} inserts a runtime-controlled value such as the turn identifier;
• ${FILLER:name} resolves a short missing value within the declared schema.

An explicit target written by the user takes precedence over a generic reference to an earlier step. The runtime also preserves data authority: a path produced on a remote device does not become a server-local path merely because an intermediate filter ran on the server.

8. Pauses, resumptions, and turn state

A turn may pause with ask or needs_inputs when a choice, credential, location, or consent is missing. The persisted dialog includes its owner, channel, conversation, and admitted callback. After the answer, the runtime reconstructs completed steps as done state and plans only the remainder; it does not automatically repeat earlier mutations.

Observations needed by downstream steps remain in structured turn state. The scratchpad subsystem also provides controlled access to persisted or large results. An uploaded attachment enters as consumable virtual input, not as an action already performed.

9. Policy, Vaglio, and consent

Safety does not depend on the proposer's goodwill. The catalog bounds what can be named; schemas and sandboxes constrain arguments and execution; policy classifies the action; Vaglio applies its guard and judgment; and the consent gate pauses the pipeline before a mutation when required.

Approval is bound to the user, turn, action, arguments, and destination. Its text is localized and each channel uses its native control: a form in the web chat, or compatible buttons and choices in Telegram. Frequency, wording, and silence do not by themselves create a persistent permission.

10. Operational guards

• a cap limits proposed steps; only validated internal normalizers may declare a longer canonical pipeline;
• independent steps may run in parallel only when executor contracts admit it and preflight preserves the same guards;
• a mutation consuming an empty collection is not presented as success;
• a cached plan with mutating argument values not grounded in the current request is rejected;
• after an effect has already committed, an error does not trigger an automatic retry that could duplicate it;
• undo, remote placement, mass input, and final output cross dedicated guards before delivery.

11. Traces and observability

TurnLog records turn and conversation identifiers, user, channel, language, intent, plan source, steps, timings, outcomes, counted effects, actual destination, and final state. Recognized credentials are redacted before persistence; attachments are exposed through signed URLs or channel transfer, not as raw filesystem paths.

The trace can establish which executors ran and which controls decided. It does not turn a model-generated explanation into evidence: verifying a fact requires the structured observation and, where applicable, the original source. The observability page describes views, metrics, and retention boundaries.

11.1 Scheduled work

The builtin scheduler runs registered maintenance jobs and feeds the observation and proposal cycles enabled by the product. User-created tasks are separate, persistent requests with an owner, schedule, command, delivery channel, and outcome history. When triggered, the body runs as a new turn for the same user; it does not inherit privileges from another channel or account.

Ask Metnos with a request like this example: “Every Monday at 8, find unread mail in my work account and send me a summary on Telegram.” If the recurrence is recognized unambiguously, Metnos records the task. Otherwise it asks for the missing detail instead of running the request body immediately.

12. Errors and recovery

Structural errors are classified as wrong tool, wrong arguments, missing input, or out of scope. When no effect has committed, recovery may propose one alternative and subjects it to the same finalization as the original plan. An operational failure such as a network outage, rate limit, or unavailable service is not hidden by arbitrarily changing executors.

If an executor returns structured options that the user can decide, the runtime turns them into a form. If recovery is unsafe, the answer states the limitation and retains any useful partial results. It must not claim that a write, send, or delete succeeded when the effect counters say otherwise.

13. What is deterministic

Metnos therefore makes the boundary between proposal and execution governable. It does not claim that fresh language planning is identical on every invocation, or that an external service always returns the same data.

Code references:

• runtime/agent_runtime.py: turn context, channels, dialogs, and the engine bridge;
• runtime/engine/dispatch.py: L0/L1 cascade, proposer, validator, guards, recovery, and terminal;
• runtime/engine/types.py and runtime/engine/executor.py: frameworks, references, and execution semantics;
• runtime/engine/cache_validity.py: cached-plan signatures;
• runtime/recurring_tasks.py and runtime/scheduler_v2/: user tasks and builtin jobs;
• runtime/turn_events.py: trace persistence and retrieval.