Повод: у terminal API есть backend, но не хватает языка для подключения

В начале сентября в экосистеме DeepSeek Harness появился архитектурный запрос: terminal backend должен получать параметры каждого конкретного запуска. На поверхности это выглядит как деталь API. На практике от такого контракта зависит, насколько прозрачно агент можно подключить к staging-серверу, bastion host, GPU-машине или уже работающей удалённой shell-сессии.

Обсуждение нельзя принимать за результат разработки. Открытая документация Harness подтверждает модульную terminal-подсистему и persistent PTY-сессии. Но доступные материалы не подтверждают, что per-spawn parameters приняты в основной код, вошли в релиз или используются официальным SSH backend. Корректная формулировка на момент проверки: это архитектурный запрос, а не анонс готовой возможности.

В терминологии Harness backend является сменяемой реализацией терминала. Один backend может запускать локальный shell, другой потенциально способен открывать SSH-подключение, третий работать с изолированным удалённым окружением. Терминалы регистрируются как capability, а агент использует операции открытия, передачи ввода, чтения вывода, отправки сигнала, закрытия и просмотра сессий.

Проблема возникает именно при создании сессии. Доступный контракт открытия терминала описывает тип backend, необязательное имя сессии и стартовый рабочий каталог. Локальному Bash этого обычно достаточно. Для SSH недостаточно: слово «ssh» говорит о транспорте, но не объясняет, к какой машине нужно подключиться, через какой разрешённый профиль, нужен ли jump host, требуется новая оболочка или attach к уже существующей.

В открытой документации нет подтверждения универсального поля для параметров отдельного spawn-вызова. Поэтому автор внешнего SSH backend вынужден переносить часть смысла подключения в глобальную конфигурацию, имя backend, имя сессии, рабочий каталог либо отдельный инструмент. Чем больше окружений и правил доступа, тем дороже такая неявность для поддержки и аудита.

  • Подтверждено: Harness поддерживает подключаемые terminal backend и операции над сессиями.
  • Не подтверждено: предложение о per-spawn parameters принято в main, включено в релиз или реализовано в официальном SSH backend.
  • Вероятное следствие текущего контракта: конкретное удалённое подключение сложнее выбрать непосредственно при открытии терминала.

Что Harness уже умеет: persistent PTY внутри живого процесса

Persistent PTY-сессия представляет собой псевдотерминал, сохраняющий состояние между отдельными вызовами инструментов. Агенту не нужно заново запускать shell после каждой команды: могут сохраняться текущая директория, экспортированные переменные, активированное виртуальное окружение и состояние интерактивной программы. Terminal-подсистема связывает сессию с владельцем-агентом и предусматривает её закрытие с очисткой ресурсов.

Это важная основа агентных процессов. Без сохранения состояния цепочка «перейти в каталог, активировать окружение, запустить тесты, прочитать лог, исправить файл» распадается на независимые команды. Им приходится каждый раз восстанавливать контекст. В документации Python SDK указано, что повторное использование одного Harness и одного session_id сохраняет bash-процесс, cwd, переменные и shell-функции.

Однако persistent не означает неуничтожаемый или долгоживущий. Документация штатного terminal-bash backend прямо фиксирует границу: сессии не переживают завершение процесса Harness. Состояние существует в пределах работающего рантайма, но не гарантированно восстанавливается после рестарта сервиса, падения процесса или сетевого разрыва.

Есть и операционные ограничения. Терминальный вывод хранится в ограниченном объёме: в model-facing слое полный результат по умолчанию ограничен 256 KiB, хотя лимит настраивается. Полноэкранные terminal UI также не относятся к целевым сценариям штатного Bash backend. Эти свойства API нужно учитывать при проектировании удалённой интеграции и диагностике длинных задач.

  • Persistent в Harness означает сохранение shell-состояния между tool calls, пока работает процесс Harness.
  • Persistent не означает автоматическое сохранение после рестарта Harness или разрыва SSH-соединения.
  • Для удалённой надёжности backend потребуется отдельная логика reconnect или attach: это инженерный вывод из ограничений штатного backend.
