Протокол ядра

1. Общие правила

Стороны. Оболочка — процесс на C#, владеет окном, устройствами вывода и каналом. Ядро — процесс на Python, принимает решения. Оболочка запускает ядро, следит за ним и перезапускает; ядро подключается клиентом.

Направления. Оболочка шлёт запросы («сделай»), ядро отвечает и шлёт события («случилось»). Ядро тоже может слать запросы — их ровно два вида: запрос разрешения и запрос данных, которыми владеет оболочка (индекс программ).

Ядро решает, оболочка показывает. Ядро не умеет открывать окна и не знает, как выглядит диалог. Оно сообщает о намерении, оболочка решает, как это выглядит и показывать ли вообще.

Всё сериализуемо. Значение любого поля — строка, число, логическое, массив или объект. Исключений нет: то, что нельзя записать в JSON, остаётся внутри стороны и наружу не выходит.

2. Каналы и кадрирование

Два канала на сессию:

Раздельные, чтобы всплеск звука не задерживал управляющее сообщение за собой. Это требование 4.0-D07, и его проверяет тест: поток PCM не должен ухудшать задержку управляющего канала.

<session> — случайный идентификатор, порождаемый оболочкой при запуске и передаваемый ядру аргументом командной строки. Дескриптор безопасности канала ограничивает доступ пользователем сессии.

[4 байта: длина полезной нагрузки, big-endian, без знака][полезная нагрузка: JSON в UTF-8]

[4 байта: длина остатка кадра][4 байта: stream_id][8 байт: порядковый номер][полезная нагрузка: байты]

3. Конверт

Поля конверта присутствуют в каждом сообщении управляющего канала без исключений.

Пример:

{
  "v": 1,
  "type": "request",
  "id": "s-0042",
  "method": "command.handle",
  "timestamp": 1756750000.123,
  "trace_id": "t-8f21",
  "payload": {"text": "запусти телеграм", "source": "typed", "require_wake": false}
}

Неизвестный method в запросе → ошибка protocol.unknown_method. Неизвестное событие → получатель молча его игнорирует. Эта асимметрия намеренна: пропущенный запрос — потерянное действие, пропущенное событие — потерянное уведомление.

4. Рукопожатие и согласование возможностей

Первое сообщение в сессии. До успешного рукопожатия любой другой метод отвечает ошибкой protocol.not_ready.

Оболочка → ядро:

{"method": "hello", "payload": {
  "protocol_versions": [1],
  "shell_version": "4.0.0",
  "capabilities": ["audio.input", "audio.output", "permissions", "window.actions"],
  "locale": "ru"
}}

Ядро → оболочка:

{"type": "response", "correlation_id": "...", "payload": {
  "protocol_versions": [1],
  "protocol_version": 1,
  "core_version": "4.0.0",
  "capabilities": ["stt", "tts", "reminders", "llm", "plugins"],
  "session_id": "3f0c…"
}}

Каждая сторона объявляет набор версий, которые реализует, даже если версия одна. Совместимы, если наборы пересекаются; работают по наибольшей общей, и ядро называет её в protocol_version ответа — дальше это значение стоит в поле v каждого сообщения.

Набор нужен потому, что оболочка обязана держать предыдущую версию один выпуск (ADR 0004): она объявляет [1, 2] и одинаково работает и с новым ядром, и со старым. С одним числом ступенчатое обновление невозможно — пришлось бы менять обе части одновременно.

Возможность — это обещание понимать группу методов. Сторона не вызывает метод, чью возможность собеседник не объявил. Так ядро и оболочка обновляются независимо: новая оболочка со старым ядром просто не покажет то, чего старое ядро не умеет.

Несовместимость версий протокола → protocol.incompatible с понятным текстом; загадочного обрыва быть не должно. Требование 4.0-D03: старая оболочка с новым ядром обязана сказать, что именно не так.

5. Ошибки

Ошибка — часть контракта, такая же, как ответ.

{"type": "error", "correlation_id": "s-0042", "payload": {
  "code": "app.not_found",
  "category": "user",
  "retryable": false,
  "message": "Не нашла программу «фотошоп».",
  "details": {"query": "фотошоп"}
}}

Код и текст разделены намеренно. Текст переводится и переформулируется, код — нет; логика ветвится по коду, пользователь читает текст. Позже по details сможет осмысленно исправиться языковая модель, вместо того чтобы зациклиться (5.0-C05).

protocol.invalid_envelope добавлен при реализации 4.0-D04: требование §15.1 объявляло отсутствие обязательного поля ошибкой категории protocol, но кода для неё в каталоге не было. Поля, которых не хватило, перечисляются в details.fields — иначе сообщение «конверт неполон» отправляет отлаживающего искать вручную.

