papayu/docs/PROTOCOL_V1.md

Protocol v1 — контракт papa-yu

Краткий документ (1–2 страницы): что гарантируется, лимиты, логирование, PLAN→APPLY, strict/best-effort.

---

Версионирование

• schema_version: 1
• schema_hash: sha256 от llm_response_schema.json (в trace)
• При изменении контракта — увеличивать schema_version; v2 — новый документ.

---

Гарантии

1. JSON: ответ LLM парсится; при неудаче — 1 repair-ретрай с подсказкой.
2. Валидация: path (no ../, absolute, ~), конфликты действий, content (no NUL, pseudo-binary).
3. UPDATE base: в APPLY каждый UPDATE_FILE — только для файлов, прочитанных в Plan.
4. Protected paths: .env, *.pem, *.key, id_rsa*, **/secrets/** — запрещены.
5. Apply: snapshot → apply → auto_check; при падении check — rollback.

---

Лимиты

Область	Переменная	По умолчанию
path_len	—	240
actions	—	200
total_content_bytes	—	5MB
context_files	PAPAYU_CONTEXT_MAX_FILES	8
file_chars	PAPAYU_CONTEXT_MAX_FILE_CHARS	20000
context_total	PAPAYU_CONTEXT_MAX_TOTAL_CHARS	120000

---

Логирование

Событие	Где
LLM_REQUEST_SENT	stderr (model, schema_version, provider, token_budget, input_chars)
LLM_RESPONSE_OK, LLM_RESPONSE_REPAIR	stderr
VALIDATION_FAILED	stderr (code, reason)
CONTEXT_CACHE_HIT, CONTEXT_CACHE_MISS	stderr (key)
CONTEXT_DIET_APPLIED	stderr (files, dropped, truncated, total_chars)
APPLY_SUCCESS, APPLY_ROLLBACK, PREVIEW_READY	stderr

Trace (PAPAYU_TRACE=1): .papa-yu/traces/<trace_id>.json — config_snapshot, context_stats, cache_stats, validated_json, schema_version, schema_hash.

---

PLAN → APPLY

1. Plan: plan: <текст> или «исправь/почини» → LLM возвращает actions: [], summary, context_requests.
2. Apply: apply: <текст> или «ok»/«применяй» при сохранённом плане → LLM применяет план с тем же context.
3. NO_CHANGES: при пустом actions в APPLY — summary обязан начинаться с NO_CHANGES:.

---

Strict / best-effort

• strict (PAPAYU_LLM_STRICT_JSON=1): response_format: json_schema в API; при ошибке schema — repair-ретрай.
• best-effort: без response_format; извлечение из json ... ; при ошибке — repair-ретрай.
• Capability detection: при 4xx/5xx с упоминанием response_format — retry без него.

---

Кеш контекста

read_file, search, logs, env кешируются в plan-цикле. Ключ Logs: {source, last_n} — разные last_n не пересекаются.

---

Контекст-диета

При превышении лимитов — урезание: search → logs → файлы низкого приоритета; FILE (read_file) — последними; для priority=0 гарантия минимум 4k chars.

---

Provider Compatibility

Provider	Endpoint	response_format: json_schema	strict	OneOf (array/object)	Режим
OpenAI	/v1/chat/completions	✅	✅	✅	strict + local validate
OpenAI-compatible (часть)	разные	⚠️	⚠️	⚠️	best-effort + local validate + repair
Ollama	/api/chat	❌ (часто)	❌	⚠️	best-effort + local validate + repair

Поведенческие гарантии:

1. Если response_format не поддержан провайдером → fallback и лог LLM_RESPONSE_FORMAT_FALLBACK.
2. Локальная schema validation выполняется всегда (если schema compile ok).
3. Repair-ретрай выполняется один раз при невалидном JSON.
4. Если после repair невалидно → Err.
5. Capability detection: при 4xx/5xx с упоминанием response_format/json_schema → retry без него.

Ускоряет диагностику: если Ollama/локальная модель «тупит» — выключи PAPAYU_LLM_STRICT_JSON или оставь пустым.