Цитата в переводе

«Сессии не переживают завершение процесса Harness.»

DeepSeek Harnessдокументация пакета @deepseek-ai/dsh-terminal-bash

Почему SSH нельзя свести к одному типу backend

В локальной среде запрос уровня terminal_open отвечает на сравнительно простой вопрос: какой терминал открыть и из какого каталога начать. В удалённой среде данных больше. Команде может понадобиться выбрать профиль staging, конкретный bastion, целевую VM, путь в удалённой файловой системе, способ аутентификации, режим attach к tmux, тайм-аут и политику повторного соединения.

Эти сведения относятся не к классу backend в целом, а к отдельному запуску. Один и тот же SSH backend может быть допустим для нескольких сред, однако правила, хосты и режимы работы у них различаются. Тип backend отвечает на вопрос «какая реализация», а профиль подключения на вопрос «в какую среду и по каким правилам».

Если backend не получает структурированный per-spawn payload, возникают обходные схемы. Можно зарегистрировать ssh-stage, ssh-prod и ssh-gpu; использовать имя сессии как ключ профиля; читать настройки из конфигурации плагина; прятать маршрут подключения в cwd; вынести его в отдельный model-facing tool. В небольшом проекте каждый вариант может работать.

Проблема обходных схем в том, что они смешивают пользовательский смысл, маршрутизацию, политику доступа и жизненный цикл соединения. Это усложняет аудит, тестирование и перенос конфигурации между средами. Сам новый аргумент API не решит задачу SSH: он не создаст туннель, не проверит права, не сохранит ключи и не восстановит удалённый процесс. Он лишь может устранить разрыв, при котором backend знает свой тип и локальный контекст, но не получает декларативного описания конкретного подключения.

  • Кодирование профиля в name или cwd может работать, но делает контракт неявным.
  • Параметры запуска не должны превращаться в канал передачи паролей, SSH-ключей и токенов.
  • Выбор цели, правила доступа и жизненный цикл соединения требуют разных уровней проектирования.

Каким мог бы быть безопасный контракт запуска

Если идею примут, практичным вариантом была бы передача backend-specific параметров при создании сессии без превращения интерфейса в неограниченный словарь. У SSH backend могла бы быть отдельная схема: идентификатор разрешённого профиля, удалённый рабочий каталог, режим create или attach и ограниченный набор настроек соединения. У локального shell была бы более короткая схема. Это предложение редакции, а не опубликованный план DeepSeek.

Ключевой принцип такого дизайна: credential reference вместо секрета. Модель или вызывающий код могут передать connectionProfileId, но не приватный ключ, пароль или токен. Затем backend получает разрешённый профиль из защищённого хранилища и проверяет policy: допустимы ли этот хост, пользователь, путь и режим запуска. Такой подход снижает вероятность попадания чувствительных данных в аргументы инструмента, логи и историю событий.

В Harness есть подсистема сессий с долговечной событийной моделью. Поэтому параметры нельзя считать косметическим изменением TypeScript-типа. Разработчикам необходимо заранее определить, какие сведения о подключении сохраняются в событиях, маскируются, хешируются или вообще не попадают в журнал. Иначе удобный API расширит поверхность утечек данных о внутренней инфраструктуре.

Строго типизированные схемы полезны и для обратной совместимости. Неограниченный Record<string, unknown> даёт внешним backend свободу, но затрудняет проверку входа. Реестр схем по backend.type позволил бы валидировать параметры до запуска, формировать точную tool schema и отклонять значения, не соответствующие policy. Наличие такого механизма в доступной документации не подтверждено.

  • Безопаснее передавать ссылку на профиль, а не SSH-ключ или пароль.
  • Нужно разделять target, lifecycle и policy: куда подключаться, как создавать или восстанавливать сессию и что разрешено агенту.
  • Схема параметров должна валидироваться для конкретного backend, а не быть бесконтрольным набором полей.