retryable значит «имеет ли смысл повторить то же самое». Поможет ли что-то другое, это поле не говорит. Просроченное подтверждение неповторяемо: тот же вызов с тем же идентификатором провалится снова. Получить новое подтверждение и позвать заново, разумеется, можно — но это уже не повтор.

Начальный каталог:

Каталог сверяется с кодом, на веру его никто не держит. tools/test_wire.py читает эту таблицу и сравнивает её с core/wire/errors.py в обе стороны, а сверх того требует, чтобы каждый код, объявленный любым инструментом реестра, здесь присутствовал. Первый прогон нашёл пять пропусков: tool.unknown, tool.invalid_arguments, confirmation.required, confirmation.expired и calc.zero_division — ядро их отправляло, а документ о них не знал.

Подтверждения и разрешения — разные вещи и разные коды. permission.* относится к каталогу разрешений (4.0-C04): есть ли у действия право в принципе. confirmation.* относится к предъявленному подтверждению (4.0-C05): спросили ли пользователя про этот конкретный вызов с этими аргументами. Одно не заменяет другого, и слить их в один код значило бы потерять различие между «так нельзя» и «так можно, но спросите».

6. Управляющие методы

Выведены из фактического поведения 3.1.0 (см. инвентарь) — не придуманы заново.

7. Потоковый текст

Ответ модели приходит по частям, чтобы речь начиналась раньше, чем ответ дописан. Реализуется в 4.0 (4.0-D06), потребитель появляется в 5.0.

{"type": "event", "method": "stream.chunk", "stream_id": 7,
 "payload": {"text": "Столица Австралии — "}}
{"type": "event", "method": "stream.end", "stream_id": 7,
 "payload": {"reason": "done"}}

reason: done, cancelled, failed. При failed рядом идёт error с тем же stream_id.

Поток открывается ответом на запрос, который его породил: {"stream_id": 7}. Получатель обязан выдержать stream.chunk до того, как обработал ответ, открывший поток — сообщения асинхронны.

8. Канал данных и обратное давление

Двоичный поток открывается управляющим сообщением и живёт до закрытия.

{"method": "stream.open", "payload": {
  "kind": "audio.input", "stream_id": 11,
  "format": {"encoding": "pcm_s16le", "rate": 16000, "channels": 1}
}}

Виды: audio.input (микрофон, оболочка → ядро), audio.output (синтез, ядро → оболочка), screen.frame (5.0, оболочка → ядро).

Кредитная схема (4.0-D08). Приёмник объявляет, сколько байт готов принять; отправитель не имеет права держать в полёте больше:

{"method": "stream.credit", "stream_id": 11, "payload": {"bytes": 65536}}

Начальный кредит — 0. Отправитель молчит, пока не получит первый кредит.

Именно ноль, без аванса: приёмник, который ещё не готов, не должен получать данные вовсе. Аванс превратил бы ошибку «забыли выдать кредит» в редко воспроизводимую — она проявлялась бы только на потоках длиннее аванса.

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

Кредит считается по потоку. Микрофон и синтез идут одновременно и в разные стороны; общий счёт связал бы их скорости друг с другом без всякой на то причины. И считается он в байтах: память съедают байты, и поток из тысячи мелких кадров ничем не лучше десяти крупных того же объёма.

Без всего этого быстрый источник кадров или звука переполняет очередь и утаскивает память — отказ, который снаружи выглядит как «программа съела гигабайт», а изнутри не выглядит никак.

Закрытие: stream.close с stream_id. Обрыв канала данных закрывает все потоки.

Перебивание — не закрытие потока (4.0b-E12). Событие speech.stop означает «оборви речь и выброси недоигранное»: поток остаётся открытым, потому что следующая реплика пойдёт по нему же. Закрытие — это конец разговора с устройством, а перебивание — реплика в этом разговоре.

{"type": "event", "method": "speech.stop", "payload": {}}

Обратного подтверждения нет: перебивание либо случилось у получателя, либо играть уже было нечего, и третьего исхода не бывает.

9. Долгие задачи

Кодинг-задача в RinaNeuro идёт минутами. Модель «запрос-ответ» этого не выражает, поэтому lifecycle закладывается сейчас (4.0-D09), а проверяется заглушкой на 60 секунд.

accepted ──> running ──┬──> done
                       ├──> failed
                       └──> cancelled
              (progress, partial — сколько угодно раз)

Ровно одно из done/failed/cancelled завершает задачу.

