qwen serve справочник по HTTP-протоколу

Этап 1 дизайна демона qwen-code . Все маршруты находятся под базовым URL демона (по умолчанию http://127.0.0.1:4170).

В этом справочнике описаны HTTP-маршруты и форматирование SSE. Читайте его вместе со схемой типизированных событий для контрактов полезной нагрузки, причин ресинхронизации и якорей истории, руководством по шине событий и воспроизведению для доставки и обратного давления, а также возможностями и версионированием для существующего протокола v1 и правил совместимости. Индекс документации демона содержит ссылки на полный набор контрактов.

Аутентификация

Если демон был запущен с --token или QWEN_SERVER_TOKEN — или привязан к не-loopback интерфейсу без обоих флагов, что генерирует эфемерный bearer-токен и выводит его один раз при запуске — каждый обычный API-маршрут, кроме /health на стандартных loopback-привязках, должен содержать:

Authorization: Bearer <token>

Без настроенного токена на default loopback заголовок является необязательным, и запросы, поступающие через основной слушатель, имеют полные права оператора API. Проверки доверия к рабочему пространству, владения сессией, X-Qwen-Client-Id, разрешений, функций, валидации и ресурсов по-прежнему применяются. Сравнение токенов выполняется за константное время. Ответы 401 единообразны для missing header / wrong scheme / wrong token.

--open-with-auth. Этот режим CLI, отключенный по умолчанию, требует loopback-привязки и доступного Web Shell. Он повторно использует обычный выбор --token через QWEN_SERVER_TOKEN или генерирует 32 случайных байта, закодированных как base64url, перед запуском демона, если этот выбор пуст. Браузер получает выбранный bearer через #token= и хранит его для каждой вкладки; протокол и промежуточное ПО видят обычный настроенный токен. Ключи доставки фрагментов зависят от разрешенного токена, а не от этого флага: любой запуск --open прикрепляет разрешенный bearer — настроенный или сгенерированный — к фрагменту #token= запускаемого URL (видимому локальным пользователям через ps / /proc, как предупреждает лаунчер), поэтому не-loopback привязка с голым --open передает свой сгенерированный bearer браузеру тем же способом; отличительные вклады этого флага — это генерация токена на loopback и резервный вариант ручного URL для сред, не поддерживающих браузер. Только прямые встроенные вызывающие объекты, игнорирующие RunHandle.resolvedToken, и клиенты, которые никогда не запускают браузер, не получают автоматических учетных данных. В средах, не поддерживающих браузер, выводится URL с секретом во фрагменте для ручного открытия. Loopback /health и статические ресурсы Web Shell сохраняют описанные ниже исключения; --require-auth по-прежнему контролирует доступ к /health.

Входящие вебхуки каналов (POST /channels/:channelName/webhooks/:source) отделены от этого контракта bearer во всех режимах. При монтировании они регистрируются до bearerAuth и проходят аутентификацию с помощью настроенного x-qwen-webhook-secret; ротация bearer-токена демона не приводит к ротации секретов источника вебхуков.

Исключение /health (Bctum): на loopback-привязках (127.0.0.0/8 / localhost / ::1 / [::1]) /health регистрируется ДО middleware bearer, поэтому зонды работоспособности внутри пода не должны передавать токен, даже если демон был запущен с --token. Не-loopback привязки (--hostname 0.0.0.0 и т. д.) защищают /health вместе с другими обычными API-маршрутами — см. раздел GET /health для обоснования.

--require-auth (#4175 PR 15). Передайте этот флаг при загрузке, чтобы распространить правило «должен быть токен» также на loopback. Загрузка завершается ошибкой, если не удается разрешить источник токена — на loopback это означает --token, QWEN_SERVER_TOKEN или --open-with-auth (который устанавливает свой собственный сгенерированный токен перед загрузкой, поэтому --require-auth --open-with-auth запускается). Fail-fast применяется только к loopback: не-loopback привязка разрешает эфемерный bearer, который она генерирует, когда ни один из настроенных источников не присутствует, и это удовлетворяет требованию флага. Исключение /health удаляется в любом случае, поэтому /health также требует Authorization: Bearer ….

Когда флаг включен, глобальный middleware bearerAuth защищает каждый обычный API-маршрут — включая /health и /capabilities. Входящие вебхуки каналов остаются независимо аутентифицированными общим секретом, а маршруты документов и ресурсов Web Shell остаются пред-аутентификационными. Таким образом, неаутентифицированный клиент не может выполнить предварительный запрос caps.features, чтобы узнать, требуется ли аутентификация: поверхностью обнаружения для этого случая является само тело ответа 401 (единообразное для маршрутов, защищенных bearer, согласно разделу Аутентификация). Тег возможности require_auth является подтверждением после аутентификации — как только клиент успешно проходит аутентификацию и читает /capabilities, наличие тега подтверждает, что демон был запущен с --require-auth (полезно для интерфейсов аудита/соответствия требованиям и для клиентов SDK, чтобы отобразить «это развертывание усилено» в панели настроек). Строгие маршруты мутаций принимают запросы основного слушателя от доверенного loopback, запросы с bearer-аутентификацией или сопряженные запросы Local Control. Недоверенные встроенные компоненты без токена все еще получают 401 { code: "token_required", error: "…" }; при наличии --require-auth глобальный middleware bearer сначала отклоняет запрос со старым телом Unauthorized.

--allow-origin <pattern> (T2.4 #4514 ). Браузерные клиенты, обращающиеся к демону кросс-доменно, по умолчанию блокируются — запрос, содержащий заголовок Origin, возвращает 403 {"error":"Request denied by CORS policy"}, поскольку клиенты CLI/SDK никогда не отправляют Origin, и демон рассматривает его наличие как признак того, что запрос поступил из браузерного контекста, в который оператор не входил добровольно. Одно исключение предшествует стене на не-loopback привязке с токеном: однодоменный запрос (Origin равен схеме прямого сокета плюс нормализованный авторитет Host) проходит bearer-аутентификацию, и его Origin удаляется на основном слушателе — при действительном bearer статус маршрута следует дальше, при отсутствующем или недействительном bearer возвращается 401, за исключением пред-аутентификационных маршрутов документа Web Shell, /assets/*, /manifest.webmanifest, /sw.js и /mcp-app-sandbox, которые обслуживаются без учетных данных, как и в других режимах — и только кросс-доменные или несоответствующие значения Origin сохраняют конверт 403. Передайте --allow-origin <pattern> (повторяемо) при загрузке, чтобы установить список разрешений вместо стены. Каждый шаблон представляет собой:

• Литерал * — разрешает любой источник. Рискованно: загрузка завершается ошибкой, если настроен *, но не удалось получить токен авторизации (bearer token). Проверка использует разрешённый токен — --token, сгенерированный токен для loopback-адреса из QWEN_SERVER_TOKEN или --open-with-auth, либо временный bearer-токен, генерируемый при привязке к non-loopback интерфейсу, если ни один из настроенных источников не доступен; таким образом, этот отказ касается только loopback-адресов. При загрузке в stderr выводится предупреждение, если * присутствует в списке. Рекомендация: используйте вместе с --require-auth на loopback-привязках, чтобы доступ к /health также контролировался через bearer-токен — по умолчанию он регистрируется до middleware проверки токена на loopback (чтобы пробы k8s/Compose могли обращаться к нему без токена), а allowlist с * делает его доступным из любого браузера с другим origin. --require-auth всё равно оставляет статические ресурсы Web Shell (/, /assets/*, /manifest.webmanifest, /sw.js, а также навигации документов /session/:id, /plugins, /channels, /live, /scheduled-tasks, /goals и /settings) доступными до авторизации на loopback по замыслу — они монтируются до middleware проверки токена, поэтому при allowlist с * они остаются читаемыми из любого браузера с другим origin; --no-web устраняет эту поверхность. На non-loopback привязках проверка bearer-токена уже обязательна при загрузке, а /health регистрируется после неё. Обычные API-маршруты защищены проверкой bearer-токена, входные данные webhook каналов сохраняют собственный контроль через общий секрет, а статические ресурсы Web Shell (/, /assets/*, /manifest.webmanifest, /sw.js, а также навигации документов /session/:id, /plugins, /channels, /live, /scheduled-tasks, /goals и /settings) остаются доступными до авторизации, если только --no-web не отключает их.
• Канонический URL источника — <scheme>://<host>[:<port>]. Без завершающего слэша, без пути, без userinfo, без запроса. Загрузка завершается ошибкой InvalidAllowOriginPatternError, если запись не проходит проверку на соответствие канонической форме new URL(pattern).origin === pattern; сообщение об ошибке указывает неверный шаблон и каноническую форму. Строгость по замыслу: тихая нормализация (например, удаление завершающего /) позволила бы проскользнуть опечаткам и принять неоднозначный ввод. Без полученного токена — что после генерации означает привязку к локальному адресу — записи HTTP(S) ограничены хостами локального адреса; браузерный источник с нелокального адреса требует токен, так как иначе он может управлять полным операторским API, включая выполнение кода от имени пользователя демона. Явно указанные источники расширений браузера сохраняют существующий путь локальной автоматизации без токена. При запуске логируется авторизация, предоставленная любому браузерному источнику без токена.

Совпавшие источники получают стандартные заголовки ответа CORS на каждый запрос:

Access-Control-Allow-Origin: <echoed origin>
Vary: Origin
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Qwen-Client-Id, Last-Event-ID, X-Qwen-Event-Epoch
Access-Control-Max-Age: 86400
Access-Control-Expose-Headers: Retry-After, X-Qwen-Event-Epoch, X-Qwen-SSE-Stream-Id

Access-Control-Allow-Origin возвращает origin запроса дословно (в нижнем/верхнем регистре, как отправил браузер), а не литерал *, даже при использовании шаблона * — кэш браузера использует его в паре с Vary: Origin в качестве ключа, и возврат значения оставляет возможность добавить Access-Control-Allow-Credentials в будущих релизах без изменения схемы. Открытые заголовки позволяют браузерным клиентам учитывать подсказки о повторных попытках, сохранять эпоху SSE и коррелировать принятые физические потоки. Access-Control-Allow-Credentials сегодня НЕ отправляется: настроенные учетные данные демона используют bearer-in-Authorization, который работает между источниками без credentials: 'include'; доверенная локальная авторизация не требует браузерных учетных данных.

Preflight-запросы OPTIONS (OPTIONS с Access-Control-Request-Method или Access-Control-Request-Headers) завершаются ответом 204 No Content плюс заголовками выше. Это конвенциональный паттерн CORS, и он безопасен — preflight лишь подтверждает, какие методы/заголовки примет демон; фактический последующий запрос все равно проходит через шлюз Host, а затем либо через авторизацию токена/listener, либо через шлюз общего секрета вебхука канала перед чтением или изменением состояния. Простые запросы OPTIONS от совпавших источников продолжают проходить дальше с прикрепленными заголовками CORS.

Источники, которые не совпадают со списком разрешений, все равно получают 403 {"error":"Request denied by CORS policy"} — та же структура ответа, что и у стены по умолчанию, поэтому клиентам, которые уже разбирали ответ стены, не нужно обрабатывать особые случаи для демонов со списком разрешений. Путь отказа не выдает никаких заголовков Access-Control-* (браузер проигнорировал бы их, а выдача косвенно раскрыла бы размер списка разрешений через наличие заголовков).

Настроенный список шаблонов намеренно НЕ возвращается в /capabilities — браузерный клиент уже знает свой собственный origin (в конце концов, он обращался к демону), а отображение списка позволило бы неаутентифицированному читателю /capabilities перечислить все доверенные источники (полезная разведка для неправильно настроенного развертывания). SDK-клиенты проверяют тег caps.features.allow_origin для определения «этот демон поддерживает обращения от браузеров с другими источниками», не нуждаясь в знании конкретных источников.

Запросы с тем же origin на локальном адресе (например, вызовы Web Shell к демону на том же 127.0.0.1:port) обрабатываются отдельным shim’ом удаления Origin, который выполняется ДО middleware CORS и удаляет заголовок Origin для 127.0.0.1:port / localhost:port / [::1]:port / host.docker.internal:port или точного связанного локального адреса и порта. Он также принимает формы без порта, соответствующие схеме, которые браузеры отправляют для портов по умолчанию: http://host на порту 80 и https://host на порту 443. Эти запросы проходят независимо от конфигурации --allow-origin — операторам не нужно указывать порт демона в списке, чтобы Web Shell работал.

Общая форма ошибки

Ответы 5xx содержат исходные поля code и data ошибки, если они присутствуют (стиль JSON-RPC — SDK ACP пересылает {code, message, data} от агента):

{
  "error": "Internal error",
  "code": -32000,
  "data": { "reason": "model quota exceeded" }
}

Некорректный JSON в теле запроса возвращает:

{ "error": "Invalid JSON in request body" }

со статусом 400.

SessionNotFoundError для неизвестного идентификатора сессии возвращает:

{
  "error": "No session with id \"<sid>\"",
  "sessionId": "<sid>",
  "code": "session_not_found"
}

со статусом 404. Конкурентное закрытие использует code: "session_closing".

WorkspaceMismatchError для POST /session, чей cwd не приводится к канонической форме зарегистрированного рабочего пространства, возвращает 400 с:

{
  "error": "Workspace mismatch: daemon is bound to \"…\"",
  "code": "workspace_mismatch",
  "boundWorkspace": "/path/the/daemon/uses/as-primary",
  "requestedWorkspace": "/path/in/the/request"
}

Используйте это для обнаружения несоответствия перед выполнением: прочитайте workspaceCwd из /capabilities и исключите cwd из POST /session (он вернется к основному рабочему пространству), или когда рекламируется multi_workspace_sessions, выберите один из workspaces[].cwd.

POST /session превышающий лимит демона --max-sessions возвращает 503 с заголовком Retry-After: 5 и:

{
  "error": "Session limit reached (20)",
  "code": "session_limit_exceeded",
  "limit": 20,
  "scope": "workspace"
}

Когда эффективный общий лимит демона отвергает новую сессию — --max-total-sessions или значение по умолчанию, описанное в limits.maxTotalSessions — возвращается та же форма ответа с "scope": "total".

Подключения к существующим сессиям НЕ учитываются в лимите, поэтому переподключения к простаивающему демону продолжают работать даже при достижении лимита.

Если бюджет инициализации канала ACP истекает до отправки newSession, POST /session возвращает 504 с Retry-After: 5 и:

{
  "error": "AcpSessionBridge initialize timed out after 10000ms",
  "code": "init_timeout",
  "errorKind": "init_timeout",
  "retryable": true,
  "sideEffectPossible": false,
  "phase": "channel.initialize",
  "timeoutMs": 10000
}

timeoutMs — и числовой суффикс error — отражают настроенный бюджет демона --initialize-timeout-ms (приведенные выше значения являются значениями по умолчанию). Полная безопасная форма повтора выше выдается только для простого создания сессии, где инициализация канала строго предшествует каждому долговременному изменению: на этом пути поле sideEffectPossible: false является авторитетным, поскольку инициализация предшествует запросу ACP newSession, и клиент, понимающий этот структурированный контракт, может выполнить повторную попытку после указанной задержки без риска дублирования Сессии.

Запросы, несущие branch или worktree, и таймауты инициализации, возвращаемые маршрутами с мутациями, отличными от простого создания (например, POST /session/:id/branch и POST /session/:id/side-task, где зафиксированный форк может пережить неудачное рукопожатие), возвращают тот же 504 с code: "init_timeout", phase и timeoutMs — но БЕЗ Retry-After, retryable или sideEffectPossible. Для них результат мутации неизвестен: подготовка ветки и worktree изменяет git до инициализации канала, а попытка отката при ошибке является best-effort (неудачный откат checkout оставляет рабочую область на новой ветке, а повторная попытка может вызвать конфликт «ветка уже существует»). Клиенты, которые классифицируют все ответы 5xx с мутацией как неоднозначные, остаются консервативно в состоянии fail-closed и должны применять ту же политику к сокращенной форме. POST /session/:id/load и POST /session/:id/resume возвращают ту же сокращенную форму init_timeout 504, когда инициализация канала завершается по таймауту до отправки запроса восстановления (этап ensureChannel); в отличие от session_restore_timeout 504, описанных в их списках ошибок, эта форма не содержит Retry-After, не содержит retryable и не устанавливает блокировку, поскольку восстановление никогда не было отправлено. Таймаут отправки newSession для POST /session является исключением: он возвращает 504 с code: "init_timeout", retryable: true иDerived из бюджета Retry-After, но без phase или sideEffectPossible, поскольку результат создания неоднозначен. Все остальные метки таймаута сохраняют общее отображение.

RestoreInProgressError — генерируется POST /session/:id/load, POST /session/:id/resume или вызываемым id POST /session, когда другая регистрация уже владеет этим id — возвращает 409 и:

{
  "error": "Session \"<sid>\" is already being restored via session/<resume|load>; retry session/<load|resume> after it completes",
  "code": "restore_in_progress",
  "reason": "restore_in_progress",
  "retryable": true,
  "sessionId": "<sid>",
  "activeAction": "load",
  "requestedAction": "resume"
}

Генерируется, когда для id, который уже имеет активный session/resume (или наоборот), выпускается session/load, или когда гонка spawn с caller-supplied-id конкурирует с любым направлением восстановления. Подождите не менее Retry-After секунд и повторите попытку. Гонки одного действия (load против load, resume против resume) объединяются вместо ошибки, пока восстановление активно.

reason различает две блокировки, которые используют этот код, и заголовок Retry-After отслеживает это:

Публичный запрос восстановления регулируется параметром limits.sessionRestoreTimeoutMs (по умолчанию 60 с). После 504 id остается заблокированным до завершения позднего запроса ACP и очистки, поэтому клиент, который продолжает повторять попытки с обычным интервалом в 5 секунд, будет бесконечно получать ошибку 409, которую он не может устранить — соблюдайте подсказку, основанную на бюджете, которая приходит вместе с awaiting_abandoned_cleanup.

SessionWorkspaceConflictError — генерируется POST /session/:id/load и POST /session/:id/resume, когда запрошенный cwd указывает на одну зарегистрированную рабочую область, но тот же id сессии уже активен или восстанавливается другим рантаймом — возвращает 409 с:

{
  "error": "Session \"<sid>\" is already live or restoring in another workspace runtime.",
  "code": "session_workspace_conflict",
  "sessionId": "<sid>",
  "workspaceCwd": "/requested/workspace",
  "workspaceId": "requested-workspace-id",
  "liveWorkspaceCwd": "/live/owner/workspace",
  "liveWorkspaceId": "live-owner-workspace-id"
}

Клиенты должны повторить попытку с рабочей областью-владельцем или дождаться завершения активного восстановления перед восстановлением id в другую рабочую область. Гонки восстановления в той же рабочей области продолжают использовать поведение объединения restore_in_progress моста.

SessionArchivedError генерируется, когда вызывающий объект пытается загрузить или возобновить сессию, чей JSONL находится под chats/archive/:

{
  "error": "Session \"<sid>\" is archived. Unarchive it before loading.",
  "code": "session_archived",
  "sessionId": "<sid>"
}

со статусом 409.

SessionArchivingError генерируется, когда переход архивирования или разархивирования сессии уже выполняется для того же id:

{
  "error": "Session \"<sid>\" is being archived or unarchived; retry later.",
  "code": "session_archiving",
  "sessionId": "<sid>"
}

со статусом 409 и Retry-After: 5.

Возможности

Демон объявляет поддерживаемые им теги функций из реестра возможностей serve. Клиенты должны ограничивать UI через features, а не через mode (согласно §10 дизайна).

['health', 'capabilities', 'session_create', 'session_startup_config', 'session_id_override', 'session_scope_override',
 'session_load', 'session_resume', 'session_transcript',
 'unstable_session_resume',
 'session_list', 'session_catalog_batch', 'session_info', 'session_prompt', 'session_mid_turn_message_mutation',
 'session_mid_turn_send_now',
 'session_cancel', 'session_events',
 'slow_client_warning', 'typed_event_schema',
 'session_set_model', 'client_identity', 'client_heartbeat',
 'session_permission_vote', 'permission_vote', 'workspace_mcp', 'workspace_skills',
 'workspace_skills_config_runtime',
 'workspace_providers', 'workspace_acp_preheat', 'workspace_acp_status',
 'auth_provider_install', 'workspace_memory',
 'workspace_agents', 'workspace_agent_generate', 'workspace_env',
 'workspace_preflight', 'session_context', 'session_context_usage',
 'session_supported_commands', 'session_tasks', 'scheduled_task_gate', 'autofix_pr_watches', 'session_monitor_tool_correlation', 'session_stats',
 'session_lsp', 'session_resources', 'session_status',
 'session_close', 'session_metadata', 'session_organization',
 'session_archive', 'mcp_guardrails',
 'workspace_mcp_manage', 'mcp_guardrail_events',
 'mcp_server_runtime_mutation',
 'workspace_file_read', 'workspace_file_bytes', 'workspace_file_write',
 'workspace_file_upload', 'workspace_file_delete', 'workspace_directory_create', 'workspace_directory_delete',
 'session_approval_mode_control', 'workspace_tool_toggle',
 'workspace_skill_settings_toggle', 'workspace_skill_settings_batch_toggle',
 'workspace_session_refresh',
 'extension_batch_activation_v2', 'extension_activation_explicit_refresh',
 'extension_state',
 'workspace_settings', 'workspace_init', 'workspace_mcp_restart',
 'session_recap', 'session_generation', 'session_btw', 'session_btw_stream', 'session_shell_command',
 'standalone_sessions_v1', 'standalone_session_options_v1',
 'mcp_workspace_pool', 'mcp_pool_restart',
 'require_auth', 'allow_origin', 'auth_device_flow',
 'permission_mediation', 'prompt_absolute_deadline', 'writer_idle_timeout',
 'non_blocking_prompt', 'session_language', 'user_language_sync', 'session_message_deletion', 'session_rewind',
 'workspace_hooks', 'session_hooks', 'workspace_extensions',
 'session_branch', 'rate_limit', 'workspace_reload', 'workspace_model_reload', 'channel_delivery',
 'multi_workspace_sessions', 'multi_workspace_session_rewind',
 'multi_workspace_session_shell', 'persistent_workspace_registration',
 'workspace_display_name', 'workspace_runtime_removal', 'workspace_runtime',
 'workspace_qualified_rest_core', 'workspace_qualified_voice',
 'workspace_qualified_memory', 'extension_management_v2', 'extension_git_credentials',
 'extension_local_path_install',
 'workspace_persisted_transcript',
 'workspace_session_export', 'workspace_archived_session_export',
 'workspace_session_live_state', 'workspace_session_live_state_batch',
 'client_mcp_over_ws', 'cdp_tunnel_over_ws', 'browser_automation_mcp']

Условные теги появляются только тогда, когда выполнено условие развертывания или доступности рантайма (см. таблицу ниже). Тег permission_mediation для F3 всегда включен и несет modes: ['first-responder', 'designated', 'consensus', 'local-only'], чтобы клиенты SDK могли интроспектировать набор, поддерживаемый сборкой; стратегия активного рантайма указана в body.policy.permission.

session_startup_config объявляет опциональный startupConfig: { modelServiceId, reasoningEffort? } при обычном и автономном создании. Всегда выполняйте предпроверку этого тега: старые маршруты обычного создания могут молча игнорировать объект. modelServiceId обязателен (1–256 символов); reasoningEffort принимает none, default, low, medium, high, xhigh или max, если они поддерживаются выбранной моделью. Отсутствие поля применяет только модель, без установщика рассуждений или неявного default. Объект нельзя комбинировать с устаревшим верхним уровнем modelServiceId или явным одиночным scope, и он подразумевает новую нить. При запуске общие настройки по умолчанию никогда не сохраняются; последующее поведение сессии не меняется.

Успех включает modelApplied: true и startupConfigApplied: { modelServiceId, reasoningEffort?, effectiveReasoning? }. Селектор модели является каноническим. Только явные запросы рассуждений включают два поля рассуждений; эффективное состояние — { state: 'disabled' }, { state: 'provider-default' } или { state: 'enabled', effort? } (рассуждения только через переключатель не имеют effort). Неверная структура вызывает 400 invalid_startup_config; отклоненный или неподтвержденный выбор вызывает 422 startup_config_rejected. Определенный отказ автономного режима откатывает принадлежащую ему запись и пытается удалить пустой выходной каталог перед возвратом; откат записи, удаление которого не может быть подтверждено, и временные сбои запуска сохраняют standalone_creation_outcome_unknown, тогда как неудачное удаление каталога только логируется, и определенный отказ все равно возвращается. Сбой подтверждения тела успешного ответа в SDK является ошибкой протокола, а не инструкцией принять восстановленную сессию.

session_scope_override является дескриптором согласования для поля sessionScope на уровне запроса в POST /session (см. ниже). Старые демоны молча игнорируют это поле, поэтому клиенты SDK должны выполнить предпроверку caps.features для этого тега перед его отправкой.

session_id_override является дескриптором согласования для опционального caller-supplied sessionId в метаданных POST /session и ACP session/new. Клиенты должны убедиться, что caps.features содержит этот тег перед отправкой поля, поскольку старые демоны могут молча его игнорировать.

persistent_workspace_registration объявляет долговечную регистрацию для рабочих областей, добавленных во время выполнения. POST /workspaces принимает { "cwd": "/absolute/path", "persist": true }; успех включает persisted: true. Регистрации ограничены канонической основной рабочей областью демона в домашнем каталоге пользователя Qwen и восстанавливаются при следующем запуске демона. Отсутствие persist сохраняет локальную для процесса регистрацию. GET /workspace-registrations перечисляет сохраненный желаемый набор, а DELETE /workspace-registrations/:id забывает запись для следующего перезапуска без горячего удаления активного рантайма.

workspace_display_name объявляет опциональный ввод displayName в POST /workspaces, обновления метаданных рабочей области через PATCH /workspaces/:workspace и опциональные поля отображаемых имен в проекциях рабочей области. Имена не участвуют в поиске или маршрутизации: id и канонический cwd остаются единственными селекторами, и дубликаты имен разрешены.

workspace_runtime_removal объявляет о синхронном горячем удалении через DELETE /workspaces/:workspace. Записи capability workspace добавляют необязательный removable; удаляться могут только строки с removable: true. Удаление также забывает все постоянные псевдонимы регистрации для runtime, но никогда не удаляет файлы, настройки, транскрипты или архивы.

workspace_runtime объявляет GET /workspace/runtime/status, POST /workspace/runtime/ensure и их эквиваленты /workspaces/:workspace/runtime/.... ensure не принимает выбор capability: он запускает или повторно использует ACP runtime выбранного доверенного workspace и возвращает его состояние жизненного цикла и монотонную эпоху runtime. Основные маршруты принадлежат только основному runtime; квалифицированные маршруты разрешают только выбранный зарегистрированный runtime и никогда не выполняют откат. Успешное ensure обновляет окно keepalive runtime на десять минут. Status является только для чтения и никогда не запускает дочерний процесс. Конкурентные ensures разделяют один физический запуск. Идущий запуск или сбой возвращают повторные 503 runtime_still_starting или 503 runtime_initialization_failed. Подготовка capability может продолжаться после истечения бюджета наблюдения ensure; в этом случае ensure всё равно возвращает живой runtime с состоянием capability non-ready для опроса status. Capability объявляется только тогда, когда все активные мосты runtime предоставляют авторитетный снимок жизненного цикла; выбранный легаси внедрённый мост возвращает 501 workspace_runtime_not_supported вместо угаданного состояния или эпохи.

workspace_runtime_stop независимо объявляет об остановке runtime, подтверждённой пользователем. GET /workspaces/runtime-stop-options — это предварительный просмотр только для чтения, глобальный для процесса: он включает количество зафиксированных дочерних процессов, смоделированный потолок дочерних процессов, а также сессии каждого видимого workspace, причины блокировки, ID канала, эпоху, текущий токен остановки и последнюю квитанцию. Обычные загруженные сессии могут быть явно остановлены; независимые клиенты ACP, включённые расписания, ожидающие работы планировщика/управления/запуска, задачи памяти, воркеры, голосовые и специальные purpose-runtimes заблокированы. POST /workspaces/:workspace/runtime/stop использует строгий гейт мутаций и только выбранный доверенный runtime. Отправьте confirmInterruptions: true, expectedChannelId, expectedRuntimeEpoch, expectedStopToken и точный expectedSessionIds из предварительного просмотра. Никогда не выполняйте откат к основному runtime. Предварительный просмотр и каждая квитанция перечисляют живые каналы ACP runtime как channels (channelId, runtimeEpoch, необязательный executionEngine); runtime может иметь по одному каналу на движок выполнения, и остановка покрывает все они. channelId называет первый перечисленный канал, а runtimeEpoch — новейшая перечисленная эпоха, поэтому канал, запущенный после предварительного просмотра, делает подтверждение устаревшим.

Успешный ответ содержит state: "stopped", stopped: true и released: true после признанного закрытия сессий и освобождения реестра процессов для каждого перечисленного дочернего процесса. Регистрация, файлы и сохранённая история остаются. Ответы включают затронутые, прерванные, закрытые и оставшиеся ID сессий. Устаревшее или заблокированное подтверждение — HTTP 409 (workspace_runtime_stop_stale / workspace_runtime_stop_blocked); частичное закрытие — 409 workspace_runtime_stop_incomplete; идущее удаление или неудачное удаление без доказанного освобождения — 503 workspace_runtime_stop_in_progress / workspace_runtime_stop_failed; неподдерживаемое управление — 501 workspace_runtime_stop_not_supported. Неаккуратное удаление, которое позже доказывает освобождение реестра, может вернуть 200 с предупреждением об ошибке; неподтверждённый сброс сессии всё ещё возвращает частичный/ошибочный результат. Общий бюджет наблюдения/закрытия составляет 60 секунд. Если он истекает, пока закрытие сессии всё ещё выполняется, ответ завершается с state: "failed" и 503 workspace_runtime_stop_failed; очистка продолжается отдельно. Выбранный workspace остаётся изолированным, и его дочерний процесс продолжает учитываться до фактического завершения очистки, даже если вызывающий получил ошибку. Опции только для чтения могут позже сообщить stopped после признанных закрытий и доказанного освобождения, или incomplete, когда сохранение было неподтверждённым; уже возвращённый снимок ошибки не меняется. Если бюджет вместо этого исчерпан между закрытиями сессий, ответ завершается с state: "incomplete" и 409 workspace_runtime_stop_incomplete: дальнейшие закрытия или принудительное убийство не начинаются, гейт допуска остановки освобождается (выживший дочерний процесс продолжает учитываться как обычно), и остановка оставшихся сессий требует нового предварительного просмотра и подтверждения. Отказ в сбросе не обходится принудительным убийством оставшихся сессий. Выход корня или падение глобального количества процессов само по себе не устанавливает освобождение выбранного дочернего процесса. На Windows, где реестр не отслеживает группы дочерних процессов, установленный выход корня является доказательством освобождения, поэтому released: true там не доказывает, что дерево процессов исчезло.

Повторное подтверждение последнего использованного токена наблюдает ту же операцию. Новое подтверждение может повторить попытку неполной остановки, ротируя токен; старые использованные токены затем становятся устаревшими. Если ответ потерян, прочитайте опции и сопоставьте последнюю квитанцию по workspace и токену остановки вместо остановки другой цели. Квитанции могут быть недоступны после удаления, изменений доверия или пересоздания демона/моста; отсутствие оставляет результат неизвестным и никогда не авторизует продолжение. SDK runtimeStopOptions() и workspaceById(id).stopRuntime(confirmation) используют REST даже при транспорте ACP и никогда автоматически не повторяют POST. Подписчики сессий получают session_closed с reason: "client_close" и cause: "workspace_runtime_stop"; фатальные выходы, связанные с остановкой, дополнительно помечают persistenceUnconfirmed: true. Обновлённые клиенты Web Shell сохраняют выбранное сохранённое/транскрипт и ждут явного Resume. Это одноразовая остановка, а не постоянное приостановление; клиент, пропустивший событие, может снова конкурировать за ёмкость.

Ответы статуса runtime и ensure используют эту форму:

{
  "v": 1,
  "workspaceCwd": "/work/project",
  "state": "active",
  "runtimeLive": true,
  "runtimeEpoch": 4,
  "capabilities": {
    "skills": {
      "state": "ready",
      "revision": 2,
      "runtimeEpoch": 4
    }
  }
}

Когда runtime workspace имеет более одного движка выполнения, runtimeLive и runtimeEpoch описывают канал, обслуживающий управление workspace (MCP и Skills): пока этот канал жив, запуск или выход другого движка не меняет их. state сообщает этот канал как cold, starting или stopping, пока он не жив; active и idle считают работу на каждом движке.

capabilities.skills.state — это not_started, starting, ready, stale или error; сбои включают {code, message} в capabilities.skills.error. Каталог Skills актуален только тогда, когда значения верхнего уровня и capability runtimeEpoch совпадают. revision упорядочивает подготовку Skills внутри одной эпохи runtime и не должен сравниваться между эпохами.

workspace_skills_config_runtime объявляет раздельные чтения Skills и мутации конфигурации под /workspace/{config,runtime}/skills и /workspaces/:workspace/{config,runtime}/skills. Web Shell использует эти маршруты для управления Skills и, при составлении новой сессии, для заполнения слэш-команд из конфига непосредственно перед заменой их каталогом runtime с соответствующей эпохой. Когда функция отсутствует, клиенты должны продолжать использовать легаси маршруты Skills и не должны вызывать runtime ensure исключительно для Skills.

session_load и session_resume объявляют маршруты явного восстановления (POST /session/:id/load и POST /session/:id/resume). Старые демоны возвращают 404 для этих путей, поэтому клиенты SDK должны предварительно проверить caps.features перед вызовом. unstable_session_resume всё ещё объявляется как устаревший псевдоним для совместимости с SDK, которые поставлялись, когда базовый метод ACP назывался connection.unstable_resumeSession; новые клиенты должны гейтовать на session_resume.

limits.sessionRestoreTimeoutMs, при наличии, представляет собой бюджет времени реального времени демона для базового запроса ACP loadSession / unstable_resumeSession. Это аддитивное поле v1. TypeScript SDK предоставляет демону 10 секунд запаса на стороне клиента, а watchdog Web Shell — 15 секунд; клиенты, взаимодействующие со старыми версиями демона, должны использовать 70 и 75 секунд соответственно.

session_transcript объявляет GET /session/:id/transcript, доступный только для чтения постраничный просмотр воспроизведения поверх сохраненного JSONL активной сессии. Он отделен от /load: не подключает клиент, не инициализирует живой EventBus, не создает живую сессию и не изменяет окно живого воспроизведения. Клиенты должны использовать его, когда им нужна полная транскрипция на диске для длительной сессии, и продолжать использовать /load только для ограниченного живого воспроизведения при холодном восстановлении UI.

workspace_persisted_transcript объявляет GET /workspaces/:workspace/session/:id/transcript, локальный для демона постраничный просмотрщик только сохраненных данных, который не запускает ACP, не запрашивает состояние живого моста, не загружает настройки, не обнаруживает возможности проекта и не создает устаревший ключ курсора сохраненных данных. Тег является безусловным, так как доверенные первичные рабочие пространства могут использовать маршрут во множественном числе; авторизация доверия для каждого рабочего пространства по-прежнему проверяется при каждом запросе. Зарегистрированные недоверенные вторичные рабочие пространства могут выполнять чтение, тогда как недоверенное первичное рабочее пространство остается заблокированным.

workspace_session_export объявляет GET /workspaces/:workspace/session/:id/export, полный экспорт только для доверенных пользователей активной сохраненной сессии выбранного рабочего пространства. Он независим от session_export и workspace_qualified_rest_core: выпущенные версии демона могут объявлять оба старых тега без реализации маршрута во множественном числе, поэтому клиенты должны предварительно проверять этот тег напрямую. Тег является безусловным, так как доверенное первичное рабочее пространство может использовать маршрут по id или cwd. Экспорт не определяет владельца живой сессии, не запускает ACP, не подключает клиента и не выполняет откат к другому рабочему пространству.

workspace_archived_session_export объявляет GET /workspaces/:workspace/session/:id/archive/export, полный экспорт только для доверенных пользователей из архивного хранилища сохраненных данных выбранного рабочего пространства. Он независим от workspace_session_export и workspace_qualified_rest_core; клиенты должны предварительно проверять этот тег напрямую. Отдельный маршрут предотвращает ситуацию, когда старый демон игнорирует намерение работы с архивом и возвращает активную транскрипцию с тем же id.

workspace_session_live_state объявляет GET /workspaces/:workspace/sessions/live-state, снимок состояния в памяти только для доверенных пользователей, содержащий живые сессии среды выполнения выбранного рабочего пространства, а также версию каталога в памяти, которая сообщает клиентам, когда необходима полная перезагрузка сохраненного каталога. Он независим от workspace_qualified_rest_core: выпущенные версии демона могут объявлять более широкую возможность REST для рабочего пространства без реализации этого маршрута, поэтому клиенты должны предварительно проверять этот тег напрямую. Тег является безусловным, так как доверенное первичное рабочее пространство может использовать маршрут по id или cwd; проверки доверия для каждого рабочего пространства по-прежнему применяются при каждом запросе, и маршрут не распространяет разрешительную политику чтения сохраненного каталога для недоверенных вторичных рабочих пространств на состояние живого моста. Тег означает наличие конечной точки; он не гарантирует, что каждый живой элемент содержит необязательный маркер активности updatedAt, который зависит от жизненного цикла.

workspace_session_live_state_batch объявляет POST /sessions/live-state. Клиенты выполняют предварительную проверку один раз перед пакетированием опросов и сохраняют маршрут для одного рабочего пространства для поддержки старых версий демона. Пакет использует те же семантики снимка состояния в памяти только для доверенных пользователей и версии каталога, что и маршрут для одного рабочего пространства.

Необязательное верхнеуровневое поле /capabilities sessionLiveStatePollIntervalMs объявляет интервал опроса состояния живых данных для всего демона в миллисекундах. Оно определяется один раз из переменной окружения запуска QWEN_SESSION_LIVE_STATE_POLL_INTERVAL_MS независимо от наложений переменных окружения рабочего пространства. Принимаются целочисленные значения от 1000 до 2147483647; отсутствующие или недействительные значения используют 5000. Web Shell использует эту подсказку для всех опросов состояния живых данных рабочего пространства и также выполняет откат к 5000, если поле отсутствует или недействительно в старой или несовместимой версии демона. Это поле не изменяет семантику снимка маршрута, немедленное обновление локального состояния/видимости или опрос полного каталога. Клиенты SDK остаются ответственными за свои собственные таймеры.

slow_client_warning охватывает поведение обратного давления SSE: (a) демон отправляет синтетический кадр потока событий slow_client_warning, когда накопление живых кадров подписчика или накопление сериализованных байтов достигает 75% заполнения, один раз за эпизод переполнения (повторная активация после того, как оба показателя упадут ниже 37.5%); (b) GET /session/:id/events принимает параметр запроса ?maxQueued=N (диапазон [16, 2048]) для предварительного определения размера накопления кадров для каждого подписчика при холодном переподключении к большому кольцу воспроизведения. Ограничение по сериализованным байтам управляется демоном (по умолчанию 2 MiB на подписчика), относится только к живым данным и намеренно не имеет параметра запроса. Размер кольца для всего демона контролируется через --event-ring-size (по умолчанию 8000, согласно #3803 §02). Старые версии демона молча не поддерживают поведение предупреждения/запроса — выполните предварительную проверку этого тега перед включением функции.

typed_event_schema объявляет полезные нагрузки событий демона, соответствующие схеме KnownDaemonEvent SDK. Старые версии демона могут все еще передавать совместимые кадры, но клиенты SDK должны выполнить предварительную проверку этого тега перед предположением о типизированном покрытии событий.

client_heartbeat объявляет POST /session/:id/heartbeat. Старые версии демона возвращают 404; выполните предварительную проверку этого тега перед отправкой периодических сигналов heartbeat.

session_close и session_metadata объявляют DELETE /session/:id и PATCH /session/:id/metadata. Старые версии демона возвращают 404; выполните предварительную проверку этих тегов перед предоставлением возможностей закрытия или переименования.

session_organization объявляет пользовательские группы сессий и закрепление. Он добавляет GET/POST/PATCH/DELETE /workspace/:id/session-groups, PATCH /session/:id/organization и организованный список с опциональным включением GET /workspace/:id/sessions?view=organized. Когда объявлены и session_organization, и workspace_qualified_rest_core, доступна также мутация организации с указанием рабочего пространства PATCH /workspaces/:workspace/session/:id/organization. Устаревшая мутация остается доступной только для первичного рабочего пространства. Старые версии демона возвращают 404 для маршрутов мутации/группы и игнорируют контракт организованного просмотра, поэтому клиенты WebShell/SDK должны выполнить предварительную проверку этих тегов перед отображением соответствующего интерфейса группировки или закрепления.

session_archive объявляет API архивирования состояния директории v1: POST /sessions/archive, POST /sessions/unarchive и GET /workspace/:id/sessions?archiveState=active|archived. Архивированные сессии не могут быть загружены или возобновлены до их разархивирования. session_archive_idle_guard объявляет аддитивную опцию архивирования requireIdle: среда выполнения, владеющая сессией, проверяет, что активная работа подтверждена как простаивающая непосредственно перед началом закрытия, и в противном случае оставляет активную транскрипцию на месте. session_storage_conflict_repair объявляет аддитивную опцию запроса resolveConflicts и корзину ответа resolvedConflicts, описанные ниже.

workspace_qualified_rest_core объявляет множественные основные REST-маршруты под /workspaces/:workspace/.... Селектор сначала разрешается как точный идентификатор рабочего пространства, затем как URL-кодированный абсолютный путь к текущему рабочему каталогу после канонизации. Новые однопространственные демоны включают основной рантайм в workspaces[] даже при отсутствии multi_workspace_sessions, что позволяет клиентам обнаруживать идентификатор, требуемый маршрутами с привязкой к рабочему пространству; для старых демонов, не содержащих массив, клиенты должны использовать запасной вариант capabilities.workspaceCwd. Маршруты статуса доверия и запроса доверия доступны для зарегистрированных недоверенных рабочих пространств; квалифицированное чтение статуса хуков (GET /workspaces/:workspace/hooks) также доступно для зарегистрированных недоверенных рабочих пространств, так как оно сообщает о ожидающем решения доверии к проектным хукам, соответствуя квалифицированной мутации подтверждения; маршруты чтения файлов следуют существующей политике чтения файловой системы. Зарегистрированные вторичные недоверенные рабочие пространства также предоставляют каталоги только сохраненных сессий и групп сессий: эти операции чтения не подключаются к сессии, не запускают ACP и не объединяют состояние живого моста. Запись файлов, изменения каталогов и другие множественные основные маршруты требуют доверенного рабочего пространства, если отдельная возможность не документирует более узкую политику: workspace_persisted_transcript (только для чтения) или мутация предоставления доверия, которая принимается для зарегистрированного недоверенного рабочего пространства независимо от того, рекламируется ли workspace_trust_grant — этот тег сообщает только о том, настроена ли горячая перезагрузка доверия, поэтому записанное решение может достичь запущенного рантайма без перезапуска демона; он никогда не сообщает, обслуживается ли маршрут. Недоверенное основное рабочее пространство продолжает получать 403 { code: "untrusted_workspace" } из множественных маршрутов каталога и транскриптов; устаревшие единичные основные маршруты сохраняют свою существующую совместимость. Этот тег охватывает основные поверхности файлов, статуса, настроек, разрешений, доверия, жизненного цикла, управления MCP, переключателей инструментов и навыков, памяти, CRUD агентов рабочего пространства и хранения сессий. Он не охватывает аутентификацию, голос, расширения, транспорт ACP/WebSocket, маршрутизацию worker-каналов или экспорт сессий с привязкой к рабочему пространству; предварительно проверьте workspace_session_export или workspace_archived_session_export отдельно. Доверие к рабочему пространству не является ACL: клиент, имеющий токен демона, может читать все поверхности зарегистрированного рабочего пространства, разрешенные этой политикой.

workspace_qualified_voice объявляет голосовые маршруты, выбираемые доверенным рантаймом рабочего пространства: GET и POST /workspaces/:workspace/voice, POST /workspaces/:workspace/voice/transcribe и WS /workspaces/:workspace/voice/stream. Он объявляется только тогда, когда включены оба: многопространственные рантаймы и общий слушатель WebSocket для ACP/Voice. Селектор следует тем же правилам id-or-encoded-absolute-cwd, что и другие множественные маршруты. Для REST неизвестный селектор возвращает 400 { code: "workspace_mismatch" }, а недоверенный селектор возвращает 403 { code: "untrusted_workspace" }; отказ при обновлении WebSocket раскрывает соответствующий HTTP-статус 400/403 без структурированного JSON-конверта. Ни один из транспортов не использует запасной вариант на основной. Устаревшие /workspace/voice, /workspace/voice/transcribe и /voice/stream остаются только для основного. Клиенты используют workspace_qualified_voice для всех квалифицированных голосовых модальностей и позволяют выбранному рантайму сообщать об ошибках, специфичных для конфигурации. Устаревшие теги workspace_voice, workspace_voice_transcription и voice_transcribe описывают только маршруты, привязанные к основному, и не должны скрывать квалифицированную вторичную конфигурацию.

workspace_qualified_memory объявляет маршруты управляемой памяти с привязкой к рабочему пространству: POST /workspaces/:workspace/memory/{remember,forget,dream} для постановки задач в очередь и GET /workspaces/:workspace/memory/{remember,forget,dream}/:taskId для их чтения обратно. Он объявляется только тогда, когда включены оба: HTTP-транспорт ACP и многопространственные рантаймы. Селектор следует тем же правилам id-or-encoded-absolute-cwd, что и другие множественные маршруты. Каждое зарегистрированное рабочее пространство получает свою собственную полосу задач; квалифицированная полоса основного пространства является тем же экземпляром, что и единичная поверхность /workspace/memory, поэтому задача, поставленная в одной, читается в другой. Разрешение строго выполняется для выбранного рантайма без запасного варианта на основной: неизвестный селектор возвращает 400 { code: "workspace_mismatch" }, недоверенный селектор возвращает 403 { code: "untrusted_workspace" }, а неактивный или завершающий работу рантайм возвращает 503 { code: "workspace_runtime_unavailable" }. Операции чтения никогда не выделяют полосу, поэтому опрос рабочего пространства без задач возвращает 404 { code: "<kind>_task_not_found" }. Идентификаторы задач ограничены их полосой и не выживают после переконфигурации рабочего пространства или замены рантайма; устаревший идентификатор возвращает 404, а не условие потери данных. Когда HTTP-транспорт ACP отключен, тег не объявляется, и неквалифицированный запрос к вторичному пространству возвращает неретраибельный 501 { code: "workspace_memory_unavailable" }, в то время как квалифицированный маршрут основного пространства продолжает работать через локально принадлежащую полосу.

session_lsp объявляет GET /session/:id/lsp, снимок статуса LSP в структурированном виде только для чтения для клиентов демона. Старые демоны возвращают 404; предварительно проверьте этот тег перед раскрытием удаленного статуса LSP.

session_resources объявляет GET /session/:id/resources, пару снимков Skill и MCP в очищенном виде только для чтения, построенных из Config выбранной живой сессии. Маршрут ограничен владельцем живой сессии: он никогда не использует запасной вариант на основной рантайм и не выводит ресурсы сессии из статуса рабочего пространства. Вложенные объекты skills и mcp повторно используют соответствующие полезные нагрузки статуса рабочего пространства, но исключают дополнения аутентификации MCP, пула, бюджета рабочего пространства и ошибок обнаружения рабочего пространства. Статус, обнаружение и учет, сообщаемые менеджером MCP выбранной сессии, остаются присутствующими. Старые демоны возвращают 404; предварительно проверьте этот тег перед отображением каталога ресурсов сессии.

session_status объявляет GET /session/:id/status, сводку живого моста для одной сессии по идентификатору. Помимо clientCount и hasActivePrompt, живые сессии раскрывают isWaitingForPermission, isWaitingForUserQuestion, pendingInteractionCount и сохраненный turnError после неудачного хода. Ошибка очищается, когда следующий промпт действительно начинается. Живая сессия, которая завершила выполняющийся ход в текущем мосту, также несет updatedAt, тот же водяной знак активности, документированный в маршруте состояния живого режима; поскольку этот маршрут возвращает сводку моста напрямую, значение не объединяется с mtime сохраненного транскрипта и может быть раньше того, которое сообщает список сессий. Как ответ статуса одиночной сессии, так и списки сессий рабочего пространства включают turnError и pendingInteractions: действия разрешения, готовые к рендерингу, или вопросы ask_user_question плюс requestId и выбираемые варианты, требуемые существующими маршрутами голосования за разрешения. Каждый пользовательский вопрос имеет answerKey; голосуйте с помощью answers, например { "0": "Polling" }, используя это значение в качестве ключа. Сохраненные только сессии опускают состояние рантайма, потому что рантайм не существует. Старые демоны возвращают 404; предварительно проверьте этот тег перед опросом статуса одиночной сессии вместо сканирования полного списка сессий.

session_info объявляет GET /workspace/:id/session-info и его близнец /workspaces/:workspace/session-info. Ответ агрегирует количество активных и архивированных сохраненных сессий без гидратации метаданных списка. Это явное O(n) сканирование диска, и его нельзя опрашивать; клиенты должны рассматривать truncated: true как результат нижней границы.

session_approval_mode_control, workspace_tool_toggle, workspace_skill_settings_toggle, workspace_skill_settings_batch_toggle, extension_batch_activation_v2, workspace_init и workspace_mcp_restart объявляют маршруты управления мутациями, описанные ниже. Управление режимом одобрения сохраняет свой нестрогий шлюз совместимости. Остальные элементы управления проходят строгую проверку авторитета оператора: проходят запросы от доверенного локального обратного адреса (trusted-loopback) основного процесса, аутентифицированные по bearer-токену или сопряженные запросы Local Control. Основной запрос без токена, достигающий строгого шлюза без авторитета доверенного локального обратного адреса, возвращает 401 token_required; отсутствующие или недействительные настроенные учетные данные и несопряженные учетные данные Local Control отклоняются ранее промежуточным ПО bearer с простым ответом 401 Unauthorized. Демоны, у которых отсутствует один из этих маршрутов, возвращают 404. Специфичные для настроек теги Skill отличаются: демоны поколения с устаревшими тегами объявляют workspace_skill_toggle и workspace_skill_batch_toggle и обслуживают свой контракт, проверенный каталогом, по тем же путям. Устаревший маршрут с одной целью может вернуть HTTP 404 skill_not_found или 409 skill_not_toggleable; устаревший пакетный маршрут возвращает HTTP 200 и помещает ошибки, полученные из каталога, в errors[]. Выполняйте предпроверку каждого тега перед раскрытием его функциональности и не пытайтесь определить специфичный для настроек контракт Skill путем проверки доступности маршрутов. Пути маршрутов и тела запросов не изменились.

mcp_guardrails (issue #4175  PR 14) охватывает поверхность бюджета MCP: поля clientCount / clientBudget / budgetMode / budgets[] в GET /workspace/mcp, поле disabledReason в ячейках отдельных серверов и флаги CLI --mcp-client-budget / --mcp-budget-mode. Старые демоны полностью пропускают новые поля; клиенты SDK выполняют предпроверку этого тега перед использованием семантики budgets[]. Дескриптор реестра также содержит modes: ['warn', 'enforce'] для будущего раскрытия режимов функций — пока что клиенты определяют режим на основе поля budgetMode снимка состояния. Отказ сервера в режиме enforce детерминирован порядком объявления Object.entries(mcpServers); будущий слой приоритетов области действия (если qwen-code его внедрит) изменит это на «сначала наименьший приоритет», чтобы соответствовать соглашению claude-code plugin < user < project < local.

Область действия определяется возможностями. При наличии mcp_workspace_pool сессии внутри одного рабочего пространства разделяют пул транспортов и WorkspaceMcpBudget, а снимок состояния выдает budgets[0].scope: 'workspace'. Различные рабочие пространства владеют независимыми пулами. Без тега каждая ACP-сессия использует свой устаревший McpClientManager, снимок состояния выдает scope: 'session', и N сессий могут каждая потреблять настроенный лимит.

workspace_file_read охватывает маршруты рабочих файлов workspace text/list/stat/glob (GET /file, GET /list, GET /glob, GET /stat). workspace_file_bytes охватывает GET /file/bytes, который был добавлен позже, чтобы клиенты могли выполнить предварительную проверку поддержки сырых байтовых окон против демонов эпохи PR19. workspace_file_write охватывает маршруты мутаций текста с учетом хеша (POST /file/write, POST /file/edit). Тег write означает, что контракт маршрута существует; это не означает, что текущее развертывание открыто для анонимных мутаций. Write/edit — это строгие маршруты мутаций, требующие авторитет оператора; доверенный loopback без токена подходит. workspace_file_upload охватывает POST /file/upload, маршрут бинарного входа: тело application/octet-stream размером до MAX_UPLOAD_BYTES (50 МиБ) записывается в workspace без перезаписи — занятое имя автоматически нумеруется (name (1).ext, name (2).ext, …). Это также строгий маршрут мутации.

workspace_file_delete охватывает только POST /workspaces/:workspace/file/delete; маршрут /file/delete для устаревшего основного процесса не существует. Тело JSON представляет собой { "path": "relative/file.txt" }, а успешное выполнение возвращает { "kind": "file_delete", "path": "relative/file.txt" }. Этот строгий маршрут мутации навсегда удаляет один обычный файл из выбранного доверенного локального рабочего пространства. Каталоги и символьные ссылки отклоняются; неподдерживаемые фабрики (включая SSH) возвращают 422. Возможность описывает поддержку протокола, а не разрешение на удаление во всех рабочих пространствах. Клиенты также должны выполнить предпроверку workspace_qualified_rest_core.

Когда объявляется workspace_qualified_rest_core, та же файловая поверхность также доступна по адресам /workspaces/:workspace/file, /workspaces/:workspace/file/bytes, /workspaces/:workspace/stat, /workspaces/:workspace/list, /workspaces/:workspace/glob, /workspaces/:workspace/file/write, /workspaces/:workspace/file/edit, /workspaces/:workspace/file/upload и /workspaces/:workspace/file/delete (последний маршрут дополнительно требует workspace_file_delete).

workspace_directory_create и workspace_directory_delete независимо объявляют POST /workspaces/:workspace/directory/create и POST /workspaces/:workspace/directory/delete. Выполняйте предпроверку тега операции вместе с workspace_qualified_rest_core; старые квалифицированные демоны могут не иметь этих маршрутов. Оба являются строгими мутациями, принадлежащими доверенному активному выбранному локальному исполняемому окружению, без резервного варианта для основного процесса или аналога для устаревшего основного процесса. Создание является эксклюзивным при существующем родительском элементе; удаление является постоянным и рекурсивным.

Тот же тег также раскрывает CRUD проектных агентов с указанием рабочего пространства по адресам /workspaces/:workspace/agents и /workspaces/:workspace/agents/:agentType. Эти множественные маршруты читают или изменяют только агентов уровня проекта для выбранного рабочего пространства; запросы с областью действия global и user возвращают 400 { code: "global_scope_not_supported_for_workspace_route" }. Маршруты /workspace/agents без указания рабочего пространства сохраняют свое существующее поведение для основного рабочего пространства и остаются единственной REST-поверхностью для области действия агентов пользователя.

extension_management_v2 объявляет каталог расширений уровня пользователя и поверхность мутаций по адресу /extensions/*, а также проекции активации рабочего пространства по адресу /workspaces/:workspace/extensions/*. Артефакты являются глобальными; маршруты рабочего пространства раскрывают только чтение проекций, точные переопределения активации и обновление среды выполнения. Чтения могут быть направлены на недоверенное зарегистрированное рабочее пространство, тогда как активация, обновление и установка с областью действия рабочего пространства требуют доверенной цели. Медленные мутации используют локальные для демона операции по адресу /extensions/operations/:operationId; генерация хранилища, а не история операций, является авторитетной после перезапуска и между демонами. Опубликованная возможность workspace_extensions и маршруты /workspace/extensions/* остаются адаптером совместимости для основного рабочего пространства. Клиенты должны выполнить предпроверку extension_management_v2 и не должны определять её на основе режима демона или workspace_qualified_rest_core.

extension_git_credentials объявляет аутентифицированные HTTPS-установки Git как по адресу POST /workspace/extensions/install, так и по адресу POST /extensions/install. Клиенты должны выполнить предпроверку этого тега перед отправкой userinfo URL или credentialPersistence; старые демоны отклоняют учетные данные в URL. Тег описывает поддержку протокола бэкенда, а не наличие хранилища ключей: режим хранения сообщает о выбранном бэкенде в результате терминальной операции.

extension_local_path_install объявляет локальные для демона источники расширений как по адресу POST /workspace/extensions/install, так и по адресу POST /extensions/install. Значение source должно быть абсолютным путем, существующим на хосте демона. Относительные пути остаются неподдерживаемыми, чтобы рабочий каталог процесса демона не мог изменить идентичность источника или затенить сокращение GitHub owner/repo. Существующая операция установки копирует расширение в управляемое хранилище; она не создает ссылку на источник. Клиенты должны выполнить предпроверку этого тега, поскольку старые демоны отклоняют локальные источники.

extension_batch_activation_v2 добавляет PUT /extensions/activation и PUT /workspaces/:workspace/extensions/activation. Оба принимают от 1 до 100 имён в extensionNames, удаляют дубликаты без учёта регистра, сохраняя порядок первого появления, фиксируют изменённые цели за одну генерацию и возвращают один дескриптор операции 202. Цель не обязана быть установленной при задании enabled или disabled: её имя создаёт декларацию желаемого состояния, которая сохраняется при установке Extension с этим именем. Глобальный маршрут принимает state: "enabled" | "disabled" и записывает V2 defaultActivation; рабочий маршрут также принимает "inherit" и применяет или сбрасывает точные переопределения для выбранного доверенного рантайма. inherit не декларирует неизвестное имя, а сброс всех неизвестных имён сообщает updated: false.

extension_activation_explicit_refresh означает, что одиночные и пакетные операции активации завершаются после надёжной фиксации политики без прямого обновления активных сессий. Вызывающие стороны, которым требуется немедленное применение, должны дождаться успешной активации, а затем отправить либо синхронный запрос POST /workspace/extensions/refresh для основного рабочего пространства, который напрямую возвращает счётчики обновлений, либо асинхронный запрос POST /workspaces/:workspace/extensions/refresh для выбранного рабочего пространства, который возвращает отдельный дескриптор операции. Эти две формы не взаимозаменяемы: асинхронная операция записывает применённую генерацию по завершении полной сверки рантайма, тогда как синхронный маршрут ничего не записывает, поэтому согласователь генераций всё ещё считает это рабочее пространство ожидающим и снова обновляет его сессии на следующем проходе. Вызывающие стороны, способные обратиться к конкретному рабочему пространству, должны предпочесть асинхронную форму. Сбой обновления не приводит к откату или понижению результата активации. Демоны без этой возможности уже включают обновление рантайма в процесс активации, поэтому совместимые клиенты не должны отправлять второе обновление. Независимый согласователь генераций с интервалом 30 секунд остаётся включённым и обычно применяет зафиксированную политику на следующем проходе; сбои сверки повторяются на последующих проходах.

Контракт протокола управления Extension V2

Все маршруты используют правила bearer-аутентификации демона, описанные выше. X-Qwen-Client-Id необязателен для маршрутов мутации V2; если он указан, он должен идентифицировать клиента, зарегистрированного с одним из целевых рантаймов рабочего пространства мутации. :extensionId — это идентификатор расширения в виде строчных шестнадцатеричных символов длиной 64. :workspace разрешается сначала как точный идентификатор рабочего пространства, а иначе — как URL-кодированный абсолютный путь cwd после канонизации.

Явное обновление Extension

Тег возможности: workspace_session_refresh для опционального выбора сессий. Оба варианта POST /workspace/extensions/refresh (основной рантайм) и POST /workspaces/:workspace/extensions/refresh (выбранный рантайм) принимают:

{ "sessionIds": ["session-1", "session-2"] }

Отсутствие sessionIds сохраняет полное обновление рантайма. Предоставленный массив дедуплицируется в порядке запроса, а [] не обновляет ни сессии, ни bootstrap-кеши. Идентификаторы должны быть непустыми строками. Некорректные форматы запросов возвращают HTTP 400; неизвестные идентификаторы, включая сессии, принадлежащие другому рабочему пространству, возвращают HTTP 404 до начала работы. Принадлежность сессии проверяется только внутри разрешённого рантайма, без возврата к основному рантайму. Применяются существующие ограничения аутентификации, строгой мутации, доверия к рабочему пространству и идентификации клиента.

Основной маршрут по-прежнему возвращает HTTP 200 с { refreshed, failed }; квалифицированный маршрут по-прежнему возвращает HTTP 202 с дескриптором операции. Счётчики описывают выбранные сессии. Обновление с sessionIds не продвигает применённую генерацию всего рабочего пространства, даже если выборка охватывает все текущие сессии. Автоматическая полная сверка остаётся неизменной и может позже обновить другие сессии. Выбор не создаёт политику активации уровня сессии: общие кеши рантайма могут изменяться, а события рабочего пространства остаются общими для всего рабочего пространства.

Клиенты должны предварительно проверить поддержку workspace_session_refresh перед передачей этого поля, включая пустой массив; старые демоны могут молча игнорировать его. Существующие вызовы без этого поля не требуют новой проверки поддержки.

Состояние ресурсов рабочего пространства

Предварительно проверьте поддержку extension_state независимо. Она поддерживает только Skills; она не подразумевает управление ресурсами MCP. Оба маршрута выбирают зарегистрированный рантайм рабочего пространства и никогда не возвращаются к основному. GET следует существующим правилам чтения с проверкой доверия; PUT требует доверенного рабочего пространства.

{
  "skills": [
    { "name": "review", "state": "enabled" },
    { "name": "deploy", "state": "disabled" }
  ]
}

PUT принимает от 1 до 100 записей, включая пакет из одного элемента. Он отвергает некорректные записи, дубликаты имён без учёта регистра и неподдерживаемые группы перед постановкой в очередь. Все имена должны принадлежать установленному целевому Extension, включая в настоящее время отключённые Skills; некорректная цель приводит к сбою операции без частичной записи. Один заблокированный коммит хранилища объединяет перечисленные переопределения для точного канонического рабочего пространства. Неперечисленные Skills и другие рабочие пространства сохраняются. Нет записи настроек, декларации будущих имён или неявной активации родительского Extension.

GET возвращает v: 1, workspaceId, workspaceCwd, extensionId, name и skills. Каждый Skill имеет name, defaultEnabled, nullable workspaceEnabled, effectiveEnabled и опциональные disabledReason/lockedScope. Опциональный skillStates манифеста задаёт значения по умолчанию; отсутствующие значения по умолчанию считаются включёнными. Для активного родителя приоритет следующий: жёсткое отключение в настройках, явное включение в настройках, отключение по умолчанию в настройках, внутреннее переопределение рабочего пространства, значение по умолчанию из манифеста. Внутреннее отключение использует disabledReason: "default" и никогда не блокирует настройки. Отключённый или удалённый родитель не может быть восстановлен переопределением Skill.

Операция set_extension_state возвращает status: "updated" с упорядоченными result.resourceStates.skills; result.states сохраняет своё значение проверки обновлений. Сохранённое состояние не является доказательством того, что каждая сессия была обновлена. Демон обновляет только Skills и их контекст команд/моделей для целевой среды выполнения, включая загрузочные и активные сессии, без перезапуска несвязанных MCP/LSP/хуков. Сбои обновления после фиксации приводят к предупреждениям без отката состояния. Переопределения сохраняются после перезапуска и обновлений Extension и удаляются при деинсталляции. Клиенты не должны использовать резервный вариант API настроек Skill, который записывает настройку более высокого приоритета.

Глобальный каталог

Ответ глобального каталога имеет следующий вид:

{
  "v": 1,
  "generation": 12,
  "extensions": [
    {
      "id": "<64 lowercase hex characters>",
      "name": "demo",
      "version": "1.2.3",
      "installType": "npm",
      "defaultActivation": "enabled",
      "workspaceOverrideCount": 1
    }
  ]
}

installType опускается, если метаданные установки недоступны. defaultActivation может быть enabled или disabled. workspaceOverrideCount исключает сохранённые записи inherit.

Ответ проекции рабочего пространства имеет следующий вид:

{
  "v": 1,
  "workspaceId": "workspace-id",
  "workspaceCwd": "/absolute/workspace",
  "trusted": true,
  "desiredGeneration": 12,
  "appliedGeneration": 11,
  "extensions": [
    {
      "extensionId": "<64 lowercase hex characters>",
      "name": "demo",
      "version": "1.2.3",
      "defaultActivation": "enabled",
      "workspaceActivation": "disabled",
      "effectiveActivation": "disabled",
      "activationSource": "workspace_override"
    }
  ]
}

workspaceActivation может быть enabled, disabled или null для наследования. activationSource может быть default, workspace_override, legacy_path_rule или cli_override. desiredGeneration — это поколение долговременного хранилища; appliedGeneration — последнее поколение, которое контроллер зафиксировал как применённое к этой среде выполнения рабочего пространства, и оно может временно отставать.

Установка требует явного согласия и начальной активации:

{
  "source": "@scope/demo",
  "consent": true,
  "activation": { "scope": "user" },
  "ref": "optional-git-ref",
  "autoUpdate": true,
  "allowPreRelease": false,
  "registry": "https://registry.npmjs.org"
}

Для начальной активации только в рабочем пространстве используйте { "scope": "workspace", "workspaceId": "target-workspace-id" }; цель должна существовать и быть доверенной. Установки демона принимают источники GitHub, Git и npm. Когда поддерживается extension_local_path_install, они также принимают абсолютный путь, существующий на хосте демона. ref неприменимо к npm, ref и autoUpdate неприменимы к локальным источникам, а registry применимо только к npm. ref, autoUpdate, allowPreRelease и registry являются необязательными.

Когда поддерживается extension_git_credentials, HTTPS-источник Git может включать userinfo, например https://username:token@git.example.com/org/repository.git. credentialPersistence допустимо только с таким источником. Это может быть stored или one_time и по умолчанию равно one_time, если опущено. Режим хранения сохраняет учётные данные через гибридное хранилище секретов демона и оставляет только чистый URL репозитория в метаданных установки, поэтому extension остаётся обновляемым. Одноразовый режим не сохраняет ни URL репозитория, ни учётные данные и создаёт необновляемый snapshot; autoUpdate: true отвергается для этого режима. Предоставление поля без учётных данных в URL, предоставление недопустимых учётных данных или использование учётных данных с источниками npm, архивами, локальными путями, SSH или не-Git приводит к 400.

Ответы операций установки с учётными данными и сами операции раскрывают credentialPersistence и могут раскрывать credentialStorage как keychain или encrypted_file. Одноразовые операции опускают source; операции хранения могут вернуть чистый источник. Записи каталога/статуса снимка опускают источник, устанавливают credentialPersistence равным one_time и сообщают not updatable. Обновление завершается ошибкой extension_not_updatable; недоступный сохранённый секрет вызывает ошибку до доступа к сети с кодом extension_credential_unavailable.

Запросы активации глобальных и рабочих пространств PUT используют одинаковое тело запроса:

{ "state": "enabled" }

state может быть enabled или disabled. Запросы обновления, деинсталляции, проверки обновлений, сброса активации и обновления не имеют обязательного тела запроса.

Пакетные запросы активации используют имена Extension:

{
  "extensionNames": ["formatter", "review-tools"],
  "state": "disabled"
}

Пакетная операция для рабочего пространства также принимает "state": "inherit". Терминальные глобальные результаты содержат name и defaultActivation; результаты для рабочего пространства содержат name, workspaceActivation (null для наследования) и effectiveActivation. Некорректные имена отвергают запрос; конфликты с существующими идентификаторами Store приводят к атомарному сбою без частичной фиксации. Неизвестная цель inherit не сохраняется, поскольку сброс переопределения не должен создавать декларацию активации по умолчанию или заменять последующее согласие на установку.

Каждая принятая асинхронная мутация возвращает:

HTTP/1.1 202 Accepted
Location: /extensions/operations/<operation-id>
Retry-After: 1
Content-Type: application/json
 
{"accepted":true,"operationId":"<operation-id>"}

Мутации с указанием рабочего пространства используют тот же глобальный путь опроса /extensions/operations/:operationId. История операций является локальной для процесса, хранит только ограниченное количество терминальных записей и теряется при перезапуске демона; клиенты должны повторно прочитать каталог или проекцию рабочего пространства и сравнить поколения, когда идентификатор операции исчезает.

Снимок операции имеет следующую структуру:

{
  "v": 1,
  "operationId": "<operation-id>",
  "operation": "install",
  "status": "running",
  "phase": "preparing",
  "createdAt": 1750000000000,
  "updatedAt": 1750000000100,
  "source": "owner/repository",
  "name": "demo"
}

status переходит из queued в running, затем в succeeded, succeeded_with_warnings или failed. Во время выполнения phase может быть preparing, committing или reconciling. Успешное завершение может включать result со значением status, равным installed, enabled, disabled, updated, uninstalled, checked или refreshed; результаты согласования могут дополнительно содержать refreshed, failed и error, тогда как результаты пакетной активации содержат упорядоченные results. Проверки обновлений возвращают result.states, ключом которого является имя extension, со значениями, такими как checking for updates, update available, up to date, not updatable или error. Учётные данные и заголовки авторизации никогда не являются полями операции.

Долговременная фиксация, за которой следует неполная очистка или несогласованность среды выполнения, не сообщается как неудачная мутация. Она возвращает succeeded_with_warnings и сохраняет зафиксированный результат:

{
  "v": 1,
  "operationId": "<operation-id>",
  "operation": "uninstall",
  "status": "succeeded_with_warnings",
  "createdAt": 1750000000000,
  "updatedAt": 1750000000200,
  "result": {
    "status": "uninstalled",
    "name": "demo",
    "refreshed": 2,
    "failed": 0
  },
  "warnings": [
    {
      "workspaceId": "workspace-id",
      "workspaceCwd": "/absolute/workspace",
      "code": "reconcile_slow",
      "error": "Runtime reconciliation took 31000ms."
    }
  ]
}

Предупреждения workspaceId и code являются необязательными; workspaceCwd и error всегда присутствуют. Клиенты должны отображать предупреждения, обновлять свой каталог/проекцию и не должны слепо повторять долговременную мутацию.

Ошибки валидации и авторизации являются синхронными HTTP-ошибками, использующими { "error": "...", "code": "..." }, когда существует стабильный код. Важными случаями являются 400 invalid_extension_id, 400 invalid_extension_names, 400 invalid_extension_name, 400 invalid_extension_activation, 400 workspace_mismatch, 403 untrusted_workspace, 404 extension_operation_not_found и 429 extension_queue_full. Валидация установки также возвращает 400 для недопустимых параметров источника/ref/registry, отсутствия согласия или отсутствия/недопустимой начальной активации. Мутация, которая терпит неудачу после 202, представляется, оставаясь в истории операций, с status: "failed", error и необязательным стабильным code; распространённые коды включают extension_prepare_timeout и extension_conflict. HTTP-код 404 для операции не подразумевает откат, поскольку история операций не является долговременной.

daemon_status объявляет GET /daemon/status, консолидированный снимок диагностических данных оператора только для чтения, описанный ниже.

daemon_update объявляет глобальную для процесса поверхность GET /daemon/update, POST /daemon/update/prepare и POST /daemon/update/restart.

scheduled_task_gate объявляет необязательный gate на POST и PATCH /scheduled-tasks, а также gate и gateStatus на представлениях задач. Gate — это командная оболочка, которую владеющая сессия запускает при каждом срабатывании вне модели: выход 0 с выводом доставляет срабатывание с этим выводом, выход 0 без чего-либо в stdout пропускает его, а ненулевой выход сообщается, когда gate начинает давать сбои, а не при каждом срабатывании. gateStatus.lastOutcome может быть quiet, delivered, failed или blocked.

• Gate требует повторяющейся задачи: POST с recurring: false или PATCH, которые устанавливают gate на одноразовой задаче или превращают задачу с gate в одноразовую, отвечают 400 gate_requires_recurring; задача, уже находящаяся в таком состоянии, сохраняет свои другие изменения. Неверно сформированный gate (пустой на POST, только комментарий, более 2048 символов, символ NUL или непарный суррогат UTF-16, обертка оболочки, такая как bash -c '…', или любая часть, запущенная в фоне с помощью &) отвечает 400 invalid_gate. Проверка & является лексической и выполняется по принципу «лучшее усилие»; при сомнениях она отказывает (& в комментарии, теле heredoc или (( … ))), а gate, прошедший эту проверку, сообщается как failed, если он завершается без вывода в stdout, пока фоновая часть все еще удерживает свой stdout (вне песочницы bwrap shell, пространство PID которой завершает эту часть вместе с командой). На PATCH, gate: null или gate: "" очищает gate и его condition.
• Устаревшая задача, защищенная condition, отклоняет любой ключ gate в PATCH с кодом 409 task_legacy_unsupported, поэтому клиент отправляет gate только если изменяет его.
• Gate, записанный через эти маршруты, не получает подтверждения от сессии. Он выполняется без присмотра только там, где вызов monitor той же команды выполнился бы без запроса: под сохраненным правилом allow Monitor(...) или Bash(...), как команда только для чтения или в сессии auto или yolo. Правило deny блокирует его во всех режимах, а режим plan блокирует его; заблокированное срабатывание завершается состоянием blocked.
• Клиенты не должны отправлять gate в демон без этого тега: такой демон отбрасывает его на POST и отвечает только для шлюза PATCH с кодом 400 empty_patch.

autofix_pr_watches объявляет GET /autofix-pr/watches (основной workspace) и GET /workspaces/:workspace/autofix-pr/watches (зарегистрированный, доверенный). Каждый отвечает на /autofix-pr наблюдения клона workspace так, как перечислено в qwen autofix-pr status, считывая файлы наблюдений из основного рабочего дерева клона (.qwen/tmp), каждое открывается без следования ссылкам и без блокировки. Блокировка не берется, GitHub не опрашивается, и не выполняется ни одна команда git, кроме git worktree list, которая находит клон. Ответ — { v: 1, available, root?, now?, watches, unreadable? }: available ложно, без наблюдений, когда для workspace не найден git-репозиторий (или git не может там работать), а root — это основное рабочее дерево клона, одинаковое для двух workspace одного клона. Наблюдение содержит поля из status (Раздел 6.10 дизайна /autofix-pr), но без thisSession, worktreePath, pushTarget, gitTrusted и worktreeWork; его session — это сессия, владеющая им, которая может отсутствовать в этой демоне. Остановка наблюдения — это ответственность навыка (/autofix-pr stop <n> в владеющей сессии); эти маршруты ничего не меняют.

Условные теги. Эти функциональные теги объявляются только тогда, когда активны их переключатель развертывания, интеграция во время выполнения или условие доступности. Наличие тега означает, что документированное поведение доступно; отсутствие означает либо более старый демон, предшествующий тегу, либо текущий демон, где это условие ложно. В настоящее время:

Live Voice по умолчанию использует конечную точку Web Shell (realtime_voice_web, WS /live/web) на всех платформах. Нативный Host для macOS требует включения: только демон macOS, запущенный с QWEN_SERVE_LIVE_NATIVE_HOST=1, объявляет realtime_voice, регистрирует WS /live/host и устанавливает Host при включении Live. Без него /live/setup сообщает nativeHost: false с ошибкой install, не подлежащей повтору, а POST /live/setup/install и POST /live/setup/launch отвечают 409 live_native_host_unavailable.

Браузерный Host отвечает на host.capture_visual только пока пользователь делится экраном со страницей, о чем страница сообщает в своем приветствии как selfChecks.screenShare. Совместное использование — это отдельное, явное действие — модель спрашивает посреди хода, и getDisplayMedia требует жеста пользователя — поэтому страница удерживает поток и берет один кадр на запрос. При отсутствии совместного использования она немедленно отвечает success: false, вместо того чтобы дать запросу истечь по таймауту.

Поскольку страница не может писать в файловую систему демона, она отправляет только JPEG. Демон игнорирует любые screenshotPath, о которых сообщает браузерная аренда, и сам сохраняет изображение под выбранным им именем в том же приватном каталоге захвата, куда пишет нативный Host. Нативный Host по-прежнему сохраняет свой собственный PNG и передает путь, как и раньше.

mcp_guardrails не входит в эту условную таблицу — это всегда активный тег, объявляемый всякий раз, когда бинарный файл поддерживает новые поля бюджета /workspace/mcp, независимо от того, настроил ли оператор бюджет. Операторы, которые не установили --mcp-client-budget, также получают новые поля (со значениями budgetMode: 'off', budgets: []).

mcp_guardrail_events (issue #4175  PR 14b) объявляет типизированные события push SSE, которые отражают пересечения состояний бюджета MCP без цикла опроса. Два типа кадров поступают на GET /session/:id/events:

• mcp_budget_warning — срабатывает один раз при пересечении вверх порога 75% для reservedSlots.size / clientBudget. Повторно активируется только после того, как отношение упадет ниже 37,5% (MCP_BUDGET_REARM_FRACTION). Зеркалирует гистерезис slow_client_warning из PR 10, но на уровне менеджера, а не уровня очереди подписчика. Полезная нагрузка: { liveCount, reservedCount, budget, thresholdRatio: 0.75, mode: 'warn' | 'enforce' }. Срабатывает в режимах warn и enforce; никогда не срабатывает в режиме off.
• mcp_child_refused_batch — срабатывает в конце каждого прохода discoverAllMcpTools*, если одному или нескольким серверам было отказано, И как пакет длиной 1 на пути отказа ленивого запуска readResource. Полезная нагрузка: { refusedServers: [{ name, transport, reason: 'budget_exhausted' }, ...], budget, liveCount, reservedCount, mode: 'enforce' }. mode является литералом 'enforce', поскольку режим warn никогда не отказывает.

Оба события находятся в кольце воспроизведения SSE для каждой сессии (они несут id), поэтому клиент, переподключающийся с помощью Last-Event-ID, возобновляет работу через них; снимок на GET /workspace/mcp остается источником истины для состояния после длительного отключения. Всегда активен после объявления — нет условного переключателя. Состояние редуктора SDK (DaemonSessionViewState) предоставляет mcpBudgetWarningCount, lastMcpBudgetWarning, mcpChildRefusedBatchCount, lastMcpChildRefusedBatch для адаптеров, которым нужен простой интерфейс отображения задержки.

Маршруты

Клиенты могут выполнять feature-detection для session_turn_status и опрашивать GET /session/:id/turns/current или GET /session/:id/turns/:promptId. Эти маршруты требуют активной владеющей Session и никогда не загружают и не сканируют другое рабочее пространство. Завершенные результаты являются best-effort записями транскрипта, считываемыми из активной ветки с ограниченным сканированием; prompt_not_found означает, что результат не был найден в живой очереди, терминальном оверлее на 64 записи или ограниченном активном окне. resultText — это сырой финальный ответ родительской модели после последней границы инструмента, перед необязательным переписыванием сообщения, и он может отсутствовать. Результаты более 32 768 кодовых единиц UTF-16 включают resultTruncated: true и resultCode: "RESULT_TEXT_TRUNCATED".

GET /health

Проба живости. Форма по умолчанию возвращает 200 {"status":"ok"}, если слушатель запущен — дешево, без доступа к мосту, подходит для высокочастотных проб живости k8s/Compose.

Передайте ?deep=1 (также принимает ?deep=true или просто ?deep) для пробы живости всего демона, которая агрегирует счетчики моста по всем управляемым средам выполнения рабочих пространств, включая рабочее пространство, которое все еще дренируется (информационно, не является истинной проверкой живости):

{
  "status": "ok",
  "workspaceCount": 2,
  "sessions": 3,
  "pendingPermissions": 1,
  "activePrompts": 1,
  "activeWork": true,
  "activeWorkReporting": "full",
  "activeWorkStaleMs": 4200,
  "connectedClients": 2,
  "channelAlive": true,
  "lastActivityAt": "2026-07-15T08:30:00.000Z",
  "idleSinceMs": 120000
}

sessions, pendingPermissions и activePrompts являются суммами. activeWork равно true, если любая среда выполнения имеет принятый, но незавершенный prompt (включая prompt, ожидающий в FIFO), работающий фоновый Agent, уведомление терминала queued/in-progress Agent, фоновую оболочку или работу workflow, управляемую Session, или ход Session, принадлежащий дочернему процессу. Агрегированное удержание session охватывает обработку целей и cron, мутацию истории и continuations Monitor в очереди или выполняемые; foreground prompts остаются собственностью демона. Работающие Monitors, предложения follow-up и внешние процессы, которые реестр shell больше не может отслеживать, остаются вне поля. Это session-scoped: работа на уровне канала, еще не привязанная к сессии — запуск в полете, ожидающее восстановление, обнаружение или аутентификация MCP — не учитывается, поэтому activeWork может читать false, даже если демон все еще отказывается освобождать этот канал. Не интерпретируйте это поле как «демон можно освободить»; оно описывает только работу, принадлежащую сессии. activeWorkReporting показывает, какая часть этого булева значения действительно подтверждена: full, когда каждая живая сессия покрыта свежим отчетом от дочернего процесса, который сообщает обо всех требуемых категориях, none, когда ни одна сессия не согласовала отчетность, и partial для всего промежуточного — включая устаревший снимок или согласованный дочерний процесс, который пропускает требуемую категорию. Снимок старше трех интервалов отчетности перестает считаться покрытием: это не отчет о том, что сессия простаивает, поэтому сессия снова читается как сохраняемая, точно так же, как если бы дочерний процесс никогда не сообщал. Обычная автоматическая очистка также отключена для согласованного, но неполного дочернего процесса; дочерний процесс, который не понимает shell или session, не может безопасно авторизовать условное закрытие согласно полному текущему предикату. Полностью неподдерживаемые исторические дочерние процессы сохраняют поведение legacy cleanup, а явные close, kill, shutdown и выход из канала остаются force operations. activeWorkStaleMs — это возраст самого старого снимка, на котором основано булево значение среди покрытых сессий, и равен 0, когда ни одна сессия не покрыта; это диагностическое значение, потому что свежесть уже оценена в activeWorkReporting демоном (только демон знает согласованный ритм каждого канала). Оценка вычисляется один раз для всех управляемых сред выполнения, а не для каждой среды отдельно, а затем комбинируется — среда выполнения без сессий является вакуумно полной, и трактовка этого как доказательства позволила бы пустому рабочему пространству поручиться за несообщаемые сессии другого рабочего пространства. lastActivityAt — это последнее ненулевое время активности рабочего пространства, а idleSinceMs выводится из того же снимка. channelAlive означает, что хотя бы один канал управляемого рабочего пространства активен; это не означает, что каждое рабочее пространство здорово. connectedClients и необязательный rateLimitHits остаются счетчиками всего демона, а не суммами по рабочим пространствам.

Контроллеры перезапуска должны считать демон занятым, когда:

const busy =
  health.activePrompts > 0 ||
  health.activeWork ||
  health.activeWorkReporting !== 'full';

Отбрасывание третьего члена делает activeWork === false неотличимым от «дочерний процесс мне ничего не сообщил», что является единственным случаем, когда действие на основе этого небезопасно. Неизвестные ответы и неудачные пробы также должны предотвращать перезапуск. activePrompts остается независимым сигналом совместимости.

Эти поля являются кэшем наблюдений, а не арендой перезапуска: даже свежий, полностью оцененный, пустой ответ описывает момент выборки, и работа может начаться сразу после него. Приведенное выше правило значительно снижает риск неверного перезапуска, но не устраняет его — строгая безопасность требует забора prepare-restart, который останавливает прием новой работы, подтверждает дренаж и только затем выполняет выключение.

⚠️ Глубокое зондирование носит информационный характер, а не является реальной проверкой работоспособности или атомарным освобождением аренды. Согласованные дочерние процессы ACP публикуют снимки активной работы по всему каналу с согласованной периодичностью, и демон оценивает их актуальность в activeWorkReporting — но он никогда не завершает канал из-за отсутствия отчета, поскольку молчание одной сессии не является доказательством того, что процесс завершился. Живость транспорта и обнаружение зависших агентов — это отдельные механизмы. connectedClients подсчитывает соединения REST SSE, а не каждый транспорт ACP. Используйте повторные выборки и корректное завершение работы для освобождения простаивающих ресурсов; используйте аутентифицированный /daemon/status для диагностики транспорта и отдельных рабочих пространств. Если любой геттер управляемой среды выполнения вызывает исключение, глубокая проверка состояния завершается ошибкой с 503 {"status":"degraded","reason":"aggregation_failed"} вместо возврата частичных итогов, и журнал демона указывает на среду выполнения рабочего пространства, вызвавшую ошибку. Во время начальной загрузки, до готовности реестра сред выполнения, возвращается 503 {"status":"degraded","reason":"bootstrap"} с Retry-After: 1. Для проверки живости слушателя используйте стандартный /health без ?deep.

Авторизация: требуется при привязке к не-loopback интерфейсам и когда loopback защищен с помощью --require-auth. При обычной привязке к loopback (127.0.0.0/8, localhost, ::1, [::1]) маршрут /health регистрируется перед middleware bearer-токена, чтобы зонды k8s/Compose внутри пода могли работать без передачи токена. При привязке к не-loopback (например, --hostname 0.0.0.0) или защищенном loopback маршрут регистрируется после middleware bearer-токена и возвращает 401 без действительного токена — иначе неаутентифицированный вызывающий объект мог бы зондировать произвольные адреса, чтобы подтвердить существование qwen serve, что представляет собой утечку информации низкой степени критичности, плохо сочетающуюся со сканированием портов. Запрет CORS + белый список Host все еще применяются к исключению для обычного loopback.

GET /daemon/update, POST /daemon/update/prepare, and POST /daemon/update/restart

Эти аутентифицированные маршруты управляют установкой Qwen Code для демона независимо от выбранного рабочего пространства. Они всегда используют REST, включая запросы от SDK-клиентов с транспортом ACP-сессий. Возможность daemon_update объявляет протокол; доступность определяется возвращаемым состоянием.

GET проверяет наличие релизов без их загрузки или активации. Успешные проверки кэшируются на 15 минут, ошибки — на одну минуту; запрос ?refresh=true инициирует новую проверку. Параллельные проверки используют один и тот же поиск. Ответ содержит state (available, up-to-date, installing, ready, restarting, unavailable или error), canInstall, необязательные currentVersion и latestVersion, а также необязательные instructions и message. currentVersion идентифицирует запущенный демон, в том числе после подготовки обновления. Неподдерживаемые методы установки могут возвращать available вместе с canInstall: false и инструкциями по ручной установке.

Автоматические обновления требуют реального жизненного цикла CLI с POSIX process.execve, автономной установки или глобальной установки через npm/pnpm/yarn/bun, запускающей опубликованный лаунчер (префикс npm, принадлежащий root, поддерживается, так как этап подготовки никогда не записывает в глобальный префикс), а также настроек оператора, разрешающих general.enableAutoUpdate. Встроенные серверы, Windows, неподдерживаемые среды выполнения Node и режим разработки возвращают unavailable. Применяются только глобальные/системные настройки; рабочие пространства не могут включить установку. Соединение должно использовать основной слушатель и его токен runtime демона, либо явно доверенное loopback-развертывание без токена. Сопряженные браузеры и соединения Local Control возвращают unavailable, поскольку их учетные данные или слушатели не переживут перезапуск; их мутации обновления возвращают 403 update_connection_unsupported.

Оба POST-маршрута требуют строгих прав оператора демона для мутаций и не принимают параметров. Сервер выбирает релиз, место назначения и лаунчер; клиенты не могут указать версию или команду.

• POST /daemon/update/prepare запускает фоновую загрузку и возвращает 202 с state: "installing". Это не изменяет активную установку. Опрашивайте GET, пока состояние не станет ready; повторные попытки подготовки используют ту же операцию, а уже подготовленное обновление возвращает 200. Если автоматическое обновление недоступно, возвращается 409 update_unavailable.
• POST /daemon/update/restart требует подготовленного обновления, иначе возвращается 409 update_not_ready. Он отвечает с помощью 202 и state: "restarting" перед активацией обновления, корректным завершением работы демона и заменой процесса обновленным лаунчером. Повторные нажатия используют один и тот же перезапуск. После ответа демон повторно определяет текущий релиз: если он новее подготовленного и одношаговое обновление охватывает его, новый релиз подготавливается, а ранее подготовленный пакет отбрасывается, поэтому долгоживущий демон переходит на актуальную последнюю версию, а не на ту, которая была последней на момент первой подготовки. Новый пакет фиксируется до отбрасывания устаревшего, и это отбрасывание выполняется по принципу «best-effort»: сбой отбрасывания приводит к утечке дискового пространства, но никогда не оставляет новый пакет сиротой и не откатывается к пакету, который может быть удален частично. Затем latestVersion сообщает о новой целевой версии, при этом state остается в состоянии restarting. При сбое повторного определения или подготовки применяется подготовленный релиз; нажатие никогда не зависает на запущенной версии из-за сбоя реестра. Замена сохраняет PID, рабочую директорию, параметры CLI, привязанный порт и эффективный токен демона, очищает старые закрепления версий и не открывает заново браузер. Клиент опрашивает GET, пока currentVersion не изменится, затем перезагружает документ по URL, захваченному при запросе обновления. Поскольку подготовка выполняется после 202 и может занимать минуты, клиент отсчитывает дедлайн перезапуска от непрерывной недоступности, а не от момента нажатия: демон, который продолжает отвечать, все еще работает. Щедрый абсолютный лимит (20 минут) страхует демон, который остается доступным, но никогда не покидает состояние restarting. Этот лимит охватывает всю цепочку подготовки, а не отдельную константу тайм-аута: загрузка автономного архива последовательно пытается скачать с OSS, затем с GitHub, выделяя по пять минут на каждый источник, а получение контрольных сумм и подписей добавляет еще две минуты, поэтому одна переподготовка может потратить около двенадцати минут на скачивание и проверку перед активацией; управляемый дочерний процесс npm ограничен десятью минутами. Каждый путь отказа оставляет на экране элемент, допускающий повторную попытку, потому что зависший демон продолжает сообщать restarting, который обычно не отображается в элементах управления. После подтверждения перезапуска restarting становится постоянным до замены процесса, поэтому доступный демон, сообщающий любое другое состояние с неизменным currentVersion, означает, что замена не завершилась на новой сборке; клиент прекращает ожидание, публикует это финальное состояние и сообщает об ошибке вместо бесконечного ожидания изменения версии. Эта проверка применяется только к опросу, инициированному после подтверждения: запросы статуса и перезапуска независимы, поэтому опрос, начатый ранее, может позже доставить снимок состояния до перезапуска, и интерпретация этого как финального состояния демона привела бы к ложной ошибке и подавила бы перезагрузку страницы, которую успешное обновление все еще должно пользователю. Проверка автономного лаунчера выполняется до закрытия сервисов; неудачная проверка оставляет демон работающим. Сбои после начала завершения работы или во время замены процесса не гарантируют восстановления.

Web Shell автоматически проверяет и подготавливает доступные поддерживаемые обновления в фоновом режиме и отображает кнопку обновления рядом с версией, когда подготовленное обновление готово или когда доступное обновление содержит ручные инструкции. В состоянии с ручными инструкциями кнопка открывает всплывающее окно с инструкциями из проверки и никогда не выполняет подготовку или перезапуск. Подготовка и готовность сохраняются при перезагрузке среды выполнения рабочего пространства. Подготовленное обновление фиксирует свою цель: опрос GET, включая ?refresh=true, продолжает сообщать о подготовленном latestVersion и никогда не загружает повторно, поэтому демон, который остается активным между несколькими релизами, не вызывает лишних загрузок в фоне. Только перезапуск заново определяет цель. Обычное завершение работы демона отбрасывает подготовленную загрузку. Сбои активации оставляют демон работающим и сообщают error; следующая проверка после кэша ошибок длительностью одна минута может подготовить новую загрузку для повторной попытки. Отключение автоматических обновлений удаляет состояние готовности и очищает загрузку перед началом перезапуска. Как только перезапуск запущен, он не прерывается: пока состояние равно restarting, маршруты статуса, подготовки и перезапуска возвращаются без обращения к настройкам оператора, а очистка при завершении работы является операцией без действия, поэтому этап переключения, занимающий несколько минут, не может потерять свой пакет данных. Нажатие кнопки в состоянии готовности явно перезапускает весь демон и прерывает его активные сеансы.

GET /daemon/status

Диагностика оператора только для чтения. В отличие от /health, это обычный API демона: он регистрируется после проверки токена доступа и ограничения частоты запросов, включая привязки к локальному интерфейсу (loopback). Параметр запроса:

• detail=summary (по умолчанию) читает только состояние демона в памяти.
• detail=full также включает диагностику активных сеансов, диагностику соединений ACP, счетчики устройства потока авторизации и разделы статуса рабочего пространства.
• любое другое значение detail возвращает 400 { "code": "invalid_detail" }.

summary намеренно не запрашивает методы статуса рабочего пространства, не запускает дочерний процесс ACP и не создает сеанс. full независимо запрашивает каждый раздел рабочего пространства; тайм-аут или исключение помечает только этот раздел как unavailable и добавляет проблему workspace_status_unavailable.

Формат ответа:

{
  "v": 1,
  "detail": "summary",
  "generatedAt": "2026-06-16T00:00:00.000Z",
  "status": "ok",
  "issues": [],
  "daemon": {
    "pid": 12345,
    "uptimeMs": 3600000,
    "mode": "http-bridge",
    "workspaceCwd": "/repo",
    "qwenCodeVersion": "0.18.1",
    "daemonId": "serve-..."
  },
  "security": {
    "tokenConfigured": true,
    "requireAuth": false,
    "loopbackBind": true,
    "allowOriginConfigured": false,
    "allowOriginMode": "none",
    "sessionShellCommandEnabled": false
  },
  "limits": {
    "maxRegisteredWorkspaces": 256,
    "maxChannelControlWorkspaces": 25,
    "maxSessions": 32,
    "maxTotalSessions": 800,
    "maxPendingPromptsPerSession": 5,
    "listenerMaxConnections": 256,
    "eventRingSize": 8000,
    "compactedReplayMaxBytes": 4194304,
    "promptDeadlineMs": null,
    "writerIdleTimeoutMs": null,
    "channelIdleTimeoutMs": 0,
    "sessionIdleTimeoutMs": 1800000,
    "acpConnectionCap": 64
  },
  "runtime": {
    "sessions": { "active": 0 },
    "permissions": { "pending": 0, "policy": "first-responder" },
    "channel": { "live": false },
    "channelWorker": {
      "enabled": false,
      "state": "disabled",
      "channels": []
    },
    "transport": {
      "restSseActive": 0,
      "acp": {
        "enabled": true,
        "connections": 0,
        "connectionStreams": 0,
        "sessionStreams": 0,
        "sseStreams": 0,
        "wsStreams": 0,
        "pendingClientRequests": 0
      }
    },
    "perf": {
      "eventLoop": { "meanMs": 0, "p50Ms": 0, "p99Ms": 0, "maxMs": 0 },
      "promptQueueWait": {
        "count": 0,
        "meanMs": 0,
        "maxMs": 0,
        "lastMs": null
      },
      "pipe": {
        "inbound": { "count": 0, "totalBytes": 0, "maxBytes": 0 },
        "outbound": { "count": 0, "totalBytes": 0, "maxBytes": 0 }
      }
    },
    "activity": {
      "activePrompts": 0,
      "pendingPrompts": 0,
      "queuedPrompts": 0,
      "lastActivityAt": null,
      "idleSinceMs": null
    }
  }
}

Ответы для нескольких рабочих пространств также включают верхнеуровневые строки workspaces[] с { id, cwd, displayName?, primary, trusted }. Необязательное отображаемое имя опускается, если оно не задано, и остается только для представления; потребители статуса должны продолжать использовать id или cwd для корреляции сред выполнения.

runtime.perf необязательно. При наличии он сообщает о задержке цикла событий процесса демона, выборках времени ожидания очереди FIFO подсказок и счетчиках байтов канала связи дочернего процесса демона; задержка цикла событий дочернего процесса ACP не включается в /daemon/status.

status равен error, если любая проблема имеет серьезность ошибки, warning, если любая проблема имеет серьезность предупреждения, иначе ok. Коды проблем стабильны и включают session_capacity_high, connection_capacity_high, pending_permissions, acp_channel_down, preflight_error, mcp_budget_warning, mcp_budget_exhausted, rate_limit_hits, channel_worker_exited, channel_worker_partial_connect, channel_restore_failed и workspace_status_unavailable. В короткий промежуток времени после готовности слушателя, но до полного монтирования среды выполнения, /daemon/status может сообщить daemon_runtime_starting; если асинхронное монтирование среды выполнения завершается ошибкой, он сообщает daemon_runtime_failed, тогда как маршруты среды выполнения, не связанные со статусом, возвращают 503.

runtime.activity сообщает о активности промптов в масштабе демона. activePrompts подсчитывает сессии с выполняющимся промптом. pendingPrompts подсчитывает все принятые промпты, которые еще не завершились, включая текущий выполняющийся промпт и промпты, ожидающие в очереди FIFO. queuedPrompts подсчитывает промпты, ожидающие в очереди FIFO, которые были приняты, но не отправлены на выполнение. lastActivityAt — это временная метка ISO 8601 последнего начала/завершения промпта или запуска сессии; null если демон не обрабатывал никакой активности с момента загрузки. idleSinceMs вычисляется из lastActivityAt во время формирования ответа.

limits.memory является аддитивным и сообщает разрешенные значения памяти демона: обязательное enforced: false, объект childHeap (mode: off, observe или admit; admissionEnforced, истинно только для управляемых admit; maxConcurrentChildren и perChildCeilingMb, оба null под mode: 'off', который ничего не моделирует — и perChildCeilingMb дополнительно null везде, где раздел не может быть смоделирован в пределах modeled.minChildHeapMb — либо пул не может покрыть один дочерний процесс при этом минимальном значении, либо максимальное значение окажется ниже него после ограничения до modeled.legacyChildCeilingMb, что равно floor(available / 2) и поэтому падает ниже минимального значения на хостах с менее чем 1024 МБ. Оно никогда не равно 0, и maxConcurrentChildren равно 0 в этих случаях, поскольку хост, который не моделирует раздел, дает вычисленный ответ, а не отсутствующую модель; и refusals, запуски, которые превысили бы смоделированное ограничение), configuredBudgetMb, effectiveBudgetMb (настроенное значение, ограниченное разрешенной памятью cgroup/хоста), budgetSource (flag / derived), availableMemoryMb, availableMemorySource (constrained / host), insufficientMemory и объект modeled, содержащий rootReserveMb, childPoolMb, minChildHeapMb, maxChildHeapMb и legacyChildCeilingMb (консервативная модель максимального значения, которое дочерний процесс ACP получает сегодня, и которое может быть ниже реального значения). runtime.memory дополнительно сообщает registeredWorkspaces (количество регистраций — записи рабочего пространства, не удаленные, включая находящиеся в процессе завершения, переходящие или заблокированные; это не количество активных дочерних процессов), activeAcpChildren (дочерние процессы ACP, управляемые демоном, с живым незавершаемым каналом — включает переходящие или заблокированные записи, но исключает рабочее пространство, для которого начато завершение процесса, даже если дочерний процесс еще не вышел; не рабочие процессы каналов, потомки MCP или незарегистрированные резервирования запусков), childRssCoverage (active_children — каждый дочерний процесс ACP с живым каналом, то есть набор, который подсчитывает activeAcpChildren; более старые демоны отправляют primary_only), объект children, описанный ниже, и объект modeled, содержащий recommendedShareAtRegisteredMb (null, когда не зарегистрировано ни одно рабочее пространство) и recommendedShareAtActiveMb (null, когда ни один дочерний процесс не активен). Каждая доля ограничена устаревшим максимальным значением для дочернего процесса и установлена как минимум по размеру кучи дочернего процесса только тогда, когда максимальное значение это позволяет — на малых хостах максимальное значение находится ниже минимального, поэтому доля × количество может превышать пул дочерних процессов. Воспринимайте долю как рекомендательную, а не как разделение пула. Определение размера кучи дочернего процесса остается рекомендательным: ни один аргумент запуска дочернего процесса не выводится из этих значений. Опциональный admit применяет смоделированное количество одновременных дочерних процессов, тогда как по умолчанию observe только фиксирует потенциальные отказы. runtime.memory.committedAcpChildren подсчитывает управляемые резервирования ACP и присоединенные дочерние процессы, включая завершающиеся дочерние процессы до освобождения реестра; он равен null, когда управляемый реестр недоступен. childHeap моделирует фиксированное разделение modeled.childPoolMb — каждый дочерний процесс получил бы одинаковый perChildCeilingMb, поэтому смоделированная сумма остается внутри пула, а не накапливается, как это было бы с долей на запуск. Воспринимайте refusals только как давление допуска: значение 0 не означает, что разделение безопасно применять, потому что дочерние процессы работают на гораздо большем максимальном значении, полученном от хоста, поэтому нагрузка, требующая больше старого пространства, чем perChildCeilingMb, здесь считается здоровой и терпела бы неудачу только после применения разделения. Две дополнительные причины, почему ненулевое количество не обязательно означает проблему с емкостью: решение о допуске учитывает завершающийся дочерний процесс до его выхода, поэтому на демоне, уже достигающем maxConcurrentChildren, каждая замена канала бронирует отказ во время окна перекрытия; и на хосте, слишком малом для моделирования раздела, maxConcurrentChildren равно 0, поэтому refusals равно общему количеству запусков ACP, а поле insufficientMemory объясняет это. В admit модель с нулевым количеством слотов приводит к сбою при запуске. Полностью управляемый демон, столкнувшийся с исчерпанием емкости, может освободить один наименее недавно использованный пустой ACP без живых сессий или ожидающих задач, дождаться отслеживаемого освобождения, затем повторить попытку допуска один раз перед запуском. Загруженные сессии остаются защищенными; регистрация рабочего пространства и сохраненная история сохраняются. Счетчик refusals подсчитывает попытки отказа в допуске, включая первоначальный отказ, за которым последовало успешное освобождение, а не окончательные видимые пользователю ошибки. Исчерпанная емкость возвращает REST HTTP 503 с code: "acp_child_capacity_exhausted", maxConcurrentChildren и committedAcpChildren (исключая отклоненное резервирование), без Retry-After. JSON-RPC ACP использует -32603 с data.errorKind, несущим этот код, data.httpStatus: 503 и те же счетчики. Проверенный откат создания автономного процесса до отправки сохраняет standalone_creation_rolled_back, его идентификатор сессии и возможность повторной попытки, и вкладывает код емкости и счетчики в capacity; неопределенные результаты создания сохраняют свою существующую семантику восстановления. Клиентам следует прекратить автоматические повторные попытки из-за проблем с емкостью и сохранить черновик или выбранную сессию для ручной повторной попытки. На обычном пути runQwenServe бюджет определяется до создания приложения bootstrap, поэтому limits.memory уже заполнено во время окна bootstrap. Оно равно null только на путях, которые не определяют бюджет (например, прямое встраивание, обходящее runQwenServeImpl). Тип SDK допускает null, поэтому корректные клиенты справляются с этим.

runtime.memory.children является аддитивным в рамках этого блока и сообщает агрегированный RSS среди дочерних процессов, указанных в childRssCoverage: rssBytes (их суммированный самостоятельно сообщаемый RSS), sampled (сколько из них дали показания) и oldestReadingAgeMs (возраст самого старого показания в сумме, чтобы вызывающий мог понять, насколько далеко друг от друга были взяты части). Знаменатель для sampled — это соседний activeAcpChildren, а не повторяется внутри блока; когда sampled ниже, rssBytes представляет собой нижнюю границу, а не общее значение. Выборка выполняется только при наличии активного наблюдателя SSE/WS, поэтому запрос статуса к демону, с которым никто не устанавливает потоковое соединение, сообщает sampled: 0 даже при наличии живых дочерних процессов — activeAcpChildren рядом с ним делает этот разрыв видимым, и rssBytes: 0 вместе с sampled: 0 никогда не означает измеренный ноль. oldestReadingAgeMs равно null, когда ничего не было выборочно проверено, а также когда каждый источник данных является мостом, предшествующим этому полю, поэтому оно никогда не означает «актуальное». Воспринимайте сумму одновременно как завышенную и заниженную оценку: суммирование RSS каждого процесса дважды учитывает страницы, разделяемые дочерними процессами, при этом каждый дочерний процесс сообщает только о своем собственном процессе, поэтому его потомки MCP и все рабочие процессы каналов отсутствуют. Это не память дерева демона. Поле является необязательным в зеркале SDK, потому что демоны, сообщающие primary_only, никогда не отправляют его.

runtime.memory.children.heap аддитивен в рамках этого блока и сообщает о максимальных значениях V8 old-generation за время жизни каждого дочернего процесса ACP, агрегируемых как максимум, а не сумма: peakOldGenerationBytes, peakLiveSetBytes, peakTotalHeapBytes, majorGcCount, majorGcMs, unclassifiedSpaceNames и reported. Потолок кучи применяется к каждому дочернему процессу отдельно, и пики достигались в разное время, поэтому общее значение не ответило бы ни на один вопрос; каждое поле представляет собой независимый максимум по всем отчитывающимся дочерним процессам, а не портрет одного дочернего процесса, и потолок для каждого дочернего процесса оценивается по каждой оси отдельно. reported показывает количество из sampled, которые внесли вклад, и это число меньше, если некоторые дочерние процессы были запущены до появления этих полей. Все значения в байтах относятся к old generation — тому, что фактически ограничивает --max-old-space-size, — а не только к old_space, поскольку дочерний процесс может исчерпать свой потолок при нескольких мегабайтах old_space, в то время как large_object_space содержит всё остальное. peakOldGenerationBytes — это зарезервированные байты, которые растут вместе с потолком, выделенным дочернему процессу, поэтому воспринимайте их как верхнюю границу потребности нагрузки, а не как её точную потребность; peakLiveSetBytes — это то, что выживает после полной сборки мусора (major GC) и не зависит от потолка, что делает это значение показателем того, что дочерний процесс не помещается в него; воспринимайте его как верхнюю границу, а не как точный набор живых объектов, так как события GC поступают асинхронно, и всё, что было выделено между сборкой и чтением, учитывается. peakLiveSetBytes равно 0 до тех пор, пока не будет зафиксирована полная сборка мусора, что является отсутствием данных, а не измерением. unclassifiedSpaceNames — это объединение пространств кучи, которые ни один отчитывающийся дочерний процесс не смог классифицировать; V8 переименовывает и добавляет пространства между версиями, неизвестные пространства исключаются из сумм, и такое исключение приводит к занижению значений, поэтому непустой массив означает, что значения в байтах неполны и их нельзя рассматривать как полное измерение. Весь объект равен null, никогда не обнуленному объекту, когда ни один выборочный дочерний процесс не предоставил данных; если наблюдатель SSE/WS не подключен, ничего не выбирается, поэтому это обычное состояние, а не краевой случай. Всё это носит наблюдательный характер: ничто здесь не определяет размер дочернего процесса, не отказывает в запуске и не перемещает limits.memory.enforced с false.

runtime.memory.pressure аддитивен в рамках этого блока и сообщает о давлении памяти самого корневого процесса демона: mode (off / observe), level (normal / soft / hard / critical), source (rss / heap / unknown), ratio и шесть исходных значений, из которых рассчитываются коэффициенты — rssBytes, rssRatio, availableBytes, heapUsedBytes, heapRatio, heapLimitBytes. ratio — это большее из rssRatio и heapRatio, а source указывает, какое именно из них было больше; при равенстве сообщается rss. availableBytes — это limits.memory.availableMemoryMb в байтах — намеренно обнаруженное значение cgroup/хоста, а не effectiveBudgetMb, потому что процесс завершает реальный лимит, а не политическое значение оператора. source: "unknown" означает, что ни один знаменатель не был измерим, и это не следует трактовать как здоровое состояние; level равно normal в этом случае только потому, что классифицировать нечего. Значения относятся только к корневому процессу демона: это собственные показатели memoryUsage() данного процесса, поэтому рост дочерних процессов не влияет на них. runtime.memory.children сообщает об этих показателях отдельно, и ни одно из значений не отражает память всего дерева процессов. Оба режима сообщают весь блок; только observe дополнительно поднимает предупреждение daemon_memory_pressure без пути в сводку статуса, поэтому off оставляет верхнеуровневый status неизменным. Ничто не исправляется ни в одном из режимов. Поле является необязательным в зеркале SDK, потому что демоны, выпущенные до runtime.memory, отправляют блок без него.

limits.maxRegisteredWorkspaces аддитивен и сообщает об установленном пределе регистрации пользователей (по умолчанию 256, настраиваемый от 1 до 256). limits.maxChannelControlWorkspaces сообщает о независимом пределе владельцев управления/восстановления, равном 25, для стандартного демона, даже когда каналы отключены. Пользовательские контроллеры объявляют это поле только тогда, когда они применяют его. Эти поля присутствуют в ответах bootstrap и ready; более старые демоны могут их опускать. Контроллер канала отвергает переходные объединения владельцев, превышающие его предел, с помощью 409 channel_control_workspace_limit_reached перед созданием кандидатов рабочих процессов; начальное объединение во время загрузки, превышающее предел, приводит к сбою запуска до публикации слушателя, поэтому у него нет HTTP-интерфейса. Емкость регистрации не определяет таймаут канала SDK.

limits.maxTotalSessions аддитивен. null означает, что эффективный глобальный предел новых сессий для демона отключен. Когда установленная емкость регистрации (по умолчанию 256, настраиваемая через QWEN_SERVE_MAX_WORKSPACES или встроенный maxRegisteredWorkspaces) превышает 25, а --max-total-sessions опущен, стандартный демон использует фиксированное общее значение 800, даже с одним рабочим пространством при запуске. При емкостях регистрации 25 или меньше несколько рабочих пространств при запуске/восстановлении с конечным maxSessionsPerWorkspace вычисляют эффективное общее значение один раз как maxSessionsPerWorkspace * workspaceCount по тому же количеству запуск+восстановление; одно рабочее пространство при запуске или восстановлении сохраняет неограниченный параметр по умолчанию. Явные общие пределы, включая отключенные значения, имеют приоритет. Последующая динамическая регистрация не пересчитывает общий предел. Прямые внедрения createServeApp должны предоставлять свою собственную политику совместного допуска. Когда установлено, оно ограничивает создание новых сессий во всем демоне и сообщает о сбоях общего предела с существующей формой ошибки session_limit_exceeded плюс scope: "total".

runtime.channel.live сообщает о канале моста ACP внутри демона. Это не рабочий процесс адаптера каналов. Каналы, управляемые демоном, используют runtime.channelWorker, чей state является одним из disabled, starting, running, exited, failed или stopped. Когда рабочий процесс достигает running, а затем завершается, /daemon/status оставляет демон в сети и сообщает код проблемы предупреждения channel_worker_exited.

Запуск рабочего процесса канала, управляемого демоном, от явного qwen serve --channel ... остается быстрым отказом (fail-fast) и имеет приоритет над сохраненными настройками запуска. Запуск без флагов восстанавливает serve.channels из каждого доверенного зарегистрированного рабочего пространства, каждое из которых предоставляет список в своих настройках области рабочего пространства. Восстановленные имена образуют один набор выбора, владельцы которого определяются обычным образом, при этом рабочее пространство, перечислившее имя, разрывает иначе неоднозначную связь владения. Эта атрибуция запуска действует столько, сколько работает демон: PUT /workspace/channel, повторно включающий такое имя, определяет его так же, как при запуске, даже если набор выбора был остановлен между тем. Имя, предоставленное не основным рабочим пространством, отбрасывается с журналом, идентифицирующим его, когда оно не может быть определено, чтобы устаревшая запись одного рабочего пространства не блокировала другие; имя, перечисленное основным рабочим пространством, все еще приводит к общему сбою восстановления, независимо от того, перечисляет ли его другое рабочее пространство тоже. all остается только для основного рабочего пространства: он игнорируется и сообщается где угодно еще.

Доверенное не основное рабочее пространство, зарегистрированное после запуска, также восстанавливает свои собственные serve.channels, загружая среду выполнения канала и резервируя аренду сервиса канала, если ничто другое не сделало этого. Это восстановление:

• происходит один раз за запуск демона — записывается, как только рабочее пространство запрашивает что-либо, — поэтому последующее удаление и повторная регистрация или повторное материализование доверия не отменяют действие оператора, который остановил один из этих каналов между тем;
• не происходит при явном выборе --channel, который не расширяется ни одним рабочим пространством, зарегистрированным позже;
• не происходит после того, как DELETE /workspace/channel перестал размещать, до тех пор, пока PUT /workspace/channel снова не зафиксирует выбор или демон не перезапустится;
• оставляет зафиксированный выбор all без изменений;
• добавляет имена этого рабочего пространства в зафиксированный выбор одним изменением, восстанавливая по одному имени за раз. В отличие от загрузки, которая отбрасывает имя, которое не может быть размещено, но сохраняет остальные, имя, которое невозможно атрибутировать, приводит к тому, что весь список этого рабочего пространства не восстанавливается, а ошибка регистрируется и сообщается так, как описано ниже.

Регистрация вообще не ожидает управления каналами. Восстановление ставится в очередь на полосу управления каналами, а ответ отправляется без ожидания завершения этой операции; то же самое касается сверки (reconcile), которую вызывает изменение регистрации или доверия для каналов, уже размещаемых демоном. Поэтому воркер, который никогда не становится готовым, задерживает только работу с каналами, поставленную в очередь после него, но никогда — другую регистрацию или сверку доверия. Обратная сторона: 201 из POST /workspaces не означает, что каналы этого рабочего пространства запущены, или что уже размещаемый канал, которым он владеет, завершил перезапуск; для этого читайте GET /workspace/channel.

Без явного выбора, восстановления при загрузке serve.channels или регистрации, подобной описанной выше, загрузка среды выполнения каналов остается ленивой.

Сохраненные имена запуска должны быть непустыми, не содержать пробелов в начале или конце и не включать небезопасные управляющие или невидимые символы. Недействительные записи пропускаются по отдельности и логируются по индексу массива; запуск не обрезает их в другие имена экземпляров и не переписывает настройки. Аргументы воркера используют --channel=<value>, сохраняя ведущий дефис как часть имени.

Недействительное поле запуска или ошибка валидации либо аренды (lease) до начала работы воркеров пропускает автоматическое восстановление, при этом в лог записывается идентификатор serve.channels, а несвязанные настройки остаются в силе. Неудачный запуск воркера позволяет демону продолжить работу после успешной очистки. Глобальные таймауты запуска среды выполнения и неподтвержденные остановки воркеров следуют существующему пути обработки ошибок запуска; аренда сохраняется, пока завершение работы воркера не подтверждено. Управление каналами сообщает об сохраненных настройках запуска и фактическом состоянии среды выполнения.

Некоторые имена serve.channels, которые демон не запустил, не просто логируются, а репортятся. Такое имя никогда не присоединяется к зафиксированному выбору, поэтому ни один снимок состояния воркера его не содержит. Сообщаются три случая:

• настроенный выбор запуска, воркер которого не смог запуститься, на пути загрузки, который оставляет демон обслуживающим запросы без своих каналов;
• имя, отброшенное разрешителем прав собственности при загрузке во время атрибуции рабочему пространству, репортится против каждого рабочего пространства, которое его перечислило;
• каждое имя, все еще не размещенное после сбоя восстановления поздней регистрации.

Они появляются в двух местах:

• /daemon/status сообщает одно предупреждение channel_restore_failed на каждое рабочее пространство, называя каждый канал вместе с его ошибкой. Это полный набор данных, который присутствует также в ответе bootstrap, единственном доступном во время записи записей загрузки. На каждое рабочее пространство называется максимум 64 канала, каждое имя ограничено 128 символами, с and <n> more, если список длиннее;
• в GET /workspaces/:workspace/channels этого рабочего пространства канал указан с runtime: { state: "error", lastError } вместо stopped, где lastError — это собственная ошибка запуска адаптера, когда воркер сообщил об ошибке для этого канала, иначе — ошибка попытки. Этот набор данных формируется из собственной области настроек каналов рабочего пространства, поэтому он может содержать только те имена, которые определяет эта область — имя, которое не конфигурирует ни одно зарегистрированное рабочее пространство, или чья конфигурация находится в другом рабочем пространстве, здесь не имеет строки и репортится только через /daemon/status.

Все остальное, что оставляет имя serve.channels неразмещенным, диагностируется только в логе демона: имя, потерянное из-за того, что весь список был нечитаемым или недействительным, список вторичного рабочего пространства, отброшенный потому, что первичное выбрало all, позднее восстановление, пропущенное потому, что зафиксированный выбор равен all, и список удаленного (SSH) рабочего пространства. Для этих случаев проверяйте логи демона.

Отчет действует до тех пор, пока канал не будет размещен — этим рабочим пространством или более поздним восстановлением из другого — до тех пор, пока его рабочее пространство не перестанет быть зарегистрированным, или пока оператор не предпримет действие: запуск, остановка или перезапуск POST на канале, PUT/DELETE /workspace/channels/:name, или PUT/DELETE /workspace/channel, изменяющий выбор. PUT /workspace/channels/:name/startup не очищает отчет: он переписывает serve.channels, ничего не говоря о неудачной попытке. Отчет хранится в памяти: перезапущенный демон снова выполняет восстановление и сообщает о результатах этой попытки. Текст ошибки очищается от учетных данных и ограничивается так же, как это делает лог демона.

После того как воркер достиг состояния готовности, неожиданные выходы перезапускаются супервизором serve в рамках ограниченной политики: до 3 попыток перезапуска в окне 5 минут, с задержками 1с, затем 5с, затем 15с. Воркер отправляет IPC heartbeat каждые 15 секунд; если heartbeat не наблюдается в течение 45 секунд, супервизор считает воркер устаревшим (stale), убивает его, записывает staleHeartbeatAt и использует тот же путь перезапуска.

runtime.channelWorker может включать дополнительные операционные поля: requestedChannels, pid, startedAt, exitCode, signal, error, restartCount, lastExitAt, lastRestartAt, nextRestartAt, lastHeartbeatAt, staleHeartbeatAt, startupFailures и startupFailuresTruncated. Каждая ошибка запуска содержит channel, phase (в настоящее время connect), необязательное поле code, предоставляемое адаптером, и message с удаленными учетными данными. Для текущей генерации воркера сохраняется не более 64 ошибок; флаг усечения означает, что было зафиксировано больше ошибок. Поле code является диагностическим и не представляет собой стабильную классификацию между адаптерами. Поле restartCount — это общее количество попыток перезапуска, выполненных этим процессом serve; запущенный воркер с restartCount > 0 считается исправным, если нет других проблем. Запущенный воркер, чьи requestedChannels включают имена, отсутствующие в channels, сообщает о channel_worker_partial_connect.

В демоне с несколькими рабочими пространствами (при повторении --workspace) поле runtime дополнительно включает channelWorkers[] — по одной записи на каждое рабочее пространство-владелец, каждая из которых является снимком channelWorker с аннотациями workspaceId, workspaceCwd и primary. Поле channelWorker остается заполненным как снимок основного рабочего пространства для обеспечения совместимости. Демоны с одним рабочим пространством не содержат поле channelWorkers[].

Управление каналами под управлением демона

Возможность channel_control объявляет ресурс выбора среды выполнения. Этот ресурс является общедоступным для всего демона, хотя его путь совместимости использует единичный префикс /workspace. Выборы среды выполнения не сохраняются постоянно и не изменяют параметр --channel времени загрузки демона.

GET /workspace/channel возвращает неизменяемый снимок менеджера:

{
  "enabled": true,
  "selection": { "mode": "names", "names": ["telegram", "feishu"] },
  "pendingSelection": { "mode": "names", "names": ["telegram"] },
  "transition": "reconciling",
  "workers": [
    {
      "workspaceId": "primary-id",
      "workspaceCwd": "/work/primary",
      "primary": true,
      "enabled": true,
      "state": "running",
      "channels": ["telegram"],
      "pid": 1234
    }
  ]
}

Поле selection равно null при отключенном состоянии. Поле pendingSelection присутствует только во время изменения. Поле transition принимает одно из значений: idle, starting, reconciling, stopping или rolling_back.

PUT /workspace/channel строго контролируется и принимает ровно один выбор:

{ "selection": { "mode": "all" } }

{ "selection": { "mode": "names", "names": ["telegram", "feishu"] } }

Имена обрезаются и дедуплицируются без сортировки; пустой массив имен недопустим. Поле all остается доступным только для основного рабочего пространства. Переход от отключенного к включенному состоянию возвращает 201; идемпотентный запрос PUT или замена возвращают 200. Ответ имеет тип { changed, replaced, partial, state }. Равный выбор оставляет исправные воркеры на месте, но восстанавливает равный выбор, если его воркер остановлен или завершился с ошибкой.

Операция DELETE /workspace/channel строго контролируется и идемпотентна. Она возвращает { changed, state }; успешное состояние — отключено. Операция POST /workspace/channel/reload также строго контролируется, повторно считывает настройки, заново разрешает группы рабочих пространств и принудительно согласовывает зафиксированный выбор. При отключенном состоянии она возвращает 409 channel_worker_not_enabled. Возможность channel_reload динамически объявляется только тогда, когда менеджер имеет зафиксированный, перезагружаемый выбор.

Каждая операция включения, замены, перезагрузки, остановки и завершения работы демона попадает в одну очередь жизненного цикла FIFO. Метод GET не ожидает эту очередь. Группы рабочих пространств, чей упорядоченный выбор не изменился, остаются онлайн. При сбоях замены предпринимается попытка остановить недавно запущенные воркеры и восстановить предыдущий зафиксированный выбор. Клиенты должны проверять rolledBack, rollbackError и state, так как очистка или восстановление также могут завершиться ошибкой. Демон сохраняет аренду PID канала обслуживания на протяжении всей транзакции и не освобождает ее до подтверждения выхода всех соответствующих дочерних процессов.

Стабильные ошибки управления:

• 400 invalid_channel_selection, channel_workspace_mismatch или ambiguous_channel_workspace
• 403 untrusted_workspace
• 409 channel_service_conflict, channel_worker_not_enabled или channel_control_workspace_limit_reached
• 500 channel_worker_stop_failed
• 502 channel_worker_start_failed, с rolledBack и необязательным очищенным от учётных данных rollbackError
• 503 daemon_draining

Строгие записи из первичного запроса без токена, который достигает шлюза без авторитетной обратной связи через loopback, возвращают 401 token_required до выполнения кода управления. Отсутствующие или недействительные настроенные учетные данные и неподтвержденные учетные данные Local Control отклоняются раньше с простой ошибкой 401 Unauthorized. Первичные запросы с авторитетной обратной связью через loopback выполняются нормально. После начала обработки запроса отключение HTTP-клиента не отменяет транзакцию жизненного цикла; клиенты могут безопасно повторить тот же запрос PUT.

Для 502 channel_worker_start_failed ответ может также включать startupFailures[] и startupFailuresTruncated. Каждый сбой добавляет доверенное значение workspaceCwd для попытки запуска воркера. Эти поля описывают неудачную транзакцию, тогда как state описывает текущее состояние после отката; последующий запрос GET не сохраняет информацию о неудачной попытке. Частично подключенный воркер вместо этого возвращает успех и раскрывает свои сбои в снимке воркера. Явный запуск с --channel без подключенного адаптера приводит к ошибке запуска. Сбой запуска, вызванный настройками, фиксируется в журнале и позволяет демону продолжить работу после успешной очистки с учетом глобального таймаута запуска среды выполнения. Невозможность подтвердить очистку сохраняет обычное поведение при сбое запуска и аренду сервиса.

Файл qwen channel status без --daemon-url продолжает читать метаданные pidfile; с --daemon-url он читает GET /workspace/channel. Во время окна перезапуска принадлежащий serve файл pidfile остается зарезервированным, но поле workerPid опускается, чтобы клиенты не отображали устаревший процесс воркера. В демоне с несколькими рабочими пространствами файл pidfile также содержит дополнительный массив workers[] (для каждого рабочего пространства: workspaceId / workspaceCwd / channels / активный workerPid), в то время как верхнеуровневые поля channels (объединение) и workerPid (основной) остаются заполненными для старых читателей; демоны с одним рабочим пространством сохраняют исходную форму одного воркера. Стандартный вывод и ошибки воркера перенаправляются в журнал демона с удалением токенов доступа, чувствительных значений переменных окружения воркера и учетных данных URL прокси.

Управление каналами рабочего пространства

Возможность channel_management объявляет конфигурацию каналов и управление средой выполнения в масштабе рабочего пространства. Маршруты с единичным префиксом /workspace направлены на основную среду выполнения. Поле /workspaces/:workspace разрешает точную зарегистрированную доверенную среду выполнения и никогда не выполняет резервный переход к основной среде выполнения.

Обнаружение только для чтения использует:

• GET /workspace/channel-types
• GET /workspace/channels
• GET /workspace/channels/events
• GET /workspaces/:workspace/channel-types
• GET /workspaces/:workspace/channels
• GET /workspaces/:workspace/channels/events

GET .../channels/events возвращает журнал событий канала (Channel) для разрешенного рабочего пространства в виде { "events": [...], "truncated": boolean } с Cache-Control: no-store, а также необязательный элемент channelLinkMeta: карту от имени экземпляра канала к метаданным ссылки без секретов (type и baseUrl, каждый из которых присутствует только если настроен как строка, а для каналов GitHub — разрешенный webOrigin — источник веб-интерфейса, который клиенты должны напрямую конкатенировать вместо повторного вывода из корневого URL API). Метаданные разрешаются из объединенных системных, пользовательских и рабочих настроек, с которыми работают воркеры каналов — локальный список управления областью не содержит каналы, настроенные в другой области — и фильтруются по каналам, чей разрешенный cwd принадлежит запрошенному рабочему пространству, поэтому одно рабочее пространство никогда не получает метаданные каналов другого рабочего пространства. Это позволяет клиентам связывать строки журнала (например, ссылку на PR или issue GitHub) даже для каналов, унаследованных из пользовательских или системных настроек. Элемент полностью опускается, когда ни один канал не разрешается, и старые демоны никогда его не отправляют; сбой чтения настроек приводит к отсутствию этого элемента, а не к сбою чтения журнала. Каждое событие записывает действие канала — принятое или пропущенное входящее сообщение (с машинной причиной: reason_filter, mention_required, duplicate, отклонение по фильтру отправителя, github_api_error), ветку GitHub, обработка которой завершилась ошибкой и которую он прочитает снова (failed с github_api_error: ошибка GitHub или локальная ошибка, когда канал не может читать или писать свое собственное состояние, либо одна из задач ветки не завершена), результат публикации, переход входящей задачи или результат опроса — и никогда не содержит текст сообщения. Опрос GitHub, который фильтрует более 20 уведомлений, записывает первые 20 отдельно и одну дополнительную строку reason_filter, где detail.filtered подсчитывает остальные, чтобы закрепленный курсор опроса не переполнял журнал повторами одного и того же пакета. Пока курсор удерживается, комментарий, повторно считанный опросом, записывается как duplicate или mention_required один раз за окно, а сбоящая ветка — как github_api_error при первом сбойном опросе в окне и на каждом десятом сбойном опросе (при ограничении частоты или сбое учетных данных: первый и каждый десятый опрос), и один раз, когда она пропускается. Строки «один раз за окно» отслеживаются под максимум 8192 ключами; строка, чей ключ больше не помещается, записывается при каждом опросе. Параметры запроса: limit (1–500, по умолчанию 100), type (разделенные запятыми inbound, outbound, task, poll), channel (повторите параметр один раз для каждого имени экземпляра) и since (ISO 8601). Маршрут не требует прав оператора. Чтения журнала выполняются асинхронно и с ограничениями: текущий журнал плюс один ротированный файл на канал, 256 КиБ на файл, 4 МиБ на запрос, 32 файла на запрос, самые свежие первыми. Метаданные ссылок дополнительно синхронно читают снимок объединенных настроек без побочных эффектов (несколько небольших JSON-файлов, разрешенных относительно эффективной среды выполнения); это декорация best-effort, поэтому любой сбой опускает элемент вместо сбоя чтения журнала. truncated равно true, если лимит записей или любое ограничение чтения обрезали результат, включая случай, когда журнал выше окна хвоста на файл. Рабочее пространство без журнала пока возвращает пустой список; директорию области, которую невозможно прочитать, отвечает 5xx вместо пустого списка.

Каталог отмечает типы, поддерживаемые этим API управления, с помощью manageable: true. Снимки экземпляров включают ревизию, отредактированные метаданные наличия секретов, состояние запуска и состояние выполнения; литеральные секреты никогда не возвращаются. Снимки каналов используют Cache-Control: no-store.

Дескрипторы полей могут раскрывать метаданные вложенных объектов через properties. Числовые дескрипторы могут использовать exclusiveMinimum для открытой нижней границы и maximum для включительной верхней границы. Сохраненное число вне вновь объявленной границы все еще принимается, когда клиент повторно отправляет его без изменений, поэтому объявление границы не блокирует несвязанные правки существующего канала; значение, которое клиент действительно изменил, должно удовлетворять обеим границам. Дескрипторы строк и секретов могут использовать multiline, чтобы предложить клиентам многострочную текстовую область; типы дескрипторов позволяют это только для полей верхнего уровня. Клиенты, которые не отображают рекламируемый тип поля, должны сохранять существующее конфигурационное значение вместо принудительного преобразования или удаления, а клиент, отображающий поле multiline в однострочном элементе управления, должен сохранять сохраненное значение дословно вместо записи обратно входного значения с удаленными символами новой строки. Объектные поля не могут быть обязательными, а вложенные свойства не могут быть секретами или полями, разрешаемыми через окружение; эти протоколы управления остаются только на верхнем уровне. Вложенное свойство required проверяется только тогда, когда родительский объект присутствует в записи; опускание родительского объекта оставляет его вложенные требования непроверенными. Записи конфигурации заменяют сохраненное значение каждого поля целиком, поэтому сохранение объекта означает повторную отправку сохраненного объекта; демон не объединяет частичные объекты.

Записи конфигурации используют оптимистичное конкурентное управление и строгий шлюз авторитета оператора:

• PUT /workspace/channels/:name
• DELETE /workspace/channels/:name
• PUT /workspace/channels/:name/startup
• эквивалентные маршруты /workspaces/:workspace/...

Каждая мутация настроек включает expectedRevision. Запросы Upsert содержат объект config и могут содержать явные операции с секретами: preserve, replace или clear. Конфигурация канала не может выбрать рабочую директорию вне разрешенного рабочего пространства.

Действия во время выполнения строго ограничены запросами POST к .../channels/:name/start, stop или restart. Они выполняются только над воркером, принадлежащим разрешенному рабочему пространству.

Управление сопряжением доступно только для экземпляров, настроенных с политикой отправителя pairing или групповой политикой:

• GET .../channels/:name/pairing-requests
• POST .../channels/:name/pairing-requests/approve с { "code": "..." }
• GET .../channels/:name/pairing-approvals
• DELETE .../channels/:name/pairing-approvals с использованием либо { "senderId": "..." }, либо { "groupId": "..." }

Все маршруты сопряжения требуют строгих прав оператора и используют Cache-Control: no-store. Запросы, одобрения и отзывы ограничены выбранным экземпляром канала и рабочим пространством. Ожидающие запросы включают типизированную сущность пользователя или группы; групповые запросы также сохраняют информацию об отправителе, инициировавшем запрос. Снимки одобрений содержат senderIds и groupIds, так как списки разрешений не сохраняют отображаемые имена. Отзыв неизвестного пользователя или группы возвращает 404 channel_pairing_approval_not_found.

Доставка канала и Notify

channel_delivery объявляет поддержку немедленной доставки по принципу «максимальных усилий». Это возможность протокола, а не сигнал о состоянии воркера. Доставка никогда не запускает отсутствующий воркер, не переключается на другое рабочее пространство, не выполняет повторные попытки, не сохраняет исходящие сообщения и не воспроизводит исторические уведомления.

Прямой Notify обходит Agent и Session и ожидает одной попытки отправки:

POST /workspace/notify
POST /workspaces/:workspace/notify
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "text": "service unavailable",
  "delivery": {
    "kind": "channel",
    "target": {
      "channelName": "dingtalk",
      "type": "user",
      "id": "platform-user-id"
    }
  }
}

Оба маршрута используют строгий мутационный шлюз. Квалифицированный маршрут разрешает только зарегистрированное доверенное рабочее пространство. Успехом является 200 {delivered:true,deliveryId}. delivered:true означает, что промис отправки в канале был выполнен; это не доказывает принятие провайдером, получение пользователем или подтверждение прочтения. Специфичная для провайдера валидация ответа и согласованная семантика причин ошибок между адаптерами IM находятся вне рамок этого контракта V1. Ошибками являются 400 channel_delivery_invalid, 503 channel_worker_unavailable или channel_delivery_queue_full, 504 channel_delivery_timeout, а также 502 channel_delivery_rejected или channel_delivery_failed. Тайм-аут имеет неизвестный результат и не повторяется. Отдельная конечная точка для проверки соединения сознательно отсутствует: обычный вызов Notify служит сквозным тестом.

Воспроизводимое событие результата содержит только корреляцию и очищенный статус:

{
  "type": "channel_delivery_result",
  "promptId": "prompt-1",
  "data": {
    "sessionId": "session-1",
    "deliveryId": "prompt-1",
    "source": "prompt",
    "status": "failed",
    "promptId": "prompt-1",
    "code": "channel_worker_unavailable",
    "error": "Channel worker is not running."
  }
}

Пустой успешный финальный Prompt опускает поля ошибки:

{
  "type": "channel_delivery_result",
  "promptId": "prompt-1",
  "data": {
    "sessionId": "session-1",
    "deliveryId": "prompt-1",
    "source": "prompt",
    "status": "skipped",
    "promptId": "prompt-1"
  }
}

source — это prompt или scheduled; status — это delivered, failed или skipped. skipped означает, что соответствующий ход успешно завершен, но последний блок ответа ассистента без инструментов был пустым или содержал только пробельные символы. Демон потребляет разрешение на доставку и публикует событие без разрешения воркера канала. Для корреляции по расписанию используются taskId и firedAt. Событие никогда не содержит идентификаторов целей, текста сообщений, учетных данных или секретов вебхуков.

Безопасность: ответ никогда не включает токены доступа (bearer tokens), идентификаторы клиентов, полные идентификаторы соединений ACP, коды пользователей потока устройства или URL-адреса верификации. Оба уровня детализации могут включать дополнительные поля daemon.runId, daemon.logMode и daemon.logHealth. summary исключает путь к журналу демона и детали потерь; full может включать logPath, logIssues, logDroppedRecords и logDroppedBytes для аутентифицированных операторов. Деградированное журналирование файлов добавляет предупреждение daemon_log_degraded без пути к обычному сводному статусу.

GET /capabilities

{
  "v": 1,
  "protocolVersions": {
    "current": "v1",
    "supported": ["v1"]
  },
  "mode": "http-bridge",
  "features": [
    "health",
    "daemon_status",
    "capabilities",
    "multi_workspace_sessions",
    "..."
  ],
  "limits": {
    "maxRegisteredWorkspaces": 256,
    "maxChannelControlWorkspaces": 25,
    "maxPendingPromptsPerSession": 5,
    "maxSessionsPerWorkspace": 32,
    "maxTotalSessions": 800,
    "sessionRestoreTimeoutMs": 60000
  },
  "modelServices": [],
  "workspaceCwd": "/canonical/path/to/primary-workspace",
  "workspaces": [
    {
      "id": "stable-workspace-id",
      "cwd": "/canonical/path/to/primary-workspace",
      "primary": true,
      "trusted": true
    },
    {
      "id": "stable-secondary-workspace-id",
      "cwd": "/canonical/path/to/secondary-workspace",
      "displayName": "Payments Production",
      "primary": false,
      "trusted": true
    }
  ]
}

Стабильный контракт: когда v увеличивается, структура кадров изменилась несовместимым с обратной совместимостью образом.

protocolVersions описывает версии протокола serve, которые демон умеет использовать. current — это предпочтительная версия протокола демона, а supported — совместимый набор. Клиенты, которым требуется конкретная версия протокола, должны проверять supported; специфичный для функций UI должен по-прежнему зависеть от features. Аддитивно к v=1: более старые демоны v=1 опускают это поле, поэтому SDK-клиенты, ориентированные на старые сборки, должны считать его необязательным.

modelServices всегда равно [] на Этапе 1. Агент использует свой единственный сервис модели по умолчанию и не перечисляет его по сети. На Этапе 2 это поле будет заполняться из зарегистрированных адаптеров моделей, чтобы SDK-клиенты могли строить выборщики сервисов; до этого момента НЕ полагайтесь на то, что это поле непустое.

workspaceCwd — это канонический абсолютный путь к основному рабочему пространству демона. Используйте его, чтобы опускать cwd в POST /session (маршрут возвращается к этому основному пути) и сохранять совместимость со старыми однорабочими клиентами. Аддитивно к v=1: демоны v=1 до §02 опускают поле — клиенты, ориентированные на старые сборки, должны выполнять проверку на null перед использованием.

workspaces[] перечисляет все зарегистрированные среды выполнения. Более новые однорабочие демоны включают основную среду выполнения даже при отсутствии multi_workspace_sessions, чтобы клиенты могли обнаружить стабильный идентификатор, требуемый маршрутами с указанием рабочего пространства; более старые демоны могут опускать массив. Каждая запись представляет собой { id, cwd, displayName?, primary, trusted, removable? }. displayName предназначен только для отображения и опускается, если не установлен. Первое/основное рабочее пространство по-прежнему отражается в workspaceCwd; новые клиенты выбирают неосновную среду выполнения, передавая её cwd в POST /session. Недоверенные рабочие пространства объявляются для диагностики, но отклоняют создание новых сессий с помощью 403 untrusted_workspace до изменения доверия. removable присутствует у демонов, поддерживающих удаление сред выполнения, и истинно только для вторичных сред выполнения, динамически создаваемых процессом или восстановленных из сохранения.

session_worktree_persistence_v1 означает, что демон может сохранять и проверять владение worktree из Части 4A. Успешные ответы на создание worktree и ответы на восстановление, дочерний элемент которых либо перемещен в простое, либо уже сообщает проверенный cwd worktree, содержат метаданные worktree плюс worktreeState: "persisted-v1". Легасовое восстановление best-effort или холодное восстановление, где запрос на восстановление был запущен, а не отложен (suppressWorktreeContextRestore выключен, поэтому маршрут запросил у моста отсутствие отсрочки), и которое поэтому сообщает об активном запросе без текущего cwd, может всё ещё возвращать worktree без этого аттестата. Клиенты, запрашивающие изоляцию, должны предварительно проверить этот тег и проверить каждый ответ; сам объект worktree не является доказательством долговременного владения.

session_worktree_reset_v1 означает, что демон поддерживает передачу владения worktree: POST /session/:id/worktree-reset перемещает владение checkout сохраненной сессии worktree в новую замену сессии. Ответы на восстановление получают три типизированные классификации 409 вместе с ним: worktree_session_superseded (sidecar сессии содержит ссылку supersededBy — классификация определяется только по этой ссылке, до любого чтения маркера, и ссылка записывается до переключения маркера, поэтому replacementSessionId в теле является редиректом для проверки, а не доказательством владения: в прерванном состоянии до коммита он называет сессию, которая не является владельцем маркера, не может быть сама восстановлена и удаляется повторенным сбросом), worktree_marker_missing (маркер checkout отсутствует; сбросьте задачу для его воссоздания — повторное восстановление не может этого сделать, потому что ни один путь восстановления не пишет маркер) и worktree_reset_interrupted (предыдущая передача завершилась аварийно в середине процесса, и ссылки sidecar совпадают; повторите сброс). Прерванная классификация проверяется первой: отсутствующий маркер, чьи ссылки supersedes/supersededBy совпадают, отображается как worktree_reset_interrupted, никогда как worktree_marker_missing. См. раздел маршрутов ниже для протокола передачи и таксономии сбоев.

Теги функций рабочего пространства и workspaces[] являются динамическими. Клиенты, добавляющие рабочее пространство, должны повторно получить /capabilities после завершения мутации; демон не рассылает изменения возможностей клиентам, закэшировавшим более ранний ответ. Забывание сохранения не выгружает активную среду выполнения, поэтому эта среда выполнения продолжает объявляться до перезапуска.

GET /brand

Продуктовый брендинг Web Shell для хостов, желающих выполнить white-labeling оболочки. Разрешается из ui.brand в областях настроек оператора. Ограничено тегом функции web_shell_brand; демон без маршрута отвечает 404.

{
  "name": "QiuQiu Code",
  "logoDataUri": "data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%2F%3E"
}

Оба поля необязательны, и {} является нормальным ответом. Отсутствие поля означает «использовать встроенный бренд клиента» — Web Shell отображает свое собственное имя и встроенный логотип. Клиенты не должны рассматривать пустое тело как ошибку.

Обработчик всегда отвечает 200, даже если настроенный логотип был отклонен. Отсутствующий файл, символическая ссылка, файл с жесткой ссылкой, каталог, не-SVG-документ или содержимое более 32 КиБ приводят к телу без logoDataUri, а причина записывается в stderr демона как qwen serve: GET /brand: ui.brand.logoPath …. Поэтому клиент не может отличить «бренд не настроен» от «логотип оператора был отклонен»; канал для оператора — это журнал демона. Одно предупреждение мягче отказа, и их два: корневой элемент <svg> без пригодного viewBox и без положительного, не процентного width/height (некорректный или нулевой viewBox считается непригодным), который браузер может отобразить пустым при фиксированном размере боковой панели; и корневой элемент с префиксом пространства имен, у которого элементы без префикса не имеют привязки к пространству имен по умолчанию, что делает их невидимыми. Промежуточное ПО перед обработчиком отвечает до его запуска — 401, когда требуется bearer-аутентификация, но она отсутствует, и 429, когда включен необязательный ограничитель частоты запросов. Демон в режиме завершения работы не отклоняет этот маршрут: ограничитель частоты запросов разрешителен во время завершения работы, поэтому обработчик продолжает отвечать 200, пока слушатель не закроется и клиент не увидит ошибку соединения. Запуск не дает 503 на этом маршруте: на пути отложенной среды выполнения по умолчанию запрос удерживается до готовности среды выполнения, после чего возвращается ответ 200, поэтому ранний сбой может произойти из-за короткого таймаута клиента. Ответ 503 с code: "daemon_runtime_starting" достигает этого маршрута только в конфигурациях, отвечающих до готовности среды выполнения (например, --open), и является повторяемым; ответ 503 с code: "daemon_runtime_failed" является терминальным до перезапуска демона и не содержит Retry-After — не повторяйте его.

Настройки рабочего пространства никогда не участвуют. Маршрут загружает настройки с помощью skipWorkspaceSettings, поэтому .qwen/settings.json репозитория не может переименовать продукт или указать имя файла для чтения и встраивания демоном во все подключенные браузеры. Читаются только System Defaults, User и System, в таком порядке приоритета. По той же причине значение бренда отклоняется с предупреждением в stderr демона всякий раз, когда подстановка плейсхолдеров изменяет его: подстановка берет значения из общепроцессного окружения, которое заполняется блоком .qwen/.env или env рабочего пространства первым при загрузке. Неразрешимый плейсхолдер (переменная не установлена) сохраняется дословно, поэтому опечатка в имени переменной отображается как литеральный текст, а не молча заменяется запасным значением.

logoDataUri должен отображаться как изображение, никогда не внедряйтесь как разметка. Демон не очищает прочитанный SVG. SVG, загруженный через src элемента img или href фавикона, не может выполнять скрипты; SVG, внедренный в документ, может. Web Shell всегда присваивает его только контексту изображения, и именно эта инвариантность делает отсутствие санитайзера безопасным.

Глобально для процесса. Маршрут не принимает селектор рабочего пространства и идентификатор сессии: значение происходит из глобальной конфигурации пользователя, поэтому оно одинаково для всех рабочих пространств, обслуживаемых демоном. Он регистрируется после bearerAuth и ограничителя частоты запросов и перед резервным вариантом SPA Web Shell, поэтому он отвечает JSON для любого заголовка Accept.

POST /workspaces

Зарегистрируйте дополнительную среду выполнения рабочего пространства. Путь должен быть существующим, доступным абсолютным каталогом, который не дублирует и не вкладывает другое зарегистрированное рабочее пространство. Регистрация локальна для процесса, если клиент не отправляет persist: true; клиенты должны выполнить предварительную проверку persistent_workspace_registration перед запросом сохранения. Когда поддерживается workspace_display_name, запрос также может включать необязательный displayName.

Когда поддерживается git_workspace_clone, тот же маршрут также принимает { "kind": "git", "url": "...", "target": "/absolute/new/path" }. Эта форма требует абсолютного target, который еще не существует, запускает асинхронное клонирование, ничего не регистрирует и возвращает 202 { "kind": "git-workspace-clone", "jobId": "..." }. Ответы 201 и 200 ниже описывают синхронные формы cwd и scratch; git-форма ничего не регистрирует, а прогресс клонирования и отмена используют GET/DELETE /workspace-git-clone-jobs/:jobId.

{
  "cwd": "/canonical/path/to/secondary-workspace",
  "persist": true,
  "displayName": "Payments Production"
}

Ново созданная среда выполнения возвращает 201; повышение уже активной вторичной рабочей области до постоянной возвращает 200. Успешное сохранение включает persisted: true:

{
  "id": "stable-workspace-id",
  "cwd": "/canonical/path/to/secondary-workspace",
  "displayName": "Payments Production",
  "primary": false,
  "trusted": true,
  "persisted": true
}

displayName должен быть строкой длиной не более 256 символов после удаления пробелов по краям. Пустой результат трактуется как отсутствие имени, а внутренние управляющие символы C0 (U+0000–U+001F) или DEL (U+007F) отклоняются. Значение JSON null не является значением создания и возвращает 400 invalid_display_name; опустите поле, чтобы не задавать начальное имя. Дублирующиеся отображаемые имена разрешены. Имя, предоставленное при регистрации, локальной для процесса, действует только для этого процесса демона; persist: true сохраняет его вместе с постоянной регистрацией, чтобы его можно было восстановить после перезапуска. Повторный запрос для уже постоянного рабочего пространства идемпотентен и не переименовывает его.

Ошибки включают 400 invalid_path / invalid_persist_flag / invalid_persist_target / invalid_display_name, 409 workspace_exists / workspace_nested / workspace_limit_reached / workspace_registration_store_too_large, 500 workspace_registration_store_error / runtime_creation_failed и 501 persistence_not_available / not_implemented.

PATCH /workspaces/:workspace

Обновите активный ресурс рабочего пространства, выбранный по ID рабочего пространства или URL-кодированному абсолютному cwd. Конечная точка в настоящее время поддерживает только метаданные отображаемого имени:

{ "displayName": "Payments Production" }

Отправьте { "displayName": null }, чтобы очистить имя. Здесь null — это маркер удаления только для обновления; ненулевые значения следуют тем же правилам нормализации строк, что и POST /workspaces. Ответом является обновленная проекция рабочего пространства { id, cwd, displayName?, primary, trusted, removable? }. Метаданные среды выполнения всегда обновляются. Если у среды выполнения есть совпадающие постоянные идентификаторы регистрации, каждый алиас обновляется атомарно через существующее хранилище регистраций схемы v1; конечная точка никогда не создает и не повышает постоянную регистрацию.

Неподдерживаемые поля завершаются ошибкой вместо того, чтобы молча игнорироваться. Ошибки включают 400 empty_patch / invalid_display_name / unsupported_field / workspace_mismatch, 409 workspace_registration_in_progress, 500 workspace_registration_store_error и 503 daemon_shutting_down.

DELETE /workspaces/:workspace

Удалите одну удаляемую вторичную среду выполнения. Селектор следует правилам маршрутизации множественных рабочих пространств и принимает либо ID рабочего пространства, либо URL-кодированный абсолютный cwd. Необязательное тело JSON — это { "force": boolean }; его отсутствие запрашивает удаление без принуждения.

Удаление без принуждения возвращает 409 workspace_busy со снимком activity, когда замороженная среда выполнения имеет сессии, подсказки, ожидающие запуски, соединения ACP, задачи памяти или рабочие процессы каналов рабочего пространства. Отправка { "force": true } запрашивает завершение этих ресурсов. Удаление из хранилища является точкой фиксации: последующая очистка ограничена и выполняется по возможности, сбои очистки логируются, и логическое удаление все равно сходится, вместо восстановления среды выполнения. Успешный ответ выглядит так:

{
  "removed": true,
  "workspaceId": "stable-workspace-id",
  "workspaceCwd": "/canonical/path/to/secondary-workspace",
  "forced": true,
  "persistedRegistrationRemoved": true,
  "activity": {
    "sessions": 2,
    "activePrompts": 1,
    "pendingSessionStarts": 0,
    "acpConnections": 1,
    "memoryTasks": 0,
    "channelWorkers": 0,
    "voiceSessions": 0
  }
}

Немедленно занятый запрос без принуждения возвращает быстрый снимок активности до начала завершения работы. После начала завершения работы ответ «занято» или «успех» содержит окончательный снимок, сделанный после закрытия шлюзов приема и завершения ACP и перед началом очистки. Ошибки включают 400 invalid_force_flag / workspace_mismatch, 409 workspace_busy / primary_workspace_removal_forbidden / static_workspace_removal_forbidden / workspace_removal_in_progress / workspace_registration_in_progress, 500 workspace_persist_failed / workspace_runtime_removal_failed, 501 workspace_runtime_removal_unsupported и 503 daemon_shutting_down.

GET /workspace-registrations

Список сохраненного желаемого набора рабочих пространств для данного основного рабочего пространства. Записи остаются видимыми с active: false, если сохраненный каталог не удалось восстановить при текущем запуске. Запись остается active: true, пока ее среда выполнения завершает работу (draining), поскольку среда выполнения все еще владеет активными ресурсами до завершения удаления. Записи включают необязательное поле displayName, если оно есть в постоянном реестре.

{
  "schemaVersion": 1,
  "primaryWorkspace": "/canonical/path/to/primary-workspace",
  "entries": [
    {
      "id": "stable-registration-id",
      "cwd": "/canonical/path/to/secondary-workspace",
      "displayName": "Payments Production",
      "active": true,
      "persisted": true
    }
  ]
}

Возвращает 501 persistence_not_available, если хранилище регистраций не настроено, и 500 workspace_registration_store_error, если хранилище недоступно для чтения.

DELETE /workspace-registrations/:id

Забывает одну сохранённую регистрацию. Это не выгружает активную среду выполнения и не завершает её сессии; restartRequired: true означает, что активная среда выполнения исчезнет при следующем перезапуске демона.

{ "removed": true, "active": true, "restartRequired": true }

Возвращает 404 workspace_registration_not_found, 500 workspace_registration_store_error или 501 persistence_not_available. Как и другие маршруты мутаций, этот эндпоинт требует аутентификации мутаций, если включена аутентификация демона.

Маршруты статуса среды выполнения только для чтения

Эти маршруты сообщают снимки среды выполнения на стороне демона. Это аддитивные маршруты v1, они не изменяют состояние и не меняют версию протокола serve. Маршруты статуса рабочего пространства сознательно не запускают дочерний процесс ACP только потому, что клиент опрашивает GET-маршрут. GET /workspace/mcp возвращает initialized: false с пустым снимком, когда демон простаивает и не хранит наблюдаемых данных MCP; если живой дочерний процесс отвечал ранее, чтение в режиме простоя воспроизводит это наблюдение с source: "cache" и его исходным значением initialized. Вместо этого GET /workspace/skills предоставляет сохраненное наблюдение демона или локальную перечисленную демоном информацию и сообщает initialized: false с записью errors (повторно доступная недоступность, а не пустой каталог) только тогда, когда сохраненное наблюдение отсутствует и оба источника недоступны (или холодное чтение ограничено частотой) — см. GET /workspace/skills. На GET /workspace/providers отвечает локально демон из настроек рабочего пространства и окружения, поэтому он не зависит от живого дочернего процесса ACP, а acpChannelLive сообщает о работоспособности. Его initialized равен true на успешном пути и false с записью errors, когда настройки рабочего пространства или конфигурация модели не могут быть разрешены; демоны, сконструированные без локального построителя провайдера демона, возвращаются к снимку живого ACP, а локальный ответ демона опускает модели, зарегистрированные во время выполнения. Маршруты статуса сессии требуют активной сессии и возвращают 404 { code: "session_not_found", ... } для неизвестных идентификаторов.

Теги возможностей:

• workspace_mcp → GET /workspace/mcp
• workspace_skills → GET /workspace/skills
• workspace_providers → GET /workspace/providers
• workspace_acp_status → GET /workspace/acp/status
• workspace_env → GET /workspace/env
• workspace_preflight → GET /workspace/preflight
• session_context → GET /session/:id/context
• session_supported_commands → GET /session/:id/supported-commands
• session_tasks → GET /session/:id/tasks
• session_resources → GET /session/:id/resources
• session_monitor_tool_correlation → записи монитора из GET /session/:id/tasks включают toolUseId для корреляции транскрипта с задачей
• session_status → GET /session/:id/status
• session_info → GET /workspace/:id/session-info и GET /workspaces/:workspace/session-info
• session_transcript → GET /session/:id/transcript
• workspace_persisted_transcript → GET /workspaces/:workspace/session/:id/transcript
• workspace_session_export → GET /workspaces/:workspace/session/:id/export
• workspace_archived_session_export → GET /workspaces/:workspace/session/:id/archive/export
• workspace_session_live_state → GET /workspaces/:workspace/sessions/live-state
• workspace_qualified_memory → POST /workspaces/:workspace/memory/{remember,forget,dream} и GET /workspaces/:workspace/memory/{remember,forget,dream}/:taskId

workspace_acp_status сообщает о текущей работоспособности канала ACP основного рабочего пространства как { channelLive: boolean }. Обработчик не создает канал, но достижение маршрута среды выполнения может сначала запустить отложенную среду выполнения демона, чья настроенная политика запуска может независимо предварительно нагревать ACP. Снимок не является арендой: клиенты должны позволить созданию сессии повторно проверить или запустить канал.

Прогрев ACP

Тег возможности: workspace_acp_preheat.

POST /workspace/acp/preheat?timeoutMs=N пытается инициализировать канал ACP основного рабочего пространства по принципу «максимальных усилий». Значение по умолчанию для timeoutMs равно 5000 и должно быть положительным целым числом, не превышающим 60000. Конкурентные вызывающие стороны и создание сессии разделяют одну и ту же инициализацию моста. Тайм-аут запроса завершает только это HTTP-ожидание; он не отменяет общую инициализацию.

interface WorkspaceAcpPreheatResult {
  ready: boolean;
  channelLive: boolean;
  durationMs: number;
  reason?: 'timeout' | 'error';
  error?: string;
}

ready всегда равно channelLive. Живой ответ не содержит полей reason и error; в противном случае поле reason принимает значение timeout или error. Поле durationMs измеряет длительность текущего HTTP-вызова, а не полный жизненный цикл инициализации, к которой присоединился вызов. Операционный тайм-аут или сбой возвращают HTTP 200. Неверное значение timeoutMs возвращает код 400, тогда как ошибки аутентификации, ограничения частоты запросов и сбои отложенного выполнения сохраняют свои обычные ответы.

Оба маршрута рабочего пространства ACP являются единичными и относятся только к основному рабочему пространству. Клиенты не должны использовать их для вторичных рабочих пространств или интерпретировать любой из ответов как гарантию постоянной готовности.

Общая ячейка статуса:

type DaemonStatus =
  | 'ok'
  | 'warning'
  | 'error'
  | 'disabled'
  | 'not_started'
  | 'unknown';
 
type DaemonErrorKind =
  | 'missing_binary'
  | 'blocked_egress'
  | 'auth_env_error'
  | 'init_timeout'
  | 'restore_timeout'
  | 'protocol_error'
  | 'missing_file'
  | 'parse_error';
 
interface DaemonStatusCell {
  kind: string;
  status: DaemonStatus;
  error?: string;
  errorKind?: DaemonErrorKind;
  hint?: string;
}

errorKind — это закрытое перечисление, общее для /workspace/preflight, /workspace/env и (в конечном итоге) защитных механизмов MCP, чтобы клиенты SDK могли отображать исправления по категориям вместо разбора сообщений в свободной форме. Исходные семь литералов статуса были взяты из #4175; restore_timeout был добавлен отдельно для запросов восстановления сессии. blocked_egress остается зарезервированным до внедрения пробы исходящего трафика.

Полезные нагрузки статуса никогда не раскрывают значения переменных окружения MCP, заголовки, детали OAuth/сервисных аккаунтов, API-ключи провайдеров, baseUrl / envKey провайдеров, тело навыка, пути файловой системы навыков, определения хуков или значения секретных переменных окружения. /workspace/env сообщает только о наличии разрешенных переменных окружения; URL-адреса прокси очищаются от учетных данных и сокращаются до host:port перед отправкой по сети.

GET /workspace/mcp

{
  "v": 1,
  "workspaceCwd": "/canonical/path",
  "initialized": true,
  "discoveryState": "completed",
  "servers": [
    {
      "kind": "mcp_server",
      "status": "ok",
      "name": "docs",
      "mcpStatus": "connected",
      "transport": "stdio",
      "disabled": false,
      "description": "Documentation server",
      "extensionName": "docs-ext"
    }
  ]
}

discoveryState принимает одно из значений: not_started, in_progress или completed. transport принимает одно из значений: stdio, sse, http, websocket, sdk или unknown. Поле errors опускается при успешном обнаружении.

source имеет значение "live", пока дочерний процесс, создавший наблюдение, активен. Когда демон простаивает, но живой дочерний процесс ранее ответил, ответ воспроизводит то наблюдение с полем source: "cache" и исходными значениями дочернего процесса, включая initialized: true и его список серверов. Кэшированное наблюдение очищается только при начале нового обнаружения MCP; завершение работы дочернего процесса не приводит к его удалению, поэтому простаивающий GET /workspace/mcp может сообщать каталог, который в данный момент не обслуживается ни одним живым дочерним процессом.

Защитные механизмы клиента MCP (проблема #4175 ). Текущие демоны расширяют полезную нагрузку четырьмя дополнительными полями и ячейкой бюджета с областью действия:

{
  "v": 1,
  "workspaceCwd": "/canonical/path",
  "initialized": true,
  "discoveryState": "completed",
  "clientCount": 3,
  "clientBudget": 2,
  "budgetMode": "enforce",
  "budgets": [
    {
      "kind": "mcp_budget",
      "scope": "workspace",
      "status": "error",
      "errorKind": "budget_exhausted",
      "hint": "Raise --mcp-client-budget or remove servers from mcpServers config.",
      "liveCount": 2,
      "budget": 2,
      "mode": "enforce",
      "refusedCount": 1,
    },
  ],
  "servers": [
    {
      "kind": "mcp_server",
      "status": "ok",
      "name": "a",
      "mcpStatus": "connected",
      "transport": "stdio",
      "disabled": false,
    },
    {
      "kind": "mcp_server",
      "status": "ok",
      "name": "b",
      "mcpStatus": "connected",
      "transport": "stdio",
      "disabled": false,
    },
    {
      "kind": "mcp_server",
      "status": "error",
      "name": "c",
      "mcpStatus": "disconnected",
      "transport": "stdio",
      "disabled": false,
      "disabledReason": "budget",
      "errorKind": "budget_exhausted",
      "hint": "...",
    },
  ],
}

budgetMode принимает одно из значений enforce, warn или off. Поле clientBudget отсутствует, если бюджет не был установлен. Поле budgets[] всегда является массивом у демонов, объявляющих поддержку mcp_guardrails (возможно пустым, когда budgetMode === 'off'); старые демоны полностью пропускают это поле. Когда поддерживается mcp_workspace_pool, ячейка содержит scope: 'workspace' и охватывает общий пул выбранной среды рабочего пространства. Когда этот тег отсутствует, включая случай QWEN_SERVE_NO_MCP_POOL=1, устаревший менеджер выдает scope: 'session'. Потребители ДОЛЖНЫ допускать дополнительные нераспознанные значения области действия.

Поле disabledReason в ячейках на уровне сервера позволяет отличить отключение оператором ('config' — disabledMcpServers конфигурационный список) от отказа из-за бюджета ('budget' — обнаружен, но никогда не подключен из-за режима enforce). Отказы детерминированы порядком объявления в Object.entries(mcpServers). Поле status: 'error', errorKind: 'budget_exhausted' на уровне сервера перекрывает исходное значение mcpStatus: 'disconnected' (которое истинно, но не отражает уровень серьезности для оператора).

Применение бюджета управляется возможностями. При наличии mcp_workspace_pool сессии внутри одной среды рабочего пространства разделяют транспорты и один WorkspaceMcpBudget; разные среды рабочего пространства никогда не разделяют пул или бюджет. Без этого тега каждый McpClientManager сессии ACP применяет свою собственную копию ограничения, и снимок представляет этот устаревший вид сессии.

Обнаружение давления бюджета. Два интерфейса, оба заполняются после PR-14b:

• Push-события (объявляются через mcp_guardrail_events): подпишитесь на GET /session/:id/events и фильтруйте кадры mcp_budget_warning / mcp_child_refused_batch через KnownDaemonEvent. Машина состояний срабатывает один раз при каждом пересечении порога 75% вверх (сбрасывается ниже 37,5%); отказы объединяются один раз за проход обнаружения в режиме enforce.

• Опрос снимков (объявляется через mcp_guardrails): выполните GET /workspace/mcp и проверьте ячейку бюджета (budgets[0]) вместе с mcp_workspace_pool, чтобы определить ее область действия:

• budgets[0].status === 'warning' ⇔ liveCount >= 0.75 * clientBudget (соответствует порогу гистерезиса, который будет использовать push-событие из PR 14b).

• budgets[0].status === 'error' ⇔ refusedCount > 0 (один или более серверов были отклонены в этом проходе обнаружения).

• budgets[0].status === 'ok' ⇔ ниже порога 75% И нет отказов.

Рекомендуемая частота опроса: согласованная с тем, что уже опрашивает /workspace/mcp; снимок дешев, а ячейка бюджета не несет дополнительных затрат на обнаружение. Клиенты SDK, подписанные на push-события, по-прежнему получают выгоду от снимка для состояния после длительного отключения (глубина кольца воспроизведения SSE конечна — --event-ring-size, по умолчанию 8000 — поэтому клиент, находящийся в автономном режиме дольше покрытия кольца, переходит на повторную синхронизацию по снимку).

GET /workspace/skills

Маршруты инвентаризации основного и квалифицированного по рабочему пространству немедленно возвращают сохраненный снимок, выполняя ревалидацию в фоновом режиме. Запуски ограничены частотой один раз в секунду, отсчитываемой от начала задачи, и параллельные читатели используют одну задачу. Фоновая ревалидация освобождает слот после пяти секунд; тайм-аут позволяет выполнить повторную попытку, но не отменяет наблюдение или работу ACP. Холодные чтения соблюдают настроенный тайм-аут запроса ACP (по умолчанию десять секунд), затем выполняют локальную перечисление демоном, если ACP недоступен. Они не навязывают фоновый дедлайн ни одному из источников. Холодное чтение, завершившееся ошибкой в течение одной секунды от своего начала, оставляет остаток этого окна возвращающим статус недоступности немедленно; более медленные сбои не оставляют окна троттлинга, поэтому клиентам требуется собственная стратегия отката при повторных попытках. Позднее успешное фоновое наблюдение может быть опубликовано, пока ожидает повторная попытка, но не может заменить наблюдение, начатое позже и уже опубликованное. Аннулированные задачи не могут публиковать результаты; успешно аннулированное наблюдение все еще может ответить своему исходному вызывающему объекту. Явное аннулирование удаляет известный недействительный инвентарь и сбрасывает ограничение частоты. Успешный предварительный нагрев ACP, завершающийся до истечения тайм-аута, также аннулирует сохраненный инвентарь, в том числе когда дочерний процесс уже был активен, так что последующее чтение видит дочерний процесс. Предварительный нагрев, который завершается по тайм-ауту, а затем находит канал активным, также сообщает ready: true — готовность всегда равна channelLive — но сохраняет инвентарь, поскольку запуск может быть еще незавершенным; следующее чтение вернет эти сохраненные данные, а фоновая ревалидация заменит их, как только односекундное ограничение запуска позволит. Удаление навыка обходит снимок и ограничение частоты, но требует свежего перечисленного каталога: оно использует локальный резервный вариант и никогда не отвечает из сохраненного снимка. Чтения идентичности включения обходят снимок и ограничение частоты, ожидая новое наблюдение с локальным резервным вариантом, а затем сохраненный снимок, когда оба источника терпят неудачу.

Ответы инвентаризации, содержащие сохраненное наблюдение демона, дополнительно включают необязательные метаданные снимка. Прямые чтения статуса конфигурации/среды выполнения, инвентари ресурсов сессии и старые демоны опускают их. Отмененное успешное холодное чтение возвращает более новый сохраненный снимок, если он доступен; в противном случае оно возвращает свое собственное некэшированное наблюдение без этих метаданных. Только инициализированные наблюдения без ошибок могут заменить сохраненный снимок:

{
  "snapshot": {
    "observedAt": 1792486800000,
    "ageMs": 1500,
    "stale": true,
    "refreshing": true
  }
}

observedAt — это время начала успешного наблюдения в миллисекундах Unix; ageMs пересчитывается для каждого ответа, консервативно включая время сбора. stale означает, что наблюдению как минимум одна секунда. refreshing сообщает, занимает ли повторная валидация общий слот; наблюдения с истекшим таймаутом могут завершиться после освобождения слота. Неудачные чтения, таймауты слотов и воспроизведение после остановки среды выполнения не обновляют временную метку; последующая успешная публикация записывает собственное время начала наблюдения. Клиенты могут отображать этот возраст, но он не является ревизией файловой системы или доказательством актуальности всех сессий. Если инициализированный снимок отсутствует и оба источника недоступны (или холодное чтение ограничено), ответ содержит initialized: false, запись errors и отсутствующие метаданные snapshot. Это повторяемая недоступность, а не пустой каталог; допустимый пустой каталог имеет initialized: true. Чтения статуса не вызывают команды обновления Skill, влияющие на сессию. Закрытые или завершающие работу среды выполнения рабочего пространства отклоняют чтения; сохраненные данные переживают удаление дочернего канала, но не вывод из эксплуатации среды выполнения.

{
  "v": 1,
  "workspaceCwd": "/canonical/path",
  "initialized": true,
  "skills": [
    {
      "kind": "skill",
      "status": "ok",
      "name": "review",
      "description": "Review code",
      "level": "project",
      "modelInvocable": true,
      "userInvocable": false,
      "installedPath": "/home/alice/project/.qwen/skills/review/SKILL.md",
      "argumentHint": "[path]"
    },
    {
      "kind": "skill",
      "status": "ok",
      "name": "database-review",
      "description": "Review database changes",
      "level": "extension",
      "modelInvocable": true,
      "installedPath": "/home/alice/.qwen/extensions/alibabacloud-database-suite/skills/database-review/SKILL.md",
      "extensionName": "alibabacloud-database-suite",
      "extensionDisplayName": "Alibaba Cloud Database Suite"
    }
  ]
}

level принимает одно из значений: project, user, extension или bundled. Поле userInvocable (логическое, необязательное) опускается для обычных навыков (означает true) и присутствует только как false, если навык нельзя вызвать вручную. Оно не блокирует описанные ниже маршруты переключателя Skill, доступные только через настройки. modelInvocable независимо: false означает, что навык остается доступным для ручного вызова, но скрыт от вызова моделью. installedPath — существующий абсолютный путь к SKILL.md навыка; демон возвращает его в том виде, в каком он сохранен, без отдельного разрешения симлинков или канонизации. Текущие демоны выводят его для каждого навыка, тогда как клиенты должны допускать его отсутствие у старых демонов v1. Тела навыков, хуки, skillRoot и другая конфигурация навыков остаются исключены. errors опускается при успешном обнаружении.

Для навыков, принадлежащих расширениям, extensionName — это каноническое имя манифеста, безопасное для использования в качестве идентификатора владельца. extensionDisplayName — необязательное локализованное значение для отображения, которое может быть неуникальным. Новые клиенты должны отображать extensionDisplayName ?? extensionName; старые демоны опускают поле отображения.

Повторные чтения обслуживаются из последнего зафиксированного снимка рабочего пространства, периодически проверяемого по памяти дочернего процесса. В устойчивом состоянии чтения не сканируют каталоги навыков и не повторно разбирают файлы SKILL.md; резервное локальное холодное чтение демона может выполнять перечисление с диска. Дочерний процесс проверяет неизменность своих источников расширений — один readdir каталога расширений плюс stat для каждой записи, файл включения и состояние активации хранилища — и обновляет их только при изменениях, поэтому расширение, установленное или переключенное вне демона, будет обнаружено при повторной валидации и появится при последующем чтении после публикации этой валидации. Теплое чтение всегда возвращает сохраненное наблюдение, даже если оно запускает фоновую работу. Безопасный режим и режим без расширений пропускают проверку, соответствуя своему исключению расширений.

GET /workspace/providers

{
  "v": 1,
  "workspaceCwd": "/canonical/path",
  "initialized": true,
  "current": { "authType": "qwen", "modelId": "qwen3(qwen)" },
  "providers": [
    {
      "kind": "model_provider",
      "status": "ok",
      "authType": "qwen",
      "current": true,
      "models": [
        {
          "modelId": "qwen3(qwen)",
          "baseModelId": "qwen3",
          "name": "Qwen 3",
          "description": null,
          "contextLimit": 4096,
          "isCurrent": true,
          "isRuntime": false
        }
      ]
    }
  ]
}

Модели сгруппированы по типу авторизации. Диагностика подключения провайдера находится в ячейке providers объекта /workspace/preflight; предварительная проверка окружения находится в /workspace/preflight и /workspace/env (ниже). errors опускается при успешном построении снимка.

GET /workspace/env

Сообщает о среде выполнения процесса демона, платформе, песочнице, прокси и наличии секретных переменных окружения из белого списка. Всегда отвечает на основе состояния process.* — демон никогда не запускает дочерний процесс ACP для обслуживания этого маршрута, и ответ идентичен независимо от того, запущен ACP или простаивает. Поле acpChannelLive носит исключительно информационный характер.

{
  "v": 1,
  "workspaceCwd": "/canonical/path",
  "initialized": true,
  "acpChannelLive": false,
  "cells": [
    { "kind": "runtime", "name": "node", "status": "ok", "value": "22.4.0" },
    { "kind": "platform", "name": "darwin", "status": "ok", "value": "arm64" },
    {
      "kind": "sandbox",
      "name": "SANDBOX",
      "status": "disabled",
      "present": false
    },
    {
      "kind": "proxy",
      "name": "HTTPS_PROXY",
      "status": "ok",
      "present": true,
      "value": "proxy.internal:1080"
    },
    {
      "kind": "proxy",
      "name": "NO_PROXY",
      "status": "disabled",
      "present": false
    },
    {
      "kind": "env_var",
      "name": "OPENAI_API_KEY",
      "status": "ok",
      "present": true
    },
    {
      "kind": "env_var",
      "name": "ANTHROPIC_BASE_URL",
      "status": "disabled",
      "present": false
    }
  ]
}

Форма ячейки:

type DaemonEnvKind =
  | 'runtime' // name: 'node' | 'bun' | 'unknown'; value: process.versions.node
  | 'platform' // name: process.platform; value: process.arch
  | 'sandbox' // name: 'SANDBOX' | 'SEATBELT_PROFILE'; value optional
  | 'proxy' // name: HTTP_PROXY | HTTPS_PROXY | NO_PROXY | ALL_PROXY; value: redacted host
  | 'env_var'; // presence-only; value field is ALWAYS omitted
 
interface DaemonEnvCell extends DaemonStatusCell {
  kind: DaemonEnvKind;
  name: string;
  present?: boolean;
  value?: string;
}

Политика редактирования. Ячейки kind: 'env_var' никогда не включают поле value; клиенты видят только present: boolean. Ячейки kind: 'proxy' пропускают исходное значение переменной окружения через редактирование учетных данных (redactProxyCredentials), а затем через разбор URL, так что в сети передается только host:port. NO_PROXY проходит редактирование дословно, поскольку это список хостов, а не URL. Белый список перечисленных секретных переменных окружения в настоящее время включает OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, DASHSCOPE_API_KEY, OPENROUTER_API_KEY и QWEN_SERVER_TOKEN. Другие переменные окружения не перечисляются, поэтому случайно установленные секреты остаются невидимыми.

GET /workspace/preflight

Сообщает о проверках готовности демона. Ячейки уровня демона (node_version, cli_entry, workspace_dir, ripgrep, git, npm) всегда заполняются из process.* и node:fs. Ячейки уровня ACP (auth, mcp_discovery, skills, providers, tool_registry, egress) требуют активного дочернего процесса ACP — когда демон простаивает, они выводят заполнители status: 'not_started'. Маршрут никогда не запускает ACP исключительно для заполнения ячеек; соответствующие ячейки возвращают значения по умолчанию not_started.

Форма ячейки:

{
  "v": 1,
  "workspaceCwd": "/canonical/path",
  "initialized": true,
  "acpChannelLive": false,
  "cells": [
    {
      "kind": "node_version",
      "status": "ok",
      "locality": "daemon",
      "detail": { "version": "22.4.0", "required": ">=22" }
    },
    {
      "kind": "cli_entry",
      "status": "ok",
      "locality": "daemon",
      "detail": { "path": "/usr/local/bin/qwen", "source": "process.argv[1]" }
    },
    {
      "kind": "workspace_dir",
      "status": "ok",
      "locality": "daemon",
      "detail": { "path": "/canonical/path" }
    },
    { "kind": "ripgrep", "status": "ok", "locality": "daemon" },
    {
      "kind": "git",
      "status": "ok",
      "locality": "daemon",
      "detail": { "version": "2.45.0" }
    },
    {
      "kind": "npm",
      "status": "ok",
      "locality": "daemon",
      "detail": { "version": "10.7.0" }
    },
    {
      "kind": "auth",
      "status": "not_started",
      "locality": "acp",
      "hint": "spawn a session to populate"
    },
    {
      "kind": "mcp_discovery",
      "status": "not_started",
      "locality": "acp",
      "hint": "spawn a session to populate"
    },
    {
      "kind": "skills",
      "status": "not_started",
      "locality": "acp",
      "hint": "spawn a session to populate"
    },
    {
      "kind": "providers",
      "status": "not_started",
      "locality": "acp",
      "hint": "spawn a session to populate"
    },
    {
      "kind": "tool_registry",
      "status": "not_started",
      "locality": "acp",
      "hint": "spawn a session to populate"
    },
    {
      "kind": "egress",
      "status": "not_started",
      "locality": "acp",
      "hint": "egress probing lands in PR 14 (#4175)"
    }
  ]
}

Форма ячейки:

type DaemonPreflightKind =
  | 'node_version'
  | 'cli_entry'
  | 'workspace_dir'
  | 'ripgrep'
  | 'git'
  | 'npm'
  | 'auth'
  | 'mcp_discovery'
  | 'skills'
  | 'providers'
  | 'tool_registry'
  | 'egress';
 
interface DaemonPreflightCell extends DaemonStatusCell {
  kind: DaemonPreflightKind;
  locality: 'daemon' | 'acp';
  detail?: Record<string, unknown>;
}

Семантика errorKind:

• missing_binary — версия Node ниже требуемой, отсутствует QWEN_CLI_ENTRY, ripgrep / git / npm не находятся в PATH (предупреждения, а не ошибки для необязательных бинарных файлов).
• missing_file — boundWorkspace не существует или не является каталогом; ошибка разбора навыка, указывающая на отсутствующий или нечитаемый файл.
• parse_error — сбой разбора SKILL.md, некорректный JSON конфигурации.
• auth_env_error — validateAuthMethod вернул ненулевую строку ошибки, или подкласс ModelConfigError был распространен из разрешения провайдера.
• init_timeout — отклонение withTimeout в мосте (фактический таймаут при ожидании roundtrip ACP). Распознается через типизированный класс BridgeTimeoutError. Примечание: преходящая ячейка mcp_discovery warning со значением connecting > 0 НЕ относится к этому типу — это нормальное состояние выполняющегося рукопожатия, отличное от реального таймаута.
• restore_timeout — загрузка или возобновление сессии превысило выделенный бюджет восстановления. Ответ REST имеет код 504 и может быть повторен; он отличается от инициализации дочернего процесса и от ограничений окна воспроизведения.
• protocol_error — запрос ACP extMethod отклонен, так как канал закрылся во время выполнения запроса, или из-за неожиданного отсутствия реестра инструментов.
• blocked_egress — зарезервировано для PR 14 (#4175). В PR 13 ячейка egress остается со значением status: 'not_started'.

Если мост не может связаться с дочерним процессом ACP при обработке предварительного запроса (например, закрытие канала во время запроса), массив errors в конверте содержит единственный объект ServeStatusCell, описывающий ошибку, а ячейки возвращают заполнители ACP not_started. Ячейки уровня демона все равно возвращаются.

GET /workspace/tools

Возвращает каталог инструментов, предоставленный дочерним процессом ACP основного рабочего пространства. Это устаревший маршрут для основного рабочего пространства: он не имеет селектора рабочего пространства и не должен использоваться для определения инструментов среды выполнения, отличной от основной.

{
  "v": 1,
  "workspaceCwd": "/canonical/path",
  "initialized": true,
  "acpChannelLive": true,
  "tools": [
    {
      "name": "ReadFile",
      "displayName": "Read",
      "description": "Read a file",
      "enabled": true
    }
  ]
}

Когда ни один дочерний процесс ACP не активен, маршрут по-прежнему возвращает 200 с acpChannelLive: false, пустым массивом tools и записью not_started в необязательном массиве errors. Неожиданные ошибки моста используют стандартный ответ об ошибке моста 500. Метод TypeScript SDK называется workspaceTools(); специального тега возможности нет, поэтому клиенты, поддерживающие старые версии демонов, должны считать 404 неподдерживаемым.

Маршруты файлов рабочего пространства

Устаревшие файловые маршруты разрешают пути через основное рабочее пространство; маршруты /workspaces/:workspace/... разрешают пути через выбранную среду выполнения рабочего пространства. Ответы используют относительные пути рабочего пространства и никогда не возвращают абсолютные пути файловой системы в обычных успешных случаях. Успешные ответы файловых операций включают:

Cache-Control: no-store
X-Content-Type-Options: nosniff

Ошибки файловой системы используют этот формат JSON:

{
  "errorKind": "hash_mismatch",
  "error": "expected sha256:..., found sha256:...",
  "hint": "re-read the file and retry with the latest hash",
  "status": 409
}

Значения errorKind включают path_outside_workspace, symlink_escape, path_not_found, binary_file, file_too_large, untrusted_workspace, permission_denied, parse_error, hash_mismatch, file_already_exists, text_not_found и ambiguous_text_match.

GET /file

Читает текстовый файл. Параметры запроса: path (обязательно), maxBytes, line, limit и cursor. Демон отклоняет бинарные файлы. Файлы, превышающие лимит полного снимка в 256 КиБ, требуют указания хотя бы одного явного параметра окна (line, limit или maxBytes); запрос без них остается file_too_large. Такое окно передается потоково, и его возвращаемое содержимое UTF-8 ограничено 256 КиБ. maxBytes всегда применяется к байтам ответа UTF-8 после декодирования, включая случаи, когда источник использует другую поддерживаемую кодировку в пределах лимита полного снимка.

Смещения строк определяются путем сканирования с начала файла, поэтому окно также отклоняется с кодом file_too_large, если достижение его требует чтения более 8 МиБ (MAX_TEXT_SCAN_BYTES). Используйте GET /file/bytes, чтобы напрямую достичь более глубокого смещения. Большой текст в кодировке, которую маршрут не может декодировать, возвращает binary_file, а не file_too_large — повторная попытка с меньшим окном не поможет, и readBytes является тем же решением, которое уже применяется для бинарных файлов.

Для файлов в пределах лимита полного снимка ответ включает hash, SHA-256 дайджест сырых байтов на диске для всего файла, даже если line, limit или maxBytes вернули фрагмент. Большие частичные окна опускают hash, сохраняют полный sizeBytes, устанавливают truncated: true и возвращают originalLineCount: null, если поток останавливается до EOF.

Постраничная загрузка с помощью cursor

Требует возможность workspace_file_read_cursor. Ответ, который имеет больше данных для передачи, возвращает hasMore: true и, если смещение байта файла выводимо, токен nextCursor. Передача его обратно как cursor возобновляет чтение за O(1), тогда как глубокое смещение line требует сканирования от байта 0 и отклоняется за пределами 8 МиБ.

GET /file?path=big.log&limit=500          → { content, nextCursor, hasMore: true }
GET /file?path=big.log&limit=500&cursor=… → next page

cursor и line взаимоисключающи (parse_error) — оба указывают начальную точку. Некорректный или слишком длинный курсор вызывает parse_error; курсор, для которого файл был заменен или усечен, вызывает hash_mismatch (409). Добавление данных не инвалидирует существующий курсор, что является случаем, ради которого эта функция существует.

content опускает завершающую новую строку последней строки, как и любое другое чтение, поэтому клиент, собирающий страницы вместе, соединяет их с помощью \n. hasMore не является пересказом nextCursor: небольшой не-UTF-8 файл, прочитанный с помощью limit, имеет больше содержимого, но не имеет выводимого смещения байта, поэтому он сообщает hasMore: true с nextCursor: null. Курсор также равен null, когда лимит байтов обрезает текущую строку, потому что возобновление с этого смещения вернуло бы неполную строку. Для многих коротких строк уменьшите limit, пока страница не закончится до лимита байтов и не вернет курсор. Для одной слишком большой строки явно запросите следующую строку (например, line=2 при начале со строки 1), затем продолжайте с курсорами; используйте GET /file/bytes, когда требуется полная слишком большая строка.

{
  "kind": "file",
  "path": "src/index.ts",
  "content": "export {};\n",
  "encoding": "utf-8",
  "bom": false,
  "lineEnding": "lf",
  "sizeBytes": 11,
  "returnedBytes": 11,
  "truncated": false,
  "hash": "sha256:...",
  "matchedIgnore": null,
  "originalLineCount": null
}

GET /file/bytes

Читает сырые байты из файла без декодирования. Параметры запроса: path (обязательно), offset (по умолчанию 0) и maxBytes (по умолчанию 65536, максимум 262144). Этот маршрут поддерживает ограниченные окна для больших бинарных файлов без загрузки всего файла целиком. Ответ включает hash только тогда, когда возвращаемое окно охватывает весь файл.

{
  "kind": "file_bytes",
  "path": "assets/logo.png",
  "offset": 0,
  "sizeBytes": 3912,
  "returnedBytes": 3912,
  "truncated": false,
  "contentBase64": "...",
  "hash": "sha256:..."
}

GET /stat

Возвращает метаданные для одного пути в основном рабочем пространстве. Параметр запроса path обязателен.

{
  "kind": "stat",
  "path": "src/index.ts",
  "type": "file",
  "sizeBytes": 128,
  "modifiedMs": 1700000000123
}

type может быть file, directory, symlink или other. Маршрут использует границы файлов рабочего пространства и общую оболочку ошибок файловой системы, описанную выше. Метод TypeScript SDK называется fileStat().

GET /list

Список каталогов основного рабочего пространства. Параметр запроса path обязателен; includeIgnored=1 (или true) включает записи, соответствующие правилам игнорирования. Ответ ограничен 2000 записями и устанавливает truncated: true, если их больше.

{
  "kind": "list",
  "path": ".",
  "entries": [{ "name": "src", "kind": "directory", "ignored": false }],
  "truncated": false,
  "matchedIgnore": null
}

Поле kind каждой записи имеет значение file, directory, symlink или other. Метод TypeScript SDK — dirList().

GET /glob

Соответствие путям внутри основного рабочего пространства. Параметр запроса pattern обязателен. Необязательный параметр cwd сужает поиск, includeIgnored=1 (или true) включает игнорируемые пути, а maxResults — целое число от 1 до 50 000 (по умолчанию 5 000).

{
  "kind": "glob",
  "pattern": "**/*.ts",
  "cwd": "",
  "matches": ["src/index.ts"],
  "count": 1,
  "truncated": false,
  "durationMs": 4
}

Совпадения являются относительными для рабочего пространства. Неверные значения запроса возвращают 400; ошибки доверия к рабочему пространству, containment, отсутствующего пути и непредвиденные сбои используют общий формат ошибок файловой системы. Метод TypeScript SDK — glob().

POST /file/write

Создает или заменяет текстовый файл. Это строгий маршрут мутации: авторизован запрос без токена из доверенного loopback-соединения в основном рабочем пространстве. Запрос без токена, достигший шлюза без полномочий доверенного loopback-соединения, возвращает 401 { "code": "token_required" }. Ошибки настроенного токена и учетных данных Local Control отвергаются ранее с простой ошибкой 401 Unauthorized; при наличии --require-auth глобальный bearer middleware отвергает неаутентифицированные запросы до выполнения маршрута.

Тело:

{
  "path": "src/new.ts",
  "content": "export const value = 1;\n",
  "mode": "create"
}

{
  "path": "src/existing.ts",
  "content": "export const value = 2;\n",
  "mode": "replace",
  "expectedHash": "sha256:..."
}

Поле mode должно иметь значение create или replace. Поле create никогда не перезаписывает существующий файл (409 file_already_exists). Поле replace требует expectedHash; отсутствующие или некорректные хеши приводят к ошибке 400 parse_error, а устаревшие хеши — к ошибке 409 hash_mismatch. Поле expectedHash состоит из sha256: плюс 64 символов нижнего регистра в шестнадцатеричном формате, вычисленных по необработанным байтам на диске.

Могут быть переданы поля bom, encoding и lineEnding. При замене профиль кодировки существующего файла сохраняется по умолчанию; явные поля переопределяют его. Запись бинарных данных находится вне области действия.

Демон записывает данные во временный файл со случайным именем в целевом каталоге, выполняет fsync там, где это поддерживается, повторно проверяет текущий хеш непосредственно перед rename(), затем переименовывает файл на место. Это предотвращает наблюдение частичной записи файла и сериализует записи, инициированные демоном, в один и тот же файл, но это не является межпроцессным сравнением и обменом на уровне ядра: внешний редактор может создать гонку в крошечном окне между финальной проверкой хеша и переименованием.

{
  "kind": "file_write",
  "path": "src/existing.ts",
  "mode": "replace",
  "created": false,
  "sizeBytes": 24,
  "hash": "sha256:...",
  "encoding": "utf-8",
  "bom": false,
  "lineEnding": "lf",
  "matchedIgnore": null
}

POST /file/edit

Применяет одну точную текстовую замену к существующему текстовому файлу. Это также строгий маршрут мутации, требующий expectedHash.

{
  "path": "src/config.ts",
  "oldText": "timeout: 30000",
  "newText": "timeout: 60000",
  "expectedHash": "sha256:..."
}

Поле oldText должно быть непустым и встречаться ровно один раз. Отсутствие совпадений возвращает 422 text_not_found; множественные совпадения возвращают 422 ambiguous_text_match. Маршрут сохраняет кодировку, BOM и окончания строк, а также повторно проверяет expectedHash непосредственно перед атомарным переименованием.

Явные записи/изменения игнорируемых путей разрешены, так как аутентифицированный вызывающий объект указал путь. Успешные ответы и события аудита включают matchedIgnore: "file" | "directory" | null.

{
  "kind": "file_edit",
  "path": "src/config.ts",
  "replacements": 1,
  "sizeBytes": 128,
  "hash": "sha256:...",
  "encoding": "utf-8",
  "bom": false,
  "lineEnding": "lf",
  "matchedIgnore": null
}

POST /workspaces/:workspace/directory/create

Требуются workspace_qualified_rest_core и workspace_directory_create, строгие полномочия мутации и активное доверенное локальное рабочее пространство. Тело запроса:

{ "path": "src/new-folder" }

Родительский каталог должен существовать. Создание является эксклюзивным: существующий файл или каталог возвращает 409 file_already_exists; конечная символическая ссылка возвращает 400 symlink_escape. Успех означает статус 201 { "kind": "directory_create", "path": "src/new-folder" }. Метод SDK — WorkspaceDaemonClient.createWorkspaceDirectory(path, clientId?).

POST /workspaces/:workspace/directory/delete

Требуются workspace_qualified_rest_core и workspace_directory_delete в соответствии с той же политикой строгой мутации и доверенного локального выполнения. Тело запроса:

{ "path": "src/old-folder" }

Рекурсивно удаляет пустой или непустой каталог. Корни рабочего пространства, обычные файлы и конечные символические ссылки отвергаются; вложенные записи символических ссылок удаляются без перехода по их целям. Отсутствующая цель возвращает 404 path_not_found. Успех означает статус 200 { "kind": "directory_delete", "path": "src/old-folder" }. Метод SDK — WorkspaceDaemonClient.deleteWorkspaceDirectory(path, clientId?).

Оба маршрута для каталогов сохраняют лексическое конечное имя, разрешая его родителя внутри выбранного рабочего пространства. Пути не должны заканчиваться разделителем; подозрительные шаблоны путей возвращают 400 path_outside_workspace, а некорректные формы конечных элементов возвращают 400 parse_error. Неподдерживаемые пользовательские фабрики возвращают 422; SSH-рабочие пространства отвергаются границей SSH с ошибкой 501. Неизвестные, недоступные, удаленные или недоверенные владельцы никогда не возвращаются к основному рабочему пространству.

Удаление является постоянным, и сбои могут привести к частичному удалению. Конкурентный писатель может вызвать ENOTEMPTY, возвращаемый как 503 io_error; повторите ту же операцию после остановки писателя. Блокировки по путям не сериализуют каталог относительно каждой дочерней записи, и внешнюю замену каталога невозможно сделать атомарной с помощью переносимых проверок на основе путей. Явные изменения игнорируемых каталогов разрешены, и события аудита аннотируют matchedIgnore, когда применимо; создание записывает sizeBytes: 0.

GET /session/:id/context

{
  "v": 1,
  "sessionId": "<sid>",
  "workspaceCwd": "/canonical/path",
  "state": {
    "models": {},
    "modes": {},
    "configOptions": []
  }
}

Для сеанса верхнего уровня поле state отражает те же структуры модели/режима/параметров конфигурации ACP, которые используются в POST /session, POST /session/:id/load и POST /session/:id/resume. Виртуальный идентификатор сеанса с префиксом subagent. разрешается относительно родительской среды выполнения и возвращает пустой объект state.

GET /session/:id/supported-commands

{
  "v": 1,
  "sessionId": "<sid>",
  "availableCommands": [
    {
      "name": "init",
      "description": "Initialize the project",
      "input": null,
      "_meta": { "source": "builtin" }
    }
  ],
  "availableSkills": ["review"]
}

Поле availableCommands представляет собой тот же снимок команд, который используется в SSE-уведомлении available_commands_update. Поле availableSkills перечисляет только имена навыков; клиенты не должны ожидать тела навыков или пути через этот маршрут.

GET /session/:id/tasks

{
  "v": 1,
  "sessionId": "<sid>",
  "now": 1700000000000,
  "tasks": [
    {
      "kind": "agent",
      "id": "agent-1",
      "label": "reviewer: check failure",
      "description": "check failure",
      "status": "running",
      "startTime": 1699999999000,
      "runtimeMs": 1000,
      "outputFile": "/tmp/agent-1.jsonl",
      "isBackgrounded": true,
      "subagentType": "reviewer"
    },
    {
      "kind": "agent",
      "id": "agent-2",
      "label": "general-purpose: run the failing test",
      "description": "run the failing test",
      "status": "running",
      "startTime": 1699999999500,
      "runtimeMs": 500,
      "outputFile": "/tmp/agent-2.jsonl",
      "isBackgrounded": false,
      "subagentType": "general-purpose",
      "parentAgentId": "agent-1",
      "parentName": "reviewer",
      "depth": 1
    }
  ]
}

Этот маршрут представляет собой снимок вне полосы пропускания только для чтения. Он намеренно не является подсказкой (prompt) и может запрашиваться во время потоковой передачи сеанса. Ответ содержит только разрешенные метаданные из реестров задач агента, оболочки и монитора; контроллеры, таймеры, смещения, ожидающие сообщения и необработанные объекты реестра никогда не раскрываются.

Задачи агента, порожденные другим суб-агентом (вложенные суб-агенты, ограниченные maxSubagentDepth), содержат три необязательных поля происхождения: parentAgentId (id задачи агента, породившего его), parentName (subagentType породившего агента, зафиксированный при регистрации, чтобы он сохранился после удаления родителя из реестра) и depth (глубина запуска, начиная с 0; 0 = запущен верхнеуровневой сессией). Агенты, запущенные верхнеуровневой сессией, не имеют полей parentAgentId и parentName; клиенты должны считать все три поля необязательными и использовать плоский список при их отсутствии.

GET /session/:id/tasks/:taskId/runtime

Детальная информация по запросу для одной shell-задачи. GET /session/:id/tasks содержит только факты жизненного цикла; этот маршрут читает захваченный файл вывода и исследует дерево процессов, поэтому открытая панель деталей запрашивает это отдельно.

Метод ACP — это _qwen/session/task_runtime с параметрами sessionId и taskId. Оба транспорта определяют владельца активной сессии; ACP также требует, чтобы соединение владело сессией.

taskId пути разрешается относительно собственного реестра shell-сессии; вызывающие стороны никогда не передают путь к файлу.

{
  "v": 1,
  "sessionId": "<sid>",
  "taskId": "bg_0123abcd",
  "runtime": {
    "memoryBytes": 104857600,
    "outputBytes": 65536,
    "outputModifiedAt": 1700000000000,
    "outputTail": "ready in 120ms\n",
    "outputTailTruncated": true
  }
}

runtime равно null, если задача неизвестна, была удалена или не является shell-задачей. memoryBytes — это резидентный набор дерева процессов shell, опрашиваемый только во время выполнения задачи; общие страницы учитываются один раз на процесс, а песочница контейнера может показывать только обертку процесса. outputTail ограничен тем же лимитом в 8 КиБ, что используется в уведомлении о завершении, а outputTailTruncated отмечает хвост, начинающийся посреди файла. outputError устанавливается, если файл невозможно прочитать; поля из успешно прочитанной части могут присутствовать.

POST /session/:id/tasks/:taskId/workflow-action

Управляет запуском рабочего процесса или начинает новый. Метод ACP — _qwen/session/tasks/workflow_action.

{
  "action": "run-script",
  "script": "export const meta = { name: 'daily-audit', description: 'Audits yesterday' }\nreturn await agent(args.question)",
  "args": { "question": "which tables grew?" },
  "sourceRef": { "id": "definition-7", "revision": "rev-3" }
}

Что означает taskId зависит от действия:

args, sourceRef и script читаются только через run-saved и run-script. args привязан к глобальной переменной args скрипта и может быть любым значением JSON; sourceRef — это собственный {id, revision} вызывающей стороны, записываемый в запуск, его журнал и снимок; script — это исходный run-script, который запускается и требуется им. Повторная попытка или перезапуск воспроизводят собственные args и sourceRef исходного запуска — именно это делает его тем же запуском — поэтому эти поля игнорируются вместе с управляющими действиями.

Начатый запуск принадлежит сессии: он выполняется в фоновом режиме без запроса подтверждения, и его завершение достигает канала завершения сессии. После этого он становится целью retry/rerun, как любой другой запуск.

retry и rerun также принимают запуск, восстановленный из истории (isHistorical в GET /session/:id/tasks), например тот, который был прерван перезапуском демона: запуск снова стартует из скрипта своего снимка, args и sourceRef, регистрируется в сессии, отправившей действие, и сообщает ей о своем завершении. retry возобновляет журнал запуска под тем же идентификатором запуска и применяется к запуску failed, над которым больше не работает ни один процесс; rerun начинает новый идентификатор запуска из любого завершенного запуска. Запись истории, содержащая argsOmitted, была запущена с слишком большим args для сохранения, поэтому ни одно из действий к ней не применимо. Также неприменимо к снимку, написанному до того, как сохранялись args, который не содержит ни argsOmitted, ни argsRecorded: журнал запуска ключуется от хеша его args, поэтому перезапуск того, чей args история не может назвать, ничего не воспроизведет и заново диспетчеризует всех агентов. Оба отказа являются workflow_args_unavailable, и GET /session/:id/tasks сообщает оба как argsUnavailable в записи, чтобы клиент мог скрыть два действия вместо обнаружения отказа путем выполнения вызова. argsOmitted остается рядом с ним как причина для клиента, который хочет указать, какая именно. Сами args никогда не передаются по сети.

run-script не передает имя определения, поэтому запуск помечается собственным export const meta скрипта — компилируемый скрипт должен объявить его, иначе запуск покажет только свой id.

Ответом является {"changed": true, "status": "running", "taskId": "<runId>"} для начатого запуска, {"changed": true, "status": "<status>"} для управляющего действия, которое вступило в силу, и {"changed": false}, когда ничего не произошло: Workflow недоступен для сессии (отключен, базовый режим, недоверенная папка), рабочее пространство недоверенное, сохраненное имя workflow неизвестно, id запуска неизвестен или другой запуск уже выполняется под тем же taskId. Дедуплицируются только пересекающиеся запуски: два одновременных вызова run-script под одним taskId начинают один запуск. Как только этот запуск вернется, ключ освобождается; повторная отправка может начать другой запуск, даже если первый еще активен. Ключ не обеспечивает идемпотентность повторных попыток после потери ответа.

Отклоненный параметр — это 400 (-32602 через ACP), а не начатый запуск: неизвестный action, run-script без script, sourceRef, который не является {id, revision} непустых строк, или скрипт, отклоненный перед запуском из-за синтаксической ошибки или нарушения детерминизма. Ошибки входных данных при запуске Workflow содержат workflow_invalid_params и сохраняют сообщение об отказе.

Четыре отказа исходят из сохраненного состояния запуска, а не из запроса. Каждый является -32602 через ACP, содержащим свой errorKind и свой data.httpStatus. Три из них — это 409; четвертый, workflow_not_recorded, является 503, потому что ничего не было начато, и тот же вызов можно просто повторить: retry записывает, что запуск снова выполняется, перед началом — эта запись предотвращает запуск другим процессом повторно — но запись не удалось сохранить.

workflowToolFeatures в GET /session/:id/supported-commands объявляет поддержку runSavedArgs и runScript; демон без них не принимает ни входные данные запуска, ни действие run-script. Он также содержит поле nameOnly, равное true, когда модель сессии может запускать только именованные рабочие процессы (tools.workflowNameOnly): собственные вызовы модели script и scriptPath отклоняются, тогда как все перечисленные выше действия, включая run-script, по-прежнему инициируют запуски. Поле retryHistorical равно true, когда retry и rerun принимают запуск, восстановленный из истории; более старый демон отвечает на них ошибкой {"changed": false}, поэтому клиент должен предлагать эти элементы управления для записи истории только если это поддерживается.

GET /session/:id/lsp

{
  "v": 1,
  "sessionId": "<sid>",
  "workspaceCwd": "/canonical/path",
  "enabled": true,
  "configuredServers": 1,
  "readyServers": 1,
  "failedServers": 0,
  "inProgressServers": 0,
  "notStartedServers": 0,
  "servers": [
    {
      "name": "typescript",
      "status": "READY",
      "languages": ["typescript", "javascript"],
      "transport": "stdio",
      "command": "typescript-language-server"
    }
  ]
}