Удалённая сессия и устойчивая сессия: разные обещания

Даже удачный spawn API не делает SSH-сессию устойчивой. Сетевой обрыв способен закрыть канал между Harness и сервером, процесс Harness может перезапуститься, удалённую VM могут заменить, а shell завершиться по тайм-ауту или политике сервера. В каждом случае backend должен явно определить, что считать восстановлением.

Возможны разные варианты: подключение к новому shell, попытка attach к tmux, проверка идентичности удалённого процесса или сообщение агенту об утрате контекста. Для задач из десятков шагов это принципиально. Агент может начать сборку, оставить тестовый процесс, перейти к анализу лога, а затем вернуться к тому же терминалу.

При обрыве опасно молча создать новый shell и выдать его за прежний. Текущая директория, PID, блокировки, активный deployment или состояние REPL к этому моменту могут не совпадать. Надёжная интеграция должна отличать восстановленный канал от новой сессии и передавать это различие вызывающей стороне.

Практическая стратегия обычно включает серверный мультиплексор либо daemon для сохранения процесса, keepalive для обнаружения обрыва, ограниченные повторы подключения, явный идентификатор удалённой сессии и проверку состояния после attach. Конкретный набор зависит от модели угроз, сетевой топологии и критичности задач. Универсальная готовая реализация такого протокола в документации DeepSeek Harness не описана.

  • Reconnect к серверу не равен восстановлению прежнего удалённого процесса.
  • Attach к tmux может сохранить shell-контекст, но требует очистки, идентификации и контроля доступа.
  • Backend должен явно сообщать, создана новая сессия или продолжена старая.

Сообщество уже проверяет удалённые execution environments

Интерес к удалённому исполнению проявляется не только в гипотетическом SSH backend. В GitHub Discussion от 31 августа разработчик под ником harryopo представил сторонний плагин dsh-remote-ide. По заявлению автора, плагин перенаправляет filesystem и subprocess capabilities в SSH-backed реализацию, использует SSH channels для exec, SFTP и PTY, а также поддерживает pooling, keepalive, восстановление соединения и jump hosts.

Это сообщение разработчика стороннего проекта, а не анонс DeepSeek и не независимый тест надёжности. Автор также заявил о 100 unit-тестах и 25 E2E-тестах с реальным SSH-сервером на openEuler. Эти цифры показывают, что тема вышла за пределы концепта, но не измеряют безопасность, поведение при разделении сети, корректность очистки процессов или восстановление после рестарта.

Пример важен архитектурно. Вместо узкого расширения терминала сторонняя интеграция затрагивает filesystem и subprocess. Документация Harness описывает эти providers в едином execution world: удалённый provider потенциально переносит в одну среду Bash, PTY, доступ к файлам и LSP-инструменты.

Поэтому одним командам достаточно SSH terminal backend, а другим больше подходит полноценный удалённый execution provider. Terminal backend удобен, когда к существующей архитектуре нужно добавить управляемую оболочку. Execution-world provider уместнее, когда агент должен целостно видеть удалённую среду, запускать процессы, читать и менять файлы, применять инструменты анализа к одному дереву проекта. Выбор определяется границами доверия и местом, где реально находится рабочее состояние.

  • dsh-remote-ide является сторонним примером, а не официальной функцией DeepSeek Harness.
  • Заявленные автором тесты нельзя считать независимой оценкой production-готовности.
  • Архитектура Harness допускает расширение не только terminal backend, но и более широкого execution world.
Цитата в переводе

«Установка на сервере не требуется. Нет удалённого агента наподобие vscode-server и нет демона.»

harryopoавтор GitHub Discussion и разработчик стороннего плагина dsh-remote-ide

Безопасность: удалённый shell меняет место риска, но не отменяет его