запрос task.cancel  ──>  response {accepted: true}  ──>  … фактическая остановка …  ──>  event task.cancelled

{"accepted": true,  "status": "running"}
{"accepted": false, "status": "done"}
{"accepted": false, "status": "unknown"}

10. Push-события

Ядро отправляет без запроса. Первый настоящий потребитель — сработавшее напоминание (4.0-E05), и хорошо, что он появляется уже в 4.0: канал проверяется на живой задаче.

Позже сюда приходят инициатива Рины и смена эмоционального состояния (этап B RinaNeuro).

11. Канал разрешений

Ядро не может выполнить опасное действие само и не умеет показывать окна. Оно просит, оболочка спрашивает пользователя, решение возвращается ядру.

{"type": "request", "method": "permission.request", "payload": {
  "request_id": "ask-7Kd2p",
  "permission": "system.power",
  "action": "shutdown",
  "reason": "Пользователь сказал «выключи компьютер»",
  "preview": "Компьютер будет выключен немедленно.",
  "ttl": 60
}}

Ответ оболочки:

{"payload": {"request_id": "ask-7Kd2p", "granted": true, "scope": "once"}}

confirmation_id по каналу не ходит вовсе. Первая редакция этого раздела возвращала его в ответе оболочки — то есть оболочка его и порождала. Это прямо противоречило 4.0-C05, где записано: решение о том, подтверждено ли действие, не должно приниматься на стороне оболочки, иначе его можно обойти со стороны интерфейса. Оболочка, выпускающая идентификаторы, может выпустить любой, и ядру нечем отличить настоящий от выдуманного, — а вся однократность и привязка к аргументам держатся ровно на том, что идентификатор выдан ядром под конкретный вызов.

Поэтому: номер просьбы (request_id) выпускает ядро, оболочка отвечает «да» или «нет», и только после «да» ядро выписывает подтверждение — себе, внутрь. Оболочка не может создать подтверждение; она может лишь разрешить его создать.

confirmation_id одноразовый. Инструмент, требующий подтверждения, отклоняет вызов без действительного идентификатора — даже если вызов пришёл изнутри ядра. Это 4.0-C05, и его критерий приёмки: попытка выполнить power_action без подтверждения падает с явной ошибкой в тесте.

Аргументы вызова в просьбу не входят. Оболочке нужно показать пользователю preview, то есть словами, что именно произойдёт; сериализованный вызов ему ни к чему; отпечаток аргументов остаётся в ядре, там же, где проверяется.

scope: once — одно исполнение; until — до истечения срока, сколько угодно раз.

Областей две. «До конца сессии» убрано: §13 и так говорит, что выданные разрешения переподключение не переживают, то есть сессия — верхняя граница любой области. Третье имя для того же поведения — приглашение считать, будто оно другое.

Опасному действию until не выдаётся. Разрешение, действующее полчаса на выключение компьютера, — это и есть тот случай, ради которого подтверждение заводили. Если оболочка попросит такую область, ядро понижает её до once и отмечает это флагом downgraded: пользователь согласился на это действие, и терять его согласие незачем, а расширять — незачем тем более.

Оболочка обязана показать preview, то есть что именно произойдёт; одного названия действия мало. Отказ по умолчанию: истёкшее окно равносильно «нет», и поздний ответ «да» разрешения не даёт. Не «ждём дальше» и не «раз молчит, значит согласен»: молчание может означать, что окна вообще никто не увидел.

12. Канал актуации — только спецификация

Форма сообщений синтеза ввода и захвата экрана описывается сейчас, реализуется в 5.0 (4.0-D13). В 4.0 методы существуют и отвечают protocol.unknown_method, а возможность actuation не объявляется.

Смысл описывать заранее: модель разрешений вокруг этих сообщений продумывается, пока это стоит абзаца. Каждый метод требует действительного confirmation_id и живой сессии актуации; вне области действия вызов отклоняется и записывается в журнал.

13. Живость, обрыв, переподключение

Heartbeat. Обе стороны шлют ping при тишине дольше 5 секунд; получатель отвечает pong. Три пропущенных подряд — сторона считается мёртвой.

Молчание — не признак смерти. Признак смерти — молчание в ответ на прямой вопрос, поэтому ping шлётся только после паузы, а мёртвой сторона считается после трёх неотвеченных подряд: одна потеря может случиться от чего угодно, три подряд — уже закономерность.

Любое сообщение считается за pong. Занятый канал пинговать незачем: собеседник, только что приславший событие, жив не менее убедительно. Отсюда счётчик тишины вместо таймера по расписанию.

