Свой AI-агент из почты, systemd и LLM

• Мало кода, если выкинуть клеекод и типизацию (модуль types), то останется примерно 6к строк пайтон скриптов. У аналогов примерно то же быстро становится сотнями тысяч строк.
  
• Наблюдаемоесть, вся работа агента сразу видна и никаких инфраструктур для отслеживания его работы просто не нужно.
  
• Простота конструкции, это просто набор конфигов и немного скриптов. В качестве инсталлятора ansible playbook.
  
• Минимальное потребление ресурсов, агент влезет на самую дешевую VPS.
  
• Агент может править себя.
  
• Вся эта конструкция не требует инфраструктуры вовсе, никаких сложных миллионов контейнеров, мониторинг вытекает их ее свойств, отлаживать проблемы этой штуки очень легко. Достаточно дать ssh на сервер агенту и показать папку где отлаживаемый агент развернут, наблюдаемость у системы просто отличная.

• Каждое событие — файл на диске. Можно открыть mutt’ом, grep’нуть, написать скрипт.
  
• Никакого отдельного брокера сообщений. Maildir — это и очередь, и canonical event store.
  
• Идемпотентность из коробки: файл либо в new/, либо в cur/, третьего не дано.
  
• Отказоустойчивость: упал процесс — файл остался в new/, следующий запуск подберёт.
  
• Полная история навсегда: после обработки файл переезжает в cur/<id>:2,S, не удаляется.

• ingress — единая точка входа. Сюда приходят все сообщения от всех каналов.
  
• enrich — обогащение контекстом. Здесь подключается LightRAG (граф знаний) и хронология треда.
  
• reasoning — собственно рассуждение. LLM получает промпт с контекстом и отвечает через tool calls.
  
• egress_router — маршрутизатор выхода. По depth IRT-цепочки решает: ответ пользователю или возврат в субагент.
  
• egress_email, egress_telegram, egress_matrix — терминальные стадии доставки наружу.
  
• cli_intent — политика: можно ли выполнять команду?
  
• cli_exec — песочница для исполнения shell-команд.
  
• thread_memory, global_memory — FSM-состояния для работы с памятью.
  
• archive — финальная запись об отправке.

def main(msg: EmailMessage, stage: FsmStage, *, config: Config) -> EmailMessage | None:

@startuml
left to right direction
package "Вход" {
  actor "Пользователь" as User
  rectangle "bridge-email" as EB
  rectangle "bridge-telegram" as TB
  rectangle "bridge-matrix" as MB
  User --> EB : Email
  User --> TB : Telegram
  User --> MB : Matrix
}
rectangle "fdm → notmuch insert" as FDM
EB --> FDM : run_fdm
TB --> FDM : run_fdm
MB --> FDM : run_fdm
rectangle "ingress" as ING
rectangle "enrich" as ENR
rectangle "reasoning" as REA
FDM --> ING
ING --> ENR
ENR --> REA
rectangle "egress_router" as EGR
rectangle "cli_intent" as CLI
rectangle "thread_memory" as TM
rectangle "global_memory" as GM
rectangle "subagent_intent" as SI
rectangle "reflect" as REF
REA --> EGR : "tool: egress_router"
REA --> CLI : "tool: cli_intent"
REA --> TM : "tool: thread_memory"
REA --> GM : "tool: global_memory"
REA --> SI : "tool: subagent_intent"
REA --> REF : "tool: reflect"
rectangle "cli_exec" as EXEC
rectangle "cli_hitl_out" as HITL
CLI --> EXEC : allow
CLI --> ING : deny
CLI --> HITL : HITL
HITL --> EGR
EXEC --> ING
TM --> ING
GM --> ING
REF --> ING
SI --> ING
rectangle "egress_email" as EE
rectangle "egress_telegram" as ET
rectangle "egress_matrix" as EM
rectangle "subagent_end" as SE
rectangle "archive" as ARC
EGR --> EE : "depth == 0"
EGR --> ET : "depth == 0"
EGR --> EM : "depth == 0"
EGR --> SE : "depth > 0"
SE --> ING
EE --> ARC
ET --> ARC
EM --> ARC
actor "Пользователь" as UserOut
EE --> UserOut
ET --> UserOut
EM --> UserOut
@enduml

match "To" ... action pipe "notmuch insert --folder=stages/reasoning/Maildir ... && threlium-dispatch.sh"

