# Terminal в Kavor: выполнение, видимое человеку и агенту Terminal — настоящий shell на Canvas. Вы продолжаете вводить команды, следить за logs и использовать знакомые инструменты; Kavor добавляет вокруг сессии контекст, наблюдаемость и совместную работу. Цель не в том, чтобы спрятать выполнение за кнопкой, а в том, чтобы человек и CodingAgent работали в одной видимой среде, каждый в ясных границах. ## Чем владеет Terminal У каждого Terminal своя сессия, shell и история экрана, сохранённая Node. Несколько Terminals полезны при разных обязанностях: приложение, тесты, база данных, logs или уже открытая вами удалённая машина. Процесс остаётся процессом shell. Kavor не превращает показанный текст в успех, каждую команду — в сохранённую задачу, и не считает инструмент завершённым только потому, что он напечатал оптимистичное сообщение. ## Что он делает сам Без Connections Terminal уже держит shell внутри Workspace и позволяет не прерывать поток переключением на внешние окна. Можно выполнять интерактивные команды, наблюдать долгие процессы и сохранять разные сессии на одном Canvas. Connections добавляют участников и канонические источники, не заменяя shell. ## Что он получает в графе Terminal поддерживает четыре прямые пары: | Connection | Что она добавляет | | --- | --- | | **Terminal + CodingAgent** | Агент может выполнять связанные команды, отслеживать процесс, читать экран или историю и прерывать выполнение при наличии разрешения. Может содержать `terminal_read_only`. | | **Terminal + File** | Экспортирует канонический абсолютный путь File в выбранную вами переменную окружения. | | **Terminal + Specification** | Экспортирует канонический абсолютный путь Markdown Specification через переменную окружения. | | **Terminal + Trigger** | Выбирает активную сессию прямой целью команды, запланированной в Schedule. | CodingAgent не обязан быть напрямую подключён к Terminal, если оба уже находятся в одном достижимом компоненте. Но именно прямая Connection позволяет `terminal_read_only` явно ограничить агента наблюдением. ## Помощь без борьбы за клавиатуру Terminal — общая поверхность с приоритетом человека. CodingAgent не должен вставлять команду поверх текста, который вы ещё набираете. Если ввод небезопасен, операция ждёт или возвращает условие для обработки, не повреждая строку. Для работы, начатой агентом, Kavor связывает команду с наблюдением. Агент может ждать результат, отменить соответствующее выполнение или прочитать видимое состояние. В существующей сессии он выбирает подходящее представление: текущий экран, ограниченный tail или полный buffer. Экран отвечает «что сейчас видит человек?». Tail помогает с недавними logs. Полный buffer нужен расследованию, которому действительно важна история, без автоматического dump всего контекста при каждом действии. ## Используйте Files и Specifications без копирования путей Connections с File или Specification принимают имя переменной окружения. Её значение — канонический абсолютный путь источника, а не содержимое. ```sh node "$IMPORT_SCRIPT" --input "$SOURCE_FILE" ``` ```sh markdownlint "$SPECIFICATION_FILE" ``` Переменные применяются при запуске сессии Terminal. Если Connection или её параметр изменились при открытом shell, новая настройка войдёт в среду после перезапуска этой сессии. `TERM` и `COLORTERM` зарезервированы эмулятором. Используйте имена, выражающие ответственность: `CHECK_SQL`, `SPECIFICATION_FILE`, `IMPORT_SCRIPT`. Общее имя `FILE` теряет смысл по мере роста графа. ## Три полезные схемы ### Реализация с видимыми свидетельствами Соедините Specification, CodingAgent и Terminal. Агент выполняет только нужные проверки, сохраняет необходимый output и регистрирует результат как output. Вы наблюдаете тот же shell и можете вмешаться. ### Диагностика работающего приложения Оставьте приложение в одном Terminal, тесты или запросы — в другом. Достижимый CodingAgent читает нужный экран или tail, формулирует гипотезу и выполняет ограниченную команду. Logs остаются видимыми, а расследование не становится чёрным ящиком. ### Контролируемая удалённая операция Вы открываете SSH-сессию в Terminal. CodingAgent может интерпретировать состояние и предлагать или выполнять команды при наличии разрешения. Kavor не становится удалённым сервисом: credentials, соединение, shell и надзор остаются в открытой вами сессии. ## Практический граф ```text Specification — Maintainer — Reviewer │ Terminal │ File: check.sql ``` Maintainer использует Specification как контракт, File как явный источник, Terminal для проверки. Reviewer оценивает результат и свидетельства. Connection File + Terminal предоставляет `CHECK_SQL`, поэтому путь не нужно копировать. ## Более точный начальный запрос > Диагностируй сбой, используя только достижимый контекст. Сначала прочитай текущий экран Terminal. Выполняй по одной > команде, объясняй, что она различает, и сохраняй output для Reviewer. Не прерывай запущенный мной процесс и > остановись до любого разрушительного действия или расширения области Specification. Для мониторинга: > Отслеживай только необходимый tail этого Terminal. Сообщи о новом свидетельстве; не считай отсутствие новых строк > успехом и не оставляй watcher, запущенный только для расследования, после завершения. ## Guardrail только для чтения `terminal_read_only` сохраняет просмотр и блокирует операции, меняющие сессию, процесс или ввод через эту прямую Connection. Он подходит Reviewer, которому нужны свидетельства, но не разрешено выполнять исправления. Guardrail принадлежит паре. Он не делает весь Terminal глобально доступным только для чтения и не заменяет разрешения операционной системы. ## Важные ограничения - Output Terminal не доказывает автоматически, что внешний эффект произошёл правильно. - CodingAgent не должен вмешиваться в незавершённый ввод человека. - Разрушительные команды всё равно требуют точной области и подходящего разрешения. - Переменная от Connection содержит путь, а не содержимое или secret. - Изменения переменных требуют перезапуска сессии Terminal. - Schedule доставляет только активной сессии и не восстанавливает автоматически команды, пропущенные при закрытом Kavor. - Процесс, запущенный для расследования, нужно остановить, если он не должен оставаться для человека. - Несколько Terminals полезны для реальных обязанностей; бессмысленное дублирование дробит операционное состояние. ## Перед делегированием команды Проверьте: выбран ли правильный Terminal; нет ли незавершённого ввода человека; ограничена и обратима ли команда; понимает ли агент, какой output является свидетельством; нужен экран, tail или полная история; понятны ли имена переменных Files и Specifications; должен ли Reviewer работать под `terminal_read_only`; ясно ли, когда остановиться, ждать или спросить ваше решение. Terminal приносит пользу графу, когда выполнение остаётся реальным, контекст — явным, а надзор не исчезает. Откройте [матрицу Connections](./connections.md), узнайте, [как CodingAgents видят и строят Canvas](./coding-agents-and-canvas.md), или настройте [Schedule для команд и prompts](./schedule.md).