Ядро упало. Оболочка обнаруживает обрыв, показывает состояние (4.0-F12), перезапускает ядро и повторяет рукопожатие. Окно не должно выглядеть зависшим — это требование 4.0-D14.

Оболочка упала. Ядро видит обрыв и завершается: без оболочки оно не нужно и не должно оставаться висеть.

Что переживает переподключение. Настройки, команды, история, напоминания, плагины — они в хранилище. Что не переживает: незакрытый уточняющий вопрос, открытые потоки, выданные разрешения, незавершённые задачи. После рукопожатия состояние собирается заново запросами; по памяти оно не восстанавливается.

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

Задачи при обрыве забываются, их не отменяют: отменить — значит отправить task.cancelled, а отправлять некому.

Перечисленное собрано в одном месте (core/wire/liveness.py) намеренно. Разложенное по владельцам, оно сбрасывалось бы в нескольких местах, и однажды где-то не сбросилось бы — причём незаметно: пережившее обрыв разрешение выглядит как обычное разрешение, и обнаружится оно только тем, что сработает.

14. Сквозная трассировка

trace_id рождается там, где началось действие — нажатие в оболочке или распознанная фраза, — и переносится во все сообщения, порождённые этим действием, включая события и ошибки. Оба слоя пишут его в журнал.

Это единственный способ отлаживать двухпроцессную систему: без него в двух журналах лежат два несвязанных набора строк.

15. Требования к реализации

Из этой спецификации выводятся conformance-тесты (4.0-D16): mock-оболочка против настоящего ядра и mock-ядро против настоящей оболочки. Набор — tools/conformance.py; обе стороны в нём видят только байты, потому что требование, выполненное вызовом функции, но не выполненное через провод, не выполнено.

Транспорт — внутри процесса, без именованного канала: ADR 0002 требует, чтобы протокол от транспорта не зависел, и conformance обязан это доказывать.

Но независимость протокола от транспорта не отменяет проверки самого транспорта. 4.0-F02 завёл вторую проверку — shell/Rina.Protocol.Probe, где настоящая оболочка идёт против настоящего ядра через именованный канал. Первый же её прогон нашёл то, чего внутрипроцессный набор поймать не мог по построению: у синхронного дескриптора Windows операции сериализуются, и пока ядро висело в чтении, его же запись ждала завершения этого чтения. Push-события §10 не работали вовсе — ядро молчало, пока оболочка чего-нибудь не пришлёт, и выглядело это как «задумалось».

Проверяется как минимум следующее.

3a. Оболочка, объявляющая [1, 2], работает с ядром, объявляющим [1], по версии 1. Без этой проверки обязательство ADR 0004 держать предыдущую версию остаётся декоративным.

1. Каждое сообщение несёт полный конверт; отсутствие обязательного поля — ошибка protocol.
2. Неизвестный метод даёт protocol.unknown_method; неизвестное событие игнорируется молча.
3. Несовместимая версия протокола даёт понятное сообщение; обрывом она не заканчивается.

4. Возможность, не объявленная в рукопожатии, не вызывается.
5. Отправитель не превышает выданный кредит.
6. Поток PCM не ухудшает задержку управляющего канала.
7. Задача на 60 секунд отдаёт прогресс, промежуточный результат и завершается ровно одним финальным событием.
8. Отмена даёт подтверждение получения, затем task.cancelled; задача, завершившаяся раньше, даёт done и не даёт cancelled.
9. Опасное действие без действительного confirmation_id отклоняется.
10. Просроченный confirmation_id отклоняется.
11. Падение ядра приводит к перезапуску и новому рукопожатию без потери пользовательских данных.
12. trace_id присутствует во всей цепочке от запроса до финального события.

16. Что осталось открытым

~~Формат reminder.fired.item~~ — закрыт в 4.0-E05, форма описана в §10. Отдельного приведения к JSON не потребовалось: хранилище с самого начала клало простые значения, и это оказалось проверяемым фактом.

• 4.0-E06a — владеет ли ядро описанием формы настроек или только значениями. От этого зависит содержимое settings.describe, и до решения метод описан лишь по имени.
• Формат декларативной страницы плагина — 4.0-H01. Словарь API v2 из 3.1.0 (title, text, note, items, button, input, table, progress, badge, divider) семантичен и переносится почти целиком, но он плоский: контейнеров, колонок и группировки в нём нет. Решается после 4.0-R05, когда станет известно, из чего состоит новый дизайн.

Справочник контракта

Собран из docs/protocol/contract-v1.json: по этому файлу сверяются обе стороны, и из него же порождается часть протокола на C#. Версия протокола — 1.