@startuml
top to bottom direction
rectangle "fdm → notmuch insert\n--folder=stages/‹stage›/Maildir" as FDM
rectangle "threlium-dispatch.sh\nnotmuch search tag:unread\nAND folder:‹stage›/Maildir\n→ systemctl start --no-block" as DISP
rectangle "threlium-work@‹stage›:‹thread_id›\nType=exec\npython -m threlium.runners.engine_submit %i\n→ JSON в UNIX-сокет" as WORK
rectangle "threlium-engine.service\nДолгоживущий демон\nparse_rfc822 → main() → run_fdm()" as ENGINE
rectangle "nm_settle()\nnew/‹id› → cur/‹id›:2,S\ntags.discard unread + to_maildir_flags" as SETTLE
rectangle "threlium-sweep@‹stage›:‹thread_id›\nRace backstop\nthrelium-dispatch.sh %i\nперепроверка backlog" as SWEEP
rectangle "RAG-loop в engine\nrag.ainsert + tag +lightrag_indexed" as RAG
rectangle "JSON error → submit exit 1\nRestart=on-failure\nбез sweep" as ERR
FDM --> DISP : "&& threlium-dispatch.sh"
DISP --> WORK
WORK --> ENGINE
ENGINE --> SETTLE
SETTLE --> SWEEP : "exit 0 → OnSuccess"
SWEEP ..> DISP : "хвост unread"
SETTLE ..> RAG : "schedule_index_pending"
ENGINE --> ERR : "exception"
@enduml

@startuml
left to right direction
package "Ingress-мосты" {
  rectangle "Email\nIMAP IDLE" as E
  rectangle "Telegram\nLong-poll" as T
  rectangle "Matrix\nmatrix-nio sync" as M
}
rectangle "run_fdm\n→ fdm → notmuch insert\nstages/ingress/Maildir" as FDM
rectangle "FSM\ningress → enrich → reasoning → ..." as FSM
rectangle "egress_router\nresolve X-Threlium-Route\n→ channel" as EGR
E --> FDM : "From: email@localhost\nX-Threlium-Route: b62(JSON)"
T --> FDM : "From: telegram@localhost\nX-Threlium-Route: b62(JSON)"
M --> FDM : "From: matrix@localhost\nX-Threlium-Route: b62(JSON)"
FDM --> FSM
FSM --> EGR
package "Egress" {
  rectangle "egress_email\nmsmtp → SMTP" as EE
  rectangle "egress_telegram\nBot API" as ET
  rectangle "egress_matrix\nClient-Server API" as EM
}
EGR --> EE
EGR --> ET
EGR --> EM
@enduml

• System-промпт из Jinja2-шаблона reasoning/system.j2.
  
• User-промпт с обогащённым контекстом из enrich (контекст графа знаний + хронология треда).
  
• Список tool_specs для каждого возможного маршрута: egress_router, cli_intent, thread_memory, global_memory, subagent_intent.

@startuml
left to right direction
package "Запись (async, после settle)" {
  rectangle "nm_settle()" as SETTLE
  rectangle "schedule_index_pending" as SCHED
  rectangle "Селектор:\nNOT tag:unread\nAND NOT tag:lightrag_indexed" as SEL
  rectangle "rag.ainsert(batch)" as INS
  rectangle "+lightrag_indexed" as TAG
  SETTLE --> SCHED
  SCHED --> SEL
  SEL --> INS
  INS --> TAG
}
package "Чтение (sync, в FSM)" {
  rectangle "enrich" as ENR
  rectangle "LLM: enrich_query_plan.j2" as PLAN
  rectangle "rag.aquery(...)" as AQ
  rectangle "Payload:\n--- user message ---\n--- lightrag context ---" as PAY
  rectangle "reasoning" as REA
  ENR --> PLAN
  PLAN --> AQ
  AQ --> PAY
  PAY --> REA
}
INS ..> AQ : "общий\nworking_dir/"
@enduml

@startuml
participant "reasoning" as R
participant "cli_intent" as CI
participant "cli_hitl_out" as HO
participant "egress_router" as ER
actor "Пользователь" as U
participant "ingress" as I
participant "cli_resume" as CR
participant "cli_exec" as CE
R -> CI : tool call: rm -rf /tmp/data
CI -> CI : classify: не в allow, не в deny
CI -> HO : HITL: спросить пользователя
HO -> ER : письмо с вопросом
ER -> U : «Разрешить rm -rf /tmp/data?»
U -> I : «Да» (ответ через канал)
I -> I : IRT-обход → From: cli_hitl_out
I -> CR : cli_resume
CR -> CE : cli_exec (разрешено)
CE -> I : observation (результат)
@enduml

• reasoning на L0 вызывает tool subagent_intent → маркер в IRT-цепочке с изолированным hop/cap.
  
• Субагент на L1 не знает, кто его вызвал. Работает как обычный агент.
  
• По завершении egress_router по depth > 0 маршрутизирует результат не наружу, а в subagent_end.
  
• subagent_end находит соответствующий subagent_intent по IRT, копирует hop/cap родителя и возвращает письмо в ingress.

