1. What an executor is (in thirty seconds)

An executor is a small specialised utility that does one thing only: reads mail, finds a file, takes a snapshot of the clock, sends a message. It lives on its own, in its own folder, and talks to Metnos through a precise contract.

Think of a toolbox. Every tool is simple and recognisable: the screwdriver tightens screws, the hammer drives nails. Nobody would ask the screwdriver to drive a nail. In Metnos it is the same: every executor is a tool with a clear job. When the user asks for something, the planner picks the right tool and uses it.

Three things define it:

• it does one thing only — its whole life revolves around a narrow task;
• it has a contract — it declares what it accepts as input and what it returns;
• it lives in a fence — it can touch only certain folders, certain network addresses, certain services.

2. Anatomy: five things in the folder

An executor is a folder on disk. Inside there are at most five files, each with its own job. Nothing more.

The three required files are the heart. The code does the work. The manifest describes the code so that the planner can decide whether to use it. The signature proves the manifest has not been tampered with since the author wrote it.

3. The manifest: the calling card

The manifest is a TOML file. You open it with a text editor and you can make sense of it even without being a programmer. It declares everything the planner needs to know: the executor's name, what it does, which arguments it takes, what the result looks like, a few examples for orientation.

What deserves a second look

Three things stand out, because the whole system rests on them.

The code fingerprint (digest): a cryptographic fingerprint computed over the bytes of the .py file. If anyone modifies even a single comma in the code without recomputing the fingerprint, the loader rejects the executor. The manifest and the code are bound like a certificate and the document it certifies.

The result shape (output.schema_inline): declares field by field what the executor returns. It serves whoever composes chains of executors (the planner does not fly blind: it reads the schema and knows what to expect at the next step) and whoever auto-generates code.

The permissions (capabilities): the manifest does not decide what the executor may do. The manifest declares what it would need in order to function; the system then decides whether to grant those permissions and under which constraints. See sandbox.

4. The fence: what it can and cannot do

An executor does not roam free on the system. It lives inside a fence, built from the permissions its manifest declares. The fence sets: what it can read on disk, what it can write, which network hosts it can speak to, which system files are off limits even if the executor were to ask for them.

The golden rule is simple: the fence is always tighter than the manifest. If a manifest asks to read /home, the fence may still cut the request down to /home/user/notes. If it asks to talk to any domain, the fence may restrict it to imap.example.com. The difference matters: the manifest is what the author hoped for, the fence is what the system decided after looking at who is calling, in which context, with what trust level.

5. An executor's life

An executor is not born active and does not stay active forever. It moves through a series of states the system manages on its own. Knowing these states helps you read the catalog: if a tool is not being picked anymore, it might be because it slipped into quarantine, not because it is broken.

6. Four origins: handwritten, generated, imported, builtin

All executors share the same external anatomy, but they are born in four different ways. The distinction is not cosmetic: it changes who writes them, where on disk they live, and where the ideas behind them come from.

Why the imported origin exists

A third-party library typically has its own textual documentation explaining how to use it: «to list the calendar, call gws calendar list; to create an event, use --summary and --start». The agentskills.io standard encodes this documentation in a precise format (a Markdown file with a structured front matter). Metnos's importer reads that format, translates it into the system's closed vocabulary, and generates the executor folder as if it had been handwritten.

The upside: any service already documented as a skill (Google calendar, mail, file storage,...) can be brought into Metnos without rewriting from scratch. The downside: you have to trust whoever wrote the skill (and its helper scripts). For this reason the importer does not install anything in /opt/metnos/executors/: imported executors live in a separate folder, under watch, and still pass through the vetting before every call.

One operational detail: imported executors that need credentials (an API key for an external service, the session file of an account) do not make them up. The first time you call one, it opens a dialog window, asks you for the missing data, encrypts it in a local vault, and proceeds. Subsequent calls find the credential already in place. No passwords in code, no configuration files to edit by hand.

7. Three concrete examples

Three executors actually in use, told from the outside. No source code: just what you ask for and what you get.

7.1 get_now — «what time is it?»

The simplest tool in the catalog. No required arguments. Returns a dictionary with the current date and time.

call: get_now(timezone="Europe/Rome")
response: { ok: true,
 content: "2026-05-06T16:45:23+02:00",
 metadata: { timezone: "Europe/Rome", iso8601: "...", epoch:... } }

No network, no file read, no write. Permissions: time:read. It is one of those tools that look superfluous until you see why they matter: the planner must never invent the date from training memory. When it needs to compute «yesterday's mail», it calls get_now first, then subtracts a day. That way «yesterday» is always today's yesterday, not the yesterday from when the model was trained.

7.2 find_files — «find the photos»

Searches files by name or pattern (the classic «extensions»). Returns the list together with basic metadata: path, name, size, last modified, type.

call: find_files(base_path="/home/user/images", pattern="*.jpg")
response: { ok: true,
 entries: [
 {path: "/home/.../foto1.jpg", size: 2458123,...},
 {path: "/home/.../foto2.jpg", size: 1923456,...},...
 ],
 metadata: { count: 247,... } }

The planner uses it when it has to hand the list off to another tool: for example to keep only the most recent photos, compute total size, compress the older ones. Note that filtering does not live in find_files: the tool returns the files and that is it. If you want a subset, you ask via the pattern, or you pipe the result into a tool that filters. One thing at a time.

7.3 filter_lists — «find overlapping events»

A tool that works on two lists rather than one. Useful when a user question intersects two sets: "which HLT appointments overlap with MNM ones in the next three months?", or "which files are present in both folders?".

call: filter_lists(op="overlap",
 from_step=2, # list A (HLT events)
 with_step=3) # list B (MNM events)
reply: { ok: true,
 op: "overlap",
 entries: [...entries of A that overlap with at least one of B... ],
 metadata: { count_a: 4, count_b: 5, count_out: 0 } }

Available operations: intersect (entries common to both lists, match on a key), union (entries from either, deduped), difference (entries of A not in B), symdiff (symmetric difference), overlap (temporal AND: entries of A whose time window overlaps with at least one in B; auto-detect start/end).

The taxonomy of list operators is closed and readable: filter_entries reduces a single list (predicates: where_starts_with, where_contains, where_glob, where_regex), filter_lists combines two lists with set ops, compute_entries computes a scalar (sum, average, min, max, count). The three primitives together cover almost every list manipulation without inventing new verbs.

7.4 send_messages — «send a message to Lucia»

Sends one or more messages over Telegram (today) or email (coming soon). Main argument: a list of messages, each with recipient and body.

call: send_messages(messages=[
 {to_user: "lucia", body: "Out for a bit, back at seven."}
 ])
response: { ok: true, ok_count: 1, fail_count: 0,
 results: [{to_user: "lucia", channel: "telegram", message_id: "abc123"}] }

A «transformative» tool: it changes the world, it really sends a message. For this reason, executors that change the world get treated with more care: their manifest declares broader permissions (net:write), they go through a check before execution, and their effect stays tracked so it can be undone. See vaglio for pre-execution checks and approval_ux for how the user is asked to confirm.

8. Going deeper

This document is an introduction. If you want to understand the mechanisms beneath — how a manifest gets signed, how the fence is applied, how the Synt generates code, how the planner picks a tool — the documents below should be read one at a time.

For design decisions (why this choice and not another) there is a registry in /opt/metnos/decisions/. Examples: why generated executors live in a different folder from handwritten ones; how to ask for a password without ending up with it in plain text in the logs; how to index thirty thousand photos without blocking everything else.

Metnos — executor, didactic introduction