chore(i18n): refresh uk translations

docs/uk/concepts/agent-loop.md

@@ -1,26 +1,27 @@
 ---
 read_when:
     - Вам потрібен точний покроковий опис циклу агента або подій життєвого циклу
+    - Ви змінюєте поведінку черги сесій, запису транскриптів або блокування запису сесії
 summary: Життєвий цикл циклу агента, потоки та семантика очікування
 title: Цикл агента
 x-i18n:
-    generated_at: "2026-04-12T18:22:00Z"
+    generated_at: "2026-04-23T03:59:22Z"
     model: gpt-5.4
     provider: openai
-    source_hash: 3c2986708b444055340e0c91b8fce7d32225fcccf3d197b797665fd36b1991a5
+    source_hash: 439b68446cc75db3ded7a7d20df8e074734e6759ecf989a41299d1b84f1ce79c
     source_path: concepts/agent-loop.md
     workflow: 15
 ---
 
 # Цикл агента (OpenClaw)
 
-Агентний цикл — це повний «реальний» запуск агента: прийом → збирання контексту → інференс моделі →
+Агентний цикл — це повний «реальний» запуск агента: приймання → збирання контексту → інференс моделі →
 виконання інструментів → потокові відповіді → збереження. Це авторитетний шлях, який перетворює повідомлення
-на дії та фінальну відповідь, водночас зберігаючи узгоджений стан сесії.
+на дії та фінальну відповідь, зберігаючи водночас узгоджений стан сесії.
 
-В OpenClaw цикл — це один серіалізований запуск на сесію, який створює події життєвого циклу та потокові події,
-поки модель думає, викликає інструменти й передає в потоці вихідні дані. У цьому документі пояснюється, як цей
-автентичний цикл з’єднано наскрізно.
+У OpenClaw цикл — це один серіалізований запуск на сесію, який генерує події життєвого циклу та потокові події,
+поки модель міркує, викликає інструменти й передає вихідні дані потоком. У цьому документі пояснюється, як цей
+автентичний цикл з’єднаний наскрізно.
 
 ## Точки входу
 
@@ -29,148 +30,157 @@ x-i18n:
 
 ## Як це працює (на високому рівні)
 
-1. RPC `agent` перевіряє параметри, визначає сесію (`sessionKey/sessionId`), зберігає метадані сесії та відразу повертає `{ runId, acceptedAt }`.
+1. RPC `agent` перевіряє параметри, визначає сесію (`sessionKey/sessionId`), зберігає метадані сесії та одразу повертає `{ runId, acceptedAt }`.
 2. `agentCommand` запускає агента:
-   - визначає типові значення model + thinking/verbose/trace
+   - визначає модель + типові значення thinking/verbose/trace
    - завантажує знімок Skills
-   - викликає `runEmbeddedPiAgent` (середовище виконання pi-agent-core)
-   - створює **lifecycle end/error**, якщо вбудований цикл цього не створив
+   - викликає `runEmbeddedPiAgent` (runtime pi-agent-core)
+   - генерує **завершення/помилку життєвого циклу**, якщо вбудований цикл сам цього не згенерував
 3. `runEmbeddedPiAgent`:
-   - серіалізує запуски через черги для кожної сесії та глобальну чергу
-   - визначає профіль model + auth і будує pi-сесію
-   - підписується на події pi та передає assistant/tool deltas у потоці
-   - примусово застосовує timeout -> перериває запуск, якщо його перевищено
-   - повертає корисні навантаження та метадані usage
+   - серіалізує запуски через черги на рівні сесії та глобальні черги
+   - визначає модель + профіль автентифікації та будує pi-сесію
+   - підписується на події pi та передає потоком дельти помічника/інструментів
+   - примусово застосовує тайм-аут -> перериває запуск, якщо його перевищено
+   - повертає корисні навантаження та метадані використання
 4. `subscribeEmbeddedPiSession` з’єднує події pi-agent-core з потоком OpenClaw `agent`:
    - події інструментів => `stream: "tool"`