@startuml
top to bottom direction
package "L0 — основной диалог" {
  rectangle "reasoning L0" as R0
  rectangle "subagent_intent\n(маркер + изолированный hop/cap)" as SI
  rectangle "ingress" as ING1
  R0 --> SI : "tool: subagent_intent"
  SI --> ING1
}
package "L1 — субагент" {
  rectangle "enrich" as ENR1
  rectangle "reasoning L1" as R1
  rectangle "egress_router\ndepth=1 > 0" as EGR1
  ING1 --> ENR1
  ENR1 --> R1
  R1 --> EGR1 : "tool: egress_router"
}
rectangle "subagent_end\nIRT-обход → subagent_intent\nкопия hop/cap родителя" as SE
rectangle "ingress L0" as ING0
rectangle "enrich L0" as ENR0
rectangle "reasoning L0\n(с результатом субагента)" as R0_2
rectangle "egress_router\ndepth=0" as EGR0
rectangle "egress_‹chan›\n→ пользователь" as OUT
EGR1 --> SE
SE --> ING0
ING0 --> ENR0
ENR0 --> R0_2
R0_2 --> EGR0 : "tool: egress_router"
EGR0 --> OUT
@enduml

• Email: payload = msgspec JSON EmailNativeId(v=1, message_id="<оригинальный MID>")
  
• Telegram/Matrix: payload = utf8(composite_inner)

• Overlay внутренних промптов LightRAG — 12 файлов, копии lightrag.prompt.PROMPTS для текущей версии lightrag-hku.
  
• addon_params для LightRAG — language, entity_types — JSON из Jinja2.
  
• Per-route tool-specs для reasoning — 6 маршрутов × 3 файла = 18 артефактов.

• Python-пакет threlium (editable install в единый .venv).
  