Перенос агента с локального shell на SSH не делает операции безопасными автоматически. Полномочия переносятся в учётную запись, ключ и policy удалённой среды. Если аккаунт может читать production-логи, перезапускать сервисы или менять инфраструктурный код, агент действует в пределах тех же прав. Задача backend не только открыть канал, но и сделать границы разрешений наблюдаемыми и проверяемыми.

Штатный terminal-bash backend предупреждает, что режим danger-full-access следует использовать только в disposable checkout или контейнере: процессы shell и редактора получают доступ ко всему, что доступно рантайму. Для SSH смысл предупреждения сохраняется, хотя объект доступа меняется. Удалённая среда должна быть отдельным policy domain: staging нельзя маскировать под production-профиль, а production не следует открывать тем же набором неявных настроек.

Минимальный прагматичный набор для production включает allowlist хостов, отдельные профили окружений, короткоживущие учётные данные там, где это возможно, запись операций, подтверждение разрушительных команд и ограничение доступных путей. Это не заявленные встроенные функции Harness: их должна обеспечивать интеграция и окружающая платформа.

Особенно нежелательно передавать секреты через prompt, строки shell-команд или «магические» YAML-переменные, смысл которых известен только автору плагина. Их сложно отозвать, легко случайно записать в вывод и трудно отличить от безобидной конфигурации при аудите. Явный идентификатор профиля и отдельный слой секретов не устраняют все угрозы, но делают модель доступа понятнее.

  • SSH backend должен работать в рамках прав удалённой учётной записи, а не обходить их.
  • Логи и история сессии требуют отдельного контроля, если параметры содержат сведения о внутренней инфраструктуре.
  • Разделение staging и production должно быть политикой доступа, а не соглашением об именовании.

Что делать до появления возможного API

Во-первых, использовать существующие persistent terminal-сессии по назначению: для сохранения контекста между вызовами в живом процессе Harness. Это применимо к локальным задачам, тестам, интерактивным отладчикам и последовательным командам. Не следует обещать пользователям сохранение сессии после перезапуска рантайма, если backend отдельно не обеспечивает такую гарантию.

Во-вторых, при потребности в удалённой среде осознанно выбрать точку расширения. Для ограниченного сценария может хватить внешнего backend, открывающего SSH-shell. Если агенту нужен единый доступ к удалённым файлам, процессам и инструментам разработки, стоит изучать capability seams filesystem и subprocess, то есть строить удалённый execution world. Такой путь сложнее, но снижает риск, что терминал и файловая система агента окажутся в разных окружениях.

В-третьих, не скрывать критически важный выбор хоста в cwd или случайном имени сессии. Пока API не предоставляет нужный параметр, лучше создать явный слой профилей на стороне интеграции, документировать соответствие и проверять его policy. Это менее изящно, чем нативный schema-driven spawn, но безопаснее и понятнее неявной кодировки маршрута.

В-четвёртых, тестировать не только успешное подключение. Нужны сценарии с обрывом сети во время команды, остановкой Harness, потерей удалённой VM, повторным attach, зависшим процессом и закрытием владельца-агента. Для каждого случая команда должна понимать, какие процессы останутся на сервере, будет ли повтор команды идемпотентным и как оператор отличит продолжение старой сессии от начала новой.

  • Считайте текущую persistence локальной в пределах жизненного цикла работающего Harness.
  • Выбирайте terminal backend для оболочки, execution provider для целостной удалённой рабочей среды.
  • Проверяйте отказоустойчивость отдельно от функционального теста «SSH подключился».
  • Не передавайте ключи и пароли в модельную схему или текстовые команды.

Что это означает на практике

История с per-spawn parameters важна не предполагаемым размером изменения, а требованиями к зрелости агентной платформы. Когда агент выходит из локальной песочницы в удалённые среды, конфигурация становится частью модели безопасности и наблюдаемости.