-   - assistant deltas => `stream: "assistant"`
+   - дельти помічника => `stream: "assistant"`
    - події життєвого циклу => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`)
 5. `agent.wait` використовує `waitForAgentRun`:
-   - чекає на **lifecycle end/error** для `runId`
+   - очікує на **завершення/помилку життєвого циклу** для `runId`
    - повертає `{ status: ok|error|timeout, startedAt, endedAt, error? }`
 
 ## Черги + паралельність
 
-- Запуски серіалізуються для кожного ключа сесії (доріжка сесії) та, за потреби, через глобальну доріжку.
-- Це запобігає конфліктам інструментів/сесій і підтримує узгодженість історії сесії.
-- Канали обміну повідомленнями можуть вибирати режими черги (collect/steer/followup), які подаються в цю систему доріжок.
+- Запуски серіалізуються для кожного ключа сесії (доріжка сесії) і, за потреби, також через глобальну доріжку.
+- Це запобігає гонкам інструментів/сесій і підтримує узгодженість історії сесії.
+- Канали повідомлень можуть вибирати режими черги (collect/steer/followup), які подаються в цю систему доріжок.
   Див. [Черга команд](/uk/concepts/queue).
+- Записи транскриптів також захищені блокуванням запису сесії у файлі сесії. Це блокування
+  враховує процеси та базується на файлі, тому воно виявляє авторів запису, які обходять внутрішньопроцесну чергу або надходять з
+  іншого процесу.
+- Блокування запису сесії типово не є реентерабельними. Якщо допоміжний компонент навмисно вкладає отримання
+  того самого блокування, зберігаючи одного логічного автора запису, він має явно ввімкнути це через
+  `allowReentrant: true`.
 
 ## Підготовка сесії + робочого простору
 
-- Робочий простір визначається та створюється; ізольовані запуски можуть перенаправлятися до кореня ізольованого робочого простору.
-- Skills завантажуються (або повторно використовуються зі знімка) та впроваджуються в env і prompt.
-- Bootstrap/context файли визначаються та впроваджуються у звіт системного prompt.
-- Отримується блокування запису сесії; `SessionManager` відкривається та підготовлюється до потокової передачі.
+- Робочий простір визначається та створюється; у sandboxed-запусках він може бути перенаправлений до кореня sandboxed-робочого простору.
+- Skills завантажуються (або повторно використовуються зі знімка) і впроваджуються в env та prompt.
+- Bootstrap/context-файли визначаються та впроваджуються у звіт системного prompt.
+- Отримується блокування запису сесії; `SessionManager` відкривається та готується до потокової передачі. Будь-який
+  пізніший шлях переписування транскрипту, Compaction або обрізання має отримати те саме блокування перед відкриттям або
+  зміненням файла транскрипту.
 
 ## Збирання prompt + системний prompt
 
-- Системний prompt будується з базового prompt OpenClaw, prompt Skills, bootstrap-контексту та перевизначень для конкретного запуску.
-- Застосовуються обмеження, специфічні для моделі, і резервні токени для Compaction.
-- Див. [Системний prompt](/uk/concepts/system-prompt), щоб побачити, що бачить модель.
+- Системний prompt будується з базового prompt OpenClaw, prompt Skills, bootstrap-контексту та перевизначень для окремого запуску.
+- Застосовуються обмеження, специфічні для моделі, та резервні токени для Compaction.
+- Див. [Системний prompt](/uk/concepts/system-prompt), щоб дізнатися, що бачить модель.
 
 ## Точки перехоплення (де можна втрутитися)
 
 OpenClaw має дві системи хуків:
 
-- **Внутрішні хуки** (хуки Gateway): скрипти на основі подій для команд і подій життєвого циклу.
-- **Plugin hooks**: точки розширення всередині циклу агента/інструментів і конвеєра gateway.
+- **Внутрішні хуки** (хуки Gateway): скрипти, керовані подіями, для команд і подій життєвого циклу.
+- **Хуки Plugin**: точки розширення всередині життєвого циклу агента/інструментів і конвеєра gateway.
 
 ### Внутрішні хуки (хуки Gateway)
 
-- **`agent:bootstrap`**: запускається під час побудови bootstrap-файлів до того, як буде фіналізовано системний prompt.
+- **`agent:bootstrap`**: запускається під час побудови bootstrap-файлів до остаточного формування системного prompt.
   Використовуйте це, щоб додавати/видаляти bootstrap-файли контексту.
-- **Хуки команд**: `/new`, `/reset`, `/stop` та інші події команд (див. документ про Hooks).
+- **Хуки команд**: `/new`, `/reset`, `/stop` та інші події команд (див. документ Hooks).
 
-Див. [Hooks](/uk/automation/hooks), щоб переглянути налаштування та приклади.
+Див. [Hooks](/uk/automation/hooks), щоб знайти налаштування та приклади.
 
-### Plugin hooks (життєвий цикл агента + gateway)
+### Хуки Plugin (життєвий цикл агента + gateway)
 
-Вони запускаються всередині циклу агента або конвеєра gateway:
+Вони виконуються всередині циклу агента або конвеєра gateway:
 
 - **`before_model_resolve`**: запускається до сесії (без `messages`), щоб детерміновано перевизначити provider/model до визначення моделі.
-- **`before_prompt_build`**: запускається після завантаження сесії (з `messages`), щоб впровадити `prependContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext` до надсилання prompt. Використовуйте `prependContext` для динамічного тексту на кожен хід, а поля системного контексту — для стабільних вказівок, які мають перебувати в просторі системного prompt.
-- **`before_agent_start`**: застарілий хук сумісності, який може запускатися в будь-якій фазі; віддавайте перевагу наведеним вище явним хукам.
-- **`before_agent_reply`**: запускається після вбудованих дій і перед викликом LLM, дозволяючи Plugin перехопити хід і повернути синтетичну відповідь або повністю приглушити хід.
+- **`before_prompt_build`**: запускається після завантаження сесії (з `messages`), щоб впровадити `prependContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext` перед надсиланням prompt. Використовуйте `prependContext` для динамічного тексту на поточний хід, а поля системного контексту — для стабільних настанов, які мають розташовуватися в просторі системного prompt.
+- **`before_agent_start`**: застарілий хук сумісності, який може запускатися в будь-якій фазі; віддавайте перевагу явним хукам вище.
+- **`before_agent_reply`**: запускається після вбудованих дій і перед викликом LLM, дозволяючи Plugin перехопити хід і повернути синтетичну відповідь або повністю заглушити хід.
 - **`agent_end`**: дає змогу перевірити фінальний список повідомлень і метадані запуску після завершення.
-- **`before_compaction` / `after_compaction`**: дає змогу спостерігати або анотувати цикли Compaction.
-- **`before_tool_call` / `after_tool_call`**: перехоплює параметри/результати інструментів.
-- **`before_install`**: дає змогу перевірити результати вбудованого сканування й за потреби заблокувати встановлення Skill або Plugin.
-- **`tool_result_persist`**: синхронно трансформує результати інструментів перед тим, як вони будуть записані до транскрипту сесії.
-- **`message_received` / `message_sending` / `message_sent`**: вхідні та вихідні хуки повідомлень.
+- **`before_compaction` / `after_compaction`**: дають змогу спостерігати за циклами Compaction або додавати до них анотації.
+- **`before_tool_call` / `after_tool_call`**: перехоплюють параметри/результати інструментів.
+- **`before_install`**: перевіряє результати вбудованого сканування і за потреби блокує встановлення skill або Plugin.
+- **`tool_result_persist`**: синхронно перетворює результати інструментів перед їх записом до транскрипту сесії.
+- **`message_received` / `message_sending` / `message_sent`**: хуки вхідних і вихідних повідомлень.
 - **`session_start` / `session_end`**: межі життєвого циклу сесії.
 - **`gateway_start` / `gateway_stop`**: події життєвого циклу gateway.
 
-Правила рішень хуків для вихідних даних/запобіжників інструментів:
+Правила ухвалення рішень у хуках для вихідних повідомлень/захисту інструментів:
 
-- `before_tool_call`: `{ block: true }` є термінальним і зупиняє обробники з нижчим пріоритетом.
-- `before_tool_call`: `{ block: false }` не виконує жодної дії та не скасовує попереднє блокування.
-- `before_install`: `{ block: true }` є термінальним і зупиняє обробники з нижчим пріоритетом.
-- `before_install`: `{ block: false }` не виконує жодної дії та не скасовує попереднє блокування.
-- `message_sending`: `{ cancel: true }` є термінальним і зупиняє обробники з нижчим пріоритетом.
-- `message_sending`: `{ cancel: false }` не виконує жодної дії та не скасовує попереднє скасування.
+- `before_tool_call`: `{ block: true }` є фінальним і зупиняє обробники з нижчим пріоритетом.
+- `before_tool_call`: `{ block: false }` нічого не робить і не скасовує попереднє блокування.
+- `before_install`: `{ block: true }` є фінальним і зупиняє обробники з нижчим пріоритетом.
+- `before_install`: `{ block: false }` нічого не робить і не скасовує попереднє блокування.
+- `message_sending`: `{ cancel: true }` є фінальним і зупиняє обробники з нижчим пріоритетом.
+- `message_sending`: `{ cancel: false }` нічого не робить і не скасовує попереднє скасування.
 
-Див. [Plugin hooks](/uk/plugins/architecture#provider-runtime-hooks), щоб переглянути API хуків і деталі реєстрації.
+Див. [Хуки Plugin](/uk/plugins/architecture#provider-runtime-hooks), щоб знайти API хуків і подробиці реєстрації.
 
 ## Потокова передача + часткові відповіді
 
-- Assistant deltas передаються в потоці з pi-agent-core і створюються як події `assistant`.
-- Потокова передача блоків може створювати часткові відповіді або на `text_end`, або на `message_end`.
-- Потокова передача міркувань може створюватися як окремий потік або як блокові відповіді.
-- Див. [Потокова передача](/uk/concepts/streaming), щоб дізнатися про розбиття на частини та поведінку блокових відповідей.
+- Дельти помічника передаються потоком з pi-agent-core і генеруються як події `assistant`.
+- Потокова передача блоків може генерувати часткові відповіді або на `text_end`, або на `message_end`.
+- Потокова передача міркувань може генеруватися як окремий потік або як відповіді блоками.
+- Див. [Streaming](/uk/concepts/streaming), щоб дізнатися про фрагментацію та поведінку блокових відповідей.
 
 ## Виконання інструментів + інструменти повідомлень
 
-- Події початку/оновлення/завершення інструментів створюються в потоці `tool`.
-- Результати інструментів очищуються з урахуванням обмежень розміру та корисних навантажень зображень перед логуванням/створенням подій.
-- Надсилання інструментів повідомлень відстежуються, щоб пригнічувати дубльовані підтвердження assistant.
+- Події початку/оновлення/завершення інструмента генеруються в потоці `tool`.
+- Результати інструментів очищуються з урахуванням розміру та зображень перед логуванням/генерацією.
+- Надсилання інструментами повідомлень відстежується, щоб уникнути дубльованих підтверджень від помічника.
 
-## Формування відповіді + пригнічення
+## Формування відповіді + придушення
 
 - Фінальні корисні навантаження збираються з:
-  - тексту assistant (та, за потреби, reasoning)
+  - тексту помічника (і, за потреби, міркувань)
   - вбудованих зведень інструментів (коли verbose увімкнено + дозволено)
-  - тексту помилки assistant, якщо модель повернула помилку
-- Точний маркер безмовності `NO_REPLY` / `no_reply` відфільтровується з вихідних
+  - тексту помилки помічника, якщо модель завершується з помилкою
+- Точний тихий токен `NO_REPLY` / `no_reply` відфільтровується з вихідних
   корисних навантажень.
 - Дублікати інструментів повідомлень видаляються з фінального списку корисних навантажень.
-- Якщо не лишилося жодних придатних до відображення корисних навантажень і інструмент повернув помилку, створюється резервна відповідь про помилку інструмента
-  (якщо тільки інструмент повідомлень ще не надіслав видиму для користувача відповідь).
+- Якщо не залишається придатних до рендерингу корисних навантажень і інструмент завершився помилкою, генерується
+  резервна відповідь про помилку інструмента
+  (якщо тільки інструмент повідомлень ще не надіслав видиму користувачеві відповідь).
 
 ## Compaction + повторні спроби
 
-- Автоматичний Compaction створює події потоку `compaction` і може ініціювати повторну спробу.
-- Під час повторної спроби буфери в пам’яті та зведення інструментів скидаються, щоб уникнути дубльованого виводу.
-- Див. [Compaction](/uk/concepts/compaction), щоб ознайомитися з конвеєром Compaction.
+- Автоматичний Compaction генерує події потоку `compaction` і може спричинити повторну спробу.
+- Під час повторної спроби буфери в пам’яті та зведення інструментів скидаються, щоб уникнути дублювання вихідних даних.
+- Див. [Compaction](/uk/concepts/compaction), щоб дізнатися про конвеєр Compaction.
 
 ## Потоки подій (зараз)
 
-- `lifecycle`: створюється `subscribeEmbeddedPiSession` (і як резервний варіант — `agentCommand`)
-- `assistant`: потокові deltas з pi-agent-core
-- `tool`: потокові події інструментів із pi-agent-core
+- `lifecycle`: генерується `subscribeEmbeddedPiSession` (і як резервний варіант — `agentCommand`)
+- `assistant`: потокові дельти з pi-agent-core
+- `tool`: потокові події інструментів з pi-agent-core
 
-## Обробка чат-каналу
+## Обробка chat-каналу
 
-- Assistant deltas буферизуються в чат-повідомлення `delta`.
-- Чат `final` створюється на **lifecycle end/error**.
+- Дельти помічника буферизуються в повідомлення chat `delta`.
+- Chat `final` генерується під час **завершення/помилки життєвого циклу**.
 
 ## Тайм-аути
 
-- Типове значення `agent.wait`: 30 с (лише очікування). Параметр `timeoutMs` його перевизначає.
-- Час виконання агента: типове значення `agents.defaults.timeoutSeconds` — 172800 с (48 годин); застосовується в таймері переривання `runEmbeddedPiAgent`.
-- Тайм-аут бездіяльності LLM: `agents.defaults.llm.idleTimeoutSeconds` перериває запит до моделі, якщо жодні фрагменти відповіді не надходять до завершення вікна бездіяльності. Установіть його явно для повільних локальних моделей або provider-ів reasoning/tool-call; установіть 0, щоб вимкнути. Якщо його не задано, OpenClaw використовує `agents.defaults.timeoutSeconds`, якщо його налаштовано, інакше 120 с. Запуски, ініційовані Cron, без явного тайм-ауту LLM або агента вимикають watchdog бездіяльності й покладаються на зовнішній тайм-аут Cron.
+- Типове значення `agent.wait`: 30 с (лише очікування). Параметр `timeoutMs` перевизначає його.
+- Runtime агента: типове значення `agents.defaults.timeoutSeconds` — 172800 с (48 годин); застосовується в таймері переривання `runEmbeddedPiAgent`.
+- Тайм-аут бездіяльності LLM: `agents.defaults.llm.idleTimeoutSeconds` перериває запит до моделі, якщо до завершення вікна бездіяльності не надходять жодні фрагменти відповіді. Установіть його явно для повільних локальних моделей або provider-ів міркувань/виклику інструментів; установіть 0, щоб вимкнути. Якщо його не встановлено, OpenClaw використовує `agents.defaults.timeoutSeconds`, якщо його налаштовано, інакше — 120 с. Для запусків, ініційованих Cron, без явного тайм-ауту LLM або агента watchdog бездіяльності вимикається, а керування передається зовнішньому тайм-ауту Cron.
 
-## Де все може завершитися завчасно
+## Де все може завершитися раніше
 
 - Тайм-аут агента (переривання)
 - AbortSignal (скасування)
-- Від’єднання Gateway або тайм-аут RPC
+- Відключення Gateway або тайм-аут RPC
 - Тайм-аут `agent.wait` (лише очікування, не зупиняє агента)
 
-## Пов’язані теми
+## Пов’язане
 
 - [Інструменти](/uk/tools) — доступні інструменти агента
-- [Hooks](/uk/automation/hooks) — скрипти на основі подій, що спрацьовують на подіях життєвого циклу агента
-- [Compaction](/uk/concepts/compaction) — як узагальнюються довгі розмови
-- [Погодження Exec](/uk/tools/exec-approvals) — бар’єри погодження для shell-команд
-- [Thinking](/uk/tools/thinking) — налаштування рівня thinking/reasoning
+- [Hooks](/uk/automation/hooks) — скрипти, керовані подіями, які запускаються подіями життєвого циклу агента
+- [Compaction](/uk/concepts/compaction) — як підсумовуються довгі розмови
+- [Підтвердження Exec](/uk/tools/exec-approvals) — бар’єри підтвердження для команд оболонки
+- [Thinking](/uk/tools/thinking) — налаштування рівня thinking/міркувань