Explain this: the local model reads delivery failures, verdicts, logs and settings

jcoffey-dev commented

2026-09-26 07:54:36 +00:00

Owner

Adds inbuxa:Explanation/set: a superuser asks the node's local model for a short plain-words reading of a failed recipient, a Classify verdict, a log line or trace event, or one setting. The server builds every prompt from stored data and the registry schema; secrets (nested ones too), raw protocol events and other events' contents never reach the model.

Shares the AI gate with spam classification; mail always keeps its slot. Own hourly count per account and own switch in inbuxa:AiLimits.
Permission sysAiExplain (superuser only, not tenant administrators) and session flag aiExplain.
Upgrade: stored administrator-only roles get the permission once at start-up; the shared User role doesn't, and an operator's later removal sticks.

Spec: specs/ai-explain.md in the drafts, with where the build differs.

Tests. Unit tests in inbuxa-features and jmap; ai_explain_tests and ai_tests pass (--ignored), and so did the JMAP suite before the last two fixes. The upgrade grant was also checked against a copy of 2026.9.23 demo data: only System Administrator gained the permission.

Fixed during the browser check: a singleton setting never saved (e.g. x:SpamSettings on most installs) answered "No such x:SpamSettings."; it's now explained from its defaults, as /get shows it, with a test. The prompts sent for a verdict, a live http.response-body event and a stored trace event were checked: no message text, response body or contents.

Console: inbuxa/inbuxa-admin feature/ai-explain.

Adds `inbuxa:Explanation/set`: a superuser asks the node's local model for a short plain-words reading of a failed recipient, a Classify verdict, a log line or trace event, or one setting. The server builds every prompt from stored data and the registry schema; secrets (nested ones too), raw protocol events and other events' contents never reach the model. - Shares the AI gate with spam classification; mail always keeps its slot. Own hourly count per account and own switch in `inbuxa:AiLimits`. - Permission `sysAiExplain` (superuser only, not tenant administrators) and session flag `aiExplain`. - Upgrade: stored administrator-only roles get the permission once at start-up; the shared User role doesn't, and an operator's later removal sticks. Spec: `specs/ai-explain.md` in the drafts, with where the build differs. **Tests.** Unit tests in `inbuxa-features` and `jmap`; `ai_explain_tests` and `ai_tests` pass (`--ignored`), and so did the JMAP suite before the last two fixes. The upgrade grant was also checked against a copy of 2026.9.23 demo data: only System Administrator gained the permission. **Fixed during the browser check:** a singleton setting never saved (e.g. x:SpamSettings on most installs) answered "No such x:SpamSettings."; it's now explained from its defaults, as /get shows it, with a test. The prompts sent for a verdict, a live `http.response-body` event and a stored trace event were checked: no message text, response body or `contents`. Console: inbuxa/inbuxa-admin `feature/ai-explain`.

jcoffey-dev added 1 commit 2026-09-26 07:54:37 +00:00

Explain this: the local model reads delivery failures, verdicts, logs and settings

ci / fork-checks (pull_request) Successful in 48s

Details

ci / build (pull_request) Successful in 9m4s

Details

d9a6db025b

A new method, inbuxa:Explanation/set, asks the node's local model for a
short plain-words reading of one thing an administrator is looking at:
a failed recipient in the queue, a Classify verdict, a log line or trace
event, or one setting with its saved value. The server builds the prompt
itself from stored data and the registry schema, never from text the
console sends, and grounds SMTP replies in RFC 3463 and RFC 5321.

What the model is never shown: secrets (including ones nested inside a
setting, like an AI model's HTTP auth), raw protocol events, and the
contents of any other event. A tag name that doesn't have a tag's shape is
refused before a model is asked.

Calls share the AI gate with spam classification, but mail always keeps
its slot, and Explain has its own hourly count per account and its own
on/off switch in inbuxa:AiLimits. The permission is sysAiExplain,
superuser only; tenant administrators can't use it. The session carries
an aiExplain flag so a console knows when to offer the button.

An install whose roles were stored before the permission existed gets it
added once, at start-up, to the roles that are administrators' alone,
not the User role their defaults share with every account. An operator
who removes it later isn't overruled.

Tests: unit tests in inbuxa-features and jmap, and ai_explain_tests
(run with --ignored) covering the acceptance tests and the upgrade.

jcoffey-dev added 1 commit 2026-09-26 08:09:49 +00:00

Explain a setting that was never saved, from its defaults

ci / fork-checks (pull_request) Successful in 20s

Details

ci / build (pull_request) Successful in 7m26s

Details

866d7d3ed5

A singleton such as x:SpamSettings has no stored object until someone
saves it; /get shows its defaults instead. Explain looked only for the
stored object, so every setting still at its defaults answered "No
such x:SpamSettings." It now falls back to the defaults the same way.

jcoffey-dev merged commit b41dfa7a1d into main

2026-09-26 08:30:45 +00:00

jcoffey-dev deleted branch feat/ai-explain

2026-09-26 08:30:45 +00:00

jcoffey-dev referenced this pull request

2026-09-26 21:21:17 +00:00

Release 2026.9.26 #58

Explain this: the local model reads delivery failures, verdicts, logs and settings #56