Praxis

Долгоживущий агент в Telegram: один субъект с файловой памятью, который переживает
рестарт вместе с недоделанной работой.

Живёт на сервере в Docker, говорит через пользовательский аккаунт Telegram (MTProto,
не Bot API), работает руками — код, git, тесты, shell, веб, почта, подключённый Windows —
и оставляет проверяемый след каждого действия.

Python: 128 модулей и 209 файлов тестов — 3813 тестов, 42% всего Python-кода.
Rust: 40 файлов в трёх компонентах. AGPL-3.0-or-later.

Что здесь необычного

Восемь решений, из-за которых этот репозиторий отличается от типового «агента с руками и
памятью». Каждое — с адресом в коде.

1. Один OpenAI-совместимый relay вместо API-биллинга — relay/

Rust-прокси, который отдаёт /chat/completions поверх подписки ChatGPT, а не
per-token API. От него питается всё: голос, оценщик, кодинг-воркеры.

Внутри — роутер на два аккаунта (relay/src/core/account_router.rs): активный слот
липкий и переживает рестарт, исчерпание квоты переводит на запасной с кулдауном, и есть
POST /v1/account/switch для осознанного перехода. Слот живёт в памяти процесса, поэтому
переключение действует сразу.

2. Ход не заканчивается на первом же тексте — work_loop.py

Классический tool-loop возвращается, как только модель выдала текст без вызова
инструмента, и вызывающий закрывает работу как сделанную. То есть «работа закончена»
выводится из молчания.

Здесь иначе: в рабочем окне ход закрывает только task_control(done|blocked|wait), и
done требует evidence. В чате дешевле: реплика без единой руки один раз возвращается ей
зеркалом — её же текст и факт «рук не звала», — и решает она.

3. Каждый ход — durable run — run_manager.py, run_snapshot.py

memory/runs/YYYY-MM/<run_id>/ с неизменяемым снимком контекста, WAL-событиями, полными
результатами инструментов и артефактами. После обрыва ход переавторствуется живьём с
того места, где встал, а не начинается заново.

Отправка в Telegram сначала записывает намерение, потом трогает сеть; повтор идёт с тем же
MTProto random_id, поэтому дубликата у собеседника не появляется
(telegram_outbox.py). Неизвестный исход побочного эффекта не объявляется ни успехом, ни
безопасным повтором — run уходит в in_doubt.

4. Канон — markdown и JSONL, а не база — memory/

Люди, комнаты, намерения, наблюдения, журнал — человекочитаемые файлы. SQLite здесь
только перестраиваемый ускоритель FTS: его можно удалить и собрать заново, канон не
пострадает. Отдельной схемы, миграции и create-DB скрипта нет намеренно.

RAG-контура тоже нет. Индекс помогает найти след; важное сверяется с первоисточником.

5. Макет кадра — frame_layout.py, gutter.py, frame_trace.py

Контекст не склеивается как попало. Чужой текст едет под гуттером > , а конец секции
вычисляется по метру, а не ищется регуляркой — поэтому сообщение собеседника не может
подделать заголовок структуры. Порядок ярусов подобран так, чтобы не ломать префиксный
кэш провайдера.

Отдельный прибор (frame_trace) измеряет собственный кадр, не сдвигая его: наблюдатель
не двигает наблюдаемое, и это проверяется тестом.

6. Она меняет свой код через предложения и гейт — selfdev.py, forge.py

Правка ядра идёт в отдельном git-worktree на ветке proposal/<id>, прогоняется полным
набором тестов в песочнице и мёржится её собственным решением с записью причины. Откат —
обычный git.

forge.py — контур кодинг-задач: изолированные worktree, независимые агенты-скауты и
ревьюеры, evidence перед интеграцией.

7. Руки за пределами контейнера — body/, hands/, serverd

body/ — Rust-клиент для Windows: интерактивная сессия и SYSTEM, типизированный envelope
внутрь, evidence наружу. Без второй LLM и без второго «я» — решения остаются в одном
месте.

hands/ — Rust-бинарь файловых рук: зоны записи, таймауты, потолки вывода и расписка
зашиты в компилируемый пол, а не только в Python.

8. Пределы названы поимённо и считаются кодом — rails.py, capabilities.py

52 рельса в реестре, каждый с именем, значением и границей; capabilities.snapshot()
собирает «что я могу» из живых констант, а не из описания. Она читает это о себе сама, и
расхождение манифеста с кодом — красный тест, а не заметка.

Быстрый старт

Полностью контейнерный бандл: один compose-файл, один .env, две команды на вход в
Telegram. Одинаково работает в Docker Desktop и на сервере — network_mode: host не
используется нигде.

cp env.bundle.example .env          # заполнить API_ID/HASH, телефон, owner id, ключ модели
docker compose -f docker-compose.bundle.yml up -d --build
docker compose -f docker-compose.bundle.yml exec praxis python mtproto_login.py send
docker compose -f docker-compose.bundle.yml exec praxis python mtproto_login.py code 12345

Подробно, включая обновление без потери состояния и опциональные профили relay/Ollama —
BUNDLE.md. Разработческий compose и production-контур с host-mount'ами —
DEPLOY.md.

Нужно: Docker с плагином compose, ~3 ГБ на образ, аккаунт Telegram и ключ модели. Первая
сборка небыстрая — внутри собирается Rust-бинарь файловых рук.

Карта репозитория

Проверки

docker compose exec praxis python praxis_test_parallel.py     # весь набор, ~2 минуты
docker compose exec praxis python praxis_test.py discover -q  # последовательно

Полный набор идёт только внутри Linux-контейнера или на Linux-сервере: часть тестов
поднимает дочерние процессы и POSIX-специфичные контуры. Нативный Windows-запуск для них
не поддерживается — точные границы в AGENTS.md.

В публичном дереве несколько тестов ожидаемо красные: они сверяют приватное содержимое
(живые рельсы, карта навыков, индекс живой памяти), которого здесь нет. Сверять надо
состав падений, а не их отсутствие.

Чего здесь нет

Публикуется исходный код, не жизнь. В репозиторий не попадают: живые soul/SOUL.md,
VOICE.md, rails.md и self/, диалоги, досье людей, комнаты, цели, receipts, Telegram-
сессия, outbox, run evidence, состояние Forge и device spool. Вместо них — *.example.md.

Секреты остаются в .env и runtime-файлах и не коммитятся. Модельные роли и лимиты живут
в memory/llm.json, который создаётся при первом старте.

Лицензия

AGPL-3.0-or-later. Полный текст — в LICENSE, дословно и без правок.

Ключевое отличие AGPL от GPL — сетевое использование: если вы измените Praxis и дадите
людям работать с изменённой версией по сети, вы обязаны предоставить этим людям исходный
код изменённой версии (раздел 13 AGPLv3).

Почему именно AGPL — в NOTICE.