π«π· Version franΓ§aise
See also: ADR-005 Β· ADR-008 Β· E-mail tools Β· Back to the index
ADR-012 β The e-mail tool family, a second motivated exception to the scope freeze
Status: Accepted Β· Date: 2026-09-26
Β· Scope: src/tools/Orkeon.Tools.Email, Orkeon.Hosting (the /credentials root and the token store), orkeon email (Orkeon.Scripting.Cli), the Orkeon.Tools umbrella
Context
The owner asked for native tools to read and send mail β SMTP, POP3, IMAP β and for a Gmail
and Hotmail client that reads, writes, creates folders and moves messages into them,
directly in Orkeon. What existed was email_parser, which read .eml files with regular
expressions and returned a placeholder for .msg; the tool inventory recorded the gap ("no
tool to send emails").
The scope is frozen: CONTRIBUTING says "no new built-in tool β write yours in a .ork.ts
script or a plugin". Neither route fits. A script runs on Jint and cannot open a socket; a
plugin would not be "directly in Orkeon", and would still need the token storage, the rights
and the screening this decision builds.
The provider constraints, checked on 2026-09-26:
- Hotmail / Outlook.com: OAuth2 is mandatory and personal accounts get no app passwords.
Since 2026-09-24, a regression on Microsoft's side makes IMAP OAuth fail for consumer
accounts ("User is authenticated but not connected"). Microsoft Graph (
Mail.ReadWrite,Mail.Send) works for them, accepts MIME in base64 (4 MB per request) and keeps ids stable across moves withPrefer: IdType="ImmutableId". - Gmail: an app password (behind 2-Step Verification) still works over IMAP and SMTP, and
so does OAuth2 XOAUTH2 with
https://mail.google.com/. Google's device flow refuses Gmail scopes, and an application left in "Testing" receives refresh tokens valid for 7 days.
Decision
- A new family,
Orkeon.Tools.Email, the eighth of theOrkeon.Toolsumbrella β the second motivated exception to the scope freeze, after the OpenRouter and Mammouth aggregators (2026-09-18). Thirteen tools: twelve new, andemail_parserrebuilt (point 7). Dependencies follow ADR-005:Domain,Tools.Abstractions,Constants.Configuration, andOrkeon.Ragfor its prompt-injection detector βOrkeon.Ragitself reachesApplication, the route ADR-006's amendment documents; no direct reference toApplicationorInfrastructure. Everything isinternalexcept the DI extensions, the token-store port and its file implementation, the error type, the helper the host reads the credentials location with, and the administration surface theorkeon emailverbs use. - MailKit 4.18.0 and MimeKit 4.18.1 (MIT) carry IMAP, POP3, SMTP and the message model.
Both are referenced directly β central package management pins no transitive version β and
the umbrella declares them again. There is one message model for every backend: Graph
messages are read (
$value) and written as MIME too, so one mapping produces what the tools return. - Three backends behind one internal port, chosen by the account's preset. IMAP + SMTP
(Gmail and any standard server), POP3 + SMTP (the inbox only; the backend declares its
capabilities and every request beyond them is refused explicitly, never dropped), and
Microsoft Graph over plain
HttpClientβ no Graph SDK β for Outlook.com, Hotmail and Microsoft 365, the default of theOutlookpreset. Transport is TLS (SslOnConnectorStartTls);Noneis accepted towards a loopback host only, and no option accepts an invalid certificate. - OAuth2 is written by hand, over
HttpClient: the RFC 8628 device-code flow for Microsoft (tenantconsumersby default); the authorization code with PKCE for Google, the redirect received by aTcpListenerbound to127.0.0.1β notHttpListener, which needs a URL reservation on Windows β with a paste-the-redirect fallback for WSL, containers and remote shells; refresh with token rotation. The tools never sign in interactively: a tool without a usable token answers "runorkeon email login <account>". - Tokens live in the internal
/credentialsroot, through the privileged VFS view.RunnerVirtualRoots.Credentialsis a new reserved root, refused to a user mount by every command. The runner host mounts it as an internal mount only when an OAuth account is declared, andFileSystemEmailTokenStorewrites throughPrivilegedFileSystemAccess(ADR-008), which no agent-facing tool resolves. Physically:<per-user settings directory>/credentials/email/, or theemailsubdirectory ofCredentialsDirectoryfor a service. Creating those directories before any mount exists (owner-only on Unix) is runner bootstrap β theHosting/Runner*EXCEPTION-BOOTSTRAPscope already ratified β so there is no new VFS exception category.IEmailTokenStorestays replaceable by a host of its own (a vault, for instance). - The guard rails are the boundary, not the model's judgment. The model names an account;
the operator's configuration holds the servers, the credentials β as environment-variable
names β and the mandatory
Rights(Read,Organize,Draft,Send,Delete,Purge). Sending fails closed onSend:AllowedRecipients(empty: nobody), the SMTP envelope is passed explicitly so noResent-*header can widen it,Fromis forced to the account, andMaxRecipients/MaxPerHourcap the volume;email_draftis the human-review path. Received content is marked untrusted and screened byPromptInjectionDocumentValidatoron the rendered text β flag by default,Screening:WithholdRejectedto withhold. Every tool declares itsToolAccessfor the permission gate, andorkeon forgedenies the twelve mailbox tools to the crews it forges (amended by FORGE-10: the tools are offered, and a try runs them on a fictitious trial mailbox). Results fit the agent loop's 4000-character cap on a tool result, without a new override β mail content is not a trusted deliverable: a search page is cut after a whole message and a body slice where its rendering ends, and the cursor or the offset resumes exactly there. email_parserjoins the family, rebuilt on MimeKit β same name, parameterspath,offsetandmax_chars, the output ofemail_read,.msgdropped (it was never parsed). This is a deliberate breaking change, with its migration in the CHANGELOG.
Rejected alternatives
- A script or a plugin. A script cannot open a socket; a plugin is outside Orkeon, which is not what was asked, and would have needed the same token storage, rights and screening.
- MSAL and the Google SDK. Two large dependency graphs for three HTTP exchanges each, and a token cache that would live outside the VFS.
- IMAP for Outlook.com personal accounts. Broken by Microsoft's regression of 2026-09-24.
Graph works, keeps ids stable across moves and files sent mail itself; IMAP stays available
as an option of the
Outlookpreset. - The Gmail REST API. A second Gmail backend and another consent review, for what IMAP and
SMTP already cover with an app password or XOAUTH2 β
X-GM-RAWbrings Gmail's own search syntax over IMAP. - A new VFS exception category for a plain token file. The tokens go through the VFS like any other file; only the directory's creation is bootstrap, and that is already ratified.
Consequences
- Built-in tool classes go from 79 to 91 and
Orkeon.Toolscarries eight families. MailKit, MimeKit and their BouncyCastle.Cryptography dependency are redistributed inside theorkeonandorkeon-repltools and the installers (THIRD-PARTY-NOTICES). - Breaking:
email_parserleavesOrkeon.Tools.FileSystemβAddOrkeonFileSystemTools()no longer registers it,AddOrkeonEmailTools(configuration)does β and its parameters and output change. - Honest limits: the token files are plain JSON, shielded from the VFS tools but not from a
shell or code tool running as the same operating-system user; every account is visible to
every crew and script that resolves the same settings file;
orkeon-replkeeps no token store, so OAuth accounts work under theorkeonrunners only. POP3 and Graph limits are in the guide. - Live validation against real Gmail and Hotmail accounts is the owner's campaign (MAIL-07). Until it is archived, the provider support is documented as campaign-pending. Dated note, 2026-10-06: Gmail was campaigned on 2026-10-04 (app password) and 2026-10-05 (OAuth2), and is documented as such; Hotmail and Outlook.com stay campaign-pending. The results are in the guide. Dated note, 2026-10-12: Hotmail through Microsoft Graph was campaigned on 2026-10-12, and MAIL-07 is closed; Outlook over IMAP and SMTP was not run and stays documented as such.
- Out of this version: deleting folders, copying a message or giving it several Gmail labels, Graph uploads above about 3 MB (an upload session), interactive human approval of a send.
Amendment (2026-10-29)
The versions named in decision 2 (MailKit 4.18.0, MimeKit 4.18.1) were those of 2026-09-26; Directory.Packages.props now pins MailKit 4.18.2 and MimeKit 4.18.2.