• Конфигурации: threlium.yaml, env/*.env, ~/.fdm.conf, ~/.msmtprc.
  
• systemd-юниты (симлинки в ~/.config/systemd/user/).
  
• Промпты (Jinja2-шаблоны).
  
• Dispatch-скрипт и вспомогательные утилиты.

llm_endpoints:
  - model: "openai/qwen3-35b"
    api_base: "http://vllm-host:8000/v1"
    score: 0.0
    chat_template_kwargs:
      enable_thinking: false
  - model: "openai/qwen3-35b"
    api_base: "http://vllm-host:8000/v1"
    score: 1.0
    chat_template_kwargs:
      enable_thinking: true

@startuml
top to bottom direction
rectangle "pytest\n(control node)" as PY
package "Docker Compose" {
  rectangle "sut\nUbuntu 24.04 + полный site.yml\nprivileged, cgroup host\nживой threlium-engine" as SUT
  rectangle "greenmail\nSMTP :3025\nIMAP :3143\nIMAPS :3993" as GM
  rectangle "wiremock\nOpenAI + Matrix mock\nState Extension\nhost :9080 → :8080" as WM
}
PY --> SUT : "compose up/down"
PY --> SUT : "docker exec"
PY --> WM : "Admin API"
SUT --> GM : "docker DNS: greenmail"
SUT --> WM : "docker DNS: wiremock\nthrelium_openai_api_base"
@enduml

@startuml
left to right direction
rectangle "SMTP inject" as SMTP
rectangle "GreenMail\nINBOX" as GM1
rectangle "IMAP bridge\n(IDLE → fetch)" as IMAP
rectangle "ingress" as ING
rectangle "enrich\n(LightRAG aquery)" as ENR
rectangle "reasoning\n(WireMock: tool call)" as REA
rectangle "egress_router" as EGR
rectangle "egress_email\n(msmtp)" as EE
rectangle "GreenMail\nINBOX pytest@" as GM2
rectangle "pytest\nassert In-Reply-To" as ASSERT
SMTP --> GM1
GM1 --> IMAP
IMAP --> ING
ING --> ENR
ENR --> REA
REA --> EGR
EGR --> EE
EE --> GM2
GM2 --> ASSERT
@enduml

• Крэш стадии: файл остаётся в new/+unread. Restart=on-failure повторяет попытку. Sweep (после успеха) перепроверяет backlog.
  
• Крэш между rename(2) и Xapian-commit: файл уже в cur/, но notmuch думает, что он в new/. settle_recovery_for_stage() на старте воркера лечит через from_maildir_flags().
  
• Крэш моста: sys.exit(1) + Restart=on-failure. Курсор восстанавливается из notmuch.
  
• Крэш движка: все submit’ы получают BindsTo на threlium-engine.service. При рестарте движка воркеры перезапускаются автоматически.
  
• LightRAG drain прервался: тег +lightrag_indexed не поставлен → следующий drain повторит ainsert. LightRAG dedup гарантирует безопасность.

namespace inbox {
  inbox = yes
  location = maildir:$THRELIUM_HOME/stages:LAYOUT=fs:DIRNAME=Maildir
}

• Режим threads с сортировкой по дате — цепочки рассуждений видны как нити писем.
  
• Виртуальная папка Virtual/All подключена как архив и в default_folders.
  
• mail_read_time = -1 — Roundcube не ставит флаг «прочитано» при открытии (в паре с ACL Dovecot).
  
• SQLite для хранения сессий — никакого MySQL/PostgreSQL.

:8080 {
    handle_path /webmail/* {
        root * /usr/share/roundcube
        php_fastcgi unix//run/php/php-fpm.sock
        file_server
    }
    route * {
        reverse_proxy 127.0.0.1:9090 {
            transport http { tls_insecure_skip_verify }
        }
    }
}

@startuml
left to right direction
actor "Оператор" as OP
package "Target host" {
  package "Caddy :8080" as CADDY {
    rectangle "/webmail/*" as WM
    rectangle "/* (всё остальное)" as ROOT
  }
  rectangle "Roundcube\nPHP-FPM" as RC
  rectangle "Cockpit :9090\n(loopback only)" as CP
  rectangle "Dovecot :143\n(loopback, PAM)" as DOV
  WM --> RC
  ROOT --> CP
  RC --> DOV : "IMAP localhost:143"
  package "$THRELIUM_HOME/stages/" {
    rectangle "ingress/Maildir" as MD1
    rectangle "enrich/Maildir" as MD2
    rectangle "reasoning/Maildir" as MD3
    rectangle "…/Maildir" as MDN
  }
  DOV --> MD1 : "read-only\nACL: lr"
  rectangle "Cockpit package\nthrelium-mail-archive\niframe → /webmail/" as PKG
  CP -- PKG
  PKG ..> WM : "iframe src"
}
OP --> CADDY : "браузер"
@enduml

ansible/
  playbooks/
    site.yml                    # единственный сценарий
    tasks/
      refresh.yml               # узкий тег: чистка + рестарт
      mail_archive_web.yml      # веб-стек (Cockpit/Caddy/…)
      mail_archive_web_acceptance.yml
      ssh_hardening.yml
  roles/threlium/
    defaults/main.yml           # дефолтные переменные
    vars/main.yml               # канон FSM-стадий
    files/
      scripts/                  # Python-код FSM + bash-скрипты
      prompts/                  # Jinja2-промпты для LLM
      mail-archive/             # статика: dovecot-virtual
    templates/
      config/                   # fdm.conf, msmtprc, threlium.yaml
      systemd/user/             # шаблоны unit-файлов
      mail-archive/             # Caddyfile, cockpit.conf, …
      env/threlium.env.j2
      pyproject.toml.j2
  host_vars/                    # per-host: LLM endpoints, секреты
  group_vars/                   # общие переменные и e2e-оверрайды
  inventory/                    # hosts (прод и e2e)

@startuml
top to bottom direction
package "--tags deploy (полный прогон)" {
  rectangle "apt: fdm, notmuch,\npython3, cockpit, caddy…" as D1
  rectangle "Каталоги + Maildir'ы" as D2
  rectangle "copy: Python-код FSM" as D3
  rectangle "template: конфиги,\nunit-файлы, env" as D4
  rectangle "pip install + venv" as D5
  rectangle "Веб-стек\n(Cockpit/Caddy/…)" as D6
  rectangle "Acceptance" as D7
  rectangle "Bundle" as D8
  D1 --> D2
  D2 --> D3
  D3 --> D4
  D4 --> D5
  D5 --> D6
  D6 --> D7
  D7 --> D8
}
package "--tags refresh (узкий прогон)" {
  rectangle "Остановка engine + мостов" as R1
  rectangle "Синхронизация:\nscripts/, env,\nшаблоны конфигов/юнитов" as R2
  rectangle "daemon-reload" as R3
  rectangle "Чистка Maildir/notmuch/\nLightRAG" as R4
  rectangle "Рестарт user-units" as R5
  R1 --> R2
  R2 --> R3
  R3 --> R4
  R4 --> R5
}
@enduml

• Оператор правит скрипт/конфиг прямо на target → daemon-reload → git commit. Симлинки сразу видят новое.
  
• Агент — через cli_exec в рамках capability-профиля. Может менять свои промпты, конфиги, даже Python-код, коммитя изменения в локальный git.
  
• Обратной синхронизации target → control нет и не предполагается. Каждая установка эволюционирует независимо.

термине. Эта конструкция домашнего агента совершенно прозрачна для отладки и модификации другими агентами!