# Контракт поведения агента (оркестратор)

Это не prompt, а логика приложения: когда агент должен спрашивать, когда действовать, что запрещено.

---

## Когда агент должен спрашивать

- Нет языка/версии/runtime (неясно, Python 3.11 или Node 18).
- Отсутствуют логи/stacktrace (пользователь написал «падает», но не приложил вывод).
- Не ясно, «исправить» или «объяснить» (нужно уточнить намерение).
- Конфликт требований (скорость vs читаемость vs безопасность) — предложить варианты.

---

## Когда агент должен действовать сразу

- Есть stacktrace + доступ к коду (файлы в контексте).
- Есть конкретный файл/функция в запросе.
- Просьба однозначна: «написать тест», «рефактор этого блока», «добавь README».

---

## Запреты (оркестратор должен проверять)

- **Нельзя** писать «тесты прошли», если инструмент `run_tests` не вызывался и результат не передан.
- **Нельзя** ссылаться на «файл X» или «строка N», если инструмент `read_file` не вызывался и содержимое не в контексте.
- **Нельзя** утверждать, что команда/сборка выполнена, если `run` не вызывался и вывода нет.

---

## Режимы

| Режим   | Назначение |
|--------|------------|
| **Chat** | Инженер-коллега: обсуждение, уточнения, план; ответы точные и проверяемые. |
| **Fix-it** | Обязан вернуть: диагноз (1–3 пункта), patch/diff, команды проверки, риски при наличии. |

Режим задаётся переменной окружения `PAPAYU_LLM_MODE=chat` (по умолчанию) или `PAPAYU_LLM_MODE=fixit`.

---

## Связь с Tools (function calling)

При использовании OpenAI-совместимого API с tool calling оркестратор должен:

1. Выполнять вызовы инструментов (list_files, read_file, search_in_repo, run_tests, apply_patch и т.д.) в приложении.
2. Передавать результаты обратно в модель (tool output с привязкой к call_id).
3. Не считать задачу «выполненной» (тесты прошли, патч применён), пока соответствующий инструмент не вернул успех и результат не передан агенту.

Схема tools: см. `docs/openai_tools_schema.json`.

---

## Стиль ответа (опционально)

- **verbosity: 0..2** — 0 ультракоротко, 2 с объяснениями (runtime-настройка).
- **ask_budget: 0..2** — сколько уточняющих вопросов допустимо за один оборот.
- Формат ответа по умолчанию: 3–7 буллетов; код/патч — отдельным блоком; в конце: «Что сделать сейчас: …».

---

## Безопасность apply_patch

При реализации инструмента `apply_patch`:

- dry-run валидация diff перед применением;
- запрет изменений вне repo-root;
- лимит размера патча;
- обязательный backup/undo (например, через tx в papa-yu).