DeepSeek Harness уже даёт основу в виде подключаемых terminal backend, persistent PTY-сессий и более широкой архитектуры execution world. Следующий шаг, если его выберут сообщество и проект, должен быть не очередным SSH-флагом, а чётким контрактом между профилем подключения, жизненным циклом сессии и политикой доступа.

Пока командам стоит использовать подтверждённые возможности, не выдавать persistence за отказоустойчивость и проектировать удалённое выполнение с расчётом на сетевой разрыв, рестарт и ошибочно настроенный доступ. В таких ситуациях исчезает конфигурационная магия и проявляется реальная инженерная архитектура.

  • Не называйте обсуждаемые per-spawn parameters реализованной функцией.
  • Используйте persistent PTY для состояния между tool calls, но не обещайте восстановление после рестарта процесса.
  • Для SSH передавайте разрешённый идентификатор профиля, а не секреты.
  • Разделяйте выбор удалённой цели, reconnect и attach, а также разграничение прав.
  • Если агенту нужны и удалённые файлы, и процессы, оценивайте execution-world подход, а не только SSH-терминал.

Источники

Практический чек-лист

Чек-лист: как спроектировать SSH-интеграцию для агентной среды

Этот чек-лист следует подготовить отдельным PDF-файлом downloads/deepseek-harness-ssh-checklist.pdf и добавить в лист Downloads. Он отделяет подтверждённые ограничения Harness от рекомендаций по проектированию интеграции.

Проверить статус возможностей

  • Зафиксировать, что per-spawn parameters в доступных материалах являются обсуждаемым запросом, а не подтверждённой функцией.
  • Не обещать сохранение terminal-сессии после завершения или рестарта процесса Harness.
  • Отделить возможности штатного terminal-bash backend от возможностей внешнего плагина.

Спроектировать подключение

  • Выбрать явный идентификатор разрешённого connection profile вместо кодирования цели в cwd или имени сессии.
  • Разделить данные о target, lifecycle и policy.
  • Не передавать ключи, пароли и токены через prompt, shell-команду или model-facing параметры.
  • Определить, нужен ли только SSH terminal backend или единый remote execution provider для файлов и процессов.

Проверить устойчивость и безопасность

  • Протестировать обрыв сети во время команды и повторное подключение.
  • Проверить поведение после остановки или рестарта Harness.
  • Проверить потерю удалённой VM, attach к существующему процессу и очистку зависших процессов.
  • Явно различать создание новой сессии и восстановление прежней.
  • Ограничить хосты и пути policy, разделить staging и production, вести наблюдаемые записи операций.

Вопросы и ответы

Реализованы ли per-spawn parameters в DeepSeek Harness?

Нет подтверждения, что обсуждаемый запрос принят в main, вошёл в релиз или реализован в официальном SSH backend. В доступных материалах речь идёт об архитектурном предложении.

Что сохраняет persistent PTY-сессия Harness?

В пределах работающего процесса Harness могут сохраняться bash-процесс, текущая директория, переменные и shell-функции при повторном использовании одного Harness и session_id.

Переживёт ли persistent-сессия рестарт Harness?

Нет, штатная документация terminal-bash backend прямо указывает, что сессии не переживают завершение процесса Harness.

Почему для SSH недостаточно просто выбрать backend?

Тип backend определяет реализацию, но не конкретную цель и правила подключения: профиль, bastion, VM, режим attach, удалённый каталог, тайм-аут и политику reconnect.

Какие данные безопаснее передавать при запуске SSH-сессии?

Практичный подход состоит в передаче идентификатора разрешённого профиля подключения вместо приватного ключа, пароля или токена. Секреты и проверка policy должны оставаться вне model-facing схемы.

Когда нужен remote execution provider, а не только SSH terminal backend?

Если агенту требуется единая удалённая среда для shell, файлов, процессов и инструментов разработки. Для ограниченного доступа к оболочке может быть достаточно terminal backend.